[CalendarServer-changes] [188] CalendarServer/trunk/doc/RFC
source_changes at macosforge.org
source_changes at macosforge.org
Fri Sep 22 13:39:00 PDT 2006
Revision: 188
http://trac.macosforge.org/projects/collaboration/changeset/188
Author: wsanchez at apple.com
Date: 2006-09-22 13:38:58 -0700 (Fri, 22 Sep 2006)
Log Message:
-----------
More informative file names
Added Paths:
-----------
CalendarServer/trunk/doc/RFC/rfc2445-iCalendar.txt
CalendarServer/trunk/doc/RFC/rfc2446-iTIP.txt
CalendarServer/trunk/doc/RFC/rfc2447-iMIP.txt
CalendarServer/trunk/doc/RFC/rfc2518-WebDAV.txt
CalendarServer/trunk/doc/RFC/rfc2518bis-WebDAV.txt
CalendarServer/trunk/doc/RFC/rfc2616-HTTP.txt
CalendarServer/trunk/doc/RFC/rfc2617-HTTP Auth.txt
CalendarServer/trunk/doc/RFC/rfc3253-DeltaV.txt
CalendarServer/trunk/doc/RFC/rfc3283-Calendaring.txt
CalendarServer/trunk/doc/RFC/rfc3744-WebDAV ACL.txt
CalendarServer/trunk/doc/RFC/rfc4559-SPNEGO.txt
Removed Paths:
-------------
CalendarServer/trunk/doc/RFC/rfc2445.txt
CalendarServer/trunk/doc/RFC/rfc2446.txt
CalendarServer/trunk/doc/RFC/rfc2447.txt
CalendarServer/trunk/doc/RFC/rfc2518.txt
CalendarServer/trunk/doc/RFC/rfc2518bis.txt
CalendarServer/trunk/doc/RFC/rfc2616.txt
CalendarServer/trunk/doc/RFC/rfc2617.txt
CalendarServer/trunk/doc/RFC/rfc3253.txt
CalendarServer/trunk/doc/RFC/rfc3283.txt
CalendarServer/trunk/doc/RFC/rfc3744.txt
CalendarServer/trunk/doc/RFC/rfc4559.txt
Copied: CalendarServer/trunk/doc/RFC/rfc2445-iCalendar.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2445.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2445-iCalendar.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2445-iCalendar.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,8291 @@
+
+
+
+
+
+
+Network Working Group F. Dawson
+Request for Comments: 2445 Lotus
+Category: Standards Track D. Stenerson
+ Microsoft
+ November 1998
+
+
+ Internet Calendaring and Scheduling Core Object Specification
+ (iCalendar)
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ There is a clear need to provide and deploy interoperable calendaring
+ and scheduling services for the Internet. Current group scheduling
+ and Personal Information Management (PIM) products are being extended
+ for use across the Internet, today, in proprietary ways. This memo
+ has been defined to provide the definition of a common format for
+ openly exchanging calendaring and scheduling information across the
+ Internet.
+
+ This memo is formatted as a registration for a MIME media type per
+ [RFC 2048]. However, the format in this memo is equally applicable
+ for use outside of a MIME message content type.
+
+ The proposed media type value is 'text/calendar'. This string would
+ label a media type containing calendaring and scheduling information
+ encoded as text characters formatted in a manner outlined below.
+
+ This MIME media type provides a standard content type for capturing
+ calendar event, to-do and journal entry information. It also can be
+ used to convey free/busy time information. The content type is
+ suitable as a MIME message entity that can be transferred over MIME
+ based email systems, using HTTP or some other Internet transport. In
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 1]
+
+RFC 2445 iCalendar November 1998
+
+
+ addition, the content type is useful as an object for interactions
+ between desktop applications using the operating system clipboard,
+ drag/drop or file systems capabilities.
+
+ This memo is based on the earlier work of the vCalendar specification
+ for the exchange of personal calendaring and scheduling information.
+ In order to avoid confusion with this referenced work, this memo is
+ to be known as the iCalendar specification.
+
+ This memo defines the format for specifying iCalendar object methods.
+ An iCalendar object method is a set of usage constraints for the
+ iCalendar object. For example, these methods might define scheduling
+ messages that request an event be scheduled, reply to an event
+ request, send a cancellation notice for an event, modify or replace
+ the definition of an event, provide a counter proposal for an
+ original event request, delegate an event request to another
+ individual, request free or busy time, reply to a free or busy time
+ request, or provide similar scheduling messages for a to-do or
+ journal entry calendar component. The iCalendar Transport-indendent
+ Interoperability Protocol (iTIP) defined in [ITIP] is one such
+ scheduling protocol.
+
+Table of Contents
+
+ 1 Introduction.....................................................5
+ 2 Basic Grammar and Conventions....................................6
+ 2.1 Formatting Conventions .......................................7
+ 2.2 Related Memos ................................................8
+ 2.3 International Considerations .................................8
+ 3 Registration Information.........................................8
+ 3.1 Content Type .................................................8
+ 3.2 Parameters ...................................................9
+ 3.3 Content Header Fields .......................................10
+ 3.4 Encoding Considerations .....................................10
+ 3.5 Security Considerations .....................................10
+ 3.6 Interoperability Considerations .............................11
+ 3.7 Applications Which Use This Media Type ......................11
+ 3.8 Additional Information ......................................11
+ 3.9 Magic Numbers ...............................................11
+ 3.10 File Extensions ............................................11
+ 3.11 Contact for Further Information: ...........................12
+ 3.12 Intended Usage .............................................12
+ 3.13 Authors/Change Controllers .................................12
+ 4 iCalendar Object Specification..................................13
+ 4.1 Content Lines ...............................................13
+ 4.1.1 List and Field Separators ................................16
+ 4.1.2 Multiple Values ..........................................16
+ 4.1.3 Binary Content ...........................................16
+
+
+
+Dawson & Stenerson Standards Track [Page 2]
+
+RFC 2445 iCalendar November 1998
+
+
+ 4.1.4 Character Set ............................................17
+ 4.2 Property Parameters .........................................17
+ 4.2.1 Alternate Text Representation ............................18
+ 4.2.2 Common Name ..............................................19
+ 4.2.3 Calendar User Type .......................................20
+ 4.2.4 Delegators ...............................................20
+ 4.2.5 Delegatees ...............................................21
+ 4.2.6 Directory Entry Reference ................................21
+ 4.2.7 Inline Encoding ..........................................22
+ 4.2.8 Format Type ..............................................23
+ 4.2.9 Free/Busy Time Type ......................................23
+ 4.2.10 Language ................................................24
+ 4.2.11 Group or List Membership ................................25
+ 4.2.12 Participation Status ....................................25
+ 4.2.13 Recurrence Identifier Range .............................27
+ 4.2.14 Alarm Trigger Relationship ..............................27
+ 4.2.15 Relationship Type .......................................28
+ 4.2.16 Participation Role ......................................29
+ 4.2.17 RSVP Expectation ........................................29
+ 4.2.18 Sent By .................................................30
+ 4.2.19 Time Zone Identifier ....................................30
+ 4.2.20 Value Data Types ........................................32
+ 4.3 Property Value Data Types ...................................32
+ 4.3.1 Binary ...................................................33
+ 4.3.2 Boolean ..................................................33
+ 4.3.3 Calendar User Address ....................................34
+ 4.3.4 Date .....................................................34
+ 4.3.5 Date-Time ................................................35
+ 4.3.6 Duration .................................................37
+ 4.3.7 Float ....................................................38
+ 4.3.8 Integer ..................................................38
+ 4.3.9 Period of Time ...........................................39
+ 4.3.10 Recurrence Rule .........................................40
+ 4.3.11 Text ....................................................45
+ 4.3.12 Time ....................................................47
+ 4.3.13 URI .....................................................49
+ 4.3.14 UTC Offset ..............................................49
+ 4.4 iCalendar Object ............................................50
+ 4.5 Property ....................................................51
+ 4.6 Calendar Components .........................................51
+ 4.6.1 Event Component ..........................................52
+ 4.6.2 To-do Component ..........................................55
+ 4.6.3 Journal Component ........................................56
+ 4.6.4 Free/Busy Component ......................................58
+ 4.6.5 Time Zone Component ......................................60
+ 4.6.6 Alarm Component ..........................................67
+ 4.7 Calendar Properties .........................................73
+ 4.7.1 Calendar Scale ...........................................73
+
+
+
+Dawson & Stenerson Standards Track [Page 3]
+
+RFC 2445 iCalendar November 1998
+
+
+ 4.7.2 Method ...................................................74
+ 4.7.3 Product Identifier .......................................75
+ 4.7.4 Version ..................................................76
+ 4.8 Component Properties ........................................77
+ 4.8.1 Descriptive Component Properties .........................77
+ 4.8.1.1 Attachment ...........................................77
+ 4.8.1.2 Categories ...........................................78
+ 4.8.1.3 Classification .......................................79
+ 4.8.1.4 Comment ..............................................80
+ 4.8.1.5 Description ..........................................81
+ 4.8.1.6 Geographic Position ..................................82
+ 4.8.1.7 Location .............................................84
+ 4.8.1.8 Percent Complete .....................................85
+ 4.8.1.9 Priority .............................................85
+ 4.8.1.10 Resources ...........................................87
+ 4.8.1.11 Status ..............................................88
+ 4.8.1.12 Summary .............................................89
+ 4.8.2 Date and Time Component Properties .......................90
+ 4.8.2.1 Date/Time Completed ..................................90
+ 4.8.2.2 Date/Time End ........................................91
+ 4.8.2.3 Date/Time Due ........................................92
+ 4.8.2.4 Date/Time Start ......................................93
+ 4.8.2.5 Duration .............................................94
+ 4.8.2.6 Free/Busy Time .......................................95
+ 4.8.2.7 Time Transparency ....................................96
+ 4.8.3 Time Zone Component Properties ...........................97
+ 4.8.3.1 Time Zone Identifier .................................97
+ 4.8.3.2 Time Zone Name .......................................98
+ 4.8.3.3 Time Zone Offset From ................................99
+ 4.8.3.4 Time Zone Offset To .................................100
+ 4.8.3.5 Time Zone URL .......................................101
+ 4.8.4 Relationship Component Properties .......................102
+ 4.8.4.1 Attendee ............................................102
+ 4.8.4.2 Contact .............................................104
+ 4.8.4.3 Organizer ...........................................106
+ 4.8.4.4 Recurrence ID .......................................107
+ 4.8.4.5 Related To ..........................................109
+ 4.8.4.6 Uniform Resource Locator ............................110
+ 4.8.4.7 Unique Identifier ...................................111
+ 4.8.5 Recurrence Component Properties .........................112
+ 4.8.5.1 Exception Date/Times ................................112
+ 4.8.5.2 Exception Rule ......................................114
+ 4.8.5.3 Recurrence Date/Times ...............................115
+ 4.8.5.4 Recurrence Rule .....................................117
+ 4.8.6 Alarm Component Properties ..............................126
+ 4.8.6.1 Action ..............................................126
+ 4.8.6.2 Repeat Count ........................................126
+ 4.8.6.3 Trigger .............................................127
+
+
+
+Dawson & Stenerson Standards Track [Page 4]
+
+RFC 2445 iCalendar November 1998
+
+
+ 4.8.7 Change Management Component Properties ..................129
+ 4.8.7.1 Date/Time Created ...................................129
+ 4.8.7.2 Date/Time Stamp .....................................130
+ 4.8.7.3 Last Modified .......................................131
+ 4.8.7.4 Sequence Number .....................................131
+ 4.8.8 Miscellaneous Component Properties ......................133
+ 4.8.8.1 Non-standard Properties .............................133
+ 4.8.8.2 Request Status ......................................134
+ 5 iCalendar Object Examples......................................136
+ 6 Recommended Practices..........................................140
+ 7 Registration of Content Type Elements..........................141
+ 7.1 Registration of New and Modified iCalendar Object Methods ..141
+ 7.2 Registration of New Properties .............................141
+ 7.2.1 Define the property .....................................142
+ 7.2.2 Post the Property definition ............................143
+ 7.2.3 Allow a comment period ..................................143
+ 7.2.4 Submit the property for approval ........................143
+ 7.3 Property Change Control ....................................143
+ 8 References.....................................................144
+ 9 Acknowledgments................................................145
+ 10 Authors' and Chairs' Addresses................................146
+ 11 Full Copyright Statement......................................148
+
+1 Introduction
+
+ The use of calendaring and scheduling has grown considerably in the
+ last decade. Enterprise and inter-enterprise business has become
+ dependent on rapid scheduling of events and actions using this
+ information technology. However, the longer term growth of
+ calendaring and scheduling, is currently limited by the lack of
+ Internet standards for the message content types that are central to
+ these knowledgeware applications. This memo is intended to progress
+ the level of interoperability possible between dissimilar calendaring
+ and scheduling applications. This memo defines a MIME content type
+ for exchanging electronic calendaring and scheduling information. The
+ Internet Calendaring and Scheduling Core Object Specification, or
+ iCalendar, allows for the capture and exchange of information
+ normally stored within a calendaring and scheduling application; such
+ as a Personal Information Manager (PIM) or a Group Scheduling
+ product.
+
+ The iCalendar format is suitable as an exchange format between
+ applications or systems. The format is defined in terms of a MIME
+ content type. This will enable the object to be exchanged using
+ several transports, including but not limited to SMTP, HTTP, a file
+ system, desktop interactive protocols such as the use of a memory-
+ based clipboard or drag/drop interactions, point-to-point
+ asynchronous communication, wired-network transport, or some form of
+
+
+
+Dawson & Stenerson Standards Track [Page 5]
+
+RFC 2445 iCalendar November 1998
+
+
+ unwired transport such as infrared might also be used.
+
+ The memo also provides for the definition of iCalendar object methods
+ that will map this content type to a set of messages for supporting
+ calendaring and scheduling operations such as requesting, replying
+ to, modifying, and canceling meetings or appointments, to-dos and
+ journal entries. The iCalendar object methods can be used to define
+ other calendaring and scheduling operations such a requesting for and
+ replying with free/busy time data. Such a scheduling protocol is
+ defined in the iCalendar Transport-independent Interoperability
+ Protocol (iTIP) defined in [ITIP].
+
+ The memo also includes a formal grammar for the content type based on
+ the Internet ABNF defined in [RFC 2234]. This ABNF is required for
+ the implementation of parsers and to serve as the definitive
+ reference when ambiguities or questions arise in interpreting the
+ descriptive prose definition of the memo.
+
+2 Basic Grammar and Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" and
+ "OPTIONAL" in this document are to be interoperated as described in
+ [RFC 2119].
+
+ This memo makes use of both a descriptive prose and a more formal
+ notation for defining the calendaring and scheduling format.
+
+ The notation used in this memo is the ABNF notation of [RFC 2234].
+ Readers intending on implementing this format defined in this memo
+ should be familiar with this notation in order to properly interpret
+ the specifications of this memo.
+
+ All numeric and hexadecimal values used in this memo are given in
+ decimal notation.
+
+ All names of properties, property parameters, enumerated property
+ values and property parameter values are case-insensitive. However,
+ all other property values are case-sensitive, unless otherwise
+ stated.
+
+ Note: All indented editorial notes, such as this one, are
+ intended to provide the reader with additional information. The
+ information is not essential to the building of an
+ implementation conformant with this memo. The information is
+ provided to highlight a particular feature or characteristic of
+ the memo.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 6]
+
+RFC 2445 iCalendar November 1998
+
+
+ The format for the iCalendar object is based on the syntax of the
+ [RFC 2425] content type. While the iCalendar object is not a profile
+ of the [RFC 2425] content type, it does reuse a number of the
+ elements from the [RFC 2425] specification.
+
+2.1 Formatting Conventions
+
+ The mechanisms defined in this memo are defined in prose. Many of the
+ terms used to describe these have common usage that is different than
+ the standards usage of this memo. In order to reference within this
+ memo elements of the calendaring and scheduling model, core object
+ (this memo) or interoperability protocol [ITIP] some formatting
+ conventions have been used. Calendaring and scheduling roles are
+ referred to in quoted-strings of text with the first character of
+ each word in upper case. For example, "Organizer" refers to a role of
+ a "Calendar User" within the scheduling protocol defined by [ITIP].
+ Calendar components defined by this memo are referred to with
+ capitalized, quoted-strings of text. All calendar components start
+ with the letter "V". For example, "VEVENT" refers to the event
+ calendar component, "VTODO" refers to the to-do calendar component
+ and "VJOURNAL" refers to the daily journal calendar component.
+ Scheduling methods defined by [ITIP] are referred to with
+ capitalized, quoted-strings of text. For example, "REQUEST" refers to
+ the method for requesting a scheduling calendar component be created
+ or modified, "REPLY" refers to the method a recipient of a request
+ uses to update their status with the "Organizer" of the calendar
+ component.
+
+ The properties defined by this memo are referred to with capitalized,
+ quoted-strings of text, followed by the word "property". For example,
+ "ATTENDEE" property refers to the iCalendar property used to convey
+ the calendar address of a calendar user. Property parameters defined
+ by this memo are referred to with lowercase, quoted-strings of text,
+ followed by the word "parameter". For example, "value" parameter
+ refers to the iCalendar property parameter used to override the
+ default data type for a property value. Enumerated values defined by
+ this memo are referred to with capitalized text, either alone or
+ followed by the word "value". For example, the "MINUTELY" value can
+ be used with the "FREQ" component of the "RECUR" data type to specify
+ repeating components based on an interval of one minute or more.
+
+
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 7]
+
+RFC 2445 iCalendar November 1998
+
+
+2.2 Related Memos
+
+ Implementers will need to be familiar with several other memos that,
+ along with this memo, form a framework for Internet calendaring and
+ scheduling standards. This memo, [ICAL], specifies a core
+ specification of objects, data types, properties and property
+ parameters.
+
+ [ITIP] - specifies an interoperability protocol for scheduling
+ between different implementations;
+
+ [IMIP] specifies an Internet email binding for [ITIP].
+
+ This memo does not attempt to repeat the specification of concepts or
+ definitions from these other memos. Where possible, references are
+ made to the memo that provides for the specification of these
+ concepts or definitions.
+
+2.3 International Considerations
+
+ In the rest of this document, descriptions of characters are of the
+ form "character name (codepoint)", where "codepoint" is from the US-
+ ASCII character set. The "character name" is the authoritative
+ description; (codepoint) is a reference to that character in US-ASCII
+ or US-ASCII compatible sets (for example the ISO-8859-x family, UTF-
+ 8, ISO-2022-xx, KOI8-R). If a non-US-ASCII compatible character set
+ is used, appropriate code-point from that character set MUST be
+ chosen instead. Use of non-US-ASCII-compatible character sets is NOT
+ recommended.
+
+3 Registration Information
+
+ The Calendaring and Scheduling Core Object Specification is intended
+ for use as a MIME content type. However, the implementation of the
+ memo is in no way limited solely as a MIME content type.
+
+3.1 Content Type
+
+ The following text is intended to register this memo as the MIME
+ content type "text/calendar".
+
+ To: ietf-types at uninett.no
+
+ Subject: Registration of MIME content type text/calendar.
+
+ MIME media type name: text
+
+ MIME subtype name: calendar
+
+
+
+Dawson & Stenerson Standards Track [Page 8]
+
+RFC 2445 iCalendar November 1998
+
+
+3.2 Parameters
+
+ Required parameters: none
+
+ Optional parameters: charset, method, component and optinfo
+
+ The "charset" parameter is defined in [RFC 2046] for other body
+ parts. It is used to identify the default character set used within
+ the body part.
+
+ The "method" parameter is used to convey the iCalendar object method
+ or transaction semantics for the calendaring and scheduling
+ information. It also is an identifier for the restricted set of
+ properties and values that the iCalendar object consists of. The
+ parameter is to be used as a guide for applications interpreting the
+ information contained within the body part. It SHOULD NOT be used to
+ exclude or require particular pieces of information unless the
+ identified method definition specifically calls for this behavior.
+ Unless specifically forbidden by a particular method definition, a
+ text/calendar content type can contain any set of properties
+ permitted by the Calendaring and Scheduling Core Object
+ Specification. The "method" parameter MUST be the same value as that
+ specified in the "METHOD" component property in the iCalendar object.
+ If one is present, the other MUST also be present.
+
+ The value for the "method" parameter is defined as follows:
+
+ method = 1*(ALPHA / DIGIT / "-")
+ ; IANA registered iCalendar object method
+
+ The "component" parameter conveys the type of iCalendar calendar
+ component within the body part. If the iCalendar object contains more
+ than one calendar component type, then multiple component parameters
+ MUST be specified.
+
+ The value for the "component" parameter is defined as follows:
+
+ component = ("VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY"
+ / "VTIMEZONE" / x-name / iana-token)
+
+ The "optinfo" parameter conveys optional information about the
+ iCalendar object within the body part. This parameter can only
+ specify semantics already specified by the iCalendar object and that
+ can be otherwise determined by parsing the body part. In addition,
+ the optional information specified by this parameter MUST be
+ consistent with that information specified by the iCalendar object.
+ For example, it can be used to convey the "Attendee" response status
+ to a meeting request. The parameter value consists of a string value.
+
+
+
+Dawson & Stenerson Standards Track [Page 9]
+
+RFC 2445 iCalendar November 1998
+
+
+ The parameter can be specified multiple times.
+
+ This parameter MAY only specify semantics already specified by the
+ iCalendar object and that can be otherwise determined by parsing the
+ body part.
+
+ The value for the "optinfo" parameter is defined as follows:
+
+ optinfo = infovalue / qinfovalue
+
+ infovalue = iana-token / x-name
+
+ qinfovalue = DQUOTE (infovalue) DQUOTE
+
+3.3 Content Header Fields
+
+ Optional content header fields: Any header fields defined by [RFC
+ 2045].
+
+3.4 Encoding Considerations
+
+ This MIME content type can contain 8bit characters, so the use of
+ quoted-printable or BASE64 MIME content-transfer-encodings might be
+ necessary when iCalendar objects are transferred across protocols
+ restricted to the 7bit repertoire. Note that a text valued property
+ in the content entity can also have content encoding of special
+ characters using a BACKSLASH character (US-ASCII decimal 92)
+ escapement technique. This means that content values can end up
+ encoded twice.
+
+3.5 Security Considerations
+
+ SPOOFING - - In this memo, the "Organizer" is the only person
+ authorized to make changes to an existing "VEVENT", "VTODO",
+ "VJOURNAL" calendar component and redistribute the updates to the
+ "Attendees". An iCalendar object that maliciously changes or cancels
+ an existing "VEVENT", "VTODO" or "VJOURNAL" or "VFREEBUSY" calendar
+ component might be constructed by someone other than the "Organizer"
+ and sent to the "Attendees". In addition in this memo, other than the
+ "Organizer", an "Attendee" of a "VEVENT", "VTODO", "VJOURNAL"
+ calendar component is the only other person authorized to update any
+ parameter associated with their "ATTENDEE" property and send it to
+ the "Organizer". An iCalendar object that maliciously changes the
+ "ATTENDEE" parameters can be constructed by someone other than the
+ real "Attendee" and sent to the "Organizer".
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 10]
+
+RFC 2445 iCalendar November 1998
+
+
+ PROCEDURAL ALARMS - - An iCalendar object can be created that
+ contains a "VEVENT" and "VTODO" calendar component with "VALARM"
+ calendar components. The "VALARM" calendar component can be of type
+ PROCEDURE and can have an attachment containing some sort of
+ executable program. Implementations that incorporate these types of
+ alarms are subject to any virus or malicious attack that might occur
+ as a result of executing the attachment.
+
+ ATTACHMENTS - - An iCalendar object can include references to Uniform
+ Resource Locators that can be programmed resources.
+
+ Implementers and users of this memo should be aware of the network
+ security implications of accepting and parsing such information. In
+ addition, the security considerations observed by implementations of
+ electronic mail systems should be followed for this memo.
+
+3.6 Interoperability Considerations
+
+ This MIME content type is intended to define a common format for
+ conveying calendaring and scheduling information between different
+ systems. It is heavily based on the earlier [VCAL] industry
+ specification.
+
+3.7 Applications Which Use This Media Type
+
+ This content-type is designed for widespread use by Internet
+ calendaring and scheduling applications. In addition, applications in
+ the workflow and document management area might find this content-
+ type applicable. The [ITIP] and [IMIP] Internet protocols directly
+ use this content-type also. Future work on an Internet calendar
+ access protocol will utilize this content-type too.
+
+3.8 Additional Information
+
+ This memo defines this content-type.
+
+3.9 Magic Numbers
+
+ None.
+
+3.10 File Extensions
+
+ The file extension of "ics" is to be used to designate a file
+ containing (an arbitrary set of) calendaring and scheduling
+ information consistent with this MIME content type.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 11]
+
+RFC 2445 iCalendar November 1998
+
+
+ The file extension of "ifb" is to be used to designate a file
+ containing free or busy time information consistent with this MIME
+ content type.
+
+ Macintosh file type codes: The file type code of "iCal" is to be used
+ in Apple MacIntosh operating system environments to designate a file
+ containing calendaring and scheduling information consistent with
+ this MIME media type.
+
+ The file type code of "iFBf" is to be used in Apple MacIntosh
+ operating system environments to designate a file containing free or
+ busy time information consistent with this MIME media type.
+
+3.11 Contact for Further Information:
+
+ Frank Dawson
+ 6544 Battleford Drive
+ Raleigh, NC 27613-3502
+ 919-676-9515 (Telephone)
+ 919-676-9564 (Data/Facsimile)
+ Frank_Dawson at Lotus.com (Internet Mail)
+
+ Derik Stenerson
+ One Microsoft Way
+ Redmond, WA 98052-6399
+ 425-936-5522 (Telephone)
+ 425-936-7329 (Facsimile)
+ deriks at microsoft.com (Internet Mail)
+
+3.12 Intended Usage
+
+ COMMON
+
+3.13 Authors/Change Controllers
+
+ Frank Dawson
+ 6544 Battleford Drive
+ Raleigh, NC 27613-3502
+ 919-676-9515 (Telephone)
+ 919-676-9564 (Data/Facsimile)
+ Frank_Dawson at Lotus.com (Internet Mail)
+
+ Derik Stenerson
+ One Microsoft Way
+ Redmond, WA 98052-6399
+ 425-936-5522 (Telephone)
+ 425-936-7329 (Facsimile)
+ deriks at microsoft.com (Internet Mail)
+
+
+
+Dawson & Stenerson Standards Track [Page 12]
+
+RFC 2445 iCalendar November 1998
+
+
+4 iCalendar Object Specification
+
+ The following sections define the details of a Calendaring and
+ Scheduling Core Object Specification. This information is intended to
+ be an integral part of the MIME content type registration. In
+ addition, this information can be used independent of such content
+ registration. In particular, this memo has direct applicability for
+ use as a calendaring and scheduling exchange format in file-, memory-
+ or network-based transport mechanisms.
+
+4.1 Content Lines
+
+ The iCalendar object is organized into individual lines of text,
+ called content lines. Content lines are delimited by a line break,
+ which is a CRLF sequence (US-ASCII decimal 13, followed by US-ASCII
+ decimal 10).
+
+ Lines of text SHOULD NOT be longer than 75 octets, excluding the line
+ break. Long content lines SHOULD be split into a multiple line
+ representations using a line "folding" technique. That is, a long
+ line can be split between any two characters by inserting a CRLF
+ immediately followed by a single linear white space character (i.e.,
+ SPACE, US-ASCII decimal 32 or HTAB, US-ASCII decimal 9). Any sequence
+ of CRLF followed immediately by a single linear white space character
+ is ignored (i.e., removed) when processing the content type.
+
+ For example the line:
+
+ DESCRIPTION:This is a long description that exists on a long line.
+
+ Can be represented as:
+
+ DESCRIPTION:This is a lo
+ ng description
+ that exists on a long line.
+
+ The process of moving from this folded multiple line representation
+ to its single line representation is called "unfolding". Unfolding is
+ accomplished by removing the CRLF character and the linear white
+ space character that immediately follows.
+
+ When parsing a content line, folded lines MUST first be unfolded
+ according to the unfolding procedure described above. When generating
+ a content line, lines longer than 75 octets SHOULD be folded
+ according to the folding procedure described above.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 13]
+
+RFC 2445 iCalendar November 1998
+
+
+ The content information associated with an iCalendar object is
+ formatted using a syntax similar to that defined by [RFC 2425]. That
+ is, the content information consists of CRLF-separated content lines.
+
+ The following notation defines the lines of content in an iCalendar
+ object:
+
+ contentline = name *(";" param ) ":" value CRLF
+ ; This ABNF is just a general definition for an initial parsing
+ ; of the content line into its property name, parameter list,
+ ; and value string
+
+ ; When parsing a content line, folded lines MUST first
+ ; be unfolded according to the unfolding procedure
+ ; described above. When generating a content line, lines
+ ; longer than 75 octets SHOULD be folded according to
+ ; the folding procedure described above.
+
+ name = x-name / iana-token
+
+ iana-token = 1*(ALPHA / DIGIT / "-")
+ ; iCalendar identifier registered with IANA
+
+ x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
+ ; Reservered for experimental use. Not intended for use in
+ ; released products.
+
+ vendorid = 3*(ALPHA / DIGIT) ;Vendor identification
+
+ param = param-name "=" param-value
+ *("," param-value)
+ ; Each property defines the specific ABNF for the parameters
+ ; allowed on the property. Refer to specific properties for
+ ; precise parameter ABNF.
+
+ param-name = iana-token / x-token
+
+ param-value = paramtext / quoted-string
+
+ paramtext = *SAFE-CHAR
+
+ value = *VALUE-CHAR
+
+ quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
+
+ NON-US-ASCII = %x80-F8
+ ; Use restricted by charset parameter
+ ; on outer MIME object (UTF-8 preferred)
+
+
+
+Dawson & Stenerson Standards Track [Page 14]
+
+RFC 2445 iCalendar November 1998
+
+
+ QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
+ ; Any character except CTLs and DQUOTE
+
+ SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E
+ / NON-US-ASCII
+ ; Any character except CTLs, DQUOTE, ";", ":", ","
+
+ VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII
+ ; Any textual character
+
+ CR = %x0D
+ ; carriage return
+
+ LF = %x0A
+ ; line feed
+
+ CRLF = CR LF
+ ; Internet standard newline
+
+ CTL = %x00-08 / %x0A-1F / %x7F
+ ; Controls
+
+ ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
+
+ DIGIT = %x30-39
+ ; 0-9
+
+ DQUOTE = %x22
+ ; Quotation Mark
+
+ WSP = SPACE / HTAB
+
+ SPACE = %x20
+
+ HTAB = %x09
+
+ The property value component of a content line has a format that is
+ property specific. Refer to the section describing each property for
+ a definition of this format.
+
+ All names of properties, property parameters, enumerated property
+ values and property parameter values are case-insensitive. However,
+ all other property values are case-sensitive, unless otherwise
+ stated.
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 15]
+
+RFC 2445 iCalendar November 1998
+
+
+4.1.1 List and Field Separators
+
+ Some properties and parameters allow a list of values. Values in a
+ list of values MUST be separated by a COMMA character (US-ASCII
+ decimal 44). There is no significance to the order of values in a
+ list. For those parameter values (such as those that specify URI
+ values) that are specified in quoted-strings, the individual quoted-
+ strings are separated by a COMMA character (US-ASCII decimal 44).
+
+ Some property values are defined in terms of multiple parts. These
+ structured property values MUST have their value parts separated by a
+ SEMICOLON character (US-ASCII decimal 59).
+
+ Some properties allow a list of parameters. Each property parameter
+ in a list of property parameters MUST be separated by a SEMICOLON
+ character (US-ASCII decimal 59).
+
+ Property parameters with values containing a COLON, a SEMICOLON or a
+ COMMA character MUST be placed in quoted text.
+
+ For example, in the following properties a SEMICOLON is used to
+ separate property parameters from each other, and a COMMA is used to
+ separate property values in a value list.
+
+ ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:MAILTO:
+ jsmith at host.com
+
+ RDATE;VALUE=DATE:19970304,19970504,19970704,19970904
+
+4.1.2 Multiple Values
+
+ Some properties defined in the iCalendar object can have multiple
+ values. The general rule for encoding multi-valued items is to simply
+ create a new content line for each value, including the property
+ name. However, it should be noted that some properties support
+ encoding multiple values in a single property by separating the
+ values with a COMMA character (US-ASCII decimal 44). Individual
+ property definitions should be consulted for determining whether a
+ specific property allows multiple values and in which of these two
+ forms.
+
+4.1.3 Binary Content
+
+ Binary content information in an iCalendar object SHOULD be
+ referenced using a URI within a property value. That is the binary
+ content information SHOULD be placed in an external MIME entity that
+ can be referenced by a URI from within the iCalendar object. In
+ applications where this is not feasible, binary content information
+
+
+
+Dawson & Stenerson Standards Track [Page 16]
+
+RFC 2445 iCalendar November 1998
+
+
+ can be included within an iCalendar object, but only after first
+ encoding it into text using the "BASE64" encoding method defined in
+ [RFC 2045]. Inline binary contact SHOULD only be used in applications
+ whose special circumstances demand that an iCalendar object be
+ expressed as a single entity. A property containing inline binary
+ content information MUST specify the "ENCODING" property parameter.
+ Binary content information placed external to the iCalendar object
+ MUST be referenced by a uniform resource identifier (URI).
+
+ The following example specifies an "ATTACH" property that references
+ an attachment external to the iCalendar object with a URI reference:
+
+ ATTACH:http://xyz.com/public/quarterly-report.doc
+
+ The following example specifies an "ATTACH" property with inline
+ binary encoded content information:
+
+ ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
+ MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
+ EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
+ <...remainder of "BASE64" encoded binary data...>
+
+4.1.4 Character Set
+
+ There is not a property parameter to declare the character set used
+ in a property value. The default character set for an iCalendar
+ object is UTF-8 as defined in [RFC 2279].
+
+ The "charset" Content-Type parameter can be used in MIME transports
+ to specify any other IANA registered character set.
+
+4.2 Property Parameters
+
+ A property can have attributes associated with it. These "property
+ parameters" contain meta-information about the property or the
+ property value. Property parameters are provided to specify such
+ information as the location of an alternate text representation for a
+ property value, the language of a text property value, the data type
+ of the property value and other attributes.
+
+ Property parameter values that contain the COLON (US-ASCII decimal
+ 58), SEMICOLON (US-ASCII decimal 59) or COMMA (US-ASCII decimal 44)
+ character separators MUST be specified as quoted-string text values.
+ Property parameter values MUST NOT contain the DOUBLE-QUOTE (US-ASCII
+ decimal 22) character. The DOUBLE-QUOTE (US-ASCII decimal 22)
+ character is used as a delimiter for parameter values that contain
+ restricted characters or URI text. For example:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 17]
+
+RFC 2445 iCalendar November 1998
+
+
+ DESCRIPTION;ALTREP="http://www.wiz.org":The Fall'98 Wild Wizards
+ Conference - - Las Vegas, NV, USA
+
+ Property parameter values that are not in quoted strings are case
+ insensitive.
+
+ The general property parameters defined by this memo are defined by
+ the following notation:
+
+ parameter = altrepparam ; Alternate text representation
+ / cnparam ; Common name
+ / cutypeparam ; Calendar user type
+ / delfromparam ; Delegator
+ / deltoparam ; Delegatee
+ / dirparam ; Directory entry
+ / encodingparam ; Inline encoding
+ / fmttypeparam ; Format type
+ / fbtypeparam ; Free/busy time type
+ / languageparam ; Language for text
+ / memberparam ; Group or list membership
+ / partstatparam ; Participation status
+ / rangeparam ; Recurrence identifier range
+ / trigrelparam ; Alarm trigger relationship
+ / reltypeparam ; Relationship type
+ / roleparam ; Participation role
+ / rsvpparam ; RSVP expectation
+ / sentbyparam ; Sent by
+ / tzidparam ; Reference to time zone object
+ / valuetypeparam ; Property value data type
+ / ianaparam
+ ; Some other IANA registered iCalendar parameter.
+ / xparam
+ ; A non-standard, experimental parameter.
+
+ ianaparam = iana-token "=" param-value *("," param-value)
+
+ xparam =x-name "=" param-value *("," param-value)
+
+4.2.1 Alternate Text Representation
+
+ Parameter Name: ALTREP
+
+ Purpose: To specify an alternate text representation for the property
+ value.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 18]
+
+RFC 2445 iCalendar November 1998
+
+
+ altrepparam = "ALTREP" "=" DQUOTE uri DQUOTE
+
+ Description: The parameter specifies a URI that points to an
+ alternate representation for a textual property value. A property
+ specifying this parameter MUST also include a value that reflects the
+ default representation of the text value. The individual URI
+ parameter values MUST each be specified in a quoted-string.
+
+ Example:
+
+ DESCRIPTION;ALTREP="CID:<part3.msg.970415T083000 at host.com>":Project
+ XYZ Review Meeting will include the following agenda items: (a)
+ Market Overview, (b) Finances, (c) Project Management
+
+ The "ALTREP" property parameter value might point to a "text/html"
+ content portion.
+
+ Content-Type:text/html
+ Content-Id:<part3.msg.970415T083000 at host.com>
+
+ <html><body>
+ <p><b>Project XYZ Review Meeting</b> will include the following
+ agenda items:<ol><li>Market
+ Overview</li><li>Finances</li><li>Project Management</li></ol></p>
+ </body></html>
+
+4.2.2 Common Name
+
+ Parameter Name: CN
+
+ Purpose: To specify the common name to be associated with the
+ calendar user specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ cnparam = "CN" "=" param-value
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter specifies the common name to be
+ associated with the calendar user specified by the property. The
+ parameter value is text. The parameter value can be used for display
+ text to be associated with the calendar address specified by the
+ property.
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 19]
+
+RFC 2445 iCalendar November 1998
+
+
+ Example:
+
+ ORGANIZER;CN="John Smith":MAILTO:jsmith at host.com
+
+4.2.3 Calendar User Type
+
+ Parameter Name: CUTYPE
+
+ Purpose: To specify the type of calendar user specified by the
+ property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ cutypeparam = "CUTYPE" "="
+ ("INDIVIDUAL" ; An individual
+ / "GROUP" ; A group of individuals
+ / "RESOURCE" ; A physical resource
+ / "ROOM" ; A room resource
+ / "UNKNOWN" ; Otherwise not known
+ / x-name ; Experimental type
+ / iana-token) ; Other IANA registered
+ ; type
+ ; Default is INDIVIDUAL
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter identifies the type of calendar
+ user specified by the property. If not specified on a property that
+ allows this parameter, the default is INDIVIDUAL.
+
+ Example:
+
+ ATTENDEE;CUTYPE=GROUP:MAILTO:ietf-calsch at imc.org
+
+4.2.4 Delegators
+
+ Parameter Name: DELEGATED-FROM
+
+ Purpose: To specify the calendar users that have delegated their
+ participation to the calendar user specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address DQUOTE
+ *("," DQUOTE cal-address DQUOTE)
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 20]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. This parameter can be specified on a property
+ that has a value type of calendar address. This parameter specifies
+ those calendar uses that have delegated their participation in a
+ group scheduled event or to-do to the calendar user specified by the
+ property. The value MUST be a MAILTO URI as defined in [RFC 1738].
+ The individual calendar address parameter values MUST each be
+ specified in a quoted-string.
+
+ Example:
+
+ ATTENDEE;DELEGATED-FROM="MAILTO:jsmith at host.com":MAILTO:
+ jdoe at host.com
+
+4.2.5 Delegatees
+
+ Parameter Name: DELEGATED-TO
+
+ Purpose: To specify the calendar users to whom the calendar user
+ specified by the property has delegated participation.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE
+ *("," DQUOTE cal-address DQUOTE)
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. This parameter specifies those calendar users
+ whom have been delegated participation in a group scheduled event or
+ to-do by the calendar user specified by the property. The value MUST
+ be a MAILTO URI as defined in [RFC 1738]. The individual calendar
+ address parameter values MUST each be specified in a quoted-string.
+
+ Example:
+
+ ATTENDEE;DELEGATED-TO="MAILTO:jdoe at host.com","MAILTO:jqpublic@
+ host.com":MAILTO:jsmith at host.com
+
+4.2.6 Directory Entry Reference
+
+ Parameter Name: DIR
+
+ Purpose: To specify reference to a directory entry associated with
+ the calendar user specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+
+
+Dawson & Stenerson Standards Track [Page 21]
+
+RFC 2445 iCalendar November 1998
+
+
+ dirparam = "DIR" "=" DQUOTE uri DQUOTE
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter specifies a reference to the
+ directory entry associated with the calendar user specified by the
+ property. The parameter value is a URI. The individual URI parameter
+ values MUST each be specified in a quoted-string.
+
+ Example:
+
+ ORGANIZER;DIR="ldap://host.com:6666/o=eDABC%20Industries,c=3DUS??
+ (cn=3DBJim%20Dolittle)":MAILTO:jimdo at host1.com
+
+4.2.7 Inline Encoding
+
+ Parameter Name: ENCODING
+
+ Purpose: To specify an alternate inline encoding for the property
+ value.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ encodingparam = "ENCODING" "="
+ ("8BIT"
+ ; "8bit" text encoding is defined in [RFC 2045]
+ / "BASE64"
+ ; "BASE64" binary encoding format is defined in [RFC 2045]
+ / iana-token
+ ; Some other IANA registered iCalendar encoding type
+ / x-name)
+ ; A non-standard, experimental encoding type
+
+ Description: The property parameter identifies the inline encoding
+ used in a property value. The default encoding is "8BIT",
+ corresponding to a property value consisting of text. The "BASE64"
+ encoding type corresponds to a property value encoded using the
+ "BASE64" encoding defined in [RFC 2045].
+
+ If the value type parameter is ";VALUE=BINARY", then the inline
+ encoding parameter MUST be specified with the value
+ ";ENCODING=BASE64".
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 22]
+
+RFC 2445 iCalendar November 1998
+
+
+ Example:
+
+ ATTACH;FMTYPE=IMAGE/JPEG;ENCODING=BASE64;VALUE=BINARY:MIICajC
+ CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA
+ qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw
+ <...remainder of "BASE64" encoded binary data...>
+
+4.2.8 Format Type
+
+ Parameter Name: FMTTYPE
+
+ Purpose: To specify the content type of a referenced object.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ fmttypeparam = "FMTTYPE" "=" iana-token
+ ; A IANA registered content type
+ / x-name
+ ; A non-standard content type
+
+ Description: This parameter can be specified on properties that are
+ used to reference an object. The parameter specifies the content type
+ of the referenced object. For example, on the "ATTACH" property, a
+ FTP type URI value does not, by itself, necessarily convey the type
+ of content associated with the resource. The parameter value MUST be
+ the TEXT for either an IANA registered content type or a non-standard
+ content type.
+
+ Example:
+
+ ATTACH;FMTTYPE=application/binary:ftp://domain.com/pub/docs/
+ agenda.doc
+
+4.2.9 Free/Busy Time Type
+
+ Parameter Name: FBTYPE
+
+ Purpose: To specify the free or busy time type.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY"
+ / "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE"
+ / x-name
+ ; Some experimental iCalendar data type.
+ / iana-token)
+
+
+
+Dawson & Stenerson Standards Track [Page 23]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; Some other IANA registered iCalendar data type.
+
+ Description: The parameter specifies the free or busy time type. The
+ value FREE indicates that the time interval is free for scheduling.
+ The value BUSY indicates that the time interval is busy because one
+ or more events have been scheduled for that interval. The value
+ BUSY-UNAVAILABLE indicates that the time interval is busy and that
+ the interval can not be scheduled. The value BUSY-TENTATIVE indicates
+ that the time interval is busy because one or more events have been
+ tentatively scheduled for that interval. If not specified on a
+ property that allows this parameter, the default is BUSY.
+
+ Example: The following is an example of this parameter on a FREEBUSY
+ property.
+
+ FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z
+
+4.2.10 Language
+
+ Parameter Name: LANGUAGE
+
+ Purpose: To specify the language for text values in a property or
+ property parameter.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ languageparam = "LANGUAGE" "=" language
+
+ language = <Text identifying a language, as defined in [RFC 1766]>
+
+ Description: This parameter can be specified on properties with a
+ text value type. The parameter identifies the language of the text in
+ the property or property parameter value. The value of the "language"
+ property parameter is that defined in [RFC 1766].
+
+ For transport in a MIME entity, the Content-Language header field can
+ be used to set the default language for the entire body part.
+ Otherwise, no default language is assumed.
+
+ Example:
+
+ SUMMARY;LANGUAGE=us-EN:Company Holiday Party
+
+ LOCATION;LANGUAGE=en:Germany
+ LOCATION;LANGUAGE=no:Tyskland
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 24]
+
+RFC 2445 iCalendar November 1998
+
+
+ The following example makes use of the Quoted-Printable encoding in
+ order to represent non-ASCII characters.
+
+ LOCATION;LANGUAGE=da:K=F8benhavn
+ LOCATION;LANGUAGE=en:Copenhagen
+
+4.2.11 Group or List Membership
+
+ Parameter Name: MEMBER
+
+ Purpose: To specify the group or list membership of the calendar user
+ specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE
+ *("," DQUOTE cal-address DQUOTE)
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter identifies the groups or list
+ membership for the calendar user specified by the property. The
+ parameter value either a single calendar address in a quoted-string
+ or a COMMA character (US-ASCII decimal 44) list of calendar
+ addresses, each in a quoted-string. The individual calendar address
+ parameter values MUST each be specified in a quoted-string.
+
+ Example:
+
+ ATTENDEE;MEMBER="MAILTO:ietf-calsch at imc.org":MAILTO:jsmith at host.com
+
+ ATTENDEE;MEMBER="MAILTO:projectA at host.com","MAILTO:projectB at host.
+ com":MAILTO:janedoe at host.com
+
+4.2.12 Participation Status
+
+ Parameter Name: PARTSTAT
+
+ Purpose: To specify the participation status for the calendar user
+ specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ partstatparam = "PARTSTAT" "="
+ ("NEEDS-ACTION" ; Event needs action
+ / "ACCEPTED" ; Event accepted
+ / "DECLINED" ; Event declined
+
+
+
+Dawson & Stenerson Standards Track [Page 25]
+
+RFC 2445 iCalendar November 1998
+
+
+ / "TENTATIVE" ; Event tentatively
+ ; accepted
+ / "DELEGATED" ; Event delegated
+ / x-name ; Experimental status
+ / iana-token) ; Other IANA registered
+ ; status
+ ; These are the participation statuses for a "VEVENT". Default is
+ ; NEEDS-ACTION
+ partstatparam /= "PARTSTAT" "="
+ ("NEEDS-ACTION" ; To-do needs action
+ / "ACCEPTED" ; To-do accepted
+ / "DECLINED" ; To-do declined
+ / "TENTATIVE" ; To-do tentatively
+ ; accepted
+ / "DELEGATED" ; To-do delegated
+ / "COMPLETED" ; To-do completed.
+ ; COMPLETED property has
+ ;date/time completed.
+ / "IN-PROCESS" ; To-do in process of
+ ; being completed
+ / x-name ; Experimental status
+ / iana-token) ; Other IANA registered
+ ; status
+ ; These are the participation statuses for a "VTODO". Default is
+ ; NEEDS-ACTION
+
+ partstatparam /= "PARTSTAT" "="
+ ("NEEDS-ACTION" ; Journal needs action
+ / "ACCEPTED" ; Journal accepted
+ / "DECLINED" ; Journal declined
+ / x-name ; Experimental status
+ / iana-token) ; Other IANA registered
+ ; status
+ ; These are the participation statuses for a "VJOURNAL". Default is
+ ; NEEDS-ACTION
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter identifies the participation
+ status for the calendar user specified by the property value. The
+ parameter values differ depending on whether they are associated with
+ a group scheduled "VEVENT", "VTODO" or "VJOURNAL". The values MUST
+ match one of the values allowed for the given calendar component. If
+ not specified on a property that allows this parameter, the default
+ value is NEEDS-ACTION.
+
+ Example:
+
+ ATTENDEE;PARTSTAT=DECLINED:MAILTO:jsmith at host.com
+
+
+
+Dawson & Stenerson Standards Track [Page 26]
+
+RFC 2445 iCalendar November 1998
+
+
+4.2.13 Recurrence Identifier Range
+
+ Parameter Name: RANGE
+
+ Purpose: To specify the effective range of recurrence instances from
+ the instance specified by the recurrence identifier specified by the
+ property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ rangeparam = "RANGE" "=" ("THISANDPRIOR"
+ ; To specify all instances prior to the recurrence identifier
+ / "THISANDFUTURE")
+ ; To specify the instance specified by the recurrence identifier
+ ; and all subsequent recurrence instances
+
+ Description: The parameter can be specified on a property that
+ specifies a recurrence identifier. The parameter specifies the
+ effective range of recurrence instances that is specified by the
+ property. The effective range is from the recurrence identified
+ specified by the property. If this parameter is not specified an
+ allowed property, then the default range is the single instance
+ specified by the recurrence identifier value of the property. The
+ parameter value can be "THISANDPRIOR" to indicate a range defined by
+ the recurrence identified value of the property and all prior
+ instances. The parameter value can also be "THISANDFUTURE" to
+ indicate a range defined by the recurrence identifier and all
+ subsequent instances.
+
+ Example:
+
+ RECURRENCE-ID;RANGE=THISANDPRIOR:19980401T133000Z
+
+4.2.14 Alarm Trigger Relationship
+
+ Parameter Name: RELATED
+
+ Purpose: To specify the relationship of the alarm trigger with
+ respect to the start or end of the calendar component.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ trigrelparam = "RELATED" "="
+ ("START" ; Trigger off of start
+ / "END") ; Trigger off of end
+
+
+
+
+Dawson & Stenerson Standards Track [Page 27]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: The parameter can be specified on properties that
+ specify an alarm trigger with a DURATION value type. The parameter
+ specifies whether the alarm will trigger relative to the start or end
+ of the calendar component. The parameter value START will set the
+ alarm to trigger off the start of the calendar component; the
+ parameter value END will set the alarm to trigger off the end of the
+ calendar component. If the parameter is not specified on an allowable
+ property, then the default is START.
+
+ Example:
+
+ TRIGGER;RELATED=END:PT5M
+
+4.2.15 Relationship Type
+
+ Parameter Name: RELTYPE
+
+ Purpose: To specify the type of hierarchical relationship associated
+ with the calendar component specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ reltypeparam = "RELTYPE" "="
+ ("PARENT" ; Parent relationship. Default.
+ / "CHILD" ; Child relationship
+ / "SIBLING ; Sibling relationship
+ / iana-token ; Some other IANA registered
+ ; iCalendar relationship type
+ / x-name) ; A non-standard, experimental
+ ; relationship type
+
+ Description: This parameter can be specified on a property that
+ references another related calendar. The parameter specifies the
+ hierarchical relationship type of the calendar component referenced
+ by the property. The parameter value can be PARENT, to indicate that
+ the referenced calendar component is a superior of calendar
+ component; CHILD to indicate that the referenced calendar component
+ is a subordinate of the calendar component; SIBLING to indicate that
+ the referenced calendar component is a peer of the calendar
+ component. If this parameter is not specified on an allowable
+ property, the default relationship type is PARENT.
+
+ Example:
+
+ RELATED-TO;RELTYPE=SIBLING:<19960401-080045-4000F192713 at host.com>
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 28]
+
+RFC 2445 iCalendar November 1998
+
+
+4.2.16 Participation Role
+
+ Parameter Name: ROLE
+
+ Purpose: To specify the participation role for the calendar user
+ specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ roleparam = "ROLE" "="
+ ("CHAIR" ; Indicates chair of the
+ ; calendar entity
+ / "REQ-PARTICIPANT" ; Indicates a participant whose
+ ; participation is required
+ / "OPT-PARTICIPANT" ; Indicates a participant whose
+ ; participation is optional
+ / "NON-PARTICIPANT" ; Indicates a participant who is
+ ; copied for information
+ ; purposes only
+ / x-name ; Experimental role
+ / iana-token) ; Other IANA role
+ ; Default is REQ-PARTICIPANT
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter specifies the participation
+ role for the calendar user specified by the property in the group
+ schedule calendar component. If not specified on a property that
+ allows this parameter, the default value is REQ-PARTICIPANT.
+
+ Example:
+
+ ATTENDEE;ROLE=CHAIR:MAILTO:mrbig at host.com
+
+4.2.17 RSVP Expectation
+
+ Parameter Name: RSVP
+
+ Purpose: To specify whether there is an expectation of a favor of a
+ reply from the calendar user specified by the property value.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ rsvpparam = "RSVP" "=" ("TRUE" / "FALSE")
+ ; Default is FALSE
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 29]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter identifies the expectation of a
+ reply from the calendar user specified by the property value. This
+ parameter is used by the "Organizer" to request a participation
+ status reply from an "Attendee" of a group scheduled event or to-do.
+ If not specified on a property that allows this parameter, the
+ default value is FALSE.
+
+ Example:
+
+ ATTENDEE;RSVP=TRUE:MAILTO:jsmith at host.com
+
+4.2.18 Sent By
+
+ Parameter Name: SENT-BY
+
+ Purpose: To specify the calendar user that is acting on behalf of the
+ calendar user specified by the property.
+
+ Format Definition: The property parameter is defined by the following
+ notation:
+
+ sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTE
+
+ Description: This parameter can be specified on properties with a
+ CAL-ADDRESS value type. The parameter specifies the calendar user
+ that is acting on behalf of the calendar user specified by the
+ property. The parameter value MUST be a MAILTO URI as defined in [RFC
+ 1738]. The individual calendar address parameter values MUST each be
+ specified in a quoted-string.
+
+ Example:
+
+ ORGANIZER;SENT-BY:"MAILTO:sray at host.com":MAILTO:jsmith at host.com
+
+4.2.19 Time Zone Identifier
+
+ Parameter Name: TZID
+
+ Purpose: To specify the identifier for the time zone definition for a
+ time component in the property value.
+
+ Format Definition: This property parameter is defined by the
+ following notation:
+
+ tzidparam = "TZID" "=" [tzidprefix] paramtext CRLF
+
+ tzidprefix = "/"
+
+
+
+Dawson & Stenerson Standards Track [Page 30]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: The parameter MUST be specified on the "DTSTART",
+ "DTEND", "DUE", "EXDATE" and "RDATE" properties when either a DATE-
+ TIME or TIME value type is specified and when the value is not either
+ a UTC or a "floating" time. Refer to the DATE-TIME or TIME value type
+ definition for a description of UTC and "floating time" formats. This
+ property parameter specifies a text value which uniquely identifies
+ the "VTIMEZONE" calendar component to be used when evaluating the
+ time portion of the property. The value of the TZID property
+ parameter will be equal to the value of the TZID property for the
+ matching time zone definition. An individual "VTIMEZONE" calendar
+ component MUST be specified for each unique "TZID" parameter value
+ specified in the iCalendar object.
+
+ The parameter MUST be specified on properties with a DATE-TIME value
+ if the DATE-TIME is not either a UTC or a "floating" time.
+
+ The presence of the SOLIDUS character (US-ASCII decimal 47) as a
+ prefix, indicates that this TZID represents a unique ID in a globally
+ defined time zone registry (when such registry is defined).
+
+ Note: This document does not define a naming convention for time
+ zone identifiers. Implementers may want to use the naming
+ conventions defined in existing time zone specifications such as
+ the public-domain Olson database [TZ]. The specification of
+ globally unique time zone identifiers is not addressed by this
+ document and is left for future study.
+
+ The following are examples of this property parameter:
+
+ DTSTART;TZID=US-Eastern:19980119T020000
+
+ DTEND;TZID=US-Eastern:19980119T030000
+
+ The TZID property parameter MUST NOT be applied to DATE-TIME or TIME
+ properties whose time values are specified in UTC.
+
+ The use of local time in a DATE-TIME or TIME value without the TZID
+ property parameter is to be interpreted as a local time value,
+ regardless of the existence of "VTIMEZONE" calendar components in the
+ iCalendar object.
+
+ For more information see the sections on the data types DATE-TIME and
+ TIME.
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 31]
+
+RFC 2445 iCalendar November 1998
+
+
+4.2.20 Value Data Types
+
+ Parameter Name: VALUE
+
+ Purpose: To explicitly specify the data type format for a property
+ value.
+
+ Format Definition: The "VALUE" property parameter is defined by the
+ following notation:
+
+ valuetypeparam = "VALUE" "=" valuetype
+
+ valuetype = ("BINARY"
+ / "BOOLEAN"
+ / "CAL-ADDRESS"
+ / "DATE"
+ / "DATE-TIME"
+ / "DURATION"
+ / "FLOAT"
+ / "INTEGER"
+ / "PERIOD"
+ / "RECUR"
+ / "TEXT"
+ / "TIME"
+ / "URI"
+ / "UTC-OFFSET"
+ / x-name
+ ; Some experimental iCalendar data type.
+ / iana-token)
+ ; Some other IANA registered iCalendar data type.
+
+ Description: The parameter specifies the data type and format of the
+ property value. The property values MUST be of a single value type.
+ For example, a "RDATE" property cannot have a combination of DATE-
+ TIME and TIME value types.
+
+ If the property's value is the default value type, then this
+ parameter need not be specified. However, if the property's default
+ value type is overridden by some other allowable value type, then
+ this parameter MUST be specified.
+
+4.3 Property Value Data Types
+
+ The properties in an iCalendar object are strongly typed. The
+ definition of each property restricts the value to be one of the
+ value data types, or simply value types, defined in this section. The
+ value type for a property will either be specified implicitly as the
+ default value type or will be explicitly specified with the "VALUE"
+
+
+
+Dawson & Stenerson Standards Track [Page 32]
+
+RFC 2445 iCalendar November 1998
+
+
+ parameter. If the value type of a property is one of the alternate
+ valid types, then it MUST be explicitly specified with the "VALUE"
+ parameter.
+
+4.3.1 Binary
+
+ Value Name: BINARY
+
+ Purpose: This value type is used to identify properties that contain
+ a character encoding of inline binary data. For example, an inline
+ attachment of an object code might be included in an iCalendar
+ object.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ binary = *(4b-char) [b-end]
+ ; A "BASE64" encoded character string, as defined by [RFC 2045].
+
+ b-end = (2b-char "==") / (3b-char "=")
+
+ b-char = ALPHA / DIGIT / "+" / "/"
+
+ Description: Property values with this value type MUST also include
+ the inline encoding parameter sequence of ";ENCODING=BASE64". That
+ is, all inline binary data MUST first be character encoded using the
+ "BASE64" encoding method defined in [RFC 2045]. No additional content
+ value encoding (i.e., BACKSLASH character encoding) is defined for
+ this value type.
+
+ Example: The following is an abridged example of a "BASE64" encoded
+ binary value data.
+
+ ATTACH;VALUE=BINARY;ENCODING=BASE64:MIICajCCAdOgAwIBAgICBEUwDQY
+ JKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlI
+ ENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZv
+ <...remainder of "BASE64" encoded binary data...>
+
+4.3.2 Boolean
+
+ Value Name: BOOLEAN
+
+ Purpose: This value type is used to identify properties that contain
+ either a "TRUE" or "FALSE" Boolean value.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 33]
+
+RFC 2445 iCalendar November 1998
+
+
+ boolean = "TRUE" / "FALSE"
+
+ Description: These values are case insensitive text. No additional
+ content value encoding (i.e., BACKSLASH character encoding) is
+ defined for this value type.
+
+ Example: The following is an example of a hypothetical property that
+ has a BOOLEAN value type:
+
+ GIBBERISH:TRUE
+
+4.3.3 Calendar User Address
+
+ Value Name: CAL-ADDRESS
+
+ Purpose: This value type is used to identify properties that contain
+ a calendar user address.
+
+ Formal Definition: The value type is as defined by the following
+ notation:
+
+ cal-address = uri
+
+ Description: The value is a URI as defined by [RFC 1738] or any other
+ IANA registered form for a URI. When used to address an Internet
+ email transport address for a calendar user, the value MUST be a
+ MAILTO URI, as defined by [RFC 1738]. No additional content value
+ encoding (i.e., BACKSLASH character encoding) is defined for this
+ value type.
+
+ Example:
+
+ ATTENDEE:MAILTO:jane_doe at host.com
+
+4.3.4 Date
+
+ Value Name: DATE
+
+ Purpose: This value type is used to identify values that contain a
+ calendar date.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ date = date-value
+
+ date-value = date-fullyear date-month date-mday
+ date-fullyear = 4DIGIT
+
+
+
+Dawson & Stenerson Standards Track [Page 34]
+
+RFC 2445 iCalendar November 1998
+
+
+ date-month = 2DIGIT ;01-12
+ date-mday = 2DIGIT ;01-28, 01-29, 01-30, 01-31
+ ;based on month/year
+
+ Description: If the property permits, multiple "date" values are
+ specified as a COMMA character (US-ASCII decimal 44) separated list
+ of values. The format for the value type is expressed as the [ISO
+ 8601] complete representation, basic format for a calendar date. The
+ textual format specifies a four-digit year, two-digit month, and
+ two-digit day of the month. There are no separator characters between
+ the year, month and day component text.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example: The following represents July 14, 1997:
+
+ 19970714
+
+4.3.5 Date-Time
+
+ Value Name: DATE-TIME
+
+ Purpose: This value type is used to identify values that specify a
+ precise calendar date and time of day.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ date-time = date "T" time ;As specified in the date and time
+ ;value definitions
+
+ Description: If the property permits, multiple "date-time" values are
+ specified as a COMMA character (US-ASCII decimal 44) separated list
+ of values. No additional content value encoding (i.e., BACKSLASH
+ character encoding) is defined for this value type.
+
+ The "DATE-TIME" data type is used to identify values that contain a
+ precise calendar date and time of day. The format is based on the
+ [ISO 8601] complete representation, basic format for a calendar date
+ and time of day. The text format is a concatenation of the "date",
+ followed by the LATIN CAPITAL LETTER T character (US-ASCII decimal
+ 84) time designator, followed by the "time" format.
+
+ The "DATE-TIME" data type expresses time values in three forms:
+
+ The form of date and time with UTC offset MUST NOT be used. For
+ example, the following is not valid for a date-time value:
+
+
+
+Dawson & Stenerson Standards Track [Page 35]
+
+RFC 2445 iCalendar November 1998
+
+
+ DTSTART:19980119T230000-0800 ;Invalid time format
+
+ FORM #1: DATE WITH LOCAL TIME
+
+ The date with local time form is simply a date-time value that does
+ not contain the UTC designator nor does it reference a time zone. For
+ example, the following represents Janurary 18, 1998, at 11 PM:
+
+ DTSTART:19980118T230000
+
+ Date-time values of this type are said to be "floating" and are not
+ bound to any time zone in particular. They are used to represent the
+ same hour, minute, and second value regardless of which time zone is
+ currently being observed. For example, an event can be defined that
+ indicates that an individual will be busy from 11:00 AM to 1:00 PM
+ every day, no matter which time zone the person is in. In these
+ cases, a local time can be specified. The recipient of an iCalendar
+ object with a property value consisting of a local time, without any
+ relative time zone information, SHOULD interpret the value as being
+ fixed to whatever time zone the ATTENDEE is in at any given moment.
+ This means that two ATTENDEEs, in different time zones, receiving the
+ same event definition as a floating time, may be participating in the
+ event at different actual times. Floating time SHOULD only be used
+ where that is the reasonable behavior.
+
+ In most cases, a fixed time is desired. To properly communicate a
+ fixed time in a property value, either UTC time or local time with
+ time zone reference MUST be specified.
+
+ The use of local time in a DATE-TIME value without the TZID property
+ parameter is to be interpreted as floating time, regardless of the
+ existence of "VTIMEZONE" calendar components in the iCalendar object.
+
+ FORM #2: DATE WITH UTC TIME
+
+ The date with UTC time, or absolute time, is identified by a LATIN
+ CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC
+ designator, appended to the time value. For example, the following
+ represents January 19, 1998, at 0700 UTC:
+
+ DTSTART:19980119T070000Z
+
+ The TZID property parameter MUST NOT be applied to DATE-TIME
+ properties whose time values are specified in UTC.
+
+ FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 36]
+
+RFC 2445 iCalendar November 1998
+
+
+ The date and local time with reference to time zone information is
+ identified by the use the TZID property parameter to reference the
+ appropriate time zone definition. TZID is discussed in detail in the
+ section on Time Zone. For example, the following represents 2 AM in
+ New York on Janurary 19, 1998:
+
+ DTSTART;TZID=US-Eastern:19980119T020000
+
+ Example: The following represents July 14, 1997, at 1:30 PM in New
+ York City in each of the three time formats, using the "DTSTART"
+ property.
+
+ DTSTART:19970714T133000 ;Local time
+ DTSTART:19970714T173000Z ;UTC time
+ DTSTART;TZID=US-Eastern:19970714T133000 ;Local time and time
+ ; zone reference
+
+ A time value MUST ONLY specify 60 seconds when specifying the
+ periodic "leap second" in the time value. For example:
+
+ COMPLETED:19970630T235960Z
+
+4.3.6 Duration
+
+ Value Name: DURATION
+
+ Purpose: This value type is used to identify properties that contain
+ a duration of time.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week)
+
+ dur-date = dur-day [dur-time]
+ dur-time = "T" (dur-hour / dur-minute / dur-second)
+ dur-week = 1*DIGIT "W"
+ dur-hour = 1*DIGIT "H" [dur-minute]
+ dur-minute = 1*DIGIT "M" [dur-second]
+ dur-second = 1*DIGIT "S"
+ dur-day = 1*DIGIT "D"
+
+ Description: If the property permits, multiple "duration" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values. The format is expressed as the [ISO 8601] basic format for
+ the duration of time. The format can represent durations in terms of
+ weeks, days, hours, minutes, and seconds.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 37]
+
+RFC 2445 iCalendar November 1998
+
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) are defined for this value type.
+
+ Example: A duration of 15 days, 5 hours and 20 seconds would be:
+
+ P15DT5H0M20S
+
+ A duration of 7 weeks would be:
+
+ P7W
+
+4.3.7 Float
+
+ Value Name: FLOAT
+
+ Purpose: This value type is used to identify properties that contain
+ a real number value.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]
+
+ Description: If the property permits, multiple "float" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example:
+
+ 1000000.0000001
+ 1.333
+ -3.14
+
+4.3.8 Integer
+
+ Value Name:INTEGER
+
+ Purpose: This value type is used to identify properties that contain
+ a signed integer value.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ integer = (["+"] / "-") 1*DIGIT
+
+
+
+
+Dawson & Stenerson Standards Track [Page 38]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: If the property permits, multiple "integer" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values. The valid range for "integer" is -2147483648 to
+ 2147483647. If the sign is not specified, then the value is assumed
+ to be positive.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example:
+
+ 1234567890
+ -1234567890
+ +1234567890
+ 432109876
+
+4.3.9 Period of Time
+
+ Value Name: PERIOD
+
+ Purpose: This value type is used to identify values that contain a
+ precise period of time.
+
+ Formal Definition: The data type is defined by the following
+ notation:
+
+ period = period-explicit / period-start
+
+ period-explicit = date-time "/" date-time
+ ; [ISO 8601] complete representation basic format for a period of
+ ; time consisting of a start and end. The start MUST be before the
+ ; end.
+
+ period-start = date-time "/" dur-value
+ ; [ISO 8601] complete representation basic format for a period of
+ ; time consisting of a start and positive duration of time.
+
+ Description: If the property permits, multiple "period" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values. There are two forms of a period of time. First, a period
+ of time is identified by its start and its end. This format is
+ expressed as the [ISO 8601] complete representation, basic format for
+ "DATE-TIME" start of the period, followed by a SOLIDUS character
+ (US-ASCII decimal 47), followed by the "DATE-TIME" of the end of the
+ period. The start of the period MUST be before the end of the period.
+ Second, a period of time can also be defined by a start and a
+ positive duration of time. The format is expressed as the [ISO 8601]
+ complete representation, basic format for the "DATE-TIME" start of
+
+
+
+Dawson & Stenerson Standards Track [Page 39]
+
+RFC 2445 iCalendar November 1998
+
+
+ the period, followed by a SOLIDUS character (US-ASCII decimal 47),
+ followed by the [ISO 8601] basic format for "DURATION" of the period.
+
+ Example: The period starting at 18:00:00 UTC, on January 1, 1997 and
+ ending at 07:00:00 UTC on January 2, 1997 would be:
+
+ 19970101T180000Z/19970102T070000Z
+
+ The period start at 18:00:00 on January 1, 1997 and lasting 5 hours
+ and 30 minutes would be:
+
+ 19970101T180000Z/PT5H30M
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+4.3.10 Recurrence Rule
+
+ Value Name: RECUR
+
+ Purpose: This value type is used to identify properties that contain
+ a recurrence rule specification.
+
+ Formal Definition: The value type is defined by the following
+ notation:
+
+ recur = "FREQ"=freq *(
+
+ ; either UNTIL or COUNT may appear in a 'recur',
+ ; but UNTIL and COUNT MUST NOT occur in the same 'recur'
+
+ ( ";" "UNTIL" "=" enddate ) /
+ ( ";" "COUNT" "=" 1*DIGIT ) /
+
+ ; the rest of these keywords are optional,
+ ; but MUST NOT occur more than once
+
+ ( ";" "INTERVAL" "=" 1*DIGIT ) /
+ ( ";" "BYSECOND" "=" byseclist ) /
+ ( ";" "BYMINUTE" "=" byminlist ) /
+ ( ";" "BYHOUR" "=" byhrlist ) /
+ ( ";" "BYDAY" "=" bywdaylist ) /
+ ( ";" "BYMONTHDAY" "=" bymodaylist ) /
+ ( ";" "BYYEARDAY" "=" byyrdaylist ) /
+ ( ";" "BYWEEKNO" "=" bywknolist ) /
+ ( ";" "BYMONTH" "=" bymolist ) /
+ ( ";" "BYSETPOS" "=" bysplist ) /
+ ( ";" "WKST" "=" weekday ) /
+
+
+
+Dawson & Stenerson Standards Track [Page 40]
+
+RFC 2445 iCalendar November 1998
+
+
+ ( ";" x-name "=" text )
+ )
+
+ freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
+ / "WEEKLY" / "MONTHLY" / "YEARLY"
+
+ enddate = date
+ enddate =/ date-time ;An UTC value
+
+ byseclist = seconds / ( seconds *("," seconds) )
+
+ seconds = 1DIGIT / 2DIGIT ;0 to 59
+
+ byminlist = minutes / ( minutes *("," minutes) )
+
+ minutes = 1DIGIT / 2DIGIT ;0 to 59
+
+ byhrlist = hour / ( hour *("," hour) )
+
+ hour = 1DIGIT / 2DIGIT ;0 to 23
+
+ bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) )
+
+ weekdaynum = [([plus] ordwk / minus ordwk)] weekday
+
+ plus = "+"
+
+ minus = "-"
+
+ ordwk = 1DIGIT / 2DIGIT ;1 to 53
+
+ weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
+ ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
+ ;FRIDAY, SATURDAY and SUNDAY days of the week.
+
+ bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) )
+
+ monthdaynum = ([plus] ordmoday) / (minus ordmoday)
+
+ ordmoday = 1DIGIT / 2DIGIT ;1 to 31
+
+ byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) )
+
+ yeardaynum = ([plus] ordyrday) / (minus ordyrday)
+
+ ordyrday = 1DIGIT / 2DIGIT / 3DIGIT ;1 to 366
+
+ bywknolist = weeknum / ( weeknum *("," weeknum) )
+
+
+
+Dawson & Stenerson Standards Track [Page 41]
+
+RFC 2445 iCalendar November 1998
+
+
+ weeknum = ([plus] ordwk) / (minus ordwk)
+
+ bymolist = monthnum / ( monthnum *("," monthnum) )
+
+ monthnum = 1DIGIT / 2DIGIT ;1 to 12
+
+ bysplist = setposday / ( setposday *("," setposday) )
+
+ setposday = yeardaynum
+
+ Description: If the property permits, multiple "recur" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values. The value type is a structured value consisting of a list
+ of one or more recurrence grammar parts. Each rule part is defined by
+ a NAME=VALUE pair. The rule parts are separated from each other by
+ the SEMICOLON character (US-ASCII decimal 59). The rule parts are not
+ ordered in any particular sequence. Individual rule parts MUST only
+ be specified once.
+
+ The FREQ rule part identifies the type of recurrence rule. This rule
+ part MUST be specified in the recurrence rule. Valid values include
+ SECONDLY, to specify repeating events based on an interval of a
+ second or more; MINUTELY, to specify repeating events based on an
+ interval of a minute or more; HOURLY, to specify repeating events
+ based on an interval of an hour or more; DAILY, to specify repeating
+ events based on an interval of a day or more; WEEKLY, to specify
+ repeating events based on an interval of a week or more; MONTHLY, to
+ specify repeating events based on an interval of a month or more; and
+ YEARLY, to specify repeating events based on an interval of a year or
+ more.
+
+ The INTERVAL rule part contains a positive integer representing how
+ often the recurrence rule repeats. The default value is "1", meaning
+ every second for a SECONDLY rule, or every minute for a MINUTELY
+ rule, every hour for an HOURLY rule, every day for a DAILY rule,
+ every week for a WEEKLY rule, every month for a MONTHLY rule and
+ every year for a YEARLY rule.
+
+ The UNTIL rule part defines a date-time value which bounds the
+ recurrence rule in an inclusive manner. If the value specified by
+ UNTIL is synchronized with the specified recurrence, this date or
+ date-time becomes the last instance of the recurrence. If specified
+ as a date-time value, then it MUST be specified in an UTC time
+ format. If not present, and the COUNT rule part is also not present,
+ the RRULE is considered to repeat forever.
+
+ The COUNT rule part defines the number of occurrences at which to
+ range-bound the recurrence. The "DTSTART" property value, if
+
+
+
+Dawson & Stenerson Standards Track [Page 42]
+
+RFC 2445 iCalendar November 1998
+
+
+ specified, counts as the first occurrence.
+
+ The BYSECOND rule part specifies a COMMA character (US-ASCII decimal
+ 44) separated list of seconds within a minute. Valid values are 0 to
+ 59. The BYMINUTE rule part specifies a COMMA character (US-ASCII
+ decimal 44) separated list of minutes within an hour. Valid values
+ are 0 to 59. The BYHOUR rule part specifies a COMMA character (US-
+ ASCII decimal 44) separated list of hours of the day. Valid values
+ are 0 to 23.
+
+ The BYDAY rule part specifies a COMMA character (US-ASCII decimal 44)
+ separated list of days of the week; MO indicates Monday; TU indicates
+ Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates
+ Friday; SA indicates Saturday; SU indicates Sunday.
+
+ Each BYDAY value can also be preceded by a positive (+n) or negative
+ (-n) integer. If present, this indicates the nth occurrence of the
+ specific day within the MONTHLY or YEARLY RRULE. For example, within
+ a MONTHLY rule, +1MO (or simply 1MO) represents the first Monday
+ within the month, whereas -1MO represents the last Monday of the
+ month. If an integer modifier is not present, it means all days of
+ this type within the specified frequency. For example, within a
+ MONTHLY rule, MO represents all Mondays within the month.
+
+ The BYMONTHDAY rule part specifies a COMMA character (ASCII decimal
+ 44) separated list of days of the month. Valid values are 1 to 31 or
+ -31 to -1. For example, -10 represents the tenth to the last day of
+ the month.
+
+ The BYYEARDAY rule part specifies a COMMA character (US-ASCII decimal
+ 44) separated list of days of the year. Valid values are 1 to 366 or
+ -366 to -1. For example, -1 represents the last day of the year
+ (December 31st) and -306 represents the 306th to the last day of the
+ year (March 1st).
+
+ The BYWEEKNO rule part specifies a COMMA character (US-ASCII decimal
+ 44) separated list of ordinals specifying weeks of the year. Valid
+ values are 1 to 53 or -53 to -1. This corresponds to weeks according
+ to week numbering as defined in [ISO 8601]. A week is defined as a
+ seven day period, starting on the day of the week defined to be the
+ week start (see WKST). Week number one of the calendar year is the
+ first week which contains at least four (4) days in that calendar
+ year. This rule part is only valid for YEARLY rules. For example, 3
+ represents the third week of the year.
+
+ Note: Assuming a Monday week start, week 53 can only occur when
+ Thursday is January 1 or if it is a leap year and Wednesday is
+ January 1.
+
+
+
+Dawson & Stenerson Standards Track [Page 43]
+
+RFC 2445 iCalendar November 1998
+
+
+ The BYMONTH rule part specifies a COMMA character (US-ASCII decimal
+ 44) separated list of months of the year. Valid values are 1 to 12.
+
+ The WKST rule part specifies the day on which the workweek starts.
+ Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant
+ when a WEEKLY RRULE has an interval greater than 1, and a BYDAY rule
+ part is specified. This is also significant when in a YEARLY RRULE
+ when a BYWEEKNO rule part is specified. The default value is MO.
+
+ The BYSETPOS rule part specifies a COMMA character (US-ASCII decimal
+ 44) separated list of values which corresponds to the nth occurrence
+ within the set of events specified by the rule. Valid values are 1 to
+ 366 or -366 to -1. It MUST only be used in conjunction with another
+ BYxxx rule part. For example "the last work day of the month" could
+ be represented as:
+
+ RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1
+
+ Each BYSETPOS value can include a positive (+n) or negative (-n)
+ integer. If present, this indicates the nth occurrence of the
+ specific occurrence within the set of events specified by the rule.
+
+ If BYxxx rule part values are found which are beyond the available
+ scope (ie, BYMONTHDAY=30 in February), they are simply ignored.
+
+ Information, not contained in the rule, necessary to determine the
+ various recurrence instance start time and dates are derived from the
+ Start Time (DTSTART) entry attribute. For example,
+ "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the
+ month or a time. This information would be the same as what is
+ specified for DTSTART.
+
+ BYxxx rule parts modify the recurrence in some manner. BYxxx rule
+ parts for a period of time which is the same or greater than the
+ frequency generally reduce or limit the number of occurrences of the
+ recurrence generated. For example, "FREQ=DAILY;BYMONTH=1" reduces the
+ number of recurrence instances from all days (if BYMONTH tag is not
+ present) to all days in January. BYxxx rule parts for a period of
+ time less than the frequency generally increase or expand the number
+ of occurrences of the recurrence. For example,
+ "FREQ=YEARLY;BYMONTH=1,2" increases the number of days within the
+ yearly recurrence set from 1 (if BYMONTH tag is not present) to 2.
+
+ If multiple BYxxx rule parts are specified, then after evaluating the
+ specified FREQ and INTERVAL rule parts, the BYxxx rule parts are
+ applied to the current set of evaluated occurrences in the following
+ order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR,
+ BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are evaluated.
+
+
+
+Dawson & Stenerson Standards Track [Page 44]
+
+RFC 2445 iCalendar November 1998
+
+
+ Here is an example of evaluating multiple BYxxx rule parts.
+
+ DTSTART;TZID=US-Eastern:19970105T083000
+ RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;
+ BYMINUTE=30
+
+ First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to arrive
+ at "every other year". Then, "BYMONTH=1" would be applied to arrive
+ at "every January, every other year". Then, "BYDAY=SU" would be
+ applied to arrive at "every Sunday in January, every other year".
+ Then, "BYHOUR=8,9" would be applied to arrive at "every Sunday in
+ January at 8 AM and 9 AM, every other year". Then, "BYMINUTE=30"
+ would be applied to arrive at "every Sunday in January at 8:30 AM and
+ 9:30 AM, every other year". Then, lacking information from RRULE, the
+ second is derived from DTSTART, to end up in "every Sunday in January
+ at 8:30:00 AM and 9:30:00 AM, every other year". Similarly, if the
+ BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY or BYMONTH rule part were
+ missing, the appropriate minute, hour, day or month would have been
+ retrieved from the "DTSTART" property.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example: The following is a rule which specifies 10 meetings which
+ occur every other day:
+
+ FREQ=DAILY;COUNT=10;INTERVAL=2
+
+ There are other examples specified in the "RRULE" specification.
+
+4.3.11 Text
+
+ Value Name: TEXT
+
+ Purpose This value type is used to identify values that contain human
+ readable text.
+
+ Formal Definition: The character sets supported by this revision of
+ iCalendar are UTF-8 and US ASCII thereof. The applicability to other
+ character sets is for future work. The value type is defined by the
+ following notation.
+
+ text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)
+ ; Folded according to description above
+
+ ESCAPED-CHAR = "\\" / "\;" / "\," / "\N" / "\n")
+ ; \\ encodes \, \N or \n encodes newline
+ ; \; encodes ;, \, encodes ,
+
+
+
+Dawson & Stenerson Standards Track [Page 45]
+
+RFC 2445 iCalendar November 1998
+
+
+ TSAFE-CHAR = %x20-21 / %x23-2B / %x2D-39 / %x3C-5B
+ %x5D-7E / NON-US-ASCII
+ ; Any character except CTLs not needed by the current
+ ; character set, DQUOTE, ";", ":", "\", ","
+
+ Note: Certain other character sets may require modification of the
+ above definitions, but this is beyond the scope of this document.
+
+ Description: If the property permits, multiple "text" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values.
+
+ The language in which the text is represented can be controlled by
+ the "LANGUAGE" property parameter.
+
+ An intentional formatted text line break MUST only be included in a
+ "TEXT" property value by representing the line break with the
+ character sequence of BACKSLASH (US-ASCII decimal 92), followed by a
+ LATIN SMALL LETTER N (US-ASCII decimal 110) or a LATIN CAPITAL LETTER
+ N (US-ASCII decimal 78), that is "\n" or "\N".
+
+ The "TEXT" property values may also contain special characters that
+ are used to signify delimiters, such as a COMMA character for lists
+ of values or a SEMICOLON character for structured values. In order to
+ support the inclusion of these special characters in "TEXT" property
+ values, they MUST be escaped with a BACKSLASH character. A BACKSLASH
+ character (US-ASCII decimal 92) in a "TEXT" property value MUST be
+ escaped with another BACKSLASH character. A COMMA character in a
+ "TEXT" property value MUST be escaped with a BACKSLASH character
+ (US-ASCII decimal 92). A SEMICOLON character in a "TEXT" property
+ value MUST be escaped with a BACKSLASH character (US-ASCII decimal
+ 92). However, a COLON character in a "TEXT" property value SHALL NOT
+ be escaped with a BACKSLASH character.Example: A multiple line value
+ of:
+
+ Project XYZ Final Review
+ Conference Room - 3B
+ Come Prepared.
+
+ would be represented as:
+
+ Project XYZ Final Review\nConference Room - 3B\nCome Prepared.
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 46]
+
+RFC 2445 iCalendar November 1998
+
+
+4.3.12 Time
+
+ Value Name: TIME
+
+ Purpose: This value type is used to identify values that contain a
+ time of day.
+
+ Formal Definition: The data type is defined by the following
+ notation:
+
+ time = time-hour time-minute time-second [time-utc]
+
+ time-hour = 2DIGIT ;00-23
+ time-minute = 2DIGIT ;00-59
+ time-second = 2DIGIT ;00-60
+ ;The "60" value is used to account for "leap" seconds.
+
+ time-utc = "Z"
+
+ Description: If the property permits, multiple "time" values are
+ specified by a COMMA character (US-ASCII decimal 44) separated list
+ of values. No additional content value encoding (i.e., BACKSLASH
+ character encoding) is defined for this value type.
+
+ The "TIME" data type is used to identify values that contain a time
+ of day. The format is based on the [ISO 8601] complete
+ representation, basic format for a time of day. The text format
+ consists of a two-digit 24-hour of the day (i.e., values 0-23), two-
+ digit minute in the hour (i.e., values 0-59), and two-digit seconds
+ in the minute (i.e., values 0-60). The seconds value of 60 MUST only
+ to be used to account for "leap" seconds. Fractions of a second are
+ not supported by this format.
+
+ In parallel to the "DATE-TIME" definition above, the "TIME" data type
+ expresses time values in three forms:
+
+ The form of time with UTC offset MUST NOT be used. For example, the
+ following is NOT VALID for a time value:
+
+ 230000-0800 ;Invalid time format
+
+ FORM #1 LOCAL TIME
+
+ The local time form is simply a time value that does not contain the
+ UTC designator nor does it reference a time zone. For example, 11:00
+ PM:
+
+ 230000
+
+
+
+Dawson & Stenerson Standards Track [Page 47]
+
+RFC 2445 iCalendar November 1998
+
+
+ Time values of this type are said to be "floating" and are not bound
+ to any time zone in particular. They are used to represent the same
+ hour, minute, and second value regardless of which time zone is
+ currently being observed. For example, an event can be defined that
+ indicates that an individual will be busy from 11:00 AM to 1:00 PM
+ every day, no matter which time zone the person is in. In these
+ cases, a local time can be specified. The recipient of an iCalendar
+ object with a property value consisting of a local time, without any
+ relative time zone information, SHOULD interpret the value as being
+ fixed to whatever time zone the ATTENDEE is in at any given moment.
+ This means that two ATTENDEEs may participate in the same event at
+ different UTC times; floating time SHOULD only be used where that is
+ reasonable behavior.
+
+ In most cases, a fixed time is desired. To properly communicate a
+ fixed time in a property value, either UTC time or local time with
+ time zone reference MUST be specified.
+
+ The use of local time in a TIME value without the TZID property
+ parameter is to be interpreted as a local time value, regardless of
+ the existence of "VTIMEZONE" calendar components in the iCalendar
+ object.
+
+ FORM #2: UTC TIME
+
+ UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z
+ suffix character (US-ASCII decimal 90), the UTC designator, appended
+ to the time value. For example, the following represents 07:00 AM
+ UTC:
+
+ 070000Z
+
+ The TZID property parameter MUST NOT be applied to TIME properties
+ whose time values are specified in UTC.
+
+ FORM #3: LOCAL TIME AND TIME ZONE REFERENCE
+
+ The local time with reference to time zone information form is
+ identified by the use the TZID property parameter to reference the
+ appropriate time zone definition. TZID is discussed in detail in the
+ section on Time Zone.
+
+ Example: The following represents 8:30 AM in New York in Winter, five
+ hours behind UTC, in each of the three formats using the "X-
+ TIMEOFDAY" non-standard property:
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 48]
+
+RFC 2445 iCalendar November 1998
+
+
+ X-TIMEOFDAY:083000
+
+ X-TIMEOFDAY:133000Z
+
+ X-TIMEOFDAY;TZID=US-Eastern:083000
+
+4.3.13 URI
+
+ Value Name: URI
+
+ Purpose: This value type is used to identify values that contain a
+ uniform resource identifier (URI) type of reference to the property
+ value.
+
+ Formal Definition: The data type is defined by the following
+ notation:
+
+ uri = <As defined by any IETF RFC>
+
+ Description: This data type might be used to reference binary
+ information, for values that are large, or otherwise undesirable to
+ include directly in the iCalendar object.
+
+ The URI value formats in RFC 1738, RFC 2111 and any other IETF
+ registered value format can be specified.
+
+ Any IANA registered URI format can be used. These include, but are
+ not limited to, those defined in RFC 1738 and RFC 2111.
+
+ When a property parameter value is a URI value type, the URI MUST be
+ specified as a quoted-string value.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example: The following is a URI for a network file:
+
+ http://host1.com/my-report.txt
+
+4.3.14 UTC Offset
+
+ Value Name: UTC-OFFSET
+
+ Purpose: This value type is used to identify properties that contain
+ an offset from UTC to local time.
+
+ Formal Definition: The data type is defined by the following
+ notation:
+
+
+
+Dawson & Stenerson Standards Track [Page 49]
+
+RFC 2445 iCalendar November 1998
+
+
+ utc-offset = time-numzone ;As defined above in time data type
+
+ time-numzone = ("+" / "-") time-hour time-minute [time-
+ second]
+
+ Description: The PLUS SIGN character MUST be specified for positive
+ UTC offsets (i.e., ahead of UTC). The value of "-0000" and "-000000"
+ are not allowed. The time-second, if present, may not be 60; if
+ absent, it defaults to zero.
+
+ No additional content value encoding (i.e., BACKSLASH character
+ encoding) is defined for this value type.
+
+ Example: The following UTC offsets are given for standard time for
+ New York (five hours behind UTC) and Geneva (one hour ahead of UTC):
+
+ -0500
+
+ +0100
+
+4.4 iCalendar Object
+
+ The Calendaring and Scheduling Core Object is a collection of
+ calendaring and scheduling information. Typically, this information
+ will consist of a single iCalendar object. However, multiple
+ iCalendar objects can be sequentially grouped together. The first
+ line and last line of the iCalendar object MUST contain a pair of
+ iCalendar object delimiter strings. The syntax for an iCalendar
+ object is as follows:
+
+ icalobject = 1*("BEGIN" ":" "VCALENDAR" CRLF
+ icalbody
+ "END" ":" "VCALENDAR" CRLF)
+
+ The following is a simple example of an iCalendar object:
+
+ BEGIN:VCALENDAR
+ VERSION:2.0
+ PRODID:-//hacksw/handcal//NONSGML v1.0//EN
+ BEGIN:VEVENT
+ DTSTART:19970714T170000Z
+ DTEND:19970715T035959Z
+ SUMMARY:Bastille Day Party
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 50]
+
+RFC 2445 iCalendar November 1998
+
+
+4.5 Property
+
+ A property is the definition of an individual attribute describing a
+ calendar or a calendar component. A property takes the form defined
+ by the "contentline" notation defined in section 4.1.1.
+
+ The following is an example of a property:
+
+ DTSTART:19960415T133000Z
+
+ This memo imposes no ordering of properties within an iCalendar
+ object.
+
+ Property names, parameter names and enumerated parameter values are
+ case insensitive. For example, the property name "DUE" is the same as
+ "due" and "Due", DTSTART;TZID=US-Eastern:19980714T120000 is the same
+ as DtStart;TzID=US-Eastern:19980714T120000.
+
+4.6 Calendar Components
+
+ The body of the iCalendar object consists of a sequence of calendar
+ properties and one or more calendar components. The calendar
+ properties are attributes that apply to the calendar as a whole. The
+ calendar components are collections of properties that express a
+ particular calendar semantic. For example, the calendar component can
+ specify an event, a to-do, a journal entry, time zone information, or
+ free/busy time information, or an alarm.
+
+ The body of the iCalendar object is defined by the following
+ notation:
+
+ icalbody = calprops component
+
+ calprops = 2*(
+
+ ; 'prodid' and 'version' are both REQUIRED,
+ ; but MUST NOT occur more than once
+
+ prodid /version /
+
+ ; 'calscale' and 'method' are optional,
+ ; but MUST NOT occur more than once
+
+ calscale /
+ method /
+
+ x-prop
+
+
+
+
+Dawson & Stenerson Standards Track [Page 51]
+
+RFC 2445 iCalendar November 1998
+
+
+ )
+
+ component = 1*(eventc / todoc / journalc / freebusyc /
+ / timezonec / iana-comp / x-comp)
+
+ iana-comp = "BEGIN" ":" iana-token CRLF
+
+ 1*contentline
+
+ "END" ":" iana-token CRLF
+
+ x-comp = "BEGIN" ":" x-name CRLF
+
+ 1*contentline
+
+ "END" ":" x-name CRLF
+
+ An iCalendar object MUST include the "PRODID" and "VERSION" calendar
+ properties. In addition, it MUST include at least one calendar
+ component. Special forms of iCalendar objects are possible to publish
+ just busy time (i.e., only a "VFREEBUSY" calendar component) or time
+ zone (i.e., only a "VTIMEZONE" calendar component) information. In
+ addition, a complex iCalendar object is possible that is used to
+ capture a complete snapshot of the contents of a calendar (e.g.,
+ composite of many different calendar components). More commonly, an
+ iCalendar object will consist of just a single "VEVENT", "VTODO" or
+ "VJOURNAL" calendar component.
+
+4.6.1 Event Component
+
+ Component Name: "VEVENT"
+
+ Purpose: Provide a grouping of component properties that describe an
+ event.
+
+ Format Definition: A "VEVENT" calendar component is defined by the
+ following notation:
+
+ eventc = "BEGIN" ":" "VEVENT" CRLF
+ eventprop *alarmc
+ "END" ":" "VEVENT" CRLF
+
+ eventprop = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ class / created / description / dtstart / geo /
+
+
+
+Dawson & Stenerson Standards Track [Page 52]
+
+RFC 2445 iCalendar November 1998
+
+
+ last-mod / location / organizer / priority /
+ dtstamp / seq / status / summary / transp /
+ uid / url / recurid /
+
+ ; either 'dtend' or 'duration' may appear in
+ ; a 'eventprop', but 'dtend' and 'duration'
+ ; MUST NOT occur in the same 'eventprop'
+
+ dtend / duration /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+
+ attach / attendee / categories / comment /
+ contact / exdate / exrule / rstatus / related /
+ resources / rdate / rrule / x-prop
+
+ )
+
+ Description: A "VEVENT" calendar component is a grouping of component
+ properties, and possibly including "VALARM" calendar components, that
+ represents a scheduled amount of time on a calendar. For example, it
+ can be an activity; such as a one-hour long, department meeting from
+ 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time
+ on an individual calendar. Hence, the event will appear as an opaque
+ interval in a search for busy time. Alternately, the event can have
+ its Time Transparency set to "TRANSPARENT" in order to prevent
+ blocking of the event in searches for busy time.
+
+ The "VEVENT" is also the calendar component used to specify an
+ anniversary or daily reminder within a calendar. These events have a
+ DATE value type for the "DTSTART" property instead of the default
+ data type of DATE-TIME. If such a "VEVENT" has a "DTEND" property, it
+ MUST be specified as a DATE value also. The anniversary type of
+ "VEVENT" can span more than one date (i.e, "DTEND" property value is
+ set to a calendar date after the "DTSTART" property value).
+
+ The "DTSTART" property for a "VEVENT" specifies the inclusive start
+ of the event. For recurring events, it also specifies the very first
+ instance in the recurrence set. The "DTEND" property for a "VEVENT"
+ calendar component specifies the non-inclusive end of the event. For
+ cases where a "VEVENT" calendar component specifies a "DTSTART"
+ property with a DATE data type but no "DTEND" property, the events
+ non-inclusive end is the end of the calendar date specified by the
+ "DTSTART" property. For cases where a "VEVENT" calendar component
+ specifies a "DTSTART" property with a DATE-TIME data type but no
+ "DTEND" property, the event ends on the same calendar date and time
+ of day specified by the "DTSTART" property.
+
+
+
+Dawson & Stenerson Standards Track [Page 53]
+
+RFC 2445 iCalendar November 1998
+
+
+ The "VEVENT" calendar component cannot be nested within another
+ calendar component. However, "VEVENT" calendar components can be
+ related to each other or to a "VTODO" or to a "VJOURNAL" calendar
+ component with the "RELATED-TO" property.
+
+ Example: The following is an example of the "VEVENT" calendar
+ component used to represent a meeting that will also be opaque to
+ searches for busy time:
+
+ BEGIN:VEVENT
+ UID:19970901T130000Z-123401 at host.com
+ DTSTAMP:19970901T1300Z
+ DTSTART:19970903T163000Z
+ DTEND:19970903T190000Z
+ SUMMARY:Annual Employee Review
+ CLASS:PRIVATE
+ CATEGORIES:BUSINESS,HUMAN RESOURCES
+ END:VEVENT
+
+ The following is an example of the "VEVENT" calendar component used
+ to represent a reminder that will not be opaque, but rather
+ transparent, to searches for busy time:
+
+ BEGIN:VEVENT
+ UID:19970901T130000Z-123402 at host.com
+ DTSTAMP:19970901T1300Z
+ DTSTART:19970401T163000Z
+ DTEND:19970402T010000Z
+ SUMMARY:Laurel is in sensitivity awareness class.
+ CLASS:PUBLIC
+ CATEGORIES:BUSINESS,HUMAN RESOURCES
+ TRANSP:TRANSPARENT
+ END:VEVENT
+
+ The following is an example of the "VEVENT" calendar component used
+ to represent an anniversary that will occur annually. Since it takes
+ up no time, it will not appear as opaque in a search for busy time;
+ no matter what the value of the "TRANSP" property indicates:
+
+ BEGIN:VEVENT
+ UID:19970901T130000Z-123403 at host.com
+ DTSTAMP:19970901T1300Z
+ DTSTART:19971102
+ SUMMARY:Our Blissful Anniversary
+ CLASS:CONFIDENTIAL
+ CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
+ RRULE:FREQ=YEARLY
+ END:VEVENT
+
+
+
+Dawson & Stenerson Standards Track [Page 54]
+
+RFC 2445 iCalendar November 1998
+
+
+4.6.2 To-do Component
+
+ Component Name: VTODO
+
+ Purpose: Provide a grouping of calendar properties that describe a
+ to-do.
+
+ Formal Definition: A "VTODO" calendar component is defined by the
+ following notation:
+
+ todoc = "BEGIN" ":" "VTODO" CRLF
+ todoprop *alarmc
+ "END" ":" "VTODO" CRLF
+
+ todoprop = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ class / completed / created / description / dtstamp /
+ dtstart / geo / last-mod / location / organizer /
+ percent / priority / recurid / seq / status /
+ summary / uid / url /
+
+ ; either 'due' or 'duration' may appear in
+ ; a 'todoprop', but 'due' and 'duration'
+ ; MUST NOT occur in the same 'todoprop'
+
+ due / duration /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+ attach / attendee / categories / comment / contact /
+ exdate / exrule / rstatus / related / resources /
+ rdate / rrule / x-prop
+
+ )
+
+ Description: A "VTODO" calendar component is a grouping of component
+ properties and possibly "VALARM" calendar components that represent
+ an action-item or assignment. For example, it can be used to
+ represent an item of work assigned to an individual; such as "turn in
+ travel expense today".
+
+ The "VTODO" calendar component cannot be nested within another
+ calendar component. However, "VTODO" calendar components can be
+ related to each other or to a "VTODO" or to a "VJOURNAL" calendar
+ component with the "RELATED-TO" property.
+
+
+
+Dawson & Stenerson Standards Track [Page 55]
+
+RFC 2445 iCalendar November 1998
+
+
+ A "VTODO" calendar component without the "DTSTART" and "DUE" (or
+ "DURATION") properties specifies a to-do that will be associated with
+ each successive calendar date, until it is completed.
+
+ Example: The following is an example of a "VTODO" calendar component:
+
+ BEGIN:VTODO
+ UID:19970901T130000Z-123404 at host.com
+ DTSTAMP:19970901T1300Z
+ DTSTART:19970415T133000Z
+ DUE:19970416T045959Z
+ SUMMARY:1996 Income Tax Preparation
+ CLASS:CONFIDENTIAL
+ CATEGORIES:FAMILY,FINANCE
+ PRIORITY:1
+ STATUS:NEEDS-ACTION
+ END:VTODO
+
+4.6.3 Journal Component
+
+ Component Name: VJOURNAL
+
+ Purpose: Provide a grouping of component properties that describe a
+ journal entry.
+
+ Formal Definition: A "VJOURNAL" calendar component is defined by the
+ following notation:
+
+ journalc = "BEGIN" ":" "VJOURNAL" CRLF
+ jourprop
+ "END" ":" "VJOURNAL" CRLF
+
+ jourprop = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ class / created / description / dtstart / dtstamp /
+ last-mod / organizer / recurid / seq / status /
+ summary / uid / url /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+
+ attach / attendee / categories / comment /
+ contact / exdate / exrule / related / rdate /
+ rrule / rstatus / x-prop
+
+
+
+
+Dawson & Stenerson Standards Track [Page 56]
+
+RFC 2445 iCalendar November 1998
+
+
+ )
+
+ Description: A "VJOURNAL" calendar component is a grouping of
+ component properties that represent one or more descriptive text
+ notes associated with a particular calendar date. The "DTSTART"
+ property is used to specify the calendar date that the journal entry
+ is associated with. Generally, it will have a DATE value data type,
+ but it can also be used to specify a DATE-TIME value data type.
+ Examples of a journal entry include a daily record of a legislative
+ body or a journal entry of individual telephone contacts for the day
+ or an ordered list of accomplishments for the day. The "VJOURNAL"
+ calendar component can also be used to associate a document with a
+ calendar date.
+
+ The "VJOURNAL" calendar component does not take up time on a
+ calendar. Hence, it does not play a role in free or busy time
+ searches - - it is as though it has a time transparency value of
+ TRANSPARENT. It is transparent to any such searches.
+
+ The "VJOURNAL" calendar component cannot be nested within another
+ calendar component. However, "VJOURNAL" calendar components can be
+ related to each other or to a "VEVENT" or to a "VTODO" calendar
+ component, with the "RELATED-TO" property.
+
+ Example: The following is an example of the "VJOURNAL" calendar
+ component:
+
+ BEGIN:VJOURNAL
+ UID:19970901T130000Z-123405 at host.com
+ DTSTAMP:19970901T1300Z
+ DTSTART;VALUE=DATE:19970317
+ SUMMARY:Staff meeting minutes
+ DESCRIPTION:1. Staff meeting: Participants include Joe\, Lisa
+ and Bob. Aurora project plans were reviewed. There is currently
+ no budget reserves for this project. Lisa will escalate to
+ management. Next meeting on Tuesday.\n
+ 2. Telephone Conference: ABC Corp. sales representative called
+ to discuss new printer. Promised to get us a demo by Friday.\n
+ 3. Henry Miller (Handsoff Insurance): Car was totaled by tree.
+ Is looking into a loaner car. 654-2323 (tel).
+ END:VJOURNAL
+
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 57]
+
+RFC 2445 iCalendar November 1998
+
+
+4.6.4 Free/Busy Component
+
+ Component Name: VFREEBUSY
+
+ Purpose: Provide a grouping of component properties that describe
+ either a request for free/busy time, describe a response to a request
+ for free/busy time or describe a published set of busy time.
+
+ Formal Definition: A "VFREEBUSY" calendar component is defined by the
+ following notation:
+
+ freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF
+ fbprop
+ "END" ":" "VFREEBUSY" CRLF
+
+ fbprop = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ contact / dtstart / dtend / duration / dtstamp /
+ organizer / uid / url /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+
+ attendee / comment / freebusy / rstatus / x-prop
+
+ )
+
+ Description: A "VFREEBUSY" calendar component is a grouping of
+ component properties that represents either a request for, a reply to
+ a request for free or busy time information or a published set of
+ busy time information.
+
+ When used to request free/busy time information, the "ATTENDEE"
+ property specifies the calendar users whose free/busy time is being
+ requested; the "ORGANIZER" property specifies the calendar user who
+ is requesting the free/busy time; the "DTSTART" and "DTEND"
+ properties specify the window of time for which the free/busy time is
+ being requested; the "UID" and "DTSTAMP" properties are specified to
+ assist in proper sequencing of multiple free/busy time requests.
+
+ When used to reply to a request for free/busy time, the "ATTENDEE"
+ property specifies the calendar user responding to the free/busy time
+ request; the "ORGANIZER" property specifies the calendar user that
+ originally requested the free/busy time; the "FREEBUSY" property
+ specifies the free/busy time information (if it exists); and the
+
+
+
+Dawson & Stenerson Standards Track [Page 58]
+
+RFC 2445 iCalendar November 1998
+
+
+ "UID" and "DTSTAMP" properties are specified to assist in proper
+ sequencing of multiple free/busy time replies.
+
+ When used to publish busy time, the "ORGANIZER" property specifies
+ the calendar user associated with the published busy time; the
+ "DTSTART" and "DTEND" properties specify an inclusive time window
+ that surrounds the busy time information; the "FREEBUSY" property
+ specifies the published busy time information; and the "DTSTAMP"
+ property specifies the date/time that iCalendar object was created.
+
+ The "VFREEBUSY" calendar component cannot be nested within another
+ calendar component. Multiple "VFREEBUSY" calendar components can be
+ specified within an iCalendar object. This permits the grouping of
+ Free/Busy information into logical collections, such as monthly
+ groups of busy time information.
+
+ The "VFREEBUSY" calendar component is intended for use in iCalendar
+ object methods involving requests for free time, requests for busy
+ time, requests for both free and busy, and the associated replies.
+
+ Free/Busy information is represented with the "FREEBUSY" property.
+ This property provides a terse representation of time periods. One or
+ more "FREEBUSY" properties can be specified in the "VFREEBUSY"
+ calendar component.
+
+ When present in a "VFREEBUSY" calendar component, the "DTSTART" and
+ "DTEND" properties SHOULD be specified prior to any "FREEBUSY"
+ properties. In a free time request, these properties can be used in
+ combination with the "DURATION" property to represent a request for a
+ duration of free time within a specified window of time.
+
+ The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are
+ not permitted within a "VFREEBUSY" calendar component. Any recurring
+ events are resolved into their individual busy time periods using the
+ "FREEBUSY" property.
+
+ Example: The following is an example of a "VFREEBUSY" calendar
+ component used to request free or busy time information:
+
+ BEGIN:VFREEBUSY
+ ORGANIZER:MAILTO:jane_doe at host1.com
+ ATTENDEE:MAILTO:john_public at host2.com
+ DTSTART:19971015T050000Z
+ DTEND:19971016T050000Z
+ DTSTAMP:19970901T083000Z
+ END:VFREEBUSY
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 59]
+
+RFC 2445 iCalendar November 1998
+
+
+ The following is an example of a "VFREEBUSY" calendar component used
+ to reply to the request with busy time information:
+
+ BEGIN:VFREEBUSY
+ ORGANIZER:MAILTO:jane_doe at host1.com
+ ATTENDEE:MAILTO:john_public at host2.com
+ DTSTAMP:19970901T100000Z
+ FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,
+ 19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
+ URL:http://host2.com/pub/busy/jpublic-01.ifb
+ COMMENT:This iCalendar file contains busy time information for
+ the next three months.
+ END:VFREEBUSY
+
+ The following is an example of a "VFREEBUSY" calendar component used
+ to publish busy time information.
+
+ BEGIN:VFREEBUSY
+ ORGANIZER:jsmith at host.com
+ DTSTART:19980313T141711Z
+ DTEND:19980410T141711Z
+ FREEBUSY:19980314T233000Z/19980315T003000Z
+ FREEBUSY:19980316T153000Z/19980316T163000Z
+ FREEBUSY:19980318T030000Z/19980318T040000Z
+ URL:http://www.host.com/calendar/busytime/jsmith.ifb
+ END:VFREEBUSY
+
+4.6.5 Time Zone Component
+
+ Component Name: VTIMEZONE
+
+ Purpose: Provide a grouping of component properties that defines a
+ time zone.
+
+ Formal Definition: A "VTIMEZONE" calendar component is defined by the
+ following notation:
+
+ timezonec = "BEGIN" ":" "VTIMEZONE" CRLF
+
+ 2*(
+
+ ; 'tzid' is required, but MUST NOT occur more
+ ; than once
+
+ tzid /
+
+ ; 'last-mod' and 'tzurl' are optional,
+ but MUST NOT occur more than once
+
+
+
+Dawson & Stenerson Standards Track [Page 60]
+
+RFC 2445 iCalendar November 1998
+
+
+ last-mod / tzurl /
+
+ ; one of 'standardc' or 'daylightc' MUST occur
+ ..; and each MAY occur more than once.
+
+ standardc / daylightc /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ x-prop
+
+ )
+
+ "END" ":" "VTIMEZONE" CRLF
+
+ standardc = "BEGIN" ":" "STANDARD" CRLF
+
+ tzprop
+
+ "END" ":" "STANDARD" CRLF
+
+ daylightc = "BEGIN" ":" "DAYLIGHT" CRLF
+
+ tzprop
+
+ "END" ":" "DAYLIGHT" CRLF
+
+ tzprop = 3*(
+
+ ; the following are each REQUIRED,
+ ; but MUST NOT occur more than once
+
+ dtstart / tzoffsetto / tzoffsetfrom /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+
+ comment / rdate / rrule / tzname / x-prop
+
+ )
+
+ Description: A time zone is unambiguously defined by the set of time
+ measurement rules determined by the governing body for a given
+ geographic area. These rules describe at a minimum the base offset
+ from UTC for the time zone, often referred to as the Standard Time
+ offset. Many locations adjust their Standard Time forward or backward
+ by one hour, in order to accommodate seasonal changes in number of
+
+
+
+Dawson & Stenerson Standards Track [Page 61]
+
+RFC 2445 iCalendar November 1998
+
+
+ daylight hours, often referred to as Daylight Saving Time. Some
+ locations adjust their time by a fraction of an hour. Standard Time
+ is also known as Winter Time. Daylight Saving Time is also known as
+ Advanced Time, Summer Time, or Legal Time in certain countries. The
+ following table shows the changes in time zone rules in effect for
+ New York City starting from 1967. Each line represents a description
+ or rule for a particular observance.
+
+ Effective Observance Rule
+
+ Date (Date/Time) Offset Abbreviation
+
+ 1967-* last Sun in Oct, 02:00 -0500 EST
+
+ 1967-1973 last Sun in Apr, 02:00 -0400 EDT
+
+ 1974-1974 Jan 6, 02:00 -0400 EDT
+
+ 1975-1975 Feb 23, 02:00 -0400 EDT
+
+ 1976-1986 last Sun in Apr, 02:00 -0400 EDT
+
+ 1987-* first Sun in Apr, 02:00 -0400 EDT
+
+ Note: The specification of a global time zone registry is not
+ addressed by this document and is left for future study.
+ However, implementers may find the Olson time zone database [TZ]
+ a useful reference. It is an informal, public-domain collection
+ of time zone information, which is currently being maintained by
+ volunteer Internet participants, and is used in several
+ operating systems. This database contains current and historical
+ time zone information for a wide variety of locations around the
+ globe; it provides a time zone identifier for every unique time
+ zone rule set in actual use since 1970, with historical data
+ going back to the introduction of standard time.
+
+ Interoperability between two calendaring and scheduling applications,
+ especially for recurring events, to-dos or journal entries, is
+ dependent on the ability to capture and convey date and time
+ information in an unambiguous format. The specification of current
+ time zone information is integral to this behavior.
+
+ If present, the "VTIMEZONE" calendar component defines the set of
+ Standard Time and Daylight Saving Time observances (or rules) for a
+ particular time zone for a given interval of time. The "VTIMEZONE"
+ calendar component cannot be nested within other calendar components.
+ Multiple "VTIMEZONE" calendar components can exist in an iCalendar
+ object. In this situation, each "VTIMEZONE" MUST represent a unique
+
+
+
+Dawson & Stenerson Standards Track [Page 62]
+
+RFC 2445 iCalendar November 1998
+
+
+ time zone definition. This is necessary for some classes of events,
+ such as airline flights, that start in one time zone and end in
+ another.
+
+ The "VTIMEZONE" calendar component MUST be present if the iCalendar
+ object contains an RRULE that generates dates on both sides of a time
+ zone shift (e.g. both in Standard Time and Daylight Saving Time)
+ unless the iCalendar object intends to convey a floating time (See
+ the section "4.1.10.11 Time" for proper interpretation of floating
+ time). It can be present if the iCalendar object does not contain
+ such a RRULE. In addition, if a RRULE is present, there MUST be valid
+ time zone information for all recurrence instances.
+
+ The "VTIMEZONE" calendar component MUST include the "TZID" property
+ and at least one definition of a standard or daylight component. The
+ standard or daylight component MUST include the "DTSTART",
+ "TZOFFSETFROM" and "TZOFFSETTO" properties.
+
+ An individual "VTIMEZONE" calendar component MUST be specified for
+ each unique "TZID" parameter value specified in the iCalendar object.
+
+ Each "VTIMEZONE" calendar component consists of a collection of one
+ or more sub-components that describe the rule for a particular
+ observance (either a Standard Time or a Daylight Saving Time
+ observance). The "STANDARD" sub-component consists of a collection of
+ properties that describe Standard Time. The "DAYLIGHT" sub-component
+ consists of a collection of properties that describe Daylight Saving
+ Time. In general this collection of properties consists of:
+
+ - the first onset date-time for the observance
+
+ - the last onset date-time for the observance, if a last onset
+ is known.
+
+ - the offset to be applied for the observance
+
+ - a rule that describes the day and time when the observance
+ takes effect
+
+ - an optional name for the observance
+
+ For a given time zone, there may be multiple unique definitions of
+ the observances over a period of time. Each observance is described
+ using either a "STANDARD" or "DAYLIGHT" sub-component. The collection
+ of these sub-components is used to describe the time zone for a given
+ period of time. The offset to apply at any given time is found by
+ locating the observance that has the last onset date and time before
+ the time in question, and using the offset value from that
+
+
+
+Dawson & Stenerson Standards Track [Page 63]
+
+RFC 2445 iCalendar November 1998
+
+
+ observance.
+
+ The top-level properties in a "VTIMEZONE" calendar component are:
+
+ The mandatory "TZID" property is a text value that uniquely
+ identifies the VTIMZONE calendar component within the scope of an
+ iCalendar object.
+
+ The optional "LAST-MODIFIED" property is a UTC value that specifies
+ the date and time that this time zone definition was last updated.
+
+ The optional "TZURL" property is url value that points to a published
+ VTIMEZONE definition. TZURL SHOULD refer to a resource that is
+ accessible by anyone who might need to interpret the object. This
+ SHOULD NOT normally be a file: URL or other URL that is not widely-
+ accessible.
+
+ The collection of properties that are used to define the STANDARD and
+ DAYLIGHT sub-components include:
+
+ The mandatory "DTSTART" property gives the effective onset date and
+ local time for the time zone sub-component definition. "DTSTART" in
+ this usage MUST be specified as a local DATE-TIME value.
+
+ The mandatory "TZOFFSETFROM" property gives the UTC offset which is
+ in use when the onset of this time zone observance begins.
+ "TZOFFSETFROM" is combined with "DTSTART" to define the effective
+ onset for the time zone sub-component definition. For example, the
+ following represents the time at which the observance of Standard
+ Time took effect in Fall 1967 for New York City:
+
+ DTSTART:19671029T020000
+
+ TZOFFSETFROM:-0400
+
+ The mandatory "TZOFFSETTO " property gives the UTC offset for the
+ time zone sub-component (Standard Time or Daylight Saving Time) when
+ this observance is in use.
+
+ The optional "TZNAME" property is the customary name for the time
+ zone. It may be specified multiple times, to allow for specifying
+ multiple language variants of the time zone names. This could be used
+ for displaying dates.
+
+ If specified, the onset for the observance defined by the time zone
+ sub-component is defined by either the "RRULE" or "RDATE" property.
+ If neither is specified, only one sub-component can be specified in
+ the "VTIMEZONE" calendar component and it is assumed that the single
+
+
+
+Dawson & Stenerson Standards Track [Page 64]
+
+RFC 2445 iCalendar November 1998
+
+
+ observance specified is always in effect.
+
+ The "RRULE" property defines the recurrence rule for the onset of the
+ observance defined by this time zone sub-component. Some specific
+ requirements for the usage of RRULE for this purpose include:
+
+ - If observance is known to have an effective end date, the
+ "UNTIL" recurrence rule parameter MUST be used to specify the
+ last valid onset of this observance (i.e., the UNTIL date-time
+ will be equal to the last instance generated by the recurrence
+ pattern). It MUST be specified in UTC time.
+
+ - The "DTSTART" and the "TZOFFSETTO" properties MUST be used
+ when generating the onset date-time values (instances) from the
+ RRULE.
+
+ Alternatively, the "RDATE" property can be used to define the onset
+ of the observance by giving the individual onset date and times.
+ "RDATE" in this usage MUST be specified as a local DATE-TIME value in
+ UTC time.
+
+ The optional "COMMENT" property is also allowed for descriptive
+ explanatory text.
+
+ Example: The following are examples of the "VTIMEZONE" calendar
+ component:
+
+ This is an example showing time zone information for the Eastern
+ United States using "RDATE" property. Note that this is only suitable
+ for a recurring event that starts on or later than April 6, 1997 at
+ 03:00:00 EDT (i.e., the earliest effective transition date and time)
+ and ends no later than April 7, 1998 02:00:00 EST (i.e., latest valid
+ date and time for EST in this scenario). For example, this can be
+ used for a recurring event that occurs every Friday, 8am-9:00 AM,
+ starting June 1, 1997, ending December 31, 1997.
+
+ BEGIN:VTIMEZONE
+ TZID:US-Eastern
+ LAST-MODIFIED:19870101T000000Z
+ BEGIN:STANDARD
+ DTSTART:19971026T020000
+ RDATE:19971026T020000
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ TZNAME:EST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19971026T020000
+
+
+
+Dawson & Stenerson Standards Track [Page 65]
+
+RFC 2445 iCalendar November 1998
+
+
+ RDATE:19970406T020000
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+
+ This is a simple example showing the current time zone rules for the
+ Eastern United States using a RRULE recurrence pattern. Note that
+ there is no effective end date to either of the Standard Time or
+ Daylight Time rules. This information would be valid for a recurring
+ event starting today and continuing indefinitely.
+
+ BEGIN:VTIMEZONE
+ TZID:US-Eastern
+ LAST-MODIFIED:19870101T000000Z
+ TZURL:http://zones.stds_r_us.net/tz/US-Eastern
+ BEGIN:STANDARD
+ DTSTART:19671029T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ TZNAME:EST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19870405T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+
+ This is an example showing a fictitious set of rules for the Eastern
+ United States, where the Daylight Time rule has an effective end date
+ (i.e., after that date, Daylight Time is no longer observed).
+
+ BEGIN:VTIMEZONE
+ TZID:US--Fictitious-Eastern
+ LAST-MODIFIED:19870101T000000Z
+ BEGIN:STANDARD
+ DTSTART:19671029T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ TZNAME:EST
+ END:STANDARD
+
+
+
+
+Dawson & Stenerson Standards Track [Page 66]
+
+RFC 2445 iCalendar November 1998
+
+
+ BEGIN:DAYLIGHT
+ DTSTART:19870405T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+
+ This is an example showing a fictitious set of rules for the Eastern
+ United States, where the first Daylight Time rule has an effective
+ end date. There is a second Daylight Time rule that picks up where
+ the other left off.
+
+ BEGIN:VTIMEZONE
+ TZID:US--Fictitious-Eastern
+ LAST-MODIFIED:19870101T000000Z
+ BEGIN:STANDARD
+ DTSTART:19671029T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ TZNAME:EST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19870405T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ BEGIN:DAYLIGHT
+ DTSTART:19990424T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=4
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+
+4.6.6 Alarm Component
+
+ Component Name: VALARM
+
+ Purpose: Provide a grouping of component properties that define an
+ alarm.
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 67]
+
+RFC 2445 iCalendar November 1998
+
+
+ Formal Definition: A "VALARM" calendar component is defined by the
+ following notation:
+
+ alarmc = "BEGIN" ":" "VALARM" CRLF
+ (audioprop / dispprop / emailprop / procprop)
+ "END" ":" "VALARM" CRLF
+
+ audioprop = 2*(
+
+ ; 'action' and 'trigger' are both REQUIRED,
+ ; but MUST NOT occur more than once
+
+ action / trigger /
+
+ ; 'duration' and 'repeat' are both optional,
+ ; and MUST NOT occur more than once each,
+ ; but if one occurs, so MUST the other
+
+ duration / repeat /
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ attach /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ x-prop
+
+ )
+
+
+
+ dispprop = 3*(
+
+ ; the following are all REQUIRED,
+ ; but MUST NOT occur more than once
+
+ action / description / trigger /
+
+ ; 'duration' and 'repeat' are both optional,
+ ; and MUST NOT occur more than once each,
+ ; but if one occurs, so MUST the other
+
+ duration / repeat /
+
+ ; the following is optional,
+
+
+
+Dawson & Stenerson Standards Track [Page 68]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; and MAY occur more than once
+
+ *x-prop
+
+ )
+
+
+
+ emailprop = 5*(
+
+ ; the following are all REQUIRED,
+ ; but MUST NOT occur more than once
+
+ action / description / trigger / summary
+
+ ; the following is REQUIRED,
+ ; and MAY occur more than once
+
+ attendee /
+
+ ; 'duration' and 'repeat' are both optional,
+ ; and MUST NOT occur more than once each,
+ ; but if one occurs, so MUST the other
+
+ duration / repeat /
+
+ ; the following are optional,
+ ; and MAY occur more than once
+
+ attach / x-prop
+
+ )
+
+
+
+ procprop = 3*(
+
+ ; the following are all REQUIRED,
+ ; but MUST NOT occur more than once
+
+ action / attach / trigger /
+
+ ; 'duration' and 'repeat' are both optional,
+ ; and MUST NOT occur more than once each,
+ ; but if one occurs, so MUST the other
+
+ duration / repeat /
+
+
+
+
+Dawson & Stenerson Standards Track [Page 69]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; 'description' is optional,
+ ; and MUST NOT occur more than once
+
+ description /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ x-prop
+
+ )
+
+ Description: A "VALARM" calendar component is a grouping of component
+ properties that is a reminder or alarm for an event or a to-do. For
+ example, it may be used to define a reminder for a pending event or
+ an overdue to-do.
+
+ The "VALARM" calendar component MUST include the "ACTION" and
+ "TRIGGER" properties. The "ACTION" property further constrains the
+ "VALARM" calendar component in the following ways:
+
+ When the action is "AUDIO", the alarm can also include one and only
+ one "ATTACH" property, which MUST point to a sound resource, which is
+ rendered when the alarm is triggered.
+
+ When the action is "DISPLAY", the alarm MUST also include a
+ "DESCRIPTION" property, which contains the text to be displayed when
+ the alarm is triggered.
+
+ When the action is "EMAIL", the alarm MUST include a "DESCRIPTION"
+ property, which contains the text to be used as the message body, a
+ "SUMMARY" property, which contains the text to be used as the message
+ subject, and one or more "ATTENDEE" properties, which contain the
+ email address of attendees to receive the message. It can also
+ include one or more "ATTACH" properties, which are intended to be
+ sent as message attachments. When the alarm is triggered, the email
+ message is sent.
+
+ When the action is "PROCEDURE", the alarm MUST include one and only
+ one "ATTACH" property, which MUST point to a procedure resource,
+ which is invoked when the alarm is triggered.
+
+ The "VALARM" calendar component MUST only appear within either a
+ "VEVENT" or "VTODO" calendar component. "VALARM" calendar components
+ cannot be nested. Multiple mutually independent "VALARM" calendar
+ components can be specified for a single "VEVENT" or "VTODO" calendar
+ component.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 70]
+
+RFC 2445 iCalendar November 1998
+
+
+ The "TRIGGER" property specifies when the alarm will be triggered.
+ The "TRIGGER" property specifies a duration prior to the start of an
+ event or a to-do. The "TRIGGER" edge may be explicitly set to be
+ relative to the "START" or "END" of the event or to-do with the
+ "RELATED" parameter of the "TRIGGER" property. The "TRIGGER" property
+ value type can alternatively be set to an absolute calendar date and
+ time of day value.
+
+ In an alarm set to trigger on the "START" of an event or to-do, the
+ "DTSTART" property MUST be present in the associated event or to-do.
+ In an alarm in a "VEVENT" calendar component set to trigger on the
+ "END" of the event, either the "DTEND" property MUST be present, or
+ the "DTSTART" and "DURATION" properties MUST both be present. In an
+ alarm in a "VTODO" calendar component set to trigger on the "END" of
+ the to-do, either the "DUE" property MUST be present, or the
+ "DTSTART" and "DURATION" properties MUST both be present.
+
+ The alarm can be defined such that it triggers repeatedly. A
+ definition of an alarm with a repeating trigger MUST include both the
+ "DURATION" and "REPEAT" properties. The "DURATION" property specifies
+ the delay period, after which the alarm will repeat. The "REPEAT"
+ property specifies the number of additional repetitions that the
+ alarm will triggered. This repitition count is in addition to the
+ initial triggering of the alarm. Both of these properties MUST be
+ present in order to specify a repeating alarm. If one of these two
+ properties is absent, then the alarm will not repeat beyond the
+ initial trigger.
+
+ The "ACTION" property is used within the "VALARM" calendar component
+ to specify the type of action invoked when the alarm is triggered.
+ The "VALARM" properties provide enough information for a specific
+ action to be invoked. It is typically the responsibility of a
+ "Calendar User Agent" (CUA) to deliver the alarm in the specified
+ fashion. An "ACTION" property value of AUDIO specifies an alarm that
+ causes a sound to be played to alert the user; DISPLAY specifies an
+ alarm that causes a text message to be displayed to the user; EMAIL
+ specifies an alarm that causes an electronic email message to be
+ delivered to one or more email addresses; and PROCEDURE specifies an
+ alarm that causes a procedure to be executed. The "ACTION" property
+ MUST specify one and only one of these values.
+
+ In an AUDIO alarm, if the optional "ATTACH" property is included, it
+ MUST specify an audio sound resource. The intention is that the sound
+ will be played as the alarm effect. If an "ATTACH" property is
+ specified that does not refer to a sound resource, or if the
+ specified sound resource cannot be rendered (because its format is
+ unsupported, or because it cannot be retrieved), then the CUA or
+ other entity responsible for playing the sound may choose a fallback
+
+
+
+Dawson & Stenerson Standards Track [Page 71]
+
+RFC 2445 iCalendar November 1998
+
+
+ action, such as playing a built-in default sound, or playing no sound
+ at all.
+
+ In a DISPLAY alarm, the intended alarm effect is for the text value
+ of the "DESCRIPTION" property to be displayed to the user.
+
+ In an EMAIL alarm, the intended alarm effect is for an email message
+ to be composed and delivered to all the addresses specified by the
+ "ATTENDEE" properties in the "VALARM" calendar component. The
+ "DESCRIPTION" property of the "VALARM" calendar component MUST be
+ used as the body text of the message, and the "SUMMARY" property MUST
+ be used as the subject text. Any "ATTACH" properties in the "VALARM"
+ calendar component SHOULD be sent as attachments to the message.
+
+ In a PROCEDURE alarm, the "ATTACH" property in the "VALARM" calendar
+ component MUST specify a procedure or program that is intended to be
+ invoked as the alarm effect. If the procedure or program is in a
+ format that cannot be rendered, then no procedure alarm will be
+ invoked. If the "DESCRIPTION" property is present, its value
+ specifies the argument string to be passed to the procedure or
+ program. "Calendar User Agents" that receive an iCalendar object with
+ this category of alarm, can disable or allow the "Calendar User" to
+ disable, or otherwise ignore this type of alarm. While a very useful
+ alarm capability, the PROCEDURE type of alarm SHOULD be treated by
+ the "Calendar User Agent" as a potential security risk.
+
+ Example: The following example is for a "VALARM" calendar component
+ that specifies an audio alarm that will sound at a precise time and
+ repeat 4 more times at 15 minute intervals:
+
+ BEGIN:VALARM
+ TRIGGER;VALUE=DATE-TIME:19970317T133000Z
+ REPEAT:4
+ DURATION:PT15M
+ ACTION:AUDIO
+ ATTACH;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell-01.aud
+ END:VALARM
+
+ The following example is for a "VALARM" calendar component that
+ specifies a display alarm that will trigger 30 minutes before the
+ scheduled start of the event or the due date/time of the to-do it is
+ associated with and will repeat 2 more times at 15 minute intervals:
+
+ BEGIN:VALARM
+ TRIGGER:-PT30M
+ REPEAT:2
+ DURATION:PT15M
+ ACTION:DISPLAY
+
+
+
+Dawson & Stenerson Standards Track [Page 72]
+
+RFC 2445 iCalendar November 1998
+
+
+ DESCRIPTION:Breakfast meeting with executive\n
+ team at 8:30 AM EST.
+ END:VALARM
+
+ The following example is for a "VALARM" calendar component that
+ specifies an email alarm that will trigger 2 days before the
+ scheduled due date/time of a to-do it is associated with. It does not
+ repeat. The email has a subject, body and attachment link.
+
+ BEGIN:VALARM
+ TRIGGER:-P2D
+ ACTION:EMAIL
+ ATTENDEE:MAILTO:john_doe at host.com
+ SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
+ DESCRIPTION:A draft agenda needs to be sent out to the attendees
+ to the weekly managers meeting (MGR-LIST). Attached is a
+ pointer the document template for the agenda file.
+ ATTACH;FMTTYPE=application/binary:http://host.com/templates/agen
+ da.doc
+ END:VALARM
+
+ The following example is for a "VALARM" calendar component that
+ specifies a procedural alarm that will trigger at a precise date/time
+ and will repeat 23 more times at one hour intervals. The alarm will
+ invoke a procedure file.
+
+ BEGIN:VALARM
+ TRIGGER;VALUE=DATE-TIME:19980101T050000Z
+ REPEAT:23
+ DURATION:PT1H
+ ACTION:PROCEDURE
+ ATTACH;FMTTYPE=application/binary:ftp://host.com/novo-
+ procs/felizano.exe
+ END:VALARM
+
+4.7 Calendar Properties
+
+ The Calendar Properties are attributes that apply to the iCalendar
+ object, as a whole. These properties do not appear within a calendar
+ component. They SHOULD be specified after the "BEGIN:VCALENDAR"
+ property and prior to any calendar component.
+
+4.7.1 Calendar Scale
+
+ Property Name: CALSCALE
+
+ Purpose: This property defines the calendar scale used for the
+ calendar information specified in the iCalendar object.
+
+
+
+Dawson & Stenerson Standards Track [Page 73]
+
+RFC 2445 iCalendar November 1998
+
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: Property can be specified in an iCalendar object. The
+ default value is "GREGORIAN".
+
+ Description: This memo is based on the Gregorian calendar scale. The
+ Gregorian calendar scale is assumed if this property is not specified
+ in the iCalendar object. It is expected that other calendar scales
+ will be defined in other specifications or by future versions of this
+ memo.
+
+ Format Definition: The property is defined by the following notation:
+
+ calscale = "CALSCALE" calparam ":" calvalue CRLF
+
+ calparam = *(";" xparam)
+
+ calvalue = "GREGORIAN" / iana-token
+
+ Example: The following is an example of this property:
+
+ CALSCALE:GREGORIAN
+
+4.7.2 Method
+
+ Property Name: METHOD
+
+ Purpose: This property defines the iCalendar object method associated
+ with the calendar object.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified in an iCalendar object.
+
+ Description: When used in a MIME message entity, the value of this
+ property MUST be the same as the Content-Type "method" parameter
+ value. This property can only appear once within the iCalendar
+ object. If either the "METHOD" property or the Content-Type "method"
+ parameter is specified, then the other MUST also be specified.
+
+ No methods are defined by this specification. This is the subject of
+ other specifications, such as the iCalendar Transport-independent
+
+
+
+Dawson & Stenerson Standards Track [Page 74]
+
+RFC 2445 iCalendar November 1998
+
+
+ Interoperability Protocol (iTIP) defined by [ITIP].
+
+ If this property is not present in the iCalendar object, then a
+ scheduling transaction MUST NOT be assumed. In such cases, the
+ iCalendar object is merely being used to transport a snapshot of some
+ calendar information; without the intention of conveying a scheduling
+ semantic.
+
+ Format Definition: The property is defined by the following notation:
+
+ method = "METHOD" metparam ":" metvalue CRLF
+
+ metparam = *(";" xparam)
+
+ metvalue = iana-token
+
+ Example: The following is a hypothetical example of this property to
+ convey that the iCalendar object is a request for a meeting:
+
+ METHOD:REQUEST
+
+4.7.3 Product Identifier
+
+ Property Name: PRODID
+
+ Purpose: This property specifies the identifier for the product that
+ created the iCalendar object.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property MUST be specified once in an iCalendar
+ object.
+
+ Description: The vendor of the implementation SHOULD assure that this
+ is a globally unique identifier; using some technique such as an FPI
+ value, as defined in [ISO 9070].
+
+ This property SHOULD not be used to alter the interpretation of an
+ iCalendar object beyond the semantics specified in this memo. For
+ example, it is not to be used to further the understanding of non-
+ standard properties.
+
+ Format Definition: The property is defined by the following notation:
+
+ prodid = "PRODID" pidparam ":" pidvalue CRLF
+
+
+
+Dawson & Stenerson Standards Track [Page 75]
+
+RFC 2445 iCalendar November 1998
+
+
+ pidparam = *(";" xparam)
+
+ pidvalue = text
+ ;Any text that describes the product and version
+ ;and that is generally assured of being unique.
+
+ Example: The following is an example of this property. It does not
+ imply that English is the default language.
+
+ PRODID:-//ABC Corporation//NONSGML My Product//EN
+
+4.7.4 Version
+
+ Property Name: VERSION
+
+ Purpose: This property specifies the identifier corresponding to the
+ highest version number or the minimum and maximum range of the
+ iCalendar specification that is required in order to interpret the
+ iCalendar object.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property MUST be specified by an iCalendar object,
+ but MUST only be specified once.
+
+ Description: A value of "2.0" corresponds to this memo.
+
+ Format Definition: The property is defined by the following notation:
+
+ version = "VERSION" verparam ":" vervalue CRLF
+
+ verparam = *(";" xparam)
+
+ vervalue = "2.0" ;This memo
+ / maxver
+ / (minver ";" maxver)
+
+ minver = <A IANA registered iCalendar version identifier>
+ ;Minimum iCalendar version needed to parse the iCalendar object
+
+ maxver = <A IANA registered iCalendar version identifier>
+ ;Maximum iCalendar version needed to parse the iCalendar object
+
+ Example: The following is an example of this property:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 76]
+
+RFC 2445 iCalendar November 1998
+
+
+ VERSION:2.0
+
+4.8 Component Properties
+
+ The following properties can appear within calendar components, as
+ specified by each component property definition.
+
+4.8.1 Descriptive Component Properties
+
+ The following properties specify descriptive information about
+ calendar components.
+
+4.8.1.1 Attachment
+
+ Property Name: ATTACH
+
+ Purpose: The property provides the capability to associate a document
+ object with a calendar component.
+
+ Value Type: The default value type for this property is URI. The
+ value type can also be set to BINARY to indicate inline binary
+ encoded content information.
+
+ Property Parameters: Non-standard, inline encoding, format type and
+ value data type property parameters can be specified on this
+ property.
+
+ Conformance: The property can be specified in a "VEVENT", "VTODO",
+ "VJOURNAL" or "VALARM" calendar components.
+
+ Description: The property can be specified within "VEVENT", "VTODO",
+ "VJOURNAL", or "VALARM" calendar components. This property can be
+ specified multiple times within an iCalendar object.
+
+ Format Definition: The property is defined by the following notation:
+
+ attach = "ATTACH" attparam ":" uri CRLF
+
+ attach =/ "ATTACH" attparam ";" "ENCODING" "=" "BASE64"
+ ";" "VALUE" "=" "BINARY" ":" binary
+
+ attparam = *(
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ (";" fmttypeparam) /
+
+
+
+
+Dawson & Stenerson Standards Track [Page 77]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following are examples of this property:
+
+ ATTACH:CID:jsmith.part3.960817T083000.xyzMail at host1.com
+
+ ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
+ reports/r-960812.ps
+
+4.8.1.2 Categories
+
+ Property Name: CATEGORIES
+
+ Purpose: This property defines the categories for a calendar
+ component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard and language property parameters
+ can be specified on this property.
+
+ Conformance: The property can be specified within "VEVENT", "VTODO"
+ or "VJOURNAL" calendar components.
+
+ Description: This property is used to specify categories or subtypes
+ of the calendar component. The categories are useful in searching for
+ a calendar component of a particular type and category. Within the
+ "VEVENT", "VTODO" or "VJOURNAL" calendar components, more than one
+ category can be specified as a list of categories separated by the
+ COMMA character (US-ASCII decimal 44).
+
+ Format Definition: The property is defined by the following notation:
+
+ categories = "CATEGORIES" catparam ":" text *("," text)
+ CRLF
+
+ catparam = *(
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ (";" languageparam ) /
+
+
+
+
+Dawson & Stenerson Standards Track [Page 78]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following are examples of this property:
+
+ CATEGORIES:APPOINTMENT,EDUCATION
+
+ CATEGORIES:MEETING
+
+4.8.1.3 Classification
+
+ Property Name: CLASS
+
+ Purpose: This property defines the access classification for a
+ calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified once in a "VEVENT",
+ "VTODO" or "VJOURNAL" calendar components.
+
+ Description: An access classification is only one component of the
+ general security system within a calendar application. It provides a
+ method of capturing the scope of the access the calendar owner
+ intends for information within an individual calendar entry. The
+ access classification of an individual iCalendar component is useful
+ when measured along with the other security components of a calendar
+ system (e.g., calendar user authentication, authorization, access
+ rights, access role, etc.). Hence, the semantics of the individual
+ access classifications cannot be completely defined by this memo
+ alone. Additionally, due to the "blind" nature of most exchange
+ processes using this memo, these access classifications cannot serve
+ as an enforcement statement for a system receiving an iCalendar
+ object. Rather, they provide a method for capturing the intention of
+ the calendar owner for the access to the calendar component.
+
+ Format Definition: The property is defined by the following notation:
+
+ class = "CLASS" classparam ":" classvalue CRLF
+
+ classparam = *(";" xparam)
+
+
+
+Dawson & Stenerson Standards Track [Page 79]
+
+RFC 2445 iCalendar November 1998
+
+
+ classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token
+ / x-name
+ ;Default is PUBLIC
+
+ Example: The following is an example of this property:
+
+ CLASS:PUBLIC
+
+4.8.1.4 Comment
+
+ Property Name: COMMENT
+
+ Purpose: This property specifies non-processing information intended
+ to provide a comment to the calendar user.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: This property can be specified in "VEVENT", "VTODO",
+ "VJOURNAL", "VTIMEZONE" or "VFREEBUSY" calendar components.
+
+ Description: The property can be specified multiple times.
+
+ Format Definition: The property is defined by the following notation:
+
+ comment = "COMMENT" commparam ":" text CRLF
+
+ commparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following is an example of this property:
+
+ COMMENT:The meeting really needs to include both ourselves
+ and the customer. We can't hold this meeting without them.
+ As a matter of fact\, the venue for the meeting ought to be at
+
+
+
+Dawson & Stenerson Standards Track [Page 80]
+
+RFC 2445 iCalendar November 1998
+
+
+ their site. - - John
+
+ The data type for this property is TEXT.
+
+4.8.1.5 Description
+
+ Property Name: DESCRIPTION
+
+ Purpose: This property provides a more complete description of the
+ calendar component, than that provided by the "SUMMARY" property.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: The property can be specified in the "VEVENT", "VTODO",
+ "VJOURNAL" or "VALARM" calendar components. The property can be
+ specified multiple times only within a "VJOURNAL" calendar component.
+
+ Description: This property is used in the "VEVENT" and "VTODO" to
+ capture lengthy textual decriptions associated with the activity.
+
+ This property is used in the "VJOURNAL" calendar component to capture
+ one more textual journal entries.
+
+ This property is used in the "VALARM" calendar component to capture
+ the display text for a DISPLAY category of alarm, to capture the body
+ text for an EMAIL category of alarm and to capture the argument
+ string for a PROCEDURE category of alarm.
+
+ Format Definition: The property is defined by the following notation:
+
+ description = "DESCRIPTION" descparam ":" text CRLF
+
+ descparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+
+
+Dawson & Stenerson Standards Track [Page 81]
+
+RFC 2445 iCalendar November 1998
+
+
+ Example: The following is an example of the property with formatted
+ line breaks in the property value:
+
+ DESCRIPTION:Meeting to provide technical review for "Phoenix"
+ design.\n Happy Face Conference Room. Phoenix design team
+ MUST attend this meeting.\n RSVP to team leader.
+
+ The following is an example of the property with folding of long
+ lines:
+
+ DESCRIPTION:Last draft of the new novel is to be completed
+ for the editor's proof today.
+
+4.8.1.6 Geographic Position
+
+ Property Name: GEO
+
+ Purpose: This property specifies information related to the global
+ position for the activity specified by a calendar component.
+
+ Value Type: FLOAT. The value MUST be two SEMICOLON separated FLOAT
+ values.
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in "VEVENT" or "VTODO"
+ calendar components.
+
+ Description: The property value specifies latitude and longitude, in
+ that order (i.e., "LAT LON" ordering). The longitude represents the
+ location east or west of the prime meridian as a positive or negative
+ real number, respectively. The longitude and latitude values MAY be
+ specified up to six decimal places, which will allow for accuracy to
+ within one meter of geographical position. Receiving applications
+ MUST accept values of this precision and MAY truncate values of
+ greater precision.
+
+ Values for latitude and longitude shall be expressed as decimal
+ fractions of degrees. Whole degrees of latitude shall be represented
+ by a two-digit decimal number ranging from 0 through 90. Whole
+ degrees of longitude shall be represented by a decimal number ranging
+ from 0 through 180. When a decimal fraction of a degree is specified,
+ it shall be separated from the whole number of degrees by a decimal
+ point.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 82]
+
+RFC 2445 iCalendar November 1998
+
+
+ Latitudes north of the equator shall be specified by a plus sign (+),
+ or by the absence of a minus sign (-), preceding the digits
+ designating degrees. Latitudes south of the Equator shall be
+ designated by a minus sign (-) preceding the digits designating
+ degrees. A point on the Equator shall be assigned to the Northern
+ Hemisphere.
+
+ Longitudes east of the prime meridian shall be specified by a plus
+ sign (+), or by the absence of a minus sign (-), preceding the digits
+ designating degrees. Longitudes west of the meridian shall be
+ designated by minus sign (-) preceding the digits designating
+ degrees. A point on the prime meridian shall be assigned to the
+ Eastern Hemisphere. A point on the 180th meridian shall be assigned
+ to the Western Hemisphere. One exception to this last convention is
+ permitted. For the special condition of describing a band of latitude
+ around the earth, the East Bounding Coordinate data element shall be
+ assigned the value +180 (180) degrees.
+
+ Any spatial address with a latitude of +90 (90) or -90 degrees will
+ specify the position at the North or South Pole, respectively. The
+ component for longitude may have any legal value.
+
+ With the exception of the special condition described above, this
+ form is specified in Department of Commerce, 1986, Representation of
+ geographic point locations for information interchange (Federal
+ Information Processing Standard 70-1): Washington, Department of
+ Commerce, National Institute of Standards and Technology.
+
+ The simple formula for converting degrees-minutes-seconds into
+ decimal degrees is:
+
+ decimal = degrees + minutes/60 + seconds/3600.
+
+ Format Definition: The property is defined by the following notation:
+
+ geo = "GEO" geoparam ":" geovalue CRLF
+
+ geoparam = *(";" xparam)
+
+ geovalue = float ";" float
+ ;Latitude and Longitude components
+
+ Example: The following is an example of this property:
+
+ GEO:37.386013;-122.082932
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 83]
+
+RFC 2445 iCalendar November 1998
+
+
+4.8.1.7 Location
+
+ Property Name: LOCATION
+
+ Purpose: The property defines the intended venue for the activity
+ defined by a calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: This property can be specified in "VEVENT" or "VTODO"
+ calendar component.
+
+ Description: Specific venues such as conference or meeting rooms may
+ be explicitly specified using this property. An alternate
+ representation may be specified that is a URI that points to
+ directory information with more structured specification of the
+ location. For example, the alternate representation may specify
+ either an LDAP URI pointing to an LDAP server entry or a CID URI
+ pointing to a MIME body part containing a vCard [RFC 2426] for the
+ location.
+
+ Format Definition: The property is defined by the following notation:
+
+ location = "LOCATION locparam ":" text CRLF
+
+ locparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following are some examples of this property:
+
+ LOCATION:Conference Room - F123, Bldg. 002
+
+ LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
+ Conference Room - F123, Bldg. 002
+
+
+
+Dawson & Stenerson Standards Track [Page 84]
+
+RFC 2445 iCalendar November 1998
+
+
+4.8.1.8 Percent Complete
+
+ Property Name: PERCENT-COMPLETE
+
+ Purpose: This property is used by an assignee or delegatee of a to-do
+ to convey the percent completion of a to-do to the Organizer.
+
+ Value Type: INTEGER
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in a "VTODO" calendar
+ component.
+
+ Description: The property value is a positive integer between zero
+ and one hundred. A value of "0" indicates the to-do has not yet been
+ started. A value of "100" indicates that the to-do has been
+ completed. Integer values in between indicate the percent partially
+ complete.
+
+ When a to-do is assigned to multiple individuals, the property value
+ indicates the percent complete for that portion of the to-do assigned
+ to the assignee or delegatee. For example, if a to-do is assigned to
+ both individuals "A" and "B". A reply from "A" with a percent
+ complete of "70" indicates that "A" has completed 70% of the to-do
+ assigned to them. A reply from "B" with a percent complete of "50"
+ indicates "B" has completed 50% of the to-do assigned to them.
+
+ Format Definition: The property is defined by the following notation:
+
+ percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF
+
+ pctparam = *(";" xparam)
+
+ Example: The following is an example of this property to show 39%
+ completion:
+
+ PERCENT-COMPLETE:39
+
+4.8.1.9 Priority
+
+ Property Name: PRIORITY
+
+ Purpose: The property defines the relative priority for a calendar
+ component.
+
+ Value Type: INTEGER
+
+
+
+Dawson & Stenerson Standards Track [Page 85]
+
+RFC 2445 iCalendar November 1998
+
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified in a "VEVENT" or "VTODO"
+ calendar component.
+
+ Description: The priority is specified as an integer in the range
+ zero to nine. A value of zero (US-ASCII decimal 48) specifies an
+ undefined priority. A value of one (US-ASCII decimal 49) is the
+ highest priority. A value of two (US-ASCII decimal 50) is the second
+ highest priority. Subsequent numbers specify a decreasing ordinal
+ priority. A value of nine (US-ASCII decimal 58) is the lowest
+ priority.
+
+ A CUA with a three-level priority scheme of "HIGH", "MEDIUM" and
+ "LOW" is mapped into this property such that a property value in the
+ range of one (US-ASCII decimal 49) to four (US-ASCII decimal 52)
+ specifies "HIGH" priority. A value of five (US-ASCII decimal 53) is
+ the normal or "MEDIUM" priority. A value in the range of six (US-
+ ASCII decimal 54) to nine (US-ASCII decimal 58) is "LOW" priority.
+
+ A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ...,
+ "C3" is mapped into this property such that a property value of one
+ (US-ASCII decimal 49) specifies "A1", a property value of two (US-
+ ASCII decimal 50) specifies "A2", a property value of three (US-ASCII
+ decimal 51) specifies "A3", and so forth up to a property value of 9
+ (US-ASCII decimal 58) specifies "C3".
+
+ Other integer values are reserved for future use.
+
+ Within a "VEVENT" calendar component, this property specifies a
+ priority for the event. This property may be useful when more than
+ one event is scheduled for a given time period.
+
+ Within a "VTODO" calendar component, this property specified a
+ priority for the to-do. This property is useful in prioritizing
+ multiple action items for a given time period.
+
+ Format Definition: The property is specified by the following
+ notation:
+
+ priority = "PRIORITY" prioparam ":" privalue CRLF
+ ;Default is zero
+
+ prioparam = *(";" xparam)
+
+ privalue = integer ;Must be in the range [0..9]
+ ; All other values are reserved for future use
+
+
+
+Dawson & Stenerson Standards Track [Page 86]
+
+RFC 2445 iCalendar November 1998
+
+
+ The following is an example of a property with the highest priority:
+
+ PRIORITY:1
+
+ The following is an example of a property with a next highest
+ priority:
+
+ PRIORITY:2
+
+ Example: The following is an example of a property with no priority.
+ This is equivalent to not specifying the "PRIORITY" property:
+
+ PRIORITY:0
+
+4.8.1.10 Resources
+
+ Property Name: RESOURCES
+
+ Purpose: This property defines the equipment or resources anticipated
+ for an activity specified by a calendar entity..
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: This property can be specified in "VEVENT" or "VTODO"
+ calendar component.
+
+ Description: The property value is an arbitrary text. More than one
+ resource can be specified as a list of resources separated by the
+ COMMA character (US-ASCII decimal 44).
+
+ Format Definition: The property is defined by the following notation:
+
+ resources = "RESOURCES" resrcparam ":" text *("," text) CRLF
+
+ resrcparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 87]
+
+RFC 2445 iCalendar November 1998
+
+
+ (";" xparam)
+
+ )
+
+ Example: The following is an example of this property:
+
+ RESOURCES:EASEL,PROJECTOR,VCR
+
+ RESOURCES;LANGUAGE=fr:1 raton-laveur
+
+4.8.1.11 Status
+
+ Property Name: STATUS
+
+ Purpose: This property defines the overall status or confirmation for
+ the calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in "VEVENT", "VTODO" or
+ "VJOURNAL" calendar components.
+
+ Description: In a group scheduled calendar component, the property is
+ used by the "Organizer" to provide a confirmation of the event to the
+ "Attendees". For example in a "VEVENT" calendar component, the
+ "Organizer" can indicate that a meeting is tentative, confirmed or
+ cancelled. In a "VTODO" calendar component, the "Organizer" can
+ indicate that an action item needs action, is completed, is in
+ process or being worked on, or has been cancelled. In a "VJOURNAL"
+ calendar component, the "Organizer" can indicate that a journal entry
+ is draft, final or has been cancelled or removed.
+
+ Format Definition: The property is defined by the following notation:
+
+ status = "STATUS" statparam] ":" statvalue CRLF
+
+ statparam = *(";" xparam)
+
+ statvalue = "TENTATIVE" ;Indicates event is
+ ;tentative.
+ / "CONFIRMED" ;Indicates event is
+ ;definite.
+ / "CANCELLED" ;Indicates event was
+ ;cancelled.
+ ;Status values for a "VEVENT"
+
+
+
+Dawson & Stenerson Standards Track [Page 88]
+
+RFC 2445 iCalendar November 1998
+
+
+ statvalue =/ "NEEDS-ACTION" ;Indicates to-do needs action.
+ / "COMPLETED" ;Indicates to-do completed.
+ / "IN-PROCESS" ;Indicates to-do in process of
+ / "CANCELLED" ;Indicates to-do was cancelled.
+ ;Status values for "VTODO".
+
+ statvalue =/ "DRAFT" ;Indicates journal is draft.
+ / "FINAL" ;Indicates journal is final.
+ / "CANCELLED" ;Indicates journal is removed.
+ ;Status values for "VJOURNAL".
+
+ Example: The following is an example of this property for a "VEVENT"
+ calendar component:
+
+ STATUS:TENTATIVE
+
+ The following is an example of this property for a "VTODO" calendar
+ component:
+
+ STATUS:NEEDS-ACTION
+
+ The following is an example of this property for a "VJOURNAL"
+ calendar component:
+
+ STATUS:DRAFT
+
+4.8.1.12 Summary
+
+ Property Name: SUMMARY
+
+ Purpose: This property defines a short summary or subject for the
+ calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: The property can be specified in "VEVENT", "VTODO",
+ "VJOURNAL" or "VALARM" calendar components.
+
+ Description: This property is used in the "VEVENT", "VTODO" and
+ "VJOURNAL" calendar components to capture a short, one line summary
+ about the activity or journal entry.
+
+ This property is used in the "VALARM" calendar component to capture
+ the subject of an EMAIL category of alarm.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 89]
+
+RFC 2445 iCalendar November 1998
+
+
+ Format Definition: The property is defined by the following notation:
+
+ summary = "SUMMARY" summparam ":" text CRLF
+
+ summparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following is an example of this property:
+
+ SUMMARY:Department Party
+
+4.8.2 Date and Time Component Properties
+
+ The following properties specify date and time related information in
+ calendar components.
+
+4.8.2.1 Date/Time Completed
+
+ Property Name: COMPLETED
+
+ Purpose: This property defines the date and time that a to-do was
+ actually completed.
+
+ Value Type: DATE-TIME
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified in a "VTODO" calendar
+ component.
+
+ Description: The date and time MUST be in a UTC format.
+
+ Format Definition: The property is defined by the following notation:
+
+ completed = "COMPLETED" compparam ":" date-time CRLF
+
+
+
+
+Dawson & Stenerson Standards Track [Page 90]
+
+RFC 2445 iCalendar November 1998
+
+
+ compparam = *(";" xparam)
+
+ Example: The following is an example of this property:
+
+ COMPLETED:19960401T235959Z
+
+4.8.2.2 Date/Time End
+
+ Property Name: DTEND
+
+ Purpose: This property specifies the date and time that a calendar
+ component ends.
+
+ Value Type: The default value type is DATE-TIME. The value type can
+ be set to a DATE value type.
+
+ Property Parameters: Non-standard, value data type, time zone
+ identifier property parameters can be specified on this property.
+
+ Conformance: This property can be specified in "VEVENT" or
+ "VFREEBUSY" calendar components.
+
+ Description: Within the "VEVENT" calendar component, this property
+ defines the date and time by which the event ends. The value MUST be
+ later in time than the value of the "DTSTART" property.
+
+ Within the "VFREEBUSY" calendar component, this property defines the
+ end date and time for the free or busy time information. The time
+ MUST be specified in the UTC time format. The value MUST be later in
+ time than the value of the "DTSTART" property.
+
+ Format Definition: The property is defined by the following notation:
+
+ dtend = "DTEND" dtendparam":" dtendval CRLF
+
+ dtendparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
+ (";" tzidparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 91]
+
+RFC 2445 iCalendar November 1998
+
+
+ (";" xparam)
+
+ )
+
+
+
+ dtendval = date-time / date
+ ;Value MUST match value type
+
+ Example: The following is an example of this property:
+
+ DTEND:19960401T235959Z
+
+ DTEND;VALUE=DATE:19980704
+
+4.8.2.3 Date/Time Due
+
+ Property Name: DUE
+
+ Purpose: This property defines the date and time that a to-do is
+ expected to be completed.
+
+ Value Type: The default value type is DATE-TIME. The value type can
+ be set to a DATE value type.
+
+ Property Parameters: Non-standard, value data type, time zone
+ identifier property parameters can be specified on this property.
+
+ Conformance: The property can be specified once in a "VTODO" calendar
+ component.
+
+ Description: The value MUST be a date/time equal to or after the
+ DTSTART value, if specified.
+
+ Format Definition: The property is defined by the following notation:
+
+ due = "DUE" dueparam":" dueval CRLF
+
+ dueparam = *(
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
+ (";" tzidparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+
+
+
+Dawson & Stenerson Standards Track [Page 92]
+
+RFC 2445 iCalendar November 1998
+
+
+ *(";" xparam)
+
+ )
+
+
+
+ dueval = date-time / date
+ ;Value MUST match value type
+
+ Example: The following is an example of this property:
+
+ DUE:19980430T235959Z
+
+4.8.2.4 Date/Time Start
+
+ Property Name: DTSTART
+
+ Purpose: This property specifies when the calendar component begins.
+
+ Value Type: The default value type is DATE-TIME. The time value MUST
+ be one of the forms defined for the DATE-TIME value type. The value
+ type can be set to a DATE value type.
+
+ Property Parameters: Non-standard, value data type, time zone
+ identifier property parameters can be specified on this property.
+
+ Conformance: This property can be specified in the "VEVENT", "VTODO",
+ "VFREEBUSY", or "VTIMEZONE" calendar components.
+
+ Description: Within the "VEVENT" calendar component, this property
+ defines the start date and time for the event. The property is
+ REQUIRED in "VEVENT" calendar components. Events can have a start
+ date/time but no end date/time. In that case, the event does not take
+ up any time.
+
+ Within the "VFREEBUSY" calendar component, this property defines the
+ start date and time for the free or busy time information. The time
+ MUST be specified in UTC time.
+
+ Within the "VTIMEZONE" calendar component, this property defines the
+ effective start date and time for a time zone specification. This
+ property is REQUIRED within each STANDARD and DAYLIGHT part included
+ in "VTIMEZONE" calendar components and MUST be specified as a local
+ DATE-TIME without the "TZID" property parameter.
+
+ Format Definition: The property is defined by the following notation:
+
+ dtstart = "DTSTART" dtstparam ":" dtstval CRLF
+
+
+
+Dawson & Stenerson Standards Track [Page 93]
+
+RFC 2445 iCalendar November 1998
+
+
+ dtstparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
+ (";" tzidparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ *(";" xparam)
+
+ )
+
+
+
+ dtstval = date-time / date
+ ;Value MUST match value type
+
+ Example: The following is an example of this property:
+
+ DTSTART:19980118T073000Z
+
+4.8.2.5 Duration
+
+ Property Name: DURATION
+
+ Purpose: The property specifies a positive duration of time.
+
+ Value Type: DURATION
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified in "VEVENT", "VTODO",
+ "VFREEBUSY" or "VALARM" calendar components.
+
+ Description: In a "VEVENT" calendar component the property may be
+ used to specify a duration of the event, instead of an explicit end
+ date/time. In a "VTODO" calendar component the property may be used
+ to specify a duration for the to-do, instead of an explicit due
+ date/time. In a "VFREEBUSY" calendar component the property may be
+ used to specify the interval of free time being requested. In a
+ "VALARM" calendar component the property may be used to specify the
+ delay period prior to repeating an alarm.
+
+ Format Definition: The property is defined by the following notation:
+
+
+
+Dawson & Stenerson Standards Track [Page 94]
+
+RFC 2445 iCalendar November 1998
+
+
+ duration = "DURATION" durparam ":" dur-value CRLF
+ ;consisting of a positive duration of time.
+
+ durparam = *(";" xparam)
+
+ Example: The following is an example of this property that specifies
+ an interval of time of 1 hour and zero minutes and zero seconds:
+
+ DURATION:PT1H0M0S
+
+ The following is an example of this property that specifies an
+ interval of time of 15 minutes.
+
+ DURATION:PT15M
+
+4.8.2.6 Free/Busy Time
+
+ Property Name: FREEBUSY
+
+ Purpose: The property defines one or more free or busy time
+ intervals.
+
+ Value Type: PERIOD. The date and time values MUST be in an UTC time
+ format.
+
+ Property Parameters: Non-standard or free/busy time type property
+ parameters can be specified on this property.
+
+ Conformance: The property can be specified in a "VFREEBUSY" calendar
+ component.
+
+ Property Parameter: "FBTYPE" and non-standard parameters can be
+ specified on this property.
+
+ Description: These time periods can be specified as either a start
+ and end date-time or a start date-time and duration. The date and
+ time MUST be a UTC time format.
+
+ "FREEBUSY" properties within the "VFREEBUSY" calendar component
+ SHOULD be sorted in ascending order, based on start time and then end
+ time, with the earliest periods first.
+
+ The "FREEBUSY" property can specify more than one value, separated by
+ the COMMA character (US-ASCII decimal 44). In such cases, the
+ "FREEBUSY" property values SHOULD all be of the same "FBTYPE"
+ property parameter type (e.g., all values of a particular "FBTYPE"
+ listed together in a single property).
+
+
+
+
+Dawson & Stenerson Standards Track [Page 95]
+
+RFC 2445 iCalendar November 1998
+
+
+ Format Definition: The property is defined by the following notation:
+
+ freebusy = "FREEBUSY" fbparam ":" fbvalue
+ CRLF
+
+ fbparam = *(
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ (";" fbtypeparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ fbvalue = period *["," period]
+ ;Time value MUST be in the UTC time format.
+
+ Example: The following are some examples of this property:
+
+ FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M
+
+ FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H
+
+ FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H,
+ 19970308T230000Z/19970309T000000Z
+
+4.8.2.7 Time Transparency
+
+ Property Name: TRANSP
+
+ Purpose: This property defines whether an event is transparent or not
+ to busy time searches.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified once in a "VEVENT"
+ calendar component.
+
+ Description: Time Transparency is the characteristic of an event that
+ determines whether it appears to consume time on a calendar. Events
+ that consume actual time for the individual or resource associated
+
+
+
+Dawson & Stenerson Standards Track [Page 96]
+
+RFC 2445 iCalendar November 1998
+
+
+ with the calendar SHOULD be recorded as OPAQUE, allowing them to be
+ detected by free-busy time searches. Other events, which do not take
+ up the individual's (or resource's) time SHOULD be recorded as
+ TRANSPARENT, making them invisible to free-busy time searches.
+
+ Format Definition: The property is specified by the following
+ notation:
+
+ transp = "TRANSP" tranparam ":" transvalue CRLF
+
+ tranparam = *(";" xparam)
+
+ transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
+ / "TRANSPARENT" ;Transparent on busy time searches.
+ ;Default value is OPAQUE
+
+ Example: The following is an example of this property for an event
+ that is transparent or does not block on free/busy time searches:
+
+ TRANSP:TRANSPARENT
+
+ The following is an example of this property for an event that is
+ opaque or blocks on free/busy time searches:
+
+ TRANSP:OPAQUE
+
+4.8.3 Time Zone Component Properties
+
+ The following properties specify time zone information in calendar
+ components.
+
+4.8.3.1 Time Zone Identifier
+
+ Property Name: TZID
+
+ Purpose: This property specifies the text value that uniquely
+ identifies the "VTIMEZONE" calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property MUST be specified in a "VTIMEZONE"
+ calendar component.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 97]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: This is the label by which a time zone calendar
+ component is referenced by any iCalendar properties whose data type
+ is either DATE-TIME or TIME and not intended to specify a UTC or a
+ "floating" time. The presence of the SOLIDUS character (US-ASCII
+ decimal 47) as a prefix, indicates that this TZID represents an
+ unique ID in a globally defined time zone registry (when such
+ registry is defined).
+
+ Note: This document does not define a naming convention for time
+ zone identifiers. Implementers may want to use the naming
+ conventions defined in existing time zone specifications such as
+ the public-domain Olson database [TZ]. The specification of
+ globally unique time zone identifiers is not addressed by this
+ document and is left for future study.
+
+ Format Definition: This property is defined by the following
+ notation:
+
+ tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF
+
+ tzidpropparam = *(";" xparam)
+
+ ;tzidprefix = "/"
+ ; Defined previously. Just listed here for reader convenience.
+
+ Example: The following are examples of non-globally unique time zone
+ identifiers:
+
+ TZID:US-Eastern
+
+ TZID:California-Los_Angeles
+
+ The following is an example of a fictitious globally unique time zone
+ identifier:
+
+ TZID:/US-New_York-New_York
+
+4.8.3.2 Time Zone Name
+
+ Property Name: TZNAME
+
+ Purpose: This property specifies the customary designation for a time
+ zone description.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard and language property parameters
+ can be specified on this property.
+
+
+
+Dawson & Stenerson Standards Track [Page 98]
+
+RFC 2445 iCalendar November 1998
+
+
+ Conformance: This property can be specified in a "VTIMEZONE" calendar
+ component.
+
+ Description: This property may be specified in multiple languages; in
+ order to provide for different language requirements.
+
+ Format Definition: This property is defined by the following
+ notation:
+
+ tzname = "TZNAME" tznparam ":" text CRLF
+
+ tznparam = *(
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following are example of this property:
+
+ TZNAME:EST
+
+ The following is an example of this property when two different
+ languages for the time zone name are specified:
+
+ TZNAME;LANGUAGE=en:EST
+ TZNAME;LANGUAGE=fr-CA:HNE
+
+4.8.3.3 Time Zone Offset From
+
+ Property Name: TZOFFSETFROM
+
+ Purpose: This property specifies the offset which is in use prior to
+ this time zone observance.
+
+ Value Type: UTC-OFFSET
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 99]
+
+RFC 2445 iCalendar November 1998
+
+
+ Conformance: This property MUST be specified in a "VTIMEZONE"
+ calendar component.
+
+ Description: This property specifies the offset which is in use prior
+ to this time observance. It is used to calculate the absolute time at
+ which the transition to a given observance takes place. This property
+ MUST only be specified in a "VTIMEZONE" calendar component. A
+ "VTIMEZONE" calendar component MUST include this property. The
+ property value is a signed numeric indicating the number of hours and
+ possibly minutes from UTC. Positive numbers represent time zones east
+ of the prime meridian, or ahead of UTC. Negative numbers represent
+ time zones west of the prime meridian, or behind UTC.
+
+ Format Definition: The property is defined by the following notation:
+
+ tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset
+ CRLF
+
+ frmparam = *(";" xparam)
+
+ Example: The following are examples of this property:
+
+ TZOFFSETFROM:-0500
+
+ TZOFFSETFROM:+1345
+
+4.8.3.4 Time Zone Offset To
+
+ Property Name: TZOFFSETTO
+
+ Purpose: This property specifies the offset which is in use in this
+ time zone observance.
+
+ Value Type: UTC-OFFSET
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property MUST be specified in a "VTIMEZONE"
+ calendar component.
+
+ Description: This property specifies the offset which is in use in
+ this time zone observance. It is used to calculate the absolute time
+ for the new observance. The property value is a signed numeric
+ indicating the number of hours and possibly minutes from UTC.
+ Positive numbers represent time zones east of the prime meridian, or
+ ahead of UTC. Negative numbers represent time zones west of the prime
+ meridian, or behind UTC.
+
+
+
+Dawson & Stenerson Standards Track [Page 100]
+
+RFC 2445 iCalendar November 1998
+
+
+ Format Definition: The property is defined by the following notation:
+
+ tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF
+
+ toparam = *(";" xparam)
+
+ Example: The following are examples of this property:
+
+ TZOFFSETTO:-0400
+
+ TZOFFSETTO:+1245
+
+4.8.3.5 Time Zone URL
+
+ Property Name: TZURL
+
+ Purpose: The TZURL provides a means for a VTIMEZONE component to
+ point to a network location that can be used to retrieve an up-to-
+ date version of itself.
+
+ Value Type: URI
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in a "VTIMEZONE" calendar
+ component.
+
+ Description: The TZURL provides a means for a VTIMEZONE component to
+ point to a network location that can be used to retrieve an up-to-
+ date version of itself. This provides a hook to handle changes
+ government bodies impose upon time zone definitions. Retrieval of
+ this resource results in an iCalendar object containing a single
+ VTIMEZONE component and a METHOD property set to PUBLISH.
+
+ Format Definition: The property is defined by the following notation:
+
+ tzurl = "TZURL" tzurlparam ":" uri CRLF
+
+ tzurlparam = *(";" xparam)
+
+ Example: The following is an example of this property:
+
+ TZURL:http://timezones.r.us.net/tz/US-California-Los_Angeles
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 101]
+
+RFC 2445 iCalendar November 1998
+
+
+4.8.4 Relationship Component Properties
+
+ The following properties specify relationship information in calendar
+ components.
+
+4.8.4.1 Attendee
+
+ Property Name: ATTENDEE
+
+ Purpose: The property defines an "Attendee" within a calendar
+ component.
+
+ Value Type: CAL-ADDRESS
+
+ Property Parameters: Non-standard, language, calendar user type,
+ group or list membership, participation role, participation status,
+ RSVP expectation, delegatee, delegator, sent by, common name or
+ directory entry reference property parameters can be specified on
+ this property.
+
+ Conformance: This property MUST be specified in an iCalendar object
+ that specifies a group scheduled calendar entity. This property MUST
+ NOT be specified in an iCalendar object when publishing the calendar
+ information (e.g., NOT in an iCalendar object that specifies the
+ publication of a calendar user's busy time, event, to-do or journal).
+ This property is not specified in an iCalendar object that specifies
+ only a time zone definition or that defines calendar entities that
+ are not group scheduled entities, but are entities only on a single
+ user's calendar.
+
+ Description: The property MUST only be specified within calendar
+ components to specify participants, non-participants and the chair of
+ a group scheduled calendar entity. The property is specified within
+ an "EMAIL" category of the "VALARM" calendar component to specify an
+ email address that is to receive the email type of iCalendar alarm.
+
+ The property parameter CN is for the common or displayable name
+ associated with the calendar address; ROLE, for the intended role
+ that the attendee will have in the calendar component; PARTSTAT, for
+ the status of the attendee's participation; RSVP, for indicating
+ whether the favor of a reply is requested; CUTYPE, to indicate the
+ type of calendar user; MEMBER, to indicate the groups that the
+ attendee belongs to; DELEGATED-TO, to indicate the calendar users
+ that the original request was delegated to; and DELEGATED-FROM, to
+ indicate whom the request was delegated from; SENT-BY, to indicate
+ whom is acting on behalf of the ATTENDEE; and DIR, to indicate the
+ URI that points to the directory information corresponding to the
+ attendee. These property parameters can be specified on an "ATTENDEE"
+
+
+
+Dawson & Stenerson Standards Track [Page 102]
+
+RFC 2445 iCalendar November 1998
+
+
+ property in either a "VEVENT", "VTODO" or "VJOURNAL" calendar
+ component. They MUST not be specified in an "ATTENDEE" property in a
+ "VFREEBUSY" or "VALARM" calendar component. If the LANGUAGE property
+ parameter is specified, the identified language applies to the CN
+ parameter.
+
+ A recipient delegated a request MUST inherit the RSVP and ROLE values
+ from the attendee that delegated the request to them.
+
+ Multiple attendees can be specified by including multiple "ATTENDEE"
+ properties within the calendar component.
+
+ Format Definition: The property is defined by the following notation:
+
+ attendee = "ATTENDEE" attparam ":" cal-address CRLF
+
+ attparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" cutypeparam) / (";"memberparam) /
+ (";" roleparam) / (";" partstatparam) /
+ (";" rsvpparam) / (";" deltoparam) /
+ (";" delfromparam) / (";" sentbyparam) /
+ (";"cnparam) / (";" dirparam) /
+ (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following are examples of this property's use for a to-
+ do:
+
+ ORGANIZER:MAILTO:jsmith at host1.com
+ ATTENDEE;MEMBER="MAILTO:DEV-GROUP at host2.com":
+ MAILTO:joecool at host2.com
+ ATTENDEE;DELEGATED-FROM="MAILTO:immud at host3.com":
+ MAILTO:ildoit at host1.com
+
+ The following is an example of this property used for specifying
+ multiple attendees to an event:
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 103]
+
+RFC 2445 iCalendar November 1998
+
+
+ ORGANIZER:MAILTO:jsmith at host1.com
+ ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry Cabot
+ :MAILTO:hcabot at host2.com
+ ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="MAILTO:bob at host.com"
+ ;PARTSTAT=ACCEPTED;CN=Jane Doe:MAILTO:jdoe at host1.com
+
+ The following is an example of this property with a URI to the
+ directory information associated with the attendee:
+
+ ATTENDEE;CN=John Smith;DIR="ldap://host.com:6666/o=eDABC%
+ 20Industries,c=3DUS??(cn=3DBJim%20Dolittle)":MAILTO:jimdo@
+ host1.com
+
+ The following is an example of this property with "delegatee" and
+ "delegator" information for an event:
+
+ ORGANIZER;CN=John Smith:MAILTO:jsmith at host.com
+ ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM=
+ "MAILTO:iamboss at host2.com";CN=Henry Cabot:MAILTO:hcabot@
+ host2.com
+ ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO=
+ "MAILTO:hcabot at host2.com";CN=The Big Cheese:MAILTO:iamboss
+ @host2.com
+ ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe
+ :MAILTO:jdoe at host1.com
+
+ Example: The following is an example of this property's use when
+ another calendar user is acting on behalf of the "Attendee":
+
+ ATTENDEE;SENT-BY=MAILTO:jan_doe at host1.com;CN=John Smith:MAILTO:
+ jsmith at host1.com
+
+4.8.4.2 Contact
+
+ Property Name: CONTACT
+
+ Purpose: The property is used to represent contact information or
+ alternately a reference to contact information associated with the
+ calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard, alternate text representation and
+ language property parameters can be specified on this property.
+
+ Conformance: The property can be specified in a "VEVENT", "VTODO",
+ "VJOURNAL" or "VFREEBUSY" calendar component.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 104]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: The property value consists of textual contact
+ information. An alternative representation for the property value can
+ also be specified that refers to a URI pointing to an alternate form,
+ such as a vCard [RFC 2426], for the contact information.
+
+ Format Definition: The property is defined by the following notation:
+
+ contact = "CONTACT" contparam ":" text CRLF
+
+ contparam = *(
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" altrepparam) / (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following is an example of this property referencing
+ textual contact information:
+
+ CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234
+
+ The following is an example of this property with an alternate
+ representation of a LDAP URI to a directory entry containing the
+ contact information:
+
+ CONTACT;ALTREP="ldap://host.com:6666/o=3DABC%20Industries\,
+ c=3DUS??(cn=3DBJim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+ +1-919-555-1234
+
+ The following is an example of this property with an alternate
+ representation of a MIME body part containing the contact
+ information, such as a vCard [RFC 2426] embedded in a [MIME-DIR]
+ content-type:
+
+ CONTACT;ALTREP="CID=<part3.msg970930T083000SILVER at host.com>":Jim
+ Dolittle\, ABC Industries\, +1-919-555-1234
+
+ The following is an example of this property referencing a network
+ resource, such as a vCard [RFC 2426] object containing the contact
+ information:
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 105]
+
+RFC 2445 iCalendar November 1998
+
+
+ CONTACT;ALTREP="http://host.com/pdi/jdoe.vcf":Jim
+ Dolittle\, ABC Industries\, +1-919-555-1234
+
+4.8.4.3 Organizer
+
+ Property Name: ORGANIZER
+
+ Purpose: The property defines the organizer for a calendar component.
+
+ Value Type: CAL-ADDRESS
+
+ Property Parameters: Non-standard, language, common name, directory
+ entry reference, sent by property parameters can be specified on this
+ property.
+
+ Conformance: This property MUST be specified in an iCalendar object
+ that specifies a group scheduled calendar entity. This property MUST
+ be specified in an iCalendar object that specifies the publication of
+ a calendar user's busy time. This property MUST NOT be specified in
+ an iCalendar object that specifies only a time zone definition or
+ that defines calendar entities that are not group scheduled entities,
+ but are entities only on a single user's calendar.
+
+ Description: The property is specified within the "VEVENT", "VTODO",
+ "VJOURNAL calendar components to specify the organizer of a group
+ scheduled calendar entity. The property is specified within the
+ "VFREEBUSY" calendar component to specify the calendar user
+ requesting the free or busy time. When publishing a "VFREEBUSY"
+ calendar component, the property is used to specify the calendar that
+ the published busy time came from.
+
+ The property has the property parameters CN, for specifying the
+ common or display name associated with the "Organizer", DIR, for
+ specifying a pointer to the directory information associated with the
+ "Organizer", SENT-BY, for specifying another calendar user that is
+ acting on behalf of the "Organizer". The non-standard parameters may
+ also be specified on this property. If the LANGUAGE property
+ parameter is specified, the identified language applies to the CN
+ parameter value.
+
+ Format Definition: The property is defined by the following notation:
+
+ organizer = "ORGANIZER" orgparam ":"
+ cal-address CRLF
+
+ orgparam = *(
+
+ ; the following are optional,
+
+
+
+Dawson & Stenerson Standards Track [Page 106]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; but MUST NOT occur more than once
+
+ (";" cnparam) / (";" dirparam) / (";" sentbyparam) /
+ (";" languageparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ Example: The following is an example of this property:
+
+ ORGANIZER;CN=John Smith:MAILTO:jsmith at host1.com
+
+ The following is an example of this property with a pointer to the
+ directory information associated with the organizer:
+
+ ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
+ ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith at host1.com
+
+ The following is an example of this property used by another calendar
+ user who is acting on behalf of the organizer, with responses
+ intended to be sent back to the organizer, not the other calendar
+ user:
+
+ ORGANIZER;SENT-BY="MAILTO:jane_doe at host.com":
+ MAILTO:jsmith at host1.com
+
+4.8.4.4 Recurrence ID
+
+ Property Name: RECURRENCE-ID
+
+ Purpose: This property is used in conjunction with the "UID" and
+ "SEQUENCE" property to identify a specific instance of a recurring
+ "VEVENT", "VTODO" or "VJOURNAL" calendar component. The property
+ value is the effective value of the "DTSTART" property of the
+ recurrence instance.
+
+ Value Type: The default value type for this property is DATE-TIME.
+ The time format can be any of the valid forms defined for a DATE-TIME
+ value type. See DATE-TIME value type definition for specific
+ interpretations of the various forms. The value type can be set to
+ DATE.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 107]
+
+RFC 2445 iCalendar November 1998
+
+
+ Property Parameters: Non-standard property, value data type, time
+ zone identifier and recurrence identifier range parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in an iCalendar object
+ containing a recurring calendar component.
+
+ Description: The full range of calendar components specified by a
+ recurrence set is referenced by referring to just the "UID" property
+ value corresponding to the calendar component. The "RECURRENCE-ID"
+ property allows the reference to an individual instance within the
+ recurrence set.
+
+ If the value of the "DTSTART" property is a DATE type value, then the
+ value MUST be the calendar date for the recurrence instance.
+
+ The date/time value is set to the time when the original recurrence
+ instance would occur; meaning that if the intent is to change a
+ Friday meeting to Thursday, the date/time is still set to the
+ original Friday meeting.
+
+ The "RECURRENCE-ID" property is used in conjunction with the "UID"
+ and "SEQUENCE" property to identify a particular instance of a
+ recurring event, to-do or journal. For a given pair of "UID" and
+ "SEQUENCE" property values, the "RECURRENCE-ID" value for a
+ recurrence instance is fixed. When the definition of the recurrence
+ set for a calendar component changes, and hence the "SEQUENCE"
+ property value changes, the "RECURRENCE-ID" for a given recurrence
+ instance might also change.The "RANGE" parameter is used to specify
+ the effective range of recurrence instances from the instance
+ specified by the "RECURRENCE-ID" property value. The default value
+ for the range parameter is the single recurrence instance only. The
+ value can also be "THISANDPRIOR" to indicate a range defined by the
+ given recurrence instance and all prior instances or the value can be
+ "THISANDFUTURE" to indicate a range defined by the given recurrence
+ instance and all subsequent instances.
+
+ Format Definition: The property is defined by the following notation:
+
+ recurid = "RECURRENCE-ID" ridparam ":" ridval CRLF
+
+ ridparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE)) /
+ (";" tzidparam) / (";" rangeparam) /
+
+
+
+Dawson & Stenerson Standards Track [Page 108]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ ridval = date-time / date
+ ;Value MUST match value type
+
+ Example: The following are examples of this property:
+
+ RECURRENCE-ID;VALUE=DATE:19960401
+
+ RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z
+
+4.8.4.5 Related To
+
+ Property Name: RELATED-TO
+
+ Purpose: The property is used to represent a relationship or
+ reference between one calendar component and another.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard and relationship type property
+ parameters can be specified on this property.
+
+ Conformance: The property can be specified one or more times in the
+ "VEVENT", "VTODO" or "VJOURNAL" calendar components.
+
+ Description: The property value consists of the persistent, globally
+ unique identifier of another calendar component. This value would be
+ represented in a calendar component by the "UID" property.
+
+ By default, the property value points to another calendar component
+ that has a PARENT relationship to the referencing object. The
+ "RELTYPE" property parameter is used to either explicitly state the
+ default PARENT relationship type to the referenced calendar component
+ or to override the default PARENT relationship type and specify
+ either a CHILD or SIBLING relationship. The PARENT relationship
+ indicates that the calendar component is a subordinate of the
+ referenced calendar component. The CHILD relationship indicates that
+ the calendar component is a superior of the referenced calendar
+ component. The SIBLING relationship indicates that the calendar
+ component is a peer of the referenced calendar component.
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 109]
+
+RFC 2445 iCalendar November 1998
+
+
+ Changes to a calendar component referenced by this property can have
+ an implicit impact on the related calendar component. For example, if
+ a group event changes its start or end date or time, then the
+ related, dependent events will need to have their start and end dates
+ changed in a corresponding way. Similarly, if a PARENT calendar
+ component is canceled or deleted, then there is an implied impact to
+ the related CHILD calendar components. This property is intended only
+ to provide information on the relationship of calendar components. It
+ is up to the target calendar system to maintain any property
+ implications of this relationship.
+
+ Format Definition: The property is defined by the following notation:
+
+ related = "RELATED-TO" [relparam] ":" text CRLF
+
+ relparam = *(
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+ (";" reltypeparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparm)
+
+ )
+
+ The following is an example of this property:
+
+ RELATED-TO:<jsmith.part7.19960817T083000.xyzMail at host3.com>
+
+ RELATED-TO:<19960401-080045-4000F192713-0052 at host1.com>
+
+4.8.4.6 Uniform Resource Locator
+
+ Property Name: URL
+
+ Purpose: This property defines a Uniform Resource Locator (URL)
+ associated with the iCalendar object.
+
+ Value Type: URI
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 110]
+
+RFC 2445 iCalendar November 1998
+
+
+ Conformance: This property can be specified once in the "VEVENT",
+ "VTODO", "VJOURNAL" or "VFREEBUSY" calendar components.
+
+ Description: This property may be used in a calendar component to
+ convey a location where a more dynamic rendition of the calendar
+ information associated with the calendar component can be found. This
+ memo does not attempt to standardize the form of the URI, nor the
+ format of the resource pointed to by the property value. If the URL
+ property and Content-Location MIME header are both specified, they
+ MUST point to the same resource.
+
+ Format Definition: The property is defined by the following notation:
+
+ url = "URL" urlparam ":" uri CRLF
+
+ urlparam = *(";" xparam)
+
+ Example: The following is an example of this property:
+
+ URL:http://abc.com/pub/calendars/jsmith/mytime.ics
+
+4.8.4.7 Unique Identifier
+
+ Property Name: UID
+
+ Purpose: This property defines the persistent, globally unique
+ identifier for the calendar component.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property MUST be specified in the "VEVENT", "VTODO",
+ "VJOURNAL" or "VFREEBUSY" calendar components.
+
+ Description: The UID itself MUST be a globally unique identifier. The
+ generator of the identifier MUST guarantee that the identifier is
+ unique. There are several algorithms that can be used to accomplish
+ this. The identifier is RECOMMENDED to be the identical syntax to the
+ [RFC 822] addr-spec. A good method to assure uniqueness is to put the
+ domain name or a domain literal IP address of the host on which the
+ identifier was created on the right hand side of the "@", and on the
+ left hand side, put a combination of the current calendar date and
+ time of day (i.e., formatted in as a DATE-TIME value) along with some
+ other currently unique (perhaps sequential) identifier available on
+ the system (for example, a process id number). Using a date/time
+ value on the left hand side and a domain name or domain literal on
+
+
+
+Dawson & Stenerson Standards Track [Page 111]
+
+RFC 2445 iCalendar November 1998
+
+
+ the right hand side makes it possible to guarantee uniqueness since
+ no two hosts should be using the same domain name or IP address at
+ the same time. Though other algorithms will work, it is RECOMMENDED
+ that the right hand side contain some domain identifier (either of
+ the host itself or otherwise) such that the generator of the message
+ identifier can guarantee the uniqueness of the left hand side within
+ the scope of that domain.
+
+ This is the method for correlating scheduling messages with the
+ referenced "VEVENT", "VTODO", or "VJOURNAL" calendar component.
+
+ The full range of calendar components specified by a recurrence set
+ is referenced by referring to just the "UID" property value
+ corresponding to the calendar component. The "RECURRENCE-ID" property
+ allows the reference to an individual instance within the recurrence
+ set.
+
+ This property is an important method for group scheduling
+ applications to match requests with later replies, modifications or
+ deletion requests. Calendaring and scheduling applications MUST
+ generate this property in "VEVENT", "VTODO" and "VJOURNAL" calendar
+ components to assure interoperability with other group scheduling
+ applications. This identifier is created by the calendar system that
+ generates an iCalendar object.
+
+ Implementations MUST be able to receive and persist values of at
+ least 255 characters for this property.
+
+ Format Definition: The property is defined by the following notation:
+
+ uid = "UID" uidparam ":" text CRLF
+
+ uidparam = *(";" xparam)
+
+ Example: The following is an example of this property:
+
+ UID:19960401T080045Z-4000F192713-0052 at host1.com
+
+4.8.5 Recurrence Component Properties
+
+ The following properties specify recurrence information in calendar
+ components.
+
+4.8.5.1 Exception Date/Times
+
+ Property Name: EXDATE
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 112]
+
+RFC 2445 iCalendar November 1998
+
+
+ Purpose: This property defines the list of date/time exceptions for a
+ recurring calendar component.
+
+ Value Type: The default value type for this property is DATE-TIME.
+ The value type can be set to DATE.
+
+ Property Parameters: Non-standard, value data type and time zone
+ identifier property parameters can be specified on this property.
+
+ Conformance: This property can be specified in an iCalendar object
+ that includes a recurring calendar component.
+
+ Description: The exception dates, if specified, are used in computing
+ the recurrence set. The recurrence set is the complete set of
+ recurrence instances for a calendar component. The recurrence set is
+ generated by considering the initial "DTSTART" property along with
+ the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
+ within the iCalendar object. The "DTSTART" property defines the first
+ instance in the recurrence set. Multiple instances of the "RRULE" and
+ "EXRULE" properties can also be specified to define more
+ sophisticated recurrence sets. The final recurrence set is generated
+ by gathering all of the start date-times generated by any of the
+ specified "RRULE" and "RDATE" properties, and then excluding any
+ start date and times which fall within the union of start date and
+ times generated by any specified "EXRULE" and "EXDATE" properties.
+ This implies that start date and times within exclusion related
+ properties (i.e., "EXDATE" and "EXRULE") take precedence over those
+ specified by inclusion properties (i.e., "RDATE" and "RRULE"). Where
+ duplicate instances are generated by the "RRULE" and "RDATE"
+ properties, only one recurrence is considered. Duplicate instances
+ are ignored.
+
+ The "EXDATE" property can be used to exclude the value specified in
+ "DTSTART". However, in such cases the original "DTSTART" date MUST
+ still be maintained by the calendaring and scheduling system because
+ the original "DTSTART" value has inherent usage dependencies by other
+ properties such as the "RECURRENCE-ID".
+
+ Format Definition: The property is defined by the following notation:
+
+ exdate = "EXDATE" exdtparam ":" exdtval *("," exdtval) CRLF
+
+ exdtparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
+
+
+
+Dawson & Stenerson Standards Track [Page 113]
+
+RFC 2445 iCalendar November 1998
+
+
+ (";" tzidparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ exdtval = date-time / date
+ ;Value MUST match value type
+
+ Example: The following is an example of this property:
+
+ EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z
+
+4.8.5.2 Exception Rule
+
+ Property Name: EXRULE
+
+ Purpose: This property defines a rule or repeating pattern for an
+ exception to a recurrence set.
+
+ Value Type: RECUR
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in "VEVENT", "VTODO" or
+ "VJOURNAL" calendar components.
+
+ Description: The exception rule, if specified, is used in computing
+ the recurrence set. The recurrence set is the complete set of
+ recurrence instances for a calendar component. The recurrence set is
+ generated by considering the initial "DTSTART" property along with
+ the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
+ within the iCalendar object. The "DTSTART" defines the first instance
+ in the recurrence set. Multiple instances of the "RRULE" and "EXRULE"
+ properties can also be specified to define more sophisticated
+ recurrence sets. The final recurrence set is generated by gathering
+ all of the start date-times generated by any of the specified "RRULE"
+ and "RDATE" properties, and excluding any start date and times which
+ fall within the union of start date and times generated by any
+ specified "EXRULE" and "EXDATE" properties. This implies that start
+ date and times within exclusion related properties (i.e., "EXDATE"
+ and "EXRULE") take precedence over those specified by inclusion
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 114]
+
+RFC 2445 iCalendar November 1998
+
+
+ properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are
+ generated by the "RRULE" and "RDATE" properties, only one recurrence
+ is considered. Duplicate instances are ignored.
+
+ The "EXRULE" property can be used to exclude the value specified in
+ "DTSTART". However, in such cases the original "DTSTART" date MUST
+ still be maintained by the calendaring and scheduling system because
+ the original "DTSTART" value has inherent usage dependencies by other
+ properties such as the "RECURRENCE-ID".
+
+ Format Definition: The property is defined by the following notation:
+
+ exrule = "EXRULE" exrparam ":" recur CRLF
+
+ exrparam = *(";" xparam)
+
+ Example: The following are examples of this property. Except every
+ other week, on Tuesday and Thursday for 4 occurrences:
+
+ EXRULE:FREQ=WEEKLY;COUNT=4;INTERVAL=2;BYDAY=TU,TH
+
+ Except daily for 10 occurrences:
+
+ EXRULE:FREQ=DAILY;COUNT=10
+
+ Except yearly in June and July for 8 occurrences:
+
+ EXRULE:FREQ=YEARLY;COUNT=8;BYMONTH=6,7
+
+4.8.5.3 Recurrence Date/Times
+
+ Property Name: RDATE
+
+ Purpose: This property defines the list of date/times for a
+ recurrence set.
+
+ Value Type: The default value type for this property is DATE-TIME.
+ The value type can be set to DATE or PERIOD.
+
+ Property Parameters: Non-standard, value data type and time zone
+ identifier property parameters can be specified on this property.
+
+ Conformance: The property can be specified in "VEVENT", "VTODO",
+ "VJOURNAL" or "VTIMEZONE" calendar components.
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 115]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: This property can appear along with the "RRULE" property
+ to define an aggregate set of repeating occurrences. When they both
+ appear in an iCalendar object, the recurring events are defined by
+ the union of occurrences defined by both the "RDATE" and "RRULE".
+
+ The recurrence dates, if specified, are used in computing the
+ recurrence set. The recurrence set is the complete set of recurrence
+ instances for a calendar component. The recurrence set is generated
+ by considering the initial "DTSTART" property along with the "RRULE",
+ "RDATE", "EXDATE" and "EXRULE" properties contained within the
+ iCalendar object. The "DTSTART" property defines the first instance
+ in the recurrence set. Multiple instances of the "RRULE" and "EXRULE"
+ properties can also be specified to define more sophisticated
+ recurrence sets. The final recurrence set is generated by gathering
+ all of the start date/times generated by any of the specified "RRULE"
+ and "RDATE" properties, and excluding any start date/times which fall
+ within the union of start date/times generated by any specified
+ "EXRULE" and "EXDATE" properties. This implies that start date/times
+ within exclusion related properties (i.e., "EXDATE" and "EXRULE")
+ take precedence over those specified by inclusion properties (i.e.,
+ "RDATE" and "RRULE"). Where duplicate instances are generated by the
+ "RRULE" and "RDATE" properties, only one recurrence is considered.
+ Duplicate instances are ignored.
+
+ Format Definition: The property is defined by the following notation:
+
+ rdate = "RDATE" rdtparam ":" rdtval *("," rdtval) CRLF
+
+ rdtparam = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) /
+ (";" tzidparam) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ rdtval = date-time / date / period
+ ;Value MUST match value type
+
+ Example: The following are examples of this property:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 116]
+
+RFC 2445 iCalendar November 1998
+
+
+ RDATE:19970714T123000Z
+
+ RDATE;TZID=US-EASTERN:19970714T083000
+
+ RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
+ 19960404T010000Z/PT3H
+
+ RDATE;VALUE=DATE:19970101,19970120,19970217,19970421
+ 19970526,19970704,19970901,19971014,19971128,19971129,19971225
+
+4.8.5.4 Recurrence Rule
+
+ Property Name: RRULE
+
+ Purpose: This property defines a rule or repeating pattern for
+ recurring events, to-dos, or time zone definitions.
+
+ Value Type: RECUR
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified one or more times in
+ recurring "VEVENT", "VTODO" and "VJOURNAL" calendar components. It
+ can also be specified once in each STANDARD or DAYLIGHT sub-component
+ of the "VTIMEZONE" calendar component.
+
+ Description: The recurrence rule, if specified, is used in computing
+ the recurrence set. The recurrence set is the complete set of
+ recurrence instances for a calendar component. The recurrence set is
+ generated by considering the initial "DTSTART" property along with
+ the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
+ within the iCalendar object. The "DTSTART" property defines the first
+ instance in the recurrence set. Multiple instances of the "RRULE" and
+ "EXRULE" properties can also be specified to define more
+ sophisticated recurrence sets. The final recurrence set is generated
+ by gathering all of the start date/times generated by any of the
+ specified "RRULE" and "RDATE" properties, and excluding any start
+ date/times which fall within the union of start date/times generated
+ by any specified "EXRULE" and "EXDATE" properties. This implies that
+ start date/times within exclusion related properties (i.e., "EXDATE"
+ and "EXRULE") take precedence over those specified by inclusion
+ properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are
+ generated by the "RRULE" and "RDATE" properties, only one recurrence
+ is considered. Duplicate instances are ignored.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 117]
+
+RFC 2445 iCalendar November 1998
+
+
+ The "DTSTART" and "DTEND" property pair or "DTSTART" and "DURATION"
+ property pair, specified within the iCalendar object defines the
+ first instance of the recurrence. When used with a recurrence rule,
+ the "DTSTART" and "DTEND" properties MUST be specified in local time
+ and the appropriate set of "VTIMEZONE" calendar components MUST be
+ included. For detail on the usage of the "VTIMEZONE" calendar
+ component, see the "VTIMEZONE" calendar component definition.
+
+ Any duration associated with the iCalendar object applies to all
+ members of the generated recurrence set. Any modified duration for
+ specific recurrences MUST be explicitly specified using the "RDATE"
+ property.
+
+ Format Definition: This property is defined by the following
+ notation:
+
+ rrule = "RRULE" rrulparam ":" recur CRLF
+
+ rrulparam = *(";" xparam)
+
+ Example: All examples assume the Eastern United States time zone.
+
+ Daily for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=DAILY;COUNT=10
+
+ ==> (1997 9:00 AM EDT)September 2-11
+
+ Daily until December 24, 1997:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
+
+ ==> (1997 9:00 AM EDT)September 2-30;October 1-25
+ (1997 9:00 AM EST)October 26-31;November 1-30;December 1-23
+
+ Every other day - forever:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=DAILY;INTERVAL=2
+ ==> (1997 9:00 AM EDT)September2,4,6,8...24,26,28,30;
+ October 2,4,6...20,22,24
+ (1997 9:00 AM EST)October 26,28,30;November 1,3,5,7...25,27,29;
+ Dec 1,3,...
+
+ Every 10 days, 5 occurrences:
+
+
+
+
+Dawson & Stenerson Standards Track [Page 118]
+
+RFC 2445 iCalendar November 1998
+
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
+
+ ==> (1997 9:00 AM EDT)September 2,12,22;October 2,12
+
+ Everyday in January, for 3 years:
+
+ DTSTART;TZID=US-Eastern:19980101T090000
+ RRULE:FREQ=YEARLY;UNTIL=20000131T090000Z;
+ BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
+ or
+ RRULE:FREQ=DAILY;UNTIL=20000131T090000Z;BYMONTH=1
+
+ ==> (1998 9:00 AM EDT)January 1-31
+ (1999 9:00 AM EDT)January 1-31
+ (2000 9:00 AM EDT)January 1-31
+
+ Weekly for 10 occurrences
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;COUNT=10
+
+ ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
+ (1997 9:00 AM EST)October 28;November 4
+
+ Weekly until December 24, 1997
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;UNTIL=19971224T000000Z
+
+ ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
+ (1997 9:00 AM EST)October 28;November 4,11,18,25;
+ December 2,9,16,23
+ Every other week - forever:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;INTERVAL=2;WKST=SU
+
+ ==> (1997 9:00 AM EDT)September 2,16,30;October 14
+ (1997 9:00 AM EST)October 28;November 11,25;December 9,23
+ (1998 9:00 AM EST)January 6,20;February
+ ...
+
+ Weekly on Tuesday and Thursday for 5 weeks:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;UNTIL=19971007T000000Z;WKST=SU;BYDAY=TU,TH
+ or
+
+
+
+Dawson & Stenerson Standards Track [Page 119]
+
+RFC 2445 iCalendar November 1998
+
+
+ RRULE:FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH
+
+ ==> (1997 9:00 AM EDT)September 2,4,9,11,16,18,23,25,30;October 2
+
+ Every other week on Monday, Wednesday and Friday until December 24,
+ 1997, but starting on Tuesday, September 2, 1997:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;
+ BYDAY=MO,WE,FR
+ ==> (1997 9:00 AM EDT)September 2,3,5,15,17,19,29;October
+ 1,3,13,15,17
+ (1997 9:00 AM EST)October 27,29,31;November 10,12,14,24,26,28;
+ December 8,10,12,22
+
+ Every other week on Tuesday and Thursday, for 8 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH
+
+ ==> (1997 9:00 AM EDT)September 2,4,16,18,30;October 2,14,16
+
+ Monthly on the 1st Friday for ten occurrences:
+
+ DTSTART;TZID=US-Eastern:19970905T090000
+ RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
+
+ ==> (1997 9:00 AM EDT)September 5;October 3
+ (1997 9:00 AM EST)November 7;Dec 5
+ (1998 9:00 AM EST)January 2;February 6;March 6;April 3
+ (1998 9:00 AM EDT)May 1;June 5
+
+ Monthly on the 1st Friday until December 24, 1997:
+
+ DTSTART;TZID=US-Eastern:19970905T090000
+ RRULE:FREQ=MONTHLY;UNTIL=19971224T000000Z;BYDAY=1FR
+
+ ==> (1997 9:00 AM EDT)September 5;October 3
+ (1997 9:00 AM EST)November 7;December 5
+
+ Every other month on the 1st and last Sunday of the month for 10
+ occurrences:
+
+ DTSTART;TZID=US-Eastern:19970907T090000
+ RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU
+
+ ==> (1997 9:00 AM EDT)September 7,28
+ (1997 9:00 AM EST)November 2,30
+
+
+
+Dawson & Stenerson Standards Track [Page 120]
+
+RFC 2445 iCalendar November 1998
+
+
+ (1998 9:00 AM EST)January 4,25;March 1,29
+ (1998 9:00 AM EDT)May 3,31
+
+ Monthly on the second to last Monday of the month for 6 months:
+
+ DTSTART;TZID=US-Eastern:19970922T090000
+ RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO
+
+ ==> (1997 9:00 AM EDT)September 22;October 20
+ (1997 9:00 AM EST)November 17;December 22
+ (1998 9:00 AM EST)January 19;February 16
+
+ Monthly on the third to the last day of the month, forever:
+
+ DTSTART;TZID=US-Eastern:19970928T090000
+ RRULE:FREQ=MONTHLY;BYMONTHDAY=-3
+
+ ==> (1997 9:00 AM EDT)September 28
+ (1997 9:00 AM EST)October 29;November 28;December 29
+ (1998 9:00 AM EST)January 29;February 26
+ ...
+
+ Monthly on the 2nd and 15th of the month for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=2,15
+
+ ==> (1997 9:00 AM EDT)September 2,15;October 2,15
+ (1997 9:00 AM EST)November 2,15;December 2,15
+ (1998 9:00 AM EST)January 2,15
+
+ Monthly on the first and last day of the month for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970930T090000
+ RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=1,-1
+
+ ==> (1997 9:00 AM EDT)September 30;October 1
+ (1997 9:00 AM EST)October 31;November 1,30;December 1,31
+ (1998 9:00 AM EST)January 1,31;February 1
+
+ Every 18 months on the 10th thru 15th of the month for 10
+ occurrences:
+
+ DTSTART;TZID=US-Eastern:19970910T090000
+ RRULE:FREQ=MONTHLY;INTERVAL=18;COUNT=10;BYMONTHDAY=10,11,12,13,14,
+ 15
+
+ ==> (1997 9:00 AM EDT)September 10,11,12,13,14,15
+
+
+
+Dawson & Stenerson Standards Track [Page 121]
+
+RFC 2445 iCalendar November 1998
+
+
+ (1999 9:00 AM EST)March 10,11,12,13
+
+ Every Tuesday, every other month:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=TU
+
+ ==> (1997 9:00 AM EDT)September 2,9,16,23,30
+ (1997 9:00 AM EST)November 4,11,18,25
+ (1998 9:00 AM EST)January 6,13,20,27;March 3,10,17,24,31
+ ...
+
+ Yearly in June and July for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970610T090000
+ RRULE:FREQ=YEARLY;COUNT=10;BYMONTH=6,7
+ ==> (1997 9:00 AM EDT)June 10;July 10
+ (1998 9:00 AM EDT)June 10;July 10
+ (1999 9:00 AM EDT)June 10;July 10
+ (2000 9:00 AM EDT)June 10;July 10
+ (2001 9:00 AM EDT)June 10;July 10
+ Note: Since none of the BYDAY, BYMONTHDAY or BYYEARDAY components
+ are specified, the day is gotten from DTSTART
+
+ Every other year on January, February, and March for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970310T090000
+ RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=10;BYMONTH=1,2,3
+
+ ==> (1997 9:00 AM EST)March 10
+ (1999 9:00 AM EST)January 10;February 10;March 10
+ (2001 9:00 AM EST)January 10;February 10;March 10
+ (2003 9:00 AM EST)January 10;February 10;March 10
+
+ Every 3rd year on the 1st, 100th and 200th day for 10 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970101T090000
+ RRULE:FREQ=YEARLY;INTERVAL=3;COUNT=10;BYYEARDAY=1,100,200
+
+ ==> (1997 9:00 AM EST)January 1
+ (1997 9:00 AM EDT)April 10;July 19
+ (2000 9:00 AM EST)January 1
+ (2000 9:00 AM EDT)April 9;July 18
+ (2003 9:00 AM EST)January 1
+ (2003 9:00 AM EDT)April 10;July 19
+ (2006 9:00 AM EST)January 1
+
+ Every 20th Monday of the year, forever:
+
+
+
+Dawson & Stenerson Standards Track [Page 122]
+
+RFC 2445 iCalendar November 1998
+
+
+ DTSTART;TZID=US-Eastern:19970519T090000
+ RRULE:FREQ=YEARLY;BYDAY=20MO
+
+ ==> (1997 9:00 AM EDT)May 19
+ (1998 9:00 AM EDT)May 18
+ (1999 9:00 AM EDT)May 17
+ ...
+
+ Monday of week number 20 (where the default start of the week is
+ Monday), forever:
+
+ DTSTART;TZID=US-Eastern:19970512T090000
+ RRULE:FREQ=YEARLY;BYWEEKNO=20;BYDAY=MO
+
+ ==> (1997 9:00 AM EDT)May 12
+ (1998 9:00 AM EDT)May 11
+ (1999 9:00 AM EDT)May 17
+ ...
+
+ Every Thursday in March, forever:
+
+ DTSTART;TZID=US-Eastern:19970313T090000
+ RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=TH
+
+ ==> (1997 9:00 AM EST)March 13,20,27
+ (1998 9:00 AM EST)March 5,12,19,26
+ (1999 9:00 AM EST)March 4,11,18,25
+ ...
+
+ Every Thursday, but only during June, July, and August, forever:
+
+ DTSTART;TZID=US-Eastern:19970605T090000
+ RRULE:FREQ=YEARLY;BYDAY=TH;BYMONTH=6,7,8
+
+ ==> (1997 9:00 AM EDT)June 5,12,19,26;July 3,10,17,24,31;
+ August 7,14,21,28
+ (1998 9:00 AM EDT)June 4,11,18,25;July 2,9,16,23,30;
+ August 6,13,20,27
+ (1999 9:00 AM EDT)June 3,10,17,24;July 1,8,15,22,29;
+ August 5,12,19,26
+ ...
+
+ Every Friday the 13th, forever:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ EXDATE;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=MONTHLY;BYDAY=FR;BYMONTHDAY=13
+
+
+
+
+Dawson & Stenerson Standards Track [Page 123]
+
+RFC 2445 iCalendar November 1998
+
+
+ ==> (1998 9:00 AM EST)February 13;March 13;November 13
+ (1999 9:00 AM EDT)August 13
+ (2000 9:00 AM EDT)October 13
+ ...
+
+ The first Saturday that follows the first Sunday of the month,
+ forever:
+
+ DTSTART;TZID=US-Eastern:19970913T090000
+ RRULE:FREQ=MONTHLY;BYDAY=SA;BYMONTHDAY=7,8,9,10,11,12,13
+
+ ==> (1997 9:00 AM EDT)September 13;October 11
+ (1997 9:00 AM EST)November 8;December 13
+ (1998 9:00 AM EST)January 10;February 7;March 7
+ (1998 9:00 AM EDT)April 11;May 9;June 13...
+ ...
+
+ Every four years, the first Tuesday after a Monday in November,
+ forever (U.S. Presidential Election day):
+
+ DTSTART;TZID=US-Eastern:19961105T090000
+ RRULE:FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4,
+ 5,6,7,8
+
+ ==> (1996 9:00 AM EST)November 5
+ (2000 9:00 AM EST)November 7
+ (2004 9:00 AM EST)November 2
+ ...
+
+ The 3rd instance into the month of one of Tuesday, Wednesday or
+ Thursday, for the next 3 months:
+
+ DTSTART;TZID=US-Eastern:19970904T090000
+ RRULE:FREQ=MONTHLY;COUNT=3;BYDAY=TU,WE,TH;BYSETPOS=3
+
+ ==> (1997 9:00 AM EDT)September 4;October 7
+ (1997 9:00 AM EST)November 6
+
+ The 2nd to last weekday of the month:
+
+ DTSTART;TZID=US-Eastern:19970929T090000
+ RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2
+
+ ==> (1997 9:00 AM EDT)September 29
+ (1997 9:00 AM EST)October 30;November 27;December 30
+ (1998 9:00 AM EST)January 29;February 26;March 30
+ ...
+
+
+
+
+Dawson & Stenerson Standards Track [Page 124]
+
+RFC 2445 iCalendar November 1998
+
+
+ Every 3 hours from 9:00 AM to 5:00 PM on a specific day:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=HOURLY;INTERVAL=3;UNTIL=19970902T170000Z
+
+ ==> (September 2, 1997 EDT)09:00,12:00,15:00
+
+ Every 15 minutes for 6 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=MINUTELY;INTERVAL=15;COUNT=6
+
+ ==> (September 2, 1997 EDT)09:00,09:15,09:30,09:45,10:00,10:15
+
+ Every hour and a half for 4 occurrences:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=MINUTELY;INTERVAL=90;COUNT=4
+
+ ==> (September 2, 1997 EDT)09:00,10:30;12:00;13:30
+
+ Every 20 minutes from 9:00 AM to 4:40 PM every day:
+
+ DTSTART;TZID=US-Eastern:19970902T090000
+ RRULE:FREQ=DAILY;BYHOUR=9,10,11,12,13,14,15,16;BYMINUTE=0,20,40
+ or
+ RRULE:FREQ=MINUTELY;INTERVAL=20;BYHOUR=9,10,11,12,13,14,15,16
+
+ ==> (September 2, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
+ ... 16:00,16:20,16:40
+ (September 3, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
+ ...16:00,16:20,16:40
+ ...
+
+ An example where the days generated makes a difference because of
+ WKST:
+
+ DTSTART;TZID=US-Eastern:19970805T090000
+ RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO
+
+ ==> (1997 EDT)Aug 5,10,19,24
+
+ changing only WKST from MO to SU, yields different results...
+
+ DTSTART;TZID=US-Eastern:19970805T090000
+ RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU
+ ==> (1997 EDT)August 5,17,19,31
+
+
+
+
+Dawson & Stenerson Standards Track [Page 125]
+
+RFC 2445 iCalendar November 1998
+
+
+4.8.6 Alarm Component Properties
+
+ The following properties specify alarm information in calendar
+ components.
+
+4.8.6.1 Action
+
+ Property Name: ACTION
+
+ Purpose: This property defines the action to be invoked when an alarm
+ is triggered.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property MUST be specified once in a "VALARM"
+ calendar component.
+
+ Description: Each "VALARM" calendar component has a particular type
+ of action associated with it. This property specifies the type of
+ action
+
+ Format Definition: The property is defined by the following notation:
+
+ action = "ACTION" actionparam ":" actionvalue CRLF
+
+ actionparam = *(";" xparam)
+
+ actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / "PROCEDURE"
+ / iana-token / x-name
+
+ Example: The following are examples of this property in a "VALARM"
+ calendar component:
+
+ ACTION:AUDIO
+
+ ACTION:DISPLAY
+
+ ACTION:PROCEDURE
+
+4.8.6.2 Repeat Count
+
+ Property Name: REPEAT
+
+ Purpose: This property defines the number of time the alarm should be
+ repeated, after the initial trigger.
+
+
+
+Dawson & Stenerson Standards Track [Page 126]
+
+RFC 2445 iCalendar November 1998
+
+
+ Value Type: INTEGER
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in a "VALARM" calendar
+ component.
+
+ Description: If the alarm triggers more than once, then this property
+ MUST be specified along with the "DURATION" property.
+
+ Format Definition: The property is defined by the following notation:
+
+ repeatcnt = "REPEAT" repparam ":" integer CRLF
+ ;Default is "0", zero.
+
+ repparam = *(";" xparam)
+
+ Example: The following is an example of this property for an alarm
+ that repeats 4 additional times with a 5 minute delay after the
+ initial triggering of the alarm:
+
+ REPEAT:4
+ DURATION:PT5M
+
+4.8.6.3 Trigger
+
+ Property Name: TRIGGER
+
+ Purpose: This property specifies when an alarm will trigger.
+
+ Value Type: The default value type is DURATION. The value type can be
+ set to a DATE-TIME value type, in which case the value MUST specify a
+ UTC formatted DATE-TIME value.
+
+ Property Parameters: Non-standard, value data type, time zone
+ identifier or trigger relationship property parameters can be
+ specified on this property. The trigger relationship property
+ parameter MUST only be specified when the value type is DURATION.
+
+ Conformance: This property MUST be specified in the "VALARM" calendar
+ component.
+
+ Description: Within the "VALARM" calendar component, this property
+ defines when the alarm will trigger. The default value type is
+ DURATION, specifying a relative time for the trigger of the alarm.
+ The default duration is relative to the start of an event or to-do
+ that the alarm is associated with. The duration can be explicitly set
+
+
+
+Dawson & Stenerson Standards Track [Page 127]
+
+RFC 2445 iCalendar November 1998
+
+
+ to trigger from either the end or the start of the associated event
+ or to-do with the "RELATED" parameter. A value of START will set the
+ alarm to trigger off the start of the associated event or to-do. A
+ value of END will set the alarm to trigger off the end of the
+ associated event or to-do.
+
+ Either a positive or negative duration may be specified for the
+ "TRIGGER" property. An alarm with a positive duration is triggered
+ after the associated start or end of the event or to-do. An alarm
+ with a negative duration is triggered before the associated start or
+ end of the event or to-do.
+
+ The "RELATED" property parameter is not valid if the value type of
+ the property is set to DATE-TIME (i.e., for an absolute date and time
+ alarm trigger). If a value type of DATE-TIME is specified, then the
+ property value MUST be specified in the UTC time format. If an
+ absolute trigger is specified on an alarm for a recurring event or
+ to-do, then the alarm will only trigger for the specified absolute
+ date/time, along with any specified repeating instances.
+
+ If the trigger is set relative to START, then the "DTSTART" property
+ MUST be present in the associated "VEVENT" or "VTODO" calendar
+ component. If an alarm is specified for an event with the trigger set
+ relative to the END, then the "DTEND" property or the "DSTART" and
+ "DURATION' properties MUST be present in the associated "VEVENT"
+ calendar component. If the alarm is specified for a to-do with a
+ trigger set relative to the END, then either the "DUE" property or
+ the "DSTART" and "DURATION' properties MUST be present in the
+ associated "VTODO" calendar component.
+
+ Alarms specified in an event or to-do which is defined in terms of a
+ DATE value type will be triggered relative to 00:00:00 UTC on the
+ specified date. For example, if "DTSTART:19980205, then the duration
+ trigger will be relative to19980205T000000Z.
+
+ Format Definition: The property is defined by the following notation:
+
+ trigger = "TRIGGER" (trigrel / trigabs)
+
+ trigrel = *(
+
+ ; the following are optional,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" "DURATION") /
+ (";" trigrelparam) /
+
+ ; the following is optional,
+
+
+
+Dawson & Stenerson Standards Track [Page 128]
+
+RFC 2445 iCalendar November 1998
+
+
+ ; and MAY occur more than once
+
+ (";" xparam)
+ ) ":" dur-value
+
+ trigabs = 1*(
+
+ ; the following is REQUIRED,
+ ; but MUST NOT occur more than once
+
+ (";" "VALUE" "=" "DATE-TIME") /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ ) ":" date-time
+
+ Example: A trigger set 15 minutes prior to the start of the event or
+ to-do.
+
+ TRIGGER:-P15M
+
+ A trigger set 5 minutes after the end of the event or to-do.
+
+ TRIGGER;RELATED=END:P5M
+
+ A trigger set to an absolute date/time.
+
+ TRIGGER;VALUE=DATE-TIME:19980101T050000Z
+
+4.8.7 Change Management Component Properties
+
+ The following properties specify change management information in
+ calendar components.
+
+4.8.7.1 Date/Time Created
+
+ Property Name: CREATED
+
+ Purpose: This property specifies the date and time that the calendar
+ information was created by the calendar user agent in the calendar
+ store.
+
+ Note: This is analogous to the creation date and time for a file
+ in the file system.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 129]
+
+RFC 2445 iCalendar November 1998
+
+
+ Value Type: DATE-TIME
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified once in "VEVENT", "VTODO"
+ or "VJOURNAL" calendar components.
+
+ Description: The date and time is a UTC value.
+
+ Format Definition: The property is defined by the following notation:
+
+ created = "CREATED" creaparam ":" date-time CRLF
+
+ creaparam = *(";" xparam)
+
+ Example: The following is an example of this property:
+
+ CREATED:19960329T133000Z
+
+4.8.7.2 Date/Time Stamp
+
+ Property Name: DTSTAMP
+
+ Purpose: The property indicates the date/time that the instance of
+ the iCalendar object was created.
+
+ Value Type: DATE-TIME
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property MUST be included in the "VEVENT", "VTODO",
+ "VJOURNAL" or "VFREEBUSY" calendar components.
+
+ Description: The value MUST be specified in the UTC time format.
+
+ This property is also useful to protocols such as [IMIP] that have
+ inherent latency issues with the delivery of content. This property
+ will assist in the proper sequencing of messages containing iCalendar
+ objects.
+
+ This property is different than the "CREATED" and "LAST-MODIFIED"
+ properties. These two properties are used to specify when the
+ particular calendar data in the calendar store was created and last
+ modified. This is different than when the iCalendar object
+ representation of the calendar service information was created or
+ last modified.
+
+
+
+Dawson & Stenerson Standards Track [Page 130]
+
+RFC 2445 iCalendar November 1998
+
+
+ Format Definition: The property is defined by the following notation:
+
+ dtstamp = "DTSTAMP" stmparam ":" date-time CRLF
+
+ stmparam = *(";" xparam)
+
+ Example:
+
+ DTSTAMP:19971210T080000Z
+
+4.8.7.3 Last Modified
+
+ Property Name: LAST-MODIFIED
+
+ Purpose: The property specifies the date and time that the
+ information associated with the calendar component was last revised
+ in the calendar store.
+
+ Note: This is analogous to the modification date and time for a
+ file in the file system.
+
+ Value Type: DATE-TIME
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: This property can be specified in the "EVENT", "VTODO",
+ "VJOURNAL" or "VTIMEZONE" calendar components.
+
+ Description: The property value MUST be specified in the UTC time
+ format.
+
+ Format Definition: The property is defined by the following notation:
+
+ last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF
+
+ lstparam = *(";" xparam)
+
+ Example: The following is are examples of this property:
+
+ LAST-MODIFIED:19960817T133000Z
+
+4.8.7.4 Sequence Number
+
+ Property Name: SEQUENCE
+
+ Purpose: This property defines the revision sequence number of the
+ calendar component within a sequence of revisions.
+
+
+
+Dawson & Stenerson Standards Track [Page 131]
+
+RFC 2445 iCalendar November 1998
+
+
+ Value Type: integer
+
+ Property Parameters: Non-standard property parameters can be
+ specified on this property.
+
+ Conformance: The property can be specified in "VEVENT", "VTODO" or
+ "VJOURNAL" calendar component.
+
+ Description: When a calendar component is created, its sequence
+ number is zero (US-ASCII decimal 48). It is monotonically incremented
+ by the "Organizer's" CUA each time the "Organizer" makes a
+ significant revision to the calendar component. When the "Organizer"
+ makes changes to one of the following properties, the sequence number
+ MUST be incremented:
+
+ . "DTSTART"
+
+ . "DTEND"
+
+ . "DUE"
+
+ . "RDATE"
+
+ . "RRULE"
+
+ . "EXDATE"
+
+ . "EXRULE"
+
+ . "STATUS"
+
+ In addition, changes made by the "Organizer" to other properties can
+ also force the sequence number to be incremented. The "Organizer" CUA
+ MUST increment the sequence number when ever it makes changes to
+ properties in the calendar component that the "Organizer" deems will
+ jeopardize the validity of the participation status of the
+ "Attendees". For example, changing the location of a meeting from one
+ locale to another distant locale could effectively impact the
+ participation status of the "Attendees".
+
+ The "Organizer" includes this property in an iCalendar object that it
+ sends to an "Attendee" to specify the current version of the calendar
+ component.
+
+ The "Attendee" includes this property in an iCalendar object that it
+ sends to the "Organizer" to specify the version of the calendar
+ component that the "Attendee" is referring to.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 132]
+
+RFC 2445 iCalendar November 1998
+
+
+ A change to the sequence number is not the mechanism that an
+ "Organizer" uses to request a response from the "Attendees". The
+ "RSVP" parameter on the "ATTENDEE" property is used by the
+ "Organizer" to indicate that a response from the "Attendees" is
+ requested.
+
+ Format Definition: This property is defined by the following
+ notation:
+
+ seq = "SEQUENCE" seqparam ":" integer CRLF
+ ; Default is "0"
+
+ seqparam = *(";" xparam)
+
+ Example: The following is an example of this property for a calendar
+ component that was just created by the "Organizer".
+
+ SEQUENCE:0
+
+ The following is an example of this property for a calendar component
+ that has been revised two different times by the "Organizer".
+
+ SEQUENCE:2
+
+4.8.8 Miscellaneous Component Properties
+
+ The following properties specify information about a number of
+ miscellaneous features of calendar components.
+
+4.8.8.1 Non-standard Properties
+
+ Property Name: Any property name with a "X-" prefix
+
+ Purpose: This class of property provides a framework for defining
+ non-standard properties.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard and language property parameters
+ can be specified on this property.
+
+ Conformance: This property can be specified in any calendar
+ component.
+
+ Description: The MIME Calendaring and Scheduling Content Type
+ provides a "standard mechanism for doing non-standard things". This
+ extension support is provided for implementers to "push the envelope"
+ on the existing version of the memo. Extension properties are
+
+
+
+Dawson & Stenerson Standards Track [Page 133]
+
+RFC 2445 iCalendar November 1998
+
+
+ specified by property and/or property parameter names that have the
+ prefix text of "X-" (the two character sequence: LATIN CAPITAL LETTER
+ X character followed by the HYPEN-MINUS character). It is recommended
+ that vendors concatenate onto this sentinel another short prefix text
+ to identify the vendor. This will facilitate readability of the
+ extensions and minimize possible collision of names between different
+ vendors. User agents that support this content type are expected to
+ be able to parse the extension properties and property parameters but
+ can ignore them.
+
+ At present, there is no registration authority for names of extension
+ properties and property parameters. The data type for this property
+ is TEXT. Optionally, the data type can be any of the other valid data
+ types.
+
+ Format Definition: The property is defined by the following notation:
+
+ x-prop = x-name *(";" xparam) [";" languageparam] ":" text CRLF
+ ; Lines longer than 75 octets should be folded
+
+ Example: The following might be the ABC vendor's extension for an
+ audio-clip form of subject property:
+
+ X-ABC-MMSUBJ;X-ABC-MMSUBJTYPE=wave:http://load.noise.org/mysubj.wav
+
+4.8.8.2 Request Status
+
+ Property Name: REQUEST-STATUS
+
+ Purpose: This property defines the status code returned for a
+ scheduling request.
+
+ Value Type: TEXT
+
+ Property Parameters: Non-standard and language property parameters
+ can be specified on this property.
+
+ Conformance: The property can be specified in "VEVENT", "VTODO",
+ "VJOURNAL" or "VFREEBUSY" calendar component.
+
+ Description: This property is used to return status code information
+ related to the processing of an associated iCalendar object. The data
+ type for this property is TEXT.
+
+ The value consists of a short return status component, a longer
+ return status description component, and optionally a status-specific
+ data component. The components of the value are separated by the
+ SEMICOLON character (US-ASCII decimal 59).
+
+
+
+Dawson & Stenerson Standards Track [Page 134]
+
+RFC 2445 iCalendar November 1998
+
+
+ The short return status is a PERIOD character (US-ASCII decimal 46)
+ separated 3-tuple of integers. For example, "3.1.1". The successive
+ levels of integers provide for a successive level of status code
+ granularity.
+
+ The following are initial classes for the return status code.
+ Individual iCalendar object methods will define specific return
+ status codes for these classes. In addition, other classes for the
+ return status code may be defined using the registration process
+ defined later in this memo.
+
+ |==============+===============================================|
+ | Short Return | Longer Return Status Description |
+ | Status Code | |
+ |==============+===============================================|
+ | 1.xx | Preliminary success. This class of status |
+ | | of status code indicates that the request has |
+ | | request has been initially processed but that |
+ | | completion is pending. |
+ |==============+===============================================|
+ | 2.xx | Successful. This class of status code |
+ | | indicates that the request was completed |
+ | | successfuly. However, the exact status code |
+ | | can indicate that a fallback has been taken. |
+ |==============+===============================================|
+ | 3.xx | Client Error. This class of status code |
+ | | indicates that the request was not successful.|
+ | | The error is the result of either a syntax or |
+ | | a semantic error in the client formatted |
+ | | request. Request should not be retried until |
+ | | the condition in the request is corrected. |
+ |==============+===============================================|
+ | 4.xx | Scheduling Error. This class of status code |
+ | | indicates that the request was not successful.|
+ | | Some sort of error occurred within the |
+ | | calendaring and scheduling service, not |
+ | | directly related to the request itself. |
+ |==============+===============================================|
+
+ Format Definition: The property is defined by the following notation:
+
+ rstatus = "REQUEST-STATUS" rstatparam ":"
+ statcode ";" statdesc [";" extdata]
+
+ rstatparam = *(
+
+ ; the following is optional,
+ ; but MUST NOT occur more than once
+
+
+
+Dawson & Stenerson Standards Track [Page 135]
+
+RFC 2445 iCalendar November 1998
+
+
+ (";" languageparm) /
+
+ ; the following is optional,
+ ; and MAY occur more than once
+
+ (";" xparam)
+
+ )
+
+ statcode = 1*DIGIT *("." 1*DIGIT)
+ ;Hierarchical, numeric return status code
+
+ statdesc = text
+ ;Textual status description
+
+ extdata = text
+ ;Textual exception data. For example, the offending property
+ ;name and value or complete property line.
+
+ Example: The following are some possible examples of this property.
+ The COMMA and SEMICOLON separator characters in the property value
+ are BACKSLASH character escaped because they appear in a text value.
+
+ REQUEST-STATUS:2.0;Success
+
+ REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
+
+ REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled
+ as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2
+
+ REQUEST-STATUS:4.1;Event conflict. Date/time is busy.
+
+ REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
+ MAILTO:jsmith at host.com
+
+5 iCalendar Object Examples
+
+ The following examples are provided as an informational source of
+ illustrative iCalendar objects consistent with this content type.
+
+ The following example specifies a three-day conference that begins at
+ 8:00 AM EDT, September 18, 1996 and end at 6:00 PM EDT, September 20,
+ 1996.
+
+ BEGIN:VCALENDAR PRODID:-//xyz Corp//NONSGML PDA Calendar Verson
+ 1.0//EN VERSION:2.0 BEGIN:VEVENT DTSTAMP:19960704T120000Z
+ UID:uid1 at host.com ORGANIZER:MAILTO:jsmith at host.com
+ DTSTART:19960918T143000Z DTEND:19960920T220000Z STATUS:CONFIRMED
+
+
+
+Dawson & Stenerson Standards Track [Page 136]
+
+RFC 2445 iCalendar November 1998
+
+
+ CATEGORIES:CONFERENCE SUMMARY:Networld+Interop Conference
+ DESCRIPTION:Networld+Interop Conference
+ and Exhibit\nAtlanta World Congress Center\n
+ Atlanta, Georgia END:VEVENT END:VCALENDAR
+
+ The following example specifies a group scheduled meeting that begin
+ at 8:30 AM EST on March 12, 1998 and end at 9:30 AM EST on March 12,
+ 1998. The "Organizer" has scheduled the meeting with one or more
+ calendar users in a group. A time zone specification for Eastern
+ United States has been specified.
+
+ BEGIN:VCALENDAR
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VTIMEZONE
+ TZID:US-Eastern
+ BEGIN:STANDARD
+ DTSTART:19981025T020000
+ RDATE:19981025T020000
+ TZOFFSETFROM:-0400
+ TZOFFSETTO:-0500
+ TZNAME:EST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19990404T020000
+ RDATE:19990404T020000
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0400
+ TZNAME:EDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+ BEGIN:VEVENT
+ DTSTAMP:19980309T231000Z
+ UID:guid-1.host1.com
+ ORGANIZER;ROLE=CHAIR:MAILTO:mrbig at host.com
+ ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
+ MAILTO:employee-A at host.com
+ DESCRIPTION:Project XYZ Review Meeting
+ CATEGORIES:MEETING
+ CLASS:PUBLIC
+ CREATED:19980309T130000Z
+ SUMMARY:XYZ Project Review
+ DTSTART;TZID=US-Eastern:19980312T083000
+ DTEND;TZID=US-Eastern:19980312T093000
+ LOCATION:1CP Conference Room 4350
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+Dawson & Stenerson Standards Track [Page 137]
+
+RFC 2445 iCalendar November 1998
+
+
+ The following is an example of an iCalendar object passed in a MIME
+ message with a single body part consisting of a "text/calendar"
+ Content Type.
+
+ TO:jsmith at host1.com
+ FROM:jdoe at host1.com
+ MIME-VERSION:1.0
+ MESSAGE-ID:<id3 at host1.com>
+ CONTENT-TYPE:text/calendar
+
+ BEGIN:VCALENDAR
+ METHOD:xyz
+ VERSION:2.0
+ PRODID:-//ABC Corporation//NONSGML My Product//EN
+ BEGIN:VEVENT
+ DTSTAMP:19970324T1200Z
+ SEQUENCE:0
+ UID:uid3 at host1.com
+ ORGANIZER:MAILTO:jdoe at host1.com
+ ATTENDEE;RSVP=TRUE:MAILTO:jsmith at host1.com
+ DTSTART:19970324T123000Z
+ DTEND:19970324T210000Z
+ CATEGORIES:MEETING,PROJECT
+ CLASS:PUBLIC
+ SUMMARY:Calendaring Interoperability Planning Meeting
+ DESCRIPTION:Discuss how we can test c&s interoperability\n
+ using iCalendar and other IETF standards.
+ LOCATION:LDB Lobby
+ ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
+ conf/bkgrnd.ps
+ END:VEVENT
+ END:VCALENDAR
+
+ The following is an example of a to-do due on April 15, 1998. An
+ audio alarm has been specified to remind the calendar user at noon,
+ the day before the to-do is expected to be completed and repeat
+ hourly, four additional times. The to-do definition has been modified
+ twice since it was initially created.
+
+ BEGIN:VCALENDAR
+ VERSION:2.0
+ PRODID:-//ABC Corporation//NONSGML My Product//EN
+ BEGIN:VTODO
+ DTSTAMP:19980130T134500Z
+ SEQUENCE:2
+ UID:uid4 at host1.com
+ ORGANIZER:MAILTO:unclesam at us.gov
+ ATTENDEE;PARTSTAT=ACCEPTED:MAILTO:jqpublic at host.com
+
+
+
+Dawson & Stenerson Standards Track [Page 138]
+
+RFC 2445 iCalendar November 1998
+
+
+ DUE:19980415T235959
+ STATUS:NEEDS-ACTION
+ SUMMARY:Submit Income Taxes
+ BEGIN:VALARM
+ ACTION:AUDIO
+ TRIGGER:19980403T120000
+ ATTACH;FMTTYPE=audio/basic:http://host.com/pub/audio-
+ files/ssbanner.aud
+ REPEAT:4
+ DURATION:PT1H
+ END:VALARM
+ END:VTODO
+ END:VCALENDAR
+
+ The following is an example of a journal entry.
+
+ BEGIN:VCALENDAR
+ VERSION:2.0
+ PRODID:-//ABC Corporation//NONSGML My Product//EN
+ BEGIN:VJOURNAL
+ DTSTAMP:19970324T120000Z
+ UID:uid5 at host1.com
+ ORGANIZER:MAILTO:jsmith at host.com
+ STATUS:DRAFT
+ CLASS:PUBLIC
+ CATEGORY:Project Report, XYZ, Weekly Meeting
+ DESCRIPTION:Project xyz Review Meeting Minutes\n
+ Agenda\n1. Review of project version 1.0 requirements.\n2.
+ Definition
+ of project processes.\n3. Review of project schedule.\n
+ Participants: John Smith, Jane Doe, Jim Dandy\n-It was
+ decided that the requirements need to be signed off by
+ product marketing.\n-Project processes were accepted.\n
+ -Project schedule needs to account for scheduled holidays
+ and employee vacation time. Check with HR for specific
+ dates.\n-New schedule will be distributed by Friday.\n-
+ Next weeks meeting is cancelled. No meeting until 3/23.
+ END:VJOURNAL
+ END:VCALENDAR
+
+ The following is an example of published busy time information. The
+ iCalendar object might be placed in the network resource
+ www.host.com/calendar/busytime/jsmith.ifb.
+
+ BEGIN:VCALENDAR
+ VERSION:2.0
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ BEGIN:VFREEBUSY
+
+
+
+Dawson & Stenerson Standards Track [Page 139]
+
+RFC 2445 iCalendar November 1998
+
+
+ ORGANIZER:MAILTO:jsmith at host.com
+ DTSTART:19980313T141711Z
+ DTEND:19980410T141711Z
+ FREEBUSY:19980314T233000Z/19980315T003000Z
+ FREEBUSY:19980316T153000Z/19980316T163000Z
+ FREEBUSY:19980318T030000Z/19980318T040000Z
+ URL:http://www.host.com/calendar/busytime/jsmith.ifb
+ END:VFREEBUSY
+ END:VCALENDAR
+
+6 Recommended Practices
+
+ These recommended practices should be followed in order to assure
+ consistent handling of the following cases for an iCalendar object.
+
+ 1. Content lines longer than 75 octets SHOULD be folded.
+
+ 2. A calendar entry with a "DTSTART" property but no "DTEND"
+ property does not take up any time. It is intended to represent
+ an event that is associated with a given calendar date and time
+ of day, such as an anniversary. Since the event does not take up
+ any time, it MUST NOT be used to record busy time no matter what
+ the value for the "TRANSP" property.
+
+ 3. When the "DTSTART" and "DTEND", for "VEVENT", "VJOURNAL" and
+ "VFREEBUSY" calendar components, and "DTSTART" and "DUE", for
+ "VTODO" calendar components, have the same value data type (e.g.,
+ DATE-TIME), they SHOULD specify values in the same time format
+ (e.g., UTC time format).
+
+ 4. When the combination of the "RRULE" and "RDATE" properties on an
+ iCalendar object produces multiple instances having the same
+ start date/time, they should be collapsed to, and considered as,
+ a single instance.
+
+ 5. When a calendar user receives multiple requests for the same
+ calendar component (e.g., REQUEST for a "VEVENT" calendar
+ component) as a result of being on multiple mailing lists
+ specified by "ATTENDEE" properties in the request, they SHOULD
+ respond to only one of the requests. The calendar user SHOULD
+ also specify (using the "MEMBER" parameter of the "ATTENDEE"
+ property) which mailing list they are a member of.
+
+ 6. An implementation can truncate a "SUMMARY" property value to 255
+ characters.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 140]
+
+RFC 2445 iCalendar November 1998
+
+
+ 7. If seconds of the minute are not supported by an implementation,
+ then a value of "00" SHOULD be specified for the seconds
+ component in a time value.
+
+ 8. If the value type parameter (VALUE=) contains an unknown value
+ type, it SHOULD be treated as TEXT.
+
+ 9. TZURL values SHOULD NOT be specified as a FILE URI type. This URI
+ form can be useful within an organization, but is problematic in
+ the Internet.
+
+ 10. Some possible English values for CATEGORIES property include
+ "ANNIVERSARY", "APPOINTMENT", "BUSINESS", "EDUCATION",
+ "HOLIDAY", "MEETING", "MISCELLANEOUS", "NON-WORKING HOURS", "NOT
+ IN OFFICE", "PERSONAL", "PHONE CALL", "SICK DAY", "SPECIAL
+ OCCASION", "TRAVEL", "VACATION". Categories can be specified in
+ any registered language.
+
+ 11. Some possible English values for RESOURCES property include
+ "CATERING", "CHAIRS", "COMPUTER PROJECTOR", "EASEL", "OVERHEAD
+ PROJECTOR", "SPEAKER PHONE", "TABLE", "TV", "VCR", "VIDEO
+ PHONE", "VEHICLE". Resources can be specified in any registered
+ language.
+
+7 Registration of Content Type Elements
+
+ This section provides the process for registration of MIME
+ Calendaring and Scheduling Content Type iCalendar object methods and
+ new or modified properties.
+
+7.1 Registration of New and Modified iCalendar Object Methods
+
+ New MIME Calendaring and Scheduling Content Type iCalendar object
+ methods are registered by the publication of an IETF Request for
+ Comments (RFC). Changes to an iCalendar object method are registered
+ by the publication of a revision of the RFC defining the method.
+
+7.2 Registration of New Properties
+
+ This section defines procedures by which new properties or enumerated
+ property values for the MIME Calendaring and Scheduling Content Type
+ can be registered with the IANA. Non-IANA properties can be used by
+ bilateral agreement, provided the associated properties names follow
+ the "X-" convention.
+
+ The procedures defined here are designed to allow public comment and
+ review of new properties, while posing only a small impediment to the
+ definition of new properties.
+
+
+
+Dawson & Stenerson Standards Track [Page 141]
+
+RFC 2445 iCalendar November 1998
+
+
+ Registration of a new property is accomplished by the following
+ steps.
+
+7.2.1 Define the property
+
+ A property is defined by completing the following template.
+
+ To: ietf-calendar at imc.org
+
+ Subject: Registration of text/calendar MIME property XXX
+
+ Property name:
+
+ Property purpose:
+
+ Property value type(s):
+
+ Property parameter (s):
+
+ Conformance:
+
+ Description:
+
+ Format definition:
+
+ Examples:
+
+ The meaning of each field in the template is as follows.
+
+ Property name: The name of the property, as it will appear in the
+ body of an text/calendar MIME Content-Type "property: value" line to
+ the left of the colon ":".
+
+ Property purpose: The purpose of the property (e.g., to indicate a
+ delegate for the event or to-do, etc.). Give a short but clear
+ description.
+
+ Property value type (s): Any of the valid value types for the
+ property value needs to be specified. The default value type also
+ needs to be specified. If a new value type is specified, it needs to
+ be declared in this section.
+
+ Property parameter (s): Any of the valid property parameters for the
+ property needs to be specified.
+
+ Conformance: The calendar components that the property can appear in
+ needs to be specified.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 142]
+
+RFC 2445 iCalendar November 1998
+
+
+ Description: Any special notes about the property, how it is to be
+ used, etc.
+
+ Format definition: The ABNF for the property definition needs to be
+ specified.
+
+ Examples: One or more examples of instances of the property needs to
+ be specified.
+
+7.2.2 Post the Property definition
+
+ The property description MUST be posted to the new property
+ discussion list, ietf-calendar at imc.org.
+
+7.2.3 Allow a comment period
+
+ Discussion on the new property MUST be allowed to take place on the
+ list for a minimum of two weeks. Consensus MUST be reached on the
+ property before proceeding to the next step.
+
+7.2.4 Submit the property for approval
+
+ Once the two-week comment period has elapsed, and the proposer is
+ convinced consensus has been reached on the property, the
+ registration application should be submitted to the Method Reviewer
+ for approval. The Method Reviewer is appointed to the Application
+ Area Directors and can either accept or reject the property
+ registration. An accepted registration should be passed on by the
+ Method Reviewer to the IANA for inclusion in the official IANA method
+ registry. The registration can be rejected for any of the following
+ reasons. 1) Insufficient comment period; 2) Consensus not reached; 3)
+ Technical deficiencies raised on the list or elsewhere have not been
+ addressed. The Method Reviewer's decision to reject a property can be
+ appealed by the proposer to the IESG, or the objections raised can be
+ addressed by the proposer and the property resubmitted.
+
+7.3 Property Change Control
+
+ Existing properties can be changed using the same process by which
+ they were registered.
+
+ 1. Define the change
+
+ 2. Post the change
+
+ 3. Allow a comment period
+
+ 4. Submit the property for approval
+
+
+
+Dawson & Stenerson Standards Track [Page 143]
+
+RFC 2445 iCalendar November 1998
+
+
+ Note that the original author or any other interested party can
+ propose a change to an existing property, but that such changes
+ should only be proposed when there are serious omissions or errors in
+ the published memo. The Method Reviewer can object to a change if it
+ is not backward compatible, but is not required to do so.
+
+ Property definitions can never be deleted from the IANA registry, but
+ properties which are no longer believed to be useful can be declared
+ OBSOLETE by a change to their "intended use" field.
+
+8 References
+
+ [IMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
+ Message-based Interoperability Protocol (IMIP)", RFC 2447,
+ November 1998.
+
+ [ITIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
+ "iCalendar Transport-Independent Interoperability Protocol
+ (iTIP) : Scheduling Events, Busy Time, To-dos and Journal
+ Entries", RFC 2446, November 1998.
+
+ [ISO 8601] ISO 8601, "Data elements and interchange formats-
+ Information interchange--Representation of dates and
+ times", International Organization for Standardization,
+ June, 1988.
+
+ [ISO 9070] ISO/IEC 9070, "Information Technology_SGML Support
+ Facilities--Registration Procedures for Public Text Owner
+ Identifiers", Second Edition, International Organization
+ for Standardization, April 1991.
+
+ [RFC 822] Crocker, D., "Standard for the Format of ARPA Internet
+ Text Messages", STD 11, RFC 822, August 1982.
+
+ [RFC 1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform
+ Resource Locators (URL)", RFC 1738, December 1994.
+
+ [RFC 1766] Alvestrand, H., "Tags for the Identification of
+ Languages", RFC 1766, March 1995.
+
+ [RFC 2045] Freed, N. and N. Borenstein, " Multipurpose Internet Mail
+ Extensions (MIME) - Part One: Format of Internet Message
+ Bodies", RFC 2045, November 1996.
+
+ [RFC 2046] Freed, N. and N. Borenstein, " Multipurpose Internet Mail
+ Extensions (MIME) - Part Two: Media Types", RFC 2046,
+ November 1996.
+
+
+
+
+Dawson & Stenerson Standards Track [Page 144]
+
+RFC 2445 iCalendar November 1998
+
+
+ [RFC 2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
+ Internet Mail Extensions (MIME) - Part Four: Registration
+ Procedures", RFC 2048, January 1997.
+
+ [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC 2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", RFC 2234, November 1997.
+
+ [RFC 2279] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", RFC 2279, January 1998.
+
+ [RFC 2425] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type
+ for Directory Information", RFC 2425, September 1998.
+
+ [RFC 2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
+ RFC 2426, September 1998.
+
+ [TZ] Olson, A.D., et al, Time zone code and data,
+ ftp://elsie.nci.nih.gov/pub/, updated periodically.
+
+ [VCAL] Internet Mail Consortium, "vCalendar - The Electronic
+ Calendaring and Scheduling Exchange Format",
+ http://www.imc.org/pdi/vcal-10.txt, September 18, 1996.
+
+9 Acknowledgments
+
+ A hearty thanks to the IETF Calendaring and Scheduling Working Group
+ and also the following individuals who have participated in the
+ drafting, review and discussion of this memo:
+
+ Roland Alden, Harald T. Alvestrand, Eric Berman, Denis Bigorgne, John
+ Binici, Bill Bliss, Philippe Boucher, Steve Carter, Andre
+ Courtemanche, Dave Crocker, David Curley, Alec Dun, John Evans, Ross
+ Finlayson, Randell Flint, Ned Freed, Patrik Faltstrom, Chuck
+ Grandgent, Mark Handley, Steve Hanna, Paul B. Hill, Paul Hoffman,
+ Ross Hopson, Mark Horton, Daryl Huff, Bruce Kahn, C. Harald Koch,
+ Ryan Jansen, Don Lavange, Antoine Leca, Theodore Lorek, Steve
+ Mansour, Skip Montanaro, Keith Moore, Cecil Murray, Chris Newman,
+ John Noerenberg, Ralph Patterson, Pete Resnick, Keith Rhodes, Robert
+ Ripberger, John Rose, Doug Royer, Andras Salamar, Ted Schuh, Vinod
+ Seraphin, Derrick Shadel, Ken Shan, Andrew Shuman, Steve Silverberg,
+ William P. Spencer, John Sun, Mark Towfiq, Yvonne Tso, Robert Visnov,
+ James L. Weiner, Mike Weston, William Wyatt.
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 145]
+
+RFC 2445 iCalendar November 1998
+
+
+10 Authors' and Chairs' Addresses
+
+ The following address information is provided in a MIME-VCARD,
+ Electronic Business Card, format.
+
+ The authors of this memo are:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Dawson;Frank
+ FN:Frank Dawson
+ ORG:Lotus Development Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive;
+ Raleigh;NC;27613-3502;USA
+ TEL;TYPE=WORK,MSG:+1-919-676-9515
+ TEL;TYPE=WORK,FAX:+1-919-676-9564
+ EMAIL;TYPE=PREF,INTERNET:Frank_Dawson at Lotus.com
+ EMAIL;TYPE=INTERNET:fdawson at earthlink.net
+ URL:http://home.earthlink.net/~fdawson
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Stenerson;Derik
+ FN:Derik Stenerson
+ ORG:Microsoft Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
+ Redmond;WA;98052-6399;USA
+ TEL;TYPE=WORK,MSG:+1-425-936-5522
+ TEL;TYPE=WORK,FAX:+1-425-936-7329
+ EMAIL;TYPE=INTERNET:deriks at Microsoft.com
+ END:VCARD
+
+ The iCalendar object is a result of the work of the Internet
+ Engineering Task Force Calendaring and Scheduling Working Group. The
+ chairmen of that working group are:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Ganguly;Anik
+ FN:Anik Ganguly
+ ORG: Open Text Inc.
+ ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
+ Livonia;MI;48152;USA
+ TEL;TYPE=WORK,MSG:+1-734-542-5955
+ EMAIL;TYPE=INTERNET:ganguly at acm.org
+ END:VCARD
+
+
+
+
+Dawson & Stenerson Standards Track [Page 146]
+
+RFC 2445 iCalendar November 1998
+
+
+ The co-chairman of that working group is:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Moskowitz;Robert
+ FN:Robert Moskowitz
+ EMAIL;TYPE=INTERNET:rgm-ietf at htt-consult.com
+ END:VCARD
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 147]
+
+RFC 2445 iCalendar November 1998
+
+
+11. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dawson & Stenerson Standards Track [Page 148]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2445.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2445.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2445.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,8291 +0,0 @@
-
-
-
-
-
-
-Network Working Group F. Dawson
-Request for Comments: 2445 Lotus
-Category: Standards Track D. Stenerson
- Microsoft
- November 1998
-
-
- Internet Calendaring and Scheduling Core Object Specification
- (iCalendar)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
-Abstract
-
- There is a clear need to provide and deploy interoperable calendaring
- and scheduling services for the Internet. Current group scheduling
- and Personal Information Management (PIM) products are being extended
- for use across the Internet, today, in proprietary ways. This memo
- has been defined to provide the definition of a common format for
- openly exchanging calendaring and scheduling information across the
- Internet.
-
- This memo is formatted as a registration for a MIME media type per
- [RFC 2048]. However, the format in this memo is equally applicable
- for use outside of a MIME message content type.
-
- The proposed media type value is 'text/calendar'. This string would
- label a media type containing calendaring and scheduling information
- encoded as text characters formatted in a manner outlined below.
-
- This MIME media type provides a standard content type for capturing
- calendar event, to-do and journal entry information. It also can be
- used to convey free/busy time information. The content type is
- suitable as a MIME message entity that can be transferred over MIME
- based email systems, using HTTP or some other Internet transport. In
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 1]
-
-RFC 2445 iCalendar November 1998
-
-
- addition, the content type is useful as an object for interactions
- between desktop applications using the operating system clipboard,
- drag/drop or file systems capabilities.
-
- This memo is based on the earlier work of the vCalendar specification
- for the exchange of personal calendaring and scheduling information.
- In order to avoid confusion with this referenced work, this memo is
- to be known as the iCalendar specification.
-
- This memo defines the format for specifying iCalendar object methods.
- An iCalendar object method is a set of usage constraints for the
- iCalendar object. For example, these methods might define scheduling
- messages that request an event be scheduled, reply to an event
- request, send a cancellation notice for an event, modify or replace
- the definition of an event, provide a counter proposal for an
- original event request, delegate an event request to another
- individual, request free or busy time, reply to a free or busy time
- request, or provide similar scheduling messages for a to-do or
- journal entry calendar component. The iCalendar Transport-indendent
- Interoperability Protocol (iTIP) defined in [ITIP] is one such
- scheduling protocol.
-
-Table of Contents
-
- 1 Introduction.....................................................5
- 2 Basic Grammar and Conventions....................................6
- 2.1 Formatting Conventions .......................................7
- 2.2 Related Memos ................................................8
- 2.3 International Considerations .................................8
- 3 Registration Information.........................................8
- 3.1 Content Type .................................................8
- 3.2 Parameters ...................................................9
- 3.3 Content Header Fields .......................................10
- 3.4 Encoding Considerations .....................................10
- 3.5 Security Considerations .....................................10
- 3.6 Interoperability Considerations .............................11
- 3.7 Applications Which Use This Media Type ......................11
- 3.8 Additional Information ......................................11
- 3.9 Magic Numbers ...............................................11
- 3.10 File Extensions ............................................11
- 3.11 Contact for Further Information: ...........................12
- 3.12 Intended Usage .............................................12
- 3.13 Authors/Change Controllers .................................12
- 4 iCalendar Object Specification..................................13
- 4.1 Content Lines ...............................................13
- 4.1.1 List and Field Separators ................................16
- 4.1.2 Multiple Values ..........................................16
- 4.1.3 Binary Content ...........................................16
-
-
-
-Dawson & Stenerson Standards Track [Page 2]
-
-RFC 2445 iCalendar November 1998
-
-
- 4.1.4 Character Set ............................................17
- 4.2 Property Parameters .........................................17
- 4.2.1 Alternate Text Representation ............................18
- 4.2.2 Common Name ..............................................19
- 4.2.3 Calendar User Type .......................................20
- 4.2.4 Delegators ...............................................20
- 4.2.5 Delegatees ...............................................21
- 4.2.6 Directory Entry Reference ................................21
- 4.2.7 Inline Encoding ..........................................22
- 4.2.8 Format Type ..............................................23
- 4.2.9 Free/Busy Time Type ......................................23
- 4.2.10 Language ................................................24
- 4.2.11 Group or List Membership ................................25
- 4.2.12 Participation Status ....................................25
- 4.2.13 Recurrence Identifier Range .............................27
- 4.2.14 Alarm Trigger Relationship ..............................27
- 4.2.15 Relationship Type .......................................28
- 4.2.16 Participation Role ......................................29
- 4.2.17 RSVP Expectation ........................................29
- 4.2.18 Sent By .................................................30
- 4.2.19 Time Zone Identifier ....................................30
- 4.2.20 Value Data Types ........................................32
- 4.3 Property Value Data Types ...................................32
- 4.3.1 Binary ...................................................33
- 4.3.2 Boolean ..................................................33
- 4.3.3 Calendar User Address ....................................34
- 4.3.4 Date .....................................................34
- 4.3.5 Date-Time ................................................35
- 4.3.6 Duration .................................................37
- 4.3.7 Float ....................................................38
- 4.3.8 Integer ..................................................38
- 4.3.9 Period of Time ...........................................39
- 4.3.10 Recurrence Rule .........................................40
- 4.3.11 Text ....................................................45
- 4.3.12 Time ....................................................47
- 4.3.13 URI .....................................................49
- 4.3.14 UTC Offset ..............................................49
- 4.4 iCalendar Object ............................................50
- 4.5 Property ....................................................51
- 4.6 Calendar Components .........................................51
- 4.6.1 Event Component ..........................................52
- 4.6.2 To-do Component ..........................................55
- 4.6.3 Journal Component ........................................56
- 4.6.4 Free/Busy Component ......................................58
- 4.6.5 Time Zone Component ......................................60
- 4.6.6 Alarm Component ..........................................67
- 4.7 Calendar Properties .........................................73
- 4.7.1 Calendar Scale ...........................................73
-
-
-
-Dawson & Stenerson Standards Track [Page 3]
-
-RFC 2445 iCalendar November 1998
-
-
- 4.7.2 Method ...................................................74
- 4.7.3 Product Identifier .......................................75
- 4.7.4 Version ..................................................76
- 4.8 Component Properties ........................................77
- 4.8.1 Descriptive Component Properties .........................77
- 4.8.1.1 Attachment ...........................................77
- 4.8.1.2 Categories ...........................................78
- 4.8.1.3 Classification .......................................79
- 4.8.1.4 Comment ..............................................80
- 4.8.1.5 Description ..........................................81
- 4.8.1.6 Geographic Position ..................................82
- 4.8.1.7 Location .............................................84
- 4.8.1.8 Percent Complete .....................................85
- 4.8.1.9 Priority .............................................85
- 4.8.1.10 Resources ...........................................87
- 4.8.1.11 Status ..............................................88
- 4.8.1.12 Summary .............................................89
- 4.8.2 Date and Time Component Properties .......................90
- 4.8.2.1 Date/Time Completed ..................................90
- 4.8.2.2 Date/Time End ........................................91
- 4.8.2.3 Date/Time Due ........................................92
- 4.8.2.4 Date/Time Start ......................................93
- 4.8.2.5 Duration .............................................94
- 4.8.2.6 Free/Busy Time .......................................95
- 4.8.2.7 Time Transparency ....................................96
- 4.8.3 Time Zone Component Properties ...........................97
- 4.8.3.1 Time Zone Identifier .................................97
- 4.8.3.2 Time Zone Name .......................................98
- 4.8.3.3 Time Zone Offset From ................................99
- 4.8.3.4 Time Zone Offset To .................................100
- 4.8.3.5 Time Zone URL .......................................101
- 4.8.4 Relationship Component Properties .......................102
- 4.8.4.1 Attendee ............................................102
- 4.8.4.2 Contact .............................................104
- 4.8.4.3 Organizer ...........................................106
- 4.8.4.4 Recurrence ID .......................................107
- 4.8.4.5 Related To ..........................................109
- 4.8.4.6 Uniform Resource Locator ............................110
- 4.8.4.7 Unique Identifier ...................................111
- 4.8.5 Recurrence Component Properties .........................112
- 4.8.5.1 Exception Date/Times ................................112
- 4.8.5.2 Exception Rule ......................................114
- 4.8.5.3 Recurrence Date/Times ...............................115
- 4.8.5.4 Recurrence Rule .....................................117
- 4.8.6 Alarm Component Properties ..............................126
- 4.8.6.1 Action ..............................................126
- 4.8.6.2 Repeat Count ........................................126
- 4.8.6.3 Trigger .............................................127
-
-
-
-Dawson & Stenerson Standards Track [Page 4]
-
-RFC 2445 iCalendar November 1998
-
-
- 4.8.7 Change Management Component Properties ..................129
- 4.8.7.1 Date/Time Created ...................................129
- 4.8.7.2 Date/Time Stamp .....................................130
- 4.8.7.3 Last Modified .......................................131
- 4.8.7.4 Sequence Number .....................................131
- 4.8.8 Miscellaneous Component Properties ......................133
- 4.8.8.1 Non-standard Properties .............................133
- 4.8.8.2 Request Status ......................................134
- 5 iCalendar Object Examples......................................136
- 6 Recommended Practices..........................................140
- 7 Registration of Content Type Elements..........................141
- 7.1 Registration of New and Modified iCalendar Object Methods ..141
- 7.2 Registration of New Properties .............................141
- 7.2.1 Define the property .....................................142
- 7.2.2 Post the Property definition ............................143
- 7.2.3 Allow a comment period ..................................143
- 7.2.4 Submit the property for approval ........................143
- 7.3 Property Change Control ....................................143
- 8 References.....................................................144
- 9 Acknowledgments................................................145
- 10 Authors' and Chairs' Addresses................................146
- 11 Full Copyright Statement......................................148
-
-1 Introduction
-
- The use of calendaring and scheduling has grown considerably in the
- last decade. Enterprise and inter-enterprise business has become
- dependent on rapid scheduling of events and actions using this
- information technology. However, the longer term growth of
- calendaring and scheduling, is currently limited by the lack of
- Internet standards for the message content types that are central to
- these knowledgeware applications. This memo is intended to progress
- the level of interoperability possible between dissimilar calendaring
- and scheduling applications. This memo defines a MIME content type
- for exchanging electronic calendaring and scheduling information. The
- Internet Calendaring and Scheduling Core Object Specification, or
- iCalendar, allows for the capture and exchange of information
- normally stored within a calendaring and scheduling application; such
- as a Personal Information Manager (PIM) or a Group Scheduling
- product.
-
- The iCalendar format is suitable as an exchange format between
- applications or systems. The format is defined in terms of a MIME
- content type. This will enable the object to be exchanged using
- several transports, including but not limited to SMTP, HTTP, a file
- system, desktop interactive protocols such as the use of a memory-
- based clipboard or drag/drop interactions, point-to-point
- asynchronous communication, wired-network transport, or some form of
-
-
-
-Dawson & Stenerson Standards Track [Page 5]
-
-RFC 2445 iCalendar November 1998
-
-
- unwired transport such as infrared might also be used.
-
- The memo also provides for the definition of iCalendar object methods
- that will map this content type to a set of messages for supporting
- calendaring and scheduling operations such as requesting, replying
- to, modifying, and canceling meetings or appointments, to-dos and
- journal entries. The iCalendar object methods can be used to define
- other calendaring and scheduling operations such a requesting for and
- replying with free/busy time data. Such a scheduling protocol is
- defined in the iCalendar Transport-independent Interoperability
- Protocol (iTIP) defined in [ITIP].
-
- The memo also includes a formal grammar for the content type based on
- the Internet ABNF defined in [RFC 2234]. This ABNF is required for
- the implementation of parsers and to serve as the definitive
- reference when ambiguities or questions arise in interpreting the
- descriptive prose definition of the memo.
-
-2 Basic Grammar and Conventions
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY" and
- "OPTIONAL" in this document are to be interoperated as described in
- [RFC 2119].
-
- This memo makes use of both a descriptive prose and a more formal
- notation for defining the calendaring and scheduling format.
-
- The notation used in this memo is the ABNF notation of [RFC 2234].
- Readers intending on implementing this format defined in this memo
- should be familiar with this notation in order to properly interpret
- the specifications of this memo.
-
- All numeric and hexadecimal values used in this memo are given in
- decimal notation.
-
- All names of properties, property parameters, enumerated property
- values and property parameter values are case-insensitive. However,
- all other property values are case-sensitive, unless otherwise
- stated.
-
- Note: All indented editorial notes, such as this one, are
- intended to provide the reader with additional information. The
- information is not essential to the building of an
- implementation conformant with this memo. The information is
- provided to highlight a particular feature or characteristic of
- the memo.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 6]
-
-RFC 2445 iCalendar November 1998
-
-
- The format for the iCalendar object is based on the syntax of the
- [RFC 2425] content type. While the iCalendar object is not a profile
- of the [RFC 2425] content type, it does reuse a number of the
- elements from the [RFC 2425] specification.
-
-2.1 Formatting Conventions
-
- The mechanisms defined in this memo are defined in prose. Many of the
- terms used to describe these have common usage that is different than
- the standards usage of this memo. In order to reference within this
- memo elements of the calendaring and scheduling model, core object
- (this memo) or interoperability protocol [ITIP] some formatting
- conventions have been used. Calendaring and scheduling roles are
- referred to in quoted-strings of text with the first character of
- each word in upper case. For example, "Organizer" refers to a role of
- a "Calendar User" within the scheduling protocol defined by [ITIP].
- Calendar components defined by this memo are referred to with
- capitalized, quoted-strings of text. All calendar components start
- with the letter "V". For example, "VEVENT" refers to the event
- calendar component, "VTODO" refers to the to-do calendar component
- and "VJOURNAL" refers to the daily journal calendar component.
- Scheduling methods defined by [ITIP] are referred to with
- capitalized, quoted-strings of text. For example, "REQUEST" refers to
- the method for requesting a scheduling calendar component be created
- or modified, "REPLY" refers to the method a recipient of a request
- uses to update their status with the "Organizer" of the calendar
- component.
-
- The properties defined by this memo are referred to with capitalized,
- quoted-strings of text, followed by the word "property". For example,
- "ATTENDEE" property refers to the iCalendar property used to convey
- the calendar address of a calendar user. Property parameters defined
- by this memo are referred to with lowercase, quoted-strings of text,
- followed by the word "parameter". For example, "value" parameter
- refers to the iCalendar property parameter used to override the
- default data type for a property value. Enumerated values defined by
- this memo are referred to with capitalized text, either alone or
- followed by the word "value". For example, the "MINUTELY" value can
- be used with the "FREQ" component of the "RECUR" data type to specify
- repeating components based on an interval of one minute or more.
-
-
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 7]
-
-RFC 2445 iCalendar November 1998
-
-
-2.2 Related Memos
-
- Implementers will need to be familiar with several other memos that,
- along with this memo, form a framework for Internet calendaring and
- scheduling standards. This memo, [ICAL], specifies a core
- specification of objects, data types, properties and property
- parameters.
-
- [ITIP] - specifies an interoperability protocol for scheduling
- between different implementations;
-
- [IMIP] specifies an Internet email binding for [ITIP].
-
- This memo does not attempt to repeat the specification of concepts or
- definitions from these other memos. Where possible, references are
- made to the memo that provides for the specification of these
- concepts or definitions.
-
-2.3 International Considerations
-
- In the rest of this document, descriptions of characters are of the
- form "character name (codepoint)", where "codepoint" is from the US-
- ASCII character set. The "character name" is the authoritative
- description; (codepoint) is a reference to that character in US-ASCII
- or US-ASCII compatible sets (for example the ISO-8859-x family, UTF-
- 8, ISO-2022-xx, KOI8-R). If a non-US-ASCII compatible character set
- is used, appropriate code-point from that character set MUST be
- chosen instead. Use of non-US-ASCII-compatible character sets is NOT
- recommended.
-
-3 Registration Information
-
- The Calendaring and Scheduling Core Object Specification is intended
- for use as a MIME content type. However, the implementation of the
- memo is in no way limited solely as a MIME content type.
-
-3.1 Content Type
-
- The following text is intended to register this memo as the MIME
- content type "text/calendar".
-
- To: ietf-types at uninett.no
-
- Subject: Registration of MIME content type text/calendar.
-
- MIME media type name: text
-
- MIME subtype name: calendar
-
-
-
-Dawson & Stenerson Standards Track [Page 8]
-
-RFC 2445 iCalendar November 1998
-
-
-3.2 Parameters
-
- Required parameters: none
-
- Optional parameters: charset, method, component and optinfo
-
- The "charset" parameter is defined in [RFC 2046] for other body
- parts. It is used to identify the default character set used within
- the body part.
-
- The "method" parameter is used to convey the iCalendar object method
- or transaction semantics for the calendaring and scheduling
- information. It also is an identifier for the restricted set of
- properties and values that the iCalendar object consists of. The
- parameter is to be used as a guide for applications interpreting the
- information contained within the body part. It SHOULD NOT be used to
- exclude or require particular pieces of information unless the
- identified method definition specifically calls for this behavior.
- Unless specifically forbidden by a particular method definition, a
- text/calendar content type can contain any set of properties
- permitted by the Calendaring and Scheduling Core Object
- Specification. The "method" parameter MUST be the same value as that
- specified in the "METHOD" component property in the iCalendar object.
- If one is present, the other MUST also be present.
-
- The value for the "method" parameter is defined as follows:
-
- method = 1*(ALPHA / DIGIT / "-")
- ; IANA registered iCalendar object method
-
- The "component" parameter conveys the type of iCalendar calendar
- component within the body part. If the iCalendar object contains more
- than one calendar component type, then multiple component parameters
- MUST be specified.
-
- The value for the "component" parameter is defined as follows:
-
- component = ("VEVENT" / "VTODO" / "VJOURNAL" / "VFREEBUSY"
- / "VTIMEZONE" / x-name / iana-token)
-
- The "optinfo" parameter conveys optional information about the
- iCalendar object within the body part. This parameter can only
- specify semantics already specified by the iCalendar object and that
- can be otherwise determined by parsing the body part. In addition,
- the optional information specified by this parameter MUST be
- consistent with that information specified by the iCalendar object.
- For example, it can be used to convey the "Attendee" response status
- to a meeting request. The parameter value consists of a string value.
-
-
-
-Dawson & Stenerson Standards Track [Page 9]
-
-RFC 2445 iCalendar November 1998
-
-
- The parameter can be specified multiple times.
-
- This parameter MAY only specify semantics already specified by the
- iCalendar object and that can be otherwise determined by parsing the
- body part.
-
- The value for the "optinfo" parameter is defined as follows:
-
- optinfo = infovalue / qinfovalue
-
- infovalue = iana-token / x-name
-
- qinfovalue = DQUOTE (infovalue) DQUOTE
-
-3.3 Content Header Fields
-
- Optional content header fields: Any header fields defined by [RFC
- 2045].
-
-3.4 Encoding Considerations
-
- This MIME content type can contain 8bit characters, so the use of
- quoted-printable or BASE64 MIME content-transfer-encodings might be
- necessary when iCalendar objects are transferred across protocols
- restricted to the 7bit repertoire. Note that a text valued property
- in the content entity can also have content encoding of special
- characters using a BACKSLASH character (US-ASCII decimal 92)
- escapement technique. This means that content values can end up
- encoded twice.
-
-3.5 Security Considerations
-
- SPOOFING - - In this memo, the "Organizer" is the only person
- authorized to make changes to an existing "VEVENT", "VTODO",
- "VJOURNAL" calendar component and redistribute the updates to the
- "Attendees". An iCalendar object that maliciously changes or cancels
- an existing "VEVENT", "VTODO" or "VJOURNAL" or "VFREEBUSY" calendar
- component might be constructed by someone other than the "Organizer"
- and sent to the "Attendees". In addition in this memo, other than the
- "Organizer", an "Attendee" of a "VEVENT", "VTODO", "VJOURNAL"
- calendar component is the only other person authorized to update any
- parameter associated with their "ATTENDEE" property and send it to
- the "Organizer". An iCalendar object that maliciously changes the
- "ATTENDEE" parameters can be constructed by someone other than the
- real "Attendee" and sent to the "Organizer".
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 10]
-
-RFC 2445 iCalendar November 1998
-
-
- PROCEDURAL ALARMS - - An iCalendar object can be created that
- contains a "VEVENT" and "VTODO" calendar component with "VALARM"
- calendar components. The "VALARM" calendar component can be of type
- PROCEDURE and can have an attachment containing some sort of
- executable program. Implementations that incorporate these types of
- alarms are subject to any virus or malicious attack that might occur
- as a result of executing the attachment.
-
- ATTACHMENTS - - An iCalendar object can include references to Uniform
- Resource Locators that can be programmed resources.
-
- Implementers and users of this memo should be aware of the network
- security implications of accepting and parsing such information. In
- addition, the security considerations observed by implementations of
- electronic mail systems should be followed for this memo.
-
-3.6 Interoperability Considerations
-
- This MIME content type is intended to define a common format for
- conveying calendaring and scheduling information between different
- systems. It is heavily based on the earlier [VCAL] industry
- specification.
-
-3.7 Applications Which Use This Media Type
-
- This content-type is designed for widespread use by Internet
- calendaring and scheduling applications. In addition, applications in
- the workflow and document management area might find this content-
- type applicable. The [ITIP] and [IMIP] Internet protocols directly
- use this content-type also. Future work on an Internet calendar
- access protocol will utilize this content-type too.
-
-3.8 Additional Information
-
- This memo defines this content-type.
-
-3.9 Magic Numbers
-
- None.
-
-3.10 File Extensions
-
- The file extension of "ics" is to be used to designate a file
- containing (an arbitrary set of) calendaring and scheduling
- information consistent with this MIME content type.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 11]
-
-RFC 2445 iCalendar November 1998
-
-
- The file extension of "ifb" is to be used to designate a file
- containing free or busy time information consistent with this MIME
- content type.
-
- Macintosh file type codes: The file type code of "iCal" is to be used
- in Apple MacIntosh operating system environments to designate a file
- containing calendaring and scheduling information consistent with
- this MIME media type.
-
- The file type code of "iFBf" is to be used in Apple MacIntosh
- operating system environments to designate a file containing free or
- busy time information consistent with this MIME media type.
-
-3.11 Contact for Further Information:
-
- Frank Dawson
- 6544 Battleford Drive
- Raleigh, NC 27613-3502
- 919-676-9515 (Telephone)
- 919-676-9564 (Data/Facsimile)
- Frank_Dawson at Lotus.com (Internet Mail)
-
- Derik Stenerson
- One Microsoft Way
- Redmond, WA 98052-6399
- 425-936-5522 (Telephone)
- 425-936-7329 (Facsimile)
- deriks at microsoft.com (Internet Mail)
-
-3.12 Intended Usage
-
- COMMON
-
-3.13 Authors/Change Controllers
-
- Frank Dawson
- 6544 Battleford Drive
- Raleigh, NC 27613-3502
- 919-676-9515 (Telephone)
- 919-676-9564 (Data/Facsimile)
- Frank_Dawson at Lotus.com (Internet Mail)
-
- Derik Stenerson
- One Microsoft Way
- Redmond, WA 98052-6399
- 425-936-5522 (Telephone)
- 425-936-7329 (Facsimile)
- deriks at microsoft.com (Internet Mail)
-
-
-
-Dawson & Stenerson Standards Track [Page 12]
-
-RFC 2445 iCalendar November 1998
-
-
-4 iCalendar Object Specification
-
- The following sections define the details of a Calendaring and
- Scheduling Core Object Specification. This information is intended to
- be an integral part of the MIME content type registration. In
- addition, this information can be used independent of such content
- registration. In particular, this memo has direct applicability for
- use as a calendaring and scheduling exchange format in file-, memory-
- or network-based transport mechanisms.
-
-4.1 Content Lines
-
- The iCalendar object is organized into individual lines of text,
- called content lines. Content lines are delimited by a line break,
- which is a CRLF sequence (US-ASCII decimal 13, followed by US-ASCII
- decimal 10).
-
- Lines of text SHOULD NOT be longer than 75 octets, excluding the line
- break. Long content lines SHOULD be split into a multiple line
- representations using a line "folding" technique. That is, a long
- line can be split between any two characters by inserting a CRLF
- immediately followed by a single linear white space character (i.e.,
- SPACE, US-ASCII decimal 32 or HTAB, US-ASCII decimal 9). Any sequence
- of CRLF followed immediately by a single linear white space character
- is ignored (i.e., removed) when processing the content type.
-
- For example the line:
-
- DESCRIPTION:This is a long description that exists on a long line.
-
- Can be represented as:
-
- DESCRIPTION:This is a lo
- ng description
- that exists on a long line.
-
- The process of moving from this folded multiple line representation
- to its single line representation is called "unfolding". Unfolding is
- accomplished by removing the CRLF character and the linear white
- space character that immediately follows.
-
- When parsing a content line, folded lines MUST first be unfolded
- according to the unfolding procedure described above. When generating
- a content line, lines longer than 75 octets SHOULD be folded
- according to the folding procedure described above.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 13]
-
-RFC 2445 iCalendar November 1998
-
-
- The content information associated with an iCalendar object is
- formatted using a syntax similar to that defined by [RFC 2425]. That
- is, the content information consists of CRLF-separated content lines.
-
- The following notation defines the lines of content in an iCalendar
- object:
-
- contentline = name *(";" param ) ":" value CRLF
- ; This ABNF is just a general definition for an initial parsing
- ; of the content line into its property name, parameter list,
- ; and value string
-
- ; When parsing a content line, folded lines MUST first
- ; be unfolded according to the unfolding procedure
- ; described above. When generating a content line, lines
- ; longer than 75 octets SHOULD be folded according to
- ; the folding procedure described above.
-
- name = x-name / iana-token
-
- iana-token = 1*(ALPHA / DIGIT / "-")
- ; iCalendar identifier registered with IANA
-
- x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
- ; Reservered for experimental use. Not intended for use in
- ; released products.
-
- vendorid = 3*(ALPHA / DIGIT) ;Vendor identification
-
- param = param-name "=" param-value
- *("," param-value)
- ; Each property defines the specific ABNF for the parameters
- ; allowed on the property. Refer to specific properties for
- ; precise parameter ABNF.
-
- param-name = iana-token / x-token
-
- param-value = paramtext / quoted-string
-
- paramtext = *SAFE-CHAR
-
- value = *VALUE-CHAR
-
- quoted-string = DQUOTE *QSAFE-CHAR DQUOTE
-
- NON-US-ASCII = %x80-F8
- ; Use restricted by charset parameter
- ; on outer MIME object (UTF-8 preferred)
-
-
-
-Dawson & Stenerson Standards Track [Page 14]
-
-RFC 2445 iCalendar November 1998
-
-
- QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
- ; Any character except CTLs and DQUOTE
-
- SAFE-CHAR = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E
- / NON-US-ASCII
- ; Any character except CTLs, DQUOTE, ";", ":", ","
-
- VALUE-CHAR = WSP / %x21-7E / NON-US-ASCII
- ; Any textual character
-
- CR = %x0D
- ; carriage return
-
- LF = %x0A
- ; line feed
-
- CRLF = CR LF
- ; Internet standard newline
-
- CTL = %x00-08 / %x0A-1F / %x7F
- ; Controls
-
- ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
-
- DIGIT = %x30-39
- ; 0-9
-
- DQUOTE = %x22
- ; Quotation Mark
-
- WSP = SPACE / HTAB
-
- SPACE = %x20
-
- HTAB = %x09
-
- The property value component of a content line has a format that is
- property specific. Refer to the section describing each property for
- a definition of this format.
-
- All names of properties, property parameters, enumerated property
- values and property parameter values are case-insensitive. However,
- all other property values are case-sensitive, unless otherwise
- stated.
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 15]
-
-RFC 2445 iCalendar November 1998
-
-
-4.1.1 List and Field Separators
-
- Some properties and parameters allow a list of values. Values in a
- list of values MUST be separated by a COMMA character (US-ASCII
- decimal 44). There is no significance to the order of values in a
- list. For those parameter values (such as those that specify URI
- values) that are specified in quoted-strings, the individual quoted-
- strings are separated by a COMMA character (US-ASCII decimal 44).
-
- Some property values are defined in terms of multiple parts. These
- structured property values MUST have their value parts separated by a
- SEMICOLON character (US-ASCII decimal 59).
-
- Some properties allow a list of parameters. Each property parameter
- in a list of property parameters MUST be separated by a SEMICOLON
- character (US-ASCII decimal 59).
-
- Property parameters with values containing a COLON, a SEMICOLON or a
- COMMA character MUST be placed in quoted text.
-
- For example, in the following properties a SEMICOLON is used to
- separate property parameters from each other, and a COMMA is used to
- separate property values in a value list.
-
- ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT:MAILTO:
- jsmith at host.com
-
- RDATE;VALUE=DATE:19970304,19970504,19970704,19970904
-
-4.1.2 Multiple Values
-
- Some properties defined in the iCalendar object can have multiple
- values. The general rule for encoding multi-valued items is to simply
- create a new content line for each value, including the property
- name. However, it should be noted that some properties support
- encoding multiple values in a single property by separating the
- values with a COMMA character (US-ASCII decimal 44). Individual
- property definitions should be consulted for determining whether a
- specific property allows multiple values and in which of these two
- forms.
-
-4.1.3 Binary Content
-
- Binary content information in an iCalendar object SHOULD be
- referenced using a URI within a property value. That is the binary
- content information SHOULD be placed in an external MIME entity that
- can be referenced by a URI from within the iCalendar object. In
- applications where this is not feasible, binary content information
-
-
-
-Dawson & Stenerson Standards Track [Page 16]
-
-RFC 2445 iCalendar November 1998
-
-
- can be included within an iCalendar object, but only after first
- encoding it into text using the "BASE64" encoding method defined in
- [RFC 2045]. Inline binary contact SHOULD only be used in applications
- whose special circumstances demand that an iCalendar object be
- expressed as a single entity. A property containing inline binary
- content information MUST specify the "ENCODING" property parameter.
- Binary content information placed external to the iCalendar object
- MUST be referenced by a uniform resource identifier (URI).
-
- The following example specifies an "ATTACH" property that references
- an attachment external to the iCalendar object with a URI reference:
-
- ATTACH:http://xyz.com/public/quarterly-report.doc
-
- The following example specifies an "ATTACH" property with inline
- binary encoded content information:
-
- ATTACH;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY:
- MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U
- EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE
- <...remainder of "BASE64" encoded binary data...>
-
-4.1.4 Character Set
-
- There is not a property parameter to declare the character set used
- in a property value. The default character set for an iCalendar
- object is UTF-8 as defined in [RFC 2279].
-
- The "charset" Content-Type parameter can be used in MIME transports
- to specify any other IANA registered character set.
-
-4.2 Property Parameters
-
- A property can have attributes associated with it. These "property
- parameters" contain meta-information about the property or the
- property value. Property parameters are provided to specify such
- information as the location of an alternate text representation for a
- property value, the language of a text property value, the data type
- of the property value and other attributes.
-
- Property parameter values that contain the COLON (US-ASCII decimal
- 58), SEMICOLON (US-ASCII decimal 59) or COMMA (US-ASCII decimal 44)
- character separators MUST be specified as quoted-string text values.
- Property parameter values MUST NOT contain the DOUBLE-QUOTE (US-ASCII
- decimal 22) character. The DOUBLE-QUOTE (US-ASCII decimal 22)
- character is used as a delimiter for parameter values that contain
- restricted characters or URI text. For example:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 17]
-
-RFC 2445 iCalendar November 1998
-
-
- DESCRIPTION;ALTREP="http://www.wiz.org":The Fall'98 Wild Wizards
- Conference - - Las Vegas, NV, USA
-
- Property parameter values that are not in quoted strings are case
- insensitive.
-
- The general property parameters defined by this memo are defined by
- the following notation:
-
- parameter = altrepparam ; Alternate text representation
- / cnparam ; Common name
- / cutypeparam ; Calendar user type
- / delfromparam ; Delegator
- / deltoparam ; Delegatee
- / dirparam ; Directory entry
- / encodingparam ; Inline encoding
- / fmttypeparam ; Format type
- / fbtypeparam ; Free/busy time type
- / languageparam ; Language for text
- / memberparam ; Group or list membership
- / partstatparam ; Participation status
- / rangeparam ; Recurrence identifier range
- / trigrelparam ; Alarm trigger relationship
- / reltypeparam ; Relationship type
- / roleparam ; Participation role
- / rsvpparam ; RSVP expectation
- / sentbyparam ; Sent by
- / tzidparam ; Reference to time zone object
- / valuetypeparam ; Property value data type
- / ianaparam
- ; Some other IANA registered iCalendar parameter.
- / xparam
- ; A non-standard, experimental parameter.
-
- ianaparam = iana-token "=" param-value *("," param-value)
-
- xparam =x-name "=" param-value *("," param-value)
-
-4.2.1 Alternate Text Representation
-
- Parameter Name: ALTREP
-
- Purpose: To specify an alternate text representation for the property
- value.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 18]
-
-RFC 2445 iCalendar November 1998
-
-
- altrepparam = "ALTREP" "=" DQUOTE uri DQUOTE
-
- Description: The parameter specifies a URI that points to an
- alternate representation for a textual property value. A property
- specifying this parameter MUST also include a value that reflects the
- default representation of the text value. The individual URI
- parameter values MUST each be specified in a quoted-string.
-
- Example:
-
- DESCRIPTION;ALTREP="CID:<part3.msg.970415T083000 at host.com>":Project
- XYZ Review Meeting will include the following agenda items: (a)
- Market Overview, (b) Finances, (c) Project Management
-
- The "ALTREP" property parameter value might point to a "text/html"
- content portion.
-
- Content-Type:text/html
- Content-Id:<part3.msg.970415T083000 at host.com>
-
- <html><body>
- <p><b>Project XYZ Review Meeting</b> will include the following
- agenda items:<ol><li>Market
- Overview</li><li>Finances</li><li>Project Management</li></ol></p>
- </body></html>
-
-4.2.2 Common Name
-
- Parameter Name: CN
-
- Purpose: To specify the common name to be associated with the
- calendar user specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- cnparam = "CN" "=" param-value
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter specifies the common name to be
- associated with the calendar user specified by the property. The
- parameter value is text. The parameter value can be used for display
- text to be associated with the calendar address specified by the
- property.
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 19]
-
-RFC 2445 iCalendar November 1998
-
-
- Example:
-
- ORGANIZER;CN="John Smith":MAILTO:jsmith at host.com
-
-4.2.3 Calendar User Type
-
- Parameter Name: CUTYPE
-
- Purpose: To specify the type of calendar user specified by the
- property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- cutypeparam = "CUTYPE" "="
- ("INDIVIDUAL" ; An individual
- / "GROUP" ; A group of individuals
- / "RESOURCE" ; A physical resource
- / "ROOM" ; A room resource
- / "UNKNOWN" ; Otherwise not known
- / x-name ; Experimental type
- / iana-token) ; Other IANA registered
- ; type
- ; Default is INDIVIDUAL
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter identifies the type of calendar
- user specified by the property. If not specified on a property that
- allows this parameter, the default is INDIVIDUAL.
-
- Example:
-
- ATTENDEE;CUTYPE=GROUP:MAILTO:ietf-calsch at imc.org
-
-4.2.4 Delegators
-
- Parameter Name: DELEGATED-FROM
-
- Purpose: To specify the calendar users that have delegated their
- participation to the calendar user specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- delfromparam = "DELEGATED-FROM" "=" DQUOTE cal-address DQUOTE
- *("," DQUOTE cal-address DQUOTE)
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 20]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. This parameter can be specified on a property
- that has a value type of calendar address. This parameter specifies
- those calendar uses that have delegated their participation in a
- group scheduled event or to-do to the calendar user specified by the
- property. The value MUST be a MAILTO URI as defined in [RFC 1738].
- The individual calendar address parameter values MUST each be
- specified in a quoted-string.
-
- Example:
-
- ATTENDEE;DELEGATED-FROM="MAILTO:jsmith at host.com":MAILTO:
- jdoe at host.com
-
-4.2.5 Delegatees
-
- Parameter Name: DELEGATED-TO
-
- Purpose: To specify the calendar users to whom the calendar user
- specified by the property has delegated participation.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- deltoparam = "DELEGATED-TO" "=" DQUOTE cal-address DQUOTE
- *("," DQUOTE cal-address DQUOTE)
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. This parameter specifies those calendar users
- whom have been delegated participation in a group scheduled event or
- to-do by the calendar user specified by the property. The value MUST
- be a MAILTO URI as defined in [RFC 1738]. The individual calendar
- address parameter values MUST each be specified in a quoted-string.
-
- Example:
-
- ATTENDEE;DELEGATED-TO="MAILTO:jdoe at host.com","MAILTO:jqpublic@
- host.com":MAILTO:jsmith at host.com
-
-4.2.6 Directory Entry Reference
-
- Parameter Name: DIR
-
- Purpose: To specify reference to a directory entry associated with
- the calendar user specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
-
-
-Dawson & Stenerson Standards Track [Page 21]
-
-RFC 2445 iCalendar November 1998
-
-
- dirparam = "DIR" "=" DQUOTE uri DQUOTE
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter specifies a reference to the
- directory entry associated with the calendar user specified by the
- property. The parameter value is a URI. The individual URI parameter
- values MUST each be specified in a quoted-string.
-
- Example:
-
- ORGANIZER;DIR="ldap://host.com:6666/o=eDABC%20Industries,c=3DUS??
- (cn=3DBJim%20Dolittle)":MAILTO:jimdo at host1.com
-
-4.2.7 Inline Encoding
-
- Parameter Name: ENCODING
-
- Purpose: To specify an alternate inline encoding for the property
- value.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- encodingparam = "ENCODING" "="
- ("8BIT"
- ; "8bit" text encoding is defined in [RFC 2045]
- / "BASE64"
- ; "BASE64" binary encoding format is defined in [RFC 2045]
- / iana-token
- ; Some other IANA registered iCalendar encoding type
- / x-name)
- ; A non-standard, experimental encoding type
-
- Description: The property parameter identifies the inline encoding
- used in a property value. The default encoding is "8BIT",
- corresponding to a property value consisting of text. The "BASE64"
- encoding type corresponds to a property value encoded using the
- "BASE64" encoding defined in [RFC 2045].
-
- If the value type parameter is ";VALUE=BINARY", then the inline
- encoding parameter MUST be specified with the value
- ";ENCODING=BASE64".
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 22]
-
-RFC 2445 iCalendar November 1998
-
-
- Example:
-
- ATTACH;FMTYPE=IMAGE/JPEG;ENCODING=BASE64;VALUE=BINARY:MIICajC
- CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA
- qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw
- <...remainder of "BASE64" encoded binary data...>
-
-4.2.8 Format Type
-
- Parameter Name: FMTTYPE
-
- Purpose: To specify the content type of a referenced object.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- fmttypeparam = "FMTTYPE" "=" iana-token
- ; A IANA registered content type
- / x-name
- ; A non-standard content type
-
- Description: This parameter can be specified on properties that are
- used to reference an object. The parameter specifies the content type
- of the referenced object. For example, on the "ATTACH" property, a
- FTP type URI value does not, by itself, necessarily convey the type
- of content associated with the resource. The parameter value MUST be
- the TEXT for either an IANA registered content type or a non-standard
- content type.
-
- Example:
-
- ATTACH;FMTTYPE=application/binary:ftp://domain.com/pub/docs/
- agenda.doc
-
-4.2.9 Free/Busy Time Type
-
- Parameter Name: FBTYPE
-
- Purpose: To specify the free or busy time type.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- fbtypeparam = "FBTYPE" "=" ("FREE" / "BUSY"
- / "BUSY-UNAVAILABLE" / "BUSY-TENTATIVE"
- / x-name
- ; Some experimental iCalendar data type.
- / iana-token)
-
-
-
-Dawson & Stenerson Standards Track [Page 23]
-
-RFC 2445 iCalendar November 1998
-
-
- ; Some other IANA registered iCalendar data type.
-
- Description: The parameter specifies the free or busy time type. The
- value FREE indicates that the time interval is free for scheduling.
- The value BUSY indicates that the time interval is busy because one
- or more events have been scheduled for that interval. The value
- BUSY-UNAVAILABLE indicates that the time interval is busy and that
- the interval can not be scheduled. The value BUSY-TENTATIVE indicates
- that the time interval is busy because one or more events have been
- tentatively scheduled for that interval. If not specified on a
- property that allows this parameter, the default is BUSY.
-
- Example: The following is an example of this parameter on a FREEBUSY
- property.
-
- FREEBUSY;FBTYPE=BUSY:19980415T133000Z/19980415T170000Z
-
-4.2.10 Language
-
- Parameter Name: LANGUAGE
-
- Purpose: To specify the language for text values in a property or
- property parameter.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- languageparam = "LANGUAGE" "=" language
-
- language = <Text identifying a language, as defined in [RFC 1766]>
-
- Description: This parameter can be specified on properties with a
- text value type. The parameter identifies the language of the text in
- the property or property parameter value. The value of the "language"
- property parameter is that defined in [RFC 1766].
-
- For transport in a MIME entity, the Content-Language header field can
- be used to set the default language for the entire body part.
- Otherwise, no default language is assumed.
-
- Example:
-
- SUMMARY;LANGUAGE=us-EN:Company Holiday Party
-
- LOCATION;LANGUAGE=en:Germany
- LOCATION;LANGUAGE=no:Tyskland
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 24]
-
-RFC 2445 iCalendar November 1998
-
-
- The following example makes use of the Quoted-Printable encoding in
- order to represent non-ASCII characters.
-
- LOCATION;LANGUAGE=da:K=F8benhavn
- LOCATION;LANGUAGE=en:Copenhagen
-
-4.2.11 Group or List Membership
-
- Parameter Name: MEMBER
-
- Purpose: To specify the group or list membership of the calendar user
- specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- memberparam = "MEMBER" "=" DQUOTE cal-address DQUOTE
- *("," DQUOTE cal-address DQUOTE)
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter identifies the groups or list
- membership for the calendar user specified by the property. The
- parameter value either a single calendar address in a quoted-string
- or a COMMA character (US-ASCII decimal 44) list of calendar
- addresses, each in a quoted-string. The individual calendar address
- parameter values MUST each be specified in a quoted-string.
-
- Example:
-
- ATTENDEE;MEMBER="MAILTO:ietf-calsch at imc.org":MAILTO:jsmith at host.com
-
- ATTENDEE;MEMBER="MAILTO:projectA at host.com","MAILTO:projectB at host.
- com":MAILTO:janedoe at host.com
-
-4.2.12 Participation Status
-
- Parameter Name: PARTSTAT
-
- Purpose: To specify the participation status for the calendar user
- specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- partstatparam = "PARTSTAT" "="
- ("NEEDS-ACTION" ; Event needs action
- / "ACCEPTED" ; Event accepted
- / "DECLINED" ; Event declined
-
-
-
-Dawson & Stenerson Standards Track [Page 25]
-
-RFC 2445 iCalendar November 1998
-
-
- / "TENTATIVE" ; Event tentatively
- ; accepted
- / "DELEGATED" ; Event delegated
- / x-name ; Experimental status
- / iana-token) ; Other IANA registered
- ; status
- ; These are the participation statuses for a "VEVENT". Default is
- ; NEEDS-ACTION
- partstatparam /= "PARTSTAT" "="
- ("NEEDS-ACTION" ; To-do needs action
- / "ACCEPTED" ; To-do accepted
- / "DECLINED" ; To-do declined
- / "TENTATIVE" ; To-do tentatively
- ; accepted
- / "DELEGATED" ; To-do delegated
- / "COMPLETED" ; To-do completed.
- ; COMPLETED property has
- ;date/time completed.
- / "IN-PROCESS" ; To-do in process of
- ; being completed
- / x-name ; Experimental status
- / iana-token) ; Other IANA registered
- ; status
- ; These are the participation statuses for a "VTODO". Default is
- ; NEEDS-ACTION
-
- partstatparam /= "PARTSTAT" "="
- ("NEEDS-ACTION" ; Journal needs action
- / "ACCEPTED" ; Journal accepted
- / "DECLINED" ; Journal declined
- / x-name ; Experimental status
- / iana-token) ; Other IANA registered
- ; status
- ; These are the participation statuses for a "VJOURNAL". Default is
- ; NEEDS-ACTION
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter identifies the participation
- status for the calendar user specified by the property value. The
- parameter values differ depending on whether they are associated with
- a group scheduled "VEVENT", "VTODO" or "VJOURNAL". The values MUST
- match one of the values allowed for the given calendar component. If
- not specified on a property that allows this parameter, the default
- value is NEEDS-ACTION.
-
- Example:
-
- ATTENDEE;PARTSTAT=DECLINED:MAILTO:jsmith at host.com
-
-
-
-Dawson & Stenerson Standards Track [Page 26]
-
-RFC 2445 iCalendar November 1998
-
-
-4.2.13 Recurrence Identifier Range
-
- Parameter Name: RANGE
-
- Purpose: To specify the effective range of recurrence instances from
- the instance specified by the recurrence identifier specified by the
- property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- rangeparam = "RANGE" "=" ("THISANDPRIOR"
- ; To specify all instances prior to the recurrence identifier
- / "THISANDFUTURE")
- ; To specify the instance specified by the recurrence identifier
- ; and all subsequent recurrence instances
-
- Description: The parameter can be specified on a property that
- specifies a recurrence identifier. The parameter specifies the
- effective range of recurrence instances that is specified by the
- property. The effective range is from the recurrence identified
- specified by the property. If this parameter is not specified an
- allowed property, then the default range is the single instance
- specified by the recurrence identifier value of the property. The
- parameter value can be "THISANDPRIOR" to indicate a range defined by
- the recurrence identified value of the property and all prior
- instances. The parameter value can also be "THISANDFUTURE" to
- indicate a range defined by the recurrence identifier and all
- subsequent instances.
-
- Example:
-
- RECURRENCE-ID;RANGE=THISANDPRIOR:19980401T133000Z
-
-4.2.14 Alarm Trigger Relationship
-
- Parameter Name: RELATED
-
- Purpose: To specify the relationship of the alarm trigger with
- respect to the start or end of the calendar component.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- trigrelparam = "RELATED" "="
- ("START" ; Trigger off of start
- / "END") ; Trigger off of end
-
-
-
-
-Dawson & Stenerson Standards Track [Page 27]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: The parameter can be specified on properties that
- specify an alarm trigger with a DURATION value type. The parameter
- specifies whether the alarm will trigger relative to the start or end
- of the calendar component. The parameter value START will set the
- alarm to trigger off the start of the calendar component; the
- parameter value END will set the alarm to trigger off the end of the
- calendar component. If the parameter is not specified on an allowable
- property, then the default is START.
-
- Example:
-
- TRIGGER;RELATED=END:PT5M
-
-4.2.15 Relationship Type
-
- Parameter Name: RELTYPE
-
- Purpose: To specify the type of hierarchical relationship associated
- with the calendar component specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- reltypeparam = "RELTYPE" "="
- ("PARENT" ; Parent relationship. Default.
- / "CHILD" ; Child relationship
- / "SIBLING ; Sibling relationship
- / iana-token ; Some other IANA registered
- ; iCalendar relationship type
- / x-name) ; A non-standard, experimental
- ; relationship type
-
- Description: This parameter can be specified on a property that
- references another related calendar. The parameter specifies the
- hierarchical relationship type of the calendar component referenced
- by the property. The parameter value can be PARENT, to indicate that
- the referenced calendar component is a superior of calendar
- component; CHILD to indicate that the referenced calendar component
- is a subordinate of the calendar component; SIBLING to indicate that
- the referenced calendar component is a peer of the calendar
- component. If this parameter is not specified on an allowable
- property, the default relationship type is PARENT.
-
- Example:
-
- RELATED-TO;RELTYPE=SIBLING:<19960401-080045-4000F192713 at host.com>
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 28]
-
-RFC 2445 iCalendar November 1998
-
-
-4.2.16 Participation Role
-
- Parameter Name: ROLE
-
- Purpose: To specify the participation role for the calendar user
- specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- roleparam = "ROLE" "="
- ("CHAIR" ; Indicates chair of the
- ; calendar entity
- / "REQ-PARTICIPANT" ; Indicates a participant whose
- ; participation is required
- / "OPT-PARTICIPANT" ; Indicates a participant whose
- ; participation is optional
- / "NON-PARTICIPANT" ; Indicates a participant who is
- ; copied for information
- ; purposes only
- / x-name ; Experimental role
- / iana-token) ; Other IANA role
- ; Default is REQ-PARTICIPANT
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter specifies the participation
- role for the calendar user specified by the property in the group
- schedule calendar component. If not specified on a property that
- allows this parameter, the default value is REQ-PARTICIPANT.
-
- Example:
-
- ATTENDEE;ROLE=CHAIR:MAILTO:mrbig at host.com
-
-4.2.17 RSVP Expectation
-
- Parameter Name: RSVP
-
- Purpose: To specify whether there is an expectation of a favor of a
- reply from the calendar user specified by the property value.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- rsvpparam = "RSVP" "=" ("TRUE" / "FALSE")
- ; Default is FALSE
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 29]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter identifies the expectation of a
- reply from the calendar user specified by the property value. This
- parameter is used by the "Organizer" to request a participation
- status reply from an "Attendee" of a group scheduled event or to-do.
- If not specified on a property that allows this parameter, the
- default value is FALSE.
-
- Example:
-
- ATTENDEE;RSVP=TRUE:MAILTO:jsmith at host.com
-
-4.2.18 Sent By
-
- Parameter Name: SENT-BY
-
- Purpose: To specify the calendar user that is acting on behalf of the
- calendar user specified by the property.
-
- Format Definition: The property parameter is defined by the following
- notation:
-
- sentbyparam = "SENT-BY" "=" DQUOTE cal-address DQUOTE
-
- Description: This parameter can be specified on properties with a
- CAL-ADDRESS value type. The parameter specifies the calendar user
- that is acting on behalf of the calendar user specified by the
- property. The parameter value MUST be a MAILTO URI as defined in [RFC
- 1738]. The individual calendar address parameter values MUST each be
- specified in a quoted-string.
-
- Example:
-
- ORGANIZER;SENT-BY:"MAILTO:sray at host.com":MAILTO:jsmith at host.com
-
-4.2.19 Time Zone Identifier
-
- Parameter Name: TZID
-
- Purpose: To specify the identifier for the time zone definition for a
- time component in the property value.
-
- Format Definition: This property parameter is defined by the
- following notation:
-
- tzidparam = "TZID" "=" [tzidprefix] paramtext CRLF
-
- tzidprefix = "/"
-
-
-
-Dawson & Stenerson Standards Track [Page 30]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: The parameter MUST be specified on the "DTSTART",
- "DTEND", "DUE", "EXDATE" and "RDATE" properties when either a DATE-
- TIME or TIME value type is specified and when the value is not either
- a UTC or a "floating" time. Refer to the DATE-TIME or TIME value type
- definition for a description of UTC and "floating time" formats. This
- property parameter specifies a text value which uniquely identifies
- the "VTIMEZONE" calendar component to be used when evaluating the
- time portion of the property. The value of the TZID property
- parameter will be equal to the value of the TZID property for the
- matching time zone definition. An individual "VTIMEZONE" calendar
- component MUST be specified for each unique "TZID" parameter value
- specified in the iCalendar object.
-
- The parameter MUST be specified on properties with a DATE-TIME value
- if the DATE-TIME is not either a UTC or a "floating" time.
-
- The presence of the SOLIDUS character (US-ASCII decimal 47) as a
- prefix, indicates that this TZID represents a unique ID in a globally
- defined time zone registry (when such registry is defined).
-
- Note: This document does not define a naming convention for time
- zone identifiers. Implementers may want to use the naming
- conventions defined in existing time zone specifications such as
- the public-domain Olson database [TZ]. The specification of
- globally unique time zone identifiers is not addressed by this
- document and is left for future study.
-
- The following are examples of this property parameter:
-
- DTSTART;TZID=US-Eastern:19980119T020000
-
- DTEND;TZID=US-Eastern:19980119T030000
-
- The TZID property parameter MUST NOT be applied to DATE-TIME or TIME
- properties whose time values are specified in UTC.
-
- The use of local time in a DATE-TIME or TIME value without the TZID
- property parameter is to be interpreted as a local time value,
- regardless of the existence of "VTIMEZONE" calendar components in the
- iCalendar object.
-
- For more information see the sections on the data types DATE-TIME and
- TIME.
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 31]
-
-RFC 2445 iCalendar November 1998
-
-
-4.2.20 Value Data Types
-
- Parameter Name: VALUE
-
- Purpose: To explicitly specify the data type format for a property
- value.
-
- Format Definition: The "VALUE" property parameter is defined by the
- following notation:
-
- valuetypeparam = "VALUE" "=" valuetype
-
- valuetype = ("BINARY"
- / "BOOLEAN"
- / "CAL-ADDRESS"
- / "DATE"
- / "DATE-TIME"
- / "DURATION"
- / "FLOAT"
- / "INTEGER"
- / "PERIOD"
- / "RECUR"
- / "TEXT"
- / "TIME"
- / "URI"
- / "UTC-OFFSET"
- / x-name
- ; Some experimental iCalendar data type.
- / iana-token)
- ; Some other IANA registered iCalendar data type.
-
- Description: The parameter specifies the data type and format of the
- property value. The property values MUST be of a single value type.
- For example, a "RDATE" property cannot have a combination of DATE-
- TIME and TIME value types.
-
- If the property's value is the default value type, then this
- parameter need not be specified. However, if the property's default
- value type is overridden by some other allowable value type, then
- this parameter MUST be specified.
-
-4.3 Property Value Data Types
-
- The properties in an iCalendar object are strongly typed. The
- definition of each property restricts the value to be one of the
- value data types, or simply value types, defined in this section. The
- value type for a property will either be specified implicitly as the
- default value type or will be explicitly specified with the "VALUE"
-
-
-
-Dawson & Stenerson Standards Track [Page 32]
-
-RFC 2445 iCalendar November 1998
-
-
- parameter. If the value type of a property is one of the alternate
- valid types, then it MUST be explicitly specified with the "VALUE"
- parameter.
-
-4.3.1 Binary
-
- Value Name: BINARY
-
- Purpose: This value type is used to identify properties that contain
- a character encoding of inline binary data. For example, an inline
- attachment of an object code might be included in an iCalendar
- object.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- binary = *(4b-char) [b-end]
- ; A "BASE64" encoded character string, as defined by [RFC 2045].
-
- b-end = (2b-char "==") / (3b-char "=")
-
- b-char = ALPHA / DIGIT / "+" / "/"
-
- Description: Property values with this value type MUST also include
- the inline encoding parameter sequence of ";ENCODING=BASE64". That
- is, all inline binary data MUST first be character encoded using the
- "BASE64" encoding method defined in [RFC 2045]. No additional content
- value encoding (i.e., BACKSLASH character encoding) is defined for
- this value type.
-
- Example: The following is an abridged example of a "BASE64" encoded
- binary value data.
-
- ATTACH;VALUE=BINARY;ENCODING=BASE64:MIICajCCAdOgAwIBAgICBEUwDQY
- JKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlI
- ENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRwwGgYDVQQLExNJbmZv
- <...remainder of "BASE64" encoded binary data...>
-
-4.3.2 Boolean
-
- Value Name: BOOLEAN
-
- Purpose: This value type is used to identify properties that contain
- either a "TRUE" or "FALSE" Boolean value.
-
- Formal Definition: The value type is defined by the following
- notation:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 33]
-
-RFC 2445 iCalendar November 1998
-
-
- boolean = "TRUE" / "FALSE"
-
- Description: These values are case insensitive text. No additional
- content value encoding (i.e., BACKSLASH character encoding) is
- defined for this value type.
-
- Example: The following is an example of a hypothetical property that
- has a BOOLEAN value type:
-
- GIBBERISH:TRUE
-
-4.3.3 Calendar User Address
-
- Value Name: CAL-ADDRESS
-
- Purpose: This value type is used to identify properties that contain
- a calendar user address.
-
- Formal Definition: The value type is as defined by the following
- notation:
-
- cal-address = uri
-
- Description: The value is a URI as defined by [RFC 1738] or any other
- IANA registered form for a URI. When used to address an Internet
- email transport address for a calendar user, the value MUST be a
- MAILTO URI, as defined by [RFC 1738]. No additional content value
- encoding (i.e., BACKSLASH character encoding) is defined for this
- value type.
-
- Example:
-
- ATTENDEE:MAILTO:jane_doe at host.com
-
-4.3.4 Date
-
- Value Name: DATE
-
- Purpose: This value type is used to identify values that contain a
- calendar date.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- date = date-value
-
- date-value = date-fullyear date-month date-mday
- date-fullyear = 4DIGIT
-
-
-
-Dawson & Stenerson Standards Track [Page 34]
-
-RFC 2445 iCalendar November 1998
-
-
- date-month = 2DIGIT ;01-12
- date-mday = 2DIGIT ;01-28, 01-29, 01-30, 01-31
- ;based on month/year
-
- Description: If the property permits, multiple "date" values are
- specified as a COMMA character (US-ASCII decimal 44) separated list
- of values. The format for the value type is expressed as the [ISO
- 8601] complete representation, basic format for a calendar date. The
- textual format specifies a four-digit year, two-digit month, and
- two-digit day of the month. There are no separator characters between
- the year, month and day component text.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example: The following represents July 14, 1997:
-
- 19970714
-
-4.3.5 Date-Time
-
- Value Name: DATE-TIME
-
- Purpose: This value type is used to identify values that specify a
- precise calendar date and time of day.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- date-time = date "T" time ;As specified in the date and time
- ;value definitions
-
- Description: If the property permits, multiple "date-time" values are
- specified as a COMMA character (US-ASCII decimal 44) separated list
- of values. No additional content value encoding (i.e., BACKSLASH
- character encoding) is defined for this value type.
-
- The "DATE-TIME" data type is used to identify values that contain a
- precise calendar date and time of day. The format is based on the
- [ISO 8601] complete representation, basic format for a calendar date
- and time of day. The text format is a concatenation of the "date",
- followed by the LATIN CAPITAL LETTER T character (US-ASCII decimal
- 84) time designator, followed by the "time" format.
-
- The "DATE-TIME" data type expresses time values in three forms:
-
- The form of date and time with UTC offset MUST NOT be used. For
- example, the following is not valid for a date-time value:
-
-
-
-Dawson & Stenerson Standards Track [Page 35]
-
-RFC 2445 iCalendar November 1998
-
-
- DTSTART:19980119T230000-0800 ;Invalid time format
-
- FORM #1: DATE WITH LOCAL TIME
-
- The date with local time form is simply a date-time value that does
- not contain the UTC designator nor does it reference a time zone. For
- example, the following represents Janurary 18, 1998, at 11 PM:
-
- DTSTART:19980118T230000
-
- Date-time values of this type are said to be "floating" and are not
- bound to any time zone in particular. They are used to represent the
- same hour, minute, and second value regardless of which time zone is
- currently being observed. For example, an event can be defined that
- indicates that an individual will be busy from 11:00 AM to 1:00 PM
- every day, no matter which time zone the person is in. In these
- cases, a local time can be specified. The recipient of an iCalendar
- object with a property value consisting of a local time, without any
- relative time zone information, SHOULD interpret the value as being
- fixed to whatever time zone the ATTENDEE is in at any given moment.
- This means that two ATTENDEEs, in different time zones, receiving the
- same event definition as a floating time, may be participating in the
- event at different actual times. Floating time SHOULD only be used
- where that is the reasonable behavior.
-
- In most cases, a fixed time is desired. To properly communicate a
- fixed time in a property value, either UTC time or local time with
- time zone reference MUST be specified.
-
- The use of local time in a DATE-TIME value without the TZID property
- parameter is to be interpreted as floating time, regardless of the
- existence of "VTIMEZONE" calendar components in the iCalendar object.
-
- FORM #2: DATE WITH UTC TIME
-
- The date with UTC time, or absolute time, is identified by a LATIN
- CAPITAL LETTER Z suffix character (US-ASCII decimal 90), the UTC
- designator, appended to the time value. For example, the following
- represents January 19, 1998, at 0700 UTC:
-
- DTSTART:19980119T070000Z
-
- The TZID property parameter MUST NOT be applied to DATE-TIME
- properties whose time values are specified in UTC.
-
- FORM #3: DATE WITH LOCAL TIME AND TIME ZONE REFERENCE
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 36]
-
-RFC 2445 iCalendar November 1998
-
-
- The date and local time with reference to time zone information is
- identified by the use the TZID property parameter to reference the
- appropriate time zone definition. TZID is discussed in detail in the
- section on Time Zone. For example, the following represents 2 AM in
- New York on Janurary 19, 1998:
-
- DTSTART;TZID=US-Eastern:19980119T020000
-
- Example: The following represents July 14, 1997, at 1:30 PM in New
- York City in each of the three time formats, using the "DTSTART"
- property.
-
- DTSTART:19970714T133000 ;Local time
- DTSTART:19970714T173000Z ;UTC time
- DTSTART;TZID=US-Eastern:19970714T133000 ;Local time and time
- ; zone reference
-
- A time value MUST ONLY specify 60 seconds when specifying the
- periodic "leap second" in the time value. For example:
-
- COMPLETED:19970630T235960Z
-
-4.3.6 Duration
-
- Value Name: DURATION
-
- Purpose: This value type is used to identify properties that contain
- a duration of time.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- dur-value = (["+"] / "-") "P" (dur-date / dur-time / dur-week)
-
- dur-date = dur-day [dur-time]
- dur-time = "T" (dur-hour / dur-minute / dur-second)
- dur-week = 1*DIGIT "W"
- dur-hour = 1*DIGIT "H" [dur-minute]
- dur-minute = 1*DIGIT "M" [dur-second]
- dur-second = 1*DIGIT "S"
- dur-day = 1*DIGIT "D"
-
- Description: If the property permits, multiple "duration" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values. The format is expressed as the [ISO 8601] basic format for
- the duration of time. The format can represent durations in terms of
- weeks, days, hours, minutes, and seconds.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 37]
-
-RFC 2445 iCalendar November 1998
-
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) are defined for this value type.
-
- Example: A duration of 15 days, 5 hours and 20 seconds would be:
-
- P15DT5H0M20S
-
- A duration of 7 weeks would be:
-
- P7W
-
-4.3.7 Float
-
- Value Name: FLOAT
-
- Purpose: This value type is used to identify properties that contain
- a real number value.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- float = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]
-
- Description: If the property permits, multiple "float" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example:
-
- 1000000.0000001
- 1.333
- -3.14
-
-4.3.8 Integer
-
- Value Name:INTEGER
-
- Purpose: This value type is used to identify properties that contain
- a signed integer value.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- integer = (["+"] / "-") 1*DIGIT
-
-
-
-
-Dawson & Stenerson Standards Track [Page 38]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: If the property permits, multiple "integer" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values. The valid range for "integer" is -2147483648 to
- 2147483647. If the sign is not specified, then the value is assumed
- to be positive.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example:
-
- 1234567890
- -1234567890
- +1234567890
- 432109876
-
-4.3.9 Period of Time
-
- Value Name: PERIOD
-
- Purpose: This value type is used to identify values that contain a
- precise period of time.
-
- Formal Definition: The data type is defined by the following
- notation:
-
- period = period-explicit / period-start
-
- period-explicit = date-time "/" date-time
- ; [ISO 8601] complete representation basic format for a period of
- ; time consisting of a start and end. The start MUST be before the
- ; end.
-
- period-start = date-time "/" dur-value
- ; [ISO 8601] complete representation basic format for a period of
- ; time consisting of a start and positive duration of time.
-
- Description: If the property permits, multiple "period" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values. There are two forms of a period of time. First, a period
- of time is identified by its start and its end. This format is
- expressed as the [ISO 8601] complete representation, basic format for
- "DATE-TIME" start of the period, followed by a SOLIDUS character
- (US-ASCII decimal 47), followed by the "DATE-TIME" of the end of the
- period. The start of the period MUST be before the end of the period.
- Second, a period of time can also be defined by a start and a
- positive duration of time. The format is expressed as the [ISO 8601]
- complete representation, basic format for the "DATE-TIME" start of
-
-
-
-Dawson & Stenerson Standards Track [Page 39]
-
-RFC 2445 iCalendar November 1998
-
-
- the period, followed by a SOLIDUS character (US-ASCII decimal 47),
- followed by the [ISO 8601] basic format for "DURATION" of the period.
-
- Example: The period starting at 18:00:00 UTC, on January 1, 1997 and
- ending at 07:00:00 UTC on January 2, 1997 would be:
-
- 19970101T180000Z/19970102T070000Z
-
- The period start at 18:00:00 on January 1, 1997 and lasting 5 hours
- and 30 minutes would be:
-
- 19970101T180000Z/PT5H30M
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
-4.3.10 Recurrence Rule
-
- Value Name: RECUR
-
- Purpose: This value type is used to identify properties that contain
- a recurrence rule specification.
-
- Formal Definition: The value type is defined by the following
- notation:
-
- recur = "FREQ"=freq *(
-
- ; either UNTIL or COUNT may appear in a 'recur',
- ; but UNTIL and COUNT MUST NOT occur in the same 'recur'
-
- ( ";" "UNTIL" "=" enddate ) /
- ( ";" "COUNT" "=" 1*DIGIT ) /
-
- ; the rest of these keywords are optional,
- ; but MUST NOT occur more than once
-
- ( ";" "INTERVAL" "=" 1*DIGIT ) /
- ( ";" "BYSECOND" "=" byseclist ) /
- ( ";" "BYMINUTE" "=" byminlist ) /
- ( ";" "BYHOUR" "=" byhrlist ) /
- ( ";" "BYDAY" "=" bywdaylist ) /
- ( ";" "BYMONTHDAY" "=" bymodaylist ) /
- ( ";" "BYYEARDAY" "=" byyrdaylist ) /
- ( ";" "BYWEEKNO" "=" bywknolist ) /
- ( ";" "BYMONTH" "=" bymolist ) /
- ( ";" "BYSETPOS" "=" bysplist ) /
- ( ";" "WKST" "=" weekday ) /
-
-
-
-Dawson & Stenerson Standards Track [Page 40]
-
-RFC 2445 iCalendar November 1998
-
-
- ( ";" x-name "=" text )
- )
-
- freq = "SECONDLY" / "MINUTELY" / "HOURLY" / "DAILY"
- / "WEEKLY" / "MONTHLY" / "YEARLY"
-
- enddate = date
- enddate =/ date-time ;An UTC value
-
- byseclist = seconds / ( seconds *("," seconds) )
-
- seconds = 1DIGIT / 2DIGIT ;0 to 59
-
- byminlist = minutes / ( minutes *("," minutes) )
-
- minutes = 1DIGIT / 2DIGIT ;0 to 59
-
- byhrlist = hour / ( hour *("," hour) )
-
- hour = 1DIGIT / 2DIGIT ;0 to 23
-
- bywdaylist = weekdaynum / ( weekdaynum *("," weekdaynum) )
-
- weekdaynum = [([plus] ordwk / minus ordwk)] weekday
-
- plus = "+"
-
- minus = "-"
-
- ordwk = 1DIGIT / 2DIGIT ;1 to 53
-
- weekday = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
- ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
- ;FRIDAY, SATURDAY and SUNDAY days of the week.
-
- bymodaylist = monthdaynum / ( monthdaynum *("," monthdaynum) )
-
- monthdaynum = ([plus] ordmoday) / (minus ordmoday)
-
- ordmoday = 1DIGIT / 2DIGIT ;1 to 31
-
- byyrdaylist = yeardaynum / ( yeardaynum *("," yeardaynum) )
-
- yeardaynum = ([plus] ordyrday) / (minus ordyrday)
-
- ordyrday = 1DIGIT / 2DIGIT / 3DIGIT ;1 to 366
-
- bywknolist = weeknum / ( weeknum *("," weeknum) )
-
-
-
-Dawson & Stenerson Standards Track [Page 41]
-
-RFC 2445 iCalendar November 1998
-
-
- weeknum = ([plus] ordwk) / (minus ordwk)
-
- bymolist = monthnum / ( monthnum *("," monthnum) )
-
- monthnum = 1DIGIT / 2DIGIT ;1 to 12
-
- bysplist = setposday / ( setposday *("," setposday) )
-
- setposday = yeardaynum
-
- Description: If the property permits, multiple "recur" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values. The value type is a structured value consisting of a list
- of one or more recurrence grammar parts. Each rule part is defined by
- a NAME=VALUE pair. The rule parts are separated from each other by
- the SEMICOLON character (US-ASCII decimal 59). The rule parts are not
- ordered in any particular sequence. Individual rule parts MUST only
- be specified once.
-
- The FREQ rule part identifies the type of recurrence rule. This rule
- part MUST be specified in the recurrence rule. Valid values include
- SECONDLY, to specify repeating events based on an interval of a
- second or more; MINUTELY, to specify repeating events based on an
- interval of a minute or more; HOURLY, to specify repeating events
- based on an interval of an hour or more; DAILY, to specify repeating
- events based on an interval of a day or more; WEEKLY, to specify
- repeating events based on an interval of a week or more; MONTHLY, to
- specify repeating events based on an interval of a month or more; and
- YEARLY, to specify repeating events based on an interval of a year or
- more.
-
- The INTERVAL rule part contains a positive integer representing how
- often the recurrence rule repeats. The default value is "1", meaning
- every second for a SECONDLY rule, or every minute for a MINUTELY
- rule, every hour for an HOURLY rule, every day for a DAILY rule,
- every week for a WEEKLY rule, every month for a MONTHLY rule and
- every year for a YEARLY rule.
-
- The UNTIL rule part defines a date-time value which bounds the
- recurrence rule in an inclusive manner. If the value specified by
- UNTIL is synchronized with the specified recurrence, this date or
- date-time becomes the last instance of the recurrence. If specified
- as a date-time value, then it MUST be specified in an UTC time
- format. If not present, and the COUNT rule part is also not present,
- the RRULE is considered to repeat forever.
-
- The COUNT rule part defines the number of occurrences at which to
- range-bound the recurrence. The "DTSTART" property value, if
-
-
-
-Dawson & Stenerson Standards Track [Page 42]
-
-RFC 2445 iCalendar November 1998
-
-
- specified, counts as the first occurrence.
-
- The BYSECOND rule part specifies a COMMA character (US-ASCII decimal
- 44) separated list of seconds within a minute. Valid values are 0 to
- 59. The BYMINUTE rule part specifies a COMMA character (US-ASCII
- decimal 44) separated list of minutes within an hour. Valid values
- are 0 to 59. The BYHOUR rule part specifies a COMMA character (US-
- ASCII decimal 44) separated list of hours of the day. Valid values
- are 0 to 23.
-
- The BYDAY rule part specifies a COMMA character (US-ASCII decimal 44)
- separated list of days of the week; MO indicates Monday; TU indicates
- Tuesday; WE indicates Wednesday; TH indicates Thursday; FR indicates
- Friday; SA indicates Saturday; SU indicates Sunday.
-
- Each BYDAY value can also be preceded by a positive (+n) or negative
- (-n) integer. If present, this indicates the nth occurrence of the
- specific day within the MONTHLY or YEARLY RRULE. For example, within
- a MONTHLY rule, +1MO (or simply 1MO) represents the first Monday
- within the month, whereas -1MO represents the last Monday of the
- month. If an integer modifier is not present, it means all days of
- this type within the specified frequency. For example, within a
- MONTHLY rule, MO represents all Mondays within the month.
-
- The BYMONTHDAY rule part specifies a COMMA character (ASCII decimal
- 44) separated list of days of the month. Valid values are 1 to 31 or
- -31 to -1. For example, -10 represents the tenth to the last day of
- the month.
-
- The BYYEARDAY rule part specifies a COMMA character (US-ASCII decimal
- 44) separated list of days of the year. Valid values are 1 to 366 or
- -366 to -1. For example, -1 represents the last day of the year
- (December 31st) and -306 represents the 306th to the last day of the
- year (March 1st).
-
- The BYWEEKNO rule part specifies a COMMA character (US-ASCII decimal
- 44) separated list of ordinals specifying weeks of the year. Valid
- values are 1 to 53 or -53 to -1. This corresponds to weeks according
- to week numbering as defined in [ISO 8601]. A week is defined as a
- seven day period, starting on the day of the week defined to be the
- week start (see WKST). Week number one of the calendar year is the
- first week which contains at least four (4) days in that calendar
- year. This rule part is only valid for YEARLY rules. For example, 3
- represents the third week of the year.
-
- Note: Assuming a Monday week start, week 53 can only occur when
- Thursday is January 1 or if it is a leap year and Wednesday is
- January 1.
-
-
-
-Dawson & Stenerson Standards Track [Page 43]
-
-RFC 2445 iCalendar November 1998
-
-
- The BYMONTH rule part specifies a COMMA character (US-ASCII decimal
- 44) separated list of months of the year. Valid values are 1 to 12.
-
- The WKST rule part specifies the day on which the workweek starts.
- Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant
- when a WEEKLY RRULE has an interval greater than 1, and a BYDAY rule
- part is specified. This is also significant when in a YEARLY RRULE
- when a BYWEEKNO rule part is specified. The default value is MO.
-
- The BYSETPOS rule part specifies a COMMA character (US-ASCII decimal
- 44) separated list of values which corresponds to the nth occurrence
- within the set of events specified by the rule. Valid values are 1 to
- 366 or -366 to -1. It MUST only be used in conjunction with another
- BYxxx rule part. For example "the last work day of the month" could
- be represented as:
-
- RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-1
-
- Each BYSETPOS value can include a positive (+n) or negative (-n)
- integer. If present, this indicates the nth occurrence of the
- specific occurrence within the set of events specified by the rule.
-
- If BYxxx rule part values are found which are beyond the available
- scope (ie, BYMONTHDAY=30 in February), they are simply ignored.
-
- Information, not contained in the rule, necessary to determine the
- various recurrence instance start time and dates are derived from the
- Start Time (DTSTART) entry attribute. For example,
- "FREQ=YEARLY;BYMONTH=1" doesn't specify a specific day within the
- month or a time. This information would be the same as what is
- specified for DTSTART.
-
- BYxxx rule parts modify the recurrence in some manner. BYxxx rule
- parts for a period of time which is the same or greater than the
- frequency generally reduce or limit the number of occurrences of the
- recurrence generated. For example, "FREQ=DAILY;BYMONTH=1" reduces the
- number of recurrence instances from all days (if BYMONTH tag is not
- present) to all days in January. BYxxx rule parts for a period of
- time less than the frequency generally increase or expand the number
- of occurrences of the recurrence. For example,
- "FREQ=YEARLY;BYMONTH=1,2" increases the number of days within the
- yearly recurrence set from 1 (if BYMONTH tag is not present) to 2.
-
- If multiple BYxxx rule parts are specified, then after evaluating the
- specified FREQ and INTERVAL rule parts, the BYxxx rule parts are
- applied to the current set of evaluated occurrences in the following
- order: BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY, BYHOUR,
- BYMINUTE, BYSECOND and BYSETPOS; then COUNT and UNTIL are evaluated.
-
-
-
-Dawson & Stenerson Standards Track [Page 44]
-
-RFC 2445 iCalendar November 1998
-
-
- Here is an example of evaluating multiple BYxxx rule parts.
-
- DTSTART;TZID=US-Eastern:19970105T083000
- RRULE:FREQ=YEARLY;INTERVAL=2;BYMONTH=1;BYDAY=SU;BYHOUR=8,9;
- BYMINUTE=30
-
- First, the "INTERVAL=2" would be applied to "FREQ=YEARLY" to arrive
- at "every other year". Then, "BYMONTH=1" would be applied to arrive
- at "every January, every other year". Then, "BYDAY=SU" would be
- applied to arrive at "every Sunday in January, every other year".
- Then, "BYHOUR=8,9" would be applied to arrive at "every Sunday in
- January at 8 AM and 9 AM, every other year". Then, "BYMINUTE=30"
- would be applied to arrive at "every Sunday in January at 8:30 AM and
- 9:30 AM, every other year". Then, lacking information from RRULE, the
- second is derived from DTSTART, to end up in "every Sunday in January
- at 8:30:00 AM and 9:30:00 AM, every other year". Similarly, if the
- BYMINUTE, BYHOUR, BYDAY, BYMONTHDAY or BYMONTH rule part were
- missing, the appropriate minute, hour, day or month would have been
- retrieved from the "DTSTART" property.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example: The following is a rule which specifies 10 meetings which
- occur every other day:
-
- FREQ=DAILY;COUNT=10;INTERVAL=2
-
- There are other examples specified in the "RRULE" specification.
-
-4.3.11 Text
-
- Value Name: TEXT
-
- Purpose This value type is used to identify values that contain human
- readable text.
-
- Formal Definition: The character sets supported by this revision of
- iCalendar are UTF-8 and US ASCII thereof. The applicability to other
- character sets is for future work. The value type is defined by the
- following notation.
-
- text = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)
- ; Folded according to description above
-
- ESCAPED-CHAR = "\\" / "\;" / "\," / "\N" / "\n")
- ; \\ encodes \, \N or \n encodes newline
- ; \; encodes ;, \, encodes ,
-
-
-
-Dawson & Stenerson Standards Track [Page 45]
-
-RFC 2445 iCalendar November 1998
-
-
- TSAFE-CHAR = %x20-21 / %x23-2B / %x2D-39 / %x3C-5B
- %x5D-7E / NON-US-ASCII
- ; Any character except CTLs not needed by the current
- ; character set, DQUOTE, ";", ":", "\", ","
-
- Note: Certain other character sets may require modification of the
- above definitions, but this is beyond the scope of this document.
-
- Description: If the property permits, multiple "text" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values.
-
- The language in which the text is represented can be controlled by
- the "LANGUAGE" property parameter.
-
- An intentional formatted text line break MUST only be included in a
- "TEXT" property value by representing the line break with the
- character sequence of BACKSLASH (US-ASCII decimal 92), followed by a
- LATIN SMALL LETTER N (US-ASCII decimal 110) or a LATIN CAPITAL LETTER
- N (US-ASCII decimal 78), that is "\n" or "\N".
-
- The "TEXT" property values may also contain special characters that
- are used to signify delimiters, such as a COMMA character for lists
- of values or a SEMICOLON character for structured values. In order to
- support the inclusion of these special characters in "TEXT" property
- values, they MUST be escaped with a BACKSLASH character. A BACKSLASH
- character (US-ASCII decimal 92) in a "TEXT" property value MUST be
- escaped with another BACKSLASH character. A COMMA character in a
- "TEXT" property value MUST be escaped with a BACKSLASH character
- (US-ASCII decimal 92). A SEMICOLON character in a "TEXT" property
- value MUST be escaped with a BACKSLASH character (US-ASCII decimal
- 92). However, a COLON character in a "TEXT" property value SHALL NOT
- be escaped with a BACKSLASH character.Example: A multiple line value
- of:
-
- Project XYZ Final Review
- Conference Room - 3B
- Come Prepared.
-
- would be represented as:
-
- Project XYZ Final Review\nConference Room - 3B\nCome Prepared.
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 46]
-
-RFC 2445 iCalendar November 1998
-
-
-4.3.12 Time
-
- Value Name: TIME
-
- Purpose: This value type is used to identify values that contain a
- time of day.
-
- Formal Definition: The data type is defined by the following
- notation:
-
- time = time-hour time-minute time-second [time-utc]
-
- time-hour = 2DIGIT ;00-23
- time-minute = 2DIGIT ;00-59
- time-second = 2DIGIT ;00-60
- ;The "60" value is used to account for "leap" seconds.
-
- time-utc = "Z"
-
- Description: If the property permits, multiple "time" values are
- specified by a COMMA character (US-ASCII decimal 44) separated list
- of values. No additional content value encoding (i.e., BACKSLASH
- character encoding) is defined for this value type.
-
- The "TIME" data type is used to identify values that contain a time
- of day. The format is based on the [ISO 8601] complete
- representation, basic format for a time of day. The text format
- consists of a two-digit 24-hour of the day (i.e., values 0-23), two-
- digit minute in the hour (i.e., values 0-59), and two-digit seconds
- in the minute (i.e., values 0-60). The seconds value of 60 MUST only
- to be used to account for "leap" seconds. Fractions of a second are
- not supported by this format.
-
- In parallel to the "DATE-TIME" definition above, the "TIME" data type
- expresses time values in three forms:
-
- The form of time with UTC offset MUST NOT be used. For example, the
- following is NOT VALID for a time value:
-
- 230000-0800 ;Invalid time format
-
- FORM #1 LOCAL TIME
-
- The local time form is simply a time value that does not contain the
- UTC designator nor does it reference a time zone. For example, 11:00
- PM:
-
- 230000
-
-
-
-Dawson & Stenerson Standards Track [Page 47]
-
-RFC 2445 iCalendar November 1998
-
-
- Time values of this type are said to be "floating" and are not bound
- to any time zone in particular. They are used to represent the same
- hour, minute, and second value regardless of which time zone is
- currently being observed. For example, an event can be defined that
- indicates that an individual will be busy from 11:00 AM to 1:00 PM
- every day, no matter which time zone the person is in. In these
- cases, a local time can be specified. The recipient of an iCalendar
- object with a property value consisting of a local time, without any
- relative time zone information, SHOULD interpret the value as being
- fixed to whatever time zone the ATTENDEE is in at any given moment.
- This means that two ATTENDEEs may participate in the same event at
- different UTC times; floating time SHOULD only be used where that is
- reasonable behavior.
-
- In most cases, a fixed time is desired. To properly communicate a
- fixed time in a property value, either UTC time or local time with
- time zone reference MUST be specified.
-
- The use of local time in a TIME value without the TZID property
- parameter is to be interpreted as a local time value, regardless of
- the existence of "VTIMEZONE" calendar components in the iCalendar
- object.
-
- FORM #2: UTC TIME
-
- UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z
- suffix character (US-ASCII decimal 90), the UTC designator, appended
- to the time value. For example, the following represents 07:00 AM
- UTC:
-
- 070000Z
-
- The TZID property parameter MUST NOT be applied to TIME properties
- whose time values are specified in UTC.
-
- FORM #3: LOCAL TIME AND TIME ZONE REFERENCE
-
- The local time with reference to time zone information form is
- identified by the use the TZID property parameter to reference the
- appropriate time zone definition. TZID is discussed in detail in the
- section on Time Zone.
-
- Example: The following represents 8:30 AM in New York in Winter, five
- hours behind UTC, in each of the three formats using the "X-
- TIMEOFDAY" non-standard property:
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 48]
-
-RFC 2445 iCalendar November 1998
-
-
- X-TIMEOFDAY:083000
-
- X-TIMEOFDAY:133000Z
-
- X-TIMEOFDAY;TZID=US-Eastern:083000
-
-4.3.13 URI
-
- Value Name: URI
-
- Purpose: This value type is used to identify values that contain a
- uniform resource identifier (URI) type of reference to the property
- value.
-
- Formal Definition: The data type is defined by the following
- notation:
-
- uri = <As defined by any IETF RFC>
-
- Description: This data type might be used to reference binary
- information, for values that are large, or otherwise undesirable to
- include directly in the iCalendar object.
-
- The URI value formats in RFC 1738, RFC 2111 and any other IETF
- registered value format can be specified.
-
- Any IANA registered URI format can be used. These include, but are
- not limited to, those defined in RFC 1738 and RFC 2111.
-
- When a property parameter value is a URI value type, the URI MUST be
- specified as a quoted-string value.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example: The following is a URI for a network file:
-
- http://host1.com/my-report.txt
-
-4.3.14 UTC Offset
-
- Value Name: UTC-OFFSET
-
- Purpose: This value type is used to identify properties that contain
- an offset from UTC to local time.
-
- Formal Definition: The data type is defined by the following
- notation:
-
-
-
-Dawson & Stenerson Standards Track [Page 49]
-
-RFC 2445 iCalendar November 1998
-
-
- utc-offset = time-numzone ;As defined above in time data type
-
- time-numzone = ("+" / "-") time-hour time-minute [time-
- second]
-
- Description: The PLUS SIGN character MUST be specified for positive
- UTC offsets (i.e., ahead of UTC). The value of "-0000" and "-000000"
- are not allowed. The time-second, if present, may not be 60; if
- absent, it defaults to zero.
-
- No additional content value encoding (i.e., BACKSLASH character
- encoding) is defined for this value type.
-
- Example: The following UTC offsets are given for standard time for
- New York (five hours behind UTC) and Geneva (one hour ahead of UTC):
-
- -0500
-
- +0100
-
-4.4 iCalendar Object
-
- The Calendaring and Scheduling Core Object is a collection of
- calendaring and scheduling information. Typically, this information
- will consist of a single iCalendar object. However, multiple
- iCalendar objects can be sequentially grouped together. The first
- line and last line of the iCalendar object MUST contain a pair of
- iCalendar object delimiter strings. The syntax for an iCalendar
- object is as follows:
-
- icalobject = 1*("BEGIN" ":" "VCALENDAR" CRLF
- icalbody
- "END" ":" "VCALENDAR" CRLF)
-
- The following is a simple example of an iCalendar object:
-
- BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//hacksw/handcal//NONSGML v1.0//EN
- BEGIN:VEVENT
- DTSTART:19970714T170000Z
- DTEND:19970715T035959Z
- SUMMARY:Bastille Day Party
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 50]
-
-RFC 2445 iCalendar November 1998
-
-
-4.5 Property
-
- A property is the definition of an individual attribute describing a
- calendar or a calendar component. A property takes the form defined
- by the "contentline" notation defined in section 4.1.1.
-
- The following is an example of a property:
-
- DTSTART:19960415T133000Z
-
- This memo imposes no ordering of properties within an iCalendar
- object.
-
- Property names, parameter names and enumerated parameter values are
- case insensitive. For example, the property name "DUE" is the same as
- "due" and "Due", DTSTART;TZID=US-Eastern:19980714T120000 is the same
- as DtStart;TzID=US-Eastern:19980714T120000.
-
-4.6 Calendar Components
-
- The body of the iCalendar object consists of a sequence of calendar
- properties and one or more calendar components. The calendar
- properties are attributes that apply to the calendar as a whole. The
- calendar components are collections of properties that express a
- particular calendar semantic. For example, the calendar component can
- specify an event, a to-do, a journal entry, time zone information, or
- free/busy time information, or an alarm.
-
- The body of the iCalendar object is defined by the following
- notation:
-
- icalbody = calprops component
-
- calprops = 2*(
-
- ; 'prodid' and 'version' are both REQUIRED,
- ; but MUST NOT occur more than once
-
- prodid /version /
-
- ; 'calscale' and 'method' are optional,
- ; but MUST NOT occur more than once
-
- calscale /
- method /
-
- x-prop
-
-
-
-
-Dawson & Stenerson Standards Track [Page 51]
-
-RFC 2445 iCalendar November 1998
-
-
- )
-
- component = 1*(eventc / todoc / journalc / freebusyc /
- / timezonec / iana-comp / x-comp)
-
- iana-comp = "BEGIN" ":" iana-token CRLF
-
- 1*contentline
-
- "END" ":" iana-token CRLF
-
- x-comp = "BEGIN" ":" x-name CRLF
-
- 1*contentline
-
- "END" ":" x-name CRLF
-
- An iCalendar object MUST include the "PRODID" and "VERSION" calendar
- properties. In addition, it MUST include at least one calendar
- component. Special forms of iCalendar objects are possible to publish
- just busy time (i.e., only a "VFREEBUSY" calendar component) or time
- zone (i.e., only a "VTIMEZONE" calendar component) information. In
- addition, a complex iCalendar object is possible that is used to
- capture a complete snapshot of the contents of a calendar (e.g.,
- composite of many different calendar components). More commonly, an
- iCalendar object will consist of just a single "VEVENT", "VTODO" or
- "VJOURNAL" calendar component.
-
-4.6.1 Event Component
-
- Component Name: "VEVENT"
-
- Purpose: Provide a grouping of component properties that describe an
- event.
-
- Format Definition: A "VEVENT" calendar component is defined by the
- following notation:
-
- eventc = "BEGIN" ":" "VEVENT" CRLF
- eventprop *alarmc
- "END" ":" "VEVENT" CRLF
-
- eventprop = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- class / created / description / dtstart / geo /
-
-
-
-Dawson & Stenerson Standards Track [Page 52]
-
-RFC 2445 iCalendar November 1998
-
-
- last-mod / location / organizer / priority /
- dtstamp / seq / status / summary / transp /
- uid / url / recurid /
-
- ; either 'dtend' or 'duration' may appear in
- ; a 'eventprop', but 'dtend' and 'duration'
- ; MUST NOT occur in the same 'eventprop'
-
- dtend / duration /
-
- ; the following are optional,
- ; and MAY occur more than once
-
- attach / attendee / categories / comment /
- contact / exdate / exrule / rstatus / related /
- resources / rdate / rrule / x-prop
-
- )
-
- Description: A "VEVENT" calendar component is a grouping of component
- properties, and possibly including "VALARM" calendar components, that
- represents a scheduled amount of time on a calendar. For example, it
- can be an activity; such as a one-hour long, department meeting from
- 8:00 AM to 9:00 AM, tomorrow. Generally, an event will take up time
- on an individual calendar. Hence, the event will appear as an opaque
- interval in a search for busy time. Alternately, the event can have
- its Time Transparency set to "TRANSPARENT" in order to prevent
- blocking of the event in searches for busy time.
-
- The "VEVENT" is also the calendar component used to specify an
- anniversary or daily reminder within a calendar. These events have a
- DATE value type for the "DTSTART" property instead of the default
- data type of DATE-TIME. If such a "VEVENT" has a "DTEND" property, it
- MUST be specified as a DATE value also. The anniversary type of
- "VEVENT" can span more than one date (i.e, "DTEND" property value is
- set to a calendar date after the "DTSTART" property value).
-
- The "DTSTART" property for a "VEVENT" specifies the inclusive start
- of the event. For recurring events, it also specifies the very first
- instance in the recurrence set. The "DTEND" property for a "VEVENT"
- calendar component specifies the non-inclusive end of the event. For
- cases where a "VEVENT" calendar component specifies a "DTSTART"
- property with a DATE data type but no "DTEND" property, the events
- non-inclusive end is the end of the calendar date specified by the
- "DTSTART" property. For cases where a "VEVENT" calendar component
- specifies a "DTSTART" property with a DATE-TIME data type but no
- "DTEND" property, the event ends on the same calendar date and time
- of day specified by the "DTSTART" property.
-
-
-
-Dawson & Stenerson Standards Track [Page 53]
-
-RFC 2445 iCalendar November 1998
-
-
- The "VEVENT" calendar component cannot be nested within another
- calendar component. However, "VEVENT" calendar components can be
- related to each other or to a "VTODO" or to a "VJOURNAL" calendar
- component with the "RELATED-TO" property.
-
- Example: The following is an example of the "VEVENT" calendar
- component used to represent a meeting that will also be opaque to
- searches for busy time:
-
- BEGIN:VEVENT
- UID:19970901T130000Z-123401 at host.com
- DTSTAMP:19970901T1300Z
- DTSTART:19970903T163000Z
- DTEND:19970903T190000Z
- SUMMARY:Annual Employee Review
- CLASS:PRIVATE
- CATEGORIES:BUSINESS,HUMAN RESOURCES
- END:VEVENT
-
- The following is an example of the "VEVENT" calendar component used
- to represent a reminder that will not be opaque, but rather
- transparent, to searches for busy time:
-
- BEGIN:VEVENT
- UID:19970901T130000Z-123402 at host.com
- DTSTAMP:19970901T1300Z
- DTSTART:19970401T163000Z
- DTEND:19970402T010000Z
- SUMMARY:Laurel is in sensitivity awareness class.
- CLASS:PUBLIC
- CATEGORIES:BUSINESS,HUMAN RESOURCES
- TRANSP:TRANSPARENT
- END:VEVENT
-
- The following is an example of the "VEVENT" calendar component used
- to represent an anniversary that will occur annually. Since it takes
- up no time, it will not appear as opaque in a search for busy time;
- no matter what the value of the "TRANSP" property indicates:
-
- BEGIN:VEVENT
- UID:19970901T130000Z-123403 at host.com
- DTSTAMP:19970901T1300Z
- DTSTART:19971102
- SUMMARY:Our Blissful Anniversary
- CLASS:CONFIDENTIAL
- CATEGORIES:ANNIVERSARY,PERSONAL,SPECIAL OCCASION
- RRULE:FREQ=YEARLY
- END:VEVENT
-
-
-
-Dawson & Stenerson Standards Track [Page 54]
-
-RFC 2445 iCalendar November 1998
-
-
-4.6.2 To-do Component
-
- Component Name: VTODO
-
- Purpose: Provide a grouping of calendar properties that describe a
- to-do.
-
- Formal Definition: A "VTODO" calendar component is defined by the
- following notation:
-
- todoc = "BEGIN" ":" "VTODO" CRLF
- todoprop *alarmc
- "END" ":" "VTODO" CRLF
-
- todoprop = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- class / completed / created / description / dtstamp /
- dtstart / geo / last-mod / location / organizer /
- percent / priority / recurid / seq / status /
- summary / uid / url /
-
- ; either 'due' or 'duration' may appear in
- ; a 'todoprop', but 'due' and 'duration'
- ; MUST NOT occur in the same 'todoprop'
-
- due / duration /
-
- ; the following are optional,
- ; and MAY occur more than once
- attach / attendee / categories / comment / contact /
- exdate / exrule / rstatus / related / resources /
- rdate / rrule / x-prop
-
- )
-
- Description: A "VTODO" calendar component is a grouping of component
- properties and possibly "VALARM" calendar components that represent
- an action-item or assignment. For example, it can be used to
- represent an item of work assigned to an individual; such as "turn in
- travel expense today".
-
- The "VTODO" calendar component cannot be nested within another
- calendar component. However, "VTODO" calendar components can be
- related to each other or to a "VTODO" or to a "VJOURNAL" calendar
- component with the "RELATED-TO" property.
-
-
-
-Dawson & Stenerson Standards Track [Page 55]
-
-RFC 2445 iCalendar November 1998
-
-
- A "VTODO" calendar component without the "DTSTART" and "DUE" (or
- "DURATION") properties specifies a to-do that will be associated with
- each successive calendar date, until it is completed.
-
- Example: The following is an example of a "VTODO" calendar component:
-
- BEGIN:VTODO
- UID:19970901T130000Z-123404 at host.com
- DTSTAMP:19970901T1300Z
- DTSTART:19970415T133000Z
- DUE:19970416T045959Z
- SUMMARY:1996 Income Tax Preparation
- CLASS:CONFIDENTIAL
- CATEGORIES:FAMILY,FINANCE
- PRIORITY:1
- STATUS:NEEDS-ACTION
- END:VTODO
-
-4.6.3 Journal Component
-
- Component Name: VJOURNAL
-
- Purpose: Provide a grouping of component properties that describe a
- journal entry.
-
- Formal Definition: A "VJOURNAL" calendar component is defined by the
- following notation:
-
- journalc = "BEGIN" ":" "VJOURNAL" CRLF
- jourprop
- "END" ":" "VJOURNAL" CRLF
-
- jourprop = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- class / created / description / dtstart / dtstamp /
- last-mod / organizer / recurid / seq / status /
- summary / uid / url /
-
- ; the following are optional,
- ; and MAY occur more than once
-
- attach / attendee / categories / comment /
- contact / exdate / exrule / related / rdate /
- rrule / rstatus / x-prop
-
-
-
-
-Dawson & Stenerson Standards Track [Page 56]
-
-RFC 2445 iCalendar November 1998
-
-
- )
-
- Description: A "VJOURNAL" calendar component is a grouping of
- component properties that represent one or more descriptive text
- notes associated with a particular calendar date. The "DTSTART"
- property is used to specify the calendar date that the journal entry
- is associated with. Generally, it will have a DATE value data type,
- but it can also be used to specify a DATE-TIME value data type.
- Examples of a journal entry include a daily record of a legislative
- body or a journal entry of individual telephone contacts for the day
- or an ordered list of accomplishments for the day. The "VJOURNAL"
- calendar component can also be used to associate a document with a
- calendar date.
-
- The "VJOURNAL" calendar component does not take up time on a
- calendar. Hence, it does not play a role in free or busy time
- searches - - it is as though it has a time transparency value of
- TRANSPARENT. It is transparent to any such searches.
-
- The "VJOURNAL" calendar component cannot be nested within another
- calendar component. However, "VJOURNAL" calendar components can be
- related to each other or to a "VEVENT" or to a "VTODO" calendar
- component, with the "RELATED-TO" property.
-
- Example: The following is an example of the "VJOURNAL" calendar
- component:
-
- BEGIN:VJOURNAL
- UID:19970901T130000Z-123405 at host.com
- DTSTAMP:19970901T1300Z
- DTSTART;VALUE=DATE:19970317
- SUMMARY:Staff meeting minutes
- DESCRIPTION:1. Staff meeting: Participants include Joe\, Lisa
- and Bob. Aurora project plans were reviewed. There is currently
- no budget reserves for this project. Lisa will escalate to
- management. Next meeting on Tuesday.\n
- 2. Telephone Conference: ABC Corp. sales representative called
- to discuss new printer. Promised to get us a demo by Friday.\n
- 3. Henry Miller (Handsoff Insurance): Car was totaled by tree.
- Is looking into a loaner car. 654-2323 (tel).
- END:VJOURNAL
-
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 57]
-
-RFC 2445 iCalendar November 1998
-
-
-4.6.4 Free/Busy Component
-
- Component Name: VFREEBUSY
-
- Purpose: Provide a grouping of component properties that describe
- either a request for free/busy time, describe a response to a request
- for free/busy time or describe a published set of busy time.
-
- Formal Definition: A "VFREEBUSY" calendar component is defined by the
- following notation:
-
- freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF
- fbprop
- "END" ":" "VFREEBUSY" CRLF
-
- fbprop = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- contact / dtstart / dtend / duration / dtstamp /
- organizer / uid / url /
-
- ; the following are optional,
- ; and MAY occur more than once
-
- attendee / comment / freebusy / rstatus / x-prop
-
- )
-
- Description: A "VFREEBUSY" calendar component is a grouping of
- component properties that represents either a request for, a reply to
- a request for free or busy time information or a published set of
- busy time information.
-
- When used to request free/busy time information, the "ATTENDEE"
- property specifies the calendar users whose free/busy time is being
- requested; the "ORGANIZER" property specifies the calendar user who
- is requesting the free/busy time; the "DTSTART" and "DTEND"
- properties specify the window of time for which the free/busy time is
- being requested; the "UID" and "DTSTAMP" properties are specified to
- assist in proper sequencing of multiple free/busy time requests.
-
- When used to reply to a request for free/busy time, the "ATTENDEE"
- property specifies the calendar user responding to the free/busy time
- request; the "ORGANIZER" property specifies the calendar user that
- originally requested the free/busy time; the "FREEBUSY" property
- specifies the free/busy time information (if it exists); and the
-
-
-
-Dawson & Stenerson Standards Track [Page 58]
-
-RFC 2445 iCalendar November 1998
-
-
- "UID" and "DTSTAMP" properties are specified to assist in proper
- sequencing of multiple free/busy time replies.
-
- When used to publish busy time, the "ORGANIZER" property specifies
- the calendar user associated with the published busy time; the
- "DTSTART" and "DTEND" properties specify an inclusive time window
- that surrounds the busy time information; the "FREEBUSY" property
- specifies the published busy time information; and the "DTSTAMP"
- property specifies the date/time that iCalendar object was created.
-
- The "VFREEBUSY" calendar component cannot be nested within another
- calendar component. Multiple "VFREEBUSY" calendar components can be
- specified within an iCalendar object. This permits the grouping of
- Free/Busy information into logical collections, such as monthly
- groups of busy time information.
-
- The "VFREEBUSY" calendar component is intended for use in iCalendar
- object methods involving requests for free time, requests for busy
- time, requests for both free and busy, and the associated replies.
-
- Free/Busy information is represented with the "FREEBUSY" property.
- This property provides a terse representation of time periods. One or
- more "FREEBUSY" properties can be specified in the "VFREEBUSY"
- calendar component.
-
- When present in a "VFREEBUSY" calendar component, the "DTSTART" and
- "DTEND" properties SHOULD be specified prior to any "FREEBUSY"
- properties. In a free time request, these properties can be used in
- combination with the "DURATION" property to represent a request for a
- duration of free time within a specified window of time.
-
- The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are
- not permitted within a "VFREEBUSY" calendar component. Any recurring
- events are resolved into their individual busy time periods using the
- "FREEBUSY" property.
-
- Example: The following is an example of a "VFREEBUSY" calendar
- component used to request free or busy time information:
-
- BEGIN:VFREEBUSY
- ORGANIZER:MAILTO:jane_doe at host1.com
- ATTENDEE:MAILTO:john_public at host2.com
- DTSTART:19971015T050000Z
- DTEND:19971016T050000Z
- DTSTAMP:19970901T083000Z
- END:VFREEBUSY
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 59]
-
-RFC 2445 iCalendar November 1998
-
-
- The following is an example of a "VFREEBUSY" calendar component used
- to reply to the request with busy time information:
-
- BEGIN:VFREEBUSY
- ORGANIZER:MAILTO:jane_doe at host1.com
- ATTENDEE:MAILTO:john_public at host2.com
- DTSTAMP:19970901T100000Z
- FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,
- 19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
- URL:http://host2.com/pub/busy/jpublic-01.ifb
- COMMENT:This iCalendar file contains busy time information for
- the next three months.
- END:VFREEBUSY
-
- The following is an example of a "VFREEBUSY" calendar component used
- to publish busy time information.
-
- BEGIN:VFREEBUSY
- ORGANIZER:jsmith at host.com
- DTSTART:19980313T141711Z
- DTEND:19980410T141711Z
- FREEBUSY:19980314T233000Z/19980315T003000Z
- FREEBUSY:19980316T153000Z/19980316T163000Z
- FREEBUSY:19980318T030000Z/19980318T040000Z
- URL:http://www.host.com/calendar/busytime/jsmith.ifb
- END:VFREEBUSY
-
-4.6.5 Time Zone Component
-
- Component Name: VTIMEZONE
-
- Purpose: Provide a grouping of component properties that defines a
- time zone.
-
- Formal Definition: A "VTIMEZONE" calendar component is defined by the
- following notation:
-
- timezonec = "BEGIN" ":" "VTIMEZONE" CRLF
-
- 2*(
-
- ; 'tzid' is required, but MUST NOT occur more
- ; than once
-
- tzid /
-
- ; 'last-mod' and 'tzurl' are optional,
- but MUST NOT occur more than once
-
-
-
-Dawson & Stenerson Standards Track [Page 60]
-
-RFC 2445 iCalendar November 1998
-
-
- last-mod / tzurl /
-
- ; one of 'standardc' or 'daylightc' MUST occur
- ..; and each MAY occur more than once.
-
- standardc / daylightc /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- x-prop
-
- )
-
- "END" ":" "VTIMEZONE" CRLF
-
- standardc = "BEGIN" ":" "STANDARD" CRLF
-
- tzprop
-
- "END" ":" "STANDARD" CRLF
-
- daylightc = "BEGIN" ":" "DAYLIGHT" CRLF
-
- tzprop
-
- "END" ":" "DAYLIGHT" CRLF
-
- tzprop = 3*(
-
- ; the following are each REQUIRED,
- ; but MUST NOT occur more than once
-
- dtstart / tzoffsetto / tzoffsetfrom /
-
- ; the following are optional,
- ; and MAY occur more than once
-
- comment / rdate / rrule / tzname / x-prop
-
- )
-
- Description: A time zone is unambiguously defined by the set of time
- measurement rules determined by the governing body for a given
- geographic area. These rules describe at a minimum the base offset
- from UTC for the time zone, often referred to as the Standard Time
- offset. Many locations adjust their Standard Time forward or backward
- by one hour, in order to accommodate seasonal changes in number of
-
-
-
-Dawson & Stenerson Standards Track [Page 61]
-
-RFC 2445 iCalendar November 1998
-
-
- daylight hours, often referred to as Daylight Saving Time. Some
- locations adjust their time by a fraction of an hour. Standard Time
- is also known as Winter Time. Daylight Saving Time is also known as
- Advanced Time, Summer Time, or Legal Time in certain countries. The
- following table shows the changes in time zone rules in effect for
- New York City starting from 1967. Each line represents a description
- or rule for a particular observance.
-
- Effective Observance Rule
-
- Date (Date/Time) Offset Abbreviation
-
- 1967-* last Sun in Oct, 02:00 -0500 EST
-
- 1967-1973 last Sun in Apr, 02:00 -0400 EDT
-
- 1974-1974 Jan 6, 02:00 -0400 EDT
-
- 1975-1975 Feb 23, 02:00 -0400 EDT
-
- 1976-1986 last Sun in Apr, 02:00 -0400 EDT
-
- 1987-* first Sun in Apr, 02:00 -0400 EDT
-
- Note: The specification of a global time zone registry is not
- addressed by this document and is left for future study.
- However, implementers may find the Olson time zone database [TZ]
- a useful reference. It is an informal, public-domain collection
- of time zone information, which is currently being maintained by
- volunteer Internet participants, and is used in several
- operating systems. This database contains current and historical
- time zone information for a wide variety of locations around the
- globe; it provides a time zone identifier for every unique time
- zone rule set in actual use since 1970, with historical data
- going back to the introduction of standard time.
-
- Interoperability between two calendaring and scheduling applications,
- especially for recurring events, to-dos or journal entries, is
- dependent on the ability to capture and convey date and time
- information in an unambiguous format. The specification of current
- time zone information is integral to this behavior.
-
- If present, the "VTIMEZONE" calendar component defines the set of
- Standard Time and Daylight Saving Time observances (or rules) for a
- particular time zone for a given interval of time. The "VTIMEZONE"
- calendar component cannot be nested within other calendar components.
- Multiple "VTIMEZONE" calendar components can exist in an iCalendar
- object. In this situation, each "VTIMEZONE" MUST represent a unique
-
-
-
-Dawson & Stenerson Standards Track [Page 62]
-
-RFC 2445 iCalendar November 1998
-
-
- time zone definition. This is necessary for some classes of events,
- such as airline flights, that start in one time zone and end in
- another.
-
- The "VTIMEZONE" calendar component MUST be present if the iCalendar
- object contains an RRULE that generates dates on both sides of a time
- zone shift (e.g. both in Standard Time and Daylight Saving Time)
- unless the iCalendar object intends to convey a floating time (See
- the section "4.1.10.11 Time" for proper interpretation of floating
- time). It can be present if the iCalendar object does not contain
- such a RRULE. In addition, if a RRULE is present, there MUST be valid
- time zone information for all recurrence instances.
-
- The "VTIMEZONE" calendar component MUST include the "TZID" property
- and at least one definition of a standard or daylight component. The
- standard or daylight component MUST include the "DTSTART",
- "TZOFFSETFROM" and "TZOFFSETTO" properties.
-
- An individual "VTIMEZONE" calendar component MUST be specified for
- each unique "TZID" parameter value specified in the iCalendar object.
-
- Each "VTIMEZONE" calendar component consists of a collection of one
- or more sub-components that describe the rule for a particular
- observance (either a Standard Time or a Daylight Saving Time
- observance). The "STANDARD" sub-component consists of a collection of
- properties that describe Standard Time. The "DAYLIGHT" sub-component
- consists of a collection of properties that describe Daylight Saving
- Time. In general this collection of properties consists of:
-
- - the first onset date-time for the observance
-
- - the last onset date-time for the observance, if a last onset
- is known.
-
- - the offset to be applied for the observance
-
- - a rule that describes the day and time when the observance
- takes effect
-
- - an optional name for the observance
-
- For a given time zone, there may be multiple unique definitions of
- the observances over a period of time. Each observance is described
- using either a "STANDARD" or "DAYLIGHT" sub-component. The collection
- of these sub-components is used to describe the time zone for a given
- period of time. The offset to apply at any given time is found by
- locating the observance that has the last onset date and time before
- the time in question, and using the offset value from that
-
-
-
-Dawson & Stenerson Standards Track [Page 63]
-
-RFC 2445 iCalendar November 1998
-
-
- observance.
-
- The top-level properties in a "VTIMEZONE" calendar component are:
-
- The mandatory "TZID" property is a text value that uniquely
- identifies the VTIMZONE calendar component within the scope of an
- iCalendar object.
-
- The optional "LAST-MODIFIED" property is a UTC value that specifies
- the date and time that this time zone definition was last updated.
-
- The optional "TZURL" property is url value that points to a published
- VTIMEZONE definition. TZURL SHOULD refer to a resource that is
- accessible by anyone who might need to interpret the object. This
- SHOULD NOT normally be a file: URL or other URL that is not widely-
- accessible.
-
- The collection of properties that are used to define the STANDARD and
- DAYLIGHT sub-components include:
-
- The mandatory "DTSTART" property gives the effective onset date and
- local time for the time zone sub-component definition. "DTSTART" in
- this usage MUST be specified as a local DATE-TIME value.
-
- The mandatory "TZOFFSETFROM" property gives the UTC offset which is
- in use when the onset of this time zone observance begins.
- "TZOFFSETFROM" is combined with "DTSTART" to define the effective
- onset for the time zone sub-component definition. For example, the
- following represents the time at which the observance of Standard
- Time took effect in Fall 1967 for New York City:
-
- DTSTART:19671029T020000
-
- TZOFFSETFROM:-0400
-
- The mandatory "TZOFFSETTO " property gives the UTC offset for the
- time zone sub-component (Standard Time or Daylight Saving Time) when
- this observance is in use.
-
- The optional "TZNAME" property is the customary name for the time
- zone. It may be specified multiple times, to allow for specifying
- multiple language variants of the time zone names. This could be used
- for displaying dates.
-
- If specified, the onset for the observance defined by the time zone
- sub-component is defined by either the "RRULE" or "RDATE" property.
- If neither is specified, only one sub-component can be specified in
- the "VTIMEZONE" calendar component and it is assumed that the single
-
-
-
-Dawson & Stenerson Standards Track [Page 64]
-
-RFC 2445 iCalendar November 1998
-
-
- observance specified is always in effect.
-
- The "RRULE" property defines the recurrence rule for the onset of the
- observance defined by this time zone sub-component. Some specific
- requirements for the usage of RRULE for this purpose include:
-
- - If observance is known to have an effective end date, the
- "UNTIL" recurrence rule parameter MUST be used to specify the
- last valid onset of this observance (i.e., the UNTIL date-time
- will be equal to the last instance generated by the recurrence
- pattern). It MUST be specified in UTC time.
-
- - The "DTSTART" and the "TZOFFSETTO" properties MUST be used
- when generating the onset date-time values (instances) from the
- RRULE.
-
- Alternatively, the "RDATE" property can be used to define the onset
- of the observance by giving the individual onset date and times.
- "RDATE" in this usage MUST be specified as a local DATE-TIME value in
- UTC time.
-
- The optional "COMMENT" property is also allowed for descriptive
- explanatory text.
-
- Example: The following are examples of the "VTIMEZONE" calendar
- component:
-
- This is an example showing time zone information for the Eastern
- United States using "RDATE" property. Note that this is only suitable
- for a recurring event that starts on or later than April 6, 1997 at
- 03:00:00 EDT (i.e., the earliest effective transition date and time)
- and ends no later than April 7, 1998 02:00:00 EST (i.e., latest valid
- date and time for EST in this scenario). For example, this can be
- used for a recurring event that occurs every Friday, 8am-9:00 AM,
- starting June 1, 1997, ending December 31, 1997.
-
- BEGIN:VTIMEZONE
- TZID:US-Eastern
- LAST-MODIFIED:19870101T000000Z
- BEGIN:STANDARD
- DTSTART:19971026T020000
- RDATE:19971026T020000
- TZOFFSETFROM:-0400
- TZOFFSETTO:-0500
- TZNAME:EST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19971026T020000
-
-
-
-Dawson & Stenerson Standards Track [Page 65]
-
-RFC 2445 iCalendar November 1998
-
-
- RDATE:19970406T020000
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- END:VTIMEZONE
-
- This is a simple example showing the current time zone rules for the
- Eastern United States using a RRULE recurrence pattern. Note that
- there is no effective end date to either of the Standard Time or
- Daylight Time rules. This information would be valid for a recurring
- event starting today and continuing indefinitely.
-
- BEGIN:VTIMEZONE
- TZID:US-Eastern
- LAST-MODIFIED:19870101T000000Z
- TZURL:http://zones.stds_r_us.net/tz/US-Eastern
- BEGIN:STANDARD
- DTSTART:19671029T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
- TZOFFSETFROM:-0400
- TZOFFSETTO:-0500
- TZNAME:EST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19870405T020000
- RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- END:VTIMEZONE
-
- This is an example showing a fictitious set of rules for the Eastern
- United States, where the Daylight Time rule has an effective end date
- (i.e., after that date, Daylight Time is no longer observed).
-
- BEGIN:VTIMEZONE
- TZID:US--Fictitious-Eastern
- LAST-MODIFIED:19870101T000000Z
- BEGIN:STANDARD
- DTSTART:19671029T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
- TZOFFSETFROM:-0400
- TZOFFSETTO:-0500
- TZNAME:EST
- END:STANDARD
-
-
-
-
-Dawson & Stenerson Standards Track [Page 66]
-
-RFC 2445 iCalendar November 1998
-
-
- BEGIN:DAYLIGHT
- DTSTART:19870405T020000
- RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- END:VTIMEZONE
-
- This is an example showing a fictitious set of rules for the Eastern
- United States, where the first Daylight Time rule has an effective
- end date. There is a second Daylight Time rule that picks up where
- the other left off.
-
- BEGIN:VTIMEZONE
- TZID:US--Fictitious-Eastern
- LAST-MODIFIED:19870101T000000Z
- BEGIN:STANDARD
- DTSTART:19671029T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
- TZOFFSETFROM:-0400
- TZOFFSETTO:-0500
- TZNAME:EST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19870405T020000
- RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4;UNTIL=19980404T070000Z
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- BEGIN:DAYLIGHT
- DTSTART:19990424T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=4
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- END:VTIMEZONE
-
-4.6.6 Alarm Component
-
- Component Name: VALARM
-
- Purpose: Provide a grouping of component properties that define an
- alarm.
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 67]
-
-RFC 2445 iCalendar November 1998
-
-
- Formal Definition: A "VALARM" calendar component is defined by the
- following notation:
-
- alarmc = "BEGIN" ":" "VALARM" CRLF
- (audioprop / dispprop / emailprop / procprop)
- "END" ":" "VALARM" CRLF
-
- audioprop = 2*(
-
- ; 'action' and 'trigger' are both REQUIRED,
- ; but MUST NOT occur more than once
-
- action / trigger /
-
- ; 'duration' and 'repeat' are both optional,
- ; and MUST NOT occur more than once each,
- ; but if one occurs, so MUST the other
-
- duration / repeat /
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- attach /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- x-prop
-
- )
-
-
-
- dispprop = 3*(
-
- ; the following are all REQUIRED,
- ; but MUST NOT occur more than once
-
- action / description / trigger /
-
- ; 'duration' and 'repeat' are both optional,
- ; and MUST NOT occur more than once each,
- ; but if one occurs, so MUST the other
-
- duration / repeat /
-
- ; the following is optional,
-
-
-
-Dawson & Stenerson Standards Track [Page 68]
-
-RFC 2445 iCalendar November 1998
-
-
- ; and MAY occur more than once
-
- *x-prop
-
- )
-
-
-
- emailprop = 5*(
-
- ; the following are all REQUIRED,
- ; but MUST NOT occur more than once
-
- action / description / trigger / summary
-
- ; the following is REQUIRED,
- ; and MAY occur more than once
-
- attendee /
-
- ; 'duration' and 'repeat' are both optional,
- ; and MUST NOT occur more than once each,
- ; but if one occurs, so MUST the other
-
- duration / repeat /
-
- ; the following are optional,
- ; and MAY occur more than once
-
- attach / x-prop
-
- )
-
-
-
- procprop = 3*(
-
- ; the following are all REQUIRED,
- ; but MUST NOT occur more than once
-
- action / attach / trigger /
-
- ; 'duration' and 'repeat' are both optional,
- ; and MUST NOT occur more than once each,
- ; but if one occurs, so MUST the other
-
- duration / repeat /
-
-
-
-
-Dawson & Stenerson Standards Track [Page 69]
-
-RFC 2445 iCalendar November 1998
-
-
- ; 'description' is optional,
- ; and MUST NOT occur more than once
-
- description /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- x-prop
-
- )
-
- Description: A "VALARM" calendar component is a grouping of component
- properties that is a reminder or alarm for an event or a to-do. For
- example, it may be used to define a reminder for a pending event or
- an overdue to-do.
-
- The "VALARM" calendar component MUST include the "ACTION" and
- "TRIGGER" properties. The "ACTION" property further constrains the
- "VALARM" calendar component in the following ways:
-
- When the action is "AUDIO", the alarm can also include one and only
- one "ATTACH" property, which MUST point to a sound resource, which is
- rendered when the alarm is triggered.
-
- When the action is "DISPLAY", the alarm MUST also include a
- "DESCRIPTION" property, which contains the text to be displayed when
- the alarm is triggered.
-
- When the action is "EMAIL", the alarm MUST include a "DESCRIPTION"
- property, which contains the text to be used as the message body, a
- "SUMMARY" property, which contains the text to be used as the message
- subject, and one or more "ATTENDEE" properties, which contain the
- email address of attendees to receive the message. It can also
- include one or more "ATTACH" properties, which are intended to be
- sent as message attachments. When the alarm is triggered, the email
- message is sent.
-
- When the action is "PROCEDURE", the alarm MUST include one and only
- one "ATTACH" property, which MUST point to a procedure resource,
- which is invoked when the alarm is triggered.
-
- The "VALARM" calendar component MUST only appear within either a
- "VEVENT" or "VTODO" calendar component. "VALARM" calendar components
- cannot be nested. Multiple mutually independent "VALARM" calendar
- components can be specified for a single "VEVENT" or "VTODO" calendar
- component.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 70]
-
-RFC 2445 iCalendar November 1998
-
-
- The "TRIGGER" property specifies when the alarm will be triggered.
- The "TRIGGER" property specifies a duration prior to the start of an
- event or a to-do. The "TRIGGER" edge may be explicitly set to be
- relative to the "START" or "END" of the event or to-do with the
- "RELATED" parameter of the "TRIGGER" property. The "TRIGGER" property
- value type can alternatively be set to an absolute calendar date and
- time of day value.
-
- In an alarm set to trigger on the "START" of an event or to-do, the
- "DTSTART" property MUST be present in the associated event or to-do.
- In an alarm in a "VEVENT" calendar component set to trigger on the
- "END" of the event, either the "DTEND" property MUST be present, or
- the "DTSTART" and "DURATION" properties MUST both be present. In an
- alarm in a "VTODO" calendar component set to trigger on the "END" of
- the to-do, either the "DUE" property MUST be present, or the
- "DTSTART" and "DURATION" properties MUST both be present.
-
- The alarm can be defined such that it triggers repeatedly. A
- definition of an alarm with a repeating trigger MUST include both the
- "DURATION" and "REPEAT" properties. The "DURATION" property specifies
- the delay period, after which the alarm will repeat. The "REPEAT"
- property specifies the number of additional repetitions that the
- alarm will triggered. This repitition count is in addition to the
- initial triggering of the alarm. Both of these properties MUST be
- present in order to specify a repeating alarm. If one of these two
- properties is absent, then the alarm will not repeat beyond the
- initial trigger.
-
- The "ACTION" property is used within the "VALARM" calendar component
- to specify the type of action invoked when the alarm is triggered.
- The "VALARM" properties provide enough information for a specific
- action to be invoked. It is typically the responsibility of a
- "Calendar User Agent" (CUA) to deliver the alarm in the specified
- fashion. An "ACTION" property value of AUDIO specifies an alarm that
- causes a sound to be played to alert the user; DISPLAY specifies an
- alarm that causes a text message to be displayed to the user; EMAIL
- specifies an alarm that causes an electronic email message to be
- delivered to one or more email addresses; and PROCEDURE specifies an
- alarm that causes a procedure to be executed. The "ACTION" property
- MUST specify one and only one of these values.
-
- In an AUDIO alarm, if the optional "ATTACH" property is included, it
- MUST specify an audio sound resource. The intention is that the sound
- will be played as the alarm effect. If an "ATTACH" property is
- specified that does not refer to a sound resource, or if the
- specified sound resource cannot be rendered (because its format is
- unsupported, or because it cannot be retrieved), then the CUA or
- other entity responsible for playing the sound may choose a fallback
-
-
-
-Dawson & Stenerson Standards Track [Page 71]
-
-RFC 2445 iCalendar November 1998
-
-
- action, such as playing a built-in default sound, or playing no sound
- at all.
-
- In a DISPLAY alarm, the intended alarm effect is for the text value
- of the "DESCRIPTION" property to be displayed to the user.
-
- In an EMAIL alarm, the intended alarm effect is for an email message
- to be composed and delivered to all the addresses specified by the
- "ATTENDEE" properties in the "VALARM" calendar component. The
- "DESCRIPTION" property of the "VALARM" calendar component MUST be
- used as the body text of the message, and the "SUMMARY" property MUST
- be used as the subject text. Any "ATTACH" properties in the "VALARM"
- calendar component SHOULD be sent as attachments to the message.
-
- In a PROCEDURE alarm, the "ATTACH" property in the "VALARM" calendar
- component MUST specify a procedure or program that is intended to be
- invoked as the alarm effect. If the procedure or program is in a
- format that cannot be rendered, then no procedure alarm will be
- invoked. If the "DESCRIPTION" property is present, its value
- specifies the argument string to be passed to the procedure or
- program. "Calendar User Agents" that receive an iCalendar object with
- this category of alarm, can disable or allow the "Calendar User" to
- disable, or otherwise ignore this type of alarm. While a very useful
- alarm capability, the PROCEDURE type of alarm SHOULD be treated by
- the "Calendar User Agent" as a potential security risk.
-
- Example: The following example is for a "VALARM" calendar component
- that specifies an audio alarm that will sound at a precise time and
- repeat 4 more times at 15 minute intervals:
-
- BEGIN:VALARM
- TRIGGER;VALUE=DATE-TIME:19970317T133000Z
- REPEAT:4
- DURATION:PT15M
- ACTION:AUDIO
- ATTACH;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell-01.aud
- END:VALARM
-
- The following example is for a "VALARM" calendar component that
- specifies a display alarm that will trigger 30 minutes before the
- scheduled start of the event or the due date/time of the to-do it is
- associated with and will repeat 2 more times at 15 minute intervals:
-
- BEGIN:VALARM
- TRIGGER:-PT30M
- REPEAT:2
- DURATION:PT15M
- ACTION:DISPLAY
-
-
-
-Dawson & Stenerson Standards Track [Page 72]
-
-RFC 2445 iCalendar November 1998
-
-
- DESCRIPTION:Breakfast meeting with executive\n
- team at 8:30 AM EST.
- END:VALARM
-
- The following example is for a "VALARM" calendar component that
- specifies an email alarm that will trigger 2 days before the
- scheduled due date/time of a to-do it is associated with. It does not
- repeat. The email has a subject, body and attachment link.
-
- BEGIN:VALARM
- TRIGGER:-P2D
- ACTION:EMAIL
- ATTENDEE:MAILTO:john_doe at host.com
- SUMMARY:*** REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING ***
- DESCRIPTION:A draft agenda needs to be sent out to the attendees
- to the weekly managers meeting (MGR-LIST). Attached is a
- pointer the document template for the agenda file.
- ATTACH;FMTTYPE=application/binary:http://host.com/templates/agen
- da.doc
- END:VALARM
-
- The following example is for a "VALARM" calendar component that
- specifies a procedural alarm that will trigger at a precise date/time
- and will repeat 23 more times at one hour intervals. The alarm will
- invoke a procedure file.
-
- BEGIN:VALARM
- TRIGGER;VALUE=DATE-TIME:19980101T050000Z
- REPEAT:23
- DURATION:PT1H
- ACTION:PROCEDURE
- ATTACH;FMTTYPE=application/binary:ftp://host.com/novo-
- procs/felizano.exe
- END:VALARM
-
-4.7 Calendar Properties
-
- The Calendar Properties are attributes that apply to the iCalendar
- object, as a whole. These properties do not appear within a calendar
- component. They SHOULD be specified after the "BEGIN:VCALENDAR"
- property and prior to any calendar component.
-
-4.7.1 Calendar Scale
-
- Property Name: CALSCALE
-
- Purpose: This property defines the calendar scale used for the
- calendar information specified in the iCalendar object.
-
-
-
-Dawson & Stenerson Standards Track [Page 73]
-
-RFC 2445 iCalendar November 1998
-
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: Property can be specified in an iCalendar object. The
- default value is "GREGORIAN".
-
- Description: This memo is based on the Gregorian calendar scale. The
- Gregorian calendar scale is assumed if this property is not specified
- in the iCalendar object. It is expected that other calendar scales
- will be defined in other specifications or by future versions of this
- memo.
-
- Format Definition: The property is defined by the following notation:
-
- calscale = "CALSCALE" calparam ":" calvalue CRLF
-
- calparam = *(";" xparam)
-
- calvalue = "GREGORIAN" / iana-token
-
- Example: The following is an example of this property:
-
- CALSCALE:GREGORIAN
-
-4.7.2 Method
-
- Property Name: METHOD
-
- Purpose: This property defines the iCalendar object method associated
- with the calendar object.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified in an iCalendar object.
-
- Description: When used in a MIME message entity, the value of this
- property MUST be the same as the Content-Type "method" parameter
- value. This property can only appear once within the iCalendar
- object. If either the "METHOD" property or the Content-Type "method"
- parameter is specified, then the other MUST also be specified.
-
- No methods are defined by this specification. This is the subject of
- other specifications, such as the iCalendar Transport-independent
-
-
-
-Dawson & Stenerson Standards Track [Page 74]
-
-RFC 2445 iCalendar November 1998
-
-
- Interoperability Protocol (iTIP) defined by [ITIP].
-
- If this property is not present in the iCalendar object, then a
- scheduling transaction MUST NOT be assumed. In such cases, the
- iCalendar object is merely being used to transport a snapshot of some
- calendar information; without the intention of conveying a scheduling
- semantic.
-
- Format Definition: The property is defined by the following notation:
-
- method = "METHOD" metparam ":" metvalue CRLF
-
- metparam = *(";" xparam)
-
- metvalue = iana-token
-
- Example: The following is a hypothetical example of this property to
- convey that the iCalendar object is a request for a meeting:
-
- METHOD:REQUEST
-
-4.7.3 Product Identifier
-
- Property Name: PRODID
-
- Purpose: This property specifies the identifier for the product that
- created the iCalendar object.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property MUST be specified once in an iCalendar
- object.
-
- Description: The vendor of the implementation SHOULD assure that this
- is a globally unique identifier; using some technique such as an FPI
- value, as defined in [ISO 9070].
-
- This property SHOULD not be used to alter the interpretation of an
- iCalendar object beyond the semantics specified in this memo. For
- example, it is not to be used to further the understanding of non-
- standard properties.
-
- Format Definition: The property is defined by the following notation:
-
- prodid = "PRODID" pidparam ":" pidvalue CRLF
-
-
-
-Dawson & Stenerson Standards Track [Page 75]
-
-RFC 2445 iCalendar November 1998
-
-
- pidparam = *(";" xparam)
-
- pidvalue = text
- ;Any text that describes the product and version
- ;and that is generally assured of being unique.
-
- Example: The following is an example of this property. It does not
- imply that English is the default language.
-
- PRODID:-//ABC Corporation//NONSGML My Product//EN
-
-4.7.4 Version
-
- Property Name: VERSION
-
- Purpose: This property specifies the identifier corresponding to the
- highest version number or the minimum and maximum range of the
- iCalendar specification that is required in order to interpret the
- iCalendar object.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property MUST be specified by an iCalendar object,
- but MUST only be specified once.
-
- Description: A value of "2.0" corresponds to this memo.
-
- Format Definition: The property is defined by the following notation:
-
- version = "VERSION" verparam ":" vervalue CRLF
-
- verparam = *(";" xparam)
-
- vervalue = "2.0" ;This memo
- / maxver
- / (minver ";" maxver)
-
- minver = <A IANA registered iCalendar version identifier>
- ;Minimum iCalendar version needed to parse the iCalendar object
-
- maxver = <A IANA registered iCalendar version identifier>
- ;Maximum iCalendar version needed to parse the iCalendar object
-
- Example: The following is an example of this property:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 76]
-
-RFC 2445 iCalendar November 1998
-
-
- VERSION:2.0
-
-4.8 Component Properties
-
- The following properties can appear within calendar components, as
- specified by each component property definition.
-
-4.8.1 Descriptive Component Properties
-
- The following properties specify descriptive information about
- calendar components.
-
-4.8.1.1 Attachment
-
- Property Name: ATTACH
-
- Purpose: The property provides the capability to associate a document
- object with a calendar component.
-
- Value Type: The default value type for this property is URI. The
- value type can also be set to BINARY to indicate inline binary
- encoded content information.
-
- Property Parameters: Non-standard, inline encoding, format type and
- value data type property parameters can be specified on this
- property.
-
- Conformance: The property can be specified in a "VEVENT", "VTODO",
- "VJOURNAL" or "VALARM" calendar components.
-
- Description: The property can be specified within "VEVENT", "VTODO",
- "VJOURNAL", or "VALARM" calendar components. This property can be
- specified multiple times within an iCalendar object.
-
- Format Definition: The property is defined by the following notation:
-
- attach = "ATTACH" attparam ":" uri CRLF
-
- attach =/ "ATTACH" attparam ";" "ENCODING" "=" "BASE64"
- ";" "VALUE" "=" "BINARY" ":" binary
-
- attparam = *(
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- (";" fmttypeparam) /
-
-
-
-
-Dawson & Stenerson Standards Track [Page 77]
-
-RFC 2445 iCalendar November 1998
-
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following are examples of this property:
-
- ATTACH:CID:jsmith.part3.960817T083000.xyzMail at host1.com
-
- ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
- reports/r-960812.ps
-
-4.8.1.2 Categories
-
- Property Name: CATEGORIES
-
- Purpose: This property defines the categories for a calendar
- component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard and language property parameters
- can be specified on this property.
-
- Conformance: The property can be specified within "VEVENT", "VTODO"
- or "VJOURNAL" calendar components.
-
- Description: This property is used to specify categories or subtypes
- of the calendar component. The categories are useful in searching for
- a calendar component of a particular type and category. Within the
- "VEVENT", "VTODO" or "VJOURNAL" calendar components, more than one
- category can be specified as a list of categories separated by the
- COMMA character (US-ASCII decimal 44).
-
- Format Definition: The property is defined by the following notation:
-
- categories = "CATEGORIES" catparam ":" text *("," text)
- CRLF
-
- catparam = *(
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- (";" languageparam ) /
-
-
-
-
-Dawson & Stenerson Standards Track [Page 78]
-
-RFC 2445 iCalendar November 1998
-
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following are examples of this property:
-
- CATEGORIES:APPOINTMENT,EDUCATION
-
- CATEGORIES:MEETING
-
-4.8.1.3 Classification
-
- Property Name: CLASS
-
- Purpose: This property defines the access classification for a
- calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified once in a "VEVENT",
- "VTODO" or "VJOURNAL" calendar components.
-
- Description: An access classification is only one component of the
- general security system within a calendar application. It provides a
- method of capturing the scope of the access the calendar owner
- intends for information within an individual calendar entry. The
- access classification of an individual iCalendar component is useful
- when measured along with the other security components of a calendar
- system (e.g., calendar user authentication, authorization, access
- rights, access role, etc.). Hence, the semantics of the individual
- access classifications cannot be completely defined by this memo
- alone. Additionally, due to the "blind" nature of most exchange
- processes using this memo, these access classifications cannot serve
- as an enforcement statement for a system receiving an iCalendar
- object. Rather, they provide a method for capturing the intention of
- the calendar owner for the access to the calendar component.
-
- Format Definition: The property is defined by the following notation:
-
- class = "CLASS" classparam ":" classvalue CRLF
-
- classparam = *(";" xparam)
-
-
-
-Dawson & Stenerson Standards Track [Page 79]
-
-RFC 2445 iCalendar November 1998
-
-
- classvalue = "PUBLIC" / "PRIVATE" / "CONFIDENTIAL" / iana-token
- / x-name
- ;Default is PUBLIC
-
- Example: The following is an example of this property:
-
- CLASS:PUBLIC
-
-4.8.1.4 Comment
-
- Property Name: COMMENT
-
- Purpose: This property specifies non-processing information intended
- to provide a comment to the calendar user.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: This property can be specified in "VEVENT", "VTODO",
- "VJOURNAL", "VTIMEZONE" or "VFREEBUSY" calendar components.
-
- Description: The property can be specified multiple times.
-
- Format Definition: The property is defined by the following notation:
-
- comment = "COMMENT" commparam ":" text CRLF
-
- commparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following is an example of this property:
-
- COMMENT:The meeting really needs to include both ourselves
- and the customer. We can't hold this meeting without them.
- As a matter of fact\, the venue for the meeting ought to be at
-
-
-
-Dawson & Stenerson Standards Track [Page 80]
-
-RFC 2445 iCalendar November 1998
-
-
- their site. - - John
-
- The data type for this property is TEXT.
-
-4.8.1.5 Description
-
- Property Name: DESCRIPTION
-
- Purpose: This property provides a more complete description of the
- calendar component, than that provided by the "SUMMARY" property.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: The property can be specified in the "VEVENT", "VTODO",
- "VJOURNAL" or "VALARM" calendar components. The property can be
- specified multiple times only within a "VJOURNAL" calendar component.
-
- Description: This property is used in the "VEVENT" and "VTODO" to
- capture lengthy textual decriptions associated with the activity.
-
- This property is used in the "VJOURNAL" calendar component to capture
- one more textual journal entries.
-
- This property is used in the "VALARM" calendar component to capture
- the display text for a DISPLAY category of alarm, to capture the body
- text for an EMAIL category of alarm and to capture the argument
- string for a PROCEDURE category of alarm.
-
- Format Definition: The property is defined by the following notation:
-
- description = "DESCRIPTION" descparam ":" text CRLF
-
- descparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
-
-
-Dawson & Stenerson Standards Track [Page 81]
-
-RFC 2445 iCalendar November 1998
-
-
- Example: The following is an example of the property with formatted
- line breaks in the property value:
-
- DESCRIPTION:Meeting to provide technical review for "Phoenix"
- design.\n Happy Face Conference Room. Phoenix design team
- MUST attend this meeting.\n RSVP to team leader.
-
- The following is an example of the property with folding of long
- lines:
-
- DESCRIPTION:Last draft of the new novel is to be completed
- for the editor's proof today.
-
-4.8.1.6 Geographic Position
-
- Property Name: GEO
-
- Purpose: This property specifies information related to the global
- position for the activity specified by a calendar component.
-
- Value Type: FLOAT. The value MUST be two SEMICOLON separated FLOAT
- values.
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in "VEVENT" or "VTODO"
- calendar components.
-
- Description: The property value specifies latitude and longitude, in
- that order (i.e., "LAT LON" ordering). The longitude represents the
- location east or west of the prime meridian as a positive or negative
- real number, respectively. The longitude and latitude values MAY be
- specified up to six decimal places, which will allow for accuracy to
- within one meter of geographical position. Receiving applications
- MUST accept values of this precision and MAY truncate values of
- greater precision.
-
- Values for latitude and longitude shall be expressed as decimal
- fractions of degrees. Whole degrees of latitude shall be represented
- by a two-digit decimal number ranging from 0 through 90. Whole
- degrees of longitude shall be represented by a decimal number ranging
- from 0 through 180. When a decimal fraction of a degree is specified,
- it shall be separated from the whole number of degrees by a decimal
- point.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 82]
-
-RFC 2445 iCalendar November 1998
-
-
- Latitudes north of the equator shall be specified by a plus sign (+),
- or by the absence of a minus sign (-), preceding the digits
- designating degrees. Latitudes south of the Equator shall be
- designated by a minus sign (-) preceding the digits designating
- degrees. A point on the Equator shall be assigned to the Northern
- Hemisphere.
-
- Longitudes east of the prime meridian shall be specified by a plus
- sign (+), or by the absence of a minus sign (-), preceding the digits
- designating degrees. Longitudes west of the meridian shall be
- designated by minus sign (-) preceding the digits designating
- degrees. A point on the prime meridian shall be assigned to the
- Eastern Hemisphere. A point on the 180th meridian shall be assigned
- to the Western Hemisphere. One exception to this last convention is
- permitted. For the special condition of describing a band of latitude
- around the earth, the East Bounding Coordinate data element shall be
- assigned the value +180 (180) degrees.
-
- Any spatial address with a latitude of +90 (90) or -90 degrees will
- specify the position at the North or South Pole, respectively. The
- component for longitude may have any legal value.
-
- With the exception of the special condition described above, this
- form is specified in Department of Commerce, 1986, Representation of
- geographic point locations for information interchange (Federal
- Information Processing Standard 70-1): Washington, Department of
- Commerce, National Institute of Standards and Technology.
-
- The simple formula for converting degrees-minutes-seconds into
- decimal degrees is:
-
- decimal = degrees + minutes/60 + seconds/3600.
-
- Format Definition: The property is defined by the following notation:
-
- geo = "GEO" geoparam ":" geovalue CRLF
-
- geoparam = *(";" xparam)
-
- geovalue = float ";" float
- ;Latitude and Longitude components
-
- Example: The following is an example of this property:
-
- GEO:37.386013;-122.082932
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 83]
-
-RFC 2445 iCalendar November 1998
-
-
-4.8.1.7 Location
-
- Property Name: LOCATION
-
- Purpose: The property defines the intended venue for the activity
- defined by a calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: This property can be specified in "VEVENT" or "VTODO"
- calendar component.
-
- Description: Specific venues such as conference or meeting rooms may
- be explicitly specified using this property. An alternate
- representation may be specified that is a URI that points to
- directory information with more structured specification of the
- location. For example, the alternate representation may specify
- either an LDAP URI pointing to an LDAP server entry or a CID URI
- pointing to a MIME body part containing a vCard [RFC 2426] for the
- location.
-
- Format Definition: The property is defined by the following notation:
-
- location = "LOCATION locparam ":" text CRLF
-
- locparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following are some examples of this property:
-
- LOCATION:Conference Room - F123, Bldg. 002
-
- LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
- Conference Room - F123, Bldg. 002
-
-
-
-Dawson & Stenerson Standards Track [Page 84]
-
-RFC 2445 iCalendar November 1998
-
-
-4.8.1.8 Percent Complete
-
- Property Name: PERCENT-COMPLETE
-
- Purpose: This property is used by an assignee or delegatee of a to-do
- to convey the percent completion of a to-do to the Organizer.
-
- Value Type: INTEGER
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in a "VTODO" calendar
- component.
-
- Description: The property value is a positive integer between zero
- and one hundred. A value of "0" indicates the to-do has not yet been
- started. A value of "100" indicates that the to-do has been
- completed. Integer values in between indicate the percent partially
- complete.
-
- When a to-do is assigned to multiple individuals, the property value
- indicates the percent complete for that portion of the to-do assigned
- to the assignee or delegatee. For example, if a to-do is assigned to
- both individuals "A" and "B". A reply from "A" with a percent
- complete of "70" indicates that "A" has completed 70% of the to-do
- assigned to them. A reply from "B" with a percent complete of "50"
- indicates "B" has completed 50% of the to-do assigned to them.
-
- Format Definition: The property is defined by the following notation:
-
- percent = "PERCENT-COMPLETE" pctparam ":" integer CRLF
-
- pctparam = *(";" xparam)
-
- Example: The following is an example of this property to show 39%
- completion:
-
- PERCENT-COMPLETE:39
-
-4.8.1.9 Priority
-
- Property Name: PRIORITY
-
- Purpose: The property defines the relative priority for a calendar
- component.
-
- Value Type: INTEGER
-
-
-
-Dawson & Stenerson Standards Track [Page 85]
-
-RFC 2445 iCalendar November 1998
-
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified in a "VEVENT" or "VTODO"
- calendar component.
-
- Description: The priority is specified as an integer in the range
- zero to nine. A value of zero (US-ASCII decimal 48) specifies an
- undefined priority. A value of one (US-ASCII decimal 49) is the
- highest priority. A value of two (US-ASCII decimal 50) is the second
- highest priority. Subsequent numbers specify a decreasing ordinal
- priority. A value of nine (US-ASCII decimal 58) is the lowest
- priority.
-
- A CUA with a three-level priority scheme of "HIGH", "MEDIUM" and
- "LOW" is mapped into this property such that a property value in the
- range of one (US-ASCII decimal 49) to four (US-ASCII decimal 52)
- specifies "HIGH" priority. A value of five (US-ASCII decimal 53) is
- the normal or "MEDIUM" priority. A value in the range of six (US-
- ASCII decimal 54) to nine (US-ASCII decimal 58) is "LOW" priority.
-
- A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", ...,
- "C3" is mapped into this property such that a property value of one
- (US-ASCII decimal 49) specifies "A1", a property value of two (US-
- ASCII decimal 50) specifies "A2", a property value of three (US-ASCII
- decimal 51) specifies "A3", and so forth up to a property value of 9
- (US-ASCII decimal 58) specifies "C3".
-
- Other integer values are reserved for future use.
-
- Within a "VEVENT" calendar component, this property specifies a
- priority for the event. This property may be useful when more than
- one event is scheduled for a given time period.
-
- Within a "VTODO" calendar component, this property specified a
- priority for the to-do. This property is useful in prioritizing
- multiple action items for a given time period.
-
- Format Definition: The property is specified by the following
- notation:
-
- priority = "PRIORITY" prioparam ":" privalue CRLF
- ;Default is zero
-
- prioparam = *(";" xparam)
-
- privalue = integer ;Must be in the range [0..9]
- ; All other values are reserved for future use
-
-
-
-Dawson & Stenerson Standards Track [Page 86]
-
-RFC 2445 iCalendar November 1998
-
-
- The following is an example of a property with the highest priority:
-
- PRIORITY:1
-
- The following is an example of a property with a next highest
- priority:
-
- PRIORITY:2
-
- Example: The following is an example of a property with no priority.
- This is equivalent to not specifying the "PRIORITY" property:
-
- PRIORITY:0
-
-4.8.1.10 Resources
-
- Property Name: RESOURCES
-
- Purpose: This property defines the equipment or resources anticipated
- for an activity specified by a calendar entity..
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: This property can be specified in "VEVENT" or "VTODO"
- calendar component.
-
- Description: The property value is an arbitrary text. More than one
- resource can be specified as a list of resources separated by the
- COMMA character (US-ASCII decimal 44).
-
- Format Definition: The property is defined by the following notation:
-
- resources = "RESOURCES" resrcparam ":" text *("," text) CRLF
-
- resrcparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 87]
-
-RFC 2445 iCalendar November 1998
-
-
- (";" xparam)
-
- )
-
- Example: The following is an example of this property:
-
- RESOURCES:EASEL,PROJECTOR,VCR
-
- RESOURCES;LANGUAGE=fr:1 raton-laveur
-
-4.8.1.11 Status
-
- Property Name: STATUS
-
- Purpose: This property defines the overall status or confirmation for
- the calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in "VEVENT", "VTODO" or
- "VJOURNAL" calendar components.
-
- Description: In a group scheduled calendar component, the property is
- used by the "Organizer" to provide a confirmation of the event to the
- "Attendees". For example in a "VEVENT" calendar component, the
- "Organizer" can indicate that a meeting is tentative, confirmed or
- cancelled. In a "VTODO" calendar component, the "Organizer" can
- indicate that an action item needs action, is completed, is in
- process or being worked on, or has been cancelled. In a "VJOURNAL"
- calendar component, the "Organizer" can indicate that a journal entry
- is draft, final or has been cancelled or removed.
-
- Format Definition: The property is defined by the following notation:
-
- status = "STATUS" statparam] ":" statvalue CRLF
-
- statparam = *(";" xparam)
-
- statvalue = "TENTATIVE" ;Indicates event is
- ;tentative.
- / "CONFIRMED" ;Indicates event is
- ;definite.
- / "CANCELLED" ;Indicates event was
- ;cancelled.
- ;Status values for a "VEVENT"
-
-
-
-Dawson & Stenerson Standards Track [Page 88]
-
-RFC 2445 iCalendar November 1998
-
-
- statvalue =/ "NEEDS-ACTION" ;Indicates to-do needs action.
- / "COMPLETED" ;Indicates to-do completed.
- / "IN-PROCESS" ;Indicates to-do in process of
- / "CANCELLED" ;Indicates to-do was cancelled.
- ;Status values for "VTODO".
-
- statvalue =/ "DRAFT" ;Indicates journal is draft.
- / "FINAL" ;Indicates journal is final.
- / "CANCELLED" ;Indicates journal is removed.
- ;Status values for "VJOURNAL".
-
- Example: The following is an example of this property for a "VEVENT"
- calendar component:
-
- STATUS:TENTATIVE
-
- The following is an example of this property for a "VTODO" calendar
- component:
-
- STATUS:NEEDS-ACTION
-
- The following is an example of this property for a "VJOURNAL"
- calendar component:
-
- STATUS:DRAFT
-
-4.8.1.12 Summary
-
- Property Name: SUMMARY
-
- Purpose: This property defines a short summary or subject for the
- calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: The property can be specified in "VEVENT", "VTODO",
- "VJOURNAL" or "VALARM" calendar components.
-
- Description: This property is used in the "VEVENT", "VTODO" and
- "VJOURNAL" calendar components to capture a short, one line summary
- about the activity or journal entry.
-
- This property is used in the "VALARM" calendar component to capture
- the subject of an EMAIL category of alarm.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 89]
-
-RFC 2445 iCalendar November 1998
-
-
- Format Definition: The property is defined by the following notation:
-
- summary = "SUMMARY" summparam ":" text CRLF
-
- summparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following is an example of this property:
-
- SUMMARY:Department Party
-
-4.8.2 Date and Time Component Properties
-
- The following properties specify date and time related information in
- calendar components.
-
-4.8.2.1 Date/Time Completed
-
- Property Name: COMPLETED
-
- Purpose: This property defines the date and time that a to-do was
- actually completed.
-
- Value Type: DATE-TIME
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified in a "VTODO" calendar
- component.
-
- Description: The date and time MUST be in a UTC format.
-
- Format Definition: The property is defined by the following notation:
-
- completed = "COMPLETED" compparam ":" date-time CRLF
-
-
-
-
-Dawson & Stenerson Standards Track [Page 90]
-
-RFC 2445 iCalendar November 1998
-
-
- compparam = *(";" xparam)
-
- Example: The following is an example of this property:
-
- COMPLETED:19960401T235959Z
-
-4.8.2.2 Date/Time End
-
- Property Name: DTEND
-
- Purpose: This property specifies the date and time that a calendar
- component ends.
-
- Value Type: The default value type is DATE-TIME. The value type can
- be set to a DATE value type.
-
- Property Parameters: Non-standard, value data type, time zone
- identifier property parameters can be specified on this property.
-
- Conformance: This property can be specified in "VEVENT" or
- "VFREEBUSY" calendar components.
-
- Description: Within the "VEVENT" calendar component, this property
- defines the date and time by which the event ends. The value MUST be
- later in time than the value of the "DTSTART" property.
-
- Within the "VFREEBUSY" calendar component, this property defines the
- end date and time for the free or busy time information. The time
- MUST be specified in the UTC time format. The value MUST be later in
- time than the value of the "DTSTART" property.
-
- Format Definition: The property is defined by the following notation:
-
- dtend = "DTEND" dtendparam":" dtendval CRLF
-
- dtendparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
- (";" tzidparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 91]
-
-RFC 2445 iCalendar November 1998
-
-
- (";" xparam)
-
- )
-
-
-
- dtendval = date-time / date
- ;Value MUST match value type
-
- Example: The following is an example of this property:
-
- DTEND:19960401T235959Z
-
- DTEND;VALUE=DATE:19980704
-
-4.8.2.3 Date/Time Due
-
- Property Name: DUE
-
- Purpose: This property defines the date and time that a to-do is
- expected to be completed.
-
- Value Type: The default value type is DATE-TIME. The value type can
- be set to a DATE value type.
-
- Property Parameters: Non-standard, value data type, time zone
- identifier property parameters can be specified on this property.
-
- Conformance: The property can be specified once in a "VTODO" calendar
- component.
-
- Description: The value MUST be a date/time equal to or after the
- DTSTART value, if specified.
-
- Format Definition: The property is defined by the following notation:
-
- due = "DUE" dueparam":" dueval CRLF
-
- dueparam = *(
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
- (";" tzidparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
-
-
-
-Dawson & Stenerson Standards Track [Page 92]
-
-RFC 2445 iCalendar November 1998
-
-
- *(";" xparam)
-
- )
-
-
-
- dueval = date-time / date
- ;Value MUST match value type
-
- Example: The following is an example of this property:
-
- DUE:19980430T235959Z
-
-4.8.2.4 Date/Time Start
-
- Property Name: DTSTART
-
- Purpose: This property specifies when the calendar component begins.
-
- Value Type: The default value type is DATE-TIME. The time value MUST
- be one of the forms defined for the DATE-TIME value type. The value
- type can be set to a DATE value type.
-
- Property Parameters: Non-standard, value data type, time zone
- identifier property parameters can be specified on this property.
-
- Conformance: This property can be specified in the "VEVENT", "VTODO",
- "VFREEBUSY", or "VTIMEZONE" calendar components.
-
- Description: Within the "VEVENT" calendar component, this property
- defines the start date and time for the event. The property is
- REQUIRED in "VEVENT" calendar components. Events can have a start
- date/time but no end date/time. In that case, the event does not take
- up any time.
-
- Within the "VFREEBUSY" calendar component, this property defines the
- start date and time for the free or busy time information. The time
- MUST be specified in UTC time.
-
- Within the "VTIMEZONE" calendar component, this property defines the
- effective start date and time for a time zone specification. This
- property is REQUIRED within each STANDARD and DAYLIGHT part included
- in "VTIMEZONE" calendar components and MUST be specified as a local
- DATE-TIME without the "TZID" property parameter.
-
- Format Definition: The property is defined by the following notation:
-
- dtstart = "DTSTART" dtstparam ":" dtstval CRLF
-
-
-
-Dawson & Stenerson Standards Track [Page 93]
-
-RFC 2445 iCalendar November 1998
-
-
- dtstparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
- (";" tzidparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- *(";" xparam)
-
- )
-
-
-
- dtstval = date-time / date
- ;Value MUST match value type
-
- Example: The following is an example of this property:
-
- DTSTART:19980118T073000Z
-
-4.8.2.5 Duration
-
- Property Name: DURATION
-
- Purpose: The property specifies a positive duration of time.
-
- Value Type: DURATION
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified in "VEVENT", "VTODO",
- "VFREEBUSY" or "VALARM" calendar components.
-
- Description: In a "VEVENT" calendar component the property may be
- used to specify a duration of the event, instead of an explicit end
- date/time. In a "VTODO" calendar component the property may be used
- to specify a duration for the to-do, instead of an explicit due
- date/time. In a "VFREEBUSY" calendar component the property may be
- used to specify the interval of free time being requested. In a
- "VALARM" calendar component the property may be used to specify the
- delay period prior to repeating an alarm.
-
- Format Definition: The property is defined by the following notation:
-
-
-
-Dawson & Stenerson Standards Track [Page 94]
-
-RFC 2445 iCalendar November 1998
-
-
- duration = "DURATION" durparam ":" dur-value CRLF
- ;consisting of a positive duration of time.
-
- durparam = *(";" xparam)
-
- Example: The following is an example of this property that specifies
- an interval of time of 1 hour and zero minutes and zero seconds:
-
- DURATION:PT1H0M0S
-
- The following is an example of this property that specifies an
- interval of time of 15 minutes.
-
- DURATION:PT15M
-
-4.8.2.6 Free/Busy Time
-
- Property Name: FREEBUSY
-
- Purpose: The property defines one or more free or busy time
- intervals.
-
- Value Type: PERIOD. The date and time values MUST be in an UTC time
- format.
-
- Property Parameters: Non-standard or free/busy time type property
- parameters can be specified on this property.
-
- Conformance: The property can be specified in a "VFREEBUSY" calendar
- component.
-
- Property Parameter: "FBTYPE" and non-standard parameters can be
- specified on this property.
-
- Description: These time periods can be specified as either a start
- and end date-time or a start date-time and duration. The date and
- time MUST be a UTC time format.
-
- "FREEBUSY" properties within the "VFREEBUSY" calendar component
- SHOULD be sorted in ascending order, based on start time and then end
- time, with the earliest periods first.
-
- The "FREEBUSY" property can specify more than one value, separated by
- the COMMA character (US-ASCII decimal 44). In such cases, the
- "FREEBUSY" property values SHOULD all be of the same "FBTYPE"
- property parameter type (e.g., all values of a particular "FBTYPE"
- listed together in a single property).
-
-
-
-
-Dawson & Stenerson Standards Track [Page 95]
-
-RFC 2445 iCalendar November 1998
-
-
- Format Definition: The property is defined by the following notation:
-
- freebusy = "FREEBUSY" fbparam ":" fbvalue
- CRLF
-
- fbparam = *(
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- (";" fbtypeparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- fbvalue = period *["," period]
- ;Time value MUST be in the UTC time format.
-
- Example: The following are some examples of this property:
-
- FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:19970308T160000Z/PT8H30M
-
- FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H
-
- FREEBUSY;FBTYPE=FREE:19970308T160000Z/PT3H,19970308T200000Z/PT1H,
- 19970308T230000Z/19970309T000000Z
-
-4.8.2.7 Time Transparency
-
- Property Name: TRANSP
-
- Purpose: This property defines whether an event is transparent or not
- to busy time searches.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified once in a "VEVENT"
- calendar component.
-
- Description: Time Transparency is the characteristic of an event that
- determines whether it appears to consume time on a calendar. Events
- that consume actual time for the individual or resource associated
-
-
-
-Dawson & Stenerson Standards Track [Page 96]
-
-RFC 2445 iCalendar November 1998
-
-
- with the calendar SHOULD be recorded as OPAQUE, allowing them to be
- detected by free-busy time searches. Other events, which do not take
- up the individual's (or resource's) time SHOULD be recorded as
- TRANSPARENT, making them invisible to free-busy time searches.
-
- Format Definition: The property is specified by the following
- notation:
-
- transp = "TRANSP" tranparam ":" transvalue CRLF
-
- tranparam = *(";" xparam)
-
- transvalue = "OPAQUE" ;Blocks or opaque on busy time searches.
- / "TRANSPARENT" ;Transparent on busy time searches.
- ;Default value is OPAQUE
-
- Example: The following is an example of this property for an event
- that is transparent or does not block on free/busy time searches:
-
- TRANSP:TRANSPARENT
-
- The following is an example of this property for an event that is
- opaque or blocks on free/busy time searches:
-
- TRANSP:OPAQUE
-
-4.8.3 Time Zone Component Properties
-
- The following properties specify time zone information in calendar
- components.
-
-4.8.3.1 Time Zone Identifier
-
- Property Name: TZID
-
- Purpose: This property specifies the text value that uniquely
- identifies the "VTIMEZONE" calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property MUST be specified in a "VTIMEZONE"
- calendar component.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 97]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: This is the label by which a time zone calendar
- component is referenced by any iCalendar properties whose data type
- is either DATE-TIME or TIME and not intended to specify a UTC or a
- "floating" time. The presence of the SOLIDUS character (US-ASCII
- decimal 47) as a prefix, indicates that this TZID represents an
- unique ID in a globally defined time zone registry (when such
- registry is defined).
-
- Note: This document does not define a naming convention for time
- zone identifiers. Implementers may want to use the naming
- conventions defined in existing time zone specifications such as
- the public-domain Olson database [TZ]. The specification of
- globally unique time zone identifiers is not addressed by this
- document and is left for future study.
-
- Format Definition: This property is defined by the following
- notation:
-
- tzid = "TZID" tzidpropparam ":" [tzidprefix] text CRLF
-
- tzidpropparam = *(";" xparam)
-
- ;tzidprefix = "/"
- ; Defined previously. Just listed here for reader convenience.
-
- Example: The following are examples of non-globally unique time zone
- identifiers:
-
- TZID:US-Eastern
-
- TZID:California-Los_Angeles
-
- The following is an example of a fictitious globally unique time zone
- identifier:
-
- TZID:/US-New_York-New_York
-
-4.8.3.2 Time Zone Name
-
- Property Name: TZNAME
-
- Purpose: This property specifies the customary designation for a time
- zone description.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard and language property parameters
- can be specified on this property.
-
-
-
-Dawson & Stenerson Standards Track [Page 98]
-
-RFC 2445 iCalendar November 1998
-
-
- Conformance: This property can be specified in a "VTIMEZONE" calendar
- component.
-
- Description: This property may be specified in multiple languages; in
- order to provide for different language requirements.
-
- Format Definition: This property is defined by the following
- notation:
-
- tzname = "TZNAME" tznparam ":" text CRLF
-
- tznparam = *(
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following are example of this property:
-
- TZNAME:EST
-
- The following is an example of this property when two different
- languages for the time zone name are specified:
-
- TZNAME;LANGUAGE=en:EST
- TZNAME;LANGUAGE=fr-CA:HNE
-
-4.8.3.3 Time Zone Offset From
-
- Property Name: TZOFFSETFROM
-
- Purpose: This property specifies the offset which is in use prior to
- this time zone observance.
-
- Value Type: UTC-OFFSET
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 99]
-
-RFC 2445 iCalendar November 1998
-
-
- Conformance: This property MUST be specified in a "VTIMEZONE"
- calendar component.
-
- Description: This property specifies the offset which is in use prior
- to this time observance. It is used to calculate the absolute time at
- which the transition to a given observance takes place. This property
- MUST only be specified in a "VTIMEZONE" calendar component. A
- "VTIMEZONE" calendar component MUST include this property. The
- property value is a signed numeric indicating the number of hours and
- possibly minutes from UTC. Positive numbers represent time zones east
- of the prime meridian, or ahead of UTC. Negative numbers represent
- time zones west of the prime meridian, or behind UTC.
-
- Format Definition: The property is defined by the following notation:
-
- tzoffsetfrom = "TZOFFSETFROM" frmparam ":" utc-offset
- CRLF
-
- frmparam = *(";" xparam)
-
- Example: The following are examples of this property:
-
- TZOFFSETFROM:-0500
-
- TZOFFSETFROM:+1345
-
-4.8.3.4 Time Zone Offset To
-
- Property Name: TZOFFSETTO
-
- Purpose: This property specifies the offset which is in use in this
- time zone observance.
-
- Value Type: UTC-OFFSET
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property MUST be specified in a "VTIMEZONE"
- calendar component.
-
- Description: This property specifies the offset which is in use in
- this time zone observance. It is used to calculate the absolute time
- for the new observance. The property value is a signed numeric
- indicating the number of hours and possibly minutes from UTC.
- Positive numbers represent time zones east of the prime meridian, or
- ahead of UTC. Negative numbers represent time zones west of the prime
- meridian, or behind UTC.
-
-
-
-Dawson & Stenerson Standards Track [Page 100]
-
-RFC 2445 iCalendar November 1998
-
-
- Format Definition: The property is defined by the following notation:
-
- tzoffsetto = "TZOFFSETTO" toparam ":" utc-offset CRLF
-
- toparam = *(";" xparam)
-
- Example: The following are examples of this property:
-
- TZOFFSETTO:-0400
-
- TZOFFSETTO:+1245
-
-4.8.3.5 Time Zone URL
-
- Property Name: TZURL
-
- Purpose: The TZURL provides a means for a VTIMEZONE component to
- point to a network location that can be used to retrieve an up-to-
- date version of itself.
-
- Value Type: URI
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in a "VTIMEZONE" calendar
- component.
-
- Description: The TZURL provides a means for a VTIMEZONE component to
- point to a network location that can be used to retrieve an up-to-
- date version of itself. This provides a hook to handle changes
- government bodies impose upon time zone definitions. Retrieval of
- this resource results in an iCalendar object containing a single
- VTIMEZONE component and a METHOD property set to PUBLISH.
-
- Format Definition: The property is defined by the following notation:
-
- tzurl = "TZURL" tzurlparam ":" uri CRLF
-
- tzurlparam = *(";" xparam)
-
- Example: The following is an example of this property:
-
- TZURL:http://timezones.r.us.net/tz/US-California-Los_Angeles
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 101]
-
-RFC 2445 iCalendar November 1998
-
-
-4.8.4 Relationship Component Properties
-
- The following properties specify relationship information in calendar
- components.
-
-4.8.4.1 Attendee
-
- Property Name: ATTENDEE
-
- Purpose: The property defines an "Attendee" within a calendar
- component.
-
- Value Type: CAL-ADDRESS
-
- Property Parameters: Non-standard, language, calendar user type,
- group or list membership, participation role, participation status,
- RSVP expectation, delegatee, delegator, sent by, common name or
- directory entry reference property parameters can be specified on
- this property.
-
- Conformance: This property MUST be specified in an iCalendar object
- that specifies a group scheduled calendar entity. This property MUST
- NOT be specified in an iCalendar object when publishing the calendar
- information (e.g., NOT in an iCalendar object that specifies the
- publication of a calendar user's busy time, event, to-do or journal).
- This property is not specified in an iCalendar object that specifies
- only a time zone definition or that defines calendar entities that
- are not group scheduled entities, but are entities only on a single
- user's calendar.
-
- Description: The property MUST only be specified within calendar
- components to specify participants, non-participants and the chair of
- a group scheduled calendar entity. The property is specified within
- an "EMAIL" category of the "VALARM" calendar component to specify an
- email address that is to receive the email type of iCalendar alarm.
-
- The property parameter CN is for the common or displayable name
- associated with the calendar address; ROLE, for the intended role
- that the attendee will have in the calendar component; PARTSTAT, for
- the status of the attendee's participation; RSVP, for indicating
- whether the favor of a reply is requested; CUTYPE, to indicate the
- type of calendar user; MEMBER, to indicate the groups that the
- attendee belongs to; DELEGATED-TO, to indicate the calendar users
- that the original request was delegated to; and DELEGATED-FROM, to
- indicate whom the request was delegated from; SENT-BY, to indicate
- whom is acting on behalf of the ATTENDEE; and DIR, to indicate the
- URI that points to the directory information corresponding to the
- attendee. These property parameters can be specified on an "ATTENDEE"
-
-
-
-Dawson & Stenerson Standards Track [Page 102]
-
-RFC 2445 iCalendar November 1998
-
-
- property in either a "VEVENT", "VTODO" or "VJOURNAL" calendar
- component. They MUST not be specified in an "ATTENDEE" property in a
- "VFREEBUSY" or "VALARM" calendar component. If the LANGUAGE property
- parameter is specified, the identified language applies to the CN
- parameter.
-
- A recipient delegated a request MUST inherit the RSVP and ROLE values
- from the attendee that delegated the request to them.
-
- Multiple attendees can be specified by including multiple "ATTENDEE"
- properties within the calendar component.
-
- Format Definition: The property is defined by the following notation:
-
- attendee = "ATTENDEE" attparam ":" cal-address CRLF
-
- attparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" cutypeparam) / (";"memberparam) /
- (";" roleparam) / (";" partstatparam) /
- (";" rsvpparam) / (";" deltoparam) /
- (";" delfromparam) / (";" sentbyparam) /
- (";"cnparam) / (";" dirparam) /
- (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following are examples of this property's use for a to-
- do:
-
- ORGANIZER:MAILTO:jsmith at host1.com
- ATTENDEE;MEMBER="MAILTO:DEV-GROUP at host2.com":
- MAILTO:joecool at host2.com
- ATTENDEE;DELEGATED-FROM="MAILTO:immud at host3.com":
- MAILTO:ildoit at host1.com
-
- The following is an example of this property used for specifying
- multiple attendees to an event:
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 103]
-
-RFC 2445 iCalendar November 1998
-
-
- ORGANIZER:MAILTO:jsmith at host1.com
- ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;CN=Henry Cabot
- :MAILTO:hcabot at host2.com
- ATTENDEE;ROLE=REQ-PARTICIPANT;DELEGATED-FROM="MAILTO:bob at host.com"
- ;PARTSTAT=ACCEPTED;CN=Jane Doe:MAILTO:jdoe at host1.com
-
- The following is an example of this property with a URI to the
- directory information associated with the attendee:
-
- ATTENDEE;CN=John Smith;DIR="ldap://host.com:6666/o=eDABC%
- 20Industries,c=3DUS??(cn=3DBJim%20Dolittle)":MAILTO:jimdo@
- host1.com
-
- The following is an example of this property with "delegatee" and
- "delegator" information for an event:
-
- ORGANIZER;CN=John Smith:MAILTO:jsmith at host.com
- ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=TENTATIVE;DELEGATED-FROM=
- "MAILTO:iamboss at host2.com";CN=Henry Cabot:MAILTO:hcabot@
- host2.com
- ATTENDEE;ROLE=NON-PARTICIPANT;PARTSTAT=DELEGATED;DELEGATED-TO=
- "MAILTO:hcabot at host2.com";CN=The Big Cheese:MAILTO:iamboss
- @host2.com
- ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Jane Doe
- :MAILTO:jdoe at host1.com
-
- Example: The following is an example of this property's use when
- another calendar user is acting on behalf of the "Attendee":
-
- ATTENDEE;SENT-BY=MAILTO:jan_doe at host1.com;CN=John Smith:MAILTO:
- jsmith at host1.com
-
-4.8.4.2 Contact
-
- Property Name: CONTACT
-
- Purpose: The property is used to represent contact information or
- alternately a reference to contact information associated with the
- calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard, alternate text representation and
- language property parameters can be specified on this property.
-
- Conformance: The property can be specified in a "VEVENT", "VTODO",
- "VJOURNAL" or "VFREEBUSY" calendar component.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 104]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: The property value consists of textual contact
- information. An alternative representation for the property value can
- also be specified that refers to a URI pointing to an alternate form,
- such as a vCard [RFC 2426], for the contact information.
-
- Format Definition: The property is defined by the following notation:
-
- contact = "CONTACT" contparam ":" text CRLF
-
- contparam = *(
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" altrepparam) / (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following is an example of this property referencing
- textual contact information:
-
- CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234
-
- The following is an example of this property with an alternate
- representation of a LDAP URI to a directory entry containing the
- contact information:
-
- CONTACT;ALTREP="ldap://host.com:6666/o=3DABC%20Industries\,
- c=3DUS??(cn=3DBJim%20Dolittle)":Jim Dolittle\, ABC Industries\,
- +1-919-555-1234
-
- The following is an example of this property with an alternate
- representation of a MIME body part containing the contact
- information, such as a vCard [RFC 2426] embedded in a [MIME-DIR]
- content-type:
-
- CONTACT;ALTREP="CID=<part3.msg970930T083000SILVER at host.com>":Jim
- Dolittle\, ABC Industries\, +1-919-555-1234
-
- The following is an example of this property referencing a network
- resource, such as a vCard [RFC 2426] object containing the contact
- information:
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 105]
-
-RFC 2445 iCalendar November 1998
-
-
- CONTACT;ALTREP="http://host.com/pdi/jdoe.vcf":Jim
- Dolittle\, ABC Industries\, +1-919-555-1234
-
-4.8.4.3 Organizer
-
- Property Name: ORGANIZER
-
- Purpose: The property defines the organizer for a calendar component.
-
- Value Type: CAL-ADDRESS
-
- Property Parameters: Non-standard, language, common name, directory
- entry reference, sent by property parameters can be specified on this
- property.
-
- Conformance: This property MUST be specified in an iCalendar object
- that specifies a group scheduled calendar entity. This property MUST
- be specified in an iCalendar object that specifies the publication of
- a calendar user's busy time. This property MUST NOT be specified in
- an iCalendar object that specifies only a time zone definition or
- that defines calendar entities that are not group scheduled entities,
- but are entities only on a single user's calendar.
-
- Description: The property is specified within the "VEVENT", "VTODO",
- "VJOURNAL calendar components to specify the organizer of a group
- scheduled calendar entity. The property is specified within the
- "VFREEBUSY" calendar component to specify the calendar user
- requesting the free or busy time. When publishing a "VFREEBUSY"
- calendar component, the property is used to specify the calendar that
- the published busy time came from.
-
- The property has the property parameters CN, for specifying the
- common or display name associated with the "Organizer", DIR, for
- specifying a pointer to the directory information associated with the
- "Organizer", SENT-BY, for specifying another calendar user that is
- acting on behalf of the "Organizer". The non-standard parameters may
- also be specified on this property. If the LANGUAGE property
- parameter is specified, the identified language applies to the CN
- parameter value.
-
- Format Definition: The property is defined by the following notation:
-
- organizer = "ORGANIZER" orgparam ":"
- cal-address CRLF
-
- orgparam = *(
-
- ; the following are optional,
-
-
-
-Dawson & Stenerson Standards Track [Page 106]
-
-RFC 2445 iCalendar November 1998
-
-
- ; but MUST NOT occur more than once
-
- (";" cnparam) / (";" dirparam) / (";" sentbyparam) /
- (";" languageparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- Example: The following is an example of this property:
-
- ORGANIZER;CN=John Smith:MAILTO:jsmith at host1.com
-
- The following is an example of this property with a pointer to the
- directory information associated with the organizer:
-
- ORGANIZER;CN=JohnSmith;DIR="ldap://host.com:6666/o=3DDC%20Associ
- ates,c=3DUS??(cn=3DJohn%20Smith)":MAILTO:jsmith at host1.com
-
- The following is an example of this property used by another calendar
- user who is acting on behalf of the organizer, with responses
- intended to be sent back to the organizer, not the other calendar
- user:
-
- ORGANIZER;SENT-BY="MAILTO:jane_doe at host.com":
- MAILTO:jsmith at host1.com
-
-4.8.4.4 Recurrence ID
-
- Property Name: RECURRENCE-ID
-
- Purpose: This property is used in conjunction with the "UID" and
- "SEQUENCE" property to identify a specific instance of a recurring
- "VEVENT", "VTODO" or "VJOURNAL" calendar component. The property
- value is the effective value of the "DTSTART" property of the
- recurrence instance.
-
- Value Type: The default value type for this property is DATE-TIME.
- The time format can be any of the valid forms defined for a DATE-TIME
- value type. See DATE-TIME value type definition for specific
- interpretations of the various forms. The value type can be set to
- DATE.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 107]
-
-RFC 2445 iCalendar November 1998
-
-
- Property Parameters: Non-standard property, value data type, time
- zone identifier and recurrence identifier range parameters can be
- specified on this property.
-
- Conformance: This property can be specified in an iCalendar object
- containing a recurring calendar component.
-
- Description: The full range of calendar components specified by a
- recurrence set is referenced by referring to just the "UID" property
- value corresponding to the calendar component. The "RECURRENCE-ID"
- property allows the reference to an individual instance within the
- recurrence set.
-
- If the value of the "DTSTART" property is a DATE type value, then the
- value MUST be the calendar date for the recurrence instance.
-
- The date/time value is set to the time when the original recurrence
- instance would occur; meaning that if the intent is to change a
- Friday meeting to Thursday, the date/time is still set to the
- original Friday meeting.
-
- The "RECURRENCE-ID" property is used in conjunction with the "UID"
- and "SEQUENCE" property to identify a particular instance of a
- recurring event, to-do or journal. For a given pair of "UID" and
- "SEQUENCE" property values, the "RECURRENCE-ID" value for a
- recurrence instance is fixed. When the definition of the recurrence
- set for a calendar component changes, and hence the "SEQUENCE"
- property value changes, the "RECURRENCE-ID" for a given recurrence
- instance might also change.The "RANGE" parameter is used to specify
- the effective range of recurrence instances from the instance
- specified by the "RECURRENCE-ID" property value. The default value
- for the range parameter is the single recurrence instance only. The
- value can also be "THISANDPRIOR" to indicate a range defined by the
- given recurrence instance and all prior instances or the value can be
- "THISANDFUTURE" to indicate a range defined by the given recurrence
- instance and all subsequent instances.
-
- Format Definition: The property is defined by the following notation:
-
- recurid = "RECURRENCE-ID" ridparam ":" ridval CRLF
-
- ridparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE)) /
- (";" tzidparam) / (";" rangeparam) /
-
-
-
-Dawson & Stenerson Standards Track [Page 108]
-
-RFC 2445 iCalendar November 1998
-
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- ridval = date-time / date
- ;Value MUST match value type
-
- Example: The following are examples of this property:
-
- RECURRENCE-ID;VALUE=DATE:19960401
-
- RECURRENCE-ID;RANGE=THISANDFUTURE:19960120T120000Z
-
-4.8.4.5 Related To
-
- Property Name: RELATED-TO
-
- Purpose: The property is used to represent a relationship or
- reference between one calendar component and another.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard and relationship type property
- parameters can be specified on this property.
-
- Conformance: The property can be specified one or more times in the
- "VEVENT", "VTODO" or "VJOURNAL" calendar components.
-
- Description: The property value consists of the persistent, globally
- unique identifier of another calendar component. This value would be
- represented in a calendar component by the "UID" property.
-
- By default, the property value points to another calendar component
- that has a PARENT relationship to the referencing object. The
- "RELTYPE" property parameter is used to either explicitly state the
- default PARENT relationship type to the referenced calendar component
- or to override the default PARENT relationship type and specify
- either a CHILD or SIBLING relationship. The PARENT relationship
- indicates that the calendar component is a subordinate of the
- referenced calendar component. The CHILD relationship indicates that
- the calendar component is a superior of the referenced calendar
- component. The SIBLING relationship indicates that the calendar
- component is a peer of the referenced calendar component.
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 109]
-
-RFC 2445 iCalendar November 1998
-
-
- Changes to a calendar component referenced by this property can have
- an implicit impact on the related calendar component. For example, if
- a group event changes its start or end date or time, then the
- related, dependent events will need to have their start and end dates
- changed in a corresponding way. Similarly, if a PARENT calendar
- component is canceled or deleted, then there is an implied impact to
- the related CHILD calendar components. This property is intended only
- to provide information on the relationship of calendar components. It
- is up to the target calendar system to maintain any property
- implications of this relationship.
-
- Format Definition: The property is defined by the following notation:
-
- related = "RELATED-TO" [relparam] ":" text CRLF
-
- relparam = *(
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
- (";" reltypeparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparm)
-
- )
-
- The following is an example of this property:
-
- RELATED-TO:<jsmith.part7.19960817T083000.xyzMail at host3.com>
-
- RELATED-TO:<19960401-080045-4000F192713-0052 at host1.com>
-
-4.8.4.6 Uniform Resource Locator
-
- Property Name: URL
-
- Purpose: This property defines a Uniform Resource Locator (URL)
- associated with the iCalendar object.
-
- Value Type: URI
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 110]
-
-RFC 2445 iCalendar November 1998
-
-
- Conformance: This property can be specified once in the "VEVENT",
- "VTODO", "VJOURNAL" or "VFREEBUSY" calendar components.
-
- Description: This property may be used in a calendar component to
- convey a location where a more dynamic rendition of the calendar
- information associated with the calendar component can be found. This
- memo does not attempt to standardize the form of the URI, nor the
- format of the resource pointed to by the property value. If the URL
- property and Content-Location MIME header are both specified, they
- MUST point to the same resource.
-
- Format Definition: The property is defined by the following notation:
-
- url = "URL" urlparam ":" uri CRLF
-
- urlparam = *(";" xparam)
-
- Example: The following is an example of this property:
-
- URL:http://abc.com/pub/calendars/jsmith/mytime.ics
-
-4.8.4.7 Unique Identifier
-
- Property Name: UID
-
- Purpose: This property defines the persistent, globally unique
- identifier for the calendar component.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property MUST be specified in the "VEVENT", "VTODO",
- "VJOURNAL" or "VFREEBUSY" calendar components.
-
- Description: The UID itself MUST be a globally unique identifier. The
- generator of the identifier MUST guarantee that the identifier is
- unique. There are several algorithms that can be used to accomplish
- this. The identifier is RECOMMENDED to be the identical syntax to the
- [RFC 822] addr-spec. A good method to assure uniqueness is to put the
- domain name or a domain literal IP address of the host on which the
- identifier was created on the right hand side of the "@", and on the
- left hand side, put a combination of the current calendar date and
- time of day (i.e., formatted in as a DATE-TIME value) along with some
- other currently unique (perhaps sequential) identifier available on
- the system (for example, a process id number). Using a date/time
- value on the left hand side and a domain name or domain literal on
-
-
-
-Dawson & Stenerson Standards Track [Page 111]
-
-RFC 2445 iCalendar November 1998
-
-
- the right hand side makes it possible to guarantee uniqueness since
- no two hosts should be using the same domain name or IP address at
- the same time. Though other algorithms will work, it is RECOMMENDED
- that the right hand side contain some domain identifier (either of
- the host itself or otherwise) such that the generator of the message
- identifier can guarantee the uniqueness of the left hand side within
- the scope of that domain.
-
- This is the method for correlating scheduling messages with the
- referenced "VEVENT", "VTODO", or "VJOURNAL" calendar component.
-
- The full range of calendar components specified by a recurrence set
- is referenced by referring to just the "UID" property value
- corresponding to the calendar component. The "RECURRENCE-ID" property
- allows the reference to an individual instance within the recurrence
- set.
-
- This property is an important method for group scheduling
- applications to match requests with later replies, modifications or
- deletion requests. Calendaring and scheduling applications MUST
- generate this property in "VEVENT", "VTODO" and "VJOURNAL" calendar
- components to assure interoperability with other group scheduling
- applications. This identifier is created by the calendar system that
- generates an iCalendar object.
-
- Implementations MUST be able to receive and persist values of at
- least 255 characters for this property.
-
- Format Definition: The property is defined by the following notation:
-
- uid = "UID" uidparam ":" text CRLF
-
- uidparam = *(";" xparam)
-
- Example: The following is an example of this property:
-
- UID:19960401T080045Z-4000F192713-0052 at host1.com
-
-4.8.5 Recurrence Component Properties
-
- The following properties specify recurrence information in calendar
- components.
-
-4.8.5.1 Exception Date/Times
-
- Property Name: EXDATE
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 112]
-
-RFC 2445 iCalendar November 1998
-
-
- Purpose: This property defines the list of date/time exceptions for a
- recurring calendar component.
-
- Value Type: The default value type for this property is DATE-TIME.
- The value type can be set to DATE.
-
- Property Parameters: Non-standard, value data type and time zone
- identifier property parameters can be specified on this property.
-
- Conformance: This property can be specified in an iCalendar object
- that includes a recurring calendar component.
-
- Description: The exception dates, if specified, are used in computing
- the recurrence set. The recurrence set is the complete set of
- recurrence instances for a calendar component. The recurrence set is
- generated by considering the initial "DTSTART" property along with
- the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
- within the iCalendar object. The "DTSTART" property defines the first
- instance in the recurrence set. Multiple instances of the "RRULE" and
- "EXRULE" properties can also be specified to define more
- sophisticated recurrence sets. The final recurrence set is generated
- by gathering all of the start date-times generated by any of the
- specified "RRULE" and "RDATE" properties, and then excluding any
- start date and times which fall within the union of start date and
- times generated by any specified "EXRULE" and "EXDATE" properties.
- This implies that start date and times within exclusion related
- properties (i.e., "EXDATE" and "EXRULE") take precedence over those
- specified by inclusion properties (i.e., "RDATE" and "RRULE"). Where
- duplicate instances are generated by the "RRULE" and "RDATE"
- properties, only one recurrence is considered. Duplicate instances
- are ignored.
-
- The "EXDATE" property can be used to exclude the value specified in
- "DTSTART". However, in such cases the original "DTSTART" date MUST
- still be maintained by the calendaring and scheduling system because
- the original "DTSTART" value has inherent usage dependencies by other
- properties such as the "RECURRENCE-ID".
-
- Format Definition: The property is defined by the following notation:
-
- exdate = "EXDATE" exdtparam ":" exdtval *("," exdtval) CRLF
-
- exdtparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE")) /
-
-
-
-Dawson & Stenerson Standards Track [Page 113]
-
-RFC 2445 iCalendar November 1998
-
-
- (";" tzidparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- exdtval = date-time / date
- ;Value MUST match value type
-
- Example: The following is an example of this property:
-
- EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z
-
-4.8.5.2 Exception Rule
-
- Property Name: EXRULE
-
- Purpose: This property defines a rule or repeating pattern for an
- exception to a recurrence set.
-
- Value Type: RECUR
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in "VEVENT", "VTODO" or
- "VJOURNAL" calendar components.
-
- Description: The exception rule, if specified, is used in computing
- the recurrence set. The recurrence set is the complete set of
- recurrence instances for a calendar component. The recurrence set is
- generated by considering the initial "DTSTART" property along with
- the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
- within the iCalendar object. The "DTSTART" defines the first instance
- in the recurrence set. Multiple instances of the "RRULE" and "EXRULE"
- properties can also be specified to define more sophisticated
- recurrence sets. The final recurrence set is generated by gathering
- all of the start date-times generated by any of the specified "RRULE"
- and "RDATE" properties, and excluding any start date and times which
- fall within the union of start date and times generated by any
- specified "EXRULE" and "EXDATE" properties. This implies that start
- date and times within exclusion related properties (i.e., "EXDATE"
- and "EXRULE") take precedence over those specified by inclusion
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 114]
-
-RFC 2445 iCalendar November 1998
-
-
- properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are
- generated by the "RRULE" and "RDATE" properties, only one recurrence
- is considered. Duplicate instances are ignored.
-
- The "EXRULE" property can be used to exclude the value specified in
- "DTSTART". However, in such cases the original "DTSTART" date MUST
- still be maintained by the calendaring and scheduling system because
- the original "DTSTART" value has inherent usage dependencies by other
- properties such as the "RECURRENCE-ID".
-
- Format Definition: The property is defined by the following notation:
-
- exrule = "EXRULE" exrparam ":" recur CRLF
-
- exrparam = *(";" xparam)
-
- Example: The following are examples of this property. Except every
- other week, on Tuesday and Thursday for 4 occurrences:
-
- EXRULE:FREQ=WEEKLY;COUNT=4;INTERVAL=2;BYDAY=TU,TH
-
- Except daily for 10 occurrences:
-
- EXRULE:FREQ=DAILY;COUNT=10
-
- Except yearly in June and July for 8 occurrences:
-
- EXRULE:FREQ=YEARLY;COUNT=8;BYMONTH=6,7
-
-4.8.5.3 Recurrence Date/Times
-
- Property Name: RDATE
-
- Purpose: This property defines the list of date/times for a
- recurrence set.
-
- Value Type: The default value type for this property is DATE-TIME.
- The value type can be set to DATE or PERIOD.
-
- Property Parameters: Non-standard, value data type and time zone
- identifier property parameters can be specified on this property.
-
- Conformance: The property can be specified in "VEVENT", "VTODO",
- "VJOURNAL" or "VTIMEZONE" calendar components.
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 115]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: This property can appear along with the "RRULE" property
- to define an aggregate set of repeating occurrences. When they both
- appear in an iCalendar object, the recurring events are defined by
- the union of occurrences defined by both the "RDATE" and "RRULE".
-
- The recurrence dates, if specified, are used in computing the
- recurrence set. The recurrence set is the complete set of recurrence
- instances for a calendar component. The recurrence set is generated
- by considering the initial "DTSTART" property along with the "RRULE",
- "RDATE", "EXDATE" and "EXRULE" properties contained within the
- iCalendar object. The "DTSTART" property defines the first instance
- in the recurrence set. Multiple instances of the "RRULE" and "EXRULE"
- properties can also be specified to define more sophisticated
- recurrence sets. The final recurrence set is generated by gathering
- all of the start date/times generated by any of the specified "RRULE"
- and "RDATE" properties, and excluding any start date/times which fall
- within the union of start date/times generated by any specified
- "EXRULE" and "EXDATE" properties. This implies that start date/times
- within exclusion related properties (i.e., "EXDATE" and "EXRULE")
- take precedence over those specified by inclusion properties (i.e.,
- "RDATE" and "RRULE"). Where duplicate instances are generated by the
- "RRULE" and "RDATE" properties, only one recurrence is considered.
- Duplicate instances are ignored.
-
- Format Definition: The property is defined by the following notation:
-
- rdate = "RDATE" rdtparam ":" rdtval *("," rdtval) CRLF
-
- rdtparam = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" ("DATE-TIME" / "DATE" / "PERIOD")) /
- (";" tzidparam) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- rdtval = date-time / date / period
- ;Value MUST match value type
-
- Example: The following are examples of this property:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 116]
-
-RFC 2445 iCalendar November 1998
-
-
- RDATE:19970714T123000Z
-
- RDATE;TZID=US-EASTERN:19970714T083000
-
- RDATE;VALUE=PERIOD:19960403T020000Z/19960403T040000Z,
- 19960404T010000Z/PT3H
-
- RDATE;VALUE=DATE:19970101,19970120,19970217,19970421
- 19970526,19970704,19970901,19971014,19971128,19971129,19971225
-
-4.8.5.4 Recurrence Rule
-
- Property Name: RRULE
-
- Purpose: This property defines a rule or repeating pattern for
- recurring events, to-dos, or time zone definitions.
-
- Value Type: RECUR
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified one or more times in
- recurring "VEVENT", "VTODO" and "VJOURNAL" calendar components. It
- can also be specified once in each STANDARD or DAYLIGHT sub-component
- of the "VTIMEZONE" calendar component.
-
- Description: The recurrence rule, if specified, is used in computing
- the recurrence set. The recurrence set is the complete set of
- recurrence instances for a calendar component. The recurrence set is
- generated by considering the initial "DTSTART" property along with
- the "RRULE", "RDATE", "EXDATE" and "EXRULE" properties contained
- within the iCalendar object. The "DTSTART" property defines the first
- instance in the recurrence set. Multiple instances of the "RRULE" and
- "EXRULE" properties can also be specified to define more
- sophisticated recurrence sets. The final recurrence set is generated
- by gathering all of the start date/times generated by any of the
- specified "RRULE" and "RDATE" properties, and excluding any start
- date/times which fall within the union of start date/times generated
- by any specified "EXRULE" and "EXDATE" properties. This implies that
- start date/times within exclusion related properties (i.e., "EXDATE"
- and "EXRULE") take precedence over those specified by inclusion
- properties (i.e., "RDATE" and "RRULE"). Where duplicate instances are
- generated by the "RRULE" and "RDATE" properties, only one recurrence
- is considered. Duplicate instances are ignored.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 117]
-
-RFC 2445 iCalendar November 1998
-
-
- The "DTSTART" and "DTEND" property pair or "DTSTART" and "DURATION"
- property pair, specified within the iCalendar object defines the
- first instance of the recurrence. When used with a recurrence rule,
- the "DTSTART" and "DTEND" properties MUST be specified in local time
- and the appropriate set of "VTIMEZONE" calendar components MUST be
- included. For detail on the usage of the "VTIMEZONE" calendar
- component, see the "VTIMEZONE" calendar component definition.
-
- Any duration associated with the iCalendar object applies to all
- members of the generated recurrence set. Any modified duration for
- specific recurrences MUST be explicitly specified using the "RDATE"
- property.
-
- Format Definition: This property is defined by the following
- notation:
-
- rrule = "RRULE" rrulparam ":" recur CRLF
-
- rrulparam = *(";" xparam)
-
- Example: All examples assume the Eastern United States time zone.
-
- Daily for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=DAILY;COUNT=10
-
- ==> (1997 9:00 AM EDT)September 2-11
-
- Daily until December 24, 1997:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
-
- ==> (1997 9:00 AM EDT)September 2-30;October 1-25
- (1997 9:00 AM EST)October 26-31;November 1-30;December 1-23
-
- Every other day - forever:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=DAILY;INTERVAL=2
- ==> (1997 9:00 AM EDT)September2,4,6,8...24,26,28,30;
- October 2,4,6...20,22,24
- (1997 9:00 AM EST)October 26,28,30;November 1,3,5,7...25,27,29;
- Dec 1,3,...
-
- Every 10 days, 5 occurrences:
-
-
-
-
-Dawson & Stenerson Standards Track [Page 118]
-
-RFC 2445 iCalendar November 1998
-
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=DAILY;INTERVAL=10;COUNT=5
-
- ==> (1997 9:00 AM EDT)September 2,12,22;October 2,12
-
- Everyday in January, for 3 years:
-
- DTSTART;TZID=US-Eastern:19980101T090000
- RRULE:FREQ=YEARLY;UNTIL=20000131T090000Z;
- BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
- or
- RRULE:FREQ=DAILY;UNTIL=20000131T090000Z;BYMONTH=1
-
- ==> (1998 9:00 AM EDT)January 1-31
- (1999 9:00 AM EDT)January 1-31
- (2000 9:00 AM EDT)January 1-31
-
- Weekly for 10 occurrences
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;COUNT=10
-
- ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
- (1997 9:00 AM EST)October 28;November 4
-
- Weekly until December 24, 1997
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;UNTIL=19971224T000000Z
-
- ==> (1997 9:00 AM EDT)September 2,9,16,23,30;October 7,14,21
- (1997 9:00 AM EST)October 28;November 4,11,18,25;
- December 2,9,16,23
- Every other week - forever:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;INTERVAL=2;WKST=SU
-
- ==> (1997 9:00 AM EDT)September 2,16,30;October 14
- (1997 9:00 AM EST)October 28;November 11,25;December 9,23
- (1998 9:00 AM EST)January 6,20;February
- ...
-
- Weekly on Tuesday and Thursday for 5 weeks:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;UNTIL=19971007T000000Z;WKST=SU;BYDAY=TU,TH
- or
-
-
-
-Dawson & Stenerson Standards Track [Page 119]
-
-RFC 2445 iCalendar November 1998
-
-
- RRULE:FREQ=WEEKLY;COUNT=10;WKST=SU;BYDAY=TU,TH
-
- ==> (1997 9:00 AM EDT)September 2,4,9,11,16,18,23,25,30;October 2
-
- Every other week on Monday, Wednesday and Friday until December 24,
- 1997, but starting on Tuesday, September 2, 1997:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;INTERVAL=2;UNTIL=19971224T000000Z;WKST=SU;
- BYDAY=MO,WE,FR
- ==> (1997 9:00 AM EDT)September 2,3,5,15,17,19,29;October
- 1,3,13,15,17
- (1997 9:00 AM EST)October 27,29,31;November 10,12,14,24,26,28;
- December 8,10,12,22
-
- Every other week on Tuesday and Thursday, for 8 occurrences:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=8;WKST=SU;BYDAY=TU,TH
-
- ==> (1997 9:00 AM EDT)September 2,4,16,18,30;October 2,14,16
-
- Monthly on the 1st Friday for ten occurrences:
-
- DTSTART;TZID=US-Eastern:19970905T090000
- RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
-
- ==> (1997 9:00 AM EDT)September 5;October 3
- (1997 9:00 AM EST)November 7;Dec 5
- (1998 9:00 AM EST)January 2;February 6;March 6;April 3
- (1998 9:00 AM EDT)May 1;June 5
-
- Monthly on the 1st Friday until December 24, 1997:
-
- DTSTART;TZID=US-Eastern:19970905T090000
- RRULE:FREQ=MONTHLY;UNTIL=19971224T000000Z;BYDAY=1FR
-
- ==> (1997 9:00 AM EDT)September 5;October 3
- (1997 9:00 AM EST)November 7;December 5
-
- Every other month on the 1st and last Sunday of the month for 10
- occurrences:
-
- DTSTART;TZID=US-Eastern:19970907T090000
- RRULE:FREQ=MONTHLY;INTERVAL=2;COUNT=10;BYDAY=1SU,-1SU
-
- ==> (1997 9:00 AM EDT)September 7,28
- (1997 9:00 AM EST)November 2,30
-
-
-
-Dawson & Stenerson Standards Track [Page 120]
-
-RFC 2445 iCalendar November 1998
-
-
- (1998 9:00 AM EST)January 4,25;March 1,29
- (1998 9:00 AM EDT)May 3,31
-
- Monthly on the second to last Monday of the month for 6 months:
-
- DTSTART;TZID=US-Eastern:19970922T090000
- RRULE:FREQ=MONTHLY;COUNT=6;BYDAY=-2MO
-
- ==> (1997 9:00 AM EDT)September 22;October 20
- (1997 9:00 AM EST)November 17;December 22
- (1998 9:00 AM EST)January 19;February 16
-
- Monthly on the third to the last day of the month, forever:
-
- DTSTART;TZID=US-Eastern:19970928T090000
- RRULE:FREQ=MONTHLY;BYMONTHDAY=-3
-
- ==> (1997 9:00 AM EDT)September 28
- (1997 9:00 AM EST)October 29;November 28;December 29
- (1998 9:00 AM EST)January 29;February 26
- ...
-
- Monthly on the 2nd and 15th of the month for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=2,15
-
- ==> (1997 9:00 AM EDT)September 2,15;October 2,15
- (1997 9:00 AM EST)November 2,15;December 2,15
- (1998 9:00 AM EST)January 2,15
-
- Monthly on the first and last day of the month for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970930T090000
- RRULE:FREQ=MONTHLY;COUNT=10;BYMONTHDAY=1,-1
-
- ==> (1997 9:00 AM EDT)September 30;October 1
- (1997 9:00 AM EST)October 31;November 1,30;December 1,31
- (1998 9:00 AM EST)January 1,31;February 1
-
- Every 18 months on the 10th thru 15th of the month for 10
- occurrences:
-
- DTSTART;TZID=US-Eastern:19970910T090000
- RRULE:FREQ=MONTHLY;INTERVAL=18;COUNT=10;BYMONTHDAY=10,11,12,13,14,
- 15
-
- ==> (1997 9:00 AM EDT)September 10,11,12,13,14,15
-
-
-
-Dawson & Stenerson Standards Track [Page 121]
-
-RFC 2445 iCalendar November 1998
-
-
- (1999 9:00 AM EST)March 10,11,12,13
-
- Every Tuesday, every other month:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=MONTHLY;INTERVAL=2;BYDAY=TU
-
- ==> (1997 9:00 AM EDT)September 2,9,16,23,30
- (1997 9:00 AM EST)November 4,11,18,25
- (1998 9:00 AM EST)January 6,13,20,27;March 3,10,17,24,31
- ...
-
- Yearly in June and July for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970610T090000
- RRULE:FREQ=YEARLY;COUNT=10;BYMONTH=6,7
- ==> (1997 9:00 AM EDT)June 10;July 10
- (1998 9:00 AM EDT)June 10;July 10
- (1999 9:00 AM EDT)June 10;July 10
- (2000 9:00 AM EDT)June 10;July 10
- (2001 9:00 AM EDT)June 10;July 10
- Note: Since none of the BYDAY, BYMONTHDAY or BYYEARDAY components
- are specified, the day is gotten from DTSTART
-
- Every other year on January, February, and March for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970310T090000
- RRULE:FREQ=YEARLY;INTERVAL=2;COUNT=10;BYMONTH=1,2,3
-
- ==> (1997 9:00 AM EST)March 10
- (1999 9:00 AM EST)January 10;February 10;March 10
- (2001 9:00 AM EST)January 10;February 10;March 10
- (2003 9:00 AM EST)January 10;February 10;March 10
-
- Every 3rd year on the 1st, 100th and 200th day for 10 occurrences:
-
- DTSTART;TZID=US-Eastern:19970101T090000
- RRULE:FREQ=YEARLY;INTERVAL=3;COUNT=10;BYYEARDAY=1,100,200
-
- ==> (1997 9:00 AM EST)January 1
- (1997 9:00 AM EDT)April 10;July 19
- (2000 9:00 AM EST)January 1
- (2000 9:00 AM EDT)April 9;July 18
- (2003 9:00 AM EST)January 1
- (2003 9:00 AM EDT)April 10;July 19
- (2006 9:00 AM EST)January 1
-
- Every 20th Monday of the year, forever:
-
-
-
-Dawson & Stenerson Standards Track [Page 122]
-
-RFC 2445 iCalendar November 1998
-
-
- DTSTART;TZID=US-Eastern:19970519T090000
- RRULE:FREQ=YEARLY;BYDAY=20MO
-
- ==> (1997 9:00 AM EDT)May 19
- (1998 9:00 AM EDT)May 18
- (1999 9:00 AM EDT)May 17
- ...
-
- Monday of week number 20 (where the default start of the week is
- Monday), forever:
-
- DTSTART;TZID=US-Eastern:19970512T090000
- RRULE:FREQ=YEARLY;BYWEEKNO=20;BYDAY=MO
-
- ==> (1997 9:00 AM EDT)May 12
- (1998 9:00 AM EDT)May 11
- (1999 9:00 AM EDT)May 17
- ...
-
- Every Thursday in March, forever:
-
- DTSTART;TZID=US-Eastern:19970313T090000
- RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=TH
-
- ==> (1997 9:00 AM EST)March 13,20,27
- (1998 9:00 AM EST)March 5,12,19,26
- (1999 9:00 AM EST)March 4,11,18,25
- ...
-
- Every Thursday, but only during June, July, and August, forever:
-
- DTSTART;TZID=US-Eastern:19970605T090000
- RRULE:FREQ=YEARLY;BYDAY=TH;BYMONTH=6,7,8
-
- ==> (1997 9:00 AM EDT)June 5,12,19,26;July 3,10,17,24,31;
- August 7,14,21,28
- (1998 9:00 AM EDT)June 4,11,18,25;July 2,9,16,23,30;
- August 6,13,20,27
- (1999 9:00 AM EDT)June 3,10,17,24;July 1,8,15,22,29;
- August 5,12,19,26
- ...
-
- Every Friday the 13th, forever:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- EXDATE;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=MONTHLY;BYDAY=FR;BYMONTHDAY=13
-
-
-
-
-Dawson & Stenerson Standards Track [Page 123]
-
-RFC 2445 iCalendar November 1998
-
-
- ==> (1998 9:00 AM EST)February 13;March 13;November 13
- (1999 9:00 AM EDT)August 13
- (2000 9:00 AM EDT)October 13
- ...
-
- The first Saturday that follows the first Sunday of the month,
- forever:
-
- DTSTART;TZID=US-Eastern:19970913T090000
- RRULE:FREQ=MONTHLY;BYDAY=SA;BYMONTHDAY=7,8,9,10,11,12,13
-
- ==> (1997 9:00 AM EDT)September 13;October 11
- (1997 9:00 AM EST)November 8;December 13
- (1998 9:00 AM EST)January 10;February 7;March 7
- (1998 9:00 AM EDT)April 11;May 9;June 13...
- ...
-
- Every four years, the first Tuesday after a Monday in November,
- forever (U.S. Presidential Election day):
-
- DTSTART;TZID=US-Eastern:19961105T090000
- RRULE:FREQ=YEARLY;INTERVAL=4;BYMONTH=11;BYDAY=TU;BYMONTHDAY=2,3,4,
- 5,6,7,8
-
- ==> (1996 9:00 AM EST)November 5
- (2000 9:00 AM EST)November 7
- (2004 9:00 AM EST)November 2
- ...
-
- The 3rd instance into the month of one of Tuesday, Wednesday or
- Thursday, for the next 3 months:
-
- DTSTART;TZID=US-Eastern:19970904T090000
- RRULE:FREQ=MONTHLY;COUNT=3;BYDAY=TU,WE,TH;BYSETPOS=3
-
- ==> (1997 9:00 AM EDT)September 4;October 7
- (1997 9:00 AM EST)November 6
-
- The 2nd to last weekday of the month:
-
- DTSTART;TZID=US-Eastern:19970929T090000
- RRULE:FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2
-
- ==> (1997 9:00 AM EDT)September 29
- (1997 9:00 AM EST)October 30;November 27;December 30
- (1998 9:00 AM EST)January 29;February 26;March 30
- ...
-
-
-
-
-Dawson & Stenerson Standards Track [Page 124]
-
-RFC 2445 iCalendar November 1998
-
-
- Every 3 hours from 9:00 AM to 5:00 PM on a specific day:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=HOURLY;INTERVAL=3;UNTIL=19970902T170000Z
-
- ==> (September 2, 1997 EDT)09:00,12:00,15:00
-
- Every 15 minutes for 6 occurrences:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=MINUTELY;INTERVAL=15;COUNT=6
-
- ==> (September 2, 1997 EDT)09:00,09:15,09:30,09:45,10:00,10:15
-
- Every hour and a half for 4 occurrences:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=MINUTELY;INTERVAL=90;COUNT=4
-
- ==> (September 2, 1997 EDT)09:00,10:30;12:00;13:30
-
- Every 20 minutes from 9:00 AM to 4:40 PM every day:
-
- DTSTART;TZID=US-Eastern:19970902T090000
- RRULE:FREQ=DAILY;BYHOUR=9,10,11,12,13,14,15,16;BYMINUTE=0,20,40
- or
- RRULE:FREQ=MINUTELY;INTERVAL=20;BYHOUR=9,10,11,12,13,14,15,16
-
- ==> (September 2, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
- ... 16:00,16:20,16:40
- (September 3, 1997 EDT)9:00,9:20,9:40,10:00,10:20,
- ...16:00,16:20,16:40
- ...
-
- An example where the days generated makes a difference because of
- WKST:
-
- DTSTART;TZID=US-Eastern:19970805T090000
- RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=MO
-
- ==> (1997 EDT)Aug 5,10,19,24
-
- changing only WKST from MO to SU, yields different results...
-
- DTSTART;TZID=US-Eastern:19970805T090000
- RRULE:FREQ=WEEKLY;INTERVAL=2;COUNT=4;BYDAY=TU,SU;WKST=SU
- ==> (1997 EDT)August 5,17,19,31
-
-
-
-
-Dawson & Stenerson Standards Track [Page 125]
-
-RFC 2445 iCalendar November 1998
-
-
-4.8.6 Alarm Component Properties
-
- The following properties specify alarm information in calendar
- components.
-
-4.8.6.1 Action
-
- Property Name: ACTION
-
- Purpose: This property defines the action to be invoked when an alarm
- is triggered.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property MUST be specified once in a "VALARM"
- calendar component.
-
- Description: Each "VALARM" calendar component has a particular type
- of action associated with it. This property specifies the type of
- action
-
- Format Definition: The property is defined by the following notation:
-
- action = "ACTION" actionparam ":" actionvalue CRLF
-
- actionparam = *(";" xparam)
-
- actionvalue = "AUDIO" / "DISPLAY" / "EMAIL" / "PROCEDURE"
- / iana-token / x-name
-
- Example: The following are examples of this property in a "VALARM"
- calendar component:
-
- ACTION:AUDIO
-
- ACTION:DISPLAY
-
- ACTION:PROCEDURE
-
-4.8.6.2 Repeat Count
-
- Property Name: REPEAT
-
- Purpose: This property defines the number of time the alarm should be
- repeated, after the initial trigger.
-
-
-
-Dawson & Stenerson Standards Track [Page 126]
-
-RFC 2445 iCalendar November 1998
-
-
- Value Type: INTEGER
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in a "VALARM" calendar
- component.
-
- Description: If the alarm triggers more than once, then this property
- MUST be specified along with the "DURATION" property.
-
- Format Definition: The property is defined by the following notation:
-
- repeatcnt = "REPEAT" repparam ":" integer CRLF
- ;Default is "0", zero.
-
- repparam = *(";" xparam)
-
- Example: The following is an example of this property for an alarm
- that repeats 4 additional times with a 5 minute delay after the
- initial triggering of the alarm:
-
- REPEAT:4
- DURATION:PT5M
-
-4.8.6.3 Trigger
-
- Property Name: TRIGGER
-
- Purpose: This property specifies when an alarm will trigger.
-
- Value Type: The default value type is DURATION. The value type can be
- set to a DATE-TIME value type, in which case the value MUST specify a
- UTC formatted DATE-TIME value.
-
- Property Parameters: Non-standard, value data type, time zone
- identifier or trigger relationship property parameters can be
- specified on this property. The trigger relationship property
- parameter MUST only be specified when the value type is DURATION.
-
- Conformance: This property MUST be specified in the "VALARM" calendar
- component.
-
- Description: Within the "VALARM" calendar component, this property
- defines when the alarm will trigger. The default value type is
- DURATION, specifying a relative time for the trigger of the alarm.
- The default duration is relative to the start of an event or to-do
- that the alarm is associated with. The duration can be explicitly set
-
-
-
-Dawson & Stenerson Standards Track [Page 127]
-
-RFC 2445 iCalendar November 1998
-
-
- to trigger from either the end or the start of the associated event
- or to-do with the "RELATED" parameter. A value of START will set the
- alarm to trigger off the start of the associated event or to-do. A
- value of END will set the alarm to trigger off the end of the
- associated event or to-do.
-
- Either a positive or negative duration may be specified for the
- "TRIGGER" property. An alarm with a positive duration is triggered
- after the associated start or end of the event or to-do. An alarm
- with a negative duration is triggered before the associated start or
- end of the event or to-do.
-
- The "RELATED" property parameter is not valid if the value type of
- the property is set to DATE-TIME (i.e., for an absolute date and time
- alarm trigger). If a value type of DATE-TIME is specified, then the
- property value MUST be specified in the UTC time format. If an
- absolute trigger is specified on an alarm for a recurring event or
- to-do, then the alarm will only trigger for the specified absolute
- date/time, along with any specified repeating instances.
-
- If the trigger is set relative to START, then the "DTSTART" property
- MUST be present in the associated "VEVENT" or "VTODO" calendar
- component. If an alarm is specified for an event with the trigger set
- relative to the END, then the "DTEND" property or the "DSTART" and
- "DURATION' properties MUST be present in the associated "VEVENT"
- calendar component. If the alarm is specified for a to-do with a
- trigger set relative to the END, then either the "DUE" property or
- the "DSTART" and "DURATION' properties MUST be present in the
- associated "VTODO" calendar component.
-
- Alarms specified in an event or to-do which is defined in terms of a
- DATE value type will be triggered relative to 00:00:00 UTC on the
- specified date. For example, if "DTSTART:19980205, then the duration
- trigger will be relative to19980205T000000Z.
-
- Format Definition: The property is defined by the following notation:
-
- trigger = "TRIGGER" (trigrel / trigabs)
-
- trigrel = *(
-
- ; the following are optional,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" "DURATION") /
- (";" trigrelparam) /
-
- ; the following is optional,
-
-
-
-Dawson & Stenerson Standards Track [Page 128]
-
-RFC 2445 iCalendar November 1998
-
-
- ; and MAY occur more than once
-
- (";" xparam)
- ) ":" dur-value
-
- trigabs = 1*(
-
- ; the following is REQUIRED,
- ; but MUST NOT occur more than once
-
- (";" "VALUE" "=" "DATE-TIME") /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- ) ":" date-time
-
- Example: A trigger set 15 minutes prior to the start of the event or
- to-do.
-
- TRIGGER:-P15M
-
- A trigger set 5 minutes after the end of the event or to-do.
-
- TRIGGER;RELATED=END:P5M
-
- A trigger set to an absolute date/time.
-
- TRIGGER;VALUE=DATE-TIME:19980101T050000Z
-
-4.8.7 Change Management Component Properties
-
- The following properties specify change management information in
- calendar components.
-
-4.8.7.1 Date/Time Created
-
- Property Name: CREATED
-
- Purpose: This property specifies the date and time that the calendar
- information was created by the calendar user agent in the calendar
- store.
-
- Note: This is analogous to the creation date and time for a file
- in the file system.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 129]
-
-RFC 2445 iCalendar November 1998
-
-
- Value Type: DATE-TIME
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified once in "VEVENT", "VTODO"
- or "VJOURNAL" calendar components.
-
- Description: The date and time is a UTC value.
-
- Format Definition: The property is defined by the following notation:
-
- created = "CREATED" creaparam ":" date-time CRLF
-
- creaparam = *(";" xparam)
-
- Example: The following is an example of this property:
-
- CREATED:19960329T133000Z
-
-4.8.7.2 Date/Time Stamp
-
- Property Name: DTSTAMP
-
- Purpose: The property indicates the date/time that the instance of
- the iCalendar object was created.
-
- Value Type: DATE-TIME
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property MUST be included in the "VEVENT", "VTODO",
- "VJOURNAL" or "VFREEBUSY" calendar components.
-
- Description: The value MUST be specified in the UTC time format.
-
- This property is also useful to protocols such as [IMIP] that have
- inherent latency issues with the delivery of content. This property
- will assist in the proper sequencing of messages containing iCalendar
- objects.
-
- This property is different than the "CREATED" and "LAST-MODIFIED"
- properties. These two properties are used to specify when the
- particular calendar data in the calendar store was created and last
- modified. This is different than when the iCalendar object
- representation of the calendar service information was created or
- last modified.
-
-
-
-Dawson & Stenerson Standards Track [Page 130]
-
-RFC 2445 iCalendar November 1998
-
-
- Format Definition: The property is defined by the following notation:
-
- dtstamp = "DTSTAMP" stmparam ":" date-time CRLF
-
- stmparam = *(";" xparam)
-
- Example:
-
- DTSTAMP:19971210T080000Z
-
-4.8.7.3 Last Modified
-
- Property Name: LAST-MODIFIED
-
- Purpose: The property specifies the date and time that the
- information associated with the calendar component was last revised
- in the calendar store.
-
- Note: This is analogous to the modification date and time for a
- file in the file system.
-
- Value Type: DATE-TIME
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: This property can be specified in the "EVENT", "VTODO",
- "VJOURNAL" or "VTIMEZONE" calendar components.
-
- Description: The property value MUST be specified in the UTC time
- format.
-
- Format Definition: The property is defined by the following notation:
-
- last-mod = "LAST-MODIFIED" lstparam ":" date-time CRLF
-
- lstparam = *(";" xparam)
-
- Example: The following is are examples of this property:
-
- LAST-MODIFIED:19960817T133000Z
-
-4.8.7.4 Sequence Number
-
- Property Name: SEQUENCE
-
- Purpose: This property defines the revision sequence number of the
- calendar component within a sequence of revisions.
-
-
-
-Dawson & Stenerson Standards Track [Page 131]
-
-RFC 2445 iCalendar November 1998
-
-
- Value Type: integer
-
- Property Parameters: Non-standard property parameters can be
- specified on this property.
-
- Conformance: The property can be specified in "VEVENT", "VTODO" or
- "VJOURNAL" calendar component.
-
- Description: When a calendar component is created, its sequence
- number is zero (US-ASCII decimal 48). It is monotonically incremented
- by the "Organizer's" CUA each time the "Organizer" makes a
- significant revision to the calendar component. When the "Organizer"
- makes changes to one of the following properties, the sequence number
- MUST be incremented:
-
- . "DTSTART"
-
- . "DTEND"
-
- . "DUE"
-
- . "RDATE"
-
- . "RRULE"
-
- . "EXDATE"
-
- . "EXRULE"
-
- . "STATUS"
-
- In addition, changes made by the "Organizer" to other properties can
- also force the sequence number to be incremented. The "Organizer" CUA
- MUST increment the sequence number when ever it makes changes to
- properties in the calendar component that the "Organizer" deems will
- jeopardize the validity of the participation status of the
- "Attendees". For example, changing the location of a meeting from one
- locale to another distant locale could effectively impact the
- participation status of the "Attendees".
-
- The "Organizer" includes this property in an iCalendar object that it
- sends to an "Attendee" to specify the current version of the calendar
- component.
-
- The "Attendee" includes this property in an iCalendar object that it
- sends to the "Organizer" to specify the version of the calendar
- component that the "Attendee" is referring to.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 132]
-
-RFC 2445 iCalendar November 1998
-
-
- A change to the sequence number is not the mechanism that an
- "Organizer" uses to request a response from the "Attendees". The
- "RSVP" parameter on the "ATTENDEE" property is used by the
- "Organizer" to indicate that a response from the "Attendees" is
- requested.
-
- Format Definition: This property is defined by the following
- notation:
-
- seq = "SEQUENCE" seqparam ":" integer CRLF
- ; Default is "0"
-
- seqparam = *(";" xparam)
-
- Example: The following is an example of this property for a calendar
- component that was just created by the "Organizer".
-
- SEQUENCE:0
-
- The following is an example of this property for a calendar component
- that has been revised two different times by the "Organizer".
-
- SEQUENCE:2
-
-4.8.8 Miscellaneous Component Properties
-
- The following properties specify information about a number of
- miscellaneous features of calendar components.
-
-4.8.8.1 Non-standard Properties
-
- Property Name: Any property name with a "X-" prefix
-
- Purpose: This class of property provides a framework for defining
- non-standard properties.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard and language property parameters
- can be specified on this property.
-
- Conformance: This property can be specified in any calendar
- component.
-
- Description: The MIME Calendaring and Scheduling Content Type
- provides a "standard mechanism for doing non-standard things". This
- extension support is provided for implementers to "push the envelope"
- on the existing version of the memo. Extension properties are
-
-
-
-Dawson & Stenerson Standards Track [Page 133]
-
-RFC 2445 iCalendar November 1998
-
-
- specified by property and/or property parameter names that have the
- prefix text of "X-" (the two character sequence: LATIN CAPITAL LETTER
- X character followed by the HYPEN-MINUS character). It is recommended
- that vendors concatenate onto this sentinel another short prefix text
- to identify the vendor. This will facilitate readability of the
- extensions and minimize possible collision of names between different
- vendors. User agents that support this content type are expected to
- be able to parse the extension properties and property parameters but
- can ignore them.
-
- At present, there is no registration authority for names of extension
- properties and property parameters. The data type for this property
- is TEXT. Optionally, the data type can be any of the other valid data
- types.
-
- Format Definition: The property is defined by the following notation:
-
- x-prop = x-name *(";" xparam) [";" languageparam] ":" text CRLF
- ; Lines longer than 75 octets should be folded
-
- Example: The following might be the ABC vendor's extension for an
- audio-clip form of subject property:
-
- X-ABC-MMSUBJ;X-ABC-MMSUBJTYPE=wave:http://load.noise.org/mysubj.wav
-
-4.8.8.2 Request Status
-
- Property Name: REQUEST-STATUS
-
- Purpose: This property defines the status code returned for a
- scheduling request.
-
- Value Type: TEXT
-
- Property Parameters: Non-standard and language property parameters
- can be specified on this property.
-
- Conformance: The property can be specified in "VEVENT", "VTODO",
- "VJOURNAL" or "VFREEBUSY" calendar component.
-
- Description: This property is used to return status code information
- related to the processing of an associated iCalendar object. The data
- type for this property is TEXT.
-
- The value consists of a short return status component, a longer
- return status description component, and optionally a status-specific
- data component. The components of the value are separated by the
- SEMICOLON character (US-ASCII decimal 59).
-
-
-
-Dawson & Stenerson Standards Track [Page 134]
-
-RFC 2445 iCalendar November 1998
-
-
- The short return status is a PERIOD character (US-ASCII decimal 46)
- separated 3-tuple of integers. For example, "3.1.1". The successive
- levels of integers provide for a successive level of status code
- granularity.
-
- The following are initial classes for the return status code.
- Individual iCalendar object methods will define specific return
- status codes for these classes. In addition, other classes for the
- return status code may be defined using the registration process
- defined later in this memo.
-
- |==============+===============================================|
- | Short Return | Longer Return Status Description |
- | Status Code | |
- |==============+===============================================|
- | 1.xx | Preliminary success. This class of status |
- | | of status code indicates that the request has |
- | | request has been initially processed but that |
- | | completion is pending. |
- |==============+===============================================|
- | 2.xx | Successful. This class of status code |
- | | indicates that the request was completed |
- | | successfuly. However, the exact status code |
- | | can indicate that a fallback has been taken. |
- |==============+===============================================|
- | 3.xx | Client Error. This class of status code |
- | | indicates that the request was not successful.|
- | | The error is the result of either a syntax or |
- | | a semantic error in the client formatted |
- | | request. Request should not be retried until |
- | | the condition in the request is corrected. |
- |==============+===============================================|
- | 4.xx | Scheduling Error. This class of status code |
- | | indicates that the request was not successful.|
- | | Some sort of error occurred within the |
- | | calendaring and scheduling service, not |
- | | directly related to the request itself. |
- |==============+===============================================|
-
- Format Definition: The property is defined by the following notation:
-
- rstatus = "REQUEST-STATUS" rstatparam ":"
- statcode ";" statdesc [";" extdata]
-
- rstatparam = *(
-
- ; the following is optional,
- ; but MUST NOT occur more than once
-
-
-
-Dawson & Stenerson Standards Track [Page 135]
-
-RFC 2445 iCalendar November 1998
-
-
- (";" languageparm) /
-
- ; the following is optional,
- ; and MAY occur more than once
-
- (";" xparam)
-
- )
-
- statcode = 1*DIGIT *("." 1*DIGIT)
- ;Hierarchical, numeric return status code
-
- statdesc = text
- ;Textual status description
-
- extdata = text
- ;Textual exception data. For example, the offending property
- ;name and value or complete property line.
-
- Example: The following are some possible examples of this property.
- The COMMA and SEMICOLON separator characters in the property value
- are BACKSLASH character escaped because they appear in a text value.
-
- REQUEST-STATUS:2.0;Success
-
- REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01
-
- REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled
- as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2
-
- REQUEST-STATUS:4.1;Event conflict. Date/time is busy.
-
- REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE:
- MAILTO:jsmith at host.com
-
-5 iCalendar Object Examples
-
- The following examples are provided as an informational source of
- illustrative iCalendar objects consistent with this content type.
-
- The following example specifies a three-day conference that begins at
- 8:00 AM EDT, September 18, 1996 and end at 6:00 PM EDT, September 20,
- 1996.
-
- BEGIN:VCALENDAR PRODID:-//xyz Corp//NONSGML PDA Calendar Verson
- 1.0//EN VERSION:2.0 BEGIN:VEVENT DTSTAMP:19960704T120000Z
- UID:uid1 at host.com ORGANIZER:MAILTO:jsmith at host.com
- DTSTART:19960918T143000Z DTEND:19960920T220000Z STATUS:CONFIRMED
-
-
-
-Dawson & Stenerson Standards Track [Page 136]
-
-RFC 2445 iCalendar November 1998
-
-
- CATEGORIES:CONFERENCE SUMMARY:Networld+Interop Conference
- DESCRIPTION:Networld+Interop Conference
- and Exhibit\nAtlanta World Congress Center\n
- Atlanta, Georgia END:VEVENT END:VCALENDAR
-
- The following example specifies a group scheduled meeting that begin
- at 8:30 AM EST on March 12, 1998 and end at 9:30 AM EST on March 12,
- 1998. The "Organizer" has scheduled the meeting with one or more
- calendar users in a group. A time zone specification for Eastern
- United States has been specified.
-
- BEGIN:VCALENDAR
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VTIMEZONE
- TZID:US-Eastern
- BEGIN:STANDARD
- DTSTART:19981025T020000
- RDATE:19981025T020000
- TZOFFSETFROM:-0400
- TZOFFSETTO:-0500
- TZNAME:EST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19990404T020000
- RDATE:19990404T020000
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0400
- TZNAME:EDT
- END:DAYLIGHT
- END:VTIMEZONE
- BEGIN:VEVENT
- DTSTAMP:19980309T231000Z
- UID:guid-1.host1.com
- ORGANIZER;ROLE=CHAIR:MAILTO:mrbig at host.com
- ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;CUTYPE=GROUP:
- MAILTO:employee-A at host.com
- DESCRIPTION:Project XYZ Review Meeting
- CATEGORIES:MEETING
- CLASS:PUBLIC
- CREATED:19980309T130000Z
- SUMMARY:XYZ Project Review
- DTSTART;TZID=US-Eastern:19980312T083000
- DTEND;TZID=US-Eastern:19980312T093000
- LOCATION:1CP Conference Room 4350
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-Dawson & Stenerson Standards Track [Page 137]
-
-RFC 2445 iCalendar November 1998
-
-
- The following is an example of an iCalendar object passed in a MIME
- message with a single body part consisting of a "text/calendar"
- Content Type.
-
- TO:jsmith at host1.com
- FROM:jdoe at host1.com
- MIME-VERSION:1.0
- MESSAGE-ID:<id3 at host1.com>
- CONTENT-TYPE:text/calendar
-
- BEGIN:VCALENDAR
- METHOD:xyz
- VERSION:2.0
- PRODID:-//ABC Corporation//NONSGML My Product//EN
- BEGIN:VEVENT
- DTSTAMP:19970324T1200Z
- SEQUENCE:0
- UID:uid3 at host1.com
- ORGANIZER:MAILTO:jdoe at host1.com
- ATTENDEE;RSVP=TRUE:MAILTO:jsmith at host1.com
- DTSTART:19970324T123000Z
- DTEND:19970324T210000Z
- CATEGORIES:MEETING,PROJECT
- CLASS:PUBLIC
- SUMMARY:Calendaring Interoperability Planning Meeting
- DESCRIPTION:Discuss how we can test c&s interoperability\n
- using iCalendar and other IETF standards.
- LOCATION:LDB Lobby
- ATTACH;FMTTYPE=application/postscript:ftp://xyzCorp.com/pub/
- conf/bkgrnd.ps
- END:VEVENT
- END:VCALENDAR
-
- The following is an example of a to-do due on April 15, 1998. An
- audio alarm has been specified to remind the calendar user at noon,
- the day before the to-do is expected to be completed and repeat
- hourly, four additional times. The to-do definition has been modified
- twice since it was initially created.
-
- BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//ABC Corporation//NONSGML My Product//EN
- BEGIN:VTODO
- DTSTAMP:19980130T134500Z
- SEQUENCE:2
- UID:uid4 at host1.com
- ORGANIZER:MAILTO:unclesam at us.gov
- ATTENDEE;PARTSTAT=ACCEPTED:MAILTO:jqpublic at host.com
-
-
-
-Dawson & Stenerson Standards Track [Page 138]
-
-RFC 2445 iCalendar November 1998
-
-
- DUE:19980415T235959
- STATUS:NEEDS-ACTION
- SUMMARY:Submit Income Taxes
- BEGIN:VALARM
- ACTION:AUDIO
- TRIGGER:19980403T120000
- ATTACH;FMTTYPE=audio/basic:http://host.com/pub/audio-
- files/ssbanner.aud
- REPEAT:4
- DURATION:PT1H
- END:VALARM
- END:VTODO
- END:VCALENDAR
-
- The following is an example of a journal entry.
-
- BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//ABC Corporation//NONSGML My Product//EN
- BEGIN:VJOURNAL
- DTSTAMP:19970324T120000Z
- UID:uid5 at host1.com
- ORGANIZER:MAILTO:jsmith at host.com
- STATUS:DRAFT
- CLASS:PUBLIC
- CATEGORY:Project Report, XYZ, Weekly Meeting
- DESCRIPTION:Project xyz Review Meeting Minutes\n
- Agenda\n1. Review of project version 1.0 requirements.\n2.
- Definition
- of project processes.\n3. Review of project schedule.\n
- Participants: John Smith, Jane Doe, Jim Dandy\n-It was
- decided that the requirements need to be signed off by
- product marketing.\n-Project processes were accepted.\n
- -Project schedule needs to account for scheduled holidays
- and employee vacation time. Check with HR for specific
- dates.\n-New schedule will be distributed by Friday.\n-
- Next weeks meeting is cancelled. No meeting until 3/23.
- END:VJOURNAL
- END:VCALENDAR
-
- The following is an example of published busy time information. The
- iCalendar object might be placed in the network resource
- www.host.com/calendar/busytime/jsmith.ifb.
-
- BEGIN:VCALENDAR
- VERSION:2.0
- PRODID:-//RDU Software//NONSGML HandCal//EN
- BEGIN:VFREEBUSY
-
-
-
-Dawson & Stenerson Standards Track [Page 139]
-
-RFC 2445 iCalendar November 1998
-
-
- ORGANIZER:MAILTO:jsmith at host.com
- DTSTART:19980313T141711Z
- DTEND:19980410T141711Z
- FREEBUSY:19980314T233000Z/19980315T003000Z
- FREEBUSY:19980316T153000Z/19980316T163000Z
- FREEBUSY:19980318T030000Z/19980318T040000Z
- URL:http://www.host.com/calendar/busytime/jsmith.ifb
- END:VFREEBUSY
- END:VCALENDAR
-
-6 Recommended Practices
-
- These recommended practices should be followed in order to assure
- consistent handling of the following cases for an iCalendar object.
-
- 1. Content lines longer than 75 octets SHOULD be folded.
-
- 2. A calendar entry with a "DTSTART" property but no "DTEND"
- property does not take up any time. It is intended to represent
- an event that is associated with a given calendar date and time
- of day, such as an anniversary. Since the event does not take up
- any time, it MUST NOT be used to record busy time no matter what
- the value for the "TRANSP" property.
-
- 3. When the "DTSTART" and "DTEND", for "VEVENT", "VJOURNAL" and
- "VFREEBUSY" calendar components, and "DTSTART" and "DUE", for
- "VTODO" calendar components, have the same value data type (e.g.,
- DATE-TIME), they SHOULD specify values in the same time format
- (e.g., UTC time format).
-
- 4. When the combination of the "RRULE" and "RDATE" properties on an
- iCalendar object produces multiple instances having the same
- start date/time, they should be collapsed to, and considered as,
- a single instance.
-
- 5. When a calendar user receives multiple requests for the same
- calendar component (e.g., REQUEST for a "VEVENT" calendar
- component) as a result of being on multiple mailing lists
- specified by "ATTENDEE" properties in the request, they SHOULD
- respond to only one of the requests. The calendar user SHOULD
- also specify (using the "MEMBER" parameter of the "ATTENDEE"
- property) which mailing list they are a member of.
-
- 6. An implementation can truncate a "SUMMARY" property value to 255
- characters.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 140]
-
-RFC 2445 iCalendar November 1998
-
-
- 7. If seconds of the minute are not supported by an implementation,
- then a value of "00" SHOULD be specified for the seconds
- component in a time value.
-
- 8. If the value type parameter (VALUE=) contains an unknown value
- type, it SHOULD be treated as TEXT.
-
- 9. TZURL values SHOULD NOT be specified as a FILE URI type. This URI
- form can be useful within an organization, but is problematic in
- the Internet.
-
- 10. Some possible English values for CATEGORIES property include
- "ANNIVERSARY", "APPOINTMENT", "BUSINESS", "EDUCATION",
- "HOLIDAY", "MEETING", "MISCELLANEOUS", "NON-WORKING HOURS", "NOT
- IN OFFICE", "PERSONAL", "PHONE CALL", "SICK DAY", "SPECIAL
- OCCASION", "TRAVEL", "VACATION". Categories can be specified in
- any registered language.
-
- 11. Some possible English values for RESOURCES property include
- "CATERING", "CHAIRS", "COMPUTER PROJECTOR", "EASEL", "OVERHEAD
- PROJECTOR", "SPEAKER PHONE", "TABLE", "TV", "VCR", "VIDEO
- PHONE", "VEHICLE". Resources can be specified in any registered
- language.
-
-7 Registration of Content Type Elements
-
- This section provides the process for registration of MIME
- Calendaring and Scheduling Content Type iCalendar object methods and
- new or modified properties.
-
-7.1 Registration of New and Modified iCalendar Object Methods
-
- New MIME Calendaring and Scheduling Content Type iCalendar object
- methods are registered by the publication of an IETF Request for
- Comments (RFC). Changes to an iCalendar object method are registered
- by the publication of a revision of the RFC defining the method.
-
-7.2 Registration of New Properties
-
- This section defines procedures by which new properties or enumerated
- property values for the MIME Calendaring and Scheduling Content Type
- can be registered with the IANA. Non-IANA properties can be used by
- bilateral agreement, provided the associated properties names follow
- the "X-" convention.
-
- The procedures defined here are designed to allow public comment and
- review of new properties, while posing only a small impediment to the
- definition of new properties.
-
-
-
-Dawson & Stenerson Standards Track [Page 141]
-
-RFC 2445 iCalendar November 1998
-
-
- Registration of a new property is accomplished by the following
- steps.
-
-7.2.1 Define the property
-
- A property is defined by completing the following template.
-
- To: ietf-calendar at imc.org
-
- Subject: Registration of text/calendar MIME property XXX
-
- Property name:
-
- Property purpose:
-
- Property value type(s):
-
- Property parameter (s):
-
- Conformance:
-
- Description:
-
- Format definition:
-
- Examples:
-
- The meaning of each field in the template is as follows.
-
- Property name: The name of the property, as it will appear in the
- body of an text/calendar MIME Content-Type "property: value" line to
- the left of the colon ":".
-
- Property purpose: The purpose of the property (e.g., to indicate a
- delegate for the event or to-do, etc.). Give a short but clear
- description.
-
- Property value type (s): Any of the valid value types for the
- property value needs to be specified. The default value type also
- needs to be specified. If a new value type is specified, it needs to
- be declared in this section.
-
- Property parameter (s): Any of the valid property parameters for the
- property needs to be specified.
-
- Conformance: The calendar components that the property can appear in
- needs to be specified.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 142]
-
-RFC 2445 iCalendar November 1998
-
-
- Description: Any special notes about the property, how it is to be
- used, etc.
-
- Format definition: The ABNF for the property definition needs to be
- specified.
-
- Examples: One or more examples of instances of the property needs to
- be specified.
-
-7.2.2 Post the Property definition
-
- The property description MUST be posted to the new property
- discussion list, ietf-calendar at imc.org.
-
-7.2.3 Allow a comment period
-
- Discussion on the new property MUST be allowed to take place on the
- list for a minimum of two weeks. Consensus MUST be reached on the
- property before proceeding to the next step.
-
-7.2.4 Submit the property for approval
-
- Once the two-week comment period has elapsed, and the proposer is
- convinced consensus has been reached on the property, the
- registration application should be submitted to the Method Reviewer
- for approval. The Method Reviewer is appointed to the Application
- Area Directors and can either accept or reject the property
- registration. An accepted registration should be passed on by the
- Method Reviewer to the IANA for inclusion in the official IANA method
- registry. The registration can be rejected for any of the following
- reasons. 1) Insufficient comment period; 2) Consensus not reached; 3)
- Technical deficiencies raised on the list or elsewhere have not been
- addressed. The Method Reviewer's decision to reject a property can be
- appealed by the proposer to the IESG, or the objections raised can be
- addressed by the proposer and the property resubmitted.
-
-7.3 Property Change Control
-
- Existing properties can be changed using the same process by which
- they were registered.
-
- 1. Define the change
-
- 2. Post the change
-
- 3. Allow a comment period
-
- 4. Submit the property for approval
-
-
-
-Dawson & Stenerson Standards Track [Page 143]
-
-RFC 2445 iCalendar November 1998
-
-
- Note that the original author or any other interested party can
- propose a change to an existing property, but that such changes
- should only be proposed when there are serious omissions or errors in
- the published memo. The Method Reviewer can object to a change if it
- is not backward compatible, but is not required to do so.
-
- Property definitions can never be deleted from the IANA registry, but
- properties which are no longer believed to be useful can be declared
- OBSOLETE by a change to their "intended use" field.
-
-8 References
-
- [IMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
- Message-based Interoperability Protocol (IMIP)", RFC 2447,
- November 1998.
-
- [ITIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
- "iCalendar Transport-Independent Interoperability Protocol
- (iTIP) : Scheduling Events, Busy Time, To-dos and Journal
- Entries", RFC 2446, November 1998.
-
- [ISO 8601] ISO 8601, "Data elements and interchange formats-
- Information interchange--Representation of dates and
- times", International Organization for Standardization,
- June, 1988.
-
- [ISO 9070] ISO/IEC 9070, "Information Technology_SGML Support
- Facilities--Registration Procedures for Public Text Owner
- Identifiers", Second Edition, International Organization
- for Standardization, April 1991.
-
- [RFC 822] Crocker, D., "Standard for the Format of ARPA Internet
- Text Messages", STD 11, RFC 822, August 1982.
-
- [RFC 1738] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform
- Resource Locators (URL)", RFC 1738, December 1994.
-
- [RFC 1766] Alvestrand, H., "Tags for the Identification of
- Languages", RFC 1766, March 1995.
-
- [RFC 2045] Freed, N. and N. Borenstein, " Multipurpose Internet Mail
- Extensions (MIME) - Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [RFC 2046] Freed, N. and N. Borenstein, " Multipurpose Internet Mail
- Extensions (MIME) - Part Two: Media Types", RFC 2046,
- November 1996.
-
-
-
-
-Dawson & Stenerson Standards Track [Page 144]
-
-RFC 2445 iCalendar November 1998
-
-
- [RFC 2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extensions (MIME) - Part Four: Registration
- Procedures", RFC 2048, January 1997.
-
- [RFC 2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC 2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
- Specifications: ABNF", RFC 2234, November 1997.
-
- [RFC 2279] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", RFC 2279, January 1998.
-
- [RFC 2425] Howes, T., Smith, M. and F. Dawson, "A MIME Content-Type
- for Directory Information", RFC 2425, September 1998.
-
- [RFC 2426] Dawson, F. and T. Howes, "vCard MIME Directory Profile",
- RFC 2426, September 1998.
-
- [TZ] Olson, A.D., et al, Time zone code and data,
- ftp://elsie.nci.nih.gov/pub/, updated periodically.
-
- [VCAL] Internet Mail Consortium, "vCalendar - The Electronic
- Calendaring and Scheduling Exchange Format",
- http://www.imc.org/pdi/vcal-10.txt, September 18, 1996.
-
-9 Acknowledgments
-
- A hearty thanks to the IETF Calendaring and Scheduling Working Group
- and also the following individuals who have participated in the
- drafting, review and discussion of this memo:
-
- Roland Alden, Harald T. Alvestrand, Eric Berman, Denis Bigorgne, John
- Binici, Bill Bliss, Philippe Boucher, Steve Carter, Andre
- Courtemanche, Dave Crocker, David Curley, Alec Dun, John Evans, Ross
- Finlayson, Randell Flint, Ned Freed, Patrik Faltstrom, Chuck
- Grandgent, Mark Handley, Steve Hanna, Paul B. Hill, Paul Hoffman,
- Ross Hopson, Mark Horton, Daryl Huff, Bruce Kahn, C. Harald Koch,
- Ryan Jansen, Don Lavange, Antoine Leca, Theodore Lorek, Steve
- Mansour, Skip Montanaro, Keith Moore, Cecil Murray, Chris Newman,
- John Noerenberg, Ralph Patterson, Pete Resnick, Keith Rhodes, Robert
- Ripberger, John Rose, Doug Royer, Andras Salamar, Ted Schuh, Vinod
- Seraphin, Derrick Shadel, Ken Shan, Andrew Shuman, Steve Silverberg,
- William P. Spencer, John Sun, Mark Towfiq, Yvonne Tso, Robert Visnov,
- James L. Weiner, Mike Weston, William Wyatt.
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 145]
-
-RFC 2445 iCalendar November 1998
-
-
-10 Authors' and Chairs' Addresses
-
- The following address information is provided in a MIME-VCARD,
- Electronic Business Card, format.
-
- The authors of this memo are:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Dawson;Frank
- FN:Frank Dawson
- ORG:Lotus Development Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive;
- Raleigh;NC;27613-3502;USA
- TEL;TYPE=WORK,MSG:+1-919-676-9515
- TEL;TYPE=WORK,FAX:+1-919-676-9564
- EMAIL;TYPE=PREF,INTERNET:Frank_Dawson at Lotus.com
- EMAIL;TYPE=INTERNET:fdawson at earthlink.net
- URL:http://home.earthlink.net/~fdawson
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Stenerson;Derik
- FN:Derik Stenerson
- ORG:Microsoft Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
- Redmond;WA;98052-6399;USA
- TEL;TYPE=WORK,MSG:+1-425-936-5522
- TEL;TYPE=WORK,FAX:+1-425-936-7329
- EMAIL;TYPE=INTERNET:deriks at Microsoft.com
- END:VCARD
-
- The iCalendar object is a result of the work of the Internet
- Engineering Task Force Calendaring and Scheduling Working Group. The
- chairmen of that working group are:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Ganguly;Anik
- FN:Anik Ganguly
- ORG: Open Text Inc.
- ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
- Livonia;MI;48152;USA
- TEL;TYPE=WORK,MSG:+1-734-542-5955
- EMAIL;TYPE=INTERNET:ganguly at acm.org
- END:VCARD
-
-
-
-
-Dawson & Stenerson Standards Track [Page 146]
-
-RFC 2445 iCalendar November 1998
-
-
- The co-chairman of that working group is:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Moskowitz;Robert
- FN:Robert Moskowitz
- EMAIL;TYPE=INTERNET:rgm-ietf at htt-consult.com
- END:VCARD
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 147]
-
-RFC 2445 iCalendar November 1998
-
-
-11. Full Copyright Statement
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dawson & Stenerson Standards Track [Page 148]
-
Copied: CalendarServer/trunk/doc/RFC/rfc2446-iTIP.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2446.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2446-iTIP.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2446-iTIP.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,6107 @@
+
+
+
+
+
+
+Network Working Group S. Silverberg
+Request for Comments: 2446 Microsoft
+Category: Standards Track S. Mansour
+ Netscape
+ F. Dawson
+ Lotus
+ R. Hopson
+ ON Technologies
+ November 1998
+
+
+ iCalendar Transport-Independent Interoperability Protocol
+ (iTIP)
+ Scheduling Events, BusyTime, To-dos and Journal Entries
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ This document specifies how calendaring systems use iCalendar objects
+ to interoperate with other calendar systems. It does so in a general
+ way so as to allow multiple methods of communication between systems.
+ Subsequent documents specify interoperable methods of communications
+ between systems that use this protocol.
+
+ The document outlines a model for calendar exchange that defines both
+ static and dynamic event, to-do, journal and free/busy objects.
+ Static objects are used to transmit information from one entity to
+ another without the expectation of continuity or referential
+ integrity with the original item. Dynamic objects are a superset of
+ static objects and will gracefully degrade to their static
+ counterparts for clients that only support static objects.
+
+ This document specifies an Internet protocol based on the iCalendar
+ object specification that provides scheduling interoperability
+ between different calendar systems. The Internet protocol is called
+ the "iCalendar Transport-Independent Interoperability Protocol
+ (iTIP)".
+
+
+
+Silverberg, et. al. Standards Track [Page 1]
+
+RFC 2446 iTIP November 1998
+
+
+ iTIP complements the iCalendar object specification by adding
+ semantics for group scheduling methods commonly available in current
+ calendar systems. These scheduling methods permit two or more
+ calendar systems to perform transactions such as publish, schedule,
+ reschedule, respond to scheduling requests, negotiation of changes or
+ cancel iCalendar-based calendar components.
+
+ iTIP is defined independent of the particular transport used to
+ transmit the scheduling information. Companion memos to iTIP provide
+ bindings of the interoperability protocol to a number of Internet
+ protocols.
+
+Table of Contents
+
+ 1 INTRODUCTION...................................................5
+ 1.1 FORMATTING CONVENTIONS .....................................5
+ 1.2 RELATED DOCUMENTS ..........................................6
+ 1.3 ITIP ROLES AND TRANSACTIONS ................................6
+ 2 INTEROPERABILITY MODELS........................................8
+ 2.1 APPLICATION PROTOCOL .......................................9
+ 2.1.1 Calendar Entry State ...................................9
+ 2.1.2 Delegation .............................................9
+ 2.1.3 Acting on Behalf of other Calendar Users ..............10
+ 2.1.4 Component Revisions ...................................10
+ 2.1.5 Message Sequencing ....................................11
+ 3 APPLICATION PROTOCOL ELEMENTS.................................12
+ 3.1 COMMON COMPONENT RESTRICTION TABLES .......................13
+ 3.2 METHODS FOR VEVENT CALENDAR COMPONENTS ....................14
+ 3.2.1 PUBLISH ...............................................15
+ 3.2.2 REQUEST ...............................................17
+ 3.2.2.1 Rescheduling an Event..............................19
+ 3.2.2.2 Updating or Reconfirmation of an Event.............19
+ 3.2.2.3 Delegating an Event to another CU..................19
+ 3.2.2.4 Changing the Organizer.............................20
+ 3.2.2.5 Sending on Behalf of the Organizer.................20
+ 3.2.2.6 Forwarding to An Uninvited CU......................20
+ 3.2.2.7 Updating Attendee Status...........................21
+ 3.2.3 REPLY .................................................21
+ 3.2.4 ADD ...................................................23
+ 3.2.5 CANCEL ................................................25
+ 3.2.6 REFRESH ...............................................26
+ 3.2.7 COUNTER ...............................................28
+ 3.2.8 DECLINECOUNTER ........................................29
+ 3.3 METHODS FOR VFREEBUSY COMPONENTS ..........................31
+ 3.3.1 PUBLISH ...............................................32
+ 3.3.2 REQUEST ...............................................33
+ 3.3.3 REPLY .................................................34
+ 3.4 METHODS FOR VTODO COMPONENTS ..............................35
+
+
+
+Silverberg, et. al. Standards Track [Page 2]
+
+RFC 2446 iTIP November 1998
+
+
+ 3.4.1 PUBLISH ...............................................35
+ 3.4.2 REQUEST ...............................................37
+ 3.4.2.1 REQUEST for Rescheduling a VTODO...................39
+ 3.4.2.2 REQUEST for Update or Reconfirmation of a VTODO....39
+ 3.4.2.3 REQUEST for Delegating a VTODO.....................40
+ 3.4.2.4 REQUEST Forwarded To An Uninvited Calendar User....40
+ 3.4.2.5 REQUEST Updated Attendee Status....................41
+ 3.4.3 REPLY .................................................41
+ 3.4.4 ADD ...................................................43
+ 3.4.5 CANCEL ................................................44
+ 3.4.6 REFRESH ...............................................46
+ 3.4.7 COUNTER ...............................................48
+ 3.4.8 DECLINECOUNTER ........................................49
+ 3.5 METHODS FOR VJOURNAL COMPONENTS ...........................50
+ 3.5.1 PUBLISH ...............................................51
+ 3.5.2 ADD ...................................................52
+ 3.5.3 CANCEL ................................................53
+ 3.6 STATUS REPLIES ............................................55
+ 3.7 IMPLEMENTATION CONSIDERATIONS .............................57
+ 3.7.1 Working With Recurrence Instances .....................57
+ 3.7.2 Attendee Property Considerations ......................58
+ 3.7.3 X-Tokens ..............................................59
+ 4 EXAMPLES......................................................59
+ 4.1 PUBLISHED EVENT EXAMPLES ..................................59
+ 4.1.1 A Minimal Published Event .............................60
+ 4.1.2 Changing A Published Event ............................60
+ 4.1.3 Canceling A Published Event ...........................61
+ 4.1.4 A Rich Published Event ................................62
+ 4.1.5 Anniversaries or Events attached to entire days .......63
+ 4.2 GROUP EVENT EXAMPLES ......................................63
+ 4.2.1 A Group Event Request .................................64
+ 4.2.2 Reply To A Group Event Request ........................65
+ 4.2.3 Update An Event .......................................65
+ 4.2.4 Countering an Event Proposal ..........................66
+ 4.2.5 Delegating an Event ...................................68
+ 4.2.6 Delegate Accepts the Meeting ..........................70
+ 4.2.7 Delegate Declines the Meeting .........................71
+ 4.2.8 Forwarding an Event Request ...........................72
+ 4.2.9 Cancel A Group Event ..................................72
+ 4.2.10 Removing Attendees ...................................74
+ 4.2.11 Replacing the Organizer ..............................75
+ 4.3 BUSY TIME EXAMPLES ........................................76
+ 4.3.1 Request Busy Time .....................................77
+ 4.3.2 Reply To A Busy Time Request ..........................77
+ 4.4 RECURRING EVENT AND TIME ZONE EXAMPLES ....................78
+ 4.4.1 A Recurring Event Spanning Time Zones .................78
+ 4.4.2 Modify A Recurring Instance ...........................79
+ 4.4.3 Cancel an Instance ....................................81
+
+
+
+Silverberg, et. al. Standards Track [Page 3]
+
+RFC 2446 iTIP November 1998
+
+
+ 4.4.4 Cancel Recurring Event ................................81
+ 4.4.5 Change All Future Instances ...........................82
+ 4.4.6 Add A New Instance To A Recurring Event ...............82
+ 4.4.7 Add A New Series of Instances To A Recurring Event ....83
+ 4.4.8 Counter An Instance Of A Recurring Event ..............87
+ 4.4.9 Error Reply To A Request ..............................88
+ 4.5 GROUP TO-DO EXAMPLES ......................................89
+ 4.5.1 A VTODO Request .......................................90
+ 4.5.2 A VTODO Reply .........................................90
+ 4.5.3 A VTODO Request for Updated Status ....................91
+ 4.5.4 A Reply: Percent-Complete .............................91
+ 4.5.5 A Reply: Completed ....................................92
+ 4.5.6 An Updated VTODO Request ..............................92
+ 4.5.7 Recurring VTODOs ......................................92
+ 4.5.7.1 Request for a Recurring VTODO......................93
+ 4.5.7.2 Calculating due dates in recurring VTODOs..........93
+ 4.5.7.3 Replying to an instance of a recurring VTODO.......93
+ 4.6 JOURNAL EXAMPLES ..........................................94
+ 4.7 OTHER EXAMPLES ............................................94
+ 4.7.1 Event Refresh .........................................94
+ 4.7.2 Bad RECURRENCE-ID .....................................95
+ 5 APPLICATION PROTOCOL FALLBACKS................................97
+ 5.1 PARTIAL IMPLEMENTATION ....................................97
+ 5.1.1 Event-Related Fallbacks ...............................97
+ 5.1.2 Free/Busy-Related Fallbacks ...........................99
+ 5.1.3 To-Do-Related Fallbacks ...............................99
+ 5.1.4 Journal-Related Fallbacks ............................101
+ 5.2 LATENCY ISSUES ...........................................102
+ 5.2.1 Cancellation of an Unknown Calendar Component. .......102
+ 5.2.2 Unexpected Reply from an Unknown Delegate ............103
+ 5.3 SEQUENCE NUMBER ..........................................103
+ 6 SECURITY CONSIDERATIONS......................................103
+ 6.1 SECURITY THREATS .........................................103
+ 6.1.1 Spoofing the "Organizer" .............................103
+ 6.1.2 Spoofing the "Attendee" ..............................103
+ 6.1.3 Unauthorized Replacement of the Organizer ............104
+ 6.1.4 Eavesdropping ........................................104
+ 6.1.5 Flooding a Calendar ..................................104
+ 6.1.6 Procedural Alarms ....................................104
+ 6.1.7 Unauthorized REFRESH Requests ........................104
+ 6.2 RECOMMENDATIONS ..........................................104
+ 6.2.1 Use of [RFC-1847] to secure iTIP transactions ........105
+ 6.2.2 Implementation Controls ..............................105
+ 7 ACKNOWLEDGMENTS..............................................106
+ 8 BIBLIOGRAPHY.................................................106
+ 9 AUTHORS' ADDRESSES...........................................107
+ 10 FULL COPYRIGHT STATEMENT....................................109
+
+
+
+
+Silverberg, et. al. Standards Track [Page 4]
+
+RFC 2446 iTIP November 1998
+
+
+1 Introduction
+
+ This document specifies how calendaring systems use iCalendar objects
+ to interoperate with other calendar systems. In particular, it
+ specifies how to schedule events, to-dos, or daily journal entries.
+ It further specifies how to search for available busy time
+ information. It does so in a general way so as to allow multiple
+ methods of communication between systems. Subsequent documents
+ specify transport bindings between systems that use this protocol.
+
+ This protocol is based on messages sent from an originator to one or
+ more recipients. For certain types of messages, a recipient may
+ reply, in order to update their status and may also return
+ transaction/request status information. The protocol supports the
+ ability for the message originator to modify or cancel the original
+ message. The protocol also supports the ability for recipients to
+ suggest changes to the originator of a message. The elements of the
+ protocol also define the user roles for its transactions.
+
+1.1 Formatting Conventions
+
+ In order to refer to elements of the calendaring and scheduling
+ model, core object or interoperability protocol defined in [iCAL] and
+ [iTIP] several formatting conventions have been utilized.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC-2119].
+
+ Calendaring and scheduling roles are referred to in quoted-strings of
+ text with the first character of each word in upper case. For
+ example, "Organizer" refers to a role of a "Calendar User" (CU)
+ within the scheduling protocol defined by [iTIP]. Calendar components
+ defined by [iCAL] are referred to with capitalized, quoted-strings of
+ text. All calendar components start with the letter "V". For example,
+ "VEVENT" refers to the event calendar component, "VTODO" refers to
+ the to-do calendar component and "VJOURNAL" refers to the daily
+ journal calendar component. Scheduling methods defined by [iTIP] are
+ referred to with capitalized, quoted-strings of text. For example,
+ "REQUEST" refers to the method for requesting a scheduling calendar
+ component be created or modified, "REPLY" refers to the method a
+ recipient of a request uses to update their status with the
+ "Organizer" of the calendar component.
+
+ Properties defined by [iCAL] are referred to with capitalized,
+ quoted-strings of text, followed by the word "property". For example,
+ "ATTENDEE" property refers to the iCalendar property used to convey
+ the calendar address of a "Calendar User". Property parameters
+
+
+
+Silverberg, et. al. Standards Track [Page 5]
+
+RFC 2446 iTIP November 1998
+
+
+ defined by this memo are referred to with lower case, quoted-strings
+ of text, followed by the word "parameter". For example, "value"
+ parameter refers to the iCalendar property parameter used to override
+ the default data type for a property value. Enumerated values defined
+ by this memo are referred to with capitalized text, either alone or
+ followed by the word "value".
+
+ In tables, the quoted-string text is specified without quotes in
+ order to minimize the table length.
+
+1.2 Related Documents
+
+ Implementers will need to be familiar with several other memos that,
+ along with this one, describe the Internet calendaring and scheduling
+ standards. This document, [iTIP], specifies an interoperability
+ protocol for scheduling between different implementations. The
+ related documents are:
+
+ [iCAL] - specifies the objects, data types, properties and
+ property parameters used in the protocols, along with the
+ methods for representing and encoding them;
+
+ [iMIP] specifies an Internet email binding for [iTIP].
+
+ This memo does not attempt to repeat the specification of concepts or
+ definitions from these other memos. Where possible, references are
+ made to the memo that provides for the specification of these
+ concepts or definitions.
+
+1.3 ITIP Roles and Transactions
+
+ ITIP defines methods for exchanging [iCAL] objects for the purposes
+ of group calendaring and scheduling between "Calendar Users" (CUs).
+ CUs take on one of two roles in iTIP. The CU who initiates an
+ exchange takes on the role of "Organizer". For example, the CU who
+ proposes a group meeting is the "Organizer". The CUs asked to
+ participate in the group meeting by the "Organizer" take on the role
+ of "Attendee". Note that "role" is also a descriptive parameter to
+ the _ATTENDEE_ property. Its use is to convey descriptive context to
+ an "Attendee" such as "chair", "req-participant" or "non-participant"
+ and has nothing to do with the calendaring workflow.
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 6]
+
+RFC 2446 iTIP November 1998
+
+
+ The ITIP methods are listed below and their usage and semantics are
+ defined in section 3 of this document.
+
+ +================+==================================================+
+ | Method | Description |
+ |================+==================================================|
+ | PUBLISH | Used to publish a calendar entry to one or more |
+ | | Calendar Users. There is no interactivity |
+ | | between the publisher and any other calendar |
+ | | user. An example might include a baseball team |
+ | | publishing its schedule to the public. |
+ | | |
+ | REQUEST | Used to schedule a calendar entry with other |
+ | | Calendar Users. Requests are interactive in that |
+ | | they require the receiver to respond using |
+ | | the Reply methods. Meeting Requests, Busy |
+ | | Time requests and the assignment of VTODOs to |
+ | | other Calendar Users are all examples. |
+ | | Requests are also used by the "Organizer" to |
+ | | update the status of a calendar entry. |
+ | | |
+ | REPLY | A Reply is used in response to a Request to |
+ | | convey "Attendee" status to the "Organizer". |
+ | | Replies are commonly used to respond to meeting |
+ | | and task requests. |
+ | | |
+ | ADD | Add one or more instances to an existing |
+ | | VEVENT, VTODO, or VJOURNAL. |
+ | | |
+ | CANCEL | Cancel one or more instances of an existing |
+ | | VEVENT, VTODO, or VJOURNAL. |
+ | | |
+ | REFRESH | The Refresh method is used by an "Attendee" to |
+ | | request the latest version of a calendar entry. |
+ | | |
+ | COUNTER | The Counter method is used by an "Attendee" to |
+ | | negotiate a change in the calendar entry. |
+ | | Examples include the request to change a |
+ | | proposed Event time or change the due date for a |
+ | | VTODO. |
+ | | |
+ | DECLINE- | Used by the "Organizer" to decline the proposed |
+ | COUNTER | counter-proprosal. |
+ +================+==================================================+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 7]
+
+RFC 2446 iTIP November 1998
+
+
+ Group scheduling in iTIP is accomplished using the set of "request"
+ and "response" methods described above. The following table shows the
+ methods broken down by who can send them.
+
+ +================+==================================================+
+ | Originator | Methods |
+ |================+==================================================|
+ | Organizer | PUBLISH, REQUEST, ADD, CANCEL, DECLINECOUNTER |
+ | | |
+ | Attendee | REPLY, REFRESH, COUNTER |
+ | | REQUEST only when delegating |
+ +================+==================================================+
+
+ Note that for some calendar component types, the allowable methods
+ are a subset of the above set.
+
+2 Interoperability Models
+
+ There are two distinct protocols relevant to interoperability: an
+ "Application Protocol" and a "Transport Protocol". The Application
+ Protocol defines the content of the iCalendar objects sent between
+ sender and receiver to accomplish the scheduling transactions listed
+ above. The Transport Protocol defines how the iCalendar objects are
+ sent between the sender and receiver. This document focuses on the
+ Application Protocol. Binding documents such as [iMIP] focus on the
+ Transport Protocol.
+
+ The connection between Sender and Receiver in the diagram below
+ refers to the Application Protocol. The iCalendar objects passed from
+ the Sender to the Receiver are presented in Section 3, Application
+ Protocol Elements.
+
+ +----------+ +----------+
+ | | iTIP | |
+ | Sender |<-------------------->| Receiver |
+ | | | |
+ +----------+ +----------+
+
+ There are several variations of this diagram in which the Sender and
+ Receiver take on various roles of a "Calendar User Agent" (CUA) or a
+ "Calendar Service" (CS).
+
+ The architecture of iTIP is depicted in the diagram below. An
+ application written to this specification may work with bindings for
+ the store-and-forward transport, the real time transport, or both.
+ Also note that iTIP could be bound to other transports.
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 8]
+
+RFC 2446 iTIP November 1998
+
+
+ +------------------------------------------+
+ | iTIP |
+ +------------------------------------------+
+ |Real-time | Store-and-Fwd | Other |
+ |Transport | Transport | Transports... |
+ +------------------------------------------+
+
+2.1 Application Protocol
+
+ In the iTIP model, a calendar entry is created and managed by an
+ "Organizer". The "Organizer" interacts with other CUs by sending one
+ or more of the iTIP messages listed above. "Attendees" use the
+ "REPLY" method to communicate their status. "Attendees" do not make
+ direct changes to the master calendar entry. They can, however, use
+ the "COUNTER" method to suggest changes to the "Organizer". In any
+ case, the "Organizer" has complete control over the master calendar
+ entry.
+
+2.1.1 Calendar Entry State
+
+ There are two distinct states relevant to calendar entries: the
+ overall state of the entry and the state associated with an
+ "Attendee" to that entry.
+
+ The state of an entry is defined by the "STATUS" property and is
+ controlled by the "Organizer." There is no default value for the
+ "STATUS" property. The "Organizer" sets the "STATUS" property to the
+ appropriate value for each calendar entry.
+
+ The state of a particular "Attendee" relative to an entry is defined
+ by the "partstat" parameter in the "ATTENDEE" property for each
+ "Attendee". When an "Organizer" issues the initial entry, "Attendee"
+ status is unknown. The "Organizer" specifies this by setting the
+ "partstat" parameter to "NEEDS-ACTION". Each "Attendee" modifies
+ their "ATTENDEE" property "partstat" parameter to an appropriate
+ value as part of a "REPLY" message sent back to the "Organizer".
+
+2.1.2 Delegation
+
+ Delegation is defined as the process by which an "Attendee" grants
+ another CU (or several CUs) the right to attend on their behalf. The
+ "Organizer" is made aware of this change because the delegating
+ "Attendee" informs the "Organizer". These steps are detailed in the
+ REQUEST method section.
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 9]
+
+RFC 2446 iTIP November 1998
+
+
+2.1.3 Acting on Behalf of other Calendar Users
+
+ In many organizations one user will act on behalf of another to
+ organize and/or respond to meeting requests. ITIP provides two
+ mechanisms that support these activities.
+
+ First, the "Organizer" is treated as a special entity, separate from
+ "Attendees". All responses from "Attendees" flow to the "Organizer",
+ making it easy to separate a calendar user organizing a meeting from
+ calendar users attending the meeting. Additionally, iCalendar
+ provides descriptive roles for each "Attendee". For instance, a role
+ of "chair" may be ascribed to one or more "Attendees". The "chair"
+ and the "Organizer" may or may not be the same calendar user. This
+ maps well to scenarios where an assistant may manage meeting
+ logistics for another individual who chairs a meeting.
+
+ Second, a "sent-by" parameter may be specified in either the
+ "Organizer" or "Attendee" properties. When specified, the "sent-by"
+ parameter indicates that the responding CU acted on behalf of the
+ specified "Attendee" or "Organizer".
+
+2.1.4 Component Revisions
+
+ The "SEQUENCE" property is used by the "Organizer" to indicate
+ revisions to the calendar component. The rules for incrementing the
+ "SEQUENCE" number are defined in [iCAL]. For clarity, these rules are
+ paraphrased here in terms of how they are applied in [iTIP]. For a
+ given "UID" in a calendar component:
+
+ . For the "PUBLISH" and "REQUEST" methods, the "SEQUENCE" property
+ value is incremented according to the rules defined in [iCAL].
+
+ . The "SEQUENCE" property value MUST be incremented each time the
+ "Organizer" uses the "ADD" or "CANCEL" methods.
+
+ . The "SEQUENCE" property value MUST NOT be incremented when using
+ "REPLY", "REFRESH", "COUNTER", "DECLINECOUNTER", or when sending a
+ delegation "REQUEST".
+
+ In some circumstances the "Organizer" may not have received responses
+ to the final revision sent out. In this situation, the "Organizer"
+ may wish to send an update "REQUEST", and set "RSVP=TRUE" for all
+ "Attendees", so that current responses can be collected.
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 10]
+
+RFC 2446 iTIP November 1998
+
+
+ The value of the "SEQUENCE" property contained in a response from an
+ "Attendee" may not always match the "Organizer's" revision.
+ Implementations may choose to have the CUA indicate to the CU that
+ the response is to an entry that has been revised and allow the CU to
+ decide whether or not to accept the response.
+
+2.1.5 Message Sequencing
+
+ CUAs that handle the [iTIP] application protocol must often correlate
+ a component in a calendar store with a component received in the
+ [iTIP] message. For example, an event may be updated with a later
+ revision of the same event. To accomplish this, a CUA must correlate
+ the version of the event already in its calendar store with the
+ version sent in the [iTIP] message. In addition to this correlation,
+ there are several factors that can cause [iTIP] messages to arrive in
+ an unexpected order. That is, an "Organizer" could receive a reply
+ to an earlier revision of a component AFTER receiving a reply to a
+ later revision.
+
+ To maximize interoperability and to handle messages that arrive in an
+ unexpected order, use the following rules:
+
+ 1. The primary key for referencing a particular iCalendar component
+ is the "UID" property value. To reference an instance of a
+ recurring component, the primary key is composed of the "UID" and
+ the "RECURRENCE-ID" properties.
+
+ 2. The secondary key for referencing a component is the "SEQUENCE"
+ property value. For components where the "UID" is the same, the
+ component with the highest numeric value for the "SEQUENCE"
+ property obsoletes all other revisions of the component with
+ lower values.
+
+ 3. "Attendees" send "REPLY" messages to the "Organizer". For
+ replies where the "UID" property value is the same, the value of
+ the "SEQUENCE" property indicates the revision of the component
+ to which the "Attendee" is replying. The reply with the highest
+ numeric value for the "SEQUENCE" property obsoletes all other
+ replies with lower values.
+
+ 4. In situations where the "UID" and "SEQUENCE" properties match,
+ the "DTSTAMP" property is used as the tie-breaker. The component
+ with the latest "DTSTAMP" overrides all others. Similarly, for
+ "Attendee" responses where the "UID" property values match and
+ the "SEQUENCE" property values match, the response with the
+ latest "DTSTAMP" overrides all others.
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 11]
+
+RFC 2446 iTIP November 1998
+
+
+ Hence, CUAs must persist the following component properties: "UID",
+ "RECURRENCE-ID", "SEQUENCE", and "DTSTAMP". Furthermore, for each
+ "ATTENDEE" property of a component CUAs must persist the "SEQUENCE"
+ and "DTSTAMP" property values associated with the "Attendee's"
+ response.
+
+3 Application Protocol Elements
+
+ ITIP messages are "text/calendar" MIME entities that contain
+ calendaring and scheduling information. The particular type of [iCAL]
+ message is referred to as the "method type". Each method type is
+ identified by a "METHOD" property specified as part of the
+ "text/calendar" content type. The table below shows various
+ combinations of calendar components and the method types that this
+ memo supports.
+
+ +=================================================+
+ | | VEVENT | VTODO | VJOURNAL | VFREEBUSY |
+ |=================================================|
+ |Publish | Yes | Yes | Yes | Yes |
+ |Request | Yes | Yes | No | Yes |
+ |Refresh | Yes | Yes | No | No |
+ |Cancel | Yes | Yes | Yes | No |
+ |Add | Yes | Yes | Yes | No |
+ |Reply | Yes | Yes | No | Yes |
+ |Counter | Yes | Yes | No | No |
+ |Decline- | | | | |
+ |Counter | Yes | Yes | No | No |
+ +=================================================+
+
+ Each method type is defined in terms of its associated components and
+ properties. Some components and properties are required, some are
+ optional and others are excluded. The restrictions are expressed in
+ this document using a simple "restriction table". The first column
+ indicates the name of a component or property. Properties of the
+ iCalendar object are not indented. Properties of a component are
+ indented. The second column contains "MUST" if the component or
+ property must be present, "MAY" if the component or property is
+ optional, and "NOT" if the component or property must not be present.
+ Entries in the second column sometimes contain comments for further
+ clarification.
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 12]
+
+RFC 2446 iTIP November 1998
+
+
+3.1 Common Component Restriction Tables
+
+ The restriction table below applies to properties of the iCalendar
+ object. That is, the properties at the outermost scope. The presence
+ column uses the following values to assert whether a property is
+ required, is optional and the number of times it may appear in the
+ iCalendar object.
+
+ Presence Value Description
+ --------------------------------------------------------------
+ 1 One instance MUST be present
+ 1+ At least one instance MUST be present
+ 0 Instances of this property Must NOT be present
+ 0+ Multiple instances MAY be present
+ 0 or 1 Up to 1 instance of this property MAY be present
+ ---------------------------------------------------------------
+
+ The tables also call out "X-PROPERTY" and "X-COMPONENT" to show
+ where vendor-specific properties and components can appear. The
+ tables do not lay out the restrictions of property parameters. Those
+ restrictions are defined in [iCAL].
+
+ Component/Property Presence
+ ------------------- ----------------------------------------------
+ CALSCALE 0 or 1
+ PRODID 1
+ VERSION 1 Value MUST be "2.0"
+ X-PROPERTY 0+
+
+
+ DateTime values MAY refer to a "VTIMEZONE" component. The property
+ restrictions in the table below apply to any "VTIMEZONE" component in
+ an ITIP message.
+
+ Component/Property Presence
+ ------------------- ----------------------------------------------
+ VTIMEZONE 0+ MUST be present if any date/time refers
+ to timezone
+ DAYLIGHT 0+ MUST be one or more of either STANDARD or
+ DAYLIGHT
+ COMMENT 0 or 1
+ DTSTART 1 MUST be local time format
+ RDATE 0+ if present RRULE MUST NOT be present
+ RRULE 0+ if present RDATE MUST NOT be present
+ TZNAME 0 or 1
+ TZOFFSET 1
+ TZOFFSETFROM 1
+ TZOFFSETTO 1
+
+
+
+Silverberg, et. al. Standards Track [Page 13]
+
+RFC 2446 iTIP November 1998
+
+
+ X-PROPERTY 0+
+ LAST-MODIFIED 0 or 1
+ STANDARD 0+ MUST be one or more of either STANDARD or
+ DAYLIGHT
+ COMMENT 0 or 1
+ DTSTART 1 MUST be local time format
+ RDATE 0+ if present RRULE MUST NOT be present
+ RRULE 0+ if present RDATE MUST NOT be present
+ TZNAME 0 or 1
+ TZOFFSETFROM 1
+ TZOFFSETTO 1
+ X-PROPERTY 0+
+ TZID 1
+ TZURL 0 or 1
+ X-PROPERTY 0+
+
+ The property restrictions in the table below apply to any "VALARM"
+ component in an ITIP message.
+
+ Component/Property Presence
+ ------------------- ----------------------------------------------
+ VALARM 0+
+ ACTION 1
+ ATTACH 0+
+ DESCRIPTION 0 or 1
+ DURATION 0 or 1 if present REPEAT MUST be present
+ REPEAT 0 or 1 if present DURATION MUST be present
+ SUMMARY 0 or 1
+ TRIGGER 1
+ X-PROPERTY 0+
+
+3.2 Methods for VEVENT Calendar Components
+
+ This section defines the property set restrictions for the method
+ types that are applicable to the "VEVENT" calendar component. Each
+ method is defined using a table that clarifies the property
+ constraints that define the particular method.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 14]
+
+RFC 2446 iTIP November 1998
+
+
+ The following summarizes the methods that are defined for the
+ "VEVENT" calendar component.
+
+ +================+==================================================+
+ | Method | Description |
+ |================+==================================================|
+ | PUBLISH | Post notification of an event. Used primarily as |
+ | | a method of advertising the existence of an |
+ | | event. |
+ | | |
+ | REQUEST | Make a request for an event. This is an explicit |
+ | | invitation to one or more "Attendees". Event |
+ | | Requests are also used to update or change an |
+ | | existing event. Clients that cannot handle |
+ | | REQUEST may degrade the event to view it as an |
+ | | PUBLISH. |
+ | | |
+ | REPLY | Reply to an event request. Clients may set their |
+ | | status ("partstat") to ACCEPTED, DECLINED, |
+ | | TENTATIVE, or DELEGATED. |
+ | | |
+ | ADD | Add one or more instances to an existing event. |
+ | | |
+ | CANCEL | Cancel one or more instances of an existing |
+ | | event. |
+ | | |
+ | REFRESH | A request is sent to an "Organizer" by an |
+ | | "Attendee" asking for the latest version of an |
+ | | event to be resent to the requester. |
+ | | |
+ | COUNTER | Counter a REQUEST with an alternative proposal, |
+ | | Sent by an "Attendee" to the "Organizer". |
+ | | |
+ | DECLINECOUNTER | Decline a counter proposal. Sent to an |
+ | | "Attendee" by the "Organizer". |
+ +================+==================================================+
+
+3.2.1 PUBLISH
+
+ The "PUBLISH" method in a "VEVENT" calendar component is an
+ unsolicited posting of an iCalendar object. Any CU may add published
+ components to their calendar. The "Organizer" MUST be present in a
+ published iCalendar component. "Attendees" MUST NOT be present. Its
+ expected usage is for encapsulating an arbitrary event as an
+ iCalendar object. The "Organizer" may subsequently update (with
+ another "PUBLISH" method), add instances to (with an "ADD" method),
+ or cancel (with a "CANCEL" method) a previously published "VEVENT"
+ calendar component.
+
+
+
+Silverberg, et. al. Standards Track [Page 15]
+
+RFC 2446 iTIP November 1998
+
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST equal "PUBLISH"
+VEVENT 1+
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ SUMMARY 1 Can be null.
+ UID 1
+ RECURRENCE-ID 0 or 1 only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+ SEQUENCE 0 or 1 MUST be present if value is greater than
+ 0, MAY be present if 0
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of
+ values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED/CANCELLED
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ ATTENDEE 0
+ REQUEST-STATUS 0
+
+VALARM 0+
+VFREEBUSY 0
+VJOURNAL 0
+
+
+
+Silverberg, et. al. Standards Track [Page 16]
+
+RFC 2446 iTIP November 1998
+
+
+VTODO 0
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+3.2.2 REQUEST
+
+ The "REQUEST" method in a "VEVENT" component provides the following
+ scheduling functions:
+
+ . Invite "Attendees" to an event;
+ . Reschedule an existing event;
+ . Response to a REFRESH request;
+ . Update the details of an existing event, without rescheduling it;
+ . Update the status of "Attendees" of an existing event, without
+ rescheduling it;
+ . Reconfirm an existing event, without rescheduling it;
+ . Forward a "VEVENT" to another uninvited CU.
+ . For an existing "VEVENT" calendar component, delegate the role of
+ "Attendee" to another CU;
+ . For an existing "VEVENT" calendar component, changing the role of
+ "Organizer" to another CU.
+
+ The "Organizer" originates the "REQUEST". The recipients of the
+ "REQUEST" method are the CUs invited to the event, the "Attendees".
+ "Attendees" use the "REPLY" method to convey attendance status to the
+ "Organizer".
+
+ The "UID" and "SEQUENCE" properties are used to distinguish the
+ various uses of the "REQUEST" method. If the "UID" property value in
+ the "REQUEST" is not found on the recipient's calendar, then the
+ "REQUEST" is for a new "VEVENT" calendar component. If the "UID"
+ property value is found on the recipient's calendar, then the
+ "REQUEST" is for a rescheduling, an update, or a reconfirm of the
+ "VEVENT" calendar component.
+
+ For the "REQUEST" method, multiple "VEVENT" components in a single
+ iCalendar object are only permitted when for components with the same
+ "UID" property. That is, a series of recurring events may have
+ instance-specific information. In this case, multiple "VEVENT"
+ components are needed to express the entire series.
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 17]
+
+RFC 2446 iTIP November 1998
+
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+-----------------------------------------------------------------
+METHOD 1 MUST be "REQUEST"
+VEVENT 1+ All components MUST have the same UID
+ ATTENDEE 1+
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ SEQUENCE 0 or 1 MUST be present if value is greater than 0,
+ MAY be present if 0
+ SUMMARY 1 Can be null
+ UID 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 only if referring to an instance of a
+ recurring calendar component. Otherwise it
+ MUST NOT be present.
+ RELATED-TO 0+
+ REQUEST-STATUS 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+VALARM 0+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 18]
+
+RFC 2446 iTIP November 1998
+
+
+VFREEBUSY 0
+VJOURNAL 0
+VTODO 0
+
+3.2.2.1 Rescheduling an Event
+
+ The "REQUEST" method may be used to reschedule an event. A
+ rescheduled event involves a change to the existing event in terms of
+ its time or recurrence intervals and possibly the location or
+ description. If the recipient CUA of a "REQUEST" method finds that
+ the "UID" property value already exists on the calendar, but that the
+ "SEQUENCE" (or "DTSTAMP") property value in the "REQUEST" method is
+ greater than the value for the existing event, then the "REQUEST"
+ method describes a rescheduling of the event.
+
+3.2.2.2 Updating or Reconfirmation of an Event
+
+ The "REQUEST" method may be used to update or reconfirm an event. An
+ update to an existing event does not involve changes to the time or
+ recurrence intervals, and might not involve a change to the location
+ or description for the event. If the recipient CUA of a "REQUEST"
+ method finds that the "UID" property value already exists on the
+ calendar and that the "SEQUENCE" property value in the "REQUEST" is
+ the same as the value for the existing event, then the "REQUEST"
+ method describes an update of the event details, but no rescheduling
+ of the event.
+
+ The update "REQUEST" method is the appropriate response to a
+ "REFRESH" method sent from an "Attendee" to the "Organizer" of an
+ event.
+
+ The "Organizer" of an event may also send unsolicited "REQUEST"
+ methods. The unsolicited "REQUEST" methods may be used to update the
+ details of the event without rescheduling it, to update the
+ "partstat" parameter of "Attendees", or to reconfirm the event.
+
+3.2.2.3 Delegating an Event to another CU
+
+ Some calendar and scheduling systems allow "Attendees" to delegate
+ their presence at an event to another calendar user. ITIP supports
+ this concept using the following workflow. Any "Attendee" may
+ delegate their right to participate in a calendar VEVENT to another
+ CU. The implication is that the delegate participates in lieu of the
+ original "Attendee"; NOT in addition to the "Attendee". The delegator
+ MUST notify the "Organizer" of this action using the steps outlined
+ below. Implementations may support or restrict delegation as they
+ see fit. For instance, some implementations may restrict a delegate
+ from delegating a "REQUEST" to another CU.
+
+
+
+Silverberg, et. al. Standards Track [Page 19]
+
+RFC 2446 iTIP November 1998
+
+
+ The "Delegator" of an event forwards the existing "REQUEST" to the
+ "Delegate". The "REQUEST" method MUST include an "ATTENDEE" property
+ with the calendar address of the "Delegate". The "Delegator" MUST
+ also send a "REPLY" method to the "Organizer" with the "Delegator's"
+ "ATTENDEE" property "partstat" parameter value set to "delegated". In
+ addition, the "delegated-to" parameter MUST be included with the
+ calendar address of the "Delegate".
+
+ In response to the request, the "Delegate" MUST send a "REPLY" method
+ to the "Organizer" and optionally, to the "Delegator". The "REPLY"
+ method " SHOULD include the "ATTENDEE" property with the "delegated-
+ from" parameter value of the "Delegator's" calendar address.
+
+ The "Delegator" may continue to receive updates to the event even
+ though they will not be attending. This is accomplished by the
+ "Delegator" setting their "role" attribute to " NON-PARTICIPANT" in
+ the "REPLY" to the "Organizer"
+
+3.2.2.4 Changing the Organizer
+
+ The situation may arise where the "Organizer" of a VEVENT is no
+ longer able to perform the "Organizer" role and abdicates without
+ passing on the "Organizer" role to someone else. When this occurs the
+ "Attendees" of the VEVENT may use out-of-band mechanisms to
+ communicate the situation and agree upon a new "Organizer". The new
+ "Organizer" should then send out a new "REQUEST" with a modified
+ version of the VEVENT in which the "SEQUENCE" number has been
+ incremented and value of the "ORGANIZER" property has been changed to
+ the calendar address of the new "Organizer".
+
+3.2.2.5 Sending on Behalf of the Organizer
+
+ There are a number of scenarios that support the need for a calendar
+ user to act on behalf of the "Organizer" without explicit role
+ changing. This might be the case if the CU designated as "Organizer"
+ was sick or unable to perform duties associated with that function.
+ In these cases iTIP supports the notion of one CU acting on behalf of
+ another. Using the "sent-by" parameter, a calendar user could send an
+ updated "VEVENT" REQUEST. In the case where one CU sends on behalf of
+ another CU, the "Attendee" responses are still directed back towards
+ the CU designated as "Organizer".
+
+3.2.2.6 Forwarding to An Uninvited CU
+
+ An "Attendee" invited to an event may invite another uninvited CU to
+ the event. The invited "Attendee" accomplishes this by forwarding the
+ original "REQUEST" method to the uninvited CU. The "Organizer"
+ decides whether or not the uninvited CU is added to the attendee
+
+
+
+Silverberg, et. al. Standards Track [Page 20]
+
+RFC 2446 iTIP November 1998
+
+
+ list. If the "Organizer" decides not to add the uninvited CU no
+ further action is required, however the "Organizer" MAY send the
+ uninvited CU a "CANCEL" message. If the "Organizer" decides to add
+ an uninvited CU, a new "ATTENDEE" property is added for the uninvited
+ CU with its property parameters set as the "Organizer" deems
+ appropriate. When forwarding a "REQUEST" to another CU, the
+ forwarding "Attendee" MUST NOT make changes to the VEVENT property
+ set.
+
+3.2.2.7 Updating Attendee Status
+
+ The "Organizer" of an event may also request updated status from one
+ or more "Attendees. The "Organizer" sends a "REQUEST" method to the
+ "Attendee" and sets the "ATTENDEE;RSVP=TRUE" property parameter. The
+ "SEQUENCE" property for the event is not changed from its previous
+ value. A recipient will determine that the only change in the
+ "REQUEST" is that their "RSVP" property parameter indicates a request
+ for updated status. The recipient SHOULD respond with a "REPLY"
+ method indicating their current status with respect to the "REQUEST".
+
+3.2.3 REPLY
+
+ The "REPLY" method in a "VEVENT" calendar component is used to
+ respond (e.g., accept or decline) to a "REQUEST" or to reply to a
+ delegation "REQUEST". When used to provide a delegation response, the
+ "Delegator" SHOULD include the calendar address of the "Delegate" on
+ the "delegated-to" property parameter of the "Delegator's" "ATTENDEE"
+ property. The "Delegate" SHOULD include the calendar address of the
+ "Delegator" on the "delegated-from" property parameter of the
+ "Delegate's" "ATTENDEE" property.
+
+ The "REPLY" method may also be used to respond to an unsuccessful
+ "REQUEST" method. Depending on the value of the "REQUEST-STATUS"
+ property no scheduling action may have been performed.
+
+ The "Organizer" of an event may receive the "REPLY" method from a CU
+ not in the original "REQUEST". For example, a "REPLY" may be received
+ from a "Delegate" to an event. In addition, the "REPLY" method may be
+ received from an unknown CU (a "Party Crasher"). This uninvited
+ "Attendee" may be accepted, or the "Organizer" may cancel the event
+ for the uninvited "Attendee" by sending a "CANCEL" method to the
+ uninvited "Attendee".
+
+ An "Attendee" can include a message to the "Organizer" using the
+ "COMMENT" property. For example, if the user indicates tentative
+ acceptance and wants to let the "Organizer" know why, the reason can
+ be expressed in the "COMMENT" property value.
+
+
+
+
+Silverberg, et. al. Standards Track [Page 21]
+
+RFC 2446 iTIP November 1998
+
+
+ The "Organizer" may also receive a "REPLY" from one CU on behalf of
+ another. Like the scenario enumerated above for the "Organizer",
+ "Attendees" may have another CU respond on their behalf. This is done
+ using the "sent-by" parameter.
+
+ The optional properties listed in the table below (those listed as
+ "0+" or "0 or 1") MUST NOT be changed from those of the original
+ request. If property changes are desired the COUNTER message must be
+ used.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "REPLY"
+VEVENT 1+ All components MUST have the same UID
+ ATTENDEE 1 MUST be the address of the Attendee
+ replying.
+ DTSTAMP 1
+ ORGANIZER 1
+ RECURRENCE-ID 0 or 1 only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it must NOT be present.
+ UID 1 MUST be the UID of the original REQUEST
+
+ SEQUENCE 0 or 1 MUST if non-zero, MUST be the sequence
+ number of the original REQUEST. MAY be
+ present if 0.
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DTSTART 0 or 1
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 22]
+
+RFC 2446 iTIP November 1998
+
+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ REQUEST-STATUS 0+
+ RRULE 0+
+ STATUS 0 or 1
+ SUMMARY 0 or 1
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+VTIMEZONE 0 or 1 MUST be present if any date/time refers
+ to a timezone
+X-COMPONENT 0+
+
+VALARM 0
+VFREEBUSY 0
+VJOURNAL 0
+VTODO 0
+
+3.2.4 ADD
+
+ The "ADD" method in a "VEVENT" calendar component is used to add one
+ or more instances to an existing "VEVENT". Unlike the "REQUEST"
+ method, when using issuing an "ADD" method, the "Organizer" does not
+ send the full "VEVENT" description; only the new instance(s). The
+ "ADD" method is especially useful if there are instance-specific
+ properties to be preserved in a recurring "VEVENT". For instance, an
+ "Organizer" may have originally scheduled a weekly Thursday meeting.
+ At some point, several instances changed. Location or start time may
+ have changed, or some instances may have unique "DESCRIPTION"
+ properties. The "ADD" method allows the "Organizer" to add new
+ instances to an existing event using a single ITIP message without
+ redefining the entire recurring pattern.
+
+ The "UID" must be that of the existing event. If the "UID" property
+ value in the "ADD" is not found on the recipient's calendar, then the
+ recipient SHOULD send a "REFRESH" to the "Organizer" in order to be
+ updated with the latest version of the "VEVENT". If an "Attendee"
+ implementation does not support the "ADD" method it should respond
+ with a "REQUEST-STATUS" value of 3.14 and ask for a "REFRESH".
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 23]
+
+RFC 2446 iTIP November 1998
+
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "ADD"
+VEVENT 1
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ SEQUENCE 1 MUST be greater than 0
+ SUMMARY 1 Can be null
+ UID 1 MUST match that of the original event
+
+ ATTACH 0+
+ ATTENDEE 0+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ RECURRENCE-ID 0
+ REQUEST-STATUS 0
+
+VALARM 0+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VFREEBUSY 0
+VTODO 0
+VJOURNAL 0
+
+
+
+
+Silverberg, et. al. Standards Track [Page 24]
+
+RFC 2446 iTIP November 1998
+
+
+3.2.5 CANCEL
+
+ The "CANCEL" method in a "VEVENT" calendar component is used to send
+ a cancellation notice of an existing event request to the
+ "Attendees". The message is sent by the "Organizer" of the event. For
+ a recurring event, either the whole event or instances of an event
+ may be cancelled. To cancel the complete range of recurring event,
+ the "UID" property value for the event MUST be specified and a
+ "RECURRENCE-ID" MUST NOT be specified in the "CANCEL" method. In
+ order to cancel an individual instance of the event, the
+ "RECURRENCE-ID" property value for the event MUST be specified in the
+ "CANCEL" method.
+
+ There are two options for canceling a sequence of instances of a
+ recurring "VEVENT" calendar component:
+
+ (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
+ be specified with the "RANGE" property parameter value of
+ THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
+ specified "VEVENT" calendar component and all instances before
+ (or after); or
+
+ (b) individual recurrence instances may be cancelled by specifying
+ multiple "RECURRENCE-ID" properties corresponding to the
+ instances to be cancelled.
+
+ When a "VEVENT" is cancelled, the "SEQUENCE" property value MUST be
+ incremented.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "CANCEL"
+
+VEVENT 1+ All must have the same UID
+ ATTENDEE 0+ MUST include all "Attendees" being removed
+ the event. MUST include all "Attendees" if
+ the entire event is cancelled.
+ DTSTAMP 1
+ ORGANIZER 1
+ SEQUENCE 1
+ UID 1 MUST be the UID of the original REQUEST
+
+ COMMENT 0 or 1
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+
+
+
+Silverberg, et. al. Standards Track [Page 25]
+
+RFC 2446 iTIP November 1998
+
+
+ CLASS 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DTSTART 0 or 1
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST be present if referring to one or
+ more or more recurring instances.
+ Otherwise it MUST NOT be present
+ RELATED-TO 0+
+ RESOURCES 0 or 1
+ RRULE 0+
+ STATUS 0 or 1 MUST be set to CANCELLED. If uninviting
+ specific "Attendees" then MUST NOT be
+ included.
+ SUMMARY 0 or 1
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+ REQUEST-STATUS 0
+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VTODO 0
+VJOURNAL 0
+VFREEBUSY 0
+VALARM 0
+
+3.2.6 REFRESH
+
+ The "REFRESH" method in a "VEVENT" calendar component is used by
+ "Attendees" of an existing event to request an updated description
+ from the event "Organizer". The "REFRESH" method must specify the
+ "UID" property of the event to update. A recurrence instance of an
+ event may be requested by specifying the "RECURRENCE-ID" property
+ corresponding to the associated event. The "Organizer" responds with
+ the latest description and version of the event.
+
+
+
+
+Silverberg, et. al. Standards Track [Page 26]
+
+RFC 2446 iTIP November 1998
+
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "REFRESH"
+
+VEVENT 1
+ ATTENDEE 1 MUST be the address of requestor
+ DTSTAMP 1
+ ORGANIZER 1
+ UID 1 MUST be the UID associated with original
+ REQUEST
+ COMMENT 0 or 1
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it must NOT be present.
+ X-PROPERTY 0+
+
+ ATTACH 0
+ CATEGORIES 0
+ CLASS 0
+ CONTACT 0
+ CREATED 0
+ DESCRIPTION 0
+ DTEND 0
+ DTSTART 0
+ DURATION 0
+ EXDATE 0
+ EXRULE 0
+ GEO 0
+ LAST-MODIFIED 0
+ LOCATION 0
+ PRIORITY 0
+ RDATE 0
+ RELATED-TO 0
+ REQUEST-STATUS 0
+ RESOURCES 0
+ RRULE 0
+ SEQUENCE 0
+ STATUS 0
+ SUMMARY 0
+ TRANSP 0
+ URL 0
+
+X-COMPONENT 0+
+
+VTODO 0
+
+
+
+Silverberg, et. al. Standards Track [Page 27]
+
+RFC 2446 iTIP November 1998
+
+
+VJOURNAL 0
+VFREEBUSY 0
+VTIMEZONE 0
+VALARM 0
+
+3.2.7 COUNTER
+
+ The "COUNTER" method for a "VEVENT" calendar component is used by an
+ "Attendee" of an existing event to submit to the "Organizer" a
+ counter proposal to the event description. The "Attendee" sends this
+ message to the "Organizer" of the event.
+
+ The counter proposal is an iCalendar object consisting of a VEVENT
+ calendar component describing the complete description of the
+ alternate event.
+
+ The "Organizer" rejects the counter proposal by sending the
+ "Attendee" a VEVENT "DECLINECOUNTER" method. The "Organizer" accepts
+ the counter proposal by rescheduling the event as described in
+ section 3.2.2.1 Rescheduling an Event.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "COUNTER"
+
+VEVENT 1
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1 MUST be the "Organizer" of the original
+ event
+ SEQUENCE 1 MUST be present if value is greater than 0,
+ MAY be present if 0
+ SUMMARY 1 Can be null
+ UID 1 MUST be the UID associated with the REQUEST
+ being countered
+
+ ATTACH 0+
+ ATTENDEE 0+ Can also be used to propose other
+ "Attendees"
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+
+
+
+Silverberg, et. al. Standards Track [Page 28]
+
+RFC 2446 iTIP November 1998
+
+
+ DTEND 0 or 1 if present DURATION MUST NOT be present
+ DURATION 0 or 1 if present DTEND MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ recurring calendar component. Otherwise it
+ MUST NOT be present.
+ RELATED-TO 0+
+ REQUEST-STATUS 0+
+ RESOURCES 0 or 1 This property may contain a list of values
+ RRULE 0+
+ STATUS 0 or 1 Value must be one of CONFIRMED/TENATIVE/
+ CANCELLED
+ TRANSP 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+VALARM 0+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VTODO 0
+VJOURNAL 0
+VFREEBUSY 0
+
+3.2.8 DECLINECOUNTER
+
+ The "DECLINECOUNTER" method in a "VEVENT" calendar component is used
+ by the "Organizer" of an event to reject a counter proposal submitted
+ by an "Attendee". The "Organizer" must send the "DECLINECOUNTER"
+ message to the "Attendee" that sent the "COUNTER" method to the
+ "Organizer".
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 29]
+
+RFC 2446 iTIP November 1998
+
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "DECLINECOUNTER"
+
+VEVENT 1
+ DTSTAMP 1
+ ORGANIZER 1
+ UID 1 MUST, same UID specified in original
+ REQUEST and subsequent COUNTER
+ COMMENT 0 or 1
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ recurring calendar component. Otherwise it
+ MUST NOT be present.
+ REQUEST-STATUS 0+
+ SEQUENCE 0 OR 1 MUST be present if value is greater than 0,
+ MAY be present if 0
+ X-PROPERTY 0+
+ ATTACH 0
+ ATTENDEE 0
+ CATEGORIES 0
+ CLASS 0
+ CONTACT 0
+ CREATED 0
+ DESCRIPTION 0
+ DTEND 0
+ DTSTART 0
+ DURATION 0
+ EXDATE 0
+ EXRULE 0
+ GEO 0
+ LAST-MODIFIED 0
+ LOCATION 0
+ PRIORITY 0
+ RDATE 0
+ RELATED-TO 0
+ RESOURCES 0
+ RRULE 0
+ STATUS 0
+ SUMMARY 0
+ TRANSP 0
+ URL 0
+
+X-COMPONENT 0+
+VTODO 0
+VJOURNAL 0
+VFREEBUSY 0
+VTIMEZONE 0
+VALARM 0
+
+
+
+Silverberg, et. al. Standards Track [Page 30]
+
+RFC 2446 iTIP November 1998
+
+
+3.3 Methods For VFREEBUSY Components
+
+ This section defines the property set for the methods that are
+ applicable to the "VFREEBUSY" calendar component. Each of the methods
+ is defined using a restriction table.
+
+ This document only addresses the transfer of busy time information.
+ Applications desiring free time information MUST infer this from
+ available busy time information.
+
+ The busy time information within the iCalendar object MAY be grouped
+ into more than one "VFREEBUSY" calendar component. This capability
+ allows busy time periods to be grouped according to some common
+ periodicity, such as a calendar week, month, or year. In this case,
+ each "VFREEBUSY" calendar component MUST include the "ATTENDEE",
+ "DTSTART" and "DTEND" properties in order to specify the source of
+ the busy time information and the date and time interval over which
+ the busy time information covers.
+
+ The "FREEBUSY" property value MAY include a list of values, separated
+ by the COMMA character ([US-ASCII] decimal 44). Alternately, multiple
+ busy time periods MAY be specified with multiple instances of the
+ "FREEBUSY" property. Both forms MUST be supported by implementations
+ conforming to this document. Duplicate busy time periods SHOULD NOT
+ be specified in an iCalendar object. However, two different busy time
+ periods MAY overlap.
+
+ "FREEBUSY" properties should be sorted such that their values are in
+ ascending order, based on the start time, and then the end time, with
+ the earliest periods first. For example, today's busy time
+ information should appear after yesterday's busy time information.
+ And the busy time for this half-hour should appear after the busy
+ time for earlier today.
+
+ Since events may span a day boundary, free busy time period may also
+ span a day boundary. Individual "A" requests busy time from
+ individuals "B", "C" and "D". Individual "B" and "C" replies with
+ busy time data to individual "A". Individual "D" does not support
+ busy time requests and does not reply with any data. If the transport
+ binding supports exception messages, then individual "D" returns an
+ "unsupported capability" message to individual "A4.34.3".
+
+ The following summarizes the methods that are defined for the
+ "VFREEBUSY" calendar component.
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 31]
+
+RFC 2446 iTIP November 1998
+
+
+ |================|==================================================|
+ | Method | Description |
+ |================|==================================================|
+ | PUBLISH | Publish unsolicited busy time data. |
+ | REQUEST | Request busy time data. |
+ | REPLY | Reply to a busy time request. |
+ |================|==================================================|
+
+3.3.1 PUBLISH
+
+ The "PUBLISH" method in a "VFREEBUSY" calendar component is used to
+ publish busy time data. The method may be sent from one CU to any
+ other. The purpose of the method is to provide a message for sending
+ unsolicited busy time data. That is, the busy time data is not being
+ sent as a "REPLY" to the receipt of a "REQUEST" method.
+
+ The "ATTENDEE" property must be specified in the busy time
+ information. The value is the CU address of the originator of the
+ busy time information.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "PUBLISH"
+
+VFREEBUSY 1+
+ DTSTAMP 1
+ DTSTART 1 DateTime values must be in UTC
+ DTEND 1 DateTime values must be in UTC
+ FREEBUSY 1+ MUST be BUSYTIME. Multiple instances are
+ allowed. Multiple instances must be sorted
+ in ascending order
+ ORGANIZER 1 MUST contain the address of originator of
+ busy time data.
+
+ COMMENT 0 or 1
+ CONTACT 0+
+ X-PROPERTY 0+
+ URL 0 or 1 Specifies busy time URL
+
+ ATTENDEE 0
+ DURATION 0
+ REQUEST-STATUS 0
+ UID 0
+
+X-COMPONENT 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 32]
+
+RFC 2446 iTIP November 1998
+
+
+VEVENT 0
+VTODO 0
+VJOURNAL 0
+VTIMEZONE 0
+VALARM 0
+
+3.3.2 REQUEST
+
+ The "REQUEST" method in a "VFREEBUSY" calendar component is used to
+ ask a "Calendar User" for their busy time information. The request
+ may be for a busy time information bounded by a specific date and
+ time interval.
+
+ This message only permits requests for busy time information. The
+ message is sent from a "Calendar User" requesting the busy time
+ information to one or more intended recipients.
+
+ If the originator of the "REQUEST" method is not authorized to make a
+ busy time request on the recipient's calendar system, then an
+ exception message SHOULD be returned in a "REPLY" method, but no busy
+ time data need be returned.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "REQUEST"
+
+VFREEBUSY 1
+ ATTENDEE 1+ contain the address of the calendar store
+ DTEND 1 DateTime values must be in UTC
+ DTSTAMP 1
+ DTSTART 1 DateTime values must be in UTC
+ ORGANIZER 1 MUST be the request originator's address
+ UID 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ X-PROPERTY 0+
+
+ FREEBUSY 0
+ DURATION 0
+ REQUEST-STATUS 0
+ URL 0
+
+X-COMPONENT 0+
+VALARM 0
+VEVENT 0
+
+
+
+Silverberg, et. al. Standards Track [Page 33]
+
+RFC 2446 iTIP November 1998
+
+
+VTODO 0
+VJOURNAL 0
+VTIMEZONE 0
+
+3.3.3 REPLY
+
+ The "REPLY" method in a "VFREEBUSY" calendar component is used to
+ respond to a busy time request. The method is sent by the recipient
+ of a busy time request to the originator of the request.
+
+ The "REPLY" method may also be used to respond to an unsuccessful
+ "REQUEST" method. Depending on the "REQUEST-STATUS" value, no busy
+ time information may be returned.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "REPLY"
+
+VFREEBUSY 1
+ ATTENDEE 1 (address of recipient replying)
+ DTSTAMP 1
+ DTEND 1 DateTime values must be in UTC
+ DTSTART 1 DateTime values must be in UTC
+ FREEBUSY 1+ (values MUST all be of the same data
+ type. Multiple instances are allowed.
+ Multiple instances MUST be sorted in
+ ascending order. Values MAY NOT overlap)
+ ORGANIZER 1 MUST be the request originator's address
+ UID 1
+
+ COMMENT 0 or 1
+ CONTACT 0+
+ REQUEST-STATUS 0+
+ URL 0 or 1 (specifies busy time URL)
+ X-PROPERTY 0+
+ DURATION 0
+ SEQUENCE 0
+
+X-COMPONENT 0+
+VALARM 0
+VEVENT 0
+VTODO 0
+VJOURNAL 0
+VTIMEZONE 0
+
+
+
+
+Silverberg, et. al. Standards Track [Page 34]
+
+RFC 2446 iTIP November 1998
+
+
+3.4 Methods For VTODO Components
+
+ This section defines the property set for the methods that are
+ applicable to the "VTODO" calendar component. Each of the methods is
+ defined using a restriction table that specifies the property
+ constraints that define the particular method.
+
+ The following summarizes the methods that are defined for the "VTODO"
+ calendar component.
+
+ +================+==================================================+
+ | Method | Description |
+ |================+==================================================|
+ | PUBLISH | Post notification of a VTODO. Used primarily as |
+ | | a method of advertising the existence of a VTODO.|
+ | | |
+ | REQUEST | Assign a VTODO. This is an explicit assignment to|
+ | | one or more Calendar Users. The REQUEST method |
+ | | is also used to update or change an existing |
+ | | VTODO. Clients that cannot handle REQUEST MAY |
+ | | degrade the method to treat it as a PUBLISH. |
+ | | |
+ | REPLY | Reply to a VTODO request. Attendees MAY set |
+ | | PARTSTAT to ACCEPTED, DECLINED, TENTATIVE, |
+ | | DELEGATED, PARTIAL, and COMPLETED. |
+ | | |
+ | ADD | Add one or more instances to an existing to-do. |
+ | | |
+ | CANCEL | Cancel one or more instances of an existing |
+ | | to-do. |
+ | | |
+ | REFRESH | A request sent to a VTODO Organizer asking for |
+ | | the latest version of a VTODO. |
+ | | |
+ | COUNTER | Counter a REQUEST with an alternative proposal. |
+ | | |
+ | DECLINECOUNTER | Decline a counter proposal by an Attendee. |
+ +================+==================================================+
+
+3.4.1 PUBLISH
+
+ The "PUBLISH" method in a "VTODO" calendar component has no
+ associated response. It is simply a posting of an iCalendar object
+ that maybe added to a calendar. It MUST have an "Organizer". It MUST
+ NOT have "Attendees". Its expected usage is for encapsulating an
+ arbitrary "VTODO" calendar component as an iCalendar object. The
+ "Organizer" MAY subsequently update (with another "PUBLISH" method),
+ add instances to (with an "ADD" method), or cancel (with a "CANCEL"
+
+
+
+Silverberg, et. al. Standards Track [Page 35]
+
+RFC 2446 iTIP November 1998
+
+
+ method) a previously published "VTODO" calendar component.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "PUBLISH"
+VTODO 1+
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ PRIORITY 1
+ SEQUENCE 0 or 1 MUST be present if value is greater than
+ 0, MAY be present if 0
+ SUMMARY 1 Can be null.
+ UID 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property may contain a list of values
+ RRULE 0+
+STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
+ PROCESS/CANCELLED
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ ATTENDEE 0
+ REQUEST-STATUS 0
+
+
+
+Silverberg, et. al. Standards Track [Page 36]
+
+RFC 2446 iTIP November 1998
+
+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+VALARM 0+
+X-COMPONENT 0+
+
+VFREEBUSY 0
+VEVENT 0
+VJOURNAL 0
+
+3.4.2 REQUEST
+
+ The "REQUEST" method in a "VTODO" calendar component provides the
+ following scheduling functions:
+
+ . Assign a to-do to one or more "Calendar Users";
+ . Reschedule an existing to-do;
+ . Update the details of an existing to-do, without rescheduling
+ it;
+ . Update the completion status of "Attendees" of an existing
+ to-do, without rescheduling it;
+ . Reconfirm an existing to-do, without rescheduling it;
+ . Delegate/reassign an existing to-do to another "Calendar User".
+
+ The assigned "Calendar Users" are identified in the "VTODO" calendar
+ component by individual "ATTENDEE;ROLE=REQ-PARTICIPANT" property
+ value sequences.
+
+ The originator of a "REQUEST" is the "Organizer" of the to-do. The
+ recipient of a "REQUEST" is the "Calendar User" assigned the to-do.
+ The "Attendee" uses the "REPLY" method to convey their acceptance and
+ completion status to the "Organizer" of the "REQUEST".
+
+ The "UID", "SEQUENCE", and "DTSTAMP" properties are used to
+ distinguish the various uses of the "REQUEST" method. If the "UID"
+ property value in the "REQUEST" is not found on the recipient's
+ calendar, then the "REQUEST" is for a new to-do. If the "UID"
+ property value is found on the recipient's calendar, then the
+ "REQUEST" is a rescheduling, an update, or a reconfirm of the "VTODO"
+ calendar object.
+
+ If the "Organizer" of the "REQUEST" method is not authorized to make
+ a to-do request on the "Attendee's" calendar system, then an
+ exception is returned in the "REQUEST-STATUS" property of a
+ subsequent "REPLY" method, but no scheduling action is performed.
+
+ For the "REQUEST" method, multiple "VTODO" components in a single
+ iCalendar object are only permitted when for components with the same
+ "UID" property. That is, a series of recurring events may have
+
+
+
+Silverberg, et. al. Standards Track [Page 37]
+
+RFC 2446 iTIP November 1998
+
+
+ instance-specific information. In this case, multiple "VTODO"
+ components are needed to express the entire series.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "REQUEST"
+VTODO 1+ All components must have the same UID
+ ATTENDEE 1+
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ PRIORITY 1
+ SEQUENCE 0 or 1 MUST be present if value is greater than
+ 0, MAY be present if 0
+ SUMMARY 1 Can be null.
+ UID 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of
+ values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 present if referring to an instance of a
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property may contain a list of
+ values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
+ PROCESS
+ URL 0 or 1
+ X-PROPERTY 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 38]
+
+RFC 2446 iTIP November 1998
+
+
+ REQUEST-STATUS 0
+
+VALARM 0+
+
+VTIMEZONE 0+ MUST be present if any date/time refers
+ to a timezone
+X-COMPONENT 0+
+
+VEVENT 0
+VFREEBUSY 0
+VJOURNAL 0
+
+3.4.2.1 REQUEST for Rescheduling a VTODO
+
+ The "REQUEST" method may be used to reschedule a "VTODO" calendar
+ component.
+
+ Rescheduling a "VTODO" calendar component involves a change to the
+ existing "VTODO" calendar component in terms of its start or due time
+ or recurrence intervals and possibly the description. If the
+ recipient CUA of a "REQUEST" method finds that the "UID" property
+ value already exists on the calendar, but that the "SEQUENCE"
+ property value in the "REQUEST" is greater than the value for the
+ existing VTODO, then the "REQUEST" method describes a rescheduling of
+ the "VTODO" calendar component.
+
+3.4.2.2 REQUEST for Update or Reconfirmation of a VTODO
+
+ The "REQUEST" method may be used to update or reconfirm a "VTODO"
+ calendar component. Reconfirmation is merely an update of "Attendee"
+ completion status or overall "VTODO" calendar component status.
+
+ An update to an existing "VTODO" calendar component does not involve
+ changes to the start or due time or recurrence intervals, nor
+ generally to the description for the "VTODO" calendar component. If
+ the recipient CUA of a "REQUEST" method finds that the "UID" property
+ value already exists on the calendar and that the "SEQUENCE" property
+ value in the "REQUEST" is the same as the value for the existing
+ event, then the "REQUEST" method describes an update of the "VTODO"
+ calendar component details, but not a rescheduling of the "VTODO"
+ calendar component.
+
+ The update "REQUEST" is the appropriate response to a "REFRESH"
+ method sent from an "Attendee" to the "Organizer" of a "VTODO"
+ calendar component.
+
+ Unsolicited "REQUEST" methods MAY be sent by the "Organizer" of a
+ "VTODO" calendar component. The unsolicited "REQUEST" methods are
+
+
+
+Silverberg, et. al. Standards Track [Page 39]
+
+RFC 2446 iTIP November 1998
+
+
+ used to update the details of the "VTODO" (without rescheduling it or
+ updating the completion status of "Attendees") or the "VTODO"
+ calendar component itself (i.e., reconfirm the "VTODO").
+
+3.4.2.3 REQUEST for Delegating a VTODO
+
+ The "REQUEST" method is also used to delegate or reassign ownership
+ of a "VTODO" calendar component to another "Calendar User". For
+ example, it may be used to delegate an "Attendee's" role (i.e.
+ "chair", or "participant") for a "VTODO" calendar component. The
+ "REQUEST" method is sent by one of the "Attendees" of an existing
+
+ "VTODO" calendar component to some other individual. An "Attendee" of
+ a "VTODO" calendar component MUST NOT delegate to the "Organizer" of
+ the event.
+
+ For the purposes of this description, the "Attendee" delegating the
+ "VTODO" calendar component is referred to as the "Delegator". The
+ "Attendee" receiving the delegation request is referred to as the
+ "Delegate".
+
+ The "Delegator" of a "VTODO" calendar component MUST forward the
+ existing "REQUEST" method for a "VTODO" calendar component to the
+ "Delegate". The "VTODO" calendar component description MUST include
+ the "Delegator's" up-to-date "VTODO" calendar component definition.
+ The "REQUEST" method MUST also include an "ATTENDEE" property with
+ the calendar address of the "Delegate". The "Delegator" MUST also
+ send a "REPLY" method back to the "Organizer" with the "Delegator's"
+ "Attendee" property "partstat" parameter value set to "DELEGATED". In
+ addition, the "delegated-to" parameter MUST be included with the
+ calendar address of the "Delegate". A response to the delegation
+ "REQUEST" is sent from the "Delegate" to the "Organizer" and
+ optionally, to the "Delegator". The "REPLY" method from the
+ "Delegate" SHOULD include the "ATTENDEE" property with their calendar
+ address and the "delegated-from" parameter with the value of the
+ "Delegator's" calendar address.
+
+ The delegation "REQUEST" method MUST assign a value for the "RSVP"
+ property parameter associated with the "Delegator's" "Attendee"
+ property to that of the "Delegate's" "ATTENDEE" property. For example
+ if the "Delegator's" "ATTENDEE" property specifies "RSVP=TRUE", then
+ the "Delegate's" "ATTENDEE" property MUST specify "RSVP=TRUE".
+
+3.4.2.4 REQUEST Forwarded To An Uninvited Calendar User
+
+ An "Attendee" assigned a "VTODO" calendar component may send the
+ "VTODO" calendar component to another new CU, not previously
+ associated with the "VTODO" calendar component. The current
+
+
+
+Silverberg, et. al. Standards Track [Page 40]
+
+RFC 2446 iTIP November 1998
+
+
+ "Attendee" assigned the "VTODO" calendar component does this by
+ forwarding the original "REQUEST" method to the new CU. The new CU
+ can send a "REPLY" to the "Organizer" of the "VTODO" calendar
+ component. The reply contains an "ATTENDEE" property for the new CU.
+
+ The "Organizer" ultimately decides whether or not the new CU becomes
+ part of the to-do and is not obligated to do anything with a "REPLY"
+ from a new (uninvited) CU. If the "Organizer" does not want the new
+ CU to be part of the to-do, the new "ATTENDEE" property is not added
+ to the "VTODO" calendar component. The "Organizer" MAY send the CU a
+ "CANCEL" message to indicate that they will not be added to the to-
+ do. If the "Organizer" decides to add the new CU, the new "ATTENDEE"
+ property is added to the "VTODO" calendar component. Furthermore, the
+ "Organizer" is free to change any "ATTENDEE" property parameter from
+ the values supplied by the new CU to something the "Organizer"
+ considers appropriate.
+
+3.4.2.5 REQUEST Updated Attendee Status
+
+ An "Organizer" of a "VTODO" may request an updated status from one or
+ more "Attendees". The "Organizer" sends a "REQUEST" method to the
+ "Attendee" with the "ATTENDEE;RSVP=TRUE" property sequence. The
+ "SEQUENCE" property for the "VTODO" is not changed from its previous
+ value. A recipient determines that the only change in the "REQUEST"
+ is that their "RSVP" property parameter indicates a request for an
+ updated status. The recipient SHOULD respond with a "REPLY" method
+ indicating their current status with respect to the "REQUEST".
+
+3.4.3 REPLY
+
+ The "REPLY" method in a "VTODO" calendar component is used to respond
+ (e.g., accept or decline) to a request or to reply to a delegation
+ request. It is also used by an "Attendee" to update their completion
+ status. When used to provide a delegation response, the "Delegator"
+ MUST include the calendar address of the "Delegate" in the
+ "delegated-to" parameter of the "Delegator's" "ATTENDEE" property.
+ The "Delegate" MUST include the calendar address of the "Delegator"
+ on the "delegated-from" parameter of the "Delegate's" "ATTENDEE"
+ property.
+
+ The "REPLY" method MAY also be used to respond to an unsuccessful
+ "VTODO" calendar component "REQUEST" method. Depending on the
+ "REQUEST-STATUS" value, no scheduling action may have been performed.
+
+ The "Organizer" of a "VTODO" calendar component MAY receive a "REPLY"
+ method from a "Calendar User" not in the original "REQUEST". For
+ example, a "REPLY" method MAY be received from a "Delegate" of a
+ "VTODO" calendar component. In addition, the "REPLY" method MAY be
+
+
+
+Silverberg, et. al. Standards Track [Page 41]
+
+RFC 2446 iTIP November 1998
+
+
+ received from an unknown "Calendar User", having been forwarded the
+ "REQUEST" by an original "Attendee" of the "VTODO" calendar
+ component. This uninvited "Attendee" MAY be accepted, or the
+ "Organizer" MAY cancel the "VTODO" calendar component for the
+ uninvited "Attendee" by sending them a "CANCEL" method.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ---------------------------------------------
+METHOD 1 MUST be "REPLY"
+VTODO 1+ All component MUST have the same UID
+ ATTENDEE 1+
+ DTSTAMP 1
+ ORGANIZER 1
+ REQUEST-STATUS 1+
+ UID 1 MUST must be the address of the replying
+ attendee
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTSTART 0 or 1
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property may contain a list of values
+ RRULE 0+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ Recurring calendar component. Otherwise it
+ MUST NOT be present
+ SEQUENCE 0 or 1 MUST be the sequence number of
+ the original REQUEST if greater than 0.
+ MAY be present if 0.
+ STATUS 0 or 1
+
+
+
+Silverberg, et. al. Standards Track [Page 42]
+
+RFC 2446 iTIP November 1998
+
+
+ SUMMARY 0 or 1 Can be null
+ URL 0 or 1
+ X-PROPERTY 0+
+
+VTIMEZONE 0 or 1 MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VALARM 0
+VEVENT 0
+VFREEBUSY 0
+
+3.4.4 ADD
+
+ The "ADD" method in a "VTODO" calendar component is used to add one
+ or more instances to an existing to-do.
+
+ If the "UID" property value in the "ADD" is not found on the
+ recipient's calendar, then the recipient SHOULD send a "REFRESH" to
+ the "Organizer" in order to be updated with the latest version of the
+ "VTODO". If an "Attendee" implementation does not support the "ADD"
+ method it should respond with a "REQUEST-STATUS" value of 5.3 and ask
+ for a "REFRESH".
+
+ The "SEQUENCE" property value is incremented as the sequence of to-
+ dos has changed.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "ADD"
+VTODO 1
+ DTSTAMP 1
+ ORGANIZER 1
+ PRIORITY 1
+ SEQUENCE 1 MUST be greater than 0
+ SUMMARY 1 Can be null.
+ UID 1 MUST match that of the original to-do
+
+ ATTACH 0+
+ ATTENDEE 0+
+ CATEGORIES 0 or 1 This property may contain a list of
+ values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 43]
+
+RFC 2446 iTIP November 1998
+
+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DTSTART 0 or 1
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property may contain a list of
+ values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
+ PROCESS
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ RECURRENCE-ID 0
+ REQUEST-STATUS 0
+
+VALARM 0+
+VTIMEZONE 0+ MUST be present if any date/time refers
+ to a timezone
+X-COMPONENT 0+
+
+VEVENT 0
+VJOURNAL 0
+VFREEBUSY 0
+
+3.4.5 CANCEL
+
+ The "CANCEL" method in a "VTODO" calendar component is used to send a
+ cancellation notice of an existing "VTODO" calendar request to the
+ "Attendees". The message is sent by the "Organizer" of a "VTODO"
+ calendar component to the "Attendees" of the "VTODO" calendar
+ component. For a recurring "VTODO" calendar component, either the
+ whole "VTODO" calendar component or instances of a "VTODO" calendar
+ component may be cancelled. To cancel the complete range of a
+ recurring "VTODO" calendar component, the "UID" property value for
+ the "VTODO" calendar component MUST be specified and a "RECURRENCE-
+ ID" MUST NOT be specified in the "CANCEL" method. In order to cancel
+ an individual instance of a recurring "VTODO" calendar component, the
+ "RECURRENCE-ID" property value for the "VTODO" calendar component
+ MUST be specified in the "CANCEL" method.
+
+
+
+Silverberg, et. al. Standards Track [Page 44]
+
+RFC 2446 iTIP November 1998
+
+
+ There are two options for canceling a sequence of instances of a
+ recurring "VTODO" calendar component:
+
+ (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
+ be specified with the "RANGE" property parameter value of
+ THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
+ specified "VTODO" calendar component and all instances before (or
+ after); or
+
+ (b) individual recurrence instances may be cancelled by specifying
+ multiple "RECURRENCE-ID" properties corresponding to the
+ instances to be cancelled.
+
+ When a "VTODO" is cancelled, the "SEQUENCE" property value MUST be
+ incremented.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ---------------------------------------------
+METHOD 1 MUST be "CANCEL"
+VTODO 1
+ ATTENDEE 0+ include all "Attendees" being removed from
+ the todo. MUST include all "Attendees" if
+ the entire todo is cancelled.
+ UID 1 MUST echo original UID
+ DTSTAMP 1
+ ORGANIZER 1
+ SEQUENCE 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTSTART 0 or 1
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ RDATE 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 45]
+
+RFC 2446 iTIP November 1998
+
+
+ RECURRENCE-ID 0 or 1 MUST only if referring to one or more
+ instances of a recurring calendar
+ component. Otherwise it MUST NOT be
+ present.
+ RELATED-TO 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0+
+ PRIORITY 0 or 1
+ STATUS 0 or 1 If present it MUST be set to "CANCELLED".
+ MUST NOT be used if purpose is to remove
+ "ATTENDEES" rather than cancel the entire
+ VTODO.
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ REQUEST-STATUS 0
+
+VTIMEZONE 0 or 1 MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VALARM 0
+VEVENT 0
+VFREEBUSY 0
+
+3.4.6 REFRESH
+
+ The "REFRESH" method in a "VTODO" calendar component is used by
+ "Attendees" of an existing "VTODO" calendar component to request an
+ updated description from the "Organizer" of the "VTODO" calendar
+ component. The "Organizer" of the "VTODO" calendar component MAY use
+ this method to request an updated status from the "Attendees". The
+ "REFRESH" method MUST specify the "UID" property corresponding to the
+ "VTODO" calendar component needing update.
+
+ A refresh of a recurrence instance of a "VTODO" calendar component
+ may be requested by specifying the "RECURRENCE-ID" property
+ corresponding to the associated "VTODO" calendar component. The
+ "Organizer" responds with the latest description and rendition of the
+ "VTODO" calendar component. In most cases this will be a REQUEST
+ unless the "VTODO" has been cancelled, in which case the ORGANIZER
+ MUST send a "CANCEL". This method is intended to facilitate machine
+ processing of requests for updates to a "VTODO" calendar component.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 46]
+
+RFC 2446 iTIP November 1998
+
+
+Component/Property Presence
+------------------- ---------------------------------------------
+METHOD 1 MUST be "REFRESH"
+VTODO 1
+ ATTENDEE 1
+ DTSTAMP 1
+ UID 1 MUST echo original UID
+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ Recurring calendar component. Otherwise it
+ MUST NOT be present
+ X-PROPERTY 0+
+
+ ATTACH 0
+ CATEGORIES 0
+ CLASS 0
+ COMMENT 0
+ CONTACT 0
+ CREATED 0
+ DESCRIPTION 0
+ DTSTART 0
+ DUE 0
+ DURATION 0
+ EXDATE 0
+ EXRULE 0
+ GEO 0
+ LAST-MODIFIED 0
+ LOCATION 0
+ ORGANIZER 0
+ PERCENT-COMPLETE 0
+ PRIORITY 0
+ RDATE 0
+ RELATED-TO 0
+ REQUEST-STATUS 0
+ RESOURCES 0
+ RRULE 0
+ SEQUENCE 0
+ STATUS 0
+ URL 0
+
+X-COMPONENT 0+
+
+VALARM 0
+VEVENT 0
+VFREEBUSY 0
+VTIMEZONE 0
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 47]
+
+RFC 2446 iTIP November 1998
+
+
+3.4.7 COUNTER
+
+ The "COUNTER" method in a "VTODO" calendar component is used by an
+ "Attendee" of an existing "VTODO" calendar component to submit to the
+ "Organizer" a counter proposal for the "VTODO" calendar component.
+ The "Attendee" sends the message to the "Organizer" of the "VTODO"
+ calendar component.
+
+ The counter proposal is an iCalendar object consisting of a "VTODO"
+ calendar component describing the complete description of the
+ alternate "VTODO" calendar component.
+
+ The "Organizer" rejects the counter proposal by sending the
+ "Attendee" a "DECLINECOUNTER" method. The "Organizer" accepts the
+ counter proposal by sending all of the "Attendees" of the "VTODO"
+ calendar component a "REQUEST" method rescheduling the "VTODO"
+ calendar component. In the latter case, the "Organizer" SHOULD reset
+ the individual "RSVP" property parameter values to TRUE on each
+ "ATTENDEE" property; in order to force a response by the "Attendees".
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "COUNTER"
+VTODO 1
+ ATTENDEE 1+
+ DTSTAMP 1
+ ORGANIZER 1
+ PRIORITY 1
+ SUMMARY 1 Can be null
+ UID 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1 Can be null
+ DTSTART 0 or 1
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+
+
+
+Silverberg, et. al. Standards Track [Page 48]
+
+RFC 2446 iTIP November 1998
+
+
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST only 3.5if referring to an instance of a
+ recurring calendar component. Otherwise it
+ MUST NOT be present.
+ RELATED-TO 0+
+ REQUEST-STATUS 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0 or 1
+ SEQUENCE 0 or 1 MUST echo the original SEQUENCE number.
+ MUST be present if non-zero. MAY be present
+ if zero.
+ STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
+ PROCESS/CANCELLED
+ URL 0 or 1
+ X-PROPERTY 0+
+
+
+VALARM 0+
+VTIMEZONE 0 or 1 MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VEVENT 0
+VFREEBUSY 0
+
+3.4.8 DECLINECOUNTER
+
+ The "DECLINECOUNTER" method in a "VTODO" calendar component is used
+ by an "Organizer" of "VTODO" calendar component to reject a counter
+ proposal offered by one of the "Attendees". The "Organizer" sends the
+ message to the "Attendee" that sent the "COUNTER" method to the
+ "Organizer".
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ---------------------------------------------
+METHOD 1 MUST be "DECLINECOUNTER"
+
+VTODO 1
+ ATTENDEE 1+ MUST for all attendees
+ DTSTAMP 1
+ ORGANIZER 1
+ SEQUENCE 1 MUST echo the original SEQUENCE number
+ UID 1 MUST echo original UID
+
+
+
+Silverberg, et. al. Standards Track [Page 49]
+
+RFC 2446 iTIP November 1998
+
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property may contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTSTART 0 or 1
+ DUE 0 or 1 If present DURATION MUST NOT be present
+ DURATION 0 or 1 If present DUE MUST NOT be present
+ EXDATE 0+
+ EXRULE 0+
+ GEO 0 or 1
+ LAST-MODIFIED 0 or 1
+ LOCATION 0 or 1
+ PERCENT-COMPLETE 0 or 1
+ PRIORITY 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+ RELATED-TO 0+
+ REQUEST-STATUS 0+
+ RESOURCES 0 or 1 This property MAY contain a list of values
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
+ PROCESS
+ URL 0 or 1
+ X-PROPERTY 0+
+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VALARM 0
+VEVENT 0
+VFREEBUSY 0
+
+3.5 Methods For VJOURNAL Components
+
+ This section defines the property set for the methods that are
+ applicable to the "VJOURNAL" calendar component.
+
+ The following summarizes the methods that are defined for the
+ "VJOURNAL" calendar component.
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 50]
+
+RFC 2446 iTIP November 1998
+
+
+ +================+==================================================+
+ | Method | Description |
+ |================+==================================================|
+ | PUBLISH | Post a journal entry. Used primarily as a method |
+ | | of advertising the existence of a journal entry. |
+ | | |
+ | ADD | Add one or more instances to an existing journal |
+ | | entry. |
+ | | |
+ | CANCEL | Cancel one or more instances of an existing |
+ | | journal entry. |
+ +================+==================================================+
+
+3.5.1 PUBLISH
+
+ The "PUBLISH" method in a "VJOURNAL" calendar component has no
+ associated response. It is simply a posting of an iCalendar object
+ that may be added to a calendar. It MUST have an "Organizer". It MUST
+ NOT have "Attendees". The expected usage is for encapsulating an
+
+ arbitrary journal entry as an iCalendar object. The "Organizer" MAY
+ subsequently update (with another "PUBLISH" method) or cancel (with a
+ "CANCEL" method) a previously published journal entry.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "PUBLISH"
+VJOURNAL 1+
+ DESCRIPTION 1 Can be null.
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ UID 1
+
+ ATTACH 0+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ EXDATE 0+
+ EXRULE 0+
+ LAST-MODIFIED 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
+
+
+
+Silverberg, et. al. Standards Track [Page 51]
+
+RFC 2446 iTIP November 1998
+
+
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+ RELATED-TO 0+
+ RRULE 0+
+ SEQUENCE 0 or 1 MUST echo the original SEQUENCE number.
+ MUST be present if non-zero. MAY be
+ present if zero.
+ STATUS 0 or 1 MAY be one of DRAFT/FINAL/CANCELLED
+ SUMMARY 0 or 1 Can be null
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ ATTENDEE 0
+
+VALARM 0+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VEVENT 0
+VFREEBUSY 0
+VTODO 0
+
+3.5.2 ADD
+
+ The "ADD" method in a "VJOURNAL" calendar component is used to add
+ one or more instances to an existing "VJOURNAL" entry. There is no
+ response to the "Organizer".
+
+ If the "UID" property value in the "ADD" is not found on the
+ recipient's calendar, then the recipient MAY treat the "ADD" as a
+ "PUBLISH".
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ----------------------------------------------
+METHOD 1 MUST be "ADD"
+VJOURNAL 1
+ DESCRIPTION 1 Can be null.
+ DTSTAMP 1
+ DTSTART 1
+ ORGANIZER 1
+ SEQUENCE 1 MUST be greater than 0
+ UID 1 MUST match that of the original journal
+
+ ATTACH 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 52]
+
+RFC 2446 iTIP November 1998
+
+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ EXDATE 0+
+ EXRULE 0+
+ LAST-MODIFIED 0 or 1
+ RDATE 0+
+ RELATED-TO 0+
+ RRULE 0+
+ STATUS 0 or 1 MAY be one of DRAFT/FINAL/CANCELLED
+ SUMMARY 0 or 1 Can be null
+ URL 0 or 1
+ X-PROPERTY 0+
+
+ ATTENDEE 0
+ RECURRENCE-ID 0
+
+VALARM 0+
+VTIMEZONE 0 or 1 MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+
+VEVENT 0
+VFREEBUSY 0
+VTODO 0
+
+3.5.3 CANCEL
+
+ The "CANCEL" method in a "VJOURNAL" calendar component is used to
+ send a cancellation notice of an existing journal entry. The message
+ is sent by the "Organizer" of a journal entry. For a recurring
+ journal entry, either the whole journal entry or instances of a
+ journal entry may be cancelled. To cancel the complete range of a
+ recurring journal entry, the "UID" property value for the journal
+ entry MUST be specified and a "RECURRENCE-ID" property MUST NOT be
+ specified in the "CANCEL" method. In order to cancel an individual
+ instance of the journal entry, the "RECURRENCE-ID" property value for
+ the journal entry MUST be specified in the "CANCEL" method.
+
+ There are two options for canceling a sequence of instances of a
+ recurring "VJOURNAL" calendar component:
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 53]
+
+RFC 2446 iTIP November 1998
+
+
+ (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
+ be specified with the "RANGE" property parameter value of
+ THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
+ specified "VTODO" calendar component and all instances before (or
+ after); or
+
+ (b) individual recurrence instances may be cancelled by specifying
+ multiple "RECURRENCE-ID" properties corresponding to the
+ instances to be cancelled.
+
+ When a "VJOURNAL" is cancelled, the "SEQUENCE" property value MUST be
+ incremented.
+
+ This method type is an iCalendar object that conforms to the
+ following property constraints:
+
+Component/Property Presence
+------------------- ---------------------------------------------
+METHOD 1 MUST be "CANCEL"
+VJOURNAL 1+ All MUST have the same UID
+ DTSTAMP 1
+ ORGANIZER 1
+ SEQUENCE 1
+ UID 1 MUST be the UID of the original REQUEST
+
+ ATTACH 0+
+ ATTENDEE 0+
+ CATEGORIES 0 or 1 This property MAY contain a list of values
+ CLASS 0 or 1
+ COMMENT 0 or 1
+ CONTACT 0+
+ CREATED 0 or 1
+ DESCRIPTION 0 or 1
+ DTSTART 0 or 1
+ EXDATE 0+
+ EXRULE 0+
+ LAST-MODIFIED 0 or 1
+ RDATE 0+
+ RECURRENCE-ID 0 or 1 only if referring to an instance of a
+ recurring calendar component. Otherwise
+ it MUST NOT be present.
+ RELATED-TO 0+
+ RRULE 0+
+ STATUS 0 or 1 MAY be present, must be "CANCELLED" if
+ present
+ SUMMARY 0 or 1
+ URL 0 or 1
+ X-PROPERTY 0+
+
+
+
+Silverberg, et. al. Standards Track [Page 54]
+
+RFC 2446 iTIP November 1998
+
+
+ REQUEST-STATUS 0
+
+VTIMEZONE 0+ MUST be present if any date/time refers to
+ a timezone
+X-COMPONENT 0+
+VALARM 0
+VEVENT 0
+VFREEBUSY 0
+VTODO 0
+
+3.6 Status Replies
+
+ The "REQUEST-STATUS" property may include the following values:
+
+|==============+============================+=========================|
+| Short Return | Longer Return Status | Offending Data |
+| Status Code | Description | |
+|==============+============================+=========================|
+| 2.0 | Success. | None. |
+|==============+============================+=========================|
+| 2.1 | Success but fallback taken | Property name and value |
+| | on one or more property | MAY be specified. |
+| | values. | |
+|==============+============================+=========================|
+| 2.2 | Success, invalid property | Property name MAY be |
+| | ignored. | specified. |
+|==============+============================+=========================|
+| 2.3 | Success, invalid property | Property parameter name |
+| | parameter ignored. | and value MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 2.4 | Success, unknown non- | Non-standard property |
+| | standard property ignored. | name MAY be specified. |
+|==============+============================+=========================|
+| 2.5 | Success, unknown non | Property and non- |
+| | standard property value | standard value MAY be |
+| | ignored. | specified. |
+|==============+============================+=========================|
+| 2.6 | Success, invalid calendar | Calendar component |
+| | component ignored. | sentinel (e.g., BEGIN: |
+| | | ALARM) MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 2.7 | Success, request forwarded | Original and forwarded |
+| | to Calendar User. | caluser addresses MAY |
+| | | be specified. |
+|==============+============================+=========================|
+| 2.8 | Success, repeating event | RRULE or RDATE property |
+
+
+
+Silverberg, et. al. Standards Track [Page 55]
+
+RFC 2446 iTIP November 1998
+
+
+| | ignored. Scheduled as a | name and value MAY be |
+| | single component. | specified. |
+|==============+============================+=========================|
+| 2.9 | Success, truncated end date| DTEND property value |
+| | time to date boundary. | MAY be specified. |
+|==============+============================+=========================|
+| 2.10 | Success, repeating VTODO | RRULE or RDATE property |
+| | ignored. Scheduled as a | name and value MAY be |
+| | single VTODO. | specified. |
+|==============+============================+=========================|
+| 2.11 | Success, unbounded RRULE | RRULE property name and |
+| | clipped at some finite | value MAY be specified. |
+| | number of instances | Number of instances MAY |
+| | | also be specified. |
+|==============+============================+=========================|
+| 3.0 | Invalid property name. | Property name MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 3.1 | Invalid property value. | Property name and value |
+| | | MAY be specified. |
+|==============+============================+=========================|
+| 3.2 | Invalid property parameter.| Property parameter name |
+| | | and value MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 3.3 | Invalid property parameter | Property parameter name |
+| | value. | and value MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 3.4 | Invalid calendar component | Calendar component |
+| | sequence. | sentinel MAY be |
+| | | specified (e.g., BEGIN: |
+| | | VTIMEZONE). |
+|==============+============================+=========================|
+| 3.5 | Invalid date or time. | Date/time value(s) MAY |
+| | | be specified. |
+|==============+============================+=========================|
+| 3.6 | Invalid rule. | Rule value MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 3.7 | Invalid Calendar User. | Attendee property value |
+| | |MAY be specified. |
+|==============+============================+=========================|
+| 3.8 | No authority. | METHOD and Attendee |
+| | | property values MAY be |
+| | | specified. |
+|==============+============================+=========================|
+
+
+
+
+Silverberg, et. al. Standards Track [Page 56]
+
+RFC 2446 iTIP November 1998
+
+
+| 3.9 | Unsupported version. | VERSION property name |
+| | | and value MAY be |
+| | | specified. |
+|==============+============================+=========================|
+| 3.10 | Request entity too large. | None. |
+|==============+============================+=========================|
+| 3.11 | Required component or | Component or property |
+| | property missing. | name MAY be specified. |
+|==============+============================+=========================|
+| 3.12 | Unknown component or | Component or property |
+| | property found | name MAY be specified |
+|==============+============================+=========================|
+| 3.13 | Unsupported component or | Component or property |
+| | property found | name MAY be specified |
+|==============+============================+=========================|
+| 3.14 | Unsupported capability | Method or action MAY |
+| | | be specified |
+|==============+============================+=========================|
+| 4.0 | Event conflict. Date/time | DTSTART and DTEND |
+| | is busy. | property name and values|
+| | | MAY be specified. |
+|==============+============================+=========================|
+| 5.0 | Request MAY supported. | Method property value |
+| | | MAY be specified. |
+|==============+============================+=========================|
+| 5.1 | Service unavailable. | ATTENDEE property value |
+| | | MAY be specified. |
+|==============+============================+=========================|
+| 5.2 | Invalid calendar service. | ATTENDEE property value |
+| | | MAY be specified. |
+|==============+============================+=========================|
+| 5.3 | No scheduling support for | ATTENDEE property value |
+| | user. | MAY be specified. |
+|==============+============================+=========================|
+
+3.7 Implementation Considerations
+
+3.7.1 Working With Recurrence Instances
+
+ iCalendar includes a recurrence grammar to represent recurring
+ events. The benefit of such a grammar is the ability to represent a
+ number of events in a single object. However, while this simplifies
+ creation of a recurring event, meeting instances still need to be
+ referenced. For instance, an "Attendee" may decline the third
+ instance of a recurring Friday event. Similarly, the "Organizer" may
+ change the time or location to a single instance of the recurring
+ event.
+
+
+
+
+Silverberg, et. al. Standards Track [Page 57]
+
+RFC 2446 iTIP November 1998
+
+
+ Since implementations may elect to store recurring events as either a
+ single event object or a collection of discreet, related event
+ objects, the protocol is designed so that each recurring instance may
+ be both referenced and versioned. Hence, implementations that choose
+ to maintain per-instance properties (such as "ATTENDEE" property
+ "partstat" parameter) may do so. However, the protocol does not
+ require per-instance recognition unless the instance itself must be
+ renegotiated.
+
+ The scenarios for recurrence instance referencing are listed below.
+ For purposes of simplification a change to an event refers to a
+ "trigger property." That is, a property that has a substantive
+ effect on the meeting itself such as start time, location, due date
+ (for "VTODO" calendar component components) and possibly description.
+
+ "Organizer" initiated actions:
+
+ . "Organizer" deletes or changes a single instance of a recurring
+ event
+ . "Organizer" makes changes that affect all future instances
+ . "Organizer" makes changes that affect all previous instances
+ . "Organizer" deletes or modifies a previously changed instance
+
+ "Attendee" initiated actions:
+
+ . "Attendee" changes status for a particular recurrence instance
+ . "Attendee" sends Event-Counter for a particular recurrence
+ instance
+
+ An instance of a recurring event is assigned a unique identification,
+ "RECURRENCE-ID" property, when that instance is renegotiated.
+ Negotiation may be necessary when a substantive change to the event
+ or to-do has be made (such as changing the start time, end time, due
+ date or location). The "Organizer" can identify a specific recurrence
+ instance using the "RECURRENCE-ID" property. The property value is
+ equal to the date/time of the instance. If the "Organizer" wishes to
+ change the "DTSTART", the original "DTSTART" value is used for
+ "RECURRENCE-ID" property and the new "DTSTART" and "DTEND" values
+ reflect the change. Note that after the change has occurred, the
+ "RECURRENCE-ID" has changed to the new "DTSTART" value.
+
+3.7.2 Attendee Property Considerations
+
+ The "ORGANIZER" property is required on published events, to-dos, and
+ journal entries for two reasons. First, only the "Organizer" is
+ allowed to update and redistribute an event or to-do component. It
+ follows that the "ORGANIZER" property MUST be present in the event,
+ to-do, or journal entry component so that the CUA has a basis for
+
+
+
+Silverberg, et. al. Standards Track [Page 58]
+
+RFC 2446 iTIP November 1998
+
+
+ authorizing an update. Second, it is prudent to provide a point of
+ contact for anyone who receives a published component in case of
+ problems.
+
+ There are valid [RFC-822] addresses that represent groups. Sending
+ email to such an address results in mail being sent to multiple
+ recipients. Such an address may be used as the value of an
+ "ATTENDEE" property. Thus, it is possible that the recipient of a
+ "REQUEST" does not appear explicitly in the list.
+
+ It is recommended that the general approach to finding a "Calendar
+ User" in an attendee list be as follows:
+
+ 1. Search for the "Calendar User" in the attendee list where
+ "TYPE=INDIVIDUAL"
+
+ 2. Failing (1) look for attendees where "TYPE=GROUP" or
+ 'TYPE=UNKNOWN". The CUA then determines if the "Calendar User"
+ is a member of one of these groups. If so, the "REPLY" method
+ sent to the "Organizer" MUST contain a new "ATTENDEE" property in
+ which:
+ . the "type" property parameter is set to INDIVIDUAL
+ . the "member" property parameter is set to the name of the
+ group
+
+ 3. Failing (2) the CUA MAY ignore or accept the request as the
+ "Calendar User" wishes.
+
+3.7.3 X-Tokens
+
+ To make iCalendar objects extensible, new property types MAY be
+ inserted into components. These properties are called X-Tokens as
+ they are prefixed with "X-". A client is not required to make sense
+ of X-Tokens. Clients are not required to save X-Tokens or use them
+ in replies.
+
+4 Examples
+
+4.1 Published Event Examples
+
+ In the calendaring and scheduling context, publication refers to the
+ one way transfer of event information. Consumers of published events
+ simply incorporate the event into a calendar. No reply is expected.
+ Individual "A" publishes an event. Individual "B" reads the event and
+ incorporates it into their calendar. Events are published in several
+ ways including: embedding the event as an object in a web page, e-
+ mailing the event to a distribution list, and posting the event to a
+ newsgroup.
+
+
+
+Silverberg, et. al. Standards Track [Page 59]
+
+RFC 2446 iTIP November 1998
+
+
+ The table below illustrates the sequence of events between the
+ publisher and the consumers of a published event.
+
+ +-------------------------------------------------------------------+
+ | Action | "Organizer" |
+ +---------------------------------+---------------------------------+
+ | Publish an event | "A" sends or posts a PUBLISH |
+ | | message |
+ +---------------------------------+---------------------------------+
+ | "B" reads a published event | |
+ +---------------------------------+---------------------------------+
+ | Publish an updated event | "A" sends or posts a PUBLISH |
+ | | message |
+ +---------------------------------+---------------------------------+
+ | "B" reads the updated event | |
+ +---------------------------------+---------------------------------+
+ | Cancel a published event | "A" sends or posts a CANCEL |
+ | | message |
+ +---------------------------------+---------------------------------+
+ | "B" reads the canceled event | |
+ | publication | |
+ +---------------------------------+---------------------------------+
+
+4.1.1 A Minimal Published Event
+
+ The iCalendar object below describes a single event that begins on
+ July 1, 1997 at 20:00 UTC. This event contains the minimum set of
+ properties for a "PUBLISH" for a "VEVENT" calendar component.
+
+ BEGIN:VCALENDAR
+ METHOD:PUBLISH
+ PRODID:-//ACME/DesktopCalendar//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:a at example.com
+ DTSTART:19970701T200000Z
+ DTSTAMP:19970611T190000Z
+ SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
+ UID:0981234-1234234-23 at example.com
+ END:VEVENT
+ END:VCALENDAR
+
+4.1.2 Changing A Published Event
+
+ The iCalendar object below describes an update to the event described
+ in 4.1.1, the time has been changed, an end time has been added, and
+ the sequence number has been adjusted.
+
+
+
+
+Silverberg, et. al. Standards Track [Page 60]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VCALENDAR
+ METHOD:PUBLISH
+ VERSION:2.0
+ PRODID:-//ACME/DesktopCalendar//EN
+ BEGIN:VEVENT
+ ORGANIZER:mailto:a at example.com
+ DTSTAMP:19970612T190000Z
+ DTSTART:19970701T210000Z
+ DTEND:19970701T230000Z
+ SEQUENCE:1
+ UID:0981234-1234234-23 at example.com
+ SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
+ END:VEVENT
+ END:VCALENDAR
+
+ The "UID" property is used by the client to identify the event. The
+ "SEQUENCE" property indicates that this is a change to the event. The
+ event with a matching UID and sequence number 0 is superseded by this
+ event.
+
+ The "SEQUENCE" property provides a reliable way to distinguish
+ different versions of the same event. Each time an event is
+ published, its sequence number is incremented. If a client receives
+ an event with a sequence number 5 and finds it has the same event
+ with sequence number 2, the event SHOULD be updated. However, if the
+ client received an event with sequence number 2 and finds it already
+ has sequence number 5 of the same event, the event MUST NOT be
+ updated.
+
+4.1.3 Canceling A Published Event
+
+ The iCalendar object below cancels the event described in 4.1.1. This
+ cancels the event with "SEQUENCE" property of 0, 1, and 2.
+
+ BEGIN:VCALENDAR
+ METHOD:CANCEL
+ VERSION:2.0
+ PRODID:-//ACME/DesktopCalendar//EN
+ BEGIN:VEVENT
+ ORGANIZER:mailto:a at example.com
+ COMMENT:DUKES forfeit the game
+ SEQUENCE:2
+ UID:0981234-1234234-23 at example.com
+ DTSTAMP:19970613T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 61]
+
+RFC 2446 iTIP November 1998
+
+
+4.1.4 A Rich Published Event
+
+ This example describes the same event as in 4.1.1, but in much
+ greater detail.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:PUBLISH
+ SCALE:GREGORIAN
+ VERSION:2.0
+ BEGIN:VTIMEZONE
+ TZID:America-Chicago
+ TZURL:http://zones.stds_r_us.net/tz/America-Chicago
+ BEGIN:STANDARD
+ DTSTART:19671029T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZOFFSETFROM:-0500
+ TZOFFSETTO:-0600
+ TZNAME:CST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19870405T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
+ TZOFFSETFROM:-0600
+ TZOFFSETTO:-0500
+ TZNAME:CDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+ BEGIN:VEVENT
+ ORGANIZER:mailto:a at example.com
+ ATTACH:http://www.dukes.com/
+ CATEGORIES:SPORTS EVENT,ENTERTAINMENT
+ CLASS:PRIVATE
+ DESCRIPTION:MIDWAY STADIUM\n
+ Big time game. MUST see.\n
+ Expected duration:2 hours\n
+ DTEND;TZID=America-Chicago:19970701T180000
+ DTSTART;TZID=America-Chicago:19970702T160000
+ DTSTAMP:19970614T190000Z
+ STATUS:CONFIRMED
+ LOCATION;VALUE=URI:http://www.midwaystadium.com/
+ PRIORITY:2
+ RESOURCES:SCOREBOARD
+ SEQUENCE:3
+ SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
+ UID:0981234-1234234-23 at example.com
+ RELATED-TO:0981234-1234234-14 at example.com
+ BEGIN:VALARM
+
+
+
+Silverberg, et. al. Standards Track [Page 62]
+
+RFC 2446 iTIP November 1998
+
+
+ TRIGGER:-PT2H
+ ACTION:DISPLAY
+ DESCRIPTION:You should be leaving for the game now.
+ END:VALARM
+ BEGIN:VALARM
+ TRIGGER:-PT30M
+ ACTION:AUDIO
+ END:VALARM
+ END:VEVENT
+ END:VCALENDAR
+
+ The "RELATED-TO" field contains the "UID" property of a related
+ calendar event. The "SEQUENCE" property 3 indicates that this event
+ supersedes versions 0, 1, and 2.
+
+4.1.5 Anniversaries or Events attached to entire days
+
+ This example demonstrates the use of the "value" parameter to tie a
+ "VEVENT" to day rather than a specific time.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:PUBLISH
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:a at example.com
+ DTSTAMP:19970614T190000Z
+ UID:0981234-1234234-23 at example.com
+ DTSTART;VALUE=DATE:19970714
+ RRULE:FREQ=YEARLY;INTERVAL=1
+ SUMMARY: Bastille Day
+ END:VEVENT
+ END:VCALENDAR
+
+4.2 Group Event Examples
+
+ Group events are distinguished from published events in that they
+ have "Attendees" and that there is interaction between the
+ "Attendees" and the "Organizer" with respect to the event. Individual
+ "A" requests a meeting between individuals "A", "B", "C" and "D".
+ Individual "B" confirms attendance to the meeting. Individual "C"
+ declines attendance. Individual "D" tentatively confirms attendance.
+ The following table illustrates the the message flow between these
+ individuals. A, the CU scheduling the meeting, is referenced as the
+ "Organizer".
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 63]
+
+RFC 2446 iTIP November 1998
+
+
++---------------------------------------------------------------------+
+| Action | "Organizer" | Attendee |
++---------------------------------------------------------------------+
+| Initiate a meeting | "A" sends a REQUEST | |
+| request | message to "B", "C",| |
+| | and "D" | |
++---------------------------------------------------------------------+
+| Accept the meeting | | "B" sends a REPLY |
+| request | | message to "A" with its |
+| | | ATTENDEE "partstat" para-|
+| | | set to "accepted" |
++---------------------------------------------------------------------+
+| Decline the meeting| | "C" sends a REPLY |
+| request | | message to "A" with its |
+| | | ATTENDEE "partstat" para-|
+| | | set to "declined" |
++---------------------------------------------------------------------+
+| Tentatively accept | | "D" sends a REPLY |
+| the meeting request| | message to "A" with its |
+| | | ATTENDEE "partstat" para-|
+| | | set to "tentative" |
++---------------------------------------------------------------------+
+| Confirm meeting | "A" sends a REQUEST | |
+| status with | message to "B" and | |
+| attendees | "D" with updated | |
+| | information. | |
++---------------------------------------------------------------------+
+
+4.2.1 A Group Event Request
+
+ A sample meeting request is sent from "A" to "B", "C", and "D". _E_
+ is also sent a copy of the request but is not expected to attend and
+ need not reply. "E" illustrates how CUAs might implement an "FYI"
+ type feature. Note the use of the "role" parameter. The default value
+ for the "role" parameter is "req-participant" and it need not be
+ enumerated. In this case we are using the value "non-participant" to
+ indicate "E" is a non-attending CU. The parameter is not needed on
+ other "Attendees" since "participant" is the default value.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C at example.com
+
+
+
+Silverberg, et. al. Standards Track [Page 64]
+
+RFC 2446 iTIP November 1998
+
+
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D at example.com
+ ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big at example.com
+ ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T200000Z
+ DTEND:19970701T2000000Z
+ SUMMARY:Conference
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.2 Reply To A Group Event Request
+
+ Attendee "B" accepts the meeting.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VEVENT
+ ATTENDEE;PARTSTAT=ACCEPTED:Mailto:B at example.com
+ ORGANIZER:MAILTO:A at example.com
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ REQUEST-STATUS:2.0;Success
+ DTSTAMP:19970612T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+ "B" could have declined the meeting or indicated tentative acceptance
+ by setting the "ATTENDEE" "partstat" parameter to "declined" or
+ "tentative", respectively. Also, "REQUEST-STATUS" is not required in
+ successful transactions.
+
+4.2.3 Update An Event
+
+ The event is moved to a different time. The combination of the "UID"
+ property (unchanged) and the "SEQUENCE" (bumped to 1) properties
+ indicate the update.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+
+
+
+Silverberg, et. al. Standards Track [Page 65]
+
+RFC 2446 iTIP November 1998
+
+
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D at example.com
+ ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE;
+ CUTYPE=ROOM:Mailto:Conf at example.com
+ ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E at example.com
+ DTSTART:19970701T180000Z
+ DTEND:19970701T190000Z
+ SUMMARY:Phone Conference
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:1
+ DTSTAMP:19970613T190000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.4 Countering an Event Proposal
+
+ "A" sends a "REQUEST" to "B" and "C". "B" makes a counter-proposal to
+ "A" to change the time and location.
+
+ "A" sends the following "REQUEST":
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ DTSTART:19970701T190000Z
+ DTEND:19970701T200000Z
+ SUMMARY:Discuss the Merits of the election results
+ LOCATION:Green Conference Room
+ UID:calsrv.example.com-873970198738777a at example.com
+ SEQUENCE:0
+ DTSTAMP:19970611T190000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ "B" sends "COUNTER" to "A", requesting changes to time and place. "B"
+ uses the "COMMENT" property to communicate a rationale for the
+ change. Note that the "SEQUENCE" property is NOT incremented on a
+ "COUNTER".
+
+
+
+Silverberg, et. al. Standards Track [Page 66]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:COUNTER
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ DTSTART:19970701T160000Z
+ DTEND:19970701T190000Z
+ DTSTAMP:19970612T190000Z
+ SUMMARY:Discuss the Merits of the election results
+ LOCATION:Green Conference Room
+ COMMENT:This time works much better and I think the big conference
+ room is too big
+ UID:calsrv.example.com-873970198738777a at example.com
+ SEQUENCE:0
+ DTSTAMP:19970611T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+ "A" accepts the changes from "B". To accept a counter-proposal, the
+ "Organizer" sends a new event "REQUEST" with an incremented sequence
+ number.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ DTSTAMP:19970613T190000Z
+ DTSTART:19970701T160000Z
+ DTEND:19970701T190000Z
+ SUMMARY:Discuss the Merits of the election results - changed to
+ meet B's schedule
+ LOCATION:Green Conference Room
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:1
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ Instead, "A" rejects "B's" counter proposal
+
+
+
+Silverberg, et. al. Standards Track [Page 67]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:DECLINECOUNTER
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ COMMENT:Sorry, I cannot change this meeting time
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ DTSTAMP:19970614T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.5 Delegating an Event
+
+ When delegating an event request to another "Calendar User", the
+ "Delegator" must both update the "Organizer" with a "REPLY" and send
+ a request to the "Delegate". There is currently no protocol
+ limitation to delegation depth. It is possible for the original
+
+ delegate to delegate the meeting to someone else, and so on. When a
+ request is delegated from one CUA to another there are a number of
+ responsibilities required of the "Delegator". The "Delegator" MUST:
+
+ . Send a "REPLY" to the "Organizer" with the following updates:
+ . The "Delegator's" "ATTENDEE" property "partstat" parameter set
+ to "delegated" and the "delegated-to" parameter is set to the
+ address of the "Delegate"
+ . Add an additional "ATTENDEE" property for the "Delegate" with
+ the "delegated-from" property parameter set to the "Delegator"
+ . Indicate whether they want to continue to receive updates when
+ the "Organizer" sends out updated versions of the event.
+ Setting the "rsvp" property parameter to "TRUE" will cause the
+ updates to be sent, setting it to "FALSE" causes no further
+ updates to be sent. Note that in either case, if the "Delegate"
+ declines the invitation the "Delegator" will be notified.
+ . The "Delegator" MUST also send a copy of the original "REQUEST"
+ method to the "Delegate".
+
+ It is not required that the "Delegate" include the "Delegator" in
+ their "REPLY" method. However, it is strongly advised since this will
+ inform the "Delegator" whether the "Delegate" plans to attend the
+ meeting. [Editors note: How so?] If the "Delegate" declines the
+ meeting, the "Delegator" may elect to delegate the "REQUEST" to
+ another CUA. The process is the same.
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 68]
+
+RFC 2446 iTIP November 1998
+
+
++---------------------------------------------------------------------+
+| Action | "Organizer" | Attendee |
++---------------------------------------------------------------------+
+| Initiate a meeting | "A" sends a REQUEST | |
+| request | message to "B" and | |
+| | "C" | |
++---------------------------------------------------------------------+
+| Delegate: | | "C" sends a REPLY to "A" |
+| "C" delegates to | | with the ATTENDEE. |
+| "E" | | "partstat" parameter set |
+| | | to "delegated" and with a|
+| | | new "ATTENDEE" property |
+| | | for "E". "E's" ATTENDEE |
+| | | "delegated-from" param |
+| | | is set to "C". "C's" |
+| | | ATTENDEE "delegated-to" |
+| | | param is set to "E". |
+| | | "C" sends REQUEST message|
+| | | to "E" with the original |
+| | | meeting request |
+| | | information. The |
+| | | "partstat" property |
+| | | parameter for "C" is set |
+| | | to "delegated" and the |
+| | | "delegated-to" |
+| | | parameter is set to |
+| | | the address of "E". An |
+| | | "ATTENDEE" property is |
+| | | added for "E" and the |
+| | | "delegated-from" |
+| | | parameter is set to |
+| | | the address of "C". |
++---------------------------------------------------------------------+
+| Confirm meeting | | "E" sends REPLY message |
+| attendance | | to "A" and optionally "C"|
+| | | with its "partstat" |
+| | | property parameter set |
+| | | to "ACCEPTED" |
++---------------------------------------------------------------------+
+| Optional: | "A" sends REQUEST | |
+| Redistribute | message to "B", "C" | |
+| meeting to | and "E". | |
+| attendees | | |
++---------------------------------------------------------------------+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 69]
+
+RFC 2446 iTIP November 1998
+
+
+ "C" responds to the "Organizer".
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:A at Example.com
+ ATTENDEE;PARTSTAT=DELEGATED;DELEGATED-
+ TO="Mailto:E at example.com":Mailto:C at example.com
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ REQUEST-STATUS:2.0;Success
+ DTSTAMP:19970611T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+ Attendee "C" delegates presence at the meeting to "E".
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;PARTSTAT=DELEGATED;DELEGATED-
+ TO="Mailto:E at example.com":Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE;
+ DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
+ DTSTART:19970701T180000Z
+ DTEND:19970701T200000Z
+ SUMMARY:Phone Conference
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ DTSTAMP:19970611T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.6 Delegate Accepts the Meeting
+
+ To accept a delegated meeting, the delegate, "E", sends the following
+ message to "A" and "C":
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+
+
+
+Silverberg, et. al. Standards Track [Page 70]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:A at Example.com
+ ATTENDEE;PARTSTAT=ACCEPTED;DELEGATED-
+ FROM="Mailto:C at example.com":Mailto:E at example.com
+ ATTENDEE;PARTSTAT=DELEGATED;
+ DELEGATED-TO="Mailto:E at example.com":Mailto:C at example.com
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ REQUEST-STATUS:2.0;Success
+ DTSTAMP:19970614T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.7 Delegate Declines the Meeting
+
+ In this example the "Delegate" declines the meeting request and sets
+ the "ATTENDEE" property "partstat" parameter to "DECLINED". The
+ "Organizer" SHOULD resend the "REQUEST" to "C" with the "partstat"
+ parameter of the "Delegate" set to "declined". This lets the
+ "Delegator" know that the "Delegate" has declined and provides an
+ opportunity to the "Delegator" to either accept the request or
+ delegate it to another CU.
+
+ Response from "E" to "A" and "C". Note the use of the "COMMENT"
+ property "E" uses to indicate why the delegation was declined.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:A at Example.com
+ ATTENDEE;PARTSTAT=DELEGATED;
+ DELEGATED-TO="Mailto:E at example.com":Mailto:C at example.com
+ ATTENDEE;PARTSTAT=DECLINED;
+ DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
+ COMMENT:Sorry, I will be out of town at that time.
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ REQUEST-STATUS:2.0;Success
+ DTSTAMP:19970614T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+ "A" resends the "REQUEST" method to "C". "A" may also wish to express
+ the fact that the item was delegated in the "COMMENT" property.
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 71]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:A at Example.com
+ ATTENDEE;PARTSTAT=DECLINED;
+ DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ SUMMARY:Phone Conference
+ DTSTART:19970701T180000Z
+ DTEND:19970701T200000Z
+ DTSTAMP:19970614T200000Z
+ COMMENT:DELEGATE (ATTENDEE Mailto:E at example.com) DECLINED YOUR
+ INVITATION
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.8 Forwarding an Event Request
+
+ The protocol does not prevent an "Attendee" from "forwarding" an
+ "VEVENT" calendar component to other "Calendar Users". Forwarding
+ differs from delegation in that the forwarded "Calendar User" (often
+ referred to as a "Party Crasher") does not replace the forwarding
+ "Calendar User". Implementations are not required to add the "Party
+ Crasher" to the "Attendee" list and hence there is no guarantee that
+ a "Party Crasher" will receive additional updates to the Event. The
+ forwarding "Calendar User" SHOULD NOT add the "Party Crasher" to the
+ attendee list. The "Organizer" MAY add the forwarded "Calendar User"
+ to the attendee list.
+
+4.2.9 Cancel A Group Event
+
+ Individual "A" requests a meeting between individuals "A", "B", "C",
+ and "D". Individual "B" declines attendance to the meeting.
+ Individual "A" decides to cancel the meeting. The following table
+ illustrates the sequence of messages that would be exchanged between
+ these individuals.
+
+ Messages related to a previously canceled event ("SEQUENCE" property
+ value is less than the "SEQUENCE" property value of the "CANCEL"
+ message) MUST be ignored.
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 72]
+
+RFC 2446 iTIP November 1998
+
+
+ +--------------------------------------------------------------------+
+ | Action | "Organizer" | "Attendee" |
+ +--------------------------------------------------------------------+
+ | Initiate a meeting | "A" sends a REQUEST | |
+ | request | message to "B", "C",| |
+ | | and "D" | |
+ +--------------------------------------------------------------------+
+ | Decline the meeting| | "B" sends a "REPLY" |
+ | request | | message to "A" with its |
+ | | | "partstat" para- |
+ | | | set to "declined". |
+ +--------------------------------------------------------------------+
+ | Cancel the meeting | "A" sends a CANCEL | |
+ | | message to "B", "C" | |
+ | | and "D" | |
+ +--------------------------------------------------------------------+
+
+ The example shows how "A" cancels the event.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:CANCEL
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;TYPE=INDIVIDUAL;Mailto:A at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
+ COMMENT:Mr. B cannot attend. It's raining. Lets cancel.
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:1
+ STATUS:CANCELLED
+ DTSTAMP:19970613T190000Z
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 73]
+
+RFC 2446 iTIP November 1998
+
+
+4.2.10 Removing Attendees
+
+ "A" wants to remove "B" from a meeting. This is done by sending a
+ "CANCEL" to "B" and removing "B" from the attendee list in the master
+ copy of the event.
+
+ +--------------------------------------------------------------------+
+ | Action | "Organizer" | "Attendee" |
+ +--------------------------------------------------------------------+
+ | Remove an "B" | "A" sends a CANCEL | |
+ | as an "Attendee" | message to "B" | |
+ +--------------------------------------------------------------------+
+ | Update the master | "A" sends the | |
+ | copy of the event | updated event to | |
+ | | the remaining | |
+ | | "Attendees" | |
+ +--------------------------------------------------------------------+
+
+ The original meeting includes "A", "B", "C", and "D". The example
+ below shows the "CANCEL" that "A" sends to "B". Note that in the
+ example below the "STATUS" property is omitted. This is used when the
+ meeting itself is cancelled and not when the intent is to remove an
+ "Attendee" from the Event.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:CANCEL
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE:mailto:B at example.com
+ COMMENT:You're off the hook for this meeting
+ UID:calsrv.example.com-873970198738777 at example.com
+ DTSTAMP:19970613T193000Z
+ SEQUENCE:1
+ END:VEVENT
+ END:VCALENDAR
+
+ The updated master copy of the event is shown below. The "Organizer"
+ MAY resend the updated event to the remaining "Attendees". Note that
+ "B" has been removed.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+
+
+
+Silverberg, et. al. Standards Track [Page 74]
+
+RFC 2446 iTIP November 1998
+
+
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
+ ATTENDEE;TYPE=ROOM:CR_Big at example.com
+ ATTENDEE;ROLE=NON-PARTICIPANT;
+ RSVP=FALSE:Mailto:E at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T200000Z
+ DTEND:19970701T203000Z
+ SUMMARY:Phone Conference
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:2
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.2.11 Replacing the Organizer
+
+ The scenario for this example begins with "A" as the "Organizer" for
+ a recurring meeting with "B", "C", and "D". "A" receives a new job
+ offer in another country and drops out of touch. "A" left no
+ forwarding address or way to be reached. Using out-of-band
+ communication, the other "Attendees" eventually learn what has
+ happened and reach an agreement that "B" should become the new
+ "Organizer" for the meeting. To do this, "B" sends out a new version
+ of the event and the other "Attendees" agree to accept "B" as the new
+ "Organizer". "B" also removes "A" from the event.
+
+ When the "Organizer" is replaced, the "SEQUENCE" property value MUST
+ be incremented.
+
+ This is the message "B" sends to "C" and "D"
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:B at example.com
+ ATTENDEE;ROLE=CHAIR;STATUS=ACCEPTED:Mailto:B at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
+ ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T200000Z
+ DTEND:19970701T203000Z
+ RRULE:FREQ=WEEKLY
+ SUMMARY:Phone Conference
+ UID:123456 at example.com
+
+
+
+Silverberg, et. al. Standards Track [Page 75]
+
+RFC 2446 iTIP November 1998
+
+
+ SEQUENCE:1
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.3 Busy Time Examples
+
+ Busy time objects can be used in several ways. First, a CU may
+ request busy time from another CU for a specific range of time. That
+ request can be answered with a busy time Reply. Additionally, a CU
+ may simply publish their busy time for a given interval and point
+ other CUs to the published location. The following examples outline
+ both scenarios.
+
+ Individual "A" publishes busy time for one week.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ VERSION:2.0
+ METHOD:PUBLISH
+ BEGIN:VFREEBUSY
+ DTSTAMP:19980101T124100Z
+ ORGANIZER:MAILTO:A at Example.com
+ DTSTART:19980101T124200Z
+ DTEND:19980107T124200Z
+ FREEBUSY:19980101T180000Z/19980101T190000Z
+ FREEBUSY:19980103T020000Z/19980103T050000Z
+ FREEBUSY:19980107T020000Z/19980107T050000Z
+ FREEBUSY:19980113T000000Z/19980113T010000Z
+ FREEBUSY:19980115T190000Z/19980115T200000Z
+ FREEBUSY:19980115T220000Z/19980115T230000Z
+ FREEBUSY:19980116T013000Z/19980116T043000Z
+ END:VFREEBUSY
+ END:VCALENDAR
+
+ Individual "A" requests busy time from individuals "B", "C".
+ Individual "B" and "C" replies with busy time data to individual "A".
+ The following table illustrates the sequence of messages that would
+ be exchanged between these individuals.
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 76]
+
+RFC 2446 iTIP November 1998
+
+
++--------------------------------------------------------------------+
+| Action | "Organizer" | Attendee |
++--------------------------------------------------------------------+
+| Initiate a busy | "A" sends "REQUEST" | |
+| time request | message to "B" and | |
+| | and "C" | |
++--------------------------------------------------------------------+
+| Reply to the "BUSY"| | "B" sends a "REPLY" |
+| request with "BUSY"| | message to "A" with |
+| time data | | busy time data |
++--------------------------------------------------------------------+
+
+4.3.1 Request Busy Time
+
+ "A" sends a "BUSY-REQUEST" to "B" and "C" for busy time
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VFREEBUSY
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+ DTSTAMP:19970613T190000Z
+ DTSTART:19970701T080000Z
+ DTEND:19970701T200000
+ UID:calsrv.example.com-873970198738777 at example.com
+ END:VFREEBUSY
+ END:VCALENDAR
+
+4.3.2 Reply To A Busy Time Request
+
+ "B" sends a "REPLY" method type of a "VFREEBUSY" calendar component
+ to "A"
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VFREEBUSY
+ ORGANIZER:MAILTO:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ DTSTART:19970701T080000Z
+ DTEND:19970701T200000Z
+ UID:calsrv.example.com-873970198738777 at example.com
+ FREEBUSY:19970701T090000Z/PT1H,19970701T140000Z/PT30M
+
+
+
+Silverberg, et. al. Standards Track [Page 77]
+
+RFC 2446 iTIP November 1998
+
+
+ DTSTAMP:19970613T190030Z
+ END:VFREEBUSY
+ END:VCALENDAR
+
+ "B" is busy from 09:00 to 10:00 and from 14:00 to 14:30.
+
+4.4 Recurring Event and Time Zone Examples
+
+4.4.1 A Recurring Event Spanning Time Zones
+
+ This event describes a weekly phone conference. The "Attendees" are
+ each in a different time zone.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTIMEZONE
+ TZID:America-SanJose
+ TZURL:http://zones.stds_r_us.net/tz/America-SanJose
+ BEGIN:STANDARD
+ DTSTART:19671029T020000
+ RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
+ TZOFFSETFROM:-0700
+ TZOFFSETTO:-0800
+ TZNAME:PST
+ END:STANDARD
+ BEGIN:DAYLIGHT
+ DTSTART:19870405T020000
+ RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
+ TZOFFSETFROM:-0800
+ TZOFFSETTO:-0700
+ TZNAME:PDT
+ END:DAYLIGHT
+ END:VTIMEZONE
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;TYPE=INDIVIDUAL:A at example.COM
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:B at example.fr
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:c at example.jp
+ DTSTAMP:19970613T190030Z
+ DTSTART;TZID=America-SanJose:19970701T140000
+ DTEND;TZID=America-SanJose:19970701T150000
+ RRULE:FREQ=WEEKLY;INTERVAL=20;WKST=SU;BYDAY=TU
+ RDATE;TZID=America-SanJose:19970910T140000
+ EXDATE;TZID=America-SanJose:19970909T140000
+ EXDATE;TZID=America-SanJose:19971028T140000
+ SUMMARY:Weekly Phone Conference
+
+
+
+Silverberg, et. al. Standards Track [Page 78]
+
+RFC 2446 iTIP November 1998
+
+
+ UID:calsrv.example.com-873970198738777 at example.com
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ The first two components of this iCalendar object are the time zone
+ components. The "DTSTART" date coincides with the first instance of
+ the RRULE property.
+
+ The recurring meeting is defined in a particular time zone,
+ presumably that of the originator. The client for each "Attendee" has
+ the responsibility of determining the recurrence time in the
+ "Attendee's" time zone.
+
+ The repeating event starts on Tuesday, July 1, 1997 at 2:00pm PDT.
+ "Attendee" B at example.fr is in France where the local time on this
+ date is 9 hours ahead of PDT or 23:00. "Attendee" C at example.jp is in
+ Japan where local time is 8 hours ahead of UTC or Wednesday, July 2
+ at 06:00. The event repeats weekly on Tuesdays (in PST/PDT). The
+ "RRULE" property results in 20 instances. The last instance falls on
+ Tuesday, November 11, 1997 2:00pm PDT. The "RDATE" property adds
+ another instance: WED, 10-SEP-1997 2:00 PM PST.
+
+ There are two exceptions to this recurring appointment. The first one
+ is:
+
+ TUE, 09-SEP-1997 23:00 GMT
+ TUE, 09-SEP-1997 14:00 PDT
+ WED, 10-SEP-1997 06:00 JST
+
+ and the second is:
+
+ TUE, 28-OCT-1997 23:00 GMT
+ TUE, 28-OCT-1997 14:00 PST
+ WED, 29-OCT-1997 06:00 JST
+
+4.4.2 Modify A Recurring Instance
+
+ In this example the "Organizer" issues a recurring meeting. Later the
+ "Organizer" changes an instance of the event by changing the
+ "DTSTART" property. Note the use of "RECURRENCE-ID" property and
+ "SEQUENCE" property in the second request.
+
+ Original Request:
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+
+
+
+Silverberg, et. al. Standards Track [Page 79]
+
+RFC 2446 iTIP November 1998
+
+
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ SEQUENCE:0
+ RRULE:FREQ=MONTHLY;BYMONTHDAY=1;UNTIL=19980901T210000Z
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+ ATTENDEE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ CLASS:PUBLIC
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970601T210000Z
+ DTEND:19970601T220000Z
+ LOCATION:Conference Call
+ DTSTAMP:19970526T083000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ The event request below is to change the time of a specific instance.
+ This changes the July 1st instance to July 3rd.
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1com
+ RECURRENCE-ID:19970701T210000Z
+ SEQUENCE:1
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+ ATTENDEE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ CLASS:PUBLIC
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970703T210000Z
+ DTEND:19970703T220000Z
+ LOCATION:Conference Call
+ DTSTAMP:19970626T093000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+Silverberg, et. al. Standards Track [Page 80]
+
+RFC 2446 iTIP November 1998
+
+
+4.4.3 Cancel an Instance
+
+ In this example the "Organizer" of a recurring event deletes the
+ August 1st instance.
+
+ BEGIN:VCALENDAR
+ METHOD:CANCEL
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+ ATTENDEE:Mailto:D at example.com
+ RECURRENCE-ID:19970801T210000Z
+ SEQUENCE:2
+ STATUS:CANCELLED
+ DTSTAMP:19970721T093000Z
+ END:VEVENT
+ END:VCALENDAR
+
+4.4.4 Cancel Recurring Event
+
+ In this example the "Organizer" wishes to cancel the entire recurring
+ event and any exceptions.
+
+ BEGIN:VCALENDAR
+ METHOD:CANCEL
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+ ATTENDEE:Mailto:D at example.com
+ DTSTAMP:19970721T103000Z
+ STATUS:CANCELLED
+ SEQUENCE:3
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 81]
+
+RFC 2446 iTIP November 1998
+
+
+4.4.5 Change All Future Instances
+
+ This example changes the meeting location from a conference call to
+ Seattle starting September 1 and extends to all future instances.
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ RECURRENCE-ID;THISANDFUTURE:19970901T210000Z
+ SEQUENCE:3
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Discussion
+ CLASS:PUBLIC
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970901T210000Z
+ DTEND:19970901T220000Z
+ LOCATION:Building 32, Microsoft, Seattle, WA
+ DTSTAMP:19970526T083000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.4.6 Add A New Instance To A Recurring Event
+
+ This example adds a one-time additional instance to the recurring
+ event. "Organizer" adds a second July meeting on the 15th.
+
+ BEGIN:VCALENDAR
+ METHOD:ADD
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:4
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ CLASS:PUBLIC
+
+
+
+Silverberg, et. al. Standards Track [Page 82]
+
+RFC 2446 iTIP November 1998
+
+
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970715T210000Z
+ DTEND:19970715T220000Z
+ LOCATION:Conference Call
+ DTSTAMP:19970629T093000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.4.7 Add A New Series of Instances To A Recurring Event
+
+ The scenario for this example involves an ongoing meeting, originally
+ set up to occur every Tuesday. The "Organizer" later decides that
+ the meetings need to be on Tuesdays and Thursdays, but does not want
+ to reschedule the entire meeting or lose any of the per-instance
+ information already collected.
+
+ The original event:
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:0
+ RRULE:WKST=SU;BYDAY=TU;FREQ=WEEKLY
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980303T210000Z
+ DTEND:19980303T220000Z
+ LOCATION:The White Room
+ DTSTAMP:19980301T093000Z
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ Assume that many other updates happen to this event and that a lot of
+ instance-specific information exists in the recurring series. The
+ "SEQUENCE" property value is 7 for the next update. Now the
+ "Organizer" wants to add Thursdays to the event:
+
+ BEGIN:VCALENDAR
+ METHOD:ADD
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+
+
+
+Silverberg, et. al. Standards Track [Page 83]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:7
+ RRULE:WKST=SU;BYDAY=TH;FREQ=WEEKLY
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980303T210000Z
+ DTEND:19980303T220000Z
+ DTSTAMP:19980303T193000Z
+ LOCATION:The Usual conference room
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ Alternatively, if the "Organizer" is not concerned with per-instance
+ updates, the entire event can be rescheduled using a "REQUEST". This
+ is done by using the "UID" of the event to reschedule and including
+ the modified "RRULE". Note, that since this is an entire rescheduling
+ of the event, any instance-specific information will be lost.
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:7
+ RRULE:WKST=SU;BYDAY=TU,TH;FREQ=WEEKLY
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980303T210000Z
+ DTEND:19980303T220000Z
+ DTSTAMP:19980303T193000Z
+ LOCATION:The White Room
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ The next series of examples illustrate how an "Organizer" would
+ respond to a "REFRESH" submitted by an "Attendee" after a series of
+ instance-specific modifications. To convey all instance-specific
+ changes, the "Organizer" must provide the latest event description
+ and the relevant instances. The first three examples show the history
+ including the initial "VEVENT" request and subsequent instance
+
+
+
+Silverberg, et. al. Standards Track [Page 84]
+
+RFC 2446 iTIP November 1998
+
+
+ changes and finally the "REFRESH".
+
+ Original Request:
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:0
+ RDATE:19980304T180000Z
+ RDATE:19980311T180000Z
+ RDATE:19980318T180000Z
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980304T180000Z
+ DTEND:19980304T200000Z
+ DTSTAMP:19980303T193000Z
+ LOCATION:Conference Room A
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ Organizer changes 2nd instance Location and Time:
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:1
+ RECURRENCE-ID:19980311T180000Z
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980311T160000Z
+ DTEND:19980311T180000Z
+ DTSTAMP:19980306T193000Z
+ LOCATION:The Small conference room
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+Silverberg, et. al. Standards Track [Page 85]
+
+RFC 2446 iTIP November 1998
+
+
+ Organizer adds a 4th instance of the meeting using the "ADD" method
+
+ BEGIN:VCALENDAR
+ METHOD:ADD
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:2
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980315T180000Z
+ DTEND:19980315T200000Z
+ DTSTAMP:19980307T193000Z
+ LOCATION:Conference Room A
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ If "B" requests a "REFRESH", "A" responds with the following to
+ capture all instance-specific data. In this case both the initial
+ request and an additional "VEVENT" that specifies the instance-
+ specific data are included. Because these are both of the same type
+ (they are both "VEVENTS"), they can be conveyed in the same iCalendar
+ object.
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:123456789 at host1.com
+ SEQUENCE:2
+ RDATE:19980304T180000Z
+ RDATE:19980311T160000Z
+ RDATE:19980315T180000Z
+ Error! Bookmark not defined.
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ SUMMARY:Review Accounts
+ DTSTART:19980304T180000Z
+ DTEND:19980304T200000Z
+ DTSTAMP:19980303T193000Z
+ LOCATION:Conference Room A
+ STATUS:CONFIRMED
+
+
+
+Silverberg, et. al. Standards Track [Page 86]
+
+RFC 2446 iTIP November 1998
+
+
+ END:VEVENT
+
+ BEGIN:VEVENT
+ Error! Bookmark not defined.
+ SEQUENCE:2
+ RECURRENCE-ID:19980311T160000Z
+ Error! Bookmark not defined.
+ ATTENDEE;ROLE=CHAIR;Error! Bookmark not defined.
+ ATTENDEE;Error! Bookmark not defined.
+ SUMMARY:Review Accounts
+ DTSTART:19980311T160000Z
+ DTEND:19980304T180000Z
+ DTSTAMP:19980306T193000Z
+ LOCATION:The Small conference room
+ STATUS:CONFIRMED
+ END:VEVENT
+
+ END:VCALENDAR
+
+4.4.8 Counter An Instance Of A Recurring Event
+
+ In this example one of the "Attendees" counters the "DTSTART"
+ property of the proposed second July meeting.
+
+ BEGIN:VCALENDAR
+ METHOD:COUNTER
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ RECURRENCE-ID:19970715T210000Z
+ SEQUENCE:4
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;RSVP=TRUE:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ CLASS:PUBLIC
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970715T220000Z
+ DTEND:19970715T230000Z
+ LOCATION:Conference Call
+ COMMENT:May we bump this by an hour? I have a conflict
+ DTSTAMP:19970629T094000Z
+ END:VEVENT
+ END:VCALENDAR
+
+
+
+
+Silverberg, et. al. Standards Track [Page 87]
+
+RFC 2446 iTIP November 1998
+
+
+4.4.9 Error Reply To A Request
+
+ The following example illustrates a scenario where a meeting is
+ proposed containing an unsupported property and a bad property.
+
+ Original Request
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:guid-1 at host1.com
+ SEQUENCE:0
+ RRULE:FREQ=MONTHLY;BYMONTHDAY=1
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:D at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ CLASS:PUBLIC
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970601T210000Z
+ DTEND:19970601T220000Z
+ DTSTAMP:19970602T094000Z
+ LOCATION:Conference Call
+ STATUS:CONFIRMED
+ FOO:BAR
+ END:VEVENT
+ END:VCALENDAR
+
+ Response from "B" to indicate that RRULE is not supported and an
+ unrecognized property was encountered
+
+ BEGIN:VCALENDAR
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ REQUEST-STATUS:2.8;Repeating event ignored. Scheduled as a single
+ event;RRULE
+ REQUEST-STATUS:3.0;Invalid Property Name;FOO
+ UID:guid-1 at host1.com
+ SEQUENCE:0
+ DTSTAMP:19970603T094000Z
+
+
+
+Silverberg, et. al. Standards Track [Page 88]
+
+RFC 2446 iTIP November 1998
+
+
+ END:VEVENT
+ END:VCALENDAR
+
+4.5 Group To-do Examples
+
+ Individual "A" creates a group task in which individuals "A", "B",
+ "C" and "D" will participate. Individual "B" confirms acceptance of
+ the task. Individual "C" declines the task. Individual "D"
+ tentatively accepts the task. The following table illustrates the
+ sequence of messages that would be exchanged between these
+ individuals. Individual "A" then issues a "REQUEST" method to obtain
+ the status of the to-do from each participant. The response indicates
+ the individual "Attendee's" completion status. The table below
+ illustrates the message flow.
+
++--------------------------------------------------------------------+
+| Action | "Organizer" | Attendee |
++--------------------------------------------------------------------+
+| Initiate a to-do | "A" sends a REQUEST | |
+| request | message to "B", "C",| |
+| | and "D" | |
++--------------------------------------------------------------------+
+| Accept the to-do | | "B" sends a "REPLY" |
+| request | | message to "A" with its |
+| | | "partstat" paramater |
+| | | set to "accepted". |
++--------------------------------------------------------------------+
+| Decline the to-do | | "C" sends a REPLY |
+| request | | message to "A" with its |
+| | | "partstat" parameter |
+| | | set to "declined". |
++--------------------------------------------------------------------+
+| Tentatively accept | | "D" sends a REPLY |
+| the to-do request | | message to "A" with its |
+| | | "partstat" parameter |
+| | | set to "tentative". |
++--------------------------------------------------------------------+
+| Check attendee | "A" sends a REQUEST | |
+| completion status | message to "B" and | |
+| | "D" with current | |
+| | information. | |
++--------------------------------------------------------------------+
+| Attendee indicates | | "B" sends a "REPLY" |
+| percent complete | | message indicating |
+| | | percent complete |
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 89]
+
+RFC 2446 iTIP November 1998
+
+
++--------------------------------------------------------------------+
+| Attendee indicates | | "D" sends a "REPLY" |
+| completion | | message indicating |
+| | | completion |
++--------------------------------------------------------------------+
+
+4.5.1 A VTODO Request
+
+ A sample "REQUEST" for a "VTODO" calendar component that "A" sends to
+ "B", "C", and "D".
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:C at example.com
+ ATTENDEE;RSVP=TRUE:Mailto:D at example.com
+ DTSTART:19970701T170000Z
+ DUE:19970722T170000Z
+ PRIORITY:1
+ SUMMARY:Create the requirements document
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ SEQUENCE:0
+ DTSTAMP:19970717T200000Z
+ STATUS:Needs Action
+ END:VTODO
+ END:VCALENDAR
+
+4.5.2 A VTODO Reply
+
+ "B" accepts the to-do.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;PARTSTAT=ACCEPTED:Mailto:B at example.com
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ COMMENT:I'll send you my input by e-mail
+ SEQUENCE:0
+ DTSTAMP:19970717T203000Z
+ REQUEST-STATUS:2.0;Success
+
+
+
+Silverberg, et. al. Standards Track [Page 90]
+
+RFC 2446 iTIP November 1998
+
+
+ END:VTODO
+ END:VCALENDAR
+
+ "B" could have declined the TODO or indicated tentative acceptance by
+ setting the "partstat" property parameter sequence to "declined" or
+ "tentative", respectively.
+
+4.5.3 A VTODO Request for Updated Status
+
+ "A" requests status from all "Attendees".
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:D at example.com
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ SUMMARY:Create the requirements document
+ PRIORITY:1
+ SEQUENCE:0
+ STATUS:IN-PROCESS
+ DTSTART:19970701T170000Z
+ DTSTAMP:19970717T230000Z
+ END:VTODO
+ END:VCALENDAR
+
+4.5.4 A Reply: Percent-Complete
+
+ A reply indicating the task being worked on and that "B" is 75%
+ complete with "B's" part of the assignment.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:MAILTO:A at example.com
+ ATTENDEE;PARTSTAT=IN-PROCESS:Mailto:B at example.com
+ PERCENT-COMPLETE:75
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ DTSTAMP:19970717T233000Z
+ SEQUENCE:0
+ END:VTODO
+ END:VCALENDAR
+
+
+
+Silverberg, et. al. Standards Track [Page 91]
+
+RFC 2446 iTIP November 1998
+
+
+4.5.5 A Reply: Completed
+
+ A reply indicating that "D" completed "D's" part of the assignment.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:MAILTO:A at example.com
+ ATTENDEE;PARTSTAT=COMPLETED:Mailto:D at example.com
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ DTSTAMP:19970717T233000Z
+ SEQUENCE:0
+ END:VTODO
+ END:VCALENDAR
+
+4.5.6 An Updated VTODO Request
+
+ Organizer "A" resends the "VTODO" calendar component. "A" sets the
+ overall completion for the to-do at 40%.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE;PARTSTAT=ACCEPTED;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;PARTSTAT=IN-PROCESS;TYPE=INDIVIDUAL:Mailto:D at example.com
+ DTSTART:19970701T170000Z
+ DUE:19970722T170000Z
+ PRIORITY:1
+ SUMMARY:Create the requirements document
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ SEQUENCE:1
+ DTSTAMP:19970718T100000Z
+ STATUS:IN-PROGRESS
+ PERCENT-COMPLETE:40
+ END:VTODO
+ END:VCALENDAR
+
+4.5.7 Recurring VTODOs
+
+ The following examples relate to recurring "VTODO" calendar
+ components.
+
+
+
+
+Silverberg, et. al. Standards Track [Page 92]
+
+RFC 2446 iTIP November 1998
+
+
+4.5.7.1 Request for a Recurring VTODO
+
+ In this example "A" sends a recurring "VTODO" calendar component to
+ "B" and "D".
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTODO
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
+ ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:D at example.com
+ RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
+ DTSTART:19980101T100000-0700
+ DUE:19980103T100000-0700
+ SUMMARY:Send Status Reports to Area Managers
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ SEQUENCE:0
+ DTSTAMP:19970717T200000Z
+ STATUS:NEEDS ACTION
+ PRIORITY:1
+ END:VTODO
+ END:VCALENDAR
+
+4.5.7.2 Calculating due dates in recurring VTODOs
+
+ The due date in a recurring "VTODO" calendar component is either a
+ fixed interval specified in the "REQUEST" method or specified using
+ the "RECURRENCE-ID" property. The former is calculated by applying
+ the difference between "DTSTART" and "DUE" properties and applying it
+ to each of the start of each recurring instance. Hence, if the
+ initial "VTODO" calendar component specifies a "DTSTART" property
+ value of "19970701T190000Z" and a "DUE" property value of
+ "19970801T190000Z" the interval of one day which is applied to each
+ recurring instance of the "VTODO" calendar component to determine the
+ "DUE" date of the instance.
+
+4.5.7.3 Replying to an instance of a recurring VTODO
+
+ In this example "B" updates "A" on a single instance of the "VTODO"
+ calendar component.
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REPLY
+ VERSION:2.0
+
+
+
+Silverberg, et. al. Standards Track [Page 93]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VTODO
+ ATTENDEE;PARTSTAT=IN-PROCESS:Mailto:B at example.com
+ PERCENT-COMPLETE:75
+ UID:calsrv.example.com-873970198738777-00 at example.com
+ DTSTAMP:19970717T233000Z
+ RECURRENCE-ID:19980101T170000Z
+ SEQUENCE:1
+ END:VTODO
+ END:VCALENDAR
+
+4.6 Journal Examples
+
+ The iCalendar object below describes a single journal entry for
+ October 2, 1997. The "RELATED-TO" property references the phone
+ conference event for which minutes were taken.
+
+ BEGIN:VCALENDAR
+ METHOD:PUBLISH
+ PRODID:-//ACME/DesktopCalendar//EN
+ VERSION:2.0
+ BEGIN:VJOURNAL
+ DTSTART:19971002T200000Z
+ ORGANIZER:MAILTO:A at Example.com
+ SUMMARY:Phone conference minutes
+ DESCRIPTION:The editors meeting was held on October 1, 1997.
+ Details are in the attached document.
+ UID:0981234-1234234-2410 at example.com
+ RELATED-TO:0981234-1234234-2402-35 at example.com
+ ATTACH:ftp://ftp.example.com/pub/ed/minutes100197.txt
+ END:VJOURNAL
+ END:VCALENDAR
+
+4.7 Other Examples
+
+4.7.1 Event Refresh
+
+ Refresh the event with "UID" property value of "guid-1-
+ 12345 at host1.com":
+
+ BEGIN:VCALENDAR
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ METHOD:REFRESH
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ ATTENDEE:Mailto:C at example.com
+
+
+
+Silverberg, et. al. Standards Track [Page 94]
+
+RFC 2446 iTIP November 1998
+
+
+ ATTENDEE:Mailto:D at example.com
+ UID: guid-1-12345 at host1.com
+ DTSTAMP:19970603T094000
+ END:VEVENT
+ END:VCALENDAR
+
+4.7.2 Bad RECURRENCE-ID
+
+ Component instances are identified by the combination of "UID",
+ "RECURRENCE-ID", and "SEQUENCE". When an "Organizer" sends a request
+ to an "Attendee", there are three cases in which an instance cannot
+ be found. They are:
+
+ 1. The component with the referenced "UID" and "RECURRENCE-ID" has
+ been found but the "SEQUENCE" number in the calendar store does
+ not match that of the ITIP message.
+
+ 2. The component with the referenced "UID" has been found, the
+ "SEQUENCE" numbers match, but the "RECURRENCE-ID" cannot be
+ found.
+
+ 3. The "UID" and "SEQUENCE" numbers are found but the CUA does not
+ support recurrences.
+
+ In case (1), two things can happen. If the "SEQUENCE" number of the
+ "Attendee's" instance is larger than that in the "Organizer's"
+ message then the "Attendee" is receiving an out-of-sequence message
+ and MUST ignore it. If the "SEQUENCE" number of the "Attendee's"
+ instance is smaller, then the "Organizer" is sending out a newer
+ version of the component and the "Attendee's" version needs to be
+ updated. Since one or more updates have been missed, the "Attendee"
+ SHOULD send a "REFRESH" message to the "Organizer" to get an updated
+ version of the event.
+
+ In case (2), something has gone wrong. Both the "Organizer" and the
+ "Attendee" should have the same instances, but the "Attendee" does
+ not have the referenced instance. In this case the "Attendee" SHOULD
+ send a "REFRESH" to the "Organizer" to get an updated version of the
+ event.
+
+ In case (3), the limitations of the "Attendee's" CUA makes it
+ impossible to match an instance other than the single instance
+ scheduled. In this case, the "Attendee" need not send a "REFRESH" to
+ the "Organizer".
+
+ The example below shows a sequence in which an "Attendee" sends a
+ "REFRESH" to the "Organizer".
+
+
+
+
+Silverberg, et. al. Standards Track [Page 95]
+
+RFC 2446 iTIP November 1998
+
+
++--------------------------------------------------------------------+
+| Action | "Organizer" | Attendee |
++--------------------------------------------------------------------+
+| Update an instance | "A" sends "REQUEST"| |
+| request | message to "B" | |
++--------------------------------------------------------------------+
+| Attendee requests | | "B" sends a "REFRESH" |
+| refresh because | | message to "A" |
+| "RECURRENCE-ID" was| | |
+| not found | | |
++--------------------------------------------------------------------+
+| Refresh the entire | "A" sends the | |
+| Event | latest copy of the | |
+| | Event to "B" | |
++--------------------------------------------------------------------+
+| Attendee handles | | "B" updates to the |
+| the request and | | latest copy of the |
+| updates the | | meeting. |
+| instance | | |
++--------------------------------------------------------------------+
+
+ Request from "A":
+
+ BEGIN:VCALENDAR
+ METHOD:REQUEST
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ VERSION:2.0
+ BEGIN:VEVENT
+ UID:acme-12345 at host1.com
+ SEQUENCE:3
+ RRULE:FREQ=WEEKLY
+ RDATE;VALUE=PERIOD:19970819T210000Z/199700819T220000Z
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ DESCRIPTION:IETF-C&S Conference Call
+ SUMMARY:IETF Calendaring Working Group Meeting
+ DTSTART:19970801T210000Z
+ DTEND:19970801T220000Z
+ RECURRENCE-ID:19970809T210000Z
+ DTSTAMP:19970726T083000
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ "B" has the event with "UID" property "acme-12345 at host1.com" but
+ "B's" "SEQUENCE" property value is "1" and the event does not have an
+ instance at the specified recurrence time. This means that "B" has
+
+
+
+Silverberg, et. al. Standards Track [Page 96]
+
+RFC 2446 iTIP November 1998
+
+
+ missed at least one update and needs a new copy of the event. "B"
+ requests the latest copy of the event with the following refresh
+ message:
+
+ BEGIN:VCALENDAR
+ PRODID:-//RDU Software//NONSGML HandCal//EN
+ METHOD:REFRESH
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:Mailto:A at example.com
+ ATTENDEE:Mailto:B at example.com
+ UID:acme-12345 at host1.com
+ DTSTAMP:19970603T094000
+ END:VEVENT
+ END:VCALENDAR
+
+5 Application Protocol Fallbacks
+
+5.1 Partial Implementation
+
+ Applications that support this memo are not required to support the
+ entire protocol. The following describes how methods and properties
+ SHOULD "fallback" in applications that do not support the complete
+ protocol. If a method or property is not addressed in this section,
+ it may be ignored.
+
+5.1.1 Event-Related Fallbacks
+
+Method Fallback
+-------------- -----------------------------------------------------
+PUBLISH Required
+REQUEST PUBLISH
+REPLY Required
+ADD Required
+CANCEL Required
+REFRESH Required
+COUNTER Reply with Not Supported
+DECLINECOUNTER Required if EVENT-COUNTER is implemented; otherwise
+ reply with Not Supported
+
+iCalendar
+Property Fallback
+-------------- -----------------------------------------------------
+CALSCALE Ignore; assume GREGORIAN
+PRODID Ignore
+METHOD Required as described in the Method list above
+VERSION Ignore
+
+
+
+
+Silverberg, et. al. Standards Track [Page 97]
+
+RFC 2446 iTIP November 1998
+
+
+Event-Related
+Components Fallback
+-------------- -----------------------------------------------------
+VALARM Reply with Not Supported
+VTIMEZONE Required if any DateTime value refers to a time zone.
+
+Component
+Property Fallback
+-------------- -----------------------------------------------------
+ATTACH Ignore
+ATTENDEE Required if EVENT-REQUEST is not implemented;
+ otherwise reply with Not Supported
+CATEGORIES Ignore
+CLASS Ignore
+COMMENT Ignore
+COMPLETED Ignore
+nCONTACT Ignore
+CREATED Ignore
+DESCRIPTION Required
+DURATION Reply with Not Supported
+DTSTAMP Required
+DTSTART Required
+DTEND Required
+EXDATE Ignore
+EXRULE Ignore Reply with Not Supported. If implemented,
+ VTIMEZONE MUST also be implemented.
+GEO Ignore
+LAST-MODIFIED Ignore
+LOCATION Required
+ORGANIZER Ignore
+PRIORITY Ignore
+RELATED-TO Ignore
+RDATE Ignore
+RRULE Ignore. The first instance occurs on the DTStart
+ property. If implemented, VTIMEZONE MUST also be
+ implemented.
+RECURRENCE-ID Required if RRULE is implemented; otherwise Ignore
+REQUEST-STATUS Required
+RESOURCES Ignore
+SEQUENCE Required
+STATUS Ignore
+SUMMARY Ignore
+TRANSP Required if FREEBUSY is implemented; otherwise Ignore
+URL Ignore
+UID Required
+X- Ignore
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 98]
+
+RFC 2446 iTIP November 1998
+
+
+5.1.2 Free/Busy-Related Fallbacks
+
+Method Fallback
+-------------- -----------------------------------------------------
+PUBLISH Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+REQUEST Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+REPLY Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+
+
+iCalendar
+Property Fallback
+-------------- -----------------------------------------------------
+CALSCALE Ignore; assume GREGORIAN.
+PRODID Ignore
+METHOD Required as described in the Method list above.
+VERSION Ignore
+
+
+Component
+Property Fallback
+-------------- -----------------------------------------------------
+COMMENT Ignore
+CONTACT Ignore
+DTEND Required
+DTSTAMP Required
+DTSTART Required
+DURATION Required
+FREEBUSY Required
+ORGANIZER Ignore
+REQUEST-STATUS Ignore
+UID Required
+URL Ignore
+X- Ignore
+
+5.1.3 To-Do-Related Fallbacks
+
+Method Fallback
+-------------- -----------------------------------------------------
+PUBLISH Required
+REQUEST PUBLISH
+REPLY Required
+ADD Required
+
+
+
+Silverberg, et. al. Standards Track [Page 99]
+
+RFC 2446 iTIP November 1998
+
+
+CANCEL Required
+REFRESH Required
+COUNTER Reply with Not Supported
+DECLINECOUNTER Required if VTODO - COUNTER is implemented; otherwise
+ reply with Not Supported
+
+iCalendar
+Property Fallback
+-------------- -----------------------------------------------------
+CALSCALE Ignore; assume GREGORIAN.
+PRODID Ignore
+METHOD Required as described in the Method list above.
+VERSION Ignore
+
+
+To-Do-Related
+Components Fallback
+-------------- -----------------------------------------------------
+VALARM Reply with Not Supported
+VTIMEZONE Required if any DateTime value refers to a time zone.
+
+
+Component
+Property Fallback
+-------------- -----------------------------------------------------
+ATTACH Ignore
+ATTENDEE Required if REQUEST is not implemented; otherwise
+ ignore
+CATEGORIES Ignore
+CLASS Ignore
+COMMENT Ignore
+COMPLETED Required
+CONTACT Ignore
+CREATED Ignore
+DESCRIPTION Required
+DUE Required
+DURATION Ignore Reply with Not Supported
+DTSTAMP Required
+DTSTART Required
+EXDATE Ignore Reply with Not Supported
+EXRULE Ignore Reply with Not Supported. If implemented,
+ VTIMEZONE MUST also be implemented.
+LAST-MODIFIED Ignore
+LOCATION Ignore
+ORGANIZER Ignore
+PERCENT-COMPLETE Ignore
+PRIORITY Required
+RECURRENCE-ID Ignore
+
+
+
+Silverberg, et. al. Standards Track [Page 100]
+
+RFC 2446 iTIP November 1998
+
+
+RELATED-TO Ignore
+REQUEST-STATUS Ignore
+RDATE Ignore
+RRULE Ignore. The first instance occurs on the DTSTART
+ property. If implemented, VTIMEZONE MUST also be
+ implemented.
+RESOURCES Ignore
+SEQUENCE Required
+STATUS Required
+SUMMARY Ignore
+URL Ignore
+UID Required
+X- Ignore
+
+5.1.4 Journal-Related Fallbacks
+
+
+Method Fallback
+-------------- -----------------------------------------------------
+PUBLISH Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+ADD Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+CANCEL Implementations MAY ignore the METHOD type. The
+ REQUEST-STATUS "3.14;Unsupported capability" MUST be
+ returned.
+
+
+iCalendar
+Property Fallback
+-------------- -----------------------------------------------------
+CALSCALE Ignore; assume GREGORIAN.
+PRODID Ignore
+METHOD Required as described in the Method list above.
+VERSION Ignore
+
+
+Journal-Related
+Components Fallback
+-------------- -----------------------------------------------------
+VTIMEZONE Required if any DateTime value refers to a time zone.
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 101]
+
+RFC 2446 iTIP November 1998
+
+
+Component
+Property Fallback
+-------------- -----------------------------------------------------
+ATTACH Ignore
+ATTENDEE Required if JOURNAL-REQUEST is implemented; otherwise
+ ignore
+CATEGORIES Ignore
+CLASS Ignore
+COMMENT Ignore
+CONTACT Ignore
+CREATED Ignore
+DESCRIPTION Required
+DTSTAMP Required
+DTSTART Required
+EXDATE Ignore
+EXRULE Ignore Reply with Not Supported. If implemented,
+ VTIMEZONE MUST also be implemented.
+LAST-MODIFIED Ignore
+ORGANIZER Ignore
+RECURRENCE-ID Ignore
+RELATED-TO Ignore
+RDATE Ignore.
+RRULE Ignore. The first instance occurs on the DTSTART
+ property. If implemented, VTIMEZONE MUST also be
+ implemented.
+SEQUENCE Required
+STATUS Ignore
+SUMMARY Required
+URL Ignore
+UID Required
+X- Ignore
+
+5.2 Latency Issues
+
+ With a store-and-forward transport, it is possible for events to
+ arrive out of sequence. That is, a "CANCEL" method may be received
+ prior to receiving the associated "REQUEST" for the calendar
+ component. This section discusses a few of these scenarios.
+
+5.2.1 Cancellation of an Unknown Calendar Component.
+
+ When a "CANCEL" method is received before the original "REQUEST"
+ method the calendar will be unable to correlate the "UID" property of
+ the cancellation with an existing calendar component. It is suggested
+ that messages that can not be correlated that also contain non-zero
+ sequence numbers be held and not discarded. Implementations MAY age
+ them out if no other messages arrive with the same "UID" property
+ value and a lower sequence number.
+
+
+
+Silverberg, et. al. Standards Track [Page 102]
+
+RFC 2446 iTIP November 1998
+
+
+5.2.2 Unexpected Reply from an Unknown Delegate
+
+ When an "Attendee" delegates an item to another CU they MUST send a
+ "REPLY" method to the "Organizer" using the "ATTENDEE" properties to
+ indicate that the request was delegated and to whom. Hence, it is
+ possible for an "Organizer" to receive an "REPLY" from a CU not
+ listed as one of the original "Attendees". The resolution is left to
+ the implementation but it is expected that the calendaring software
+ will either accept the reply or hold it until the related "REPLY"
+ method is received from the "Delegator". If the version of the
+ "REPLY" method is out of date the "Organizer" SHOULD treat the
+ message as a "REFRESH" message and update the delegate with the
+ correct version.
+
+5.3 Sequence Number
+
+ Under some conditions, a CUA may receive requests and replies with
+ the same "SEQUENCE" property value. The "DTSTAMP" property is
+ utilized as a tie-breaker when two items with the same "SEQUENCE"
+ property value are evaluated.
+
+6 Security Considerations
+
+ ITIP is an abstract transport protocol which will be bound to a
+ real-time transport, a store-and-forward transport, and perhaps other
+ transports. The transport protocol will be responsible for providing
+ facilities for authentication and encryption using standard Internet
+ mechanisms that are mutually understood between the sender and
+ receiver.
+
+6.1 Security Threats
+
+6.1.1 Spoofing the "Organizer"
+
+ In iTIP, the "Organizer" (or someone working on the "Organizer's"
+ behalf) is the only person authorized to make changes to an existing
+ "VEVENT", "VTODO", "VJOURNAL" calendar component and republish it or
+ redistribute updates to the "Attendees". An iCalendar object that
+ maliciously changes or cancels an existing "VEVENT", "VTODO" or
+ "VJOURNAL" calendar component may be constructed by someone other
+ than the "Organizer" and republished or sent to the "Attendees".
+
+6.1.2 Spoofing the "Attendee"
+
+ In iTIP, an "Attendee" of a "VEVENT" or "VTODO" calendar component
+ (or someone working on the "Attendee's" behalf) is the only person
+ authorized to update any parameter associated with their "ATTENDEE"
+ property and send it to the "Organizer". An iCalendar object that
+
+
+
+Silverberg, et. al. Standards Track [Page 103]
+
+RFC 2446 iTIP November 1998
+
+
+ maliciously changes the "ATTENDEE" parameters may be constructed by
+ someone other than the real "Attendee" and sent to the "Organizer".
+
+6.1.3 Unauthorized Replacement of the Organizer
+
+ There will be circumstances when "Attendees" of an event or to-do
+ decide, using out-of-band mechanisms, that the "Organizer" must be
+ replaced. When the new "Organizer" sends out the updated "VEVENT" or
+ "VTODO" the "Attendee's" CUA will detect that the "Organizer" has
+ been changed, but it has no way of knowing whether or not the change
+ was mutually agreed upon.
+
+6.1.4 Eavesdropping
+
+ The iCalendar object is constructed with human-readable clear text.
+ Any information contained in an iCalendar object may be read and/or
+ changed by unauthorized persons while the object is in transit.
+
+6.1.5 Flooding a Calendar
+
+ Implementations MAY provide a means to automatically incorporate
+ "REQUEST" methods into a calendar. This presents the opportunity for
+ a calendar to be flooded with requests, which effectively block all
+ the calendar's free time.
+
+6.1.6 Procedural Alarms
+
+ The "REQUEST" methods for "VEVENT" and "VTODO" calendar components
+ MAY contain "VALARM" calendar components. The "VALARM" calendar
+ component may be of type "PROCEDURE" and MAY have an attachment
+ containing an executable program. Implementations that incorporate
+ these types of alarms are subject to any virus or malicious attack
+ that may occur as a result of executing the attachment.
+
+6.1.7 Unauthorized REFRESH Requests
+
+ It is possible for an "Organizer" to receive a "REFRESH" request from
+ someone who is not an "Attendee" of an event or to-do. Only
+ "Attendee's" of an event or to-do are authorized to receive replies
+ to "REFRESH" requests. Replying to such requests to anyone who is not
+ an "Attendee" may be a security problem.
+
+6.2 Recommendations
+
+ For an application where the information is sensitive or critical and
+ the network is subject is subject to a high probability of attack,
+ iTIP transactions SHOULD be encrypted. This may be accomplished using
+ public key technology, specifically Security Multiparts for MIME
+
+
+
+Silverberg, et. al. Standards Track [Page 104]
+
+RFC 2446 iTIP November 1998
+
+
+ [RFC-1847] in the iTIP transport binding. This helps mitigate the
+ threats of spoofing, eavesdropping and malicious changes in transit.
+
+6.2.1 Use of [RFC-1847] to secure iTIP transactions
+
+ iTIP transport bindings MUST provide a mechanism based on Security
+ Multiparts for MIME [RFC-1847] to enable authentication of the
+ sender's identity, and privacy and integrity of the data being
+ transmitted. This allows the receiver of a signed iCalendar object to
+ verify the identity of the sender. This sender may then be correlated
+ to an "ATTENDEE" property in the iCalendar object. If the correlation
+ is made and the sender is authorized to make the requested change or
+ update then the operation may proceed. It also allows the message to
+ be encrypted to prevent unauthorized reading of the message contents
+ in transit. iTIP transport binding documents describe this process in
+ detail.
+
+ Implementations MAY provide controls for users to disable this
+ capability.
+
+6.2.2 Implementation Controls
+
+ The threat of unauthorized replacement of the "Organizer" SHOULD be
+ mitigated by a calendar system that uses this protocol by providing
+ controls or alerts that make "Calendar Users" aware of such
+ "Organizer" changes and allowing them to decide whether or not the
+ request should be honored.
+
+ The threat of flooding a calendar SHOULD be mitigated by a calendar
+ system that uses this protocol by providing controls that may be used
+ to limit the acceptable sources for iTIP transactions, and perhaps
+ the size of messages and volume of traffic, by source.
+
+ The threat of malicious procedural alarms SHOULD be mitigated by a
+ calendar system that uses this protocol by providing controls that
+ may be used to disallow procedural alarms in iTIP transactions and/or
+ remove all alarms from the object before delivery to the recipient.
+
+ The threat of unauthorized "REFRESH" requests SHOULD be mitigated by
+ a calendar system that uses this protocol by providing controls or
+ alerts that allow "Calendar User" to decide whether or not the
+ request should be honored. An implementation MAY decide to maintain,
+ for audit or historical purposes, "Calendar Users" who were part of
+ an attendee list and who were subsequently uninvited. Similar
+ controls or alerts should be provided when a "REFRESH" request is
+ received from these "Calendar Users" as well.
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 105]
+
+RFC 2446 iTIP November 1998
+
+
+7 Acknowledgments
+
+ A hearty thanks to the following individuals who have participated in
+ the drafting, review and discussion of this memo:
+
+ Anik Ganguly, Dan Hickman, Paul Hill, Daryl Huff, Bruce Kahn, Antoine
+ Leca, Bob Mahoney, John Noerenberg, Leo Parker, John Rose, Doug
+ Royer, Vinod Seraphin, Richard Shusterman, Derik Stenerson, John Sun,
+ Alexander Taler, Kevin Tsurutome.
+
+8 Bibliography
+
+ [iCAL] Dawson, F. and D. Stenerson, "Internet Calendaring and
+ Scheduling Core Object Specification - iCalendar", RFC
+ 2445, November 1998.
+
+ [iMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
+ Message-Based Interoperability Protocol - iMIP", RFC 2447,
+ November 1998.
+
+ [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [US-ASCII] Coded Character Set--7-bit American Standard Code for
+ Information Interchange, ANSI X3.4-1986.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 106]
+
+RFC 2446 iTIP November 1998
+
+
+9 Authors' Addresses
+
+ The following address information is provided in a vCard v3.0,
+ Electronic Business Card, format.
+
+ The authors of this memo are:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Dawson;Frank
+ FN:Frank Dawson
+ ORG:Lotus Development Corporation
+ ADR;WORK;POSTAL;PARCEL:;;6544 Battleford Drive;Raleigh;NC;27613-
+ 3502;USA
+ TEL;TYPE=WORK,MSG:+1-919-676-9515
+ TEL;TYPE=WORK,FAX:+1-919-676-9564
+ EMAIL;TYPE=PREF,INTERNET:Frank_Dawson at Lotus.com
+ EMAIL;TYPE=INTERNET:fdawson at earthlink.net
+ URL:http://home.earthlink.net/~fdawson
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Hopson;Ross
+ FN:Ross Hopson
+ ORG:On Technology, Inc.
+ ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 1600;434 Fayetteville St.
+ Mall\, Two Hannover Square;Raleigh;NC;27601
+ TEL;TYPE=WORK,MSG:+1-919-890-4036
+ TEL;TYPE=WORK,FAX:+1-919-890-4100
+ EMAIL;TYPE=INTERNET:rhopson at on.com
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Mansour;Steve
+ FN:Steve Mansour
+ ORG:Netscape Communications Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;501 East Middlefield Road;Mountain
+ View;CA;94043;USA
+ TEL;TYPE=WORK,MSG:+1-650-937-2378
+ TEL;TYPE=WORK,FAX:+1-650-937-2103
+ EMAIL;TYPE=INTERNET:sman at netscape.com
+ END:VCARD
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 107]
+
+RFC 2446 iTIP November 1998
+
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Silverberg;Steve
+ FN:Steve Silverberg
+ ORG:Microsoft Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
+ Redmond;WA;98052-6399;USA
+ TEL;TYPE=WORK,MSG:+1-425-936-9277
+ TEL;TYPE=WORK,FAX:+1-425-936-8019
+ EMAIL;INTERNET:stevesil at Microsoft.com
+ END:VCARD
+
+ The iCalendar object is a result of the work of the Internet
+ Engineering Task Force Calendaring and scheduling Working Group. The
+ chairman of that working group is:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Ganguly;Anik
+ FN:Anik Ganguly
+ ORG:Open Text Inc.
+ ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
+ Livonia;MI;48152;USA
+ TEL;TYPE=WORK,MSG:+1-734-542-5955
+ EMAIL;TYPE=INTERNET:ganguly at acm.org
+ END:VCARD
+
+ The co-chairman of that working group is:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Moskowitz;Robert
+ FN:Robert Moskowitz
+ NICKNAME:Bob
+ EMAIL; TYPE=INTERNET:rgm-ietf at htt-consult.com
+ END:VCARD
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 108]
+
+RFC 2446 iTIP November 1998
+
+
+10. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Silverberg, et. al. Standards Track [Page 109]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2446.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2446.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2446.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,6107 +0,0 @@
-
-
-
-
-
-
-Network Working Group S. Silverberg
-Request for Comments: 2446 Microsoft
-Category: Standards Track S. Mansour
- Netscape
- F. Dawson
- Lotus
- R. Hopson
- ON Technologies
- November 1998
-
-
- iCalendar Transport-Independent Interoperability Protocol
- (iTIP)
- Scheduling Events, BusyTime, To-dos and Journal Entries
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
-Abstract
-
- This document specifies how calendaring systems use iCalendar objects
- to interoperate with other calendar systems. It does so in a general
- way so as to allow multiple methods of communication between systems.
- Subsequent documents specify interoperable methods of communications
- between systems that use this protocol.
-
- The document outlines a model for calendar exchange that defines both
- static and dynamic event, to-do, journal and free/busy objects.
- Static objects are used to transmit information from one entity to
- another without the expectation of continuity or referential
- integrity with the original item. Dynamic objects are a superset of
- static objects and will gracefully degrade to their static
- counterparts for clients that only support static objects.
-
- This document specifies an Internet protocol based on the iCalendar
- object specification that provides scheduling interoperability
- between different calendar systems. The Internet protocol is called
- the "iCalendar Transport-Independent Interoperability Protocol
- (iTIP)".
-
-
-
-Silverberg, et. al. Standards Track [Page 1]
-
-RFC 2446 iTIP November 1998
-
-
- iTIP complements the iCalendar object specification by adding
- semantics for group scheduling methods commonly available in current
- calendar systems. These scheduling methods permit two or more
- calendar systems to perform transactions such as publish, schedule,
- reschedule, respond to scheduling requests, negotiation of changes or
- cancel iCalendar-based calendar components.
-
- iTIP is defined independent of the particular transport used to
- transmit the scheduling information. Companion memos to iTIP provide
- bindings of the interoperability protocol to a number of Internet
- protocols.
-
-Table of Contents
-
- 1 INTRODUCTION...................................................5
- 1.1 FORMATTING CONVENTIONS .....................................5
- 1.2 RELATED DOCUMENTS ..........................................6
- 1.3 ITIP ROLES AND TRANSACTIONS ................................6
- 2 INTEROPERABILITY MODELS........................................8
- 2.1 APPLICATION PROTOCOL .......................................9
- 2.1.1 Calendar Entry State ...................................9
- 2.1.2 Delegation .............................................9
- 2.1.3 Acting on Behalf of other Calendar Users ..............10
- 2.1.4 Component Revisions ...................................10
- 2.1.5 Message Sequencing ....................................11
- 3 APPLICATION PROTOCOL ELEMENTS.................................12
- 3.1 COMMON COMPONENT RESTRICTION TABLES .......................13
- 3.2 METHODS FOR VEVENT CALENDAR COMPONENTS ....................14
- 3.2.1 PUBLISH ...............................................15
- 3.2.2 REQUEST ...............................................17
- 3.2.2.1 Rescheduling an Event..............................19
- 3.2.2.2 Updating or Reconfirmation of an Event.............19
- 3.2.2.3 Delegating an Event to another CU..................19
- 3.2.2.4 Changing the Organizer.............................20
- 3.2.2.5 Sending on Behalf of the Organizer.................20
- 3.2.2.6 Forwarding to An Uninvited CU......................20
- 3.2.2.7 Updating Attendee Status...........................21
- 3.2.3 REPLY .................................................21
- 3.2.4 ADD ...................................................23
- 3.2.5 CANCEL ................................................25
- 3.2.6 REFRESH ...............................................26
- 3.2.7 COUNTER ...............................................28
- 3.2.8 DECLINECOUNTER ........................................29
- 3.3 METHODS FOR VFREEBUSY COMPONENTS ..........................31
- 3.3.1 PUBLISH ...............................................32
- 3.3.2 REQUEST ...............................................33
- 3.3.3 REPLY .................................................34
- 3.4 METHODS FOR VTODO COMPONENTS ..............................35
-
-
-
-Silverberg, et. al. Standards Track [Page 2]
-
-RFC 2446 iTIP November 1998
-
-
- 3.4.1 PUBLISH ...............................................35
- 3.4.2 REQUEST ...............................................37
- 3.4.2.1 REQUEST for Rescheduling a VTODO...................39
- 3.4.2.2 REQUEST for Update or Reconfirmation of a VTODO....39
- 3.4.2.3 REQUEST for Delegating a VTODO.....................40
- 3.4.2.4 REQUEST Forwarded To An Uninvited Calendar User....40
- 3.4.2.5 REQUEST Updated Attendee Status....................41
- 3.4.3 REPLY .................................................41
- 3.4.4 ADD ...................................................43
- 3.4.5 CANCEL ................................................44
- 3.4.6 REFRESH ...............................................46
- 3.4.7 COUNTER ...............................................48
- 3.4.8 DECLINECOUNTER ........................................49
- 3.5 METHODS FOR VJOURNAL COMPONENTS ...........................50
- 3.5.1 PUBLISH ...............................................51
- 3.5.2 ADD ...................................................52
- 3.5.3 CANCEL ................................................53
- 3.6 STATUS REPLIES ............................................55
- 3.7 IMPLEMENTATION CONSIDERATIONS .............................57
- 3.7.1 Working With Recurrence Instances .....................57
- 3.7.2 Attendee Property Considerations ......................58
- 3.7.3 X-Tokens ..............................................59
- 4 EXAMPLES......................................................59
- 4.1 PUBLISHED EVENT EXAMPLES ..................................59
- 4.1.1 A Minimal Published Event .............................60
- 4.1.2 Changing A Published Event ............................60
- 4.1.3 Canceling A Published Event ...........................61
- 4.1.4 A Rich Published Event ................................62
- 4.1.5 Anniversaries or Events attached to entire days .......63
- 4.2 GROUP EVENT EXAMPLES ......................................63
- 4.2.1 A Group Event Request .................................64
- 4.2.2 Reply To A Group Event Request ........................65
- 4.2.3 Update An Event .......................................65
- 4.2.4 Countering an Event Proposal ..........................66
- 4.2.5 Delegating an Event ...................................68
- 4.2.6 Delegate Accepts the Meeting ..........................70
- 4.2.7 Delegate Declines the Meeting .........................71
- 4.2.8 Forwarding an Event Request ...........................72
- 4.2.9 Cancel A Group Event ..................................72
- 4.2.10 Removing Attendees ...................................74
- 4.2.11 Replacing the Organizer ..............................75
- 4.3 BUSY TIME EXAMPLES ........................................76
- 4.3.1 Request Busy Time .....................................77
- 4.3.2 Reply To A Busy Time Request ..........................77
- 4.4 RECURRING EVENT AND TIME ZONE EXAMPLES ....................78
- 4.4.1 A Recurring Event Spanning Time Zones .................78
- 4.4.2 Modify A Recurring Instance ...........................79
- 4.4.3 Cancel an Instance ....................................81
-
-
-
-Silverberg, et. al. Standards Track [Page 3]
-
-RFC 2446 iTIP November 1998
-
-
- 4.4.4 Cancel Recurring Event ................................81
- 4.4.5 Change All Future Instances ...........................82
- 4.4.6 Add A New Instance To A Recurring Event ...............82
- 4.4.7 Add A New Series of Instances To A Recurring Event ....83
- 4.4.8 Counter An Instance Of A Recurring Event ..............87
- 4.4.9 Error Reply To A Request ..............................88
- 4.5 GROUP TO-DO EXAMPLES ......................................89
- 4.5.1 A VTODO Request .......................................90
- 4.5.2 A VTODO Reply .........................................90
- 4.5.3 A VTODO Request for Updated Status ....................91
- 4.5.4 A Reply: Percent-Complete .............................91
- 4.5.5 A Reply: Completed ....................................92
- 4.5.6 An Updated VTODO Request ..............................92
- 4.5.7 Recurring VTODOs ......................................92
- 4.5.7.1 Request for a Recurring VTODO......................93
- 4.5.7.2 Calculating due dates in recurring VTODOs..........93
- 4.5.7.3 Replying to an instance of a recurring VTODO.......93
- 4.6 JOURNAL EXAMPLES ..........................................94
- 4.7 OTHER EXAMPLES ............................................94
- 4.7.1 Event Refresh .........................................94
- 4.7.2 Bad RECURRENCE-ID .....................................95
- 5 APPLICATION PROTOCOL FALLBACKS................................97
- 5.1 PARTIAL IMPLEMENTATION ....................................97
- 5.1.1 Event-Related Fallbacks ...............................97
- 5.1.2 Free/Busy-Related Fallbacks ...........................99
- 5.1.3 To-Do-Related Fallbacks ...............................99
- 5.1.4 Journal-Related Fallbacks ............................101
- 5.2 LATENCY ISSUES ...........................................102
- 5.2.1 Cancellation of an Unknown Calendar Component. .......102
- 5.2.2 Unexpected Reply from an Unknown Delegate ............103
- 5.3 SEQUENCE NUMBER ..........................................103
- 6 SECURITY CONSIDERATIONS......................................103
- 6.1 SECURITY THREATS .........................................103
- 6.1.1 Spoofing the "Organizer" .............................103
- 6.1.2 Spoofing the "Attendee" ..............................103
- 6.1.3 Unauthorized Replacement of the Organizer ............104
- 6.1.4 Eavesdropping ........................................104
- 6.1.5 Flooding a Calendar ..................................104
- 6.1.6 Procedural Alarms ....................................104
- 6.1.7 Unauthorized REFRESH Requests ........................104
- 6.2 RECOMMENDATIONS ..........................................104
- 6.2.1 Use of [RFC-1847] to secure iTIP transactions ........105
- 6.2.2 Implementation Controls ..............................105
- 7 ACKNOWLEDGMENTS..............................................106
- 8 BIBLIOGRAPHY.................................................106
- 9 AUTHORS' ADDRESSES...........................................107
- 10 FULL COPYRIGHT STATEMENT....................................109
-
-
-
-
-Silverberg, et. al. Standards Track [Page 4]
-
-RFC 2446 iTIP November 1998
-
-
-1 Introduction
-
- This document specifies how calendaring systems use iCalendar objects
- to interoperate with other calendar systems. In particular, it
- specifies how to schedule events, to-dos, or daily journal entries.
- It further specifies how to search for available busy time
- information. It does so in a general way so as to allow multiple
- methods of communication between systems. Subsequent documents
- specify transport bindings between systems that use this protocol.
-
- This protocol is based on messages sent from an originator to one or
- more recipients. For certain types of messages, a recipient may
- reply, in order to update their status and may also return
- transaction/request status information. The protocol supports the
- ability for the message originator to modify or cancel the original
- message. The protocol also supports the ability for recipients to
- suggest changes to the originator of a message. The elements of the
- protocol also define the user roles for its transactions.
-
-1.1 Formatting Conventions
-
- In order to refer to elements of the calendaring and scheduling
- model, core object or interoperability protocol defined in [iCAL] and
- [iTIP] several formatting conventions have been utilized.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
- document are to be interpreted as described in [RFC-2119].
-
- Calendaring and scheduling roles are referred to in quoted-strings of
- text with the first character of each word in upper case. For
- example, "Organizer" refers to a role of a "Calendar User" (CU)
- within the scheduling protocol defined by [iTIP]. Calendar components
- defined by [iCAL] are referred to with capitalized, quoted-strings of
- text. All calendar components start with the letter "V". For example,
- "VEVENT" refers to the event calendar component, "VTODO" refers to
- the to-do calendar component and "VJOURNAL" refers to the daily
- journal calendar component. Scheduling methods defined by [iTIP] are
- referred to with capitalized, quoted-strings of text. For example,
- "REQUEST" refers to the method for requesting a scheduling calendar
- component be created or modified, "REPLY" refers to the method a
- recipient of a request uses to update their status with the
- "Organizer" of the calendar component.
-
- Properties defined by [iCAL] are referred to with capitalized,
- quoted-strings of text, followed by the word "property". For example,
- "ATTENDEE" property refers to the iCalendar property used to convey
- the calendar address of a "Calendar User". Property parameters
-
-
-
-Silverberg, et. al. Standards Track [Page 5]
-
-RFC 2446 iTIP November 1998
-
-
- defined by this memo are referred to with lower case, quoted-strings
- of text, followed by the word "parameter". For example, "value"
- parameter refers to the iCalendar property parameter used to override
- the default data type for a property value. Enumerated values defined
- by this memo are referred to with capitalized text, either alone or
- followed by the word "value".
-
- In tables, the quoted-string text is specified without quotes in
- order to minimize the table length.
-
-1.2 Related Documents
-
- Implementers will need to be familiar with several other memos that,
- along with this one, describe the Internet calendaring and scheduling
- standards. This document, [iTIP], specifies an interoperability
- protocol for scheduling between different implementations. The
- related documents are:
-
- [iCAL] - specifies the objects, data types, properties and
- property parameters used in the protocols, along with the
- methods for representing and encoding them;
-
- [iMIP] specifies an Internet email binding for [iTIP].
-
- This memo does not attempt to repeat the specification of concepts or
- definitions from these other memos. Where possible, references are
- made to the memo that provides for the specification of these
- concepts or definitions.
-
-1.3 ITIP Roles and Transactions
-
- ITIP defines methods for exchanging [iCAL] objects for the purposes
- of group calendaring and scheduling between "Calendar Users" (CUs).
- CUs take on one of two roles in iTIP. The CU who initiates an
- exchange takes on the role of "Organizer". For example, the CU who
- proposes a group meeting is the "Organizer". The CUs asked to
- participate in the group meeting by the "Organizer" take on the role
- of "Attendee". Note that "role" is also a descriptive parameter to
- the _ATTENDEE_ property. Its use is to convey descriptive context to
- an "Attendee" such as "chair", "req-participant" or "non-participant"
- and has nothing to do with the calendaring workflow.
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 6]
-
-RFC 2446 iTIP November 1998
-
-
- The ITIP methods are listed below and their usage and semantics are
- defined in section 3 of this document.
-
- +================+==================================================+
- | Method | Description |
- |================+==================================================|
- | PUBLISH | Used to publish a calendar entry to one or more |
- | | Calendar Users. There is no interactivity |
- | | between the publisher and any other calendar |
- | | user. An example might include a baseball team |
- | | publishing its schedule to the public. |
- | | |
- | REQUEST | Used to schedule a calendar entry with other |
- | | Calendar Users. Requests are interactive in that |
- | | they require the receiver to respond using |
- | | the Reply methods. Meeting Requests, Busy |
- | | Time requests and the assignment of VTODOs to |
- | | other Calendar Users are all examples. |
- | | Requests are also used by the "Organizer" to |
- | | update the status of a calendar entry. |
- | | |
- | REPLY | A Reply is used in response to a Request to |
- | | convey "Attendee" status to the "Organizer". |
- | | Replies are commonly used to respond to meeting |
- | | and task requests. |
- | | |
- | ADD | Add one or more instances to an existing |
- | | VEVENT, VTODO, or VJOURNAL. |
- | | |
- | CANCEL | Cancel one or more instances of an existing |
- | | VEVENT, VTODO, or VJOURNAL. |
- | | |
- | REFRESH | The Refresh method is used by an "Attendee" to |
- | | request the latest version of a calendar entry. |
- | | |
- | COUNTER | The Counter method is used by an "Attendee" to |
- | | negotiate a change in the calendar entry. |
- | | Examples include the request to change a |
- | | proposed Event time or change the due date for a |
- | | VTODO. |
- | | |
- | DECLINE- | Used by the "Organizer" to decline the proposed |
- | COUNTER | counter-proprosal. |
- +================+==================================================+
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 7]
-
-RFC 2446 iTIP November 1998
-
-
- Group scheduling in iTIP is accomplished using the set of "request"
- and "response" methods described above. The following table shows the
- methods broken down by who can send them.
-
- +================+==================================================+
- | Originator | Methods |
- |================+==================================================|
- | Organizer | PUBLISH, REQUEST, ADD, CANCEL, DECLINECOUNTER |
- | | |
- | Attendee | REPLY, REFRESH, COUNTER |
- | | REQUEST only when delegating |
- +================+==================================================+
-
- Note that for some calendar component types, the allowable methods
- are a subset of the above set.
-
-2 Interoperability Models
-
- There are two distinct protocols relevant to interoperability: an
- "Application Protocol" and a "Transport Protocol". The Application
- Protocol defines the content of the iCalendar objects sent between
- sender and receiver to accomplish the scheduling transactions listed
- above. The Transport Protocol defines how the iCalendar objects are
- sent between the sender and receiver. This document focuses on the
- Application Protocol. Binding documents such as [iMIP] focus on the
- Transport Protocol.
-
- The connection between Sender and Receiver in the diagram below
- refers to the Application Protocol. The iCalendar objects passed from
- the Sender to the Receiver are presented in Section 3, Application
- Protocol Elements.
-
- +----------+ +----------+
- | | iTIP | |
- | Sender |<-------------------->| Receiver |
- | | | |
- +----------+ +----------+
-
- There are several variations of this diagram in which the Sender and
- Receiver take on various roles of a "Calendar User Agent" (CUA) or a
- "Calendar Service" (CS).
-
- The architecture of iTIP is depicted in the diagram below. An
- application written to this specification may work with bindings for
- the store-and-forward transport, the real time transport, or both.
- Also note that iTIP could be bound to other transports.
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 8]
-
-RFC 2446 iTIP November 1998
-
-
- +------------------------------------------+
- | iTIP |
- +------------------------------------------+
- |Real-time | Store-and-Fwd | Other |
- |Transport | Transport | Transports... |
- +------------------------------------------+
-
-2.1 Application Protocol
-
- In the iTIP model, a calendar entry is created and managed by an
- "Organizer". The "Organizer" interacts with other CUs by sending one
- or more of the iTIP messages listed above. "Attendees" use the
- "REPLY" method to communicate their status. "Attendees" do not make
- direct changes to the master calendar entry. They can, however, use
- the "COUNTER" method to suggest changes to the "Organizer". In any
- case, the "Organizer" has complete control over the master calendar
- entry.
-
-2.1.1 Calendar Entry State
-
- There are two distinct states relevant to calendar entries: the
- overall state of the entry and the state associated with an
- "Attendee" to that entry.
-
- The state of an entry is defined by the "STATUS" property and is
- controlled by the "Organizer." There is no default value for the
- "STATUS" property. The "Organizer" sets the "STATUS" property to the
- appropriate value for each calendar entry.
-
- The state of a particular "Attendee" relative to an entry is defined
- by the "partstat" parameter in the "ATTENDEE" property for each
- "Attendee". When an "Organizer" issues the initial entry, "Attendee"
- status is unknown. The "Organizer" specifies this by setting the
- "partstat" parameter to "NEEDS-ACTION". Each "Attendee" modifies
- their "ATTENDEE" property "partstat" parameter to an appropriate
- value as part of a "REPLY" message sent back to the "Organizer".
-
-2.1.2 Delegation
-
- Delegation is defined as the process by which an "Attendee" grants
- another CU (or several CUs) the right to attend on their behalf. The
- "Organizer" is made aware of this change because the delegating
- "Attendee" informs the "Organizer". These steps are detailed in the
- REQUEST method section.
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 9]
-
-RFC 2446 iTIP November 1998
-
-
-2.1.3 Acting on Behalf of other Calendar Users
-
- In many organizations one user will act on behalf of another to
- organize and/or respond to meeting requests. ITIP provides two
- mechanisms that support these activities.
-
- First, the "Organizer" is treated as a special entity, separate from
- "Attendees". All responses from "Attendees" flow to the "Organizer",
- making it easy to separate a calendar user organizing a meeting from
- calendar users attending the meeting. Additionally, iCalendar
- provides descriptive roles for each "Attendee". For instance, a role
- of "chair" may be ascribed to one or more "Attendees". The "chair"
- and the "Organizer" may or may not be the same calendar user. This
- maps well to scenarios where an assistant may manage meeting
- logistics for another individual who chairs a meeting.
-
- Second, a "sent-by" parameter may be specified in either the
- "Organizer" or "Attendee" properties. When specified, the "sent-by"
- parameter indicates that the responding CU acted on behalf of the
- specified "Attendee" or "Organizer".
-
-2.1.4 Component Revisions
-
- The "SEQUENCE" property is used by the "Organizer" to indicate
- revisions to the calendar component. The rules for incrementing the
- "SEQUENCE" number are defined in [iCAL]. For clarity, these rules are
- paraphrased here in terms of how they are applied in [iTIP]. For a
- given "UID" in a calendar component:
-
- . For the "PUBLISH" and "REQUEST" methods, the "SEQUENCE" property
- value is incremented according to the rules defined in [iCAL].
-
- . The "SEQUENCE" property value MUST be incremented each time the
- "Organizer" uses the "ADD" or "CANCEL" methods.
-
- . The "SEQUENCE" property value MUST NOT be incremented when using
- "REPLY", "REFRESH", "COUNTER", "DECLINECOUNTER", or when sending a
- delegation "REQUEST".
-
- In some circumstances the "Organizer" may not have received responses
- to the final revision sent out. In this situation, the "Organizer"
- may wish to send an update "REQUEST", and set "RSVP=TRUE" for all
- "Attendees", so that current responses can be collected.
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 10]
-
-RFC 2446 iTIP November 1998
-
-
- The value of the "SEQUENCE" property contained in a response from an
- "Attendee" may not always match the "Organizer's" revision.
- Implementations may choose to have the CUA indicate to the CU that
- the response is to an entry that has been revised and allow the CU to
- decide whether or not to accept the response.
-
-2.1.5 Message Sequencing
-
- CUAs that handle the [iTIP] application protocol must often correlate
- a component in a calendar store with a component received in the
- [iTIP] message. For example, an event may be updated with a later
- revision of the same event. To accomplish this, a CUA must correlate
- the version of the event already in its calendar store with the
- version sent in the [iTIP] message. In addition to this correlation,
- there are several factors that can cause [iTIP] messages to arrive in
- an unexpected order. That is, an "Organizer" could receive a reply
- to an earlier revision of a component AFTER receiving a reply to a
- later revision.
-
- To maximize interoperability and to handle messages that arrive in an
- unexpected order, use the following rules:
-
- 1. The primary key for referencing a particular iCalendar component
- is the "UID" property value. To reference an instance of a
- recurring component, the primary key is composed of the "UID" and
- the "RECURRENCE-ID" properties.
-
- 2. The secondary key for referencing a component is the "SEQUENCE"
- property value. For components where the "UID" is the same, the
- component with the highest numeric value for the "SEQUENCE"
- property obsoletes all other revisions of the component with
- lower values.
-
- 3. "Attendees" send "REPLY" messages to the "Organizer". For
- replies where the "UID" property value is the same, the value of
- the "SEQUENCE" property indicates the revision of the component
- to which the "Attendee" is replying. The reply with the highest
- numeric value for the "SEQUENCE" property obsoletes all other
- replies with lower values.
-
- 4. In situations where the "UID" and "SEQUENCE" properties match,
- the "DTSTAMP" property is used as the tie-breaker. The component
- with the latest "DTSTAMP" overrides all others. Similarly, for
- "Attendee" responses where the "UID" property values match and
- the "SEQUENCE" property values match, the response with the
- latest "DTSTAMP" overrides all others.
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 11]
-
-RFC 2446 iTIP November 1998
-
-
- Hence, CUAs must persist the following component properties: "UID",
- "RECURRENCE-ID", "SEQUENCE", and "DTSTAMP". Furthermore, for each
- "ATTENDEE" property of a component CUAs must persist the "SEQUENCE"
- and "DTSTAMP" property values associated with the "Attendee's"
- response.
-
-3 Application Protocol Elements
-
- ITIP messages are "text/calendar" MIME entities that contain
- calendaring and scheduling information. The particular type of [iCAL]
- message is referred to as the "method type". Each method type is
- identified by a "METHOD" property specified as part of the
- "text/calendar" content type. The table below shows various
- combinations of calendar components and the method types that this
- memo supports.
-
- +=================================================+
- | | VEVENT | VTODO | VJOURNAL | VFREEBUSY |
- |=================================================|
- |Publish | Yes | Yes | Yes | Yes |
- |Request | Yes | Yes | No | Yes |
- |Refresh | Yes | Yes | No | No |
- |Cancel | Yes | Yes | Yes | No |
- |Add | Yes | Yes | Yes | No |
- |Reply | Yes | Yes | No | Yes |
- |Counter | Yes | Yes | No | No |
- |Decline- | | | | |
- |Counter | Yes | Yes | No | No |
- +=================================================+
-
- Each method type is defined in terms of its associated components and
- properties. Some components and properties are required, some are
- optional and others are excluded. The restrictions are expressed in
- this document using a simple "restriction table". The first column
- indicates the name of a component or property. Properties of the
- iCalendar object are not indented. Properties of a component are
- indented. The second column contains "MUST" if the component or
- property must be present, "MAY" if the component or property is
- optional, and "NOT" if the component or property must not be present.
- Entries in the second column sometimes contain comments for further
- clarification.
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 12]
-
-RFC 2446 iTIP November 1998
-
-
-3.1 Common Component Restriction Tables
-
- The restriction table below applies to properties of the iCalendar
- object. That is, the properties at the outermost scope. The presence
- column uses the following values to assert whether a property is
- required, is optional and the number of times it may appear in the
- iCalendar object.
-
- Presence Value Description
- --------------------------------------------------------------
- 1 One instance MUST be present
- 1+ At least one instance MUST be present
- 0 Instances of this property Must NOT be present
- 0+ Multiple instances MAY be present
- 0 or 1 Up to 1 instance of this property MAY be present
- ---------------------------------------------------------------
-
- The tables also call out "X-PROPERTY" and "X-COMPONENT" to show
- where vendor-specific properties and components can appear. The
- tables do not lay out the restrictions of property parameters. Those
- restrictions are defined in [iCAL].
-
- Component/Property Presence
- ------------------- ----------------------------------------------
- CALSCALE 0 or 1
- PRODID 1
- VERSION 1 Value MUST be "2.0"
- X-PROPERTY 0+
-
-
- DateTime values MAY refer to a "VTIMEZONE" component. The property
- restrictions in the table below apply to any "VTIMEZONE" component in
- an ITIP message.
-
- Component/Property Presence
- ------------------- ----------------------------------------------
- VTIMEZONE 0+ MUST be present if any date/time refers
- to timezone
- DAYLIGHT 0+ MUST be one or more of either STANDARD or
- DAYLIGHT
- COMMENT 0 or 1
- DTSTART 1 MUST be local time format
- RDATE 0+ if present RRULE MUST NOT be present
- RRULE 0+ if present RDATE MUST NOT be present
- TZNAME 0 or 1
- TZOFFSET 1
- TZOFFSETFROM 1
- TZOFFSETTO 1
-
-
-
-Silverberg, et. al. Standards Track [Page 13]
-
-RFC 2446 iTIP November 1998
-
-
- X-PROPERTY 0+
- LAST-MODIFIED 0 or 1
- STANDARD 0+ MUST be one or more of either STANDARD or
- DAYLIGHT
- COMMENT 0 or 1
- DTSTART 1 MUST be local time format
- RDATE 0+ if present RRULE MUST NOT be present
- RRULE 0+ if present RDATE MUST NOT be present
- TZNAME 0 or 1
- TZOFFSETFROM 1
- TZOFFSETTO 1
- X-PROPERTY 0+
- TZID 1
- TZURL 0 or 1
- X-PROPERTY 0+
-
- The property restrictions in the table below apply to any "VALARM"
- component in an ITIP message.
-
- Component/Property Presence
- ------------------- ----------------------------------------------
- VALARM 0+
- ACTION 1
- ATTACH 0+
- DESCRIPTION 0 or 1
- DURATION 0 or 1 if present REPEAT MUST be present
- REPEAT 0 or 1 if present DURATION MUST be present
- SUMMARY 0 or 1
- TRIGGER 1
- X-PROPERTY 0+
-
-3.2 Methods for VEVENT Calendar Components
-
- This section defines the property set restrictions for the method
- types that are applicable to the "VEVENT" calendar component. Each
- method is defined using a table that clarifies the property
- constraints that define the particular method.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 14]
-
-RFC 2446 iTIP November 1998
-
-
- The following summarizes the methods that are defined for the
- "VEVENT" calendar component.
-
- +================+==================================================+
- | Method | Description |
- |================+==================================================|
- | PUBLISH | Post notification of an event. Used primarily as |
- | | a method of advertising the existence of an |
- | | event. |
- | | |
- | REQUEST | Make a request for an event. This is an explicit |
- | | invitation to one or more "Attendees". Event |
- | | Requests are also used to update or change an |
- | | existing event. Clients that cannot handle |
- | | REQUEST may degrade the event to view it as an |
- | | PUBLISH. |
- | | |
- | REPLY | Reply to an event request. Clients may set their |
- | | status ("partstat") to ACCEPTED, DECLINED, |
- | | TENTATIVE, or DELEGATED. |
- | | |
- | ADD | Add one or more instances to an existing event. |
- | | |
- | CANCEL | Cancel one or more instances of an existing |
- | | event. |
- | | |
- | REFRESH | A request is sent to an "Organizer" by an |
- | | "Attendee" asking for the latest version of an |
- | | event to be resent to the requester. |
- | | |
- | COUNTER | Counter a REQUEST with an alternative proposal, |
- | | Sent by an "Attendee" to the "Organizer". |
- | | |
- | DECLINECOUNTER | Decline a counter proposal. Sent to an |
- | | "Attendee" by the "Organizer". |
- +================+==================================================+
-
-3.2.1 PUBLISH
-
- The "PUBLISH" method in a "VEVENT" calendar component is an
- unsolicited posting of an iCalendar object. Any CU may add published
- components to their calendar. The "Organizer" MUST be present in a
- published iCalendar component. "Attendees" MUST NOT be present. Its
- expected usage is for encapsulating an arbitrary event as an
- iCalendar object. The "Organizer" may subsequently update (with
- another "PUBLISH" method), add instances to (with an "ADD" method),
- or cancel (with a "CANCEL" method) a previously published "VEVENT"
- calendar component.
-
-
-
-Silverberg, et. al. Standards Track [Page 15]
-
-RFC 2446 iTIP November 1998
-
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST equal "PUBLISH"
-VEVENT 1+
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- SUMMARY 1 Can be null.
- UID 1
- RECURRENCE-ID 0 or 1 only if referring to an instance of a
- recurring calendar component. Otherwise
- it MUST NOT be present.
- SEQUENCE 0 or 1 MUST be present if value is greater than
- 0, MAY be present if 0
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of
- values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RELATED-TO 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0+
- STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED/CANCELLED
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
- ATTENDEE 0
- REQUEST-STATUS 0
-
-VALARM 0+
-VFREEBUSY 0
-VJOURNAL 0
-
-
-
-Silverberg, et. al. Standards Track [Page 16]
-
-RFC 2446 iTIP November 1998
-
-
-VTODO 0
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-3.2.2 REQUEST
-
- The "REQUEST" method in a "VEVENT" component provides the following
- scheduling functions:
-
- . Invite "Attendees" to an event;
- . Reschedule an existing event;
- . Response to a REFRESH request;
- . Update the details of an existing event, without rescheduling it;
- . Update the status of "Attendees" of an existing event, without
- rescheduling it;
- . Reconfirm an existing event, without rescheduling it;
- . Forward a "VEVENT" to another uninvited CU.
- . For an existing "VEVENT" calendar component, delegate the role of
- "Attendee" to another CU;
- . For an existing "VEVENT" calendar component, changing the role of
- "Organizer" to another CU.
-
- The "Organizer" originates the "REQUEST". The recipients of the
- "REQUEST" method are the CUs invited to the event, the "Attendees".
- "Attendees" use the "REPLY" method to convey attendance status to the
- "Organizer".
-
- The "UID" and "SEQUENCE" properties are used to distinguish the
- various uses of the "REQUEST" method. If the "UID" property value in
- the "REQUEST" is not found on the recipient's calendar, then the
- "REQUEST" is for a new "VEVENT" calendar component. If the "UID"
- property value is found on the recipient's calendar, then the
- "REQUEST" is for a rescheduling, an update, or a reconfirm of the
- "VEVENT" calendar component.
-
- For the "REQUEST" method, multiple "VEVENT" components in a single
- iCalendar object are only permitted when for components with the same
- "UID" property. That is, a series of recurring events may have
- instance-specific information. In this case, multiple "VEVENT"
- components are needed to express the entire series.
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 17]
-
-RFC 2446 iTIP November 1998
-
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
------------------------------------------------------------------
-METHOD 1 MUST be "REQUEST"
-VEVENT 1+ All components MUST have the same UID
- ATTENDEE 1+
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- SEQUENCE 0 or 1 MUST be present if value is greater than 0,
- MAY be present if 0
- SUMMARY 1 Can be null
- UID 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 only if referring to an instance of a
- recurring calendar component. Otherwise it
- MUST NOT be present.
- RELATED-TO 0+
- REQUEST-STATUS 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0+
- STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
-VALARM 0+
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 18]
-
-RFC 2446 iTIP November 1998
-
-
-VFREEBUSY 0
-VJOURNAL 0
-VTODO 0
-
-3.2.2.1 Rescheduling an Event
-
- The "REQUEST" method may be used to reschedule an event. A
- rescheduled event involves a change to the existing event in terms of
- its time or recurrence intervals and possibly the location or
- description. If the recipient CUA of a "REQUEST" method finds that
- the "UID" property value already exists on the calendar, but that the
- "SEQUENCE" (or "DTSTAMP") property value in the "REQUEST" method is
- greater than the value for the existing event, then the "REQUEST"
- method describes a rescheduling of the event.
-
-3.2.2.2 Updating or Reconfirmation of an Event
-
- The "REQUEST" method may be used to update or reconfirm an event. An
- update to an existing event does not involve changes to the time or
- recurrence intervals, and might not involve a change to the location
- or description for the event. If the recipient CUA of a "REQUEST"
- method finds that the "UID" property value already exists on the
- calendar and that the "SEQUENCE" property value in the "REQUEST" is
- the same as the value for the existing event, then the "REQUEST"
- method describes an update of the event details, but no rescheduling
- of the event.
-
- The update "REQUEST" method is the appropriate response to a
- "REFRESH" method sent from an "Attendee" to the "Organizer" of an
- event.
-
- The "Organizer" of an event may also send unsolicited "REQUEST"
- methods. The unsolicited "REQUEST" methods may be used to update the
- details of the event without rescheduling it, to update the
- "partstat" parameter of "Attendees", or to reconfirm the event.
-
-3.2.2.3 Delegating an Event to another CU
-
- Some calendar and scheduling systems allow "Attendees" to delegate
- their presence at an event to another calendar user. ITIP supports
- this concept using the following workflow. Any "Attendee" may
- delegate their right to participate in a calendar VEVENT to another
- CU. The implication is that the delegate participates in lieu of the
- original "Attendee"; NOT in addition to the "Attendee". The delegator
- MUST notify the "Organizer" of this action using the steps outlined
- below. Implementations may support or restrict delegation as they
- see fit. For instance, some implementations may restrict a delegate
- from delegating a "REQUEST" to another CU.
-
-
-
-Silverberg, et. al. Standards Track [Page 19]
-
-RFC 2446 iTIP November 1998
-
-
- The "Delegator" of an event forwards the existing "REQUEST" to the
- "Delegate". The "REQUEST" method MUST include an "ATTENDEE" property
- with the calendar address of the "Delegate". The "Delegator" MUST
- also send a "REPLY" method to the "Organizer" with the "Delegator's"
- "ATTENDEE" property "partstat" parameter value set to "delegated". In
- addition, the "delegated-to" parameter MUST be included with the
- calendar address of the "Delegate".
-
- In response to the request, the "Delegate" MUST send a "REPLY" method
- to the "Organizer" and optionally, to the "Delegator". The "REPLY"
- method " SHOULD include the "ATTENDEE" property with the "delegated-
- from" parameter value of the "Delegator's" calendar address.
-
- The "Delegator" may continue to receive updates to the event even
- though they will not be attending. This is accomplished by the
- "Delegator" setting their "role" attribute to " NON-PARTICIPANT" in
- the "REPLY" to the "Organizer"
-
-3.2.2.4 Changing the Organizer
-
- The situation may arise where the "Organizer" of a VEVENT is no
- longer able to perform the "Organizer" role and abdicates without
- passing on the "Organizer" role to someone else. When this occurs the
- "Attendees" of the VEVENT may use out-of-band mechanisms to
- communicate the situation and agree upon a new "Organizer". The new
- "Organizer" should then send out a new "REQUEST" with a modified
- version of the VEVENT in which the "SEQUENCE" number has been
- incremented and value of the "ORGANIZER" property has been changed to
- the calendar address of the new "Organizer".
-
-3.2.2.5 Sending on Behalf of the Organizer
-
- There are a number of scenarios that support the need for a calendar
- user to act on behalf of the "Organizer" without explicit role
- changing. This might be the case if the CU designated as "Organizer"
- was sick or unable to perform duties associated with that function.
- In these cases iTIP supports the notion of one CU acting on behalf of
- another. Using the "sent-by" parameter, a calendar user could send an
- updated "VEVENT" REQUEST. In the case where one CU sends on behalf of
- another CU, the "Attendee" responses are still directed back towards
- the CU designated as "Organizer".
-
-3.2.2.6 Forwarding to An Uninvited CU
-
- An "Attendee" invited to an event may invite another uninvited CU to
- the event. The invited "Attendee" accomplishes this by forwarding the
- original "REQUEST" method to the uninvited CU. The "Organizer"
- decides whether or not the uninvited CU is added to the attendee
-
-
-
-Silverberg, et. al. Standards Track [Page 20]
-
-RFC 2446 iTIP November 1998
-
-
- list. If the "Organizer" decides not to add the uninvited CU no
- further action is required, however the "Organizer" MAY send the
- uninvited CU a "CANCEL" message. If the "Organizer" decides to add
- an uninvited CU, a new "ATTENDEE" property is added for the uninvited
- CU with its property parameters set as the "Organizer" deems
- appropriate. When forwarding a "REQUEST" to another CU, the
- forwarding "Attendee" MUST NOT make changes to the VEVENT property
- set.
-
-3.2.2.7 Updating Attendee Status
-
- The "Organizer" of an event may also request updated status from one
- or more "Attendees. The "Organizer" sends a "REQUEST" method to the
- "Attendee" and sets the "ATTENDEE;RSVP=TRUE" property parameter. The
- "SEQUENCE" property for the event is not changed from its previous
- value. A recipient will determine that the only change in the
- "REQUEST" is that their "RSVP" property parameter indicates a request
- for updated status. The recipient SHOULD respond with a "REPLY"
- method indicating their current status with respect to the "REQUEST".
-
-3.2.3 REPLY
-
- The "REPLY" method in a "VEVENT" calendar component is used to
- respond (e.g., accept or decline) to a "REQUEST" or to reply to a
- delegation "REQUEST". When used to provide a delegation response, the
- "Delegator" SHOULD include the calendar address of the "Delegate" on
- the "delegated-to" property parameter of the "Delegator's" "ATTENDEE"
- property. The "Delegate" SHOULD include the calendar address of the
- "Delegator" on the "delegated-from" property parameter of the
- "Delegate's" "ATTENDEE" property.
-
- The "REPLY" method may also be used to respond to an unsuccessful
- "REQUEST" method. Depending on the value of the "REQUEST-STATUS"
- property no scheduling action may have been performed.
-
- The "Organizer" of an event may receive the "REPLY" method from a CU
- not in the original "REQUEST". For example, a "REPLY" may be received
- from a "Delegate" to an event. In addition, the "REPLY" method may be
- received from an unknown CU (a "Party Crasher"). This uninvited
- "Attendee" may be accepted, or the "Organizer" may cancel the event
- for the uninvited "Attendee" by sending a "CANCEL" method to the
- uninvited "Attendee".
-
- An "Attendee" can include a message to the "Organizer" using the
- "COMMENT" property. For example, if the user indicates tentative
- acceptance and wants to let the "Organizer" know why, the reason can
- be expressed in the "COMMENT" property value.
-
-
-
-
-Silverberg, et. al. Standards Track [Page 21]
-
-RFC 2446 iTIP November 1998
-
-
- The "Organizer" may also receive a "REPLY" from one CU on behalf of
- another. Like the scenario enumerated above for the "Organizer",
- "Attendees" may have another CU respond on their behalf. This is done
- using the "sent-by" parameter.
-
- The optional properties listed in the table below (those listed as
- "0+" or "0 or 1") MUST NOT be changed from those of the original
- request. If property changes are desired the COUNTER message must be
- used.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "REPLY"
-VEVENT 1+ All components MUST have the same UID
- ATTENDEE 1 MUST be the address of the Attendee
- replying.
- DTSTAMP 1
- ORGANIZER 1
- RECURRENCE-ID 0 or 1 only if referring to an instance of a
- recurring calendar component. Otherwise
- it must NOT be present.
- UID 1 MUST be the UID of the original REQUEST
-
- SEQUENCE 0 or 1 MUST if non-zero, MUST be the sequence
- number of the original REQUEST. MAY be
- present if 0.
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DTSTART 0 or 1
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RELATED-TO 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 22]
-
-RFC 2446 iTIP November 1998
-
-
- RESOURCES 0 or 1 This property MAY contain a list of values
- REQUEST-STATUS 0+
- RRULE 0+
- STATUS 0 or 1
- SUMMARY 0 or 1
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
-VTIMEZONE 0 or 1 MUST be present if any date/time refers
- to a timezone
-X-COMPONENT 0+
-
-VALARM 0
-VFREEBUSY 0
-VJOURNAL 0
-VTODO 0
-
-3.2.4 ADD
-
- The "ADD" method in a "VEVENT" calendar component is used to add one
- or more instances to an existing "VEVENT". Unlike the "REQUEST"
- method, when using issuing an "ADD" method, the "Organizer" does not
- send the full "VEVENT" description; only the new instance(s). The
- "ADD" method is especially useful if there are instance-specific
- properties to be preserved in a recurring "VEVENT". For instance, an
- "Organizer" may have originally scheduled a weekly Thursday meeting.
- At some point, several instances changed. Location or start time may
- have changed, or some instances may have unique "DESCRIPTION"
- properties. The "ADD" method allows the "Organizer" to add new
- instances to an existing event using a single ITIP message without
- redefining the entire recurring pattern.
-
- The "UID" must be that of the existing event. If the "UID" property
- value in the "ADD" is not found on the recipient's calendar, then the
- recipient SHOULD send a "REFRESH" to the "Organizer" in order to be
- updated with the latest version of the "VEVENT". If an "Attendee"
- implementation does not support the "ADD" method it should respond
- with a "REQUEST-STATUS" value of 3.14 and ask for a "REFRESH".
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 23]
-
-RFC 2446 iTIP November 1998
-
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "ADD"
-VEVENT 1
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- SEQUENCE 1 MUST be greater than 0
- SUMMARY 1 Can be null
- UID 1 MUST match that of the original event
-
- ATTACH 0+
- ATTENDEE 0+
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RELATED-TO 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0+
- STATUS 0 or 1 MAY be one of TENTATIVE/CONFIRMED
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
- RECURRENCE-ID 0
- REQUEST-STATUS 0
-
-VALARM 0+
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VFREEBUSY 0
-VTODO 0
-VJOURNAL 0
-
-
-
-
-Silverberg, et. al. Standards Track [Page 24]
-
-RFC 2446 iTIP November 1998
-
-
-3.2.5 CANCEL
-
- The "CANCEL" method in a "VEVENT" calendar component is used to send
- a cancellation notice of an existing event request to the
- "Attendees". The message is sent by the "Organizer" of the event. For
- a recurring event, either the whole event or instances of an event
- may be cancelled. To cancel the complete range of recurring event,
- the "UID" property value for the event MUST be specified and a
- "RECURRENCE-ID" MUST NOT be specified in the "CANCEL" method. In
- order to cancel an individual instance of the event, the
- "RECURRENCE-ID" property value for the event MUST be specified in the
- "CANCEL" method.
-
- There are two options for canceling a sequence of instances of a
- recurring "VEVENT" calendar component:
-
- (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
- be specified with the "RANGE" property parameter value of
- THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
- specified "VEVENT" calendar component and all instances before
- (or after); or
-
- (b) individual recurrence instances may be cancelled by specifying
- multiple "RECURRENCE-ID" properties corresponding to the
- instances to be cancelled.
-
- When a "VEVENT" is cancelled, the "SEQUENCE" property value MUST be
- incremented.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "CANCEL"
-
-VEVENT 1+ All must have the same UID
- ATTENDEE 0+ MUST include all "Attendees" being removed
- the event. MUST include all "Attendees" if
- the entire event is cancelled.
- DTSTAMP 1
- ORGANIZER 1
- SEQUENCE 1
- UID 1 MUST be the UID of the original REQUEST
-
- COMMENT 0 or 1
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
-
-
-
-Silverberg, et. al. Standards Track [Page 25]
-
-RFC 2446 iTIP November 1998
-
-
- CLASS 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DTSTART 0 or 1
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST be present if referring to one or
- more or more recurring instances.
- Otherwise it MUST NOT be present
- RELATED-TO 0+
- RESOURCES 0 or 1
- RRULE 0+
- STATUS 0 or 1 MUST be set to CANCELLED. If uninviting
- specific "Attendees" then MUST NOT be
- included.
- SUMMARY 0 or 1
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
- REQUEST-STATUS 0
-
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VTODO 0
-VJOURNAL 0
-VFREEBUSY 0
-VALARM 0
-
-3.2.6 REFRESH
-
- The "REFRESH" method in a "VEVENT" calendar component is used by
- "Attendees" of an existing event to request an updated description
- from the event "Organizer". The "REFRESH" method must specify the
- "UID" property of the event to update. A recurrence instance of an
- event may be requested by specifying the "RECURRENCE-ID" property
- corresponding to the associated event. The "Organizer" responds with
- the latest description and version of the event.
-
-
-
-
-Silverberg, et. al. Standards Track [Page 26]
-
-RFC 2446 iTIP November 1998
-
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "REFRESH"
-
-VEVENT 1
- ATTENDEE 1 MUST be the address of requestor
- DTSTAMP 1
- ORGANIZER 1
- UID 1 MUST be the UID associated with original
- REQUEST
- COMMENT 0 or 1
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- recurring calendar component. Otherwise
- it must NOT be present.
- X-PROPERTY 0+
-
- ATTACH 0
- CATEGORIES 0
- CLASS 0
- CONTACT 0
- CREATED 0
- DESCRIPTION 0
- DTEND 0
- DTSTART 0
- DURATION 0
- EXDATE 0
- EXRULE 0
- GEO 0
- LAST-MODIFIED 0
- LOCATION 0
- PRIORITY 0
- RDATE 0
- RELATED-TO 0
- REQUEST-STATUS 0
- RESOURCES 0
- RRULE 0
- SEQUENCE 0
- STATUS 0
- SUMMARY 0
- TRANSP 0
- URL 0
-
-X-COMPONENT 0+
-
-VTODO 0
-
-
-
-Silverberg, et. al. Standards Track [Page 27]
-
-RFC 2446 iTIP November 1998
-
-
-VJOURNAL 0
-VFREEBUSY 0
-VTIMEZONE 0
-VALARM 0
-
-3.2.7 COUNTER
-
- The "COUNTER" method for a "VEVENT" calendar component is used by an
- "Attendee" of an existing event to submit to the "Organizer" a
- counter proposal to the event description. The "Attendee" sends this
- message to the "Organizer" of the event.
-
- The counter proposal is an iCalendar object consisting of a VEVENT
- calendar component describing the complete description of the
- alternate event.
-
- The "Organizer" rejects the counter proposal by sending the
- "Attendee" a VEVENT "DECLINECOUNTER" method. The "Organizer" accepts
- the counter proposal by rescheduling the event as described in
- section 3.2.2.1 Rescheduling an Event.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "COUNTER"
-
-VEVENT 1
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1 MUST be the "Organizer" of the original
- event
- SEQUENCE 1 MUST be present if value is greater than 0,
- MAY be present if 0
- SUMMARY 1 Can be null
- UID 1 MUST be the UID associated with the REQUEST
- being countered
-
- ATTACH 0+
- ATTENDEE 0+ Can also be used to propose other
- "Attendees"
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
-
-
-
-Silverberg, et. al. Standards Track [Page 28]
-
-RFC 2446 iTIP November 1998
-
-
- DTEND 0 or 1 if present DURATION MUST NOT be present
- DURATION 0 or 1 if present DTEND MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- recurring calendar component. Otherwise it
- MUST NOT be present.
- RELATED-TO 0+
- REQUEST-STATUS 0+
- RESOURCES 0 or 1 This property may contain a list of values
- RRULE 0+
- STATUS 0 or 1 Value must be one of CONFIRMED/TENATIVE/
- CANCELLED
- TRANSP 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
-VALARM 0+
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VTODO 0
-VJOURNAL 0
-VFREEBUSY 0
-
-3.2.8 DECLINECOUNTER
-
- The "DECLINECOUNTER" method in a "VEVENT" calendar component is used
- by the "Organizer" of an event to reject a counter proposal submitted
- by an "Attendee". The "Organizer" must send the "DECLINECOUNTER"
- message to the "Attendee" that sent the "COUNTER" method to the
- "Organizer".
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 29]
-
-RFC 2446 iTIP November 1998
-
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "DECLINECOUNTER"
-
-VEVENT 1
- DTSTAMP 1
- ORGANIZER 1
- UID 1 MUST, same UID specified in original
- REQUEST and subsequent COUNTER
- COMMENT 0 or 1
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- recurring calendar component. Otherwise it
- MUST NOT be present.
- REQUEST-STATUS 0+
- SEQUENCE 0 OR 1 MUST be present if value is greater than 0,
- MAY be present if 0
- X-PROPERTY 0+
- ATTACH 0
- ATTENDEE 0
- CATEGORIES 0
- CLASS 0
- CONTACT 0
- CREATED 0
- DESCRIPTION 0
- DTEND 0
- DTSTART 0
- DURATION 0
- EXDATE 0
- EXRULE 0
- GEO 0
- LAST-MODIFIED 0
- LOCATION 0
- PRIORITY 0
- RDATE 0
- RELATED-TO 0
- RESOURCES 0
- RRULE 0
- STATUS 0
- SUMMARY 0
- TRANSP 0
- URL 0
-
-X-COMPONENT 0+
-VTODO 0
-VJOURNAL 0
-VFREEBUSY 0
-VTIMEZONE 0
-VALARM 0
-
-
-
-Silverberg, et. al. Standards Track [Page 30]
-
-RFC 2446 iTIP November 1998
-
-
-3.3 Methods For VFREEBUSY Components
-
- This section defines the property set for the methods that are
- applicable to the "VFREEBUSY" calendar component. Each of the methods
- is defined using a restriction table.
-
- This document only addresses the transfer of busy time information.
- Applications desiring free time information MUST infer this from
- available busy time information.
-
- The busy time information within the iCalendar object MAY be grouped
- into more than one "VFREEBUSY" calendar component. This capability
- allows busy time periods to be grouped according to some common
- periodicity, such as a calendar week, month, or year. In this case,
- each "VFREEBUSY" calendar component MUST include the "ATTENDEE",
- "DTSTART" and "DTEND" properties in order to specify the source of
- the busy time information and the date and time interval over which
- the busy time information covers.
-
- The "FREEBUSY" property value MAY include a list of values, separated
- by the COMMA character ([US-ASCII] decimal 44). Alternately, multiple
- busy time periods MAY be specified with multiple instances of the
- "FREEBUSY" property. Both forms MUST be supported by implementations
- conforming to this document. Duplicate busy time periods SHOULD NOT
- be specified in an iCalendar object. However, two different busy time
- periods MAY overlap.
-
- "FREEBUSY" properties should be sorted such that their values are in
- ascending order, based on the start time, and then the end time, with
- the earliest periods first. For example, today's busy time
- information should appear after yesterday's busy time information.
- And the busy time for this half-hour should appear after the busy
- time for earlier today.
-
- Since events may span a day boundary, free busy time period may also
- span a day boundary. Individual "A" requests busy time from
- individuals "B", "C" and "D". Individual "B" and "C" replies with
- busy time data to individual "A". Individual "D" does not support
- busy time requests and does not reply with any data. If the transport
- binding supports exception messages, then individual "D" returns an
- "unsupported capability" message to individual "A4.34.3".
-
- The following summarizes the methods that are defined for the
- "VFREEBUSY" calendar component.
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 31]
-
-RFC 2446 iTIP November 1998
-
-
- |================|==================================================|
- | Method | Description |
- |================|==================================================|
- | PUBLISH | Publish unsolicited busy time data. |
- | REQUEST | Request busy time data. |
- | REPLY | Reply to a busy time request. |
- |================|==================================================|
-
-3.3.1 PUBLISH
-
- The "PUBLISH" method in a "VFREEBUSY" calendar component is used to
- publish busy time data. The method may be sent from one CU to any
- other. The purpose of the method is to provide a message for sending
- unsolicited busy time data. That is, the busy time data is not being
- sent as a "REPLY" to the receipt of a "REQUEST" method.
-
- The "ATTENDEE" property must be specified in the busy time
- information. The value is the CU address of the originator of the
- busy time information.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "PUBLISH"
-
-VFREEBUSY 1+
- DTSTAMP 1
- DTSTART 1 DateTime values must be in UTC
- DTEND 1 DateTime values must be in UTC
- FREEBUSY 1+ MUST be BUSYTIME. Multiple instances are
- allowed. Multiple instances must be sorted
- in ascending order
- ORGANIZER 1 MUST contain the address of originator of
- busy time data.
-
- COMMENT 0 or 1
- CONTACT 0+
- X-PROPERTY 0+
- URL 0 or 1 Specifies busy time URL
-
- ATTENDEE 0
- DURATION 0
- REQUEST-STATUS 0
- UID 0
-
-X-COMPONENT 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 32]
-
-RFC 2446 iTIP November 1998
-
-
-VEVENT 0
-VTODO 0
-VJOURNAL 0
-VTIMEZONE 0
-VALARM 0
-
-3.3.2 REQUEST
-
- The "REQUEST" method in a "VFREEBUSY" calendar component is used to
- ask a "Calendar User" for their busy time information. The request
- may be for a busy time information bounded by a specific date and
- time interval.
-
- This message only permits requests for busy time information. The
- message is sent from a "Calendar User" requesting the busy time
- information to one or more intended recipients.
-
- If the originator of the "REQUEST" method is not authorized to make a
- busy time request on the recipient's calendar system, then an
- exception message SHOULD be returned in a "REPLY" method, but no busy
- time data need be returned.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "REQUEST"
-
-VFREEBUSY 1
- ATTENDEE 1+ contain the address of the calendar store
- DTEND 1 DateTime values must be in UTC
- DTSTAMP 1
- DTSTART 1 DateTime values must be in UTC
- ORGANIZER 1 MUST be the request originator's address
- UID 1
- COMMENT 0 or 1
- CONTACT 0+
- X-PROPERTY 0+
-
- FREEBUSY 0
- DURATION 0
- REQUEST-STATUS 0
- URL 0
-
-X-COMPONENT 0+
-VALARM 0
-VEVENT 0
-
-
-
-Silverberg, et. al. Standards Track [Page 33]
-
-RFC 2446 iTIP November 1998
-
-
-VTODO 0
-VJOURNAL 0
-VTIMEZONE 0
-
-3.3.3 REPLY
-
- The "REPLY" method in a "VFREEBUSY" calendar component is used to
- respond to a busy time request. The method is sent by the recipient
- of a busy time request to the originator of the request.
-
- The "REPLY" method may also be used to respond to an unsuccessful
- "REQUEST" method. Depending on the "REQUEST-STATUS" value, no busy
- time information may be returned.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "REPLY"
-
-VFREEBUSY 1
- ATTENDEE 1 (address of recipient replying)
- DTSTAMP 1
- DTEND 1 DateTime values must be in UTC
- DTSTART 1 DateTime values must be in UTC
- FREEBUSY 1+ (values MUST all be of the same data
- type. Multiple instances are allowed.
- Multiple instances MUST be sorted in
- ascending order. Values MAY NOT overlap)
- ORGANIZER 1 MUST be the request originator's address
- UID 1
-
- COMMENT 0 or 1
- CONTACT 0+
- REQUEST-STATUS 0+
- URL 0 or 1 (specifies busy time URL)
- X-PROPERTY 0+
- DURATION 0
- SEQUENCE 0
-
-X-COMPONENT 0+
-VALARM 0
-VEVENT 0
-VTODO 0
-VJOURNAL 0
-VTIMEZONE 0
-
-
-
-
-Silverberg, et. al. Standards Track [Page 34]
-
-RFC 2446 iTIP November 1998
-
-
-3.4 Methods For VTODO Components
-
- This section defines the property set for the methods that are
- applicable to the "VTODO" calendar component. Each of the methods is
- defined using a restriction table that specifies the property
- constraints that define the particular method.
-
- The following summarizes the methods that are defined for the "VTODO"
- calendar component.
-
- +================+==================================================+
- | Method | Description |
- |================+==================================================|
- | PUBLISH | Post notification of a VTODO. Used primarily as |
- | | a method of advertising the existence of a VTODO.|
- | | |
- | REQUEST | Assign a VTODO. This is an explicit assignment to|
- | | one or more Calendar Users. The REQUEST method |
- | | is also used to update or change an existing |
- | | VTODO. Clients that cannot handle REQUEST MAY |
- | | degrade the method to treat it as a PUBLISH. |
- | | |
- | REPLY | Reply to a VTODO request. Attendees MAY set |
- | | PARTSTAT to ACCEPTED, DECLINED, TENTATIVE, |
- | | DELEGATED, PARTIAL, and COMPLETED. |
- | | |
- | ADD | Add one or more instances to an existing to-do. |
- | | |
- | CANCEL | Cancel one or more instances of an existing |
- | | to-do. |
- | | |
- | REFRESH | A request sent to a VTODO Organizer asking for |
- | | the latest version of a VTODO. |
- | | |
- | COUNTER | Counter a REQUEST with an alternative proposal. |
- | | |
- | DECLINECOUNTER | Decline a counter proposal by an Attendee. |
- +================+==================================================+
-
-3.4.1 PUBLISH
-
- The "PUBLISH" method in a "VTODO" calendar component has no
- associated response. It is simply a posting of an iCalendar object
- that maybe added to a calendar. It MUST have an "Organizer". It MUST
- NOT have "Attendees". Its expected usage is for encapsulating an
- arbitrary "VTODO" calendar component as an iCalendar object. The
- "Organizer" MAY subsequently update (with another "PUBLISH" method),
- add instances to (with an "ADD" method), or cancel (with a "CANCEL"
-
-
-
-Silverberg, et. al. Standards Track [Page 35]
-
-RFC 2446 iTIP November 1998
-
-
- method) a previously published "VTODO" calendar component.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "PUBLISH"
-VTODO 1+
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- PRIORITY 1
- SEQUENCE 0 or 1 MUST be present if value is greater than
- 0, MAY be present if 0
- SUMMARY 1 Can be null.
- UID 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- recurring calendar component. Otherwise
- it MUST NOT be present.
-
- RELATED-TO 0+
- RESOURCES 0 or 1 This property may contain a list of values
- RRULE 0+
-STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
- PROCESS/CANCELLED
- URL 0 or 1
- X-PROPERTY 0+
-
- ATTENDEE 0
- REQUEST-STATUS 0
-
-
-
-Silverberg, et. al. Standards Track [Page 36]
-
-RFC 2446 iTIP November 1998
-
-
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-VALARM 0+
-X-COMPONENT 0+
-
-VFREEBUSY 0
-VEVENT 0
-VJOURNAL 0
-
-3.4.2 REQUEST
-
- The "REQUEST" method in a "VTODO" calendar component provides the
- following scheduling functions:
-
- . Assign a to-do to one or more "Calendar Users";
- . Reschedule an existing to-do;
- . Update the details of an existing to-do, without rescheduling
- it;
- . Update the completion status of "Attendees" of an existing
- to-do, without rescheduling it;
- . Reconfirm an existing to-do, without rescheduling it;
- . Delegate/reassign an existing to-do to another "Calendar User".
-
- The assigned "Calendar Users" are identified in the "VTODO" calendar
- component by individual "ATTENDEE;ROLE=REQ-PARTICIPANT" property
- value sequences.
-
- The originator of a "REQUEST" is the "Organizer" of the to-do. The
- recipient of a "REQUEST" is the "Calendar User" assigned the to-do.
- The "Attendee" uses the "REPLY" method to convey their acceptance and
- completion status to the "Organizer" of the "REQUEST".
-
- The "UID", "SEQUENCE", and "DTSTAMP" properties are used to
- distinguish the various uses of the "REQUEST" method. If the "UID"
- property value in the "REQUEST" is not found on the recipient's
- calendar, then the "REQUEST" is for a new to-do. If the "UID"
- property value is found on the recipient's calendar, then the
- "REQUEST" is a rescheduling, an update, or a reconfirm of the "VTODO"
- calendar object.
-
- If the "Organizer" of the "REQUEST" method is not authorized to make
- a to-do request on the "Attendee's" calendar system, then an
- exception is returned in the "REQUEST-STATUS" property of a
- subsequent "REPLY" method, but no scheduling action is performed.
-
- For the "REQUEST" method, multiple "VTODO" components in a single
- iCalendar object are only permitted when for components with the same
- "UID" property. That is, a series of recurring events may have
-
-
-
-Silverberg, et. al. Standards Track [Page 37]
-
-RFC 2446 iTIP November 1998
-
-
- instance-specific information. In this case, multiple "VTODO"
- components are needed to express the entire series.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "REQUEST"
-VTODO 1+ All components must have the same UID
- ATTENDEE 1+
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- PRIORITY 1
- SEQUENCE 0 or 1 MUST be present if value is greater than
- 0, MAY be present if 0
- SUMMARY 1 Can be null.
- UID 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of
- values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 present if referring to an instance of a
- recurring calendar component. Otherwise
- it MUST NOT be present.
- RELATED-TO 0+
- RESOURCES 0 or 1 This property may contain a list of
- values
- RRULE 0+
- STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
- PROCESS
- URL 0 or 1
- X-PROPERTY 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 38]
-
-RFC 2446 iTIP November 1998
-
-
- REQUEST-STATUS 0
-
-VALARM 0+
-
-VTIMEZONE 0+ MUST be present if any date/time refers
- to a timezone
-X-COMPONENT 0+
-
-VEVENT 0
-VFREEBUSY 0
-VJOURNAL 0
-
-3.4.2.1 REQUEST for Rescheduling a VTODO
-
- The "REQUEST" method may be used to reschedule a "VTODO" calendar
- component.
-
- Rescheduling a "VTODO" calendar component involves a change to the
- existing "VTODO" calendar component in terms of its start or due time
- or recurrence intervals and possibly the description. If the
- recipient CUA of a "REQUEST" method finds that the "UID" property
- value already exists on the calendar, but that the "SEQUENCE"
- property value in the "REQUEST" is greater than the value for the
- existing VTODO, then the "REQUEST" method describes a rescheduling of
- the "VTODO" calendar component.
-
-3.4.2.2 REQUEST for Update or Reconfirmation of a VTODO
-
- The "REQUEST" method may be used to update or reconfirm a "VTODO"
- calendar component. Reconfirmation is merely an update of "Attendee"
- completion status or overall "VTODO" calendar component status.
-
- An update to an existing "VTODO" calendar component does not involve
- changes to the start or due time or recurrence intervals, nor
- generally to the description for the "VTODO" calendar component. If
- the recipient CUA of a "REQUEST" method finds that the "UID" property
- value already exists on the calendar and that the "SEQUENCE" property
- value in the "REQUEST" is the same as the value for the existing
- event, then the "REQUEST" method describes an update of the "VTODO"
- calendar component details, but not a rescheduling of the "VTODO"
- calendar component.
-
- The update "REQUEST" is the appropriate response to a "REFRESH"
- method sent from an "Attendee" to the "Organizer" of a "VTODO"
- calendar component.
-
- Unsolicited "REQUEST" methods MAY be sent by the "Organizer" of a
- "VTODO" calendar component. The unsolicited "REQUEST" methods are
-
-
-
-Silverberg, et. al. Standards Track [Page 39]
-
-RFC 2446 iTIP November 1998
-
-
- used to update the details of the "VTODO" (without rescheduling it or
- updating the completion status of "Attendees") or the "VTODO"
- calendar component itself (i.e., reconfirm the "VTODO").
-
-3.4.2.3 REQUEST for Delegating a VTODO
-
- The "REQUEST" method is also used to delegate or reassign ownership
- of a "VTODO" calendar component to another "Calendar User". For
- example, it may be used to delegate an "Attendee's" role (i.e.
- "chair", or "participant") for a "VTODO" calendar component. The
- "REQUEST" method is sent by one of the "Attendees" of an existing
-
- "VTODO" calendar component to some other individual. An "Attendee" of
- a "VTODO" calendar component MUST NOT delegate to the "Organizer" of
- the event.
-
- For the purposes of this description, the "Attendee" delegating the
- "VTODO" calendar component is referred to as the "Delegator". The
- "Attendee" receiving the delegation request is referred to as the
- "Delegate".
-
- The "Delegator" of a "VTODO" calendar component MUST forward the
- existing "REQUEST" method for a "VTODO" calendar component to the
- "Delegate". The "VTODO" calendar component description MUST include
- the "Delegator's" up-to-date "VTODO" calendar component definition.
- The "REQUEST" method MUST also include an "ATTENDEE" property with
- the calendar address of the "Delegate". The "Delegator" MUST also
- send a "REPLY" method back to the "Organizer" with the "Delegator's"
- "Attendee" property "partstat" parameter value set to "DELEGATED". In
- addition, the "delegated-to" parameter MUST be included with the
- calendar address of the "Delegate". A response to the delegation
- "REQUEST" is sent from the "Delegate" to the "Organizer" and
- optionally, to the "Delegator". The "REPLY" method from the
- "Delegate" SHOULD include the "ATTENDEE" property with their calendar
- address and the "delegated-from" parameter with the value of the
- "Delegator's" calendar address.
-
- The delegation "REQUEST" method MUST assign a value for the "RSVP"
- property parameter associated with the "Delegator's" "Attendee"
- property to that of the "Delegate's" "ATTENDEE" property. For example
- if the "Delegator's" "ATTENDEE" property specifies "RSVP=TRUE", then
- the "Delegate's" "ATTENDEE" property MUST specify "RSVP=TRUE".
-
-3.4.2.4 REQUEST Forwarded To An Uninvited Calendar User
-
- An "Attendee" assigned a "VTODO" calendar component may send the
- "VTODO" calendar component to another new CU, not previously
- associated with the "VTODO" calendar component. The current
-
-
-
-Silverberg, et. al. Standards Track [Page 40]
-
-RFC 2446 iTIP November 1998
-
-
- "Attendee" assigned the "VTODO" calendar component does this by
- forwarding the original "REQUEST" method to the new CU. The new CU
- can send a "REPLY" to the "Organizer" of the "VTODO" calendar
- component. The reply contains an "ATTENDEE" property for the new CU.
-
- The "Organizer" ultimately decides whether or not the new CU becomes
- part of the to-do and is not obligated to do anything with a "REPLY"
- from a new (uninvited) CU. If the "Organizer" does not want the new
- CU to be part of the to-do, the new "ATTENDEE" property is not added
- to the "VTODO" calendar component. The "Organizer" MAY send the CU a
- "CANCEL" message to indicate that they will not be added to the to-
- do. If the "Organizer" decides to add the new CU, the new "ATTENDEE"
- property is added to the "VTODO" calendar component. Furthermore, the
- "Organizer" is free to change any "ATTENDEE" property parameter from
- the values supplied by the new CU to something the "Organizer"
- considers appropriate.
-
-3.4.2.5 REQUEST Updated Attendee Status
-
- An "Organizer" of a "VTODO" may request an updated status from one or
- more "Attendees". The "Organizer" sends a "REQUEST" method to the
- "Attendee" with the "ATTENDEE;RSVP=TRUE" property sequence. The
- "SEQUENCE" property for the "VTODO" is not changed from its previous
- value. A recipient determines that the only change in the "REQUEST"
- is that their "RSVP" property parameter indicates a request for an
- updated status. The recipient SHOULD respond with a "REPLY" method
- indicating their current status with respect to the "REQUEST".
-
-3.4.3 REPLY
-
- The "REPLY" method in a "VTODO" calendar component is used to respond
- (e.g., accept or decline) to a request or to reply to a delegation
- request. It is also used by an "Attendee" to update their completion
- status. When used to provide a delegation response, the "Delegator"
- MUST include the calendar address of the "Delegate" in the
- "delegated-to" parameter of the "Delegator's" "ATTENDEE" property.
- The "Delegate" MUST include the calendar address of the "Delegator"
- on the "delegated-from" parameter of the "Delegate's" "ATTENDEE"
- property.
-
- The "REPLY" method MAY also be used to respond to an unsuccessful
- "VTODO" calendar component "REQUEST" method. Depending on the
- "REQUEST-STATUS" value, no scheduling action may have been performed.
-
- The "Organizer" of a "VTODO" calendar component MAY receive a "REPLY"
- method from a "Calendar User" not in the original "REQUEST". For
- example, a "REPLY" method MAY be received from a "Delegate" of a
- "VTODO" calendar component. In addition, the "REPLY" method MAY be
-
-
-
-Silverberg, et. al. Standards Track [Page 41]
-
-RFC 2446 iTIP November 1998
-
-
- received from an unknown "Calendar User", having been forwarded the
- "REQUEST" by an original "Attendee" of the "VTODO" calendar
- component. This uninvited "Attendee" MAY be accepted, or the
- "Organizer" MAY cancel the "VTODO" calendar component for the
- uninvited "Attendee" by sending them a "CANCEL" method.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ---------------------------------------------
-METHOD 1 MUST be "REPLY"
-VTODO 1+ All component MUST have the same UID
- ATTENDEE 1+
- DTSTAMP 1
- ORGANIZER 1
- REQUEST-STATUS 1+
- UID 1 MUST must be the address of the replying
- attendee
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTSTART 0 or 1
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RELATED-TO 0+
- RESOURCES 0 or 1 This property may contain a list of values
- RRULE 0+
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- Recurring calendar component. Otherwise it
- MUST NOT be present
- SEQUENCE 0 or 1 MUST be the sequence number of
- the original REQUEST if greater than 0.
- MAY be present if 0.
- STATUS 0 or 1
-
-
-
-Silverberg, et. al. Standards Track [Page 42]
-
-RFC 2446 iTIP November 1998
-
-
- SUMMARY 0 or 1 Can be null
- URL 0 or 1
- X-PROPERTY 0+
-
-VTIMEZONE 0 or 1 MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VALARM 0
-VEVENT 0
-VFREEBUSY 0
-
-3.4.4 ADD
-
- The "ADD" method in a "VTODO" calendar component is used to add one
- or more instances to an existing to-do.
-
- If the "UID" property value in the "ADD" is not found on the
- recipient's calendar, then the recipient SHOULD send a "REFRESH" to
- the "Organizer" in order to be updated with the latest version of the
- "VTODO". If an "Attendee" implementation does not support the "ADD"
- method it should respond with a "REQUEST-STATUS" value of 5.3 and ask
- for a "REFRESH".
-
- The "SEQUENCE" property value is incremented as the sequence of to-
- dos has changed.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "ADD"
-VTODO 1
- DTSTAMP 1
- ORGANIZER 1
- PRIORITY 1
- SEQUENCE 1 MUST be greater than 0
- SUMMARY 1 Can be null.
- UID 1 MUST match that of the original to-do
-
- ATTACH 0+
- ATTENDEE 0+
- CATEGORIES 0 or 1 This property may contain a list of
- values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 43]
-
-RFC 2446 iTIP November 1998
-
-
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DTSTART 0 or 1
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- RDATE 0+
- RELATED-TO 0+
- RESOURCES 0 or 1 This property may contain a list of
- values
- RRULE 0+
- STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
- PROCESS
- URL 0 or 1
- X-PROPERTY 0+
-
- RECURRENCE-ID 0
- REQUEST-STATUS 0
-
-VALARM 0+
-VTIMEZONE 0+ MUST be present if any date/time refers
- to a timezone
-X-COMPONENT 0+
-
-VEVENT 0
-VJOURNAL 0
-VFREEBUSY 0
-
-3.4.5 CANCEL
-
- The "CANCEL" method in a "VTODO" calendar component is used to send a
- cancellation notice of an existing "VTODO" calendar request to the
- "Attendees". The message is sent by the "Organizer" of a "VTODO"
- calendar component to the "Attendees" of the "VTODO" calendar
- component. For a recurring "VTODO" calendar component, either the
- whole "VTODO" calendar component or instances of a "VTODO" calendar
- component may be cancelled. To cancel the complete range of a
- recurring "VTODO" calendar component, the "UID" property value for
- the "VTODO" calendar component MUST be specified and a "RECURRENCE-
- ID" MUST NOT be specified in the "CANCEL" method. In order to cancel
- an individual instance of a recurring "VTODO" calendar component, the
- "RECURRENCE-ID" property value for the "VTODO" calendar component
- MUST be specified in the "CANCEL" method.
-
-
-
-Silverberg, et. al. Standards Track [Page 44]
-
-RFC 2446 iTIP November 1998
-
-
- There are two options for canceling a sequence of instances of a
- recurring "VTODO" calendar component:
-
- (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
- be specified with the "RANGE" property parameter value of
- THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
- specified "VTODO" calendar component and all instances before (or
- after); or
-
- (b) individual recurrence instances may be cancelled by specifying
- multiple "RECURRENCE-ID" properties corresponding to the
- instances to be cancelled.
-
- When a "VTODO" is cancelled, the "SEQUENCE" property value MUST be
- incremented.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ---------------------------------------------
-METHOD 1 MUST be "CANCEL"
-VTODO 1
- ATTENDEE 0+ include all "Attendees" being removed from
- the todo. MUST include all "Attendees" if
- the entire todo is cancelled.
- UID 1 MUST echo original UID
- DTSTAMP 1
- ORGANIZER 1
- SEQUENCE 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTSTART 0 or 1
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- RDATE 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 45]
-
-RFC 2446 iTIP November 1998
-
-
- RECURRENCE-ID 0 or 1 MUST only if referring to one or more
- instances of a recurring calendar
- component. Otherwise it MUST NOT be
- present.
- RELATED-TO 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0+
- PRIORITY 0 or 1
- STATUS 0 or 1 If present it MUST be set to "CANCELLED".
- MUST NOT be used if purpose is to remove
- "ATTENDEES" rather than cancel the entire
- VTODO.
- URL 0 or 1
- X-PROPERTY 0+
-
- REQUEST-STATUS 0
-
-VTIMEZONE 0 or 1 MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VALARM 0
-VEVENT 0
-VFREEBUSY 0
-
-3.4.6 REFRESH
-
- The "REFRESH" method in a "VTODO" calendar component is used by
- "Attendees" of an existing "VTODO" calendar component to request an
- updated description from the "Organizer" of the "VTODO" calendar
- component. The "Organizer" of the "VTODO" calendar component MAY use
- this method to request an updated status from the "Attendees". The
- "REFRESH" method MUST specify the "UID" property corresponding to the
- "VTODO" calendar component needing update.
-
- A refresh of a recurrence instance of a "VTODO" calendar component
- may be requested by specifying the "RECURRENCE-ID" property
- corresponding to the associated "VTODO" calendar component. The
- "Organizer" responds with the latest description and rendition of the
- "VTODO" calendar component. In most cases this will be a REQUEST
- unless the "VTODO" has been cancelled, in which case the ORGANIZER
- MUST send a "CANCEL". This method is intended to facilitate machine
- processing of requests for updates to a "VTODO" calendar component.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 46]
-
-RFC 2446 iTIP November 1998
-
-
-Component/Property Presence
-------------------- ---------------------------------------------
-METHOD 1 MUST be "REFRESH"
-VTODO 1
- ATTENDEE 1
- DTSTAMP 1
- UID 1 MUST echo original UID
-
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- Recurring calendar component. Otherwise it
- MUST NOT be present
- X-PROPERTY 0+
-
- ATTACH 0
- CATEGORIES 0
- CLASS 0
- COMMENT 0
- CONTACT 0
- CREATED 0
- DESCRIPTION 0
- DTSTART 0
- DUE 0
- DURATION 0
- EXDATE 0
- EXRULE 0
- GEO 0
- LAST-MODIFIED 0
- LOCATION 0
- ORGANIZER 0
- PERCENT-COMPLETE 0
- PRIORITY 0
- RDATE 0
- RELATED-TO 0
- REQUEST-STATUS 0
- RESOURCES 0
- RRULE 0
- SEQUENCE 0
- STATUS 0
- URL 0
-
-X-COMPONENT 0+
-
-VALARM 0
-VEVENT 0
-VFREEBUSY 0
-VTIMEZONE 0
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 47]
-
-RFC 2446 iTIP November 1998
-
-
-3.4.7 COUNTER
-
- The "COUNTER" method in a "VTODO" calendar component is used by an
- "Attendee" of an existing "VTODO" calendar component to submit to the
- "Organizer" a counter proposal for the "VTODO" calendar component.
- The "Attendee" sends the message to the "Organizer" of the "VTODO"
- calendar component.
-
- The counter proposal is an iCalendar object consisting of a "VTODO"
- calendar component describing the complete description of the
- alternate "VTODO" calendar component.
-
- The "Organizer" rejects the counter proposal by sending the
- "Attendee" a "DECLINECOUNTER" method. The "Organizer" accepts the
- counter proposal by sending all of the "Attendees" of the "VTODO"
- calendar component a "REQUEST" method rescheduling the "VTODO"
- calendar component. In the latter case, the "Organizer" SHOULD reset
- the individual "RSVP" property parameter values to TRUE on each
- "ATTENDEE" property; in order to force a response by the "Attendees".
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "COUNTER"
-VTODO 1
- ATTENDEE 1+
- DTSTAMP 1
- ORGANIZER 1
- PRIORITY 1
- SUMMARY 1 Can be null
- UID 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1 Can be null
- DTSTART 0 or 1
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
-
-
-
-Silverberg, et. al. Standards Track [Page 48]
-
-RFC 2446 iTIP November 1998
-
-
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST only 3.5if referring to an instance of a
- recurring calendar component. Otherwise it
- MUST NOT be present.
- RELATED-TO 0+
- REQUEST-STATUS 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0 or 1
- SEQUENCE 0 or 1 MUST echo the original SEQUENCE number.
- MUST be present if non-zero. MAY be present
- if zero.
- STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
- PROCESS/CANCELLED
- URL 0 or 1
- X-PROPERTY 0+
-
-
-VALARM 0+
-VTIMEZONE 0 or 1 MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VEVENT 0
-VFREEBUSY 0
-
-3.4.8 DECLINECOUNTER
-
- The "DECLINECOUNTER" method in a "VTODO" calendar component is used
- by an "Organizer" of "VTODO" calendar component to reject a counter
- proposal offered by one of the "Attendees". The "Organizer" sends the
- message to the "Attendee" that sent the "COUNTER" method to the
- "Organizer".
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ---------------------------------------------
-METHOD 1 MUST be "DECLINECOUNTER"
-
-VTODO 1
- ATTENDEE 1+ MUST for all attendees
- DTSTAMP 1
- ORGANIZER 1
- SEQUENCE 1 MUST echo the original SEQUENCE number
- UID 1 MUST echo original UID
-
-
-
-Silverberg, et. al. Standards Track [Page 49]
-
-RFC 2446 iTIP November 1998
-
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property may contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTSTART 0 or 1
- DUE 0 or 1 If present DURATION MUST NOT be present
- DURATION 0 or 1 If present DUE MUST NOT be present
- EXDATE 0+
- EXRULE 0+
- GEO 0 or 1
- LAST-MODIFIED 0 or 1
- LOCATION 0 or 1
- PERCENT-COMPLETE 0 or 1
- PRIORITY 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
- recurring calendar component. Otherwise
- it MUST NOT be present.
- RELATED-TO 0+
- REQUEST-STATUS 0+
- RESOURCES 0 or 1 This property MAY contain a list of values
- RRULE 0+
- STATUS 0 or 1 MAY be one of COMPLETED/NEEDS ACTION/IN-
- PROCESS
- URL 0 or 1
- X-PROPERTY 0+
-
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VALARM 0
-VEVENT 0
-VFREEBUSY 0
-
-3.5 Methods For VJOURNAL Components
-
- This section defines the property set for the methods that are
- applicable to the "VJOURNAL" calendar component.
-
- The following summarizes the methods that are defined for the
- "VJOURNAL" calendar component.
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 50]
-
-RFC 2446 iTIP November 1998
-
-
- +================+==================================================+
- | Method | Description |
- |================+==================================================|
- | PUBLISH | Post a journal entry. Used primarily as a method |
- | | of advertising the existence of a journal entry. |
- | | |
- | ADD | Add one or more instances to an existing journal |
- | | entry. |
- | | |
- | CANCEL | Cancel one or more instances of an existing |
- | | journal entry. |
- +================+==================================================+
-
-3.5.1 PUBLISH
-
- The "PUBLISH" method in a "VJOURNAL" calendar component has no
- associated response. It is simply a posting of an iCalendar object
- that may be added to a calendar. It MUST have an "Organizer". It MUST
- NOT have "Attendees". The expected usage is for encapsulating an
-
- arbitrary journal entry as an iCalendar object. The "Organizer" MAY
- subsequently update (with another "PUBLISH" method) or cancel (with a
- "CANCEL" method) a previously published journal entry.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "PUBLISH"
-VJOURNAL 1+
- DESCRIPTION 1 Can be null.
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- UID 1
-
- ATTACH 0+
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- EXDATE 0+
- EXRULE 0+
- LAST-MODIFIED 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 MUST only if referring to an instance of a
-
-
-
-Silverberg, et. al. Standards Track [Page 51]
-
-RFC 2446 iTIP November 1998
-
-
- recurring calendar component. Otherwise
- it MUST NOT be present.
- RELATED-TO 0+
- RRULE 0+
- SEQUENCE 0 or 1 MUST echo the original SEQUENCE number.
- MUST be present if non-zero. MAY be
- present if zero.
- STATUS 0 or 1 MAY be one of DRAFT/FINAL/CANCELLED
- SUMMARY 0 or 1 Can be null
- URL 0 or 1
- X-PROPERTY 0+
-
- ATTENDEE 0
-
-VALARM 0+
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VEVENT 0
-VFREEBUSY 0
-VTODO 0
-
-3.5.2 ADD
-
- The "ADD" method in a "VJOURNAL" calendar component is used to add
- one or more instances to an existing "VJOURNAL" entry. There is no
- response to the "Organizer".
-
- If the "UID" property value in the "ADD" is not found on the
- recipient's calendar, then the recipient MAY treat the "ADD" as a
- "PUBLISH".
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ----------------------------------------------
-METHOD 1 MUST be "ADD"
-VJOURNAL 1
- DESCRIPTION 1 Can be null.
- DTSTAMP 1
- DTSTART 1
- ORGANIZER 1
- SEQUENCE 1 MUST be greater than 0
- UID 1 MUST match that of the original journal
-
- ATTACH 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 52]
-
-RFC 2446 iTIP November 1998
-
-
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- EXDATE 0+
- EXRULE 0+
- LAST-MODIFIED 0 or 1
- RDATE 0+
- RELATED-TO 0+
- RRULE 0+
- STATUS 0 or 1 MAY be one of DRAFT/FINAL/CANCELLED
- SUMMARY 0 or 1 Can be null
- URL 0 or 1
- X-PROPERTY 0+
-
- ATTENDEE 0
- RECURRENCE-ID 0
-
-VALARM 0+
-VTIMEZONE 0 or 1 MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-
-VEVENT 0
-VFREEBUSY 0
-VTODO 0
-
-3.5.3 CANCEL
-
- The "CANCEL" method in a "VJOURNAL" calendar component is used to
- send a cancellation notice of an existing journal entry. The message
- is sent by the "Organizer" of a journal entry. For a recurring
- journal entry, either the whole journal entry or instances of a
- journal entry may be cancelled. To cancel the complete range of a
- recurring journal entry, the "UID" property value for the journal
- entry MUST be specified and a "RECURRENCE-ID" property MUST NOT be
- specified in the "CANCEL" method. In order to cancel an individual
- instance of the journal entry, the "RECURRENCE-ID" property value for
- the journal entry MUST be specified in the "CANCEL" method.
-
- There are two options for canceling a sequence of instances of a
- recurring "VJOURNAL" calendar component:
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 53]
-
-RFC 2446 iTIP November 1998
-
-
- (a) the "RECURRENCE-ID" property for an instance in the sequence MUST
- be specified with the "RANGE" property parameter value of
- THISANDPRIOR (or THISANDFUTURE) to indicate cancellation of the
- specified "VTODO" calendar component and all instances before (or
- after); or
-
- (b) individual recurrence instances may be cancelled by specifying
- multiple "RECURRENCE-ID" properties corresponding to the
- instances to be cancelled.
-
- When a "VJOURNAL" is cancelled, the "SEQUENCE" property value MUST be
- incremented.
-
- This method type is an iCalendar object that conforms to the
- following property constraints:
-
-Component/Property Presence
-------------------- ---------------------------------------------
-METHOD 1 MUST be "CANCEL"
-VJOURNAL 1+ All MUST have the same UID
- DTSTAMP 1
- ORGANIZER 1
- SEQUENCE 1
- UID 1 MUST be the UID of the original REQUEST
-
- ATTACH 0+
- ATTENDEE 0+
- CATEGORIES 0 or 1 This property MAY contain a list of values
- CLASS 0 or 1
- COMMENT 0 or 1
- CONTACT 0+
- CREATED 0 or 1
- DESCRIPTION 0 or 1
- DTSTART 0 or 1
- EXDATE 0+
- EXRULE 0+
- LAST-MODIFIED 0 or 1
- RDATE 0+
- RECURRENCE-ID 0 or 1 only if referring to an instance of a
- recurring calendar component. Otherwise
- it MUST NOT be present.
- RELATED-TO 0+
- RRULE 0+
- STATUS 0 or 1 MAY be present, must be "CANCELLED" if
- present
- SUMMARY 0 or 1
- URL 0 or 1
- X-PROPERTY 0+
-
-
-
-Silverberg, et. al. Standards Track [Page 54]
-
-RFC 2446 iTIP November 1998
-
-
- REQUEST-STATUS 0
-
-VTIMEZONE 0+ MUST be present if any date/time refers to
- a timezone
-X-COMPONENT 0+
-VALARM 0
-VEVENT 0
-VFREEBUSY 0
-VTODO 0
-
-3.6 Status Replies
-
- The "REQUEST-STATUS" property may include the following values:
-
-|==============+============================+=========================|
-| Short Return | Longer Return Status | Offending Data |
-| Status Code | Description | |
-|==============+============================+=========================|
-| 2.0 | Success. | None. |
-|==============+============================+=========================|
-| 2.1 | Success but fallback taken | Property name and value |
-| | on one or more property | MAY be specified. |
-| | values. | |
-|==============+============================+=========================|
-| 2.2 | Success, invalid property | Property name MAY be |
-| | ignored. | specified. |
-|==============+============================+=========================|
-| 2.3 | Success, invalid property | Property parameter name |
-| | parameter ignored. | and value MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 2.4 | Success, unknown non- | Non-standard property |
-| | standard property ignored. | name MAY be specified. |
-|==============+============================+=========================|
-| 2.5 | Success, unknown non | Property and non- |
-| | standard property value | standard value MAY be |
-| | ignored. | specified. |
-|==============+============================+=========================|
-| 2.6 | Success, invalid calendar | Calendar component |
-| | component ignored. | sentinel (e.g., BEGIN: |
-| | | ALARM) MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 2.7 | Success, request forwarded | Original and forwarded |
-| | to Calendar User. | caluser addresses MAY |
-| | | be specified. |
-|==============+============================+=========================|
-| 2.8 | Success, repeating event | RRULE or RDATE property |
-
-
-
-Silverberg, et. al. Standards Track [Page 55]
-
-RFC 2446 iTIP November 1998
-
-
-| | ignored. Scheduled as a | name and value MAY be |
-| | single component. | specified. |
-|==============+============================+=========================|
-| 2.9 | Success, truncated end date| DTEND property value |
-| | time to date boundary. | MAY be specified. |
-|==============+============================+=========================|
-| 2.10 | Success, repeating VTODO | RRULE or RDATE property |
-| | ignored. Scheduled as a | name and value MAY be |
-| | single VTODO. | specified. |
-|==============+============================+=========================|
-| 2.11 | Success, unbounded RRULE | RRULE property name and |
-| | clipped at some finite | value MAY be specified. |
-| | number of instances | Number of instances MAY |
-| | | also be specified. |
-|==============+============================+=========================|
-| 3.0 | Invalid property name. | Property name MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 3.1 | Invalid property value. | Property name and value |
-| | | MAY be specified. |
-|==============+============================+=========================|
-| 3.2 | Invalid property parameter.| Property parameter name |
-| | | and value MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 3.3 | Invalid property parameter | Property parameter name |
-| | value. | and value MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 3.4 | Invalid calendar component | Calendar component |
-| | sequence. | sentinel MAY be |
-| | | specified (e.g., BEGIN: |
-| | | VTIMEZONE). |
-|==============+============================+=========================|
-| 3.5 | Invalid date or time. | Date/time value(s) MAY |
-| | | be specified. |
-|==============+============================+=========================|
-| 3.6 | Invalid rule. | Rule value MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 3.7 | Invalid Calendar User. | Attendee property value |
-| | |MAY be specified. |
-|==============+============================+=========================|
-| 3.8 | No authority. | METHOD and Attendee |
-| | | property values MAY be |
-| | | specified. |
-|==============+============================+=========================|
-
-
-
-
-Silverberg, et. al. Standards Track [Page 56]
-
-RFC 2446 iTIP November 1998
-
-
-| 3.9 | Unsupported version. | VERSION property name |
-| | | and value MAY be |
-| | | specified. |
-|==============+============================+=========================|
-| 3.10 | Request entity too large. | None. |
-|==============+============================+=========================|
-| 3.11 | Required component or | Component or property |
-| | property missing. | name MAY be specified. |
-|==============+============================+=========================|
-| 3.12 | Unknown component or | Component or property |
-| | property found | name MAY be specified |
-|==============+============================+=========================|
-| 3.13 | Unsupported component or | Component or property |
-| | property found | name MAY be specified |
-|==============+============================+=========================|
-| 3.14 | Unsupported capability | Method or action MAY |
-| | | be specified |
-|==============+============================+=========================|
-| 4.0 | Event conflict. Date/time | DTSTART and DTEND |
-| | is busy. | property name and values|
-| | | MAY be specified. |
-|==============+============================+=========================|
-| 5.0 | Request MAY supported. | Method property value |
-| | | MAY be specified. |
-|==============+============================+=========================|
-| 5.1 | Service unavailable. | ATTENDEE property value |
-| | | MAY be specified. |
-|==============+============================+=========================|
-| 5.2 | Invalid calendar service. | ATTENDEE property value |
-| | | MAY be specified. |
-|==============+============================+=========================|
-| 5.3 | No scheduling support for | ATTENDEE property value |
-| | user. | MAY be specified. |
-|==============+============================+=========================|
-
-3.7 Implementation Considerations
-
-3.7.1 Working With Recurrence Instances
-
- iCalendar includes a recurrence grammar to represent recurring
- events. The benefit of such a grammar is the ability to represent a
- number of events in a single object. However, while this simplifies
- creation of a recurring event, meeting instances still need to be
- referenced. For instance, an "Attendee" may decline the third
- instance of a recurring Friday event. Similarly, the "Organizer" may
- change the time or location to a single instance of the recurring
- event.
-
-
-
-
-Silverberg, et. al. Standards Track [Page 57]
-
-RFC 2446 iTIP November 1998
-
-
- Since implementations may elect to store recurring events as either a
- single event object or a collection of discreet, related event
- objects, the protocol is designed so that each recurring instance may
- be both referenced and versioned. Hence, implementations that choose
- to maintain per-instance properties (such as "ATTENDEE" property
- "partstat" parameter) may do so. However, the protocol does not
- require per-instance recognition unless the instance itself must be
- renegotiated.
-
- The scenarios for recurrence instance referencing are listed below.
- For purposes of simplification a change to an event refers to a
- "trigger property." That is, a property that has a substantive
- effect on the meeting itself such as start time, location, due date
- (for "VTODO" calendar component components) and possibly description.
-
- "Organizer" initiated actions:
-
- . "Organizer" deletes or changes a single instance of a recurring
- event
- . "Organizer" makes changes that affect all future instances
- . "Organizer" makes changes that affect all previous instances
- . "Organizer" deletes or modifies a previously changed instance
-
- "Attendee" initiated actions:
-
- . "Attendee" changes status for a particular recurrence instance
- . "Attendee" sends Event-Counter for a particular recurrence
- instance
-
- An instance of a recurring event is assigned a unique identification,
- "RECURRENCE-ID" property, when that instance is renegotiated.
- Negotiation may be necessary when a substantive change to the event
- or to-do has be made (such as changing the start time, end time, due
- date or location). The "Organizer" can identify a specific recurrence
- instance using the "RECURRENCE-ID" property. The property value is
- equal to the date/time of the instance. If the "Organizer" wishes to
- change the "DTSTART", the original "DTSTART" value is used for
- "RECURRENCE-ID" property and the new "DTSTART" and "DTEND" values
- reflect the change. Note that after the change has occurred, the
- "RECURRENCE-ID" has changed to the new "DTSTART" value.
-
-3.7.2 Attendee Property Considerations
-
- The "ORGANIZER" property is required on published events, to-dos, and
- journal entries for two reasons. First, only the "Organizer" is
- allowed to update and redistribute an event or to-do component. It
- follows that the "ORGANIZER" property MUST be present in the event,
- to-do, or journal entry component so that the CUA has a basis for
-
-
-
-Silverberg, et. al. Standards Track [Page 58]
-
-RFC 2446 iTIP November 1998
-
-
- authorizing an update. Second, it is prudent to provide a point of
- contact for anyone who receives a published component in case of
- problems.
-
- There are valid [RFC-822] addresses that represent groups. Sending
- email to such an address results in mail being sent to multiple
- recipients. Such an address may be used as the value of an
- "ATTENDEE" property. Thus, it is possible that the recipient of a
- "REQUEST" does not appear explicitly in the list.
-
- It is recommended that the general approach to finding a "Calendar
- User" in an attendee list be as follows:
-
- 1. Search for the "Calendar User" in the attendee list where
- "TYPE=INDIVIDUAL"
-
- 2. Failing (1) look for attendees where "TYPE=GROUP" or
- 'TYPE=UNKNOWN". The CUA then determines if the "Calendar User"
- is a member of one of these groups. If so, the "REPLY" method
- sent to the "Organizer" MUST contain a new "ATTENDEE" property in
- which:
- . the "type" property parameter is set to INDIVIDUAL
- . the "member" property parameter is set to the name of the
- group
-
- 3. Failing (2) the CUA MAY ignore or accept the request as the
- "Calendar User" wishes.
-
-3.7.3 X-Tokens
-
- To make iCalendar objects extensible, new property types MAY be
- inserted into components. These properties are called X-Tokens as
- they are prefixed with "X-". A client is not required to make sense
- of X-Tokens. Clients are not required to save X-Tokens or use them
- in replies.
-
-4 Examples
-
-4.1 Published Event Examples
-
- In the calendaring and scheduling context, publication refers to the
- one way transfer of event information. Consumers of published events
- simply incorporate the event into a calendar. No reply is expected.
- Individual "A" publishes an event. Individual "B" reads the event and
- incorporates it into their calendar. Events are published in several
- ways including: embedding the event as an object in a web page, e-
- mailing the event to a distribution list, and posting the event to a
- newsgroup.
-
-
-
-Silverberg, et. al. Standards Track [Page 59]
-
-RFC 2446 iTIP November 1998
-
-
- The table below illustrates the sequence of events between the
- publisher and the consumers of a published event.
-
- +-------------------------------------------------------------------+
- | Action | "Organizer" |
- +---------------------------------+---------------------------------+
- | Publish an event | "A" sends or posts a PUBLISH |
- | | message |
- +---------------------------------+---------------------------------+
- | "B" reads a published event | |
- +---------------------------------+---------------------------------+
- | Publish an updated event | "A" sends or posts a PUBLISH |
- | | message |
- +---------------------------------+---------------------------------+
- | "B" reads the updated event | |
- +---------------------------------+---------------------------------+
- | Cancel a published event | "A" sends or posts a CANCEL |
- | | message |
- +---------------------------------+---------------------------------+
- | "B" reads the canceled event | |
- | publication | |
- +---------------------------------+---------------------------------+
-
-4.1.1 A Minimal Published Event
-
- The iCalendar object below describes a single event that begins on
- July 1, 1997 at 20:00 UTC. This event contains the minimum set of
- properties for a "PUBLISH" for a "VEVENT" calendar component.
-
- BEGIN:VCALENDAR
- METHOD:PUBLISH
- PRODID:-//ACME/DesktopCalendar//EN
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:a at example.com
- DTSTART:19970701T200000Z
- DTSTAMP:19970611T190000Z
- SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
- UID:0981234-1234234-23 at example.com
- END:VEVENT
- END:VCALENDAR
-
-4.1.2 Changing A Published Event
-
- The iCalendar object below describes an update to the event described
- in 4.1.1, the time has been changed, an end time has been added, and
- the sequence number has been adjusted.
-
-
-
-
-Silverberg, et. al. Standards Track [Page 60]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VCALENDAR
- METHOD:PUBLISH
- VERSION:2.0
- PRODID:-//ACME/DesktopCalendar//EN
- BEGIN:VEVENT
- ORGANIZER:mailto:a at example.com
- DTSTAMP:19970612T190000Z
- DTSTART:19970701T210000Z
- DTEND:19970701T230000Z
- SEQUENCE:1
- UID:0981234-1234234-23 at example.com
- SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
- END:VEVENT
- END:VCALENDAR
-
- The "UID" property is used by the client to identify the event. The
- "SEQUENCE" property indicates that this is a change to the event. The
- event with a matching UID and sequence number 0 is superseded by this
- event.
-
- The "SEQUENCE" property provides a reliable way to distinguish
- different versions of the same event. Each time an event is
- published, its sequence number is incremented. If a client receives
- an event with a sequence number 5 and finds it has the same event
- with sequence number 2, the event SHOULD be updated. However, if the
- client received an event with sequence number 2 and finds it already
- has sequence number 5 of the same event, the event MUST NOT be
- updated.
-
-4.1.3 Canceling A Published Event
-
- The iCalendar object below cancels the event described in 4.1.1. This
- cancels the event with "SEQUENCE" property of 0, 1, and 2.
-
- BEGIN:VCALENDAR
- METHOD:CANCEL
- VERSION:2.0
- PRODID:-//ACME/DesktopCalendar//EN
- BEGIN:VEVENT
- ORGANIZER:mailto:a at example.com
- COMMENT:DUKES forfeit the game
- SEQUENCE:2
- UID:0981234-1234234-23 at example.com
- DTSTAMP:19970613T190000Z
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 61]
-
-RFC 2446 iTIP November 1998
-
-
-4.1.4 A Rich Published Event
-
- This example describes the same event as in 4.1.1, but in much
- greater detail.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:PUBLISH
- SCALE:GREGORIAN
- VERSION:2.0
- BEGIN:VTIMEZONE
- TZID:America-Chicago
- TZURL:http://zones.stds_r_us.net/tz/America-Chicago
- BEGIN:STANDARD
- DTSTART:19671029T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
- TZOFFSETFROM:-0500
- TZOFFSETTO:-0600
- TZNAME:CST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19870405T020000
- RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
- TZOFFSETFROM:-0600
- TZOFFSETTO:-0500
- TZNAME:CDT
- END:DAYLIGHT
- END:VTIMEZONE
- BEGIN:VEVENT
- ORGANIZER:mailto:a at example.com
- ATTACH:http://www.dukes.com/
- CATEGORIES:SPORTS EVENT,ENTERTAINMENT
- CLASS:PRIVATE
- DESCRIPTION:MIDWAY STADIUM\n
- Big time game. MUST see.\n
- Expected duration:2 hours\n
- DTEND;TZID=America-Chicago:19970701T180000
- DTSTART;TZID=America-Chicago:19970702T160000
- DTSTAMP:19970614T190000Z
- STATUS:CONFIRMED
- LOCATION;VALUE=URI:http://www.midwaystadium.com/
- PRIORITY:2
- RESOURCES:SCOREBOARD
- SEQUENCE:3
- SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES
- UID:0981234-1234234-23 at example.com
- RELATED-TO:0981234-1234234-14 at example.com
- BEGIN:VALARM
-
-
-
-Silverberg, et. al. Standards Track [Page 62]
-
-RFC 2446 iTIP November 1998
-
-
- TRIGGER:-PT2H
- ACTION:DISPLAY
- DESCRIPTION:You should be leaving for the game now.
- END:VALARM
- BEGIN:VALARM
- TRIGGER:-PT30M
- ACTION:AUDIO
- END:VALARM
- END:VEVENT
- END:VCALENDAR
-
- The "RELATED-TO" field contains the "UID" property of a related
- calendar event. The "SEQUENCE" property 3 indicates that this event
- supersedes versions 0, 1, and 2.
-
-4.1.5 Anniversaries or Events attached to entire days
-
- This example demonstrates the use of the "value" parameter to tie a
- "VEVENT" to day rather than a specific time.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:PUBLISH
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:a at example.com
- DTSTAMP:19970614T190000Z
- UID:0981234-1234234-23 at example.com
- DTSTART;VALUE=DATE:19970714
- RRULE:FREQ=YEARLY;INTERVAL=1
- SUMMARY: Bastille Day
- END:VEVENT
- END:VCALENDAR
-
-4.2 Group Event Examples
-
- Group events are distinguished from published events in that they
- have "Attendees" and that there is interaction between the
- "Attendees" and the "Organizer" with respect to the event. Individual
- "A" requests a meeting between individuals "A", "B", "C" and "D".
- Individual "B" confirms attendance to the meeting. Individual "C"
- declines attendance. Individual "D" tentatively confirms attendance.
- The following table illustrates the the message flow between these
- individuals. A, the CU scheduling the meeting, is referenced as the
- "Organizer".
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 63]
-
-RFC 2446 iTIP November 1998
-
-
-+---------------------------------------------------------------------+
-| Action | "Organizer" | Attendee |
-+---------------------------------------------------------------------+
-| Initiate a meeting | "A" sends a REQUEST | |
-| request | message to "B", "C",| |
-| | and "D" | |
-+---------------------------------------------------------------------+
-| Accept the meeting | | "B" sends a REPLY |
-| request | | message to "A" with its |
-| | | ATTENDEE "partstat" para-|
-| | | set to "accepted" |
-+---------------------------------------------------------------------+
-| Decline the meeting| | "C" sends a REPLY |
-| request | | message to "A" with its |
-| | | ATTENDEE "partstat" para-|
-| | | set to "declined" |
-+---------------------------------------------------------------------+
-| Tentatively accept | | "D" sends a REPLY |
-| the meeting request| | message to "A" with its |
-| | | ATTENDEE "partstat" para-|
-| | | set to "tentative" |
-+---------------------------------------------------------------------+
-| Confirm meeting | "A" sends a REQUEST | |
-| status with | message to "B" and | |
-| attendees | "D" with updated | |
-| | information. | |
-+---------------------------------------------------------------------+
-
-4.2.1 A Group Event Request
-
- A sample meeting request is sent from "A" to "B", "C", and "D". _E_
- is also sent a copy of the request but is not expected to attend and
- need not reply. "E" illustrates how CUAs might implement an "FYI"
- type feature. Note the use of the "role" parameter. The default value
- for the "role" parameter is "req-participant" and it need not be
- enumerated. In this case we are using the value "non-participant" to
- indicate "E" is a non-attending CU. The parameter is not needed on
- other "Attendees" since "participant" is the default value.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C at example.com
-
-
-
-Silverberg, et. al. Standards Track [Page 64]
-
-RFC 2446 iTIP November 1998
-
-
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D at example.com
- ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big at example.com
- ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T200000Z
- DTEND:19970701T2000000Z
- SUMMARY:Conference
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.2.2 Reply To A Group Event Request
-
- Attendee "B" accepts the meeting.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VEVENT
- ATTENDEE;PARTSTAT=ACCEPTED:Mailto:B at example.com
- ORGANIZER:MAILTO:A at example.com
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- REQUEST-STATUS:2.0;Success
- DTSTAMP:19970612T190000Z
- END:VEVENT
- END:VCALENDAR
-
- "B" could have declined the meeting or indicated tentative acceptance
- by setting the "ATTENDEE" "partstat" parameter to "declined" or
- "tentative", respectively. Also, "REQUEST-STATUS" is not required in
- successful transactions.
-
-4.2.3 Update An Event
-
- The event is moved to a different time. The combination of the "UID"
- property (unchanged) and the "SEQUENCE" (bumped to 1) properties
- indicate the update.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
-
-
-
-Silverberg, et. al. Standards Track [Page 65]
-
-RFC 2446 iTIP November 1998
-
-
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D at example.com
- ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE;
- CUTYPE=ROOM:Mailto:Conf at example.com
- ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E at example.com
- DTSTART:19970701T180000Z
- DTEND:19970701T190000Z
- SUMMARY:Phone Conference
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:1
- DTSTAMP:19970613T190000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.2.4 Countering an Event Proposal
-
- "A" sends a "REQUEST" to "B" and "C". "B" makes a counter-proposal to
- "A" to change the time and location.
-
- "A" sends the following "REQUEST":
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
- DTSTART:19970701T190000Z
- DTEND:19970701T200000Z
- SUMMARY:Discuss the Merits of the election results
- LOCATION:Green Conference Room
- UID:calsrv.example.com-873970198738777a at example.com
- SEQUENCE:0
- DTSTAMP:19970611T190000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- "B" sends "COUNTER" to "A", requesting changes to time and place. "B"
- uses the "COMMENT" property to communicate a rationale for the
- change. Note that the "SEQUENCE" property is NOT incremented on a
- "COUNTER".
-
-
-
-Silverberg, et. al. Standards Track [Page 66]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:COUNTER
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
- DTSTART:19970701T160000Z
- DTEND:19970701T190000Z
- DTSTAMP:19970612T190000Z
- SUMMARY:Discuss the Merits of the election results
- LOCATION:Green Conference Room
- COMMENT:This time works much better and I think the big conference
- room is too big
- UID:calsrv.example.com-873970198738777a at example.com
- SEQUENCE:0
- DTSTAMP:19970611T190000Z
- END:VEVENT
- END:VCALENDAR
-
- "A" accepts the changes from "B". To accept a counter-proposal, the
- "Organizer" sends a new event "REQUEST" with an incremented sequence
- number.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:C at example.com
- DTSTAMP:19970613T190000Z
- DTSTART:19970701T160000Z
- DTEND:19970701T190000Z
- SUMMARY:Discuss the Merits of the election results - changed to
- meet B's schedule
- LOCATION:Green Conference Room
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:1
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- Instead, "A" rejects "B's" counter proposal
-
-
-
-Silverberg, et. al. Standards Track [Page 67]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:DECLINECOUNTER
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- COMMENT:Sorry, I cannot change this meeting time
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- DTSTAMP:19970614T190000Z
- END:VEVENT
- END:VCALENDAR
-
-4.2.5 Delegating an Event
-
- When delegating an event request to another "Calendar User", the
- "Delegator" must both update the "Organizer" with a "REPLY" and send
- a request to the "Delegate". There is currently no protocol
- limitation to delegation depth. It is possible for the original
-
- delegate to delegate the meeting to someone else, and so on. When a
- request is delegated from one CUA to another there are a number of
- responsibilities required of the "Delegator". The "Delegator" MUST:
-
- . Send a "REPLY" to the "Organizer" with the following updates:
- . The "Delegator's" "ATTENDEE" property "partstat" parameter set
- to "delegated" and the "delegated-to" parameter is set to the
- address of the "Delegate"
- . Add an additional "ATTENDEE" property for the "Delegate" with
- the "delegated-from" property parameter set to the "Delegator"
- . Indicate whether they want to continue to receive updates when
- the "Organizer" sends out updated versions of the event.
- Setting the "rsvp" property parameter to "TRUE" will cause the
- updates to be sent, setting it to "FALSE" causes no further
- updates to be sent. Note that in either case, if the "Delegate"
- declines the invitation the "Delegator" will be notified.
- . The "Delegator" MUST also send a copy of the original "REQUEST"
- method to the "Delegate".
-
- It is not required that the "Delegate" include the "Delegator" in
- their "REPLY" method. However, it is strongly advised since this will
- inform the "Delegator" whether the "Delegate" plans to attend the
- meeting. [Editors note: How so?] If the "Delegate" declines the
- meeting, the "Delegator" may elect to delegate the "REQUEST" to
- another CUA. The process is the same.
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 68]
-
-RFC 2446 iTIP November 1998
-
-
-+---------------------------------------------------------------------+
-| Action | "Organizer" | Attendee |
-+---------------------------------------------------------------------+
-| Initiate a meeting | "A" sends a REQUEST | |
-| request | message to "B" and | |
-| | "C" | |
-+---------------------------------------------------------------------+
-| Delegate: | | "C" sends a REPLY to "A" |
-| "C" delegates to | | with the ATTENDEE. |
-| "E" | | "partstat" parameter set |
-| | | to "delegated" and with a|
-| | | new "ATTENDEE" property |
-| | | for "E". "E's" ATTENDEE |
-| | | "delegated-from" param |
-| | | is set to "C". "C's" |
-| | | ATTENDEE "delegated-to" |
-| | | param is set to "E". |
-| | | "C" sends REQUEST message|
-| | | to "E" with the original |
-| | | meeting request |
-| | | information. The |
-| | | "partstat" property |
-| | | parameter for "C" is set |
-| | | to "delegated" and the |
-| | | "delegated-to" |
-| | | parameter is set to |
-| | | the address of "E". An |
-| | | "ATTENDEE" property is |
-| | | added for "E" and the |
-| | | "delegated-from" |
-| | | parameter is set to |
-| | | the address of "C". |
-+---------------------------------------------------------------------+
-| Confirm meeting | | "E" sends REPLY message |
-| attendance | | to "A" and optionally "C"|
-| | | with its "partstat" |
-| | | property parameter set |
-| | | to "ACCEPTED" |
-+---------------------------------------------------------------------+
-| Optional: | "A" sends REQUEST | |
-| Redistribute | message to "B", "C" | |
-| meeting to | and "E". | |
-| attendees | | |
-+---------------------------------------------------------------------+
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 69]
-
-RFC 2446 iTIP November 1998
-
-
- "C" responds to the "Organizer".
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:MAILTO:A at Example.com
- ATTENDEE;PARTSTAT=DELEGATED;DELEGATED-
- TO="Mailto:E at example.com":Mailto:C at example.com
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- REQUEST-STATUS:2.0;Success
- DTSTAMP:19970611T190000Z
- END:VEVENT
- END:VCALENDAR
-
- Attendee "C" delegates presence at the meeting to "E".
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;PARTSTAT=DELEGATED;DELEGATED-
- TO="Mailto:E at example.com":Mailto:C at example.com
- ATTENDEE;RSVP=TRUE;
- DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
- DTSTART:19970701T180000Z
- DTEND:19970701T200000Z
- SUMMARY:Phone Conference
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- STATUS:CONFIRMED
- DTSTAMP:19970611T190000Z
- END:VEVENT
- END:VCALENDAR
-
-4.2.6 Delegate Accepts the Meeting
-
- To accept a delegated meeting, the delegate, "E", sends the following
- message to "A" and "C":
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
-
-
-
-Silverberg, et. al. Standards Track [Page 70]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VEVENT
- ORGANIZER:MAILTO:A at Example.com
- ATTENDEE;PARTSTAT=ACCEPTED;DELEGATED-
- FROM="Mailto:C at example.com":Mailto:E at example.com
- ATTENDEE;PARTSTAT=DELEGATED;
- DELEGATED-TO="Mailto:E at example.com":Mailto:C at example.com
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- REQUEST-STATUS:2.0;Success
- DTSTAMP:19970614T190000Z
- END:VEVENT
- END:VCALENDAR
-
-4.2.7 Delegate Declines the Meeting
-
- In this example the "Delegate" declines the meeting request and sets
- the "ATTENDEE" property "partstat" parameter to "DECLINED". The
- "Organizer" SHOULD resend the "REQUEST" to "C" with the "partstat"
- parameter of the "Delegate" set to "declined". This lets the
- "Delegator" know that the "Delegate" has declined and provides an
- opportunity to the "Delegator" to either accept the request or
- delegate it to another CU.
-
- Response from "E" to "A" and "C". Note the use of the "COMMENT"
- property "E" uses to indicate why the delegation was declined.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:MAILTO:A at Example.com
- ATTENDEE;PARTSTAT=DELEGATED;
- DELEGATED-TO="Mailto:E at example.com":Mailto:C at example.com
- ATTENDEE;PARTSTAT=DECLINED;
- DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
- COMMENT:Sorry, I will be out of town at that time.
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- REQUEST-STATUS:2.0;Success
- DTSTAMP:19970614T190000Z
- END:VEVENT
- END:VCALENDAR
-
- "A" resends the "REQUEST" method to "C". "A" may also wish to express
- the fact that the item was delegated in the "COMMENT" property.
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 71]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:MAILTO:A at Example.com
- ATTENDEE;PARTSTAT=DECLINED;
- DELEGATED-FROM="Mailto:C at example.com":Mailto:E at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- SUMMARY:Phone Conference
- DTSTART:19970701T180000Z
- DTEND:19970701T200000Z
- DTSTAMP:19970614T200000Z
- COMMENT:DELEGATE (ATTENDEE Mailto:E at example.com) DECLINED YOUR
- INVITATION
- END:VEVENT
- END:VCALENDAR
-
-4.2.8 Forwarding an Event Request
-
- The protocol does not prevent an "Attendee" from "forwarding" an
- "VEVENT" calendar component to other "Calendar Users". Forwarding
- differs from delegation in that the forwarded "Calendar User" (often
- referred to as a "Party Crasher") does not replace the forwarding
- "Calendar User". Implementations are not required to add the "Party
- Crasher" to the "Attendee" list and hence there is no guarantee that
- a "Party Crasher" will receive additional updates to the Event. The
- forwarding "Calendar User" SHOULD NOT add the "Party Crasher" to the
- attendee list. The "Organizer" MAY add the forwarded "Calendar User"
- to the attendee list.
-
-4.2.9 Cancel A Group Event
-
- Individual "A" requests a meeting between individuals "A", "B", "C",
- and "D". Individual "B" declines attendance to the meeting.
- Individual "A" decides to cancel the meeting. The following table
- illustrates the sequence of messages that would be exchanged between
- these individuals.
-
- Messages related to a previously canceled event ("SEQUENCE" property
- value is less than the "SEQUENCE" property value of the "CANCEL"
- message) MUST be ignored.
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 72]
-
-RFC 2446 iTIP November 1998
-
-
- +--------------------------------------------------------------------+
- | Action | "Organizer" | "Attendee" |
- +--------------------------------------------------------------------+
- | Initiate a meeting | "A" sends a REQUEST | |
- | request | message to "B", "C",| |
- | | and "D" | |
- +--------------------------------------------------------------------+
- | Decline the meeting| | "B" sends a "REPLY" |
- | request | | message to "A" with its |
- | | | "partstat" para- |
- | | | set to "declined". |
- +--------------------------------------------------------------------+
- | Cancel the meeting | "A" sends a CANCEL | |
- | | message to "B", "C" | |
- | | and "D" | |
- +--------------------------------------------------------------------+
-
- The example shows how "A" cancels the event.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:CANCEL
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;TYPE=INDIVIDUAL;Mailto:A at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
- COMMENT:Mr. B cannot attend. It's raining. Lets cancel.
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:1
- STATUS:CANCELLED
- DTSTAMP:19970613T190000Z
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 73]
-
-RFC 2446 iTIP November 1998
-
-
-4.2.10 Removing Attendees
-
- "A" wants to remove "B" from a meeting. This is done by sending a
- "CANCEL" to "B" and removing "B" from the attendee list in the master
- copy of the event.
-
- +--------------------------------------------------------------------+
- | Action | "Organizer" | "Attendee" |
- +--------------------------------------------------------------------+
- | Remove an "B" | "A" sends a CANCEL | |
- | as an "Attendee" | message to "B" | |
- +--------------------------------------------------------------------+
- | Update the master | "A" sends the | |
- | copy of the event | updated event to | |
- | | the remaining | |
- | | "Attendees" | |
- +--------------------------------------------------------------------+
-
- The original meeting includes "A", "B", "C", and "D". The example
- below shows the "CANCEL" that "A" sends to "B". Note that in the
- example below the "STATUS" property is omitted. This is used when the
- meeting itself is cancelled and not when the intent is to remove an
- "Attendee" from the Event.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:CANCEL
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE:mailto:B at example.com
- COMMENT:You're off the hook for this meeting
- UID:calsrv.example.com-873970198738777 at example.com
- DTSTAMP:19970613T193000Z
- SEQUENCE:1
- END:VEVENT
- END:VCALENDAR
-
- The updated master copy of the event is shown below. The "Organizer"
- MAY resend the updated event to the remaining "Attendees". Note that
- "B" has been removed.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
-
-
-
-Silverberg, et. al. Standards Track [Page 74]
-
-RFC 2446 iTIP November 1998
-
-
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
- ATTENDEE;TYPE=ROOM:CR_Big at example.com
- ATTENDEE;ROLE=NON-PARTICIPANT;
- RSVP=FALSE:Mailto:E at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T200000Z
- DTEND:19970701T203000Z
- SUMMARY:Phone Conference
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:2
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.2.11 Replacing the Organizer
-
- The scenario for this example begins with "A" as the "Organizer" for
- a recurring meeting with "B", "C", and "D". "A" receives a new job
- offer in another country and drops out of touch. "A" left no
- forwarding address or way to be reached. Using out-of-band
- communication, the other "Attendees" eventually learn what has
- happened and reach an agreement that "B" should become the new
- "Organizer" for the meeting. To do this, "B" sends out a new version
- of the event and the other "Attendees" agree to accept "B" as the new
- "Organizer". "B" also removes "A" from the event.
-
- When the "Organizer" is replaced, the "SEQUENCE" property value MUST
- be incremented.
-
- This is the message "B" sends to "C" and "D"
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:B at example.com
- ATTENDEE;ROLE=CHAIR;STATUS=ACCEPTED:Mailto:B at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:C at example.com
- ATTENDEE;TYPE=INDIVIDUAL:Mailto:D at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T200000Z
- DTEND:19970701T203000Z
- RRULE:FREQ=WEEKLY
- SUMMARY:Phone Conference
- UID:123456 at example.com
-
-
-
-Silverberg, et. al. Standards Track [Page 75]
-
-RFC 2446 iTIP November 1998
-
-
- SEQUENCE:1
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.3 Busy Time Examples
-
- Busy time objects can be used in several ways. First, a CU may
- request busy time from another CU for a specific range of time. That
- request can be answered with a busy time Reply. Additionally, a CU
- may simply publish their busy time for a given interval and point
- other CUs to the published location. The following examples outline
- both scenarios.
-
- Individual "A" publishes busy time for one week.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- VERSION:2.0
- METHOD:PUBLISH
- BEGIN:VFREEBUSY
- DTSTAMP:19980101T124100Z
- ORGANIZER:MAILTO:A at Example.com
- DTSTART:19980101T124200Z
- DTEND:19980107T124200Z
- FREEBUSY:19980101T180000Z/19980101T190000Z
- FREEBUSY:19980103T020000Z/19980103T050000Z
- FREEBUSY:19980107T020000Z/19980107T050000Z
- FREEBUSY:19980113T000000Z/19980113T010000Z
- FREEBUSY:19980115T190000Z/19980115T200000Z
- FREEBUSY:19980115T220000Z/19980115T230000Z
- FREEBUSY:19980116T013000Z/19980116T043000Z
- END:VFREEBUSY
- END:VCALENDAR
-
- Individual "A" requests busy time from individuals "B", "C".
- Individual "B" and "C" replies with busy time data to individual "A".
- The following table illustrates the sequence of messages that would
- be exchanged between these individuals.
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 76]
-
-RFC 2446 iTIP November 1998
-
-
-+--------------------------------------------------------------------+
-| Action | "Organizer" | Attendee |
-+--------------------------------------------------------------------+
-| Initiate a busy | "A" sends "REQUEST" | |
-| time request | message to "B" and | |
-| | and "C" | |
-+--------------------------------------------------------------------+
-| Reply to the "BUSY"| | "B" sends a "REPLY" |
-| request with "BUSY"| | message to "A" with |
-| time data | | busy time data |
-+--------------------------------------------------------------------+
-
-4.3.1 Request Busy Time
-
- "A" sends a "BUSY-REQUEST" to "B" and "C" for busy time
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VFREEBUSY
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
- DTSTAMP:19970613T190000Z
- DTSTART:19970701T080000Z
- DTEND:19970701T200000
- UID:calsrv.example.com-873970198738777 at example.com
- END:VFREEBUSY
- END:VCALENDAR
-
-4.3.2 Reply To A Busy Time Request
-
- "B" sends a "REPLY" method type of a "VFREEBUSY" calendar component
- to "A"
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VFREEBUSY
- ORGANIZER:MAILTO:A at example.com
- ATTENDEE:Mailto:B at example.com
- DTSTART:19970701T080000Z
- DTEND:19970701T200000Z
- UID:calsrv.example.com-873970198738777 at example.com
- FREEBUSY:19970701T090000Z/PT1H,19970701T140000Z/PT30M
-
-
-
-Silverberg, et. al. Standards Track [Page 77]
-
-RFC 2446 iTIP November 1998
-
-
- DTSTAMP:19970613T190030Z
- END:VFREEBUSY
- END:VCALENDAR
-
- "B" is busy from 09:00 to 10:00 and from 14:00 to 14:30.
-
-4.4 Recurring Event and Time Zone Examples
-
-4.4.1 A Recurring Event Spanning Time Zones
-
- This event describes a weekly phone conference. The "Attendees" are
- each in a different time zone.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTIMEZONE
- TZID:America-SanJose
- TZURL:http://zones.stds_r_us.net/tz/America-SanJose
- BEGIN:STANDARD
- DTSTART:19671029T020000
- RRULE:FREQ=YEARLY;BYDAY=-1SU;BYMONTH=10
- TZOFFSETFROM:-0700
- TZOFFSETTO:-0800
- TZNAME:PST
- END:STANDARD
- BEGIN:DAYLIGHT
- DTSTART:19870405T020000
- RRULE:FREQ=YEARLY;BYDAY=1SU;BYMONTH=4
- TZOFFSETFROM:-0800
- TZOFFSETTO:-0700
- TZNAME:PDT
- END:DAYLIGHT
- END:VTIMEZONE
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;TYPE=INDIVIDUAL:A at example.COM
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:B at example.fr
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:c at example.jp
- DTSTAMP:19970613T190030Z
- DTSTART;TZID=America-SanJose:19970701T140000
- DTEND;TZID=America-SanJose:19970701T150000
- RRULE:FREQ=WEEKLY;INTERVAL=20;WKST=SU;BYDAY=TU
- RDATE;TZID=America-SanJose:19970910T140000
- EXDATE;TZID=America-SanJose:19970909T140000
- EXDATE;TZID=America-SanJose:19971028T140000
- SUMMARY:Weekly Phone Conference
-
-
-
-Silverberg, et. al. Standards Track [Page 78]
-
-RFC 2446 iTIP November 1998
-
-
- UID:calsrv.example.com-873970198738777 at example.com
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- The first two components of this iCalendar object are the time zone
- components. The "DTSTART" date coincides with the first instance of
- the RRULE property.
-
- The recurring meeting is defined in a particular time zone,
- presumably that of the originator. The client for each "Attendee" has
- the responsibility of determining the recurrence time in the
- "Attendee's" time zone.
-
- The repeating event starts on Tuesday, July 1, 1997 at 2:00pm PDT.
- "Attendee" B at example.fr is in France where the local time on this
- date is 9 hours ahead of PDT or 23:00. "Attendee" C at example.jp is in
- Japan where local time is 8 hours ahead of UTC or Wednesday, July 2
- at 06:00. The event repeats weekly on Tuesdays (in PST/PDT). The
- "RRULE" property results in 20 instances. The last instance falls on
- Tuesday, November 11, 1997 2:00pm PDT. The "RDATE" property adds
- another instance: WED, 10-SEP-1997 2:00 PM PST.
-
- There are two exceptions to this recurring appointment. The first one
- is:
-
- TUE, 09-SEP-1997 23:00 GMT
- TUE, 09-SEP-1997 14:00 PDT
- WED, 10-SEP-1997 06:00 JST
-
- and the second is:
-
- TUE, 28-OCT-1997 23:00 GMT
- TUE, 28-OCT-1997 14:00 PST
- WED, 29-OCT-1997 06:00 JST
-
-4.4.2 Modify A Recurring Instance
-
- In this example the "Organizer" issues a recurring meeting. Later the
- "Organizer" changes an instance of the event by changing the
- "DTSTART" property. Note the use of "RECURRENCE-ID" property and
- "SEQUENCE" property in the second request.
-
- Original Request:
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
-
-
-
-Silverberg, et. al. Standards Track [Page 79]
-
-RFC 2446 iTIP November 1998
-
-
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- SEQUENCE:0
- RRULE:FREQ=MONTHLY;BYMONTHDAY=1;UNTIL=19980901T210000Z
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
- ATTENDEE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Conference Call
- CLASS:PUBLIC
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970601T210000Z
- DTEND:19970601T220000Z
- LOCATION:Conference Call
- DTSTAMP:19970526T083000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- The event request below is to change the time of a specific instance.
- This changes the July 1st instance to July 3rd.
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1com
- RECURRENCE-ID:19970701T210000Z
- SEQUENCE:1
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
- ATTENDEE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Conference Call
- CLASS:PUBLIC
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970703T210000Z
- DTEND:19970703T220000Z
- LOCATION:Conference Call
- DTSTAMP:19970626T093000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-
-
-Silverberg, et. al. Standards Track [Page 80]
-
-RFC 2446 iTIP November 1998
-
-
-4.4.3 Cancel an Instance
-
- In this example the "Organizer" of a recurring event deletes the
- August 1st instance.
-
- BEGIN:VCALENDAR
- METHOD:CANCEL
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
- ATTENDEE:Mailto:D at example.com
- RECURRENCE-ID:19970801T210000Z
- SEQUENCE:2
- STATUS:CANCELLED
- DTSTAMP:19970721T093000Z
- END:VEVENT
- END:VCALENDAR
-
-4.4.4 Cancel Recurring Event
-
- In this example the "Organizer" wishes to cancel the entire recurring
- event and any exceptions.
-
- BEGIN:VCALENDAR
- METHOD:CANCEL
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
- ATTENDEE:Mailto:D at example.com
- DTSTAMP:19970721T103000Z
- STATUS:CANCELLED
- SEQUENCE:3
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 81]
-
-RFC 2446 iTIP November 1998
-
-
-4.4.5 Change All Future Instances
-
- This example changes the meeting location from a conference call to
- Seattle starting September 1 and extends to all future instances.
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- RECURRENCE-ID;THISANDFUTURE:19970901T210000Z
- SEQUENCE:3
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Discussion
- CLASS:PUBLIC
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970901T210000Z
- DTEND:19970901T220000Z
- LOCATION:Building 32, Microsoft, Seattle, WA
- DTSTAMP:19970526T083000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.4.6 Add A New Instance To A Recurring Event
-
- This example adds a one-time additional instance to the recurring
- event. "Organizer" adds a second July meeting on the 15th.
-
- BEGIN:VCALENDAR
- METHOD:ADD
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:4
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Conference Call
- CLASS:PUBLIC
-
-
-
-Silverberg, et. al. Standards Track [Page 82]
-
-RFC 2446 iTIP November 1998
-
-
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970715T210000Z
- DTEND:19970715T220000Z
- LOCATION:Conference Call
- DTSTAMP:19970629T093000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.4.7 Add A New Series of Instances To A Recurring Event
-
- The scenario for this example involves an ongoing meeting, originally
- set up to occur every Tuesday. The "Organizer" later decides that
- the meetings need to be on Tuesdays and Thursdays, but does not want
- to reschedule the entire meeting or lose any of the per-instance
- information already collected.
-
- The original event:
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:0
- RRULE:WKST=SU;BYDAY=TU;FREQ=WEEKLY
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980303T210000Z
- DTEND:19980303T220000Z
- LOCATION:The White Room
- DTSTAMP:19980301T093000Z
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- Assume that many other updates happen to this event and that a lot of
- instance-specific information exists in the recurring series. The
- "SEQUENCE" property value is 7 for the next update. Now the
- "Organizer" wants to add Thursdays to the event:
-
- BEGIN:VCALENDAR
- METHOD:ADD
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
-
-
-
-Silverberg, et. al. Standards Track [Page 83]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:7
- RRULE:WKST=SU;BYDAY=TH;FREQ=WEEKLY
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980303T210000Z
- DTEND:19980303T220000Z
- DTSTAMP:19980303T193000Z
- LOCATION:The Usual conference room
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- Alternatively, if the "Organizer" is not concerned with per-instance
- updates, the entire event can be rescheduled using a "REQUEST". This
- is done by using the "UID" of the event to reschedule and including
- the modified "RRULE". Note, that since this is an entire rescheduling
- of the event, any instance-specific information will be lost.
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:7
- RRULE:WKST=SU;BYDAY=TU,TH;FREQ=WEEKLY
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980303T210000Z
- DTEND:19980303T220000Z
- DTSTAMP:19980303T193000Z
- LOCATION:The White Room
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- The next series of examples illustrate how an "Organizer" would
- respond to a "REFRESH" submitted by an "Attendee" after a series of
- instance-specific modifications. To convey all instance-specific
- changes, the "Organizer" must provide the latest event description
- and the relevant instances. The first three examples show the history
- including the initial "VEVENT" request and subsequent instance
-
-
-
-Silverberg, et. al. Standards Track [Page 84]
-
-RFC 2446 iTIP November 1998
-
-
- changes and finally the "REFRESH".
-
- Original Request:
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:0
- RDATE:19980304T180000Z
- RDATE:19980311T180000Z
- RDATE:19980318T180000Z
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980304T180000Z
- DTEND:19980304T200000Z
- DTSTAMP:19980303T193000Z
- LOCATION:Conference Room A
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- Organizer changes 2nd instance Location and Time:
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:1
- RECURRENCE-ID:19980311T180000Z
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980311T160000Z
- DTEND:19980311T180000Z
- DTSTAMP:19980306T193000Z
- LOCATION:The Small conference room
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-Silverberg, et. al. Standards Track [Page 85]
-
-RFC 2446 iTIP November 1998
-
-
- Organizer adds a 4th instance of the meeting using the "ADD" method
-
- BEGIN:VCALENDAR
- METHOD:ADD
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:2
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980315T180000Z
- DTEND:19980315T200000Z
- DTSTAMP:19980307T193000Z
- LOCATION:Conference Room A
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- If "B" requests a "REFRESH", "A" responds with the following to
- capture all instance-specific data. In this case both the initial
- request and an additional "VEVENT" that specifies the instance-
- specific data are included. Because these are both of the same type
- (they are both "VEVENTS"), they can be conveyed in the same iCalendar
- object.
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:123456789 at host1.com
- SEQUENCE:2
- RDATE:19980304T180000Z
- RDATE:19980311T160000Z
- RDATE:19980315T180000Z
- Error! Bookmark not defined.
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- SUMMARY:Review Accounts
- DTSTART:19980304T180000Z
- DTEND:19980304T200000Z
- DTSTAMP:19980303T193000Z
- LOCATION:Conference Room A
- STATUS:CONFIRMED
-
-
-
-Silverberg, et. al. Standards Track [Page 86]
-
-RFC 2446 iTIP November 1998
-
-
- END:VEVENT
-
- BEGIN:VEVENT
- Error! Bookmark not defined.
- SEQUENCE:2
- RECURRENCE-ID:19980311T160000Z
- Error! Bookmark not defined.
- ATTENDEE;ROLE=CHAIR;Error! Bookmark not defined.
- ATTENDEE;Error! Bookmark not defined.
- SUMMARY:Review Accounts
- DTSTART:19980311T160000Z
- DTEND:19980304T180000Z
- DTSTAMP:19980306T193000Z
- LOCATION:The Small conference room
- STATUS:CONFIRMED
- END:VEVENT
-
- END:VCALENDAR
-
-4.4.8 Counter An Instance Of A Recurring Event
-
- In this example one of the "Attendees" counters the "DTSTART"
- property of the proposed second July meeting.
-
- BEGIN:VCALENDAR
- METHOD:COUNTER
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- RECURRENCE-ID:19970715T210000Z
- SEQUENCE:4
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;RSVP=TRUE:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Conference Call
- CLASS:PUBLIC
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970715T220000Z
- DTEND:19970715T230000Z
- LOCATION:Conference Call
- COMMENT:May we bump this by an hour? I have a conflict
- DTSTAMP:19970629T094000Z
- END:VEVENT
- END:VCALENDAR
-
-
-
-
-Silverberg, et. al. Standards Track [Page 87]
-
-RFC 2446 iTIP November 1998
-
-
-4.4.9 Error Reply To A Request
-
- The following example illustrates a scenario where a meeting is
- proposed containing an unsupported property and a bad property.
-
- Original Request
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:guid-1 at host1.com
- SEQUENCE:0
- RRULE:FREQ=MONTHLY;BYMONTHDAY=1
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE:Mailto:D at example.com
- DESCRIPTION:IETF-C&S Conference Call
- CLASS:PUBLIC
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970601T210000Z
- DTEND:19970601T220000Z
- DTSTAMP:19970602T094000Z
- LOCATION:Conference Call
- STATUS:CONFIRMED
- FOO:BAR
- END:VEVENT
- END:VCALENDAR
-
- Response from "B" to indicate that RRULE is not supported and an
- unrecognized property was encountered
-
- BEGIN:VCALENDAR
- PRODID:-//RDU Software//NONSGML HandCal//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- REQUEST-STATUS:2.8;Repeating event ignored. Scheduled as a single
- event;RRULE
- REQUEST-STATUS:3.0;Invalid Property Name;FOO
- UID:guid-1 at host1.com
- SEQUENCE:0
- DTSTAMP:19970603T094000Z
-
-
-
-Silverberg, et. al. Standards Track [Page 88]
-
-RFC 2446 iTIP November 1998
-
-
- END:VEVENT
- END:VCALENDAR
-
-4.5 Group To-do Examples
-
- Individual "A" creates a group task in which individuals "A", "B",
- "C" and "D" will participate. Individual "B" confirms acceptance of
- the task. Individual "C" declines the task. Individual "D"
- tentatively accepts the task. The following table illustrates the
- sequence of messages that would be exchanged between these
- individuals. Individual "A" then issues a "REQUEST" method to obtain
- the status of the to-do from each participant. The response indicates
- the individual "Attendee's" completion status. The table below
- illustrates the message flow.
-
-+--------------------------------------------------------------------+
-| Action | "Organizer" | Attendee |
-+--------------------------------------------------------------------+
-| Initiate a to-do | "A" sends a REQUEST | |
-| request | message to "B", "C",| |
-| | and "D" | |
-+--------------------------------------------------------------------+
-| Accept the to-do | | "B" sends a "REPLY" |
-| request | | message to "A" with its |
-| | | "partstat" paramater |
-| | | set to "accepted". |
-+--------------------------------------------------------------------+
-| Decline the to-do | | "C" sends a REPLY |
-| request | | message to "A" with its |
-| | | "partstat" parameter |
-| | | set to "declined". |
-+--------------------------------------------------------------------+
-| Tentatively accept | | "D" sends a REPLY |
-| the to-do request | | message to "A" with its |
-| | | "partstat" parameter |
-| | | set to "tentative". |
-+--------------------------------------------------------------------+
-| Check attendee | "A" sends a REQUEST | |
-| completion status | message to "B" and | |
-| | "D" with current | |
-| | information. | |
-+--------------------------------------------------------------------+
-| Attendee indicates | | "B" sends a "REPLY" |
-| percent complete | | message indicating |
-| | | percent complete |
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 89]
-
-RFC 2446 iTIP November 1998
-
-
-+--------------------------------------------------------------------+
-| Attendee indicates | | "D" sends a "REPLY" |
-| completion | | message indicating |
-| | | completion |
-+--------------------------------------------------------------------+
-
-4.5.1 A VTODO Request
-
- A sample "REQUEST" for a "VTODO" calendar component that "A" sends to
- "B", "C", and "D".
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE:Mailto:C at example.com
- ATTENDEE;RSVP=TRUE:Mailto:D at example.com
- DTSTART:19970701T170000Z
- DUE:19970722T170000Z
- PRIORITY:1
- SUMMARY:Create the requirements document
- UID:calsrv.example.com-873970198738777-00 at example.com
- SEQUENCE:0
- DTSTAMP:19970717T200000Z
- STATUS:Needs Action
- END:VTODO
- END:VCALENDAR
-
-4.5.2 A VTODO Reply
-
- "B" accepts the to-do.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;PARTSTAT=ACCEPTED:Mailto:B at example.com
- UID:calsrv.example.com-873970198738777-00 at example.com
- COMMENT:I'll send you my input by e-mail
- SEQUENCE:0
- DTSTAMP:19970717T203000Z
- REQUEST-STATUS:2.0;Success
-
-
-
-Silverberg, et. al. Standards Track [Page 90]
-
-RFC 2446 iTIP November 1998
-
-
- END:VTODO
- END:VCALENDAR
-
- "B" could have declined the TODO or indicated tentative acceptance by
- setting the "partstat" property parameter sequence to "declined" or
- "tentative", respectively.
-
-4.5.3 A VTODO Request for Updated Status
-
- "A" requests status from all "Attendees".
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:D at example.com
- UID:calsrv.example.com-873970198738777-00 at example.com
- SUMMARY:Create the requirements document
- PRIORITY:1
- SEQUENCE:0
- STATUS:IN-PROCESS
- DTSTART:19970701T170000Z
- DTSTAMP:19970717T230000Z
- END:VTODO
- END:VCALENDAR
-
-4.5.4 A Reply: Percent-Complete
-
- A reply indicating the task being worked on and that "B" is 75%
- complete with "B's" part of the assignment.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:MAILTO:A at example.com
- ATTENDEE;PARTSTAT=IN-PROCESS:Mailto:B at example.com
- PERCENT-COMPLETE:75
- UID:calsrv.example.com-873970198738777-00 at example.com
- DTSTAMP:19970717T233000Z
- SEQUENCE:0
- END:VTODO
- END:VCALENDAR
-
-
-
-Silverberg, et. al. Standards Track [Page 91]
-
-RFC 2446 iTIP November 1998
-
-
-4.5.5 A Reply: Completed
-
- A reply indicating that "D" completed "D's" part of the assignment.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:MAILTO:A at example.com
- ATTENDEE;PARTSTAT=COMPLETED:Mailto:D at example.com
- UID:calsrv.example.com-873970198738777-00 at example.com
- DTSTAMP:19970717T233000Z
- SEQUENCE:0
- END:VTODO
- END:VCALENDAR
-
-4.5.6 An Updated VTODO Request
-
- Organizer "A" resends the "VTODO" calendar component. "A" sets the
- overall completion for the to-do at 40%.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE;PARTSTAT=ACCEPTED;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;PARTSTAT=IN-PROCESS;TYPE=INDIVIDUAL:Mailto:D at example.com
- DTSTART:19970701T170000Z
- DUE:19970722T170000Z
- PRIORITY:1
- SUMMARY:Create the requirements document
- UID:calsrv.example.com-873970198738777-00 at example.com
- SEQUENCE:1
- DTSTAMP:19970718T100000Z
- STATUS:IN-PROGRESS
- PERCENT-COMPLETE:40
- END:VTODO
- END:VCALENDAR
-
-4.5.7 Recurring VTODOs
-
- The following examples relate to recurring "VTODO" calendar
- components.
-
-
-
-
-Silverberg, et. al. Standards Track [Page 92]
-
-RFC 2446 iTIP November 1998
-
-
-4.5.7.1 Request for a Recurring VTODO
-
- In this example "A" sends a recurring "VTODO" calendar component to
- "B" and "D".
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTODO
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR:Mailto:A at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:B at example.com
- ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL:Mailto:D at example.com
- RRULE:FREQ=MONTHLY;COUNT=10;BYDAY=1FR
- DTSTART:19980101T100000-0700
- DUE:19980103T100000-0700
- SUMMARY:Send Status Reports to Area Managers
- UID:calsrv.example.com-873970198738777-00 at example.com
- SEQUENCE:0
- DTSTAMP:19970717T200000Z
- STATUS:NEEDS ACTION
- PRIORITY:1
- END:VTODO
- END:VCALENDAR
-
-4.5.7.2 Calculating due dates in recurring VTODOs
-
- The due date in a recurring "VTODO" calendar component is either a
- fixed interval specified in the "REQUEST" method or specified using
- the "RECURRENCE-ID" property. The former is calculated by applying
- the difference between "DTSTART" and "DUE" properties and applying it
- to each of the start of each recurring instance. Hence, if the
- initial "VTODO" calendar component specifies a "DTSTART" property
- value of "19970701T190000Z" and a "DUE" property value of
- "19970801T190000Z" the interval of one day which is applied to each
- recurring instance of the "VTODO" calendar component to determine the
- "DUE" date of the instance.
-
-4.5.7.3 Replying to an instance of a recurring VTODO
-
- In this example "B" updates "A" on a single instance of the "VTODO"
- calendar component.
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REPLY
- VERSION:2.0
-
-
-
-Silverberg, et. al. Standards Track [Page 93]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VTODO
- ATTENDEE;PARTSTAT=IN-PROCESS:Mailto:B at example.com
- PERCENT-COMPLETE:75
- UID:calsrv.example.com-873970198738777-00 at example.com
- DTSTAMP:19970717T233000Z
- RECURRENCE-ID:19980101T170000Z
- SEQUENCE:1
- END:VTODO
- END:VCALENDAR
-
-4.6 Journal Examples
-
- The iCalendar object below describes a single journal entry for
- October 2, 1997. The "RELATED-TO" property references the phone
- conference event for which minutes were taken.
-
- BEGIN:VCALENDAR
- METHOD:PUBLISH
- PRODID:-//ACME/DesktopCalendar//EN
- VERSION:2.0
- BEGIN:VJOURNAL
- DTSTART:19971002T200000Z
- ORGANIZER:MAILTO:A at Example.com
- SUMMARY:Phone conference minutes
- DESCRIPTION:The editors meeting was held on October 1, 1997.
- Details are in the attached document.
- UID:0981234-1234234-2410 at example.com
- RELATED-TO:0981234-1234234-2402-35 at example.com
- ATTACH:ftp://ftp.example.com/pub/ed/minutes100197.txt
- END:VJOURNAL
- END:VCALENDAR
-
-4.7 Other Examples
-
-4.7.1 Event Refresh
-
- Refresh the event with "UID" property value of "guid-1-
- 12345 at host1.com":
-
- BEGIN:VCALENDAR
- PRODID:-//RDU Software//NONSGML HandCal//EN
- METHOD:REFRESH
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- ATTENDEE:Mailto:C at example.com
-
-
-
-Silverberg, et. al. Standards Track [Page 94]
-
-RFC 2446 iTIP November 1998
-
-
- ATTENDEE:Mailto:D at example.com
- UID: guid-1-12345 at host1.com
- DTSTAMP:19970603T094000
- END:VEVENT
- END:VCALENDAR
-
-4.7.2 Bad RECURRENCE-ID
-
- Component instances are identified by the combination of "UID",
- "RECURRENCE-ID", and "SEQUENCE". When an "Organizer" sends a request
- to an "Attendee", there are three cases in which an instance cannot
- be found. They are:
-
- 1. The component with the referenced "UID" and "RECURRENCE-ID" has
- been found but the "SEQUENCE" number in the calendar store does
- not match that of the ITIP message.
-
- 2. The component with the referenced "UID" has been found, the
- "SEQUENCE" numbers match, but the "RECURRENCE-ID" cannot be
- found.
-
- 3. The "UID" and "SEQUENCE" numbers are found but the CUA does not
- support recurrences.
-
- In case (1), two things can happen. If the "SEQUENCE" number of the
- "Attendee's" instance is larger than that in the "Organizer's"
- message then the "Attendee" is receiving an out-of-sequence message
- and MUST ignore it. If the "SEQUENCE" number of the "Attendee's"
- instance is smaller, then the "Organizer" is sending out a newer
- version of the component and the "Attendee's" version needs to be
- updated. Since one or more updates have been missed, the "Attendee"
- SHOULD send a "REFRESH" message to the "Organizer" to get an updated
- version of the event.
-
- In case (2), something has gone wrong. Both the "Organizer" and the
- "Attendee" should have the same instances, but the "Attendee" does
- not have the referenced instance. In this case the "Attendee" SHOULD
- send a "REFRESH" to the "Organizer" to get an updated version of the
- event.
-
- In case (3), the limitations of the "Attendee's" CUA makes it
- impossible to match an instance other than the single instance
- scheduled. In this case, the "Attendee" need not send a "REFRESH" to
- the "Organizer".
-
- The example below shows a sequence in which an "Attendee" sends a
- "REFRESH" to the "Organizer".
-
-
-
-
-Silverberg, et. al. Standards Track [Page 95]
-
-RFC 2446 iTIP November 1998
-
-
-+--------------------------------------------------------------------+
-| Action | "Organizer" | Attendee |
-+--------------------------------------------------------------------+
-| Update an instance | "A" sends "REQUEST"| |
-| request | message to "B" | |
-+--------------------------------------------------------------------+
-| Attendee requests | | "B" sends a "REFRESH" |
-| refresh because | | message to "A" |
-| "RECURRENCE-ID" was| | |
-| not found | | |
-+--------------------------------------------------------------------+
-| Refresh the entire | "A" sends the | |
-| Event | latest copy of the | |
-| | Event to "B" | |
-+--------------------------------------------------------------------+
-| Attendee handles | | "B" updates to the |
-| the request and | | latest copy of the |
-| updates the | | meeting. |
-| instance | | |
-+--------------------------------------------------------------------+
-
- Request from "A":
-
- BEGIN:VCALENDAR
- METHOD:REQUEST
- PRODID:-//RDU Software//NONSGML HandCal//EN
- VERSION:2.0
- BEGIN:VEVENT
- UID:acme-12345 at host1.com
- SEQUENCE:3
- RRULE:FREQ=WEEKLY
- RDATE;VALUE=PERIOD:19970819T210000Z/199700819T220000Z
- ORGANIZER:Mailto:A at example.com
- ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- DESCRIPTION:IETF-C&S Conference Call
- SUMMARY:IETF Calendaring Working Group Meeting
- DTSTART:19970801T210000Z
- DTEND:19970801T220000Z
- RECURRENCE-ID:19970809T210000Z
- DTSTAMP:19970726T083000
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- "B" has the event with "UID" property "acme-12345 at host1.com" but
- "B's" "SEQUENCE" property value is "1" and the event does not have an
- instance at the specified recurrence time. This means that "B" has
-
-
-
-Silverberg, et. al. Standards Track [Page 96]
-
-RFC 2446 iTIP November 1998
-
-
- missed at least one update and needs a new copy of the event. "B"
- requests the latest copy of the event with the following refresh
- message:
-
- BEGIN:VCALENDAR
- PRODID:-//RDU Software//NONSGML HandCal//EN
- METHOD:REFRESH
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:Mailto:A at example.com
- ATTENDEE:Mailto:B at example.com
- UID:acme-12345 at host1.com
- DTSTAMP:19970603T094000
- END:VEVENT
- END:VCALENDAR
-
-5 Application Protocol Fallbacks
-
-5.1 Partial Implementation
-
- Applications that support this memo are not required to support the
- entire protocol. The following describes how methods and properties
- SHOULD "fallback" in applications that do not support the complete
- protocol. If a method or property is not addressed in this section,
- it may be ignored.
-
-5.1.1 Event-Related Fallbacks
-
-Method Fallback
--------------- -----------------------------------------------------
-PUBLISH Required
-REQUEST PUBLISH
-REPLY Required
-ADD Required
-CANCEL Required
-REFRESH Required
-COUNTER Reply with Not Supported
-DECLINECOUNTER Required if EVENT-COUNTER is implemented; otherwise
- reply with Not Supported
-
-iCalendar
-Property Fallback
--------------- -----------------------------------------------------
-CALSCALE Ignore; assume GREGORIAN
-PRODID Ignore
-METHOD Required as described in the Method list above
-VERSION Ignore
-
-
-
-
-Silverberg, et. al. Standards Track [Page 97]
-
-RFC 2446 iTIP November 1998
-
-
-Event-Related
-Components Fallback
--------------- -----------------------------------------------------
-VALARM Reply with Not Supported
-VTIMEZONE Required if any DateTime value refers to a time zone.
-
-Component
-Property Fallback
--------------- -----------------------------------------------------
-ATTACH Ignore
-ATTENDEE Required if EVENT-REQUEST is not implemented;
- otherwise reply with Not Supported
-CATEGORIES Ignore
-CLASS Ignore
-COMMENT Ignore
-COMPLETED Ignore
-nCONTACT Ignore
-CREATED Ignore
-DESCRIPTION Required
-DURATION Reply with Not Supported
-DTSTAMP Required
-DTSTART Required
-DTEND Required
-EXDATE Ignore
-EXRULE Ignore Reply with Not Supported. If implemented,
- VTIMEZONE MUST also be implemented.
-GEO Ignore
-LAST-MODIFIED Ignore
-LOCATION Required
-ORGANIZER Ignore
-PRIORITY Ignore
-RELATED-TO Ignore
-RDATE Ignore
-RRULE Ignore. The first instance occurs on the DTStart
- property. If implemented, VTIMEZONE MUST also be
- implemented.
-RECURRENCE-ID Required if RRULE is implemented; otherwise Ignore
-REQUEST-STATUS Required
-RESOURCES Ignore
-SEQUENCE Required
-STATUS Ignore
-SUMMARY Ignore
-TRANSP Required if FREEBUSY is implemented; otherwise Ignore
-URL Ignore
-UID Required
-X- Ignore
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 98]
-
-RFC 2446 iTIP November 1998
-
-
-5.1.2 Free/Busy-Related Fallbacks
-
-Method Fallback
--------------- -----------------------------------------------------
-PUBLISH Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-REQUEST Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-REPLY Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-
-
-iCalendar
-Property Fallback
--------------- -----------------------------------------------------
-CALSCALE Ignore; assume GREGORIAN.
-PRODID Ignore
-METHOD Required as described in the Method list above.
-VERSION Ignore
-
-
-Component
-Property Fallback
--------------- -----------------------------------------------------
-COMMENT Ignore
-CONTACT Ignore
-DTEND Required
-DTSTAMP Required
-DTSTART Required
-DURATION Required
-FREEBUSY Required
-ORGANIZER Ignore
-REQUEST-STATUS Ignore
-UID Required
-URL Ignore
-X- Ignore
-
-5.1.3 To-Do-Related Fallbacks
-
-Method Fallback
--------------- -----------------------------------------------------
-PUBLISH Required
-REQUEST PUBLISH
-REPLY Required
-ADD Required
-
-
-
-Silverberg, et. al. Standards Track [Page 99]
-
-RFC 2446 iTIP November 1998
-
-
-CANCEL Required
-REFRESH Required
-COUNTER Reply with Not Supported
-DECLINECOUNTER Required if VTODO - COUNTER is implemented; otherwise
- reply with Not Supported
-
-iCalendar
-Property Fallback
--------------- -----------------------------------------------------
-CALSCALE Ignore; assume GREGORIAN.
-PRODID Ignore
-METHOD Required as described in the Method list above.
-VERSION Ignore
-
-
-To-Do-Related
-Components Fallback
--------------- -----------------------------------------------------
-VALARM Reply with Not Supported
-VTIMEZONE Required if any DateTime value refers to a time zone.
-
-
-Component
-Property Fallback
--------------- -----------------------------------------------------
-ATTACH Ignore
-ATTENDEE Required if REQUEST is not implemented; otherwise
- ignore
-CATEGORIES Ignore
-CLASS Ignore
-COMMENT Ignore
-COMPLETED Required
-CONTACT Ignore
-CREATED Ignore
-DESCRIPTION Required
-DUE Required
-DURATION Ignore Reply with Not Supported
-DTSTAMP Required
-DTSTART Required
-EXDATE Ignore Reply with Not Supported
-EXRULE Ignore Reply with Not Supported. If implemented,
- VTIMEZONE MUST also be implemented.
-LAST-MODIFIED Ignore
-LOCATION Ignore
-ORGANIZER Ignore
-PERCENT-COMPLETE Ignore
-PRIORITY Required
-RECURRENCE-ID Ignore
-
-
-
-Silverberg, et. al. Standards Track [Page 100]
-
-RFC 2446 iTIP November 1998
-
-
-RELATED-TO Ignore
-REQUEST-STATUS Ignore
-RDATE Ignore
-RRULE Ignore. The first instance occurs on the DTSTART
- property. If implemented, VTIMEZONE MUST also be
- implemented.
-RESOURCES Ignore
-SEQUENCE Required
-STATUS Required
-SUMMARY Ignore
-URL Ignore
-UID Required
-X- Ignore
-
-5.1.4 Journal-Related Fallbacks
-
-
-Method Fallback
--------------- -----------------------------------------------------
-PUBLISH Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-ADD Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-CANCEL Implementations MAY ignore the METHOD type. The
- REQUEST-STATUS "3.14;Unsupported capability" MUST be
- returned.
-
-
-iCalendar
-Property Fallback
--------------- -----------------------------------------------------
-CALSCALE Ignore; assume GREGORIAN.
-PRODID Ignore
-METHOD Required as described in the Method list above.
-VERSION Ignore
-
-
-Journal-Related
-Components Fallback
--------------- -----------------------------------------------------
-VTIMEZONE Required if any DateTime value refers to a time zone.
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 101]
-
-RFC 2446 iTIP November 1998
-
-
-Component
-Property Fallback
--------------- -----------------------------------------------------
-ATTACH Ignore
-ATTENDEE Required if JOURNAL-REQUEST is implemented; otherwise
- ignore
-CATEGORIES Ignore
-CLASS Ignore
-COMMENT Ignore
-CONTACT Ignore
-CREATED Ignore
-DESCRIPTION Required
-DTSTAMP Required
-DTSTART Required
-EXDATE Ignore
-EXRULE Ignore Reply with Not Supported. If implemented,
- VTIMEZONE MUST also be implemented.
-LAST-MODIFIED Ignore
-ORGANIZER Ignore
-RECURRENCE-ID Ignore
-RELATED-TO Ignore
-RDATE Ignore.
-RRULE Ignore. The first instance occurs on the DTSTART
- property. If implemented, VTIMEZONE MUST also be
- implemented.
-SEQUENCE Required
-STATUS Ignore
-SUMMARY Required
-URL Ignore
-UID Required
-X- Ignore
-
-5.2 Latency Issues
-
- With a store-and-forward transport, it is possible for events to
- arrive out of sequence. That is, a "CANCEL" method may be received
- prior to receiving the associated "REQUEST" for the calendar
- component. This section discusses a few of these scenarios.
-
-5.2.1 Cancellation of an Unknown Calendar Component.
-
- When a "CANCEL" method is received before the original "REQUEST"
- method the calendar will be unable to correlate the "UID" property of
- the cancellation with an existing calendar component. It is suggested
- that messages that can not be correlated that also contain non-zero
- sequence numbers be held and not discarded. Implementations MAY age
- them out if no other messages arrive with the same "UID" property
- value and a lower sequence number.
-
-
-
-Silverberg, et. al. Standards Track [Page 102]
-
-RFC 2446 iTIP November 1998
-
-
-5.2.2 Unexpected Reply from an Unknown Delegate
-
- When an "Attendee" delegates an item to another CU they MUST send a
- "REPLY" method to the "Organizer" using the "ATTENDEE" properties to
- indicate that the request was delegated and to whom. Hence, it is
- possible for an "Organizer" to receive an "REPLY" from a CU not
- listed as one of the original "Attendees". The resolution is left to
- the implementation but it is expected that the calendaring software
- will either accept the reply or hold it until the related "REPLY"
- method is received from the "Delegator". If the version of the
- "REPLY" method is out of date the "Organizer" SHOULD treat the
- message as a "REFRESH" message and update the delegate with the
- correct version.
-
-5.3 Sequence Number
-
- Under some conditions, a CUA may receive requests and replies with
- the same "SEQUENCE" property value. The "DTSTAMP" property is
- utilized as a tie-breaker when two items with the same "SEQUENCE"
- property value are evaluated.
-
-6 Security Considerations
-
- ITIP is an abstract transport protocol which will be bound to a
- real-time transport, a store-and-forward transport, and perhaps other
- transports. The transport protocol will be responsible for providing
- facilities for authentication and encryption using standard Internet
- mechanisms that are mutually understood between the sender and
- receiver.
-
-6.1 Security Threats
-
-6.1.1 Spoofing the "Organizer"
-
- In iTIP, the "Organizer" (or someone working on the "Organizer's"
- behalf) is the only person authorized to make changes to an existing
- "VEVENT", "VTODO", "VJOURNAL" calendar component and republish it or
- redistribute updates to the "Attendees". An iCalendar object that
- maliciously changes or cancels an existing "VEVENT", "VTODO" or
- "VJOURNAL" calendar component may be constructed by someone other
- than the "Organizer" and republished or sent to the "Attendees".
-
-6.1.2 Spoofing the "Attendee"
-
- In iTIP, an "Attendee" of a "VEVENT" or "VTODO" calendar component
- (or someone working on the "Attendee's" behalf) is the only person
- authorized to update any parameter associated with their "ATTENDEE"
- property and send it to the "Organizer". An iCalendar object that
-
-
-
-Silverberg, et. al. Standards Track [Page 103]
-
-RFC 2446 iTIP November 1998
-
-
- maliciously changes the "ATTENDEE" parameters may be constructed by
- someone other than the real "Attendee" and sent to the "Organizer".
-
-6.1.3 Unauthorized Replacement of the Organizer
-
- There will be circumstances when "Attendees" of an event or to-do
- decide, using out-of-band mechanisms, that the "Organizer" must be
- replaced. When the new "Organizer" sends out the updated "VEVENT" or
- "VTODO" the "Attendee's" CUA will detect that the "Organizer" has
- been changed, but it has no way of knowing whether or not the change
- was mutually agreed upon.
-
-6.1.4 Eavesdropping
-
- The iCalendar object is constructed with human-readable clear text.
- Any information contained in an iCalendar object may be read and/or
- changed by unauthorized persons while the object is in transit.
-
-6.1.5 Flooding a Calendar
-
- Implementations MAY provide a means to automatically incorporate
- "REQUEST" methods into a calendar. This presents the opportunity for
- a calendar to be flooded with requests, which effectively block all
- the calendar's free time.
-
-6.1.6 Procedural Alarms
-
- The "REQUEST" methods for "VEVENT" and "VTODO" calendar components
- MAY contain "VALARM" calendar components. The "VALARM" calendar
- component may be of type "PROCEDURE" and MAY have an attachment
- containing an executable program. Implementations that incorporate
- these types of alarms are subject to any virus or malicious attack
- that may occur as a result of executing the attachment.
-
-6.1.7 Unauthorized REFRESH Requests
-
- It is possible for an "Organizer" to receive a "REFRESH" request from
- someone who is not an "Attendee" of an event or to-do. Only
- "Attendee's" of an event or to-do are authorized to receive replies
- to "REFRESH" requests. Replying to such requests to anyone who is not
- an "Attendee" may be a security problem.
-
-6.2 Recommendations
-
- For an application where the information is sensitive or critical and
- the network is subject is subject to a high probability of attack,
- iTIP transactions SHOULD be encrypted. This may be accomplished using
- public key technology, specifically Security Multiparts for MIME
-
-
-
-Silverberg, et. al. Standards Track [Page 104]
-
-RFC 2446 iTIP November 1998
-
-
- [RFC-1847] in the iTIP transport binding. This helps mitigate the
- threats of spoofing, eavesdropping and malicious changes in transit.
-
-6.2.1 Use of [RFC-1847] to secure iTIP transactions
-
- iTIP transport bindings MUST provide a mechanism based on Security
- Multiparts for MIME [RFC-1847] to enable authentication of the
- sender's identity, and privacy and integrity of the data being
- transmitted. This allows the receiver of a signed iCalendar object to
- verify the identity of the sender. This sender may then be correlated
- to an "ATTENDEE" property in the iCalendar object. If the correlation
- is made and the sender is authorized to make the requested change or
- update then the operation may proceed. It also allows the message to
- be encrypted to prevent unauthorized reading of the message contents
- in transit. iTIP transport binding documents describe this process in
- detail.
-
- Implementations MAY provide controls for users to disable this
- capability.
-
-6.2.2 Implementation Controls
-
- The threat of unauthorized replacement of the "Organizer" SHOULD be
- mitigated by a calendar system that uses this protocol by providing
- controls or alerts that make "Calendar Users" aware of such
- "Organizer" changes and allowing them to decide whether or not the
- request should be honored.
-
- The threat of flooding a calendar SHOULD be mitigated by a calendar
- system that uses this protocol by providing controls that may be used
- to limit the acceptable sources for iTIP transactions, and perhaps
- the size of messages and volume of traffic, by source.
-
- The threat of malicious procedural alarms SHOULD be mitigated by a
- calendar system that uses this protocol by providing controls that
- may be used to disallow procedural alarms in iTIP transactions and/or
- remove all alarms from the object before delivery to the recipient.
-
- The threat of unauthorized "REFRESH" requests SHOULD be mitigated by
- a calendar system that uses this protocol by providing controls or
- alerts that allow "Calendar User" to decide whether or not the
- request should be honored. An implementation MAY decide to maintain,
- for audit or historical purposes, "Calendar Users" who were part of
- an attendee list and who were subsequently uninvited. Similar
- controls or alerts should be provided when a "REFRESH" request is
- received from these "Calendar Users" as well.
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 105]
-
-RFC 2446 iTIP November 1998
-
-
-7 Acknowledgments
-
- A hearty thanks to the following individuals who have participated in
- the drafting, review and discussion of this memo:
-
- Anik Ganguly, Dan Hickman, Paul Hill, Daryl Huff, Bruce Kahn, Antoine
- Leca, Bob Mahoney, John Noerenberg, Leo Parker, John Rose, Doug
- Royer, Vinod Seraphin, Richard Shusterman, Derik Stenerson, John Sun,
- Alexander Taler, Kevin Tsurutome.
-
-8 Bibliography
-
- [iCAL] Dawson, F. and D. Stenerson, "Internet Calendaring and
- Scheduling Core Object Specification - iCalendar", RFC
- 2445, November 1998.
-
- [iMIP] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
- Message-Based Interoperability Protocol - iMIP", RFC 2447,
- November 1998.
-
- [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [US-ASCII] Coded Character Set--7-bit American Standard Code for
- Information Interchange, ANSI X3.4-1986.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 106]
-
-RFC 2446 iTIP November 1998
-
-
-9 Authors' Addresses
-
- The following address information is provided in a vCard v3.0,
- Electronic Business Card, format.
-
- The authors of this memo are:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Dawson;Frank
- FN:Frank Dawson
- ORG:Lotus Development Corporation
- ADR;WORK;POSTAL;PARCEL:;;6544 Battleford Drive;Raleigh;NC;27613-
- 3502;USA
- TEL;TYPE=WORK,MSG:+1-919-676-9515
- TEL;TYPE=WORK,FAX:+1-919-676-9564
- EMAIL;TYPE=PREF,INTERNET:Frank_Dawson at Lotus.com
- EMAIL;TYPE=INTERNET:fdawson at earthlink.net
- URL:http://home.earthlink.net/~fdawson
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Hopson;Ross
- FN:Ross Hopson
- ORG:On Technology, Inc.
- ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 1600;434 Fayetteville St.
- Mall\, Two Hannover Square;Raleigh;NC;27601
- TEL;TYPE=WORK,MSG:+1-919-890-4036
- TEL;TYPE=WORK,FAX:+1-919-890-4100
- EMAIL;TYPE=INTERNET:rhopson at on.com
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Mansour;Steve
- FN:Steve Mansour
- ORG:Netscape Communications Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;501 East Middlefield Road;Mountain
- View;CA;94043;USA
- TEL;TYPE=WORK,MSG:+1-650-937-2378
- TEL;TYPE=WORK,FAX:+1-650-937-2103
- EMAIL;TYPE=INTERNET:sman at netscape.com
- END:VCARD
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 107]
-
-RFC 2446 iTIP November 1998
-
-
- BEGIN:VCARD
- VERSION:3.0
- N:Silverberg;Steve
- FN:Steve Silverberg
- ORG:Microsoft Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
- Redmond;WA;98052-6399;USA
- TEL;TYPE=WORK,MSG:+1-425-936-9277
- TEL;TYPE=WORK,FAX:+1-425-936-8019
- EMAIL;INTERNET:stevesil at Microsoft.com
- END:VCARD
-
- The iCalendar object is a result of the work of the Internet
- Engineering Task Force Calendaring and scheduling Working Group. The
- chairman of that working group is:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Ganguly;Anik
- FN:Anik Ganguly
- ORG:Open Text Inc.
- ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
- Livonia;MI;48152;USA
- TEL;TYPE=WORK,MSG:+1-734-542-5955
- EMAIL;TYPE=INTERNET:ganguly at acm.org
- END:VCARD
-
- The co-chairman of that working group is:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Moskowitz;Robert
- FN:Robert Moskowitz
- NICKNAME:Bob
- EMAIL; TYPE=INTERNET:rgm-ietf at htt-consult.com
- END:VCARD
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 108]
-
-RFC 2446 iTIP November 1998
-
-
-10. Full Copyright Statement
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Silverberg, et. al. Standards Track [Page 109]
-
Copied: CalendarServer/trunk/doc/RFC/rfc2447-iMIP.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2447.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2447-iMIP.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2447-iMIP.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,1011 @@
+
+
+
+
+
+
+Network Working Group F. Dawson
+Request for Comments: 2447 Lotus
+Category: Standards Track S. Mansour
+ Netscape
+ S. Silverberg
+ Microsoft
+ November 1998
+
+
+ iCalendar Message-Based Interoperability Protocol
+ (iMIP)
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ This document, [iMIP], specifies a binding from the iCalendar
+ Transport-independent Interoperability Protocol (iTIP) to Internet
+ email-based transports. Calendaring entries defined by the iCalendar
+ Object Model [iCAL] are composed using constructs from [RFC-822],
+ [RFC-2045], [RFC-2046], [RFC-2047], [RFC-2048] and [RFC-2049].
+
+ This document is based on discussions within the Internet Engineering
+ Task Force (IETF) Calendaring and Scheduling (CALSCH) working group.
+ More information about the IETF CALSCH working group activities can
+ be found on the IMC web site at http://www.imc.org, the IETF web site
+ at http://www.ietf.org/html.charters/calsch-charter.html. Refer to
+ the references within this document for further information on how to
+ access these various documents.
+
+
+
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 1]
+
+RFC 2447 iMIP November 1998
+
+
+Table of Contents
+
+ 1 INTRODUCTION........................................................2
+ 1.1 RELATED MEMOS ...................................................2
+ 1.2 FORMATTING CONVENTIONS ..........................................3
+ 1.3 TERMINOLOGY .....................................................4
+ 2 MIME MESSAGE FORMAT BINDING.........................................4
+ 2.1 MIME MEDIA TYPE .................................................4
+ 2.2 SECURITY ........................................................4
+ 2.2.1 Authorization ...............................................4
+ 2.2.2 Authentication ..............................................5
+ 2.2.3 Confidentiality .............................................5
+ 2.3 [RFC-822] ADDRESSES .............................................5
+ 2.4 CONTENT TYPE ....................................................5
+ 2.5 CONTENT-TRANSFER-ENCODING .......................................6
+ 2.6 CONTENT-DISPOSITION .............................................6
+ 3 SECURITY CONSIDERATIONS.............................................7
+ 4 EXAMPLES............................................................8
+ 4.1 SINGLE COMPONENT WITH AN ATTACH PROPERTY ........................8
+ 4.2 USING MULTIPART ALTERNATIVE FOR LOW FIDELITY CLIENTS ............8
+ 4.3 SINGLE COMPONENT WITH AN ATTACH PROPERTY AND INLINE ATTACHMENT ..9
+ 4.4 MULTIPLE SIMILAR COMPONENTS ....................................10
+ 4.5 MULTIPLE MIXED COMPONENTS ......................................11
+ 4.6 DETAILED COMPONENTS WITH AN ATTACH PROPERTY ....................13
+ 5 RECOMMENDED PRACTICES..............................................14
+ 5.1 USE OF CONTENT AND MESSAGE IDS .................................14
+ 6 BIBLIOGRAPHY.......................................................15
+ 7 AUTHORS' ADDRESSES.................................................16
+ 8 FULL COPYRIGHT STATEMENT...........................................18
+
+1 Introduction
+
+ This binding document provides the transport specific information
+ necessary convey iCalendar Transport-independent Interoperability
+ Protocol (iTIP) over MIME as defined in [RFC-822] and [RFC-2045].
+
+1.1 Related Memos
+
+ Implementers will need to be familiar with several other memos that,
+ along with this memo, form a framework for Internet calendaring and
+ scheduling standards.
+
+ This document, [iMIP], specifies an Internet email binding for iTIP.
+
+ [iCAL] - specifies a core specification of objects, data types,
+ properties and property parameters;
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 2]
+
+RFC 2447 iMIP November 1998
+
+
+ [iTIP] - specifies an interoperability protocol for scheduling
+ between different implementations;
+
+ This memo does not attempt to repeat the specification of concepts or
+ definitions from these other memos. Where possible, references are
+ made to the memo that provides for the specification of these
+ concepts or definitions.
+
+1.2 Formatting Conventions
+
+ The mechanisms defined in this memo are defined in prose. In order to
+ refer to elements of the calendaring and scheduling model, core
+ object or interoperability protocol defined in [iCAL] and [iTIP] some
+ formatting conventions have been used.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC-2119].
+
+ Calendaring and scheduling roles are referred to in quoted-strings of
+ text with the first character of each word in upper case. For
+ example, "Organizer" refers to a role of a "Calendar User" within the
+ scheduling protocol defined by [iTIP].
+
+ Calendar components defined by [iCAL] are referred to with
+ capitalized, quoted-strings of text. All calendar components start
+ with the letter "V". For example, "VEVENT" refers to the event
+ calendar component, "VTODO" refers to the to-do calendar component
+ and "VJOURNAL" refers to the daily journal calendar component.
+
+ Scheduling methods defined by [iTIP] are referred to with
+ capitalized, quoted-strings of text. For example, "REQUEST" refers to
+ the method for requesting a scheduling calendar component be created
+ or modified, "REPLY" refers to the method a recipient of a request
+ uses to update their status with the "Organizer" of the calendar
+ component.
+
+ Properties defined by [iCAL] are referred to with capitalized,
+ quoted-strings of text, followed by the word "property". For example,
+ "ATTENDEE" property refers to the iCalendar property used to convey
+ the calendar address of a calendar user.
+
+ Property parameters defined by [iCAL] are referred to with lower
+ case, quoted-strings of text, followed by the word "parameter". For
+ example, "value" parameter refers to the iCalendar property parameter
+ used to override the default data type for a property value.
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 3]
+
+RFC 2447 iMIP November 1998
+
+
+1.3 Terminology
+
+ The email terms used in this memo are defined in [RFC-822] and [RFC-
+ 2045]. The calendaring and scheduling terms used in this memo are
+ defined in [iCAL] and [iTIP].
+
+2 MIME Message Format Binding
+
+ This section defines the message binding to the MIME electronic mail
+ transport.
+
+ The sections below refer to the "originator" and the "respondent" of
+ an iMIP message. Typically, the originator is the "Organizer" of an
+ event. The respondent is an "Attendee" of the event.
+
+ The [RFC-822] "Reply-To" header typically contains the email address
+ of the originator or respondent of an event. However, this cannot be
+ guaranteed as Mail User Agents (MUA) are not required to enforce iMIP
+ semantics.
+
+2.1 MIME Media Type
+
+ A MIME entity containing content information formatted according to
+ this document will be referenced as a "text/calendar" content type.
+ It is assumed that this content type will be transported through a
+ MIME electronic mail transport.
+
+2.2 Security
+
+ This section addresses several aspects of security including
+ Authentication, Authorization and Confidentiality. Authentication and
+ confidentiality can be achieved using [RFC-1847] that specifies the
+ Security Multiparts for MIME. This framework defines new content
+ types and subtypes of multipart: signed and encrypted. Each contains
+ two body parts: one for the protected data and another for the
+ control information necessary to remove the protection.
+
+2.2.1 Authorization
+
+ In [iTIP] messages, only the "Organizer" is authorized to modify or
+ cancel calendar entries they organize. That is, spoof at xyz.com is not
+ allowed to modify or cancel a meeting that was organized by
+ a at example.com. Furthermore, only the respondent has the authorization
+ to indicate their status to the "Organizer". That is, the "Organizer"
+ must ignore an [iTIP] message from spoof at xyz.com that declines a
+ meeting invitation for b at example.com.
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 4]
+
+RFC 2447 iMIP November 1998
+
+
+ Implementations of iMIP SHOULD verify the authenticity of the creator
+ of an iCalendar object before taking any action. The methods for
+ doing this are presented later in this document.
+
+ [RFC-1847] Message flow in iTIP supports someone working on behalf of
+ a "Calendar User" through use of the "sent-by" parameter that is
+ associated with the "ATTENDEE" and "ORGANIZER" properties. However,
+ there is no mechanism to verify whether or not a "Calendar User" has
+ authorized someone to work on their behalf. It is left to
+ implementations to provide mechanisms for the "Calendar Users" to
+ make that decision.
+
+2.2.2 Authentication
+
+ Authentication can be performed using an implementation of [RFC-1847]
+ "multipart/signed" that supports public/private key certificates.
+ Authentication is possible only on messages that have been signed.
+ Authenticating an unsigned message may not be reliable.
+
+2.2.3 Confidentiality
+
+ To ensure confidentiality using iMIP implementations should utilize
+ [RFC-1847]-compliant encryption. The protocol does not restrict a
+ "Calendar User Agent" (CUA) from forwarding iCalendar objects to
+ other users or agents.
+
+2.3 [RFC-822] Addresses
+
+ The calendar address specified within the "ATTENDEE" property in an
+ iCalendar object MUST be a fully qualified, [RFC-822] address
+ specification for the corresponding "Organizer" or "Attendee" of the
+ "VEVENT" or "VTODO".
+
+ Because [iTIP] does not preclude "Attendees" from forwarding
+ "VEVENTS" or "VTODOS" to others, the [RFC-822] "Sender" value may not
+ equal that of the "Organizer". Additionally, the "Organizer" or
+ "Attendee" cannot be reliably inferred by the [RFC-822] "Sender" or
+ "Reply-to" values of an iMIP message. The relevant address MUST be
+ ascertained by opening the "text/calendar" MIME body part and
+ examining the "ATTENDEE" and "ORGANIZER" properties.
+
+2.4 Content Type
+
+ A MIME body part containing content information that conforms to this
+ document MUST have an [RFC-2045] "Content-Type" value of
+ "text/calendar". The [RFC-2045] "Content-Type" header field must also
+ include the type parameter "method". The value MUST be the same as
+ the value of the "METHOD" calendar property within the iCalendar
+
+
+
+Dawson, et. al. Standards Track [Page 5]
+
+RFC 2447 iMIP November 1998
+
+
+ object. This means that a MIME message containing multiple iCalendar
+ objects with different method values must be further encapsulated
+ with a "multipart/mixed" MIME entity. This will allow each of the
+ iCalendar objects to be encapsulated within their own "text/calendar"
+ MIME entity.
+
+ A "charset" parameter MUST be present if the iCalendar object
+ contains characters that are not part of the US-ASCII character set.
+ [RFC-2046] discusses the selection of an appropriate "charset" value.
+
+ The optional "component" parameter defines the iCalendar component
+ type contained within the iCalendar object.
+
+ The following is an example of this header field with a value that
+ indicates an event message.
+
+ Content-Type:text/calendar; method=request; charset=UTF-8;
+ component=vevent
+
+ The "text/calendar" content type allows for the scheduling message
+ type to be included in a MIME message with other content information
+ (i.e., "multipart/mixed") or included in a MIME message with a
+ clear-text, human-readable form of the scheduling message (i.e.,
+ "multipart/alternative").
+
+ In order to permit the information in the scheduling message to be
+ understood by MIME user agents (UA) that do not support the
+ "text/calendar" content type, scheduling messages SHOULD be sent with
+ an alternative, human-readable form of the information.
+
+2.5 Content-Transfer-Encoding
+
+ Note that the default character set for iCalendar objects is UTF-8. A
+ transfer encoding SHOULD be used for iCalendar objects containing any
+ characters that are not part of the US-ASCII character set.
+
+2.6 Content-Disposition
+
+ The handling of a MIME part should be based on its [RFC-2045]
+ "Content-Type". However, this is not guaranteed to work in all
+ environments. Some environments handle MIME attachments based on
+ their file type or extension. To operate correctly in these
+ environments, implementations may wish to include a "Content-
+ Disposition" property to define a file name.
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 6]
+
+RFC 2447 iMIP November 1998
+
+
+3 Security Considerations
+
+ The security threats that applications must address when implementing
+ iTIP are detailed in [iTIP]. Two spoofing threats are identified:
+ Spoofing the "Organizer", and Spoofing an "Attendee". To address
+ these threats, the originator of an iCalendar object must be
+ authenticated by a recipient. Once authenticated, a determination can
+ be made as to whether or not the originator is authorized to perform
+ the requested operation. Compliant applications MUST support signing
+ and encrypting text/calendar attachments using a mechanism based on
+ Security Multiparts for MIME [RFC-1847] to facilitate the
+ authentication the originator of the iCalendar object.
+ Implementations MAY provide a means for users to disable signing and
+ encrypting. The steps are described below:
+
+ 1. The iCalendar object MUST be signed by the "Organizer" sending an
+ update or the "Attendee" sending a reply.
+
+ 2. Using the [RFC-1847]-compliant security mechanism, determine who
+ signed the iCalendar object. This is the "signer". Note that the
+ signer is not necessarily the person sending an e-mail message since
+ an e-mail message can be forwarded.
+
+ 3. Correlate the signer to an "ATTENDEE" property in the iCalendar
+ object. If the signer cannot be correlated to an "ATTENDEE" property,
+ ignore the message.
+
+ 4. Determine whether or not the "ATTENDEE" is authorized to perform
+ the operation as defined by [iTIP]. If the conditions are not met,
+ ignore the message.
+
+ 5. If all the above conditions are met, the message can be processed.
+
+ To address the confidentiality security threats, signed iMIP messages
+ SHOULD be encrypted by a mechanism based on Security Multiparts for
+ MIME [RFC-1847].
+
+ It is possible to receive iMIP messages sent by someone working on
+ behalf of another "Calendar User". This is determined by examining
+ the "sent-by" parameter in the relevant "ORGANIZER" or "ATTENDEE"
+ property. [iCAL] and [iTIP] provide no mechanism to verify that a
+ "Calendar User" has authorized someone else to work on their behalf.
+ To address this security issue, implementations MUST provide
+ mechanisms for the "Calendar Users" to make that decision before
+ applying changes from someone working on behalf of a "Calendar User".
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 7]
+
+RFC 2447 iMIP November 1998
+
+
+4 Examples
+
+4.1 Single Component With An ATTACH Property
+
+ This minimal message shows how an iCalendar object references an
+ attachment. The attachment is accessible via its URL.
+
+ From: sman at netscape.com
+ To: stevesil at microsoft.com
+ Subject: Phone Conference
+ Mime-Version: 1.0
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
+ Content-Transfer-Encoding: 7bit
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:sman at netscape.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:sman at netscape.com
+ ATTENDEE;RSVP=YES:mailto:stevesil at microsoft.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T210000Z
+ DTEND:19970701T230000Z
+ SUMMARY:Phone Conference
+ DESCRIPTION:Please review the attached document.
+ UID:calsvr.example.com-873970198738777
+ ATTACH:ftp://ftp.bar.com/pub/docs/foo.doc
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.2 Using Multipart Alternative for Low Fidelity Clients
+
+ This example shows how a client can emit a multipart message that
+ includes both a plain text version as well as the full iCalendar
+ object. Clients that do not support text/calendar will still be
+ capable of rendering the plain text representation.
+
+ From: foo1 at example.com
+ To: foo2 at example.com
+ Subject: Phone Conference
+ Mime-Version: 1.0
+ Content-Type: multipart/alternative;boundary="01BD3665.3AF0D360"
+
+ --01BD3665.3AF0D360
+ Content-Type: text/plain;charset=us-ascii
+
+
+
+Dawson, et. al. Standards Track [Page 8]
+
+RFC 2447 iMIP November 1998
+
+
+ Content-Transfer-Encoding: 7bit
+
+ This is an alternative representation of a TEXT/CALENDAR MIME Object
+ When: 7/1/1997 10:00AM PDT - 7/1/97 10:30AM PDT
+ Where:
+ Organizer: foo1 at example.com
+ Summary: Phone Conference
+
+ --01BD3665.3AF0D360
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
+ Content-Transfer-Encoding: 7bit
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:foo1 at example.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
+ ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T170000Z
+ DTEND:19970701T173000Z
+ SUMMARY:Phone Conference
+ UID:calsvr.example.com-8739701987387771
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ --01BD3665.3AF0D360
+
+4.3 Single Component With An ATTACH Property and Inline Attachment
+
+ This example shows how a message containing an iCalendar object
+ references an attached document. The reference is made using a
+ Content-id (CID). Thus, the iCalendar object and the document are
+ packaged in a multipart/related encapsulation.
+
+ From: foo1 at example.com
+ To: foo2 at example.com
+ Subject: Phone Conference
+ Mime-Version: 1.0
+ Content-Type: multipart/related; boundary="boundary-example-1";
+ type=text/calendar
+
+ --boundary-example-1
+
+
+
+
+Dawson, et. al. Standards Track [Page 9]
+
+RFC 2447 iMIP November 1998
+
+
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
+ Content-Transfer-Encoding: 7bit
+ Content-Disposition: attachment; filename="event.vcs"
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:foo1 at example.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
+ ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T180000Z
+ DTEND:19970701T183000Z
+ SUMMARY:Phone Conference
+ UID:calsvr.example.com-8739701987387771
+ ATTACH:cid:123456789 at example.com
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ --boundary-example-1
+ Content-Type: application/msword; name="FieldReport.doc"
+ Content-Transfer-Encoding: base64
+ Content-Disposition: inline; filename="FieldReport.doc"
+ Content-ID: <123456789 at example.com>
+
+ 0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAABAAAARAAAAAAA
+ AAAAEAAAQAAAAAEAAAD+////AAAAAEUAAAD/////////////////////////////////
+
+ --boundary-example-1--
+
+4.4 Multiple Similar Components
+
+ Multiple iCalendar components of the same type can be included in the
+ iCalendar object when the METHOD is the same for each component.
+
+ From: foo1 at example.com
+ To: foo2 at example.com
+ Subject: Summer Company Holidays
+ Mime-Version: 1.0
+ Content-Type:text/calendar; method=PUBLISH; charset=US-ASCII
+ Content-Transfer-Encoding: 7bit
+ Content-Disposition: attachment; filename="event.vcs"
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 10]
+
+RFC 2447 iMIP November 1998
+
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DESKTOPCALENDAR//EN
+ METHOD:PUBLISH
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:FOO1 at EXAMPLE.COM
+ DTSTAMP:19970611T150000Z
+ DTSTART:19970701T150000Z
+ DTEND:19970701T230000Z
+ SUMMARY:Company Picnic
+ DESCRIPTION:Food and drink will be provided
+ UID:CALSVR.EXAMPLE.COM-873970198738777-1
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ BEGIN:VEVENT
+ ORGANIZER:MAILTO:FOO1 at EXAMPLE.COM
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970715T150000Z
+ DTEND:19970715T230000Z
+ SUMMARY:Company Bowling Tournament
+ DESCRIPTION:We have 10 lanes reserved
+ UID:CALSVR.EXAMPLE.COM-873970198738777-2
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+4.5 Multiple Mixed Components
+
+ Different component types must be encapsulated in separate iCalendar
+ objects.
+
+ From: foo1 at example.com
+ To: foo2 at example.com
+ Subject: Phone Conference
+ Mime-Version: 1.0
+ Content-Type:multipart/mixed;boundary="--FEE3790DC7E35189CA67CE2C"
+
+ This is a multi-part message in MIME format.
+
+ ----FEE3790DC7E35189CA67CE2C
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
+ Content-Transfer-Encoding: 7bit
+ Content-Disposition: attachment; filename="event1.vcs"
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 11]
+
+RFC 2447 iMIP November 1998
+
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:mailto:foo1 at example.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
+ ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970701T210000Z
+ DTEND:19970701T230000Z
+ SUMMARY:Phone Conference
+ DESCRIPTION:Discuss what happened at the last meeting
+ UID:calsvr.example.com-8739701987387772
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ ----FEE3790DC7E35189CA67CE2C
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
+ Content-Transfer-Encoding:7bit
+ Content-Disposition: attachment; filename="todo1.vcs"
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ METHOD:REQUEST
+ VERSION:2.0
+ BEGIN:VTODO
+ DUE:19970701T090000-0700
+ ORGANIZER:mailto:foo1 at example.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
+ ATTENDEE;RSVP=YES:mailto:foo2 at example.com
+ SUMMARY:Phone Conference
+ DESCRIPTION:Discuss a new location for the company picnic
+ UID:calsvr.example.com-td-8739701987387773
+ SEQUENCE:0
+ STATUS:NEEDS ACTION
+ END:VEVENT
+ END:VCALENDAR
+
+ ----FEE3790DC7E35189CA67CE2C
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 12]
+
+RFC 2447 iMIP November 1998
+
+
+4.6 Detailed Components With An ATTACH Property
+
+ This example shows the format of a message containing a group meeting
+ between three individuals. The multipart/related encapsulation is
+ used because the iCalendar object contains an ATTACH property that
+ uses a CID to reference the attachment.
+
+ From: foo1 at example.com
+ MIME-Version: 1.0
+ To: foo2 at example.com,foo3 at example.com
+ Subject: REQUEST - Phone Conference
+ Content-Type:multipart/related;boundary="--FEE3790DC7E35189CA67CE2C"
+
+ ----FEE3790DC7E35189CA67CE2C
+ Content-Type: multipart/alternative;
+ boundary="--00FEE3790DC7E35189CA67CE2C00"
+
+ ----00FEE3790DC7E35189CA67CE2C00
+ Content-Type: text/plain; charset=us-ascii
+ Content-Transfer-Encoding: 7bit
+
+ When: 7/1/1997 10:00PM PDT- 7/1/97 10:30 PM PDT
+ Where:
+ Organizer: foo1 at example.com
+ Summary: Let's discuss the attached document
+
+ ----00FEE3790DC7E35189CA67CE2C00
+
+ Content-Type:text/calendar; method=REQUEST; charset=US-ASCII;
+ Component=vevent
+ Content-Transfer-Encoding: 7bit
+ Content-Disposition: attachment; filename="event.vcs"
+
+ BEGIN:VCALENDAR
+ PRODID:-//ACME/DesktopCalendar//EN
+ PROFILE:REQUEST
+ PROFILE-VERSION:1.0
+ VERSION:2.0
+ BEGIN:VEVENT
+ ORGANIZER:foo1 at example.com
+ ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:foo1 at example.com
+ ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
+ ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo3 at example.com
+ DTSTAMP:19970611T190000Z
+ DTSTART:19970621T170000Z
+ DTEND:199706211T173000Z
+ SUMMARY:Let's discuss the attached document
+ UID:calsvr.example.com-873970198738777-8aa
+
+
+
+Dawson, et. al. Standards Track [Page 13]
+
+RFC 2447 iMIP November 1998
+
+
+ ATTACH:cid:calsvr.example.com-12345aaa
+ SEQUENCE:0
+ STATUS:CONFIRMED
+ END:VEVENT
+ END:VCALENDAR
+
+ ----00FEE3790DC7E35189CA67CE2C00
+
+ ----FEE3790DC7E35189CA67CE2C
+ Content-Type: application/msword; name="FieldReport.doc"
+ Content-Transfer-Encoding: base64
+ Content-Disposition: inline; filename="FieldReport.doc"
+ Content-ID: <calsvr.example.com-12345aaa>
+
+
+ R0lGODdhTAQZAJEAAFVVVd3d3e4AAP///ywAAAAATAQZAAAC/5yPOSLhD6OctNqLs94XqAG
+ 4kiW5omm6sq27gvH8kzX9o1y+s73/g8MCofEovGITCoxKMbyCR16cNSq9YrNarfcrvdriIH
+ 5LL5jE6rxc3G+v2cguf0uv2Oz+v38L7/DxgoOKjURnjIIbe3yNjo+AgZWYVIWWl5iZnJY6J.
+
+ ----FEE3790DC7E35189CA67CE2C
+
+5 Recommended Practices
+
+ This section outlines a series of recommended practices when using a
+ messaging transport to exchange iCalendar objects.
+
+5.1 Use of Content and Message IDs
+
+ The [iCAL] specification makes frequent use of the URI for data types
+ in properties such as "DESCRIPTION", "ATTACH", "CONTACT" and others.
+ Two forms of URIs are Message ID (MID) and Content ID (CID). These
+ are defined in [RFC-2111]. Although [RFC-2111] allows referencing
+ messages or MIME body parts in other MIME entities or stores, it is
+ strongly recommended that iMIP implementations include all referenced
+ messages and body parts in a single MIME entity. Simply put, if an
+ iCalendar object contains CID or MID references to other messages or
+ body parts, implementations should ensure that these messages and/or
+ body parts are transmitted with the iCalendar object. If they are not
+ there is no guarantee that the receiving "CU" will have the access or
+ the authorization to view those objects.
+
+
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 14]
+
+RFC 2447 iMIP November 1998
+
+
+6 Bibliography
+
+ [CHST] Character Sets, ftp://ftp.isi.edu/in-
+ notes/iana/assignments/character-sets
+
+ [iCAL] Dawson, F. and D. Stenerson, "Internet Calendaring and
+ Scheduling Core Object Specification - iCalendar", RFC
+ 2445, November 1998.
+
+ [iTIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
+ "iCalendar Transport-Independent Interoperability Protocol
+ (iTIP): Scheduling Events, Busy Time, To-dos and Journal
+ Entries", RFC 2446, November 1998.
+
+ [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet
+ Text Messages", STD 11, RFC 822, August 1982.
+
+ [RFC-1847] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
+ "Security Multiparts for MIME: Multipart/Signed and
+ Multipart/Encrypted", RFC 1847, October 1995.
+
+ [RFC-2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) - Part One: Format of Internet Message
+ Bodies", RFC 2045, November 1996.
+
+ [RFC-2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) - Part Two: Media Types", RFC 2046,
+ November 1996.
+
+ [RFC-2047] Moore, K., "Multipurpose Internet Mail Extensions (MIME) -
+ Part Three: Message Header Extensions for Non-ASCII Text",
+ RFC 2047, November 1996.
+
+ [RFC-2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
+ Internet Mail Extensions (MIME) - Part Four: Registration
+ Procedures", RFC 2048, January 1997.
+
+ [RFC-2111] Levinson, E., "Content-ID and Message-ID Uniform Resource
+ Locators", RFC 2111, March 1997.
+
+ [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 15]
+
+RFC 2447 iMIP November 1998
+
+
+7 Authors' Addresses
+
+ The following address information is provided in a vCard v3.0,
+ Electronic Business Card, format.
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Dawson;Frank
+ FN:Frank Dawson
+ ORG:Lotus Development Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford
+ Drive;Raleigh;NC;27613-3502;USA
+ TEL;TYPE=WORK,MSG:+1-919-676-9515
+ TEL;TYPE=WORK,FAX:+1-919-676-9564
+ EMAIL;TYPE=INTERNET:fdawson at earthlink.net
+ URL:http://home.earthlink.net/~fdawson
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Mansour;Steve
+ FN:Steve Mansour
+ ORG:Netscape Communications Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;501 East Middlefield Road;Mountain
+ View;CA;94043;USA
+ TEL;TYPE=WORK,MSG:+1-650-937-2378
+ TEL;TYPE=WORK,FAX:+1-650-937-2103
+ EMAIL;TYPE=INTERNET:sman at netscape.com
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Silverberg;Steve
+ FN:Steve Silverberg
+ ORG:Microsoft Corporation
+ ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
+ Redmond;WA;98052-6399;USA
+ TEL;TYPE=WORK,MSG:+1-425-936-9277
+ TEL;TYPE=WORK,FAX:+1-425-936-8019
+ EMAIL;TYPE=INTERNET:stevesil at Microsoft.com
+ END:VCARD
+
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 16]
+
+RFC 2447 iMIP November 1998
+
+
+ The iCalendar Object is a result of the work of the Internet
+ Engineering Task Force Calendaring and scheduling Working Group. The
+ chairmen of that working group are:
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Ganguly;Anik
+ FN:Anik Ganguly
+ ORG:Open Text Inc.
+ ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
+ Livonia;MI;48152;USA
+ TEL;TYPE=WORK,MSG:+1-734-542-5955
+ EMAIL;TYPE=INTERNET:ganguly at acm.org
+ END:VCARD
+
+ BEGIN:VCARD
+ VERSION:3.0
+ N:Moskowitz;Robert
+ FN:Robert Moskowitz
+ EMAIL;TYPE=INTERNET:rgm-ietf at htt-consult.com
+ END:VCARD
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 17]
+
+RFC 2447 iMIP November 1998
+
+
+8. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dawson, et. al. Standards Track [Page 18]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2447.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2447.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2447.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,1011 +0,0 @@
-
-
-
-
-
-
-Network Working Group F. Dawson
-Request for Comments: 2447 Lotus
-Category: Standards Track S. Mansour
- Netscape
- S. Silverberg
- Microsoft
- November 1998
-
-
- iCalendar Message-Based Interoperability Protocol
- (iMIP)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
-Abstract
-
- This document, [iMIP], specifies a binding from the iCalendar
- Transport-independent Interoperability Protocol (iTIP) to Internet
- email-based transports. Calendaring entries defined by the iCalendar
- Object Model [iCAL] are composed using constructs from [RFC-822],
- [RFC-2045], [RFC-2046], [RFC-2047], [RFC-2048] and [RFC-2049].
-
- This document is based on discussions within the Internet Engineering
- Task Force (IETF) Calendaring and Scheduling (CALSCH) working group.
- More information about the IETF CALSCH working group activities can
- be found on the IMC web site at http://www.imc.org, the IETF web site
- at http://www.ietf.org/html.charters/calsch-charter.html. Refer to
- the references within this document for further information on how to
- access these various documents.
-
-
-
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 1]
-
-RFC 2447 iMIP November 1998
-
-
-Table of Contents
-
- 1 INTRODUCTION........................................................2
- 1.1 RELATED MEMOS ...................................................2
- 1.2 FORMATTING CONVENTIONS ..........................................3
- 1.3 TERMINOLOGY .....................................................4
- 2 MIME MESSAGE FORMAT BINDING.........................................4
- 2.1 MIME MEDIA TYPE .................................................4
- 2.2 SECURITY ........................................................4
- 2.2.1 Authorization ...............................................4
- 2.2.2 Authentication ..............................................5
- 2.2.3 Confidentiality .............................................5
- 2.3 [RFC-822] ADDRESSES .............................................5
- 2.4 CONTENT TYPE ....................................................5
- 2.5 CONTENT-TRANSFER-ENCODING .......................................6
- 2.6 CONTENT-DISPOSITION .............................................6
- 3 SECURITY CONSIDERATIONS.............................................7
- 4 EXAMPLES............................................................8
- 4.1 SINGLE COMPONENT WITH AN ATTACH PROPERTY ........................8
- 4.2 USING MULTIPART ALTERNATIVE FOR LOW FIDELITY CLIENTS ............8
- 4.3 SINGLE COMPONENT WITH AN ATTACH PROPERTY AND INLINE ATTACHMENT ..9
- 4.4 MULTIPLE SIMILAR COMPONENTS ....................................10
- 4.5 MULTIPLE MIXED COMPONENTS ......................................11
- 4.6 DETAILED COMPONENTS WITH AN ATTACH PROPERTY ....................13
- 5 RECOMMENDED PRACTICES..............................................14
- 5.1 USE OF CONTENT AND MESSAGE IDS .................................14
- 6 BIBLIOGRAPHY.......................................................15
- 7 AUTHORS' ADDRESSES.................................................16
- 8 FULL COPYRIGHT STATEMENT...........................................18
-
-1 Introduction
-
- This binding document provides the transport specific information
- necessary convey iCalendar Transport-independent Interoperability
- Protocol (iTIP) over MIME as defined in [RFC-822] and [RFC-2045].
-
-1.1 Related Memos
-
- Implementers will need to be familiar with several other memos that,
- along with this memo, form a framework for Internet calendaring and
- scheduling standards.
-
- This document, [iMIP], specifies an Internet email binding for iTIP.
-
- [iCAL] - specifies a core specification of objects, data types,
- properties and property parameters;
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 2]
-
-RFC 2447 iMIP November 1998
-
-
- [iTIP] - specifies an interoperability protocol for scheduling
- between different implementations;
-
- This memo does not attempt to repeat the specification of concepts or
- definitions from these other memos. Where possible, references are
- made to the memo that provides for the specification of these
- concepts or definitions.
-
-1.2 Formatting Conventions
-
- The mechanisms defined in this memo are defined in prose. In order to
- refer to elements of the calendaring and scheduling model, core
- object or interoperability protocol defined in [iCAL] and [iTIP] some
- formatting conventions have been used.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this
- document are to be interpreted as described in [RFC-2119].
-
- Calendaring and scheduling roles are referred to in quoted-strings of
- text with the first character of each word in upper case. For
- example, "Organizer" refers to a role of a "Calendar User" within the
- scheduling protocol defined by [iTIP].
-
- Calendar components defined by [iCAL] are referred to with
- capitalized, quoted-strings of text. All calendar components start
- with the letter "V". For example, "VEVENT" refers to the event
- calendar component, "VTODO" refers to the to-do calendar component
- and "VJOURNAL" refers to the daily journal calendar component.
-
- Scheduling methods defined by [iTIP] are referred to with
- capitalized, quoted-strings of text. For example, "REQUEST" refers to
- the method for requesting a scheduling calendar component be created
- or modified, "REPLY" refers to the method a recipient of a request
- uses to update their status with the "Organizer" of the calendar
- component.
-
- Properties defined by [iCAL] are referred to with capitalized,
- quoted-strings of text, followed by the word "property". For example,
- "ATTENDEE" property refers to the iCalendar property used to convey
- the calendar address of a calendar user.
-
- Property parameters defined by [iCAL] are referred to with lower
- case, quoted-strings of text, followed by the word "parameter". For
- example, "value" parameter refers to the iCalendar property parameter
- used to override the default data type for a property value.
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 3]
-
-RFC 2447 iMIP November 1998
-
-
-1.3 Terminology
-
- The email terms used in this memo are defined in [RFC-822] and [RFC-
- 2045]. The calendaring and scheduling terms used in this memo are
- defined in [iCAL] and [iTIP].
-
-2 MIME Message Format Binding
-
- This section defines the message binding to the MIME electronic mail
- transport.
-
- The sections below refer to the "originator" and the "respondent" of
- an iMIP message. Typically, the originator is the "Organizer" of an
- event. The respondent is an "Attendee" of the event.
-
- The [RFC-822] "Reply-To" header typically contains the email address
- of the originator or respondent of an event. However, this cannot be
- guaranteed as Mail User Agents (MUA) are not required to enforce iMIP
- semantics.
-
-2.1 MIME Media Type
-
- A MIME entity containing content information formatted according to
- this document will be referenced as a "text/calendar" content type.
- It is assumed that this content type will be transported through a
- MIME electronic mail transport.
-
-2.2 Security
-
- This section addresses several aspects of security including
- Authentication, Authorization and Confidentiality. Authentication and
- confidentiality can be achieved using [RFC-1847] that specifies the
- Security Multiparts for MIME. This framework defines new content
- types and subtypes of multipart: signed and encrypted. Each contains
- two body parts: one for the protected data and another for the
- control information necessary to remove the protection.
-
-2.2.1 Authorization
-
- In [iTIP] messages, only the "Organizer" is authorized to modify or
- cancel calendar entries they organize. That is, spoof at xyz.com is not
- allowed to modify or cancel a meeting that was organized by
- a at example.com. Furthermore, only the respondent has the authorization
- to indicate their status to the "Organizer". That is, the "Organizer"
- must ignore an [iTIP] message from spoof at xyz.com that declines a
- meeting invitation for b at example.com.
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 4]
-
-RFC 2447 iMIP November 1998
-
-
- Implementations of iMIP SHOULD verify the authenticity of the creator
- of an iCalendar object before taking any action. The methods for
- doing this are presented later in this document.
-
- [RFC-1847] Message flow in iTIP supports someone working on behalf of
- a "Calendar User" through use of the "sent-by" parameter that is
- associated with the "ATTENDEE" and "ORGANIZER" properties. However,
- there is no mechanism to verify whether or not a "Calendar User" has
- authorized someone to work on their behalf. It is left to
- implementations to provide mechanisms for the "Calendar Users" to
- make that decision.
-
-2.2.2 Authentication
-
- Authentication can be performed using an implementation of [RFC-1847]
- "multipart/signed" that supports public/private key certificates.
- Authentication is possible only on messages that have been signed.
- Authenticating an unsigned message may not be reliable.
-
-2.2.3 Confidentiality
-
- To ensure confidentiality using iMIP implementations should utilize
- [RFC-1847]-compliant encryption. The protocol does not restrict a
- "Calendar User Agent" (CUA) from forwarding iCalendar objects to
- other users or agents.
-
-2.3 [RFC-822] Addresses
-
- The calendar address specified within the "ATTENDEE" property in an
- iCalendar object MUST be a fully qualified, [RFC-822] address
- specification for the corresponding "Organizer" or "Attendee" of the
- "VEVENT" or "VTODO".
-
- Because [iTIP] does not preclude "Attendees" from forwarding
- "VEVENTS" or "VTODOS" to others, the [RFC-822] "Sender" value may not
- equal that of the "Organizer". Additionally, the "Organizer" or
- "Attendee" cannot be reliably inferred by the [RFC-822] "Sender" or
- "Reply-to" values of an iMIP message. The relevant address MUST be
- ascertained by opening the "text/calendar" MIME body part and
- examining the "ATTENDEE" and "ORGANIZER" properties.
-
-2.4 Content Type
-
- A MIME body part containing content information that conforms to this
- document MUST have an [RFC-2045] "Content-Type" value of
- "text/calendar". The [RFC-2045] "Content-Type" header field must also
- include the type parameter "method". The value MUST be the same as
- the value of the "METHOD" calendar property within the iCalendar
-
-
-
-Dawson, et. al. Standards Track [Page 5]
-
-RFC 2447 iMIP November 1998
-
-
- object. This means that a MIME message containing multiple iCalendar
- objects with different method values must be further encapsulated
- with a "multipart/mixed" MIME entity. This will allow each of the
- iCalendar objects to be encapsulated within their own "text/calendar"
- MIME entity.
-
- A "charset" parameter MUST be present if the iCalendar object
- contains characters that are not part of the US-ASCII character set.
- [RFC-2046] discusses the selection of an appropriate "charset" value.
-
- The optional "component" parameter defines the iCalendar component
- type contained within the iCalendar object.
-
- The following is an example of this header field with a value that
- indicates an event message.
-
- Content-Type:text/calendar; method=request; charset=UTF-8;
- component=vevent
-
- The "text/calendar" content type allows for the scheduling message
- type to be included in a MIME message with other content information
- (i.e., "multipart/mixed") or included in a MIME message with a
- clear-text, human-readable form of the scheduling message (i.e.,
- "multipart/alternative").
-
- In order to permit the information in the scheduling message to be
- understood by MIME user agents (UA) that do not support the
- "text/calendar" content type, scheduling messages SHOULD be sent with
- an alternative, human-readable form of the information.
-
-2.5 Content-Transfer-Encoding
-
- Note that the default character set for iCalendar objects is UTF-8. A
- transfer encoding SHOULD be used for iCalendar objects containing any
- characters that are not part of the US-ASCII character set.
-
-2.6 Content-Disposition
-
- The handling of a MIME part should be based on its [RFC-2045]
- "Content-Type". However, this is not guaranteed to work in all
- environments. Some environments handle MIME attachments based on
- their file type or extension. To operate correctly in these
- environments, implementations may wish to include a "Content-
- Disposition" property to define a file name.
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 6]
-
-RFC 2447 iMIP November 1998
-
-
-3 Security Considerations
-
- The security threats that applications must address when implementing
- iTIP are detailed in [iTIP]. Two spoofing threats are identified:
- Spoofing the "Organizer", and Spoofing an "Attendee". To address
- these threats, the originator of an iCalendar object must be
- authenticated by a recipient. Once authenticated, a determination can
- be made as to whether or not the originator is authorized to perform
- the requested operation. Compliant applications MUST support signing
- and encrypting text/calendar attachments using a mechanism based on
- Security Multiparts for MIME [RFC-1847] to facilitate the
- authentication the originator of the iCalendar object.
- Implementations MAY provide a means for users to disable signing and
- encrypting. The steps are described below:
-
- 1. The iCalendar object MUST be signed by the "Organizer" sending an
- update or the "Attendee" sending a reply.
-
- 2. Using the [RFC-1847]-compliant security mechanism, determine who
- signed the iCalendar object. This is the "signer". Note that the
- signer is not necessarily the person sending an e-mail message since
- an e-mail message can be forwarded.
-
- 3. Correlate the signer to an "ATTENDEE" property in the iCalendar
- object. If the signer cannot be correlated to an "ATTENDEE" property,
- ignore the message.
-
- 4. Determine whether or not the "ATTENDEE" is authorized to perform
- the operation as defined by [iTIP]. If the conditions are not met,
- ignore the message.
-
- 5. If all the above conditions are met, the message can be processed.
-
- To address the confidentiality security threats, signed iMIP messages
- SHOULD be encrypted by a mechanism based on Security Multiparts for
- MIME [RFC-1847].
-
- It is possible to receive iMIP messages sent by someone working on
- behalf of another "Calendar User". This is determined by examining
- the "sent-by" parameter in the relevant "ORGANIZER" or "ATTENDEE"
- property. [iCAL] and [iTIP] provide no mechanism to verify that a
- "Calendar User" has authorized someone else to work on their behalf.
- To address this security issue, implementations MUST provide
- mechanisms for the "Calendar Users" to make that decision before
- applying changes from someone working on behalf of a "Calendar User".
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 7]
-
-RFC 2447 iMIP November 1998
-
-
-4 Examples
-
-4.1 Single Component With An ATTACH Property
-
- This minimal message shows how an iCalendar object references an
- attachment. The attachment is accessible via its URL.
-
- From: sman at netscape.com
- To: stevesil at microsoft.com
- Subject: Phone Conference
- Mime-Version: 1.0
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
- Content-Transfer-Encoding: 7bit
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:sman at netscape.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:sman at netscape.com
- ATTENDEE;RSVP=YES:mailto:stevesil at microsoft.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T210000Z
- DTEND:19970701T230000Z
- SUMMARY:Phone Conference
- DESCRIPTION:Please review the attached document.
- UID:calsvr.example.com-873970198738777
- ATTACH:ftp://ftp.bar.com/pub/docs/foo.doc
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.2 Using Multipart Alternative for Low Fidelity Clients
-
- This example shows how a client can emit a multipart message that
- includes both a plain text version as well as the full iCalendar
- object. Clients that do not support text/calendar will still be
- capable of rendering the plain text representation.
-
- From: foo1 at example.com
- To: foo2 at example.com
- Subject: Phone Conference
- Mime-Version: 1.0
- Content-Type: multipart/alternative;boundary="01BD3665.3AF0D360"
-
- --01BD3665.3AF0D360
- Content-Type: text/plain;charset=us-ascii
-
-
-
-Dawson, et. al. Standards Track [Page 8]
-
-RFC 2447 iMIP November 1998
-
-
- Content-Transfer-Encoding: 7bit
-
- This is an alternative representation of a TEXT/CALENDAR MIME Object
- When: 7/1/1997 10:00AM PDT - 7/1/97 10:30AM PDT
- Where:
- Organizer: foo1 at example.com
- Summary: Phone Conference
-
- --01BD3665.3AF0D360
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
- Content-Transfer-Encoding: 7bit
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:foo1 at example.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
- ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T170000Z
- DTEND:19970701T173000Z
- SUMMARY:Phone Conference
- UID:calsvr.example.com-8739701987387771
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- --01BD3665.3AF0D360
-
-4.3 Single Component With An ATTACH Property and Inline Attachment
-
- This example shows how a message containing an iCalendar object
- references an attached document. The reference is made using a
- Content-id (CID). Thus, the iCalendar object and the document are
- packaged in a multipart/related encapsulation.
-
- From: foo1 at example.com
- To: foo2 at example.com
- Subject: Phone Conference
- Mime-Version: 1.0
- Content-Type: multipart/related; boundary="boundary-example-1";
- type=text/calendar
-
- --boundary-example-1
-
-
-
-
-Dawson, et. al. Standards Track [Page 9]
-
-RFC 2447 iMIP November 1998
-
-
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
- Content-Transfer-Encoding: 7bit
- Content-Disposition: attachment; filename="event.vcs"
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:foo1 at example.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
- ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T180000Z
- DTEND:19970701T183000Z
- SUMMARY:Phone Conference
- UID:calsvr.example.com-8739701987387771
- ATTACH:cid:123456789 at example.com
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- --boundary-example-1
- Content-Type: application/msword; name="FieldReport.doc"
- Content-Transfer-Encoding: base64
- Content-Disposition: inline; filename="FieldReport.doc"
- Content-ID: <123456789 at example.com>
-
- 0M8R4KGxGuEAAAAAAAAAAAAAAAAAAAAAPgADAP7/CQAGAAAAAAAAAAABAAAARAAAAAAA
- AAAAEAAAQAAAAAEAAAD+////AAAAAEUAAAD/////////////////////////////////
-
- --boundary-example-1--
-
-4.4 Multiple Similar Components
-
- Multiple iCalendar components of the same type can be included in the
- iCalendar object when the METHOD is the same for each component.
-
- From: foo1 at example.com
- To: foo2 at example.com
- Subject: Summer Company Holidays
- Mime-Version: 1.0
- Content-Type:text/calendar; method=PUBLISH; charset=US-ASCII
- Content-Transfer-Encoding: 7bit
- Content-Disposition: attachment; filename="event.vcs"
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 10]
-
-RFC 2447 iMIP November 1998
-
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DESKTOPCALENDAR//EN
- METHOD:PUBLISH
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:MAILTO:FOO1 at EXAMPLE.COM
- DTSTAMP:19970611T150000Z
- DTSTART:19970701T150000Z
- DTEND:19970701T230000Z
- SUMMARY:Company Picnic
- DESCRIPTION:Food and drink will be provided
- UID:CALSVR.EXAMPLE.COM-873970198738777-1
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- BEGIN:VEVENT
- ORGANIZER:MAILTO:FOO1 at EXAMPLE.COM
- DTSTAMP:19970611T190000Z
- DTSTART:19970715T150000Z
- DTEND:19970715T230000Z
- SUMMARY:Company Bowling Tournament
- DESCRIPTION:We have 10 lanes reserved
- UID:CALSVR.EXAMPLE.COM-873970198738777-2
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
-4.5 Multiple Mixed Components
-
- Different component types must be encapsulated in separate iCalendar
- objects.
-
- From: foo1 at example.com
- To: foo2 at example.com
- Subject: Phone Conference
- Mime-Version: 1.0
- Content-Type:multipart/mixed;boundary="--FEE3790DC7E35189CA67CE2C"
-
- This is a multi-part message in MIME format.
-
- ----FEE3790DC7E35189CA67CE2C
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
- Content-Transfer-Encoding: 7bit
- Content-Disposition: attachment; filename="event1.vcs"
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 11]
-
-RFC 2447 iMIP November 1998
-
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:mailto:foo1 at example.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
- ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970701T210000Z
- DTEND:19970701T230000Z
- SUMMARY:Phone Conference
- DESCRIPTION:Discuss what happened at the last meeting
- UID:calsvr.example.com-8739701987387772
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- ----FEE3790DC7E35189CA67CE2C
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII
- Content-Transfer-Encoding:7bit
- Content-Disposition: attachment; filename="todo1.vcs"
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- METHOD:REQUEST
- VERSION:2.0
- BEGIN:VTODO
- DUE:19970701T090000-0700
- ORGANIZER:mailto:foo1 at example.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:mailto:foo1 at example.com
- ATTENDEE;RSVP=YES:mailto:foo2 at example.com
- SUMMARY:Phone Conference
- DESCRIPTION:Discuss a new location for the company picnic
- UID:calsvr.example.com-td-8739701987387773
- SEQUENCE:0
- STATUS:NEEDS ACTION
- END:VEVENT
- END:VCALENDAR
-
- ----FEE3790DC7E35189CA67CE2C
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 12]
-
-RFC 2447 iMIP November 1998
-
-
-4.6 Detailed Components With An ATTACH Property
-
- This example shows the format of a message containing a group meeting
- between three individuals. The multipart/related encapsulation is
- used because the iCalendar object contains an ATTACH property that
- uses a CID to reference the attachment.
-
- From: foo1 at example.com
- MIME-Version: 1.0
- To: foo2 at example.com,foo3 at example.com
- Subject: REQUEST - Phone Conference
- Content-Type:multipart/related;boundary="--FEE3790DC7E35189CA67CE2C"
-
- ----FEE3790DC7E35189CA67CE2C
- Content-Type: multipart/alternative;
- boundary="--00FEE3790DC7E35189CA67CE2C00"
-
- ----00FEE3790DC7E35189CA67CE2C00
- Content-Type: text/plain; charset=us-ascii
- Content-Transfer-Encoding: 7bit
-
- When: 7/1/1997 10:00PM PDT- 7/1/97 10:30 PM PDT
- Where:
- Organizer: foo1 at example.com
- Summary: Let's discuss the attached document
-
- ----00FEE3790DC7E35189CA67CE2C00
-
- Content-Type:text/calendar; method=REQUEST; charset=US-ASCII;
- Component=vevent
- Content-Transfer-Encoding: 7bit
- Content-Disposition: attachment; filename="event.vcs"
-
- BEGIN:VCALENDAR
- PRODID:-//ACME/DesktopCalendar//EN
- PROFILE:REQUEST
- PROFILE-VERSION:1.0
- VERSION:2.0
- BEGIN:VEVENT
- ORGANIZER:foo1 at example.com
- ATTENDEE;ROLE=CHAIR;ATTSTAT=ACCEPTED:foo1 at example.com
- ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo2 at example.com
- ATTENDEE;RSVP=YES;TYPE=INDIVIDUAL:mailto:foo3 at example.com
- DTSTAMP:19970611T190000Z
- DTSTART:19970621T170000Z
- DTEND:199706211T173000Z
- SUMMARY:Let's discuss the attached document
- UID:calsvr.example.com-873970198738777-8aa
-
-
-
-Dawson, et. al. Standards Track [Page 13]
-
-RFC 2447 iMIP November 1998
-
-
- ATTACH:cid:calsvr.example.com-12345aaa
- SEQUENCE:0
- STATUS:CONFIRMED
- END:VEVENT
- END:VCALENDAR
-
- ----00FEE3790DC7E35189CA67CE2C00
-
- ----FEE3790DC7E35189CA67CE2C
- Content-Type: application/msword; name="FieldReport.doc"
- Content-Transfer-Encoding: base64
- Content-Disposition: inline; filename="FieldReport.doc"
- Content-ID: <calsvr.example.com-12345aaa>
-
-
- R0lGODdhTAQZAJEAAFVVVd3d3e4AAP///ywAAAAATAQZAAAC/5yPOSLhD6OctNqLs94XqAG
- 4kiW5omm6sq27gvH8kzX9o1y+s73/g8MCofEovGITCoxKMbyCR16cNSq9YrNarfcrvdriIH
- 5LL5jE6rxc3G+v2cguf0uv2Oz+v38L7/DxgoOKjURnjIIbe3yNjo+AgZWYVIWWl5iZnJY6J.
-
- ----FEE3790DC7E35189CA67CE2C
-
-5 Recommended Practices
-
- This section outlines a series of recommended practices when using a
- messaging transport to exchange iCalendar objects.
-
-5.1 Use of Content and Message IDs
-
- The [iCAL] specification makes frequent use of the URI for data types
- in properties such as "DESCRIPTION", "ATTACH", "CONTACT" and others.
- Two forms of URIs are Message ID (MID) and Content ID (CID). These
- are defined in [RFC-2111]. Although [RFC-2111] allows referencing
- messages or MIME body parts in other MIME entities or stores, it is
- strongly recommended that iMIP implementations include all referenced
- messages and body parts in a single MIME entity. Simply put, if an
- iCalendar object contains CID or MID references to other messages or
- body parts, implementations should ensure that these messages and/or
- body parts are transmitted with the iCalendar object. If they are not
- there is no guarantee that the receiving "CU" will have the access or
- the authorization to view those objects.
-
-
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 14]
-
-RFC 2447 iMIP November 1998
-
-
-6 Bibliography
-
- [CHST] Character Sets, ftp://ftp.isi.edu/in-
- notes/iana/assignments/character-sets
-
- [iCAL] Dawson, F. and D. Stenerson, "Internet Calendaring and
- Scheduling Core Object Specification - iCalendar", RFC
- 2445, November 1998.
-
- [iTIP] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
- "iCalendar Transport-Independent Interoperability Protocol
- (iTIP): Scheduling Events, Busy Time, To-dos and Journal
- Entries", RFC 2446, November 1998.
-
- [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet
- Text Messages", STD 11, RFC 822, August 1982.
-
- [RFC-1847] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
- "Security Multiparts for MIME: Multipart/Signed and
- Multipart/Encrypted", RFC 1847, October 1995.
-
- [RFC-2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) - Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [RFC-2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) - Part Two: Media Types", RFC 2046,
- November 1996.
-
- [RFC-2047] Moore, K., "Multipurpose Internet Mail Extensions (MIME) -
- Part Three: Message Header Extensions for Non-ASCII Text",
- RFC 2047, November 1996.
-
- [RFC-2048] Freed, N., Klensin, J. and J. Postel, "Multipurpose
- Internet Mail Extensions (MIME) - Part Four: Registration
- Procedures", RFC 2048, January 1997.
-
- [RFC-2111] Levinson, E., "Content-ID and Message-ID Uniform Resource
- Locators", RFC 2111, March 1997.
-
- [RFC-2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 15]
-
-RFC 2447 iMIP November 1998
-
-
-7 Authors' Addresses
-
- The following address information is provided in a vCard v3.0,
- Electronic Business Card, format.
-
- BEGIN:VCARD
- VERSION:3.0
- N:Dawson;Frank
- FN:Frank Dawson
- ORG:Lotus Development Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford
- Drive;Raleigh;NC;27613-3502;USA
- TEL;TYPE=WORK,MSG:+1-919-676-9515
- TEL;TYPE=WORK,FAX:+1-919-676-9564
- EMAIL;TYPE=INTERNET:fdawson at earthlink.net
- URL:http://home.earthlink.net/~fdawson
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Mansour;Steve
- FN:Steve Mansour
- ORG:Netscape Communications Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;501 East Middlefield Road;Mountain
- View;CA;94043;USA
- TEL;TYPE=WORK,MSG:+1-650-937-2378
- TEL;TYPE=WORK,FAX:+1-650-937-2103
- EMAIL;TYPE=INTERNET:sman at netscape.com
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Silverberg;Steve
- FN:Steve Silverberg
- ORG:Microsoft Corporation
- ADR;TYPE=WORK,POSTAL,PARCEL:;;One Microsoft Way;
- Redmond;WA;98052-6399;USA
- TEL;TYPE=WORK,MSG:+1-425-936-9277
- TEL;TYPE=WORK,FAX:+1-425-936-8019
- EMAIL;TYPE=INTERNET:stevesil at Microsoft.com
- END:VCARD
-
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 16]
-
-RFC 2447 iMIP November 1998
-
-
- The iCalendar Object is a result of the work of the Internet
- Engineering Task Force Calendaring and scheduling Working Group. The
- chairmen of that working group are:
-
- BEGIN:VCARD
- VERSION:3.0
- N:Ganguly;Anik
- FN:Anik Ganguly
- ORG:Open Text Inc.
- ADR;TYPE=WORK,POSTAL,PARCEL:;Suite 101;38777 West Six Mile Road;
- Livonia;MI;48152;USA
- TEL;TYPE=WORK,MSG:+1-734-542-5955
- EMAIL;TYPE=INTERNET:ganguly at acm.org
- END:VCARD
-
- BEGIN:VCARD
- VERSION:3.0
- N:Moskowitz;Robert
- FN:Robert Moskowitz
- EMAIL;TYPE=INTERNET:rgm-ietf at htt-consult.com
- END:VCARD
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 17]
-
-RFC 2447 iMIP November 1998
-
-
-8. Full Copyright Statement
-
- Copyright (C) The Internet Society (1998). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dawson, et. al. Standards Track [Page 18]
-
Copied: CalendarServer/trunk/doc/RFC/rfc2518-WebDAV.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2518.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2518-WebDAV.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2518-WebDAV.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,5267 @@
+
+
+
+
+
+
+Network Working Group Y. Goland
+Request for Comments: 2518 Microsoft
+Category: Standards Track E. Whitehead
+ UC Irvine
+ A. Faizi
+ Netscape
+ S. Carter
+ Novell
+ D. Jensen
+ Novell
+ February 1999
+
+
+ HTTP Extensions for Distributed Authoring -- WEBDAV
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ This document specifies a set of methods, headers, and content-types
+ ancillary to HTTP/1.1 for the management of resource properties,
+ creation and management of resource collections, namespace
+ manipulation, and resource locking (collision avoidance).
+
+Table of Contents
+
+ ABSTRACT............................................................1
+ 1 INTRODUCTION .....................................................5
+ 2 NOTATIONAL CONVENTIONS ...........................................7
+ 3 TERMINOLOGY ......................................................7
+ 4 DATA MODEL FOR RESOURCE PROPERTIES ...............................8
+ 4.1 The Resource Property Model ...................................8
+ 4.2 Existing Metadata Proposals ...................................8
+ 4.3 Properties and HTTP Headers ...................................9
+ 4.4 Property Values ...............................................9
+ 4.5 Property Names ...............................................10
+ 4.6 Media Independent Links ......................................10
+ 5 COLLECTIONS OF WEB RESOURCES ....................................11
+
+
+
+Goland, et al. Standards Track [Page 1]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 5.1 HTTP URL Namespace Model .....................................11
+ 5.2 Collection Resources .........................................11
+ 5.3 Creation and Retrieval of Collection Resources ...............12
+ 5.4 Source Resources and Output Resources ........................13
+ 6 LOCKING .........................................................14
+ 6.1 Exclusive Vs. Shared Locks ...................................14
+ 6.2 Required Support .............................................16
+ 6.3 Lock Tokens ..................................................16
+ 6.4 opaquelocktoken Lock Token URI Scheme ........................16
+ 6.4.1 Node Field Generation Without the IEEE 802 Address ........17
+ 6.5 Lock Capability Discovery ....................................19
+ 6.6 Active Lock Discovery ........................................19
+ 6.7 Usage Considerations .........................................19
+ 7 WRITE LOCK ......................................................20
+ 7.1 Methods Restricted by Write Locks ............................20
+ 7.2 Write Locks and Lock Tokens ..................................20
+ 7.3 Write Locks and Properties ...................................20
+ 7.4 Write Locks and Null Resources ...............................21
+ 7.5 Write Locks and Collections ..................................21
+ 7.6 Write Locks and the If Request Header ........................22
+ 7.6.1 Example - Write Lock ......................................22
+ 7.7 Write Locks and COPY/MOVE ....................................23
+ 7.8 Refreshing Write Locks .......................................23
+ 8 HTTP METHODS FOR DISTRIBUTED AUTHORING ..........................23
+ 8.1 PROPFIND .....................................................24
+ 8.1.1 Example - Retrieving Named Properties .....................25
+ 8.1.2 Example - Using allprop to Retrieve All Properties ........26
+ 8.1.3 Example - Using propname to Retrieve all Property Names ...29
+ 8.2 PROPPATCH ....................................................31
+ 8.2.1 Status Codes for use with 207 (Multi-Status) ..............31
+ 8.2.2 Example - PROPPATCH .......................................32
+ 8.3 MKCOL Method .................................................33
+ 8.3.1 Request ...................................................33
+ 8.3.2 Status Codes ..............................................33
+ 8.3.3 Example - MKCOL ...........................................34
+ 8.4 GET, HEAD for Collections ....................................34
+ 8.5 POST for Collections .........................................35
+ 8.6 DELETE .......................................................35
+ 8.6.1 DELETE for Non-Collection Resources .......................35
+ 8.6.2 DELETE for Collections ....................................36
+ 8.7 PUT ..........................................................36
+ 8.7.1 PUT for Non-Collection Resources ..........................36
+ 8.7.2 PUT for Collections .......................................37
+ 8.8 COPY Method ..................................................37
+ 8.8.1 COPY for HTTP/1.1 resources ...............................37
+ 8.8.2 COPY for Properties .......................................38
+ 8.8.3 COPY for Collections ......................................38
+ 8.8.4 COPY and the Overwrite Header .............................39
+
+
+
+Goland, et al. Standards Track [Page 2]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 8.8.5 Status Codes ..............................................39
+ 8.8.6 Example - COPY with Overwrite .............................40
+ 8.8.7 Example - COPY with No Overwrite ..........................40
+ 8.8.8 Example - COPY of a Collection ............................41
+ 8.9 MOVE Method ..................................................42
+ 8.9.1 MOVE for Properties .......................................42
+ 8.9.2 MOVE for Collections ......................................42
+ 8.9.3 MOVE and the Overwrite Header .............................43
+ 8.9.4 Status Codes ..............................................43
+ 8.9.5 Example - MOVE of a Non-Collection ........................44
+ 8.9.6 Example - MOVE of a Collection ............................44
+ 8.10 LOCK Method ..................................................45
+ 8.10.1 Operation .................................................46
+ 8.10.2 The Effect of Locks on Properties and Collections .........46
+ 8.10.3 Locking Replicated Resources ..............................46
+ 8.10.4 Depth and Locking .........................................46
+ 8.10.5 Interaction with other Methods ............................47
+ 8.10.6 Lock Compatibility Table ..................................47
+ 8.10.7 Status Codes ..............................................48
+ 8.10.8 Example - Simple Lock Request .............................48
+ 8.10.9 Example - Refreshing a Write Lock .........................49
+ 8.10.10 Example - Multi-Resource Lock Request ....................50
+ 8.11 UNLOCK Method ................................................51
+ 8.11.1 Example - UNLOCK ..........................................52
+ 9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ..........................52
+ 9.1 DAV Header ...................................................52
+ 9.2 Depth Header .................................................52
+ 9.3 Destination Header ...........................................54
+ 9.4 If Header ....................................................54
+ 9.4.1 No-tag-list Production ....................................55
+ 9.4.2 Tagged-list Production ....................................55
+ 9.4.3 not Production ............................................56
+ 9.4.4 Matching Function .........................................56
+ 9.4.5 If Header and Non-DAV Compliant Proxies ...................57
+ 9.5 Lock-Token Header ............................................57
+ 9.6 Overwrite Header .............................................57
+ 9.7 Status-URI Response Header ...................................57
+ 9.8 Timeout Request Header .......................................58
+ 10 STATUS CODE EXTENSIONS TO HTTP/1.1 ............................59
+ 10.1 102 Processing ...............................................59
+ 10.2 207 Multi-Status .............................................59
+ 10.3 422 Unprocessable Entity .....................................60
+ 10.4 423 Locked ...................................................60
+ 10.5 424 Failed Dependency ........................................60
+ 10.6 507 Insufficient Storage .....................................60
+ 11 MULTI-STATUS RESPONSE .........................................60
+ 12 XML ELEMENT DEFINITIONS .......................................61
+ 12.1 activelock XML Element .......................................61
+
+
+
+Goland, et al. Standards Track [Page 3]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 12.1.1 depth XML Element .........................................61
+ 12.1.2 locktoken XML Element .....................................61
+ 12.1.3 timeout XML Element .......................................61
+ 12.2 collection XML Element .......................................62
+ 12.3 href XML Element .............................................62
+ 12.4 link XML Element .............................................62
+ 12.4.1 dst XML Element ...........................................62
+ 12.4.2 src XML Element ...........................................62
+ 12.5 lockentry XML Element ........................................63
+ 12.6 lockinfo XML Element .........................................63
+ 12.7 lockscope XML Element ........................................63
+ 12.7.1 exclusive XML Element .....................................63
+ 12.7.2 shared XML Element ........................................63
+ 12.8 locktype XML Element .........................................64
+ 12.8.1 write XML Element .........................................64
+ 12.9 multistatus XML Element ......................................64
+ 12.9.1 response XML Element ......................................64
+ 12.9.2 responsedescription XML Element ...........................65
+ 12.10 owner XML Element ...........................................65
+ 12.11 prop XML element ............................................66
+ 12.12 propertybehavior XML element ................................66
+ 12.12.1 keepalive XML element ....................................66
+ 12.12.2 omit XML element .........................................67
+ 12.13 propertyupdate XML element ..................................67
+ 12.13.1 remove XML element .......................................67
+ 12.13.2 set XML element ..........................................67
+ 12.14 propfind XML Element ........................................68
+ 12.14.1 allprop XML Element ......................................68
+ 12.14.2 propname XML Element .....................................68
+ 13 DAV PROPERTIES ................................................68
+ 13.1 creationdate Property ........................................69
+ 13.2 displayname Property .........................................69
+ 13.3 getcontentlanguage Property ..................................69
+ 13.4 getcontentlength Property ....................................69
+ 13.5 getcontenttype Property ......................................70
+ 13.6 getetag Property .............................................70
+ 13.7 getlastmodified Property .....................................70
+ 13.8 lockdiscovery Property .......................................71
+ 13.8.1 Example - Retrieving the lockdiscovery Property ...........71
+ 13.9 resourcetype Property ........................................72
+ 13.10 source Property .............................................72
+ 13.10.1 Example - A source Property ..............................72
+ 13.11 supportedlock Property ......................................73
+ 13.11.1 Example - Retrieving the supportedlock Property ..........73
+ 14 INSTRUCTIONS FOR PROCESSING XML IN DAV ........................74
+ 15 DAV COMPLIANCE CLASSES ........................................75
+ 15.1 Class 1 ......................................................75
+ 15.2 Class 2 ......................................................75
+
+
+
+Goland, et al. Standards Track [Page 4]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 16 INTERNATIONALIZATION CONSIDERATIONS ...........................76
+ 17 SECURITY CONSIDERATIONS .......................................77
+ 17.1 Authentication of Clients ....................................77
+ 17.2 Denial of Service ............................................78
+ 17.3 Security through Obscurity ...................................78
+ 17.4 Privacy Issues Connected to Locks ............................78
+ 17.5 Privacy Issues Connected to Properties .......................79
+ 17.6 Reduction of Security due to Source Link .....................79
+ 17.7 Implications of XML External Entities ........................79
+ 17.8 Risks Connected with Lock Tokens .............................80
+ 18 IANA CONSIDERATIONS ...........................................80
+ 19 INTELLECTUAL PROPERTY .........................................81
+ 20 ACKNOWLEDGEMENTS ..............................................82
+ 21 REFERENCES ....................................................82
+ 21.1 Normative References .........................................82
+ 21.2 Informational References .....................................83
+ 22 AUTHORS' ADDRESSES ............................................84
+ 23 APPENDICES ....................................................86
+ 23.1 Appendix 1 - WebDAV Document Type Definition .................86
+ 23.2 Appendix 2 - ISO 8601 Date and Time Profile ..................88
+ 23.3 Appendix 3 - Notes on Processing XML Elements ................89
+ 23.3.1 Notes on Empty XML Elements ...............................89
+ 23.3.2 Notes on Illegal XML Processing ...........................89
+ 23.4 Appendix 4 -- XML Namespaces for WebDAV ......................92
+ 23.4.1 Introduction ..............................................92
+ 23.4.2 Meaning of Qualified Names ................................92
+ 24 FULL COPYRIGHT STATEMENT ......................................94
+
+
+
+1 Introduction
+
+ This document describes an extension to the HTTP/1.1 protocol that
+ allows clients to perform remote web content authoring operations.
+ This extension provides a coherent set of methods, headers, request
+ entity body formats, and response entity body formats that provide
+ operations for:
+
+ Properties: The ability to create, remove, and query information
+ about Web pages, such as their authors, creation dates, etc. Also,
+ the ability to link pages of any media type to related pages.
+
+ Collections: The ability to create sets of documents and to retrieve
+ a hierarchical membership listing (like a directory listing in a file
+ system).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 5]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Locking: The ability to keep more than one person from working on a
+ document at the same time. This prevents the "lost update problem,"
+ in which modifications are lost as first one author then another
+ writes changes without merging the other author's changes.
+
+ Namespace Operations: The ability to instruct the server to copy and
+ move Web resources.
+
+ Requirements and rationale for these operations are described in a
+ companion document, "Requirements for a Distributed Authoring and
+ Versioning Protocol for the World Wide Web" [RFC2291].
+
+ The sections below provide a detailed introduction to resource
+ properties (section 4), collections of resources (section 5), and
+ locking operations (section 6). These sections introduce the
+ abstractions manipulated by the WebDAV-specific HTTP methods
+ described in section 8, "HTTP Methods for Distributed Authoring".
+
+ In HTTP/1.1, method parameter information was exclusively encoded in
+ HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
+ information either in an Extensible Markup Language (XML) [REC-XML]
+ request entity body, or in an HTTP header. The use of XML to encode
+ method parameters was motivated by the ability to add extra XML
+ elements to existing structures, providing extensibility; and by
+ XML's ability to encode information in ISO 10646 character sets,
+ providing internationalization support. As a rule of thumb,
+ parameters are encoded in XML entity bodies when they have unbounded
+ length, or when they may be shown to a human user and hence require
+ encoding in an ISO 10646 character set. Otherwise, parameters are
+ encoded within HTTP headers. Section 9 describes the new HTTP
+ headers used with WebDAV methods.
+
+ In addition to encoding method parameters, XML is used in WebDAV to
+ encode the responses from methods, providing the extensibility and
+ internationalization advantages of XML for method output, as well as
+ input.
+
+ XML elements used in this specification are defined in section 12.
+
+ The XML namespace extension (Appendix 4) is also used in this
+ specification in order to allow for new XML elements to be added
+ without fear of colliding with other element names.
+
+ While the status codes provided by HTTP/1.1 are sufficient to
+ describe most error conditions encountered by WebDAV methods, there
+ are some errors that do not fall neatly into the existing categories.
+ New status codes developed for the WebDAV methods are defined in
+ section 10. Since some WebDAV methods may operate over many
+
+
+
+Goland, et al. Standards Track [Page 6]
+
+RFC 2518 WEBDAV February 1999
+
+
+ resources, the Multi-Status response has been introduced to return
+ status information for multiple resources. The Multi-Status response
+ is described in section 11.
+
+ WebDAV employs the property mechanism to store information about the
+ current state of the resource. For example, when a lock is taken out
+ on a resource, a lock information property describes the current
+ state of the lock. Section 13 defines the properties used within the
+ WebDAV specification.
+
+ Finishing off the specification are sections on what it means to be
+ compliant with this specification (section 15), on
+ internationalization support (section 16), and on security (section
+ 17).
+
+2 Notational Conventions
+
+ Since this document describes a set of extensions to the HTTP/1.1
+ protocol, the augmented BNF used herein to describe protocol elements
+ is exactly the same as described in section 2.1 of [RFC2068]. Since
+ this augmented BNF uses the basic production rules provided in
+ section 2.2 of [RFC2068], these rules apply to this document as well.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [RFC2119].
+
+3 Terminology
+
+ URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
+ respectively. These terms (and the distinction between them) are
+ defined in [RFC2396].
+
+ Collection - A resource that contains a set of URIs, termed member
+ URIs, which identify member resources and meets the requirements in
+ section 5 of this specification.
+
+ Member URI - A URI which is a member of the set of URIs contained by
+ a collection.
+
+ Internal Member URI - A Member URI that is immediately relative to
+ the URI of the collection (the definition of immediately relative is
+ given in section 5.2).
+
+ Property - A name/value pair that contains descriptive information
+ about a resource.
+
+
+
+
+
+Goland, et al. Standards Track [Page 7]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Live Property - A property whose semantics and syntax are enforced by
+ the server. For example, the live "getcontentlength" property has
+ its value, the length of the entity returned by a GET request,
+ automatically calculated by the server.
+
+ Dead Property - A property whose semantics and syntax are not
+ enforced by the server. The server only records the value of a dead
+ property; the client is responsible for maintaining the consistency
+ of the syntax and semantics of a dead property.
+
+ Null Resource - A resource which responds with a 404 (Not Found) to
+ any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK.
+ A NULL resource MUST NOT appear as a member of its parent collection.
+
+4 Data Model for Resource Properties
+
+4.1 The Resource Property Model
+
+ Properties are pieces of data that describe the state of a resource.
+ Properties are data about data.
+
+ Properties are used in distributed authoring environments to provide
+ for efficient discovery and management of resources. For example, a
+ 'subject' property might allow for the indexing of all resources by
+ their subject, and an 'author' property might allow for the discovery
+ of what authors have written which documents.
+
+ The DAV property model consists of name/value pairs. The name of a
+ property identifies the property's syntax and semantics, and provides
+ an address by which to refer to its syntax and semantics.
+
+ There are two categories of properties: "live" and "dead". A live
+ property has its syntax and semantics enforced by the server. Live
+ properties include cases where a) the value of a property is read-
+ only, maintained by the server, and b) the value of the property is
+ maintained by the client, but the server performs syntax checking on
+ submitted values. All instances of a given live property MUST comply
+ with the definition associated with that property name. A dead
+ property has its syntax and semantics enforced by the client; the
+ server merely records the value of the property verbatim.
+
+4.2 Existing Metadata Proposals
+
+ Properties have long played an essential role in the maintenance of
+ large document repositories, and many current proposals contain some
+ notion of a property, or discuss web metadata more generally. These
+ include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several
+ proposals on representing relationships within HTML. Work on PICS-NG
+
+
+
+Goland, et al. Standards Track [Page 8]
+
+RFC 2518 WEBDAV February 1999
+
+
+ and Web Collections has been subsumed by the Resource Description
+ Framework (RDF) metadata activity of the World Wide Web Consortium.
+ RDF consists of a network-based data model and an XML representation
+ of that model.
+
+ Some proposals come from a digital library perspective. These
+ include the Dublin Core [RFC2413] metadata set and the Warwick
+ Framework [WF], a container architecture for different metadata
+ schemas. The literature includes many examples of metadata,
+ including MARC [USMARC], a bibliographic metadata format, and a
+ technical report bibliographic format employed by the Dienst system
+ [RFC1807]. Additionally, the proceedings from the first IEEE Metadata
+ conference describe many community-specific metadata sets.
+
+ Participants of the 1996 Metadata II Workshop in Warwick, UK [WF],
+ noted that "new metadata sets will develop as the networked
+ infrastructure matures" and "different communities will propose,
+ design, and be responsible for different types of metadata." These
+ observations can be corroborated by noting that many community-
+ specific sets of metadata already exist, and there is significant
+ motivation for the development of new forms of metadata as many
+ communities increasingly make their data available in digital form,
+ requiring a metadata format to assist data location and cataloging.
+
+4.3 Properties and HTTP Headers
+
+ Properties already exist, in a limited sense, in HTTP message
+ headers. However, in distributed authoring environments a relatively
+ large number of properties are needed to describe the state of a
+ resource, and setting/returning them all through HTTP headers is
+ inefficient. Thus a mechanism is needed which allows a principal to
+ identify a set of properties in which the principal is interested and
+ to set or retrieve just those properties.
+
+4.4 Property Values
+
+ The value of a property when expressed in XML MUST be well formed.
+
+ XML has been chosen because it is a flexible, self-describing,
+ structured data format that supports rich schema definitions, and
+ because of its support for multiple character sets. XML's self-
+ describing nature allows any property's value to be extended by
+ adding new elements. Older clients will not break when they
+ encounter extensions because they will still have the data specified
+ in the original schema and will ignore elements they do not
+ understand. XML's support for multiple character sets allows any
+ human-readable property to be encoded and read in a character set
+ familiar to the user. XML's support for multiple human languages,
+
+
+
+Goland, et al. Standards Track [Page 9]
+
+RFC 2518 WEBDAV February 1999
+
+
+ using the "xml:lang" attribute, handles cases where the same
+ character set is employed by multiple human languages.
+
+4.5 Property Names
+
+ A property name is a universally unique identifier that is associated
+ with a schema that provides information about the syntax and
+ semantics of the property.
+
+ Because a property's name is universally unique, clients can depend
+ upon consistent behavior for a particular property across multiple
+ resources, on the same and across different servers, so long as that
+ property is "live" on the resources in question, and the
+ implementation of the live property is faithful to its definition.
+
+ The XML namespace mechanism, which is based on URIs [RFC2396], is
+ used to name properties because it prevents namespace collisions and
+ provides for varying degrees of administrative control.
+
+ The property namespace is flat; that is, no hierarchy of properties
+ is explicitly recognized. Thus, if a property A and a property A/B
+ exist on a resource, there is no recognition of any relationship
+ between the two properties. It is expected that a separate
+ specification will eventually be produced which will address issues
+ relating to hierarchical properties.
+
+ Finally, it is not possible to define the same property twice on a
+ single resource, as this would cause a collision in the resource's
+ property namespace.
+
+4.6 Media Independent Links
+
+ Although HTML resources support links to other resources, the Web
+ needs more general support for links between resources of any media
+ type (media types are also known as MIME types, or content types).
+ WebDAV provides such links. A WebDAV link is a special type of
+ property value, formally defined in section 12.4, that allows typed
+ connections to be established between resources of any media type.
+ The property value consists of source and destination Uniform
+ Resource Identifiers (URIs); the property name identifies the link
+ type.
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 10]
+
+RFC 2518 WEBDAV February 1999
+
+
+5 Collections of Web Resources
+
+ This section provides a description of a new type of Web resource,
+ the collection, and discusses its interactions with the HTTP URL
+ namespace. The purpose of a collection resource is to model
+ collection-like objects (e.g., file system directories) within a
+ server's namespace.
+
+ All DAV compliant resources MUST support the HTTP URL namespace model
+ specified herein.
+
+5.1 HTTP URL Namespace Model
+
+ The HTTP URL namespace is a hierarchical namespace where the
+ hierarchy is delimited with the "/" character.
+
+ An HTTP URL namespace is said to be consistent if it meets the
+ following conditions: for every URL in the HTTP hierarchy there
+ exists a collection that contains that URL as an internal member.
+ The root, or top-level collection of the namespace under
+ consideration is exempt from the previous rule.
+
+ Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
+ namespace be consistent. However, certain WebDAV methods are
+ prohibited from producing results that cause namespace
+ inconsistencies.
+
+ Although implicit in [RFC2068] and [RFC2396], any resource, including
+ collection resources, MAY be identified by more than one URI. For
+ example, a resource could be identified by multiple HTTP URLs.
+
+5.2 Collection Resources
+
+ A collection is a resource whose state consists of at least a list of
+ internal member URIs and a set of properties, but which may have
+ additional state such as entity bodies returned by GET. An internal
+ member URI MUST be immediately relative to a base URI of the
+ collection. That is, the internal member URI is equal to a
+ containing collection's URI plus an additional segment for non-
+ collection resources, or additional segment plus trailing slash "/"
+ for collection resources, where segment is defined in section 3.3 of
+ [RFC2396].
+
+ Any given internal member URI MUST only belong to the collection
+ once, i.e., it is illegal to have multiple instances of the same URI
+ in a collection. Properties defined on collections behave exactly as
+ do properties on non-collection resources.
+
+
+
+
+Goland, et al. Standards Track [Page 11]
+
+RFC 2518 WEBDAV February 1999
+
+
+ For all WebDAV compliant resources A and B, identified by URIs U and
+ V, for which U is immediately relative to V, B MUST be a collection
+ that has U as an internal member URI. So, if the resource with URL
+ http://foo.com/bar/blah is WebDAV compliant and if the resource with
+ URL http://foo.com/bar/ is WebDAV compliant then the resource with
+ URL http://foo.com/bar/ must be a collection and must contain URL
+ http://foo.com/bar/blah as an internal member.
+
+ Collection resources MAY list the URLs of non-WebDAV compliant
+ children in the HTTP URL namespace hierarchy as internal members but
+ are not required to do so. For example, if the resource with URL
+ http://foo.com/bar/blah is not WebDAV compliant and the URL
+ http://foo.com/bar/ identifies a collection then URL
+ http://foo.com/bar/blah may or may not be an internal member of the
+ collection with URL http://foo.com/bar/.
+
+ If a WebDAV compliant resource has no WebDAV compliant children in
+ the HTTP URL namespace hierarchy then the WebDAV compliant resource
+ is not required to be a collection.
+
+ There is a standing convention that when a collection is referred to
+ by its name without a trailing slash, the trailing slash is
+ automatically appended. Due to this, a resource may accept a URI
+ without a trailing "/" to point to a collection. In this case it
+ SHOULD return a content-location header in the response pointing to
+ the URI ending with the "/". For example, if a client invokes a
+ method on http://foo.bar/blah (no trailing slash), the resource
+ http://foo.bar/blah/ (trailing slash) may respond as if the operation
+ were invoked on it, and should return a content-location header with
+ http://foo.bar/blah/ in it. In general clients SHOULD use the "/"
+ form of collection names.
+
+ A resource MAY be a collection but not be WebDAV compliant. That is,
+ the resource may comply with all the rules set out in this
+ specification regarding how a collection is to behave without
+ necessarily supporting all methods that a WebDAV compliant resource
+ is required to support. In such a case the resource may return the
+ DAV:resourcetype property with the value DAV:collection but MUST NOT
+ return a DAV header containing the value "1" on an OPTIONS response.
+
+5.3 Creation and Retrieval of Collection Resources
+
+ This document specifies the MKCOL method to create new collection
+ resources, rather than using the existing HTTP/1.1 PUT or POST
+ method, for the following reasons:
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 12]
+
+RFC 2518 WEBDAV February 1999
+
+
+ In HTTP/1.1, the PUT method is defined to store the request body at
+ the location specified by the Request-URI. While a description
+ format for a collection can readily be constructed for use with PUT,
+ the implications of sending such a description to the server are
+ undesirable. For example, if a description of a collection that
+ omitted some existing resources were PUT to a server, this might be
+ interpreted as a command to remove those members. This would extend
+ PUT to perform DELETE functionality, which is undesirable since it
+ changes the semantics of PUT, and makes it difficult to control
+ DELETE functionality with an access control scheme based on methods.
+
+ While the POST method is sufficiently open-ended that a "create a
+ collection" POST command could be constructed, this is undesirable
+ because it would be difficult to separate access control for
+ collection creation from other uses of POST.
+
+ The exact definition of the behavior of GET and PUT on collections is
+ defined later in this document.
+
+5.4 Source Resources and Output Resources
+
+ For many resources, the entity returned by a GET method exactly
+ matches the persistent state of the resource, for example, a GIF file
+ stored on a disk. For this simple case, the URI at which a resource
+ is accessed is identical to the URI at which the source (the
+ persistent state) of the resource is accessed. This is also the case
+ for HTML source files that are not processed by the server prior to
+ transmission.
+
+ However, the server can sometimes process HTML resources before they
+ are transmitted as a return entity body. For example, a server-
+ side-include directive within an HTML file might instruct a server to
+ replace the directive with another value, such as the current date.
+ In this case, what is returned by GET (HTML plus date) differs from
+ the persistent state of the resource (HTML plus directive).
+ Typically there is no way to access the HTML resource containing the
+ unprocessed directive.
+
+ Sometimes the entity returned by GET is the output of a data-
+ producing process that is described by one or more source resources
+ (that may not even have a location in the URI namespace). A single
+ data-producing process may dynamically generate the state of a
+ potentially large number of output resources. An example of this is
+ a CGI script that describes a "finger" gateway process that maps part
+ of the namespace of a server into finger requests, such as
+ http://www.foo.bar.org/finger_gateway/user@host.
+
+
+
+
+
+Goland, et al. Standards Track [Page 13]
+
+RFC 2518 WEBDAV February 1999
+
+
+ In the absence of distributed authoring capabilities, it is
+ acceptable to have no mapping of source resource(s) to the URI
+ namespace. In fact, preventing access to the source resource(s) has
+ desirable security benefits. However, if remote editing of the
+ source resource(s) is desired, the source resource(s) should be given
+ a location in the URI namespace. This source location should not be
+ one of the locations at which the generated output is retrievable,
+ since in general it is impossible for the server to differentiate
+ requests for source resources from requests for process output
+ resources. There is often a many-to-many relationship between source
+ resources and output resources.
+
+ On WebDAV compliant servers the URI of the source resource(s) may be
+ stored in a link on the output resource with type DAV:source (see
+ section 13.10 for a description of the source link property).
+ Storing the source URIs in links on the output resources places the
+ burden of discovering the source on the authoring client. Note that
+ the value of a source link is not guaranteed to point to the correct
+ source. Source links may break or incorrect values may be entered.
+ Also note that not all servers will allow the client to set the
+ source link value. For example a server which generates source links
+ on the fly for its CGI files will most likely not allow a client to
+ set the source link value.
+
+6 Locking
+
+ The ability to lock a resource provides a mechanism for serializing
+ access to that resource. Using a lock, an authoring client can
+ provide a reasonable guarantee that another principal will not modify
+ a resource while it is being edited. In this way, a client can
+ prevent the "lost update" problem.
+
+ This specification allows locks to vary over two client-specified
+ parameters, the number of principals involved (exclusive vs. shared)
+ and the type of access to be granted. This document defines locking
+ for only one access type, write. However, the syntax is extensible,
+ and permits the eventual specification of locking for other access
+ types.
+
+6.1 Exclusive Vs. Shared Locks
+
+ The most basic form of lock is an exclusive lock. This is a lock
+ where the access right in question is only granted to a single
+ principal. The need for this arbitration results from a desire to
+ avoid having to merge results.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 14]
+
+RFC 2518 WEBDAV February 1999
+
+
+ However, there are times when the goal of a lock is not to exclude
+ others from exercising an access right but rather to provide a
+ mechanism for principals to indicate that they intend to exercise
+ their access rights. Shared locks are provided for this case. A
+ shared lock allows multiple principals to receive a lock. Hence any
+ principal with appropriate access can get the lock.
+
+ With shared locks there are two trust sets that affect a resource.
+ The first trust set is created by access permissions. Principals who
+ are trusted, for example, may have permission to write to the
+ resource. Among those who have access permission to write to the
+ resource, the set of principals who have taken out a shared lock also
+ must trust each other, creating a (typically) smaller trust set
+ within the access permission write set.
+
+ Starting with every possible principal on the Internet, in most
+ situations the vast majority of these principals will not have write
+ access to a given resource. Of the small number who do have write
+ access, some principals may decide to guarantee their edits are free
+ from overwrite conflicts by using exclusive write locks. Others may
+ decide they trust their collaborators will not overwrite their work
+ (the potential set of collaborators being the set of principals who
+ have write permission) and use a shared lock, which informs their
+ collaborators that a principal may be working on the resource.
+
+ The WebDAV extensions to HTTP do not need to provide all of the
+ communications paths necessary for principals to coordinate their
+ activities. When using shared locks, principals may use any out of
+ band communication channel to coordinate their work (e.g., face-to-
+ face interaction, written notes, post-it notes on the screen,
+ telephone conversation, Email, etc.) The intent of a shared lock is
+ to let collaborators know who else may be working on a resource.
+
+ Shared locks are included because experience from web distributed
+ authoring systems has indicated that exclusive locks are often too
+ rigid. An exclusive lock is used to enforce a particular editing
+ process: take out an exclusive lock, read the resource, perform
+ edits, write the resource, release the lock. This editing process
+ has the problem that locks are not always properly released, for
+ example when a program crashes, or when a lock owner leaves without
+ unlocking a resource. While both timeouts and administrative action
+ can be used to remove an offending lock, neither mechanism may be
+ available when needed; the timeout may be long or the administrator
+ may not be available.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 15]
+
+RFC 2518 WEBDAV February 1999
+
+
+6.2 Required Support
+
+ A WebDAV compliant server is not required to support locking in any
+ form. If the server does support locking it may choose to support
+ any combination of exclusive and shared locks for any access types.
+
+ The reason for this flexibility is that locking policy strikes to the
+ very heart of the resource management and versioning systems employed
+ by various storage repositories. These repositories require control
+ over what sort of locking will be made available. For example, some
+ repositories only support shared write locks while others only
+ provide support for exclusive write locks while yet others use no
+ locking at all. As each system is sufficiently different to merit
+ exclusion of certain locking features, this specification leaves
+ locking as the sole axis of negotiation within WebDAV.
+
+6.3 Lock Tokens
+
+ A lock token is a type of state token, represented as a URI, which
+ identifies a particular lock. A lock token is returned by every
+ successful LOCK operation in the lockdiscovery property in the
+ response body, and can also be found through lock discovery on a
+ resource.
+
+ Lock token URIs MUST be unique across all resources for all time.
+ This uniqueness constraint allows lock tokens to be submitted across
+ resources and servers without fear of confusion.
+
+ This specification provides a lock token URI scheme called
+ opaquelocktoken that meets the uniqueness requirements. However
+ resources are free to return any URI scheme so long as it meets the
+ uniqueness requirements.
+
+ Having a lock token provides no special access rights. Anyone can
+ find out anyone else's lock token by performing lock discovery.
+ Locks MUST be enforced based upon whatever authentication mechanism
+ is used by the server, not based on the secrecy of the token values.
+
+6.4 opaquelocktoken Lock Token URI Scheme
+
+ The opaquelocktoken URI scheme is designed to be unique across all
+ resources for all time. Due to this uniqueness quality, a client may
+ submit an opaque lock token in an If header on a resource other than
+ the one that returned it.
+
+ All resources MUST recognize the opaquelocktoken scheme and, at
+ minimum, recognize that the lock token does not refer to an
+ outstanding lock on the resource.
+
+
+
+Goland, et al. Standards Track [Page 16]
+
+RFC 2518 WEBDAV February 1999
+
+
+ In order to guarantee uniqueness across all resources for all time
+ the opaquelocktoken requires the use of the Universal Unique
+ Identifier (UUID) mechanism, as described in [ISO-11578].
+
+ Opaquelocktoken generators, however, have a choice of how they create
+ these tokens. They can either generate a new UUID for every lock
+ token they create or they can create a single UUID and then add
+ extension characters. If the second method is selected then the
+ program generating the extensions MUST guarantee that the same
+ extension will never be used twice with the associated UUID.
+
+ OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The UUID
+ production is the string representation of a UUID, as defined in
+ [ISO-11578]. Note that white space (LWS) is not allowed between
+ elements of this production.
+
+ Extension = path ; path is defined in section 3.2.1 of RFC 2068
+ [RFC2068]
+
+6.4.1 Node Field Generation Without the IEEE 802 Address
+
+ UUIDs, as defined in [ISO-11578], contain a "node" field that
+ contains one of the IEEE 802 addresses for the server machine. As
+ noted in section 17.8, there are several security risks associated
+ with exposing a machine's IEEE 802 address. This section provides an
+ alternate mechanism for generating the "node" field of a UUID which
+ does not employ an IEEE 802 address. WebDAV servers MAY use this
+ algorithm for creating the node field when generating UUIDs. The
+ text in this section is originally from an Internet-Draft by Paul
+ Leach and Rich Salz, who are noted here to properly attribute their
+ work.
+
+ The ideal solution is to obtain a 47 bit cryptographic quality random
+ number, and use it as the low 47 bits of the node ID, with the most
+ significant bit of the first octet of the node ID set to 1. This bit
+ is the unicast/multicast bit, which will never be set in IEEE 802
+ addresses obtained from network cards; hence, there can never be a
+ conflict between UUIDs generated by machines with and without network
+ cards.
+
+ If a system does not have a primitive to generate cryptographic
+ quality random numbers, then in most systems there are usually a
+ fairly large number of sources of randomness available from which one
+ can be generated. Such sources are system specific, but often
+ include:
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 17]
+
+RFC 2518 WEBDAV February 1999
+
+
+ - the percent of memory in use
+ - the size of main memory in bytes
+ - the amount of free main memory in bytes
+ - the size of the paging or swap file in bytes
+ - free bytes of paging or swap file
+ - the total size of user virtual address space in bytes
+ - the total available user address space bytes
+ - the size of boot disk drive in bytes
+ - the free disk space on boot drive in bytes
+ - the current time
+ - the amount of time since the system booted
+ - the individual sizes of files in various system directories
+ - the creation, last read, and modification times of files in
+ various system directories
+ - the utilization factors of various system resources (heap, etc.)
+ - current mouse cursor position
+ - current caret position
+ - current number of running processes, threads
+ - handles or IDs of the desktop window and the active window
+ - the value of stack pointer of the caller
+ - the process and thread ID of caller
+ - various processor architecture specific performance counters
+ (instructions executed, cache misses, TLB misses)
+
+ (Note that it is precisely the above kinds of sources of randomness
+ that are used to seed cryptographic quality random number generators
+ on systems without special hardware for their construction.)
+
+ In addition, items such as the computer's name and the name of the
+ operating system, while not strictly speaking random, will help
+ differentiate the results from those obtained by other systems.
+
+ The exact algorithm to generate a node ID using these data is system
+ specific, because both the data available and the functions to obtain
+ them are often very system specific. However, assuming that one can
+ concatenate all the values from the randomness sources into a buffer,
+ and that a cryptographic hash function such as MD5 is available, then
+ any 6 bytes of the MD5 hash of the buffer, with the multicast bit
+ (the high bit of the first byte) set will be an appropriately random
+ node ID.
+
+ Other hash functions, such as SHA-1, can also be used. The only
+ requirement is that the result be suitably random _ in the sense that
+ the outputs from a set uniformly distributed inputs are themselves
+ uniformly distributed, and that a single bit change in the input can
+ be expected to cause half of the output bits to change.
+
+
+
+
+
+Goland, et al. Standards Track [Page 18]
+
+RFC 2518 WEBDAV February 1999
+
+
+6.5 Lock Capability Discovery
+
+ Since server lock support is optional, a client trying to lock a
+ resource on a server can either try the lock and hope for the best,
+ or perform some form of discovery to determine what lock capabilities
+ the server supports. This is known as lock capability discovery.
+ Lock capability discovery differs from discovery of supported access
+ control types, since there may be access control types without
+ corresponding lock types. A client can determine what lock types the
+ server supports by retrieving the supportedlock property.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the supportedlock property.
+
+6.6 Active Lock Discovery
+
+ If another principal locks a resource that a principal wishes to
+ access, it is useful for the second principal to be able to find out
+ who the first principal is. For this purpose the lockdiscovery
+ property is provided. This property lists all outstanding locks,
+ describes their type, and where available, provides their lock token.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the lockdiscovery property.
+
+6.7 Usage Considerations
+
+ Although the locking mechanisms specified here provide some help in
+ preventing lost updates, they cannot guarantee that updates will
+ never be lost. Consider the following scenario:
+
+ Two clients A and B are interested in editing the resource '
+ index.html'. Client A is an HTTP client rather than a WebDAV client,
+ and so does not know how to perform locking.
+ Client A doesn't lock the document, but does a GET and begins
+ editing.
+ Client B does LOCK, performs a GET and begins editing.
+ Client B finishes editing, performs a PUT, then an UNLOCK.
+ Client A performs a PUT, overwriting and losing all of B's changes.
+
+ There are several reasons why the WebDAV protocol itself cannot
+ prevent this situation. First, it cannot force all clients to use
+ locking because it must be compatible with HTTP clients that do not
+ comprehend locking. Second, it cannot require servers to support
+ locking because of the variety of repository implementations, some of
+ which rely on reservations and merging rather than on locking.
+ Finally, being stateless, it cannot enforce a sequence of operations
+ like LOCK / GET / PUT / UNLOCK.
+
+
+
+Goland, et al. Standards Track [Page 19]
+
+RFC 2518 WEBDAV February 1999
+
+
+ WebDAV servers that support locking can reduce the likelihood that
+ clients will accidentally overwrite each other's changes by requiring
+ clients to lock resources before modifying them. Such servers would
+ effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
+ resources.
+
+ WebDAV clients can be good citizens by using a lock / retrieve /
+ write /unlock sequence of operations (at least by default) whenever
+ they interact with a WebDAV server that supports locking.
+
+ HTTP 1.1 clients can be good citizens, avoiding overwriting other
+ clients' changes, by using entity tags in If-Match headers with any
+ requests that would modify resources.
+
+ Information managers may attempt to prevent overwrites by
+ implementing client-side procedures requiring locking before
+ modifying WebDAV resources.
+
+7 Write Lock
+
+ This section describes the semantics specific to the write lock type.
+ The write lock is a specific instance of a lock type, and is the only
+ lock type described in this specification.
+
+7.1 Methods Restricted by Write Locks
+
+ A write lock MUST prevent a principal without the lock from
+ successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE,
+ DELETE, or MKCOL on the locked resource. All other current methods,
+ GET in particular, function independently of the lock.
+
+ Note, however, that as new methods are created it will be necessary
+ to specify how they interact with a write lock.
+
+7.2 Write Locks and Lock Tokens
+
+ A successful request for an exclusive or shared write lock MUST
+ result in the generation of a unique lock token associated with the
+ requesting principal. Thus if five principals have a shared write
+ lock on the same resource there will be five lock tokens, one for
+ each principal.
+
+7.3 Write Locks and Properties
+
+ While those without a write lock may not alter a property on a
+ resource it is still possible for the values of live properties to
+ change, even while locked, due to the requirements of their schemas.
+
+
+
+
+Goland, et al. Standards Track [Page 20]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Only dead properties and live properties defined to respect locks are
+ guaranteed not to change while write locked.
+
+7.4 Write Locks and Null Resources
+
+ It is possible to assert a write lock on a null resource in order to
+ lock the name.
+
+ A write locked null resource, referred to as a lock-null resource,
+ MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to
+ any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND,
+ LOCK, and UNLOCK. A lock-null resource MUST appear as a member of
+ its parent collection. Additionally the lock-null resource MUST have
+ defined on it all mandatory DAV properties. Most of these
+ properties, such as all the get* properties, will have no value as a
+ lock-null resource does not support the GET method. Lock-Null
+ resources MUST have defined values for lockdiscovery and
+ supportedlock properties.
+
+ Until a method such as PUT or MKCOL is successfully executed on the
+ lock-null resource the resource MUST stay in the lock-null state.
+ However, once a PUT or MKCOL is successfully executed on a lock-null
+ resource the resource ceases to be in the lock-null state.
+
+ If the resource is unlocked, for any reason, without a PUT, MKCOL, or
+ similar method having been successfully executed upon it then the
+ resource MUST return to the null state.
+
+7.5 Write Locks and Collections
+
+ A write lock on a collection, whether created by a "Depth: 0" or
+ "Depth: infinity" lock request, prevents the addition or removal of
+ member URIs of the collection by non-lock owners. As a consequence,
+ when a principal issues a PUT or POST request to create a new
+ resource under a URI which needs to be an internal member of a write
+ locked collection to maintain HTTP namespace consistency, or issues a
+ DELETE to remove a resource which has a URI which is an existing
+ internal member URI of a write locked collection, this request MUST
+ fail if the principal does not have a write lock on the collection.
+
+ However, if a write lock request is issued to a collection containing
+ member URIs identifying resources that are currently locked in a
+ manner which conflicts with the write lock, the request MUST fail
+ with a 423 (Locked) status code.
+
+ If a lock owner causes the URI of a resource to be added as an
+ internal member URI of a locked collection then the new resource MUST
+ be automatically added to the lock. This is the only mechanism that
+
+
+
+Goland, et al. Standards Track [Page 21]
+
+RFC 2518 WEBDAV February 1999
+
+
+ allows a resource to be added to a write lock. Thus, for example, if
+ the collection /a/b/ is write locked and the resource /c is moved to
+ /a/b/c then resource /a/b/c will be added to the write lock.
+
+7.6 Write Locks and the If Request Header
+
+ If a user agent is not required to have knowledge about a lock when
+ requesting an operation on a locked resource, the following scenario
+ might occur. Program A, run by User A, takes out a write lock on a
+ resource. Program B, also run by User A, has no knowledge of the
+ lock taken out by Program A, yet performs a PUT to the locked
+ resource. In this scenario, the PUT succeeds because locks are
+ associated with a principal, not a program, and thus program B,
+ because it is acting with principal A's credential, is allowed to
+ perform the PUT. However, had program B known about the lock, it
+ would not have overwritten the resource, preferring instead to
+ present a dialog box describing the conflict to the user. Due to
+ this scenario, a mechanism is needed to prevent different programs
+ from accidentally ignoring locks taken out by other programs with the
+ same authorization.
+
+ In order to prevent these collisions a lock token MUST be submitted
+ by an authorized principal in the If header for all locked resources
+ that a method may interact with or the method MUST fail. For
+ example, if a resource is to be moved and both the source and
+ destination are locked then two lock tokens must be submitted, one
+ for the source and the other for the destination.
+
+7.6.1 Example - Write Lock
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+ If: <http://www.ics.uci.edu/users/f/fielding/index.html>
+ (<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, even though both the source and destination are
+ locked, only one lock token must be submitted, for the lock on the
+ destination. This is because the source resource is not modified by
+ a COPY, and hence unaffected by the write lock. In this example, user
+ agent authentication has previously occurred via a mechanism outside
+ the scope of the HTTP protocol, in the underlying transport layer.
+
+
+
+Goland, et al. Standards Track [Page 22]
+
+RFC 2518 WEBDAV February 1999
+
+
+7.7 Write Locks and COPY/MOVE
+
+ A COPY method invocation MUST NOT duplicate any write locks active on
+ the source. However, as previously noted, if the COPY copies the
+ resource into a collection that is locked with "Depth: infinity",
+ then the resource will be added to the lock.
+
+ A successful MOVE request on a write locked resource MUST NOT move
+ the write lock with the resource. However, the resource is subject to
+ being added to an existing lock at the destination, as specified in
+ section 7.5. For example, if the MOVE makes the resource a child of a
+ collection that is locked with "Depth: infinity", then the resource
+ will be added to that collection's lock. Additionally, if a resource
+ locked with "Depth: infinity" is moved to a destination that is
+ within the scope of the same lock (e.g., within the namespace tree
+ covered by the lock), the moved resource will again be a added to the
+ lock. In both these examples, as specified in section 7.6, an If
+ header must be submitted containing a lock token for both the source
+ and destination.
+
+7.8 Refreshing Write Locks
+
+ A client MUST NOT submit the same write lock request twice. Note
+ that a client is always aware it is resubmitting the same lock
+ request because it must include the lock token in the If header in
+ order to make the request for a resource that is already locked.
+
+ However, a client may submit a LOCK method with an If header but
+ without a body. This form of LOCK MUST only be used to "refresh" a
+ lock. Meaning, at minimum, that any timers associated with the lock
+ MUST be re-set.
+
+ A server may return a Timeout header with a lock refresh that is
+ different than the Timeout header returned when the lock was
+ originally requested. Additionally clients may submit Timeout
+ headers of arbitrary value with their lock refresh requests.
+ Servers, as always, may ignore Timeout headers submitted by the
+ client.
+
+ If an error is received in response to a refresh LOCK request the
+ client SHOULD assume that the lock was not refreshed.
+
+8 HTTP Methods for Distributed Authoring
+
+ The following new HTTP methods use XML as a request and response
+ format. All DAV compliant clients and resources MUST use XML parsers
+ that are compliant with [REC-XML]. All XML used in either requests
+ or responses MUST be, at minimum, well formed. If a server receives
+
+
+
+Goland, et al. Standards Track [Page 23]
+
+RFC 2518 WEBDAV February 1999
+
+
+ ill-formed XML in a request it MUST reject the entire request with a
+ 400 (Bad Request). If a client receives ill-formed XML in a response
+ then it MUST NOT assume anything about the outcome of the executed
+ method and SHOULD treat the server as malfunctioning.
+
+8.1 PROPFIND
+
+ The PROPFIND method retrieves properties defined on the resource
+ identified by the Request-URI, if the resource does not have any
+ internal members, or on the resource identified by the Request-URI
+ and potentially its member resources, if the resource is a collection
+ that has internal member URIs. All DAV compliant resources MUST
+ support the PROPFIND method and the propfind XML element (section
+ 12.14) along with all XML elements defined for use with that element.
+
+ A client may submit a Depth header with a value of "0", "1", or
+ "infinity" with a PROPFIND on a collection resource with internal
+ member URIs. DAV compliant servers MUST support the "0", "1" and
+ "infinity" behaviors. By default, the PROPFIND method without a Depth
+ header MUST act as if a "Depth: infinity" header was included.
+
+ A client may submit a propfind XML element in the body of the request
+ method describing what information is being requested. It is
+ possible to request particular property values, all property values,
+ or a list of the names of the resource's properties. A client may
+ choose not to submit a request body. An empty PROPFIND request body
+ MUST be treated as a request for the names and values of all
+ properties.
+
+ All servers MUST support returning a response of content type
+ text/xml or application/xml that contains a multistatus XML element
+ that describes the results of the attempts to retrieve the various
+ properties.
+
+ If there is an error retrieving a property then a proper error result
+ MUST be included in the response. A request to retrieve the value of
+ a property which does not exist is an error and MUST be noted, if the
+ response uses a multistatus XML element, with a response XML element
+ which contains a 404 (Not Found) status value.
+
+ Consequently, the multistatus XML element for a collection resource
+ with member URIs MUST include a response XML element for each member
+ URI of the collection, to whatever depth was requested. Each response
+ XML element MUST contain an href XML element that gives the URI of
+ the resource on which the properties in the prop XML element are
+ defined. Results for a PROPFIND on a collection resource with
+ internal member URIs are returned as a flat list whose order of
+ entries is not significant.
+
+
+
+Goland, et al. Standards Track [Page 24]
+
+RFC 2518 WEBDAV February 1999
+
+
+ In the case of allprop and propname, if a principal does not have the
+ right to know whether a particular property exists then the property
+ should be silently excluded from the response.
+
+ The results of this method SHOULD NOT be cached.
+
+8.1.1 Example - Retrieving Named Properties
+
+ >>Request
+
+ PROPFIND /file HTTP/1.1
+ Host: www.foo.bar
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <R:DingALing/>
+ <R:Random/>
+ </D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/file</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+ <R:Name>J.J. Johnson</R:Name>
+ </R:author>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><R:DingALing/><R:Random/></D:prop>
+
+
+
+Goland, et al. Standards Track [Page 25]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:responsedescription> The user does not have access to
+ the DingALing property.
+ </D:responsedescription>
+ </D:propstat>
+ </D:response>
+ <D:responsedescription> There has been an access violation error.
+ </D:responsedescription>
+ </D:multistatus>
+
+ In this example, PROPFIND is executed on a non-collection resource
+ http://www.foo.bar/file. The propfind XML element specifies the name
+ of four properties whose values are being requested. In this case
+ only two properties were returned, since the principal issuing the
+ request did not have sufficient access rights to see the third and
+ fourth properties.
+
+8.1.2 Example - Using allprop to Retrieve All Properties
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Depth: 1
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+
+
+
+Goland, et al. Standards Track [Page 26]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <R:Name>Hadrian</R:Name>
+ </R:author>
+ <D:creationdate>
+ 1997-12-01T17:42:21-08:00
+ </D:creationdate>
+ <D:displayname>
+ Example collection
+ </D:displayname>
+ <D:resourcetype><D:collection/></D:resourcetype>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://www.foo.bar/container/front.html</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox>
+ <R:BoxType>Box type B</R:BoxType>
+ </R:bigbox>
+ <D:creationdate>
+ 1997-12-01T18:27:21-08:00
+ </D:creationdate>
+ <D:displayname>
+ Example HTML resource
+ </D:displayname>
+ <D:getcontentlength>
+ 4525
+ </D:getcontentlength>
+ <D:getcontenttype>
+ text/html
+ </D:getcontenttype>
+ <D:getetag>
+ zzyzx
+ </D:getetag>
+ <D:getlastmodified>
+ Monday, 12-Jan-98 09:25:56 GMT
+ </D:getlastmodified>
+
+
+
+Goland, et al. Standards Track [Page 27]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:resourcetype/>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ In this example, PROPFIND was invoked on the resource
+ http://www.foo.bar/container/ with a Depth header of 1, meaning the
+ request applies to the resource and its children, and a propfind XML
+ element containing the allprop XML element, meaning the request
+ should return the name and value of all properties defined on each
+ resource.
+
+ The resource http://www.foo.bar/container/ has six properties defined
+ on it:
+
+ http://www.foo.bar/boxschema/bigbox,
+ http://www.foo.bar/boxschema/author, DAV:creationdate,
+ DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
+
+ The last four properties are WebDAV-specific, defined in section 13.
+ Since GET is not supported on this resource, the get* properties
+ (e.g., getcontentlength) are not defined on this resource. The DAV-
+ specific properties assert that "container" was created on December
+ 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
+ (creationdate), has a name of "Example collection" (displayname), a
+ collection resource type (resourcetype), and supports exclusive write
+ and shared write locks (supportedlock).
+
+ The resource http://www.foo.bar/container/front.html has nine
+ properties defined on it:
+
+ http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
+ property type), DAV:creationdate, DAV:displayname,
+ DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
+ DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
+
+
+
+
+Goland, et al. Standards Track [Page 28]
+
+RFC 2518 WEBDAV February 1999
+
+
+ The DAV-specific properties assert that "front.html" was created on
+ December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
+ (creationdate), has a name of "Example HTML resource" (displayname),
+ a content length of 4525 bytes (getcontentlength), a MIME type of
+ "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was
+ last modified on Monday, January 12, 1998, at 09:25:56 GMT
+ (getlastmodified), has an empty resource type, meaning that it is not
+ a collection (resourcetype), and supports both exclusive write and
+ shared write locks (supportedlock).
+
+8.1.3 Example - Using propname to Retrieve all Property Names
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <propfind xmlns="DAV:">
+ <propname/>
+ </propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <multistatus xmlns="DAV:">
+ <response>
+ <href>http://www.foo.bar/container/</href>
+ <propstat>
+ <prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <creationdate/>
+ <displayname/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ <response>
+ <href>http://www.foo.bar/container/front.html</href>
+
+
+
+Goland, et al. Standards Track [Page 29]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <propstat>
+ <prop xmlns:R="http://www.foo.bar/boxschema/">
+ <R:bigbox/>
+ <creationdate/>
+ <displayname/>
+ <getcontentlength/>
+ <getcontenttype/>
+ <getetag/>
+ <getlastmodified/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ </multistatus>
+
+
+ In this example, PROPFIND is invoked on the collection resource
+ http://www.foo.bar/container/, with a propfind XML element containing
+ the propname XML element, meaning the name of all properties should
+ be returned. Since no Depth header is present, it assumes its
+ default value of "infinity", meaning the name of the properties on
+ the collection and all its progeny should be returned.
+
+ Consistent with the previous example, resource
+ http://www.foo.bar/container/ has six properties defined on it,
+ http://www.foo.bar/boxschema/bigbox,
+ http://www.foo.bar/boxschema/author, DAV:creationdate,
+ DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
+
+ The resource http://www.foo.bar/container/index.html, a member of the
+ "container" collection, has nine properties defined on it,
+ http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
+ DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
+ DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
+ DAV:supportedlock.
+
+ This example also demonstrates the use of XML namespace scoping, and
+ the default namespace. Since the "xmlns" attribute does not contain
+ an explicit "shorthand name" (prefix) letter, the namespace applies
+ by default to all enclosed elements. Hence, all elements which do
+ not explicitly state the namespace to which they belong are members
+ of the "DAV:" namespace schema.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 30]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.2 PROPPATCH
+
+ The PROPPATCH method processes instructions specified in the request
+ body to set and/or remove properties defined on the resource
+ identified by the Request-URI.
+
+ All DAV compliant resources MUST support the PROPPATCH method and
+ MUST process instructions that are specified using the
+ propertyupdate, set, and remove XML elements of the DAV schema.
+ Execution of the directives in this method is, of course, subject to
+ access control constraints. DAV compliant resources SHOULD support
+ the setting of arbitrary dead properties.
+
+ The request message body of a PROPPATCH method MUST contain the
+ propertyupdate XML element. Instruction processing MUST occur in the
+ order instructions are received (i.e., from top to bottom).
+ Instructions MUST either all be executed or none executed. Thus if
+ any error occurs during processing all executed instructions MUST be
+ undone and a proper error result returned. Instruction processing
+ details can be found in the definition of the set and remove
+ instructions in section 12.13.
+
+8.2.1 Status Codes for use with 207 (Multi-Status)
+
+ The following are examples of response codes one would expect to be
+ used in a 207 (Multi-Status) response for this method. Note,
+ however, that unless explicitly prohibited any 2/3/4/5xx series
+ response code may be used in a 207 (Multi-Status) response.
+
+ 200 (OK) - The command succeeded. As there can be a mixture of sets
+ and removes in a body, a 201 (Created) seems inappropriate.
+
+ 403 (Forbidden) - The client, for reasons the server chooses not to
+ specify, cannot alter one of the properties.
+
+ 409 (Conflict) - The client has provided a value whose semantics are
+ not appropriate for the property. This includes trying to set read-
+ only properties.
+
+ 423 (Locked) - The specified resource is locked and the client either
+ is not a lock owner or the lock type requires a lock token to be
+ submitted and the client did not submit it.
+
+ 507 (Insufficient Storage) - The server did not have sufficient space
+ to record the property.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 31]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.2.2 Example - PROPPATCH
+
+ >>Request
+
+ PROPPATCH /bar.html HTTP/1.1
+ Host: www.foo.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propertyupdate xmlns:D="DAV:"
+ xmlns:Z="http://www.w3.com/standards/z39.50/">
+ <D:set>
+ <D:prop>
+ <Z:authors>
+ <Z:Author>Jim Whitehead</Z:Author>
+ <Z:Author>Roy Fielding</Z:Author>
+ </Z:authors>
+ </D:prop>
+ </D:set>
+ <D:remove>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ </D:remove>
+ </D:propertyupdate>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:Z="http://www.w3.com/standards/z39.50">
+ <D:response>
+ <D:href>http://www.foo.com/bar.html</D:href>
+ <D:propstat>
+ <D:prop><Z:Authors/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ <D:status>HTTP/1.1 409 Conflict</D:status>
+ </D:propstat>
+ <D:responsedescription> Copyright Owner can not be deleted or
+ altered.</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+
+
+Goland, et al. Standards Track [Page 32]
+
+RFC 2518 WEBDAV February 1999
+
+
+ In this example, the client requests the server to set the value of
+ the http://www.w3.com/standards/z39.50/Authors property, and to
+ remove the property http://www.w3.com/standards/z39.50/Copyright-
+ Owner. Since the Copyright-Owner property could not be removed, no
+ property modifications occur. The 424 (Failed Dependency) status
+ code for the Authors property indicates this action would have
+ succeeded if it were not for the conflict with removing the
+ Copyright-Owner property.
+
+8.3 MKCOL Method
+
+ The MKCOL method is used to create a new collection. All DAV
+ compliant resources MUST support the MKCOL method.
+
+8.3.1 Request
+
+ MKCOL creates a new collection resource at the location specified by
+ the Request-URI. If the resource identified by the Request-URI is
+ non-null then the MKCOL MUST fail. During MKCOL processing, a server
+ MUST make the Request-URI a member of its parent collection, unless
+ the Request-URI is "/". If no such ancestor exists, the method MUST
+ fail. When the MKCOL operation creates a new collection resource,
+ all ancestors MUST already exist, or the method MUST fail with a 409
+ (Conflict) status code. For example, if a request to create
+ collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists,
+ the request must fail.
+
+ When MKCOL is invoked without a request body, the newly created
+ collection SHOULD have no members.
+
+ A MKCOL request message may contain a message body. The behavior of
+ a MKCOL request when the body is present is limited to creating
+ collections, members of a collection, bodies of members and
+ properties on the collections or members. If the server receives a
+ MKCOL request entity type it does not support or understand it MUST
+ respond with a 415 (Unsupported Media Type) status code. The exact
+ behavior of MKCOL for various request media types is undefined in
+ this document, and will be specified in separate documents.
+
+8.3.2 Status Codes
+
+ Responses from a MKCOL request MUST NOT be cached as MKCOL has non-
+ idempotent semantics.
+
+ 201 (Created) - The collection or structured resource was created in
+ its entirety.
+
+
+
+
+
+Goland, et al. Standards Track [Page 33]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 403 (Forbidden) - This indicates at least one of two conditions: 1)
+ the server does not allow the creation of collections at the given
+ location in its namespace, or 2) the parent collection of the
+ Request-URI exists but cannot accept members.
+
+ 405 (Method Not Allowed) - MKCOL can only be executed on a
+ deleted/non-existent resource.
+
+ 409 (Conflict) - A collection cannot be made at the Request-URI until
+ one or more intermediate collections have been created.
+
+ 415 (Unsupported Media Type)- The server does not support the request
+ type of the body.
+
+ 507 (Insufficient Storage) - The resource does not have sufficient
+ space to record the state of the resource after the execution of this
+ method.
+
+8.3.3 Example - MKCOL
+
+ This example creates a collection called /webdisc/xfiles/ on the
+ server www.server.org.
+
+ >>Request
+
+ MKCOL /webdisc/xfiles/ HTTP/1.1
+ Host: www.server.org
+
+ >>Response
+
+ HTTP/1.1 201 Created
+
+8.4 GET, HEAD for Collections
+
+ The semantics of GET are unchanged when applied to a collection,
+ since GET is defined as, "retrieve whatever information (in the form
+ of an entity) is identified by the Request-URI" [RFC2068]. GET when
+ applied to a collection may return the contents of an "index.html"
+ resource, a human-readable view of the contents of the collection, or
+ something else altogether. Hence it is possible that the result of a
+ GET on a collection will bear no correlation to the membership of the
+ collection.
+
+ Similarly, since the definition of HEAD is a GET without a response
+ message body, the semantics of HEAD are unmodified when applied to
+ collection resources.
+
+
+
+
+
+Goland, et al. Standards Track [Page 34]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.5 POST for Collections
+
+ Since by definition the actual function performed by POST is
+ determined by the server and often depends on the particular
+ resource, the behavior of POST when applied to collections cannot be
+ meaningfully modified because it is largely undefined. Thus the
+ semantics of POST are unmodified when applied to a collection.
+
+8.6 DELETE
+
+ 8.6.1 DELETE for Non-Collection Resources
+
+ If the DELETE method is issued to a non-collection resource whose
+ URIs are an internal member of one or more collections, then during
+ DELETE processing a server MUST remove any URI for the resource
+ identified by the Request-URI from collections which contain it as a
+ member.
+
+8.6.2 DELETE for Collections
+
+ The DELETE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header with
+ a DELETE on a collection with any value but infinity.
+
+ DELETE instructs that the collection specified in the Request-URI and
+ all resources identified by its internal member URIs are to be
+ deleted.
+
+ If any resource identified by a member URI cannot be deleted then all
+ of the member's ancestors MUST NOT be deleted, so as to maintain
+ namespace consistency.
+
+ Any headers included with DELETE MUST be applied in processing every
+ resource to be deleted.
+
+ When the DELETE method has completed processing it MUST result in a
+ consistent namespace.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI then the response MUST be a 207 (Multi-Status).
+ 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi-
+ Status). They can be safely left out because the client will know
+ that the ancestors of a resource could not be deleted when the client
+ receives an error for the ancestor's progeny. Additionally 204 (No
+ Content) errors SHOULD NOT be returned in the 207 (Multi-Status).
+ The reason for this prohibition is that 204 (No Content) is the
+ default success code.
+
+
+
+
+Goland, et al. Standards Track [Page 35]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.6.2.1 Example - DELETE
+
+ >>Request
+
+ DELETE /container/ HTTP/1.1
+ Host: www.foo.bar
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.foo.bar/container/resource3</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ </d:response>
+ </d:multistatus>
+
+ In this example the attempt to delete
+ http://www.foo.bar/container/resource3 failed because it is locked,
+ and no lock token was submitted with the request. Consequently, the
+ attempt to delete http://www.foo.bar/container/ also failed. Thus the
+ client knows that the attempt to delete http://www.foo.bar/container/
+ must have also failed since the parent can not be deleted unless its
+ child has also been deleted. Even though a Depth header has not been
+ included, a depth of infinity is assumed because the method is on a
+ collection.
+
+8.7 PUT
+
+8.7.1 PUT for Non-Collection Resources
+
+ A PUT performed on an existing resource replaces the GET response
+ entity of the resource. Properties defined on the resource may be
+ recomputed during PUT processing but are not otherwise affected. For
+ example, if a server recognizes the content type of the request body,
+ it may be able to automatically extract information that could be
+ profitably exposed as properties.
+
+ A PUT that would result in the creation of a resource without an
+ appropriately scoped parent collection MUST fail with a 409
+ (Conflict).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 36]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.7.2 PUT for Collections
+
+ As defined in the HTTP/1.1 specification [RFC2068], the "PUT method
+ requests that the enclosed entity be stored under the supplied
+ Request-URI." Since submission of an entity representing a
+ collection would implicitly encode creation and deletion of
+ resources, this specification intentionally does not define a
+ transmission format for creating a collection using PUT. Instead,
+ the MKCOL method is defined to create collections.
+
+ When the PUT operation creates a new non-collection resource all
+ ancestors MUST already exist. If all ancestors do not exist, the
+ method MUST fail with a 409 (Conflict) status code. For example, if
+ resource /a/b/c/d.html is to be created and /a/b/c/ does not exist,
+ then the request must fail.
+
+8.8 COPY Method
+
+ The COPY method creates a duplicate of the source resource,
+ identified by the Request-URI, in the destination resource,
+ identified by the URI in the Destination header. The Destination
+ header MUST be present. The exact behavior of the COPY method
+ depends on the type of the source resource.
+
+ All WebDAV compliant resources MUST support the COPY method.
+ However, support for the COPY method does not guarantee the ability
+ to copy a resource. For example, separate programs may control
+ resources on the same server. As a result, it may not be possible to
+ copy a resource to a location that appears to be on the same server.
+
+8.8.1 COPY for HTTP/1.1 resources
+
+ When the source resource is not a collection the result of the COPY
+ method is the creation of a new resource at the destination whose
+ state and behavior match that of the source resource as closely as
+ possible. After a successful COPY invocation, all properties on the
+ source resource MUST be duplicated on the destination resource,
+ subject to modifying headers and XML elements, following the
+ definition for copying properties. Since the environment at the
+ destination may be different than at the source due to factors
+ outside the scope of control of the server, such as the absence of
+ resources required for correct operation, it may not be possible to
+ completely duplicate the behavior of the resource at the destination.
+ Subsequent alterations to the destination resource will not modify
+ the source resource. Subsequent alterations to the source resource
+ will not modify the destination resource.
+
+
+
+
+
+Goland, et al. Standards Track [Page 37]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.8.2. COPY for Properties
+
+ The following section defines how properties on a resource are
+ handled during a COPY operation.
+
+ Live properties SHOULD be duplicated as identically behaving live
+ properties at the destination resource. If a property cannot be
+ copied live, then its value MUST be duplicated, octet-for-octet, in
+ an identically named, dead property on the destination resource
+ subject to the effects of the propertybehavior XML element.
+
+ The propertybehavior XML element can specify that properties are
+ copied on best effort, that all live properties must be successfully
+ copied or the method must fail, or that a specified list of live
+ properties must be successfully copied or the method must fail. The
+ propertybehavior XML element is defined in section 12.12.
+
+8.8.3 COPY for Collections
+
+ The COPY method on a collection without a Depth header MUST act as if
+ a Depth header with value "infinity" was included. A client may
+ submit a Depth header on a COPY on a collection with a value of "0"
+ or "infinity". DAV compliant servers MUST support the "0" and
+ "infinity" Depth header behaviors.
+
+ A COPY of depth infinity instructs that the collection resource
+ identified by the Request-URI is to be copied to the location
+ identified by the URI in the Destination header, and all its internal
+ member resources are to be copied to a location relative to it,
+ recursively through all levels of the collection hierarchy.
+
+ A COPY of "Depth: 0" only instructs that the collection and its
+ properties but not resources identified by its internal member URIs,
+ are to be copied.
+
+ Any headers included with a COPY MUST be applied in processing every
+ resource to be copied with the exception of the Destination header.
+
+ The Destination header only specifies the destination URI for the
+ Request-URI. When applied to members of the collection identified by
+ the Request-URI the value of Destination is to be modified to reflect
+ the current location in the hierarchy. So, if the Request- URI is
+ /a/ with Host header value http://fun.com/ and the Destination is
+ http://fun.com/b/ then when http://fun.com/a/c/d is processed it must
+ use a Destination of http://fun.com/b/c/d.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 38]
+
+RFC 2518 WEBDAV February 1999
+
+
+ When the COPY method has completed processing it MUST have created a
+ consistent namespace at the destination (see section 5.1 for the
+ definition of namespace consistency). However, if an error occurs
+ while copying an internal collection, the server MUST NOT copy any
+ resources identified by members of this collection (i.e., the server
+ must skip this subtree), as this would create an inconsistent
+ namespace. After detecting an error, the COPY operation SHOULD try to
+ finish as much of the original copy operation as possible (i.e., the
+ server should still attempt to copy other subtrees and their members,
+ that are not descendents of an error-causing collection). So, for
+ example, if an infinite depth copy operation is performed on
+ collection /a/, which contains collections /a/b/ and /a/c/, and an
+ error occurs copying /a/b/, an attempt should still be made to copy
+ /a/c/. Similarly, after encountering an error copying a non-
+ collection resource as part of an infinite depth copy, the server
+ SHOULD try to finish as much of the original copy operation as
+ possible.
+
+ If an error in executing the COPY method occurs with a resource other
+ than the resource identified in the Request-URI then the response
+ MUST be a 207 (Multi-Status).
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a COPY method. These responses can
+ be safely omitted because the client will know that the progeny of a
+ resource could not be copied when the client receives an error for
+ the parent. Additionally 201 (Created)/204 (No Content) status codes
+ SHOULD NOT be returned as values in 207 (Multi-Status) responses from
+ COPY methods. They, too, can be safely omitted because they are the
+ default success codes.
+
+8.8.4 COPY and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the copy the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F" then the operation will fail.
+
+8.8.5 Status Codes
+
+ 201 (Created) - The source resource was successfully copied. The
+ copy operation resulted in the creation of a new resource.
+
+ 204 (No Content) - The source resource was successfully copied to a
+ pre-existing destination resource.
+
+ 403 (Forbidden) _ The source and destination URIs are the same.
+
+
+
+
+Goland, et al. Standards Track [Page 39]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 409 (Conflict) _ A resource cannot be created at the destination
+ until one or more intermediate collections have been created.
+
+ 412 (Precondition Failed) - The server was unable to maintain the
+ liveness of the properties listed in the propertybehavior XML element
+ or the Overwrite header is "F" and the state of the destination
+ resource is non-null.
+
+ 423 (Locked) - The destination resource was locked.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+
+ 507 (Insufficient Storage) - The destination resource does not have
+ sufficient space to record the state of the resource after the
+ execution of this method.
+
+8.8.6 Example - COPY with Overwrite
+
+ This example shows resource
+ http://www.ics.uci.edu/~fielding/index.html being copied to the
+ location http://www.ics.uci.edu/users/f/fielding/index.html. The 204
+ (No Content) status code indicates the existing resource at the
+ destination was overwritten.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+8.8.7 Example - COPY with No Overwrite
+
+ The following example shows the same copy operation being performed,
+ but with the Overwrite header set to "F." A response of 412
+ (Precondition Failed) is returned because the destination resource
+ has a non-null state.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+ Overwrite: F
+
+
+
+Goland, et al. Standards Track [Page 40]
+
+RFC 2518 WEBDAV February 1999
+
+
+ >>Response
+
+ HTTP/1.1 412 Precondition Failed
+
+8.8.8 Example - COPY of a Collection
+
+ >>Request
+
+ COPY /container/ HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/othercontainer/
+ Depth: infinity
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:propertybehavior xmlns:d="DAV:">
+ <d:keepalive>*</d:keepalive>
+ </d:propertybehavior>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.foo.bar/othercontainer/R2/</d:href>
+ <d:status>HTTP/1.1 412 Precondition Failed</d:status>
+ </d:response>
+ </d:multistatus>
+
+ The Depth header is unnecessary as the default behavior of COPY on a
+ collection is to act as if a "Depth: infinity" header had been
+ submitted. In this example most of the resources, along with the
+ collection, were copied successfully. However the collection R2
+ failed, most likely due to a problem with maintaining the liveness of
+ properties (this is specified by the propertybehavior XML element).
+ Because there was an error copying R2, none of R2's members were
+ copied. However no errors were listed for those members due to the
+ error minimization rules given in section 8.8.3.
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 41]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.9 MOVE Method
+
+ The MOVE operation on a non-collection resource is the logical
+ equivalent of a copy (COPY), followed by consistency maintenance
+ processing, followed by a delete of the source, where all three
+ actions are performed atomically. The consistency maintenance step
+ allows the server to perform updates caused by the move, such as
+ updating all URIs other than the Request-URI which identify the
+ source resource, to point to the new destination resource.
+ Consequently, the Destination header MUST be present on all MOVE
+ methods and MUST follow all COPY requirements for the COPY part of
+ the MOVE method. All DAV compliant resources MUST support the MOVE
+ method. However, support for the MOVE method does not guarantee the
+ ability to move a resource to a particular destination.
+
+ For example, separate programs may actually control different sets of
+ resources on the same server. Therefore, it may not be possible to
+ move a resource within a namespace that appears to belong to the same
+ server.
+
+ If a resource exists at the destination, the destination resource
+ will be DELETEd as a side-effect of the MOVE operation, subject to
+ the restrictions of the Overwrite header.
+
+8.9.1 MOVE for Properties
+
+ The behavior of properties on a MOVE, including the effects of the
+ propertybehavior XML element, MUST be the same as specified in
+ section 8.8.2.
+
+8.9.2 MOVE for Collections
+
+ A MOVE with "Depth: infinity" instructs that the collection
+ identified by the Request-URI be moved to the URI specified in the
+ Destination header, and all resources identified by its internal
+ member URIs are to be moved to locations relative to it, recursively
+ through all levels of the collection hierarchy.
+
+ The MOVE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header on a
+ MOVE on a collection with any value but "infinity".
+
+ Any headers included with MOVE MUST be applied in processing every
+ resource to be moved with the exception of the Destination header.
+
+ The behavior of the Destination header is the same as given for COPY
+ on collections.
+
+
+
+
+Goland, et al. Standards Track [Page 42]
+
+RFC 2518 WEBDAV February 1999
+
+
+ When the MOVE method has completed processing it MUST have created a
+ consistent namespace at both the source and destination (see section
+ 5.1 for the definition of namespace consistency). However, if an
+ error occurs while moving an internal collection, the server MUST NOT
+ move any resources identified by members of the failed collection
+ (i.e., the server must skip the error-causing subtree), as this would
+ create an inconsistent namespace. In this case, after detecting the
+ error, the move operation SHOULD try to finish as much of the
+ original move as possible (i.e., the server should still attempt to
+ move other subtrees and the resources identified by their members,
+ that are not descendents of an error-causing collection). So, for
+ example, if an infinite depth move is performed on collection /a/,
+ which contains collections /a/b/ and /a/c/, and an error occurs
+ moving /a/b/, an attempt should still be made to try moving /a/c/.
+ Similarly, after encountering an error moving a non-collection
+ resource as part of an infinite depth move, the server SHOULD try to
+ finish as much of the original move operation as possible.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI then the response MUST be a 207 (Multi-Status).
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a MOVE method. These errors can be
+ safely omitted because the client will know that the progeny of a
+ resource could not be moved when the client receives an error for the
+ parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
+ NOT be returned as values in 207 (Multi-Status) responses from a
+ MOVE. These responses can be safely omitted because they are the
+ default success codes.
+
+8.9.3 MOVE and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the move the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F" then the operation will fail.
+
+8.9.4 Status Codes
+
+ 201 (Created) - The source resource was successfully moved, and a new
+ resource was created at the destination.
+
+ 204 (No Content) - The source resource was successfully moved to a
+ pre-existing destination resource.
+
+ 403 (Forbidden) _ The source and destination URIs are the same.
+
+
+
+
+
+Goland, et al. Standards Track [Page 43]
+
+RFC 2518 WEBDAV February 1999
+
+
+ 409 (Conflict) _ A resource cannot be created at the destination
+ until one or more intermediate collections have been created.
+
+ 412 (Precondition Failed) - The server was unable to maintain the
+ liveness of the properties listed in the propertybehavior XML element
+ or the Overwrite header is "F" and the state of the destination
+ resource is non-null.
+
+ 423 (Locked) - The source or the destination resource was locked.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+
+8.9.5 Example - MOVE of a Non-Collection
+
+ This example shows resource
+ http://www.ics.uci.edu/~fielding/index.html being moved to the
+ location http://www.ics.uci.edu/users/f/fielding/index.html. The
+ contents of the destination resource would have been overwritten if
+ the destination resource had been non-null. In this case, since
+ there was nothing at the destination resource, the response code is
+ 201 (Created).
+
+ >>Request
+
+ MOVE /~fielding/index.html HTTP/1.1
+ Host: www.ics.uci.edu
+ Destination: http://www.ics.uci.edu/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 201 Created
+ Location: http://www.ics.uci.edu/users/f/fielding/index.html
+
+
+8.9.6 Example - MOVE of a Collection
+
+ >>Request
+
+ MOVE /container/ HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/othercontainer/
+ Overwrite: F
+ If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
+ (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+Goland, et al. Standards Track [Page 44]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:propertybehavior xmlns:d='DAV:'>
+ <d:keepalive>*</d:keepalive>
+ </d:propertybehavior>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d='DAV:'>
+ <d:response>
+ <d:href>http://www.foo.bar/othercontainer/C2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ </d:response>
+ </d:multistatus>
+
+ In this example the client has submitted a number of lock tokens with
+ the request. A lock token will need to be submitted for every
+ resource, both source and destination, anywhere in the scope of the
+ method, that is locked. In this case the proper lock token was not
+ submitted for the destination http://www.foo.bar/othercontainer/C2/.
+ This means that the resource /container/C2/ could not be moved.
+ Because there was an error copying /container/C2/, none of
+ /container/C2's members were copied. However no errors were listed
+ for those members due to the error minimization rules given in
+ section 8.8.3. User agent authentication has previously occurred via
+ a mechanism outside the scope of the HTTP protocol, in an underlying
+ transport layer.
+
+8.10 LOCK Method
+
+ The following sections describe the LOCK method, which is used to
+ take out a lock of any access type. These sections on the LOCK
+ method describe only those semantics that are specific to the LOCK
+ method and are independent of the access type of the lock being
+ requested.
+
+ Any resource which supports the LOCK method MUST, at minimum, support
+ the XML request and response formats defined herein.
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 45]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.10.1 Operation
+
+ A LOCK method invocation creates the lock specified by the lockinfo
+ XML element on the Request-URI. Lock method requests SHOULD have a
+ XML request body which contains an owner XML element for this lock
+ request, unless this is a refresh request. The LOCK request may have
+ a Timeout header.
+
+ Clients MUST assume that locks may arbitrarily disappear at any time,
+ regardless of the value given in the Timeout header. The Timeout
+ header only indicates the behavior of the server if "extraordinary"
+ circumstances do not occur. For example, an administrator may remove
+ a lock at any time or the system may crash in such a way that it
+ loses the record of the lock's existence. The response MUST contain
+ the value of the lockdiscovery property in a prop XML element.
+
+ In order to indicate the lock token associated with a newly created
+ lock, a Lock-Token response header MUST be included in the response
+ for every successful LOCK request for a new lock. Note that the
+ Lock-Token header would not be returned in the response for a
+ successful refresh LOCK request because a new lock was not created.
+
+8.10.2 The Effect of Locks on Properties and Collections
+
+ The scope of a lock is the entire state of the resource, including
+ its body and associated properties. As a result, a lock on a
+ resource MUST also lock the resource's properties.
+
+ For collections, a lock also affects the ability to add or remove
+ members. The nature of the effect depends upon the type of access
+ control involved.
+
+8.10.3 Locking Replicated Resources
+
+ A resource may be made available through more than one URI. However
+ locks apply to resources, not URIs. Therefore a LOCK request on a
+ resource MUST NOT succeed if can not be honored by all the URIs
+ through which the resource is addressable.
+
+8.10.4 Depth and Locking
+
+ The Depth header may be used with the LOCK method. Values other than
+ 0 or infinity MUST NOT be used with the Depth header on a LOCK
+ method. All resources that support the LOCK method MUST support the
+ Depth header.
+
+ A Depth header of value 0 means to just lock the resource specified
+ by the Request-URI.
+
+
+
+Goland, et al. Standards Track [Page 46]
+
+RFC 2518 WEBDAV February 1999
+
+
+ If the Depth header is set to infinity then the resource specified in
+ the Request-URI along with all its internal members, all the way down
+ the hierarchy, are to be locked. A successful result MUST return a
+ single lock token which represents all the resources that have been
+ locked. If an UNLOCK is successfully executed on this token, all
+ associated resources are unlocked. If the lock cannot be granted to
+ all resources, a 409 (Conflict) status code MUST be returned with a
+ response entity body containing a multistatus XML element describing
+ which resource(s) prevented the lock from being granted. Hence,
+ partial success is not an option. Either the entire hierarchy is
+ locked or no resources are locked.
+
+ If no Depth header is submitted on a LOCK request then the request
+ MUST act as if a "Depth:infinity" had been submitted.
+
+8.10.5 Interaction with other Methods
+
+ The interaction of a LOCK with various methods is dependent upon the
+ lock type. However, independent of lock type, a successful DELETE of
+ a resource MUST cause all of its locks to be removed.
+
+8.10.6 Lock Compatibility Table
+
+ The table below describes the behavior that occurs when a lock
+ request is made on a resource.
+
+ Current lock state/ | Shared Lock | Exclusive
+ Lock request | | Lock
+ =====================+=================+==============
+ None | True | True
+ ---------------------+-----------------+--------------
+ Shared Lock | True | False
+ ---------------------+-----------------+--------------
+ Exclusive Lock | False | False*
+ ------------------------------------------------------
+
+ Legend: True = lock may be granted. False = lock MUST NOT be
+ granted. *=It is illegal for a principal to request the same lock
+ twice.
+
+ The current lock state of a resource is given in the leftmost column,
+ and lock requests are listed in the first row. The intersection of a
+ row and column gives the result of a lock request. For example, if a
+ shared lock is held on a resource, and an exclusive lock is
+ requested, the table entry is "false", indicating the lock must not
+ be granted.
+
+
+
+
+
+Goland, et al. Standards Track [Page 47]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.10.7 Status Codes
+
+ 200 (OK) - The lock request succeeded and the value of the
+ lockdiscovery property is included in the body.
+
+ 412 (Precondition Failed) - The included lock token was not
+ enforceable on this resource or the server could not satisfy the
+ request in the lockinfo XML element.
+
+ 423 (Locked) - The resource is locked, so the method has been
+ rejected.
+
+8.10.8 Example - Simple Lock Request
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw at webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D='DAV:'>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ <D:owner>
+ <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>Infinity</D:depth>
+
+
+
+Goland, et al. Standards Track [Page 48]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:owner>
+ <D:href>
+ http://www.ics.uci.edu/~ejw/contact.html
+ </D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href>
+ opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+ This example shows the successful creation of an exclusive write lock
+ on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc.
+ The resource http://www.ics.uci.edu/~ejw/contact.html contains
+ contact information for the owner of the lock. The server has an
+ activity-based timeout policy in place on this resource, which causes
+ the lock to automatically be removed after 1 week (604800 seconds).
+ Note that the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+8.10.9 Example - Refreshing a Write Lock
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
+ Authorization: Digest username="ejw",
+ realm="ejw at webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+
+
+
+Goland, et al. Standards Track [Page 49]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>Infinity</D:depth>
+ <D:owner>
+ <D:href>
+ http://www.ics.uci.edu/~ejw/contact.html
+ </D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href>
+ opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+ This request would refresh the lock, resetting any time outs. Notice
+ that the client asked for an infinite time out but the server choose
+ to ignore the request. In this example, the nonce, response, and
+ opaque fields have not been calculated in the Authorization request
+ header.
+
+8.10.10 Example - Multi-Resource Lock Request
+
+ >>Request
+
+ LOCK /webdav/ HTTP/1.1
+ Host: webdav.sb.aol.com
+ Timeout: Infinite, Second-4100000000
+ Depth: infinity
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw at webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D="DAV:">
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:owner>
+ <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+
+
+Goland, et al. Standards Track [Page 50]
+
+RFC 2518 WEBDAV February 1999
+
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://webdav.sb.aol.com/webdav/secret</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://webdav.sb.aol.com/webdav/</D:href>
+ <D:propstat>
+ <D:prop><D:lockdiscovery/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ This example shows a request for an exclusive write lock on a
+ collection and all its children. In this request, the client has
+ specified that it desires an infinite length lock, if available,
+ otherwise a timeout of 4.1 billion seconds, if available. The request
+ entity body contains the contact information for the principal taking
+ out the lock, in this case a web page URL.
+
+ The error is a 403 (Forbidden) response on the resource
+ http://webdav.sb.aol.com/webdav/secret. Because this resource could
+ not be locked, none of the resources were locked. Note also that the
+ lockdiscovery property for the Request-URI has been included as
+ required. In this example the lockdiscovery property is empty which
+ means that there are no outstanding locks on the resource.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+8.11 UNLOCK Method
+
+ The UNLOCK method removes the lock identified by the lock token in
+ the Lock-Token request header from the Request-URI, and all other
+ resources included in the lock. If all resources which have been
+ locked under the submitted lock token can not be unlocked then the
+ UNLOCK request MUST fail.
+
+ Any DAV compliant resource which supports the LOCK method MUST
+ support the UNLOCK method.
+
+
+
+
+
+Goland, et al. Standards Track [Page 51]
+
+RFC 2518 WEBDAV February 1999
+
+
+8.11.1 Example - UNLOCK
+
+ >>Request
+
+ UNLOCK /workspace/webdav/info.doc HTTP/1.1
+ Host: webdav.sb.aol.com
+ Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
+ Authorization: Digest username="ejw",
+ realm="ejw at webdav.sb.aol.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, the lock identified by the lock token
+ "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is
+ successfully removed from the resource
+ http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock
+ included more than just one resource, the lock is removed from all
+ resources included in the lock. The 204 (No Content) status code is
+ used instead of 200 (OK) because there is no response entity body.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+9 HTTP Headers for Distributed Authoring
+
+9.1 DAV Header
+
+ DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend]
+
+ This header indicates that the resource supports the DAV schema and
+ protocol as specified. All DAV compliant resources MUST return the
+ DAV header on all OPTIONS responses.
+
+ The value is a list of all compliance classes that the resource
+ supports. Note that above a comma has already been added to the 2.
+ This is because a resource can not be level 2 compliant unless it is
+ also level 1 compliant. Please refer to section 15 for more details.
+ In general, however, support for one compliance class does not entail
+ support for any other.
+
+9.2 Depth Header
+
+ Depth = "Depth" ":" ("0" | "1" | "infinity")
+
+
+
+
+Goland, et al. Standards Track [Page 52]
+
+RFC 2518 WEBDAV February 1999
+
+
+ The Depth header is used with methods executed on resources which
+ could potentially have internal members to indicate whether the
+ method is to be applied only to the resource ("Depth: 0"), to the
+ resource and its immediate children, ("Depth: 1"), or the resource
+ and all its progeny ("Depth: infinity").
+
+ The Depth header is only supported if a method's definition
+ explicitly provides for such support.
+
+ The following rules are the default behavior for any method that
+ supports the Depth header. A method may override these defaults by
+ defining different behavior in its definition.
+
+ Methods which support the Depth header may choose not to support all
+ of the header's values and may define, on a case by case basis, the
+ behavior of the method if a Depth header is not present. For example,
+ the MOVE method only supports "Depth: infinity" and if a Depth header
+ is not present will act as if a "Depth: infinity" header had been
+ applied.
+
+ Clients MUST NOT rely upon methods executing on members of their
+ hierarchies in any particular order or on the execution being atomic
+ unless the particular method explicitly provides such guarantees.
+
+ Upon execution, a method with a Depth header will perform as much of
+ its assigned task as possible and then return a response specifying
+ what it was able to accomplish and what it failed to do.
+
+ So, for example, an attempt to COPY a hierarchy may result in some of
+ the members being copied and some not.
+
+ Any headers on a method that has a defined interaction with the Depth
+ header MUST be applied to all resources in the scope of the method
+ except where alternative behavior is explicitly defined. For example,
+ an If-Match header will have its value applied against every resource
+ in the method's scope and will cause the method to fail if the header
+ fails to match.
+
+ If a resource, source or destination, within the scope of the method
+ with a Depth header is locked in such a way as to prevent the
+ successful execution of the method, then the lock token for that
+ resource MUST be submitted with the request in the If request header.
+
+ The Depth header only specifies the behavior of the method with
+ regards to internal children. If a resource does not have internal
+ children then the Depth header MUST be ignored.
+
+
+
+
+
+Goland, et al. Standards Track [Page 53]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Please note, however, that it is always an error to submit a value
+ for the Depth header that is not allowed by the method's definition.
+ Thus submitting a "Depth: 1" on a COPY, even if the resource does not
+ have internal members, will result in a 400 (Bad Request). The method
+ should fail not because the resource doesn't have internal members,
+ but because of the illegal value in the header.
+
+9.3 Destination Header
+
+ Destination = "Destination" ":" absoluteURI
+
+ The Destination header specifies the URI which identifies a
+ destination resource for methods such as COPY and MOVE, which take
+ two URIs as parameters. Note that the absoluteURI production is
+ defined in [RFC2396].
+
+9.4 If Header
+
+ If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
+ No-tag-list = List
+ Tagged-list = Resource 1*List
+ Resource = Coded-URL
+ List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
+ State-token = Coded-URL
+ Coded-URL = "<" absoluteURI ">"
+
+ The If header is intended to have similar functionality to the If-
+ Match header defined in section 14.25 of [RFC2068]. However the If
+ header is intended for use with any URI which represents state
+ information, referred to as a state token, about a resource as well
+ as ETags. A typical example of a state token is a lock token, and
+ lock tokens are the only state tokens defined in this specification.
+
+ All DAV compliant resources MUST honor the If header.
+
+ The If header's purpose is to describe a series of state lists. If
+ the state of the resource to which the header is applied does not
+ match any of the specified state lists then the request MUST fail
+ with a 412 (Precondition Failed). If one of the described state
+ lists matches the state of the resource then the request may succeed.
+
+ Note that the absoluteURI production is defined in [RFC2396].
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 54]
+
+RFC 2518 WEBDAV February 1999
+
+
+9.4.1 No-tag-list Production
+
+ The No-tag-list production describes a series of state tokens and
+ ETags. If multiple No-tag-list productions are used then one only
+ needs to match the state of the resource for the method to be allowed
+ to continue.
+
+ If a method, due to the presence of a Depth or Destination header, is
+ applied to multiple resources then the No-tag-list production MUST be
+ applied to each resource the method is applied to.
+
+9.4.1.1 Example - No-tag-list If Header
+
+ If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another
+ ETag"])
+
+ The previous header would require that any resources within the scope
+ of the method must either be locked with the specified lock token and
+ in the state identified by the "I am an ETag" ETag or in the state
+ identified by the second ETag "I am another ETag". To put the matter
+ more plainly one can think of the previous If header as being in the
+ form (or (and <locktoken:a-write-lock-token> ["I am an ETag"]) (and
+ ["I am another ETag"])).
+
+9.4.2 Tagged-list Production
+
+ The tagged-list production scopes a list production. That is, it
+ specifies that the lists following the resource specification only
+ apply to the specified resource. The scope of the resource
+ production begins with the list production immediately following the
+ resource production and ends with the next resource production, if
+ any.
+
+ When the If header is applied to a particular resource, the Tagged-
+ list productions MUST be searched to determine if any of the listed
+ resources match the operand resource(s) for the current method. If
+ none of the resource productions match the current resource then the
+ header MUST be ignored. If one of the resource productions does
+ match the name of the resource under consideration then the list
+ productions following the resource production MUST be applied to the
+ resource in the manner specified in the previous section.
+
+ The same URI MUST NOT appear more than once in a resource production
+ in an If header.
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 55]
+
+RFC 2518 WEBDAV February 1999
+
+
+9.4.2.1 Example - Tagged List If header
+
+ COPY /resource1 HTTP/1.1
+ Host: www.foo.bar
+ Destination: http://www.foo.bar/resource2
+ If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token>
+ [W/"A weak ETag"]) (["strong ETag"])
+ <http://www.bar.bar/random>(["another strong ETag"])
+
+ In this example http://www.foo.bar/resource1 is being copied to
+ http://www.foo.bar/resource2. When the method is first applied to
+ http://www.foo.bar/resource1, resource1 must be in the state
+ specified by "(<locktoken:a-write-lock-token> [W/"A weak ETag"])
+ (["strong ETag"])", that is, it either must be locked with a lock
+ token of "locktoken:a-write-lock-token" and have a weak entity tag
+ W/"A weak ETag" or it must have a strong entity tag "strong ETag".
+
+ That is the only success condition since the resource
+ http://www.bar.bar/random never has the method applied to it (the
+ only other resource listed in the If header) and
+ http://www.foo.bar/resource2 is not listed in the If header.
+
+9.4.3 not Production
+
+ Every state token or ETag is either current, and hence describes the
+ state of a resource, or is not current, and does not describe the
+ state of a resource. The boolean operation of matching a state token
+ or ETag to the current state of a resource thus resolves to a true or
+ false value. The not production is used to reverse that value. The
+ scope of the not production is the state-token or entity-tag
+ immediately following it.
+
+ If: (Not <locktoken:write1> <locktoken:write2>)
+
+ When submitted with a request, this If header requires that all
+ operand resources must not be locked with locktoken:write1 and must
+ be locked with locktoken:write2.
+
+9.4.4 Matching Function
+
+ When performing If header processing, the definition of a matching
+ state token or entity tag is as follows.
+
+ Matching entity tag: Where the entity tag matches an entity tag
+ associated with that resource.
+
+ Matching state token: Where there is an exact match between the state
+ token in the If header and any state token on the resource.
+
+
+
+Goland, et al. Standards Track [Page 56]
+
+RFC 2518 WEBDAV February 1999
+
+
+9.4.5 If Header and Non-DAV Compliant Proxies
+
+ Non-DAV compliant proxies will not honor the If header, since they
+ will not understand the If header, and HTTP requires non-understood
+ headers to be ignored. When communicating with HTTP/1.1 proxies, the
+ "Cache-Control: no-cache" request header MUST be used so as to
+ prevent the proxy from improperly trying to service the request from
+ its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
+ request header MUST be used for the same reason.
+
+9.5 Lock-Token Header
+
+ Lock-Token = "Lock-Token" ":" Coded-URL
+
+ The Lock-Token request header is used with the UNLOCK method to
+ identify the lock to be removed. The lock token in the Lock-Token
+ request header MUST identify a lock that contains the resource
+ identified by Request-URI as a member.
+
+ The Lock-Token response header is used with the LOCK method to
+ indicate the lock token created as a result of a successful LOCK
+ request to create a new lock.
+
+9.6 Overwrite Header
+
+ Overwrite = "Overwrite" ":" ("T" | "F")
+
+ The Overwrite header specifies whether the server should overwrite
+ the state of a non-null destination resource during a COPY or MOVE.
+ A value of "F" states that the server must not perform the COPY or
+ MOVE operation if the state of the destination resource is non-null.
+ If the overwrite header is not included in a COPY or MOVE request
+ then the resource MUST treat the request as if it has an overwrite
+ header of value "T". While the Overwrite header appears to duplicate
+ the functionality of the If-Match: * header of HTTP/1.1, If-Match
+ applies only to the Request-URI, and not to the Destination of a COPY
+ or MOVE.
+
+ If a COPY or MOVE is not performed due to the value of the Overwrite
+ header, the method MUST fail with a 412 (Precondition Failed) status
+ code.
+
+ All DAV compliant resources MUST support the Overwrite header.
+
+9.7 Status-URI Response Header
+
+ The Status-URI response header may be used with the 102 (Processing)
+ status code to inform the client as to the status of a method.
+
+
+
+Goland, et al. Standards Track [Page 57]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code
+ is defined in 6.1.1 of [RFC2068]
+
+ The URIs listed in the header are source resources which have been
+ affected by the outstanding method. The status code indicates the
+ resolution of the method on the identified resource. So, for
+ example, if a MOVE method on a collection is outstanding and a 102
+ (Processing) response with a Status-URI response header is returned,
+ the included URIs will indicate resources that have had move
+ attempted on them and what the result was.
+
+9.8 Timeout Request Header
+
+ TimeOut = "Timeout" ":" 1#TimeType
+ TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other)
+ DAVTimeOutVal = 1*digit
+ Other = "Extend" field-value ; See section 4.2 of [RFC2068]
+
+ Clients may include Timeout headers in their LOCK requests. However,
+ the server is not required to honor or even consider these requests.
+ Clients MUST NOT submit a Timeout request header with any method
+ other than a LOCK method.
+
+ A Timeout request header MUST contain at least one TimeType and may
+ contain multiple TimeType entries. The purpose of listing multiple
+ TimeType entries is to indicate multiple different values and value
+ types that are acceptable to the client. The client lists the
+ TimeType entries in order of preference.
+
+ Timeout response values MUST use a Second value, Infinite, or a
+ TimeType the client has indicated familiarity with. The server may
+ assume a client is familiar with any TimeType submitted in a Timeout
+ header.
+
+ The "Second" TimeType specifies the number of seconds that will
+ elapse between granting of the lock at the server, and the automatic
+ removal of the lock. The timeout value for TimeType "Second" MUST
+ NOT be greater than 2^32-1.
+
+ The timeout counter SHOULD be restarted any time an owner of the lock
+ sends a method to any member of the lock, including unsupported
+ methods, or methods which are unsuccessful. However the lock MUST be
+ refreshed if a refresh LOCK method is successfully received.
+
+ If the timeout expires then the lock may be lost. Specifically, if
+ the server wishes to harvest the lock upon time-out, the server
+ SHOULD act as if an UNLOCK method was executed by the server on the
+ resource using the lock token of the timed-out lock, performed with
+
+
+
+Goland, et al. Standards Track [Page 58]
+
+RFC 2518 WEBDAV February 1999
+
+
+ its override authority. Thus logs should be updated with the
+ disposition of the lock, notifications should be sent, etc., just as
+ they would be for an UNLOCK request.
+
+ Servers are advised to pay close attention to the values submitted by
+ clients, as they will be indicative of the type of activity the
+ client intends to perform. For example, an applet running in a
+ browser may need to lock a resource, but because of the instability
+ of the environment within which the applet is running, the applet may
+ be turned off without warning. As a result, the applet is likely to
+ ask for a relatively small timeout value so that if the applet dies,
+ the lock can be quickly harvested. However, a document management
+ system is likely to ask for an extremely long timeout because its
+ user may be planning on going off-line.
+
+ A client MUST NOT assume that just because the time-out has expired
+ the lock has been lost.
+
+10 Status Code Extensions to HTTP/1.1
+
+ The following status codes are added to those defined in HTTP/1.1
+ [RFC2068].
+
+10.1 102 Processing
+
+ The 102 (Processing) status code is an interim response used to
+ inform the client that the server has accepted the complete request,
+ but has not yet completed it. This status code SHOULD only be sent
+ when the server has a reasonable expectation that the request will
+ take significant time to complete. As guidance, if a method is taking
+ longer than 20 seconds (a reasonable, but arbitrary value) to process
+ the server SHOULD return a 102 (Processing) response. The server MUST
+ send a final response after the request has been completed.
+
+ Methods can potentially take a long period of time to process,
+ especially methods that support the Depth header. In such cases the
+ client may time-out the connection while waiting for a response. To
+ prevent this the server may return a 102 (Processing) status code to
+ indicate to the client that the server is still processing the
+ method.
+
+10.2 207 Multi-Status
+
+ The 207 (Multi-Status) status code provides status for multiple
+ independent operations (see section 11 for more information).
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 59]
+
+RFC 2518 WEBDAV February 1999
+
+
+10.3 422 Unprocessable Entity
+
+ The 422 (Unprocessable Entity) status code means the server
+ understands the content type of the request entity (hence a
+ 415(Unsupported Media Type) status code is inappropriate), and the
+ syntax of the request entity is correct (thus a 400 (Bad Request)
+ status code is inappropriate) but was unable to process the contained
+ instructions. For example, this error condition may occur if an XML
+ request body contains well-formed (i.e., syntactically correct), but
+ semantically erroneous XML instructions.
+
+10.4 423 Locked
+
+ The 423 (Locked) status code means the source or destination resource
+ of a method is locked.
+
+10.5 424 Failed Dependency
+
+ The 424 (Failed Dependency) status code means that the method could
+ not be performed on the resource because the requested action
+ depended on another action and that action failed. For example, if a
+ command in a PROPPATCH method fails then, at minimum, the rest of the
+ commands will also fail with 424 (Failed Dependency).
+
+10.6 507 Insufficient Storage
+
+ The 507 (Insufficient Storage) status code means the method could not
+ be performed on the resource because the server is unable to store
+ the representation needed to successfully complete the request. This
+ condition is considered to be temporary. If the request which
+ received this status code was the result of a user action, the
+ request MUST NOT be repeated until it is requested by a separate user
+ action.
+
+11 Multi-Status Response
+
+ The default 207 (Multi-Status) response body is a text/xml or
+ application/xml HTTP entity that contains a single XML element called
+ multistatus, which contains a set of XML elements called response
+ which contain 200, 300, 400, and 500 series status codes generated
+ during the method invocation. 100 series status codes SHOULD NOT be
+ recorded in a response XML element.
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 60]
+
+RFC 2518 WEBDAV February 1999
+
+
+12 XML Element Definitions
+
+ In the section below, the final line of each section gives the
+ element type declaration using the format defined in [REC-XML]. The
+ "Value" field, where present, specifies further restrictions on the
+ allowable contents of the XML element using BNF (i.e., to further
+ restrict the values of a PCDATA element).
+
+12.1 activelock XML Element
+
+ Name: activelock
+ Namespace: DAV:
+ Purpose: Describes a lock on a resource.
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?) >
+
+12.1.1 depth XML Element
+
+ Name: depth
+ Namespace: DAV:
+ Purpose: The value of the Depth header.
+ Value: "0" | "1" | "infinity"
+
+ <!ELEMENT depth (#PCDATA) >
+
+12.1.2 locktoken XML Element
+
+ Name: locktoken
+ Namespace: DAV:
+ Purpose: The lock token associated with a lock.
+ Description: The href contains one or more opaque lock token URIs
+ which all refer to the same lock (i.e., the OpaqueLockToken-URI
+ production in section 6.4).
+
+ <!ELEMENT locktoken (href+) >
+
+12.1.3 timeout XML Element
+
+ Name: timeout
+ Namespace: DAV:
+ Purpose: The timeout associated with a lock
+ Value: TimeType ;Defined in section 9.8
+
+ <!ELEMENT timeout (#PCDATA) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 61]
+
+RFC 2518 WEBDAV February 1999
+
+
+12.2 collection XML Element
+
+ Name: collection
+ Namespace: DAV:
+ Purpose: Identifies the associated resource as a collection. The
+ resourcetype property of a collection resource MUST have this value.
+
+ <!ELEMENT collection EMPTY >
+
+12.3 href XML Element
+
+ Name: href
+ Namespace: DAV:
+ Purpose: Identifies the content of the element as a URI.
+ Value: URI ; See section 3.2.1 of [RFC2068]
+
+ <!ELEMENT href (#PCDATA)>
+
+12.4 link XML Element
+
+ Name: link
+ Namespace: DAV:
+ Purpose: Identifies the property as a link and contains the source
+ and destination of that link.
+ Description: The link XML element is used to provide the sources and
+ destinations of a link. The name of the property containing the link
+ XML element provides the type of the link. Link is a multi-valued
+ element, so multiple links may be used together to indicate multiple
+ links with the same type. The values in the href XML elements inside
+ the src and dst XML elements of the link XML element MUST NOT be
+ rejected if they point to resources which do not exist.
+
+ <!ELEMENT link (src+, dst+) >
+
+12.4.1 dst XML Element
+
+ Name: dst
+ Namespace: DAV:
+ Purpose: Indicates the destination of a link
+ Value: URI
+
+ <!ELEMENT dst (#PCDATA) >
+
+12.4.2 src XML Element
+
+ Name: src
+ Namespace: DAV:
+ Purpose: Indicates the source of a link.
+
+
+
+Goland, et al. Standards Track [Page 62]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Value: URI
+
+ <!ELEMENT src (#PCDATA) >
+
+12.5 lockentry XML Element
+
+ Name: lockentry
+ Namespace: DAV:
+ Purpose: Defines the types of locks that can be used with the
+ resource.
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+
+12.6 lockinfo XML Element
+
+ Name: lockinfo
+ Namespace: DAV:
+ Purpose: The lockinfo XML element is used with a LOCK method to
+ specify the type of lock the client wishes to have created.
+
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+12.7 lockscope XML Element
+
+ Name: lockscope
+ Namespace: DAV:
+ Purpose: Specifies whether a lock is an exclusive lock, or a
+ shared lock.
+
+ <!ELEMENT lockscope (exclusive | shared) >
+
+12.7.1 exclusive XML Element
+
+ Name: exclusive
+ Namespace: DAV:
+ Purpose: Specifies an exclusive lock
+
+ <!ELEMENT exclusive EMPTY >
+
+12.7.2 shared XML Element
+
+ Name: shared
+ Namespace: DAV:
+ Purpose: Specifies a shared lock
+
+ <!ELEMENT shared EMPTY >
+
+
+
+
+
+Goland, et al. Standards Track [Page 63]
+
+RFC 2518 WEBDAV February 1999
+
+
+12.8 locktype XML Element
+
+ Name: locktype
+ Namespace: DAV:
+ Purpose: Specifies the access type of a lock. At present, this
+ specification only defines one lock type, the write lock.
+
+ <!ELEMENT locktype (write) >
+
+12.8.1 write XML Element
+
+ Name: write
+ Namespace: DAV:
+ Purpose: Specifies a write lock.
+
+ <!ELEMENT write EMPTY >
+
+12.9 multistatus XML Element
+
+ Name: multistatus
+ Namespace: DAV:
+ Purpose: Contains multiple response messages.
+ Description: The responsedescription at the top level is used to
+ provide a general message describing the overarching nature of the
+ response. If this value is available an application may use it
+ instead of presenting the individual response descriptions contained
+ within the responses.
+
+ <!ELEMENT multistatus (response+, responsedescription?) >
+
+12.9.1 response XML Element
+
+ Name: response
+ Namespace: DAV:
+ Purpose: Holds a single response describing the effect of a
+ method on resource and/or its properties.
+ Description: A particular href MUST NOT appear more than once as the
+ child of a response XML element under a multistatus XML element.
+ This requirement is necessary in order to keep processing costs for a
+ response to linear time. Essentially, this prevents having to search
+ in order to group together all the responses by href. There are,
+ however, no requirements regarding ordering based on href values.
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+ responsedescription?) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 64]
+
+RFC 2518 WEBDAV February 1999
+
+
+12.9.1.1 propstat XML Element
+
+ Name: propstat
+ Namespace: DAV:
+ Purpose: Groups together a prop and status element that is
+ associated with a particular href element.
+ Description: The propstat XML element MUST contain one prop XML
+ element and one status XML element. The contents of the prop XML
+ element MUST only list the names of properties to which the result in
+ the status element applies.
+
+ <!ELEMENT propstat (prop, status, responsedescription?) >
+
+12.9.1.2 status XML Element
+
+ Name: status
+ Namespace: DAV:
+ Purpose: Holds a single HTTP status-line
+ Value: status-line ;status-line defined in [RFC2068]
+
+ <!ELEMENT status (#PCDATA) >
+
+12.9.2 responsedescription XML Element
+
+ Name: responsedescription
+ Namespace: DAV:
+ Purpose: Contains a message that can be displayed to the user
+ explaining the nature of the response.
+ Description: This XML element provides information suitable to be
+ presented to a user.
+
+ <!ELEMENT responsedescription (#PCDATA) >
+
+12.10 owner XML Element
+
+ Name: owner
+ Namespace: DAV:
+ Purpose: Provides information about the principal taking out a
+ lock.
+ Description: The owner XML element provides information sufficient
+ for either directly contacting a principal (such as a telephone
+ number or Email URI), or for discovering the principal (such as the
+ URL of a homepage) who owns a lock.
+
+ <!ELEMENT owner ANY>
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 65]
+
+RFC 2518 WEBDAV February 1999
+
+
+12.11 prop XML element
+
+ Name: prop
+ Namespace: DAV:
+ Purpose: Contains properties related to a resource.
+ Description: The prop XML element is a generic container for
+ properties defined on resources. All elements inside a prop XML
+ element MUST define properties related to the resource. No other
+ elements may be used inside of a prop element.
+
+ <!ELEMENT prop ANY>
+
+12.12 propertybehavior XML element
+
+ Name: propertybehavior Namespace: DAV: Purpose: Specifies
+ how properties are handled during a COPY or MOVE.
+ Description: The propertybehavior XML element specifies how
+ properties are handled during a COPY or MOVE. If this XML element is
+ not included in the request body then the server is expected to act
+ as defined by the default property handling behavior of the
+ associated method. All WebDAV compliant resources MUST support the
+ propertybehavior XML element.
+
+ <!ELEMENT propertybehavior (omit | keepalive) >
+
+12.12.1 keepalive XML element
+
+ Name: keepalive
+ Namespace: DAV:
+ Purpose: Specifies requirements for the copying/moving of live
+ properties.
+ Description: If a list of URIs is included as the value of keepalive
+ then the named properties MUST be "live" after they are copied
+ (moved) to the destination resource of a COPY (or MOVE). If the
+ value "*" is given for the keepalive XML element, this designates
+ that all live properties on the source resource MUST be live on the
+ destination. If the requirements specified by the keepalive element
+ can not be honored then the method MUST fail with a 412 (Precondition
+ Failed). All DAV compliant resources MUST support the keepalive XML
+ element for use with the COPY and MOVE methods.
+ Value: "*" ; #PCDATA value can only be "*"
+
+ <!ELEMENT keepalive (#PCDATA | href+) >
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 66]
+
+RFC 2518 WEBDAV February 1999
+
+
+12.12.2 omit XML element
+
+ Name: omit
+ Namespace: DAV:
+ Purpose: The omit XML element instructs the server that it should
+ use best effort to copy properties but a failure to copy a property
+ MUST NOT cause the method to fail. Description: The default behavior
+ for a COPY or MOVE is to copy/move all properties or fail the method.
+ In certain circumstances, such as when a server copies a resource
+ over another protocol such as FTP, it may not be possible to
+ copy/move the properties associated with the resource. Thus any
+ attempt to copy/move over FTP would always have to fail because
+ properties could not be moved over, even as dead properties. All DAV
+ compliant resources MUST support the omit XML element on COPY/MOVE
+ methods.
+
+ <!ELEMENT omit EMPTY >
+
+12.13 propertyupdate XML element
+
+ Name: propertyupdate
+ Namespace: DAV:
+ Purpose: Contains a request to alter the properties on a
+ resource.
+ Description: This XML element is a container for the information
+ required to modify the properties on the resource. This XML element
+ is multi-valued.
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+
+12.13.1 remove XML element
+
+ Name: remove
+ Namespace: DAV:
+ Purpose: Lists the DAV properties to be removed from a resource.
+ Description: Remove instructs that the properties specified in prop
+ should be removed. Specifying the removal of a property that does
+ not exist is not an error. All the XML elements in a prop XML
+ element inside of a remove XML element MUST be empty, as only the
+ names of properties to be removed are required.
+
+ <!ELEMENT remove (prop) >
+
+12.13.2 set XML element
+
+ Name: set
+ Namespace: DAV:
+ Purpose: Lists the DAV property values to be set for a resource.
+
+
+
+Goland, et al. Standards Track [Page 67]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Description: The set XML element MUST contain only a prop XML
+ element. The elements contained by the prop XML element inside the
+ set XML element MUST specify the name and value of properties that
+ are set on the resource identified by Request-URI. If a property
+ already exists then its value is replaced. Language tagging
+ information in the property's value (in the "xml:lang" attribute, if
+ present) MUST be persistently stored along with the property, and
+ MUST be subsequently retrievable using PROPFIND.
+
+ <!ELEMENT set (prop) >
+
+12.14 propfind XML Element
+
+ Name: propfind
+ Namespace: DAV:
+ Purpose: Specifies the properties to be returned from a PROPFIND
+ method. Two special elements are specified for use with propfind,
+ allprop and propname. If prop is used inside propfind it MUST only
+ contain property names, not values.
+
+ <!ELEMENT propfind (allprop | propname | prop) >
+
+12.14.1 allprop XML Element
+
+ Name: allprop Namespace: DAV: Purpose: The allprop XML
+ element specifies that all property names and values on the resource
+ are to be returned.
+
+ <!ELEMENT allprop EMPTY >
+
+12.14.2 propname XML Element
+
+ Name: propname Namespace: DAV: Purpose: The propname XML
+ element specifies that only a list of property names on the resource
+ is to be returned.
+
+ <!ELEMENT propname EMPTY >
+
+13 DAV Properties
+
+ For DAV properties, the name of the property is also the same as the
+ name of the XML element that contains its value. In the section
+ below, the final line of each section gives the element type
+ declaration using the format defined in [REC-XML]. The "Value" field,
+ where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element).
+
+
+
+
+Goland, et al. Standards Track [Page 68]
+
+RFC 2518 WEBDAV February 1999
+
+
+13.1 creationdate Property
+
+ Name: creationdate
+ Namespace: DAV:
+ Purpose: Records the time and date the resource was created.
+ Value: date-time ; See Appendix 2
+ Description: The creationdate property should be defined on all DAV
+ compliant resources. If present, it contains a timestamp of the
+ moment when the resource was created (i.e., the moment it had non-
+ null state).
+
+ <!ELEMENT creationdate (#PCDATA) >
+
+13.2 displayname Property
+
+ Name: displayname
+ Namespace: DAV:
+ Purpose: Provides a name for the resource that is suitable for
+ presentation to a user.
+ Description: The displayname property should be defined on all DAV
+ compliant resources. If present, the property contains a description
+ of the resource that is suitable for presentation to a user.
+
+ <!ELEMENT displayname (#PCDATA) >
+
+13.3 getcontentlanguage Property
+
+ Name: getcontentlanguage
+ Namespace: DAV:
+ Purpose: Contains the Content-Language header returned by a GET
+ without accept headers
+ Description: The getcontentlanguage property MUST be defined on any
+ DAV compliant resource that returns the Content-Language header on a
+ GET.
+ Value: language-tag ;language-tag is defined in section 14.13
+ of [RFC2068]
+
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+
+13.4 getcontentlength Property
+
+ Name: getcontentlength
+ Namespace: DAV:
+ Purpose: Contains the Content-Length header returned by a GET
+ without accept headers.
+ Description: The getcontentlength property MUST be defined on any
+ DAV compliant resource that returns the Content-Length header in
+ response to a GET.
+
+
+
+Goland, et al. Standards Track [Page 69]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Value: content-length ; see section 14.14 of [RFC2068]
+
+ <!ELEMENT getcontentlength (#PCDATA) >
+
+13.5 getcontenttype Property
+
+ Name: getcontenttype
+ Namespace: DAV:
+ Purpose: Contains the Content-Type header returned by a GET
+ without accept headers.
+ Description: This getcontenttype property MUST be defined on any DAV
+ compliant resource that returns the Content-Type header in response
+ to a GET.
+ Value: media-type ; defined in section 3.7 of [RFC2068]
+
+ <!ELEMENT getcontenttype (#PCDATA) >
+
+13.6 getetag Property
+
+ Name: getetag
+ Namespace: DAV:
+ Purpose: Contains the ETag header returned by a GET without
+ accept headers.
+ Description: The getetag property MUST be defined on any DAV
+ compliant resource that returns the Etag header.
+ Value: entity-tag ; defined in section 3.11 of [RFC2068]
+
+ <!ELEMENT getetag (#PCDATA) >
+
+13.7 getlastmodified Property
+
+ Name: getlastmodified
+ Namespace: DAV:
+ Purpose: Contains the Last-Modified header returned by a GET
+ method without accept headers.
+ Description: Note that the last-modified date on a resource may
+ reflect changes in any part of the state of the resource, not
+ necessarily just a change to the response to the GET method. For
+ example, a change in a property may cause the last-modified date to
+ change. The getlastmodified property MUST be defined on any DAV
+ compliant resource that returns the Last-Modified header in response
+ to a GET.
+ Value: HTTP-date ; defined in section 3.3.1 of [RFC2068]
+
+ <!ELEMENT getlastmodified (#PCDATA) >
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 70]
+
+RFC 2518 WEBDAV February 1999
+
+
+13.8 lockdiscovery Property
+
+ Name: lockdiscovery
+ Namespace: DAV:
+ Purpose: Describes the active locks on a resource
+ Description: The lockdiscovery property returns a listing of who has
+ a lock, what type of lock he has, the timeout type and the time
+ remaining on the timeout, and the associated lock token. The server
+ is free to withhold any or all of this information if the requesting
+ principal does not have sufficient access rights to see the requested
+ data.
+
+ <!ELEMENT lockdiscovery (activelock)* >
+
+13.8.1 Example - Retrieving the lockdiscovery Property
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.foo.bar
+ Content-Length: xxxx
+ Content-Type: text/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D='DAV:'>
+ <D:prop><D:lockdiscovery/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D='DAV:'>
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>0</D:depth>
+ <D:owner>Jane Smith</D:owner>
+ <D:timeout>Infinite</D:timeout>
+ <D:locktoken>
+
+
+
+Goland, et al. Standards Track [Page 71]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:href>
+ opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76
+ </D:href>
+ </D:locktoken>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ This resource has a single exclusive write lock on it, with an
+ infinite timeout.
+
+13.9 resourcetype Property
+
+ Name: resourcetype
+ Namespace: DAV:
+ Purpose: Specifies the nature of the resource.
+ Description: The resourcetype property MUST be defined on all DAV
+ compliant resources. The default value is empty.
+
+ <!ELEMENT resourcetype ANY >
+
+13.10 source Property
+
+ Name: source
+ Namespace: DAV:
+ Purpose: The destination of the source link identifies the
+ resource that contains the unprocessed source of the link's source.
+ Description: The source of the link (src) is typically the URI of the
+ output resource on which the link is defined, and there is typically
+ only one destination (dst) of the link, which is the URI where the
+ unprocessed source of the resource may be accessed. When more than
+ one link destination exists, this specification asserts no policy on
+ ordering.
+
+ <!ELEMENT source (link)* >
+
+13.10.1 Example - A source Property
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:" xmlns:F="http://www.foocorp.com/Project/">
+ <D:source>
+ <D:link>
+ <F:projfiles>Source</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+
+
+
+Goland, et al. Standards Track [Page 72]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:dst>http://foo.bar/src/main.c</D:dst>
+ </D:link>
+ <D:link>
+ <F:projfiles>Library</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+ <D:dst>http://foo.bar/src/main.lib</D:dst>
+ </D:link>
+ <D:link>
+ <F:projfiles>Makefile</F:projfiles>
+ <D:src>http://foo.bar/program</D:src>
+ <D:dst>http://foo.bar/src/makefile</D:dst>
+ </D:link>
+ </D:source>
+ </D:prop>
+
+ In this example the resource http://foo.bar/program has a source
+ property that contains three links. Each link contains three
+ elements, two of which, src and dst, are part of the DAV schema
+ defined in this document, and one which is defined by the schema
+ http://www.foocorp.com/project/ (Source, Library, and Makefile). A
+ client which only implements the elements in the DAV spec will not
+ understand the foocorp elements and will ignore them, thus seeing the
+ expected source and destination links. An enhanced client may know
+ about the foocorp elements and be able to present the user with
+ additional information about the links. This example demonstrates
+ the power of XML markup, allowing element values to be enhanced
+ without breaking older clients.
+
+13.11 supportedlock Property
+
+ Name: supportedlock
+ Namespace: DAV:
+ Purpose: To provide a listing of the lock capabilities supported
+ by the resource.
+ Description: The supportedlock property of a resource returns a
+ listing of the combinations of scope and access types which may be
+ specified in a lock request on the resource. Note that the actual
+ contents are themselves controlled by access controls so a server is
+ not required to provide information the client is not authorized to
+ see.
+
+ <!ELEMENT supportedlock (lockentry)* >
+
+13.11.1 Example - Retrieving the supportedlock Property
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+
+
+
+Goland, et al. Standards Track [Page 73]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Host: www.foo.bar
+ Content-Length: xxxx
+ Content-Type: text/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop><D:supportedlock/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.foo.bar/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+14 Instructions for Processing XML in DAV
+
+ All DAV compliant resources MUST ignore any unknown XML element and
+ all its children encountered while processing a DAV method that uses
+ XML as its command language.
+
+ This restriction also applies to the processing, by clients, of DAV
+ property values where unknown XML elements SHOULD be ignored unless
+ the property's schema declares otherwise.
+
+
+
+
+
+Goland, et al. Standards Track [Page 74]
+
+RFC 2518 WEBDAV February 1999
+
+
+ This restriction does not apply to setting dead DAV properties on the
+ server where the server MUST record unknown XML elements.
+
+ Additionally, this restriction does not apply to the use of XML where
+ XML happens to be the content type of the entity body, for example,
+ when used as the body of a PUT.
+
+ Since XML can be transported as text/xml or application/xml, a DAV
+ server MUST accept DAV method requests with XML parameters
+ transported as either text/xml or application/xml, and DAV client
+ MUST accept XML responses using either text/xml or application/xml.
+
+15 DAV Compliance Classes
+
+ A DAV compliant resource can choose from two classes of compliance.
+ A client can discover the compliance classes of a resource by
+ executing OPTIONS on the resource, and examining the "DAV" header
+ which is returned.
+
+ Since this document describes extensions to the HTTP/1.1 protocol,
+ minimally all DAV compliant resources, clients, and proxies MUST be
+ compliant with [RFC2068].
+
+ Compliance classes are not necessarily sequential. A resource that is
+ class 2 compliant must also be class 1 compliant; but if additional
+ compliance classes are defined later, a resource that is class 1, 2,
+ and 4 compliant might not be class 3 compliant. Also note that
+ identifiers other than numbers may be used as compliance class
+ identifiers.
+
+15.1 Class 1
+
+ A class 1 compliant resource MUST meet all "MUST" requirements in all
+ sections of this document.
+
+ Class 1 compliant resources MUST return, at minimum, the value "1" in
+ the DAV header on all responses to the OPTIONS method.
+
+15.2 Class 2
+
+ A class 2 compliant resource MUST meet all class 1 requirements and
+ support the LOCK method, the supportedlock property, the
+ lockdiscovery property, the Time-Out response header and the Lock-
+ Token request header. A class "2" compliant resource SHOULD also
+ support the Time-Out request header and the owner XML element.
+
+ Class 2 compliant resources MUST return, at minimum, the values "1"
+ and "2" in the DAV header on all responses to the OPTIONS method.
+
+
+
+Goland, et al. Standards Track [Page 75]
+
+RFC 2518 WEBDAV February 1999
+
+
+16 Internationalization Considerations
+
+ In the realm of internationalization, this specification complies
+ with the IETF Character Set Policy [RFC2277]. In this specification,
+ human-readable fields can be found either in the value of a property,
+ or in an error message returned in a response entity body. In both
+ cases, the human-readable content is encoded using XML, which has
+ explicit provisions for character set tagging and encoding, and
+ requires that XML processors read XML elements encoded, at minimum,
+ using the UTF-8 [UTF-8] encoding of the ISO 10646 multilingual plane.
+ XML examples in this specification demonstrate use of the charset
+ parameter of the Content-Type header, as defined in [RFC2376], as
+ well as the XML "encoding" attribute, which together provide charset
+ identification information for MIME and XML processors.
+
+ XML also provides a language tagging capability for specifying the
+ language of the contents of a particular XML element. XML uses
+ either IANA registered language tags (see [RFC1766]) or ISO 639
+ language tags [ISO-639] in the "xml:lang" attribute of an XML element
+ to identify the language of its content and attributes.
+
+ WebDAV applications MUST support the character set tagging, character
+ set encoding, and the language tagging functionality of the XML
+ specification. Implementors of WebDAV applications are strongly
+ encouraged to read "XML Media Types" [RFC2376] for instruction on
+ which MIME media type to use for XML transport, and on use of the
+ charset parameter of the Content-Type header.
+
+ Names used within this specification fall into three categories:
+ names of protocol elements such as methods and headers, names of XML
+ elements, and names of properties. Naming of protocol elements
+ follows the precedent of HTTP, using English names encoded in USASCII
+ for methods and headers. Since these protocol elements are not
+ visible to users, and are in fact simply long token identifiers, they
+ do not need to support encoding in multiple character sets.
+ Similarly, though the names of XML elements used in this
+ specification are English names encoded in UTF-8, these names are not
+ visible to the user, and hence do not need to support multiple
+ character set encodings.
+
+ The name of a property defined on a resource is a URI. Although some
+ applications (e.g., a generic property viewer) will display property
+ URIs directly to their users, it is expected that the typical
+ application will use a fixed set of properties, and will provide a
+ mapping from the property name URI to a human-readable field when
+ displaying the property name to a user. It is only in the case where
+
+
+
+
+
+Goland, et al. Standards Track [Page 76]
+
+RFC 2518 WEBDAV February 1999
+
+
+ the set of properties is not known ahead of time that an application
+ need display a property name URI to a user. We recommend that
+ applications provide human-readable property names wherever feasible.
+
+ For error reporting, we follow the convention of HTTP/1.1 status
+ codes, including with each status code a short, English description
+ of the code (e.g., 423 (Locked)). While the possibility exists that
+ a poorly crafted user agent would display this message to a user,
+ internationalized applications will ignore this message, and display
+ an appropriate message in the user's language and character set.
+
+ Since interoperation of clients and servers does not require locale
+ information, this specification does not specify any mechanism for
+ transmission of this information.
+
+17 Security Considerations
+
+ This section is provided to detail issues concerning security
+ implications of which WebDAV applications need to be aware.
+
+ All of the security considerations of HTTP/1.1 (discussed in
+ [RFC2068]) and XML (discussed in [RFC2376]) also apply to WebDAV. In
+ addition, the security risks inherent in remote authoring require
+ stronger authentication technology, introduce several new privacy
+ concerns, and may increase the hazards from poor server design.
+ These issues are detailed below.
+
+17.1 Authentication of Clients
+
+ Due to their emphasis on authoring, WebDAV servers need to use
+ authentication technology to protect not just access to a network
+ resource, but the integrity of the resource as well. Furthermore,
+ the introduction of locking functionality requires support for
+ authentication.
+
+ A password sent in the clear over an insecure channel is an
+ inadequate means for protecting the accessibility and integrity of a
+ resource as the password may be intercepted. Since Basic
+ authentication for HTTP/1.1 performs essentially clear text
+ transmission of a password, Basic authentication MUST NOT be used to
+ authenticate a WebDAV client to a server unless the connection is
+ secure. Furthermore, a WebDAV server MUST NOT send Basic
+ authentication credentials in a WWW-Authenticate header unless the
+ connection is secure. Examples of secure connections include a
+ Transport Layer Security (TLS) connection employing a strong cipher
+ suite with mutual authentication of client and server, or a
+ connection over a network which is physically secure, for example, an
+ isolated network in a building with restricted access.
+
+
+
+Goland, et al. Standards Track [Page 77]
+
+RFC 2518 WEBDAV February 1999
+
+
+ WebDAV applications MUST support the Digest authentication scheme
+ [RFC2069]. Since Digest authentication verifies that both parties to
+ a communication know a shared secret, a password, without having to
+ send that secret in the clear, Digest authentication avoids the
+ security problems inherent in Basic authentication while providing a
+ level of authentication which is useful in a wide range of scenarios.
+
+17.2 Denial of Service
+
+ Denial of service attacks are of special concern to WebDAV servers.
+ WebDAV plus HTTP enables denial of service attacks on every part of a
+ system's resources.
+
+ The underlying storage can be attacked by PUTting extremely large
+ files.
+
+ Asking for recursive operations on large collections can attack
+ processing time.
+
+ Making multiple pipelined requests on multiple connections can attack
+ network connections.
+
+ WebDAV servers need to be aware of the possibility of a denial of
+ service attack at all levels.
+
+17.3 Security through Obscurity
+
+ WebDAV provides, through the PROPFIND method, a mechanism for listing
+ the member resources of a collection. This greatly diminishes the
+ effectiveness of security or privacy techniques that rely only on the
+ difficulty of discovering the names of network resources. Users of
+ WebDAV servers are encouraged to use access control techniques to
+ prevent unwanted access to resources, rather than depending on the
+ relative obscurity of their resource names.
+
+17.4 Privacy Issues Connected to Locks
+
+ When submitting a lock request a user agent may also submit an owner
+ XML field giving contact information for the person taking out the
+ lock (for those cases where a person, rather than a robot, is taking
+ out the lock). This contact information is stored in a lockdiscovery
+ property on the resource, and can be used by other collaborators to
+ begin negotiation over access to the resource. However, in many
+ cases this contact information can be very private, and should not be
+ widely disseminated. Servers SHOULD limit read access to the
+ lockdiscovery property as appropriate. Furthermore, user agents
+
+
+
+
+
+Goland, et al. Standards Track [Page 78]
+
+RFC 2518 WEBDAV February 1999
+
+
+ SHOULD provide control over whether contact information is sent at
+ all, and if contact information is sent, control over exactly what
+ information is sent.
+
+17.5 Privacy Issues Connected to Properties
+
+ Since property values are typically used to hold information such as
+ the author of a document, there is the possibility that privacy
+ concerns could arise stemming from widespread access to a resource's
+ property data. To reduce the risk of inadvertent release of private
+ information via properties, servers are encouraged to develop access
+ control mechanisms that separate read access to the resource body and
+ read access to the resource's properties. This allows a user to
+ control the dissemination of their property data without overly
+ restricting access to the resource's contents.
+
+17.6 Reduction of Security due to Source Link
+
+ HTTP/1.1 warns against providing read access to script code because
+ it may contain sensitive information. Yet WebDAV, via its source
+ link facility, can potentially provide a URI for script resources so
+ they may be authored. For HTTP/1.1, a server could reasonably
+ prevent access to source resources due to the predominance of read-
+ only access. WebDAV, with its emphasis on authoring, encourages read
+ and write access to source resources, and provides the source link
+ facility to identify the source. This reduces the security benefits
+ of eliminating access to source resources. Users and administrators
+ of WebDAV servers should be very cautious when allowing remote
+ authoring of scripts, limiting read and write access to the source
+ resources to authorized principals.
+
+17.7 Implications of XML External Entities
+
+ XML supports a facility known as "external entities", defined in
+ section 4.2.2 of [REC-XML], which instruct an XML processor to
+ retrieve and perform an inline include of XML located at a particular
+ URI. An external XML entity can be used to append or modify the
+ document type declaration (DTD) associated with an XML document. An
+ external XML entity can also be used to include XML within the
+ content of an XML document. For non-validating XML, such as the XML
+ used in this specification, including an external XML entity is not
+ required by [REC-XML]. However, [REC-XML] does state that an XML
+ processor may, at its discretion, include the external XML entity.
+
+ External XML entities have no inherent trustworthiness and are
+ subject to all the attacks that are endemic to any HTTP GET request.
+ Furthermore, it is possible for an external XML entity to modify the
+ DTD, and hence affect the final form of an XML document, in the worst
+
+
+
+Goland, et al. Standards Track [Page 79]
+
+RFC 2518 WEBDAV February 1999
+
+
+ case significantly modifying its semantics, or exposing the XML
+ processor to the security risks discussed in [RFC2376]. Therefore,
+ implementers must be aware that external XML entities should be
+ treated as untrustworthy.
+
+ There is also the scalability risk that would accompany a widely
+ deployed application which made use of external XML entities. In
+ this situation, it is possible that there would be significant
+ numbers of requests for one external XML entity, potentially
+ overloading any server which fields requests for the resource
+ containing the external XML entity.
+
+17.8 Risks Connected with Lock Tokens
+
+ This specification, in section 6.4, requires the use of Universal
+ Unique Identifiers (UUIDs) for lock tokens, in order to guarantee
+ their uniqueness across space and time. UUIDs, as defined in [ISO-
+ 11578], contain a "node" field which "consists of the IEEE address,
+ usually the host address. For systems with multiple IEEE 802 nodes,
+ any available node address can be used." Since a WebDAV server will
+ issue many locks over its lifetime, the implication is that it will
+ also be publicly exposing its IEEE 802 address.
+
+ There are several risks associated with exposure of IEEE 802
+ addresses. Using the IEEE 802 address:
+
+ * It is possible to track the movement of hardware from subnet to
+ subnet.
+
+ * It may be possible to identify the manufacturer of the hardware
+ running a WebDAV server.
+
+ * It may be possible to determine the number of each type of computer
+ running WebDAV.
+
+ Section 6.4.1 of this specification details an alternate mechanism
+ for generating the "node" field of a UUID without using an IEEE 802
+ address, which alleviates the risks associated with exposure of IEEE
+ 802 addresses by using an alternate source of uniqueness.
+
+18 IANA Considerations
+
+ This document defines two namespaces, the namespace of property
+ names, and the namespace of WebDAV-specific XML elements used within
+ property values.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 80]
+
+RFC 2518 WEBDAV February 1999
+
+
+ URIs are used for both names, for several reasons. Assignment of a
+ URI does not require a request to a central naming authority, and
+ hence allow WebDAV property names and XML elements to be quickly
+ defined by any WebDAV user or application. URIs also provide a
+ unique address space, ensuring that the distributed users of WebDAV
+ will not have collisions among the property names and XML elements
+ they create.
+
+ This specification defines a distinguished set of property names and
+ XML elements that are understood by all WebDAV applications. The
+ property names and XML elements in this specification are all derived
+ from the base URI DAV: by adding a suffix to this URI, for example,
+ DAV:creationdate for the "creationdate" property.
+
+ This specification also defines a URI scheme for the encoding of lock
+ tokens, the opaquelocktoken URI scheme described in section 6.4.
+
+ To ensure correct interoperation based on this specification, IANA
+ must reserve the URI namespaces starting with "DAV:" and with
+ "opaquelocktoken:" for use by this specification, its revisions, and
+ related WebDAV specifications.
+
+19 Intellectual Property
+
+ The following notice is copied from RFC 2026 [RFC2026], section 10.4,
+ and describes the position of the IETF concerning intellectual
+ property claims made against this document.
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use other technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ IETF's procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such
+ proprietary rights by implementors or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+
+
+
+Goland, et al. Standards Track [Page 81]
+
+RFC 2518 WEBDAV February 1999
+
+
+20 Acknowledgements
+
+ A specification such as this thrives on piercing critical review and
+ withers from apathetic neglect. The authors gratefully acknowledge
+ the contributions of the following people, whose insights were so
+ valuable at every stage of our work.
+
+ Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
+ Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
+ Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
+ Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
+ Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
+ Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
+ Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
+ Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
+ Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
+ Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
+ Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
+ Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
+ Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
+ Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
+
+ Two from this list deserve special mention. The contributions by
+ Larry Masinter have been invaluable, both in helping the formation of
+ the working group and in patiently coaching the authors along the
+ way. In so many ways he has set high standards we have toiled to
+ meet. The contributions of Judith Slein in clarifying the
+ requirements, and in patiently reviewing draft after draft, both
+ improved this specification and expanded our minds on document
+ management.
+
+ We would also like to thank John Turner for developing the XML DTD.
+
+21 References
+
+21.1 Normative References
+
+ [RFC1766] Alvestrand, H., "Tags for the Identification of
+ Languages", RFC 1766, March 1995.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 82]
+
+RFC 2518 WEBDAV February 1999
+
+
+ [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter,
+ "Uniform Resource Identifiers (URI): Generic Syntax",
+ RFC 2396, August 1998.
+
+ [REC-XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen,
+ "Extensible Markup Language (XML)." World Wide Web
+ Consortium Recommendation REC-xml-19980210.
+ http://www.w3.org/TR/1998/REC-xml-19980210.
+
+ [REC-XML-NAMES] T. Bray, D. Hollander, A. Layman, "Namespaces in
+ XML". World Wide Web Consortium Recommendation REC-
+ xml-names-19990114. http://www.w3.org/TR/1999/REC-
+ xml-names-19990114/
+
+ [RFC2069] Franks, J., Hallam-Baker, P., Hostetler, J., Leach,
+ P, Luotonen, A., Sink, E. and L. Stewart, "An
+ Extension to HTTP : Digest Access Authentication",
+ RFC 2069, January 1997.
+
+ [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and
+ T. Berners-Lee, "Hypertext Transfer Protocol --
+ HTTP/1.1", RFC 2068, January 1997.
+
+ [ISO-639] ISO (International Organization for Standardization).
+ ISO 639:1988. "Code for the representation of names
+ of languages."
+
+ [ISO-8601] ISO (International Organization for Standardization).
+ ISO 8601:1988. "Data elements and interchange formats
+ - Information interchange - Representation of dates
+ and times."
+
+ [ISO-11578] ISO (International Organization for Standardization).
+ ISO/IEC 11578:1996. "Information technology - Open
+ Systems Interconnection - Remote Procedure Call
+ (RPC)"
+
+ [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
+
+ [UTF-8] Yergeau, F., "UTF-8, a transformation format of
+ Unicode and ISO 10646", RFC 2279, January 1998.
+
+21.2 Informational References
+
+ [RFC2026] Bradner, S., "The Internet Standards Process - Revision
+ 3", BCP 9, RFC 2026, October 1996.
+
+
+
+
+
+Goland, et al. Standards Track [Page 83]
+
+RFC 2518 WEBDAV February 1999
+
+
+ [RFC1807] Lasher, R. and D. Cohen, "A Format for Bibliographic
+ Records", RFC 1807, June 1995.
+
+ [WF] C. Lagoze, "The Warwick Framework: A Container
+ Architecture for Diverse Sets of Metadata", D-Lib
+ Magazine, July/August 1996.
+ http://www.dlib.org/dlib/july96/lagoze/07lagoze.html
+
+ [USMARC] Network Development and MARC Standards, Office, ed. 1994.
+ "USMARC Format for Bibliographic Data", 1994. Washington,
+ DC: Cataloging Distribution Service, Library of Congress.
+
+ [REC-PICS] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS
+ Label Distribution Label Syntax and Communication
+ Protocols" Version 1.1, World Wide Web Consortium
+ Recommendation REC-PICS-labels-961031.
+ http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html.
+
+ [RFC2291] Slein, J., Vitali, F., Whitehead, E. and D. Durand,
+ "Requirements for Distributed Authoring and Versioning
+ Protocol for the World Wide Web", RFC 2291, February 1998.
+
+ [RFC2413] Weibel, S., Kunze, J., Lagoze, C. and M. Wolf, "Dublin
+ Core Metadata for Resource Discovery", RFC 2413, September
+ 1998.
+
+ [RFC2376] Whitehead, E. and M. Murata, "XML Media Types", RFC 2376,
+ July 1998.
+
+22 Authors' Addresses
+
+ Y. Y. Goland
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052-6399
+
+ EMail: yarong at microsoft.com
+
+
+ E. J. Whitehead, Jr.
+ Dept. Of Information and Computer Science
+ University of California, Irvine
+ Irvine, CA 92697-3425
+
+ EMail: ejw at ics.uci.edu
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 84]
+
+RFC 2518 WEBDAV February 1999
+
+
+ A. Faizi
+ Netscape
+ 685 East Middlefield Road
+ Mountain View, CA 94043
+
+ EMail: asad at netscape.com
+
+
+ S. R. Carter
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+
+ EMail: srcarter at novell.com
+
+
+ D. Jensen
+ Novell
+ 1555 N. Technology Way
+ M/S ORM F111
+ Orem, UT 84097-2399
+
+ EMail: dcjensen at novell.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 85]
+
+RFC 2518 WEBDAV February 1999
+
+
+23 Appendices
+
+23.1 Appendix 1 - WebDAV Document Type Definition
+
+ This section provides a document type definition, following the rules
+ in [REC-XML], for the XML elements used in the protocol stream and in
+ the values of properties. It collects the element definitions given
+ in sections 12 and 13.
+
+ <!DOCTYPE webdav-1.0 [
+
+ <!--============ XML Elements from Section 12 ==================-->
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?) >
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+ <!ELEMENT locktype (write) >
+ <!ELEMENT write EMPTY >
+
+ <!ELEMENT lockscope (exclusive | shared) >
+ <!ELEMENT exclusive EMPTY >
+ <!ELEMENT shared EMPTY >
+
+ <!ELEMENT depth (#PCDATA) >
+
+ <!ELEMENT owner ANY >
+
+ <!ELEMENT timeout (#PCDATA) >
+
+ <!ELEMENT locktoken (href+) >
+
+ <!ELEMENT href (#PCDATA) >
+
+ <!ELEMENT link (src+, dst+) >
+ <!ELEMENT dst (#PCDATA) >
+ <!ELEMENT src (#PCDATA) >
+
+ <!ELEMENT multistatus (response+, responsedescription?) >
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+ responsedescription?) >
+ <!ELEMENT status (#PCDATA) >
+ <!ELEMENT propstat (prop, status, responsedescription?) >
+ <!ELEMENT responsedescription (#PCDATA) >
+
+
+
+
+Goland, et al. Standards Track [Page 86]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <!ELEMENT prop ANY >
+
+ <!ELEMENT propertybehavior (omit | keepalive) >
+ <!ELEMENT omit EMPTY >
+
+ <!ELEMENT keepalive (#PCDATA | href+) >
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+ <!ELEMENT remove (prop) >
+ <!ELEMENT set (prop) >
+
+ <!ELEMENT propfind (allprop | propname | prop) >
+ <!ELEMENT allprop EMPTY >
+ <!ELEMENT propname EMPTY >
+
+ <!ELEMENT collection EMPTY >
+
+ <!--=========== Property Elements from Section 13 ===============-->
+ <!ELEMENT creationdate (#PCDATA) >
+ <!ELEMENT displayname (#PCDATA) >
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+ <!ELEMENT getcontentlength (#PCDATA) >
+ <!ELEMENT getcontenttype (#PCDATA) >
+ <!ELEMENT getetag (#PCDATA) >
+ <!ELEMENT getlastmodified (#PCDATA) >
+ <!ELEMENT lockdiscovery (activelock)* >
+ <!ELEMENT resourcetype ANY >
+ <!ELEMENT source (link)* >
+ <!ELEMENT supportedlock (lockentry)* >
+ ]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 87]
+
+RFC 2518 WEBDAV February 1999
+
+
+23.2 Appendix 2 - ISO 8601 Date and Time Profile
+
+ The creationdate property specifies the use of the ISO 8601 date
+ format [ISO-8601]. This section defines a profile of the ISO 8601
+ date format for use with this specification. This profile is quoted
+ from an Internet-Draft by Chris Newman, and is mentioned here to
+ properly attribute his work.
+
+ date-time = full-date "T" full-time
+
+ full-date = date-fullyear "-" date-month "-" date-mday
+ full-time = partial-time time-offset
+
+ date-fullyear = 4DIGIT
+ date-month = 2DIGIT ; 01-12
+ date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
+ month/year
+ time-hour = 2DIGIT ; 00-23
+ time-minute = 2DIGIT ; 00-59
+ time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules
+ time-secfrac = "." 1*DIGIT
+ time-numoffset = ("+" / "-") time-hour ":" time-minute
+ time-offset = "Z" / time-numoffset
+
+ partial-time = time-hour ":" time-minute ":" time-second
+ [time-secfrac]
+
+ Numeric offsets are calculated as local time minus UTC (Coordinated
+ Universal Time). So the equivalent time in UTC can be determined by
+ subtracting the offset from the local time. For example, 18:50:00-
+ 04:00 is the same time as 22:58:00Z.
+
+ If the time in UTC is known, but the offset to local time is unknown,
+ this can be represented with an offset of "-00:00". This differs
+ from an offset of "Z" which implies that UTC is the preferred
+ reference point for the specified time.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 88]
+
+RFC 2518 WEBDAV February 1999
+
+
+23.3 Appendix 3 - Notes on Processing XML Elements
+
+23.3.1 Notes on Empty XML Elements
+
+ XML supports two mechanisms for indicating that an XML element does
+ not have any content. The first is to declare an XML element of the
+ form <A></A>. The second is to declare an XML element of the form
+ <A/>. The two XML elements are semantically identical.
+
+ It is a violation of the XML specification to use the <A></A> form if
+ the associated DTD declares the element to be EMPTY (e.g., <!ELEMENT
+ A EMPTY>). If such a statement is included, then the empty element
+ format, <A/> must be used. If the element is not declared to be
+ EMPTY, then either form <A></A> or <A/> may be used for empty
+ elements.
+
+ 23.3.2 Notes on Illegal XML Processing
+
+ XML is a flexible data format that makes it easy to submit data that
+ appears legal but in fact is not. The philosophy of "Be flexible in
+ what you accept and strict in what you send" still applies, but it
+ must not be applied inappropriately. XML is extremely flexible in
+ dealing with issues of white space, element ordering, inserting new
+ elements, etc. This flexibility does not require extension,
+ especially not in the area of the meaning of elements.
+
+ There is no kindness in accepting illegal combinations of XML
+ elements. At best it will cause an unwanted result and at worst it
+ can cause real damage.
+
+23.3.2.1 Example - XML Syntax Error
+
+ The following request body for a PROPFIND method is illegal.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:propname/>
+ </D:propfind>
+
+ The definition of the propfind element only allows for the allprop or
+ the propname element, not both. Thus the above is an error and must
+ be responded to with a 400 (Bad Request).
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 89]
+
+RFC 2518 WEBDAV February 1999
+
+
+ Imagine, however, that a server wanted to be "kind" and decided to
+ pick the allprop element as the true element and respond to it. A
+ client running over a bandwidth limited line who intended to execute
+ a propname would be in for a big surprise if the server treated the
+ command as an allprop.
+
+ Additionally, if a server were lenient and decided to reply to this
+ request, the results would vary randomly from server to server, with
+ some servers executing the allprop directive, and others executing
+ the propname directive. This reduces interoperability rather than
+ increasing it.
+
+23.3.2.2 Example - Unknown XML Element
+
+ The previous example was illegal because it contained two elements
+ that were explicitly banned from appearing together in the propfind
+ element. However, XML is an extensible language, so one can imagine
+ new elements being defined for use with propfind. Below is the
+ request body of a PROPFIND and, like the previous example, must be
+ rejected with a 400 (Bad Request) by a server that does not
+ understand the expired-props element.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+ <E:expired-props/>
+ </D:propfind>
+
+ To understand why a 400 (Bad Request) is returned let us look at the
+ request body as the server unfamiliar with expired-props sees it.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+ </D:propfind>
+
+ As the server does not understand the expired-props element,
+ according to the WebDAV-specific XML processing rules specified in
+ section 14, it must ignore it. Thus the server sees an empty
+ propfind, which by the definition of the propfind element is illegal.
+
+ Please note that had the extension been additive it would not
+ necessarily have resulted in a 400 (Bad Request). For example,
+ imagine the following request body for a PROPFIND:
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.foo.bar/standards/props/">
+
+
+
+Goland, et al. Standards Track [Page 90]
+
+RFC 2518 WEBDAV February 1999
+
+
+ <D:propname/>
+ <E:leave-out>*boss*</E:leave-out>
+ </D:propfind>
+
+ The previous example contains the fictitious element leave-out. Its
+ purpose is to prevent the return of any property whose name matches
+ the submitted pattern. If the previous example were submitted to a
+ server unfamiliar with leave-out, the only result would be that the
+ leave-out element would be ignored and a propname would be executed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 91]
+
+RFC 2518 WEBDAV February 1999
+
+
+23.4 Appendix 4 -- XML Namespaces for WebDAV
+
+23.4.1 Introduction
+
+ All DAV compliant systems MUST support the XML namespace extensions
+ as specified in [REC-XML-NAMES].
+
+23.4.2 Meaning of Qualified Names
+
+ [Note to the reader: This section does not appear in [REC-XML-NAMES],
+ but is necessary to avoid ambiguity for WebDAV XML processors.]
+
+ WebDAV compliant XML processors MUST interpret a qualified name as a
+ URI constructed by appending the LocalPart to the namespace name URI.
+
+ Example
+
+ <del:glider xmlns:del="http://www.del.jensen.org/">
+ <del:glidername>
+ Johnny Updraft
+ </del:glidername>
+ <del:glideraccidents/>
+ </del:glider>
+
+ In this example, the qualified element name "del:glider" is
+ interpreted as the URL "http://www.del.jensen.org/glider".
+
+ <bar:glider xmlns:del="http://www.del.jensen.org/">
+ <bar:glidername>
+ Johnny Updraft
+ </bar:glidername>
+ <bar:glideraccidents/>
+ </bar:glider>
+
+ Even though this example is syntactically different from the previous
+ example, it is semantically identical. Each instance of the
+ namespace name "bar" is replaced with "http://www.del.jensen.org/"
+ and then appended to the local name for each element tag. The
+ resulting tag names in this example are exactly the same as for the
+ previous example.
+
+ <foo:r xmlns:foo="http://www.del.jensen.org/glide">
+ <foo:rname>
+ Johnny Updraft
+ </foo:rname>
+ <foo:raccidents/>
+ </foo:r>
+
+
+
+
+Goland, et al. Standards Track [Page 92]
+
+RFC 2518 WEBDAV February 1999
+
+
+ This example is semantically identical to the two previous ones.
+ Each instance of the namespace name "foo" is replaced with
+ "http://www.del.jensen.org/glide" which is then appended to the local
+ name for each element tag, the resulting tag names are identical to
+ those in the previous examples.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 93]
+
+RFC 2518 WEBDAV February 1999
+
+
+24. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Goland, et al. Standards Track [Page 94]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2518.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2518.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2518.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,5267 +0,0 @@
-
-
-
-
-
-
-Network Working Group Y. Goland
-Request for Comments: 2518 Microsoft
-Category: Standards Track E. Whitehead
- UC Irvine
- A. Faizi
- Netscape
- S. Carter
- Novell
- D. Jensen
- Novell
- February 1999
-
-
- HTTP Extensions for Distributed Authoring -- WEBDAV
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- This document specifies a set of methods, headers, and content-types
- ancillary to HTTP/1.1 for the management of resource properties,
- creation and management of resource collections, namespace
- manipulation, and resource locking (collision avoidance).
-
-Table of Contents
-
- ABSTRACT............................................................1
- 1 INTRODUCTION .....................................................5
- 2 NOTATIONAL CONVENTIONS ...........................................7
- 3 TERMINOLOGY ......................................................7
- 4 DATA MODEL FOR RESOURCE PROPERTIES ...............................8
- 4.1 The Resource Property Model ...................................8
- 4.2 Existing Metadata Proposals ...................................8
- 4.3 Properties and HTTP Headers ...................................9
- 4.4 Property Values ...............................................9
- 4.5 Property Names ...............................................10
- 4.6 Media Independent Links ......................................10
- 5 COLLECTIONS OF WEB RESOURCES ....................................11
-
-
-
-Goland, et al. Standards Track [Page 1]
-
-RFC 2518 WEBDAV February 1999
-
-
- 5.1 HTTP URL Namespace Model .....................................11
- 5.2 Collection Resources .........................................11
- 5.3 Creation and Retrieval of Collection Resources ...............12
- 5.4 Source Resources and Output Resources ........................13
- 6 LOCKING .........................................................14
- 6.1 Exclusive Vs. Shared Locks ...................................14
- 6.2 Required Support .............................................16
- 6.3 Lock Tokens ..................................................16
- 6.4 opaquelocktoken Lock Token URI Scheme ........................16
- 6.4.1 Node Field Generation Without the IEEE 802 Address ........17
- 6.5 Lock Capability Discovery ....................................19
- 6.6 Active Lock Discovery ........................................19
- 6.7 Usage Considerations .........................................19
- 7 WRITE LOCK ......................................................20
- 7.1 Methods Restricted by Write Locks ............................20
- 7.2 Write Locks and Lock Tokens ..................................20
- 7.3 Write Locks and Properties ...................................20
- 7.4 Write Locks and Null Resources ...............................21
- 7.5 Write Locks and Collections ..................................21
- 7.6 Write Locks and the If Request Header ........................22
- 7.6.1 Example - Write Lock ......................................22
- 7.7 Write Locks and COPY/MOVE ....................................23
- 7.8 Refreshing Write Locks .......................................23
- 8 HTTP METHODS FOR DISTRIBUTED AUTHORING ..........................23
- 8.1 PROPFIND .....................................................24
- 8.1.1 Example - Retrieving Named Properties .....................25
- 8.1.2 Example - Using allprop to Retrieve All Properties ........26
- 8.1.3 Example - Using propname to Retrieve all Property Names ...29
- 8.2 PROPPATCH ....................................................31
- 8.2.1 Status Codes for use with 207 (Multi-Status) ..............31
- 8.2.2 Example - PROPPATCH .......................................32
- 8.3 MKCOL Method .................................................33
- 8.3.1 Request ...................................................33
- 8.3.2 Status Codes ..............................................33
- 8.3.3 Example - MKCOL ...........................................34
- 8.4 GET, HEAD for Collections ....................................34
- 8.5 POST for Collections .........................................35
- 8.6 DELETE .......................................................35
- 8.6.1 DELETE for Non-Collection Resources .......................35
- 8.6.2 DELETE for Collections ....................................36
- 8.7 PUT ..........................................................36
- 8.7.1 PUT for Non-Collection Resources ..........................36
- 8.7.2 PUT for Collections .......................................37
- 8.8 COPY Method ..................................................37
- 8.8.1 COPY for HTTP/1.1 resources ...............................37
- 8.8.2 COPY for Properties .......................................38
- 8.8.3 COPY for Collections ......................................38
- 8.8.4 COPY and the Overwrite Header .............................39
-
-
-
-Goland, et al. Standards Track [Page 2]
-
-RFC 2518 WEBDAV February 1999
-
-
- 8.8.5 Status Codes ..............................................39
- 8.8.6 Example - COPY with Overwrite .............................40
- 8.8.7 Example - COPY with No Overwrite ..........................40
- 8.8.8 Example - COPY of a Collection ............................41
- 8.9 MOVE Method ..................................................42
- 8.9.1 MOVE for Properties .......................................42
- 8.9.2 MOVE for Collections ......................................42
- 8.9.3 MOVE and the Overwrite Header .............................43
- 8.9.4 Status Codes ..............................................43
- 8.9.5 Example - MOVE of a Non-Collection ........................44
- 8.9.6 Example - MOVE of a Collection ............................44
- 8.10 LOCK Method ..................................................45
- 8.10.1 Operation .................................................46
- 8.10.2 The Effect of Locks on Properties and Collections .........46
- 8.10.3 Locking Replicated Resources ..............................46
- 8.10.4 Depth and Locking .........................................46
- 8.10.5 Interaction with other Methods ............................47
- 8.10.6 Lock Compatibility Table ..................................47
- 8.10.7 Status Codes ..............................................48
- 8.10.8 Example - Simple Lock Request .............................48
- 8.10.9 Example - Refreshing a Write Lock .........................49
- 8.10.10 Example - Multi-Resource Lock Request ....................50
- 8.11 UNLOCK Method ................................................51
- 8.11.1 Example - UNLOCK ..........................................52
- 9 HTTP HEADERS FOR DISTRIBUTED AUTHORING ..........................52
- 9.1 DAV Header ...................................................52
- 9.2 Depth Header .................................................52
- 9.3 Destination Header ...........................................54
- 9.4 If Header ....................................................54
- 9.4.1 No-tag-list Production ....................................55
- 9.4.2 Tagged-list Production ....................................55
- 9.4.3 not Production ............................................56
- 9.4.4 Matching Function .........................................56
- 9.4.5 If Header and Non-DAV Compliant Proxies ...................57
- 9.5 Lock-Token Header ............................................57
- 9.6 Overwrite Header .............................................57
- 9.7 Status-URI Response Header ...................................57
- 9.8 Timeout Request Header .......................................58
- 10 STATUS CODE EXTENSIONS TO HTTP/1.1 ............................59
- 10.1 102 Processing ...............................................59
- 10.2 207 Multi-Status .............................................59
- 10.3 422 Unprocessable Entity .....................................60
- 10.4 423 Locked ...................................................60
- 10.5 424 Failed Dependency ........................................60
- 10.6 507 Insufficient Storage .....................................60
- 11 MULTI-STATUS RESPONSE .........................................60
- 12 XML ELEMENT DEFINITIONS .......................................61
- 12.1 activelock XML Element .......................................61
-
-
-
-Goland, et al. Standards Track [Page 3]
-
-RFC 2518 WEBDAV February 1999
-
-
- 12.1.1 depth XML Element .........................................61
- 12.1.2 locktoken XML Element .....................................61
- 12.1.3 timeout XML Element .......................................61
- 12.2 collection XML Element .......................................62
- 12.3 href XML Element .............................................62
- 12.4 link XML Element .............................................62
- 12.4.1 dst XML Element ...........................................62
- 12.4.2 src XML Element ...........................................62
- 12.5 lockentry XML Element ........................................63
- 12.6 lockinfo XML Element .........................................63
- 12.7 lockscope XML Element ........................................63
- 12.7.1 exclusive XML Element .....................................63
- 12.7.2 shared XML Element ........................................63
- 12.8 locktype XML Element .........................................64
- 12.8.1 write XML Element .........................................64
- 12.9 multistatus XML Element ......................................64
- 12.9.1 response XML Element ......................................64
- 12.9.2 responsedescription XML Element ...........................65
- 12.10 owner XML Element ...........................................65
- 12.11 prop XML element ............................................66
- 12.12 propertybehavior XML element ................................66
- 12.12.1 keepalive XML element ....................................66
- 12.12.2 omit XML element .........................................67
- 12.13 propertyupdate XML element ..................................67
- 12.13.1 remove XML element .......................................67
- 12.13.2 set XML element ..........................................67
- 12.14 propfind XML Element ........................................68
- 12.14.1 allprop XML Element ......................................68
- 12.14.2 propname XML Element .....................................68
- 13 DAV PROPERTIES ................................................68
- 13.1 creationdate Property ........................................69
- 13.2 displayname Property .........................................69
- 13.3 getcontentlanguage Property ..................................69
- 13.4 getcontentlength Property ....................................69
- 13.5 getcontenttype Property ......................................70
- 13.6 getetag Property .............................................70
- 13.7 getlastmodified Property .....................................70
- 13.8 lockdiscovery Property .......................................71
- 13.8.1 Example - Retrieving the lockdiscovery Property ...........71
- 13.9 resourcetype Property ........................................72
- 13.10 source Property .............................................72
- 13.10.1 Example - A source Property ..............................72
- 13.11 supportedlock Property ......................................73
- 13.11.1 Example - Retrieving the supportedlock Property ..........73
- 14 INSTRUCTIONS FOR PROCESSING XML IN DAV ........................74
- 15 DAV COMPLIANCE CLASSES ........................................75
- 15.1 Class 1 ......................................................75
- 15.2 Class 2 ......................................................75
-
-
-
-Goland, et al. Standards Track [Page 4]
-
-RFC 2518 WEBDAV February 1999
-
-
- 16 INTERNATIONALIZATION CONSIDERATIONS ...........................76
- 17 SECURITY CONSIDERATIONS .......................................77
- 17.1 Authentication of Clients ....................................77
- 17.2 Denial of Service ............................................78
- 17.3 Security through Obscurity ...................................78
- 17.4 Privacy Issues Connected to Locks ............................78
- 17.5 Privacy Issues Connected to Properties .......................79
- 17.6 Reduction of Security due to Source Link .....................79
- 17.7 Implications of XML External Entities ........................79
- 17.8 Risks Connected with Lock Tokens .............................80
- 18 IANA CONSIDERATIONS ...........................................80
- 19 INTELLECTUAL PROPERTY .........................................81
- 20 ACKNOWLEDGEMENTS ..............................................82
- 21 REFERENCES ....................................................82
- 21.1 Normative References .........................................82
- 21.2 Informational References .....................................83
- 22 AUTHORS' ADDRESSES ............................................84
- 23 APPENDICES ....................................................86
- 23.1 Appendix 1 - WebDAV Document Type Definition .................86
- 23.2 Appendix 2 - ISO 8601 Date and Time Profile ..................88
- 23.3 Appendix 3 - Notes on Processing XML Elements ................89
- 23.3.1 Notes on Empty XML Elements ...............................89
- 23.3.2 Notes on Illegal XML Processing ...........................89
- 23.4 Appendix 4 -- XML Namespaces for WebDAV ......................92
- 23.4.1 Introduction ..............................................92
- 23.4.2 Meaning of Qualified Names ................................92
- 24 FULL COPYRIGHT STATEMENT ......................................94
-
-
-
-1 Introduction
-
- This document describes an extension to the HTTP/1.1 protocol that
- allows clients to perform remote web content authoring operations.
- This extension provides a coherent set of methods, headers, request
- entity body formats, and response entity body formats that provide
- operations for:
-
- Properties: The ability to create, remove, and query information
- about Web pages, such as their authors, creation dates, etc. Also,
- the ability to link pages of any media type to related pages.
-
- Collections: The ability to create sets of documents and to retrieve
- a hierarchical membership listing (like a directory listing in a file
- system).
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 5]
-
-RFC 2518 WEBDAV February 1999
-
-
- Locking: The ability to keep more than one person from working on a
- document at the same time. This prevents the "lost update problem,"
- in which modifications are lost as first one author then another
- writes changes without merging the other author's changes.
-
- Namespace Operations: The ability to instruct the server to copy and
- move Web resources.
-
- Requirements and rationale for these operations are described in a
- companion document, "Requirements for a Distributed Authoring and
- Versioning Protocol for the World Wide Web" [RFC2291].
-
- The sections below provide a detailed introduction to resource
- properties (section 4), collections of resources (section 5), and
- locking operations (section 6). These sections introduce the
- abstractions manipulated by the WebDAV-specific HTTP methods
- described in section 8, "HTTP Methods for Distributed Authoring".
-
- In HTTP/1.1, method parameter information was exclusively encoded in
- HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
- information either in an Extensible Markup Language (XML) [REC-XML]
- request entity body, or in an HTTP header. The use of XML to encode
- method parameters was motivated by the ability to add extra XML
- elements to existing structures, providing extensibility; and by
- XML's ability to encode information in ISO 10646 character sets,
- providing internationalization support. As a rule of thumb,
- parameters are encoded in XML entity bodies when they have unbounded
- length, or when they may be shown to a human user and hence require
- encoding in an ISO 10646 character set. Otherwise, parameters are
- encoded within HTTP headers. Section 9 describes the new HTTP
- headers used with WebDAV methods.
-
- In addition to encoding method parameters, XML is used in WebDAV to
- encode the responses from methods, providing the extensibility and
- internationalization advantages of XML for method output, as well as
- input.
-
- XML elements used in this specification are defined in section 12.
-
- The XML namespace extension (Appendix 4) is also used in this
- specification in order to allow for new XML elements to be added
- without fear of colliding with other element names.
-
- While the status codes provided by HTTP/1.1 are sufficient to
- describe most error conditions encountered by WebDAV methods, there
- are some errors that do not fall neatly into the existing categories.
- New status codes developed for the WebDAV methods are defined in
- section 10. Since some WebDAV methods may operate over many
-
-
-
-Goland, et al. Standards Track [Page 6]
-
-RFC 2518 WEBDAV February 1999
-
-
- resources, the Multi-Status response has been introduced to return
- status information for multiple resources. The Multi-Status response
- is described in section 11.
-
- WebDAV employs the property mechanism to store information about the
- current state of the resource. For example, when a lock is taken out
- on a resource, a lock information property describes the current
- state of the lock. Section 13 defines the properties used within the
- WebDAV specification.
-
- Finishing off the specification are sections on what it means to be
- compliant with this specification (section 15), on
- internationalization support (section 16), and on security (section
- 17).
-
-2 Notational Conventions
-
- Since this document describes a set of extensions to the HTTP/1.1
- protocol, the augmented BNF used herein to describe protocol elements
- is exactly the same as described in section 2.1 of [RFC2068]. Since
- this augmented BNF uses the basic production rules provided in
- section 2.2 of [RFC2068], these rules apply to this document as well.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [RFC2119].
-
-3 Terminology
-
- URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
- respectively. These terms (and the distinction between them) are
- defined in [RFC2396].
-
- Collection - A resource that contains a set of URIs, termed member
- URIs, which identify member resources and meets the requirements in
- section 5 of this specification.
-
- Member URI - A URI which is a member of the set of URIs contained by
- a collection.
-
- Internal Member URI - A Member URI that is immediately relative to
- the URI of the collection (the definition of immediately relative is
- given in section 5.2).
-
- Property - A name/value pair that contains descriptive information
- about a resource.
-
-
-
-
-
-Goland, et al. Standards Track [Page 7]
-
-RFC 2518 WEBDAV February 1999
-
-
- Live Property - A property whose semantics and syntax are enforced by
- the server. For example, the live "getcontentlength" property has
- its value, the length of the entity returned by a GET request,
- automatically calculated by the server.
-
- Dead Property - A property whose semantics and syntax are not
- enforced by the server. The server only records the value of a dead
- property; the client is responsible for maintaining the consistency
- of the syntax and semantics of a dead property.
-
- Null Resource - A resource which responds with a 404 (Not Found) to
- any HTTP/1.1 or DAV method except for PUT, MKCOL, OPTIONS and LOCK.
- A NULL resource MUST NOT appear as a member of its parent collection.
-
-4 Data Model for Resource Properties
-
-4.1 The Resource Property Model
-
- Properties are pieces of data that describe the state of a resource.
- Properties are data about data.
-
- Properties are used in distributed authoring environments to provide
- for efficient discovery and management of resources. For example, a
- 'subject' property might allow for the indexing of all resources by
- their subject, and an 'author' property might allow for the discovery
- of what authors have written which documents.
-
- The DAV property model consists of name/value pairs. The name of a
- property identifies the property's syntax and semantics, and provides
- an address by which to refer to its syntax and semantics.
-
- There are two categories of properties: "live" and "dead". A live
- property has its syntax and semantics enforced by the server. Live
- properties include cases where a) the value of a property is read-
- only, maintained by the server, and b) the value of the property is
- maintained by the client, but the server performs syntax checking on
- submitted values. All instances of a given live property MUST comply
- with the definition associated with that property name. A dead
- property has its syntax and semantics enforced by the client; the
- server merely records the value of the property verbatim.
-
-4.2 Existing Metadata Proposals
-
- Properties have long played an essential role in the maintenance of
- large document repositories, and many current proposals contain some
- notion of a property, or discuss web metadata more generally. These
- include PICS [REC-PICS], PICS-NG, XML, Web Collections, and several
- proposals on representing relationships within HTML. Work on PICS-NG
-
-
-
-Goland, et al. Standards Track [Page 8]
-
-RFC 2518 WEBDAV February 1999
-
-
- and Web Collections has been subsumed by the Resource Description
- Framework (RDF) metadata activity of the World Wide Web Consortium.
- RDF consists of a network-based data model and an XML representation
- of that model.
-
- Some proposals come from a digital library perspective. These
- include the Dublin Core [RFC2413] metadata set and the Warwick
- Framework [WF], a container architecture for different metadata
- schemas. The literature includes many examples of metadata,
- including MARC [USMARC], a bibliographic metadata format, and a
- technical report bibliographic format employed by the Dienst system
- [RFC1807]. Additionally, the proceedings from the first IEEE Metadata
- conference describe many community-specific metadata sets.
-
- Participants of the 1996 Metadata II Workshop in Warwick, UK [WF],
- noted that "new metadata sets will develop as the networked
- infrastructure matures" and "different communities will propose,
- design, and be responsible for different types of metadata." These
- observations can be corroborated by noting that many community-
- specific sets of metadata already exist, and there is significant
- motivation for the development of new forms of metadata as many
- communities increasingly make their data available in digital form,
- requiring a metadata format to assist data location and cataloging.
-
-4.3 Properties and HTTP Headers
-
- Properties already exist, in a limited sense, in HTTP message
- headers. However, in distributed authoring environments a relatively
- large number of properties are needed to describe the state of a
- resource, and setting/returning them all through HTTP headers is
- inefficient. Thus a mechanism is needed which allows a principal to
- identify a set of properties in which the principal is interested and
- to set or retrieve just those properties.
-
-4.4 Property Values
-
- The value of a property when expressed in XML MUST be well formed.
-
- XML has been chosen because it is a flexible, self-describing,
- structured data format that supports rich schema definitions, and
- because of its support for multiple character sets. XML's self-
- describing nature allows any property's value to be extended by
- adding new elements. Older clients will not break when they
- encounter extensions because they will still have the data specified
- in the original schema and will ignore elements they do not
- understand. XML's support for multiple character sets allows any
- human-readable property to be encoded and read in a character set
- familiar to the user. XML's support for multiple human languages,
-
-
-
-Goland, et al. Standards Track [Page 9]
-
-RFC 2518 WEBDAV February 1999
-
-
- using the "xml:lang" attribute, handles cases where the same
- character set is employed by multiple human languages.
-
-4.5 Property Names
-
- A property name is a universally unique identifier that is associated
- with a schema that provides information about the syntax and
- semantics of the property.
-
- Because a property's name is universally unique, clients can depend
- upon consistent behavior for a particular property across multiple
- resources, on the same and across different servers, so long as that
- property is "live" on the resources in question, and the
- implementation of the live property is faithful to its definition.
-
- The XML namespace mechanism, which is based on URIs [RFC2396], is
- used to name properties because it prevents namespace collisions and
- provides for varying degrees of administrative control.
-
- The property namespace is flat; that is, no hierarchy of properties
- is explicitly recognized. Thus, if a property A and a property A/B
- exist on a resource, there is no recognition of any relationship
- between the two properties. It is expected that a separate
- specification will eventually be produced which will address issues
- relating to hierarchical properties.
-
- Finally, it is not possible to define the same property twice on a
- single resource, as this would cause a collision in the resource's
- property namespace.
-
-4.6 Media Independent Links
-
- Although HTML resources support links to other resources, the Web
- needs more general support for links between resources of any media
- type (media types are also known as MIME types, or content types).
- WebDAV provides such links. A WebDAV link is a special type of
- property value, formally defined in section 12.4, that allows typed
- connections to be established between resources of any media type.
- The property value consists of source and destination Uniform
- Resource Identifiers (URIs); the property name identifies the link
- type.
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 10]
-
-RFC 2518 WEBDAV February 1999
-
-
-5 Collections of Web Resources
-
- This section provides a description of a new type of Web resource,
- the collection, and discusses its interactions with the HTTP URL
- namespace. The purpose of a collection resource is to model
- collection-like objects (e.g., file system directories) within a
- server's namespace.
-
- All DAV compliant resources MUST support the HTTP URL namespace model
- specified herein.
-
-5.1 HTTP URL Namespace Model
-
- The HTTP URL namespace is a hierarchical namespace where the
- hierarchy is delimited with the "/" character.
-
- An HTTP URL namespace is said to be consistent if it meets the
- following conditions: for every URL in the HTTP hierarchy there
- exists a collection that contains that URL as an internal member.
- The root, or top-level collection of the namespace under
- consideration is exempt from the previous rule.
-
- Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
- namespace be consistent. However, certain WebDAV methods are
- prohibited from producing results that cause namespace
- inconsistencies.
-
- Although implicit in [RFC2068] and [RFC2396], any resource, including
- collection resources, MAY be identified by more than one URI. For
- example, a resource could be identified by multiple HTTP URLs.
-
-5.2 Collection Resources
-
- A collection is a resource whose state consists of at least a list of
- internal member URIs and a set of properties, but which may have
- additional state such as entity bodies returned by GET. An internal
- member URI MUST be immediately relative to a base URI of the
- collection. That is, the internal member URI is equal to a
- containing collection's URI plus an additional segment for non-
- collection resources, or additional segment plus trailing slash "/"
- for collection resources, where segment is defined in section 3.3 of
- [RFC2396].
-
- Any given internal member URI MUST only belong to the collection
- once, i.e., it is illegal to have multiple instances of the same URI
- in a collection. Properties defined on collections behave exactly as
- do properties on non-collection resources.
-
-
-
-
-Goland, et al. Standards Track [Page 11]
-
-RFC 2518 WEBDAV February 1999
-
-
- For all WebDAV compliant resources A and B, identified by URIs U and
- V, for which U is immediately relative to V, B MUST be a collection
- that has U as an internal member URI. So, if the resource with URL
- http://foo.com/bar/blah is WebDAV compliant and if the resource with
- URL http://foo.com/bar/ is WebDAV compliant then the resource with
- URL http://foo.com/bar/ must be a collection and must contain URL
- http://foo.com/bar/blah as an internal member.
-
- Collection resources MAY list the URLs of non-WebDAV compliant
- children in the HTTP URL namespace hierarchy as internal members but
- are not required to do so. For example, if the resource with URL
- http://foo.com/bar/blah is not WebDAV compliant and the URL
- http://foo.com/bar/ identifies a collection then URL
- http://foo.com/bar/blah may or may not be an internal member of the
- collection with URL http://foo.com/bar/.
-
- If a WebDAV compliant resource has no WebDAV compliant children in
- the HTTP URL namespace hierarchy then the WebDAV compliant resource
- is not required to be a collection.
-
- There is a standing convention that when a collection is referred to
- by its name without a trailing slash, the trailing slash is
- automatically appended. Due to this, a resource may accept a URI
- without a trailing "/" to point to a collection. In this case it
- SHOULD return a content-location header in the response pointing to
- the URI ending with the "/". For example, if a client invokes a
- method on http://foo.bar/blah (no trailing slash), the resource
- http://foo.bar/blah/ (trailing slash) may respond as if the operation
- were invoked on it, and should return a content-location header with
- http://foo.bar/blah/ in it. In general clients SHOULD use the "/"
- form of collection names.
-
- A resource MAY be a collection but not be WebDAV compliant. That is,
- the resource may comply with all the rules set out in this
- specification regarding how a collection is to behave without
- necessarily supporting all methods that a WebDAV compliant resource
- is required to support. In such a case the resource may return the
- DAV:resourcetype property with the value DAV:collection but MUST NOT
- return a DAV header containing the value "1" on an OPTIONS response.
-
-5.3 Creation and Retrieval of Collection Resources
-
- This document specifies the MKCOL method to create new collection
- resources, rather than using the existing HTTP/1.1 PUT or POST
- method, for the following reasons:
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 12]
-
-RFC 2518 WEBDAV February 1999
-
-
- In HTTP/1.1, the PUT method is defined to store the request body at
- the location specified by the Request-URI. While a description
- format for a collection can readily be constructed for use with PUT,
- the implications of sending such a description to the server are
- undesirable. For example, if a description of a collection that
- omitted some existing resources were PUT to a server, this might be
- interpreted as a command to remove those members. This would extend
- PUT to perform DELETE functionality, which is undesirable since it
- changes the semantics of PUT, and makes it difficult to control
- DELETE functionality with an access control scheme based on methods.
-
- While the POST method is sufficiently open-ended that a "create a
- collection" POST command could be constructed, this is undesirable
- because it would be difficult to separate access control for
- collection creation from other uses of POST.
-
- The exact definition of the behavior of GET and PUT on collections is
- defined later in this document.
-
-5.4 Source Resources and Output Resources
-
- For many resources, the entity returned by a GET method exactly
- matches the persistent state of the resource, for example, a GIF file
- stored on a disk. For this simple case, the URI at which a resource
- is accessed is identical to the URI at which the source (the
- persistent state) of the resource is accessed. This is also the case
- for HTML source files that are not processed by the server prior to
- transmission.
-
- However, the server can sometimes process HTML resources before they
- are transmitted as a return entity body. For example, a server-
- side-include directive within an HTML file might instruct a server to
- replace the directive with another value, such as the current date.
- In this case, what is returned by GET (HTML plus date) differs from
- the persistent state of the resource (HTML plus directive).
- Typically there is no way to access the HTML resource containing the
- unprocessed directive.
-
- Sometimes the entity returned by GET is the output of a data-
- producing process that is described by one or more source resources
- (that may not even have a location in the URI namespace). A single
- data-producing process may dynamically generate the state of a
- potentially large number of output resources. An example of this is
- a CGI script that describes a "finger" gateway process that maps part
- of the namespace of a server into finger requests, such as
- http://www.foo.bar.org/finger_gateway/user@host.
-
-
-
-
-
-Goland, et al. Standards Track [Page 13]
-
-RFC 2518 WEBDAV February 1999
-
-
- In the absence of distributed authoring capabilities, it is
- acceptable to have no mapping of source resource(s) to the URI
- namespace. In fact, preventing access to the source resource(s) has
- desirable security benefits. However, if remote editing of the
- source resource(s) is desired, the source resource(s) should be given
- a location in the URI namespace. This source location should not be
- one of the locations at which the generated output is retrievable,
- since in general it is impossible for the server to differentiate
- requests for source resources from requests for process output
- resources. There is often a many-to-many relationship between source
- resources and output resources.
-
- On WebDAV compliant servers the URI of the source resource(s) may be
- stored in a link on the output resource with type DAV:source (see
- section 13.10 for a description of the source link property).
- Storing the source URIs in links on the output resources places the
- burden of discovering the source on the authoring client. Note that
- the value of a source link is not guaranteed to point to the correct
- source. Source links may break or incorrect values may be entered.
- Also note that not all servers will allow the client to set the
- source link value. For example a server which generates source links
- on the fly for its CGI files will most likely not allow a client to
- set the source link value.
-
-6 Locking
-
- The ability to lock a resource provides a mechanism for serializing
- access to that resource. Using a lock, an authoring client can
- provide a reasonable guarantee that another principal will not modify
- a resource while it is being edited. In this way, a client can
- prevent the "lost update" problem.
-
- This specification allows locks to vary over two client-specified
- parameters, the number of principals involved (exclusive vs. shared)
- and the type of access to be granted. This document defines locking
- for only one access type, write. However, the syntax is extensible,
- and permits the eventual specification of locking for other access
- types.
-
-6.1 Exclusive Vs. Shared Locks
-
- The most basic form of lock is an exclusive lock. This is a lock
- where the access right in question is only granted to a single
- principal. The need for this arbitration results from a desire to
- avoid having to merge results.
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 14]
-
-RFC 2518 WEBDAV February 1999
-
-
- However, there are times when the goal of a lock is not to exclude
- others from exercising an access right but rather to provide a
- mechanism for principals to indicate that they intend to exercise
- their access rights. Shared locks are provided for this case. A
- shared lock allows multiple principals to receive a lock. Hence any
- principal with appropriate access can get the lock.
-
- With shared locks there are two trust sets that affect a resource.
- The first trust set is created by access permissions. Principals who
- are trusted, for example, may have permission to write to the
- resource. Among those who have access permission to write to the
- resource, the set of principals who have taken out a shared lock also
- must trust each other, creating a (typically) smaller trust set
- within the access permission write set.
-
- Starting with every possible principal on the Internet, in most
- situations the vast majority of these principals will not have write
- access to a given resource. Of the small number who do have write
- access, some principals may decide to guarantee their edits are free
- from overwrite conflicts by using exclusive write locks. Others may
- decide they trust their collaborators will not overwrite their work
- (the potential set of collaborators being the set of principals who
- have write permission) and use a shared lock, which informs their
- collaborators that a principal may be working on the resource.
-
- The WebDAV extensions to HTTP do not need to provide all of the
- communications paths necessary for principals to coordinate their
- activities. When using shared locks, principals may use any out of
- band communication channel to coordinate their work (e.g., face-to-
- face interaction, written notes, post-it notes on the screen,
- telephone conversation, Email, etc.) The intent of a shared lock is
- to let collaborators know who else may be working on a resource.
-
- Shared locks are included because experience from web distributed
- authoring systems has indicated that exclusive locks are often too
- rigid. An exclusive lock is used to enforce a particular editing
- process: take out an exclusive lock, read the resource, perform
- edits, write the resource, release the lock. This editing process
- has the problem that locks are not always properly released, for
- example when a program crashes, or when a lock owner leaves without
- unlocking a resource. While both timeouts and administrative action
- can be used to remove an offending lock, neither mechanism may be
- available when needed; the timeout may be long or the administrator
- may not be available.
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 15]
-
-RFC 2518 WEBDAV February 1999
-
-
-6.2 Required Support
-
- A WebDAV compliant server is not required to support locking in any
- form. If the server does support locking it may choose to support
- any combination of exclusive and shared locks for any access types.
-
- The reason for this flexibility is that locking policy strikes to the
- very heart of the resource management and versioning systems employed
- by various storage repositories. These repositories require control
- over what sort of locking will be made available. For example, some
- repositories only support shared write locks while others only
- provide support for exclusive write locks while yet others use no
- locking at all. As each system is sufficiently different to merit
- exclusion of certain locking features, this specification leaves
- locking as the sole axis of negotiation within WebDAV.
-
-6.3 Lock Tokens
-
- A lock token is a type of state token, represented as a URI, which
- identifies a particular lock. A lock token is returned by every
- successful LOCK operation in the lockdiscovery property in the
- response body, and can also be found through lock discovery on a
- resource.
-
- Lock token URIs MUST be unique across all resources for all time.
- This uniqueness constraint allows lock tokens to be submitted across
- resources and servers without fear of confusion.
-
- This specification provides a lock token URI scheme called
- opaquelocktoken that meets the uniqueness requirements. However
- resources are free to return any URI scheme so long as it meets the
- uniqueness requirements.
-
- Having a lock token provides no special access rights. Anyone can
- find out anyone else's lock token by performing lock discovery.
- Locks MUST be enforced based upon whatever authentication mechanism
- is used by the server, not based on the secrecy of the token values.
-
-6.4 opaquelocktoken Lock Token URI Scheme
-
- The opaquelocktoken URI scheme is designed to be unique across all
- resources for all time. Due to this uniqueness quality, a client may
- submit an opaque lock token in an If header on a resource other than
- the one that returned it.
-
- All resources MUST recognize the opaquelocktoken scheme and, at
- minimum, recognize that the lock token does not refer to an
- outstanding lock on the resource.
-
-
-
-Goland, et al. Standards Track [Page 16]
-
-RFC 2518 WEBDAV February 1999
-
-
- In order to guarantee uniqueness across all resources for all time
- the opaquelocktoken requires the use of the Universal Unique
- Identifier (UUID) mechanism, as described in [ISO-11578].
-
- Opaquelocktoken generators, however, have a choice of how they create
- these tokens. They can either generate a new UUID for every lock
- token they create or they can create a single UUID and then add
- extension characters. If the second method is selected then the
- program generating the extensions MUST guarantee that the same
- extension will never be used twice with the associated UUID.
-
- OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension] ; The UUID
- production is the string representation of a UUID, as defined in
- [ISO-11578]. Note that white space (LWS) is not allowed between
- elements of this production.
-
- Extension = path ; path is defined in section 3.2.1 of RFC 2068
- [RFC2068]
-
-6.4.1 Node Field Generation Without the IEEE 802 Address
-
- UUIDs, as defined in [ISO-11578], contain a "node" field that
- contains one of the IEEE 802 addresses for the server machine. As
- noted in section 17.8, there are several security risks associated
- with exposing a machine's IEEE 802 address. This section provides an
- alternate mechanism for generating the "node" field of a UUID which
- does not employ an IEEE 802 address. WebDAV servers MAY use this
- algorithm for creating the node field when generating UUIDs. The
- text in this section is originally from an Internet-Draft by Paul
- Leach and Rich Salz, who are noted here to properly attribute their
- work.
-
- The ideal solution is to obtain a 47 bit cryptographic quality random
- number, and use it as the low 47 bits of the node ID, with the most
- significant bit of the first octet of the node ID set to 1. This bit
- is the unicast/multicast bit, which will never be set in IEEE 802
- addresses obtained from network cards; hence, there can never be a
- conflict between UUIDs generated by machines with and without network
- cards.
-
- If a system does not have a primitive to generate cryptographic
- quality random numbers, then in most systems there are usually a
- fairly large number of sources of randomness available from which one
- can be generated. Such sources are system specific, but often
- include:
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 17]
-
-RFC 2518 WEBDAV February 1999
-
-
- - the percent of memory in use
- - the size of main memory in bytes
- - the amount of free main memory in bytes
- - the size of the paging or swap file in bytes
- - free bytes of paging or swap file
- - the total size of user virtual address space in bytes
- - the total available user address space bytes
- - the size of boot disk drive in bytes
- - the free disk space on boot drive in bytes
- - the current time
- - the amount of time since the system booted
- - the individual sizes of files in various system directories
- - the creation, last read, and modification times of files in
- various system directories
- - the utilization factors of various system resources (heap, etc.)
- - current mouse cursor position
- - current caret position
- - current number of running processes, threads
- - handles or IDs of the desktop window and the active window
- - the value of stack pointer of the caller
- - the process and thread ID of caller
- - various processor architecture specific performance counters
- (instructions executed, cache misses, TLB misses)
-
- (Note that it is precisely the above kinds of sources of randomness
- that are used to seed cryptographic quality random number generators
- on systems without special hardware for their construction.)
-
- In addition, items such as the computer's name and the name of the
- operating system, while not strictly speaking random, will help
- differentiate the results from those obtained by other systems.
-
- The exact algorithm to generate a node ID using these data is system
- specific, because both the data available and the functions to obtain
- them are often very system specific. However, assuming that one can
- concatenate all the values from the randomness sources into a buffer,
- and that a cryptographic hash function such as MD5 is available, then
- any 6 bytes of the MD5 hash of the buffer, with the multicast bit
- (the high bit of the first byte) set will be an appropriately random
- node ID.
-
- Other hash functions, such as SHA-1, can also be used. The only
- requirement is that the result be suitably random _ in the sense that
- the outputs from a set uniformly distributed inputs are themselves
- uniformly distributed, and that a single bit change in the input can
- be expected to cause half of the output bits to change.
-
-
-
-
-
-Goland, et al. Standards Track [Page 18]
-
-RFC 2518 WEBDAV February 1999
-
-
-6.5 Lock Capability Discovery
-
- Since server lock support is optional, a client trying to lock a
- resource on a server can either try the lock and hope for the best,
- or perform some form of discovery to determine what lock capabilities
- the server supports. This is known as lock capability discovery.
- Lock capability discovery differs from discovery of supported access
- control types, since there may be access control types without
- corresponding lock types. A client can determine what lock types the
- server supports by retrieving the supportedlock property.
-
- Any DAV compliant resource that supports the LOCK method MUST support
- the supportedlock property.
-
-6.6 Active Lock Discovery
-
- If another principal locks a resource that a principal wishes to
- access, it is useful for the second principal to be able to find out
- who the first principal is. For this purpose the lockdiscovery
- property is provided. This property lists all outstanding locks,
- describes their type, and where available, provides their lock token.
-
- Any DAV compliant resource that supports the LOCK method MUST support
- the lockdiscovery property.
-
-6.7 Usage Considerations
-
- Although the locking mechanisms specified here provide some help in
- preventing lost updates, they cannot guarantee that updates will
- never be lost. Consider the following scenario:
-
- Two clients A and B are interested in editing the resource '
- index.html'. Client A is an HTTP client rather than a WebDAV client,
- and so does not know how to perform locking.
- Client A doesn't lock the document, but does a GET and begins
- editing.
- Client B does LOCK, performs a GET and begins editing.
- Client B finishes editing, performs a PUT, then an UNLOCK.
- Client A performs a PUT, overwriting and losing all of B's changes.
-
- There are several reasons why the WebDAV protocol itself cannot
- prevent this situation. First, it cannot force all clients to use
- locking because it must be compatible with HTTP clients that do not
- comprehend locking. Second, it cannot require servers to support
- locking because of the variety of repository implementations, some of
- which rely on reservations and merging rather than on locking.
- Finally, being stateless, it cannot enforce a sequence of operations
- like LOCK / GET / PUT / UNLOCK.
-
-
-
-Goland, et al. Standards Track [Page 19]
-
-RFC 2518 WEBDAV February 1999
-
-
- WebDAV servers that support locking can reduce the likelihood that
- clients will accidentally overwrite each other's changes by requiring
- clients to lock resources before modifying them. Such servers would
- effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
- resources.
-
- WebDAV clients can be good citizens by using a lock / retrieve /
- write /unlock sequence of operations (at least by default) whenever
- they interact with a WebDAV server that supports locking.
-
- HTTP 1.1 clients can be good citizens, avoiding overwriting other
- clients' changes, by using entity tags in If-Match headers with any
- requests that would modify resources.
-
- Information managers may attempt to prevent overwrites by
- implementing client-side procedures requiring locking before
- modifying WebDAV resources.
-
-7 Write Lock
-
- This section describes the semantics specific to the write lock type.
- The write lock is a specific instance of a lock type, and is the only
- lock type described in this specification.
-
-7.1 Methods Restricted by Write Locks
-
- A write lock MUST prevent a principal without the lock from
- successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE,
- DELETE, or MKCOL on the locked resource. All other current methods,
- GET in particular, function independently of the lock.
-
- Note, however, that as new methods are created it will be necessary
- to specify how they interact with a write lock.
-
-7.2 Write Locks and Lock Tokens
-
- A successful request for an exclusive or shared write lock MUST
- result in the generation of a unique lock token associated with the
- requesting principal. Thus if five principals have a shared write
- lock on the same resource there will be five lock tokens, one for
- each principal.
-
-7.3 Write Locks and Properties
-
- While those without a write lock may not alter a property on a
- resource it is still possible for the values of live properties to
- change, even while locked, due to the requirements of their schemas.
-
-
-
-
-Goland, et al. Standards Track [Page 20]
-
-RFC 2518 WEBDAV February 1999
-
-
- Only dead properties and live properties defined to respect locks are
- guaranteed not to change while write locked.
-
-7.4 Write Locks and Null Resources
-
- It is possible to assert a write lock on a null resource in order to
- lock the name.
-
- A write locked null resource, referred to as a lock-null resource,
- MUST respond with a 404 (Not Found) or 405 (Method Not Allowed) to
- any HTTP/1.1 or DAV methods except for PUT, MKCOL, OPTIONS, PROPFIND,
- LOCK, and UNLOCK. A lock-null resource MUST appear as a member of
- its parent collection. Additionally the lock-null resource MUST have
- defined on it all mandatory DAV properties. Most of these
- properties, such as all the get* properties, will have no value as a
- lock-null resource does not support the GET method. Lock-Null
- resources MUST have defined values for lockdiscovery and
- supportedlock properties.
-
- Until a method such as PUT or MKCOL is successfully executed on the
- lock-null resource the resource MUST stay in the lock-null state.
- However, once a PUT or MKCOL is successfully executed on a lock-null
- resource the resource ceases to be in the lock-null state.
-
- If the resource is unlocked, for any reason, without a PUT, MKCOL, or
- similar method having been successfully executed upon it then the
- resource MUST return to the null state.
-
-7.5 Write Locks and Collections
-
- A write lock on a collection, whether created by a "Depth: 0" or
- "Depth: infinity" lock request, prevents the addition or removal of
- member URIs of the collection by non-lock owners. As a consequence,
- when a principal issues a PUT or POST request to create a new
- resource under a URI which needs to be an internal member of a write
- locked collection to maintain HTTP namespace consistency, or issues a
- DELETE to remove a resource which has a URI which is an existing
- internal member URI of a write locked collection, this request MUST
- fail if the principal does not have a write lock on the collection.
-
- However, if a write lock request is issued to a collection containing
- member URIs identifying resources that are currently locked in a
- manner which conflicts with the write lock, the request MUST fail
- with a 423 (Locked) status code.
-
- If a lock owner causes the URI of a resource to be added as an
- internal member URI of a locked collection then the new resource MUST
- be automatically added to the lock. This is the only mechanism that
-
-
-
-Goland, et al. Standards Track [Page 21]
-
-RFC 2518 WEBDAV February 1999
-
-
- allows a resource to be added to a write lock. Thus, for example, if
- the collection /a/b/ is write locked and the resource /c is moved to
- /a/b/c then resource /a/b/c will be added to the write lock.
-
-7.6 Write Locks and the If Request Header
-
- If a user agent is not required to have knowledge about a lock when
- requesting an operation on a locked resource, the following scenario
- might occur. Program A, run by User A, takes out a write lock on a
- resource. Program B, also run by User A, has no knowledge of the
- lock taken out by Program A, yet performs a PUT to the locked
- resource. In this scenario, the PUT succeeds because locks are
- associated with a principal, not a program, and thus program B,
- because it is acting with principal A's credential, is allowed to
- perform the PUT. However, had program B known about the lock, it
- would not have overwritten the resource, preferring instead to
- present a dialog box describing the conflict to the user. Due to
- this scenario, a mechanism is needed to prevent different programs
- from accidentally ignoring locks taken out by other programs with the
- same authorization.
-
- In order to prevent these collisions a lock token MUST be submitted
- by an authorized principal in the If header for all locked resources
- that a method may interact with or the method MUST fail. For
- example, if a resource is to be moved and both the source and
- destination are locked then two lock tokens must be submitted, one
- for the source and the other for the destination.
-
-7.6.1 Example - Write Lock
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.ics.uci.edu
- Destination: http://www.ics.uci.edu/users/f/fielding/index.html
- If: <http://www.ics.uci.edu/users/f/fielding/index.html>
- (<opaquelocktoken:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, even though both the source and destination are
- locked, only one lock token must be submitted, for the lock on the
- destination. This is because the source resource is not modified by
- a COPY, and hence unaffected by the write lock. In this example, user
- agent authentication has previously occurred via a mechanism outside
- the scope of the HTTP protocol, in the underlying transport layer.
-
-
-
-Goland, et al. Standards Track [Page 22]
-
-RFC 2518 WEBDAV February 1999
-
-
-7.7 Write Locks and COPY/MOVE
-
- A COPY method invocation MUST NOT duplicate any write locks active on
- the source. However, as previously noted, if the COPY copies the
- resource into a collection that is locked with "Depth: infinity",
- then the resource will be added to the lock.
-
- A successful MOVE request on a write locked resource MUST NOT move
- the write lock with the resource. However, the resource is subject to
- being added to an existing lock at the destination, as specified in
- section 7.5. For example, if the MOVE makes the resource a child of a
- collection that is locked with "Depth: infinity", then the resource
- will be added to that collection's lock. Additionally, if a resource
- locked with "Depth: infinity" is moved to a destination that is
- within the scope of the same lock (e.g., within the namespace tree
- covered by the lock), the moved resource will again be a added to the
- lock. In both these examples, as specified in section 7.6, an If
- header must be submitted containing a lock token for both the source
- and destination.
-
-7.8 Refreshing Write Locks
-
- A client MUST NOT submit the same write lock request twice. Note
- that a client is always aware it is resubmitting the same lock
- request because it must include the lock token in the If header in
- order to make the request for a resource that is already locked.
-
- However, a client may submit a LOCK method with an If header but
- without a body. This form of LOCK MUST only be used to "refresh" a
- lock. Meaning, at minimum, that any timers associated with the lock
- MUST be re-set.
-
- A server may return a Timeout header with a lock refresh that is
- different than the Timeout header returned when the lock was
- originally requested. Additionally clients may submit Timeout
- headers of arbitrary value with their lock refresh requests.
- Servers, as always, may ignore Timeout headers submitted by the
- client.
-
- If an error is received in response to a refresh LOCK request the
- client SHOULD assume that the lock was not refreshed.
-
-8 HTTP Methods for Distributed Authoring
-
- The following new HTTP methods use XML as a request and response
- format. All DAV compliant clients and resources MUST use XML parsers
- that are compliant with [REC-XML]. All XML used in either requests
- or responses MUST be, at minimum, well formed. If a server receives
-
-
-
-Goland, et al. Standards Track [Page 23]
-
-RFC 2518 WEBDAV February 1999
-
-
- ill-formed XML in a request it MUST reject the entire request with a
- 400 (Bad Request). If a client receives ill-formed XML in a response
- then it MUST NOT assume anything about the outcome of the executed
- method and SHOULD treat the server as malfunctioning.
-
-8.1 PROPFIND
-
- The PROPFIND method retrieves properties defined on the resource
- identified by the Request-URI, if the resource does not have any
- internal members, or on the resource identified by the Request-URI
- and potentially its member resources, if the resource is a collection
- that has internal member URIs. All DAV compliant resources MUST
- support the PROPFIND method and the propfind XML element (section
- 12.14) along with all XML elements defined for use with that element.
-
- A client may submit a Depth header with a value of "0", "1", or
- "infinity" with a PROPFIND on a collection resource with internal
- member URIs. DAV compliant servers MUST support the "0", "1" and
- "infinity" behaviors. By default, the PROPFIND method without a Depth
- header MUST act as if a "Depth: infinity" header was included.
-
- A client may submit a propfind XML element in the body of the request
- method describing what information is being requested. It is
- possible to request particular property values, all property values,
- or a list of the names of the resource's properties. A client may
- choose not to submit a request body. An empty PROPFIND request body
- MUST be treated as a request for the names and values of all
- properties.
-
- All servers MUST support returning a response of content type
- text/xml or application/xml that contains a multistatus XML element
- that describes the results of the attempts to retrieve the various
- properties.
-
- If there is an error retrieving a property then a proper error result
- MUST be included in the response. A request to retrieve the value of
- a property which does not exist is an error and MUST be noted, if the
- response uses a multistatus XML element, with a response XML element
- which contains a 404 (Not Found) status value.
-
- Consequently, the multistatus XML element for a collection resource
- with member URIs MUST include a response XML element for each member
- URI of the collection, to whatever depth was requested. Each response
- XML element MUST contain an href XML element that gives the URI of
- the resource on which the properties in the prop XML element are
- defined. Results for a PROPFIND on a collection resource with
- internal member URIs are returned as a flat list whose order of
- entries is not significant.
-
-
-
-Goland, et al. Standards Track [Page 24]
-
-RFC 2518 WEBDAV February 1999
-
-
- In the case of allprop and propname, if a principal does not have the
- right to know whether a particular property exists then the property
- should be silently excluded from the response.
-
- The results of this method SHOULD NOT be cached.
-
-8.1.1 Example - Retrieving Named Properties
-
- >>Request
-
- PROPFIND /file HTTP/1.1
- Host: www.foo.bar
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox/>
- <R:author/>
- <R:DingALing/>
- <R:Random/>
- </D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.foo.bar/file</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox>
- <R:BoxType>Box type A</R:BoxType>
- </R:bigbox>
- <R:author>
- <R:Name>J.J. Johnson</R:Name>
- </R:author>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><R:DingALing/><R:Random/></D:prop>
-
-
-
-Goland, et al. Standards Track [Page 25]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- <D:responsedescription> The user does not have access to
- the DingALing property.
- </D:responsedescription>
- </D:propstat>
- </D:response>
- <D:responsedescription> There has been an access violation error.
- </D:responsedescription>
- </D:multistatus>
-
- In this example, PROPFIND is executed on a non-collection resource
- http://www.foo.bar/file. The propfind XML element specifies the name
- of four properties whose values are being requested. In this case
- only two properties were returned, since the principal issuing the
- request did not have sufficient access rights to see the third and
- fourth properties.
-
-8.1.2 Example - Using allprop to Retrieve All Properties
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.foo.bar
- Depth: 1
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.foo.bar/container/</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox>
- <R:BoxType>Box type A</R:BoxType>
- </R:bigbox>
- <R:author>
-
-
-
-Goland, et al. Standards Track [Page 26]
-
-RFC 2518 WEBDAV February 1999
-
-
- <R:Name>Hadrian</R:Name>
- </R:author>
- <D:creationdate>
- 1997-12-01T17:42:21-08:00
- </D:creationdate>
- <D:displayname>
- Example collection
- </D:displayname>
- <D:resourcetype><D:collection/></D:resourcetype>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://www.foo.bar/container/front.html</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox>
- <R:BoxType>Box type B</R:BoxType>
- </R:bigbox>
- <D:creationdate>
- 1997-12-01T18:27:21-08:00
- </D:creationdate>
- <D:displayname>
- Example HTML resource
- </D:displayname>
- <D:getcontentlength>
- 4525
- </D:getcontentlength>
- <D:getcontenttype>
- text/html
- </D:getcontenttype>
- <D:getetag>
- zzyzx
- </D:getetag>
- <D:getlastmodified>
- Monday, 12-Jan-98 09:25:56 GMT
- </D:getlastmodified>
-
-
-
-Goland, et al. Standards Track [Page 27]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:resourcetype/>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- In this example, PROPFIND was invoked on the resource
- http://www.foo.bar/container/ with a Depth header of 1, meaning the
- request applies to the resource and its children, and a propfind XML
- element containing the allprop XML element, meaning the request
- should return the name and value of all properties defined on each
- resource.
-
- The resource http://www.foo.bar/container/ has six properties defined
- on it:
-
- http://www.foo.bar/boxschema/bigbox,
- http://www.foo.bar/boxschema/author, DAV:creationdate,
- DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
-
- The last four properties are WebDAV-specific, defined in section 13.
- Since GET is not supported on this resource, the get* properties
- (e.g., getcontentlength) are not defined on this resource. The DAV-
- specific properties assert that "container" was created on December
- 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
- (creationdate), has a name of "Example collection" (displayname), a
- collection resource type (resourcetype), and supports exclusive write
- and shared write locks (supportedlock).
-
- The resource http://www.foo.bar/container/front.html has nine
- properties defined on it:
-
- http://www.foo.bar/boxschema/bigbox (another instance of the "bigbox"
- property type), DAV:creationdate, DAV:displayname,
- DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
- DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
-
-
-
-
-Goland, et al. Standards Track [Page 28]
-
-RFC 2518 WEBDAV February 1999
-
-
- The DAV-specific properties assert that "front.html" was created on
- December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
- (creationdate), has a name of "Example HTML resource" (displayname),
- a content length of 4525 bytes (getcontentlength), a MIME type of
- "text/html" (getcontenttype), an entity tag of "zzyzx" (getetag), was
- last modified on Monday, January 12, 1998, at 09:25:56 GMT
- (getlastmodified), has an empty resource type, meaning that it is not
- a collection (resourcetype), and supports both exclusive write and
- shared write locks (supportedlock).
-
-8.1.3 Example - Using propname to Retrieve all Property Names
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.foo.bar
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <propfind xmlns="DAV:">
- <propname/>
- </propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <multistatus xmlns="DAV:">
- <response>
- <href>http://www.foo.bar/container/</href>
- <propstat>
- <prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox/>
- <R:author/>
- <creationdate/>
- <displayname/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
- </propstat>
- </response>
- <response>
- <href>http://www.foo.bar/container/front.html</href>
-
-
-
-Goland, et al. Standards Track [Page 29]
-
-RFC 2518 WEBDAV February 1999
-
-
- <propstat>
- <prop xmlns:R="http://www.foo.bar/boxschema/">
- <R:bigbox/>
- <creationdate/>
- <displayname/>
- <getcontentlength/>
- <getcontenttype/>
- <getetag/>
- <getlastmodified/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
- </propstat>
- </response>
- </multistatus>
-
-
- In this example, PROPFIND is invoked on the collection resource
- http://www.foo.bar/container/, with a propfind XML element containing
- the propname XML element, meaning the name of all properties should
- be returned. Since no Depth header is present, it assumes its
- default value of "infinity", meaning the name of the properties on
- the collection and all its progeny should be returned.
-
- Consistent with the previous example, resource
- http://www.foo.bar/container/ has six properties defined on it,
- http://www.foo.bar/boxschema/bigbox,
- http://www.foo.bar/boxschema/author, DAV:creationdate,
- DAV:displayname, DAV:resourcetype, and DAV:supportedlock.
-
- The resource http://www.foo.bar/container/index.html, a member of the
- "container" collection, has nine properties defined on it,
- http://www.foo.bar/boxschema/bigbox, DAV:creationdate,
- DAV:displayname, DAV:getcontentlength, DAV:getcontenttype,
- DAV:getetag, DAV:getlastmodified, DAV:resourcetype, and
- DAV:supportedlock.
-
- This example also demonstrates the use of XML namespace scoping, and
- the default namespace. Since the "xmlns" attribute does not contain
- an explicit "shorthand name" (prefix) letter, the namespace applies
- by default to all enclosed elements. Hence, all elements which do
- not explicitly state the namespace to which they belong are members
- of the "DAV:" namespace schema.
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 30]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.2 PROPPATCH
-
- The PROPPATCH method processes instructions specified in the request
- body to set and/or remove properties defined on the resource
- identified by the Request-URI.
-
- All DAV compliant resources MUST support the PROPPATCH method and
- MUST process instructions that are specified using the
- propertyupdate, set, and remove XML elements of the DAV schema.
- Execution of the directives in this method is, of course, subject to
- access control constraints. DAV compliant resources SHOULD support
- the setting of arbitrary dead properties.
-
- The request message body of a PROPPATCH method MUST contain the
- propertyupdate XML element. Instruction processing MUST occur in the
- order instructions are received (i.e., from top to bottom).
- Instructions MUST either all be executed or none executed. Thus if
- any error occurs during processing all executed instructions MUST be
- undone and a proper error result returned. Instruction processing
- details can be found in the definition of the set and remove
- instructions in section 12.13.
-
-8.2.1 Status Codes for use with 207 (Multi-Status)
-
- The following are examples of response codes one would expect to be
- used in a 207 (Multi-Status) response for this method. Note,
- however, that unless explicitly prohibited any 2/3/4/5xx series
- response code may be used in a 207 (Multi-Status) response.
-
- 200 (OK) - The command succeeded. As there can be a mixture of sets
- and removes in a body, a 201 (Created) seems inappropriate.
-
- 403 (Forbidden) - The client, for reasons the server chooses not to
- specify, cannot alter one of the properties.
-
- 409 (Conflict) - The client has provided a value whose semantics are
- not appropriate for the property. This includes trying to set read-
- only properties.
-
- 423 (Locked) - The specified resource is locked and the client either
- is not a lock owner or the lock type requires a lock token to be
- submitted and the client did not submit it.
-
- 507 (Insufficient Storage) - The server did not have sufficient space
- to record the property.
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 31]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.2.2 Example - PROPPATCH
-
- >>Request
-
- PROPPATCH /bar.html HTTP/1.1
- Host: www.foo.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propertyupdate xmlns:D="DAV:"
- xmlns:Z="http://www.w3.com/standards/z39.50/">
- <D:set>
- <D:prop>
- <Z:authors>
- <Z:Author>Jim Whitehead</Z:Author>
- <Z:Author>Roy Fielding</Z:Author>
- </Z:authors>
- </D:prop>
- </D:set>
- <D:remove>
- <D:prop><Z:Copyright-Owner/></D:prop>
- </D:remove>
- </D:propertyupdate>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:Z="http://www.w3.com/standards/z39.50">
- <D:response>
- <D:href>http://www.foo.com/bar.html</D:href>
- <D:propstat>
- <D:prop><Z:Authors/></D:prop>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><Z:Copyright-Owner/></D:prop>
- <D:status>HTTP/1.1 409 Conflict</D:status>
- </D:propstat>
- <D:responsedescription> Copyright Owner can not be deleted or
- altered.</D:responsedescription>
- </D:response>
- </D:multistatus>
-
-
-
-Goland, et al. Standards Track [Page 32]
-
-RFC 2518 WEBDAV February 1999
-
-
- In this example, the client requests the server to set the value of
- the http://www.w3.com/standards/z39.50/Authors property, and to
- remove the property http://www.w3.com/standards/z39.50/Copyright-
- Owner. Since the Copyright-Owner property could not be removed, no
- property modifications occur. The 424 (Failed Dependency) status
- code for the Authors property indicates this action would have
- succeeded if it were not for the conflict with removing the
- Copyright-Owner property.
-
-8.3 MKCOL Method
-
- The MKCOL method is used to create a new collection. All DAV
- compliant resources MUST support the MKCOL method.
-
-8.3.1 Request
-
- MKCOL creates a new collection resource at the location specified by
- the Request-URI. If the resource identified by the Request-URI is
- non-null then the MKCOL MUST fail. During MKCOL processing, a server
- MUST make the Request-URI a member of its parent collection, unless
- the Request-URI is "/". If no such ancestor exists, the method MUST
- fail. When the MKCOL operation creates a new collection resource,
- all ancestors MUST already exist, or the method MUST fail with a 409
- (Conflict) status code. For example, if a request to create
- collection /a/b/c/d/ is made, and neither /a/b/ nor /a/b/c/ exists,
- the request must fail.
-
- When MKCOL is invoked without a request body, the newly created
- collection SHOULD have no members.
-
- A MKCOL request message may contain a message body. The behavior of
- a MKCOL request when the body is present is limited to creating
- collections, members of a collection, bodies of members and
- properties on the collections or members. If the server receives a
- MKCOL request entity type it does not support or understand it MUST
- respond with a 415 (Unsupported Media Type) status code. The exact
- behavior of MKCOL for various request media types is undefined in
- this document, and will be specified in separate documents.
-
-8.3.2 Status Codes
-
- Responses from a MKCOL request MUST NOT be cached as MKCOL has non-
- idempotent semantics.
-
- 201 (Created) - The collection or structured resource was created in
- its entirety.
-
-
-
-
-
-Goland, et al. Standards Track [Page 33]
-
-RFC 2518 WEBDAV February 1999
-
-
- 403 (Forbidden) - This indicates at least one of two conditions: 1)
- the server does not allow the creation of collections at the given
- location in its namespace, or 2) the parent collection of the
- Request-URI exists but cannot accept members.
-
- 405 (Method Not Allowed) - MKCOL can only be executed on a
- deleted/non-existent resource.
-
- 409 (Conflict) - A collection cannot be made at the Request-URI until
- one or more intermediate collections have been created.
-
- 415 (Unsupported Media Type)- The server does not support the request
- type of the body.
-
- 507 (Insufficient Storage) - The resource does not have sufficient
- space to record the state of the resource after the execution of this
- method.
-
-8.3.3 Example - MKCOL
-
- This example creates a collection called /webdisc/xfiles/ on the
- server www.server.org.
-
- >>Request
-
- MKCOL /webdisc/xfiles/ HTTP/1.1
- Host: www.server.org
-
- >>Response
-
- HTTP/1.1 201 Created
-
-8.4 GET, HEAD for Collections
-
- The semantics of GET are unchanged when applied to a collection,
- since GET is defined as, "retrieve whatever information (in the form
- of an entity) is identified by the Request-URI" [RFC2068]. GET when
- applied to a collection may return the contents of an "index.html"
- resource, a human-readable view of the contents of the collection, or
- something else altogether. Hence it is possible that the result of a
- GET on a collection will bear no correlation to the membership of the
- collection.
-
- Similarly, since the definition of HEAD is a GET without a response
- message body, the semantics of HEAD are unmodified when applied to
- collection resources.
-
-
-
-
-
-Goland, et al. Standards Track [Page 34]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.5 POST for Collections
-
- Since by definition the actual function performed by POST is
- determined by the server and often depends on the particular
- resource, the behavior of POST when applied to collections cannot be
- meaningfully modified because it is largely undefined. Thus the
- semantics of POST are unmodified when applied to a collection.
-
-8.6 DELETE
-
- 8.6.1 DELETE for Non-Collection Resources
-
- If the DELETE method is issued to a non-collection resource whose
- URIs are an internal member of one or more collections, then during
- DELETE processing a server MUST remove any URI for the resource
- identified by the Request-URI from collections which contain it as a
- member.
-
-8.6.2 DELETE for Collections
-
- The DELETE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header with
- a DELETE on a collection with any value but infinity.
-
- DELETE instructs that the collection specified in the Request-URI and
- all resources identified by its internal member URIs are to be
- deleted.
-
- If any resource identified by a member URI cannot be deleted then all
- of the member's ancestors MUST NOT be deleted, so as to maintain
- namespace consistency.
-
- Any headers included with DELETE MUST be applied in processing every
- resource to be deleted.
-
- When the DELETE method has completed processing it MUST result in a
- consistent namespace.
-
- If an error occurs with a resource other than the resource identified
- in the Request-URI then the response MUST be a 207 (Multi-Status).
- 424 (Failed Dependency) errors SHOULD NOT be in the 207 (Multi-
- Status). They can be safely left out because the client will know
- that the ancestors of a resource could not be deleted when the client
- receives an error for the ancestor's progeny. Additionally 204 (No
- Content) errors SHOULD NOT be returned in the 207 (Multi-Status).
- The reason for this prohibition is that 204 (No Content) is the
- default success code.
-
-
-
-
-Goland, et al. Standards Track [Page 35]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.6.2.1 Example - DELETE
-
- >>Request
-
- DELETE /container/ HTTP/1.1
- Host: www.foo.bar
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.foo.bar/container/resource3</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- </d:response>
- </d:multistatus>
-
- In this example the attempt to delete
- http://www.foo.bar/container/resource3 failed because it is locked,
- and no lock token was submitted with the request. Consequently, the
- attempt to delete http://www.foo.bar/container/ also failed. Thus the
- client knows that the attempt to delete http://www.foo.bar/container/
- must have also failed since the parent can not be deleted unless its
- child has also been deleted. Even though a Depth header has not been
- included, a depth of infinity is assumed because the method is on a
- collection.
-
-8.7 PUT
-
-8.7.1 PUT for Non-Collection Resources
-
- A PUT performed on an existing resource replaces the GET response
- entity of the resource. Properties defined on the resource may be
- recomputed during PUT processing but are not otherwise affected. For
- example, if a server recognizes the content type of the request body,
- it may be able to automatically extract information that could be
- profitably exposed as properties.
-
- A PUT that would result in the creation of a resource without an
- appropriately scoped parent collection MUST fail with a 409
- (Conflict).
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 36]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.7.2 PUT for Collections
-
- As defined in the HTTP/1.1 specification [RFC2068], the "PUT method
- requests that the enclosed entity be stored under the supplied
- Request-URI." Since submission of an entity representing a
- collection would implicitly encode creation and deletion of
- resources, this specification intentionally does not define a
- transmission format for creating a collection using PUT. Instead,
- the MKCOL method is defined to create collections.
-
- When the PUT operation creates a new non-collection resource all
- ancestors MUST already exist. If all ancestors do not exist, the
- method MUST fail with a 409 (Conflict) status code. For example, if
- resource /a/b/c/d.html is to be created and /a/b/c/ does not exist,
- then the request must fail.
-
-8.8 COPY Method
-
- The COPY method creates a duplicate of the source resource,
- identified by the Request-URI, in the destination resource,
- identified by the URI in the Destination header. The Destination
- header MUST be present. The exact behavior of the COPY method
- depends on the type of the source resource.
-
- All WebDAV compliant resources MUST support the COPY method.
- However, support for the COPY method does not guarantee the ability
- to copy a resource. For example, separate programs may control
- resources on the same server. As a result, it may not be possible to
- copy a resource to a location that appears to be on the same server.
-
-8.8.1 COPY for HTTP/1.1 resources
-
- When the source resource is not a collection the result of the COPY
- method is the creation of a new resource at the destination whose
- state and behavior match that of the source resource as closely as
- possible. After a successful COPY invocation, all properties on the
- source resource MUST be duplicated on the destination resource,
- subject to modifying headers and XML elements, following the
- definition for copying properties. Since the environment at the
- destination may be different than at the source due to factors
- outside the scope of control of the server, such as the absence of
- resources required for correct operation, it may not be possible to
- completely duplicate the behavior of the resource at the destination.
- Subsequent alterations to the destination resource will not modify
- the source resource. Subsequent alterations to the source resource
- will not modify the destination resource.
-
-
-
-
-
-Goland, et al. Standards Track [Page 37]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.8.2. COPY for Properties
-
- The following section defines how properties on a resource are
- handled during a COPY operation.
-
- Live properties SHOULD be duplicated as identically behaving live
- properties at the destination resource. If a property cannot be
- copied live, then its value MUST be duplicated, octet-for-octet, in
- an identically named, dead property on the destination resource
- subject to the effects of the propertybehavior XML element.
-
- The propertybehavior XML element can specify that properties are
- copied on best effort, that all live properties must be successfully
- copied or the method must fail, or that a specified list of live
- properties must be successfully copied or the method must fail. The
- propertybehavior XML element is defined in section 12.12.
-
-8.8.3 COPY for Collections
-
- The COPY method on a collection without a Depth header MUST act as if
- a Depth header with value "infinity" was included. A client may
- submit a Depth header on a COPY on a collection with a value of "0"
- or "infinity". DAV compliant servers MUST support the "0" and
- "infinity" Depth header behaviors.
-
- A COPY of depth infinity instructs that the collection resource
- identified by the Request-URI is to be copied to the location
- identified by the URI in the Destination header, and all its internal
- member resources are to be copied to a location relative to it,
- recursively through all levels of the collection hierarchy.
-
- A COPY of "Depth: 0" only instructs that the collection and its
- properties but not resources identified by its internal member URIs,
- are to be copied.
-
- Any headers included with a COPY MUST be applied in processing every
- resource to be copied with the exception of the Destination header.
-
- The Destination header only specifies the destination URI for the
- Request-URI. When applied to members of the collection identified by
- the Request-URI the value of Destination is to be modified to reflect
- the current location in the hierarchy. So, if the Request- URI is
- /a/ with Host header value http://fun.com/ and the Destination is
- http://fun.com/b/ then when http://fun.com/a/c/d is processed it must
- use a Destination of http://fun.com/b/c/d.
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 38]
-
-RFC 2518 WEBDAV February 1999
-
-
- When the COPY method has completed processing it MUST have created a
- consistent namespace at the destination (see section 5.1 for the
- definition of namespace consistency). However, if an error occurs
- while copying an internal collection, the server MUST NOT copy any
- resources identified by members of this collection (i.e., the server
- must skip this subtree), as this would create an inconsistent
- namespace. After detecting an error, the COPY operation SHOULD try to
- finish as much of the original copy operation as possible (i.e., the
- server should still attempt to copy other subtrees and their members,
- that are not descendents of an error-causing collection). So, for
- example, if an infinite depth copy operation is performed on
- collection /a/, which contains collections /a/b/ and /a/c/, and an
- error occurs copying /a/b/, an attempt should still be made to copy
- /a/c/. Similarly, after encountering an error copying a non-
- collection resource as part of an infinite depth copy, the server
- SHOULD try to finish as much of the original copy operation as
- possible.
-
- If an error in executing the COPY method occurs with a resource other
- than the resource identified in the Request-URI then the response
- MUST be a 207 (Multi-Status).
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a COPY method. These responses can
- be safely omitted because the client will know that the progeny of a
- resource could not be copied when the client receives an error for
- the parent. Additionally 201 (Created)/204 (No Content) status codes
- SHOULD NOT be returned as values in 207 (Multi-Status) responses from
- COPY methods. They, too, can be safely omitted because they are the
- default success codes.
-
-8.8.4 COPY and the Overwrite Header
-
- If a resource exists at the destination and the Overwrite header is
- "T" then prior to performing the copy the server MUST perform a
- DELETE with "Depth: infinity" on the destination resource. If the
- Overwrite header is set to "F" then the operation will fail.
-
-8.8.5 Status Codes
-
- 201 (Created) - The source resource was successfully copied. The
- copy operation resulted in the creation of a new resource.
-
- 204 (No Content) - The source resource was successfully copied to a
- pre-existing destination resource.
-
- 403 (Forbidden) _ The source and destination URIs are the same.
-
-
-
-
-Goland, et al. Standards Track [Page 39]
-
-RFC 2518 WEBDAV February 1999
-
-
- 409 (Conflict) _ A resource cannot be created at the destination
- until one or more intermediate collections have been created.
-
- 412 (Precondition Failed) - The server was unable to maintain the
- liveness of the properties listed in the propertybehavior XML element
- or the Overwrite header is "F" and the state of the destination
- resource is non-null.
-
- 423 (Locked) - The destination resource was locked.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server and the destination server refuses to accept the resource.
-
- 507 (Insufficient Storage) - The destination resource does not have
- sufficient space to record the state of the resource after the
- execution of this method.
-
-8.8.6 Example - COPY with Overwrite
-
- This example shows resource
- http://www.ics.uci.edu/~fielding/index.html being copied to the
- location http://www.ics.uci.edu/users/f/fielding/index.html. The 204
- (No Content) status code indicates the existing resource at the
- destination was overwritten.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.ics.uci.edu
- Destination: http://www.ics.uci.edu/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 204 No Content
-
-8.8.7 Example - COPY with No Overwrite
-
- The following example shows the same copy operation being performed,
- but with the Overwrite header set to "F." A response of 412
- (Precondition Failed) is returned because the destination resource
- has a non-null state.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.ics.uci.edu
- Destination: http://www.ics.uci.edu/users/f/fielding/index.html
- Overwrite: F
-
-
-
-Goland, et al. Standards Track [Page 40]
-
-RFC 2518 WEBDAV February 1999
-
-
- >>Response
-
- HTTP/1.1 412 Precondition Failed
-
-8.8.8 Example - COPY of a Collection
-
- >>Request
-
- COPY /container/ HTTP/1.1
- Host: www.foo.bar
- Destination: http://www.foo.bar/othercontainer/
- Depth: infinity
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:propertybehavior xmlns:d="DAV:">
- <d:keepalive>*</d:keepalive>
- </d:propertybehavior>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.foo.bar/othercontainer/R2/</d:href>
- <d:status>HTTP/1.1 412 Precondition Failed</d:status>
- </d:response>
- </d:multistatus>
-
- The Depth header is unnecessary as the default behavior of COPY on a
- collection is to act as if a "Depth: infinity" header had been
- submitted. In this example most of the resources, along with the
- collection, were copied successfully. However the collection R2
- failed, most likely due to a problem with maintaining the liveness of
- properties (this is specified by the propertybehavior XML element).
- Because there was an error copying R2, none of R2's members were
- copied. However no errors were listed for those members due to the
- error minimization rules given in section 8.8.3.
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 41]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.9 MOVE Method
-
- The MOVE operation on a non-collection resource is the logical
- equivalent of a copy (COPY), followed by consistency maintenance
- processing, followed by a delete of the source, where all three
- actions are performed atomically. The consistency maintenance step
- allows the server to perform updates caused by the move, such as
- updating all URIs other than the Request-URI which identify the
- source resource, to point to the new destination resource.
- Consequently, the Destination header MUST be present on all MOVE
- methods and MUST follow all COPY requirements for the COPY part of
- the MOVE method. All DAV compliant resources MUST support the MOVE
- method. However, support for the MOVE method does not guarantee the
- ability to move a resource to a particular destination.
-
- For example, separate programs may actually control different sets of
- resources on the same server. Therefore, it may not be possible to
- move a resource within a namespace that appears to belong to the same
- server.
-
- If a resource exists at the destination, the destination resource
- will be DELETEd as a side-effect of the MOVE operation, subject to
- the restrictions of the Overwrite header.
-
-8.9.1 MOVE for Properties
-
- The behavior of properties on a MOVE, including the effects of the
- propertybehavior XML element, MUST be the same as specified in
- section 8.8.2.
-
-8.9.2 MOVE for Collections
-
- A MOVE with "Depth: infinity" instructs that the collection
- identified by the Request-URI be moved to the URI specified in the
- Destination header, and all resources identified by its internal
- member URIs are to be moved to locations relative to it, recursively
- through all levels of the collection hierarchy.
-
- The MOVE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header on a
- MOVE on a collection with any value but "infinity".
-
- Any headers included with MOVE MUST be applied in processing every
- resource to be moved with the exception of the Destination header.
-
- The behavior of the Destination header is the same as given for COPY
- on collections.
-
-
-
-
-Goland, et al. Standards Track [Page 42]
-
-RFC 2518 WEBDAV February 1999
-
-
- When the MOVE method has completed processing it MUST have created a
- consistent namespace at both the source and destination (see section
- 5.1 for the definition of namespace consistency). However, if an
- error occurs while moving an internal collection, the server MUST NOT
- move any resources identified by members of the failed collection
- (i.e., the server must skip the error-causing subtree), as this would
- create an inconsistent namespace. In this case, after detecting the
- error, the move operation SHOULD try to finish as much of the
- original move as possible (i.e., the server should still attempt to
- move other subtrees and the resources identified by their members,
- that are not descendents of an error-causing collection). So, for
- example, if an infinite depth move is performed on collection /a/,
- which contains collections /a/b/ and /a/c/, and an error occurs
- moving /a/b/, an attempt should still be made to try moving /a/c/.
- Similarly, after encountering an error moving a non-collection
- resource as part of an infinite depth move, the server SHOULD try to
- finish as much of the original move operation as possible.
-
- If an error occurs with a resource other than the resource identified
- in the Request-URI then the response MUST be a 207 (Multi-Status).
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a MOVE method. These errors can be
- safely omitted because the client will know that the progeny of a
- resource could not be moved when the client receives an error for the
- parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
- NOT be returned as values in 207 (Multi-Status) responses from a
- MOVE. These responses can be safely omitted because they are the
- default success codes.
-
-8.9.3 MOVE and the Overwrite Header
-
- If a resource exists at the destination and the Overwrite header is
- "T" then prior to performing the move the server MUST perform a
- DELETE with "Depth: infinity" on the destination resource. If the
- Overwrite header is set to "F" then the operation will fail.
-
-8.9.4 Status Codes
-
- 201 (Created) - The source resource was successfully moved, and a new
- resource was created at the destination.
-
- 204 (No Content) - The source resource was successfully moved to a
- pre-existing destination resource.
-
- 403 (Forbidden) _ The source and destination URIs are the same.
-
-
-
-
-
-Goland, et al. Standards Track [Page 43]
-
-RFC 2518 WEBDAV February 1999
-
-
- 409 (Conflict) _ A resource cannot be created at the destination
- until one or more intermediate collections have been created.
-
- 412 (Precondition Failed) - The server was unable to maintain the
- liveness of the properties listed in the propertybehavior XML element
- or the Overwrite header is "F" and the state of the destination
- resource is non-null.
-
- 423 (Locked) - The source or the destination resource was locked.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server and the destination server refuses to accept the resource.
-
-8.9.5 Example - MOVE of a Non-Collection
-
- This example shows resource
- http://www.ics.uci.edu/~fielding/index.html being moved to the
- location http://www.ics.uci.edu/users/f/fielding/index.html. The
- contents of the destination resource would have been overwritten if
- the destination resource had been non-null. In this case, since
- there was nothing at the destination resource, the response code is
- 201 (Created).
-
- >>Request
-
- MOVE /~fielding/index.html HTTP/1.1
- Host: www.ics.uci.edu
- Destination: http://www.ics.uci.edu/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 201 Created
- Location: http://www.ics.uci.edu/users/f/fielding/index.html
-
-
-8.9.6 Example - MOVE of a Collection
-
- >>Request
-
- MOVE /container/ HTTP/1.1
- Host: www.foo.bar
- Destination: http://www.foo.bar/othercontainer/
- Overwrite: F
- If: (<opaquelocktoken:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
- (<opaquelocktoken:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
-
-
-
-Goland, et al. Standards Track [Page 44]
-
-RFC 2518 WEBDAV February 1999
-
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:propertybehavior xmlns:d='DAV:'>
- <d:keepalive>*</d:keepalive>
- </d:propertybehavior>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d='DAV:'>
- <d:response>
- <d:href>http://www.foo.bar/othercontainer/C2/</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- </d:response>
- </d:multistatus>
-
- In this example the client has submitted a number of lock tokens with
- the request. A lock token will need to be submitted for every
- resource, both source and destination, anywhere in the scope of the
- method, that is locked. In this case the proper lock token was not
- submitted for the destination http://www.foo.bar/othercontainer/C2/.
- This means that the resource /container/C2/ could not be moved.
- Because there was an error copying /container/C2/, none of
- /container/C2's members were copied. However no errors were listed
- for those members due to the error minimization rules given in
- section 8.8.3. User agent authentication has previously occurred via
- a mechanism outside the scope of the HTTP protocol, in an underlying
- transport layer.
-
-8.10 LOCK Method
-
- The following sections describe the LOCK method, which is used to
- take out a lock of any access type. These sections on the LOCK
- method describe only those semantics that are specific to the LOCK
- method and are independent of the access type of the lock being
- requested.
-
- Any resource which supports the LOCK method MUST, at minimum, support
- the XML request and response formats defined herein.
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 45]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.10.1 Operation
-
- A LOCK method invocation creates the lock specified by the lockinfo
- XML element on the Request-URI. Lock method requests SHOULD have a
- XML request body which contains an owner XML element for this lock
- request, unless this is a refresh request. The LOCK request may have
- a Timeout header.
-
- Clients MUST assume that locks may arbitrarily disappear at any time,
- regardless of the value given in the Timeout header. The Timeout
- header only indicates the behavior of the server if "extraordinary"
- circumstances do not occur. For example, an administrator may remove
- a lock at any time or the system may crash in such a way that it
- loses the record of the lock's existence. The response MUST contain
- the value of the lockdiscovery property in a prop XML element.
-
- In order to indicate the lock token associated with a newly created
- lock, a Lock-Token response header MUST be included in the response
- for every successful LOCK request for a new lock. Note that the
- Lock-Token header would not be returned in the response for a
- successful refresh LOCK request because a new lock was not created.
-
-8.10.2 The Effect of Locks on Properties and Collections
-
- The scope of a lock is the entire state of the resource, including
- its body and associated properties. As a result, a lock on a
- resource MUST also lock the resource's properties.
-
- For collections, a lock also affects the ability to add or remove
- members. The nature of the effect depends upon the type of access
- control involved.
-
-8.10.3 Locking Replicated Resources
-
- A resource may be made available through more than one URI. However
- locks apply to resources, not URIs. Therefore a LOCK request on a
- resource MUST NOT succeed if can not be honored by all the URIs
- through which the resource is addressable.
-
-8.10.4 Depth and Locking
-
- The Depth header may be used with the LOCK method. Values other than
- 0 or infinity MUST NOT be used with the Depth header on a LOCK
- method. All resources that support the LOCK method MUST support the
- Depth header.
-
- A Depth header of value 0 means to just lock the resource specified
- by the Request-URI.
-
-
-
-Goland, et al. Standards Track [Page 46]
-
-RFC 2518 WEBDAV February 1999
-
-
- If the Depth header is set to infinity then the resource specified in
- the Request-URI along with all its internal members, all the way down
- the hierarchy, are to be locked. A successful result MUST return a
- single lock token which represents all the resources that have been
- locked. If an UNLOCK is successfully executed on this token, all
- associated resources are unlocked. If the lock cannot be granted to
- all resources, a 409 (Conflict) status code MUST be returned with a
- response entity body containing a multistatus XML element describing
- which resource(s) prevented the lock from being granted. Hence,
- partial success is not an option. Either the entire hierarchy is
- locked or no resources are locked.
-
- If no Depth header is submitted on a LOCK request then the request
- MUST act as if a "Depth:infinity" had been submitted.
-
-8.10.5 Interaction with other Methods
-
- The interaction of a LOCK with various methods is dependent upon the
- lock type. However, independent of lock type, a successful DELETE of
- a resource MUST cause all of its locks to be removed.
-
-8.10.6 Lock Compatibility Table
-
- The table below describes the behavior that occurs when a lock
- request is made on a resource.
-
- Current lock state/ | Shared Lock | Exclusive
- Lock request | | Lock
- =====================+=================+==============
- None | True | True
- ---------------------+-----------------+--------------
- Shared Lock | True | False
- ---------------------+-----------------+--------------
- Exclusive Lock | False | False*
- ------------------------------------------------------
-
- Legend: True = lock may be granted. False = lock MUST NOT be
- granted. *=It is illegal for a principal to request the same lock
- twice.
-
- The current lock state of a resource is given in the leftmost column,
- and lock requests are listed in the first row. The intersection of a
- row and column gives the result of a lock request. For example, if a
- shared lock is held on a resource, and an exclusive lock is
- requested, the table entry is "false", indicating the lock must not
- be granted.
-
-
-
-
-
-Goland, et al. Standards Track [Page 47]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.10.7 Status Codes
-
- 200 (OK) - The lock request succeeded and the value of the
- lockdiscovery property is included in the body.
-
- 412 (Precondition Failed) - The included lock token was not
- enforceable on this resource or the server could not satisfy the
- request in the lockinfo XML element.
-
- 423 (Locked) - The resource is locked, so the method has been
- rejected.
-
-8.10.8 Example - Simple Lock Request
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: webdav.sb.aol.com
- Timeout: Infinite, Second-4100000000
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw at webdav.sb.aol.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D='DAV:'>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- <D:owner>
- <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
- >>Response
-
- HTTP/1.1 200 OK
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>Infinity</D:depth>
-
-
-
-Goland, et al. Standards Track [Page 48]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:owner>
- <D:href>
- http://www.ics.uci.edu/~ejw/contact.html
- </D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href>
- opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
- </D:href>
- </D:locktoken>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
- This example shows the successful creation of an exclusive write lock
- on resource http://webdav.sb.aol.com/workspace/webdav/proposal.doc.
- The resource http://www.ics.uci.edu/~ejw/contact.html contains
- contact information for the owner of the lock. The server has an
- activity-based timeout policy in place on this resource, which causes
- the lock to automatically be removed after 1 week (604800 seconds).
- Note that the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-8.10.9 Example - Refreshing a Write Lock
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: webdav.sb.aol.com
- Timeout: Infinite, Second-4100000000
- If: (<opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>)
- Authorization: Digest username="ejw",
- realm="ejw at webdav.sb.aol.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- >>Response
-
- HTTP/1.1 200 OK
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
-
-
-
-Goland, et al. Standards Track [Page 49]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>Infinity</D:depth>
- <D:owner>
- <D:href>
- http://www.ics.uci.edu/~ejw/contact.html
- </D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href>
- opaquelocktoken:e71d4fae-5dec-22d6-fea5-00a0c91e6be4
- </D:href>
- </D:locktoken>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
- This request would refresh the lock, resetting any time outs. Notice
- that the client asked for an infinite time out but the server choose
- to ignore the request. In this example, the nonce, response, and
- opaque fields have not been calculated in the Authorization request
- header.
-
-8.10.10 Example - Multi-Resource Lock Request
-
- >>Request
-
- LOCK /webdav/ HTTP/1.1
- Host: webdav.sb.aol.com
- Timeout: Infinite, Second-4100000000
- Depth: infinity
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw at webdav.sb.aol.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D="DAV:">
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:owner>
- <D:href>http://www.ics.uci.edu/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
- >>Response
-
-
-
-Goland, et al. Standards Track [Page 50]
-
-RFC 2518 WEBDAV February 1999
-
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://webdav.sb.aol.com/webdav/secret</D:href>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- </D:response>
- <D:response>
- <D:href>http://webdav.sb.aol.com/webdav/</D:href>
- <D:propstat>
- <D:prop><D:lockdiscovery/></D:prop>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- This example shows a request for an exclusive write lock on a
- collection and all its children. In this request, the client has
- specified that it desires an infinite length lock, if available,
- otherwise a timeout of 4.1 billion seconds, if available. The request
- entity body contains the contact information for the principal taking
- out the lock, in this case a web page URL.
-
- The error is a 403 (Forbidden) response on the resource
- http://webdav.sb.aol.com/webdav/secret. Because this resource could
- not be locked, none of the resources were locked. Note also that the
- lockdiscovery property for the Request-URI has been included as
- required. In this example the lockdiscovery property is empty which
- means that there are no outstanding locks on the resource.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-8.11 UNLOCK Method
-
- The UNLOCK method removes the lock identified by the lock token in
- the Lock-Token request header from the Request-URI, and all other
- resources included in the lock. If all resources which have been
- locked under the submitted lock token can not be unlocked then the
- UNLOCK request MUST fail.
-
- Any DAV compliant resource which supports the LOCK method MUST
- support the UNLOCK method.
-
-
-
-
-
-Goland, et al. Standards Track [Page 51]
-
-RFC 2518 WEBDAV February 1999
-
-
-8.11.1 Example - UNLOCK
-
- >>Request
-
- UNLOCK /workspace/webdav/info.doc HTTP/1.1
- Host: webdav.sb.aol.com
- Lock-Token: <opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
- Authorization: Digest username="ejw",
- realm="ejw at webdav.sb.aol.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, the lock identified by the lock token
- "opaquelocktoken:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is
- successfully removed from the resource
- http://webdav.sb.aol.com/workspace/webdav/info.doc. If this lock
- included more than just one resource, the lock is removed from all
- resources included in the lock. The 204 (No Content) status code is
- used instead of 200 (OK) because there is no response entity body.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-9 HTTP Headers for Distributed Authoring
-
-9.1 DAV Header
-
- DAV = "DAV" ":" "1" ["," "2"] ["," 1#extend]
-
- This header indicates that the resource supports the DAV schema and
- protocol as specified. All DAV compliant resources MUST return the
- DAV header on all OPTIONS responses.
-
- The value is a list of all compliance classes that the resource
- supports. Note that above a comma has already been added to the 2.
- This is because a resource can not be level 2 compliant unless it is
- also level 1 compliant. Please refer to section 15 for more details.
- In general, however, support for one compliance class does not entail
- support for any other.
-
-9.2 Depth Header
-
- Depth = "Depth" ":" ("0" | "1" | "infinity")
-
-
-
-
-Goland, et al. Standards Track [Page 52]
-
-RFC 2518 WEBDAV February 1999
-
-
- The Depth header is used with methods executed on resources which
- could potentially have internal members to indicate whether the
- method is to be applied only to the resource ("Depth: 0"), to the
- resource and its immediate children, ("Depth: 1"), or the resource
- and all its progeny ("Depth: infinity").
-
- The Depth header is only supported if a method's definition
- explicitly provides for such support.
-
- The following rules are the default behavior for any method that
- supports the Depth header. A method may override these defaults by
- defining different behavior in its definition.
-
- Methods which support the Depth header may choose not to support all
- of the header's values and may define, on a case by case basis, the
- behavior of the method if a Depth header is not present. For example,
- the MOVE method only supports "Depth: infinity" and if a Depth header
- is not present will act as if a "Depth: infinity" header had been
- applied.
-
- Clients MUST NOT rely upon methods executing on members of their
- hierarchies in any particular order or on the execution being atomic
- unless the particular method explicitly provides such guarantees.
-
- Upon execution, a method with a Depth header will perform as much of
- its assigned task as possible and then return a response specifying
- what it was able to accomplish and what it failed to do.
-
- So, for example, an attempt to COPY a hierarchy may result in some of
- the members being copied and some not.
-
- Any headers on a method that has a defined interaction with the Depth
- header MUST be applied to all resources in the scope of the method
- except where alternative behavior is explicitly defined. For example,
- an If-Match header will have its value applied against every resource
- in the method's scope and will cause the method to fail if the header
- fails to match.
-
- If a resource, source or destination, within the scope of the method
- with a Depth header is locked in such a way as to prevent the
- successful execution of the method, then the lock token for that
- resource MUST be submitted with the request in the If request header.
-
- The Depth header only specifies the behavior of the method with
- regards to internal children. If a resource does not have internal
- children then the Depth header MUST be ignored.
-
-
-
-
-
-Goland, et al. Standards Track [Page 53]
-
-RFC 2518 WEBDAV February 1999
-
-
- Please note, however, that it is always an error to submit a value
- for the Depth header that is not allowed by the method's definition.
- Thus submitting a "Depth: 1" on a COPY, even if the resource does not
- have internal members, will result in a 400 (Bad Request). The method
- should fail not because the resource doesn't have internal members,
- but because of the illegal value in the header.
-
-9.3 Destination Header
-
- Destination = "Destination" ":" absoluteURI
-
- The Destination header specifies the URI which identifies a
- destination resource for methods such as COPY and MOVE, which take
- two URIs as parameters. Note that the absoluteURI production is
- defined in [RFC2396].
-
-9.4 If Header
-
- If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
- No-tag-list = List
- Tagged-list = Resource 1*List
- Resource = Coded-URL
- List = "(" 1*(["Not"](State-token | "[" entity-tag "]")) ")"
- State-token = Coded-URL
- Coded-URL = "<" absoluteURI ">"
-
- The If header is intended to have similar functionality to the If-
- Match header defined in section 14.25 of [RFC2068]. However the If
- header is intended for use with any URI which represents state
- information, referred to as a state token, about a resource as well
- as ETags. A typical example of a state token is a lock token, and
- lock tokens are the only state tokens defined in this specification.
-
- All DAV compliant resources MUST honor the If header.
-
- The If header's purpose is to describe a series of state lists. If
- the state of the resource to which the header is applied does not
- match any of the specified state lists then the request MUST fail
- with a 412 (Precondition Failed). If one of the described state
- lists matches the state of the resource then the request may succeed.
-
- Note that the absoluteURI production is defined in [RFC2396].
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 54]
-
-RFC 2518 WEBDAV February 1999
-
-
-9.4.1 No-tag-list Production
-
- The No-tag-list production describes a series of state tokens and
- ETags. If multiple No-tag-list productions are used then one only
- needs to match the state of the resource for the method to be allowed
- to continue.
-
- If a method, due to the presence of a Depth or Destination header, is
- applied to multiple resources then the No-tag-list production MUST be
- applied to each resource the method is applied to.
-
-9.4.1.1 Example - No-tag-list If Header
-
- If: (<locktoken:a-write-lock-token> ["I am an ETag"]) (["I am another
- ETag"])
-
- The previous header would require that any resources within the scope
- of the method must either be locked with the specified lock token and
- in the state identified by the "I am an ETag" ETag or in the state
- identified by the second ETag "I am another ETag". To put the matter
- more plainly one can think of the previous If header as being in the
- form (or (and <locktoken:a-write-lock-token> ["I am an ETag"]) (and
- ["I am another ETag"])).
-
-9.4.2 Tagged-list Production
-
- The tagged-list production scopes a list production. That is, it
- specifies that the lists following the resource specification only
- apply to the specified resource. The scope of the resource
- production begins with the list production immediately following the
- resource production and ends with the next resource production, if
- any.
-
- When the If header is applied to a particular resource, the Tagged-
- list productions MUST be searched to determine if any of the listed
- resources match the operand resource(s) for the current method. If
- none of the resource productions match the current resource then the
- header MUST be ignored. If one of the resource productions does
- match the name of the resource under consideration then the list
- productions following the resource production MUST be applied to the
- resource in the manner specified in the previous section.
-
- The same URI MUST NOT appear more than once in a resource production
- in an If header.
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 55]
-
-RFC 2518 WEBDAV February 1999
-
-
-9.4.2.1 Example - Tagged List If header
-
- COPY /resource1 HTTP/1.1
- Host: www.foo.bar
- Destination: http://www.foo.bar/resource2
- If: <http://www.foo.bar/resource1> (<locktoken:a-write-lock-token>
- [W/"A weak ETag"]) (["strong ETag"])
- <http://www.bar.bar/random>(["another strong ETag"])
-
- In this example http://www.foo.bar/resource1 is being copied to
- http://www.foo.bar/resource2. When the method is first applied to
- http://www.foo.bar/resource1, resource1 must be in the state
- specified by "(<locktoken:a-write-lock-token> [W/"A weak ETag"])
- (["strong ETag"])", that is, it either must be locked with a lock
- token of "locktoken:a-write-lock-token" and have a weak entity tag
- W/"A weak ETag" or it must have a strong entity tag "strong ETag".
-
- That is the only success condition since the resource
- http://www.bar.bar/random never has the method applied to it (the
- only other resource listed in the If header) and
- http://www.foo.bar/resource2 is not listed in the If header.
-
-9.4.3 not Production
-
- Every state token or ETag is either current, and hence describes the
- state of a resource, or is not current, and does not describe the
- state of a resource. The boolean operation of matching a state token
- or ETag to the current state of a resource thus resolves to a true or
- false value. The not production is used to reverse that value. The
- scope of the not production is the state-token or entity-tag
- immediately following it.
-
- If: (Not <locktoken:write1> <locktoken:write2>)
-
- When submitted with a request, this If header requires that all
- operand resources must not be locked with locktoken:write1 and must
- be locked with locktoken:write2.
-
-9.4.4 Matching Function
-
- When performing If header processing, the definition of a matching
- state token or entity tag is as follows.
-
- Matching entity tag: Where the entity tag matches an entity tag
- associated with that resource.
-
- Matching state token: Where there is an exact match between the state
- token in the If header and any state token on the resource.
-
-
-
-Goland, et al. Standards Track [Page 56]
-
-RFC 2518 WEBDAV February 1999
-
-
-9.4.5 If Header and Non-DAV Compliant Proxies
-
- Non-DAV compliant proxies will not honor the If header, since they
- will not understand the If header, and HTTP requires non-understood
- headers to be ignored. When communicating with HTTP/1.1 proxies, the
- "Cache-Control: no-cache" request header MUST be used so as to
- prevent the proxy from improperly trying to service the request from
- its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
- request header MUST be used for the same reason.
-
-9.5 Lock-Token Header
-
- Lock-Token = "Lock-Token" ":" Coded-URL
-
- The Lock-Token request header is used with the UNLOCK method to
- identify the lock to be removed. The lock token in the Lock-Token
- request header MUST identify a lock that contains the resource
- identified by Request-URI as a member.
-
- The Lock-Token response header is used with the LOCK method to
- indicate the lock token created as a result of a successful LOCK
- request to create a new lock.
-
-9.6 Overwrite Header
-
- Overwrite = "Overwrite" ":" ("T" | "F")
-
- The Overwrite header specifies whether the server should overwrite
- the state of a non-null destination resource during a COPY or MOVE.
- A value of "F" states that the server must not perform the COPY or
- MOVE operation if the state of the destination resource is non-null.
- If the overwrite header is not included in a COPY or MOVE request
- then the resource MUST treat the request as if it has an overwrite
- header of value "T". While the Overwrite header appears to duplicate
- the functionality of the If-Match: * header of HTTP/1.1, If-Match
- applies only to the Request-URI, and not to the Destination of a COPY
- or MOVE.
-
- If a COPY or MOVE is not performed due to the value of the Overwrite
- header, the method MUST fail with a 412 (Precondition Failed) status
- code.
-
- All DAV compliant resources MUST support the Overwrite header.
-
-9.7 Status-URI Response Header
-
- The Status-URI response header may be used with the 102 (Processing)
- status code to inform the client as to the status of a method.
-
-
-
-Goland, et al. Standards Track [Page 57]
-
-RFC 2518 WEBDAV February 1999
-
-
- Status-URI = "Status-URI" ":" *(Status-Code Coded-URL) ; Status-Code
- is defined in 6.1.1 of [RFC2068]
-
- The URIs listed in the header are source resources which have been
- affected by the outstanding method. The status code indicates the
- resolution of the method on the identified resource. So, for
- example, if a MOVE method on a collection is outstanding and a 102
- (Processing) response with a Status-URI response header is returned,
- the included URIs will indicate resources that have had move
- attempted on them and what the result was.
-
-9.8 Timeout Request Header
-
- TimeOut = "Timeout" ":" 1#TimeType
- TimeType = ("Second-" DAVTimeOutVal | "Infinite" | Other)
- DAVTimeOutVal = 1*digit
- Other = "Extend" field-value ; See section 4.2 of [RFC2068]
-
- Clients may include Timeout headers in their LOCK requests. However,
- the server is not required to honor or even consider these requests.
- Clients MUST NOT submit a Timeout request header with any method
- other than a LOCK method.
-
- A Timeout request header MUST contain at least one TimeType and may
- contain multiple TimeType entries. The purpose of listing multiple
- TimeType entries is to indicate multiple different values and value
- types that are acceptable to the client. The client lists the
- TimeType entries in order of preference.
-
- Timeout response values MUST use a Second value, Infinite, or a
- TimeType the client has indicated familiarity with. The server may
- assume a client is familiar with any TimeType submitted in a Timeout
- header.
-
- The "Second" TimeType specifies the number of seconds that will
- elapse between granting of the lock at the server, and the automatic
- removal of the lock. The timeout value for TimeType "Second" MUST
- NOT be greater than 2^32-1.
-
- The timeout counter SHOULD be restarted any time an owner of the lock
- sends a method to any member of the lock, including unsupported
- methods, or methods which are unsuccessful. However the lock MUST be
- refreshed if a refresh LOCK method is successfully received.
-
- If the timeout expires then the lock may be lost. Specifically, if
- the server wishes to harvest the lock upon time-out, the server
- SHOULD act as if an UNLOCK method was executed by the server on the
- resource using the lock token of the timed-out lock, performed with
-
-
-
-Goland, et al. Standards Track [Page 58]
-
-RFC 2518 WEBDAV February 1999
-
-
- its override authority. Thus logs should be updated with the
- disposition of the lock, notifications should be sent, etc., just as
- they would be for an UNLOCK request.
-
- Servers are advised to pay close attention to the values submitted by
- clients, as they will be indicative of the type of activity the
- client intends to perform. For example, an applet running in a
- browser may need to lock a resource, but because of the instability
- of the environment within which the applet is running, the applet may
- be turned off without warning. As a result, the applet is likely to
- ask for a relatively small timeout value so that if the applet dies,
- the lock can be quickly harvested. However, a document management
- system is likely to ask for an extremely long timeout because its
- user may be planning on going off-line.
-
- A client MUST NOT assume that just because the time-out has expired
- the lock has been lost.
-
-10 Status Code Extensions to HTTP/1.1
-
- The following status codes are added to those defined in HTTP/1.1
- [RFC2068].
-
-10.1 102 Processing
-
- The 102 (Processing) status code is an interim response used to
- inform the client that the server has accepted the complete request,
- but has not yet completed it. This status code SHOULD only be sent
- when the server has a reasonable expectation that the request will
- take significant time to complete. As guidance, if a method is taking
- longer than 20 seconds (a reasonable, but arbitrary value) to process
- the server SHOULD return a 102 (Processing) response. The server MUST
- send a final response after the request has been completed.
-
- Methods can potentially take a long period of time to process,
- especially methods that support the Depth header. In such cases the
- client may time-out the connection while waiting for a response. To
- prevent this the server may return a 102 (Processing) status code to
- indicate to the client that the server is still processing the
- method.
-
-10.2 207 Multi-Status
-
- The 207 (Multi-Status) status code provides status for multiple
- independent operations (see section 11 for more information).
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 59]
-
-RFC 2518 WEBDAV February 1999
-
-
-10.3 422 Unprocessable Entity
-
- The 422 (Unprocessable Entity) status code means the server
- understands the content type of the request entity (hence a
- 415(Unsupported Media Type) status code is inappropriate), and the
- syntax of the request entity is correct (thus a 400 (Bad Request)
- status code is inappropriate) but was unable to process the contained
- instructions. For example, this error condition may occur if an XML
- request body contains well-formed (i.e., syntactically correct), but
- semantically erroneous XML instructions.
-
-10.4 423 Locked
-
- The 423 (Locked) status code means the source or destination resource
- of a method is locked.
-
-10.5 424 Failed Dependency
-
- The 424 (Failed Dependency) status code means that the method could
- not be performed on the resource because the requested action
- depended on another action and that action failed. For example, if a
- command in a PROPPATCH method fails then, at minimum, the rest of the
- commands will also fail with 424 (Failed Dependency).
-
-10.6 507 Insufficient Storage
-
- The 507 (Insufficient Storage) status code means the method could not
- be performed on the resource because the server is unable to store
- the representation needed to successfully complete the request. This
- condition is considered to be temporary. If the request which
- received this status code was the result of a user action, the
- request MUST NOT be repeated until it is requested by a separate user
- action.
-
-11 Multi-Status Response
-
- The default 207 (Multi-Status) response body is a text/xml or
- application/xml HTTP entity that contains a single XML element called
- multistatus, which contains a set of XML elements called response
- which contain 200, 300, 400, and 500 series status codes generated
- during the method invocation. 100 series status codes SHOULD NOT be
- recorded in a response XML element.
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 60]
-
-RFC 2518 WEBDAV February 1999
-
-
-12 XML Element Definitions
-
- In the section below, the final line of each section gives the
- element type declaration using the format defined in [REC-XML]. The
- "Value" field, where present, specifies further restrictions on the
- allowable contents of the XML element using BNF (i.e., to further
- restrict the values of a PCDATA element).
-
-12.1 activelock XML Element
-
- Name: activelock
- Namespace: DAV:
- Purpose: Describes a lock on a resource.
-
- <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
- locktoken?) >
-
-12.1.1 depth XML Element
-
- Name: depth
- Namespace: DAV:
- Purpose: The value of the Depth header.
- Value: "0" | "1" | "infinity"
-
- <!ELEMENT depth (#PCDATA) >
-
-12.1.2 locktoken XML Element
-
- Name: locktoken
- Namespace: DAV:
- Purpose: The lock token associated with a lock.
- Description: The href contains one or more opaque lock token URIs
- which all refer to the same lock (i.e., the OpaqueLockToken-URI
- production in section 6.4).
-
- <!ELEMENT locktoken (href+) >
-
-12.1.3 timeout XML Element
-
- Name: timeout
- Namespace: DAV:
- Purpose: The timeout associated with a lock
- Value: TimeType ;Defined in section 9.8
-
- <!ELEMENT timeout (#PCDATA) >
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 61]
-
-RFC 2518 WEBDAV February 1999
-
-
-12.2 collection XML Element
-
- Name: collection
- Namespace: DAV:
- Purpose: Identifies the associated resource as a collection. The
- resourcetype property of a collection resource MUST have this value.
-
- <!ELEMENT collection EMPTY >
-
-12.3 href XML Element
-
- Name: href
- Namespace: DAV:
- Purpose: Identifies the content of the element as a URI.
- Value: URI ; See section 3.2.1 of [RFC2068]
-
- <!ELEMENT href (#PCDATA)>
-
-12.4 link XML Element
-
- Name: link
- Namespace: DAV:
- Purpose: Identifies the property as a link and contains the source
- and destination of that link.
- Description: The link XML element is used to provide the sources and
- destinations of a link. The name of the property containing the link
- XML element provides the type of the link. Link is a multi-valued
- element, so multiple links may be used together to indicate multiple
- links with the same type. The values in the href XML elements inside
- the src and dst XML elements of the link XML element MUST NOT be
- rejected if they point to resources which do not exist.
-
- <!ELEMENT link (src+, dst+) >
-
-12.4.1 dst XML Element
-
- Name: dst
- Namespace: DAV:
- Purpose: Indicates the destination of a link
- Value: URI
-
- <!ELEMENT dst (#PCDATA) >
-
-12.4.2 src XML Element
-
- Name: src
- Namespace: DAV:
- Purpose: Indicates the source of a link.
-
-
-
-Goland, et al. Standards Track [Page 62]
-
-RFC 2518 WEBDAV February 1999
-
-
- Value: URI
-
- <!ELEMENT src (#PCDATA) >
-
-12.5 lockentry XML Element
-
- Name: lockentry
- Namespace: DAV:
- Purpose: Defines the types of locks that can be used with the
- resource.
-
- <!ELEMENT lockentry (lockscope, locktype) >
-
-12.6 lockinfo XML Element
-
- Name: lockinfo
- Namespace: DAV:
- Purpose: The lockinfo XML element is used with a LOCK method to
- specify the type of lock the client wishes to have created.
-
- <!ELEMENT lockinfo (lockscope, locktype, owner?) >
-
-12.7 lockscope XML Element
-
- Name: lockscope
- Namespace: DAV:
- Purpose: Specifies whether a lock is an exclusive lock, or a
- shared lock.
-
- <!ELEMENT lockscope (exclusive | shared) >
-
-12.7.1 exclusive XML Element
-
- Name: exclusive
- Namespace: DAV:
- Purpose: Specifies an exclusive lock
-
- <!ELEMENT exclusive EMPTY >
-
-12.7.2 shared XML Element
-
- Name: shared
- Namespace: DAV:
- Purpose: Specifies a shared lock
-
- <!ELEMENT shared EMPTY >
-
-
-
-
-
-Goland, et al. Standards Track [Page 63]
-
-RFC 2518 WEBDAV February 1999
-
-
-12.8 locktype XML Element
-
- Name: locktype
- Namespace: DAV:
- Purpose: Specifies the access type of a lock. At present, this
- specification only defines one lock type, the write lock.
-
- <!ELEMENT locktype (write) >
-
-12.8.1 write XML Element
-
- Name: write
- Namespace: DAV:
- Purpose: Specifies a write lock.
-
- <!ELEMENT write EMPTY >
-
-12.9 multistatus XML Element
-
- Name: multistatus
- Namespace: DAV:
- Purpose: Contains multiple response messages.
- Description: The responsedescription at the top level is used to
- provide a general message describing the overarching nature of the
- response. If this value is available an application may use it
- instead of presenting the individual response descriptions contained
- within the responses.
-
- <!ELEMENT multistatus (response+, responsedescription?) >
-
-12.9.1 response XML Element
-
- Name: response
- Namespace: DAV:
- Purpose: Holds a single response describing the effect of a
- method on resource and/or its properties.
- Description: A particular href MUST NOT appear more than once as the
- child of a response XML element under a multistatus XML element.
- This requirement is necessary in order to keep processing costs for a
- response to linear time. Essentially, this prevents having to search
- in order to group together all the responses by href. There are,
- however, no requirements regarding ordering based on href values.
-
- <!ELEMENT response (href, ((href*, status)|(propstat+)),
- responsedescription?) >
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 64]
-
-RFC 2518 WEBDAV February 1999
-
-
-12.9.1.1 propstat XML Element
-
- Name: propstat
- Namespace: DAV:
- Purpose: Groups together a prop and status element that is
- associated with a particular href element.
- Description: The propstat XML element MUST contain one prop XML
- element and one status XML element. The contents of the prop XML
- element MUST only list the names of properties to which the result in
- the status element applies.
-
- <!ELEMENT propstat (prop, status, responsedescription?) >
-
-12.9.1.2 status XML Element
-
- Name: status
- Namespace: DAV:
- Purpose: Holds a single HTTP status-line
- Value: status-line ;status-line defined in [RFC2068]
-
- <!ELEMENT status (#PCDATA) >
-
-12.9.2 responsedescription XML Element
-
- Name: responsedescription
- Namespace: DAV:
- Purpose: Contains a message that can be displayed to the user
- explaining the nature of the response.
- Description: This XML element provides information suitable to be
- presented to a user.
-
- <!ELEMENT responsedescription (#PCDATA) >
-
-12.10 owner XML Element
-
- Name: owner
- Namespace: DAV:
- Purpose: Provides information about the principal taking out a
- lock.
- Description: The owner XML element provides information sufficient
- for either directly contacting a principal (such as a telephone
- number or Email URI), or for discovering the principal (such as the
- URL of a homepage) who owns a lock.
-
- <!ELEMENT owner ANY>
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 65]
-
-RFC 2518 WEBDAV February 1999
-
-
-12.11 prop XML element
-
- Name: prop
- Namespace: DAV:
- Purpose: Contains properties related to a resource.
- Description: The prop XML element is a generic container for
- properties defined on resources. All elements inside a prop XML
- element MUST define properties related to the resource. No other
- elements may be used inside of a prop element.
-
- <!ELEMENT prop ANY>
-
-12.12 propertybehavior XML element
-
- Name: propertybehavior Namespace: DAV: Purpose: Specifies
- how properties are handled during a COPY or MOVE.
- Description: The propertybehavior XML element specifies how
- properties are handled during a COPY or MOVE. If this XML element is
- not included in the request body then the server is expected to act
- as defined by the default property handling behavior of the
- associated method. All WebDAV compliant resources MUST support the
- propertybehavior XML element.
-
- <!ELEMENT propertybehavior (omit | keepalive) >
-
-12.12.1 keepalive XML element
-
- Name: keepalive
- Namespace: DAV:
- Purpose: Specifies requirements for the copying/moving of live
- properties.
- Description: If a list of URIs is included as the value of keepalive
- then the named properties MUST be "live" after they are copied
- (moved) to the destination resource of a COPY (or MOVE). If the
- value "*" is given for the keepalive XML element, this designates
- that all live properties on the source resource MUST be live on the
- destination. If the requirements specified by the keepalive element
- can not be honored then the method MUST fail with a 412 (Precondition
- Failed). All DAV compliant resources MUST support the keepalive XML
- element for use with the COPY and MOVE methods.
- Value: "*" ; #PCDATA value can only be "*"
-
- <!ELEMENT keepalive (#PCDATA | href+) >
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 66]
-
-RFC 2518 WEBDAV February 1999
-
-
-12.12.2 omit XML element
-
- Name: omit
- Namespace: DAV:
- Purpose: The omit XML element instructs the server that it should
- use best effort to copy properties but a failure to copy a property
- MUST NOT cause the method to fail. Description: The default behavior
- for a COPY or MOVE is to copy/move all properties or fail the method.
- In certain circumstances, such as when a server copies a resource
- over another protocol such as FTP, it may not be possible to
- copy/move the properties associated with the resource. Thus any
- attempt to copy/move over FTP would always have to fail because
- properties could not be moved over, even as dead properties. All DAV
- compliant resources MUST support the omit XML element on COPY/MOVE
- methods.
-
- <!ELEMENT omit EMPTY >
-
-12.13 propertyupdate XML element
-
- Name: propertyupdate
- Namespace: DAV:
- Purpose: Contains a request to alter the properties on a
- resource.
- Description: This XML element is a container for the information
- required to modify the properties on the resource. This XML element
- is multi-valued.
-
- <!ELEMENT propertyupdate (remove | set)+ >
-
-12.13.1 remove XML element
-
- Name: remove
- Namespace: DAV:
- Purpose: Lists the DAV properties to be removed from a resource.
- Description: Remove instructs that the properties specified in prop
- should be removed. Specifying the removal of a property that does
- not exist is not an error. All the XML elements in a prop XML
- element inside of a remove XML element MUST be empty, as only the
- names of properties to be removed are required.
-
- <!ELEMENT remove (prop) >
-
-12.13.2 set XML element
-
- Name: set
- Namespace: DAV:
- Purpose: Lists the DAV property values to be set for a resource.
-
-
-
-Goland, et al. Standards Track [Page 67]
-
-RFC 2518 WEBDAV February 1999
-
-
- Description: The set XML element MUST contain only a prop XML
- element. The elements contained by the prop XML element inside the
- set XML element MUST specify the name and value of properties that
- are set on the resource identified by Request-URI. If a property
- already exists then its value is replaced. Language tagging
- information in the property's value (in the "xml:lang" attribute, if
- present) MUST be persistently stored along with the property, and
- MUST be subsequently retrievable using PROPFIND.
-
- <!ELEMENT set (prop) >
-
-12.14 propfind XML Element
-
- Name: propfind
- Namespace: DAV:
- Purpose: Specifies the properties to be returned from a PROPFIND
- method. Two special elements are specified for use with propfind,
- allprop and propname. If prop is used inside propfind it MUST only
- contain property names, not values.
-
- <!ELEMENT propfind (allprop | propname | prop) >
-
-12.14.1 allprop XML Element
-
- Name: allprop Namespace: DAV: Purpose: The allprop XML
- element specifies that all property names and values on the resource
- are to be returned.
-
- <!ELEMENT allprop EMPTY >
-
-12.14.2 propname XML Element
-
- Name: propname Namespace: DAV: Purpose: The propname XML
- element specifies that only a list of property names on the resource
- is to be returned.
-
- <!ELEMENT propname EMPTY >
-
-13 DAV Properties
-
- For DAV properties, the name of the property is also the same as the
- name of the XML element that contains its value. In the section
- below, the final line of each section gives the element type
- declaration using the format defined in [REC-XML]. The "Value" field,
- where present, specifies further restrictions on the allowable
- contents of the XML element using BNF (i.e., to further restrict the
- values of a PCDATA element).
-
-
-
-
-Goland, et al. Standards Track [Page 68]
-
-RFC 2518 WEBDAV February 1999
-
-
-13.1 creationdate Property
-
- Name: creationdate
- Namespace: DAV:
- Purpose: Records the time and date the resource was created.
- Value: date-time ; See Appendix 2
- Description: The creationdate property should be defined on all DAV
- compliant resources. If present, it contains a timestamp of the
- moment when the resource was created (i.e., the moment it had non-
- null state).
-
- <!ELEMENT creationdate (#PCDATA) >
-
-13.2 displayname Property
-
- Name: displayname
- Namespace: DAV:
- Purpose: Provides a name for the resource that is suitable for
- presentation to a user.
- Description: The displayname property should be defined on all DAV
- compliant resources. If present, the property contains a description
- of the resource that is suitable for presentation to a user.
-
- <!ELEMENT displayname (#PCDATA) >
-
-13.3 getcontentlanguage Property
-
- Name: getcontentlanguage
- Namespace: DAV:
- Purpose: Contains the Content-Language header returned by a GET
- without accept headers
- Description: The getcontentlanguage property MUST be defined on any
- DAV compliant resource that returns the Content-Language header on a
- GET.
- Value: language-tag ;language-tag is defined in section 14.13
- of [RFC2068]
-
- <!ELEMENT getcontentlanguage (#PCDATA) >
-
-13.4 getcontentlength Property
-
- Name: getcontentlength
- Namespace: DAV:
- Purpose: Contains the Content-Length header returned by a GET
- without accept headers.
- Description: The getcontentlength property MUST be defined on any
- DAV compliant resource that returns the Content-Length header in
- response to a GET.
-
-
-
-Goland, et al. Standards Track [Page 69]
-
-RFC 2518 WEBDAV February 1999
-
-
- Value: content-length ; see section 14.14 of [RFC2068]
-
- <!ELEMENT getcontentlength (#PCDATA) >
-
-13.5 getcontenttype Property
-
- Name: getcontenttype
- Namespace: DAV:
- Purpose: Contains the Content-Type header returned by a GET
- without accept headers.
- Description: This getcontenttype property MUST be defined on any DAV
- compliant resource that returns the Content-Type header in response
- to a GET.
- Value: media-type ; defined in section 3.7 of [RFC2068]
-
- <!ELEMENT getcontenttype (#PCDATA) >
-
-13.6 getetag Property
-
- Name: getetag
- Namespace: DAV:
- Purpose: Contains the ETag header returned by a GET without
- accept headers.
- Description: The getetag property MUST be defined on any DAV
- compliant resource that returns the Etag header.
- Value: entity-tag ; defined in section 3.11 of [RFC2068]
-
- <!ELEMENT getetag (#PCDATA) >
-
-13.7 getlastmodified Property
-
- Name: getlastmodified
- Namespace: DAV:
- Purpose: Contains the Last-Modified header returned by a GET
- method without accept headers.
- Description: Note that the last-modified date on a resource may
- reflect changes in any part of the state of the resource, not
- necessarily just a change to the response to the GET method. For
- example, a change in a property may cause the last-modified date to
- change. The getlastmodified property MUST be defined on any DAV
- compliant resource that returns the Last-Modified header in response
- to a GET.
- Value: HTTP-date ; defined in section 3.3.1 of [RFC2068]
-
- <!ELEMENT getlastmodified (#PCDATA) >
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 70]
-
-RFC 2518 WEBDAV February 1999
-
-
-13.8 lockdiscovery Property
-
- Name: lockdiscovery
- Namespace: DAV:
- Purpose: Describes the active locks on a resource
- Description: The lockdiscovery property returns a listing of who has
- a lock, what type of lock he has, the timeout type and the time
- remaining on the timeout, and the associated lock token. The server
- is free to withhold any or all of this information if the requesting
- principal does not have sufficient access rights to see the requested
- data.
-
- <!ELEMENT lockdiscovery (activelock)* >
-
-13.8.1 Example - Retrieving the lockdiscovery Property
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.foo.bar
- Content-Length: xxxx
- Content-Type: text/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D='DAV:'>
- <D:prop><D:lockdiscovery/></D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D='DAV:'>
- <D:response>
- <D:href>http://www.foo.bar/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>0</D:depth>
- <D:owner>Jane Smith</D:owner>
- <D:timeout>Infinite</D:timeout>
- <D:locktoken>
-
-
-
-Goland, et al. Standards Track [Page 71]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:href>
- opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76
- </D:href>
- </D:locktoken>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- This resource has a single exclusive write lock on it, with an
- infinite timeout.
-
-13.9 resourcetype Property
-
- Name: resourcetype
- Namespace: DAV:
- Purpose: Specifies the nature of the resource.
- Description: The resourcetype property MUST be defined on all DAV
- compliant resources. The default value is empty.
-
- <!ELEMENT resourcetype ANY >
-
-13.10 source Property
-
- Name: source
- Namespace: DAV:
- Purpose: The destination of the source link identifies the
- resource that contains the unprocessed source of the link's source.
- Description: The source of the link (src) is typically the URI of the
- output resource on which the link is defined, and there is typically
- only one destination (dst) of the link, which is the URI where the
- unprocessed source of the resource may be accessed. When more than
- one link destination exists, this specification asserts no policy on
- ordering.
-
- <!ELEMENT source (link)* >
-
-13.10.1 Example - A source Property
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:" xmlns:F="http://www.foocorp.com/Project/">
- <D:source>
- <D:link>
- <F:projfiles>Source</F:projfiles>
- <D:src>http://foo.bar/program</D:src>
-
-
-
-Goland, et al. Standards Track [Page 72]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:dst>http://foo.bar/src/main.c</D:dst>
- </D:link>
- <D:link>
- <F:projfiles>Library</F:projfiles>
- <D:src>http://foo.bar/program</D:src>
- <D:dst>http://foo.bar/src/main.lib</D:dst>
- </D:link>
- <D:link>
- <F:projfiles>Makefile</F:projfiles>
- <D:src>http://foo.bar/program</D:src>
- <D:dst>http://foo.bar/src/makefile</D:dst>
- </D:link>
- </D:source>
- </D:prop>
-
- In this example the resource http://foo.bar/program has a source
- property that contains three links. Each link contains three
- elements, two of which, src and dst, are part of the DAV schema
- defined in this document, and one which is defined by the schema
- http://www.foocorp.com/project/ (Source, Library, and Makefile). A
- client which only implements the elements in the DAV spec will not
- understand the foocorp elements and will ignore them, thus seeing the
- expected source and destination links. An enhanced client may know
- about the foocorp elements and be able to present the user with
- additional information about the links. This example demonstrates
- the power of XML markup, allowing element values to be enhanced
- without breaking older clients.
-
-13.11 supportedlock Property
-
- Name: supportedlock
- Namespace: DAV:
- Purpose: To provide a listing of the lock capabilities supported
- by the resource.
- Description: The supportedlock property of a resource returns a
- listing of the combinations of scope and access types which may be
- specified in a lock request on the resource. Note that the actual
- contents are themselves controlled by access controls so a server is
- not required to provide information the client is not authorized to
- see.
-
- <!ELEMENT supportedlock (lockentry)* >
-
-13.11.1 Example - Retrieving the supportedlock Property
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
-
-
-
-Goland, et al. Standards Track [Page 73]
-
-RFC 2518 WEBDAV February 1999
-
-
- Host: www.foo.bar
- Content-Length: xxxx
- Content-Type: text/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop><D:supportedlock/></D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.foo.bar/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-14 Instructions for Processing XML in DAV
-
- All DAV compliant resources MUST ignore any unknown XML element and
- all its children encountered while processing a DAV method that uses
- XML as its command language.
-
- This restriction also applies to the processing, by clients, of DAV
- property values where unknown XML elements SHOULD be ignored unless
- the property's schema declares otherwise.
-
-
-
-
-
-Goland, et al. Standards Track [Page 74]
-
-RFC 2518 WEBDAV February 1999
-
-
- This restriction does not apply to setting dead DAV properties on the
- server where the server MUST record unknown XML elements.
-
- Additionally, this restriction does not apply to the use of XML where
- XML happens to be the content type of the entity body, for example,
- when used as the body of a PUT.
-
- Since XML can be transported as text/xml or application/xml, a DAV
- server MUST accept DAV method requests with XML parameters
- transported as either text/xml or application/xml, and DAV client
- MUST accept XML responses using either text/xml or application/xml.
-
-15 DAV Compliance Classes
-
- A DAV compliant resource can choose from two classes of compliance.
- A client can discover the compliance classes of a resource by
- executing OPTIONS on the resource, and examining the "DAV" header
- which is returned.
-
- Since this document describes extensions to the HTTP/1.1 protocol,
- minimally all DAV compliant resources, clients, and proxies MUST be
- compliant with [RFC2068].
-
- Compliance classes are not necessarily sequential. A resource that is
- class 2 compliant must also be class 1 compliant; but if additional
- compliance classes are defined later, a resource that is class 1, 2,
- and 4 compliant might not be class 3 compliant. Also note that
- identifiers other than numbers may be used as compliance class
- identifiers.
-
-15.1 Class 1
-
- A class 1 compliant resource MUST meet all "MUST" requirements in all
- sections of this document.
-
- Class 1 compliant resources MUST return, at minimum, the value "1" in
- the DAV header on all responses to the OPTIONS method.
-
-15.2 Class 2
-
- A class 2 compliant resource MUST meet all class 1 requirements and
- support the LOCK method, the supportedlock property, the
- lockdiscovery property, the Time-Out response header and the Lock-
- Token request header. A class "2" compliant resource SHOULD also
- support the Time-Out request header and the owner XML element.
-
- Class 2 compliant resources MUST return, at minimum, the values "1"
- and "2" in the DAV header on all responses to the OPTIONS method.
-
-
-
-Goland, et al. Standards Track [Page 75]
-
-RFC 2518 WEBDAV February 1999
-
-
-16 Internationalization Considerations
-
- In the realm of internationalization, this specification complies
- with the IETF Character Set Policy [RFC2277]. In this specification,
- human-readable fields can be found either in the value of a property,
- or in an error message returned in a response entity body. In both
- cases, the human-readable content is encoded using XML, which has
- explicit provisions for character set tagging and encoding, and
- requires that XML processors read XML elements encoded, at minimum,
- using the UTF-8 [UTF-8] encoding of the ISO 10646 multilingual plane.
- XML examples in this specification demonstrate use of the charset
- parameter of the Content-Type header, as defined in [RFC2376], as
- well as the XML "encoding" attribute, which together provide charset
- identification information for MIME and XML processors.
-
- XML also provides a language tagging capability for specifying the
- language of the contents of a particular XML element. XML uses
- either IANA registered language tags (see [RFC1766]) or ISO 639
- language tags [ISO-639] in the "xml:lang" attribute of an XML element
- to identify the language of its content and attributes.
-
- WebDAV applications MUST support the character set tagging, character
- set encoding, and the language tagging functionality of the XML
- specification. Implementors of WebDAV applications are strongly
- encouraged to read "XML Media Types" [RFC2376] for instruction on
- which MIME media type to use for XML transport, and on use of the
- charset parameter of the Content-Type header.
-
- Names used within this specification fall into three categories:
- names of protocol elements such as methods and headers, names of XML
- elements, and names of properties. Naming of protocol elements
- follows the precedent of HTTP, using English names encoded in USASCII
- for methods and headers. Since these protocol elements are not
- visible to users, and are in fact simply long token identifiers, they
- do not need to support encoding in multiple character sets.
- Similarly, though the names of XML elements used in this
- specification are English names encoded in UTF-8, these names are not
- visible to the user, and hence do not need to support multiple
- character set encodings.
-
- The name of a property defined on a resource is a URI. Although some
- applications (e.g., a generic property viewer) will display property
- URIs directly to their users, it is expected that the typical
- application will use a fixed set of properties, and will provide a
- mapping from the property name URI to a human-readable field when
- displaying the property name to a user. It is only in the case where
-
-
-
-
-
-Goland, et al. Standards Track [Page 76]
-
-RFC 2518 WEBDAV February 1999
-
-
- the set of properties is not known ahead of time that an application
- need display a property name URI to a user. We recommend that
- applications provide human-readable property names wherever feasible.
-
- For error reporting, we follow the convention of HTTP/1.1 status
- codes, including with each status code a short, English description
- of the code (e.g., 423 (Locked)). While the possibility exists that
- a poorly crafted user agent would display this message to a user,
- internationalized applications will ignore this message, and display
- an appropriate message in the user's language and character set.
-
- Since interoperation of clients and servers does not require locale
- information, this specification does not specify any mechanism for
- transmission of this information.
-
-17 Security Considerations
-
- This section is provided to detail issues concerning security
- implications of which WebDAV applications need to be aware.
-
- All of the security considerations of HTTP/1.1 (discussed in
- [RFC2068]) and XML (discussed in [RFC2376]) also apply to WebDAV. In
- addition, the security risks inherent in remote authoring require
- stronger authentication technology, introduce several new privacy
- concerns, and may increase the hazards from poor server design.
- These issues are detailed below.
-
-17.1 Authentication of Clients
-
- Due to their emphasis on authoring, WebDAV servers need to use
- authentication technology to protect not just access to a network
- resource, but the integrity of the resource as well. Furthermore,
- the introduction of locking functionality requires support for
- authentication.
-
- A password sent in the clear over an insecure channel is an
- inadequate means for protecting the accessibility and integrity of a
- resource as the password may be intercepted. Since Basic
- authentication for HTTP/1.1 performs essentially clear text
- transmission of a password, Basic authentication MUST NOT be used to
- authenticate a WebDAV client to a server unless the connection is
- secure. Furthermore, a WebDAV server MUST NOT send Basic
- authentication credentials in a WWW-Authenticate header unless the
- connection is secure. Examples of secure connections include a
- Transport Layer Security (TLS) connection employing a strong cipher
- suite with mutual authentication of client and server, or a
- connection over a network which is physically secure, for example, an
- isolated network in a building with restricted access.
-
-
-
-Goland, et al. Standards Track [Page 77]
-
-RFC 2518 WEBDAV February 1999
-
-
- WebDAV applications MUST support the Digest authentication scheme
- [RFC2069]. Since Digest authentication verifies that both parties to
- a communication know a shared secret, a password, without having to
- send that secret in the clear, Digest authentication avoids the
- security problems inherent in Basic authentication while providing a
- level of authentication which is useful in a wide range of scenarios.
-
-17.2 Denial of Service
-
- Denial of service attacks are of special concern to WebDAV servers.
- WebDAV plus HTTP enables denial of service attacks on every part of a
- system's resources.
-
- The underlying storage can be attacked by PUTting extremely large
- files.
-
- Asking for recursive operations on large collections can attack
- processing time.
-
- Making multiple pipelined requests on multiple connections can attack
- network connections.
-
- WebDAV servers need to be aware of the possibility of a denial of
- service attack at all levels.
-
-17.3 Security through Obscurity
-
- WebDAV provides, through the PROPFIND method, a mechanism for listing
- the member resources of a collection. This greatly diminishes the
- effectiveness of security or privacy techniques that rely only on the
- difficulty of discovering the names of network resources. Users of
- WebDAV servers are encouraged to use access control techniques to
- prevent unwanted access to resources, rather than depending on the
- relative obscurity of their resource names.
-
-17.4 Privacy Issues Connected to Locks
-
- When submitting a lock request a user agent may also submit an owner
- XML field giving contact information for the person taking out the
- lock (for those cases where a person, rather than a robot, is taking
- out the lock). This contact information is stored in a lockdiscovery
- property on the resource, and can be used by other collaborators to
- begin negotiation over access to the resource. However, in many
- cases this contact information can be very private, and should not be
- widely disseminated. Servers SHOULD limit read access to the
- lockdiscovery property as appropriate. Furthermore, user agents
-
-
-
-
-
-Goland, et al. Standards Track [Page 78]
-
-RFC 2518 WEBDAV February 1999
-
-
- SHOULD provide control over whether contact information is sent at
- all, and if contact information is sent, control over exactly what
- information is sent.
-
-17.5 Privacy Issues Connected to Properties
-
- Since property values are typically used to hold information such as
- the author of a document, there is the possibility that privacy
- concerns could arise stemming from widespread access to a resource's
- property data. To reduce the risk of inadvertent release of private
- information via properties, servers are encouraged to develop access
- control mechanisms that separate read access to the resource body and
- read access to the resource's properties. This allows a user to
- control the dissemination of their property data without overly
- restricting access to the resource's contents.
-
-17.6 Reduction of Security due to Source Link
-
- HTTP/1.1 warns against providing read access to script code because
- it may contain sensitive information. Yet WebDAV, via its source
- link facility, can potentially provide a URI for script resources so
- they may be authored. For HTTP/1.1, a server could reasonably
- prevent access to source resources due to the predominance of read-
- only access. WebDAV, with its emphasis on authoring, encourages read
- and write access to source resources, and provides the source link
- facility to identify the source. This reduces the security benefits
- of eliminating access to source resources. Users and administrators
- of WebDAV servers should be very cautious when allowing remote
- authoring of scripts, limiting read and write access to the source
- resources to authorized principals.
-
-17.7 Implications of XML External Entities
-
- XML supports a facility known as "external entities", defined in
- section 4.2.2 of [REC-XML], which instruct an XML processor to
- retrieve and perform an inline include of XML located at a particular
- URI. An external XML entity can be used to append or modify the
- document type declaration (DTD) associated with an XML document. An
- external XML entity can also be used to include XML within the
- content of an XML document. For non-validating XML, such as the XML
- used in this specification, including an external XML entity is not
- required by [REC-XML]. However, [REC-XML] does state that an XML
- processor may, at its discretion, include the external XML entity.
-
- External XML entities have no inherent trustworthiness and are
- subject to all the attacks that are endemic to any HTTP GET request.
- Furthermore, it is possible for an external XML entity to modify the
- DTD, and hence affect the final form of an XML document, in the worst
-
-
-
-Goland, et al. Standards Track [Page 79]
-
-RFC 2518 WEBDAV February 1999
-
-
- case significantly modifying its semantics, or exposing the XML
- processor to the security risks discussed in [RFC2376]. Therefore,
- implementers must be aware that external XML entities should be
- treated as untrustworthy.
-
- There is also the scalability risk that would accompany a widely
- deployed application which made use of external XML entities. In
- this situation, it is possible that there would be significant
- numbers of requests for one external XML entity, potentially
- overloading any server which fields requests for the resource
- containing the external XML entity.
-
-17.8 Risks Connected with Lock Tokens
-
- This specification, in section 6.4, requires the use of Universal
- Unique Identifiers (UUIDs) for lock tokens, in order to guarantee
- their uniqueness across space and time. UUIDs, as defined in [ISO-
- 11578], contain a "node" field which "consists of the IEEE address,
- usually the host address. For systems with multiple IEEE 802 nodes,
- any available node address can be used." Since a WebDAV server will
- issue many locks over its lifetime, the implication is that it will
- also be publicly exposing its IEEE 802 address.
-
- There are several risks associated with exposure of IEEE 802
- addresses. Using the IEEE 802 address:
-
- * It is possible to track the movement of hardware from subnet to
- subnet.
-
- * It may be possible to identify the manufacturer of the hardware
- running a WebDAV server.
-
- * It may be possible to determine the number of each type of computer
- running WebDAV.
-
- Section 6.4.1 of this specification details an alternate mechanism
- for generating the "node" field of a UUID without using an IEEE 802
- address, which alleviates the risks associated with exposure of IEEE
- 802 addresses by using an alternate source of uniqueness.
-
-18 IANA Considerations
-
- This document defines two namespaces, the namespace of property
- names, and the namespace of WebDAV-specific XML elements used within
- property values.
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 80]
-
-RFC 2518 WEBDAV February 1999
-
-
- URIs are used for both names, for several reasons. Assignment of a
- URI does not require a request to a central naming authority, and
- hence allow WebDAV property names and XML elements to be quickly
- defined by any WebDAV user or application. URIs also provide a
- unique address space, ensuring that the distributed users of WebDAV
- will not have collisions among the property names and XML elements
- they create.
-
- This specification defines a distinguished set of property names and
- XML elements that are understood by all WebDAV applications. The
- property names and XML elements in this specification are all derived
- from the base URI DAV: by adding a suffix to this URI, for example,
- DAV:creationdate for the "creationdate" property.
-
- This specification also defines a URI scheme for the encoding of lock
- tokens, the opaquelocktoken URI scheme described in section 6.4.
-
- To ensure correct interoperation based on this specification, IANA
- must reserve the URI namespaces starting with "DAV:" and with
- "opaquelocktoken:" for use by this specification, its revisions, and
- related WebDAV specifications.
-
-19 Intellectual Property
-
- The following notice is copied from RFC 2026 [RFC2026], section 10.4,
- and describes the position of the IETF concerning intellectual
- property claims made against this document.
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use other technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- IETF's procedures with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementors or users of this specification can
- be obtained from the IETF Secretariat.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights which may cover technology that may be required to practice
- this standard. Please address the information to the IETF Executive
- Director.
-
-
-
-
-Goland, et al. Standards Track [Page 81]
-
-RFC 2518 WEBDAV February 1999
-
-
-20 Acknowledgements
-
- A specification such as this thrives on piercing critical review and
- withers from apathetic neglect. The authors gratefully acknowledge
- the contributions of the following people, whose insights were so
- valuable at every stage of our work.
-
- Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
- Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
- Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
- Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
- Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
- Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
- Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
- Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
- Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
- Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
- Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
- Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
- Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
- Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
-
- Two from this list deserve special mention. The contributions by
- Larry Masinter have been invaluable, both in helping the formation of
- the working group and in patiently coaching the authors along the
- way. In so many ways he has set high standards we have toiled to
- meet. The contributions of Judith Slein in clarifying the
- requirements, and in patiently reviewing draft after draft, both
- improved this specification and expanded our minds on document
- management.
-
- We would also like to thank John Turner for developing the XML DTD.
-
-21 References
-
-21.1 Normative References
-
- [RFC1766] Alvestrand, H., "Tags for the Identification of
- Languages", RFC 1766, March 1995.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", BCP 18, RFC 2277, January 1998.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 82]
-
-RFC 2518 WEBDAV February 1999
-
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter,
- "Uniform Resource Identifiers (URI): Generic Syntax",
- RFC 2396, August 1998.
-
- [REC-XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen,
- "Extensible Markup Language (XML)." World Wide Web
- Consortium Recommendation REC-xml-19980210.
- http://www.w3.org/TR/1998/REC-xml-19980210.
-
- [REC-XML-NAMES] T. Bray, D. Hollander, A. Layman, "Namespaces in
- XML". World Wide Web Consortium Recommendation REC-
- xml-names-19990114. http://www.w3.org/TR/1999/REC-
- xml-names-19990114/
-
- [RFC2069] Franks, J., Hallam-Baker, P., Hostetler, J., Leach,
- P, Luotonen, A., Sink, E. and L. Stewart, "An
- Extension to HTTP : Digest Access Authentication",
- RFC 2069, January 1997.
-
- [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and
- T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2068, January 1997.
-
- [ISO-639] ISO (International Organization for Standardization).
- ISO 639:1988. "Code for the representation of names
- of languages."
-
- [ISO-8601] ISO (International Organization for Standardization).
- ISO 8601:1988. "Data elements and interchange formats
- - Information interchange - Representation of dates
- and times."
-
- [ISO-11578] ISO (International Organization for Standardization).
- ISO/IEC 11578:1996. "Information technology - Open
- Systems Interconnection - Remote Procedure Call
- (RPC)"
-
- [RFC2141] Moats, R., "URN Syntax", RFC 2141, May 1997.
-
- [UTF-8] Yergeau, F., "UTF-8, a transformation format of
- Unicode and ISO 10646", RFC 2279, January 1998.
-
-21.2 Informational References
-
- [RFC2026] Bradner, S., "The Internet Standards Process - Revision
- 3", BCP 9, RFC 2026, October 1996.
-
-
-
-
-
-Goland, et al. Standards Track [Page 83]
-
-RFC 2518 WEBDAV February 1999
-
-
- [RFC1807] Lasher, R. and D. Cohen, "A Format for Bibliographic
- Records", RFC 1807, June 1995.
-
- [WF] C. Lagoze, "The Warwick Framework: A Container
- Architecture for Diverse Sets of Metadata", D-Lib
- Magazine, July/August 1996.
- http://www.dlib.org/dlib/july96/lagoze/07lagoze.html
-
- [USMARC] Network Development and MARC Standards, Office, ed. 1994.
- "USMARC Format for Bibliographic Data", 1994. Washington,
- DC: Cataloging Distribution Service, Library of Congress.
-
- [REC-PICS] J. Miller, T. Krauskopf, P. Resnick, W. Treese, "PICS
- Label Distribution Label Syntax and Communication
- Protocols" Version 1.1, World Wide Web Consortium
- Recommendation REC-PICS-labels-961031.
- http://www.w3.org/pub/WWW/TR/REC-PICS-labels-961031.html.
-
- [RFC2291] Slein, J., Vitali, F., Whitehead, E. and D. Durand,
- "Requirements for Distributed Authoring and Versioning
- Protocol for the World Wide Web", RFC 2291, February 1998.
-
- [RFC2413] Weibel, S., Kunze, J., Lagoze, C. and M. Wolf, "Dublin
- Core Metadata for Resource Discovery", RFC 2413, September
- 1998.
-
- [RFC2376] Whitehead, E. and M. Murata, "XML Media Types", RFC 2376,
- July 1998.
-
-22 Authors' Addresses
-
- Y. Y. Goland
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052-6399
-
- EMail: yarong at microsoft.com
-
-
- E. J. Whitehead, Jr.
- Dept. Of Information and Computer Science
- University of California, Irvine
- Irvine, CA 92697-3425
-
- EMail: ejw at ics.uci.edu
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 84]
-
-RFC 2518 WEBDAV February 1999
-
-
- A. Faizi
- Netscape
- 685 East Middlefield Road
- Mountain View, CA 94043
-
- EMail: asad at netscape.com
-
-
- S. R. Carter
- Novell
- 1555 N. Technology Way
- M/S ORM F111
- Orem, UT 84097-2399
-
- EMail: srcarter at novell.com
-
-
- D. Jensen
- Novell
- 1555 N. Technology Way
- M/S ORM F111
- Orem, UT 84097-2399
-
- EMail: dcjensen at novell.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 85]
-
-RFC 2518 WEBDAV February 1999
-
-
-23 Appendices
-
-23.1 Appendix 1 - WebDAV Document Type Definition
-
- This section provides a document type definition, following the rules
- in [REC-XML], for the XML elements used in the protocol stream and in
- the values of properties. It collects the element definitions given
- in sections 12 and 13.
-
- <!DOCTYPE webdav-1.0 [
-
- <!--============ XML Elements from Section 12 ==================-->
-
- <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
- locktoken?) >
-
- <!ELEMENT lockentry (lockscope, locktype) >
- <!ELEMENT lockinfo (lockscope, locktype, owner?) >
-
- <!ELEMENT locktype (write) >
- <!ELEMENT write EMPTY >
-
- <!ELEMENT lockscope (exclusive | shared) >
- <!ELEMENT exclusive EMPTY >
- <!ELEMENT shared EMPTY >
-
- <!ELEMENT depth (#PCDATA) >
-
- <!ELEMENT owner ANY >
-
- <!ELEMENT timeout (#PCDATA) >
-
- <!ELEMENT locktoken (href+) >
-
- <!ELEMENT href (#PCDATA) >
-
- <!ELEMENT link (src+, dst+) >
- <!ELEMENT dst (#PCDATA) >
- <!ELEMENT src (#PCDATA) >
-
- <!ELEMENT multistatus (response+, responsedescription?) >
-
- <!ELEMENT response (href, ((href*, status)|(propstat+)),
- responsedescription?) >
- <!ELEMENT status (#PCDATA) >
- <!ELEMENT propstat (prop, status, responsedescription?) >
- <!ELEMENT responsedescription (#PCDATA) >
-
-
-
-
-Goland, et al. Standards Track [Page 86]
-
-RFC 2518 WEBDAV February 1999
-
-
- <!ELEMENT prop ANY >
-
- <!ELEMENT propertybehavior (omit | keepalive) >
- <!ELEMENT omit EMPTY >
-
- <!ELEMENT keepalive (#PCDATA | href+) >
-
- <!ELEMENT propertyupdate (remove | set)+ >
- <!ELEMENT remove (prop) >
- <!ELEMENT set (prop) >
-
- <!ELEMENT propfind (allprop | propname | prop) >
- <!ELEMENT allprop EMPTY >
- <!ELEMENT propname EMPTY >
-
- <!ELEMENT collection EMPTY >
-
- <!--=========== Property Elements from Section 13 ===============-->
- <!ELEMENT creationdate (#PCDATA) >
- <!ELEMENT displayname (#PCDATA) >
- <!ELEMENT getcontentlanguage (#PCDATA) >
- <!ELEMENT getcontentlength (#PCDATA) >
- <!ELEMENT getcontenttype (#PCDATA) >
- <!ELEMENT getetag (#PCDATA) >
- <!ELEMENT getlastmodified (#PCDATA) >
- <!ELEMENT lockdiscovery (activelock)* >
- <!ELEMENT resourcetype ANY >
- <!ELEMENT source (link)* >
- <!ELEMENT supportedlock (lockentry)* >
- ]>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 87]
-
-RFC 2518 WEBDAV February 1999
-
-
-23.2 Appendix 2 - ISO 8601 Date and Time Profile
-
- The creationdate property specifies the use of the ISO 8601 date
- format [ISO-8601]. This section defines a profile of the ISO 8601
- date format for use with this specification. This profile is quoted
- from an Internet-Draft by Chris Newman, and is mentioned here to
- properly attribute his work.
-
- date-time = full-date "T" full-time
-
- full-date = date-fullyear "-" date-month "-" date-mday
- full-time = partial-time time-offset
-
- date-fullyear = 4DIGIT
- date-month = 2DIGIT ; 01-12
- date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
- month/year
- time-hour = 2DIGIT ; 00-23
- time-minute = 2DIGIT ; 00-59
- time-second = 2DIGIT ; 00-59, 00-60 based on leap second rules
- time-secfrac = "." 1*DIGIT
- time-numoffset = ("+" / "-") time-hour ":" time-minute
- time-offset = "Z" / time-numoffset
-
- partial-time = time-hour ":" time-minute ":" time-second
- [time-secfrac]
-
- Numeric offsets are calculated as local time minus UTC (Coordinated
- Universal Time). So the equivalent time in UTC can be determined by
- subtracting the offset from the local time. For example, 18:50:00-
- 04:00 is the same time as 22:58:00Z.
-
- If the time in UTC is known, but the offset to local time is unknown,
- this can be represented with an offset of "-00:00". This differs
- from an offset of "Z" which implies that UTC is the preferred
- reference point for the specified time.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 88]
-
-RFC 2518 WEBDAV February 1999
-
-
-23.3 Appendix 3 - Notes on Processing XML Elements
-
-23.3.1 Notes on Empty XML Elements
-
- XML supports two mechanisms for indicating that an XML element does
- not have any content. The first is to declare an XML element of the
- form <A></A>. The second is to declare an XML element of the form
- <A/>. The two XML elements are semantically identical.
-
- It is a violation of the XML specification to use the <A></A> form if
- the associated DTD declares the element to be EMPTY (e.g., <!ELEMENT
- A EMPTY>). If such a statement is included, then the empty element
- format, <A/> must be used. If the element is not declared to be
- EMPTY, then either form <A></A> or <A/> may be used for empty
- elements.
-
- 23.3.2 Notes on Illegal XML Processing
-
- XML is a flexible data format that makes it easy to submit data that
- appears legal but in fact is not. The philosophy of "Be flexible in
- what you accept and strict in what you send" still applies, but it
- must not be applied inappropriately. XML is extremely flexible in
- dealing with issues of white space, element ordering, inserting new
- elements, etc. This flexibility does not require extension,
- especially not in the area of the meaning of elements.
-
- There is no kindness in accepting illegal combinations of XML
- elements. At best it will cause an unwanted result and at worst it
- can cause real damage.
-
-23.3.2.1 Example - XML Syntax Error
-
- The following request body for a PROPFIND method is illegal.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- <D:propname/>
- </D:propfind>
-
- The definition of the propfind element only allows for the allprop or
- the propname element, not both. Thus the above is an error and must
- be responded to with a 400 (Bad Request).
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 89]
-
-RFC 2518 WEBDAV February 1999
-
-
- Imagine, however, that a server wanted to be "kind" and decided to
- pick the allprop element as the true element and respond to it. A
- client running over a bandwidth limited line who intended to execute
- a propname would be in for a big surprise if the server treated the
- command as an allprop.
-
- Additionally, if a server were lenient and decided to reply to this
- request, the results would vary randomly from server to server, with
- some servers executing the allprop directive, and others executing
- the propname directive. This reduces interoperability rather than
- increasing it.
-
-23.3.2.2 Example - Unknown XML Element
-
- The previous example was illegal because it contained two elements
- that were explicitly banned from appearing together in the propfind
- element. However, XML is an extensible language, so one can imagine
- new elements being defined for use with propfind. Below is the
- request body of a PROPFIND and, like the previous example, must be
- rejected with a 400 (Bad Request) by a server that does not
- understand the expired-props element.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.foo.bar/standards/props/">
- <E:expired-props/>
- </D:propfind>
-
- To understand why a 400 (Bad Request) is returned let us look at the
- request body as the server unfamiliar with expired-props sees it.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.foo.bar/standards/props/">
- </D:propfind>
-
- As the server does not understand the expired-props element,
- according to the WebDAV-specific XML processing rules specified in
- section 14, it must ignore it. Thus the server sees an empty
- propfind, which by the definition of the propfind element is illegal.
-
- Please note that had the extension been additive it would not
- necessarily have resulted in a 400 (Bad Request). For example,
- imagine the following request body for a PROPFIND:
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.foo.bar/standards/props/">
-
-
-
-Goland, et al. Standards Track [Page 90]
-
-RFC 2518 WEBDAV February 1999
-
-
- <D:propname/>
- <E:leave-out>*boss*</E:leave-out>
- </D:propfind>
-
- The previous example contains the fictitious element leave-out. Its
- purpose is to prevent the return of any property whose name matches
- the submitted pattern. If the previous example were submitted to a
- server unfamiliar with leave-out, the only result would be that the
- leave-out element would be ignored and a propname would be executed.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 91]
-
-RFC 2518 WEBDAV February 1999
-
-
-23.4 Appendix 4 -- XML Namespaces for WebDAV
-
-23.4.1 Introduction
-
- All DAV compliant systems MUST support the XML namespace extensions
- as specified in [REC-XML-NAMES].
-
-23.4.2 Meaning of Qualified Names
-
- [Note to the reader: This section does not appear in [REC-XML-NAMES],
- but is necessary to avoid ambiguity for WebDAV XML processors.]
-
- WebDAV compliant XML processors MUST interpret a qualified name as a
- URI constructed by appending the LocalPart to the namespace name URI.
-
- Example
-
- <del:glider xmlns:del="http://www.del.jensen.org/">
- <del:glidername>
- Johnny Updraft
- </del:glidername>
- <del:glideraccidents/>
- </del:glider>
-
- In this example, the qualified element name "del:glider" is
- interpreted as the URL "http://www.del.jensen.org/glider".
-
- <bar:glider xmlns:del="http://www.del.jensen.org/">
- <bar:glidername>
- Johnny Updraft
- </bar:glidername>
- <bar:glideraccidents/>
- </bar:glider>
-
- Even though this example is syntactically different from the previous
- example, it is semantically identical. Each instance of the
- namespace name "bar" is replaced with "http://www.del.jensen.org/"
- and then appended to the local name for each element tag. The
- resulting tag names in this example are exactly the same as for the
- previous example.
-
- <foo:r xmlns:foo="http://www.del.jensen.org/glide">
- <foo:rname>
- Johnny Updraft
- </foo:rname>
- <foo:raccidents/>
- </foo:r>
-
-
-
-
-Goland, et al. Standards Track [Page 92]
-
-RFC 2518 WEBDAV February 1999
-
-
- This example is semantically identical to the two previous ones.
- Each instance of the namespace name "foo" is replaced with
- "http://www.del.jensen.org/glide" which is then appended to the local
- name for each element tag, the resulting tag names are identical to
- those in the previous examples.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 93]
-
-RFC 2518 WEBDAV February 1999
-
-
-24. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Goland, et al. Standards Track [Page 94]
-
Copied: CalendarServer/trunk/doc/RFC/rfc2518bis-WebDAV.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2518bis.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2518bis-WebDAV.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2518bis-WebDAV.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,8066 @@
+
+
+
+
+WebDAV L. Dusseault, Ed.
+Internet-Draft OSAF
+Obsoletes: 2518 (if approved) April 2006
+Expires: October 3, 2006
+
+
+ HTTP Extensions for Distributed Authoring - WebDAV
+ draft-ietf-webdav-rfc2518bis-15
+
+Status of this Memo
+
+ By submitting this Internet-Draft, each author represents that any
+ applicable patent or other IPR claims of which he or she is aware
+ have been or will be disclosed, and any of which he or she becomes
+ aware will be disclosed, in accordance with Section 6 of BCP 79.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt.
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This Internet-Draft will expire on October 3, 2006.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2006).
+
+Abstract
+
+ WebDAV consists of a set of methods, headers, and content-types
+ ancillary to HTTP/1.1 for the management of resource properties,
+ creation and management of resource collections, URL namespace
+ manipulation, and resource locking (collision avoidance).
+
+ RFC2518 was published in February 1999, and this specification makes
+ minor revisions mostly due to interoperability experience.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 1]
+
+Internet-Draft WebDAV April 2006
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 9
+ 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 4. Data Model for Resource Properties . . . . . . . . . . . . . 12
+ 4.1. The Resource Property Model . . . . . . . . . . . . . . 12
+ 4.2. Properties and HTTP Headers . . . . . . . . . . . . . . 12
+ 4.3. Property Values . . . . . . . . . . . . . . . . . . . . 12
+ 4.3.1. Example - Property with Mixed Content . . . . . . . 14
+ 4.4. Property Names . . . . . . . . . . . . . . . . . . . . . 16
+ 4.5. Source Resources and Output Resources . . . . . . . . . 16
+ 5. Collections of Web Resources . . . . . . . . . . . . . . . . 17
+ 5.1. HTTP URL Namespace Model . . . . . . . . . . . . . . . . 17
+ 5.2. Collection Resources . . . . . . . . . . . . . . . . . . 17
+ 6. Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
+ 6.1. Lock Model . . . . . . . . . . . . . . . . . . . . . . . 20
+ 6.2. Exclusive Vs. Shared Locks . . . . . . . . . . . . . . . 21
+ 6.3. Required Support . . . . . . . . . . . . . . . . . . . . 22
+ 6.4. Lock Creator and Privileges . . . . . . . . . . . . . . 22
+ 6.5. Lock Tokens . . . . . . . . . . . . . . . . . . . . . . 23
+ 6.6. Lock Timeout . . . . . . . . . . . . . . . . . . . . . . 24
+ 6.7. Lock Capability Discovery . . . . . . . . . . . . . . . 24
+ 6.8. Active Lock Discovery . . . . . . . . . . . . . . . . . 25
+ 7. Write Lock . . . . . . . . . . . . . . . . . . . . . . . . . 26
+ 7.1. Write Locks and Properties . . . . . . . . . . . . . . . 26
+ 7.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . 27
+ 7.3. Write Locks and Unmapped URLs . . . . . . . . . . . . . 28
+ 7.4. Write Locks and Collections . . . . . . . . . . . . . . 29
+ 7.5. Write Locks and the If Request Header . . . . . . . . . 30
+ 7.5.1. Example - Write Lock and COPY . . . . . . . . . . . 31
+ 7.5.2. Example - Deleting a member of a locked collection . 31
+ 7.6. Write Locks and COPY/MOVE . . . . . . . . . . . . . . . 32
+ 7.7. Refreshing Write Locks . . . . . . . . . . . . . . . . . 33
+ 8. General Request and Response Handling . . . . . . . . . . . . 34
+ 8.1. Precedence in Error Handling . . . . . . . . . . . . . . 34
+ 8.2. Use of XML . . . . . . . . . . . . . . . . . . . . . . . 34
+ 8.3. URL Handling . . . . . . . . . . . . . . . . . . . . . . 35
+ 8.3.1. Example - Correct URL Handling . . . . . . . . . . . 35
+ 8.4. Required Bodies in Requests . . . . . . . . . . . . . . 36
+ 8.5. HTTP Headers for use in WebDAV . . . . . . . . . . . . . 36
+ 8.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . 36
+ 8.7. Including error response bodies . . . . . . . . . . . . 37
+ 8.8. Impact of Namespace Operations on Cache Validators . . . 37
+ 9. HTTP Methods for Distributed Authoring . . . . . . . . . . . 39
+ 9.1. PROPFIND Method . . . . . . . . . . . . . . . . . . . . 39
+ 9.1.1. PROPFIND status codes . . . . . . . . . . . . . . . 40
+ 9.1.2. Status Codes for use in 'propstat' Element . . . . . 41
+
+
+
+Dusseault Expires October 3, 2006 [Page 2]
+
+Internet-Draft WebDAV April 2006
+
+
+ 9.1.3. Example - Retrieving Named Properties . . . . . . . 41
+ 9.1.4. Example - Using so-called 'allprop' . . . . . . . . 43
+ 9.1.5. Example - Using 'propname' to Retrieve all
+ Property Names . . . . . . . . . . . . . . . . . . . 43
+ 9.1.6. Example - Using 'allprop' . . . . . . . . . . . . . 45
+ 9.2. PROPPATCH Method . . . . . . . . . . . . . . . . . . . . 47
+ 9.2.1. Status Codes for use in 'propstat' Element . . . . . 48
+ 9.2.2. Example - PROPPATCH . . . . . . . . . . . . . . . . 49
+ 9.3. MKCOL Method . . . . . . . . . . . . . . . . . . . . . . 50
+ 9.3.1. MKCOL Status Codes . . . . . . . . . . . . . . . . . 51
+ 9.3.2. Example - MKCOL . . . . . . . . . . . . . . . . . . 51
+ 9.4. GET, HEAD for Collections . . . . . . . . . . . . . . . 52
+ 9.5. POST for Collections . . . . . . . . . . . . . . . . . . 52
+ 9.6. DELETE Requirements . . . . . . . . . . . . . . . . . . 52
+ 9.6.1. DELETE for Collections . . . . . . . . . . . . . . . 53
+ 9.6.2. Example - DELETE . . . . . . . . . . . . . . . . . . 53
+ 9.7. PUT Requirements . . . . . . . . . . . . . . . . . . . . 54
+ 9.7.1. PUT for Non-Collection Resources . . . . . . . . . . 54
+ 9.7.2. PUT for Collections . . . . . . . . . . . . . . . . 55
+ 9.8. COPY Method . . . . . . . . . . . . . . . . . . . . . . 55
+ 9.8.1. COPY for Non-collection Resources . . . . . . . . . 55
+ 9.8.2. COPY for Properties . . . . . . . . . . . . . . . . 56
+ 9.8.3. COPY for Collections . . . . . . . . . . . . . . . . 56
+ 9.8.4. COPY and Overwriting Destination Resources . . . . . 57
+ 9.8.5. Status Codes . . . . . . . . . . . . . . . . . . . . 58
+ 9.8.6. Example - COPY with Overwrite . . . . . . . . . . . 59
+ 9.8.7. Example - COPY with No Overwrite . . . . . . . . . . 59
+ 9.8.8. Example - COPY of a Collection . . . . . . . . . . . 60
+ 9.9. MOVE Method . . . . . . . . . . . . . . . . . . . . . . 60
+ 9.9.1. MOVE for Properties . . . . . . . . . . . . . . . . 61
+ 9.9.2. MOVE for Collections . . . . . . . . . . . . . . . . 61
+ 9.9.3. MOVE and the Overwrite Header . . . . . . . . . . . 62
+ 9.9.4. Status Codes . . . . . . . . . . . . . . . . . . . . 62
+ 9.9.5. Example - MOVE of a Non-Collection . . . . . . . . . 63
+ 9.9.6. Example - MOVE of a Collection . . . . . . . . . . . 64
+ 9.10. LOCK Method . . . . . . . . . . . . . . . . . . . . . . 65
+ 9.10.1. Creating a lock on existing resource . . . . . . . . 65
+ 9.10.2. Refreshing Locks . . . . . . . . . . . . . . . . . . 65
+ 9.10.3. Depth and Locking . . . . . . . . . . . . . . . . . 66
+ 9.10.4. Locking Unmapped URLs . . . . . . . . . . . . . . . 66
+ 9.10.5. Lock Compatibility Table . . . . . . . . . . . . . . 67
+ 9.10.6. LOCK Responses . . . . . . . . . . . . . . . . . . . 67
+ 9.10.7. Example - Simple Lock Request . . . . . . . . . . . 68
+ 9.10.8. Example - Refreshing a Write Lock . . . . . . . . . 70
+ 9.10.9. Example - Multi-Resource Lock Request . . . . . . . 71
+ 9.11. UNLOCK Method . . . . . . . . . . . . . . . . . . . . . 72
+ 9.11.1. Status Codes . . . . . . . . . . . . . . . . . . . . 72
+ 9.11.2. Example - UNLOCK . . . . . . . . . . . . . . . . . . 73
+
+
+
+Dusseault Expires October 3, 2006 [Page 3]
+
+Internet-Draft WebDAV April 2006
+
+
+ 10. HTTP Headers for Distributed Authoring . . . . . . . . . . . 74
+ 10.1. DAV Header . . . . . . . . . . . . . . . . . . . . . . . 74
+ 10.2. Depth Header . . . . . . . . . . . . . . . . . . . . . . 75
+ 10.3. Destination Header . . . . . . . . . . . . . . . . . . . 76
+ 10.4. If Header . . . . . . . . . . . . . . . . . . . . . . . 76
+ 10.4.1. Purpose . . . . . . . . . . . . . . . . . . . . . . 76
+ 10.4.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 77
+ 10.4.3. List Evaluation . . . . . . . . . . . . . . . . . . 78
+ 10.4.4. Matching State Tokens and ETags . . . . . . . . . . 78
+ 10.4.5. If Header and Non-DAV Aware Proxies . . . . . . . . 79
+ 10.4.6. Example - No-tag Production . . . . . . . . . . . . 79
+ 10.4.7. Example - using "Not" with No-tag Production . . . . 79
+ 10.4.8. Example - causing a Condition to always evaluate
+ to True . . . . . . . . . . . . . . . . . . . . . . 80
+ 10.4.9. Example - Tagged List If header in COPY . . . . . . 80
+ 10.4.10. Example - Matching lock tokens with collection
+ locks . . . . . . . . . . . . . . . . . . . . . . . 80
+ 10.4.11. Example - Matching ETags on unmapped URLs . . . . . 81
+ 10.5. Lock-Token Header . . . . . . . . . . . . . . . . . . . 81
+ 10.6. Overwrite Header . . . . . . . . . . . . . . . . . . . . 81
+ 10.7. Timeout Request Header . . . . . . . . . . . . . . . . . 82
+ 11. Status Code Extensions to HTTP/1.1 . . . . . . . . . . . . . 83
+ 11.1. 207 Multi-Status . . . . . . . . . . . . . . . . . . . . 83
+ 11.2. 422 Unprocessable Entity . . . . . . . . . . . . . . . . 83
+ 11.3. 423 Locked . . . . . . . . . . . . . . . . . . . . . . . 83
+ 11.4. 424 Failed Dependency . . . . . . . . . . . . . . . . . 83
+ 11.5. 507 Insufficient Storage . . . . . . . . . . . . . . . . 83
+ 12. Use of HTTP Status Codes . . . . . . . . . . . . . . . . . . 84
+ 12.1. 412 Precondition Failed . . . . . . . . . . . . . . . . 84
+ 12.2. 414 Request-URI Too Long . . . . . . . . . . . . . . . . 84
+ 13. Multi-Status Response . . . . . . . . . . . . . . . . . . . . 85
+ 13.1. Response headers . . . . . . . . . . . . . . . . . . . . 85
+ 13.2. Handling redirected child resources . . . . . . . . . . 86
+ 13.3. Internal Status Codes . . . . . . . . . . . . . . . . . 86
+ 14. XML Element Definitions . . . . . . . . . . . . . . . . . . . 87
+ 14.1. activelock XML Element . . . . . . . . . . . . . . . . . 87
+ 14.2. allprop XML Element . . . . . . . . . . . . . . . . . . 87
+ 14.3. collection XML Element . . . . . . . . . . . . . . . . . 87
+ 14.4. depth XML Element . . . . . . . . . . . . . . . . . . . 87
+ 14.5. error XML Element . . . . . . . . . . . . . . . . . . . 88
+ 14.6. exclusive XML Element . . . . . . . . . . . . . . . . . 88
+ 14.7. href XML Element . . . . . . . . . . . . . . . . . . . . 88
+ 14.8. include XML Element . . . . . . . . . . . . . . . . . . 89
+ 14.9. location XML Element . . . . . . . . . . . . . . . . . . 89
+ 14.10. lockentry XML Element . . . . . . . . . . . . . . . . . 89
+ 14.11. lockinfo XML Element . . . . . . . . . . . . . . . . . . 89
+ 14.12. lockroot XML Element . . . . . . . . . . . . . . . . . . 90
+ 14.13. lockscope XML Element . . . . . . . . . . . . . . . . . 90
+
+
+
+Dusseault Expires October 3, 2006 [Page 4]
+
+Internet-Draft WebDAV April 2006
+
+
+ 14.14. locktoken XML Element . . . . . . . . . . . . . . . . . 90
+ 14.15. locktype XML Element . . . . . . . . . . . . . . . . . . 90
+ 14.16. multistatus XML Element . . . . . . . . . . . . . . . . 91
+ 14.17. owner XML Element . . . . . . . . . . . . . . . . . . . 91
+ 14.18. prop XML element . . . . . . . . . . . . . . . . . . . . 91
+ 14.19. propertyupdate XML element . . . . . . . . . . . . . . . 92
+ 14.20. propfind XML Element . . . . . . . . . . . . . . . . . . 92
+ 14.21. propname XML Element . . . . . . . . . . . . . . . . . . 92
+ 14.22. propstat XML Element . . . . . . . . . . . . . . . . . . 92
+ 14.23. remove XML element . . . . . . . . . . . . . . . . . . . 93
+ 14.24. response XML Element . . . . . . . . . . . . . . . . . . 93
+ 14.25. responsedescription XML Element . . . . . . . . . . . . 94
+ 14.26. set XML element . . . . . . . . . . . . . . . . . . . . 94
+ 14.27. shared XML Element . . . . . . . . . . . . . . . . . . . 94
+ 14.28. status XML Element . . . . . . . . . . . . . . . . . . . 94
+ 14.29. timeout XML Element . . . . . . . . . . . . . . . . . . 95
+ 14.30. write XML Element . . . . . . . . . . . . . . . . . . . 95
+ 15. DAV Properties . . . . . . . . . . . . . . . . . . . . . . . 96
+ 15.1. creationdate Property . . . . . . . . . . . . . . . . . 96
+ 15.2. displayname Property . . . . . . . . . . . . . . . . . . 97
+ 15.3. getcontentlanguage Property . . . . . . . . . . . . . . 97
+ 15.4. getcontentlength Property . . . . . . . . . . . . . . . 98
+ 15.5. getcontenttype Property . . . . . . . . . . . . . . . . 98
+ 15.6. getetag Property . . . . . . . . . . . . . . . . . . . . 99
+ 15.7. getlastmodified Property . . . . . . . . . . . . . . . . 99
+ 15.8. lockdiscovery Property . . . . . . . . . . . . . . . . . 100
+ 15.8.1. Example - Retrieving DAV:lockdiscovery . . . . . . . 101
+ 15.9. resourcetype Property . . . . . . . . . . . . . . . . . 102
+ 15.10. supportedlock Property . . . . . . . . . . . . . . . . . 103
+ 15.10.1. Example - Retrieving DAV:supportedlock . . . . . . . 104
+ 16. Precondition/postcondition XML elements . . . . . . . . . . . 105
+ 17. XML Extensibility in DAV . . . . . . . . . . . . . . . . . . 109
+ 18. DAV Compliance Classes . . . . . . . . . . . . . . . . . . . 111
+ 18.1. Class 1 . . . . . . . . . . . . . . . . . . . . . . . . 111
+ 18.2. Class 2 . . . . . . . . . . . . . . . . . . . . . . . . 111
+ 18.3. Class 3 . . . . . . . . . . . . . . . . . . . . . . . . 111
+ 19. Internationalization Considerations . . . . . . . . . . . . . 113
+ 20. Security Considerations . . . . . . . . . . . . . . . . . . . 115
+ 20.1. Authentication of Clients . . . . . . . . . . . . . . . 115
+ 20.2. Denial of Service . . . . . . . . . . . . . . . . . . . 115
+ 20.3. Security through Obscurity . . . . . . . . . . . . . . . 116
+ 20.4. Privacy Issues Connected to Locks . . . . . . . . . . . 116
+ 20.5. Privacy Issues Connected to Properties . . . . . . . . . 116
+ 20.6. Implications of XML Entities . . . . . . . . . . . . . . 117
+ 20.7. Risks Connected with Lock Tokens . . . . . . . . . . . . 118
+ 20.8. Hosting Malicious Content . . . . . . . . . . . . . . . 118
+ 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 119
+ 21.1. New URI Schemes . . . . . . . . . . . . . . . . . . . . 119
+
+
+
+Dusseault Expires October 3, 2006 [Page 5]
+
+Internet-Draft WebDAV April 2006
+
+
+ 21.2. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 119
+ 21.3. Message Header Fields . . . . . . . . . . . . . . . . . 119
+ 21.3.1. DAV . . . . . . . . . . . . . . . . . . . . . . . . 119
+ 21.3.2. Depth . . . . . . . . . . . . . . . . . . . . . . . 119
+ 21.3.3. Destination . . . . . . . . . . . . . . . . . . . . 120
+ 21.3.4. If . . . . . . . . . . . . . . . . . . . . . . . . . 120
+ 21.3.5. Lock-Token . . . . . . . . . . . . . . . . . . . . . 120
+ 21.3.6. Overwrite . . . . . . . . . . . . . . . . . . . . . 120
+ 21.3.7. Timeout . . . . . . . . . . . . . . . . . . . . . . 121
+ 22. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 122
+ 23. Contributors to This Specification . . . . . . . . . . . . . 124
+ 24. Authors of RFC2518 . . . . . . . . . . . . . . . . . . . . . 125
+ 25. References . . . . . . . . . . . . . . . . . . . . . . . . . 126
+ 25.1. Normative References . . . . . . . . . . . . . . . . . . 126
+ 25.2. Informational References . . . . . . . . . . . . . . . . 127
+ Appendix A. Notes on Processing XML Elements . . . . . . . . . . 128
+ A.1. Notes on Empty XML Elements . . . . . . . . . . . . . . 128
+ A.2. Notes on Illegal XML Processing . . . . . . . . . . . . 128
+ A.3. Example - XML Syntax Error . . . . . . . . . . . . . . . 128
+ A.4. Example - Unexpected XML Element . . . . . . . . . . . . 129
+ Appendix B. Notes on HTTP Client Compatibility . . . . . . . . . 130
+ Appendix C. The opaquelocktoken scheme and URIs . . . . . . . . 131
+ Appendix D. Lock-null Resources . . . . . . . . . . . . . . . . 132
+ Appendix E. Guidance for Clients Desiring to Authenticate . . . 133
+ Appendix F. Summary of changes from RFC2518 . . . . . . . . . . 135
+ F.1. Changes for both Client and Server Implementations . . . 135
+ F.2. Changes for Server Implementations . . . . . . . . . . . 136
+ F.3. Other Changes . . . . . . . . . . . . . . . . . . . . . 137
+ Appendix G. Change Log (to be removed by RFC Editor before
+ publication) . . . . . . . . . . . . . . . . . . . . 138
+ G.1. Changes from -05 to -06 . . . . . . . . . . . . . . . . 138
+ G.2. Changes in -07 . . . . . . . . . . . . . . . . . . . . . 138
+ G.3. Changes in -08 . . . . . . . . . . . . . . . . . . . . . 139
+ G.4. Changes in -09 . . . . . . . . . . . . . . . . . . . . . 140
+ G.5. Changes in -10 . . . . . . . . . . . . . . . . . . . . . 141
+ G.6. Changes in -11 . . . . . . . . . . . . . . . . . . . . . 141
+ G.7. Changes in -12 . . . . . . . . . . . . . . . . . . . . . 141
+ G.8. Changes in -13 . . . . . . . . . . . . . . . . . . . . . 142
+ G.9. Changes in -14 . . . . . . . . . . . . . . . . . . . . . 142
+ G.10. Changes in -15 . . . . . . . . . . . . . . . . . . . . . 142
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 143
+ Intellectual Property and Copyright Statements . . . . . . . . . 144
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 6]
+
+Internet-Draft WebDAV April 2006
+
+
+1. Introduction
+
+ This document describes an extension to the HTTP/1.1 protocol that
+ allows clients to perform remote web content authoring operations.
+ This extension provides a coherent set of methods, headers, request
+ entity body formats, and response entity body formats that provide
+ operations for:
+
+ Properties: The ability to create, remove, and query information
+ about Web pages, such as their authors, creation dates, etc.
+
+ Collections: The ability to create sets of documents and to retrieve
+ a hierarchical membership listing (like a directory listing in a file
+ system).
+
+ Locking: The ability to keep more than one person from working on a
+ document at the same time. This prevents the "lost update problem",
+ in which modifications are lost as first one author then another
+ writes changes without merging the other author's changes.
+
+ Namespace Operations: The ability to instruct the server to copy and
+ move Web resources, operations which change the mapping from URLs to
+ resources.
+
+ Requirements and rationale for these operations are described in a
+ companion document, "Requirements for a Distributed Authoring and
+ Versioning Protocol for the World Wide Web" [RFC2291].
+
+ This document does not specify the versioning operations suggested by
+ [RFC2291]. That work was done in a separate document, "Versioning
+ Extensions to WebDAV" [RFC3253].
+
+ The sections below provide a detailed introduction to various WebDAV
+ abstractions: resource properties (Section 4), collections of
+ resources (Section 5), locks (Section 6) in general and write locks
+ (Section 7) specifically.
+
+ These abstractions are manipulated by the WebDAV-specific HTTP
+ methods (Section 9) and the new HTTP headers (Section 10) used with
+ WebDAV methods. General considerations for handling HTTP requests
+ and responses in WebDAV are found in Section 8.
+
+ While the status codes provided by HTTP/1.1 are sufficient to
+ describe most error conditions encountered by WebDAV methods, there
+ are some errors that do not fall neatly into the existing categories.
+ This specification defines new status codes developed for WebDAV
+ methods (Section 11) and describes existing HTTP status codes
+ (Section 12) as used in WebDAV. Since some WebDAV methods may
+
+
+
+Dusseault Expires October 3, 2006 [Page 7]
+
+Internet-Draft WebDAV April 2006
+
+
+ operate over many resources, the Multi-Status response (Section 13)
+ has been introduced to return status information for multiple
+ resources. Finally, this version of WebDAV introduces precondition
+ and postcondition (Section 16) XML elements in error response bodies.
+
+ WebDAV uses XML ([REC-XML]) for property names and some values, and
+ also uses XML to marshal complicated request and response. This
+ specification contains DTD and text definitions of all all properties
+ (Section 15) and all other XML elements (Section 14) used in
+ marshalling. WebDAV includes a few special rules on extending
+ (Section 17) WebDAV XML marshalling in backwards-compatible ways.
+
+ Finishing off the specification are sections on what it means for a
+ resource to be compliant with this specification (Section 18), on
+ internationalization support (Section 19), and on security
+ (Section 20).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 8]
+
+Internet-Draft WebDAV April 2006
+
+
+2. Notational Conventions
+
+ Since this document describes a set of extensions to the HTTP/1.1
+ protocol, the augmented BNF used herein to describe protocol elements
+ is exactly the same as described in Section 2.1 of [RFC2616],
+ including the rules about implied linear white-space. Since this
+ augmented BNF uses the basic production rules provided in Section 2.2
+ of [RFC2616], these rules apply to this document as well.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ Note that in natural language, a property like the "creationdate"
+ property in the "DAV:" XML namespace is sometimes referred to as
+ "DAV:creationdate" for brevity.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 9]
+
+Internet-Draft WebDAV April 2006
+
+
+3. Terminology
+
+ URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
+ respectively. These terms (and the distinction between them) are
+ defined in [RFC3986].
+
+ URI/URL Mapping - A relation between an absolute URI and a resource.
+ Since a resource can represent items that are not network
+ retrievable, as well as those that are, it is possible for a resource
+ to have zero, one, or many URI mappings. Mapping a resource to an
+ "http" scheme URI makes it possible to submit HTTP protocol requests
+ to the resource using the URI.
+
+ Path Segment - Informally, the characters found between slashes ("/")
+ in a URI. Formally, as defined in Section 3.3 of [RFC3986].
+
+ Collection - Informally, a resource that also acts as a container of
+ references to child resources. Formally, a resource that contains a
+ set of mappings between path segments and resources and meets the
+ requirements defined in Section 5.
+
+ Internal Member (of a Collection) - Informally, a child resource of a
+ collection. Formally, a resource referenced by a path segment
+ mapping contained in the collection.
+
+ Internal Member URL (of a Collection) - A URL of an internal member,
+ consisting of the URL of the collection (including trailing slash)
+ plus the path segment identifying the internal member.
+
+ Member (of a Collection) - Informally, a "descendant" of a
+ collection. Formally, an internal member of the collection, or,
+ recursively, a member of an internal member.
+
+ Member URL (of a Collection) - A URL that is either an internal
+ member URL of the collection itself, or is an internal member URL of
+ a member of that collection.
+
+ Property - A name/value pair that contains descriptive information
+ about a resource.
+
+ Live Property - A property whose semantics and syntax are enforced by
+ the server. For example, the live property DAV:getcontentlength has
+ its value, the length of the entity returned by a GET request,
+ automatically calculated by the server.
+
+ Dead Property - A property whose semantics and syntax are not
+ enforced by the server. The server only records the value of a dead
+ property; the client is responsible for maintaining the consistency
+
+
+
+Dusseault Expires October 3, 2006 [Page 10]
+
+Internet-Draft WebDAV April 2006
+
+
+ of the syntax and semantics of a dead property.
+
+ Principal - A "principal" is a distinct human or computational actor
+ that initiates access to network resources.
+
+ State Token - A URI which represents a state of a resource. Lock
+ tokens are the only state tokens defined in this specification.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 11]
+
+Internet-Draft WebDAV April 2006
+
+
+4. Data Model for Resource Properties
+
+4.1. The Resource Property Model
+
+ Properties are pieces of data that describe the state of a resource.
+ Properties are data about data.
+
+ Properties are used in distributed authoring environments to provide
+ for efficient discovery and management of resources. For example, a
+ 'subject' property might allow for the indexing of all resources by
+ their subject, and an 'author' property might allow for the discovery
+ of what authors have written which documents.
+
+ The DAV property model consists of name/value pairs. The name of a
+ property identifies the property's syntax and semantics, and provides
+ an address by which to refer to its syntax and semantics.
+
+ There are two categories of properties: "live" and "dead". A live
+ property has its syntax and semantics enforced by the server. Live
+ properties include cases where a) the value of a property is
+ protected, maintained by the server, and b) the value of the property
+ is maintained by the client, but the server performs syntax checking
+ on submitted values. All instances of a given live property MUST
+ comply with the definition associated with that property name. A
+ dead property has its syntax and semantics enforced by the client;
+ the server merely records the value of the property verbatim.
+
+4.2. Properties and HTTP Headers
+
+ Properties already exist, in a limited sense, in HTTP message
+ headers. However, in distributed authoring environments a relatively
+ large number of properties are needed to describe the state of a
+ resource, and setting/returning them all through HTTP headers is
+ inefficient. Thus a mechanism is needed which allows a principal to
+ identify a set of properties in which the principal is interested and
+ to set or retrieve just those properties.
+
+4.3. Property Values
+
+ The value of a property is always a (well-formed) XML fragment.
+
+ XML has been chosen because it is a flexible, self-describing,
+ structured data format that supports rich schema definitions, and
+ because of its support for multiple character sets. XML's self-
+ describing nature allows any property's value to be extended by
+ adding new elements. Older clients will not break when they
+ encounter extensions because they will still have the data specified
+ in the original schema and MUST ignore elements they do not
+
+
+
+Dusseault Expires October 3, 2006 [Page 12]
+
+Internet-Draft WebDAV April 2006
+
+
+ understand.
+
+ XML's support for multiple character sets allows any human-readable
+ property to be encoded and read in a character set familiar to the
+ user. XML's support for multiple human languages, using the "xml:
+ lang" attribute, handles cases where the same character set is
+ employed by multiple human languages. Note that xml:lang scope is
+ recursive, so an xml:lang attribute on any element containing a
+ property name element applies to the property value unless it has
+ been overridden by a more locally scoped attribute. Note that a
+ property only has one value, in one language (or language MAY be left
+ undefined), not multiple values in different languages or a single
+ value in multiple languages.
+
+ A property is always represented with an XML element consisting of
+ the property name, called the "property name element". The simplest
+ example is an empty property, which is different from a property that
+ does not exist:
+
+ <R:title xmlns:R="http://www.example.com/ns/"></R:title>
+
+ The value of the property appears inside the property name element.
+ The value may be any kind of well-formed XML content, including both
+ text-only and mixed content. Servers MUST preserve the following XML
+ Information Items (using the terminology from [REC-XML-INFOSET]) in
+ storage and transmission of dead properties:
+
+ For the property name Element Information Item itself:
+
+ [namespace name]
+
+ [local name]
+
+ [attributes] named "xml:lang" or any such attribute in scope
+
+ [children] of type element or character
+
+ On all Element Information Items in the property value:
+
+ [namespace name]
+
+ [local name]
+
+ [attributes]
+
+ [children] of type element or character
+
+ On Attribute Information Items in the property value:
+
+
+
+Dusseault Expires October 3, 2006 [Page 13]
+
+Internet-Draft WebDAV April 2006
+
+
+ [namespace name]
+
+ [local name]
+
+ [normalized value]
+
+ On Character Information Items in the property value:
+
+ [character code]
+
+ Since prefixes are used in some XML vocabularies (XPath and XML
+ Schema, for example), servers SHOULD preserve, for any Information
+ Item in the value:
+
+ [prefix]
+
+ XML Infoset attributes not listed above MAY be preserved by the
+ server, but clients MUST NOT rely on them being preserved. The above
+ rules would also apply by default to live properties, unless defined
+ otherwise.
+
+ Servers MUST ignore the XML attribute xml:space if present and never
+ use it to change white space handling. White space in property
+ values is significant.
+
+4.3.1. Example - Property with Mixed Content
+
+ Consider a dead property 'author' created by the client as follows:
+
+ <D:prop xml:lang="en" xmlns:D="DAV:">
+ <x:author xmlns:x='http://example.com/ns'>
+ <x:name>Jane Doe</x:name>
+ <!-- Jane's contact info -->
+ <x:uri type='email'
+ added='2005-11-26'>mailto:jane.doe at example.com</x:uri>
+ <x:uri type='web'
+ added='2005-11-27'>http://www.example.com</x:uri>
+ <x:notes xmlns:h='http://www.w3.org/1999/xhtml'>
+ Jane has been working way <h:em>too</h:em> long on the
+ long-awaited revision of <![CDATA[<RFC2518>]]>.
+ </x:notes>
+ </x:author>
+ </D:prop>
+
+ When this property is requested, a server might return:
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 14]
+
+Internet-Draft WebDAV April 2006
+
+
+ <D:prop xmlns:D='DAV:'><author
+ xml:lang='en'
+ xmlns:x='http://example.com/ns'
+ xmlns='http://example.com/ns'
+ xmlns:h='http://www.w3.org/1999/xhtml'>
+ <x:name>Jane Doe</x:name>
+ <x:uri added="2005-11-26" type="email"
+ >mailto:jane.doe at example.com</x:uri>
+ <x:uri added="2005-11-27" type="web"
+ >http://www.example.com</x:uri>
+ <x:notes>
+ Jane has been working way <h:em>too</h:em> long on the
+ long-awaited revision of <RFC2518>.
+ </x:notes>
+ </author>
+ </D:prop>
+
+ Note in this example:
+
+ o The [prefix] for the property name itself was not preserved, being
+ non-significant, all other [prefix] values have been preserved,
+
+ o attribute values have been rewritten with double quotes instead of
+ single quotes (quoting style is not significant), and attribute
+ order has not been preserved,
+
+ o the xml:lang attribute has been returned on the property name
+ element itself (it was in scope when the property was set, but the
+ exact position in the response is not considered significant as
+ long as it is in scope),
+
+ o whitespace between tags has been preserved everywhere (whitespace
+ between attributes not so),
+
+ o CDATA encapsulation was replaced with character escaping (the
+ reverse would also be legal),
+
+ o the comment item was stripped (as would have been a processing
+ instruction item).
+
+ Implementation note: there are cases such as editing scenarios where
+ clients may require that XML content is preserved character-by-
+ character (such as attribute ordering or quoting style). In this
+ case, clients should consider using a text-only property value by
+ escaping all characters that have a special meaning in XML parsing.
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 15]
+
+Internet-Draft WebDAV April 2006
+
+
+4.4. Property Names
+
+ A property name is a universally unique identifier that is associated
+ with a schema that provides information about the syntax and
+ semantics of the property.
+
+ Because a property's name is universally unique, clients can depend
+ upon consistent behavior for a particular property across multiple
+ resources, on the same and across different servers, so long as that
+ property is "live" on the resources in question, and the
+ implementation of the live property is faithful to its definition.
+
+ The XML namespace mechanism, which is based on URIs ([RFC3986]), is
+ used to name properties because it prevents namespace collisions and
+ provides for varying degrees of administrative control.
+
+ The property namespace is flat; that is, no hierarchy of properties
+ is explicitly recognized. Thus, if a property A and a property A/B
+ exist on a resource, there is no recognition of any relationship
+ between the two properties. It is expected that a separate
+ specification will eventually be produced which will address issues
+ relating to hierarchical properties.
+
+ Finally, it is not possible to define the same property twice on a
+ single resource, as this would cause a collision in the resource's
+ property namespace.
+
+4.5. Source Resources and Output Resources
+
+ Some HTTP resources are dynamically generated by the server. For
+ these resources, there presumably exists source code somewhere
+ governing how that resource is generated. The relationship of source
+ files to output HTTP resources may be one to one, one to many, many
+ to one or many to many. There is no mechanism in HTTP to determine
+ whether a resource is even dynamic, let alone where its source files
+ exist or how to author them. Although this problem would usefully be
+ solved, interoperable WebDAV implementations have been widely
+ deployed without actually solving this problem, by dealing only with
+ static resources. Thus, the source vs. output problem is not solved
+ in this specification and has been deferred to a separate document.
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 16]
+
+Internet-Draft WebDAV April 2006
+
+
+5. Collections of Web Resources
+
+ This section provides a description of a new type of Web resource,
+ the collection, and discusses its interactions with the HTTP URL
+ namespace. The purpose of a collection resource is to model
+ collection-like objects (e.g., file system directories) within a
+ server's namespace.
+
+ All DAV compliant resources MUST support the HTTP URL namespace model
+ specified herein.
+
+5.1. HTTP URL Namespace Model
+
+ The HTTP URL namespace is a hierarchical namespace where the
+ hierarchy is delimited with the "/" character.
+
+ An HTTP URL namespace is said to be consistent if it meets the
+ following conditions: for every URL in the HTTP hierarchy there
+ exists a collection that contains that URL as an internal member URL.
+ The root, or top-level collection of the namespace under
+ consideration, is exempt from the previous rule. The top-level
+ collection of the namespace under consideration is not necessarily
+ the collection identified by the absolute path '/', it may be
+ identified by one or more path segments (e.g. /servlets/webdav/...)
+
+ Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
+ namespace be consistent -- a WebDAV-compatible resource may not have
+ a parent collection. However, certain WebDAV methods are prohibited
+ from producing results that cause namespace inconsistencies.
+
+ As is implicit in [RFC2616] and [RFC3986], any resource, including
+ collection resources, MAY be identified by more than one URI. For
+ example, a resource could be identified by multiple HTTP URLs.
+
+5.2. Collection Resources
+
+ Collection resources differ from other resources in that they also
+ act as containers. A collection is a resource whose state consists
+ of at least a set of mappings between path segments and resources,
+ and a set of properties on the collection itself. In this document,
+ a resource B will be said to be contained in the collection resource
+ A if there is a path segment mapping which maps to B and which is
+ contained in A. A collection MUST contain at most one mapping for a
+ given path segment, i.e., it is illegal to have the same path segment
+ mapped to more than one resource.
+
+ Properties defined on collections behave exactly as do properties on
+ non-collection resources. A collection MAY have additional state
+
+
+
+Dusseault Expires October 3, 2006 [Page 17]
+
+Internet-Draft WebDAV April 2006
+
+
+ such as entity bodies returned by GET.
+
+ For all WebDAV compliant resources A and B, identified by URLs "U"
+ and "V" respectively, such that "V" is equal to "U/SEGMENT", A MUST
+ be a collection that contains a mapping from "SEGMENT" to B. So, if
+ resource B with URL "http://example.com/bar/blah" is WebDAV compliant
+ and if resource A with URL "http://example.com/bar/" is WebDAV
+ compliant, then resource A must be a collection and must contain
+ exactly one mapping from "blah" to B.
+
+ Although commonly a mapping consists of a single segment and a
+ resource, in general, a mapping consists of a set of segments and a
+ resource. This allows a server to treat a set of segments as
+ equivalent (i.e. either all of the segments are mapped to the same
+ resource, or none of the segments are mapped to a resource). For
+ example, a server that performs case-folding on segments will treat
+ the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can
+ then use any of these segments to identify the resource. Note that a
+ PROPFIND result will select one of these equivalent segments to
+ identify the mapping, so there will be one PROPFIND response element
+ per mapping, not one per segment in the mapping.
+
+ Collection resources MAY have mappings to non-WebDAV compliant
+ resources in the HTTP URL namespace hierarchy but are not required to
+ do so. For example, if resource X with URL
+ "http://example.com/bar/blah" is not WebDAV compliant and resource A
+ with "URL http://example.com/bar/" identifies a WebDAV collection,
+ then A may or may not have a mapping from "blah" to X.
+
+ If a WebDAV compliant resource has no WebDAV compliant internal
+ members in the HTTP URL namespace hierarchy then the WebDAV compliant
+ resource is not required to be a collection.
+
+ There is a standing convention that when a collection is referred to
+ by its name without a trailing slash, the server MAY handle the
+ request as if the trailing slash were present. In this case it
+ SHOULD return a Content-Location header in the response, pointing to
+ the URL ending with the "/". For example, if a client invokes a
+ method on http://example.com/blah (no trailing slash), the server may
+ respond as if the operation were invoked on http://example.com/blah/
+ (trailing slash), and should return a Content-Location header with
+ the value http://example.com/blah/. Wherever a server produces a URL
+ referring to a collection, the server SHOULD include the trailing
+ slash. In general clients SHOULD use the trailing slash form of
+ collection names. If clients do not use the trailing slash form the
+ client needs to be prepared to see a redirect response. Clients will
+ find the DAV:resourcetype property more reliable than the URL to find
+ out if a resource is a collection.
+
+
+
+Dusseault Expires October 3, 2006 [Page 18]
+
+Internet-Draft WebDAV April 2006
+
+
+ Clients MUST be able to support the case where WebDAV resources are
+ contained inside non-WebDAV resources. For example, if a OPTIONS
+ response from "http://example.com/servlet/dav/collection" indicates
+ WebDAV support, the client cannot assume that
+ "http://example.com/servlet/dav/" or its parent necessarily are
+ WebDAV collections.
+
+ A typical scenario in which mapped URLs do not appear as members of
+ their parent collection is the case where a server allows links or
+ redirects to non-WebDAV resources. For instance, "/col/link" might
+ not appear as a member of "/col/", although the server would respond
+ with a 302 status to a GET request to "/col/link", thus the URL
+ "/col/link" would indeed be mapped. Similarly, a dynamically-
+ generated page might have a URL mapping from "/col/index.html", thus
+ this resource might respond with a 200 OK to a GET request yet not
+ appear as a member of "/col/".
+
+ Some mappings to even WebDAV-compliant resources might not appear in
+ the parent collection. An example for this case are servers that
+ support multiple alias URLs for each WebDAV compliant resource. A
+ server may implement case-insensitive URLs, thus "/col/a" and
+ "/col/A" identify the same resource, yet only either "a" or "A" are
+ reported upon listing the members of "/col". In cases where a server
+ treats a set of segments as equivalent, the server MUST expose only
+ one preferred segment per mapping, consistently chosen, in PROPFIND
+ responses.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 19]
+
+Internet-Draft WebDAV April 2006
+
+
+6. Locking
+
+ The ability to lock a resource provides a mechanism for serializing
+ access to that resource. Using a lock, an authoring client can
+ provide a reasonable guarantee that another principal will not modify
+ a resource while it is being edited. In this way, a client can
+ prevent the "lost update" problem.
+
+ This specification allows locks to vary over two client-specified
+ parameters, the number of principals involved (exclusive vs. shared)
+ and the type of access to be granted. This document defines locking
+ for only one access type, write. However, the syntax is extensible,
+ and permits the eventual specification of locking for other access
+ types.
+
+6.1. Lock Model
+
+ This section provides a concise model for how locking behaves. Later
+ sections will provide more detail on some of the concepts and refer
+ back to these model statements. Normative statements related to LOCK
+ and UNLOCK method handling can be found in the sections on those
+ methods, whereas normative statements that cover any method are
+ gathered here.
+
+ 1. A lock either directly or indirectly locks a resource.
+
+ 2. A resource becomes directly locked when a LOCK request to a URL
+ of that resource creates a new lock. The "lock-root" of the new
+ lock is that URL. If at the time of the request, the URL is not
+ mapped to a resource, a new empty resource is created and
+ directly locked.
+
+ 3. An exclusive lock (Section 6.2) conflicts with any other kind of
+ lock on the same resource, whether either lock is direct or
+ indirect. A server MUST NOT create conflicting locks on a
+ resource.
+
+ 4. For a collection that is locked with an infinite depth lock L,
+ all member resources are indirectly locked. Changes in
+ membership of a such a collection affect the set of indirectly
+ locked resources:
+
+ * If a member resource is added to the collection, the new
+ member resource MUST NOT already have a conflicting lock,
+ because the new resource MUST become indirectly locked by L.
+
+ * If a member resource stops being a member of the collection,
+ then the resource MUST no longer be indirectly locked by L.
+
+
+
+Dusseault Expires October 3, 2006 [Page 20]
+
+Internet-Draft WebDAV April 2006
+
+
+ 5. Each lock is identified by a single unique lock token
+ (Section 6.5).
+
+ 6. An UNLOCK request deletes the lock with the specified lock token.
+ After a lock is deleted, no resource is locked by that lock.
+
+ 7. A lock token is "submitted" in a request when it appears in an If
+ header (the Write Lock (Section 7) section discusses when token
+ submission is required for write locks).
+
+ 8. If a request causes the lock-root of any lock to become an
+ unmapped URL, then the lock MUST also be deleted by that request.
+
+6.2. Exclusive Vs. Shared Locks
+
+ The most basic form of lock is an exclusive lock. Exclusive locks
+ avoid having to deal with content change conflicts, without requiring
+ any coordination other than the methods described in this
+ specification.
+
+ However, there are times when the goal of a lock is not to exclude
+ others from exercising an access right but rather to provide a
+ mechanism for principals to indicate that they intend to exercise
+ their access rights. Shared locks are provided for this case. A
+ shared lock allows multiple principals to receive a lock. Hence any
+ principal with appropriate access can use the lock.
+
+ With shared locks there are two trust sets that affect a resource.
+ The first trust set is created by access permissions. Principals who
+ are trusted, for example, may have permission to write to the
+ resource. Among those who have access permission to write to the
+ resource, the set of principals who have taken out a shared lock also
+ must trust each other, creating a (typically) smaller trust set
+ within the access permission write set.
+
+ Starting with every possible principal on the Internet, in most
+ situations the vast majority of these principals will not have write
+ access to a given resource. Of the small number who do have write
+ access, some principals may decide to guarantee their edits are free
+ from overwrite conflicts by using exclusive write locks. Others may
+ decide they trust their collaborators will not overwrite their work
+ (the potential set of collaborators being the set of principals who
+ have write permission) and use a shared lock, which informs their
+ collaborators that a principal may be working on the resource.
+
+ The WebDAV extensions to HTTP do not need to provide all of the
+ communications paths necessary for principals to coordinate their
+ activities. When using shared locks, principals may use any out of
+
+
+
+Dusseault Expires October 3, 2006 [Page 21]
+
+Internet-Draft WebDAV April 2006
+
+
+ band communication channel to coordinate their work (e.g., face-to-
+ face interaction, written notes, post-it notes on the screen,
+ telephone conversation, Email, etc.) The intent of a shared lock is
+ to let collaborators know who else may be working on a resource.
+
+ Shared locks are included because experience from web distributed
+ authoring systems has indicated that exclusive locks are often too
+ rigid. An exclusive lock is used to enforce a particular editing
+ process: take out an exclusive lock, read the resource, perform
+ edits, write the resource, release the lock. This editing process
+ has the problem that locks are not always properly released, for
+ example when a program crashes, or when a lock creator leaves without
+ unlocking a resource. While both timeouts (Section 6.6) and
+ administrative action can be used to remove an offending lock,
+ neither mechanism may be available when needed; the timeout may be
+ long or the administrator may not be available.
+
+ A successful request for a new shared lock MUST result in the
+ generation of a unique lock associated with the requesting principal.
+ Thus if five principals have taken out shared write locks on the same
+ resource there will be five locks and five lock tokens, one for each
+ principal.
+
+6.3. Required Support
+
+ A WebDAV compliant resource is not required to support locking in any
+ form. If the resource does support locking it may choose to support
+ any combination of exclusive and shared locks for any access types.
+
+ The reason for this flexibility is that locking policy strikes to the
+ very heart of the resource management and versioning systems employed
+ by various storage repositories. These repositories require control
+ over what sort of locking will be made available. For example, some
+ repositories only support shared write locks while others only
+ provide support for exclusive write locks while yet others use no
+ locking at all. As each system is sufficiently different to merit
+ exclusion of certain locking features, this specification leaves
+ locking as the sole axis of negotiation within WebDAV.
+
+6.4. Lock Creator and Privileges
+
+ The creator of a lock has special privileges to use the lock to
+ modify the resource. When a locked resource is modified, a server
+ MUST check that the authenticated principal matches the lock creator
+ (in addition to checking for valid lock token submission).
+
+ The server MAY allow privileged users other than the lock creator to
+ destroy a lock (for example, the resource owner or an administrator).
+
+
+
+Dusseault Expires October 3, 2006 [Page 22]
+
+Internet-Draft WebDAV April 2006
+
+
+ The 'unlock' privilege in [RFC3744] was defined to provide that
+ permission.
+
+ There is no requirement for servers to accept LOCK requests from all
+ users or from anonymous users.
+
+ Note that having a lock does not confer full privilege to modify the
+ locked resource. Write access and other privileges MUST be enforced
+ through normal privilege or authentication mechanisms, not based on
+ the possible obscurity of lock token values.
+
+6.5. Lock Tokens
+
+ A lock token is a type of state token which identifies a particular
+ lock. Each lock has exactly one unique lock token generated by the
+ server. Clients MUST NOT attempt to interpret lock tokens in any
+ way.
+
+ Lock token URIs MUST be unique across all resources for all time.
+ This uniqueness constraint allows lock tokens to be submitted across
+ resources and servers without fear of confusion. Since lock tokens
+ are unique, a client MAY submit a lock token in an If header on a
+ resource other than the one that returned it.
+
+ When a LOCK operation creates a new lock, the new lock token is
+ returned in the Lock-Token response header defined in Section 10.5,
+ and also in the body of the response.
+
+ Servers MAY make lock tokens publicly readable (e.g. in the DAV:
+ lockdiscovery property). One use case for making lock tokens
+ readable is so that a long-lived lock can be removed by the resource
+ owner (the client that obtained the lock might have crashed or
+ disconnected before cleaning up the lock). Except for the case of
+ using UNLOCK under user guidance, a client SHOULD NOT use a lock
+ token created by another client instance.
+
+ This specification encourages servers to create UUIDs for lock
+ tokens, and to use the URI form defined by "A Universally Unique
+ Identifier (UUID) URN Namespace" ([RFC4122]). However servers are
+ free to use any URI (e.g. from another scheme) so long as it meets
+ the uniqueness requirements. For example, a valid lock token might
+ be constructed using the "opaquelocktoken" scheme defined in
+ Appendix C.
+
+ Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 23]
+
+Internet-Draft WebDAV April 2006
+
+
+6.6. Lock Timeout
+
+ A lock MAY have a limited lifetime. The lifetime is suggested by the
+ client when creating or refreshing the lock, but the server
+ ultimately chooses the timeout value. Timeout is measured in seconds
+ remaining until lock expiration.
+
+ The timeout counter MUST be restarted if a refresh lock request is
+ successful (see Section 9.10.2). The timeout counter SHOULD NOT be
+ restarted at any other time.
+
+ If the timeout expires then the lock SHOULD be removed. In this case
+ the server SHOULD act as if an UNLOCK method was executed by the
+ server on the resource using the lock token of the timed-out lock,
+ performed with its override authority. Thus logs should be updated
+ with the disposition of the lock, notifications should be sent, etc.,
+ just as they would be for an UNLOCK request.
+
+ Servers are advised to pay close attention to the values submitted by
+ clients, as they will be indicative of the type of activity the
+ client intends to perform. For example, an applet running in a
+ browser may need to lock a resource, but because of the instability
+ of the environment within which the applet is running, the applet may
+ be turned off without warning. As a result, the applet is likely to
+ ask for a relatively small timeout value so that if the applet dies,
+ the lock can be quickly harvested. However, a document management
+ system is likely to ask for an extremely long timeout because its
+ user may be planning on going off-line.
+
+ A client MUST NOT assume that just because the time-out has expired
+ the lock has immediately been removed.
+
+ Likewise, a client MUST NOT assume that just because the time-out has
+ not expired, the lock still exists. Clients MUST assume that locks
+ can arbitrarily disappear at any time, regardless of the value given
+ in the Timeout header. The Timeout header only indicates the
+ behavior of the server if extraordinary circumstances do not occur.
+ For example, a sufficiently privileged user may remove a lock at any
+ time or the system may crash in such a way that it loses the record
+ of the lock's existence.
+
+6.7. Lock Capability Discovery
+
+ Since server lock support is optional, a client trying to lock a
+ resource on a server can either try the lock and hope for the best,
+ or perform some form of discovery to determine what lock capabilities
+ the server supports. This is known as lock capability discovery. A
+ client can determine what lock types the server supports by
+
+
+
+Dusseault Expires October 3, 2006 [Page 24]
+
+Internet-Draft WebDAV April 2006
+
+
+ retrieving the DAV:supportedlock property.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the DAV:supportedlock property.
+
+6.8. Active Lock Discovery
+
+ If another principal locks a resource that a principal wishes to
+ access, it is useful for the second principal to be able to find out
+ who the first principal is. For this purpose the DAV:lockdiscovery
+ property is provided. This property lists all outstanding locks,
+ describes their type, and MAY even provide the lock tokens.
+
+ Any DAV compliant resource that supports the LOCK method MUST support
+ the DAV:lockdiscovery property.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 25]
+
+Internet-Draft WebDAV April 2006
+
+
+7. Write Lock
+
+ This section describes the semantics specific to the write lock type.
+ The write lock is a specific instance of a lock type, and is the only
+ lock type described in this specification.
+
+ An exclusive write lock protects a resource: it prevents changes by
+ any principal other than the lock creator and in any case where the
+ lock token is not submitted (e.g. by a client process other than the
+ one holding the lock).
+
+ Clients MUST submit a lock-token they are authorized to use in any
+ request which modifies a write-locked resource. The list of
+ modifications covered by a write-lock include:
+
+ 1. A change to any of the following aspects of any write-locked
+ resource:
+
+ * any variant,
+
+ * any dead property,
+
+ * any live property which is lockable (a live property is
+ lockable unless otherwise defined.)
+
+ 2. For collections, any modification of an internal member URI. An
+ internal member URI of a collection is considered to be modified
+ if it is added, removed, or identifies a different resource.
+ More discussion on write locks and collections is found in
+ Section 7.4.
+
+ 3. A modification of the mapping of the root of the write lock,
+ either to another resource or to no resource (e.g. DELETE).
+
+ Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH,
+ LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and
+ MKCOL are affected by write locks. All other HTTP/WebDAV methods
+ defined so far, GET in particular, function independently of a write
+ lock.
+
+ The next few sections describe in more specific terms how write locks
+ interact with various operations.
+
+7.1. Write Locks and Properties
+
+ While those without a write lock may not alter a property on a
+ resource it is still possible for the values of live properties to
+ change, even while locked, due to the requirements of their schemas.
+
+
+
+Dusseault Expires October 3, 2006 [Page 26]
+
+Internet-Draft WebDAV April 2006
+
+
+ Only dead properties and live properties defined as lockable are
+ guaranteed not to change while write locked.
+
+7.2. Avoiding Lost Updates
+
+ Although the write locks provide some help in preventing lost
+ updates, they cannot guarantee that updates will never be lost.
+ Consider the following scenario:
+
+ Two clients A and B are interested in editing the resource
+ 'index.html'. Client A is an HTTP client rather than a WebDAV
+ client, and so does not know how to perform locking.
+
+ Client A doesn't lock the document, but does a GET and begins
+ editing.
+
+ Client B does LOCK, performs a GET and begins editing.
+
+ Client B finishes editing, performs a PUT, then an UNLOCK.
+
+ Client A performs a PUT, overwriting and losing all of B's changes.
+
+ There are several reasons why the WebDAV protocol itself cannot
+ prevent this situation. First, it cannot force all clients to use
+ locking because it must be compatible with HTTP clients that do not
+ comprehend locking. Second, it cannot require servers to support
+ locking because of the variety of repository implementations, some of
+ which rely on reservations and merging rather than on locking.
+ Finally, being stateless, it cannot enforce a sequence of operations
+ like LOCK / GET / PUT / UNLOCK.
+
+ WebDAV servers that support locking can reduce the likelihood that
+ clients will accidentally overwrite each other's changes by requiring
+ clients to lock resources before modifying them. Such servers would
+ effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
+ resources.
+
+ WebDAV clients can be good citizens by using a lock / retrieve /
+ write /unlock sequence of operations (at least by default) whenever
+ they interact with a WebDAV server that supports locking.
+
+ HTTP 1.1 clients can be good citizens, avoiding overwriting other
+ clients' changes, by using entity tags in If-Match headers with any
+ requests that would modify resources.
+
+ Information managers may attempt to prevent overwrites by
+ implementing client-side procedures requiring locking before
+ modifying WebDAV resources.
+
+
+
+Dusseault Expires October 3, 2006 [Page 27]
+
+Internet-Draft WebDAV April 2006
+
+
+7.3. Write Locks and Unmapped URLs
+
+ WebDAV provides the ability to send a LOCK request to an unmapped URL
+ in order to reserve the name for use. This is a simple way to avoid
+ the lost-update problem on the creation of a new resource (another
+ way is to use If-None-Match header specified in Section 14.26 of
+ [RFC2616]). It has the side benefit of locking the new resource
+ immediately for use of the creator.
+
+ Note that the lost-update problem is not an issue for collections
+ because MKCOL can only be used to create a collection, not to
+ overwrite an existing collection. When trying to lock a collection
+ upon creation, clients can attempt to increase the likelihood of
+ getting the lock by pipelining the MKCOL and LOCK requests together
+ (but because this doesn't convert two separate operations into one
+ atomic operation there's no guarantee this will work).
+
+ A successful lock request to an unmapped URL MUST result in the
+ creation of a locked (non-collection) resource with empty content.
+ Subsequently, a successful PUT request (with the correct lock token)
+ provides the content for the resource. Note that the LOCK request
+ has no mechanism for the client to provide Content-Type or Content-
+ Language, thus the server will use defaults or empty values and rely
+ on the subsequent PUT request for correct values.
+
+ A resource created with a LOCK is empty but otherwise behaves in
+ every way as a normal resource. It behaves the same way as a
+ resource created by a PUT request with an empty body (and where a
+ Content-Type and Content-Language was not specified), followed by a
+ LOCK request to the same resource. Following from this model, a
+ locked empty resource:
+
+ o Can be read, deleted, moved, copied, and in all ways behave as a
+ regular non-collection resource.
+
+ o Appears as a member of its parent collection.
+
+ o SHOULD NOT disappear when its lock goes away (clients must
+ therefore be responsible for cleaning up their own mess, as with
+ any other operation or any non-empty resource)
+
+ o MAY NOT have values for properties like DAV:getcontentlanguage
+ which haven't been specified yet by the client.
+
+ o Can be updated (have content added) with a PUT request.
+
+ o MUST NOT be converted into a collection. The server MUST fail a
+ MKCOL request (as it would with a MKCOL request to any existing
+
+
+
+Dusseault Expires October 3, 2006 [Page 28]
+
+Internet-Draft WebDAV April 2006
+
+
+ non-collection resource).
+
+ o MUST have defined values for DAV:lockdiscovery and DAV:
+ supportedlock properties.
+
+ o The response MUST indicate that a resource was created, by use of
+ the "201 Created" response code (a LOCK request to an existing
+ resource instead will result in 200 OK). The body must still
+ include the DAV:lockdiscovery property, as with a LOCK request to
+ an existing resource.
+
+ The client is expected to update the locked empty resource shortly
+ after locking it, using PUT and possibly PROPPATCH.
+
+ Alternatively and for backwards compatibility to [RFC2518], servers
+ MAY implement Lock-Null Resources (LNRs) instead (see definition in
+ Appendix D). Clients can easily interoperate both with servers that
+ support the old model LNRs and the recommended model of "locked empty
+ resources" by only attempting PUT after a LOCK to an unmapped URL,
+ not MKCOL or GET, and by not relying on specific properties of LNRs.
+
+7.4. Write Locks and Collections
+
+ There are two kinds of collection write locks. A "Depth 0" write
+ lock on a collection protects the collection properties plus the
+ internal member URLs of that one collection, while not protecting the
+ content or properties of member resources (if the collection itself
+ has any entity bodies, those are also protected). A "Depth:
+ infinity" write lock on a collection provides the same protection on
+ that collection and also provides write lock protection on every
+ member resource.
+
+ Expressed otherwise, a write lock protects any request that would
+ create a new resource in a write locked collection, any request that
+ would remove an internal member URL of a write locked collection, and
+ any request that would change the segment name of any internal
+ member.
+
+ Thus, a collection write lock protects all the following actions:
+
+ o DELETE a collection's direct internal member,
+
+ o MOVE an internal member out of the collection,
+
+ o MOVE an internal member into the collection,
+
+ o MOVE to rename an internal member within a collection,
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 29]
+
+Internet-Draft WebDAV April 2006
+
+
+ o COPY an internal member into a collection, and
+
+ o PUT or MKCOL request which would create a new internal member.
+
+ The collection's lock token is required in addition to the lock token
+ on the internal member itself, if it is locked separately.
+
+ In addition, a depth-infinity lock affects all write operations to
+ all members of the locked collection. With a depth-infinity lock,
+ the resource identified by the root of the lock is directly locked,
+ and all its members are indirectly locked.
+
+ o Any new resource added as a descendent of a depth-infinity locked
+ collection becomes indirectly locked.
+
+ o Any indirectly locked resource moved out of the locked collection
+ into an unlocked collection is thereafter unlocked.
+
+ o Any indirectly locked resource moved out of a locked source
+ collection into a depth-infinity locked target collection remains
+ indirectly locked but is now protected by the lock on the target
+ collection (the target collection's lock token will thereafter be
+ required to make further changes).
+
+ If a depth-infinity write LOCK request is issued to a collection
+ containing member URLs identifying resources that are currently
+ locked in a manner which conflicts with the new lock (see Section 6.1
+ point 3), the request MUST fail with a 423 (Locked) status code, and
+ the response SHOULD contain the 'no-conflicting-lock' precondition.
+
+ If a lock request causes the URL of a resource to be added as an
+ internal member URL of a depth-infinity locked collection then the
+ new resource MUST be automatically protected by the lock. For
+ example, if the collection /a/b/ is write locked and the resource /c
+ is moved to /a/b/c then resource /a/b/c will be added to the write
+ lock.
+
+7.5. Write Locks and the If Request Header
+
+ A user agent has to demonstrate knowledge of a lock when requesting
+ an operation on a locked resource. Otherwise, the following scenario
+ might occur. In the scenario, program A, run by User A, takes out a
+ write lock on a resource. Program B, also run by User A, has no
+ knowledge of the lock taken out by program A, yet performs a PUT to
+ the locked resource. In this scenario, the PUT succeeds because
+ locks are associated with a principal, not a program, and thus
+ program B, because it is acting with principal A's credential, is
+ allowed to perform the PUT. However, had program B known about the
+
+
+
+Dusseault Expires October 3, 2006 [Page 30]
+
+Internet-Draft WebDAV April 2006
+
+
+ lock, it would not have overwritten the resource, preferring instead
+ to present a dialog box describing the conflict to the user. Due to
+ this scenario, a mechanism is needed to prevent different programs
+ from accidentally ignoring locks taken out by other programs with the
+ same authorization.
+
+ In order to prevent these collisions a lock token MUST be submitted
+ by an authorized principal for all locked resources that a method may
+ change or the method MUST fail. A lock token is submitted when it
+ appears in an If header. For example, if a resource is to be moved
+ and both the source and destination are locked then two lock tokens
+ must be submitted in the If header, one for the source and the other
+ for the destination.
+
+7.5.1. Example - Write Lock and COPY
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+ If: <http://www.example.com/users/f/fielding/index.html>
+ (<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, even though both the source and destination are
+ locked, only one lock token must be submitted, for the lock on the
+ destination. This is because the source resource is not modified by
+ a COPY, and hence unaffected by the write lock. In this example,
+ user agent authentication has previously occurred via a mechanism
+ outside the scope of the HTTP protocol, in the underlying transport
+ layer.
+
+7.5.2. Example - Deleting a member of a locked collection
+
+ Consider a collection "/locked" exclusively write-locked with Depth:
+ Infinity, and an attempt to delete an internal member "/locked/
+ member":
+
+ >>Request
+
+ DELETE /locked/member HTTP/1.1
+ Host: example.com
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 31]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 423 Locked
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:lock-token-submitted>
+ <D:href>/locked/</D:href>
+ </D:lock-token-submitted>
+ </D:error>
+
+ Thus the client would need to submit the lock token with the request
+ to make it succeed. To do that, various forms of the If header (see
+ Section 10.4) could be used.
+
+ "No-Tag-List" format:
+
+ If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ "Tagged-List" format, for "http://example.com/locked/":
+
+ If: <http://example.com/locked/>
+ (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ "Tagged-List" format, for "http://example.com/locked/member":
+
+ If: <http://example.com/locked/member>
+ (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
+
+ Note that for the purpose of submitting the lock token the actual
+ form doesn't matter; what's relevant is that the lock token appears
+ in the If header, and that the If header itself evaluates to true.
+
+7.6. Write Locks and COPY/MOVE
+
+ A COPY method invocation MUST NOT duplicate any write locks active on
+ the source. However, as previously noted, if the COPY copies the
+ resource into a collection that is locked with "Depth: infinity",
+ then the resource will be added to the lock.
+
+ A successful MOVE request on a write locked resource MUST NOT move
+ the write lock with the resource. However, if there is an existing
+ lock at the destination, the server MUST add the moved resource to
+ the destination lock scope. For example, if the MOVE makes the
+ resource a child of a collection that is locked with "Depth:
+ infinity", then the resource will be added to that collection's lock.
+
+
+
+Dusseault Expires October 3, 2006 [Page 32]
+
+Internet-Draft WebDAV April 2006
+
+
+ Additionally, if a resource locked with "Depth: infinity" is moved to
+ a destination that is within the scope of the same lock (e.g., within
+ the URL namespace tree covered by the lock), the moved resource will
+ again be a added to the lock. In both these examples, as specified
+ in Section 7.5, an If header must be submitted containing a lock
+ token for both the source and destination.
+
+7.7. Refreshing Write Locks
+
+ A client MUST NOT submit the same write lock request twice. Note
+ that a client is always aware it is resubmitting the same lock
+ request because it must include the lock token in the If header in
+ order to make the request for a resource that is already locked.
+
+ However, a client may submit a LOCK request with an If header but
+ without a body. This form of LOCK MUST only be used to "refresh" a
+ lock. Meaning, at minimum, that any timers associated with the lock
+ MUST be re-set.
+
+ Clients may submit Timeout headers of arbitrary value with their lock
+ refresh requests. Servers, as always, may ignore Timeout headers
+ submitted by the client, and a server MAY refresh a lock with a
+ timeout period that is different than the previous timeout period
+ used for the lock, provided it advertises the new value in the LOCK
+ refresh response.
+
+ If an error is received in response to a refresh LOCK request the
+ client MUST NOT assume that the lock was refreshed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 33]
+
+Internet-Draft WebDAV April 2006
+
+
+8. General Request and Response Handling
+
+8.1. Precedence in Error Handling
+
+ Servers MUST return authorization errors in preference to other
+ errors. This avoids leaking information about protected resources
+ (e.g. a client that finds that a hidden resource exists by seeing a
+ 423 Locked response to an anonymous request to the resource).
+
+8.2. Use of XML
+
+ In HTTP/1.1, method parameter information was exclusively encoded in
+ HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
+ information either in an XML ([REC-XML]) request entity body, or in
+ an HTTP header. The use of XML to encode method parameters was
+ motivated by the ability to add extra XML elements to existing
+ structures, providing extensibility; and by XML's ability to encode
+ information in ISO 10646 character sets, providing
+ internationalization support.
+
+ In addition to encoding method parameters, XML is used in WebDAV to
+ encode the responses from methods, providing the extensibility and
+ internationalization advantages of XML for method output, as well as
+ input.
+
+ When XML is used for a request or response body, the Content-Type
+ type SHOULD be application/xml. Implementations MUST accept both
+ text/xml and application/xml in request and response bodies. Use of
+ text/xml is deprecated.
+
+ All DAV compliant clients and resources MUST use XML parsers that are
+ compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either
+ requests or responses MUST be, at minimum, well formed and use
+ namespaces correctly. If a server receives XML that is not well-
+ formed then the server MUST reject the entire request with a 400 (Bad
+ Request). If a client receives XML that is not well-formed in a
+ response then the client MUST NOT assume anything about the outcome
+ of the executed method and SHOULD treat the server as malfunctioning.
+
+ Note that processing XML submitted by an untrusted source may cause
+ risks connected to privacy, security, and service quality (see
+ Section 20). Servers MAY reject questionable requests (even though
+ they consist of well-formed XML), for instance with a 400 (Bad
+ Request) status code and an optional response body explaining the
+ problem.
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 34]
+
+Internet-Draft WebDAV April 2006
+
+
+8.3. URL Handling
+
+ URLs appear in many places in requests and responses.
+ Interoperability experience with [RFC2518] showed that many clients
+ parsing Multi-Status responses did not fully implement the full
+ Reference Resolution defined in Section 5 of [RFC3986]. Thus,
+ servers in particular need to be careful in handling URLs in
+ responses, to ensure that clients have enough context to be able to
+ interpret all the URLs. The rules in this section apply not only to
+ resource URLs in the 'href' element in Multi-Status responses, but
+ also to the Destination and If header resource URLs.
+
+ The sender has a choice between two approaches: using a relative
+ reference, which is resolved against the Request-URI, or a full URI.
+ A server MUST ensure that every 'href' value within a Multi-Status
+ response uses the same format.
+
+ WebDAV only uses one form of relative reference in its extensions,
+ the absolute path.
+
+ Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )
+
+ The absolute-URI, path-absolute and query productions are defined in
+ Section 4.3, 3.3 and 3.4 of [RFC3986].
+
+ Within Simple-ref productions, senders MUST NOT:
+
+ o use dot-segments ("." or ".."), or
+
+ o have prefixes that do not match the Request-URI (using the
+ comparison rules defined in Section 3.2.3 of [RFC2616]).
+
+ Identifiers for collections SHOULD end in a '/' character.
+
+8.3.1. Example - Correct URL Handling
+
+ Consider the collection http://example.com/sample/ with the internal
+ member URL http://example.com/sample/a%20test and the PROPFIND
+ request below:
+
+ >>Request:
+
+ PROPFIND /sample/ HTTP/1.1
+ Host: example.com
+ Depth: 1
+
+ In this case, the server should return two 'href' elements containing
+ either
+
+
+
+Dusseault Expires October 3, 2006 [Page 35]
+
+Internet-Draft WebDAV April 2006
+
+
+ o 'http://example.com/sample/' and
+ 'http://example.com/sample/a%20test', or
+
+ o '/sample/' and '/sample/a%20test'
+
+ Note that even though the server may be storing the member resource
+ internally as 'a test', it has to be percent-encoded when used inside
+ a URI reference (see Section 2.1 of [RFC3986]). Also note that a
+ legal URI may still contain characters that need to be escaped within
+ XML character data, such as the ampersand character.
+
+8.4. Required Bodies in Requests
+
+ Some of these new methods do not define bodies. Servers MUST examine
+ all requests for a body, even when a body was not expected. In cases
+ where a request body is present but would be ignored by a server, the
+ server MUST reject the request with 415 (Unsupported Media Type).
+ This informs the client (which may have been attempting to use an
+ extension) that the body could not be processed as the client
+ intended.
+
+8.5. HTTP Headers for use in WebDAV
+
+ HTTP defines many headers that can be used in WebDAV requests and
+ responses. Not all of these are appropriate in all situations and
+ some interactions may be undefined. Note that HTTP 1.1 requires the
+ Date header in all responses if possible (see Section 14.18,
+ [RFC2616]).
+
+ The server MUST do authorization checks before checking any HTTP
+ conditional header.
+
+8.6. ETag
+
+ HTTP 1.1 recommends the use of ETags rather than modification dates,
+ for cache-control, and there are even stronger reasons to prefer
+ ETags for authoring. Correct use of ETags is even more important in
+ a distributed authoring environment, because ETags are necessary
+ along with locks to avoid the lost-update problem. A client might
+ fail to renew a lock, for example when the lock times out and the
+ client is accidentally offline or in the middle of a long upload.
+ When a client fails to renew the lock, it's quite possible the
+ resource can still be relocked and the user can go on editing, as
+ long as no changes were made in the meantime. ETags are required for
+ the client to be able to distinguish this case. Otherwise, the
+ client is forced to ask the user whether to overwrite the resource on
+ the server without even being able to tell the user whether it has
+ changed. Timestamps do not solve this problem nearly as well as
+
+
+
+Dusseault Expires October 3, 2006 [Page 36]
+
+Internet-Draft WebDAV April 2006
+
+
+ ETags.
+
+ Strong ETags are much more useful for authoring use cases than weak
+ ETags. Semantic equivalence can be a useful concept but that depends
+ on the document type and the application type, and interoperability
+ might require some agreement or standard outside the scope of this
+ specification and HTTP. Note also that weak ETags have certain
+ restrictions in HTTP, e.g. these cannot be used in If-Match headers.
+
+ Note that the meaning of an ETag in a PUT response is not clearly
+ defined either in this document or in RFC2616 (i.e., whether the ETag
+ means that the resource is octet-for-octet equivalent to the body of
+ the PUT request, or whether the server could have made minor changes
+ in the formatting or content of the document upon storage). This is
+ an HTTP issue, not purely a WebDAV issue, and is being addressed in
+ [I-D.draft-whitehead-http-etag].
+
+ Because clients may be forced to prompt users or throw away changed
+ content if the ETag changes, a WebDAV server SHOULD NOT change the
+ ETag (or the Last-Modified time) for a resource that has an unchanged
+ body and location. The ETag represents the state of the body or
+ contents of the resource. There is no similar way to tell if
+ properties have changed.
+
+8.7. Including error response bodies
+
+ HTTP and WebDAV did not use the bodies of most error responses for
+ machine-parsable information until DeltaV introduced a mechanism to
+ include more specific information in the body of an error response
+ (Section 1.6 of [RFC3253]). The error body mechanism is appropriate
+ to use with any error response that may take a body but does not
+ already have a body defined. The mechanism is particularly
+ appropriate when a status code can mean many things (for example, 400
+ Bad Request can mean required headers are missing, headers are
+ incorrectly formatted, or much more). This error body mechanism is
+ covered in Section 16.
+
+8.8. Impact of Namespace Operations on Cache Validators
+
+ Note that the HTTP response headers "Etag" and "Last-Modified" (see
+ [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per
+ resource), and are used by clients for caching. Therefore servers
+ must ensure that executing any operation that affects the URL
+ namespace (such as COPY, MOVE, DELETE, PUT or MKCOL) does preserve
+ their semantics, in particular:
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 37]
+
+Internet-Draft WebDAV April 2006
+
+
+ o For any given URL, the "Last-Modified" value MUST increment every
+ time the representation returned upon GET changes (within the
+ limits of timestamp resolution).
+
+ o For any given URL, an "ETag" value MUST NOT be re-used for
+ different representations returned by GET.
+
+ In practice this means that servers
+
+ o might have to increment "Last-Modified" timestamps for every
+ resource inside the destination namespace of a namespace operation
+ unless it can do so more selectively, and
+
+ o similarily, might have to re-assign "ETag" values for these
+ resources (unless the server allocates entity tags in a way so
+ that they are unique across the whole URL namespace managed by the
+ server).
+
+ Note that these considerations also apply to specific use cases, such
+ as using PUT to create a new resource at a URL that has been mapped
+ before, but has been deleted since then.
+
+ Finally, WebDAV properties (such as DAV:getetag and DAV:
+ getlastmodified) that inherit their semantics from HTTP headers must
+ behave accordingly.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 38]
+
+Internet-Draft WebDAV April 2006
+
+
+9. HTTP Methods for Distributed Authoring
+
+9.1. PROPFIND Method
+
+ The PROPFIND method retrieves properties defined on the resource
+ identified by the Request-URI, if the resource does not have any
+ internal members, or on the resource identified by the Request-URI
+ and potentially its member resources, if the resource is a collection
+ that has internal member URLs. All DAV compliant resources MUST
+ support the PROPFIND method and the propfind XML element
+ (Section 14.20) along with all XML elements defined for use with that
+ element.
+
+ A client MUST submit a Depth header with a value of "0", "1", or
+ "infinity" with a PROPFIND request. Servers MUST support "0" and "1"
+ depth requests on WebDAV-compliant resources and SHOULD support
+ "infinity" requests. In practice, support for depth infinity
+ requests MAY be disabled, due to the performance and security
+ concerns associated with this behavior. Since clients weren't
+ required to include the Depth header in [RFC2518], servers SHOULD
+ treat such a request as if a "Depth: infinity" header was included.
+
+ A client may submit a 'propfind' XML element in the body of the
+ request method describing what information is being requested. It is
+ possible to:
+
+ o Request particular property values, by naming the properties
+ desired within the 'prop' element (the ordering of properties in
+ here MAY be ignored by server),
+
+ o Request property values for those properties defined in this
+ specification plus dead properties, by using the 'allprop' element
+ (the 'include' element can be used with 'allprop' to instruct the
+ server to also include additional live properties that may not
+ have been returned otherwise),
+
+ o Request a list of names of all the properties defined on the
+ resource, by using the 'propname' element.
+
+ A client may choose not to submit a request body. An empty PROPFIND
+ request body MUST be treated as if it were an 'allprop' request.
+
+ Note that 'allprop' does not return values for all live properties.
+ WebDAV servers increasingly have expensively-calculated or lengthy
+ properties (see [RFC3253] and [RFC3744]) and do not return all
+ properties already. Instead, WebDAV clients can use propname
+ requests to discover what live properties exist, and request named
+ properties when retrieving values. For a live property defined
+
+
+
+Dusseault Expires October 3, 2006 [Page 39]
+
+Internet-Draft WebDAV April 2006
+
+
+ elsewhere, that definition can specify whether that live property
+ would be returned in 'allprop' requests or not.
+
+ All servers MUST support returning a response of content type text/
+ xml or application/xml that contains a multistatus XML element that
+ describes the results of the attempts to retrieve the various
+ properties.
+
+ If there is an error retrieving a property then a proper error result
+ MUST be included in the response. A request to retrieve the value of
+ a property which does not exist is an error and MUST be noted, if the
+ response uses a 'multistatus' XML element, with a 'response' XML
+ element which contains a 404 (Not Found) status value.
+
+ Consequently, the 'multistatus' XML element for a collection resource
+ MUST include a 'response' XML element for each member URL of the
+ collection, to whatever depth was requested. It SHOULD NOT include
+ any 'response' elements for resources that are not WebDAV-compliant.
+ Each 'response' element MUST contain an 'href' element that contains
+ the URL of the resource on which the properties in the prop XML
+ element are defined. Results for a PROPFIND on a collection resource
+ are returned as a flat list whose order of entries is not
+ significant. Note that a resource may have only one value for a
+ property of a given name, so the property may only show up once in
+ PROPFIND responses.
+
+ Properties may be subject to access control. In the case of
+ 'allprop' and 'propname' requests, if a principal does not have the
+ right to know whether a particular property exists then the property
+ MAY be silently excluded from the response.
+
+ Some PROPFIND results MAY be cached, with care as there is no cache
+ validation mechanism for most properties. This method is both safe
+ and idempotent (see Section 9.1 of [RFC2616]).
+
+9.1.1. PROPFIND status codes
+
+ This section, as with similar sections for other methods, provides
+ some guidance on error codes and preconditions or postconditions
+ (defined in Section 16) that might be particularly useful with
+ PROPFIND.
+
+ 403 Forbidden - A server MAY reject PROPFIND requests on collections
+ with depth header of "Infinity", in which case it SHOULD use this
+ error with the precondition code 'propfind-finite-depth' inside the
+ error body.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 40]
+
+Internet-Draft WebDAV April 2006
+
+
+9.1.2. Status Codes for use in 'propstat' Element
+
+ In PROPFIND responses, information about individual properties is
+ returned inside 'propstat' elements (see Section 14.22), each
+ containing an individual 'status' element containing information
+ about the properties appearing in it. The list below summarizes the
+ most common status codes used inside 'propstat', however clients
+ should be prepared to handle other 2/3/4/5xx series status codes as
+ well.
+
+ 200 OK - A property exists and/or its value is successfully returned.
+
+ 401 Unauthorized - The property cannot be viewed without appropriate
+ authorization.
+
+ 403 Forbidden - The property cannot be viewed regardless of
+ authentication.
+
+ 404 Not Found - The property does not exist.
+
+9.1.3. Example - Retrieving Named Properties
+
+ >>Request
+
+ PROPFIND /file HTTP/1.1
+ Host: www.example.com
+ Content-type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <R:DingALing/>
+ <R:Random/>
+ </D:prop>
+ </D:propfind>
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 41]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response xmlns:R="http://ns.example.com/boxschema/">
+ <D:href>http://www.example.com/file</D:href>
+ <D:propstat>
+ <D:prop>
+ <R:bigbox>
+ <R:BoxType>Box type A</R:BoxType>
+ </R:bigbox>
+ <R:author>
+ <R:Name>J.J. Johnson</R:Name>
+ </R:author>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><R:DingALing/><R:Random/></D:prop>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:responsedescription> The user does not have access to the
+ DingALing property.
+ </D:responsedescription>
+ </D:propstat>
+ </D:response>
+ <D:responsedescription> There has been an access violation error.
+ </D:responsedescription>
+ </D:multistatus>
+
+
+ In this example, PROPFIND is executed on a non-collection resource
+ http://www.example.com/file. The propfind XML element specifies the
+ name of four properties whose values are being requested. In this
+ case only two properties were returned, since the principal issuing
+ the request did not have sufficient access rights to see the third
+ and fourth properties.
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 42]
+
+Internet-Draft WebDAV April 2006
+
+
+9.1.4. Example - Using so-called 'allprop'
+
+ >>Request
+
+ PROPFIND /mycol/ HTTP/1.1
+ Host: www.example.com
+ Depth: 1
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:include>
+ <D:creationdate/>
+ <D:getlastmodified/>
+ </D:include>
+ </D:propfind>
+
+ In this example, PROPFIND is executed on the resource
+ http://www.example.com/mycol/ and its internal member resources. The
+ client requests the values of all live properties defined in this
+ specification, plus all dead properties, plus two more live
+ properties defined in [RFC3253]. The response is not shown.
+
+9.1.5. Example - Using 'propname' to Retrieve all Property Names
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <propfind xmlns="DAV:">
+ <propname/>
+ </propfind>
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 43]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <multistatus xmlns="DAV:">
+ <response>
+ <href>http://www.example.com/container/</href>
+ <propstat>
+ <prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <R:author/>
+ <creationdate/>
+ <displayname/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ <response>
+ <href>http://www.example.com/container/front.html</href>
+ <propstat>
+ <prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox/>
+ <creationdate/>
+ <displayname/>
+ <getcontentlength/>
+ <getcontenttype/>
+ <getetag/>
+ <getlastmodified/>
+ <resourcetype/>
+ <supportedlock/>
+ </prop>
+ <status>HTTP/1.1 200 OK</status>
+ </propstat>
+ </response>
+ </multistatus>
+
+ In this example, PROPFIND is invoked on the collection resource
+ http://www.example.com/container/, with a propfind XML element
+ containing the propname XML element, meaning the name of all
+ properties should be returned. Since no Depth header is present, it
+ assumes its default value of "infinity", meaning the name of the
+ properties on the collection and all its descendents should be
+ returned.
+
+
+
+Dusseault Expires October 3, 2006 [Page 44]
+
+Internet-Draft WebDAV April 2006
+
+
+ Consistent with the previous example, resource
+ http://www.example.com/container/ has six properties defined on it:
+ bigbox and author in the "http://ns.example.com/boxschema/"
+ namespace, and creationdate, displayname, resourcetype, and
+ supportedlock in the "DAV:" namespace.
+
+ The resource http://www.example.com/container/index.html, a member of
+ the "container" collection, has nine properties defined on it, bigbox
+ in the "http://ns.example.com/boxschema/" namespace and,
+ creationdate, displayname, getcontentlength, getcontenttype, getetag,
+ getlastmodified, resourcetype, and supportedlock in the "DAV:"
+ namespace.
+
+ This example also demonstrates the use of XML namespace scoping and
+ the default namespace. Since the "xmlns" attribute does not contain
+ a prefix, the namespace applies by default to all enclosed elements.
+ Hence, all elements which do not explicitly state the namespace to
+ which they belong are members of the "DAV:" namespace.
+
+9.1.6. Example - Using 'allprop'
+
+ Note that 'allprop', despite its name which remains for backward-
+ compatibility, does not return every property, but only dead
+ properties and the live properties defined in this specification.
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Depth: 1
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ </D:propfind>
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+
+
+
+Dusseault Expires October 3, 2006 [Page 45]
+
+Internet-Draft WebDAV April 2006
+
+
+ <D:href>/container/</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox>
+ <R:author><R:Name>Hadrian</R:Name></R:author>
+ <D:creationdate>1997-12-01T17:42:21-08:00</D:creationdate>
+ <D:displayname>Example collection</D:displayname>
+ <D:resourcetype><D:collection/></D:resourcetype>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/container/front.html</D:href>
+ <D:propstat>
+ <D:prop xmlns:R="http://ns.example.com/boxschema/">
+ <R:bigbox><R:BoxType>Box type B</R:BoxType>
+ </R:bigbox>
+ <D:creationdate>1997-12-01T18:27:21-08:00</D:creationdate>
+ <D:displayname>Example HTML resource</D:displayname>
+ <D:getcontentlength>4525</D:getcontentlength>
+ <D:getcontenttype>text/html</D:getcontenttype>
+ <D:getetag>"zzyzx"</D:getetag>
+ <D:getlastmodified
+ >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified>
+ <D:resourcetype/>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+
+
+
+Dusseault Expires October 3, 2006 [Page 46]
+
+Internet-Draft WebDAV April 2006
+
+
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ In this example, PROPFIND was invoked on the resource
+ http://www.example.com/container/ with a Depth header of 1, meaning
+ the request applies to the resource and its children, and a propfind
+ XML element containing the allprop XML element, meaning the request
+ should return the name and value of all the dead properties defined
+ on the resources, plus the name and value of all the properties
+ defined in this specification. This example illustrates the use of
+ relative references in the 'href' elements of the response.
+
+ The resource http://www.example.com/container/ has six properties
+ defined on it: 'bigbox' and 'author in the
+ "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV:
+ displayname, DAV:resourcetype, and DAV:supportedlock.
+
+ The last four properties are WebDAV-specific, defined in Section 15.
+ Since GET is not supported on this resource, the get* properties
+ (e.g., DAV:getcontentlength) are not defined on this resource. The
+ WebDAV-specific properties assert that "container" was created on
+ December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
+ (DAV:creationdate), has a name of "Example collection" (DAV:
+ displayname), a collection resource type (DAV:resourcetype), and
+ supports exclusive write and shared write locks (DAV:supportedlock).
+
+ The resource http://www.example.com/container/front.html has nine
+ properties defined on it:
+
+ 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another
+ instance of the "bigbox" property type), DAV:creationdate, DAV:
+ displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
+ DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
+
+ The DAV-specific properties assert that "front.html" was created on
+ December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
+ (DAV:creationdate), has a name of "Example HTML resource" (DAV:
+ displayname), a content length of 4525 bytes (DAV:getcontentlength),
+ a MIME type of "text/html" (DAV:getcontenttype), an entity tag of
+ "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998,
+ at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type,
+ meaning that it is not a collection (DAV:resourcetype), and supports
+ both exclusive write and shared write locks (DAV:supportedlock).
+
+9.2. PROPPATCH Method
+
+ The PROPPATCH method processes instructions specified in the request
+
+
+
+Dusseault Expires October 3, 2006 [Page 47]
+
+Internet-Draft WebDAV April 2006
+
+
+ body to set and/or remove properties defined on the resource
+ identified by the Request-URI.
+
+ All DAV compliant resources MUST support the PROPPATCH method and
+ MUST process instructions that are specified using the
+ propertyupdate, set, and remove XML elements. Execution of the
+ directives in this method is, of course, subject to access control
+ constraints. DAV compliant resources SHOULD support the setting of
+ arbitrary dead properties.
+
+ The request message body of a PROPPATCH method MUST contain the
+ propertyupdate XML element.
+
+ Servers MUST process PROPPATCH instructions in document order (an
+ exception to the normal rule that ordering is irrelevant).
+ Instructions MUST either all be executed or none executed. Thus if
+ any error occurs during processing all executed instructions MUST be
+ undone and a proper error result returned. Instruction processing
+ details can be found in the definition of the set and remove
+ instructions in Section 14.23 and Section 14.26.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.2.1. Status Codes for use in 'propstat' Element
+
+ In PROPPATCH responses, information about individual properties is
+ returned inside 'propstat' elements (see Section 14.22), each
+ containing an individual 'status' element containing information
+ about the properties appearing in it. The list below summarizes the
+ most common status codes used inside 'propstat', however clients
+ should be prepared to handle other 2/3/4/5xx series status codes as
+ well.
+
+ 200 (OK) - The property set or change succeeded. Note that if this
+ appears for one property, it appears for every property in the
+ response, due to the atomicity of PROPPATCH.
+
+ 403 (Forbidden) - The client, for reasons the server chooses not to
+ specify, cannot alter one of the properties.
+
+ 403 (Forbidden): The client has attempted to set a protected
+ property, such as DAV:getetag. If returning this error, the server
+ SHOULD use the precondition code 'cannot-modify-protected-property'
+ inside the response body.
+
+ 409 (Conflict) - The client has provided a value whose semantics are
+ not appropriate for the property.
+
+
+
+Dusseault Expires October 3, 2006 [Page 48]
+
+Internet-Draft WebDAV April 2006
+
+
+ 424 (Failed Dependency) - The property change could not be made
+ because of another property change that failed.
+
+ 507 (Insufficient Storage) - The server did not have sufficient space
+ to record the property.
+
+9.2.2. Example - PROPPATCH
+
+ >>Request
+
+ PROPPATCH /bar.html HTTP/1.1
+ Host: www.example.com
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propertyupdate xmlns:D="DAV:"
+ xmlns:Z="http://ns.example.com/standards/z39.50/">
+ <D:set>
+ <D:prop>
+ <Z:Authors>
+ <Z:Author>Jim Whitehead</Z:Author>
+ <Z:Author>Roy Fielding</Z:Author>
+ </Z:Authors>
+ </D:prop>
+ </D:set>
+ <D:remove>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ </D:remove>
+ </D:propertyupdate>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 49]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:Z="http://ns.example.com/standards/z39.50/">
+ <D:response>
+ <D:href>http://www.example.com/bar.html</D:href>
+ <D:propstat>
+ <D:prop><Z:Authors/></D:prop>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop><Z:Copyright-Owner/></D:prop>
+ <D:status>HTTP/1.1 409 Conflict</D:status>
+ </D:propstat>
+ <D:responsedescription> Copyright Owner can not be deleted or
+ altered.</D:responsedescription>
+ </D:response>
+ </D:multistatus>
+
+ In this example, the client requests the server to set the value of
+ the "Authors" property in the
+ "http://ns.example.com/standards/z39.50/" namespace, and to remove
+ the property "Copyright-Owner" in the same namespace. Since the
+ Copyright-Owner property could not be removed, no property
+ modifications occur. The 424 (Failed Dependency) status code for the
+ Authors property indicates this action would have succeeded if it
+ were not for the conflict with removing the Copyright-Owner property.
+
+9.3. MKCOL Method
+
+ The MKCOL method is used to create a new collection. All WebDAV
+ compliant resources MUST support the MKCOL method.
+
+ MKCOL creates a new collection resource at the location specified by
+ the Request-URI. If the Request-URI is already mapped to a resource
+ then the MKCOL MUST fail. During MKCOL processing, a server MUST
+ make the Request-URI an internal member of its parent collection,
+ unless the Request-URI is "/". If no such ancestor exists, the
+ method MUST fail. When the MKCOL operation creates a new collection
+ resource, all ancestors MUST already exist, or the method MUST fail
+ with a 409 (Conflict) status code. For example, if a request to
+ create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the
+ request must fail.
+
+
+
+Dusseault Expires October 3, 2006 [Page 50]
+
+Internet-Draft WebDAV April 2006
+
+
+ When MKCOL is invoked without a request body, the newly created
+ collection SHOULD have no members.
+
+ A MKCOL request message may contain a message body. The precise
+ behavior of a MKCOL request when the body is present is undefined,
+ but limited to creating collections, members of a collection, bodies
+ of members and properties on the collections or members. If the
+ server receives a MKCOL request entity type it does not support or
+ understand it MUST respond with a 415 (Unsupported Media Type) status
+ code. If the server decides to reject the request based on the
+ presence of an entity or the type of an entity, it should use the 415
+ (Unsupported Media Type) status code.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.3.1. MKCOL Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to MKCOL:
+
+ 201 (Created) - The collection was created.
+
+ 403 (Forbidden) - This indicates at least one of two conditions: 1)
+ the server does not allow the creation of collections at the given
+ location in its URL namespace, or 2) the parent collection of the
+ Request-URI exists but cannot accept members.
+
+ 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped
+ URL.
+
+ 409 (Conflict) - A collection cannot be made at the Request-URI until
+ one or more intermediate collections have been created. The server
+ MUST NOT create those intermediate collections automatically.
+
+ 415 (Unsupported Media Type) - The server does not support the
+ request body type (since this specification does not define any body
+ for MKCOL requests).
+
+ 507 (Insufficient Storage) - The resource does not have sufficient
+ space to record the state of the resource after the execution of this
+ method.
+
+9.3.2. Example - MKCOL
+
+ This example creates a collection called /webdisc/xfiles/ on the
+ server www.example.com.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 51]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Request
+
+ MKCOL /webdisc/xfiles/ HTTP/1.1
+ Host: www.example.com
+
+
+ >>Response
+
+ HTTP/1.1 201 Created
+
+9.4. GET, HEAD for Collections
+
+ The semantics of GET are unchanged when applied to a collection,
+ since GET is defined as, "retrieve whatever information (in the form
+ of an entity) is identified by the Request-URI" [RFC2616]. GET when
+ applied to a collection may return the contents of an "index.html"
+ resource, a human-readable view of the contents of the collection, or
+ something else altogether. Hence it is possible that the result of a
+ GET on a collection will bear no correlation to the membership of the
+ collection.
+
+ Similarly, since the definition of HEAD is a GET without a response
+ message body, the semantics of HEAD are unmodified when applied to
+ collection resources.
+
+9.5. POST for Collections
+
+ Since by definition the actual function performed by POST is
+ determined by the server and often depends on the particular
+ resource, the behavior of POST when applied to collections cannot be
+ meaningfully modified because it is largely undefined. Thus the
+ semantics of POST are unmodified when applied to a collection.
+
+9.6. DELETE Requirements
+
+ DELETE is defined in [RFC2616], Section 9.7, to "delete the resource
+ identified by the Request-URI". However, WebDAV changes some DELETE
+ handling requirements.
+
+ A server processing a successful DELETE request:
+
+ MUST destroy locks rooted on the deleted resource
+
+ MUST remove the mapping from the Request-URI to any resource.
+
+ Thus, after a successful DELETE operation (and in the absence of
+ other actions) a subsequent GET/HEAD/PROPFIND request to the target
+ Request-URI MUST return 404 (Not Found).
+
+
+
+Dusseault Expires October 3, 2006 [Page 52]
+
+Internet-Draft WebDAV April 2006
+
+
+9.6.1. DELETE for Collections
+
+ The DELETE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header with
+ a DELETE on a collection with any value but infinity.
+
+ DELETE instructs that the collection specified in the Request-URI and
+ all resources identified by its internal member URLs are to be
+ deleted.
+
+ If any resource identified by a member URL cannot be deleted then all
+ of the member's ancestors MUST NOT be deleted, so as to maintain URL
+ namespace consistency.
+
+ Any headers included with DELETE MUST be applied in processing every
+ resource to be deleted.
+
+ When the DELETE method has completed processing it MUST result in a
+ consistent URL namespace.
+
+ If an error occurs deleting a member resource (a resource other than
+ the resource identified in the Request-URI) then the response can be
+ a 207 (Multi-Status). Multi-Status is used here to indicate which
+ internal resources could NOT be deleted, including an error code
+ which should help the client understand which resources caused the
+ failure. For example, the Multi-Status body could include a response
+ with status 423 (Locked) if an internal resource was locked.
+
+ The server MAY return a 4xx status response, rather than a 207, if
+ the request failed completely.
+
+ 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi-
+ Status) response for DELETE. They can be safely left out because the
+ client will know that the ancestors of a resource could not be
+ deleted when the client receives an error for the ancestor's progeny.
+ Additionally 204 (No Content) errors SHOULD NOT be returned in the
+ 207 (Multi-Status). The reason for this prohibition is that 204 (No
+ Content) is the default success code.
+
+9.6.2. Example - DELETE
+
+ >>Request
+
+ DELETE /container/ HTTP/1.1
+ Host: www.example.com
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 53]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.example.com/container/resource3</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+ In this example the attempt to delete
+ http://www.example.com/container/resource3 failed because it is
+ locked, and no lock token was submitted with the request.
+ Consequently, the attempt to delete http://www.example.com/container/
+ also failed. Thus the client knows that the attempt to delete
+ http://www.example.com/container/ must have also failed since the
+ parent can not be deleted unless its child has also been deleted.
+ Even though a Depth header has not been included, a depth of infinity
+ is assumed because the method is on a collection.
+
+9.7. PUT Requirements
+
+9.7.1. PUT for Non-Collection Resources
+
+ A PUT performed on an existing resource replaces the GET response
+ entity of the resource. Properties defined on the resource may be
+ recomputed during PUT processing but are not otherwise affected. For
+ example, if a server recognizes the content type of the request body,
+ it may be able to automatically extract information that could be
+ profitably exposed as properties.
+
+ A PUT that would result in the creation of a resource without an
+ appropriately scoped parent collection MUST fail with a 409
+ (Conflict).
+
+ A PUT request is the only way a client has to indicate to the server
+ what Content-Type a resource should have, and whether it should
+ change if the resource is overwritten. Thus, a client SHOULD provide
+ a Content-Type for a new resource if any is known. If the client
+ does not provide a Content-Type for a new resource, the server MAY
+ create a resource with no Content-Type assigned, or it MAY attempt to
+ assign a Content-Type.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 54]
+
+Internet-Draft WebDAV April 2006
+
+
+ Note that although a recipient should treat metadata supplied with an
+ HTTP request as authorative, in practice there's no guarantee that a
+ server will accept Content- headers. Many servers do not allow
+ configuring the Content-Type on a per-resource basis in the first
+ place. Thus, clients should not rely on the ability to directly
+ influence the content type by including a Content-Type request
+ header.
+
+9.7.2. PUT for Collections
+
+ This specification does not define the behavior of the PUT method for
+ existing collections. A PUT request to an existing collection MAY be
+ treated as an error (405 Method Not Allowed).
+
+ The MKCOL method is defined to create collections.
+
+9.8. COPY Method
+
+ The COPY method creates a duplicate of the source resource identified
+ by the Request-URI, in the destination resource identified by the URI
+ in the Destination header. The Destination header MUST be present.
+ The exact behavior of the COPY method depends on the type of the
+ source resource.
+
+ All WebDAV compliant resources MUST support the COPY method.
+ However, support for the COPY method does not guarantee the ability
+ to copy a resource. For example, separate programs may control
+ resources on the same server. As a result, it may not be possible to
+ copy a resource to a location that appears to be on the same server.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.8.1. COPY for Non-collection Resources
+
+ When the source resource is not a collection the result of the COPY
+ method is the creation of a new resource at the destination whose
+ state and behavior match that of the source resource as closely as
+ possible. Since the environment at the destination may be different
+ than at the source due to factors outside the scope of control of the
+ server, such as the absence of resources required for correct
+ operation, it may not be possible to completely duplicate the
+ behavior of the resource at the destination. Subsequent alterations
+ to the destination resource will not modify the source resource.
+ Subsequent alterations to the source resource will not modify the
+ destination resource.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 55]
+
+Internet-Draft WebDAV April 2006
+
+
+9.8.2. COPY for Properties
+
+ After a successful COPY invocation, all dead properties on the source
+ resource SHOULD be duplicated on the destination resource. Live
+ properties described in this document SHOULD be duplicated as
+ identically behaving live properties at the destination resource, but
+ not necessarily with the same values. Servers SHOULD NOT convert
+ live properties into dead properties on the destination resource,
+ because clients may then draw incorrect conclusions about the state
+ or functionality of a resource. Note that some live properties are
+ defined such that the absence of the property has a specific meaning
+ (e.g. a flag with one meaning if present and the opposite if absent),
+ and in these cases, a successful COPY might result in the property
+ being reported as "Not Found" in subsequent requests.
+
+ When the destination is an unmapped URL, a COPY operation creates a
+ new resource much like a PUT operation does. Live properties which
+ are related to resource creation (such as DAV:creationdate) should
+ have their values set accordingly.
+
+9.8.3. COPY for Collections
+
+ The COPY method on a collection without a Depth header MUST act as if
+ a Depth header with value "infinity" was included. A client may
+ submit a Depth header on a COPY on a collection with a value of "0"
+ or "infinity". Servers MUST support the "0" and "infinity" Depth
+ header behaviors on WebDAV-compliant resources.
+
+ A COPY of depth infinity instructs that the collection resource
+ identified by the Request-URI is to be copied to the location
+ identified by the URI in the Destination header, and all its internal
+ member resources are to be copied to a location relative to it,
+ recursively through all levels of the collection hierarchy. Note
+ that a depth infinity COPY of /A/ into /A/B/ could lead to infinite
+ recursion if not handled correctly.
+
+ A COPY of "Depth: 0" only instructs that the collection and its
+ properties but not resources identified by its internal member URLs,
+ are to be copied.
+
+ Any headers included with a COPY MUST be applied in processing every
+ resource to be copied with the exception of the Destination header.
+
+ The Destination header only specifies the destination URI for the
+ Request-URI. When applied to members of the collection identified by
+ the Request-URI the value of Destination is to be modified to reflect
+ the current location in the hierarchy. So, if the Request-URI is /a/
+ with Host header value http://example.com/ and the Destination is
+
+
+
+Dusseault Expires October 3, 2006 [Page 56]
+
+Internet-Draft WebDAV April 2006
+
+
+ http://example.com/b/ then when http://example.com/a/c/d is processed
+ it must use a Destination of http://example.com/b/c/d.
+
+ When the COPY method has completed processing it MUST have created a
+ consistent URL namespace at the destination (see Section 5.1 for the
+ definition of namespace consistency). However, if an error occurs
+ while copying an internal collection, the server MUST NOT copy any
+ resources identified by members of this collection (i.e., the server
+ must skip this subtree), as this would create an inconsistent
+ namespace. After detecting an error, the COPY operation SHOULD try
+ to finish as much of the original copy operation as possible (i.e.,
+ the server should still attempt to copy other subtrees and their
+ members, that are not descendents of an error-causing collection).
+
+ So, for example, if an infinite depth copy operation is performed on
+ collection /a/, which contains collections /a/b/ and /a/c/, and an
+ error occurs copying /a/b/, an attempt should still be made to copy
+ /a/c/. Similarly, after encountering an error copying a non-
+ collection resource as part of an infinite depth copy, the server
+ SHOULD try to finish as much of the original copy operation as
+ possible.
+
+ If an error in executing the COPY method occurs with a resource other
+ than the resource identified in the Request-URI then the response
+ MUST be a 207 (Multi-Status), and the URL of the resource causing the
+ failure MUST appear with the specific error.
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a COPY method. These responses can
+ be safely omitted because the client will know that the progeny of a
+ resource could not be copied when the client receives an error for
+ the parent. Additionally 201 (Created)/204 (No Content) status codes
+ SHOULD NOT be returned as values in 207 (Multi-Status) responses from
+ COPY methods. They, too, can be safely omitted because they are the
+ default success codes.
+
+9.8.4. COPY and Overwriting Destination Resources
+
+ If a COPY request has an Overwrite header with a value of "F", and a
+ resource exists at the Destination URL, the server MUST fail the
+ request.
+
+ When a server executes a COPY request and overwrites a destination
+ resource, the exact behavior MAY depend on many factors, including
+ WebDAV extension capabilities (see particularly [RFC3253]). For
+ example, when an ordinary resource is overwritten, the server could
+ delete the target resource before doing the copy, or could do an in-
+ place overwrite to preserve live properties.
+
+
+
+Dusseault Expires October 3, 2006 [Page 57]
+
+Internet-Draft WebDAV April 2006
+
+
+ When a collection is overwritten, the membership of the destination
+ collection after the successful COPY request MUST be the same
+ membership as the source collection immediately before the COPY.
+ Thus, merging the membership of the source and destination
+ collections together in the destination is not a compliant behavior.
+
+ In general, if clients require the state of the destination URL to be
+ wiped out prior to a COPY (e.g. to force live properties to be
+ reset), then the client could send a DELETE to the destination before
+ the COPY request to ensure this reset.
+
+9.8.5. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to COPY:
+
+ 201 (Created) - The source resource was successfully copied. The
+ COPY operation resulted in the creation of a new resource.
+
+ 204 (No Content) - The source resource was successfully copied to a
+ pre-existing destination resource.
+
+ 207 (Multi-Status) - Multiple resources were to be affected by the
+ COPY, but errors on some of them prevented the operation from taking
+ place. Specific error messages, together with the most appropriate
+ of the source and destination URLs, appear in the body of the multi-
+ status response. E.g. if a destination resource was locked and could
+ not be overwritten, then the destination resource URL appears with
+ the 423 (Locked) status.
+
+ 403 (Forbidden) - The operation is forbidden. A special case for
+ COPY could be that the source and destination resources are the same
+ resource.
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+
+ 412 (Precondition Failed) - A precondition header check failed, e.g.
+ the Overwrite header is "F" and the destination URL is already mapped
+ to a resource.
+
+ 423 (Locked) - The destination resource, or resource within the
+ destination collection, was locked. This response SHOULD contain the
+ 'lock-token-submitted' precondition element.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server, repository or URL namespace. Either the source namespace
+
+
+
+Dusseault Expires October 3, 2006 [Page 58]
+
+Internet-Draft WebDAV April 2006
+
+
+ does not support copying to the destination namespace, or the
+ destination namespace refuses to accept the resource. The client may
+ wish to try GET/PUT and PROPFIND/PROPPATCH instead.
+
+ 507 (Insufficient Storage) - The destination resource does not have
+ sufficient space to record the state of the resource after the
+ execution of this method.
+
+9.8.6. Example - COPY with Overwrite
+
+ This example shows resource
+ http://www.example.com/~fielding/index.html being copied to the
+ location http://www.example.com/users/f/fielding/index.html. The 204
+ (No Content) status code indicates the existing resource at the
+ destination was overwritten.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+9.8.7. Example - COPY with No Overwrite
+
+ The following example shows the same copy operation being performed,
+ but with the Overwrite header set to "F." A response of 412
+ (Precondition Failed) is returned because the destination URL is
+ already mapped to a resource.
+
+ >>Request
+
+ COPY /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/users/f/fielding/index.html
+ Overwrite: F
+
+ >>Response
+
+ HTTP/1.1 412 Precondition Failed
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 59]
+
+Internet-Draft WebDAV April 2006
+
+
+9.8.8. Example - COPY of a Collection
+
+ >>Request
+
+ COPY /container/ HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/othercontainer/
+ Depth: infinity
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+
+ <d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>http://www.example.com/othercontainer/R2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+ The Depth header is unnecessary as the default behavior of COPY on a
+ collection is to act as if a "Depth: infinity" header had been
+ submitted. In this example most of the resources, along with the
+ collection, were copied successfully. However the collection R2
+ failed because the destination R2 is locked. Because there was an
+ error copying R2, none of R2's members were copied. However no
+ errors were listed for those members due to the error minimization
+ rules.
+
+9.9. MOVE Method
+
+ The MOVE operation on a non-collection resource is the logical
+ equivalent of a copy (COPY), followed by consistency maintenance
+ processing, followed by a delete of the source, where all three
+ actions are performed in a single operation. The consistency
+ maintenance step allows the server to perform updates caused by the
+ move, such as updating all URLs other than the Request-URI which
+ identify the source resource, to point to the new destination
+ resource.
+
+ The Destination header MUST be present on all MOVE methods and MUST
+ follow all COPY requirements for the COPY part of the MOVE method.
+ All WebDAV compliant resources MUST support the MOVE method.
+
+
+
+Dusseault Expires October 3, 2006 [Page 60]
+
+Internet-Draft WebDAV April 2006
+
+
+ Support for the MOVE method does not guarantee the ability to move a
+ resource to a particular destination. For example, separate programs
+ may actually control different sets of resources on the same server.
+ Therefore, it may not be possible to move a resource within a
+ namespace that appears to belong to the same server.
+
+ If a resource exists at the destination, the destination resource
+ will be deleted as a side-effect of the MOVE operation, subject to
+ the restrictions of the Overwrite header.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.9.1. MOVE for Properties
+
+ Live properties described in this document SHOULD be moved along with
+ the resource, such that the resource has identically behaving live
+ properties at the destination resource, but not necessarily with the
+ same values. Note that some live properties are defined such that
+ the absence of the property has a specific meaning (e.g. a flag with
+ one meaning if present and the opposite if absent), and in these
+ cases, a successful MOVE might result in the property being reported
+ as "Not Found" in subsequent requests. If the live properties will
+ not work the same way at the destination, the server MAY fail the
+ request.
+
+ MOVE is frequently used by clients to rename a file without changing
+ its parent collection, so it's not appropriate to reset all live
+ properties which are set at resource creation. For example, the DAV:
+ creationdate property value SHOULD remain the same after a MOVE.
+
+ Dead properties MUST be moved along with the resource.
+
+9.9.2. MOVE for Collections
+
+ A MOVE with "Depth: infinity" instructs that the collection
+ identified by the Request-URI be moved to the address specified in
+ the Destination header, and all resources identified by its internal
+ member URLs are to be moved to locations relative to it, recursively
+ through all levels of the collection hierarchy.
+
+ The MOVE method on a collection MUST act as if a "Depth: infinity"
+ header was used on it. A client MUST NOT submit a Depth header on a
+ MOVE on a collection with any value but "infinity".
+
+ Any headers included with MOVE MUST be applied in processing every
+ resource to be moved with the exception of the Destination header.
+ The behavior of the Destination header is the same as given for COPY
+
+
+
+Dusseault Expires October 3, 2006 [Page 61]
+
+Internet-Draft WebDAV April 2006
+
+
+ on collections.
+
+ When the MOVE method has completed processing it MUST have created a
+ consistent URL namespace at both the source and destination (see
+ section 5.1 for the definition of namespace consistency). However,
+ if an error occurs while moving an internal collection, the server
+ MUST NOT move any resources identified by members of the failed
+ collection (i.e., the server must skip the error-causing subtree), as
+ this would create an inconsistent namespace. In this case, after
+ detecting the error, the move operation SHOULD try to finish as much
+ of the original move as possible (i.e., the server should still
+ attempt to move other subtrees and the resources identified by their
+ members, that are not descendents of an error-causing collection).
+ So, for example, if an infinite depth move is performed on collection
+ /a/, which contains collections /a/b/ and /a/c/, and an error occurs
+ moving /a/b/, an attempt should still be made to try moving /a/c/.
+ Similarly, after encountering an error moving a non-collection
+ resource as part of an infinite depth move, the server SHOULD try to
+ finish as much of the original move operation as possible.
+
+ If an error occurs with a resource other than the resource identified
+ in the Request-URI then the response MUST be a 207 (Multi-Status),
+ and the errored resource's URL MUST appear with the specific error.
+
+ The 424 (Failed Dependency) status code SHOULD NOT be returned in the
+ 207 (Multi-Status) response from a MOVE method. These errors can be
+ safely omitted because the client will know that the progeny of a
+ resource could not be moved when the client receives an error for the
+ parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
+ NOT be returned as values in 207 (Multi-Status) responses from a
+ MOVE. These responses can be safely omitted because they are the
+ default success codes.
+
+9.9.3. MOVE and the Overwrite Header
+
+ If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the move the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource. If the
+ Overwrite header is set to "F" then the operation will fail.
+
+9.9.4. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to MOVE:
+
+ 201 (Created) - The source resource was successfully moved, and a new
+ URL mapping was created at the destination.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 62]
+
+Internet-Draft WebDAV April 2006
+
+
+ 204 (No Content) - The source resource was successfully moved to a
+ URL that was already mapped.
+
+ 207 (Multi-Status) - Multiple resources were to be affected by the
+ MOVE, but errors on some of them prevented the operation from taking
+ place. Specific error messages, together with the most appropriate
+ of the source and destination URLs, appear in the body of the multi-
+ status response. E.g. if a source resource was locked and could not
+ be moved, then the source resource URL appears with the 423 (Locked)
+ status.
+
+ 403 (Forbidden) - Among many possible reasons for forbidding a MOVE
+ operation, this status code is recommended for use when the source
+ and destination resources are the same.
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+ Or, the server was unable to preserve the behavior of the live
+ properties and still move the resource to the destination (see
+ 'preserved-live-properties' postcondition).
+
+ 412 (Precondition Failed) - A condition header failed. Specific to
+ MOVE, this could mean that the Overwrite header is "F" and the
+ destination URL is already mapped to a resource.
+
+ 423 (Locked) - The source or the destination resource, the source or
+ destination resource parent, or some resource within the source or
+ destination collection, was locked. This response SHOULD contain the
+ 'lock-token-submitted' precondition element.
+
+ 502 (Bad Gateway) - This may occur when the destination is on another
+ server and the destination server refuses to accept the resource.
+ This could also occur when the destination is on another sub-section
+ of the same server namespace.
+
+9.9.5. Example - MOVE of a Non-Collection
+
+ This example shows resource
+ http://www.example.com/~fielding/index.html being moved to the
+ location http://www.example.com/users/f/fielding/index.html. The
+ contents of the destination resource would have been overwritten if
+ the destination URL was already mapped to a resource. In this case,
+ since there was nothing at the destination resource, the response
+ code is 201 (Created).
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 63]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Request
+
+ MOVE /~fielding/index.html HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example/users/f/fielding/index.html
+
+ >>Response
+
+ HTTP/1.1 201 Created
+ Location: http://www.example.com/users/f/fielding/index.html
+
+9.9.6. Example - MOVE of a Collection
+
+ >>Request
+
+ MOVE /container/ HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/othercontainer/
+ Overwrite: F
+ If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
+ (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <d:multistatus xmlns:d='DAV:'>
+ <d:response>
+ <d:href>http://www.example.com/othercontainer/C2/</d:href>
+ <d:status>HTTP/1.1 423 Locked</d:status>
+ <d:error><d:lock-token-submitted/></d:error>
+ </d:response>
+ </d:multistatus>
+
+ In this example the client has submitted a number of lock tokens with
+ the request. A lock token will need to be submitted for every
+ resource, both source and destination, anywhere in the scope of the
+ method, that is locked. In this case the proper lock token was not
+ submitted for the destination
+ http://www.example.com/othercontainer/C2/. This means that the
+ resource /container/C2/ could not be moved. Because there was an
+ error moving /container/C2/, none of /container/C2's members were
+ moved. However no errors were listed for those members due to the
+ error minimization rules. User agent authentication has previously
+ occurred via a mechanism outside the scope of the HTTP protocol, in
+
+
+
+Dusseault Expires October 3, 2006 [Page 64]
+
+Internet-Draft WebDAV April 2006
+
+
+ an underlying transport layer.
+
+9.10. LOCK Method
+
+ The following sections describe the LOCK method, which is used to
+ take out a lock of any access type and to refresh an existing lock.
+ These sections on the LOCK method describe only those semantics that
+ are specific to the LOCK method and are independent of the access
+ type of the lock being requested.
+
+ Any resource which supports the LOCK method MUST, at minimum, support
+ the XML request and response formats defined herein.
+
+ This method is neither idempotent nor safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.10.1. Creating a lock on existing resource
+
+ A LOCK request to an existing resource will create a lock on the
+ resource identified by the Request-URI, provided the resource is not
+ already locked with a conflicting lock. The resource identified in
+ the Request-URI becomes the root of the lock. Lock method requests
+ to create a new lock MUST have an XML request body. The server MUST
+ preserve the information provided by the client in the 'owner' field
+ in the request body when the lock information is requested. The LOCK
+ request MAY have a Timeout header.
+
+ When a new lock is created, the LOCK response:
+
+ o MUST contain a body with the value of the DAV:lockdiscovery
+ property in a prop XML element. This MUST contain the full
+ information about the lock just granted, while information about
+ other (shared) locks is OPTIONAL.
+
+ o MUST include the Lock-Token response header with the token
+ associated with the new lock.
+
+9.10.2. Refreshing Locks
+
+ A lock is refreshed by sending a LOCK request to the URL of a
+ resource within the scope of the lock. This request MUST NOT have a
+ body and it MUST specify which lock to refresh by using the 'If'
+ header with a single lock token (only one lock may be refreshed at a
+ time). The request MAY contain a Timeout header, which a server MAY
+ accept to change the duration remaining on the lock to the new value.
+ A server MUST ignore the Depth header on a LOCK refresh.
+
+ If the resource has other (shared) locks, those locks are unaffected
+
+
+
+Dusseault Expires October 3, 2006 [Page 65]
+
+Internet-Draft WebDAV April 2006
+
+
+ by a lock refresh. Additionally, those locks do not prevent the
+ named lock from being refreshed.
+
+ The Lock-Token header is not returned in the response for a
+ successful refresh LOCK request, but the LOCK response body MUST
+ contain the new value for the DAV:lockdiscovery body.
+
+9.10.3. Depth and Locking
+
+ The Depth header may be used with the LOCK method. Values other than
+ 0 or infinity MUST NOT be used with the Depth header on a LOCK
+ method. All resources that support the LOCK method MUST support the
+ Depth header.
+
+ A Depth header of value 0 means to just lock the resource specified
+ by the Request-URI.
+
+ If the Depth header is set to infinity then the resource specified in
+ the Request-URI along with all its members, all the way down the
+ hierarchy, are to be locked. A successful result MUST return a
+ single lock token. Similarly, if an UNLOCK is successfully executed
+ on this token, all associated resources are unlocked. Hence, partial
+ success is not an option for LOCK or UNLOCK. Either the entire
+ hierarchy is locked or no resources are locked.
+
+ If the lock cannot be granted to all resources, the server MUST
+ return a Multi-Status response with a 'response' element for at least
+ one resource which prevented the lock from being granted, along with
+ a suitable status code for that failure (e.g. 403 (Forbidden) or 423
+ (Locked)). Additionally, if the resource causing the failure was not
+ the resource requested, then the server SHOULD include a 'response'
+ element for the Request-URI as well, with a 'status' element
+ containing 424 Failed Dependency.
+
+ If no Depth header is submitted on a LOCK request then the request
+ MUST act as if a "Depth:infinity" had been submitted.
+
+9.10.4. Locking Unmapped URLs
+
+ A successful LOCK method MUST result in the creation of an empty
+ resource which is locked (and which is not a collection), when a
+ resource did not previously exist at that URL. Later on, the lock
+ may go away but the empty resource remains. Empty resources MUST
+ then appear in PROPFIND responses including that URL in the response
+ scope. A server MUST respond successfully to a GET request to an
+ empty resource, either by using a 204 No Content response, or by
+ using 200 OK with a Content-Length header indicating zero length
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 66]
+
+Internet-Draft WebDAV April 2006
+
+
+9.10.5. Lock Compatibility Table
+
+ The table below describes the behavior that occurs when a lock
+ request is made on a resource.
+
+ +--------------------------+----------------+-------------------+
+ | Current State | Shared Lock OK | Exclusive Lock OK |
+ +--------------------------+----------------+-------------------+
+ | None | True | True |
+ | | | |
+ | Shared Lock | True | False |
+ | | | |
+ | Exclusive Lock | False | False* |
+ +--------------------------+----------------+-------------------+
+
+ Legend: True = lock may be granted. False = lock MUST NOT be
+ granted. *=It is illegal for a principal to request the same lock
+ twice.
+
+ The current lock state of a resource is given in the leftmost column,
+ and lock requests are listed in the first row. The intersection of a
+ row and column gives the result of a lock request. For example, if a
+ shared lock is held on a resource, and an exclusive lock is
+ requested, the table entry is "false", indicating the lock must not
+ be granted.
+
+9.10.6. LOCK Responses
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to LOCK:
+
+ 200 (OK) - The LOCK request succeeded and the value of the DAV:
+ lockdiscovery property is included in the response body.
+
+ 201 (Created) - The LOCK request was to an unmapped URL, the request
+ succeeded and resulted in the creation of a new resource, and the
+ value of the DAV:lockdiscovery property is included in the response
+ body.
+
+ 409 (Conflict) - A resource cannot be created at the destination
+ until one or more intermediate collections have been created. The
+ server MUST NOT create those intermediate collections automatically.
+
+ 423 (Locked), potentially with 'no-conflicting-lock' precondition
+ code - There is already a lock on the resource which is not
+ compatible with the requested lock (see lock compatibility table
+ above).
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 67]
+
+Internet-Draft WebDAV April 2006
+
+
+ 412 (Precondition Failed), with 'lock-token-matches-request-uri'
+ precondition code - The LOCK request was made with a If header,
+ indicating that the client wishes to refresh the given lock.
+ However, the Request-URI did not fall within the scope of the lock
+ identified by the token. The lock may have a scope that does not
+ include the Request-URI, or the lock could have disappeared, or the
+ token may be invalid.
+
+9.10.7. Example - Simple Lock Request
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw at example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D='DAV:'>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 68]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>infinity</D:depth>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href
+ >http://example.com/workspace/webdav/proposal.doc</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+
+ This example shows the successful creation of an exclusive write lock
+ on resource http://example.com/workspace/webdav/proposal.doc. The
+ resource http://example.org/~ejw/contact.html contains contact
+ information for the creator of the lock. The server has an activity-
+ based timeout policy in place on this resource, which causes the lock
+ to automatically be removed after 1 week (604800 seconds). Note that
+ the nonce, response, and opaque fields have not been calculated in
+ the Authorization request header.
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 69]
+
+Internet-Draft WebDAV April 2006
+
+
+9.10.8. Example - Refreshing a Write Lock
+
+ >>Request
+
+ LOCK /workspace/webdav/proposal.doc HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
+ Authorization: Digest username="ejw",
+ realm="ejw at example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 200 OK
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:prop xmlns:D="DAV:">
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>infinity</D:depth>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ <D:timeout>Second-604800</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href
+ >http://example.com/workspace/webdav/proposal.doc</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+
+
+ This request would refresh the lock, attempting to reset the timeout
+ to the new value specified in the timeout header. Notice that the
+ client asked for an infinite time out but the server choose to ignore
+ the request. In this example, the nonce, response, and opaque fields
+ have not been calculated in the Authorization request header.
+
+
+
+Dusseault Expires October 3, 2006 [Page 70]
+
+Internet-Draft WebDAV April 2006
+
+
+9.10.9. Example - Multi-Resource Lock Request
+
+ >>Request
+
+ LOCK /webdav/ HTTP/1.1
+ Host: example.com
+ Timeout: Infinite, Second-4100000000
+ Depth: infinity
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="ejw at example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:lockinfo xmlns:D="DAV:">
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:owner>
+ <D:href>http://example.org/~ejw/contact.html</D:href>
+ </D:owner>
+ </D:lockinfo>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://example.com/webdav/secret</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://example.com/webdav/</D:href>
+ <D:status>HTTP/1.1 424 Failed Dependency</D:status>
+ </D:response>
+ </D:multistatus>
+
+
+ This example shows a request for an exclusive write lock on a
+ collection and all its children. In this request, the client has
+ specified that it desires an infinite length lock, if available,
+ otherwise a timeout of 4.1 billion seconds, if available. The
+ request entity body contains the contact information for the
+
+
+
+Dusseault Expires October 3, 2006 [Page 71]
+
+Internet-Draft WebDAV April 2006
+
+
+ principal taking out the lock, in this case a web page URL.
+
+ The error is a 403 (Forbidden) response on the resource
+ http://example.com/webdav/secret. Because this resource could not be
+ locked, none of the resources were locked. Note also that the a
+ 'response' element for the Request-URI itself has been included as
+ required.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+9.11. UNLOCK Method
+
+ The UNLOCK method removes the lock identified by the lock token in
+ the Lock-Token request header. The Request-URI MUST identify a
+ resource within the scope of the lock.
+
+ Note that use of Lock-Token header to provide the lock token is not
+ consistent with other state-changing methods which all require an If
+ header with the lock token. Thus, the If header is not needed to
+ provide the lock token. Naturally when the If header is present it
+ has its normal meaning as a conditional header.
+
+ For a successful response to this method, the server MUST delete the
+ lock entirely.
+
+ If all resources which have been locked under the submitted lock
+ token can not be unlocked then the UNLOCK request MUST fail.
+
+ A successful response to an UNLOCK method does not mean that the
+ resource is necessarily unlocked. It means that the specific lock
+ corresponding to the specified token no longer exists.
+
+ Any DAV compliant resource which supports the LOCK method MUST
+ support the UNLOCK method.
+
+ This method is idempotent, but not safe (see Section 9.1 of
+ [RFC2616]). Responses to this method MUST NOT be cached.
+
+9.11.1. Status Codes
+
+ In addition to the general status codes possible, the following
+ status codes have specific applicability to UNLOCK:
+
+ 204 (No Content) - Normal success response (rather than 200 OK, since
+ 200 OK would imply a response body, and an UNLOCK success response
+ does not normally contain a body)
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 72]
+
+Internet-Draft WebDAV April 2006
+
+
+ 400 (Bad Request) - No lock token was provided.
+
+ 403 (Forbidden) - The currently authenticated principal does not have
+ permission to remove the lock.
+
+ 409 (Conflict), with 'lock-token-matches-request-uri' precondition -
+ The resource was not locked, or the request was made to a Request-URI
+ that was not within the scope of the lock.
+
+9.11.2. Example - UNLOCK
+
+ >>Request
+
+ UNLOCK /workspace/webdav/info.doc HTTP/1.1
+ Host: example.com
+ Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
+ Authorization: Digest username="ejw"
+ realm="ejw at example.com", nonce="...",
+ uri="/workspace/webdav/proposal.doc",
+ response="...", opaque="..."
+
+ >>Response
+
+ HTTP/1.1 204 No Content
+
+ In this example, the lock identified by the lock token
+ "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully
+ removed from the resource
+ http://example.com/workspace/webdav/info.doc. If this lock included
+ more than just one resource, the lock is removed from all resources
+ included in the lock.
+
+ In this example, the nonce, response, and opaque fields have not been
+ calculated in the Authorization request header.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 73]
+
+Internet-Draft WebDAV April 2006
+
+
+10. HTTP Headers for Distributed Authoring
+
+ All DAV headers follow the same basic formatting rules as HTTP
+ headers. This includes rules like line continuation and how to
+ combine (or separate) multiple instances of the same header using
+ commas.
+
+ WebDAV adds two new conditional headers to the set defined in HTTP:
+ the If and Overwrite headers.
+
+10.1. DAV Header
+
+ DAV = "DAV" ":" #( compliance-class )
+ compliance-class = ( "1" | "2" | "3" | extend )
+ extend = Coded-URL | token
+ Coded-URL = "<" absolute-URI ">"
+ ; No LWS allowed in Coded-URL
+ ; absolute-URI is defined in RFC3986
+
+ This general-header appearing in the response indicates that the
+ resource supports the DAV schema and protocol as specified. All DAV
+ compliant resources MUST return the DAV header with compliance-class
+ "1" on all OPTIONS responses. In cases where WebDAV is only
+ supported in part of the server namespace, an OPTIONS request to non-
+ WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.
+
+ The value is a comma-separated list of all compliance class
+ identifiers that the resource supports. Class identifiers may be
+ Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can
+ appear in any order. Identifiers that are standardized through the
+ IETF RFC process are tokens, but other identifiers SHOULD be Coded-
+ URLs to encourage uniqueness.
+
+ A resource must show class 1 compliance if it shows class 2 or 3
+ compliance. In general, support for one compliance class does not
+ entail support for any other, and in particular, support for
+ compliance class 3 does not require support for compliance class 2.
+ Please refer to Section 18 for more details on compliance classes
+ defined in this specification.
+
+ Note that many WebDAV servers do not advertise WebDAV support in
+ response to "OPTIONS *".
+
+ As a request header, this header allows the client to advertise
+ compliance with named features when the server needs that
+ information. Clients SHOULD NOT send this header unless a standards
+ track specification requires it. Any extension that makes use of
+ this as a request header will need to carefully consider caching
+
+
+
+Dusseault Expires October 3, 2006 [Page 74]
+
+Internet-Draft WebDAV April 2006
+
+
+ implications.
+
+10.2. Depth Header
+
+ Depth = "Depth" ":" ("0" | "1" | "infinity")
+
+ The Depth request header is used with methods executed on resources
+ which could potentially have internal members to indicate whether the
+ method is to be applied only to the resource ("Depth: 0"), to the
+ resource and its internal members only, ("Depth: 1"), or the resource
+ and all its members ("Depth: infinity").
+
+ The Depth header is only supported if a method's definition
+ explicitly provides for such support.
+
+ The following rules are the default behavior for any method that
+ supports the Depth header. A method may override these defaults by
+ defining different behavior in its definition.
+
+ Methods which support the Depth header may choose not to support all
+ of the header's values and may define, on a case by case basis, the
+ behavior of the method if a Depth header is not present. For
+ example, the MOVE method only supports "Depth: infinity" and if a
+ Depth header is not present will act as if a "Depth: infinity" header
+ had been applied.
+
+ Clients MUST NOT rely upon methods executing on members of their
+ hierarchies in any particular order or on the execution being atomic
+ unless the particular method explicitly provides such guarantees.
+
+ Upon execution, a method with a Depth header will perform as much of
+ its assigned task as possible and then return a response specifying
+ what it was able to accomplish and what it failed to do.
+
+ So, for example, an attempt to COPY a hierarchy may result in some of
+ the members being copied and some not.
+
+ By default, the Depth header does not interact with other headers.
+ That is, each header on a request with a Depth header MUST be applied
+ only to the Request-URI if it applies to any resource, unless
+ specific Depth behavior is defined for that header.
+
+ If a resource, source or destination, within the scope of the method
+ with a Depth header is locked in such a way as to prevent the
+ successful execution of the method, then the lock token for that
+ resource MUST be submitted with the request in the If request header.
+
+ The Depth header only specifies the behavior of the method with
+
+
+
+Dusseault Expires October 3, 2006 [Page 75]
+
+Internet-Draft WebDAV April 2006
+
+
+ regards to internal members. If a resource does not have internal
+ members then the Depth header MUST be ignored.
+
+10.3. Destination Header
+
+ The Destination request header specifies the URI which identifies a
+ destination resource for methods such as COPY and MOVE, which take
+ two URIs as parameters.
+
+ Destination = "Destination" ":" Simple-ref
+
+ If the Destination value is an absolute-URI (Section 4.3 of
+ [RFC3986]), it may name a different server (or different port or
+ scheme). If the source server cannot attempt a copy to the remote
+ server, it MUST fail the request. Note that copying and moving
+ resources to remote servers is not fully defined in this
+ specification (e.g. specific error conditions).
+
+ If the Destination value is too long or otherwise unacceptable, the
+ server SHOULD return 400 (Bad Request), ideally with helpful
+ information in an error body.
+
+10.4. If Header
+
+ The If request header is intended to have similar functionality to
+ the If-Match header defined in Section 14.24 of [RFC2616]. However
+ the If header handles any state token as well as ETags. A typical
+ example of a state token is a lock token, and lock tokens are the
+ only state tokens defined in this specification.
+
+10.4.1. Purpose
+
+ The If header has two distinct purposes:
+
+ o The first purpose is to make a request conditional by supplying a
+ series of state lists with conditions that match tokens and ETags
+ to specific resource. If this header is evaluated and all state
+ lists fail, then the request MUST fail with a 412 (Precondition
+ Failed) status. On the other hand, the request can succeed only
+ if one of the described state lists succeeds. The success
+ criteria for state lists and matching functions are defined in
+ Section 10.4.3 and Section 10.4.4.
+
+ o Additionally, the mere fact that a state token appears in an If
+ header means that it has been "submitted" with the request. In
+ general, this is used to indicate that the client has knowledge of
+ that state token. The semantics for submitting a state token
+ depend on its type (for lock tokens, please refer to Section 6).
+
+
+
+Dusseault Expires October 3, 2006 [Page 76]
+
+Internet-Draft WebDAV April 2006
+
+
+ Note that these two purposes need to be treated distinctly: a state
+ token counts as being submitted independently of whether the server
+ actually has evaluated the state list it appears in, and also
+ independently of whether the condition it expressed was found to be
+ true or not.
+
+10.4.2. Syntax
+
+ If = "If" ":" ( 1*No-tag-list | 1*Tagged-list )
+
+ No-tag-list = List
+ Tagged-list = Resource-Tag 1*List
+
+ List = "(" 1*Condition ")"
+ Condition = ["Not"] (State-token | "[" entity-tag "]")
+ ; entity-tag: see Section 3.11 of [RFC2616]
+ ; No LWS allowed between "[", entity-tag and "]"
+
+ State-token = Coded-URL
+
+ Resource-Tag = "<" Simple-ref ">"
+ ; Simple-ref: see Section 8.3
+ ; No LWS allowed in Resource-Tag
+
+ The syntax distinguishes between untagged lists ("No-tag-list") and
+ tagged lists ("Tagged-list"). Untagged lists apply to the resource
+ identified by the Request-URI, while tagged lists apply to the
+ resource identified by the preceding Resource-Tag.
+
+ A Resource-Tag applies to all subsequent Lists, up to the next
+ Resource-Tag.
+
+ Note that the two list types cannot be mixed within an If header.
+ This is not a functional restriction because the No-tag-list syntax
+ is just a shorthand notation for a Tagged-list production with a
+ Resource-Tag referring to the Request-URI.
+
+ Each List consists of one or more Conditions. Each Condition is
+ defined in terms of an entity-tag or state-token, potentially negated
+ by the prefix "Not".
+
+ Note that the If header syntax does not allow multiple instances of
+ If headers in a single request. However, the HTTP header syntax
+ allows extending single header values across multiple lines, by
+ inserting a line break followed by whitespace (see [RFC2616], Section
+ 4.2).
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 77]
+
+Internet-Draft WebDAV April 2006
+
+
+10.4.3. List Evaluation
+
+ A Condition that consists of a single entity-tag or state-token
+ evaluates to true if the resource matches the described state (where
+ the individual matching functions are defined below in
+ Section 10.4.4). Prefixing it with "Not" reverses the result of the
+ evaluation (thus, the "Not" applies only to the subsequent entity-tag
+ or state-token).
+
+ Each List production describes a series of conditions. The whole
+ list evaluates to true if and only if each condition evaluates to
+ true (that is, the list represents a logical conjunction of
+ Conditions).
+
+ Each No-tag-list and Tagged-list production may contain one or more
+ Lists. They evaluate to true if and only if any of the contained
+ lists evaluates to true (that is, if there's more than one List, that
+ List sequence represents a logical disjunction of the Lists).
+
+ Finally, the whole If header evaluates to true if and only if at
+ least one of the No-tag-list or Tagged-list productions evaluates to
+ true. If the header evaluates to false, the server MUST reject the
+ request with a 412 (Precondition Failed) status. Otherwise,
+ execution of the request can proceed as if the header wasn't present.
+
+10.4.4. Matching State Tokens and ETags
+
+ When performing If header processing, the definition of a matching
+ state token or entity tag is as follows:
+
+ Identifying a resource: The resource is identified by the URI along
+ with the token, in tagged list production, or by the Request-URI in
+ untagged list production.
+
+ Matching entity tag: Where the entity tag matches an entity tag
+ associated with the identified resource. Servers MUST use either the
+ weak or the strong comparison function defined in Section 13.3.3 of
+ [RFC2616].
+
+ Matching state token: Where there is an exact match between the state
+ token in the If header and any state token on the identified
+ resource. A lock state token is considered to match if the resource
+ is anywhere in the scope of the lock.
+
+ Handling unmapped URLs: for both ETags and state tokens, treat as if
+ the URL identified a resource that exists but does not have the
+ specified state.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 78]
+
+Internet-Draft WebDAV April 2006
+
+
+10.4.5. If Header and Non-DAV Aware Proxies
+
+ Non-DAV aware proxies will not honor the If header, since they will
+ not understand the If header, and HTTP requires non-understood
+ headers to be ignored. When communicating with HTTP/1.1 proxies, the
+ client MUST use the "Cache-Control: no-cache" request header so as to
+ prevent the proxy from improperly trying to service the request from
+ its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
+ request header MUST be used for the same reason.
+
+ As in general clients may not be able to reliably detect non-DAV
+ aware intermediates, they are advised to always prevent caching using
+ the request directives mentioned above.
+
+10.4.6. Example - No-tag Production
+
+ If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ ["I am an ETag"])
+ (["I am another ETag"])
+
+ The previous header would require that the resource identified in the
+ Request-URI be locked with the specified lock token and be in the
+ state identified by the "I am an ETag" ETag or in the state
+ identified by the second ETag "I am another ETag".
+
+ To put the matter more plainly one can think of the previous If
+ header as expressing the condition below:
+
+ (
+ is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
+ matches-etag("I am an ETag")
+ )
+ OR
+ (
+ matches-etag("I am another ETag")
+ )
+
+10.4.7. Example - using "Not" with No-tag Production
+
+ If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)
+
+ This If header requires that the resource must not be locked with a
+ lock having the lock token
+ urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
+ lock with the lock token
+ urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 79]
+
+Internet-Draft WebDAV April 2006
+
+
+10.4.8. Example - causing a Condition to always evaluate to True
+
+ There may be cases where a client wishes to submit state tokens, but
+ doesn't want the request to fail just because the state token isn't
+ current anymore. One simple way to do this is to include a Condition
+ that is known to always evaluate to true, such as in:
+
+ If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
+ (Not <DAV:no-lock>)
+
+ "DAV:no-lock" is known to never represent a current lock token, as
+ lock tokens are assigned by the server, following the uniqueness
+ requirements described in Section 6.5, therefore in particular
+ exclude URIs in the "DAV:" scheme. Thus, by applying "Not" to a
+ known not to be current state token, the Condition always evaluates
+ to true. Consequently, the whole If header will always evaluate to
+ true, and the lock token
+ urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be submitted in
+ any case.
+
+10.4.9. Example - Tagged List If header in COPY
+
+ >>Request
+
+ COPY /resource1 HTTP/1.1
+ Host: www.example.com
+ Destination: /resource2
+ If: </resource1>
+ (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
+ [W/"A weak ETag"]) (["strong ETag"])
+
+ In this example http://www.example.com/resource1 is being copied to
+ http://www.example.com/resource2. When the method is first applied
+ to http://www.example.com/resource1, resource1 must be in the state
+ specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
+ weak ETag"]) (["strong ETag"])", that is, it either must be locked
+ with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
+ and have a weak entity tag W/"A weak ETag" or it must have a strong
+ entity tag "strong ETag".
+
+10.4.10. Example - Matching lock tokens with collection locks
+
+ DELETE /specs/rfc2518.txt HTTP/1.1
+ Host: www.example.com
+ If: <http://www.example.com/specs/>
+ (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
+
+ For this example, the lock token must be compared to the identified
+
+
+
+Dusseault Expires October 3, 2006 [Page 80]
+
+Internet-Draft WebDAV April 2006
+
+
+ resource, which is the 'specs' collection identified by the URL in
+ the tagged list production. If the 'specs' collection is not locked
+ by a lock with the specified lock token, the request MUST fail.
+ Otherwise, this request could succeed, because the If header
+ evaluates to true, and because the lock token for the lock affecting
+ the affected resource has been submitted.
+
+10.4.11. Example - Matching ETags on unmapped URLs
+
+ Consider a collection "/specs" that does not contain the member
+ "/specs/rfc2518.doc". In this case, the If header
+
+ If: </specs/rfc2518.doc> (["4217"])
+
+ will evaluate to false (the URI isn't mapped, thus the resource
+ identified by the URI doesn't have an entity matching the ETag
+ "4217").
+
+ On the other hand, an If header of
+
+ If: </specs/rfc2518.doc> (Not ["4217"])
+
+ will consequently evaluate to true.
+
+ Note that as defined above in Section 10.4.4, the same considerations
+ apply to matching state tokens.
+
+10.5. Lock-Token Header
+
+ Lock-Token = "Lock-Token" ":" Coded-URL
+
+ The Lock-Token request header is used with the UNLOCK method to
+ identify the lock to be removed. The lock token in the Lock-Token
+ request header MUST identify a lock that contains the resource
+ identified by Request-URI as a member.
+
+ The Lock-Token response header is used with the LOCK method to
+ indicate the lock token created as a result of a successful LOCK
+ request to create a new lock.
+
+10.6. Overwrite Header
+
+ Overwrite = "Overwrite" ":" ("T" | "F")
+
+ The Overwrite request header specifies whether the server should
+ overwrite a resource mapped to the destination URL during a COPY or
+ MOVE. A value of "F" states that the server must not perform the
+ COPY or MOVE operation if the destination URL does map to a resource.
+
+
+
+Dusseault Expires October 3, 2006 [Page 81]
+
+Internet-Draft WebDAV April 2006
+
+
+ If the overwrite header is not included in a COPY or MOVE request
+ then the resource MUST treat the request as if it has an overwrite
+ header of value "T". While the Overwrite header appears to duplicate
+ the functionality of the If-Match: * header of HTTP/1.1, If-Match
+ applies only to the Request-URI, and not to the Destination of a COPY
+ or MOVE.
+
+ If a COPY or MOVE is not performed due to the value of the Overwrite
+ header, the method MUST fail with a 412 (Precondition Failed) status
+ code. The server MUST do authorization checks before checking this
+ or any conditional header.
+
+ All DAV compliant resources MUST support the Overwrite header.
+
+10.7. Timeout Request Header
+
+ TimeOut = "Timeout" ":" 1#TimeType
+ TimeType = ("Second-" DAVTimeOutVal | "Infinite")
+ ; No LWS allowed within TimeType
+ DAVTimeOutVal = 1*DIGIT
+
+ Clients MAY include Timeout request headers in their LOCK requests.
+ However, the server is not required to honor or even consider these
+ requests. Clients MUST NOT submit a Timeout request header with any
+ method other than a LOCK method.
+
+ The "Second" TimeType specifies the number of seconds that will
+ elapse between granting of the lock at the server, and the automatic
+ removal of the lock. The timeout value for TimeType "Second" MUST
+ NOT be greater than 2^32-1.
+
+ See Section 6.6 for a description of lock timeout behavior.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 82]
+
+Internet-Draft WebDAV April 2006
+
+
+11. Status Code Extensions to HTTP/1.1
+
+ The following status codes are added to those defined in HTTP/1.1
+ [RFC2616].
+
+11.1. 207 Multi-Status
+
+ The 207 (Multi-Status) status code provides status for multiple
+ independent operations (see Section 13 for more information).
+
+11.2. 422 Unprocessable Entity
+
+ The 422 (Unprocessable Entity) status code means the server
+ understands the content type of the request entity (hence a
+ 415(Unsupported Media Type) status code is inappropriate), and the
+ syntax of the request entity is correct (thus a 400 (Bad Request)
+ status code is inappropriate) but was unable to process the contained
+ instructions. For example, this error condition may occur if an XML
+ request body contains well-formed (i.e., syntactically correct), but
+ semantically erroneous XML instructions.
+
+11.3. 423 Locked
+
+ The 423 (Locked) status code means the source or destination resource
+ of a method is locked. This response SHOULD contain an appropriate
+ precondition or postcondition code, such as 'lock-token-submitted' or
+ 'no-conflicting-lock".
+
+11.4. 424 Failed Dependency
+
+ The 424 (Failed Dependency) status code means that the method could
+ not be performed on the resource because the requested action
+ depended on another action and that action failed. For example, if a
+ command in a PROPPATCH method fails then, at minimum, the rest of the
+ commands will also fail with 424 (Failed Dependency).
+
+11.5. 507 Insufficient Storage
+
+ The 507 (Insufficient Storage) status code means the method could not
+ be performed on the resource because the server is unable to store
+ the representation needed to successfully complete the request. This
+ condition is considered to be temporary. If the request which
+ received this status code was the result of a user action, the
+ request MUST NOT be repeated until it is requested by a separate user
+ action.
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 83]
+
+Internet-Draft WebDAV April 2006
+
+
+12. Use of HTTP Status Codes
+
+ These HTTP codes are not redefined, but their use is somewhat
+ extended by WebDAV methods and requirements. In general, many HTTP
+ status codes can be used in response to any request, not just in
+ cases described in this document. Note also that WebDAV servers are
+ known to use 300-level redirect responses (and early interoperability
+ tests found clients unprepared to see those responses). A 300-level
+ response MUST NOT be used when the server has created a new resource
+ in response to the request.
+
+12.1. 412 Precondition Failed
+
+ Any request can contain a conditional header defined in HTTP (If-
+ Match, If-Modified-Since, etc.) or the "If" or "Overwrite"
+ conditional headers defined in this specification. If the server
+ evaluates a conditional header, and if that condition fails to hold,
+ then this error code MUST be returned. On the other hand, if the
+ client did not include a conditional header in the request, then the
+ server MUST NOT use this status code.
+
+12.2. 414 Request-URI Too Long
+
+ This status code is used in HTTP 1.1 only for Request-URIs, not URIs
+ in other locations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 84]
+
+Internet-Draft WebDAV April 2006
+
+
+13. Multi-Status Response
+
+ A Multi-Status response conveys information about multiple resources
+ in situations where multiple status codes might be appropriate. The
+ default Multi-Status response body is a text/xml or application/xml
+ HTTP entity with a 'multistatus' root element. Further elements
+ contain 200, 300, 400, and 500 series status codes generated during
+ the method invocation. 100 series status codes SHOULD NOT be recorded
+ in a 'response' XML element.
+
+ Although '207' is used as the overall response status code, the
+ recipient needs to consult the contents of the multistatus response
+ body for further information about the success or failure of the
+ method execution. The response MAY be used in success, partial
+ success and also in failure situations.
+
+ The 'multistatus' root element holds zero or more 'response' elements
+ in any order, each with information about an individual resource.
+ Each 'response' element MUST have an 'href' element to identify the
+ resource.
+
+ A Multi-Status response uses one out of two distinct formats for
+ representing the status:
+
+ 1. A 'status' element as child of the 'response' element indicates
+ the status of the message excecution for the identified resource
+ as a whole (for instance, see Section 9.6.2). Some method
+ definitions provide information about specific status codes
+ clients should be prepared to see in a response. However,
+ clients MUST be able to handle other status codes, using the
+ generic rules defined in Section 10 of [RFC2616].
+
+ 2. For PROPFIND and PROPPATCH, the format has been extended using
+ the 'propstat' element instead of 'status', providing information
+ about individual properties of a resource. This format is
+ specific to PROPFIND and PROPPATCH, and is described in detail in
+ Section 9.1 and Section 9.2.
+
+13.1. Response headers
+
+ HTTP defines the Location header to indicate a preferred URL for the
+ resource that was addressed in the Request-URI (e.g. in response to
+ successful PUT requests or in redirect responses). However, use of
+ this header creates ambiguity when there are URLs in the body of the
+ response, as with Multi-Status. Thus, use of the Location header
+ with the Multi-Status response is intentionally undefined.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 85]
+
+Internet-Draft WebDAV April 2006
+
+
+13.2. Handling redirected child resources
+
+ Redirect responses (300-303, 305 and 307) defined in HTTP 1.1
+ normally take a Location header to indicate the new URI for the
+ single resource redirected from the Request-URI. Multi-Status
+ responses contain many resource addresses, but the original
+ definition in [RFC2518] did not have any place for the server to
+ provide the new URI for redirected resources. This specification
+ does define a 'location' element for this information (see
+ Section 14.9). Servers MUST use this new element with redirect
+ responses in Multi-Status.
+
+ Clients encountering redirected resources in Multi-Status MUST NOT
+ rely on the 'location' element being present with a new URI. If the
+ element is not present, the client MAY reissue the request to the
+ individual redirected resource, because the response to that request
+ can be redirected with a Location header containing the new URI.
+
+13.3. Internal Status Codes
+
+ Section 9.2.1, Section 9.1.2, Section 9.6.1, Section 9.8.3 and
+ Section 9.9.2 define various status codes used in Multi-Status
+ responses. This specification does not define the meaning of other
+ status codes that could appear in these responses.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 86]
+
+Internet-Draft WebDAV April 2006
+
+
+14. XML Element Definitions
+
+ In this section, the final line of each section gives the element
+ type declaration using the format defined in [REC-XML]. The "Value"
+ field, where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element). Note that all of the elements defined
+ here may be extended according to the rules defined in Section 17.
+ All elements defined here are in the "DAV:" namespace.
+
+14.1. activelock XML Element
+
+ Name: activelock
+
+ Purpose: Describes a lock on a resource.
+
+
+ <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
+ locktoken?, lockroot)>
+
+14.2. allprop XML Element
+
+ Name: allprop
+
+ Purpose: Specifies that all names and values of dead properties and
+ the live properties defined by this document existing on the
+ resource are to be returned.
+
+ <!ELEMENT allprop EMPTY >
+
+14.3. collection XML Element
+
+ Name: collection
+
+ Purpose: Identifies the associated resource as a collection. The
+ DAV:resourcetype property of a collection resource MUST contain
+ this element. It is normally empty but extensions may add sub-
+ elements.
+
+ <!ELEMENT collection EMPTY >
+
+14.4. depth XML Element
+
+ Name: depth
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 87]
+
+Internet-Draft WebDAV April 2006
+
+
+ Purpose: The value of the Depth header.
+
+ Value: "0" | "1" | "infinity"
+
+ <!ELEMENT depth (#PCDATA) >
+
+14.5. error XML Element
+
+ Name: error
+
+ Purpose: Error responses, particularly 403 Forbidden and 409
+ Conflict, sometimes need more information to indicate what went
+ wrong. When an error response contains a body in WebDAV, the body
+ is in XML with the root element 'error'. The 'error' element
+ SHOULD include a failed precondition or postcondition element.
+
+ Description: Contains at least one XML element, and MUST NOT contain
+ text or mixed content. Any element that is a child of the 'error'
+ element is considered to be a precondition or postcondition code.
+ Unrecognized elements SHOULD be ignored.
+
+ <!ELEMENT error ANY >
+
+14.6. exclusive XML Element
+
+ Name: exclusive
+
+ Purpose: Specifies an exclusive lock.
+
+
+ <!ELEMENT exclusive EMPTY >
+
+
+14.7. href XML Element
+
+ Name: href
+
+ Purpose: MUST contain a URI or a relative reference.
+
+ Description: There may be limits on the value of 'href' depending on
+ the context of its use. Refer to the specification text where
+ 'href' is used to see what limitations apply in each case.
+
+ Value: Simple-ref
+
+
+ <!ELEMENT href (#PCDATA)>
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 88]
+
+Internet-Draft WebDAV April 2006
+
+
+14.8. include XML Element
+
+ Name: include
+
+ Purpose: Any child element represents the name of a property to be
+ included in the PROPFIND response. All elements inside an
+ 'include' XML element MUST define properties related to the
+ resource, although possible property names are in no way limited
+ to those property names defined in this document or other
+ standards. This element MUST NOT contain text or mixed content.
+
+ <!ELEMENT include ANY >
+
+14.9. location XML Element
+
+ Name: location
+
+ Purpose: HTTP defines the "Location" header (see [RFC2616], Section
+ 14.30) for use with some status codes (such as 201 and the 300
+ series codes). When these codes are used inside a 'multistatus'
+ element, the 'location' element can be used to provide the
+ accompanying Location header value.
+
+ Description: Contains a single href element with the same value that
+ would be used in a Location header.
+
+
+ <!ELEMENT location (href)>
+
+14.10. lockentry XML Element
+
+ Name: lockentry
+
+ Purpose: Defines the types of locks that can be used with the
+ resource.
+
+ <!ELEMENT lockentry (lockscope, locktype) >
+
+14.11. lockinfo XML Element
+
+ Name: lockinfo
+
+ Purpose: The 'lockinfo' XML element is used with a LOCK method to
+ specify the type of lock the client wishes to have created.
+
+
+ <!ELEMENT lockinfo (lockscope, locktype, owner?) >
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 89]
+
+Internet-Draft WebDAV April 2006
+
+
+14.12. lockroot XML Element
+
+ Name: lockroot
+
+ Purpose: Contains the root URL of the lock, which is the URL through
+ which the resource was addressed in the LOCK request.
+
+ Description: The href element contains the root of the lock. The
+ server SHOULD include this in all DAV:lockdiscovery property
+ values and the response to LOCK requests.
+
+ <!ELEMENT lockroot (href) >
+
+14.13. lockscope XML Element
+
+ Name: lockscope
+
+ Purpose: Specifies whether a lock is an exclusive lock, or a shared
+ lock.
+
+
+ <!ELEMENT lockscope (exclusive | shared) >
+
+
+14.14. locktoken XML Element
+
+ Name: locktoken
+
+ Purpose: The lock token associated with a lock.
+
+ Description: The href contains a single lock token URI which refers
+ to the lock.
+
+ <!ELEMENT locktoken (href) >
+
+14.15. locktype XML Element
+
+ Name: locktype
+
+ Purpose: Specifies the access type of a lock. At present, this
+ specification only defines one lock type, the write lock.
+
+
+ <!ELEMENT locktype (write) >
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 90]
+
+Internet-Draft WebDAV April 2006
+
+
+14.16. multistatus XML Element
+
+ Name: multistatus
+
+ Purpose: Contains multiple response messages.
+
+ Description: The 'responsedescription' element at the top level is
+ used to provide a general message describing the overarching
+ nature of the response. If this value is available an application
+ may use it instead of presenting the individual response
+ descriptions contained within the responses.
+
+
+ <!ELEMENT multistatus (response*, responsedescription?) >
+
+
+14.17. owner XML Element
+
+ Name: owner
+
+ Purpose: Provides information about the creator of a lock.
+
+ Description: Allows a client to provide information sufficient for
+ either directly contacting a principal (such as a telephone number
+ or Email URI), or for discovering the principal (such as the URL
+ of a homepage) who created a lock. The value provided MUST be
+ treated as a dead property in terms of XML Information Item
+ preservation. The server MUST NOT alter the value unless the
+ owner value provided by the client is empty. For a certain amount
+ of interoperability between different client implementations, if
+ clients have URI-formatted contact information for the lock
+ creator suitable for user display, then clients SHOULD put those
+ URIs in 'href' child elements of the 'owner' element.
+
+ Extensibility: MAY be extended with child elements, mixed content,
+ text content or attributes.
+
+ <!ELEMENT owner ANY >
+
+14.18. prop XML element
+
+ Name: prop
+
+ Purpose: Contains properties related to a resource.
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 91]
+
+Internet-Draft WebDAV April 2006
+
+
+ Description: A generic container for properties defined on
+ resources. All elements inside a 'prop' XML element MUST define
+ properties related to the resource, although possible property
+ names are in no way limited to those property names defined in
+ this document or other standards. This element MUST NOT contain
+ text or mixed content.
+
+ <!ELEMENT prop ANY >
+
+14.19. propertyupdate XML element
+
+ Name: propertyupdate
+
+ Purpose: Contains a request to alter the properties on a resource.
+
+ Description: This XML element is a container for the information
+ required to modify the properties on the resource.
+
+ <!ELEMENT propertyupdate (remove | set)+ >
+
+14.20. propfind XML Element
+
+ Name: propfind
+
+ Purpose: Specifies the properties to be returned from a PROPFIND
+ method. Four special elements are specified for use with
+ 'propfind': 'prop', 'allprop', 'include' and 'propname'. If
+ 'prop' is used inside 'propfind' it MUST NOT contain property
+ values.
+
+ <!ELEMENT propfind ( propname | (allprop, include?) | prop ) >
+
+14.21. propname XML Element
+
+ Name: propname
+
+ Purpose: Specifies that only a list of property names on the
+ resource is to be returned.
+
+ <!ELEMENT propname EMPTY >
+
+14.22. propstat XML Element
+
+ Name: propstat
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 92]
+
+Internet-Draft WebDAV April 2006
+
+
+ Purpose: Groups together a prop and status element that is
+ associated with a particular 'href' element.
+
+ Description: The propstat XML element MUST contain one prop XML
+ element and one status XML element. The contents of the prop XML
+ element MUST only list the names of properties to which the result
+ in the status element applies. The optional precondition/
+ postcondition element and 'responsedescription' text also apply to
+ the properties named in 'prop'.
+
+ <!ELEMENT propstat (prop, status, error?, responsedescription?) >
+
+14.23. remove XML element
+
+ Name: remove
+
+ Purpose: Lists the properties to be removed from a resource.
+
+ Description: Remove instructs that the properties specified in prop
+ should be removed. Specifying the removal of a property that does
+ not exist is not an error. All the XML elements in a 'prop' XML
+ element inside of a 'remove' XML element MUST be empty, as only
+ the names of properties to be removed are required.
+
+ <!ELEMENT remove (prop) >
+
+14.24. response XML Element
+
+ Name: response
+
+ Purpose: Holds a single response describing the effect of a method
+ on resource and/or its properties.
+
+ Description: The 'href' element contains a HTTP URL pointing to a
+ WebDAV resource when used in the 'response' container. A
+ particular 'href' value MUST NOT appear more than once as the
+ child of a 'response' XML element under a 'multistatus' XML
+ element. This requirement is necessary in order to keep
+ processing costs for a response to linear time. Essentially, this
+ prevents having to search in order to group together all the
+ responses by 'href'. There are, however, no requirements
+ regarding ordering based on 'href' values. The optional
+ precondition/postcondition element and 'responsedescription' text
+ can provide additional information about this resource relative to
+ the request or result.
+
+
+ <!ELEMENT response (href, ((href*, status)|(propstat+)),
+
+
+
+Dusseault Expires October 3, 2006 [Page 93]
+
+Internet-Draft WebDAV April 2006
+
+
+ error?, responsedescription? , location?) >
+
+14.25. responsedescription XML Element
+
+ Name: responsedescription
+
+ Purpose: Contains information about a status response within a
+ Multi-Status.
+
+ Description: Provides information suitable to be presented to a
+ user.
+
+ <!ELEMENT responsedescription (#PCDATA) >
+
+14.26. set XML element
+
+ Name: set
+
+ Purpose: Lists the property values to be set for a resource.
+
+ Description: The 'set' element MUST contain only a 'prop' element.
+ The elements contained by the 'prop' element inside the 'set'
+ element MUST specify the name and value of properties that are set
+ on the resource identified by Request-URI. If a property already
+ exists then its value is replaced. Language tagging information
+ appearing in the scope of the 'prop' element (in the "xml:lang"
+ attribute, if present) MUST be persistently stored along with the
+ property, and MUST be subsequently retrievable using PROPFIND.
+
+ <!ELEMENT set (prop) >
+
+14.27. shared XML Element
+
+ Name: shared
+
+ Purpose: Specifies a shared lock.
+
+
+ <!ELEMENT shared EMPTY >
+
+
+14.28. status XML Element
+
+ Name: status
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 94]
+
+Internet-Draft WebDAV April 2006
+
+
+ Purpose: Holds a single HTTP status-line.
+
+ Value: status-line (defined in Section 6.1 of [RFC2616])
+
+ <!ELEMENT status (#PCDATA) >
+
+14.29. timeout XML Element
+
+ Name: timeout
+
+ Purpose: The number of seconds remaining before a lock expires.
+
+ Value: TimeType (defined in Section 10.7).
+
+
+ <!ELEMENT timeout (#PCDATA) >
+
+14.30. write XML Element
+
+ Name: write
+
+ Purpose: Specifies a write lock.
+
+
+ <!ELEMENT write EMPTY >
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 95]
+
+Internet-Draft WebDAV April 2006
+
+
+15. DAV Properties
+
+ For DAV properties, the name of the property is also the same as the
+ name of the XML element that contains its value. In the section
+ below, the final line of each section gives the element type
+ declaration using the format defined in [REC-XML]. The "Value"
+ field, where present, specifies further restrictions on the allowable
+ contents of the XML element using BNF (i.e., to further restrict the
+ values of a PCDATA element).
+
+ A protected property is one which cannot be changed with a PROPPATCH
+ request. There may be other requests which would result in a change
+ to a protected property (as when a LOCK request affects the value of
+ DAV:lockdiscovery). Note that a given property could be protected on
+ one type of resource, but not protected on another type of resource.
+
+ A computed property is one with a value defined in terms of a
+ computation (based on the content and other properties of that
+ resource, or even of some other resource). A computed property is
+ always a protected property.
+
+ COPY and MOVE behavior refers to local COPY and MOVE operations.
+
+ For properties defined based on HTTP GET response headers (DAV:get*),
+ the value could include LWS as defined in [RFC2616], Section 4.2.
+ Server implementors SHOULD NOT include extra LWS in these values,
+ however client implementors MUST be prepared to handle extra LWS.
+
+15.1. creationdate Property
+
+ Name: creationdate
+
+ Purpose: Records the time and date the resource was created.
+
+ Value: date-time (defined in [RFC3339], see the ABNF in section
+ 5.6.)
+
+ Protected: MAY be protected. Some servers allow DAV:creationdate to
+ be changed to reflect the time the document was created if that is
+ more meaningful to the user (rather than the time it was
+ uploaded). Thus, clients SHOULD NOT use this property in
+ synchronization logic (use DAV:getetag instead).
+
+ COPY/MOVE behaviour: This property value SHOULD be kept during a
+ MOVE operation, but is normally re-initialized when a resource is
+ created with a COPY. It should not be set in a COPY.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 96]
+
+Internet-Draft WebDAV April 2006
+
+
+ Description: The DAV:creationdate property SHOULD be defined on all
+ DAV compliant resources. If present, it contains a timestamp of
+ the moment when the resource was created. Servers that are
+ incapable of persistently recording the creation date SHOULD
+ instead leave it undefined (i.e. report "Not Found").
+
+ <!ELEMENT creationdate (#PCDATA) >
+
+15.2. displayname Property
+
+ Name: displayname
+
+ Purpose: Provides a name for the resource that is suitable for
+ presentation to a user.
+
+ Value: Any text.
+
+ Protected: SHOULD NOT be protected. Note that servers implementing
+ [RFC2518] might have made this a protected property as this is a
+ new requirement.
+
+ COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: Contains a description of the resource that is suitable
+ for presentation to a user. This property is defined on the
+ resource, and hence SHOULD have the same value independent of the
+ Request-URI used to retrieve it (thus computing this property
+ based on the Request-URI is deprecated). While generic clients
+ might display the property value to end users, client UI designers
+ must understand that the method for identifying resources is still
+ the URL. Changes to DAV:displayname do not issue moves or copies
+ to the server, but simply change a piece of meta-data on the
+ individual resource. Two resources can have the same DAV:
+ displayname value even within the same collection.
+
+ <!ELEMENT displayname (#PCDATA) >
+
+15.3. getcontentlanguage Property
+
+ Name: getcontentlanguage
+
+ Purpose: Contains the Content-Language header value (from Section
+ 14.12 of [RFC2616]) as it would be returned by a GET without
+ accept headers.
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 97]
+
+Internet-Draft WebDAV April 2006
+
+
+ Value: language-tag (language-tag is defined in Section 3.10 of
+ [RFC2616]).
+
+ Protected: SHOULD NOT be protected, so that clients can reset the
+ language. Note that servers implementing [RFC2518] might have
+ made this a protected property as this is a new requirement.
+
+ COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: The DAV:getcontentlanguage property MUST be defined on
+ any DAV compliant resource that returns the Content-Language
+ header on a GET.
+
+ <!ELEMENT getcontentlanguage (#PCDATA) >
+
+15.4. getcontentlength Property
+
+ Name: getcontentlength
+
+ Purpose: Contains the Content-Length header returned by a GET
+ without accept headers.
+
+ Value: See Section 14.13 of [RFC2616].
+
+ Protected: This property is computed, therefore protected.
+
+ Description: The DAV:getcontentlength property MUST be defined on
+ any DAV compliant resource that returns the Content-Length header
+ in response to a GET.
+
+ COPY/MOVE behaviour: This property value is dependent on the size of
+ the destination resource, not the value of the property on the
+ source resource.
+
+ <!ELEMENT getcontentlength (#PCDATA) >
+
+15.5. getcontenttype Property
+
+ Name: getcontenttype
+
+ Purpose: Contains the Content-Type header value (from Section 14.17
+ of [RFC2616]) as it would be returned by a GET without accept
+ headers.
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 98]
+
+Internet-Draft WebDAV April 2006
+
+
+ Value: media-type (defined in Section 3.7 of [RFC2616])
+
+ Protected: Potentially protected if the server prefers to assign
+ content types on its own (see also discussion in Section 9.7.1).
+
+ COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
+ and MOVE operations.
+
+ Description: This property MUST be defined on any DAV compliant
+ resource that returns the Content-Type header in response to a
+ GET.
+
+ <!ELEMENT getcontenttype (#PCDATA) >
+
+15.6. getetag Property
+
+ Name: getetag
+
+ Purpose: Contains the ETag header value (from Section 14.19 of
+ [RFC2616]) as it would be returned by a GET without accept
+ headers.
+
+ Value: entity-tag (defined in Section 3.11 of [RFC2616])
+
+ Protected: MUST be protected because this value is created and
+ controlled by the server.
+
+ COPY/MOVE behaviour: This property value is dependent on the final
+ state of the destination resource, not the value of the property
+ on the source resource. Also note the considerations in
+ Section 8.8.
+
+ Description: The getetag property MUST be defined on any DAV
+ compliant resource that returns the Etag header. Refer to Section
+ 3.11 of RFC2616 for a complete definition of the semantics of an
+ ETag, and to Section 8.6 for a discussion of ETags in WebDAV.
+
+ <!ELEMENT getetag (#PCDATA) >
+
+15.7. getlastmodified Property
+
+ Name: getlastmodified
+
+ Purpose: Contains the Last-Modified header value (from Section 14.29
+ of [RFC2616]) as it would be returned by a GET method without
+ accept headers.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 99]
+
+Internet-Draft WebDAV April 2006
+
+
+ Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616])
+
+ Protected: SHOULD be protected because some clients may rely on the
+ value for appropriate caching behavior, or on the value of the
+ Last-Modified header to which this property is linked.
+
+ COPY/MOVE behaviour: This property value is dependent on the last
+ modified date of the destination resource, not the value of the
+ property on the source resource. Note that some server
+ implementations use the file system date modified value for the
+ DAV:getlastmodified value, and this can be preserved in a MOVE
+ even when the HTTP Last-Modified value SHOULD change. Note that
+ since [RFC2616] requires clients to use ETags where provided, a
+ server implementing ETags can count on clients using a much better
+ mechanism than modification dates for offline synchronization or
+ cache control. Also note the considerations in Section 8.8.
+
+ Description: Note that the last-modified date on a resource SHOULD
+ only reflect changes in the body (the GET responses) of the
+ resource. A change in a property only SHOULD NOT cause the last-
+ modified date to change, because clients MAY rely on the last-
+ modified date to know when to overwrite the existing body. The
+ DAV:getlastmodified property MUST be defined on any DAV compliant
+ resource that returns the Last-Modified header in response to a
+ GET.
+
+ <!ELEMENT getlastmodified (#PCDATA) >
+
+15.8. lockdiscovery Property
+
+ Name: lockdiscovery
+
+ Purpose: Describes the active locks on a resource
+
+ Protected: MUST be protected. Clients change the list of locks
+ through LOCK and UNLOCK, not through PROPPATCH.
+
+ COPY/MOVE behaviour: The value of this property depends on the lock
+ state of the destination, not on the locks of the source resource.
+ Recall that locks are not moved in a MOVE operation.
+
+ Description: Returns a listing of who has a lock, what type of lock
+ he has, the timeout type and the time remaining on the timeout,
+ and the associated lock token. If there are no locks, but the
+ server supports locks, the property will be present but contain
+ zero 'activelock' elements. If there is one or more lock, an
+ 'activelock' element appears for each lock on the resource. This
+ property is NOT lockable with respect to write locks (Section 7).
+
+
+
+Dusseault Expires October 3, 2006 [Page 100]
+
+Internet-Draft WebDAV April 2006
+
+
+ <!ELEMENT lockdiscovery (activelock)* >
+
+15.8.1. Example - Retrieving DAV:lockdiscovery
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Length: xxxx
+ Content-Type: application/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D='DAV:'>
+ <D:prop><D:lockdiscovery/></D:prop>
+ </D:propfind>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 101]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D='DAV:'>
+ <D:response>
+ <D:href>http://www.example.com/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:lockdiscovery>
+ <D:activelock>
+ <D:locktype><D:write/></D:locktype>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:depth>0</D:depth>
+ <D:owner>Jane Smith</D:owner>
+ <D:timeout>Infinite</D:timeout>
+ <D:locktoken>
+ <D:href
+ >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href>
+ </D:locktoken>
+ <D:lockroot>
+ <D:href>http://www.example.com/container/</D:href>
+ </D:lockroot>
+ </D:activelock>
+ </D:lockdiscovery>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+ This resource has a single exclusive write lock on it, with an
+ infinite timeout.
+
+15.9. resourcetype Property
+
+ Name: resourcetype
+
+ Purpose: Specifies the nature of the resource.
+
+ Protected: SHOULD be protected. Resource type is generally decided
+ through the operation creating the resource (MKCOL vs PUT), not by
+ PROPPATCH.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 102]
+
+Internet-Draft WebDAV April 2006
+
+
+ COPY/MOVE behaviour: Generally a COPY/MOVE of a resource results in
+ the same type of resource at the destination.
+
+ Description: MUST be defined on all DAV compliant resources. Each
+ child element identifies a specific type the resource belongs to,
+ such as 'collection', which is the only resource type defined by
+ this specification (see Section 14.3). If the element contains
+ the 'collection' child element plus additional unrecognized
+ elements, it should generally be treated as a collection. If the
+ element contains no recognized child elements, it should be
+ treated as a non-collection resource. The default value is empty.
+ This element MUST NOT contain text or mixed content. Any custom
+ child element is considered to be an identifier for a resource
+ type.
+
+ Example: (fictional example to show extensibility)
+
+ <x:resourcetype xmlns:x="DAV:">
+ <x:collection/>
+ <f:search-results xmlns:f="http://www.example.com/ns"/>
+ </x:resourcetype>
+
+15.10. supportedlock Property
+
+ Name: supportedlock
+
+ Purpose: To provide a listing of the lock capabilities supported by
+ the resource.
+
+ Protected: MUST be protected. Servers determine what lock
+ mechanisms are supported, not clients.
+
+ COPY/MOVE behaviour: This property value is dependent on the kind of
+ locks supported at the destination, not on the value of the
+ property at the source resource. Servers attempting to COPY to a
+ destination should not attempt to set this property at the
+ destination.
+
+ Description: Returns a listing of the combinations of scope and
+ access types which may be specified in a lock request on the
+ resource. Note that the actual contents are themselves controlled
+ by access controls so a server is not required to provide
+ information the client is not authorized to see. This property is
+ NOT lockable with respect to write locks (Section 7).
+
+ <!ELEMENT supportedlock (lockentry)* >
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 103]
+
+Internet-Draft WebDAV April 2006
+
+
+15.10.1. Example - Retrieving DAV:supportedlock
+
+ >>Request
+
+ PROPFIND /container/ HTTP/1.1
+ Host: www.example.com
+ Content-Length: xxxx
+ Content-Type: application/xml; charset="utf-8"
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop><D:supportedlock/></D:prop>
+ </D:propfind>
+
+ >>Response
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:supportedlock>
+ <D:lockentry>
+ <D:lockscope><D:exclusive/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ <D:lockentry>
+ <D:lockscope><D:shared/></D:lockscope>
+ <D:locktype><D:write/></D:locktype>
+ </D:lockentry>
+ </D:supportedlock>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 104]
+
+Internet-Draft WebDAV April 2006
+
+
+16. Precondition/postcondition XML elements
+
+ As introduced in Section 8.7, extra information on error conditions
+ can be included in the body of many status responses. This section
+ makes requirements on the use of the error body mechanism and
+ introduces a number of precondition and postcondition codes.
+
+ A "precondition" of a method describes the state of the server that
+ must be true for that method to be performed. A "postcondition" of a
+ method describes the state of the server that must be true after that
+ method has been completed.
+
+ Each precondition and postcondition has a unique XML element
+ associated with it. In a 207 Multi-Status response, the XML element
+ MUST appear inside an 'error' element in the appropriate 'propstat or
+ 'response' element depending on whether the condition applies to one
+ or more properties or to the resource as a whole. In all other error
+ responses, the XML element MUST be returned as the child of a top-
+ level 'error' element in the response body, unless otherwise
+ negotiated by the request, along with an appropriate response status.
+ The most common response status codes are 403 (Forbidden) if the
+ request should not be repeated because it will always fail, and 409
+ (Conflict) if it is expected that the user might be able to resolve
+ the conflict and resubmit the request. The 'error' element MAY
+ contain child elements with specific error information and MAY be
+ extended with any custom child elements.
+
+ This mechanism does not take the place of using a correct numeric
+ status code as defined here or in HTTP, because the client MUST
+ always be able to take a reasonable course of action based only on
+ the numeric code. However, it does remove the need to define new
+ numeric codes. The new machine-readable codes used for this purpose
+ are XML elements classified as preconditions and postconditions, so
+ naturally any group defining a new condition code can use their own
+ namespace. As always, the "DAV:" namespace is reserved for use by
+ IETF-chartered WebDAV working groups.
+
+ A server supporting this specification SHOULD use the XML error
+ whenever a precondition or postcondition defined in this document is
+ violated. For error conditions not specified in this document, the
+ server MAY simply choose an appropriate numeric status and leave the
+ response body blank. However, a server MAY instead use a custom
+ condition code and other supporting text, because even when clients
+ do not automatically recognize condition codes they can be quite
+ useful in interoperability testing and debugging.
+
+ Example - Response with precondition code
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 105]
+
+Internet-Draft WebDAV April 2006
+
+
+ >>Response
+
+ HTTP/1.1 423 Locked
+ Content-Type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:lock-token-submitted>
+ <D:href>/workspace/webdav/</D:href>
+ </D:lock-token-submitted>
+ </D:error>
+
+ In this example, a client unaware of a "Depth: infinity" lock on the
+ parent collection "/workspace/webdav/" attempted to modify the
+ collection member "/workspace/webdav/proposal.doc".
+
+ Some other useful preconditions and postconditions have been defined
+ in other specifications extending WebDAV, such as [RFC3744] (see
+ particularly Section 7.1.1), [RFC3253], and [RFC3648].
+
+ All these elements are in the "DAV:" namespace. If not specified
+ otherwise, the content for each condition's XML element is defined to
+ be empty.
+
+ Name: lock-token-matches-request-uri
+
+ Use with: 409 Conflict
+
+ Purpose: (precondition) -- A request may include a Lock-Token header
+ to identify a lock for the UNLOCK method. However, if the
+ Request-URI does not fall within the scope of the lock identified
+ by the token, the server SHOULD use this error. The lock may have
+ a scope that does not include the Request-URI, or the lock could
+ have disappeared, or the token may be invalid.
+
+ Name: lock-token-submitted (precondition)
+
+ Use with: 423 Locked
+
+ Purpose: The request could not succeed because a lock token should
+ have been submitted. This element, if present, MUST contain at
+ least one URL of a locked resource that prevented the request. In
+ cases of MOVE, COPY and DELETE where collection locks are
+ involved, it can be difficult for the client to find out which
+ locked resource made the request fail -- but the server is only
+ resonsible for returning one such locked resource. The server MAY
+ return every locked resource that prevented the request from
+
+
+
+Dusseault Expires October 3, 2006 [Page 106]
+
+Internet-Draft WebDAV April 2006
+
+
+ succeeding if it knows them all.
+
+ <!ELEMENT lock-token-submitted (href+) >
+
+ Name: no-conflicting-lock (precondition)
+
+ Use with: Typically 423 Locked
+
+ Purpose: A LOCK request failed due the presence of an already
+ existing conflicting lock. Note that a lock can be in conflict
+ although the resource to which the request was directed is only
+ indirectly locked. In this case, the precondition code can be
+ used to inform the client about the resource which is the root of
+ the conflicting lock, avoiding a separate lookup of the
+ "lockdiscovery" property.
+
+ <!ELEMENT no-conflicting-lock (href)* >
+
+ Name: no-external-entities
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- If the server rejects a client request
+ because the request body contains an external entity, the server
+ SHOULD use this error.
+
+ Name: preserved-live-properties
+
+ Use with: 409 Conflict
+
+ Purpose: (postcondition) -- The server received an otherwise-valid
+ MOVE or COPY request, but cannot maintain the live properties with
+ the same behavior at the destination. It may be that the server
+ only supports some live properties in some parts of the
+ repository, or simply has an internal error.
+
+ Name: propfind-finite-depth
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- This server does not allow infinite-depth
+ PROPFIND requests on collections.
+
+ Name: cannot-modify-protected-property
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 107]
+
+Internet-Draft WebDAV April 2006
+
+
+ Use with: 403 Forbidden
+
+ Purpose: (precondition) -- The client attempted to set a protected
+ property in a PROPPATCH (such as DAV:getetag). See also
+ [RFC3253], Section 3.12.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 108]
+
+Internet-Draft WebDAV April 2006
+
+
+17. XML Extensibility in DAV
+
+ The XML namespace extension ([REC-XML-NAMES]) is used in this
+ specification in order to allow for new XML elements to be added
+ without fear of colliding with other element names. Although WebDAV
+ request and response bodies can be extended by arbitrary XML
+ elements, which can be ignored by the message recipient, an XML
+ element in the "DAV:" namespace SHOULD NOT be used in the request or
+ response body unless that XML element is explicitly defined in an
+ IETF RFC reviewed by a WebDAV working group.
+
+ For WebDAV to be both extensibile and backwards-compatible, both
+ clients and servers need to know how to behave when unexpected or
+ unrecognized command extensions are received. For XML processing,
+ this means that clients and servers MUST process received XML
+ documents as if unexpected elements and attributes (and all children
+ of unrecognized elements) were not there. An unexpected element or
+ attribute includes one which may be used in another context but is
+ not expected here. Ignoring such items for purposes of processing
+ can of course be consistent with logging all information or
+ presenting for debugging.
+
+ This restriction also applies to the processing, by clients, of DAV
+ property values where unexpected XML elements SHOULD be ignored
+ unless the property's schema declares otherwise.
+
+ This restriction does not apply to setting dead DAV properties on the
+ server where the server MUST record all XML elements.
+
+ Additionally, this restriction does not apply to the use of XML where
+ XML happens to be the content type of the entity body, for example,
+ when used as the body of a PUT.
+
+ Processing instructions in XML SHOULD be ignored by recipients.
+ Thus, specifications extending WebDAV SHOULD NOT use processing
+ instructions to define normative behavior.
+
+ XML DTD fragments are included for all the XML elements defined in
+ this specification. However, correct XML will not be valid according
+ to any DTD due to namespace usage and extension rules. In
+ particular:
+
+ o Elements (from this specification) are in the "DAV:" namespace,
+
+ o Element ordering is irrelevant unless otherwise stated,
+
+ o Extension attributes MAY be added,
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 109]
+
+Internet-Draft WebDAV April 2006
+
+
+ o For element type definitions of "ANY", the normative text
+ definition for that element defines what can be in it and what
+ that means.
+
+ o For element type definitions of "#PCDATA", extension elements MUST
+ NOT be added.
+
+ o For other element type definitions, including "EMPTY", extension
+ elements MAY be added.
+
+ Note that this means that elements containing elements cannot be
+ extended to contain text, and vice versa.
+
+ With DTD validation relaxed by the rules above, the constraints
+ described by the DTD fragments are normative (see for example
+ Appendix A). A recipient of a WebDAV message with an XML body MUST
+ NOT validate the XML document according to any hard-coded or
+ dynamically-declared DTD.
+
+ Note that this section describes backwards-compatible extensibility
+ rules. There might also be times when an extension is designed not
+ to be backwards-compatible, for example defining an extension that
+ reuses an XML element defined in this document but omitting one of
+ the child elements required by the DTDs in this specification.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 110]
+
+Internet-Draft WebDAV April 2006
+
+
+18. DAV Compliance Classes
+
+ A DAV compliant resource can advertise several classes of compliance.
+ A client can discover the compliance classes of a resource by
+ executing OPTIONS on the resource, and examining the "DAV" header
+ which is returned. Note particularly that resources are spoken of as
+ being compliant, rather than servers. That is because theoretically
+ some resources on a server could support different feature sets.
+ E.g. a server could have a sub-repository where an advanced feature
+ like versioning was supported, even if that feature was not supported
+ on all sub-repositories.
+
+ Since this document describes extensions to the HTTP/1.1 protocol,
+ minimally all DAV compliant resources, clients, and proxies MUST be
+ compliant with [RFC2616].
+
+ A resource that is class 2 or class 3 compliant must also be class 1
+ compliant.
+
+18.1. Class 1
+
+ A class 1 compliant resource MUST meet all "MUST" requirements in all
+ sections of this document.
+
+ Class 1 compliant resources MUST return, at minimum, the value "1" in
+ the DAV header on all responses to the OPTIONS method.
+
+18.2. Class 2
+
+ A class 2 compliant resource MUST meet all class 1 requirements and
+ support the LOCK method, the DAV:supportedlock property, the DAV:
+ lockdiscovery property, the Time-Out response header and the Lock-
+ Token request header. A class "2" compliant resource SHOULD also
+ support the Time-Out request header and the 'owner' XML element.
+
+ Class 2 compliant resources MUST return, at minimum, the values "1"
+ and "2" in the DAV header on all responses to the OPTIONS method.
+
+18.3. Class 3
+
+ A resource can explicitly advertise its support for the revisions to
+ [RFC2518] made in this document. Class 1 MUST be supported as well.
+ Class 2 MAY be supported. Advertising class 3 support in addition to
+ class 1 and 2 means that the server supports all the requirements in
+ this specification. Advertising class 3 and class 1 support, but not
+ class 2, means that the server supports all the requirements in this
+ specification except possibly those that involve locking support.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 111]
+
+Internet-Draft WebDAV April 2006
+
+
+ Example:
+
+ DAV: 1, 3
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 112]
+
+Internet-Draft WebDAV April 2006
+
+
+19. Internationalization Considerations
+
+ In the realm of internationalization, this specification complies
+ with the IETF Character Set Policy [RFC2277]. In this specification,
+ human-readable fields can be found either in the value of a property,
+ or in an error message returned in a response entity body. In both
+ cases, the human-readable content is encoded using XML, which has
+ explicit provisions for character set tagging and encoding, and
+ requires that XML processors read XML elements encoded, at minimum,
+ using the UTF-8 [RFC3629] and UTF-16 encodings of the ISO 10646
+ multilingual plane. XML examples in this specification demonstrate
+ use of the charset parameter of the Content-Type header, as defined
+ in [RFC3023], as well as the XML declarations which provide charset
+ identification information for MIME and XML processors.
+
+ XML also provides a language tagging capability for specifying the
+ language of the contents of a particular XML element. The "xml:lang"
+ attribute appears on an XML element to identify the language of its
+ content and attributes. See [REC-XML] for definitions of values and
+ scoping.
+
+ WebDAV applications MUST support the character set tagging, character
+ set encoding, and the language tagging functionality of the XML
+ specification. Implementors of WebDAV applications are strongly
+ encouraged to read "XML Media Types" [RFC3023] for instruction on
+ which MIME media type to use for XML transport, and on use of the
+ charset parameter of the Content-Type header.
+
+ Names used within this specification fall into four categories: names
+ of protocol elements such as methods and headers, names of XML
+ elements, names of properties, and names of conditions. Naming of
+ protocol elements follows the precedent of HTTP, using English names
+ encoded in USASCII for methods and headers. Since these protocol
+ elements are not visible to users, and are simply long token
+ identifiers, they do not need to support multiple languages.
+ Similarly, the names of XML elements used in this specification are
+ not visible to the user and hence do not need to support multiple
+ languages.
+
+ WebDAV property names are qualified XML names (pairs of XML namespace
+ name and local name). Although some applications (e.g., a generic
+ property viewer) will display property names directly to their users,
+ it is expected that the typical application will use a fixed set of
+ properties, and will provide a mapping from the property name and
+ namespace to a human-readable field when displaying the property name
+ to a user. It is only in the case where the set of properties is not
+ known ahead of time that an application need display a property name
+ to a user. We recommend that applications provide human-readable
+
+
+
+Dusseault Expires October 3, 2006 [Page 113]
+
+Internet-Draft WebDAV April 2006
+
+
+ property names wherever feasible.
+
+ For error reporting, we follow the convention of HTTP/1.1 status
+ codes, including with each status code a short, English description
+ of the code (e.g., 423 (Locked)). While the possibility exists that
+ a poorly crafted user agent would display this message to a user,
+ internationalized applications will ignore this message, and display
+ an appropriate message in the user's language and character set.
+
+ Since interoperation of clients and servers does not require locale
+ information, this specification does not specify any mechanism for
+ transmission of this information.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 114]
+
+Internet-Draft WebDAV April 2006
+
+
+20. Security Considerations
+
+ This section is provided to detail issues concerning security
+ implications of which WebDAV applications need to be aware.
+
+ All of the security considerations of HTTP/1.1 (discussed in
+ [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In
+ addition, the security risks inherent in remote authoring require
+ stronger authentication technology, introduce several new privacy
+ concerns, and may increase the hazards from poor server design.
+ These issues are detailed below.
+
+20.1. Authentication of Clients
+
+ Due to their emphasis on authoring, WebDAV servers need to use
+ authentication technology to protect not just access to a network
+ resource, but the integrity of the resource as well. Furthermore,
+ the introduction of locking functionality requires support for
+ authentication.
+
+ A password sent in the clear over an insecure channel is an
+ inadequate means for protecting the accessibility and integrity of a
+ resource as the password may be intercepted. Since Basic
+ authentication for HTTP/1.1 performs essentially clear text
+ transmission of a password, Basic authentication MUST NOT be used to
+ authenticate a WebDAV client to a server unless the connection is
+ secure. Furthermore, a WebDAV server MUST NOT send Basic
+ authentication credentials in a WWW-Authenticate header unless the
+ connection is secure. Examples of secure connections include a
+ Transport Layer Security (TLS) connection employing a strong cipher
+ suite with mutual authentication of client and server, or a
+ connection over a network which is physically secure, for example, an
+ isolated network in a building with restricted access.
+
+ WebDAV applications MUST support the Digest authentication scheme
+ [RFC2617]. Since Digest authentication verifies that both parties to
+ a communication know a shared secret, a password, without having to
+ send that secret in the clear, Digest authentication avoids the
+ security problems inherent in Basic authentication while providing a
+ level of authentication which is useful in a wide range of scenarios.
+
+20.2. Denial of Service
+
+ Denial of service attacks are of special concern to WebDAV servers.
+ WebDAV plus HTTP enables denial of service attacks on every part of a
+ system's resources.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 115]
+
+Internet-Draft WebDAV April 2006
+
+
+ o The underlying storage can be attacked by PUTting extremely large
+ files.
+
+ o Asking for recursive operations on large collections can attack
+ processing time.
+
+ o Making multiple pipelined requests on multiple connections can
+ attack network connections.
+
+ WebDAV servers need to be aware of the possibility of a denial of
+ service attack at all levels. The proper response to such an attack
+ MAY be to simply drop the connection, or if the server is able to
+ make a response, the server MAY use a 400-level status request such
+ as 400 (Bad Request) and indicate why the request was refused (a 500-
+ level status response would indicate that the problem is with the
+ server, whereas unintentional DOS attacks are something the client is
+ capable of remedying).
+
+20.3. Security through Obscurity
+
+ WebDAV provides, through the PROPFIND method, a mechanism for listing
+ the member resources of a collection. This greatly diminishes the
+ effectiveness of security or privacy techniques that rely only on the
+ difficulty of discovering the names of network resources. Users of
+ WebDAV servers are encouraged to use access control techniques to
+ prevent unwanted access to resources, rather than depending on the
+ relative obscurity of their resource names.
+
+20.4. Privacy Issues Connected to Locks
+
+ When submitting a lock request a user agent may also submit an
+ 'owner' XML field giving contact information for the person taking
+ out the lock (for those cases where a person, rather than a robot, is
+ taking out the lock). This contact information is stored in a DAV:
+ lockdiscovery property on the resource, and can be used by other
+ collaborators to begin negotiation over access to the resource.
+ However, in many cases this contact information can be very private,
+ and should not be widely disseminated. Servers SHOULD limit read
+ access to the DAV:lockdiscovery property as appropriate.
+ Furthermore, user agents SHOULD provide control over whether contact
+ information is sent at all, and if contact information is sent,
+ control over exactly what information is sent.
+
+20.5. Privacy Issues Connected to Properties
+
+ Since property values are typically used to hold information such as
+ the author of a document, there is the possibility that privacy
+ concerns could arise stemming from widespread access to a resource's
+
+
+
+Dusseault Expires October 3, 2006 [Page 116]
+
+Internet-Draft WebDAV April 2006
+
+
+ property data. To reduce the risk of inadvertent release of private
+ information via properties, servers are encouraged to develop access
+ control mechanisms that separate read access to the resource body and
+ read access to the resource's properties. This allows a user to
+ control the dissemination of their property data without overly
+ restricting access to the resource's contents.
+
+20.6. Implications of XML Entities
+
+ XML supports a facility known as "external entities", defined in
+ Section 4.2.2 of [REC-XML], which instruct an XML processor to
+ retrieve and include additional XML. An external XML entity can be
+ used to append or modify the document type declaration (DTD)
+ associated with an XML document. An external XML entity can also be
+ used to include XML within the content of an XML document. For non-
+ validating XML, such as the XML used in this specification, including
+ an external XML entity is not required by XML. However, XML does
+ state that an XML processor may, at its discretion, include the
+ external XML entity.
+
+ External XML entities have no inherent trustworthiness and are
+ subject to all the attacks that are endemic to any HTTP GET request.
+ Furthermore, it is possible for an external XML entity to modify the
+ DTD, and hence affect the final form of an XML document, in the worst
+ case significantly modifying its semantics, or exposing the XML
+ processor to the security risks discussed in [RFC3023]. Therefore,
+ implementers must be aware that external XML entities should be
+ treated as untrustworthy. If a server implementor chooses not to
+ handle external XML entities, it SHOULD respond to requests
+ containing external entities with the 'no-external-entities'
+ condition code.
+
+ There is also the scalability risk that would accompany a widely
+ deployed application which made use of external XML entities. In
+ this situation, it is possible that there would be significant
+ numbers of requests for one external XML entity, potentially
+ overloading any server which fields requests for the resource
+ containing the external XML entity.
+
+ Furthermore, there's also a risk based on the evaluation of "internal
+ entities" as defined in Section 4.2.2 of [REC-XML]. A small,
+ carefully crafted request using nested internal entities may require
+ enormous amounts of memory and/or processing time to process. Server
+ implementors should be aware of this risk and configure their XML
+ parsers so that requests like these can be detected and rejected as
+ early as possible.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 117]
+
+Internet-Draft WebDAV April 2006
+
+
+20.7. Risks Connected with Lock Tokens
+
+ This specification encourages the use of "A Universally Unique
+ Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens
+ (Section 6.5), in order to guarantee their uniqueness across space
+ and time. Version 1 UUIDs (defined in Section 4) MAY contain a
+ "node" field that "consists of an IEEE 802 MAC address, usually the
+ host address. For systems with multiple IEEE addresses, any
+ available one can be used". Since a WebDAV server will issue many
+ locks over its lifetime, the implication is that it may also be
+ publicly exposing its IEEE 802 address.
+
+ There are several risks associated with exposure of IEEE 802
+ addresses. Using the IEEE 802 address:
+
+ o It is possible to track the movement of hardware from subnet to
+ subnet.
+
+ o It may be possible to identify the manufacturer of the hardware
+ running a WebDAV server.
+
+ o It may be possible to determine the number of each type of
+ computer running WebDAV.
+
+ This risk only applies to host address based UUID versions. Section
+ 4 of [RFC4122] describes several other mechanisms for generating
+ UUIDs that do not involve the host address and therefore do not
+ suffer from this risk.
+
+20.8. Hosting Malicious Content
+
+ HTTP has the ability to host programs which are executed on client
+ machines. These programs can take many forms including web scripts,
+ executables, plug in modules, and macros in documents. WebDAV does
+ not change any of the security concerns around these programs yet
+ often WebDAV is used in contexts where a wide range of users can
+ publish documents on a server. The server might not have a close
+ trust relationship with the author that is publishing the document.
+ Servers that allow clients to publish arbitrary content can usefully
+ implement precautions to check that content published to the server
+ is not harmful to other clients. Servers could do this by techniques
+ such as restricting the types of content that is allowed to be
+ published and running virus and malware detection software on
+ published content. Servers can also mitigate the risk by having
+ appropriate access restriction and authentication of users that are
+ allowed to publish content to the server.
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 118]
+
+Internet-Draft WebDAV April 2006
+
+
+21. IANA Considerations
+
+21.1. New URI Schemes
+
+ This specification defines two URI schemes:
+
+ 1. the "opaquelocktoken" scheme defined in Appendix C, and
+
+ 2. the "DAV" URI scheme, which historically was used in [RFC2518] to
+ disambiguate WebDAV property and XML element names and which
+ continues to be used for that purpose in this specification and
+ others extending WebDAV. Creation of identifiers in the "DAV:"
+ namespace is controlled by the IETF.
+
+ Note that defining new URI schemes for XML namespaces is now
+ discouraged. "DAV:" was defined before standard best practices
+ emerged.
+
+21.2. XML Namespaces
+
+ XML namespaces disambiguate WebDAV property names and XML elements.
+ Any WebDAV user or application can define a new namespace in order to
+ create custom properties or extend WebDAV XML syntax. IANA does not
+ need to manage such namespaces, property names or element names.
+
+21.3. Message Header Fields
+
+ The message header fields below should be added to the permanent
+ registry (see [RFC3864]).
+
+21.3.1. DAV
+
+ Header field name: DAV
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.1)
+
+21.3.2. Depth
+
+ Header field name: Depth
+
+ Applicable protocol: http
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 119]
+
+Internet-Draft WebDAV April 2006
+
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.2)
+
+21.3.3. Destination
+
+ Header field name: Destination
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.3)
+
+21.3.4. If
+
+ Header field name: If
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.4)
+
+21.3.5. Lock-Token
+
+ Header field name: Lock-Token
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.5)
+
+21.3.6. Overwrite
+
+ Header field name: Overwrite
+
+ Applicable protocol: http
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 120]
+
+Internet-Draft WebDAV April 2006
+
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.6)
+
+21.3.7. Timeout
+
+ Header field name: Timeout
+
+ Applicable protocol: http
+
+ Status: standard
+
+ Author/Change controller: IETF
+
+ Specification document: this specification (Section 10.7)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 121]
+
+Internet-Draft WebDAV April 2006
+
+
+22. Acknowledgements
+
+ A specification such as this thrives on piercing critical review and
+ withers from apathetic neglect. The authors gratefully acknowledge
+ the contributions of the following people, whose insights were so
+ valuable at every stage of our work.
+
+ Contributors to RFC2518
+
+ Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
+ Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
+ Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
+ Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
+ Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
+ Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
+ Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
+ Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
+ Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
+ Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
+ Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
+ Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
+ Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
+ Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
+
+ Two from this list deserve special mention. The contributions by
+ Larry Masinter have been invaluable, both in helping the formation of
+ the working group and in patiently coaching the authors along the
+ way. In so many ways he has set high standards we have toiled to
+ meet. The contributions of Judith Slein in clarifying the
+ requirements, and in patiently reviewing draft after draft, both
+ improved this specification and expanded our minds on document
+ management.
+
+ We would also like to thank John Turner for developing the XML DTD.
+
+ The authors of RFC2518 were Yaron Goland, Jim Whitehead, A. Faizi,
+ Steve Carter and D. Jensen. Although their names had to be removed
+ due to IETF author count restrictions they can take credit for the
+ majority of the design of WebDAV.
+
+ Additional Acknowledgements for This Specification
+
+ Significant contributors of text for this specification are listed as
+ contributors in the section below. We must also gratefully
+ acknowledge Geoff Clemm, Joel Soderberg, and Dan Brotsky for hashing
+ out specific text on the list or in meetings. Joe Hildebrand and
+ Cullen Jennings helped close many issues. Barry Lind described an
+ additional security consideration and Cullen Jennings provided text
+
+
+
+Dusseault Expires October 3, 2006 [Page 122]
+
+Internet-Draft WebDAV April 2006
+
+
+ for that consideration. Jason Crawford tracked issue status for this
+ document for a period of years, followed by Elias Sinderson.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 123]
+
+Internet-Draft WebDAV April 2006
+
+
+23. Contributors to This Specification
+
+ Julian Reschke,
+ <green/>bytes GmbH,
+ Hafenweg 16, 48155 Muenster, Germany,
+ Email: julian.reschke at greenbytes.de
+
+
+ Elias Sinderson
+ University of California, Santa Cruz
+ 1156 High Street, Santa Cruz, CA 95064
+ Email: elias at cse.ucsc.edu
+
+
+ Jim Whitehead,
+ University of California, Santa Cruz
+ 1156 High Street, Santa Cruz, CA 95064
+ Email: ejw at soe.ucsc.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 124]
+
+Internet-Draft WebDAV April 2006
+
+
+24. Authors of RFC2518
+
+ Y. Y. Goland,
+ Microsoft Corporation,
+ One Microsoft Way,
+ Redmond, WA 98052-6399.
+ Email: yarong at microsoft.com.
+
+
+ E. J. Whitehead, Jr.,
+ Dept. Of Information and Computer Science,
+ University of California, Irvine,
+ Irvine, CA 92697-3425.
+ Email: ejw at ics.uci.edu.
+
+
+ A. Faizi,
+ Netscape,
+ 685 East Middlefield Road,
+ Mountain View, CA 94043.
+ Email: asad at netscape.com.
+
+
+ S. R. Carter,
+ Novell,
+ 1555 N. Technology Way,
+ M/S ORM F111,
+ Orem, UT 84097-2399.
+ Email: srcarter at novell.com.
+
+
+ D. Jensen,
+ Novell,
+ 1555 N. Technology Way,
+ M/S ORM F111,
+ Orem, UT 84097-2399.
+ Email: dcjensen at novell.com.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 125]
+
+Internet-Draft WebDAV April 2006
+
+
+25. References
+
+25.1. Normative References
+
+ [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
+ F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third
+ Edition)", W3C REC-xml-20040204, February 2004,
+ <http://www.w3.org/TR/2004/REC-xml-20040204>.
+
+ [REC-XML-INFOSET]
+ Cowan, J. and R. Tobin, "XML Information Set (Second
+ Edition)", W3C REC-xml-infoset-20040204, February 2004,
+ <http://www.w3.org/TR/2004/REC-xml-infoset-20040204/>.
+
+ [REC-XML-NAMES]
+ Bray, T., Hollander, D., and A. Layman, "Namespaces in
+ XML", W3C REC-xml-names-19990114, January 1999,
+ <http://www.w3.org/TR/1999/REC-xml-names-19990114>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [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.
+
+ [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
+ Timestamps", RFC 3339, July 2002.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629, November 2003.
+
+ [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+ Resource Identifier (URI): Generic Syntax", STD 66,
+ RFC 3986, January 2005.
+
+ [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
+ Unique IDentifier (UUID) URN Namespace", RFC 4122,
+ July 2005.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 126]
+
+Internet-Draft WebDAV April 2006
+
+
+25.2. Informational References
+
+ [I-D.draft-whitehead-http-etag]
+ Whitehead, J., "Design Considerations for State
+ Identifiers in HTTP and WebDAV",
+ draft-whitehead-http-etag-00 (work in progress),
+ February 2006.
+
+ [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D. Durand,
+ "Requirements for a Distributed Authoring and Versioning
+ Protocol for the World Wide Web", RFC 2291, February 1998.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
+ Jensen, "HTTP Extensions for Distributed Authoring --
+ WEBDAV", RFC 2518, February 1999.
+
+ [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
+ Types", RFC 3023, January 2001.
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
+ Whitehead, "Versioning Extensions to WebDAV (Web
+ Distributed Authoring and Versioning)", RFC 3253,
+ March 2002.
+
+ [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web Distributed
+ Authoring and Versioning (WebDAV) Ordered Collections
+ Protocol", RFC 3648, December 2003.
+
+ [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
+ Distributed Authoring and Versioning (WebDAV) Access
+ Control Protocol", RFC 3744, May 2004.
+
+ [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
+ Procedures for Message Header Fields", BCP 90, RFC 3864,
+ September 2004.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 127]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix A. Notes on Processing XML Elements
+
+A.1. Notes on Empty XML Elements
+
+ XML supports two mechanisms for indicating that an XML element does
+ not have any content. The first is to declare an XML element of the
+ form <A></A>. The second is to declare an XML element of the form
+ <A/>. The two XML elements are semantically identical.
+
+A.2. Notes on Illegal XML Processing
+
+ XML is a flexible data format that makes it easy to submit data that
+ appears legal but in fact is not. The philosophy of "Be flexible in
+ what you accept and strict in what you send" still applies, but it
+ must not be applied inappropriately. XML is extremely flexible in
+ dealing with issues of white space, element ordering, inserting new
+ elements, etc. This flexibility does not require extension,
+ especially not in the area of the meaning of elements.
+
+ There is no kindness in accepting illegal combinations of XML
+ elements. At best it will cause an unwanted result and at worst it
+ can cause real damage.
+
+A.3. Example - XML Syntax Error
+
+ The following request body for a PROPFIND method is illegal.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:allprop/>
+ <D:propname/>
+ </D:propfind>
+
+ The definition of the propfind element only allows for the allprop or
+ the propname element, not both. Thus the above is an error and must
+ be responded to with a 400 (Bad Request).
+
+ Imagine, however, that a server wanted to be "kind" and decided to
+ pick the allprop element as the true element and respond to it. A
+ client running over a bandwidth limited line who intended to execute
+ a propname would be in for a big surprise if the server treated the
+ command as an allprop.
+
+ Additionally, if a server were lenient and decided to reply to this
+ request, the results would vary randomly from server to server, with
+ some servers executing the allprop directive, and others executing
+ the propname directive. This reduces interoperability rather than
+ increasing it.
+
+
+
+Dusseault Expires October 3, 2006 [Page 128]
+
+Internet-Draft WebDAV April 2006
+
+
+A.4. Example - Unexpected XML Element
+
+ The previous example was illegal because it contained two elements
+ that were explicitly banned from appearing together in the propfind
+ element. However, XML is an extensible language, so one can imagine
+ new elements being defined for use with propfind. Below is the
+ request body of a PROPFIND and, like the previous example, must be
+ rejected with a 400 (Bad Request) by a server that does not
+ understand the expired-props element.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ <E:expired-props/>
+ </D:propfind>
+
+ To understand why a 400 (Bad Request) is returned let us look at the
+ request body as the server unfamiliar with expired-props sees it.
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ </D:propfind>
+
+ As the server does not understand the 'expired-props' element,
+ according to the WebDAV-specific XML processing rules specified in
+ Section 17, it must process the request as if the element were not
+ there. Thus the server sees an empty propfind, which by the
+ definition of the propfind element is illegal.
+
+ Please note that had the extension been additive it would not
+ necessarily have resulted in a 400 (Bad Request). For example,
+ imagine the following request body for a PROPFIND:
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:"
+ xmlns:E="http://www.example.com/standards/props/">
+ <D:propname/>
+ <E:leave-out>*boss*</E:leave-out>
+ </D:propfind>
+
+ The previous example contains the fictitious element leave-out. Its
+ purpose is to prevent the return of any property whose name matches
+ the submitted pattern. If the previous example were submitted to a
+ server unfamiliar with 'leave-out', the only result would be that the
+ 'leave-out' element would be ignored and a propname would be
+ executed.
+
+
+
+Dusseault Expires October 3, 2006 [Page 129]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix B. Notes on HTTP Client Compatibility
+
+ WebDAV was designed to be, and has been found to be, backward-
+ compatible with HTTP 1.1. The PUT and DELETE methods are defined in
+ HTTP and thus may be used by HTTP clients as well as WebDAV-aware
+ clients, but the responses to PUT and DELETE have been extended in
+ this specification in ways that only a WebDAV client would be
+ entirely prepared for. Some theoretical concerns were raised about
+ whether those responses would cause interoperability problems with
+ HTTP-only clients, and this section addresses those concerns.
+
+ Since any HTTP client ought to handle unrecognized 400-level and 500-
+ level status codes as errors, the following new status codes should
+ not present any issues: 422, 423 and 507 (424 is also a new status
+ code but it appears only in the body of a Multistatus response.) So,
+ for example, if a HTTP client attempted to PUT or DELETE a locked
+ resource, the 423 Locked response ought to result in a generic error
+ presented to the user.
+
+ The 207 Multistatus response is interesting because a HTTP client
+ issuing a DELETE request to a collection might interpret a 207
+ response as a success, even though it does not realize the resource
+ is a collection and cannot understand that the DELETE operation might
+ have been a complete or partial failure. That interpretation isn't
+ entirely justified, because a 200-level response indicates that the
+ server "received, understood and accepted" the request, not that the
+ request resulted in complete success.
+
+ One option is that a server could treat a DELETE of a collection as
+ an atomic operation, and use either 204 No Content in case of
+ success, or some appropriate error response (400 or 500 level) for an
+ error. This approach would indeed maximize backward compatibility.
+ However, since interoperability tests and working group discussions
+ have not turned up any instances of HTTP clients issuing a DELETE
+ request against a WebDAV collection, this concern is more theoretical
+ than practical. Thus, servers are likely to be completely successful
+ at interoperating with HTTP clients even if they treat any collection
+ DELETE request as a WebDAV request and send a 207 Multistatus
+ response.
+
+ In general server implementations are encouraged to use the detailed
+ responses and other mechanisms defined in this document rather than
+ make changes for theoretical interoperability concerns.
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 130]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix C. The opaquelocktoken scheme and URIs
+
+ The 'opaquelocktoken' URI scheme was defined in [RFC2518] (and
+ registered by IANA) in order to create syntactically correct and
+ easy-to-generate URIs out of UUIDs, intended to be used as lock
+ tokens and to be unique across all resources for all time.
+
+ An opaquelocktoken URI is constructed by concatenating the
+ 'opaquelocktoken' scheme with a UUID, along with an optional
+ extension. Servers can create new UUIDs for each new lock token. If
+ a server wishes to reuse UUIDs the server MUST add an extension and
+ the algorithm generating the extension MUST guarantee that the same
+ extension will never be used twice with the associated UUID.
+
+ OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension]
+ ; UUID is defined in Section 3 of [RFC4122]. Note that linear
+ ; white space (LWS) is not allowed between elements of
+ ; this production.
+
+ Extension = path
+ ; path is defined in Section 3.3 of [RFC3986]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 131]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix D. Lock-null Resources
+
+ The original WebDAV model for locking unmapped URLs created "lock-
+ null resources". This model was over-complicated and some
+ interoperability and implementation problems were discovered. The
+ new WebDAV model for locking unmapped URLs (see Section 7.3) creates
+ "locked empty resources". Lock-null resources are deprecated. This
+ section discusses the original model briefly because clients MUST be
+ able to handle either model.
+
+ In the original "lock-null resource" model, which is no longer
+ recommended for implementation:
+
+ o A lock-null resource sometimes appeared as "Not Found". The
+ server responds with a 404 or 405 to any method except for PUT,
+ MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK.
+
+ o A lock-null resource does however show up as a member of its
+ parent collection.
+
+ o The server removes the lock-null resource entirely (its URI
+ becomes unmapped) if its lock goes away before it is converted to
+ a regular resource. Recall that locks go away not only when they
+ expire or are unlcoked, but are also removed if a resource is
+ renamed or moved, or if any parent collection is renamed or moved.
+
+ o The server converts the lock-null resource into a regular resource
+ if a PUT request to the URL is successful.
+
+ o The server converts the lock-null resource into a collection if a
+ MKCOL request to the URL is successful (though interoperability
+ experience showed that not all servers followed this requirement).
+
+ o Property values were defined for DAV:lockdiscovery and DAV:
+ supportedlock properties but not necessarily for other properties
+ like DAV:getcontenttype.
+
+ Clients can easily interoperate both with servers that support the
+ old model "lock-null resources" and the recommended model of "locked
+ empty resources" by only attempting PUT after a LOCK to an unmapped
+ URL, not MKCOL or GET.
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 132]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix E. Guidance for Clients Desiring to Authenticate
+
+ Many WebDAV clients already implemented have account settings
+ (similar to the way email clients store IMAP account settings).
+ Thus, the WebDAV client would be able to authenticate with its first
+ couple requests to the server, provided it had a way to get the
+ authentication challenge from the server with realm name, nonce and
+ other challenge information. Note that the results of some requests
+ might vary according to whether the client is authenticated or not --
+ a PROPFIND might return more visible resources if the client is
+ authenticated, yet not fail if the client is anonymous.
+
+ There are a number of ways the client might be able to trigger the
+ server do provide an authentication challenge. This appendix
+ describes a couple approaches that seem particularly likely to work.
+
+ The first approach is to perform a request that ought to require
+ authentication. However, it's possible that a server might handle
+ any request even without authentication, so to be entirely safe the
+ client could add a conditional header to ensure that even if the
+ request passes permissions checks it's not actually handled by the
+ server. An example of following this approach would be to use a PUT
+ request with an "If-Match" header with a made-up ETag value. This
+ approach might fail to result in an authentication challenge if the
+ server does not test authorization before testing conditionals as is
+ required (see Section 8.5), or if the server does not need to test
+ authorization.
+
+ Example - forcing auth challenge with write request
+
+ >>Request
+
+ PUT /forceauth.txt HTTP/1.1
+ Host: www.example.com
+ If-Match: "xxx"
+ Content-Type: text/plain
+ Content-Length: 0
+
+
+ The second approach is to use an Authorization header (defined in
+ [RFC2617]) which is likely to be rejected by the server but which
+ will then prompt a proper authentication challenge. For example, the
+ client could start with a PROPFIND request containing an
+ Authorization header containing a made-up Basic userid:password
+ string or with actual plausible credentials. This approach relies on
+ the server responding with a "401 Unauthorized" along with a
+ challenge if it receives an Authorization header with an unrecognized
+ username, invalid password, or if it doesn't even handle Basic
+
+
+
+Dusseault Expires October 3, 2006 [Page 133]
+
+Internet-Draft WebDAV April 2006
+
+
+ authentication. This seems likely to work because of the
+ requirements of RFC2617:
+
+ "If the origin server does not wish to accept the credentials sent
+ with a request, it SHOULD return a 401 (Unauthorized) response. The
+ response MUST include a WWW-Authenticate header field containing at
+ least one (possibly new) challenge applicable to the requested
+ resource."
+
+ There's a slight problem with implementing that recommendation in
+ some cases, because some servers do not even have challenge
+ information for certain resources. Thus, when there's no way to
+ authenticate to a resource or the resource is entirely publicly
+ available over all accepted methods, the server MAY ignore the
+ Authorization header, and the client presumably try again later.
+
+ Example - forcing auth challenge with Authorization header
+
+ >>Request
+
+ PROPFIND /docs/ HTTP/1.1
+ Host: www.example.com
+ Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+ Content-type: application/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ [body omitted]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 134]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix F. Summary of changes from RFC2518
+
+ This section lists major changes between this document and RFC2518,
+ starting with those that are likely to result in implementation
+ changes. Servers will advertise support for all changes in this
+ specification by returning the compliance class "3" in the DAV
+ response header (see Sections 10.1 and 18.3).
+
+F.1. Changes for both Client and Server Implementations
+
+ Collections and Namespace Operations
+
+ o The semantics of PROPFIND 'allprop' (Section 9.1) have been
+ relaxed so that servers may leave out live properties defined in
+ other specifications, such as [RFC3253] and [RFC3744]. Related to
+ this, 'allprop' requests can now be extended with the 'include'
+ syntax to include specific named properties, thereby avoiding
+ additional requests due to changed 'allprop' semantics.
+
+ o Servers are now allowed to reject PROPFIND requests with Depth:
+ Infinity. Clients that used this will need to be able to do a
+ series of Depth:1 requests instead.
+
+ o Multistatus response bodies now can transport the value of HTTP's
+ Location response header in the new 'location' element. Clients
+ may use this to avoid additional roundtrips to the server when
+ there is a 'response' element with a 3xx status (see
+ Section 14.24).
+
+ o The definition of COPY has been relaxed so that it doesn't require
+ servers to first delete the target resources anymore (this was a
+ known incompatibility with [RFC3253]). See Section 9.8.
+
+ Headers and Marshalling
+
+ o The Destination and If request headers now allow absolute paths in
+ addition to full URIs (see Section 8.3). This may be useful for
+ clients operating through a reverse proxy that does rewrite the
+ Host request header, but not WebDAV-specific headers.
+
+ o This specification adopts the error marshalling extensions and the
+ "precondition/postcondition" terminology defined in [RFC3253] (see
+ Section 16). Related to that, it adds the "error" XML element
+ inside multistatus response bodies (see Section 14.5, however note
+ that it uses a format different from the one recommend in
+ RFC3253).
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 135]
+
+Internet-Draft WebDAV April 2006
+
+
+ o Senders and recipients are now required to support the UTF-16
+ character encoding in XML message bodies (see Section 19).
+
+ Locking
+
+ o RFC2518's concept of "lock-null resources" (LNRs) has been
+ replaced by a simplified approach, the "locked empty resources"
+ (see Section 7.3). There are some aspects of lock-null resources
+ clients can not rely on anymore, namely the ability to use them to
+ create a locked collection or the fact that they disappear upon
+ UNLOCK when no PUT or MKCOL request was issued. Note that servers
+ are still allowed to implement LNRs as per RFC2518.
+
+ o There is no implicit refresh of locks anymore. Locks are only
+ refreshed upon explicit request (see Section 9.10.2).
+
+ o Clarified that the DAV:owner value supplied in the LOCK request
+ must be preserved by the server just like a dead property
+ (Section 14.17). Also added the DAV:lockroot element
+ (Section 14.12) which allows clients to discover the root of lock.
+
+F.2. Changes for Server Implementations
+
+ Collections and Namespace Operations
+
+ o Due to interoperability problems, allowable formats for contents
+ of 'href' elements in multistatus responses have been limited (see
+ Section 8.3).
+
+ o Due to lack of implementation, support for the 'propertybehaviour'
+ request body for COPY and MOVE has been removed. Instead,
+ requirements for property preservation have been clarified (see
+ Sections 9.8 and 9.9).
+
+ Properties
+
+ o Strengthened server requirements for storage of property values,
+ in particular persistence of language information (xml:lang),
+ whitespace, and XML namespace information (see Section 4.3).
+
+ o Clarified requirements on which properties should be writeable by
+ the client; in particular, setting "DAV:displayname" should be
+ supported by servers (see Section 15).
+
+ o Only 'rfc1123-date' productions are legal as values for DAV:
+ getlastmodified (see Section 15.7).
+
+ Headers and Marshalling
+
+
+
+Dusseault Expires October 3, 2006 [Page 136]
+
+Internet-Draft WebDAV April 2006
+
+
+ o Servers are now required to do authorization checks before
+ processing conditional headers (see Section 8.5).
+
+ Locking
+
+ o Strengthened requirement to check identity of lock creator when
+ accessing locked resources (see Section 6.4). Clients should be
+ aware that lock tokens returned to other principals can only be
+ used to break a lock, if at all.
+
+ o Section 8.10.4 of [RFC2518] incorrectly required servers to return
+ a 409 status where a 207 status was really appropriate. This has
+ been corrected (Section 9.10).
+
+F.3. Other Changes
+
+ The definition of collection state has been fixed so it doesn't vary
+ anymore depending on the Request-URI (see Section 5.2).
+
+ The DAV:source property introduced in Section 4.6 of [RFC2518] was
+ removed due to lack of implementation experience.
+
+ The DAV header now allows non-IETF extensions through URIs in
+ addition to compliance class tokens. It also can now be used in
+ requests, although this specification does not define any associated
+ semantics for the compliance classes defined in here (see
+ Section 10.1).
+
+ In RFC2518, the definition of the Depth header (Section 9.2) required
+ that by default request headers would be applied to each resource in
+ scope. Based on implementation experience, the default has now been
+ reversed (see Section 10.2).
+
+ The definitions of HTTP status code 102 ([RFC2518], Section 10.1) and
+ the Status-URI response header (Section 9.7) have been removed due to
+ lack of implementation.
+
+ The TimeType format used in the Timeout request header and the
+ "timeout" XML element used to be extensible. Now, only the two
+ formats defined by this specification are allowed (see Section 10.7).
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 137]
+
+Internet-Draft WebDAV April 2006
+
+
+Appendix G. Change Log (to be removed by RFC Editor before publication)
+
+G.1. Changes from -05 to -06
+
+ Specified that a successful LOCK request to an unmapped URL creates a
+ new, empty locked resource.
+
+ Resolved UNLOCK_NEEDS_IF_HEADER by clarifying that only Lock-Token
+ header is needed on UNLOCK.
+
+ Added Section 16 on preconditions and postconditions and defined a
+ number of preconditions and postconditions. The 'lock-token-
+ submitted' precondition resolves the REPORT_OTHER_RESOURCE_LOCKED
+ issue.
+
+ Added example of matching lock token to URI in the case of a
+ collection lock in the If header section.
+
+ Removed ability for Destination header to take "abs_path" in order to
+ keep consistent with other places where client provides URLs (If
+ header, href element in request body)
+
+ Clarified the href element - that it generally contains HTTP URIs but
+ not always.
+
+ Attempted to fix the BNF describing the If header to allow commas
+
+ Clarified presence of Depth header on LOCK refresh requests.
+
+G.2. Changes in -07
+
+ Added text to "COPY and the Overwrite Header" section to resolve
+ issue OVERWRITE_DELETE_ALL_TOO_STRONG.
+
+ Added text to "HTTP URL Namespace Model" section to provide more
+ clarification and examples on what consistency means and what is not
+ required, to resolve issue CONSISTENCY.
+
+ Resolve DEFINE_PRINCIPAL by importing definition of principal from
+ RFC3744.
+
+ Resolve INTEROP_DELETE_AND_MULTISTATUS by adding appendix 3
+ discussing backward-compatibility concerns.
+
+ Resolve DATE_FORMAT_GETLASTMODIFIED by allowing only rfc1123-date,
+ not HTTP-date for getlastmodified.
+
+ Resolve COPY_INTO_YOURSELF_CLARIFY by adding sentence to first para.
+
+
+
+Dusseault Expires October 3, 2006 [Page 138]
+
+Internet-Draft WebDAV April 2006
+
+
+ of COPY section.
+
+ Confirm that WHEN_TO_MULTISTATUS_FOR_DELETE_1 and
+ WHEN_TO_MULTISTATUS_FOR_DELETE_2 are resolved and tweak language in
+ DELETE section slightly to be clearly consistent.
+
+ More text clarifications to deal with several of the issues in
+ LOCK_ISSUES. This may not completely resolve that set but we need
+ feedback from the originator of the issues at this point.
+
+ Resolved COPY_INTO_YOURSELF_CLARIFY with new sentence in Copy For
+ Collections section.
+
+ Double checked that LEVEL_OR_CLASS is resolved by using class, not
+ level.
+
+ Further work to resolve IF_AND_AUTH and LOCK_SEMANTICS, clarifying
+ text on using locks and being authenticated.
+
+ Added notes on use of 503 status response to resolve issue
+ PROPFIND_INFINITY
+
+ Removed section on other uses of Metadata (and associated references)
+
+ Added reference to RFC4122 for lock tokens and removed section on
+ generating UUIDs
+
+ Explained that even with language variation, a property has only one
+ value (Section 4.5).
+
+ Added section on lock owner (7.1) and what to do if lock requested by
+ unauthenticated user
+
+ Removed Section 4.2 -- justification on why to have metadata, not
+ needed now
+
+ Removed paragraph in Section 5.2 about collections with resource type
+ "DAV:collection" but which are non-WebDAV compliant -- not
+ implemented.
+
+G.3. Changes in -08
+
+ Added security considerations section on scripts and cookie sessions,
+ suggested by Barry Lind
+
+ Clarified which error codes are defined and undefined in MultiStatus
+
+ Moved opaquelocktoken definition to an appendix and refer to RFC4122
+
+
+
+Dusseault Expires October 3, 2006 [Page 139]
+
+Internet-Draft WebDAV April 2006
+
+
+ for use of 'urn:uuid:' URI scheme; fix all lock token examples to use
+ this.
+
+ Multi-status responses contain URLs which MUST either be absolute
+ (and begin with the Request-URI or MUST be relative with new
+ limitations. (bug 12)
+
+ Moved status code sections before example sections within PROPFIND
+ section for section ordering consistency.
+
+ Clarified use of Location header with Multi-Status
+
+ Bugzilla issue resolutions: bugs 9, 12, 14, 19, 20, 29, 30, 34, 36,
+ 102 and 172.
+
+G.4. Changes in -09
+
+ Bugzilla editorial issues: bugs 30, 57, 63, 68, 88, 89, 168, 180,
+ 182, 185, 187.
+
+ More clarity between URL namespaces and XML namespaces, particularly
+ at the beginning of paragraphs using the word namespace
+
+ More consistency in referring to properties with the namespace, as in
+ "DAV:lockdiscovery", and referring to XML element names in single
+ quotes, e.g. 'allprop' element.
+
+ Figure (example) formatting fixes
+
+ Bugzilla issues: bugs 24, 37, 39, 43, 45, 27, 25
+
+ Replaced references to "non-null state" of resources with more clear
+ language about URLs that are mapped to resources, bug 25. Also added
+ definition of URL/URI mapping. Bug 40.
+
+ Bugzilla issues: bug 7, 8, 9, 41, 47, 51, 62, 93, 171, 172. Bugs 28
+ and 94 were iterated on.
+
+ Bugzilla issues: 56, 59, 79, 99, 103, 175, 178. Part of bug 23.
+ Iteration on bug 10.
+
+ Iteration on bugs 10, 46 and 47. Bug 11.
+
+ Remove "102 Processing" response
+
+ Fix bug 46, 105, 107, 120, 140 and 201.
+
+ Another stab at bug 12 - relative v. absolute URLs in Multi-Status
+
+
+
+Dusseault Expires October 3, 2006 [Page 140]
+
+Internet-Draft WebDAV April 2006
+
+
+ response hrefs
+
+ Fix bug 6, 11, 15, 16, 28, 32, 42, 51, 52, 53, 58, 60, 62, 186, 189,
+ 191, 199, 200
+
+ Fix bug 96
+
+G.5. Changes in -10
+
+ Clarify lock intro text on when a client might use another client's
+ lock token - suggestion by Geoff, Nov 15
+
+ Removed Force-Authenticate header and instead added an appendix
+ explaining how existing mechanisms might resolve the need of clients
+ to get an authentication challenge (bug 18).
+
+ Bug 62, 113, 125, 131, 143, 144, 171, 193
+
+ Bug 176, 177, 179, 181, 184, 206, 207, 208
+
+G.6. Changes in -11
+
+ Bug 10, 50, 92, 213, 214, 215
+
+ not recommend use of 414 for over-long Destination URI, bug 179
+
+ Changes for bug 10, 31, 42, 44, 46, 47, 80, 86, 99, 124, 132, 143,
+ 147, 152, 166, 177, 188, 216, 218
+
+ Various changes discussed in conference call, including bug 10, 42,
+ 44, 80, 97, 152.
+
+ Bugs 55, 85, 86
+
+G.7. Changes in -12
+
+ Incorporated GULP (Lock model) into document, making a fair number of
+ changes to rationalize the new order of explaining things, keeping
+ text that explains a lock model concept in more detail but removing
+ text that is redundant or inconsistent.
+
+ Various bugs including 46, 48, 53, 97, 152, 179, 184, 188, 200, 210,
+ 211, and 225. Moved URL Handling from Multi-Status section to
+ general request and response handling section as it now applies to
+ Destination and If as well as 'href' in Multi-Status. Moved GR&RH
+ section up one level to be the new Section 8.
+
+ Bug 53, 184, 210, 213, 217, 221
+
+
+
+Dusseault Expires October 3, 2006 [Page 141]
+
+Internet-Draft WebDAV April 2006
+
+
+ Further rewriting of URL Handling section. Changes resulting from
+ discussion of empty locked resources and how servers should handle
+ Content-Type in that situation. Bug 48, 179.
+
+ Bug 227, 228
+
+G.8. Changes in -13
+
+ Moved the timeout model text and clarified it (bug 229).
+
+ Fixed the definition of collection state (bug 227).
+
+ Made the depth header required on PROPFIND requests (bug 213).
+
+ Fixed inconsistencies in Destination header definition (bug 211).
+
+ Improved appendix on HTTP client compatibility (bug 100).
+
+ Fixed external references with unwieldy pointers (bug 72).
+
+G.9. Changes in -14
+
+ Changes section rewritten, if section rewritten
+
+ Collection definition and membership requirements changed (bug 227)
+
+ Bug 100 and 229 iterations, smallish editorial changes
+
+G.10. Changes in -15
+
+ Moved lock-null resource explanation to an appendix.
+
+ Reverted to RFC2518 behavior of refreshing lock with "If" header.
+
+ Removed section on locks and multiple bindings.
+
+ Removed requirement for clients to upate a property only once in a
+ PROPPATCH.
+
+ Updated displayname property description.
+
+ Copy-edit level changes e.g. "read-only" to "protected", and defining
+ what it means to protect a resource with a lock.
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 142]
+
+Internet-Draft WebDAV April 2006
+
+
+Author's Address
+
+ Lisa Dusseault (editor)
+ Open Source Application Foundation
+ 2064 Edgewood Dr.
+ Palo Alto, CA 94303
+ US
+
+ Email: lisa at osafoundation.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 143]
+
+Internet-Draft WebDAV April 2006
+
+
+Intellectual Property Statement
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr at ietf.org.
+
+
+Disclaimer of Validity
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+Copyright Statement
+
+ Copyright (C) The Internet Society (2006). This document is subject
+ to the rights, licenses and restrictions contained in BCP 78, and
+ except as set forth therein, the authors retain all their rights.
+
+
+Acknowledgment
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+Dusseault Expires October 3, 2006 [Page 144]
+
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2518bis.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2518bis.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2518bis.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,8066 +0,0 @@
-
-
-
-
-WebDAV L. Dusseault, Ed.
-Internet-Draft OSAF
-Obsoletes: 2518 (if approved) April 2006
-Expires: October 3, 2006
-
-
- HTTP Extensions for Distributed Authoring - WebDAV
- draft-ietf-webdav-rfc2518bis-15
-
-Status of this Memo
-
- By submitting this Internet-Draft, each author represents that any
- applicable patent or other IPR claims of which he or she is aware
- have been or will be disclosed, and any of which he or she becomes
- aware will be disclosed, in accordance with Section 6 of BCP 79.
-
- Internet-Drafts are working documents of the Internet Engineering
- Task Force (IETF), its areas, and its working groups. Note that
- other groups may also distribute working documents as Internet-
- Drafts.
-
- Internet-Drafts are draft documents valid for a maximum of six months
- and may be updated, replaced, or obsoleted by other documents at any
- time. It is inappropriate to use Internet-Drafts as reference
- material or to cite them other than as "work in progress."
-
- The list of current Internet-Drafts can be accessed at
- http://www.ietf.org/ietf/1id-abstracts.txt.
-
- The list of Internet-Draft Shadow Directories can be accessed at
- http://www.ietf.org/shadow.html.
-
- This Internet-Draft will expire on October 3, 2006.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- WebDAV consists of a set of methods, headers, and content-types
- ancillary to HTTP/1.1 for the management of resource properties,
- creation and management of resource collections, URL namespace
- manipulation, and resource locking (collision avoidance).
-
- RFC2518 was published in February 1999, and this specification makes
- minor revisions mostly due to interoperability experience.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 1]
-
-Internet-Draft WebDAV April 2006
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7
- 2. Notational Conventions . . . . . . . . . . . . . . . . . . . 9
- 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 10
- 4. Data Model for Resource Properties . . . . . . . . . . . . . 12
- 4.1. The Resource Property Model . . . . . . . . . . . . . . 12
- 4.2. Properties and HTTP Headers . . . . . . . . . . . . . . 12
- 4.3. Property Values . . . . . . . . . . . . . . . . . . . . 12
- 4.3.1. Example - Property with Mixed Content . . . . . . . 14
- 4.4. Property Names . . . . . . . . . . . . . . . . . . . . . 16
- 4.5. Source Resources and Output Resources . . . . . . . . . 16
- 5. Collections of Web Resources . . . . . . . . . . . . . . . . 17
- 5.1. HTTP URL Namespace Model . . . . . . . . . . . . . . . . 17
- 5.2. Collection Resources . . . . . . . . . . . . . . . . . . 17
- 6. Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
- 6.1. Lock Model . . . . . . . . . . . . . . . . . . . . . . . 20
- 6.2. Exclusive Vs. Shared Locks . . . . . . . . . . . . . . . 21
- 6.3. Required Support . . . . . . . . . . . . . . . . . . . . 22
- 6.4. Lock Creator and Privileges . . . . . . . . . . . . . . 22
- 6.5. Lock Tokens . . . . . . . . . . . . . . . . . . . . . . 23
- 6.6. Lock Timeout . . . . . . . . . . . . . . . . . . . . . . 24
- 6.7. Lock Capability Discovery . . . . . . . . . . . . . . . 24
- 6.8. Active Lock Discovery . . . . . . . . . . . . . . . . . 25
- 7. Write Lock . . . . . . . . . . . . . . . . . . . . . . . . . 26
- 7.1. Write Locks and Properties . . . . . . . . . . . . . . . 26
- 7.2. Avoiding Lost Updates . . . . . . . . . . . . . . . . . 27
- 7.3. Write Locks and Unmapped URLs . . . . . . . . . . . . . 28
- 7.4. Write Locks and Collections . . . . . . . . . . . . . . 29
- 7.5. Write Locks and the If Request Header . . . . . . . . . 30
- 7.5.1. Example - Write Lock and COPY . . . . . . . . . . . 31
- 7.5.2. Example - Deleting a member of a locked collection . 31
- 7.6. Write Locks and COPY/MOVE . . . . . . . . . . . . . . . 32
- 7.7. Refreshing Write Locks . . . . . . . . . . . . . . . . . 33
- 8. General Request and Response Handling . . . . . . . . . . . . 34
- 8.1. Precedence in Error Handling . . . . . . . . . . . . . . 34
- 8.2. Use of XML . . . . . . . . . . . . . . . . . . . . . . . 34
- 8.3. URL Handling . . . . . . . . . . . . . . . . . . . . . . 35
- 8.3.1. Example - Correct URL Handling . . . . . . . . . . . 35
- 8.4. Required Bodies in Requests . . . . . . . . . . . . . . 36
- 8.5. HTTP Headers for use in WebDAV . . . . . . . . . . . . . 36
- 8.6. ETag . . . . . . . . . . . . . . . . . . . . . . . . . . 36
- 8.7. Including error response bodies . . . . . . . . . . . . 37
- 8.8. Impact of Namespace Operations on Cache Validators . . . 37
- 9. HTTP Methods for Distributed Authoring . . . . . . . . . . . 39
- 9.1. PROPFIND Method . . . . . . . . . . . . . . . . . . . . 39
- 9.1.1. PROPFIND status codes . . . . . . . . . . . . . . . 40
- 9.1.2. Status Codes for use in 'propstat' Element . . . . . 41
-
-
-
-Dusseault Expires October 3, 2006 [Page 2]
-
-Internet-Draft WebDAV April 2006
-
-
- 9.1.3. Example - Retrieving Named Properties . . . . . . . 41
- 9.1.4. Example - Using so-called 'allprop' . . . . . . . . 43
- 9.1.5. Example - Using 'propname' to Retrieve all
- Property Names . . . . . . . . . . . . . . . . . . . 43
- 9.1.6. Example - Using 'allprop' . . . . . . . . . . . . . 45
- 9.2. PROPPATCH Method . . . . . . . . . . . . . . . . . . . . 47
- 9.2.1. Status Codes for use in 'propstat' Element . . . . . 48
- 9.2.2. Example - PROPPATCH . . . . . . . . . . . . . . . . 49
- 9.3. MKCOL Method . . . . . . . . . . . . . . . . . . . . . . 50
- 9.3.1. MKCOL Status Codes . . . . . . . . . . . . . . . . . 51
- 9.3.2. Example - MKCOL . . . . . . . . . . . . . . . . . . 51
- 9.4. GET, HEAD for Collections . . . . . . . . . . . . . . . 52
- 9.5. POST for Collections . . . . . . . . . . . . . . . . . . 52
- 9.6. DELETE Requirements . . . . . . . . . . . . . . . . . . 52
- 9.6.1. DELETE for Collections . . . . . . . . . . . . . . . 53
- 9.6.2. Example - DELETE . . . . . . . . . . . . . . . . . . 53
- 9.7. PUT Requirements . . . . . . . . . . . . . . . . . . . . 54
- 9.7.1. PUT for Non-Collection Resources . . . . . . . . . . 54
- 9.7.2. PUT for Collections . . . . . . . . . . . . . . . . 55
- 9.8. COPY Method . . . . . . . . . . . . . . . . . . . . . . 55
- 9.8.1. COPY for Non-collection Resources . . . . . . . . . 55
- 9.8.2. COPY for Properties . . . . . . . . . . . . . . . . 56
- 9.8.3. COPY for Collections . . . . . . . . . . . . . . . . 56
- 9.8.4. COPY and Overwriting Destination Resources . . . . . 57
- 9.8.5. Status Codes . . . . . . . . . . . . . . . . . . . . 58
- 9.8.6. Example - COPY with Overwrite . . . . . . . . . . . 59
- 9.8.7. Example - COPY with No Overwrite . . . . . . . . . . 59
- 9.8.8. Example - COPY of a Collection . . . . . . . . . . . 60
- 9.9. MOVE Method . . . . . . . . . . . . . . . . . . . . . . 60
- 9.9.1. MOVE for Properties . . . . . . . . . . . . . . . . 61
- 9.9.2. MOVE for Collections . . . . . . . . . . . . . . . . 61
- 9.9.3. MOVE and the Overwrite Header . . . . . . . . . . . 62
- 9.9.4. Status Codes . . . . . . . . . . . . . . . . . . . . 62
- 9.9.5. Example - MOVE of a Non-Collection . . . . . . . . . 63
- 9.9.6. Example - MOVE of a Collection . . . . . . . . . . . 64
- 9.10. LOCK Method . . . . . . . . . . . . . . . . . . . . . . 65
- 9.10.1. Creating a lock on existing resource . . . . . . . . 65
- 9.10.2. Refreshing Locks . . . . . . . . . . . . . . . . . . 65
- 9.10.3. Depth and Locking . . . . . . . . . . . . . . . . . 66
- 9.10.4. Locking Unmapped URLs . . . . . . . . . . . . . . . 66
- 9.10.5. Lock Compatibility Table . . . . . . . . . . . . . . 67
- 9.10.6. LOCK Responses . . . . . . . . . . . . . . . . . . . 67
- 9.10.7. Example - Simple Lock Request . . . . . . . . . . . 68
- 9.10.8. Example - Refreshing a Write Lock . . . . . . . . . 70
- 9.10.9. Example - Multi-Resource Lock Request . . . . . . . 71
- 9.11. UNLOCK Method . . . . . . . . . . . . . . . . . . . . . 72
- 9.11.1. Status Codes . . . . . . . . . . . . . . . . . . . . 72
- 9.11.2. Example - UNLOCK . . . . . . . . . . . . . . . . . . 73
-
-
-
-Dusseault Expires October 3, 2006 [Page 3]
-
-Internet-Draft WebDAV April 2006
-
-
- 10. HTTP Headers for Distributed Authoring . . . . . . . . . . . 74
- 10.1. DAV Header . . . . . . . . . . . . . . . . . . . . . . . 74
- 10.2. Depth Header . . . . . . . . . . . . . . . . . . . . . . 75
- 10.3. Destination Header . . . . . . . . . . . . . . . . . . . 76
- 10.4. If Header . . . . . . . . . . . . . . . . . . . . . . . 76
- 10.4.1. Purpose . . . . . . . . . . . . . . . . . . . . . . 76
- 10.4.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . 77
- 10.4.3. List Evaluation . . . . . . . . . . . . . . . . . . 78
- 10.4.4. Matching State Tokens and ETags . . . . . . . . . . 78
- 10.4.5. If Header and Non-DAV Aware Proxies . . . . . . . . 79
- 10.4.6. Example - No-tag Production . . . . . . . . . . . . 79
- 10.4.7. Example - using "Not" with No-tag Production . . . . 79
- 10.4.8. Example - causing a Condition to always evaluate
- to True . . . . . . . . . . . . . . . . . . . . . . 80
- 10.4.9. Example - Tagged List If header in COPY . . . . . . 80
- 10.4.10. Example - Matching lock tokens with collection
- locks . . . . . . . . . . . . . . . . . . . . . . . 80
- 10.4.11. Example - Matching ETags on unmapped URLs . . . . . 81
- 10.5. Lock-Token Header . . . . . . . . . . . . . . . . . . . 81
- 10.6. Overwrite Header . . . . . . . . . . . . . . . . . . . . 81
- 10.7. Timeout Request Header . . . . . . . . . . . . . . . . . 82
- 11. Status Code Extensions to HTTP/1.1 . . . . . . . . . . . . . 83
- 11.1. 207 Multi-Status . . . . . . . . . . . . . . . . . . . . 83
- 11.2. 422 Unprocessable Entity . . . . . . . . . . . . . . . . 83
- 11.3. 423 Locked . . . . . . . . . . . . . . . . . . . . . . . 83
- 11.4. 424 Failed Dependency . . . . . . . . . . . . . . . . . 83
- 11.5. 507 Insufficient Storage . . . . . . . . . . . . . . . . 83
- 12. Use of HTTP Status Codes . . . . . . . . . . . . . . . . . . 84
- 12.1. 412 Precondition Failed . . . . . . . . . . . . . . . . 84
- 12.2. 414 Request-URI Too Long . . . . . . . . . . . . . . . . 84
- 13. Multi-Status Response . . . . . . . . . . . . . . . . . . . . 85
- 13.1. Response headers . . . . . . . . . . . . . . . . . . . . 85
- 13.2. Handling redirected child resources . . . . . . . . . . 86
- 13.3. Internal Status Codes . . . . . . . . . . . . . . . . . 86
- 14. XML Element Definitions . . . . . . . . . . . . . . . . . . . 87
- 14.1. activelock XML Element . . . . . . . . . . . . . . . . . 87
- 14.2. allprop XML Element . . . . . . . . . . . . . . . . . . 87
- 14.3. collection XML Element . . . . . . . . . . . . . . . . . 87
- 14.4. depth XML Element . . . . . . . . . . . . . . . . . . . 87
- 14.5. error XML Element . . . . . . . . . . . . . . . . . . . 88
- 14.6. exclusive XML Element . . . . . . . . . . . . . . . . . 88
- 14.7. href XML Element . . . . . . . . . . . . . . . . . . . . 88
- 14.8. include XML Element . . . . . . . . . . . . . . . . . . 89
- 14.9. location XML Element . . . . . . . . . . . . . . . . . . 89
- 14.10. lockentry XML Element . . . . . . . . . . . . . . . . . 89
- 14.11. lockinfo XML Element . . . . . . . . . . . . . . . . . . 89
- 14.12. lockroot XML Element . . . . . . . . . . . . . . . . . . 90
- 14.13. lockscope XML Element . . . . . . . . . . . . . . . . . 90
-
-
-
-Dusseault Expires October 3, 2006 [Page 4]
-
-Internet-Draft WebDAV April 2006
-
-
- 14.14. locktoken XML Element . . . . . . . . . . . . . . . . . 90
- 14.15. locktype XML Element . . . . . . . . . . . . . . . . . . 90
- 14.16. multistatus XML Element . . . . . . . . . . . . . . . . 91
- 14.17. owner XML Element . . . . . . . . . . . . . . . . . . . 91
- 14.18. prop XML element . . . . . . . . . . . . . . . . . . . . 91
- 14.19. propertyupdate XML element . . . . . . . . . . . . . . . 92
- 14.20. propfind XML Element . . . . . . . . . . . . . . . . . . 92
- 14.21. propname XML Element . . . . . . . . . . . . . . . . . . 92
- 14.22. propstat XML Element . . . . . . . . . . . . . . . . . . 92
- 14.23. remove XML element . . . . . . . . . . . . . . . . . . . 93
- 14.24. response XML Element . . . . . . . . . . . . . . . . . . 93
- 14.25. responsedescription XML Element . . . . . . . . . . . . 94
- 14.26. set XML element . . . . . . . . . . . . . . . . . . . . 94
- 14.27. shared XML Element . . . . . . . . . . . . . . . . . . . 94
- 14.28. status XML Element . . . . . . . . . . . . . . . . . . . 94
- 14.29. timeout XML Element . . . . . . . . . . . . . . . . . . 95
- 14.30. write XML Element . . . . . . . . . . . . . . . . . . . 95
- 15. DAV Properties . . . . . . . . . . . . . . . . . . . . . . . 96
- 15.1. creationdate Property . . . . . . . . . . . . . . . . . 96
- 15.2. displayname Property . . . . . . . . . . . . . . . . . . 97
- 15.3. getcontentlanguage Property . . . . . . . . . . . . . . 97
- 15.4. getcontentlength Property . . . . . . . . . . . . . . . 98
- 15.5. getcontenttype Property . . . . . . . . . . . . . . . . 98
- 15.6. getetag Property . . . . . . . . . . . . . . . . . . . . 99
- 15.7. getlastmodified Property . . . . . . . . . . . . . . . . 99
- 15.8. lockdiscovery Property . . . . . . . . . . . . . . . . . 100
- 15.8.1. Example - Retrieving DAV:lockdiscovery . . . . . . . 101
- 15.9. resourcetype Property . . . . . . . . . . . . . . . . . 102
- 15.10. supportedlock Property . . . . . . . . . . . . . . . . . 103
- 15.10.1. Example - Retrieving DAV:supportedlock . . . . . . . 104
- 16. Precondition/postcondition XML elements . . . . . . . . . . . 105
- 17. XML Extensibility in DAV . . . . . . . . . . . . . . . . . . 109
- 18. DAV Compliance Classes . . . . . . . . . . . . . . . . . . . 111
- 18.1. Class 1 . . . . . . . . . . . . . . . . . . . . . . . . 111
- 18.2. Class 2 . . . . . . . . . . . . . . . . . . . . . . . . 111
- 18.3. Class 3 . . . . . . . . . . . . . . . . . . . . . . . . 111
- 19. Internationalization Considerations . . . . . . . . . . . . . 113
- 20. Security Considerations . . . . . . . . . . . . . . . . . . . 115
- 20.1. Authentication of Clients . . . . . . . . . . . . . . . 115
- 20.2. Denial of Service . . . . . . . . . . . . . . . . . . . 115
- 20.3. Security through Obscurity . . . . . . . . . . . . . . . 116
- 20.4. Privacy Issues Connected to Locks . . . . . . . . . . . 116
- 20.5. Privacy Issues Connected to Properties . . . . . . . . . 116
- 20.6. Implications of XML Entities . . . . . . . . . . . . . . 117
- 20.7. Risks Connected with Lock Tokens . . . . . . . . . . . . 118
- 20.8. Hosting Malicious Content . . . . . . . . . . . . . . . 118
- 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 119
- 21.1. New URI Schemes . . . . . . . . . . . . . . . . . . . . 119
-
-
-
-Dusseault Expires October 3, 2006 [Page 5]
-
-Internet-Draft WebDAV April 2006
-
-
- 21.2. XML Namespaces . . . . . . . . . . . . . . . . . . . . . 119
- 21.3. Message Header Fields . . . . . . . . . . . . . . . . . 119
- 21.3.1. DAV . . . . . . . . . . . . . . . . . . . . . . . . 119
- 21.3.2. Depth . . . . . . . . . . . . . . . . . . . . . . . 119
- 21.3.3. Destination . . . . . . . . . . . . . . . . . . . . 120
- 21.3.4. If . . . . . . . . . . . . . . . . . . . . . . . . . 120
- 21.3.5. Lock-Token . . . . . . . . . . . . . . . . . . . . . 120
- 21.3.6. Overwrite . . . . . . . . . . . . . . . . . . . . . 120
- 21.3.7. Timeout . . . . . . . . . . . . . . . . . . . . . . 121
- 22. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 122
- 23. Contributors to This Specification . . . . . . . . . . . . . 124
- 24. Authors of RFC2518 . . . . . . . . . . . . . . . . . . . . . 125
- 25. References . . . . . . . . . . . . . . . . . . . . . . . . . 126
- 25.1. Normative References . . . . . . . . . . . . . . . . . . 126
- 25.2. Informational References . . . . . . . . . . . . . . . . 127
- Appendix A. Notes on Processing XML Elements . . . . . . . . . . 128
- A.1. Notes on Empty XML Elements . . . . . . . . . . . . . . 128
- A.2. Notes on Illegal XML Processing . . . . . . . . . . . . 128
- A.3. Example - XML Syntax Error . . . . . . . . . . . . . . . 128
- A.4. Example - Unexpected XML Element . . . . . . . . . . . . 129
- Appendix B. Notes on HTTP Client Compatibility . . . . . . . . . 130
- Appendix C. The opaquelocktoken scheme and URIs . . . . . . . . 131
- Appendix D. Lock-null Resources . . . . . . . . . . . . . . . . 132
- Appendix E. Guidance for Clients Desiring to Authenticate . . . 133
- Appendix F. Summary of changes from RFC2518 . . . . . . . . . . 135
- F.1. Changes for both Client and Server Implementations . . . 135
- F.2. Changes for Server Implementations . . . . . . . . . . . 136
- F.3. Other Changes . . . . . . . . . . . . . . . . . . . . . 137
- Appendix G. Change Log (to be removed by RFC Editor before
- publication) . . . . . . . . . . . . . . . . . . . . 138
- G.1. Changes from -05 to -06 . . . . . . . . . . . . . . . . 138
- G.2. Changes in -07 . . . . . . . . . . . . . . . . . . . . . 138
- G.3. Changes in -08 . . . . . . . . . . . . . . . . . . . . . 139
- G.4. Changes in -09 . . . . . . . . . . . . . . . . . . . . . 140
- G.5. Changes in -10 . . . . . . . . . . . . . . . . . . . . . 141
- G.6. Changes in -11 . . . . . . . . . . . . . . . . . . . . . 141
- G.7. Changes in -12 . . . . . . . . . . . . . . . . . . . . . 141
- G.8. Changes in -13 . . . . . . . . . . . . . . . . . . . . . 142
- G.9. Changes in -14 . . . . . . . . . . . . . . . . . . . . . 142
- G.10. Changes in -15 . . . . . . . . . . . . . . . . . . . . . 142
- Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 143
- Intellectual Property and Copyright Statements . . . . . . . . . 144
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 6]
-
-Internet-Draft WebDAV April 2006
-
-
-1. Introduction
-
- This document describes an extension to the HTTP/1.1 protocol that
- allows clients to perform remote web content authoring operations.
- This extension provides a coherent set of methods, headers, request
- entity body formats, and response entity body formats that provide
- operations for:
-
- Properties: The ability to create, remove, and query information
- about Web pages, such as their authors, creation dates, etc.
-
- Collections: The ability to create sets of documents and to retrieve
- a hierarchical membership listing (like a directory listing in a file
- system).
-
- Locking: The ability to keep more than one person from working on a
- document at the same time. This prevents the "lost update problem",
- in which modifications are lost as first one author then another
- writes changes without merging the other author's changes.
-
- Namespace Operations: The ability to instruct the server to copy and
- move Web resources, operations which change the mapping from URLs to
- resources.
-
- Requirements and rationale for these operations are described in a
- companion document, "Requirements for a Distributed Authoring and
- Versioning Protocol for the World Wide Web" [RFC2291].
-
- This document does not specify the versioning operations suggested by
- [RFC2291]. That work was done in a separate document, "Versioning
- Extensions to WebDAV" [RFC3253].
-
- The sections below provide a detailed introduction to various WebDAV
- abstractions: resource properties (Section 4), collections of
- resources (Section 5), locks (Section 6) in general and write locks
- (Section 7) specifically.
-
- These abstractions are manipulated by the WebDAV-specific HTTP
- methods (Section 9) and the new HTTP headers (Section 10) used with
- WebDAV methods. General considerations for handling HTTP requests
- and responses in WebDAV are found in Section 8.
-
- While the status codes provided by HTTP/1.1 are sufficient to
- describe most error conditions encountered by WebDAV methods, there
- are some errors that do not fall neatly into the existing categories.
- This specification defines new status codes developed for WebDAV
- methods (Section 11) and describes existing HTTP status codes
- (Section 12) as used in WebDAV. Since some WebDAV methods may
-
-
-
-Dusseault Expires October 3, 2006 [Page 7]
-
-Internet-Draft WebDAV April 2006
-
-
- operate over many resources, the Multi-Status response (Section 13)
- has been introduced to return status information for multiple
- resources. Finally, this version of WebDAV introduces precondition
- and postcondition (Section 16) XML elements in error response bodies.
-
- WebDAV uses XML ([REC-XML]) for property names and some values, and
- also uses XML to marshal complicated request and response. This
- specification contains DTD and text definitions of all all properties
- (Section 15) and all other XML elements (Section 14) used in
- marshalling. WebDAV includes a few special rules on extending
- (Section 17) WebDAV XML marshalling in backwards-compatible ways.
-
- Finishing off the specification are sections on what it means for a
- resource to be compliant with this specification (Section 18), on
- internationalization support (Section 19), and on security
- (Section 20).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 8]
-
-Internet-Draft WebDAV April 2006
-
-
-2. Notational Conventions
-
- Since this document describes a set of extensions to the HTTP/1.1
- protocol, the augmented BNF used herein to describe protocol elements
- is exactly the same as described in Section 2.1 of [RFC2616],
- including the rules about implied linear white-space. Since this
- augmented BNF uses the basic production rules provided in Section 2.2
- of [RFC2616], these rules apply to this document as well.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
- Note that in natural language, a property like the "creationdate"
- property in the "DAV:" XML namespace is sometimes referred to as
- "DAV:creationdate" for brevity.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 9]
-
-Internet-Draft WebDAV April 2006
-
-
-3. Terminology
-
- URI/URL - A Uniform Resource Identifier and Uniform Resource Locator,
- respectively. These terms (and the distinction between them) are
- defined in [RFC3986].
-
- URI/URL Mapping - A relation between an absolute URI and a resource.
- Since a resource can represent items that are not network
- retrievable, as well as those that are, it is possible for a resource
- to have zero, one, or many URI mappings. Mapping a resource to an
- "http" scheme URI makes it possible to submit HTTP protocol requests
- to the resource using the URI.
-
- Path Segment - Informally, the characters found between slashes ("/")
- in a URI. Formally, as defined in Section 3.3 of [RFC3986].
-
- Collection - Informally, a resource that also acts as a container of
- references to child resources. Formally, a resource that contains a
- set of mappings between path segments and resources and meets the
- requirements defined in Section 5.
-
- Internal Member (of a Collection) - Informally, a child resource of a
- collection. Formally, a resource referenced by a path segment
- mapping contained in the collection.
-
- Internal Member URL (of a Collection) - A URL of an internal member,
- consisting of the URL of the collection (including trailing slash)
- plus the path segment identifying the internal member.
-
- Member (of a Collection) - Informally, a "descendant" of a
- collection. Formally, an internal member of the collection, or,
- recursively, a member of an internal member.
-
- Member URL (of a Collection) - A URL that is either an internal
- member URL of the collection itself, or is an internal member URL of
- a member of that collection.
-
- Property - A name/value pair that contains descriptive information
- about a resource.
-
- Live Property - A property whose semantics and syntax are enforced by
- the server. For example, the live property DAV:getcontentlength has
- its value, the length of the entity returned by a GET request,
- automatically calculated by the server.
-
- Dead Property - A property whose semantics and syntax are not
- enforced by the server. The server only records the value of a dead
- property; the client is responsible for maintaining the consistency
-
-
-
-Dusseault Expires October 3, 2006 [Page 10]
-
-Internet-Draft WebDAV April 2006
-
-
- of the syntax and semantics of a dead property.
-
- Principal - A "principal" is a distinct human or computational actor
- that initiates access to network resources.
-
- State Token - A URI which represents a state of a resource. Lock
- tokens are the only state tokens defined in this specification.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 11]
-
-Internet-Draft WebDAV April 2006
-
-
-4. Data Model for Resource Properties
-
-4.1. The Resource Property Model
-
- Properties are pieces of data that describe the state of a resource.
- Properties are data about data.
-
- Properties are used in distributed authoring environments to provide
- for efficient discovery and management of resources. For example, a
- 'subject' property might allow for the indexing of all resources by
- their subject, and an 'author' property might allow for the discovery
- of what authors have written which documents.
-
- The DAV property model consists of name/value pairs. The name of a
- property identifies the property's syntax and semantics, and provides
- an address by which to refer to its syntax and semantics.
-
- There are two categories of properties: "live" and "dead". A live
- property has its syntax and semantics enforced by the server. Live
- properties include cases where a) the value of a property is
- protected, maintained by the server, and b) the value of the property
- is maintained by the client, but the server performs syntax checking
- on submitted values. All instances of a given live property MUST
- comply with the definition associated with that property name. A
- dead property has its syntax and semantics enforced by the client;
- the server merely records the value of the property verbatim.
-
-4.2. Properties and HTTP Headers
-
- Properties already exist, in a limited sense, in HTTP message
- headers. However, in distributed authoring environments a relatively
- large number of properties are needed to describe the state of a
- resource, and setting/returning them all through HTTP headers is
- inefficient. Thus a mechanism is needed which allows a principal to
- identify a set of properties in which the principal is interested and
- to set or retrieve just those properties.
-
-4.3. Property Values
-
- The value of a property is always a (well-formed) XML fragment.
-
- XML has been chosen because it is a flexible, self-describing,
- structured data format that supports rich schema definitions, and
- because of its support for multiple character sets. XML's self-
- describing nature allows any property's value to be extended by
- adding new elements. Older clients will not break when they
- encounter extensions because they will still have the data specified
- in the original schema and MUST ignore elements they do not
-
-
-
-Dusseault Expires October 3, 2006 [Page 12]
-
-Internet-Draft WebDAV April 2006
-
-
- understand.
-
- XML's support for multiple character sets allows any human-readable
- property to be encoded and read in a character set familiar to the
- user. XML's support for multiple human languages, using the "xml:
- lang" attribute, handles cases where the same character set is
- employed by multiple human languages. Note that xml:lang scope is
- recursive, so an xml:lang attribute on any element containing a
- property name element applies to the property value unless it has
- been overridden by a more locally scoped attribute. Note that a
- property only has one value, in one language (or language MAY be left
- undefined), not multiple values in different languages or a single
- value in multiple languages.
-
- A property is always represented with an XML element consisting of
- the property name, called the "property name element". The simplest
- example is an empty property, which is different from a property that
- does not exist:
-
- <R:title xmlns:R="http://www.example.com/ns/"></R:title>
-
- The value of the property appears inside the property name element.
- The value may be any kind of well-formed XML content, including both
- text-only and mixed content. Servers MUST preserve the following XML
- Information Items (using the terminology from [REC-XML-INFOSET]) in
- storage and transmission of dead properties:
-
- For the property name Element Information Item itself:
-
- [namespace name]
-
- [local name]
-
- [attributes] named "xml:lang" or any such attribute in scope
-
- [children] of type element or character
-
- On all Element Information Items in the property value:
-
- [namespace name]
-
- [local name]
-
- [attributes]
-
- [children] of type element or character
-
- On Attribute Information Items in the property value:
-
-
-
-Dusseault Expires October 3, 2006 [Page 13]
-
-Internet-Draft WebDAV April 2006
-
-
- [namespace name]
-
- [local name]
-
- [normalized value]
-
- On Character Information Items in the property value:
-
- [character code]
-
- Since prefixes are used in some XML vocabularies (XPath and XML
- Schema, for example), servers SHOULD preserve, for any Information
- Item in the value:
-
- [prefix]
-
- XML Infoset attributes not listed above MAY be preserved by the
- server, but clients MUST NOT rely on them being preserved. The above
- rules would also apply by default to live properties, unless defined
- otherwise.
-
- Servers MUST ignore the XML attribute xml:space if present and never
- use it to change white space handling. White space in property
- values is significant.
-
-4.3.1. Example - Property with Mixed Content
-
- Consider a dead property 'author' created by the client as follows:
-
- <D:prop xml:lang="en" xmlns:D="DAV:">
- <x:author xmlns:x='http://example.com/ns'>
- <x:name>Jane Doe</x:name>
- <!-- Jane's contact info -->
- <x:uri type='email'
- added='2005-11-26'>mailto:jane.doe at example.com</x:uri>
- <x:uri type='web'
- added='2005-11-27'>http://www.example.com</x:uri>
- <x:notes xmlns:h='http://www.w3.org/1999/xhtml'>
- Jane has been working way <h:em>too</h:em> long on the
- long-awaited revision of <![CDATA[<RFC2518>]]>.
- </x:notes>
- </x:author>
- </D:prop>
-
- When this property is requested, a server might return:
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 14]
-
-Internet-Draft WebDAV April 2006
-
-
- <D:prop xmlns:D='DAV:'><author
- xml:lang='en'
- xmlns:x='http://example.com/ns'
- xmlns='http://example.com/ns'
- xmlns:h='http://www.w3.org/1999/xhtml'>
- <x:name>Jane Doe</x:name>
- <x:uri added="2005-11-26" type="email"
- >mailto:jane.doe at example.com</x:uri>
- <x:uri added="2005-11-27" type="web"
- >http://www.example.com</x:uri>
- <x:notes>
- Jane has been working way <h:em>too</h:em> long on the
- long-awaited revision of <RFC2518>.
- </x:notes>
- </author>
- </D:prop>
-
- Note in this example:
-
- o The [prefix] for the property name itself was not preserved, being
- non-significant, all other [prefix] values have been preserved,
-
- o attribute values have been rewritten with double quotes instead of
- single quotes (quoting style is not significant), and attribute
- order has not been preserved,
-
- o the xml:lang attribute has been returned on the property name
- element itself (it was in scope when the property was set, but the
- exact position in the response is not considered significant as
- long as it is in scope),
-
- o whitespace between tags has been preserved everywhere (whitespace
- between attributes not so),
-
- o CDATA encapsulation was replaced with character escaping (the
- reverse would also be legal),
-
- o the comment item was stripped (as would have been a processing
- instruction item).
-
- Implementation note: there are cases such as editing scenarios where
- clients may require that XML content is preserved character-by-
- character (such as attribute ordering or quoting style). In this
- case, clients should consider using a text-only property value by
- escaping all characters that have a special meaning in XML parsing.
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 15]
-
-Internet-Draft WebDAV April 2006
-
-
-4.4. Property Names
-
- A property name is a universally unique identifier that is associated
- with a schema that provides information about the syntax and
- semantics of the property.
-
- Because a property's name is universally unique, clients can depend
- upon consistent behavior for a particular property across multiple
- resources, on the same and across different servers, so long as that
- property is "live" on the resources in question, and the
- implementation of the live property is faithful to its definition.
-
- The XML namespace mechanism, which is based on URIs ([RFC3986]), is
- used to name properties because it prevents namespace collisions and
- provides for varying degrees of administrative control.
-
- The property namespace is flat; that is, no hierarchy of properties
- is explicitly recognized. Thus, if a property A and a property A/B
- exist on a resource, there is no recognition of any relationship
- between the two properties. It is expected that a separate
- specification will eventually be produced which will address issues
- relating to hierarchical properties.
-
- Finally, it is not possible to define the same property twice on a
- single resource, as this would cause a collision in the resource's
- property namespace.
-
-4.5. Source Resources and Output Resources
-
- Some HTTP resources are dynamically generated by the server. For
- these resources, there presumably exists source code somewhere
- governing how that resource is generated. The relationship of source
- files to output HTTP resources may be one to one, one to many, many
- to one or many to many. There is no mechanism in HTTP to determine
- whether a resource is even dynamic, let alone where its source files
- exist or how to author them. Although this problem would usefully be
- solved, interoperable WebDAV implementations have been widely
- deployed without actually solving this problem, by dealing only with
- static resources. Thus, the source vs. output problem is not solved
- in this specification and has been deferred to a separate document.
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 16]
-
-Internet-Draft WebDAV April 2006
-
-
-5. Collections of Web Resources
-
- This section provides a description of a new type of Web resource,
- the collection, and discusses its interactions with the HTTP URL
- namespace. The purpose of a collection resource is to model
- collection-like objects (e.g., file system directories) within a
- server's namespace.
-
- All DAV compliant resources MUST support the HTTP URL namespace model
- specified herein.
-
-5.1. HTTP URL Namespace Model
-
- The HTTP URL namespace is a hierarchical namespace where the
- hierarchy is delimited with the "/" character.
-
- An HTTP URL namespace is said to be consistent if it meets the
- following conditions: for every URL in the HTTP hierarchy there
- exists a collection that contains that URL as an internal member URL.
- The root, or top-level collection of the namespace under
- consideration, is exempt from the previous rule. The top-level
- collection of the namespace under consideration is not necessarily
- the collection identified by the absolute path '/', it may be
- identified by one or more path segments (e.g. /servlets/webdav/...)
-
- Neither HTTP/1.1 nor WebDAV require that the entire HTTP URL
- namespace be consistent -- a WebDAV-compatible resource may not have
- a parent collection. However, certain WebDAV methods are prohibited
- from producing results that cause namespace inconsistencies.
-
- As is implicit in [RFC2616] and [RFC3986], any resource, including
- collection resources, MAY be identified by more than one URI. For
- example, a resource could be identified by multiple HTTP URLs.
-
-5.2. Collection Resources
-
- Collection resources differ from other resources in that they also
- act as containers. A collection is a resource whose state consists
- of at least a set of mappings between path segments and resources,
- and a set of properties on the collection itself. In this document,
- a resource B will be said to be contained in the collection resource
- A if there is a path segment mapping which maps to B and which is
- contained in A. A collection MUST contain at most one mapping for a
- given path segment, i.e., it is illegal to have the same path segment
- mapped to more than one resource.
-
- Properties defined on collections behave exactly as do properties on
- non-collection resources. A collection MAY have additional state
-
-
-
-Dusseault Expires October 3, 2006 [Page 17]
-
-Internet-Draft WebDAV April 2006
-
-
- such as entity bodies returned by GET.
-
- For all WebDAV compliant resources A and B, identified by URLs "U"
- and "V" respectively, such that "V" is equal to "U/SEGMENT", A MUST
- be a collection that contains a mapping from "SEGMENT" to B. So, if
- resource B with URL "http://example.com/bar/blah" is WebDAV compliant
- and if resource A with URL "http://example.com/bar/" is WebDAV
- compliant, then resource A must be a collection and must contain
- exactly one mapping from "blah" to B.
-
- Although commonly a mapping consists of a single segment and a
- resource, in general, a mapping consists of a set of segments and a
- resource. This allows a server to treat a set of segments as
- equivalent (i.e. either all of the segments are mapped to the same
- resource, or none of the segments are mapped to a resource). For
- example, a server that performs case-folding on segments will treat
- the segments "ab", "Ab", "aB", and "AB" as equivalent. A client can
- then use any of these segments to identify the resource. Note that a
- PROPFIND result will select one of these equivalent segments to
- identify the mapping, so there will be one PROPFIND response element
- per mapping, not one per segment in the mapping.
-
- Collection resources MAY have mappings to non-WebDAV compliant
- resources in the HTTP URL namespace hierarchy but are not required to
- do so. For example, if resource X with URL
- "http://example.com/bar/blah" is not WebDAV compliant and resource A
- with "URL http://example.com/bar/" identifies a WebDAV collection,
- then A may or may not have a mapping from "blah" to X.
-
- If a WebDAV compliant resource has no WebDAV compliant internal
- members in the HTTP URL namespace hierarchy then the WebDAV compliant
- resource is not required to be a collection.
-
- There is a standing convention that when a collection is referred to
- by its name without a trailing slash, the server MAY handle the
- request as if the trailing slash were present. In this case it
- SHOULD return a Content-Location header in the response, pointing to
- the URL ending with the "/". For example, if a client invokes a
- method on http://example.com/blah (no trailing slash), the server may
- respond as if the operation were invoked on http://example.com/blah/
- (trailing slash), and should return a Content-Location header with
- the value http://example.com/blah/. Wherever a server produces a URL
- referring to a collection, the server SHOULD include the trailing
- slash. In general clients SHOULD use the trailing slash form of
- collection names. If clients do not use the trailing slash form the
- client needs to be prepared to see a redirect response. Clients will
- find the DAV:resourcetype property more reliable than the URL to find
- out if a resource is a collection.
-
-
-
-Dusseault Expires October 3, 2006 [Page 18]
-
-Internet-Draft WebDAV April 2006
-
-
- Clients MUST be able to support the case where WebDAV resources are
- contained inside non-WebDAV resources. For example, if a OPTIONS
- response from "http://example.com/servlet/dav/collection" indicates
- WebDAV support, the client cannot assume that
- "http://example.com/servlet/dav/" or its parent necessarily are
- WebDAV collections.
-
- A typical scenario in which mapped URLs do not appear as members of
- their parent collection is the case where a server allows links or
- redirects to non-WebDAV resources. For instance, "/col/link" might
- not appear as a member of "/col/", although the server would respond
- with a 302 status to a GET request to "/col/link", thus the URL
- "/col/link" would indeed be mapped. Similarly, a dynamically-
- generated page might have a URL mapping from "/col/index.html", thus
- this resource might respond with a 200 OK to a GET request yet not
- appear as a member of "/col/".
-
- Some mappings to even WebDAV-compliant resources might not appear in
- the parent collection. An example for this case are servers that
- support multiple alias URLs for each WebDAV compliant resource. A
- server may implement case-insensitive URLs, thus "/col/a" and
- "/col/A" identify the same resource, yet only either "a" or "A" are
- reported upon listing the members of "/col". In cases where a server
- treats a set of segments as equivalent, the server MUST expose only
- one preferred segment per mapping, consistently chosen, in PROPFIND
- responses.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 19]
-
-Internet-Draft WebDAV April 2006
-
-
-6. Locking
-
- The ability to lock a resource provides a mechanism for serializing
- access to that resource. Using a lock, an authoring client can
- provide a reasonable guarantee that another principal will not modify
- a resource while it is being edited. In this way, a client can
- prevent the "lost update" problem.
-
- This specification allows locks to vary over two client-specified
- parameters, the number of principals involved (exclusive vs. shared)
- and the type of access to be granted. This document defines locking
- for only one access type, write. However, the syntax is extensible,
- and permits the eventual specification of locking for other access
- types.
-
-6.1. Lock Model
-
- This section provides a concise model for how locking behaves. Later
- sections will provide more detail on some of the concepts and refer
- back to these model statements. Normative statements related to LOCK
- and UNLOCK method handling can be found in the sections on those
- methods, whereas normative statements that cover any method are
- gathered here.
-
- 1. A lock either directly or indirectly locks a resource.
-
- 2. A resource becomes directly locked when a LOCK request to a URL
- of that resource creates a new lock. The "lock-root" of the new
- lock is that URL. If at the time of the request, the URL is not
- mapped to a resource, a new empty resource is created and
- directly locked.
-
- 3. An exclusive lock (Section 6.2) conflicts with any other kind of
- lock on the same resource, whether either lock is direct or
- indirect. A server MUST NOT create conflicting locks on a
- resource.
-
- 4. For a collection that is locked with an infinite depth lock L,
- all member resources are indirectly locked. Changes in
- membership of a such a collection affect the set of indirectly
- locked resources:
-
- * If a member resource is added to the collection, the new
- member resource MUST NOT already have a conflicting lock,
- because the new resource MUST become indirectly locked by L.
-
- * If a member resource stops being a member of the collection,
- then the resource MUST no longer be indirectly locked by L.
-
-
-
-Dusseault Expires October 3, 2006 [Page 20]
-
-Internet-Draft WebDAV April 2006
-
-
- 5. Each lock is identified by a single unique lock token
- (Section 6.5).
-
- 6. An UNLOCK request deletes the lock with the specified lock token.
- After a lock is deleted, no resource is locked by that lock.
-
- 7. A lock token is "submitted" in a request when it appears in an If
- header (the Write Lock (Section 7) section discusses when token
- submission is required for write locks).
-
- 8. If a request causes the lock-root of any lock to become an
- unmapped URL, then the lock MUST also be deleted by that request.
-
-6.2. Exclusive Vs. Shared Locks
-
- The most basic form of lock is an exclusive lock. Exclusive locks
- avoid having to deal with content change conflicts, without requiring
- any coordination other than the methods described in this
- specification.
-
- However, there are times when the goal of a lock is not to exclude
- others from exercising an access right but rather to provide a
- mechanism for principals to indicate that they intend to exercise
- their access rights. Shared locks are provided for this case. A
- shared lock allows multiple principals to receive a lock. Hence any
- principal with appropriate access can use the lock.
-
- With shared locks there are two trust sets that affect a resource.
- The first trust set is created by access permissions. Principals who
- are trusted, for example, may have permission to write to the
- resource. Among those who have access permission to write to the
- resource, the set of principals who have taken out a shared lock also
- must trust each other, creating a (typically) smaller trust set
- within the access permission write set.
-
- Starting with every possible principal on the Internet, in most
- situations the vast majority of these principals will not have write
- access to a given resource. Of the small number who do have write
- access, some principals may decide to guarantee their edits are free
- from overwrite conflicts by using exclusive write locks. Others may
- decide they trust their collaborators will not overwrite their work
- (the potential set of collaborators being the set of principals who
- have write permission) and use a shared lock, which informs their
- collaborators that a principal may be working on the resource.
-
- The WebDAV extensions to HTTP do not need to provide all of the
- communications paths necessary for principals to coordinate their
- activities. When using shared locks, principals may use any out of
-
-
-
-Dusseault Expires October 3, 2006 [Page 21]
-
-Internet-Draft WebDAV April 2006
-
-
- band communication channel to coordinate their work (e.g., face-to-
- face interaction, written notes, post-it notes on the screen,
- telephone conversation, Email, etc.) The intent of a shared lock is
- to let collaborators know who else may be working on a resource.
-
- Shared locks are included because experience from web distributed
- authoring systems has indicated that exclusive locks are often too
- rigid. An exclusive lock is used to enforce a particular editing
- process: take out an exclusive lock, read the resource, perform
- edits, write the resource, release the lock. This editing process
- has the problem that locks are not always properly released, for
- example when a program crashes, or when a lock creator leaves without
- unlocking a resource. While both timeouts (Section 6.6) and
- administrative action can be used to remove an offending lock,
- neither mechanism may be available when needed; the timeout may be
- long or the administrator may not be available.
-
- A successful request for a new shared lock MUST result in the
- generation of a unique lock associated with the requesting principal.
- Thus if five principals have taken out shared write locks on the same
- resource there will be five locks and five lock tokens, one for each
- principal.
-
-6.3. Required Support
-
- A WebDAV compliant resource is not required to support locking in any
- form. If the resource does support locking it may choose to support
- any combination of exclusive and shared locks for any access types.
-
- The reason for this flexibility is that locking policy strikes to the
- very heart of the resource management and versioning systems employed
- by various storage repositories. These repositories require control
- over what sort of locking will be made available. For example, some
- repositories only support shared write locks while others only
- provide support for exclusive write locks while yet others use no
- locking at all. As each system is sufficiently different to merit
- exclusion of certain locking features, this specification leaves
- locking as the sole axis of negotiation within WebDAV.
-
-6.4. Lock Creator and Privileges
-
- The creator of a lock has special privileges to use the lock to
- modify the resource. When a locked resource is modified, a server
- MUST check that the authenticated principal matches the lock creator
- (in addition to checking for valid lock token submission).
-
- The server MAY allow privileged users other than the lock creator to
- destroy a lock (for example, the resource owner or an administrator).
-
-
-
-Dusseault Expires October 3, 2006 [Page 22]
-
-Internet-Draft WebDAV April 2006
-
-
- The 'unlock' privilege in [RFC3744] was defined to provide that
- permission.
-
- There is no requirement for servers to accept LOCK requests from all
- users or from anonymous users.
-
- Note that having a lock does not confer full privilege to modify the
- locked resource. Write access and other privileges MUST be enforced
- through normal privilege or authentication mechanisms, not based on
- the possible obscurity of lock token values.
-
-6.5. Lock Tokens
-
- A lock token is a type of state token which identifies a particular
- lock. Each lock has exactly one unique lock token generated by the
- server. Clients MUST NOT attempt to interpret lock tokens in any
- way.
-
- Lock token URIs MUST be unique across all resources for all time.
- This uniqueness constraint allows lock tokens to be submitted across
- resources and servers without fear of confusion. Since lock tokens
- are unique, a client MAY submit a lock token in an If header on a
- resource other than the one that returned it.
-
- When a LOCK operation creates a new lock, the new lock token is
- returned in the Lock-Token response header defined in Section 10.5,
- and also in the body of the response.
-
- Servers MAY make lock tokens publicly readable (e.g. in the DAV:
- lockdiscovery property). One use case for making lock tokens
- readable is so that a long-lived lock can be removed by the resource
- owner (the client that obtained the lock might have crashed or
- disconnected before cleaning up the lock). Except for the case of
- using UNLOCK under user guidance, a client SHOULD NOT use a lock
- token created by another client instance.
-
- This specification encourages servers to create UUIDs for lock
- tokens, and to use the URI form defined by "A Universally Unique
- Identifier (UUID) URN Namespace" ([RFC4122]). However servers are
- free to use any URI (e.g. from another scheme) so long as it meets
- the uniqueness requirements. For example, a valid lock token might
- be constructed using the "opaquelocktoken" scheme defined in
- Appendix C.
-
- Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 23]
-
-Internet-Draft WebDAV April 2006
-
-
-6.6. Lock Timeout
-
- A lock MAY have a limited lifetime. The lifetime is suggested by the
- client when creating or refreshing the lock, but the server
- ultimately chooses the timeout value. Timeout is measured in seconds
- remaining until lock expiration.
-
- The timeout counter MUST be restarted if a refresh lock request is
- successful (see Section 9.10.2). The timeout counter SHOULD NOT be
- restarted at any other time.
-
- If the timeout expires then the lock SHOULD be removed. In this case
- the server SHOULD act as if an UNLOCK method was executed by the
- server on the resource using the lock token of the timed-out lock,
- performed with its override authority. Thus logs should be updated
- with the disposition of the lock, notifications should be sent, etc.,
- just as they would be for an UNLOCK request.
-
- Servers are advised to pay close attention to the values submitted by
- clients, as they will be indicative of the type of activity the
- client intends to perform. For example, an applet running in a
- browser may need to lock a resource, but because of the instability
- of the environment within which the applet is running, the applet may
- be turned off without warning. As a result, the applet is likely to
- ask for a relatively small timeout value so that if the applet dies,
- the lock can be quickly harvested. However, a document management
- system is likely to ask for an extremely long timeout because its
- user may be planning on going off-line.
-
- A client MUST NOT assume that just because the time-out has expired
- the lock has immediately been removed.
-
- Likewise, a client MUST NOT assume that just because the time-out has
- not expired, the lock still exists. Clients MUST assume that locks
- can arbitrarily disappear at any time, regardless of the value given
- in the Timeout header. The Timeout header only indicates the
- behavior of the server if extraordinary circumstances do not occur.
- For example, a sufficiently privileged user may remove a lock at any
- time or the system may crash in such a way that it loses the record
- of the lock's existence.
-
-6.7. Lock Capability Discovery
-
- Since server lock support is optional, a client trying to lock a
- resource on a server can either try the lock and hope for the best,
- or perform some form of discovery to determine what lock capabilities
- the server supports. This is known as lock capability discovery. A
- client can determine what lock types the server supports by
-
-
-
-Dusseault Expires October 3, 2006 [Page 24]
-
-Internet-Draft WebDAV April 2006
-
-
- retrieving the DAV:supportedlock property.
-
- Any DAV compliant resource that supports the LOCK method MUST support
- the DAV:supportedlock property.
-
-6.8. Active Lock Discovery
-
- If another principal locks a resource that a principal wishes to
- access, it is useful for the second principal to be able to find out
- who the first principal is. For this purpose the DAV:lockdiscovery
- property is provided. This property lists all outstanding locks,
- describes their type, and MAY even provide the lock tokens.
-
- Any DAV compliant resource that supports the LOCK method MUST support
- the DAV:lockdiscovery property.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 25]
-
-Internet-Draft WebDAV April 2006
-
-
-7. Write Lock
-
- This section describes the semantics specific to the write lock type.
- The write lock is a specific instance of a lock type, and is the only
- lock type described in this specification.
-
- An exclusive write lock protects a resource: it prevents changes by
- any principal other than the lock creator and in any case where the
- lock token is not submitted (e.g. by a client process other than the
- one holding the lock).
-
- Clients MUST submit a lock-token they are authorized to use in any
- request which modifies a write-locked resource. The list of
- modifications covered by a write-lock include:
-
- 1. A change to any of the following aspects of any write-locked
- resource:
-
- * any variant,
-
- * any dead property,
-
- * any live property which is lockable (a live property is
- lockable unless otherwise defined.)
-
- 2. For collections, any modification of an internal member URI. An
- internal member URI of a collection is considered to be modified
- if it is added, removed, or identifies a different resource.
- More discussion on write locks and collections is found in
- Section 7.4.
-
- 3. A modification of the mapping of the root of the write lock,
- either to another resource or to no resource (e.g. DELETE).
-
- Of the methods defined in HTTP and WebDAV, PUT, POST, PROPPATCH,
- LOCK, UNLOCK, MOVE, COPY (for the destination resource), DELETE, and
- MKCOL are affected by write locks. All other HTTP/WebDAV methods
- defined so far, GET in particular, function independently of a write
- lock.
-
- The next few sections describe in more specific terms how write locks
- interact with various operations.
-
-7.1. Write Locks and Properties
-
- While those without a write lock may not alter a property on a
- resource it is still possible for the values of live properties to
- change, even while locked, due to the requirements of their schemas.
-
-
-
-Dusseault Expires October 3, 2006 [Page 26]
-
-Internet-Draft WebDAV April 2006
-
-
- Only dead properties and live properties defined as lockable are
- guaranteed not to change while write locked.
-
-7.2. Avoiding Lost Updates
-
- Although the write locks provide some help in preventing lost
- updates, they cannot guarantee that updates will never be lost.
- Consider the following scenario:
-
- Two clients A and B are interested in editing the resource
- 'index.html'. Client A is an HTTP client rather than a WebDAV
- client, and so does not know how to perform locking.
-
- Client A doesn't lock the document, but does a GET and begins
- editing.
-
- Client B does LOCK, performs a GET and begins editing.
-
- Client B finishes editing, performs a PUT, then an UNLOCK.
-
- Client A performs a PUT, overwriting and losing all of B's changes.
-
- There are several reasons why the WebDAV protocol itself cannot
- prevent this situation. First, it cannot force all clients to use
- locking because it must be compatible with HTTP clients that do not
- comprehend locking. Second, it cannot require servers to support
- locking because of the variety of repository implementations, some of
- which rely on reservations and merging rather than on locking.
- Finally, being stateless, it cannot enforce a sequence of operations
- like LOCK / GET / PUT / UNLOCK.
-
- WebDAV servers that support locking can reduce the likelihood that
- clients will accidentally overwrite each other's changes by requiring
- clients to lock resources before modifying them. Such servers would
- effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying
- resources.
-
- WebDAV clients can be good citizens by using a lock / retrieve /
- write /unlock sequence of operations (at least by default) whenever
- they interact with a WebDAV server that supports locking.
-
- HTTP 1.1 clients can be good citizens, avoiding overwriting other
- clients' changes, by using entity tags in If-Match headers with any
- requests that would modify resources.
-
- Information managers may attempt to prevent overwrites by
- implementing client-side procedures requiring locking before
- modifying WebDAV resources.
-
-
-
-Dusseault Expires October 3, 2006 [Page 27]
-
-Internet-Draft WebDAV April 2006
-
-
-7.3. Write Locks and Unmapped URLs
-
- WebDAV provides the ability to send a LOCK request to an unmapped URL
- in order to reserve the name for use. This is a simple way to avoid
- the lost-update problem on the creation of a new resource (another
- way is to use If-None-Match header specified in Section 14.26 of
- [RFC2616]). It has the side benefit of locking the new resource
- immediately for use of the creator.
-
- Note that the lost-update problem is not an issue for collections
- because MKCOL can only be used to create a collection, not to
- overwrite an existing collection. When trying to lock a collection
- upon creation, clients can attempt to increase the likelihood of
- getting the lock by pipelining the MKCOL and LOCK requests together
- (but because this doesn't convert two separate operations into one
- atomic operation there's no guarantee this will work).
-
- A successful lock request to an unmapped URL MUST result in the
- creation of a locked (non-collection) resource with empty content.
- Subsequently, a successful PUT request (with the correct lock token)
- provides the content for the resource. Note that the LOCK request
- has no mechanism for the client to provide Content-Type or Content-
- Language, thus the server will use defaults or empty values and rely
- on the subsequent PUT request for correct values.
-
- A resource created with a LOCK is empty but otherwise behaves in
- every way as a normal resource. It behaves the same way as a
- resource created by a PUT request with an empty body (and where a
- Content-Type and Content-Language was not specified), followed by a
- LOCK request to the same resource. Following from this model, a
- locked empty resource:
-
- o Can be read, deleted, moved, copied, and in all ways behave as a
- regular non-collection resource.
-
- o Appears as a member of its parent collection.
-
- o SHOULD NOT disappear when its lock goes away (clients must
- therefore be responsible for cleaning up their own mess, as with
- any other operation or any non-empty resource)
-
- o MAY NOT have values for properties like DAV:getcontentlanguage
- which haven't been specified yet by the client.
-
- o Can be updated (have content added) with a PUT request.
-
- o MUST NOT be converted into a collection. The server MUST fail a
- MKCOL request (as it would with a MKCOL request to any existing
-
-
-
-Dusseault Expires October 3, 2006 [Page 28]
-
-Internet-Draft WebDAV April 2006
-
-
- non-collection resource).
-
- o MUST have defined values for DAV:lockdiscovery and DAV:
- supportedlock properties.
-
- o The response MUST indicate that a resource was created, by use of
- the "201 Created" response code (a LOCK request to an existing
- resource instead will result in 200 OK). The body must still
- include the DAV:lockdiscovery property, as with a LOCK request to
- an existing resource.
-
- The client is expected to update the locked empty resource shortly
- after locking it, using PUT and possibly PROPPATCH.
-
- Alternatively and for backwards compatibility to [RFC2518], servers
- MAY implement Lock-Null Resources (LNRs) instead (see definition in
- Appendix D). Clients can easily interoperate both with servers that
- support the old model LNRs and the recommended model of "locked empty
- resources" by only attempting PUT after a LOCK to an unmapped URL,
- not MKCOL or GET, and by not relying on specific properties of LNRs.
-
-7.4. Write Locks and Collections
-
- There are two kinds of collection write locks. A "Depth 0" write
- lock on a collection protects the collection properties plus the
- internal member URLs of that one collection, while not protecting the
- content or properties of member resources (if the collection itself
- has any entity bodies, those are also protected). A "Depth:
- infinity" write lock on a collection provides the same protection on
- that collection and also provides write lock protection on every
- member resource.
-
- Expressed otherwise, a write lock protects any request that would
- create a new resource in a write locked collection, any request that
- would remove an internal member URL of a write locked collection, and
- any request that would change the segment name of any internal
- member.
-
- Thus, a collection write lock protects all the following actions:
-
- o DELETE a collection's direct internal member,
-
- o MOVE an internal member out of the collection,
-
- o MOVE an internal member into the collection,
-
- o MOVE to rename an internal member within a collection,
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 29]
-
-Internet-Draft WebDAV April 2006
-
-
- o COPY an internal member into a collection, and
-
- o PUT or MKCOL request which would create a new internal member.
-
- The collection's lock token is required in addition to the lock token
- on the internal member itself, if it is locked separately.
-
- In addition, a depth-infinity lock affects all write operations to
- all members of the locked collection. With a depth-infinity lock,
- the resource identified by the root of the lock is directly locked,
- and all its members are indirectly locked.
-
- o Any new resource added as a descendent of a depth-infinity locked
- collection becomes indirectly locked.
-
- o Any indirectly locked resource moved out of the locked collection
- into an unlocked collection is thereafter unlocked.
-
- o Any indirectly locked resource moved out of a locked source
- collection into a depth-infinity locked target collection remains
- indirectly locked but is now protected by the lock on the target
- collection (the target collection's lock token will thereafter be
- required to make further changes).
-
- If a depth-infinity write LOCK request is issued to a collection
- containing member URLs identifying resources that are currently
- locked in a manner which conflicts with the new lock (see Section 6.1
- point 3), the request MUST fail with a 423 (Locked) status code, and
- the response SHOULD contain the 'no-conflicting-lock' precondition.
-
- If a lock request causes the URL of a resource to be added as an
- internal member URL of a depth-infinity locked collection then the
- new resource MUST be automatically protected by the lock. For
- example, if the collection /a/b/ is write locked and the resource /c
- is moved to /a/b/c then resource /a/b/c will be added to the write
- lock.
-
-7.5. Write Locks and the If Request Header
-
- A user agent has to demonstrate knowledge of a lock when requesting
- an operation on a locked resource. Otherwise, the following scenario
- might occur. In the scenario, program A, run by User A, takes out a
- write lock on a resource. Program B, also run by User A, has no
- knowledge of the lock taken out by program A, yet performs a PUT to
- the locked resource. In this scenario, the PUT succeeds because
- locks are associated with a principal, not a program, and thus
- program B, because it is acting with principal A's credential, is
- allowed to perform the PUT. However, had program B known about the
-
-
-
-Dusseault Expires October 3, 2006 [Page 30]
-
-Internet-Draft WebDAV April 2006
-
-
- lock, it would not have overwritten the resource, preferring instead
- to present a dialog box describing the conflict to the user. Due to
- this scenario, a mechanism is needed to prevent different programs
- from accidentally ignoring locks taken out by other programs with the
- same authorization.
-
- In order to prevent these collisions a lock token MUST be submitted
- by an authorized principal for all locked resources that a method may
- change or the method MUST fail. A lock token is submitted when it
- appears in an If header. For example, if a resource is to be moved
- and both the source and destination are locked then two lock tokens
- must be submitted in the If header, one for the source and the other
- for the destination.
-
-7.5.1. Example - Write Lock and COPY
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
- If: <http://www.example.com/users/f/fielding/index.html>
- (<urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6>)
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, even though both the source and destination are
- locked, only one lock token must be submitted, for the lock on the
- destination. This is because the source resource is not modified by
- a COPY, and hence unaffected by the write lock. In this example,
- user agent authentication has previously occurred via a mechanism
- outside the scope of the HTTP protocol, in the underlying transport
- layer.
-
-7.5.2. Example - Deleting a member of a locked collection
-
- Consider a collection "/locked" exclusively write-locked with Depth:
- Infinity, and an attempt to delete an internal member "/locked/
- member":
-
- >>Request
-
- DELETE /locked/member HTTP/1.1
- Host: example.com
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 31]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 423 Locked
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:lock-token-submitted>
- <D:href>/locked/</D:href>
- </D:lock-token-submitted>
- </D:error>
-
- Thus the client would need to submit the lock token with the request
- to make it succeed. To do that, various forms of the If header (see
- Section 10.4) could be used.
-
- "No-Tag-List" format:
-
- If: (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- "Tagged-List" format, for "http://example.com/locked/":
-
- If: <http://example.com/locked/>
- (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- "Tagged-List" format, for "http://example.com/locked/member":
-
- If: <http://example.com/locked/member>
- (<urn:uuid:150852e2-3847-42d5-8cbe-0f4f296f26cf>)
-
- Note that for the purpose of submitting the lock token the actual
- form doesn't matter; what's relevant is that the lock token appears
- in the If header, and that the If header itself evaluates to true.
-
-7.6. Write Locks and COPY/MOVE
-
- A COPY method invocation MUST NOT duplicate any write locks active on
- the source. However, as previously noted, if the COPY copies the
- resource into a collection that is locked with "Depth: infinity",
- then the resource will be added to the lock.
-
- A successful MOVE request on a write locked resource MUST NOT move
- the write lock with the resource. However, if there is an existing
- lock at the destination, the server MUST add the moved resource to
- the destination lock scope. For example, if the MOVE makes the
- resource a child of a collection that is locked with "Depth:
- infinity", then the resource will be added to that collection's lock.
-
-
-
-Dusseault Expires October 3, 2006 [Page 32]
-
-Internet-Draft WebDAV April 2006
-
-
- Additionally, if a resource locked with "Depth: infinity" is moved to
- a destination that is within the scope of the same lock (e.g., within
- the URL namespace tree covered by the lock), the moved resource will
- again be a added to the lock. In both these examples, as specified
- in Section 7.5, an If header must be submitted containing a lock
- token for both the source and destination.
-
-7.7. Refreshing Write Locks
-
- A client MUST NOT submit the same write lock request twice. Note
- that a client is always aware it is resubmitting the same lock
- request because it must include the lock token in the If header in
- order to make the request for a resource that is already locked.
-
- However, a client may submit a LOCK request with an If header but
- without a body. This form of LOCK MUST only be used to "refresh" a
- lock. Meaning, at minimum, that any timers associated with the lock
- MUST be re-set.
-
- Clients may submit Timeout headers of arbitrary value with their lock
- refresh requests. Servers, as always, may ignore Timeout headers
- submitted by the client, and a server MAY refresh a lock with a
- timeout period that is different than the previous timeout period
- used for the lock, provided it advertises the new value in the LOCK
- refresh response.
-
- If an error is received in response to a refresh LOCK request the
- client MUST NOT assume that the lock was refreshed.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 33]
-
-Internet-Draft WebDAV April 2006
-
-
-8. General Request and Response Handling
-
-8.1. Precedence in Error Handling
-
- Servers MUST return authorization errors in preference to other
- errors. This avoids leaking information about protected resources
- (e.g. a client that finds that a hidden resource exists by seeing a
- 423 Locked response to an anonymous request to the resource).
-
-8.2. Use of XML
-
- In HTTP/1.1, method parameter information was exclusively encoded in
- HTTP headers. Unlike HTTP/1.1, WebDAV encodes method parameter
- information either in an XML ([REC-XML]) request entity body, or in
- an HTTP header. The use of XML to encode method parameters was
- motivated by the ability to add extra XML elements to existing
- structures, providing extensibility; and by XML's ability to encode
- information in ISO 10646 character sets, providing
- internationalization support.
-
- In addition to encoding method parameters, XML is used in WebDAV to
- encode the responses from methods, providing the extensibility and
- internationalization advantages of XML for method output, as well as
- input.
-
- When XML is used for a request or response body, the Content-Type
- type SHOULD be application/xml. Implementations MUST accept both
- text/xml and application/xml in request and response bodies. Use of
- text/xml is deprecated.
-
- All DAV compliant clients and resources MUST use XML parsers that are
- compliant with [REC-XML] and [REC-XML-NAMES]. All XML used in either
- requests or responses MUST be, at minimum, well formed and use
- namespaces correctly. If a server receives XML that is not well-
- formed then the server MUST reject the entire request with a 400 (Bad
- Request). If a client receives XML that is not well-formed in a
- response then the client MUST NOT assume anything about the outcome
- of the executed method and SHOULD treat the server as malfunctioning.
-
- Note that processing XML submitted by an untrusted source may cause
- risks connected to privacy, security, and service quality (see
- Section 20). Servers MAY reject questionable requests (even though
- they consist of well-formed XML), for instance with a 400 (Bad
- Request) status code and an optional response body explaining the
- problem.
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 34]
-
-Internet-Draft WebDAV April 2006
-
-
-8.3. URL Handling
-
- URLs appear in many places in requests and responses.
- Interoperability experience with [RFC2518] showed that many clients
- parsing Multi-Status responses did not fully implement the full
- Reference Resolution defined in Section 5 of [RFC3986]. Thus,
- servers in particular need to be careful in handling URLs in
- responses, to ensure that clients have enough context to be able to
- interpret all the URLs. The rules in this section apply not only to
- resource URLs in the 'href' element in Multi-Status responses, but
- also to the Destination and If header resource URLs.
-
- The sender has a choice between two approaches: using a relative
- reference, which is resolved against the Request-URI, or a full URI.
- A server MUST ensure that every 'href' value within a Multi-Status
- response uses the same format.
-
- WebDAV only uses one form of relative reference in its extensions,
- the absolute path.
-
- Simple-ref = absolute-URI | ( path-absolute [ "?" query ] )
-
- The absolute-URI, path-absolute and query productions are defined in
- Section 4.3, 3.3 and 3.4 of [RFC3986].
-
- Within Simple-ref productions, senders MUST NOT:
-
- o use dot-segments ("." or ".."), or
-
- o have prefixes that do not match the Request-URI (using the
- comparison rules defined in Section 3.2.3 of [RFC2616]).
-
- Identifiers for collections SHOULD end in a '/' character.
-
-8.3.1. Example - Correct URL Handling
-
- Consider the collection http://example.com/sample/ with the internal
- member URL http://example.com/sample/a%20test and the PROPFIND
- request below:
-
- >>Request:
-
- PROPFIND /sample/ HTTP/1.1
- Host: example.com
- Depth: 1
-
- In this case, the server should return two 'href' elements containing
- either
-
-
-
-Dusseault Expires October 3, 2006 [Page 35]
-
-Internet-Draft WebDAV April 2006
-
-
- o 'http://example.com/sample/' and
- 'http://example.com/sample/a%20test', or
-
- o '/sample/' and '/sample/a%20test'
-
- Note that even though the server may be storing the member resource
- internally as 'a test', it has to be percent-encoded when used inside
- a URI reference (see Section 2.1 of [RFC3986]). Also note that a
- legal URI may still contain characters that need to be escaped within
- XML character data, such as the ampersand character.
-
-8.4. Required Bodies in Requests
-
- Some of these new methods do not define bodies. Servers MUST examine
- all requests for a body, even when a body was not expected. In cases
- where a request body is present but would be ignored by a server, the
- server MUST reject the request with 415 (Unsupported Media Type).
- This informs the client (which may have been attempting to use an
- extension) that the body could not be processed as the client
- intended.
-
-8.5. HTTP Headers for use in WebDAV
-
- HTTP defines many headers that can be used in WebDAV requests and
- responses. Not all of these are appropriate in all situations and
- some interactions may be undefined. Note that HTTP 1.1 requires the
- Date header in all responses if possible (see Section 14.18,
- [RFC2616]).
-
- The server MUST do authorization checks before checking any HTTP
- conditional header.
-
-8.6. ETag
-
- HTTP 1.1 recommends the use of ETags rather than modification dates,
- for cache-control, and there are even stronger reasons to prefer
- ETags for authoring. Correct use of ETags is even more important in
- a distributed authoring environment, because ETags are necessary
- along with locks to avoid the lost-update problem. A client might
- fail to renew a lock, for example when the lock times out and the
- client is accidentally offline or in the middle of a long upload.
- When a client fails to renew the lock, it's quite possible the
- resource can still be relocked and the user can go on editing, as
- long as no changes were made in the meantime. ETags are required for
- the client to be able to distinguish this case. Otherwise, the
- client is forced to ask the user whether to overwrite the resource on
- the server without even being able to tell the user whether it has
- changed. Timestamps do not solve this problem nearly as well as
-
-
-
-Dusseault Expires October 3, 2006 [Page 36]
-
-Internet-Draft WebDAV April 2006
-
-
- ETags.
-
- Strong ETags are much more useful for authoring use cases than weak
- ETags. Semantic equivalence can be a useful concept but that depends
- on the document type and the application type, and interoperability
- might require some agreement or standard outside the scope of this
- specification and HTTP. Note also that weak ETags have certain
- restrictions in HTTP, e.g. these cannot be used in If-Match headers.
-
- Note that the meaning of an ETag in a PUT response is not clearly
- defined either in this document or in RFC2616 (i.e., whether the ETag
- means that the resource is octet-for-octet equivalent to the body of
- the PUT request, or whether the server could have made minor changes
- in the formatting or content of the document upon storage). This is
- an HTTP issue, not purely a WebDAV issue, and is being addressed in
- [I-D.draft-whitehead-http-etag].
-
- Because clients may be forced to prompt users or throw away changed
- content if the ETag changes, a WebDAV server SHOULD NOT change the
- ETag (or the Last-Modified time) for a resource that has an unchanged
- body and location. The ETag represents the state of the body or
- contents of the resource. There is no similar way to tell if
- properties have changed.
-
-8.7. Including error response bodies
-
- HTTP and WebDAV did not use the bodies of most error responses for
- machine-parsable information until DeltaV introduced a mechanism to
- include more specific information in the body of an error response
- (Section 1.6 of [RFC3253]). The error body mechanism is appropriate
- to use with any error response that may take a body but does not
- already have a body defined. The mechanism is particularly
- appropriate when a status code can mean many things (for example, 400
- Bad Request can mean required headers are missing, headers are
- incorrectly formatted, or much more). This error body mechanism is
- covered in Section 16.
-
-8.8. Impact of Namespace Operations on Cache Validators
-
- Note that the HTTP response headers "Etag" and "Last-Modified" (see
- [RFC2616], Sections 14.19 and 14.29) are defined per URL (not per
- resource), and are used by clients for caching. Therefore servers
- must ensure that executing any operation that affects the URL
- namespace (such as COPY, MOVE, DELETE, PUT or MKCOL) does preserve
- their semantics, in particular:
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 37]
-
-Internet-Draft WebDAV April 2006
-
-
- o For any given URL, the "Last-Modified" value MUST increment every
- time the representation returned upon GET changes (within the
- limits of timestamp resolution).
-
- o For any given URL, an "ETag" value MUST NOT be re-used for
- different representations returned by GET.
-
- In practice this means that servers
-
- o might have to increment "Last-Modified" timestamps for every
- resource inside the destination namespace of a namespace operation
- unless it can do so more selectively, and
-
- o similarily, might have to re-assign "ETag" values for these
- resources (unless the server allocates entity tags in a way so
- that they are unique across the whole URL namespace managed by the
- server).
-
- Note that these considerations also apply to specific use cases, such
- as using PUT to create a new resource at a URL that has been mapped
- before, but has been deleted since then.
-
- Finally, WebDAV properties (such as DAV:getetag and DAV:
- getlastmodified) that inherit their semantics from HTTP headers must
- behave accordingly.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 38]
-
-Internet-Draft WebDAV April 2006
-
-
-9. HTTP Methods for Distributed Authoring
-
-9.1. PROPFIND Method
-
- The PROPFIND method retrieves properties defined on the resource
- identified by the Request-URI, if the resource does not have any
- internal members, or on the resource identified by the Request-URI
- and potentially its member resources, if the resource is a collection
- that has internal member URLs. All DAV compliant resources MUST
- support the PROPFIND method and the propfind XML element
- (Section 14.20) along with all XML elements defined for use with that
- element.
-
- A client MUST submit a Depth header with a value of "0", "1", or
- "infinity" with a PROPFIND request. Servers MUST support "0" and "1"
- depth requests on WebDAV-compliant resources and SHOULD support
- "infinity" requests. In practice, support for depth infinity
- requests MAY be disabled, due to the performance and security
- concerns associated with this behavior. Since clients weren't
- required to include the Depth header in [RFC2518], servers SHOULD
- treat such a request as if a "Depth: infinity" header was included.
-
- A client may submit a 'propfind' XML element in the body of the
- request method describing what information is being requested. It is
- possible to:
-
- o Request particular property values, by naming the properties
- desired within the 'prop' element (the ordering of properties in
- here MAY be ignored by server),
-
- o Request property values for those properties defined in this
- specification plus dead properties, by using the 'allprop' element
- (the 'include' element can be used with 'allprop' to instruct the
- server to also include additional live properties that may not
- have been returned otherwise),
-
- o Request a list of names of all the properties defined on the
- resource, by using the 'propname' element.
-
- A client may choose not to submit a request body. An empty PROPFIND
- request body MUST be treated as if it were an 'allprop' request.
-
- Note that 'allprop' does not return values for all live properties.
- WebDAV servers increasingly have expensively-calculated or lengthy
- properties (see [RFC3253] and [RFC3744]) and do not return all
- properties already. Instead, WebDAV clients can use propname
- requests to discover what live properties exist, and request named
- properties when retrieving values. For a live property defined
-
-
-
-Dusseault Expires October 3, 2006 [Page 39]
-
-Internet-Draft WebDAV April 2006
-
-
- elsewhere, that definition can specify whether that live property
- would be returned in 'allprop' requests or not.
-
- All servers MUST support returning a response of content type text/
- xml or application/xml that contains a multistatus XML element that
- describes the results of the attempts to retrieve the various
- properties.
-
- If there is an error retrieving a property then a proper error result
- MUST be included in the response. A request to retrieve the value of
- a property which does not exist is an error and MUST be noted, if the
- response uses a 'multistatus' XML element, with a 'response' XML
- element which contains a 404 (Not Found) status value.
-
- Consequently, the 'multistatus' XML element for a collection resource
- MUST include a 'response' XML element for each member URL of the
- collection, to whatever depth was requested. It SHOULD NOT include
- any 'response' elements for resources that are not WebDAV-compliant.
- Each 'response' element MUST contain an 'href' element that contains
- the URL of the resource on which the properties in the prop XML
- element are defined. Results for a PROPFIND on a collection resource
- are returned as a flat list whose order of entries is not
- significant. Note that a resource may have only one value for a
- property of a given name, so the property may only show up once in
- PROPFIND responses.
-
- Properties may be subject to access control. In the case of
- 'allprop' and 'propname' requests, if a principal does not have the
- right to know whether a particular property exists then the property
- MAY be silently excluded from the response.
-
- Some PROPFIND results MAY be cached, with care as there is no cache
- validation mechanism for most properties. This method is both safe
- and idempotent (see Section 9.1 of [RFC2616]).
-
-9.1.1. PROPFIND status codes
-
- This section, as with similar sections for other methods, provides
- some guidance on error codes and preconditions or postconditions
- (defined in Section 16) that might be particularly useful with
- PROPFIND.
-
- 403 Forbidden - A server MAY reject PROPFIND requests on collections
- with depth header of "Infinity", in which case it SHOULD use this
- error with the precondition code 'propfind-finite-depth' inside the
- error body.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 40]
-
-Internet-Draft WebDAV April 2006
-
-
-9.1.2. Status Codes for use in 'propstat' Element
-
- In PROPFIND responses, information about individual properties is
- returned inside 'propstat' elements (see Section 14.22), each
- containing an individual 'status' element containing information
- about the properties appearing in it. The list below summarizes the
- most common status codes used inside 'propstat', however clients
- should be prepared to handle other 2/3/4/5xx series status codes as
- well.
-
- 200 OK - A property exists and/or its value is successfully returned.
-
- 401 Unauthorized - The property cannot be viewed without appropriate
- authorization.
-
- 403 Forbidden - The property cannot be viewed regardless of
- authentication.
-
- 404 Not Found - The property does not exist.
-
-9.1.3. Example - Retrieving Named Properties
-
- >>Request
-
- PROPFIND /file HTTP/1.1
- Host: www.example.com
- Content-type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <R:author/>
- <R:DingALing/>
- <R:Random/>
- </D:prop>
- </D:propfind>
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 41]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response xmlns:R="http://ns.example.com/boxschema/">
- <D:href>http://www.example.com/file</D:href>
- <D:propstat>
- <D:prop>
- <R:bigbox>
- <R:BoxType>Box type A</R:BoxType>
- </R:bigbox>
- <R:author>
- <R:Name>J.J. Johnson</R:Name>
- </R:author>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><R:DingALing/><R:Random/></D:prop>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- <D:responsedescription> The user does not have access to the
- DingALing property.
- </D:responsedescription>
- </D:propstat>
- </D:response>
- <D:responsedescription> There has been an access violation error.
- </D:responsedescription>
- </D:multistatus>
-
-
- In this example, PROPFIND is executed on a non-collection resource
- http://www.example.com/file. The propfind XML element specifies the
- name of four properties whose values are being requested. In this
- case only two properties were returned, since the principal issuing
- the request did not have sufficient access rights to see the third
- and fourth properties.
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 42]
-
-Internet-Draft WebDAV April 2006
-
-
-9.1.4. Example - Using so-called 'allprop'
-
- >>Request
-
- PROPFIND /mycol/ HTTP/1.1
- Host: www.example.com
- Depth: 1
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- <D:include>
- <D:creationdate/>
- <D:getlastmodified/>
- </D:include>
- </D:propfind>
-
- In this example, PROPFIND is executed on the resource
- http://www.example.com/mycol/ and its internal member resources. The
- client requests the values of all live properties defined in this
- specification, plus all dead properties, plus two more live
- properties defined in [RFC3253]. The response is not shown.
-
-9.1.5. Example - Using 'propname' to Retrieve all Property Names
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <propfind xmlns="DAV:">
- <propname/>
- </propfind>
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 43]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <multistatus xmlns="DAV:">
- <response>
- <href>http://www.example.com/container/</href>
- <propstat>
- <prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <R:author/>
- <creationdate/>
- <displayname/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
- </propstat>
- </response>
- <response>
- <href>http://www.example.com/container/front.html</href>
- <propstat>
- <prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox/>
- <creationdate/>
- <displayname/>
- <getcontentlength/>
- <getcontenttype/>
- <getetag/>
- <getlastmodified/>
- <resourcetype/>
- <supportedlock/>
- </prop>
- <status>HTTP/1.1 200 OK</status>
- </propstat>
- </response>
- </multistatus>
-
- In this example, PROPFIND is invoked on the collection resource
- http://www.example.com/container/, with a propfind XML element
- containing the propname XML element, meaning the name of all
- properties should be returned. Since no Depth header is present, it
- assumes its default value of "infinity", meaning the name of the
- properties on the collection and all its descendents should be
- returned.
-
-
-
-Dusseault Expires October 3, 2006 [Page 44]
-
-Internet-Draft WebDAV April 2006
-
-
- Consistent with the previous example, resource
- http://www.example.com/container/ has six properties defined on it:
- bigbox and author in the "http://ns.example.com/boxschema/"
- namespace, and creationdate, displayname, resourcetype, and
- supportedlock in the "DAV:" namespace.
-
- The resource http://www.example.com/container/index.html, a member of
- the "container" collection, has nine properties defined on it, bigbox
- in the "http://ns.example.com/boxschema/" namespace and,
- creationdate, displayname, getcontentlength, getcontenttype, getetag,
- getlastmodified, resourcetype, and supportedlock in the "DAV:"
- namespace.
-
- This example also demonstrates the use of XML namespace scoping and
- the default namespace. Since the "xmlns" attribute does not contain
- a prefix, the namespace applies by default to all enclosed elements.
- Hence, all elements which do not explicitly state the namespace to
- which they belong are members of the "DAV:" namespace.
-
-9.1.6. Example - Using 'allprop'
-
- Note that 'allprop', despite its name which remains for backward-
- compatibility, does not return every property, but only dead
- properties and the live properties defined in this specification.
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Depth: 1
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- </D:propfind>
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
-
-
-
-Dusseault Expires October 3, 2006 [Page 45]
-
-Internet-Draft WebDAV April 2006
-
-
- <D:href>/container/</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox><R:BoxType>Box type A</R:BoxType></R:bigbox>
- <R:author><R:Name>Hadrian</R:Name></R:author>
- <D:creationdate>1997-12-01T17:42:21-08:00</D:creationdate>
- <D:displayname>Example collection</D:displayname>
- <D:resourcetype><D:collection/></D:resourcetype>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>/container/front.html</D:href>
- <D:propstat>
- <D:prop xmlns:R="http://ns.example.com/boxschema/">
- <R:bigbox><R:BoxType>Box type B</R:BoxType>
- </R:bigbox>
- <D:creationdate>1997-12-01T18:27:21-08:00</D:creationdate>
- <D:displayname>Example HTML resource</D:displayname>
- <D:getcontentlength>4525</D:getcontentlength>
- <D:getcontenttype>text/html</D:getcontenttype>
- <D:getetag>"zzyzx"</D:getetag>
- <D:getlastmodified
- >Mon, 12 Jan 1998 09:25:56 GMT</D:getlastmodified>
- <D:resourcetype/>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
-
-
-
-Dusseault Expires October 3, 2006 [Page 46]
-
-Internet-Draft WebDAV April 2006
-
-
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- In this example, PROPFIND was invoked on the resource
- http://www.example.com/container/ with a Depth header of 1, meaning
- the request applies to the resource and its children, and a propfind
- XML element containing the allprop XML element, meaning the request
- should return the name and value of all the dead properties defined
- on the resources, plus the name and value of all the properties
- defined in this specification. This example illustrates the use of
- relative references in the 'href' elements of the response.
-
- The resource http://www.example.com/container/ has six properties
- defined on it: 'bigbox' and 'author in the
- "http://ns.example.com/boxschema/" namespace, DAV:creationdate, DAV:
- displayname, DAV:resourcetype, and DAV:supportedlock.
-
- The last four properties are WebDAV-specific, defined in Section 15.
- Since GET is not supported on this resource, the get* properties
- (e.g., DAV:getcontentlength) are not defined on this resource. The
- WebDAV-specific properties assert that "container" was created on
- December 1, 1997, at 5:42:21PM, in a time zone 8 hours west of GMT
- (DAV:creationdate), has a name of "Example collection" (DAV:
- displayname), a collection resource type (DAV:resourcetype), and
- supports exclusive write and shared write locks (DAV:supportedlock).
-
- The resource http://www.example.com/container/front.html has nine
- properties defined on it:
-
- 'bigbox' in the "http://ns.example.com/boxschema/" namespace (another
- instance of the "bigbox" property type), DAV:creationdate, DAV:
- displayname, DAV:getcontentlength, DAV:getcontenttype, DAV:getetag,
- DAV:getlastmodified, DAV:resourcetype, and DAV:supportedlock.
-
- The DAV-specific properties assert that "front.html" was created on
- December 1, 1997, at 6:27:21PM, in a time zone 8 hours west of GMT
- (DAV:creationdate), has a name of "Example HTML resource" (DAV:
- displayname), a content length of 4525 bytes (DAV:getcontentlength),
- a MIME type of "text/html" (DAV:getcontenttype), an entity tag of
- "zzyzx" (DAV:getetag), was last modified on Monday, January 12, 1998,
- at 09:25:56 GMT (DAV:getlastmodified), has an empty resource type,
- meaning that it is not a collection (DAV:resourcetype), and supports
- both exclusive write and shared write locks (DAV:supportedlock).
-
-9.2. PROPPATCH Method
-
- The PROPPATCH method processes instructions specified in the request
-
-
-
-Dusseault Expires October 3, 2006 [Page 47]
-
-Internet-Draft WebDAV April 2006
-
-
- body to set and/or remove properties defined on the resource
- identified by the Request-URI.
-
- All DAV compliant resources MUST support the PROPPATCH method and
- MUST process instructions that are specified using the
- propertyupdate, set, and remove XML elements. Execution of the
- directives in this method is, of course, subject to access control
- constraints. DAV compliant resources SHOULD support the setting of
- arbitrary dead properties.
-
- The request message body of a PROPPATCH method MUST contain the
- propertyupdate XML element.
-
- Servers MUST process PROPPATCH instructions in document order (an
- exception to the normal rule that ordering is irrelevant).
- Instructions MUST either all be executed or none executed. Thus if
- any error occurs during processing all executed instructions MUST be
- undone and a proper error result returned. Instruction processing
- details can be found in the definition of the set and remove
- instructions in Section 14.23 and Section 14.26.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.2.1. Status Codes for use in 'propstat' Element
-
- In PROPPATCH responses, information about individual properties is
- returned inside 'propstat' elements (see Section 14.22), each
- containing an individual 'status' element containing information
- about the properties appearing in it. The list below summarizes the
- most common status codes used inside 'propstat', however clients
- should be prepared to handle other 2/3/4/5xx series status codes as
- well.
-
- 200 (OK) - The property set or change succeeded. Note that if this
- appears for one property, it appears for every property in the
- response, due to the atomicity of PROPPATCH.
-
- 403 (Forbidden) - The client, for reasons the server chooses not to
- specify, cannot alter one of the properties.
-
- 403 (Forbidden): The client has attempted to set a protected
- property, such as DAV:getetag. If returning this error, the server
- SHOULD use the precondition code 'cannot-modify-protected-property'
- inside the response body.
-
- 409 (Conflict) - The client has provided a value whose semantics are
- not appropriate for the property.
-
-
-
-Dusseault Expires October 3, 2006 [Page 48]
-
-Internet-Draft WebDAV April 2006
-
-
- 424 (Failed Dependency) - The property change could not be made
- because of another property change that failed.
-
- 507 (Insufficient Storage) - The server did not have sufficient space
- to record the property.
-
-9.2.2. Example - PROPPATCH
-
- >>Request
-
- PROPPATCH /bar.html HTTP/1.1
- Host: www.example.com
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propertyupdate xmlns:D="DAV:"
- xmlns:Z="http://ns.example.com/standards/z39.50/">
- <D:set>
- <D:prop>
- <Z:Authors>
- <Z:Author>Jim Whitehead</Z:Author>
- <Z:Author>Roy Fielding</Z:Author>
- </Z:Authors>
- </D:prop>
- </D:set>
- <D:remove>
- <D:prop><Z:Copyright-Owner/></D:prop>
- </D:remove>
- </D:propertyupdate>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 49]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:Z="http://ns.example.com/standards/z39.50/">
- <D:response>
- <D:href>http://www.example.com/bar.html</D:href>
- <D:propstat>
- <D:prop><Z:Authors/></D:prop>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop><Z:Copyright-Owner/></D:prop>
- <D:status>HTTP/1.1 409 Conflict</D:status>
- </D:propstat>
- <D:responsedescription> Copyright Owner can not be deleted or
- altered.</D:responsedescription>
- </D:response>
- </D:multistatus>
-
- In this example, the client requests the server to set the value of
- the "Authors" property in the
- "http://ns.example.com/standards/z39.50/" namespace, and to remove
- the property "Copyright-Owner" in the same namespace. Since the
- Copyright-Owner property could not be removed, no property
- modifications occur. The 424 (Failed Dependency) status code for the
- Authors property indicates this action would have succeeded if it
- were not for the conflict with removing the Copyright-Owner property.
-
-9.3. MKCOL Method
-
- The MKCOL method is used to create a new collection. All WebDAV
- compliant resources MUST support the MKCOL method.
-
- MKCOL creates a new collection resource at the location specified by
- the Request-URI. If the Request-URI is already mapped to a resource
- then the MKCOL MUST fail. During MKCOL processing, a server MUST
- make the Request-URI an internal member of its parent collection,
- unless the Request-URI is "/". If no such ancestor exists, the
- method MUST fail. When the MKCOL operation creates a new collection
- resource, all ancestors MUST already exist, or the method MUST fail
- with a 409 (Conflict) status code. For example, if a request to
- create collection /a/b/c/d/ is made, and /a/b/c/ does not exist, the
- request must fail.
-
-
-
-Dusseault Expires October 3, 2006 [Page 50]
-
-Internet-Draft WebDAV April 2006
-
-
- When MKCOL is invoked without a request body, the newly created
- collection SHOULD have no members.
-
- A MKCOL request message may contain a message body. The precise
- behavior of a MKCOL request when the body is present is undefined,
- but limited to creating collections, members of a collection, bodies
- of members and properties on the collections or members. If the
- server receives a MKCOL request entity type it does not support or
- understand it MUST respond with a 415 (Unsupported Media Type) status
- code. If the server decides to reject the request based on the
- presence of an entity or the type of an entity, it should use the 415
- (Unsupported Media Type) status code.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.3.1. MKCOL Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to MKCOL:
-
- 201 (Created) - The collection was created.
-
- 403 (Forbidden) - This indicates at least one of two conditions: 1)
- the server does not allow the creation of collections at the given
- location in its URL namespace, or 2) the parent collection of the
- Request-URI exists but cannot accept members.
-
- 405 (Method Not Allowed) - MKCOL can only be executed on an unmapped
- URL.
-
- 409 (Conflict) - A collection cannot be made at the Request-URI until
- one or more intermediate collections have been created. The server
- MUST NOT create those intermediate collections automatically.
-
- 415 (Unsupported Media Type) - The server does not support the
- request body type (since this specification does not define any body
- for MKCOL requests).
-
- 507 (Insufficient Storage) - The resource does not have sufficient
- space to record the state of the resource after the execution of this
- method.
-
-9.3.2. Example - MKCOL
-
- This example creates a collection called /webdisc/xfiles/ on the
- server www.example.com.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 51]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Request
-
- MKCOL /webdisc/xfiles/ HTTP/1.1
- Host: www.example.com
-
-
- >>Response
-
- HTTP/1.1 201 Created
-
-9.4. GET, HEAD for Collections
-
- The semantics of GET are unchanged when applied to a collection,
- since GET is defined as, "retrieve whatever information (in the form
- of an entity) is identified by the Request-URI" [RFC2616]. GET when
- applied to a collection may return the contents of an "index.html"
- resource, a human-readable view of the contents of the collection, or
- something else altogether. Hence it is possible that the result of a
- GET on a collection will bear no correlation to the membership of the
- collection.
-
- Similarly, since the definition of HEAD is a GET without a response
- message body, the semantics of HEAD are unmodified when applied to
- collection resources.
-
-9.5. POST for Collections
-
- Since by definition the actual function performed by POST is
- determined by the server and often depends on the particular
- resource, the behavior of POST when applied to collections cannot be
- meaningfully modified because it is largely undefined. Thus the
- semantics of POST are unmodified when applied to a collection.
-
-9.6. DELETE Requirements
-
- DELETE is defined in [RFC2616], Section 9.7, to "delete the resource
- identified by the Request-URI". However, WebDAV changes some DELETE
- handling requirements.
-
- A server processing a successful DELETE request:
-
- MUST destroy locks rooted on the deleted resource
-
- MUST remove the mapping from the Request-URI to any resource.
-
- Thus, after a successful DELETE operation (and in the absence of
- other actions) a subsequent GET/HEAD/PROPFIND request to the target
- Request-URI MUST return 404 (Not Found).
-
-
-
-Dusseault Expires October 3, 2006 [Page 52]
-
-Internet-Draft WebDAV April 2006
-
-
-9.6.1. DELETE for Collections
-
- The DELETE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header with
- a DELETE on a collection with any value but infinity.
-
- DELETE instructs that the collection specified in the Request-URI and
- all resources identified by its internal member URLs are to be
- deleted.
-
- If any resource identified by a member URL cannot be deleted then all
- of the member's ancestors MUST NOT be deleted, so as to maintain URL
- namespace consistency.
-
- Any headers included with DELETE MUST be applied in processing every
- resource to be deleted.
-
- When the DELETE method has completed processing it MUST result in a
- consistent URL namespace.
-
- If an error occurs deleting a member resource (a resource other than
- the resource identified in the Request-URI) then the response can be
- a 207 (Multi-Status). Multi-Status is used here to indicate which
- internal resources could NOT be deleted, including an error code
- which should help the client understand which resources caused the
- failure. For example, the Multi-Status body could include a response
- with status 423 (Locked) if an internal resource was locked.
-
- The server MAY return a 4xx status response, rather than a 207, if
- the request failed completely.
-
- 424 (Failed Dependency) status codes SHOULD NOT be in the 207 (Multi-
- Status) response for DELETE. They can be safely left out because the
- client will know that the ancestors of a resource could not be
- deleted when the client receives an error for the ancestor's progeny.
- Additionally 204 (No Content) errors SHOULD NOT be returned in the
- 207 (Multi-Status). The reason for this prohibition is that 204 (No
- Content) is the default success code.
-
-9.6.2. Example - DELETE
-
- >>Request
-
- DELETE /container/ HTTP/1.1
- Host: www.example.com
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 53]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.example.com/container/resource3</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
- In this example the attempt to delete
- http://www.example.com/container/resource3 failed because it is
- locked, and no lock token was submitted with the request.
- Consequently, the attempt to delete http://www.example.com/container/
- also failed. Thus the client knows that the attempt to delete
- http://www.example.com/container/ must have also failed since the
- parent can not be deleted unless its child has also been deleted.
- Even though a Depth header has not been included, a depth of infinity
- is assumed because the method is on a collection.
-
-9.7. PUT Requirements
-
-9.7.1. PUT for Non-Collection Resources
-
- A PUT performed on an existing resource replaces the GET response
- entity of the resource. Properties defined on the resource may be
- recomputed during PUT processing but are not otherwise affected. For
- example, if a server recognizes the content type of the request body,
- it may be able to automatically extract information that could be
- profitably exposed as properties.
-
- A PUT that would result in the creation of a resource without an
- appropriately scoped parent collection MUST fail with a 409
- (Conflict).
-
- A PUT request is the only way a client has to indicate to the server
- what Content-Type a resource should have, and whether it should
- change if the resource is overwritten. Thus, a client SHOULD provide
- a Content-Type for a new resource if any is known. If the client
- does not provide a Content-Type for a new resource, the server MAY
- create a resource with no Content-Type assigned, or it MAY attempt to
- assign a Content-Type.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 54]
-
-Internet-Draft WebDAV April 2006
-
-
- Note that although a recipient should treat metadata supplied with an
- HTTP request as authorative, in practice there's no guarantee that a
- server will accept Content- headers. Many servers do not allow
- configuring the Content-Type on a per-resource basis in the first
- place. Thus, clients should not rely on the ability to directly
- influence the content type by including a Content-Type request
- header.
-
-9.7.2. PUT for Collections
-
- This specification does not define the behavior of the PUT method for
- existing collections. A PUT request to an existing collection MAY be
- treated as an error (405 Method Not Allowed).
-
- The MKCOL method is defined to create collections.
-
-9.8. COPY Method
-
- The COPY method creates a duplicate of the source resource identified
- by the Request-URI, in the destination resource identified by the URI
- in the Destination header. The Destination header MUST be present.
- The exact behavior of the COPY method depends on the type of the
- source resource.
-
- All WebDAV compliant resources MUST support the COPY method.
- However, support for the COPY method does not guarantee the ability
- to copy a resource. For example, separate programs may control
- resources on the same server. As a result, it may not be possible to
- copy a resource to a location that appears to be on the same server.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.8.1. COPY for Non-collection Resources
-
- When the source resource is not a collection the result of the COPY
- method is the creation of a new resource at the destination whose
- state and behavior match that of the source resource as closely as
- possible. Since the environment at the destination may be different
- than at the source due to factors outside the scope of control of the
- server, such as the absence of resources required for correct
- operation, it may not be possible to completely duplicate the
- behavior of the resource at the destination. Subsequent alterations
- to the destination resource will not modify the source resource.
- Subsequent alterations to the source resource will not modify the
- destination resource.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 55]
-
-Internet-Draft WebDAV April 2006
-
-
-9.8.2. COPY for Properties
-
- After a successful COPY invocation, all dead properties on the source
- resource SHOULD be duplicated on the destination resource. Live
- properties described in this document SHOULD be duplicated as
- identically behaving live properties at the destination resource, but
- not necessarily with the same values. Servers SHOULD NOT convert
- live properties into dead properties on the destination resource,
- because clients may then draw incorrect conclusions about the state
- or functionality of a resource. Note that some live properties are
- defined such that the absence of the property has a specific meaning
- (e.g. a flag with one meaning if present and the opposite if absent),
- and in these cases, a successful COPY might result in the property
- being reported as "Not Found" in subsequent requests.
-
- When the destination is an unmapped URL, a COPY operation creates a
- new resource much like a PUT operation does. Live properties which
- are related to resource creation (such as DAV:creationdate) should
- have their values set accordingly.
-
-9.8.3. COPY for Collections
-
- The COPY method on a collection without a Depth header MUST act as if
- a Depth header with value "infinity" was included. A client may
- submit a Depth header on a COPY on a collection with a value of "0"
- or "infinity". Servers MUST support the "0" and "infinity" Depth
- header behaviors on WebDAV-compliant resources.
-
- A COPY of depth infinity instructs that the collection resource
- identified by the Request-URI is to be copied to the location
- identified by the URI in the Destination header, and all its internal
- member resources are to be copied to a location relative to it,
- recursively through all levels of the collection hierarchy. Note
- that a depth infinity COPY of /A/ into /A/B/ could lead to infinite
- recursion if not handled correctly.
-
- A COPY of "Depth: 0" only instructs that the collection and its
- properties but not resources identified by its internal member URLs,
- are to be copied.
-
- Any headers included with a COPY MUST be applied in processing every
- resource to be copied with the exception of the Destination header.
-
- The Destination header only specifies the destination URI for the
- Request-URI. When applied to members of the collection identified by
- the Request-URI the value of Destination is to be modified to reflect
- the current location in the hierarchy. So, if the Request-URI is /a/
- with Host header value http://example.com/ and the Destination is
-
-
-
-Dusseault Expires October 3, 2006 [Page 56]
-
-Internet-Draft WebDAV April 2006
-
-
- http://example.com/b/ then when http://example.com/a/c/d is processed
- it must use a Destination of http://example.com/b/c/d.
-
- When the COPY method has completed processing it MUST have created a
- consistent URL namespace at the destination (see Section 5.1 for the
- definition of namespace consistency). However, if an error occurs
- while copying an internal collection, the server MUST NOT copy any
- resources identified by members of this collection (i.e., the server
- must skip this subtree), as this would create an inconsistent
- namespace. After detecting an error, the COPY operation SHOULD try
- to finish as much of the original copy operation as possible (i.e.,
- the server should still attempt to copy other subtrees and their
- members, that are not descendents of an error-causing collection).
-
- So, for example, if an infinite depth copy operation is performed on
- collection /a/, which contains collections /a/b/ and /a/c/, and an
- error occurs copying /a/b/, an attempt should still be made to copy
- /a/c/. Similarly, after encountering an error copying a non-
- collection resource as part of an infinite depth copy, the server
- SHOULD try to finish as much of the original copy operation as
- possible.
-
- If an error in executing the COPY method occurs with a resource other
- than the resource identified in the Request-URI then the response
- MUST be a 207 (Multi-Status), and the URL of the resource causing the
- failure MUST appear with the specific error.
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a COPY method. These responses can
- be safely omitted because the client will know that the progeny of a
- resource could not be copied when the client receives an error for
- the parent. Additionally 201 (Created)/204 (No Content) status codes
- SHOULD NOT be returned as values in 207 (Multi-Status) responses from
- COPY methods. They, too, can be safely omitted because they are the
- default success codes.
-
-9.8.4. COPY and Overwriting Destination Resources
-
- If a COPY request has an Overwrite header with a value of "F", and a
- resource exists at the Destination URL, the server MUST fail the
- request.
-
- When a server executes a COPY request and overwrites a destination
- resource, the exact behavior MAY depend on many factors, including
- WebDAV extension capabilities (see particularly [RFC3253]). For
- example, when an ordinary resource is overwritten, the server could
- delete the target resource before doing the copy, or could do an in-
- place overwrite to preserve live properties.
-
-
-
-Dusseault Expires October 3, 2006 [Page 57]
-
-Internet-Draft WebDAV April 2006
-
-
- When a collection is overwritten, the membership of the destination
- collection after the successful COPY request MUST be the same
- membership as the source collection immediately before the COPY.
- Thus, merging the membership of the source and destination
- collections together in the destination is not a compliant behavior.
-
- In general, if clients require the state of the destination URL to be
- wiped out prior to a COPY (e.g. to force live properties to be
- reset), then the client could send a DELETE to the destination before
- the COPY request to ensure this reset.
-
-9.8.5. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to COPY:
-
- 201 (Created) - The source resource was successfully copied. The
- COPY operation resulted in the creation of a new resource.
-
- 204 (No Content) - The source resource was successfully copied to a
- pre-existing destination resource.
-
- 207 (Multi-Status) - Multiple resources were to be affected by the
- COPY, but errors on some of them prevented the operation from taking
- place. Specific error messages, together with the most appropriate
- of the source and destination URLs, appear in the body of the multi-
- status response. E.g. if a destination resource was locked and could
- not be overwritten, then the destination resource URL appears with
- the 423 (Locked) status.
-
- 403 (Forbidden) - The operation is forbidden. A special case for
- COPY could be that the source and destination resources are the same
- resource.
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
-
- 412 (Precondition Failed) - A precondition header check failed, e.g.
- the Overwrite header is "F" and the destination URL is already mapped
- to a resource.
-
- 423 (Locked) - The destination resource, or resource within the
- destination collection, was locked. This response SHOULD contain the
- 'lock-token-submitted' precondition element.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server, repository or URL namespace. Either the source namespace
-
-
-
-Dusseault Expires October 3, 2006 [Page 58]
-
-Internet-Draft WebDAV April 2006
-
-
- does not support copying to the destination namespace, or the
- destination namespace refuses to accept the resource. The client may
- wish to try GET/PUT and PROPFIND/PROPPATCH instead.
-
- 507 (Insufficient Storage) - The destination resource does not have
- sufficient space to record the state of the resource after the
- execution of this method.
-
-9.8.6. Example - COPY with Overwrite
-
- This example shows resource
- http://www.example.com/~fielding/index.html being copied to the
- location http://www.example.com/users/f/fielding/index.html. The 204
- (No Content) status code indicates the existing resource at the
- destination was overwritten.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 204 No Content
-
-9.8.7. Example - COPY with No Overwrite
-
- The following example shows the same copy operation being performed,
- but with the Overwrite header set to "F." A response of 412
- (Precondition Failed) is returned because the destination URL is
- already mapped to a resource.
-
- >>Request
-
- COPY /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/users/f/fielding/index.html
- Overwrite: F
-
- >>Response
-
- HTTP/1.1 412 Precondition Failed
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 59]
-
-Internet-Draft WebDAV April 2006
-
-
-9.8.8. Example - COPY of a Collection
-
- >>Request
-
- COPY /container/ HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/othercontainer/
- Depth: infinity
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
-
- <d:multistatus xmlns:d="DAV:">
- <d:response>
- <d:href>http://www.example.com/othercontainer/R2/</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
- The Depth header is unnecessary as the default behavior of COPY on a
- collection is to act as if a "Depth: infinity" header had been
- submitted. In this example most of the resources, along with the
- collection, were copied successfully. However the collection R2
- failed because the destination R2 is locked. Because there was an
- error copying R2, none of R2's members were copied. However no
- errors were listed for those members due to the error minimization
- rules.
-
-9.9. MOVE Method
-
- The MOVE operation on a non-collection resource is the logical
- equivalent of a copy (COPY), followed by consistency maintenance
- processing, followed by a delete of the source, where all three
- actions are performed in a single operation. The consistency
- maintenance step allows the server to perform updates caused by the
- move, such as updating all URLs other than the Request-URI which
- identify the source resource, to point to the new destination
- resource.
-
- The Destination header MUST be present on all MOVE methods and MUST
- follow all COPY requirements for the COPY part of the MOVE method.
- All WebDAV compliant resources MUST support the MOVE method.
-
-
-
-Dusseault Expires October 3, 2006 [Page 60]
-
-Internet-Draft WebDAV April 2006
-
-
- Support for the MOVE method does not guarantee the ability to move a
- resource to a particular destination. For example, separate programs
- may actually control different sets of resources on the same server.
- Therefore, it may not be possible to move a resource within a
- namespace that appears to belong to the same server.
-
- If a resource exists at the destination, the destination resource
- will be deleted as a side-effect of the MOVE operation, subject to
- the restrictions of the Overwrite header.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.9.1. MOVE for Properties
-
- Live properties described in this document SHOULD be moved along with
- the resource, such that the resource has identically behaving live
- properties at the destination resource, but not necessarily with the
- same values. Note that some live properties are defined such that
- the absence of the property has a specific meaning (e.g. a flag with
- one meaning if present and the opposite if absent), and in these
- cases, a successful MOVE might result in the property being reported
- as "Not Found" in subsequent requests. If the live properties will
- not work the same way at the destination, the server MAY fail the
- request.
-
- MOVE is frequently used by clients to rename a file without changing
- its parent collection, so it's not appropriate to reset all live
- properties which are set at resource creation. For example, the DAV:
- creationdate property value SHOULD remain the same after a MOVE.
-
- Dead properties MUST be moved along with the resource.
-
-9.9.2. MOVE for Collections
-
- A MOVE with "Depth: infinity" instructs that the collection
- identified by the Request-URI be moved to the address specified in
- the Destination header, and all resources identified by its internal
- member URLs are to be moved to locations relative to it, recursively
- through all levels of the collection hierarchy.
-
- The MOVE method on a collection MUST act as if a "Depth: infinity"
- header was used on it. A client MUST NOT submit a Depth header on a
- MOVE on a collection with any value but "infinity".
-
- Any headers included with MOVE MUST be applied in processing every
- resource to be moved with the exception of the Destination header.
- The behavior of the Destination header is the same as given for COPY
-
-
-
-Dusseault Expires October 3, 2006 [Page 61]
-
-Internet-Draft WebDAV April 2006
-
-
- on collections.
-
- When the MOVE method has completed processing it MUST have created a
- consistent URL namespace at both the source and destination (see
- section 5.1 for the definition of namespace consistency). However,
- if an error occurs while moving an internal collection, the server
- MUST NOT move any resources identified by members of the failed
- collection (i.e., the server must skip the error-causing subtree), as
- this would create an inconsistent namespace. In this case, after
- detecting the error, the move operation SHOULD try to finish as much
- of the original move as possible (i.e., the server should still
- attempt to move other subtrees and the resources identified by their
- members, that are not descendents of an error-causing collection).
- So, for example, if an infinite depth move is performed on collection
- /a/, which contains collections /a/b/ and /a/c/, and an error occurs
- moving /a/b/, an attempt should still be made to try moving /a/c/.
- Similarly, after encountering an error moving a non-collection
- resource as part of an infinite depth move, the server SHOULD try to
- finish as much of the original move operation as possible.
-
- If an error occurs with a resource other than the resource identified
- in the Request-URI then the response MUST be a 207 (Multi-Status),
- and the errored resource's URL MUST appear with the specific error.
-
- The 424 (Failed Dependency) status code SHOULD NOT be returned in the
- 207 (Multi-Status) response from a MOVE method. These errors can be
- safely omitted because the client will know that the progeny of a
- resource could not be moved when the client receives an error for the
- parent. Additionally 201 (Created)/204 (No Content) responses SHOULD
- NOT be returned as values in 207 (Multi-Status) responses from a
- MOVE. These responses can be safely omitted because they are the
- default success codes.
-
-9.9.3. MOVE and the Overwrite Header
-
- If a resource exists at the destination and the Overwrite header is
- "T" then prior to performing the move the server MUST perform a
- DELETE with "Depth: infinity" on the destination resource. If the
- Overwrite header is set to "F" then the operation will fail.
-
-9.9.4. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to MOVE:
-
- 201 (Created) - The source resource was successfully moved, and a new
- URL mapping was created at the destination.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 62]
-
-Internet-Draft WebDAV April 2006
-
-
- 204 (No Content) - The source resource was successfully moved to a
- URL that was already mapped.
-
- 207 (Multi-Status) - Multiple resources were to be affected by the
- MOVE, but errors on some of them prevented the operation from taking
- place. Specific error messages, together with the most appropriate
- of the source and destination URLs, appear in the body of the multi-
- status response. E.g. if a source resource was locked and could not
- be moved, then the source resource URL appears with the 423 (Locked)
- status.
-
- 403 (Forbidden) - Among many possible reasons for forbidding a MOVE
- operation, this status code is recommended for use when the source
- and destination resources are the same.
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
- Or, the server was unable to preserve the behavior of the live
- properties and still move the resource to the destination (see
- 'preserved-live-properties' postcondition).
-
- 412 (Precondition Failed) - A condition header failed. Specific to
- MOVE, this could mean that the Overwrite header is "F" and the
- destination URL is already mapped to a resource.
-
- 423 (Locked) - The source or the destination resource, the source or
- destination resource parent, or some resource within the source or
- destination collection, was locked. This response SHOULD contain the
- 'lock-token-submitted' precondition element.
-
- 502 (Bad Gateway) - This may occur when the destination is on another
- server and the destination server refuses to accept the resource.
- This could also occur when the destination is on another sub-section
- of the same server namespace.
-
-9.9.5. Example - MOVE of a Non-Collection
-
- This example shows resource
- http://www.example.com/~fielding/index.html being moved to the
- location http://www.example.com/users/f/fielding/index.html. The
- contents of the destination resource would have been overwritten if
- the destination URL was already mapped to a resource. In this case,
- since there was nothing at the destination resource, the response
- code is 201 (Created).
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 63]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Request
-
- MOVE /~fielding/index.html HTTP/1.1
- Host: www.example.com
- Destination: http://www.example/users/f/fielding/index.html
-
- >>Response
-
- HTTP/1.1 201 Created
- Location: http://www.example.com/users/f/fielding/index.html
-
-9.9.6. Example - MOVE of a Collection
-
- >>Request
-
- MOVE /container/ HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/othercontainer/
- Overwrite: F
- If: (<urn:uuid:fe184f2e-6eec-41d0-c765-01adc56e6bb4>)
- (<urn:uuid:e454f3f3-acdc-452a-56c7-00a5c91e4b77>)
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <d:multistatus xmlns:d='DAV:'>
- <d:response>
- <d:href>http://www.example.com/othercontainer/C2/</d:href>
- <d:status>HTTP/1.1 423 Locked</d:status>
- <d:error><d:lock-token-submitted/></d:error>
- </d:response>
- </d:multistatus>
-
- In this example the client has submitted a number of lock tokens with
- the request. A lock token will need to be submitted for every
- resource, both source and destination, anywhere in the scope of the
- method, that is locked. In this case the proper lock token was not
- submitted for the destination
- http://www.example.com/othercontainer/C2/. This means that the
- resource /container/C2/ could not be moved. Because there was an
- error moving /container/C2/, none of /container/C2's members were
- moved. However no errors were listed for those members due to the
- error minimization rules. User agent authentication has previously
- occurred via a mechanism outside the scope of the HTTP protocol, in
-
-
-
-Dusseault Expires October 3, 2006 [Page 64]
-
-Internet-Draft WebDAV April 2006
-
-
- an underlying transport layer.
-
-9.10. LOCK Method
-
- The following sections describe the LOCK method, which is used to
- take out a lock of any access type and to refresh an existing lock.
- These sections on the LOCK method describe only those semantics that
- are specific to the LOCK method and are independent of the access
- type of the lock being requested.
-
- Any resource which supports the LOCK method MUST, at minimum, support
- the XML request and response formats defined herein.
-
- This method is neither idempotent nor safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.10.1. Creating a lock on existing resource
-
- A LOCK request to an existing resource will create a lock on the
- resource identified by the Request-URI, provided the resource is not
- already locked with a conflicting lock. The resource identified in
- the Request-URI becomes the root of the lock. Lock method requests
- to create a new lock MUST have an XML request body. The server MUST
- preserve the information provided by the client in the 'owner' field
- in the request body when the lock information is requested. The LOCK
- request MAY have a Timeout header.
-
- When a new lock is created, the LOCK response:
-
- o MUST contain a body with the value of the DAV:lockdiscovery
- property in a prop XML element. This MUST contain the full
- information about the lock just granted, while information about
- other (shared) locks is OPTIONAL.
-
- o MUST include the Lock-Token response header with the token
- associated with the new lock.
-
-9.10.2. Refreshing Locks
-
- A lock is refreshed by sending a LOCK request to the URL of a
- resource within the scope of the lock. This request MUST NOT have a
- body and it MUST specify which lock to refresh by using the 'If'
- header with a single lock token (only one lock may be refreshed at a
- time). The request MAY contain a Timeout header, which a server MAY
- accept to change the duration remaining on the lock to the new value.
- A server MUST ignore the Depth header on a LOCK refresh.
-
- If the resource has other (shared) locks, those locks are unaffected
-
-
-
-Dusseault Expires October 3, 2006 [Page 65]
-
-Internet-Draft WebDAV April 2006
-
-
- by a lock refresh. Additionally, those locks do not prevent the
- named lock from being refreshed.
-
- The Lock-Token header is not returned in the response for a
- successful refresh LOCK request, but the LOCK response body MUST
- contain the new value for the DAV:lockdiscovery body.
-
-9.10.3. Depth and Locking
-
- The Depth header may be used with the LOCK method. Values other than
- 0 or infinity MUST NOT be used with the Depth header on a LOCK
- method. All resources that support the LOCK method MUST support the
- Depth header.
-
- A Depth header of value 0 means to just lock the resource specified
- by the Request-URI.
-
- If the Depth header is set to infinity then the resource specified in
- the Request-URI along with all its members, all the way down the
- hierarchy, are to be locked. A successful result MUST return a
- single lock token. Similarly, if an UNLOCK is successfully executed
- on this token, all associated resources are unlocked. Hence, partial
- success is not an option for LOCK or UNLOCK. Either the entire
- hierarchy is locked or no resources are locked.
-
- If the lock cannot be granted to all resources, the server MUST
- return a Multi-Status response with a 'response' element for at least
- one resource which prevented the lock from being granted, along with
- a suitable status code for that failure (e.g. 403 (Forbidden) or 423
- (Locked)). Additionally, if the resource causing the failure was not
- the resource requested, then the server SHOULD include a 'response'
- element for the Request-URI as well, with a 'status' element
- containing 424 Failed Dependency.
-
- If no Depth header is submitted on a LOCK request then the request
- MUST act as if a "Depth:infinity" had been submitted.
-
-9.10.4. Locking Unmapped URLs
-
- A successful LOCK method MUST result in the creation of an empty
- resource which is locked (and which is not a collection), when a
- resource did not previously exist at that URL. Later on, the lock
- may go away but the empty resource remains. Empty resources MUST
- then appear in PROPFIND responses including that URL in the response
- scope. A server MUST respond successfully to a GET request to an
- empty resource, either by using a 204 No Content response, or by
- using 200 OK with a Content-Length header indicating zero length
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 66]
-
-Internet-Draft WebDAV April 2006
-
-
-9.10.5. Lock Compatibility Table
-
- The table below describes the behavior that occurs when a lock
- request is made on a resource.
-
- +--------------------------+----------------+-------------------+
- | Current State | Shared Lock OK | Exclusive Lock OK |
- +--------------------------+----------------+-------------------+
- | None | True | True |
- | | | |
- | Shared Lock | True | False |
- | | | |
- | Exclusive Lock | False | False* |
- +--------------------------+----------------+-------------------+
-
- Legend: True = lock may be granted. False = lock MUST NOT be
- granted. *=It is illegal for a principal to request the same lock
- twice.
-
- The current lock state of a resource is given in the leftmost column,
- and lock requests are listed in the first row. The intersection of a
- row and column gives the result of a lock request. For example, if a
- shared lock is held on a resource, and an exclusive lock is
- requested, the table entry is "false", indicating the lock must not
- be granted.
-
-9.10.6. LOCK Responses
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to LOCK:
-
- 200 (OK) - The LOCK request succeeded and the value of the DAV:
- lockdiscovery property is included in the response body.
-
- 201 (Created) - The LOCK request was to an unmapped URL, the request
- succeeded and resulted in the creation of a new resource, and the
- value of the DAV:lockdiscovery property is included in the response
- body.
-
- 409 (Conflict) - A resource cannot be created at the destination
- until one or more intermediate collections have been created. The
- server MUST NOT create those intermediate collections automatically.
-
- 423 (Locked), potentially with 'no-conflicting-lock' precondition
- code - There is already a lock on the resource which is not
- compatible with the requested lock (see lock compatibility table
- above).
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 67]
-
-Internet-Draft WebDAV April 2006
-
-
- 412 (Precondition Failed), with 'lock-token-matches-request-uri'
- precondition code - The LOCK request was made with a If header,
- indicating that the client wishes to refresh the given lock.
- However, the Request-URI did not fall within the scope of the lock
- identified by the token. The lock may have a scope that does not
- include the Request-URI, or the lock could have disappeared, or the
- token may be invalid.
-
-9.10.7. Example - Simple Lock Request
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw at example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D='DAV:'>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 68]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 200 OK
- Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>infinity</D:depth>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href
- >http://example.com/workspace/webdav/proposal.doc</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
-
- This example shows the successful creation of an exclusive write lock
- on resource http://example.com/workspace/webdav/proposal.doc. The
- resource http://example.org/~ejw/contact.html contains contact
- information for the creator of the lock. The server has an activity-
- based timeout policy in place on this resource, which causes the lock
- to automatically be removed after 1 week (604800 seconds). Note that
- the nonce, response, and opaque fields have not been calculated in
- the Authorization request header.
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 69]
-
-Internet-Draft WebDAV April 2006
-
-
-9.10.8. Example - Refreshing a Write Lock
-
- >>Request
-
- LOCK /workspace/webdav/proposal.doc HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- Lock-Token: <urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4>
- Authorization: Digest username="ejw",
- realm="ejw at example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- >>Response
-
- HTTP/1.1 200 OK
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:prop xmlns:D="DAV:">
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>infinity</D:depth>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- <D:timeout>Second-604800</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:e71d4fae-5dec-22d6-fea5-00a0c91e6be4</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href
- >http://example.com/workspace/webdav/proposal.doc</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
-
-
- This request would refresh the lock, attempting to reset the timeout
- to the new value specified in the timeout header. Notice that the
- client asked for an infinite time out but the server choose to ignore
- the request. In this example, the nonce, response, and opaque fields
- have not been calculated in the Authorization request header.
-
-
-
-Dusseault Expires October 3, 2006 [Page 70]
-
-Internet-Draft WebDAV April 2006
-
-
-9.10.9. Example - Multi-Resource Lock Request
-
- >>Request
-
- LOCK /webdav/ HTTP/1.1
- Host: example.com
- Timeout: Infinite, Second-4100000000
- Depth: infinity
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="ejw at example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:lockinfo xmlns:D="DAV:">
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:owner>
- <D:href>http://example.org/~ejw/contact.html</D:href>
- </D:owner>
- </D:lockinfo>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://example.com/webdav/secret</D:href>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- </D:response>
- <D:response>
- <D:href>http://example.com/webdav/</D:href>
- <D:status>HTTP/1.1 424 Failed Dependency</D:status>
- </D:response>
- </D:multistatus>
-
-
- This example shows a request for an exclusive write lock on a
- collection and all its children. In this request, the client has
- specified that it desires an infinite length lock, if available,
- otherwise a timeout of 4.1 billion seconds, if available. The
- request entity body contains the contact information for the
-
-
-
-Dusseault Expires October 3, 2006 [Page 71]
-
-Internet-Draft WebDAV April 2006
-
-
- principal taking out the lock, in this case a web page URL.
-
- The error is a 403 (Forbidden) response on the resource
- http://example.com/webdav/secret. Because this resource could not be
- locked, none of the resources were locked. Note also that the a
- 'response' element for the Request-URI itself has been included as
- required.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-9.11. UNLOCK Method
-
- The UNLOCK method removes the lock identified by the lock token in
- the Lock-Token request header. The Request-URI MUST identify a
- resource within the scope of the lock.
-
- Note that use of Lock-Token header to provide the lock token is not
- consistent with other state-changing methods which all require an If
- header with the lock token. Thus, the If header is not needed to
- provide the lock token. Naturally when the If header is present it
- has its normal meaning as a conditional header.
-
- For a successful response to this method, the server MUST delete the
- lock entirely.
-
- If all resources which have been locked under the submitted lock
- token can not be unlocked then the UNLOCK request MUST fail.
-
- A successful response to an UNLOCK method does not mean that the
- resource is necessarily unlocked. It means that the specific lock
- corresponding to the specified token no longer exists.
-
- Any DAV compliant resource which supports the LOCK method MUST
- support the UNLOCK method.
-
- This method is idempotent, but not safe (see Section 9.1 of
- [RFC2616]). Responses to this method MUST NOT be cached.
-
-9.11.1. Status Codes
-
- In addition to the general status codes possible, the following
- status codes have specific applicability to UNLOCK:
-
- 204 (No Content) - Normal success response (rather than 200 OK, since
- 200 OK would imply a response body, and an UNLOCK success response
- does not normally contain a body)
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 72]
-
-Internet-Draft WebDAV April 2006
-
-
- 400 (Bad Request) - No lock token was provided.
-
- 403 (Forbidden) - The currently authenticated principal does not have
- permission to remove the lock.
-
- 409 (Conflict), with 'lock-token-matches-request-uri' precondition -
- The resource was not locked, or the request was made to a Request-URI
- that was not within the scope of the lock.
-
-9.11.2. Example - UNLOCK
-
- >>Request
-
- UNLOCK /workspace/webdav/info.doc HTTP/1.1
- Host: example.com
- Lock-Token: <urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7>
- Authorization: Digest username="ejw"
- realm="ejw at example.com", nonce="...",
- uri="/workspace/webdav/proposal.doc",
- response="...", opaque="..."
-
- >>Response
-
- HTTP/1.1 204 No Content
-
- In this example, the lock identified by the lock token
- "urn:uuid:a515cfa4-5da4-22e1-f5b5-00a0451e6bf7" is successfully
- removed from the resource
- http://example.com/workspace/webdav/info.doc. If this lock included
- more than just one resource, the lock is removed from all resources
- included in the lock.
-
- In this example, the nonce, response, and opaque fields have not been
- calculated in the Authorization request header.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 73]
-
-Internet-Draft WebDAV April 2006
-
-
-10. HTTP Headers for Distributed Authoring
-
- All DAV headers follow the same basic formatting rules as HTTP
- headers. This includes rules like line continuation and how to
- combine (or separate) multiple instances of the same header using
- commas.
-
- WebDAV adds two new conditional headers to the set defined in HTTP:
- the If and Overwrite headers.
-
-10.1. DAV Header
-
- DAV = "DAV" ":" #( compliance-class )
- compliance-class = ( "1" | "2" | "3" | extend )
- extend = Coded-URL | token
- Coded-URL = "<" absolute-URI ">"
- ; No LWS allowed in Coded-URL
- ; absolute-URI is defined in RFC3986
-
- This general-header appearing in the response indicates that the
- resource supports the DAV schema and protocol as specified. All DAV
- compliant resources MUST return the DAV header with compliance-class
- "1" on all OPTIONS responses. In cases where WebDAV is only
- supported in part of the server namespace, an OPTIONS request to non-
- WebDAV resources (including "/") SHOULD NOT advertise WebDAV support.
-
- The value is a comma-separated list of all compliance class
- identifiers that the resource supports. Class identifiers may be
- Coded-URLs or tokens (as defined by [RFC2616]). Identifiers can
- appear in any order. Identifiers that are standardized through the
- IETF RFC process are tokens, but other identifiers SHOULD be Coded-
- URLs to encourage uniqueness.
-
- A resource must show class 1 compliance if it shows class 2 or 3
- compliance. In general, support for one compliance class does not
- entail support for any other, and in particular, support for
- compliance class 3 does not require support for compliance class 2.
- Please refer to Section 18 for more details on compliance classes
- defined in this specification.
-
- Note that many WebDAV servers do not advertise WebDAV support in
- response to "OPTIONS *".
-
- As a request header, this header allows the client to advertise
- compliance with named features when the server needs that
- information. Clients SHOULD NOT send this header unless a standards
- track specification requires it. Any extension that makes use of
- this as a request header will need to carefully consider caching
-
-
-
-Dusseault Expires October 3, 2006 [Page 74]
-
-Internet-Draft WebDAV April 2006
-
-
- implications.
-
-10.2. Depth Header
-
- Depth = "Depth" ":" ("0" | "1" | "infinity")
-
- The Depth request header is used with methods executed on resources
- which could potentially have internal members to indicate whether the
- method is to be applied only to the resource ("Depth: 0"), to the
- resource and its internal members only, ("Depth: 1"), or the resource
- and all its members ("Depth: infinity").
-
- The Depth header is only supported if a method's definition
- explicitly provides for such support.
-
- The following rules are the default behavior for any method that
- supports the Depth header. A method may override these defaults by
- defining different behavior in its definition.
-
- Methods which support the Depth header may choose not to support all
- of the header's values and may define, on a case by case basis, the
- behavior of the method if a Depth header is not present. For
- example, the MOVE method only supports "Depth: infinity" and if a
- Depth header is not present will act as if a "Depth: infinity" header
- had been applied.
-
- Clients MUST NOT rely upon methods executing on members of their
- hierarchies in any particular order or on the execution being atomic
- unless the particular method explicitly provides such guarantees.
-
- Upon execution, a method with a Depth header will perform as much of
- its assigned task as possible and then return a response specifying
- what it was able to accomplish and what it failed to do.
-
- So, for example, an attempt to COPY a hierarchy may result in some of
- the members being copied and some not.
-
- By default, the Depth header does not interact with other headers.
- That is, each header on a request with a Depth header MUST be applied
- only to the Request-URI if it applies to any resource, unless
- specific Depth behavior is defined for that header.
-
- If a resource, source or destination, within the scope of the method
- with a Depth header is locked in such a way as to prevent the
- successful execution of the method, then the lock token for that
- resource MUST be submitted with the request in the If request header.
-
- The Depth header only specifies the behavior of the method with
-
-
-
-Dusseault Expires October 3, 2006 [Page 75]
-
-Internet-Draft WebDAV April 2006
-
-
- regards to internal members. If a resource does not have internal
- members then the Depth header MUST be ignored.
-
-10.3. Destination Header
-
- The Destination request header specifies the URI which identifies a
- destination resource for methods such as COPY and MOVE, which take
- two URIs as parameters.
-
- Destination = "Destination" ":" Simple-ref
-
- If the Destination value is an absolute-URI (Section 4.3 of
- [RFC3986]), it may name a different server (or different port or
- scheme). If the source server cannot attempt a copy to the remote
- server, it MUST fail the request. Note that copying and moving
- resources to remote servers is not fully defined in this
- specification (e.g. specific error conditions).
-
- If the Destination value is too long or otherwise unacceptable, the
- server SHOULD return 400 (Bad Request), ideally with helpful
- information in an error body.
-
-10.4. If Header
-
- The If request header is intended to have similar functionality to
- the If-Match header defined in Section 14.24 of [RFC2616]. However
- the If header handles any state token as well as ETags. A typical
- example of a state token is a lock token, and lock tokens are the
- only state tokens defined in this specification.
-
-10.4.1. Purpose
-
- The If header has two distinct purposes:
-
- o The first purpose is to make a request conditional by supplying a
- series of state lists with conditions that match tokens and ETags
- to specific resource. If this header is evaluated and all state
- lists fail, then the request MUST fail with a 412 (Precondition
- Failed) status. On the other hand, the request can succeed only
- if one of the described state lists succeeds. The success
- criteria for state lists and matching functions are defined in
- Section 10.4.3 and Section 10.4.4.
-
- o Additionally, the mere fact that a state token appears in an If
- header means that it has been "submitted" with the request. In
- general, this is used to indicate that the client has knowledge of
- that state token. The semantics for submitting a state token
- depend on its type (for lock tokens, please refer to Section 6).
-
-
-
-Dusseault Expires October 3, 2006 [Page 76]
-
-Internet-Draft WebDAV April 2006
-
-
- Note that these two purposes need to be treated distinctly: a state
- token counts as being submitted independently of whether the server
- actually has evaluated the state list it appears in, and also
- independently of whether the condition it expressed was found to be
- true or not.
-
-10.4.2. Syntax
-
- If = "If" ":" ( 1*No-tag-list | 1*Tagged-list )
-
- No-tag-list = List
- Tagged-list = Resource-Tag 1*List
-
- List = "(" 1*Condition ")"
- Condition = ["Not"] (State-token | "[" entity-tag "]")
- ; entity-tag: see Section 3.11 of [RFC2616]
- ; No LWS allowed between "[", entity-tag and "]"
-
- State-token = Coded-URL
-
- Resource-Tag = "<" Simple-ref ">"
- ; Simple-ref: see Section 8.3
- ; No LWS allowed in Resource-Tag
-
- The syntax distinguishes between untagged lists ("No-tag-list") and
- tagged lists ("Tagged-list"). Untagged lists apply to the resource
- identified by the Request-URI, while tagged lists apply to the
- resource identified by the preceding Resource-Tag.
-
- A Resource-Tag applies to all subsequent Lists, up to the next
- Resource-Tag.
-
- Note that the two list types cannot be mixed within an If header.
- This is not a functional restriction because the No-tag-list syntax
- is just a shorthand notation for a Tagged-list production with a
- Resource-Tag referring to the Request-URI.
-
- Each List consists of one or more Conditions. Each Condition is
- defined in terms of an entity-tag or state-token, potentially negated
- by the prefix "Not".
-
- Note that the If header syntax does not allow multiple instances of
- If headers in a single request. However, the HTTP header syntax
- allows extending single header values across multiple lines, by
- inserting a line break followed by whitespace (see [RFC2616], Section
- 4.2).
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 77]
-
-Internet-Draft WebDAV April 2006
-
-
-10.4.3. List Evaluation
-
- A Condition that consists of a single entity-tag or state-token
- evaluates to true if the resource matches the described state (where
- the individual matching functions are defined below in
- Section 10.4.4). Prefixing it with "Not" reverses the result of the
- evaluation (thus, the "Not" applies only to the subsequent entity-tag
- or state-token).
-
- Each List production describes a series of conditions. The whole
- list evaluates to true if and only if each condition evaluates to
- true (that is, the list represents a logical conjunction of
- Conditions).
-
- Each No-tag-list and Tagged-list production may contain one or more
- Lists. They evaluate to true if and only if any of the contained
- lists evaluates to true (that is, if there's more than one List, that
- List sequence represents a logical disjunction of the Lists).
-
- Finally, the whole If header evaluates to true if and only if at
- least one of the No-tag-list or Tagged-list productions evaluates to
- true. If the header evaluates to false, the server MUST reject the
- request with a 412 (Precondition Failed) status. Otherwise,
- execution of the request can proceed as if the header wasn't present.
-
-10.4.4. Matching State Tokens and ETags
-
- When performing If header processing, the definition of a matching
- state token or entity tag is as follows:
-
- Identifying a resource: The resource is identified by the URI along
- with the token, in tagged list production, or by the Request-URI in
- untagged list production.
-
- Matching entity tag: Where the entity tag matches an entity tag
- associated with the identified resource. Servers MUST use either the
- weak or the strong comparison function defined in Section 13.3.3 of
- [RFC2616].
-
- Matching state token: Where there is an exact match between the state
- token in the If header and any state token on the identified
- resource. A lock state token is considered to match if the resource
- is anywhere in the scope of the lock.
-
- Handling unmapped URLs: for both ETags and state tokens, treat as if
- the URL identified a resource that exists but does not have the
- specified state.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 78]
-
-Internet-Draft WebDAV April 2006
-
-
-10.4.5. If Header and Non-DAV Aware Proxies
-
- Non-DAV aware proxies will not honor the If header, since they will
- not understand the If header, and HTTP requires non-understood
- headers to be ignored. When communicating with HTTP/1.1 proxies, the
- client MUST use the "Cache-Control: no-cache" request header so as to
- prevent the proxy from improperly trying to service the request from
- its cache. When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
- request header MUST be used for the same reason.
-
- As in general clients may not be able to reliably detect non-DAV
- aware intermediates, they are advised to always prevent caching using
- the request directives mentioned above.
-
-10.4.6. Example - No-tag Production
-
- If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- ["I am an ETag"])
- (["I am another ETag"])
-
- The previous header would require that the resource identified in the
- Request-URI be locked with the specified lock token and be in the
- state identified by the "I am an ETag" ETag or in the state
- identified by the second ETag "I am another ETag".
-
- To put the matter more plainly one can think of the previous If
- header as expressing the condition below:
-
- (
- is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
- matches-etag("I am an ETag")
- )
- OR
- (
- matches-etag("I am another ETag")
- )
-
-10.4.7. Example - using "Not" with No-tag Production
-
- If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)
-
- This If header requires that the resource must not be locked with a
- lock having the lock token
- urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
- lock with the lock token
- urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 79]
-
-Internet-Draft WebDAV April 2006
-
-
-10.4.8. Example - causing a Condition to always evaluate to True
-
- There may be cases where a client wishes to submit state tokens, but
- doesn't want the request to fail just because the state token isn't
- current anymore. One simple way to do this is to include a Condition
- that is known to always evaluate to true, such as in:
-
- If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
- (Not <DAV:no-lock>)
-
- "DAV:no-lock" is known to never represent a current lock token, as
- lock tokens are assigned by the server, following the uniqueness
- requirements described in Section 6.5, therefore in particular
- exclude URIs in the "DAV:" scheme. Thus, by applying "Not" to a
- known not to be current state token, the Condition always evaluates
- to true. Consequently, the whole If header will always evaluate to
- true, and the lock token
- urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be submitted in
- any case.
-
-10.4.9. Example - Tagged List If header in COPY
-
- >>Request
-
- COPY /resource1 HTTP/1.1
- Host: www.example.com
- Destination: /resource2
- If: </resource1>
- (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
- [W/"A weak ETag"]) (["strong ETag"])
-
- In this example http://www.example.com/resource1 is being copied to
- http://www.example.com/resource2. When the method is first applied
- to http://www.example.com/resource1, resource1 must be in the state
- specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
- weak ETag"]) (["strong ETag"])", that is, it either must be locked
- with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
- and have a weak entity tag W/"A weak ETag" or it must have a strong
- entity tag "strong ETag".
-
-10.4.10. Example - Matching lock tokens with collection locks
-
- DELETE /specs/rfc2518.txt HTTP/1.1
- Host: www.example.com
- If: <http://www.example.com/specs/>
- (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
-
- For this example, the lock token must be compared to the identified
-
-
-
-Dusseault Expires October 3, 2006 [Page 80]
-
-Internet-Draft WebDAV April 2006
-
-
- resource, which is the 'specs' collection identified by the URL in
- the tagged list production. If the 'specs' collection is not locked
- by a lock with the specified lock token, the request MUST fail.
- Otherwise, this request could succeed, because the If header
- evaluates to true, and because the lock token for the lock affecting
- the affected resource has been submitted.
-
-10.4.11. Example - Matching ETags on unmapped URLs
-
- Consider a collection "/specs" that does not contain the member
- "/specs/rfc2518.doc". In this case, the If header
-
- If: </specs/rfc2518.doc> (["4217"])
-
- will evaluate to false (the URI isn't mapped, thus the resource
- identified by the URI doesn't have an entity matching the ETag
- "4217").
-
- On the other hand, an If header of
-
- If: </specs/rfc2518.doc> (Not ["4217"])
-
- will consequently evaluate to true.
-
- Note that as defined above in Section 10.4.4, the same considerations
- apply to matching state tokens.
-
-10.5. Lock-Token Header
-
- Lock-Token = "Lock-Token" ":" Coded-URL
-
- The Lock-Token request header is used with the UNLOCK method to
- identify the lock to be removed. The lock token in the Lock-Token
- request header MUST identify a lock that contains the resource
- identified by Request-URI as a member.
-
- The Lock-Token response header is used with the LOCK method to
- indicate the lock token created as a result of a successful LOCK
- request to create a new lock.
-
-10.6. Overwrite Header
-
- Overwrite = "Overwrite" ":" ("T" | "F")
-
- The Overwrite request header specifies whether the server should
- overwrite a resource mapped to the destination URL during a COPY or
- MOVE. A value of "F" states that the server must not perform the
- COPY or MOVE operation if the destination URL does map to a resource.
-
-
-
-Dusseault Expires October 3, 2006 [Page 81]
-
-Internet-Draft WebDAV April 2006
-
-
- If the overwrite header is not included in a COPY or MOVE request
- then the resource MUST treat the request as if it has an overwrite
- header of value "T". While the Overwrite header appears to duplicate
- the functionality of the If-Match: * header of HTTP/1.1, If-Match
- applies only to the Request-URI, and not to the Destination of a COPY
- or MOVE.
-
- If a COPY or MOVE is not performed due to the value of the Overwrite
- header, the method MUST fail with a 412 (Precondition Failed) status
- code. The server MUST do authorization checks before checking this
- or any conditional header.
-
- All DAV compliant resources MUST support the Overwrite header.
-
-10.7. Timeout Request Header
-
- TimeOut = "Timeout" ":" 1#TimeType
- TimeType = ("Second-" DAVTimeOutVal | "Infinite")
- ; No LWS allowed within TimeType
- DAVTimeOutVal = 1*DIGIT
-
- Clients MAY include Timeout request headers in their LOCK requests.
- However, the server is not required to honor or even consider these
- requests. Clients MUST NOT submit a Timeout request header with any
- method other than a LOCK method.
-
- The "Second" TimeType specifies the number of seconds that will
- elapse between granting of the lock at the server, and the automatic
- removal of the lock. The timeout value for TimeType "Second" MUST
- NOT be greater than 2^32-1.
-
- See Section 6.6 for a description of lock timeout behavior.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 82]
-
-Internet-Draft WebDAV April 2006
-
-
-11. Status Code Extensions to HTTP/1.1
-
- The following status codes are added to those defined in HTTP/1.1
- [RFC2616].
-
-11.1. 207 Multi-Status
-
- The 207 (Multi-Status) status code provides status for multiple
- independent operations (see Section 13 for more information).
-
-11.2. 422 Unprocessable Entity
-
- The 422 (Unprocessable Entity) status code means the server
- understands the content type of the request entity (hence a
- 415(Unsupported Media Type) status code is inappropriate), and the
- syntax of the request entity is correct (thus a 400 (Bad Request)
- status code is inappropriate) but was unable to process the contained
- instructions. For example, this error condition may occur if an XML
- request body contains well-formed (i.e., syntactically correct), but
- semantically erroneous XML instructions.
-
-11.3. 423 Locked
-
- The 423 (Locked) status code means the source or destination resource
- of a method is locked. This response SHOULD contain an appropriate
- precondition or postcondition code, such as 'lock-token-submitted' or
- 'no-conflicting-lock".
-
-11.4. 424 Failed Dependency
-
- The 424 (Failed Dependency) status code means that the method could
- not be performed on the resource because the requested action
- depended on another action and that action failed. For example, if a
- command in a PROPPATCH method fails then, at minimum, the rest of the
- commands will also fail with 424 (Failed Dependency).
-
-11.5. 507 Insufficient Storage
-
- The 507 (Insufficient Storage) status code means the method could not
- be performed on the resource because the server is unable to store
- the representation needed to successfully complete the request. This
- condition is considered to be temporary. If the request which
- received this status code was the result of a user action, the
- request MUST NOT be repeated until it is requested by a separate user
- action.
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 83]
-
-Internet-Draft WebDAV April 2006
-
-
-12. Use of HTTP Status Codes
-
- These HTTP codes are not redefined, but their use is somewhat
- extended by WebDAV methods and requirements. In general, many HTTP
- status codes can be used in response to any request, not just in
- cases described in this document. Note also that WebDAV servers are
- known to use 300-level redirect responses (and early interoperability
- tests found clients unprepared to see those responses). A 300-level
- response MUST NOT be used when the server has created a new resource
- in response to the request.
-
-12.1. 412 Precondition Failed
-
- Any request can contain a conditional header defined in HTTP (If-
- Match, If-Modified-Since, etc.) or the "If" or "Overwrite"
- conditional headers defined in this specification. If the server
- evaluates a conditional header, and if that condition fails to hold,
- then this error code MUST be returned. On the other hand, if the
- client did not include a conditional header in the request, then the
- server MUST NOT use this status code.
-
-12.2. 414 Request-URI Too Long
-
- This status code is used in HTTP 1.1 only for Request-URIs, not URIs
- in other locations.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 84]
-
-Internet-Draft WebDAV April 2006
-
-
-13. Multi-Status Response
-
- A Multi-Status response conveys information about multiple resources
- in situations where multiple status codes might be appropriate. The
- default Multi-Status response body is a text/xml or application/xml
- HTTP entity with a 'multistatus' root element. Further elements
- contain 200, 300, 400, and 500 series status codes generated during
- the method invocation. 100 series status codes SHOULD NOT be recorded
- in a 'response' XML element.
-
- Although '207' is used as the overall response status code, the
- recipient needs to consult the contents of the multistatus response
- body for further information about the success or failure of the
- method execution. The response MAY be used in success, partial
- success and also in failure situations.
-
- The 'multistatus' root element holds zero or more 'response' elements
- in any order, each with information about an individual resource.
- Each 'response' element MUST have an 'href' element to identify the
- resource.
-
- A Multi-Status response uses one out of two distinct formats for
- representing the status:
-
- 1. A 'status' element as child of the 'response' element indicates
- the status of the message excecution for the identified resource
- as a whole (for instance, see Section 9.6.2). Some method
- definitions provide information about specific status codes
- clients should be prepared to see in a response. However,
- clients MUST be able to handle other status codes, using the
- generic rules defined in Section 10 of [RFC2616].
-
- 2. For PROPFIND and PROPPATCH, the format has been extended using
- the 'propstat' element instead of 'status', providing information
- about individual properties of a resource. This format is
- specific to PROPFIND and PROPPATCH, and is described in detail in
- Section 9.1 and Section 9.2.
-
-13.1. Response headers
-
- HTTP defines the Location header to indicate a preferred URL for the
- resource that was addressed in the Request-URI (e.g. in response to
- successful PUT requests or in redirect responses). However, use of
- this header creates ambiguity when there are URLs in the body of the
- response, as with Multi-Status. Thus, use of the Location header
- with the Multi-Status response is intentionally undefined.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 85]
-
-Internet-Draft WebDAV April 2006
-
-
-13.2. Handling redirected child resources
-
- Redirect responses (300-303, 305 and 307) defined in HTTP 1.1
- normally take a Location header to indicate the new URI for the
- single resource redirected from the Request-URI. Multi-Status
- responses contain many resource addresses, but the original
- definition in [RFC2518] did not have any place for the server to
- provide the new URI for redirected resources. This specification
- does define a 'location' element for this information (see
- Section 14.9). Servers MUST use this new element with redirect
- responses in Multi-Status.
-
- Clients encountering redirected resources in Multi-Status MUST NOT
- rely on the 'location' element being present with a new URI. If the
- element is not present, the client MAY reissue the request to the
- individual redirected resource, because the response to that request
- can be redirected with a Location header containing the new URI.
-
-13.3. Internal Status Codes
-
- Section 9.2.1, Section 9.1.2, Section 9.6.1, Section 9.8.3 and
- Section 9.9.2 define various status codes used in Multi-Status
- responses. This specification does not define the meaning of other
- status codes that could appear in these responses.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 86]
-
-Internet-Draft WebDAV April 2006
-
-
-14. XML Element Definitions
-
- In this section, the final line of each section gives the element
- type declaration using the format defined in [REC-XML]. The "Value"
- field, where present, specifies further restrictions on the allowable
- contents of the XML element using BNF (i.e., to further restrict the
- values of a PCDATA element). Note that all of the elements defined
- here may be extended according to the rules defined in Section 17.
- All elements defined here are in the "DAV:" namespace.
-
-14.1. activelock XML Element
-
- Name: activelock
-
- Purpose: Describes a lock on a resource.
-
-
- <!ELEMENT activelock (lockscope, locktype, depth, owner?, timeout?,
- locktoken?, lockroot)>
-
-14.2. allprop XML Element
-
- Name: allprop
-
- Purpose: Specifies that all names and values of dead properties and
- the live properties defined by this document existing on the
- resource are to be returned.
-
- <!ELEMENT allprop EMPTY >
-
-14.3. collection XML Element
-
- Name: collection
-
- Purpose: Identifies the associated resource as a collection. The
- DAV:resourcetype property of a collection resource MUST contain
- this element. It is normally empty but extensions may add sub-
- elements.
-
- <!ELEMENT collection EMPTY >
-
-14.4. depth XML Element
-
- Name: depth
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 87]
-
-Internet-Draft WebDAV April 2006
-
-
- Purpose: The value of the Depth header.
-
- Value: "0" | "1" | "infinity"
-
- <!ELEMENT depth (#PCDATA) >
-
-14.5. error XML Element
-
- Name: error
-
- Purpose: Error responses, particularly 403 Forbidden and 409
- Conflict, sometimes need more information to indicate what went
- wrong. When an error response contains a body in WebDAV, the body
- is in XML with the root element 'error'. The 'error' element
- SHOULD include a failed precondition or postcondition element.
-
- Description: Contains at least one XML element, and MUST NOT contain
- text or mixed content. Any element that is a child of the 'error'
- element is considered to be a precondition or postcondition code.
- Unrecognized elements SHOULD be ignored.
-
- <!ELEMENT error ANY >
-
-14.6. exclusive XML Element
-
- Name: exclusive
-
- Purpose: Specifies an exclusive lock.
-
-
- <!ELEMENT exclusive EMPTY >
-
-
-14.7. href XML Element
-
- Name: href
-
- Purpose: MUST contain a URI or a relative reference.
-
- Description: There may be limits on the value of 'href' depending on
- the context of its use. Refer to the specification text where
- 'href' is used to see what limitations apply in each case.
-
- Value: Simple-ref
-
-
- <!ELEMENT href (#PCDATA)>
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 88]
-
-Internet-Draft WebDAV April 2006
-
-
-14.8. include XML Element
-
- Name: include
-
- Purpose: Any child element represents the name of a property to be
- included in the PROPFIND response. All elements inside an
- 'include' XML element MUST define properties related to the
- resource, although possible property names are in no way limited
- to those property names defined in this document or other
- standards. This element MUST NOT contain text or mixed content.
-
- <!ELEMENT include ANY >
-
-14.9. location XML Element
-
- Name: location
-
- Purpose: HTTP defines the "Location" header (see [RFC2616], Section
- 14.30) for use with some status codes (such as 201 and the 300
- series codes). When these codes are used inside a 'multistatus'
- element, the 'location' element can be used to provide the
- accompanying Location header value.
-
- Description: Contains a single href element with the same value that
- would be used in a Location header.
-
-
- <!ELEMENT location (href)>
-
-14.10. lockentry XML Element
-
- Name: lockentry
-
- Purpose: Defines the types of locks that can be used with the
- resource.
-
- <!ELEMENT lockentry (lockscope, locktype) >
-
-14.11. lockinfo XML Element
-
- Name: lockinfo
-
- Purpose: The 'lockinfo' XML element is used with a LOCK method to
- specify the type of lock the client wishes to have created.
-
-
- <!ELEMENT lockinfo (lockscope, locktype, owner?) >
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 89]
-
-Internet-Draft WebDAV April 2006
-
-
-14.12. lockroot XML Element
-
- Name: lockroot
-
- Purpose: Contains the root URL of the lock, which is the URL through
- which the resource was addressed in the LOCK request.
-
- Description: The href element contains the root of the lock. The
- server SHOULD include this in all DAV:lockdiscovery property
- values and the response to LOCK requests.
-
- <!ELEMENT lockroot (href) >
-
-14.13. lockscope XML Element
-
- Name: lockscope
-
- Purpose: Specifies whether a lock is an exclusive lock, or a shared
- lock.
-
-
- <!ELEMENT lockscope (exclusive | shared) >
-
-
-14.14. locktoken XML Element
-
- Name: locktoken
-
- Purpose: The lock token associated with a lock.
-
- Description: The href contains a single lock token URI which refers
- to the lock.
-
- <!ELEMENT locktoken (href) >
-
-14.15. locktype XML Element
-
- Name: locktype
-
- Purpose: Specifies the access type of a lock. At present, this
- specification only defines one lock type, the write lock.
-
-
- <!ELEMENT locktype (write) >
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 90]
-
-Internet-Draft WebDAV April 2006
-
-
-14.16. multistatus XML Element
-
- Name: multistatus
-
- Purpose: Contains multiple response messages.
-
- Description: The 'responsedescription' element at the top level is
- used to provide a general message describing the overarching
- nature of the response. If this value is available an application
- may use it instead of presenting the individual response
- descriptions contained within the responses.
-
-
- <!ELEMENT multistatus (response*, responsedescription?) >
-
-
-14.17. owner XML Element
-
- Name: owner
-
- Purpose: Provides information about the creator of a lock.
-
- Description: Allows a client to provide information sufficient for
- either directly contacting a principal (such as a telephone number
- or Email URI), or for discovering the principal (such as the URL
- of a homepage) who created a lock. The value provided MUST be
- treated as a dead property in terms of XML Information Item
- preservation. The server MUST NOT alter the value unless the
- owner value provided by the client is empty. For a certain amount
- of interoperability between different client implementations, if
- clients have URI-formatted contact information for the lock
- creator suitable for user display, then clients SHOULD put those
- URIs in 'href' child elements of the 'owner' element.
-
- Extensibility: MAY be extended with child elements, mixed content,
- text content or attributes.
-
- <!ELEMENT owner ANY >
-
-14.18. prop XML element
-
- Name: prop
-
- Purpose: Contains properties related to a resource.
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 91]
-
-Internet-Draft WebDAV April 2006
-
-
- Description: A generic container for properties defined on
- resources. All elements inside a 'prop' XML element MUST define
- properties related to the resource, although possible property
- names are in no way limited to those property names defined in
- this document or other standards. This element MUST NOT contain
- text or mixed content.
-
- <!ELEMENT prop ANY >
-
-14.19. propertyupdate XML element
-
- Name: propertyupdate
-
- Purpose: Contains a request to alter the properties on a resource.
-
- Description: This XML element is a container for the information
- required to modify the properties on the resource.
-
- <!ELEMENT propertyupdate (remove | set)+ >
-
-14.20. propfind XML Element
-
- Name: propfind
-
- Purpose: Specifies the properties to be returned from a PROPFIND
- method. Four special elements are specified for use with
- 'propfind': 'prop', 'allprop', 'include' and 'propname'. If
- 'prop' is used inside 'propfind' it MUST NOT contain property
- values.
-
- <!ELEMENT propfind ( propname | (allprop, include?) | prop ) >
-
-14.21. propname XML Element
-
- Name: propname
-
- Purpose: Specifies that only a list of property names on the
- resource is to be returned.
-
- <!ELEMENT propname EMPTY >
-
-14.22. propstat XML Element
-
- Name: propstat
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 92]
-
-Internet-Draft WebDAV April 2006
-
-
- Purpose: Groups together a prop and status element that is
- associated with a particular 'href' element.
-
- Description: The propstat XML element MUST contain one prop XML
- element and one status XML element. The contents of the prop XML
- element MUST only list the names of properties to which the result
- in the status element applies. The optional precondition/
- postcondition element and 'responsedescription' text also apply to
- the properties named in 'prop'.
-
- <!ELEMENT propstat (prop, status, error?, responsedescription?) >
-
-14.23. remove XML element
-
- Name: remove
-
- Purpose: Lists the properties to be removed from a resource.
-
- Description: Remove instructs that the properties specified in prop
- should be removed. Specifying the removal of a property that does
- not exist is not an error. All the XML elements in a 'prop' XML
- element inside of a 'remove' XML element MUST be empty, as only
- the names of properties to be removed are required.
-
- <!ELEMENT remove (prop) >
-
-14.24. response XML Element
-
- Name: response
-
- Purpose: Holds a single response describing the effect of a method
- on resource and/or its properties.
-
- Description: The 'href' element contains a HTTP URL pointing to a
- WebDAV resource when used in the 'response' container. A
- particular 'href' value MUST NOT appear more than once as the
- child of a 'response' XML element under a 'multistatus' XML
- element. This requirement is necessary in order to keep
- processing costs for a response to linear time. Essentially, this
- prevents having to search in order to group together all the
- responses by 'href'. There are, however, no requirements
- regarding ordering based on 'href' values. The optional
- precondition/postcondition element and 'responsedescription' text
- can provide additional information about this resource relative to
- the request or result.
-
-
- <!ELEMENT response (href, ((href*, status)|(propstat+)),
-
-
-
-Dusseault Expires October 3, 2006 [Page 93]
-
-Internet-Draft WebDAV April 2006
-
-
- error?, responsedescription? , location?) >
-
-14.25. responsedescription XML Element
-
- Name: responsedescription
-
- Purpose: Contains information about a status response within a
- Multi-Status.
-
- Description: Provides information suitable to be presented to a
- user.
-
- <!ELEMENT responsedescription (#PCDATA) >
-
-14.26. set XML element
-
- Name: set
-
- Purpose: Lists the property values to be set for a resource.
-
- Description: The 'set' element MUST contain only a 'prop' element.
- The elements contained by the 'prop' element inside the 'set'
- element MUST specify the name and value of properties that are set
- on the resource identified by Request-URI. If a property already
- exists then its value is replaced. Language tagging information
- appearing in the scope of the 'prop' element (in the "xml:lang"
- attribute, if present) MUST be persistently stored along with the
- property, and MUST be subsequently retrievable using PROPFIND.
-
- <!ELEMENT set (prop) >
-
-14.27. shared XML Element
-
- Name: shared
-
- Purpose: Specifies a shared lock.
-
-
- <!ELEMENT shared EMPTY >
-
-
-14.28. status XML Element
-
- Name: status
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 94]
-
-Internet-Draft WebDAV April 2006
-
-
- Purpose: Holds a single HTTP status-line.
-
- Value: status-line (defined in Section 6.1 of [RFC2616])
-
- <!ELEMENT status (#PCDATA) >
-
-14.29. timeout XML Element
-
- Name: timeout
-
- Purpose: The number of seconds remaining before a lock expires.
-
- Value: TimeType (defined in Section 10.7).
-
-
- <!ELEMENT timeout (#PCDATA) >
-
-14.30. write XML Element
-
- Name: write
-
- Purpose: Specifies a write lock.
-
-
- <!ELEMENT write EMPTY >
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 95]
-
-Internet-Draft WebDAV April 2006
-
-
-15. DAV Properties
-
- For DAV properties, the name of the property is also the same as the
- name of the XML element that contains its value. In the section
- below, the final line of each section gives the element type
- declaration using the format defined in [REC-XML]. The "Value"
- field, where present, specifies further restrictions on the allowable
- contents of the XML element using BNF (i.e., to further restrict the
- values of a PCDATA element).
-
- A protected property is one which cannot be changed with a PROPPATCH
- request. There may be other requests which would result in a change
- to a protected property (as when a LOCK request affects the value of
- DAV:lockdiscovery). Note that a given property could be protected on
- one type of resource, but not protected on another type of resource.
-
- A computed property is one with a value defined in terms of a
- computation (based on the content and other properties of that
- resource, or even of some other resource). A computed property is
- always a protected property.
-
- COPY and MOVE behavior refers to local COPY and MOVE operations.
-
- For properties defined based on HTTP GET response headers (DAV:get*),
- the value could include LWS as defined in [RFC2616], Section 4.2.
- Server implementors SHOULD NOT include extra LWS in these values,
- however client implementors MUST be prepared to handle extra LWS.
-
-15.1. creationdate Property
-
- Name: creationdate
-
- Purpose: Records the time and date the resource was created.
-
- Value: date-time (defined in [RFC3339], see the ABNF in section
- 5.6.)
-
- Protected: MAY be protected. Some servers allow DAV:creationdate to
- be changed to reflect the time the document was created if that is
- more meaningful to the user (rather than the time it was
- uploaded). Thus, clients SHOULD NOT use this property in
- synchronization logic (use DAV:getetag instead).
-
- COPY/MOVE behaviour: This property value SHOULD be kept during a
- MOVE operation, but is normally re-initialized when a resource is
- created with a COPY. It should not be set in a COPY.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 96]
-
-Internet-Draft WebDAV April 2006
-
-
- Description: The DAV:creationdate property SHOULD be defined on all
- DAV compliant resources. If present, it contains a timestamp of
- the moment when the resource was created. Servers that are
- incapable of persistently recording the creation date SHOULD
- instead leave it undefined (i.e. report "Not Found").
-
- <!ELEMENT creationdate (#PCDATA) >
-
-15.2. displayname Property
-
- Name: displayname
-
- Purpose: Provides a name for the resource that is suitable for
- presentation to a user.
-
- Value: Any text.
-
- Protected: SHOULD NOT be protected. Note that servers implementing
- [RFC2518] might have made this a protected property as this is a
- new requirement.
-
- COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: Contains a description of the resource that is suitable
- for presentation to a user. This property is defined on the
- resource, and hence SHOULD have the same value independent of the
- Request-URI used to retrieve it (thus computing this property
- based on the Request-URI is deprecated). While generic clients
- might display the property value to end users, client UI designers
- must understand that the method for identifying resources is still
- the URL. Changes to DAV:displayname do not issue moves or copies
- to the server, but simply change a piece of meta-data on the
- individual resource. Two resources can have the same DAV:
- displayname value even within the same collection.
-
- <!ELEMENT displayname (#PCDATA) >
-
-15.3. getcontentlanguage Property
-
- Name: getcontentlanguage
-
- Purpose: Contains the Content-Language header value (from Section
- 14.12 of [RFC2616]) as it would be returned by a GET without
- accept headers.
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 97]
-
-Internet-Draft WebDAV April 2006
-
-
- Value: language-tag (language-tag is defined in Section 3.10 of
- [RFC2616]).
-
- Protected: SHOULD NOT be protected, so that clients can reset the
- language. Note that servers implementing [RFC2518] might have
- made this a protected property as this is a new requirement.
-
- COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: The DAV:getcontentlanguage property MUST be defined on
- any DAV compliant resource that returns the Content-Language
- header on a GET.
-
- <!ELEMENT getcontentlanguage (#PCDATA) >
-
-15.4. getcontentlength Property
-
- Name: getcontentlength
-
- Purpose: Contains the Content-Length header returned by a GET
- without accept headers.
-
- Value: See Section 14.13 of [RFC2616].
-
- Protected: This property is computed, therefore protected.
-
- Description: The DAV:getcontentlength property MUST be defined on
- any DAV compliant resource that returns the Content-Length header
- in response to a GET.
-
- COPY/MOVE behaviour: This property value is dependent on the size of
- the destination resource, not the value of the property on the
- source resource.
-
- <!ELEMENT getcontentlength (#PCDATA) >
-
-15.5. getcontenttype Property
-
- Name: getcontenttype
-
- Purpose: Contains the Content-Type header value (from Section 14.17
- of [RFC2616]) as it would be returned by a GET without accept
- headers.
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 98]
-
-Internet-Draft WebDAV April 2006
-
-
- Value: media-type (defined in Section 3.7 of [RFC2616])
-
- Protected: Potentially protected if the server prefers to assign
- content types on its own (see also discussion in Section 9.7.1).
-
- COPY/MOVE behaviour: This property value SHOULD be preserved in COPY
- and MOVE operations.
-
- Description: This property MUST be defined on any DAV compliant
- resource that returns the Content-Type header in response to a
- GET.
-
- <!ELEMENT getcontenttype (#PCDATA) >
-
-15.6. getetag Property
-
- Name: getetag
-
- Purpose: Contains the ETag header value (from Section 14.19 of
- [RFC2616]) as it would be returned by a GET without accept
- headers.
-
- Value: entity-tag (defined in Section 3.11 of [RFC2616])
-
- Protected: MUST be protected because this value is created and
- controlled by the server.
-
- COPY/MOVE behaviour: This property value is dependent on the final
- state of the destination resource, not the value of the property
- on the source resource. Also note the considerations in
- Section 8.8.
-
- Description: The getetag property MUST be defined on any DAV
- compliant resource that returns the Etag header. Refer to Section
- 3.11 of RFC2616 for a complete definition of the semantics of an
- ETag, and to Section 8.6 for a discussion of ETags in WebDAV.
-
- <!ELEMENT getetag (#PCDATA) >
-
-15.7. getlastmodified Property
-
- Name: getlastmodified
-
- Purpose: Contains the Last-Modified header value (from Section 14.29
- of [RFC2616]) as it would be returned by a GET method without
- accept headers.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 99]
-
-Internet-Draft WebDAV April 2006
-
-
- Value: rfc1123-date (defined in Section 3.3.1 of [RFC2616])
-
- Protected: SHOULD be protected because some clients may rely on the
- value for appropriate caching behavior, or on the value of the
- Last-Modified header to which this property is linked.
-
- COPY/MOVE behaviour: This property value is dependent on the last
- modified date of the destination resource, not the value of the
- property on the source resource. Note that some server
- implementations use the file system date modified value for the
- DAV:getlastmodified value, and this can be preserved in a MOVE
- even when the HTTP Last-Modified value SHOULD change. Note that
- since [RFC2616] requires clients to use ETags where provided, a
- server implementing ETags can count on clients using a much better
- mechanism than modification dates for offline synchronization or
- cache control. Also note the considerations in Section 8.8.
-
- Description: Note that the last-modified date on a resource SHOULD
- only reflect changes in the body (the GET responses) of the
- resource. A change in a property only SHOULD NOT cause the last-
- modified date to change, because clients MAY rely on the last-
- modified date to know when to overwrite the existing body. The
- DAV:getlastmodified property MUST be defined on any DAV compliant
- resource that returns the Last-Modified header in response to a
- GET.
-
- <!ELEMENT getlastmodified (#PCDATA) >
-
-15.8. lockdiscovery Property
-
- Name: lockdiscovery
-
- Purpose: Describes the active locks on a resource
-
- Protected: MUST be protected. Clients change the list of locks
- through LOCK and UNLOCK, not through PROPPATCH.
-
- COPY/MOVE behaviour: The value of this property depends on the lock
- state of the destination, not on the locks of the source resource.
- Recall that locks are not moved in a MOVE operation.
-
- Description: Returns a listing of who has a lock, what type of lock
- he has, the timeout type and the time remaining on the timeout,
- and the associated lock token. If there are no locks, but the
- server supports locks, the property will be present but contain
- zero 'activelock' elements. If there is one or more lock, an
- 'activelock' element appears for each lock on the resource. This
- property is NOT lockable with respect to write locks (Section 7).
-
-
-
-Dusseault Expires October 3, 2006 [Page 100]
-
-Internet-Draft WebDAV April 2006
-
-
- <!ELEMENT lockdiscovery (activelock)* >
-
-15.8.1. Example - Retrieving DAV:lockdiscovery
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Length: xxxx
- Content-Type: application/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D='DAV:'>
- <D:prop><D:lockdiscovery/></D:prop>
- </D:propfind>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 101]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D='DAV:'>
- <D:response>
- <D:href>http://www.example.com/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:lockdiscovery>
- <D:activelock>
- <D:locktype><D:write/></D:locktype>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:depth>0</D:depth>
- <D:owner>Jane Smith</D:owner>
- <D:timeout>Infinite</D:timeout>
- <D:locktoken>
- <D:href
- >urn:uuid:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href>
- </D:locktoken>
- <D:lockroot>
- <D:href>http://www.example.com/container/</D:href>
- </D:lockroot>
- </D:activelock>
- </D:lockdiscovery>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
- This resource has a single exclusive write lock on it, with an
- infinite timeout.
-
-15.9. resourcetype Property
-
- Name: resourcetype
-
- Purpose: Specifies the nature of the resource.
-
- Protected: SHOULD be protected. Resource type is generally decided
- through the operation creating the resource (MKCOL vs PUT), not by
- PROPPATCH.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 102]
-
-Internet-Draft WebDAV April 2006
-
-
- COPY/MOVE behaviour: Generally a COPY/MOVE of a resource results in
- the same type of resource at the destination.
-
- Description: MUST be defined on all DAV compliant resources. Each
- child element identifies a specific type the resource belongs to,
- such as 'collection', which is the only resource type defined by
- this specification (see Section 14.3). If the element contains
- the 'collection' child element plus additional unrecognized
- elements, it should generally be treated as a collection. If the
- element contains no recognized child elements, it should be
- treated as a non-collection resource. The default value is empty.
- This element MUST NOT contain text or mixed content. Any custom
- child element is considered to be an identifier for a resource
- type.
-
- Example: (fictional example to show extensibility)
-
- <x:resourcetype xmlns:x="DAV:">
- <x:collection/>
- <f:search-results xmlns:f="http://www.example.com/ns"/>
- </x:resourcetype>
-
-15.10. supportedlock Property
-
- Name: supportedlock
-
- Purpose: To provide a listing of the lock capabilities supported by
- the resource.
-
- Protected: MUST be protected. Servers determine what lock
- mechanisms are supported, not clients.
-
- COPY/MOVE behaviour: This property value is dependent on the kind of
- locks supported at the destination, not on the value of the
- property at the source resource. Servers attempting to COPY to a
- destination should not attempt to set this property at the
- destination.
-
- Description: Returns a listing of the combinations of scope and
- access types which may be specified in a lock request on the
- resource. Note that the actual contents are themselves controlled
- by access controls so a server is not required to provide
- information the client is not authorized to see. This property is
- NOT lockable with respect to write locks (Section 7).
-
- <!ELEMENT supportedlock (lockentry)* >
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 103]
-
-Internet-Draft WebDAV April 2006
-
-
-15.10.1. Example - Retrieving DAV:supportedlock
-
- >>Request
-
- PROPFIND /container/ HTTP/1.1
- Host: www.example.com
- Content-Length: xxxx
- Content-Type: application/xml; charset="utf-8"
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop><D:supportedlock/></D:prop>
- </D:propfind>
-
- >>Response
-
- HTTP/1.1 207 Multi-Status
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:supportedlock>
- <D:lockentry>
- <D:lockscope><D:exclusive/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- <D:lockentry>
- <D:lockscope><D:shared/></D:lockscope>
- <D:locktype><D:write/></D:locktype>
- </D:lockentry>
- </D:supportedlock>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 104]
-
-Internet-Draft WebDAV April 2006
-
-
-16. Precondition/postcondition XML elements
-
- As introduced in Section 8.7, extra information on error conditions
- can be included in the body of many status responses. This section
- makes requirements on the use of the error body mechanism and
- introduces a number of precondition and postcondition codes.
-
- A "precondition" of a method describes the state of the server that
- must be true for that method to be performed. A "postcondition" of a
- method describes the state of the server that must be true after that
- method has been completed.
-
- Each precondition and postcondition has a unique XML element
- associated with it. In a 207 Multi-Status response, the XML element
- MUST appear inside an 'error' element in the appropriate 'propstat or
- 'response' element depending on whether the condition applies to one
- or more properties or to the resource as a whole. In all other error
- responses, the XML element MUST be returned as the child of a top-
- level 'error' element in the response body, unless otherwise
- negotiated by the request, along with an appropriate response status.
- The most common response status codes are 403 (Forbidden) if the
- request should not be repeated because it will always fail, and 409
- (Conflict) if it is expected that the user might be able to resolve
- the conflict and resubmit the request. The 'error' element MAY
- contain child elements with specific error information and MAY be
- extended with any custom child elements.
-
- This mechanism does not take the place of using a correct numeric
- status code as defined here or in HTTP, because the client MUST
- always be able to take a reasonable course of action based only on
- the numeric code. However, it does remove the need to define new
- numeric codes. The new machine-readable codes used for this purpose
- are XML elements classified as preconditions and postconditions, so
- naturally any group defining a new condition code can use their own
- namespace. As always, the "DAV:" namespace is reserved for use by
- IETF-chartered WebDAV working groups.
-
- A server supporting this specification SHOULD use the XML error
- whenever a precondition or postcondition defined in this document is
- violated. For error conditions not specified in this document, the
- server MAY simply choose an appropriate numeric status and leave the
- response body blank. However, a server MAY instead use a custom
- condition code and other supporting text, because even when clients
- do not automatically recognize condition codes they can be quite
- useful in interoperability testing and debugging.
-
- Example - Response with precondition code
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 105]
-
-Internet-Draft WebDAV April 2006
-
-
- >>Response
-
- HTTP/1.1 423 Locked
- Content-Type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:lock-token-submitted>
- <D:href>/workspace/webdav/</D:href>
- </D:lock-token-submitted>
- </D:error>
-
- In this example, a client unaware of a "Depth: infinity" lock on the
- parent collection "/workspace/webdav/" attempted to modify the
- collection member "/workspace/webdav/proposal.doc".
-
- Some other useful preconditions and postconditions have been defined
- in other specifications extending WebDAV, such as [RFC3744] (see
- particularly Section 7.1.1), [RFC3253], and [RFC3648].
-
- All these elements are in the "DAV:" namespace. If not specified
- otherwise, the content for each condition's XML element is defined to
- be empty.
-
- Name: lock-token-matches-request-uri
-
- Use with: 409 Conflict
-
- Purpose: (precondition) -- A request may include a Lock-Token header
- to identify a lock for the UNLOCK method. However, if the
- Request-URI does not fall within the scope of the lock identified
- by the token, the server SHOULD use this error. The lock may have
- a scope that does not include the Request-URI, or the lock could
- have disappeared, or the token may be invalid.
-
- Name: lock-token-submitted (precondition)
-
- Use with: 423 Locked
-
- Purpose: The request could not succeed because a lock token should
- have been submitted. This element, if present, MUST contain at
- least one URL of a locked resource that prevented the request. In
- cases of MOVE, COPY and DELETE where collection locks are
- involved, it can be difficult for the client to find out which
- locked resource made the request fail -- but the server is only
- resonsible for returning one such locked resource. The server MAY
- return every locked resource that prevented the request from
-
-
-
-Dusseault Expires October 3, 2006 [Page 106]
-
-Internet-Draft WebDAV April 2006
-
-
- succeeding if it knows them all.
-
- <!ELEMENT lock-token-submitted (href+) >
-
- Name: no-conflicting-lock (precondition)
-
- Use with: Typically 423 Locked
-
- Purpose: A LOCK request failed due the presence of an already
- existing conflicting lock. Note that a lock can be in conflict
- although the resource to which the request was directed is only
- indirectly locked. In this case, the precondition code can be
- used to inform the client about the resource which is the root of
- the conflicting lock, avoiding a separate lookup of the
- "lockdiscovery" property.
-
- <!ELEMENT no-conflicting-lock (href)* >
-
- Name: no-external-entities
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- If the server rejects a client request
- because the request body contains an external entity, the server
- SHOULD use this error.
-
- Name: preserved-live-properties
-
- Use with: 409 Conflict
-
- Purpose: (postcondition) -- The server received an otherwise-valid
- MOVE or COPY request, but cannot maintain the live properties with
- the same behavior at the destination. It may be that the server
- only supports some live properties in some parts of the
- repository, or simply has an internal error.
-
- Name: propfind-finite-depth
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- This server does not allow infinite-depth
- PROPFIND requests on collections.
-
- Name: cannot-modify-protected-property
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 107]
-
-Internet-Draft WebDAV April 2006
-
-
- Use with: 403 Forbidden
-
- Purpose: (precondition) -- The client attempted to set a protected
- property in a PROPPATCH (such as DAV:getetag). See also
- [RFC3253], Section 3.12.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 108]
-
-Internet-Draft WebDAV April 2006
-
-
-17. XML Extensibility in DAV
-
- The XML namespace extension ([REC-XML-NAMES]) is used in this
- specification in order to allow for new XML elements to be added
- without fear of colliding with other element names. Although WebDAV
- request and response bodies can be extended by arbitrary XML
- elements, which can be ignored by the message recipient, an XML
- element in the "DAV:" namespace SHOULD NOT be used in the request or
- response body unless that XML element is explicitly defined in an
- IETF RFC reviewed by a WebDAV working group.
-
- For WebDAV to be both extensibile and backwards-compatible, both
- clients and servers need to know how to behave when unexpected or
- unrecognized command extensions are received. For XML processing,
- this means that clients and servers MUST process received XML
- documents as if unexpected elements and attributes (and all children
- of unrecognized elements) were not there. An unexpected element or
- attribute includes one which may be used in another context but is
- not expected here. Ignoring such items for purposes of processing
- can of course be consistent with logging all information or
- presenting for debugging.
-
- This restriction also applies to the processing, by clients, of DAV
- property values where unexpected XML elements SHOULD be ignored
- unless the property's schema declares otherwise.
-
- This restriction does not apply to setting dead DAV properties on the
- server where the server MUST record all XML elements.
-
- Additionally, this restriction does not apply to the use of XML where
- XML happens to be the content type of the entity body, for example,
- when used as the body of a PUT.
-
- Processing instructions in XML SHOULD be ignored by recipients.
- Thus, specifications extending WebDAV SHOULD NOT use processing
- instructions to define normative behavior.
-
- XML DTD fragments are included for all the XML elements defined in
- this specification. However, correct XML will not be valid according
- to any DTD due to namespace usage and extension rules. In
- particular:
-
- o Elements (from this specification) are in the "DAV:" namespace,
-
- o Element ordering is irrelevant unless otherwise stated,
-
- o Extension attributes MAY be added,
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 109]
-
-Internet-Draft WebDAV April 2006
-
-
- o For element type definitions of "ANY", the normative text
- definition for that element defines what can be in it and what
- that means.
-
- o For element type definitions of "#PCDATA", extension elements MUST
- NOT be added.
-
- o For other element type definitions, including "EMPTY", extension
- elements MAY be added.
-
- Note that this means that elements containing elements cannot be
- extended to contain text, and vice versa.
-
- With DTD validation relaxed by the rules above, the constraints
- described by the DTD fragments are normative (see for example
- Appendix A). A recipient of a WebDAV message with an XML body MUST
- NOT validate the XML document according to any hard-coded or
- dynamically-declared DTD.
-
- Note that this section describes backwards-compatible extensibility
- rules. There might also be times when an extension is designed not
- to be backwards-compatible, for example defining an extension that
- reuses an XML element defined in this document but omitting one of
- the child elements required by the DTDs in this specification.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 110]
-
-Internet-Draft WebDAV April 2006
-
-
-18. DAV Compliance Classes
-
- A DAV compliant resource can advertise several classes of compliance.
- A client can discover the compliance classes of a resource by
- executing OPTIONS on the resource, and examining the "DAV" header
- which is returned. Note particularly that resources are spoken of as
- being compliant, rather than servers. That is because theoretically
- some resources on a server could support different feature sets.
- E.g. a server could have a sub-repository where an advanced feature
- like versioning was supported, even if that feature was not supported
- on all sub-repositories.
-
- Since this document describes extensions to the HTTP/1.1 protocol,
- minimally all DAV compliant resources, clients, and proxies MUST be
- compliant with [RFC2616].
-
- A resource that is class 2 or class 3 compliant must also be class 1
- compliant.
-
-18.1. Class 1
-
- A class 1 compliant resource MUST meet all "MUST" requirements in all
- sections of this document.
-
- Class 1 compliant resources MUST return, at minimum, the value "1" in
- the DAV header on all responses to the OPTIONS method.
-
-18.2. Class 2
-
- A class 2 compliant resource MUST meet all class 1 requirements and
- support the LOCK method, the DAV:supportedlock property, the DAV:
- lockdiscovery property, the Time-Out response header and the Lock-
- Token request header. A class "2" compliant resource SHOULD also
- support the Time-Out request header and the 'owner' XML element.
-
- Class 2 compliant resources MUST return, at minimum, the values "1"
- and "2" in the DAV header on all responses to the OPTIONS method.
-
-18.3. Class 3
-
- A resource can explicitly advertise its support for the revisions to
- [RFC2518] made in this document. Class 1 MUST be supported as well.
- Class 2 MAY be supported. Advertising class 3 support in addition to
- class 1 and 2 means that the server supports all the requirements in
- this specification. Advertising class 3 and class 1 support, but not
- class 2, means that the server supports all the requirements in this
- specification except possibly those that involve locking support.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 111]
-
-Internet-Draft WebDAV April 2006
-
-
- Example:
-
- DAV: 1, 3
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 112]
-
-Internet-Draft WebDAV April 2006
-
-
-19. Internationalization Considerations
-
- In the realm of internationalization, this specification complies
- with the IETF Character Set Policy [RFC2277]. In this specification,
- human-readable fields can be found either in the value of a property,
- or in an error message returned in a response entity body. In both
- cases, the human-readable content is encoded using XML, which has
- explicit provisions for character set tagging and encoding, and
- requires that XML processors read XML elements encoded, at minimum,
- using the UTF-8 [RFC3629] and UTF-16 encodings of the ISO 10646
- multilingual plane. XML examples in this specification demonstrate
- use of the charset parameter of the Content-Type header, as defined
- in [RFC3023], as well as the XML declarations which provide charset
- identification information for MIME and XML processors.
-
- XML also provides a language tagging capability for specifying the
- language of the contents of a particular XML element. The "xml:lang"
- attribute appears on an XML element to identify the language of its
- content and attributes. See [REC-XML] for definitions of values and
- scoping.
-
- WebDAV applications MUST support the character set tagging, character
- set encoding, and the language tagging functionality of the XML
- specification. Implementors of WebDAV applications are strongly
- encouraged to read "XML Media Types" [RFC3023] for instruction on
- which MIME media type to use for XML transport, and on use of the
- charset parameter of the Content-Type header.
-
- Names used within this specification fall into four categories: names
- of protocol elements such as methods and headers, names of XML
- elements, names of properties, and names of conditions. Naming of
- protocol elements follows the precedent of HTTP, using English names
- encoded in USASCII for methods and headers. Since these protocol
- elements are not visible to users, and are simply long token
- identifiers, they do not need to support multiple languages.
- Similarly, the names of XML elements used in this specification are
- not visible to the user and hence do not need to support multiple
- languages.
-
- WebDAV property names are qualified XML names (pairs of XML namespace
- name and local name). Although some applications (e.g., a generic
- property viewer) will display property names directly to their users,
- it is expected that the typical application will use a fixed set of
- properties, and will provide a mapping from the property name and
- namespace to a human-readable field when displaying the property name
- to a user. It is only in the case where the set of properties is not
- known ahead of time that an application need display a property name
- to a user. We recommend that applications provide human-readable
-
-
-
-Dusseault Expires October 3, 2006 [Page 113]
-
-Internet-Draft WebDAV April 2006
-
-
- property names wherever feasible.
-
- For error reporting, we follow the convention of HTTP/1.1 status
- codes, including with each status code a short, English description
- of the code (e.g., 423 (Locked)). While the possibility exists that
- a poorly crafted user agent would display this message to a user,
- internationalized applications will ignore this message, and display
- an appropriate message in the user's language and character set.
-
- Since interoperation of clients and servers does not require locale
- information, this specification does not specify any mechanism for
- transmission of this information.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 114]
-
-Internet-Draft WebDAV April 2006
-
-
-20. Security Considerations
-
- This section is provided to detail issues concerning security
- implications of which WebDAV applications need to be aware.
-
- All of the security considerations of HTTP/1.1 (discussed in
- [RFC2616]) and XML (discussed in [RFC3023]) also apply to WebDAV. In
- addition, the security risks inherent in remote authoring require
- stronger authentication technology, introduce several new privacy
- concerns, and may increase the hazards from poor server design.
- These issues are detailed below.
-
-20.1. Authentication of Clients
-
- Due to their emphasis on authoring, WebDAV servers need to use
- authentication technology to protect not just access to a network
- resource, but the integrity of the resource as well. Furthermore,
- the introduction of locking functionality requires support for
- authentication.
-
- A password sent in the clear over an insecure channel is an
- inadequate means for protecting the accessibility and integrity of a
- resource as the password may be intercepted. Since Basic
- authentication for HTTP/1.1 performs essentially clear text
- transmission of a password, Basic authentication MUST NOT be used to
- authenticate a WebDAV client to a server unless the connection is
- secure. Furthermore, a WebDAV server MUST NOT send Basic
- authentication credentials in a WWW-Authenticate header unless the
- connection is secure. Examples of secure connections include a
- Transport Layer Security (TLS) connection employing a strong cipher
- suite with mutual authentication of client and server, or a
- connection over a network which is physically secure, for example, an
- isolated network in a building with restricted access.
-
- WebDAV applications MUST support the Digest authentication scheme
- [RFC2617]. Since Digest authentication verifies that both parties to
- a communication know a shared secret, a password, without having to
- send that secret in the clear, Digest authentication avoids the
- security problems inherent in Basic authentication while providing a
- level of authentication which is useful in a wide range of scenarios.
-
-20.2. Denial of Service
-
- Denial of service attacks are of special concern to WebDAV servers.
- WebDAV plus HTTP enables denial of service attacks on every part of a
- system's resources.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 115]
-
-Internet-Draft WebDAV April 2006
-
-
- o The underlying storage can be attacked by PUTting extremely large
- files.
-
- o Asking for recursive operations on large collections can attack
- processing time.
-
- o Making multiple pipelined requests on multiple connections can
- attack network connections.
-
- WebDAV servers need to be aware of the possibility of a denial of
- service attack at all levels. The proper response to such an attack
- MAY be to simply drop the connection, or if the server is able to
- make a response, the server MAY use a 400-level status request such
- as 400 (Bad Request) and indicate why the request was refused (a 500-
- level status response would indicate that the problem is with the
- server, whereas unintentional DOS attacks are something the client is
- capable of remedying).
-
-20.3. Security through Obscurity
-
- WebDAV provides, through the PROPFIND method, a mechanism for listing
- the member resources of a collection. This greatly diminishes the
- effectiveness of security or privacy techniques that rely only on the
- difficulty of discovering the names of network resources. Users of
- WebDAV servers are encouraged to use access control techniques to
- prevent unwanted access to resources, rather than depending on the
- relative obscurity of their resource names.
-
-20.4. Privacy Issues Connected to Locks
-
- When submitting a lock request a user agent may also submit an
- 'owner' XML field giving contact information for the person taking
- out the lock (for those cases where a person, rather than a robot, is
- taking out the lock). This contact information is stored in a DAV:
- lockdiscovery property on the resource, and can be used by other
- collaborators to begin negotiation over access to the resource.
- However, in many cases this contact information can be very private,
- and should not be widely disseminated. Servers SHOULD limit read
- access to the DAV:lockdiscovery property as appropriate.
- Furthermore, user agents SHOULD provide control over whether contact
- information is sent at all, and if contact information is sent,
- control over exactly what information is sent.
-
-20.5. Privacy Issues Connected to Properties
-
- Since property values are typically used to hold information such as
- the author of a document, there is the possibility that privacy
- concerns could arise stemming from widespread access to a resource's
-
-
-
-Dusseault Expires October 3, 2006 [Page 116]
-
-Internet-Draft WebDAV April 2006
-
-
- property data. To reduce the risk of inadvertent release of private
- information via properties, servers are encouraged to develop access
- control mechanisms that separate read access to the resource body and
- read access to the resource's properties. This allows a user to
- control the dissemination of their property data without overly
- restricting access to the resource's contents.
-
-20.6. Implications of XML Entities
-
- XML supports a facility known as "external entities", defined in
- Section 4.2.2 of [REC-XML], which instruct an XML processor to
- retrieve and include additional XML. An external XML entity can be
- used to append or modify the document type declaration (DTD)
- associated with an XML document. An external XML entity can also be
- used to include XML within the content of an XML document. For non-
- validating XML, such as the XML used in this specification, including
- an external XML entity is not required by XML. However, XML does
- state that an XML processor may, at its discretion, include the
- external XML entity.
-
- External XML entities have no inherent trustworthiness and are
- subject to all the attacks that are endemic to any HTTP GET request.
- Furthermore, it is possible for an external XML entity to modify the
- DTD, and hence affect the final form of an XML document, in the worst
- case significantly modifying its semantics, or exposing the XML
- processor to the security risks discussed in [RFC3023]. Therefore,
- implementers must be aware that external XML entities should be
- treated as untrustworthy. If a server implementor chooses not to
- handle external XML entities, it SHOULD respond to requests
- containing external entities with the 'no-external-entities'
- condition code.
-
- There is also the scalability risk that would accompany a widely
- deployed application which made use of external XML entities. In
- this situation, it is possible that there would be significant
- numbers of requests for one external XML entity, potentially
- overloading any server which fields requests for the resource
- containing the external XML entity.
-
- Furthermore, there's also a risk based on the evaluation of "internal
- entities" as defined in Section 4.2.2 of [REC-XML]. A small,
- carefully crafted request using nested internal entities may require
- enormous amounts of memory and/or processing time to process. Server
- implementors should be aware of this risk and configure their XML
- parsers so that requests like these can be detected and rejected as
- early as possible.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 117]
-
-Internet-Draft WebDAV April 2006
-
-
-20.7. Risks Connected with Lock Tokens
-
- This specification encourages the use of "A Universally Unique
- Identifier (UUID) URN Namespace" ([RFC4122]) for lock tokens
- (Section 6.5), in order to guarantee their uniqueness across space
- and time. Version 1 UUIDs (defined in Section 4) MAY contain a
- "node" field that "consists of an IEEE 802 MAC address, usually the
- host address. For systems with multiple IEEE addresses, any
- available one can be used". Since a WebDAV server will issue many
- locks over its lifetime, the implication is that it may also be
- publicly exposing its IEEE 802 address.
-
- There are several risks associated with exposure of IEEE 802
- addresses. Using the IEEE 802 address:
-
- o It is possible to track the movement of hardware from subnet to
- subnet.
-
- o It may be possible to identify the manufacturer of the hardware
- running a WebDAV server.
-
- o It may be possible to determine the number of each type of
- computer running WebDAV.
-
- This risk only applies to host address based UUID versions. Section
- 4 of [RFC4122] describes several other mechanisms for generating
- UUIDs that do not involve the host address and therefore do not
- suffer from this risk.
-
-20.8. Hosting Malicious Content
-
- HTTP has the ability to host programs which are executed on client
- machines. These programs can take many forms including web scripts,
- executables, plug in modules, and macros in documents. WebDAV does
- not change any of the security concerns around these programs yet
- often WebDAV is used in contexts where a wide range of users can
- publish documents on a server. The server might not have a close
- trust relationship with the author that is publishing the document.
- Servers that allow clients to publish arbitrary content can usefully
- implement precautions to check that content published to the server
- is not harmful to other clients. Servers could do this by techniques
- such as restricting the types of content that is allowed to be
- published and running virus and malware detection software on
- published content. Servers can also mitigate the risk by having
- appropriate access restriction and authentication of users that are
- allowed to publish content to the server.
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 118]
-
-Internet-Draft WebDAV April 2006
-
-
-21. IANA Considerations
-
-21.1. New URI Schemes
-
- This specification defines two URI schemes:
-
- 1. the "opaquelocktoken" scheme defined in Appendix C, and
-
- 2. the "DAV" URI scheme, which historically was used in [RFC2518] to
- disambiguate WebDAV property and XML element names and which
- continues to be used for that purpose in this specification and
- others extending WebDAV. Creation of identifiers in the "DAV:"
- namespace is controlled by the IETF.
-
- Note that defining new URI schemes for XML namespaces is now
- discouraged. "DAV:" was defined before standard best practices
- emerged.
-
-21.2. XML Namespaces
-
- XML namespaces disambiguate WebDAV property names and XML elements.
- Any WebDAV user or application can define a new namespace in order to
- create custom properties or extend WebDAV XML syntax. IANA does not
- need to manage such namespaces, property names or element names.
-
-21.3. Message Header Fields
-
- The message header fields below should be added to the permanent
- registry (see [RFC3864]).
-
-21.3.1. DAV
-
- Header field name: DAV
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.1)
-
-21.3.2. Depth
-
- Header field name: Depth
-
- Applicable protocol: http
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 119]
-
-Internet-Draft WebDAV April 2006
-
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.2)
-
-21.3.3. Destination
-
- Header field name: Destination
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.3)
-
-21.3.4. If
-
- Header field name: If
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.4)
-
-21.3.5. Lock-Token
-
- Header field name: Lock-Token
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.5)
-
-21.3.6. Overwrite
-
- Header field name: Overwrite
-
- Applicable protocol: http
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 120]
-
-Internet-Draft WebDAV April 2006
-
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.6)
-
-21.3.7. Timeout
-
- Header field name: Timeout
-
- Applicable protocol: http
-
- Status: standard
-
- Author/Change controller: IETF
-
- Specification document: this specification (Section 10.7)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 121]
-
-Internet-Draft WebDAV April 2006
-
-
-22. Acknowledgements
-
- A specification such as this thrives on piercing critical review and
- withers from apathetic neglect. The authors gratefully acknowledge
- the contributions of the following people, whose insights were so
- valuable at every stage of our work.
-
- Contributors to RFC2518
-
- Terry Allen, Harald Alvestrand, Jim Amsden, Becky Anderson, Alan
- Babich, Sanford Barr, Dylan Barrell, Bernard Chester, Tim Berners-
- Lee, Dan Connolly, Jim Cunningham, Ron Daniel, Jr., Jim Davis, Keith
- Dawson, Mark Day, Brian Deen, Martin Duerst, David Durand, Lee
- Farrell, Chuck Fay, Wesley Felter, Roy Fielding, Mark Fisher, Alan
- Freier, George Florentine, Jim Gettys, Phill Hallam-Baker, Dennis
- Hamilton, Steve Henning, Mead Himelstein, Alex Hopmann, Andre van der
- Hoek, Ben Laurie, Paul Leach, Ora Lassila, Karen MacArthur, Steven
- Martin, Larry Masinter, Michael Mealling, Keith Moore, Thomas Narten,
- Henrik Nielsen, Kenji Ota, Bob Parker, Glenn Peterson, Jon Radoff,
- Saveen Reddy, Henry Sanders, Christopher Seiwald, Judith Slein, Mike
- Spreitzer, Einar Stefferud, Greg Stein, Ralph Swick, Kenji Takahashi,
- Richard N. Taylor, Robert Thau, John Turner, Sankar Virdhagriswaran,
- Fabio Vitali, Gregory Woodhouse, and Lauren Wood.
-
- Two from this list deserve special mention. The contributions by
- Larry Masinter have been invaluable, both in helping the formation of
- the working group and in patiently coaching the authors along the
- way. In so many ways he has set high standards we have toiled to
- meet. The contributions of Judith Slein in clarifying the
- requirements, and in patiently reviewing draft after draft, both
- improved this specification and expanded our minds on document
- management.
-
- We would also like to thank John Turner for developing the XML DTD.
-
- The authors of RFC2518 were Yaron Goland, Jim Whitehead, A. Faizi,
- Steve Carter and D. Jensen. Although their names had to be removed
- due to IETF author count restrictions they can take credit for the
- majority of the design of WebDAV.
-
- Additional Acknowledgements for This Specification
-
- Significant contributors of text for this specification are listed as
- contributors in the section below. We must also gratefully
- acknowledge Geoff Clemm, Joel Soderberg, and Dan Brotsky for hashing
- out specific text on the list or in meetings. Joe Hildebrand and
- Cullen Jennings helped close many issues. Barry Lind described an
- additional security consideration and Cullen Jennings provided text
-
-
-
-Dusseault Expires October 3, 2006 [Page 122]
-
-Internet-Draft WebDAV April 2006
-
-
- for that consideration. Jason Crawford tracked issue status for this
- document for a period of years, followed by Elias Sinderson.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 123]
-
-Internet-Draft WebDAV April 2006
-
-
-23. Contributors to This Specification
-
- Julian Reschke,
- <green/>bytes GmbH,
- Hafenweg 16, 48155 Muenster, Germany,
- Email: julian.reschke at greenbytes.de
-
-
- Elias Sinderson
- University of California, Santa Cruz
- 1156 High Street, Santa Cruz, CA 95064
- Email: elias at cse.ucsc.edu
-
-
- Jim Whitehead,
- University of California, Santa Cruz
- 1156 High Street, Santa Cruz, CA 95064
- Email: ejw at soe.ucsc.edu
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 124]
-
-Internet-Draft WebDAV April 2006
-
-
-24. Authors of RFC2518
-
- Y. Y. Goland,
- Microsoft Corporation,
- One Microsoft Way,
- Redmond, WA 98052-6399.
- Email: yarong at microsoft.com.
-
-
- E. J. Whitehead, Jr.,
- Dept. Of Information and Computer Science,
- University of California, Irvine,
- Irvine, CA 92697-3425.
- Email: ejw at ics.uci.edu.
-
-
- A. Faizi,
- Netscape,
- 685 East Middlefield Road,
- Mountain View, CA 94043.
- Email: asad at netscape.com.
-
-
- S. R. Carter,
- Novell,
- 1555 N. Technology Way,
- M/S ORM F111,
- Orem, UT 84097-2399.
- Email: srcarter at novell.com.
-
-
- D. Jensen,
- Novell,
- 1555 N. Technology Way,
- M/S ORM F111,
- Orem, UT 84097-2399.
- Email: dcjensen at novell.com.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 125]
-
-Internet-Draft WebDAV April 2006
-
-
-25. References
-
-25.1. Normative References
-
- [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and
- F. Yergeau, "Extensible Markup Language (XML) 1.0 (Third
- Edition)", W3C REC-xml-20040204, February 2004,
- <http://www.w3.org/TR/2004/REC-xml-20040204>.
-
- [REC-XML-INFOSET]
- Cowan, J. and R. Tobin, "XML Information Set (Second
- Edition)", W3C REC-xml-infoset-20040204, February 2004,
- <http://www.w3.org/TR/2004/REC-xml-infoset-20040204/>.
-
- [REC-XML-NAMES]
- Bray, T., Hollander, D., and A. Layman, "Namespaces in
- XML", W3C REC-xml-names-19990114, January 1999,
- <http://www.w3.org/TR/1999/REC-xml-names-19990114>.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", BCP 18, RFC 2277, January 1998.
-
- [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.
-
- [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
- Timestamps", RFC 3339, July 2002.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629, November 2003.
-
- [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
- Resource Identifier (URI): Generic Syntax", STD 66,
- RFC 3986, January 2005.
-
- [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally
- Unique IDentifier (UUID) URN Namespace", RFC 4122,
- July 2005.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 126]
-
-Internet-Draft WebDAV April 2006
-
-
-25.2. Informational References
-
- [I-D.draft-whitehead-http-etag]
- Whitehead, J., "Design Considerations for State
- Identifiers in HTTP and WebDAV",
- draft-whitehead-http-etag-00 (work in progress),
- February 2006.
-
- [RFC2291] Slein, J., Vitali, F., Whitehead, E., and D. Durand,
- "Requirements for a Distributed Authoring and Versioning
- Protocol for the World Wide Web", RFC 2291, February 1998.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
- Jensen, "HTTP Extensions for Distributed Authoring --
- WEBDAV", RFC 2518, February 1999.
-
- [RFC3023] Murata, M., St. Laurent, S., and D. Kohn, "XML Media
- Types", RFC 3023, January 2001.
-
- [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
- Whitehead, "Versioning Extensions to WebDAV (Web
- Distributed Authoring and Versioning)", RFC 3253,
- March 2002.
-
- [RFC3648] Whitehead, J. and J. Reschke, Ed., "Web Distributed
- Authoring and Versioning (WebDAV) Ordered Collections
- Protocol", RFC 3648, December 2003.
-
- [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
- Distributed Authoring and Versioning (WebDAV) Access
- Control Protocol", RFC 3744, May 2004.
-
- [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
- Procedures for Message Header Fields", BCP 90, RFC 3864,
- September 2004.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 127]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix A. Notes on Processing XML Elements
-
-A.1. Notes on Empty XML Elements
-
- XML supports two mechanisms for indicating that an XML element does
- not have any content. The first is to declare an XML element of the
- form <A></A>. The second is to declare an XML element of the form
- <A/>. The two XML elements are semantically identical.
-
-A.2. Notes on Illegal XML Processing
-
- XML is a flexible data format that makes it easy to submit data that
- appears legal but in fact is not. The philosophy of "Be flexible in
- what you accept and strict in what you send" still applies, but it
- must not be applied inappropriately. XML is extremely flexible in
- dealing with issues of white space, element ordering, inserting new
- elements, etc. This flexibility does not require extension,
- especially not in the area of the meaning of elements.
-
- There is no kindness in accepting illegal combinations of XML
- elements. At best it will cause an unwanted result and at worst it
- can cause real damage.
-
-A.3. Example - XML Syntax Error
-
- The following request body for a PROPFIND method is illegal.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:allprop/>
- <D:propname/>
- </D:propfind>
-
- The definition of the propfind element only allows for the allprop or
- the propname element, not both. Thus the above is an error and must
- be responded to with a 400 (Bad Request).
-
- Imagine, however, that a server wanted to be "kind" and decided to
- pick the allprop element as the true element and respond to it. A
- client running over a bandwidth limited line who intended to execute
- a propname would be in for a big surprise if the server treated the
- command as an allprop.
-
- Additionally, if a server were lenient and decided to reply to this
- request, the results would vary randomly from server to server, with
- some servers executing the allprop directive, and others executing
- the propname directive. This reduces interoperability rather than
- increasing it.
-
-
-
-Dusseault Expires October 3, 2006 [Page 128]
-
-Internet-Draft WebDAV April 2006
-
-
-A.4. Example - Unexpected XML Element
-
- The previous example was illegal because it contained two elements
- that were explicitly banned from appearing together in the propfind
- element. However, XML is an extensible language, so one can imagine
- new elements being defined for use with propfind. Below is the
- request body of a PROPFIND and, like the previous example, must be
- rejected with a 400 (Bad Request) by a server that does not
- understand the expired-props element.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- <E:expired-props/>
- </D:propfind>
-
- To understand why a 400 (Bad Request) is returned let us look at the
- request body as the server unfamiliar with expired-props sees it.
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- </D:propfind>
-
- As the server does not understand the 'expired-props' element,
- according to the WebDAV-specific XML processing rules specified in
- Section 17, it must process the request as if the element were not
- there. Thus the server sees an empty propfind, which by the
- definition of the propfind element is illegal.
-
- Please note that had the extension been additive it would not
- necessarily have resulted in a 400 (Bad Request). For example,
- imagine the following request body for a PROPFIND:
-
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:"
- xmlns:E="http://www.example.com/standards/props/">
- <D:propname/>
- <E:leave-out>*boss*</E:leave-out>
- </D:propfind>
-
- The previous example contains the fictitious element leave-out. Its
- purpose is to prevent the return of any property whose name matches
- the submitted pattern. If the previous example were submitted to a
- server unfamiliar with 'leave-out', the only result would be that the
- 'leave-out' element would be ignored and a propname would be
- executed.
-
-
-
-Dusseault Expires October 3, 2006 [Page 129]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix B. Notes on HTTP Client Compatibility
-
- WebDAV was designed to be, and has been found to be, backward-
- compatible with HTTP 1.1. The PUT and DELETE methods are defined in
- HTTP and thus may be used by HTTP clients as well as WebDAV-aware
- clients, but the responses to PUT and DELETE have been extended in
- this specification in ways that only a WebDAV client would be
- entirely prepared for. Some theoretical concerns were raised about
- whether those responses would cause interoperability problems with
- HTTP-only clients, and this section addresses those concerns.
-
- Since any HTTP client ought to handle unrecognized 400-level and 500-
- level status codes as errors, the following new status codes should
- not present any issues: 422, 423 and 507 (424 is also a new status
- code but it appears only in the body of a Multistatus response.) So,
- for example, if a HTTP client attempted to PUT or DELETE a locked
- resource, the 423 Locked response ought to result in a generic error
- presented to the user.
-
- The 207 Multistatus response is interesting because a HTTP client
- issuing a DELETE request to a collection might interpret a 207
- response as a success, even though it does not realize the resource
- is a collection and cannot understand that the DELETE operation might
- have been a complete or partial failure. That interpretation isn't
- entirely justified, because a 200-level response indicates that the
- server "received, understood and accepted" the request, not that the
- request resulted in complete success.
-
- One option is that a server could treat a DELETE of a collection as
- an atomic operation, and use either 204 No Content in case of
- success, or some appropriate error response (400 or 500 level) for an
- error. This approach would indeed maximize backward compatibility.
- However, since interoperability tests and working group discussions
- have not turned up any instances of HTTP clients issuing a DELETE
- request against a WebDAV collection, this concern is more theoretical
- than practical. Thus, servers are likely to be completely successful
- at interoperating with HTTP clients even if they treat any collection
- DELETE request as a WebDAV request and send a 207 Multistatus
- response.
-
- In general server implementations are encouraged to use the detailed
- responses and other mechanisms defined in this document rather than
- make changes for theoretical interoperability concerns.
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 130]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix C. The opaquelocktoken scheme and URIs
-
- The 'opaquelocktoken' URI scheme was defined in [RFC2518] (and
- registered by IANA) in order to create syntactically correct and
- easy-to-generate URIs out of UUIDs, intended to be used as lock
- tokens and to be unique across all resources for all time.
-
- An opaquelocktoken URI is constructed by concatenating the
- 'opaquelocktoken' scheme with a UUID, along with an optional
- extension. Servers can create new UUIDs for each new lock token. If
- a server wishes to reuse UUIDs the server MUST add an extension and
- the algorithm generating the extension MUST guarantee that the same
- extension will never be used twice with the associated UUID.
-
- OpaqueLockToken-URI = "opaquelocktoken:" UUID [Extension]
- ; UUID is defined in Section 3 of [RFC4122]. Note that linear
- ; white space (LWS) is not allowed between elements of
- ; this production.
-
- Extension = path
- ; path is defined in Section 3.3 of [RFC3986]
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 131]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix D. Lock-null Resources
-
- The original WebDAV model for locking unmapped URLs created "lock-
- null resources". This model was over-complicated and some
- interoperability and implementation problems were discovered. The
- new WebDAV model for locking unmapped URLs (see Section 7.3) creates
- "locked empty resources". Lock-null resources are deprecated. This
- section discusses the original model briefly because clients MUST be
- able to handle either model.
-
- In the original "lock-null resource" model, which is no longer
- recommended for implementation:
-
- o A lock-null resource sometimes appeared as "Not Found". The
- server responds with a 404 or 405 to any method except for PUT,
- MKCOL, OPTIONS, PROPFIND, LOCK, UNLOCK.
-
- o A lock-null resource does however show up as a member of its
- parent collection.
-
- o The server removes the lock-null resource entirely (its URI
- becomes unmapped) if its lock goes away before it is converted to
- a regular resource. Recall that locks go away not only when they
- expire or are unlcoked, but are also removed if a resource is
- renamed or moved, or if any parent collection is renamed or moved.
-
- o The server converts the lock-null resource into a regular resource
- if a PUT request to the URL is successful.
-
- o The server converts the lock-null resource into a collection if a
- MKCOL request to the URL is successful (though interoperability
- experience showed that not all servers followed this requirement).
-
- o Property values were defined for DAV:lockdiscovery and DAV:
- supportedlock properties but not necessarily for other properties
- like DAV:getcontenttype.
-
- Clients can easily interoperate both with servers that support the
- old model "lock-null resources" and the recommended model of "locked
- empty resources" by only attempting PUT after a LOCK to an unmapped
- URL, not MKCOL or GET.
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 132]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix E. Guidance for Clients Desiring to Authenticate
-
- Many WebDAV clients already implemented have account settings
- (similar to the way email clients store IMAP account settings).
- Thus, the WebDAV client would be able to authenticate with its first
- couple requests to the server, provided it had a way to get the
- authentication challenge from the server with realm name, nonce and
- other challenge information. Note that the results of some requests
- might vary according to whether the client is authenticated or not --
- a PROPFIND might return more visible resources if the client is
- authenticated, yet not fail if the client is anonymous.
-
- There are a number of ways the client might be able to trigger the
- server do provide an authentication challenge. This appendix
- describes a couple approaches that seem particularly likely to work.
-
- The first approach is to perform a request that ought to require
- authentication. However, it's possible that a server might handle
- any request even without authentication, so to be entirely safe the
- client could add a conditional header to ensure that even if the
- request passes permissions checks it's not actually handled by the
- server. An example of following this approach would be to use a PUT
- request with an "If-Match" header with a made-up ETag value. This
- approach might fail to result in an authentication challenge if the
- server does not test authorization before testing conditionals as is
- required (see Section 8.5), or if the server does not need to test
- authorization.
-
- Example - forcing auth challenge with write request
-
- >>Request
-
- PUT /forceauth.txt HTTP/1.1
- Host: www.example.com
- If-Match: "xxx"
- Content-Type: text/plain
- Content-Length: 0
-
-
- The second approach is to use an Authorization header (defined in
- [RFC2617]) which is likely to be rejected by the server but which
- will then prompt a proper authentication challenge. For example, the
- client could start with a PROPFIND request containing an
- Authorization header containing a made-up Basic userid:password
- string or with actual plausible credentials. This approach relies on
- the server responding with a "401 Unauthorized" along with a
- challenge if it receives an Authorization header with an unrecognized
- username, invalid password, or if it doesn't even handle Basic
-
-
-
-Dusseault Expires October 3, 2006 [Page 133]
-
-Internet-Draft WebDAV April 2006
-
-
- authentication. This seems likely to work because of the
- requirements of RFC2617:
-
- "If the origin server does not wish to accept the credentials sent
- with a request, it SHOULD return a 401 (Unauthorized) response. The
- response MUST include a WWW-Authenticate header field containing at
- least one (possibly new) challenge applicable to the requested
- resource."
-
- There's a slight problem with implementing that recommendation in
- some cases, because some servers do not even have challenge
- information for certain resources. Thus, when there's no way to
- authenticate to a resource or the resource is entirely publicly
- available over all accepted methods, the server MAY ignore the
- Authorization header, and the client presumably try again later.
-
- Example - forcing auth challenge with Authorization header
-
- >>Request
-
- PROPFIND /docs/ HTTP/1.1
- Host: www.example.com
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
- Content-type: application/xml; charset="utf-8"
- Content-Length: xxxx
-
- [body omitted]
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 134]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix F. Summary of changes from RFC2518
-
- This section lists major changes between this document and RFC2518,
- starting with those that are likely to result in implementation
- changes. Servers will advertise support for all changes in this
- specification by returning the compliance class "3" in the DAV
- response header (see Sections 10.1 and 18.3).
-
-F.1. Changes for both Client and Server Implementations
-
- Collections and Namespace Operations
-
- o The semantics of PROPFIND 'allprop' (Section 9.1) have been
- relaxed so that servers may leave out live properties defined in
- other specifications, such as [RFC3253] and [RFC3744]. Related to
- this, 'allprop' requests can now be extended with the 'include'
- syntax to include specific named properties, thereby avoiding
- additional requests due to changed 'allprop' semantics.
-
- o Servers are now allowed to reject PROPFIND requests with Depth:
- Infinity. Clients that used this will need to be able to do a
- series of Depth:1 requests instead.
-
- o Multistatus response bodies now can transport the value of HTTP's
- Location response header in the new 'location' element. Clients
- may use this to avoid additional roundtrips to the server when
- there is a 'response' element with a 3xx status (see
- Section 14.24).
-
- o The definition of COPY has been relaxed so that it doesn't require
- servers to first delete the target resources anymore (this was a
- known incompatibility with [RFC3253]). See Section 9.8.
-
- Headers and Marshalling
-
- o The Destination and If request headers now allow absolute paths in
- addition to full URIs (see Section 8.3). This may be useful for
- clients operating through a reverse proxy that does rewrite the
- Host request header, but not WebDAV-specific headers.
-
- o This specification adopts the error marshalling extensions and the
- "precondition/postcondition" terminology defined in [RFC3253] (see
- Section 16). Related to that, it adds the "error" XML element
- inside multistatus response bodies (see Section 14.5, however note
- that it uses a format different from the one recommend in
- RFC3253).
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 135]
-
-Internet-Draft WebDAV April 2006
-
-
- o Senders and recipients are now required to support the UTF-16
- character encoding in XML message bodies (see Section 19).
-
- Locking
-
- o RFC2518's concept of "lock-null resources" (LNRs) has been
- replaced by a simplified approach, the "locked empty resources"
- (see Section 7.3). There are some aspects of lock-null resources
- clients can not rely on anymore, namely the ability to use them to
- create a locked collection or the fact that they disappear upon
- UNLOCK when no PUT or MKCOL request was issued. Note that servers
- are still allowed to implement LNRs as per RFC2518.
-
- o There is no implicit refresh of locks anymore. Locks are only
- refreshed upon explicit request (see Section 9.10.2).
-
- o Clarified that the DAV:owner value supplied in the LOCK request
- must be preserved by the server just like a dead property
- (Section 14.17). Also added the DAV:lockroot element
- (Section 14.12) which allows clients to discover the root of lock.
-
-F.2. Changes for Server Implementations
-
- Collections and Namespace Operations
-
- o Due to interoperability problems, allowable formats for contents
- of 'href' elements in multistatus responses have been limited (see
- Section 8.3).
-
- o Due to lack of implementation, support for the 'propertybehaviour'
- request body for COPY and MOVE has been removed. Instead,
- requirements for property preservation have been clarified (see
- Sections 9.8 and 9.9).
-
- Properties
-
- o Strengthened server requirements for storage of property values,
- in particular persistence of language information (xml:lang),
- whitespace, and XML namespace information (see Section 4.3).
-
- o Clarified requirements on which properties should be writeable by
- the client; in particular, setting "DAV:displayname" should be
- supported by servers (see Section 15).
-
- o Only 'rfc1123-date' productions are legal as values for DAV:
- getlastmodified (see Section 15.7).
-
- Headers and Marshalling
-
-
-
-Dusseault Expires October 3, 2006 [Page 136]
-
-Internet-Draft WebDAV April 2006
-
-
- o Servers are now required to do authorization checks before
- processing conditional headers (see Section 8.5).
-
- Locking
-
- o Strengthened requirement to check identity of lock creator when
- accessing locked resources (see Section 6.4). Clients should be
- aware that lock tokens returned to other principals can only be
- used to break a lock, if at all.
-
- o Section 8.10.4 of [RFC2518] incorrectly required servers to return
- a 409 status where a 207 status was really appropriate. This has
- been corrected (Section 9.10).
-
-F.3. Other Changes
-
- The definition of collection state has been fixed so it doesn't vary
- anymore depending on the Request-URI (see Section 5.2).
-
- The DAV:source property introduced in Section 4.6 of [RFC2518] was
- removed due to lack of implementation experience.
-
- The DAV header now allows non-IETF extensions through URIs in
- addition to compliance class tokens. It also can now be used in
- requests, although this specification does not define any associated
- semantics for the compliance classes defined in here (see
- Section 10.1).
-
- In RFC2518, the definition of the Depth header (Section 9.2) required
- that by default request headers would be applied to each resource in
- scope. Based on implementation experience, the default has now been
- reversed (see Section 10.2).
-
- The definitions of HTTP status code 102 ([RFC2518], Section 10.1) and
- the Status-URI response header (Section 9.7) have been removed due to
- lack of implementation.
-
- The TimeType format used in the Timeout request header and the
- "timeout" XML element used to be extensible. Now, only the two
- formats defined by this specification are allowed (see Section 10.7).
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 137]
-
-Internet-Draft WebDAV April 2006
-
-
-Appendix G. Change Log (to be removed by RFC Editor before publication)
-
-G.1. Changes from -05 to -06
-
- Specified that a successful LOCK request to an unmapped URL creates a
- new, empty locked resource.
-
- Resolved UNLOCK_NEEDS_IF_HEADER by clarifying that only Lock-Token
- header is needed on UNLOCK.
-
- Added Section 16 on preconditions and postconditions and defined a
- number of preconditions and postconditions. The 'lock-token-
- submitted' precondition resolves the REPORT_OTHER_RESOURCE_LOCKED
- issue.
-
- Added example of matching lock token to URI in the case of a
- collection lock in the If header section.
-
- Removed ability for Destination header to take "abs_path" in order to
- keep consistent with other places where client provides URLs (If
- header, href element in request body)
-
- Clarified the href element - that it generally contains HTTP URIs but
- not always.
-
- Attempted to fix the BNF describing the If header to allow commas
-
- Clarified presence of Depth header on LOCK refresh requests.
-
-G.2. Changes in -07
-
- Added text to "COPY and the Overwrite Header" section to resolve
- issue OVERWRITE_DELETE_ALL_TOO_STRONG.
-
- Added text to "HTTP URL Namespace Model" section to provide more
- clarification and examples on what consistency means and what is not
- required, to resolve issue CONSISTENCY.
-
- Resolve DEFINE_PRINCIPAL by importing definition of principal from
- RFC3744.
-
- Resolve INTEROP_DELETE_AND_MULTISTATUS by adding appendix 3
- discussing backward-compatibility concerns.
-
- Resolve DATE_FORMAT_GETLASTMODIFIED by allowing only rfc1123-date,
- not HTTP-date for getlastmodified.
-
- Resolve COPY_INTO_YOURSELF_CLARIFY by adding sentence to first para.
-
-
-
-Dusseault Expires October 3, 2006 [Page 138]
-
-Internet-Draft WebDAV April 2006
-
-
- of COPY section.
-
- Confirm that WHEN_TO_MULTISTATUS_FOR_DELETE_1 and
- WHEN_TO_MULTISTATUS_FOR_DELETE_2 are resolved and tweak language in
- DELETE section slightly to be clearly consistent.
-
- More text clarifications to deal with several of the issues in
- LOCK_ISSUES. This may not completely resolve that set but we need
- feedback from the originator of the issues at this point.
-
- Resolved COPY_INTO_YOURSELF_CLARIFY with new sentence in Copy For
- Collections section.
-
- Double checked that LEVEL_OR_CLASS is resolved by using class, not
- level.
-
- Further work to resolve IF_AND_AUTH and LOCK_SEMANTICS, clarifying
- text on using locks and being authenticated.
-
- Added notes on use of 503 status response to resolve issue
- PROPFIND_INFINITY
-
- Removed section on other uses of Metadata (and associated references)
-
- Added reference to RFC4122 for lock tokens and removed section on
- generating UUIDs
-
- Explained that even with language variation, a property has only one
- value (Section 4.5).
-
- Added section on lock owner (7.1) and what to do if lock requested by
- unauthenticated user
-
- Removed Section 4.2 -- justification on why to have metadata, not
- needed now
-
- Removed paragraph in Section 5.2 about collections with resource type
- "DAV:collection" but which are non-WebDAV compliant -- not
- implemented.
-
-G.3. Changes in -08
-
- Added security considerations section on scripts and cookie sessions,
- suggested by Barry Lind
-
- Clarified which error codes are defined and undefined in MultiStatus
-
- Moved opaquelocktoken definition to an appendix and refer to RFC4122
-
-
-
-Dusseault Expires October 3, 2006 [Page 139]
-
-Internet-Draft WebDAV April 2006
-
-
- for use of 'urn:uuid:' URI scheme; fix all lock token examples to use
- this.
-
- Multi-status responses contain URLs which MUST either be absolute
- (and begin with the Request-URI or MUST be relative with new
- limitations. (bug 12)
-
- Moved status code sections before example sections within PROPFIND
- section for section ordering consistency.
-
- Clarified use of Location header with Multi-Status
-
- Bugzilla issue resolutions: bugs 9, 12, 14, 19, 20, 29, 30, 34, 36,
- 102 and 172.
-
-G.4. Changes in -09
-
- Bugzilla editorial issues: bugs 30, 57, 63, 68, 88, 89, 168, 180,
- 182, 185, 187.
-
- More clarity between URL namespaces and XML namespaces, particularly
- at the beginning of paragraphs using the word namespace
-
- More consistency in referring to properties with the namespace, as in
- "DAV:lockdiscovery", and referring to XML element names in single
- quotes, e.g. 'allprop' element.
-
- Figure (example) formatting fixes
-
- Bugzilla issues: bugs 24, 37, 39, 43, 45, 27, 25
-
- Replaced references to "non-null state" of resources with more clear
- language about URLs that are mapped to resources, bug 25. Also added
- definition of URL/URI mapping. Bug 40.
-
- Bugzilla issues: bug 7, 8, 9, 41, 47, 51, 62, 93, 171, 172. Bugs 28
- and 94 were iterated on.
-
- Bugzilla issues: 56, 59, 79, 99, 103, 175, 178. Part of bug 23.
- Iteration on bug 10.
-
- Iteration on bugs 10, 46 and 47. Bug 11.
-
- Remove "102 Processing" response
-
- Fix bug 46, 105, 107, 120, 140 and 201.
-
- Another stab at bug 12 - relative v. absolute URLs in Multi-Status
-
-
-
-Dusseault Expires October 3, 2006 [Page 140]
-
-Internet-Draft WebDAV April 2006
-
-
- response hrefs
-
- Fix bug 6, 11, 15, 16, 28, 32, 42, 51, 52, 53, 58, 60, 62, 186, 189,
- 191, 199, 200
-
- Fix bug 96
-
-G.5. Changes in -10
-
- Clarify lock intro text on when a client might use another client's
- lock token - suggestion by Geoff, Nov 15
-
- Removed Force-Authenticate header and instead added an appendix
- explaining how existing mechanisms might resolve the need of clients
- to get an authentication challenge (bug 18).
-
- Bug 62, 113, 125, 131, 143, 144, 171, 193
-
- Bug 176, 177, 179, 181, 184, 206, 207, 208
-
-G.6. Changes in -11
-
- Bug 10, 50, 92, 213, 214, 215
-
- not recommend use of 414 for over-long Destination URI, bug 179
-
- Changes for bug 10, 31, 42, 44, 46, 47, 80, 86, 99, 124, 132, 143,
- 147, 152, 166, 177, 188, 216, 218
-
- Various changes discussed in conference call, including bug 10, 42,
- 44, 80, 97, 152.
-
- Bugs 55, 85, 86
-
-G.7. Changes in -12
-
- Incorporated GULP (Lock model) into document, making a fair number of
- changes to rationalize the new order of explaining things, keeping
- text that explains a lock model concept in more detail but removing
- text that is redundant or inconsistent.
-
- Various bugs including 46, 48, 53, 97, 152, 179, 184, 188, 200, 210,
- 211, and 225. Moved URL Handling from Multi-Status section to
- general request and response handling section as it now applies to
- Destination and If as well as 'href' in Multi-Status. Moved GR&RH
- section up one level to be the new Section 8.
-
- Bug 53, 184, 210, 213, 217, 221
-
-
-
-Dusseault Expires October 3, 2006 [Page 141]
-
-Internet-Draft WebDAV April 2006
-
-
- Further rewriting of URL Handling section. Changes resulting from
- discussion of empty locked resources and how servers should handle
- Content-Type in that situation. Bug 48, 179.
-
- Bug 227, 228
-
-G.8. Changes in -13
-
- Moved the timeout model text and clarified it (bug 229).
-
- Fixed the definition of collection state (bug 227).
-
- Made the depth header required on PROPFIND requests (bug 213).
-
- Fixed inconsistencies in Destination header definition (bug 211).
-
- Improved appendix on HTTP client compatibility (bug 100).
-
- Fixed external references with unwieldy pointers (bug 72).
-
-G.9. Changes in -14
-
- Changes section rewritten, if section rewritten
-
- Collection definition and membership requirements changed (bug 227)
-
- Bug 100 and 229 iterations, smallish editorial changes
-
-G.10. Changes in -15
-
- Moved lock-null resource explanation to an appendix.
-
- Reverted to RFC2518 behavior of refreshing lock with "If" header.
-
- Removed section on locks and multiple bindings.
-
- Removed requirement for clients to upate a property only once in a
- PROPPATCH.
-
- Updated displayname property description.
-
- Copy-edit level changes e.g. "read-only" to "protected", and defining
- what it means to protect a resource with a lock.
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 142]
-
-Internet-Draft WebDAV April 2006
-
-
-Author's Address
-
- Lisa Dusseault (editor)
- Open Source Application Foundation
- 2064 Edgewood Dr.
- Palo Alto, CA 94303
- US
-
- Email: lisa at osafoundation.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 143]
-
-Internet-Draft WebDAV April 2006
-
-
-Intellectual Property Statement
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr at ietf.org.
-
-
-Disclaimer of Validity
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-
-Copyright Statement
-
- Copyright (C) The Internet Society (2006). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
-
-Acknowledgment
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-Dusseault Expires October 3, 2006 [Page 144]
-
-
Copied: CalendarServer/trunk/doc/RFC/rfc2616-HTTP.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2616.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2616-HTTP.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2616-HTTP.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,9859 @@
+
+
+
+
+
+
+Network Working Group R. Fielding
+Request for Comments: 2616 UC Irvine
+Obsoletes: 2068 J. Gettys
+Category: Standards Track Compaq/W3C
+ J. Mogul
+ Compaq
+ H. Frystyk
+ W3C/MIT
+ L. Masinter
+ Xerox
+ P. Leach
+ Microsoft
+ T. Berners-Lee
+ W3C/MIT
+ June 1999
+
+
+ Hypertext Transfer Protocol -- HTTP/1.1
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. It is a generic, stateless, protocol which can be used for
+ many tasks beyond its use for hypertext, such as name servers and
+ distributed object management systems, through extension of its
+ request methods, error codes and headers [47]. A feature of HTTP is
+ the typing and negotiation of data representation, allowing systems
+ to be built independently of the data being transferred.
+
+ HTTP has been in use by the World-Wide Web global information
+ initiative since 1990. This specification defines the protocol
+ referred to as "HTTP/1.1", and is an update to RFC 2068 [33].
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 1]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+Table of Contents
+
+ 1 Introduction ...................................................7
+ 1.1 Purpose......................................................7
+ 1.2 Requirements .................................................8
+ 1.3 Terminology ..................................................8
+ 1.4 Overall Operation ...........................................12
+ 2 Notational Conventions and Generic Grammar ....................14
+ 2.1 Augmented BNF ...............................................14
+ 2.2 Basic Rules .................................................15
+ 3 Protocol Parameters ...........................................17
+ 3.1 HTTP Version ................................................17
+ 3.2 Uniform Resource Identifiers ................................18
+ 3.2.1 General Syntax ...........................................19
+ 3.2.2 http URL .................................................19
+ 3.2.3 URI Comparison ...........................................20
+ 3.3 Date/Time Formats ...........................................20
+ 3.3.1 Full Date ................................................20
+ 3.3.2 Delta Seconds ............................................21
+ 3.4 Character Sets ..............................................21
+ 3.4.1 Missing Charset ..........................................22
+ 3.5 Content Codings .............................................23
+ 3.6 Transfer Codings ............................................24
+ 3.6.1 Chunked Transfer Coding ..................................25
+ 3.7 Media Types .................................................26
+ 3.7.1 Canonicalization and Text Defaults .......................27
+ 3.7.2 Multipart Types ..........................................27
+ 3.8 Product Tokens ..............................................28
+ 3.9 Quality Values ..............................................29
+ 3.10 Language Tags ...............................................29
+ 3.11 Entity Tags .................................................30
+ 3.12 Range Units .................................................30
+ 4 HTTP Message ..................................................31
+ 4.1 Message Types ...............................................31
+ 4.2 Message Headers .............................................31
+ 4.3 Message Body ................................................32
+ 4.4 Message Length ..............................................33
+ 4.5 General Header Fields .......................................34
+ 5 Request .......................................................35
+ 5.1 Request-Line ................................................35
+ 5.1.1 Method ...................................................36
+ 5.1.2 Request-URI ..............................................36
+ 5.2 The Resource Identified by a Request ........................38
+ 5.3 Request Header Fields .......................................38
+ 6 Response ......................................................39
+ 6.1 Status-Line .................................................39
+ 6.1.1 Status Code and Reason Phrase ............................39
+ 6.2 Response Header Fields ......................................41
+
+
+
+Fielding, et al. Standards Track [Page 2]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 7 Entity ........................................................42
+ 7.1 Entity Header Fields ........................................42
+ 7.2 Entity Body .................................................43
+ 7.2.1 Type .....................................................43
+ 7.2.2 Entity Length ............................................43
+ 8 Connections ...................................................44
+ 8.1 Persistent Connections ......................................44
+ 8.1.1 Purpose ..................................................44
+ 8.1.2 Overall Operation ........................................45
+ 8.1.3 Proxy Servers ............................................46
+ 8.1.4 Practical Considerations .................................46
+ 8.2 Message Transmission Requirements ...........................47
+ 8.2.1 Persistent Connections and Flow Control ..................47
+ 8.2.2 Monitoring Connections for Error Status Messages .........48
+ 8.2.3 Use of the 100 (Continue) Status .........................48
+ 8.2.4 Client Behavior if Server Prematurely Closes Connection ..50
+ 9 Method Definitions ............................................51
+ 9.1 Safe and Idempotent Methods .................................51
+ 9.1.1 Safe Methods .............................................51
+ 9.1.2 Idempotent Methods .......................................51
+ 9.2 OPTIONS .....................................................52
+ 9.3 GET .........................................................53
+ 9.4 HEAD ........................................................54
+ 9.5 POST ........................................................54
+ 9.6 PUT .........................................................55
+ 9.7 DELETE ......................................................56
+ 9.8 TRACE .......................................................56
+ 9.9 CONNECT .....................................................57
+ 10 Status Code Definitions ......................................57
+ 10.1 Informational 1xx ...........................................57
+ 10.1.1 100 Continue .............................................58
+ 10.1.2 101 Switching Protocols ..................................58
+ 10.2 Successful 2xx ..............................................58
+ 10.2.1 200 OK ...................................................58
+ 10.2.2 201 Created ..............................................59
+ 10.2.3 202 Accepted .............................................59
+ 10.2.4 203 Non-Authoritative Information ........................59
+ 10.2.5 204 No Content ...........................................60
+ 10.2.6 205 Reset Content ........................................60
+ 10.2.7 206 Partial Content ......................................60
+ 10.3 Redirection 3xx .............................................61
+ 10.3.1 300 Multiple Choices .....................................61
+ 10.3.2 301 Moved Permanently ....................................62
+ 10.3.3 302 Found ................................................62
+ 10.3.4 303 See Other ............................................63
+ 10.3.5 304 Not Modified .........................................63
+ 10.3.6 305 Use Proxy ............................................64
+ 10.3.7 306 (Unused) .............................................64
+
+
+
+Fielding, et al. Standards Track [Page 3]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 10.3.8 307 Temporary Redirect ...................................65
+ 10.4 Client Error 4xx ............................................65
+ 10.4.1 400 Bad Request .........................................65
+ 10.4.2 401 Unauthorized ........................................66
+ 10.4.3 402 Payment Required ....................................66
+ 10.4.4 403 Forbidden ...........................................66
+ 10.4.5 404 Not Found ...........................................66
+ 10.4.6 405 Method Not Allowed ..................................66
+ 10.4.7 406 Not Acceptable ......................................67
+ 10.4.8 407 Proxy Authentication Required .......................67
+ 10.4.9 408 Request Timeout .....................................67
+ 10.4.10 409 Conflict ............................................67
+ 10.4.11 410 Gone ................................................68
+ 10.4.12 411 Length Required .....................................68
+ 10.4.13 412 Precondition Failed .................................68
+ 10.4.14 413 Request Entity Too Large ............................69
+ 10.4.15 414 Request-URI Too Long ................................69
+ 10.4.16 415 Unsupported Media Type ..............................69
+ 10.4.17 416 Requested Range Not Satisfiable .....................69
+ 10.4.18 417 Expectation Failed ..................................70
+ 10.5 Server Error 5xx ............................................70
+ 10.5.1 500 Internal Server Error ................................70
+ 10.5.2 501 Not Implemented ......................................70
+ 10.5.3 502 Bad Gateway ..........................................70
+ 10.5.4 503 Service Unavailable ..................................70
+ 10.5.5 504 Gateway Timeout ......................................71
+ 10.5.6 505 HTTP Version Not Supported ...........................71
+ 11 Access Authentication ........................................71
+ 12 Content Negotiation ..........................................71
+ 12.1 Server-driven Negotiation ...................................72
+ 12.2 Agent-driven Negotiation ....................................73
+ 12.3 Transparent Negotiation .....................................74
+ 13 Caching in HTTP ..............................................74
+ 13.1.1 Cache Correctness ........................................75
+ 13.1.2 Warnings .................................................76
+ 13.1.3 Cache-control Mechanisms .................................77
+ 13.1.4 Explicit User Agent Warnings .............................78
+ 13.1.5 Exceptions to the Rules and Warnings .....................78
+ 13.1.6 Client-controlled Behavior ...............................79
+ 13.2 Expiration Model ............................................79
+ 13.2.1 Server-Specified Expiration ..............................79
+ 13.2.2 Heuristic Expiration .....................................80
+ 13.2.3 Age Calculations .........................................80
+ 13.2.4 Expiration Calculations ..................................83
+ 13.2.5 Disambiguating Expiration Values .........................84
+ 13.2.6 Disambiguating Multiple Responses ........................84
+ 13.3 Validation Model ............................................85
+ 13.3.1 Last-Modified Dates ......................................86
+
+
+
+Fielding, et al. Standards Track [Page 4]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 13.3.2 Entity Tag Cache Validators ..............................86
+ 13.3.3 Weak and Strong Validators ...............................86
+ 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates.89
+ 13.3.5 Non-validating Conditionals ..............................90
+ 13.4 Response Cacheability .......................................91
+ 13.5 Constructing Responses From Caches ..........................92
+ 13.5.1 End-to-end and Hop-by-hop Headers ........................92
+ 13.5.2 Non-modifiable Headers ...................................92
+ 13.5.3 Combining Headers ........................................94
+ 13.5.4 Combining Byte Ranges ....................................95
+ 13.6 Caching Negotiated Responses ................................95
+ 13.7 Shared and Non-Shared Caches ................................96
+ 13.8 Errors or Incomplete Response Cache Behavior ................97
+ 13.9 Side Effects of GET and HEAD ................................97
+ 13.10 Invalidation After Updates or Deletions ...................97
+ 13.11 Write-Through Mandatory ...................................98
+ 13.12 Cache Replacement .........................................99
+ 13.13 History Lists .............................................99
+ 14 Header Field Definitions ....................................100
+ 14.1 Accept .....................................................100
+ 14.2 Accept-Charset .............................................102
+ 14.3 Accept-Encoding ............................................102
+ 14.4 Accept-Language ............................................104
+ 14.5 Accept-Ranges ..............................................105
+ 14.6 Age ........................................................106
+ 14.7 Allow ......................................................106
+ 14.8 Authorization ..............................................107
+ 14.9 Cache-Control ..............................................108
+ 14.9.1 What is Cacheable .......................................109
+ 14.9.2 What May be Stored by Caches ............................110
+ 14.9.3 Modifications of the Basic Expiration Mechanism .........111
+ 14.9.4 Cache Revalidation and Reload Controls ..................113
+ 14.9.5 No-Transform Directive ..................................115
+ 14.9.6 Cache Control Extensions ................................116
+ 14.10 Connection ...............................................117
+ 14.11 Content-Encoding .........................................118
+ 14.12 Content-Language .........................................118
+ 14.13 Content-Length ...........................................119
+ 14.14 Content-Location .........................................120
+ 14.15 Content-MD5 ..............................................121
+ 14.16 Content-Range ............................................122
+ 14.17 Content-Type .............................................124
+ 14.18 Date .....................................................124
+ 14.18.1 Clockless Origin Server Operation ......................125
+ 14.19 ETag .....................................................126
+ 14.20 Expect ...................................................126
+ 14.21 Expires ..................................................127
+ 14.22 From .....................................................128
+
+
+
+Fielding, et al. Standards Track [Page 5]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 14.23 Host .....................................................128
+ 14.24 If-Match .................................................129
+ 14.25 If-Modified-Since ........................................130
+ 14.26 If-None-Match ............................................132
+ 14.27 If-Range .................................................133
+ 14.28 If-Unmodified-Since ......................................134
+ 14.29 Last-Modified ............................................134
+ 14.30 Location .................................................135
+ 14.31 Max-Forwards .............................................136
+ 14.32 Pragma ...................................................136
+ 14.33 Proxy-Authenticate .......................................137
+ 14.34 Proxy-Authorization ......................................137
+ 14.35 Range ....................................................138
+ 14.35.1 Byte Ranges ...........................................138
+ 14.35.2 Range Retrieval Requests ..............................139
+ 14.36 Referer ..................................................140
+ 14.37 Retry-After ..............................................141
+ 14.38 Server ...................................................141
+ 14.39 TE .......................................................142
+ 14.40 Trailer ..................................................143
+ 14.41 Transfer-Encoding..........................................143
+ 14.42 Upgrade ..................................................144
+ 14.43 User-Agent ...............................................145
+ 14.44 Vary .....................................................145
+ 14.45 Via ......................................................146
+ 14.46 Warning ..................................................148
+ 14.47 WWW-Authenticate .........................................150
+ 15 Security Considerations .......................................150
+ 15.1 Personal Information....................................151
+ 15.1.1 Abuse of Server Log Information .........................151
+ 15.1.2 Transfer of Sensitive Information .......................151
+ 15.1.3 Encoding Sensitive Information in URI's .................152
+ 15.1.4 Privacy Issues Connected to Accept Headers ..............152
+ 15.2 Attacks Based On File and Path Names .......................153
+ 15.3 DNS Spoofing ...............................................154
+ 15.4 Location Headers and Spoofing ..............................154
+ 15.5 Content-Disposition Issues .................................154
+ 15.6 Authentication Credentials and Idle Clients ................155
+ 15.7 Proxies and Caching ........................................155
+ 15.7.1 Denial of Service Attacks on Proxies....................156
+ 16 Acknowledgments .............................................156
+ 17 References ..................................................158
+ 18 Authors' Addresses ..........................................162
+ 19 Appendices ..................................................164
+ 19.1 Internet Media Type message/http and application/http ......164
+ 19.2 Internet Media Type multipart/byteranges ...................165
+ 19.3 Tolerant Applications ......................................166
+ 19.4 Differences Between HTTP Entities and RFC 2045 Entities ....167
+
+
+
+Fielding, et al. Standards Track [Page 6]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 19.4.1 MIME-Version ............................................167
+ 19.4.2 Conversion to Canonical Form ............................167
+ 19.4.3 Conversion of Date Formats ..............................168
+ 19.4.4 Introduction of Content-Encoding ........................168
+ 19.4.5 No Content-Transfer-Encoding ............................168
+ 19.4.6 Introduction of Transfer-Encoding .......................169
+ 19.4.7 MHTML and Line Length Limitations .......................169
+ 19.5 Additional Features ........................................169
+ 19.5.1 Content-Disposition .....................................170
+ 19.6 Compatibility with Previous Versions .......................170
+ 19.6.1 Changes from HTTP/1.0 ...................................171
+ 19.6.2 Compatibility with HTTP/1.0 Persistent Connections ......172
+ 19.6.3 Changes from RFC 2068 ...................................172
+ 20 Index .......................................................175
+ 21 Full Copyright Statement ....................................176
+
+1 Introduction
+
+1.1 Purpose
+
+ The Hypertext Transfer Protocol (HTTP) is an application-level
+ protocol for distributed, collaborative, hypermedia information
+ systems. HTTP has been in use by the World-Wide Web global
+ information initiative since 1990. The first version of HTTP,
+ referred to as HTTP/0.9, was a simple protocol for raw data transfer
+ across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved
+ the protocol by allowing messages to be in the format of MIME-like
+ messages, containing metainformation about the data transferred and
+ modifiers on the request/response semantics. However, HTTP/1.0 does
+ not sufficiently take into consideration the effects of hierarchical
+ proxies, caching, the need for persistent connections, or virtual
+ hosts. In addition, the proliferation of incompletely-implemented
+ applications calling themselves "HTTP/1.0" has necessitated a
+ protocol version change in order for two communicating applications
+ to determine each other's true capabilities.
+
+ This specification defines the protocol referred to as "HTTP/1.1".
+ This protocol includes more stringent requirements than HTTP/1.0 in
+ order to ensure reliable implementation of its features.
+
+ Practical information systems require more functionality than simple
+ retrieval, including search, front-end update, and annotation. HTTP
+ allows an open-ended set of methods and headers that indicate the
+ purpose of a request [47]. It builds on the discipline of reference
+ provided by the Uniform Resource Identifier (URI) [3], as a location
+ (URL) [4] or name (URN) [20], for indicating the resource to which a
+
+
+
+
+
+Fielding, et al. Standards Track [Page 7]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ method is to be applied. Messages are passed in a format similar to
+ that used by Internet mail [9] as defined by the Multipurpose
+ Internet Mail Extensions (MIME) [7].
+
+ HTTP is also used as a generic protocol for communication between
+ user agents and proxies/gateways to other Internet systems, including
+ those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2],
+ and WAIS [10] protocols. In this way, HTTP allows basic hypermedia
+ access to resources available from diverse applications.
+
+1.2 Requirements
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119 [34].
+
+ An implementation is not compliant if it fails to satisfy one or more
+ of the MUST or REQUIRED level requirements for the protocols it
+ implements. An implementation that satisfies all the MUST or REQUIRED
+ level and all the SHOULD level requirements for its protocols is said
+ to be "unconditionally compliant"; one that satisfies all the MUST
+ level requirements but not all the SHOULD level requirements for its
+ protocols is said to be "conditionally compliant."
+
+1.3 Terminology
+
+ This specification uses a number of terms to refer to the roles
+ played by participants in, and objects of, the HTTP communication.
+
+ connection
+ A transport layer virtual circuit established between two programs
+ for the purpose of communication.
+
+ message
+ The basic unit of HTTP communication, consisting of a structured
+ sequence of octets matching the syntax defined in section 4 and
+ transmitted via the connection.
+
+ request
+ An HTTP request message, as defined in section 5.
+
+ response
+ An HTTP response message, as defined in section 6.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 8]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ resource
+ A network data object or service that can be identified by a URI,
+ as defined in section 3.2. Resources may be available in multiple
+ representations (e.g. multiple languages, data formats, size, and
+ resolutions) or vary in other ways.
+
+ entity
+ The information transferred as the payload of a request or
+ response. An entity consists of metainformation in the form of
+ entity-header fields and content in the form of an entity-body, as
+ described in section 7.
+
+ representation
+ An entity included with a response that is subject to content
+ negotiation, as described in section 12. There may exist multiple
+ representations associated with a particular response status.
+
+ content negotiation
+ The mechanism for selecting the appropriate representation when
+ servicing a request, as described in section 12. The
+ representation of entities in any response can be negotiated
+ (including error responses).
+
+ variant
+ A resource may have one, or more than one, representation(s)
+ associated with it at any given instant. Each of these
+ representations is termed a `varriant'. Use of the term `variant'
+ does not necessarily imply that the resource is subject to content
+ negotiation.
+
+ client
+ A program that establishes connections for the purpose of sending
+ requests.
+
+ user agent
+ The client which initiates a request. These are often browsers,
+ editors, spiders (web-traversing robots), or other end user tools.
+
+ server
+ An application program that accepts connections in order to
+ service requests by sending back responses. Any given program may
+ be capable of being both a client and a server; our use of these
+ terms refers only to the role being performed by the program for a
+ particular connection, rather than to the program's capabilities
+ in general. Likewise, any server may act as an origin server,
+ proxy, gateway, or tunnel, switching behavior based on the nature
+ of each request.
+
+
+
+
+Fielding, et al. Standards Track [Page 9]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ origin server
+ The server on which a given resource resides or is to be created.
+
+ proxy
+ An intermediary program which acts as both a server and a client
+ for the purpose of making requests on behalf of other clients.
+ Requests are serviced internally or by passing them on, with
+ possible translation, to other servers. A proxy MUST implement
+ both the client and server requirements of this specification. A
+ "transparent proxy" is a proxy that does not modify the request or
+ response beyond what is required for proxy authentication and
+ identification. A "non-transparent proxy" is a proxy that modifies
+ the request or response in order to provide some added service to
+ the user agent, such as group annotation services, media type
+ transformation, protocol reduction, or anonymity filtering. Except
+ where either transparent or non-transparent behavior is explicitly
+ stated, the HTTP proxy requirements apply to both types of
+ proxies.
+
+ gateway
+ A server which acts as an intermediary for some other server.
+ Unlike a proxy, a gateway receives requests as if it were the
+ origin server for the requested resource; the requesting client
+ may not be aware that it is communicating with a gateway.
+
+ tunnel
+ An intermediary program which is acting as a blind relay between
+ two connections. Once active, a tunnel is not considered a party
+ to the HTTP communication, though the tunnel may have been
+ initiated by an HTTP request. The tunnel ceases to exist when both
+ ends of the relayed connections are closed.
+
+ cache
+ A program's local store of response messages and the subsystem
+ that controls its message storage, retrieval, and deletion. A
+ cache stores cacheable responses in order to reduce the response
+ time and network bandwidth consumption on future, equivalent
+ requests. Any client or server may include a cache, though a cache
+ cannot be used by a server that is acting as a tunnel.
+
+ cacheable
+ A response is cacheable if a cache is allowed to store a copy of
+ the response message for use in answering subsequent requests. The
+ rules for determining the cacheability of HTTP responses are
+ defined in section 13. Even if a resource is cacheable, there may
+ be additional constraints on whether a cache can use the cached
+ copy for a particular request.
+
+
+
+
+Fielding, et al. Standards Track [Page 10]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ first-hand
+ A response is first-hand if it comes directly and without
+ unnecessary delay from the origin server, perhaps via one or more
+ proxies. A response is also first-hand if its validity has just
+ been checked directly with the origin server.
+
+ explicit expiration time
+ The time at which the origin server intends that an entity should
+ no longer be returned by a cache without further validation.
+
+ heuristic expiration time
+ An expiration time assigned by a cache when no explicit expiration
+ time is available.
+
+ age
+ The age of a response is the time since it was sent by, or
+ successfully validated with, the origin server.
+
+ freshness lifetime
+ The length of time between the generation of a response and its
+ expiration time.
+
+ fresh
+ A response is fresh if its age has not yet exceeded its freshness
+ lifetime.
+
+ stale
+ A response is stale if its age has passed its freshness lifetime.
+
+ semantically transparent
+ A cache behaves in a "semantically transparent" manner, with
+ respect to a particular response, when its use affects neither the
+ requesting client nor the origin server, except to improve
+ performance. When a cache is semantically transparent, the client
+ receives exactly the same response (except for hop-by-hop headers)
+ that it would have received had its request been handled directly
+ by the origin server.
+
+ validator
+ A protocol element (e.g., an entity tag or a Last-Modified time)
+ that is used to find out whether a cache entry is an equivalent
+ copy of an entity.
+
+ upstream/downstream
+ Upstream and downstream describe the flow of a message: all
+ messages flow from upstream to downstream.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 11]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ inbound/outbound
+ Inbound and outbound refer to the request and response paths for
+ messages: "inbound" means "traveling toward the origin server",
+ and "outbound" means "traveling toward the user agent"
+
+1.4 Overall Operation
+
+ The HTTP protocol is a request/response protocol. A client sends a
+ request to the server in the form of a request method, URI, and
+ protocol version, followed by a MIME-like message containing request
+ modifiers, client information, and possible body content over a
+ connection with a server. The server responds with a status line,
+ including the message's protocol version and a success or error code,
+ followed by a MIME-like message containing server information, entity
+ metainformation, and possible entity-body content. The relationship
+ between HTTP and MIME is described in appendix 19.4.
+
+ Most HTTP communication is initiated by a user agent and consists of
+ a request to be applied to a resource on some origin server. In the
+ simplest case, this may be accomplished via a single connection (v)
+ between the user agent (UA) and the origin server (O).
+
+ request chain ------------------------>
+ UA -------------------v------------------- O
+ <----------------------- response chain
+
+ A more complicated situation occurs when one or more intermediaries
+ are present in the request/response chain. There are three common
+ forms of intermediary: proxy, gateway, and tunnel. A proxy is a
+ forwarding agent, receiving requests for a URI in its absolute form,
+ rewriting all or part of the message, and forwarding the reformatted
+ request toward the server identified by the URI. A gateway is a
+ receiving agent, acting as a layer above some other server(s) and, if
+ necessary, translating the requests to the underlying server's
+ protocol. A tunnel acts as a relay point between two connections
+ without changing the messages; tunnels are used when the
+ communication needs to pass through an intermediary (such as a
+ firewall) even when the intermediary cannot understand the contents
+ of the messages.
+
+ request chain -------------------------------------->
+ UA -----v----- A -----v----- B -----v----- C -----v----- O
+ <------------------------------------- response chain
+
+ The figure above shows three intermediaries (A, B, and C) between the
+ user agent and origin server. A request or response message that
+ travels the whole chain will pass through four separate connections.
+ This distinction is important because some HTTP communication options
+
+
+
+Fielding, et al. Standards Track [Page 12]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ may apply only to the connection with the nearest, non-tunnel
+ neighbor, only to the end-points of the chain, or to all connections
+ along the chain. Although the diagram is linear, each participant may
+ be engaged in multiple, simultaneous communications. For example, B
+ may be receiving requests from many clients other than A, and/or
+ forwarding requests to servers other than C, at the same time that it
+ is handling A's request.
+
+ Any party to the communication which is not acting as a tunnel may
+ employ an internal cache for handling requests. The effect of a cache
+ is that the request/response chain is shortened if one of the
+ participants along the chain has a cached response applicable to that
+ request. The following illustrates the resulting chain if B has a
+ cached copy of an earlier response from O (via C) for a request which
+ has not been cached by UA or A.
+
+ request chain ---------->
+ UA -----v----- A -----v----- B - - - - - - C - - - - - - O
+ <--------- response chain
+
+ Not all responses are usefully cacheable, and some requests may
+ contain modifiers which place special requirements on cache behavior.
+ HTTP requirements for cache behavior and cacheable responses are
+ defined in section 13.
+
+ In fact, there are a wide variety of architectures and configurations
+ of caches and proxies currently being experimented with or deployed
+ across the World Wide Web. These systems include national hierarchies
+ of proxy caches to save transoceanic bandwidth, systems that
+ broadcast or multicast cache entries, organizations that distribute
+ subsets of cached data via CD-ROM, and so on. HTTP systems are used
+ in corporate intranets over high-bandwidth links, and for access via
+ PDAs with low-power radio links and intermittent connectivity. The
+ goal of HTTP/1.1 is to support the wide diversity of configurations
+ already deployed while introducing protocol constructs that meet the
+ needs of those who build web applications that require high
+ reliability and, failing that, at least reliable indications of
+ failure.
+
+ HTTP communication usually takes place over TCP/IP connections. The
+ default port is TCP 80 [19], but other ports can be used. This does
+ not preclude HTTP from being implemented on top of any other protocol
+ on the Internet, or on other networks. HTTP only presumes a reliable
+ transport; any protocol that provides such guarantees can be used;
+ the mapping of the HTTP/1.1 request and response structures onto the
+ transport data units of the protocol in question is outside the scope
+ of this specification.
+
+
+
+
+Fielding, et al. Standards Track [Page 13]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ In HTTP/1.0, most implementations used a new connection for each
+ request/response exchange. In HTTP/1.1, a connection may be used for
+ one or more request/response exchanges, although connections may be
+ closed for a variety of reasons (see section 8.1).
+
+2 Notational Conventions and Generic Grammar
+
+2.1 Augmented BNF
+
+ All of the mechanisms specified in this document are described in
+ both prose and an augmented Backus-Naur Form (BNF) similar to that
+ used by RFC 822 [9]. Implementors will need to be familiar with the
+ notation in order to understand this specification. The augmented BNF
+ includes the following constructs:
+
+ name = definition
+ The name of a rule is simply the name itself (without any
+ enclosing "<" and ">") and is separated from its definition by the
+ equal "=" character. White space is only significant in that
+ indentation of continuation lines is used to indicate a rule
+ definition that spans more than one line. Certain basic rules are
+ in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle
+ brackets are used within definitions whenever their presence will
+ facilitate discerning the use of rule names.
+
+ "literal"
+ Quotation marks surround literal text. Unless stated otherwise,
+ the text is case-insensitive.
+
+ rule1 | rule2
+ Elements separated by a bar ("|") are alternatives, e.g., "yes |
+ no" will accept yes or no.
+
+ (rule1 rule2)
+ Elements enclosed in parentheses are treated as a single element.
+ Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
+ foo elem" and "elem bar elem".
+
+ *rule
+ The character "*" preceding an element indicates repetition. The
+ full form is "<n>*<m>element" indicating at least <n> and at most
+ <m> occurrences of element. Default values are 0 and infinity so
+ that "*(element)" allows any number, including zero; "1*element"
+ requires at least one; and "1*2element" allows one or two.
+
+ [rule]
+ Square brackets enclose optional elements; "[foo bar]" is
+ equivalent to "*1(foo bar)".
+
+
+
+Fielding, et al. Standards Track [Page 14]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ N rule
+ Specific repetition: "<n>(element)" is equivalent to
+ "<n>*<n>(element)"; that is, exactly <n> occurrences of (element).
+ Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three
+ alphabetic characters.
+
+ #rule
+ A construct "#" is defined, similar to "*", for defining lists of
+ elements. The full form is "<n>#<m>element" indicating at least
+ <n> and at most <m> elements, each separated by one or more commas
+ (",") and OPTIONAL linear white space (LWS). This makes the usual
+ form of lists very easy; a rule such as
+ ( *LWS element *( *LWS "," *LWS element ))
+ can be shown as
+ 1#element
+ Wherever this construct is used, null elements are allowed, but do
+ not contribute to the count of elements present. That is,
+ "(element), , (element) " is permitted, but counts as only two
+ elements. Therefore, where at least one element is required, at
+ least one non-null element MUST be present. Default values are 0
+ and infinity so that "#element" allows any number, including zero;
+ "1#element" requires at least one; and "1#2element" allows one or
+ two.
+
+ ; comment
+ A semi-colon, set off some distance to the right of rule text,
+ starts a comment that continues to the end of line. This is a
+ simple way of including useful notes in parallel with the
+ specifications.
+
+ implied *LWS
+ The grammar described by this specification is word-based. Except
+ where noted otherwise, linear white space (LWS) can be included
+ between any two adjacent words (token or quoted-string), and
+ between adjacent words and separators, without changing the
+ interpretation of a field. At least one delimiter (LWS and/or
+
+ separators) MUST exist between any two tokens (for the definition
+ of "token" below), since they would otherwise be interpreted as a
+ single token.
+
+2.2 Basic Rules
+
+ The following rules are used throughout this specification to
+ describe basic parsing constructs. The US-ASCII coded character set
+ is defined by ANSI X3.4-1986 [21].
+
+
+
+
+
+Fielding, et al. Standards Track [Page 15]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ OCTET = <any 8-bit sequence of data>
+ CHAR = <any US-ASCII character (octets 0 - 127)>
+ UPALPHA = <any US-ASCII uppercase letter "A".."Z">
+ LOALPHA = <any US-ASCII lowercase letter "a".."z">
+ ALPHA = UPALPHA | LOALPHA
+ DIGIT = <any US-ASCII digit "0".."9">
+ CTL = <any US-ASCII control character
+ (octets 0 - 31) and DEL (127)>
+ CR = <US-ASCII CR, carriage return (13)>
+ LF = <US-ASCII LF, linefeed (10)>
+ SP = <US-ASCII SP, space (32)>
+ HT = <US-ASCII HT, horizontal-tab (9)>
+ <"> = <US-ASCII double-quote mark (34)>
+
+ HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
+ protocol elements except the entity-body (see appendix 19.3 for
+ tolerant applications). The end-of-line marker within an entity-body
+ is defined by its associated media type, as described in section 3.7.
+
+ CRLF = CR LF
+
+ HTTP/1.1 header field values can be folded onto multiple lines if the
+ continuation line begins with a space or horizontal tab. All linear
+ white space, including folding, has the same semantics as SP. A
+ recipient MAY replace any linear white space with a single SP before
+ interpreting the field value or forwarding the message downstream.
+
+ LWS = [CRLF] 1*( SP | HT )
+
+ The TEXT rule is only used for descriptive field contents and values
+ that are not intended to be interpreted by the message parser. Words
+ of *TEXT MAY contain characters from character sets other than ISO-
+ 8859-1 [22] only when encoded according to the rules of RFC 2047
+ [14].
+
+ TEXT = <any OCTET except CTLs,
+ but including LWS>
+
+ A CRLF is allowed in the definition of TEXT only as part of a header
+ field continuation. It is expected that the folding LWS will be
+ replaced with a single SP before interpretation of the TEXT value.
+
+ Hexadecimal numeric characters are used in several protocol elements.
+
+ HEX = "A" | "B" | "C" | "D" | "E" | "F"
+ | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
+
+
+
+
+
+Fielding, et al. Standards Track [Page 16]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Many HTTP/1.1 header field values consist of words separated by LWS
+ or special characters. These special characters MUST be in a quoted
+ string to be used within a parameter value (as defined in section
+ 3.6).
+
+ token = 1*<any CHAR except CTLs or separators>
+ separators = "(" | ")" | "<" | ">" | "@"
+ | "," | ";" | ":" | "\" | <">
+ | "/" | "[" | "]" | "?" | "="
+ | "{" | "}" | SP | HT
+
+ Comments can be included in some HTTP header fields by surrounding
+ the comment text with parentheses. Comments are only allowed in
+ fields containing "comment" as part of their field value definition.
+ In all other fields, parentheses are considered part of the field
+ value.
+
+ comment = "(" *( ctext | quoted-pair | comment ) ")"
+ ctext = <any TEXT excluding "(" and ")">
+
+ A string of text is parsed as a single word if it is quoted using
+ double-quote marks.
+
+ quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
+ qdtext = <any TEXT except <">>
+
+ The backslash character ("\") MAY be used as a single-character
+ quoting mechanism only within quoted-string and comment constructs.
+
+ quoted-pair = "\" CHAR
+
+3 Protocol Parameters
+
+3.1 HTTP Version
+
+ HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
+ of the protocol. The protocol versioning policy is intended to allow
+ the sender to indicate the format of a message and its capacity for
+ understanding further HTTP communication, rather than the features
+ obtained via that communication. No change is made to the version
+ number for the addition of message components which do not affect
+ communication behavior or which only add to extensible field values.
+ The <minor> number is incremented when the changes made to the
+ protocol add features which do not change the general message parsing
+ algorithm, but which may add to the message semantics and imply
+ additional capabilities of the sender. The <major> number is
+ incremented when the format of a message within the protocol is
+ changed. See RFC 2145 [36] for a fuller explanation.
+
+
+
+Fielding, et al. Standards Track [Page 17]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The version of an HTTP message is indicated by an HTTP-Version field
+ in the first line of the message.
+
+ HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
+
+ Note that the major and minor numbers MUST be treated as separate
+ integers and that each MAY be incremented higher than a single digit.
+ Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is
+ lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and
+ MUST NOT be sent.
+
+ An application that sends a request or response message that includes
+ HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant
+ with this specification. Applications that are at least conditionally
+ compliant with this specification SHOULD use an HTTP-Version of
+ "HTTP/1.1" in their messages, and MUST do so for any message that is
+ not compatible with HTTP/1.0. For more details on when to send
+ specific HTTP-Version values, see RFC 2145 [36].
+
+ The HTTP version of an application is the highest HTTP version for
+ which the application is at least conditionally compliant.
+
+ Proxy and gateway applications need to be careful when forwarding
+ messages in protocol versions different from that of the application.
+ Since the protocol version indicates the protocol capability of the
+ sender, a proxy/gateway MUST NOT send a message with a version
+ indicator which is greater than its actual version. If a higher
+ version request is received, the proxy/gateway MUST either downgrade
+ the request version, or respond with an error, or switch to tunnel
+ behavior.
+
+ Due to interoperability problems with HTTP/1.0 proxies discovered
+ since the publication of RFC 2068[33], caching proxies MUST, gateways
+ MAY, and tunnels MUST NOT upgrade the request to the highest version
+ they support. The proxy/gateway's response to that request MUST be in
+ the same major version as the request.
+
+ Note: Converting between versions of HTTP may involve modification
+ of header fields required or forbidden by the versions involved.
+
+3.2 Uniform Resource Identifiers
+
+ URIs have been known by many names: WWW addresses, Universal Document
+ Identifiers, Universal Resource Identifiers [3], and finally the
+ combination of Uniform Resource Locators (URL) [4] and Names (URN)
+ [20]. As far as HTTP is concerned, Uniform Resource Identifiers are
+ simply formatted strings which identify--via name, location, or any
+ other characteristic--a resource.
+
+
+
+Fielding, et al. Standards Track [Page 18]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+3.2.1 General Syntax
+
+ URIs in HTTP can be represented in absolute form or relative to some
+ known base URI [11], depending upon the context of their use. The two
+ forms are differentiated by the fact that absolute URIs always begin
+ with a scheme name followed by a colon. For definitive information on
+ URL syntax and semantics, see "Uniform Resource Identifiers (URI):
+ Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs
+ 1738 [4] and RFC 1808 [11]). This specification adopts the
+ definitions of "URI-reference", "absoluteURI", "relativeURI", "port",
+ "host","abs_path", "rel_path", and "authority" from that
+ specification.
+
+ The HTTP protocol does not place any a priori limit on the length of
+ a URI. Servers MUST be able to handle the URI of any resource they
+ serve, and SHOULD be able to handle URIs of unbounded length if they
+ provide GET-based forms that could generate such URIs. A server
+ SHOULD return 414 (Request-URI Too Long) status if a URI is longer
+ than the server can handle (see section 10.4.15).
+
+ Note: Servers ought to be cautious about depending on URI lengths
+ above 255 bytes, because some older client or proxy
+ implementations might not properly support these lengths.
+
+3.2.2 http URL
+
+ The "http" scheme is used to locate network resources via the HTTP
+ protocol. This section defines the scheme-specific syntax and
+ semantics for http URLs.
+
+ http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
+
+ If the port is empty or not given, port 80 is assumed. The semantics
+ are that the identified resource is located at the server listening
+ for TCP connections on that port of that host, and the Request-URI
+ for the resource is abs_path (section 5.1.2). The use of IP addresses
+ in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If
+ the abs_path is not present in the URL, it MUST be given as "/" when
+ used as a Request-URI for a resource (section 5.1.2). If a proxy
+ receives a host name which is not a fully qualified domain name, it
+ MAY add its domain to the host name it received. If a proxy receives
+ a fully qualified domain name, the proxy MUST NOT change the host
+ name.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 19]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+3.2.3 URI Comparison
+
+ When comparing two URIs to decide if they match or not, a client
+ SHOULD use a case-sensitive octet-by-octet comparison of the entire
+ URIs, with these exceptions:
+
+ - A port that is empty or not given is equivalent to the default
+ port for that URI-reference;
+
+ - Comparisons of host names MUST be case-insensitive;
+
+ - Comparisons of scheme names MUST be case-insensitive;
+
+ - An empty abs_path is equivalent to an abs_path of "/".
+
+ Characters other than those in the "reserved" and "unsafe" sets (see
+ RFC 2396 [42]) are equivalent to their ""%" HEX HEX" encoding.
+
+ For example, the following three URIs are equivalent:
+
+ http://abc.com:80/~smith/home.html
+ http://ABC.com/%7Esmith/home.html
+ http://ABC.com:/%7esmith/home.html
+
+3.3 Date/Time Formats
+
+3.3.1 Full Date
+
+ HTTP applications have historically allowed three different formats
+ for the representation of date/time stamps:
+
+ Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
+ Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
+ Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
+
+ The first format is preferred as an Internet standard and represents
+ a fixed-length subset of that defined by RFC 1123 [8] (an update to
+ RFC 822 [9]). The second format is in common use, but is based on the
+ obsolete RFC 850 [12] date format and lacks a four-digit year.
+ HTTP/1.1 clients and servers that parse the date value MUST accept
+ all three formats (for compatibility with HTTP/1.0), though they MUST
+ only generate the RFC 1123 format for representing HTTP-date values
+ in header fields. See section 19.3 for further information.
+
+ Note: Recipients of date values are encouraged to be robust in
+ accepting date values that may have been sent by non-HTTP
+ applications, as is sometimes the case when retrieving or posting
+ messages via proxies/gateways to SMTP or NNTP.
+
+
+
+Fielding, et al. Standards Track [Page 20]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ All HTTP date/time stamps MUST be represented in Greenwich Mean Time
+ (GMT), without exception. For the purposes of HTTP, GMT is exactly
+ equal to UTC (Coordinated Universal Time). This is indicated in the
+ first two formats by the inclusion of "GMT" as the three-letter
+ abbreviation for time zone, and MUST be assumed when reading the
+ asctime format. HTTP-date is case sensitive and MUST NOT include
+ additional LWS beyond that specifically included as SP in the
+ grammar.
+
+ HTTP-date = rfc1123-date | rfc850-date | asctime-date
+ rfc1123-date = wkday "," SP date1 SP time SP "GMT"
+ rfc850-date = weekday "," SP date2 SP time SP "GMT"
+ asctime-date = wkday SP date3 SP time SP 4DIGIT
+ date1 = 2DIGIT SP month SP 4DIGIT
+ ; day month year (e.g., 02 Jun 1982)
+ date2 = 2DIGIT "-" month "-" 2DIGIT
+ ; day-month-year (e.g., 02-Jun-82)
+ date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
+ ; month day (e.g., Jun 2)
+ time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
+ ; 00:00:00 - 23:59:59
+ wkday = "Mon" | "Tue" | "Wed"
+ | "Thu" | "Fri" | "Sat" | "Sun"
+ weekday = "Monday" | "Tuesday" | "Wednesday"
+ | "Thursday" | "Friday" | "Saturday" | "Sunday"
+ month = "Jan" | "Feb" | "Mar" | "Apr"
+ | "May" | "Jun" | "Jul" | "Aug"
+ | "Sep" | "Oct" | "Nov" | "Dec"
+
+ Note: HTTP requirements for the date/time stamp format apply only
+ to their usage within the protocol stream. Clients and servers are
+ not required to use these formats for user presentation, request
+ logging, etc.
+
+3.3.2 Delta Seconds
+
+ Some HTTP header fields allow a time value to be specified as an
+ integer number of seconds, represented in decimal, after the time
+ that the message was received.
+
+ delta-seconds = 1*DIGIT
+
+3.4 Character Sets
+
+ HTTP uses the same definition of the term "character set" as that
+ described for MIME:
+
+
+
+
+
+Fielding, et al. Standards Track [Page 21]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The term "character set" is used in this document to refer to a
+ method used with one or more tables to convert a sequence of octets
+ into a sequence of characters. Note that unconditional conversion in
+ the other direction is not required, in that not all characters may
+ be available in a given character set and a character set may provide
+ more than one sequence of octets to represent a particular character.
+ This definition is intended to allow various kinds of character
+ encoding, from simple single-table mappings such as US-ASCII to
+ complex table switching methods such as those that use ISO-2022's
+ techniques. However, the definition associated with a MIME character
+ set name MUST fully specify the mapping to be performed from octets
+ to characters. In particular, use of external profiling information
+ to determine the exact mapping is not permitted.
+
+ Note: This use of the term "character set" is more commonly
+ referred to as a "character encoding." However, since HTTP and
+ MIME share the same registry, it is important that the terminology
+ also be shared.
+
+ HTTP character sets are identified by case-insensitive tokens. The
+ complete set of tokens is defined by the IANA Character Set registry
+ [19].
+
+ charset = token
+
+ Although HTTP allows an arbitrary token to be used as a charset
+ value, any token that has a predefined value within the IANA
+ Character Set registry [19] MUST represent the character set defined
+ by that registry. Applications SHOULD limit their use of character
+ sets to those defined by the IANA registry.
+
+ Implementors should be aware of IETF character set requirements [38]
+ [41].
+
+3.4.1 Missing Charset
+
+ Some HTTP/1.0 software has interpreted a Content-Type header without
+ charset parameter incorrectly to mean "recipient should guess."
+ Senders wishing to defeat this behavior MAY include a charset
+ parameter even when the charset is ISO-8859-1 and SHOULD do so when
+ it is known that it will not confuse the recipient.
+
+ Unfortunately, some older HTTP/1.0 clients did not deal properly with
+ an explicit charset parameter. HTTP/1.1 recipients MUST respect the
+ charset label provided by the sender; and those user agents that have
+ a provision to "guess" a charset MUST use the charset from the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 22]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ content-type field if they support that charset, rather than the
+ recipient's preference, when initially displaying a document. See
+ section 3.7.1.
+
+3.5 Content Codings
+
+ Content coding values indicate an encoding transformation that has
+ been or can be applied to an entity. Content codings are primarily
+ used to allow a document to be compressed or otherwise usefully
+ transformed without losing the identity of its underlying media type
+ and without loss of information. Frequently, the entity is stored in
+ coded form, transmitted directly, and only decoded by the recipient.
+
+ content-coding = token
+
+ All content-coding values are case-insensitive. HTTP/1.1 uses
+ content-coding values in the Accept-Encoding (section 14.3) and
+ Content-Encoding (section 14.11) header fields. Although the value
+ describes the content-coding, what is more important is that it
+ indicates what decoding mechanism will be required to remove the
+ encoding.
+
+ The Internet Assigned Numbers Authority (IANA) acts as a registry for
+ content-coding value tokens. Initially, the registry contains the
+ following tokens:
+
+ gzip An encoding format produced by the file compression program
+ "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a
+ Lempel-Ziv coding (LZ77) with a 32 bit CRC.
+
+ compress
+ The encoding format produced by the common UNIX file compression
+ program "compress". This format is an adaptive Lempel-Ziv-Welch
+ coding (LZW).
+
+ Use of program names for the identification of encoding formats
+ is not desirable and is discouraged for future encodings. Their
+ use here is representative of historical practice, not good
+ design. For compatibility with previous implementations of HTTP,
+ applications SHOULD consider "x-gzip" and "x-compress" to be
+ equivalent to "gzip" and "compress" respectively.
+
+ deflate
+ The "zlib" format defined in RFC 1950 [31] in combination with
+ the "deflate" compression mechanism described in RFC 1951 [29].
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 23]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ identity
+ The default (identity) encoding; the use of no transformation
+ whatsoever. This content-coding is used only in the Accept-
+ Encoding header, and SHOULD NOT be used in the Content-Encoding
+ header.
+
+ New content-coding value tokens SHOULD be registered; to allow
+ interoperability between clients and servers, specifications of the
+ content coding algorithms needed to implement a new value SHOULD be
+ publicly available and adequate for independent implementation, and
+ conform to the purpose of content coding defined in this section.
+
+3.6 Transfer Codings
+
+ Transfer-coding values are used to indicate an encoding
+ transformation that has been, can be, or may need to be applied to an
+ entity-body in order to ensure "safe transport" through the network.
+ This differs from a content coding in that the transfer-coding is a
+ property of the message, not of the original entity.
+
+ transfer-coding = "chunked" | transfer-extension
+ transfer-extension = token *( ";" parameter )
+
+ Parameters are in the form of attribute/value pairs.
+
+ parameter = attribute "=" value
+ attribute = token
+ value = token | quoted-string
+
+ All transfer-coding values are case-insensitive. HTTP/1.1 uses
+ transfer-coding values in the TE header field (section 14.39) and in
+ the Transfer-Encoding header field (section 14.41).
+
+ Whenever a transfer-coding is applied to a message-body, the set of
+ transfer-codings MUST include "chunked", unless the message is
+ terminated by closing the connection. When the "chunked" transfer-
+ coding is used, it MUST be the last transfer-coding applied to the
+ message-body. The "chunked" transfer-coding MUST NOT be applied more
+ than once to a message-body. These rules allow the recipient to
+ determine the transfer-length of the message (section 4.4).
+
+ Transfer-codings are analogous to the Content-Transfer-Encoding
+ values of MIME [7], which were designed to enable safe transport of
+ binary data over a 7-bit transport service. However, safe transport
+ has a different focus for an 8bit-clean transfer protocol. In HTTP,
+ the only unsafe characteristic of message-bodies is the difficulty in
+ determining the exact body length (section 7.2.2), or the desire to
+ encrypt data over a shared transport.
+
+
+
+Fielding, et al. Standards Track [Page 24]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Internet Assigned Numbers Authority (IANA) acts as a registry for
+ transfer-coding value tokens. Initially, the registry contains the
+ following tokens: "chunked" (section 3.6.1), "identity" (section
+ 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate"
+ (section 3.5).
+
+ New transfer-coding value tokens SHOULD be registered in the same way
+ as new content-coding value tokens (section 3.5).
+
+ A server which receives an entity-body with a transfer-coding it does
+ not understand SHOULD return 501 (Unimplemented), and close the
+ connection. A server MUST NOT send transfer-codings to an HTTP/1.0
+ client.
+
+3.6.1 Chunked Transfer Coding
+
+ The chunked encoding modifies the body of a message in order to
+ transfer it as a series of chunks, each with its own size indicator,
+ followed by an OPTIONAL trailer containing entity-header fields. This
+ allows dynamically produced content to be transferred along with the
+ information necessary for the recipient to verify that it has
+ received the full message.
+
+ Chunked-Body = *chunk
+ last-chunk
+ trailer
+ CRLF
+
+ chunk = chunk-size [ chunk-extension ] CRLF
+ chunk-data CRLF
+ chunk-size = 1*HEX
+ last-chunk = 1*("0") [ chunk-extension ] CRLF
+
+ chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
+ chunk-ext-name = token
+ chunk-ext-val = token | quoted-string
+ chunk-data = chunk-size(OCTET)
+ trailer = *(entity-header CRLF)
+
+ The chunk-size field is a string of hex digits indicating the size of
+ the chunk. The chunked encoding is ended by any chunk whose size is
+ zero, followed by the trailer, which is terminated by an empty line.
+
+ The trailer allows the sender to include additional HTTP header
+ fields at the end of the message. The Trailer header field can be
+ used to indicate which header fields are included in a trailer (see
+ section 14.40).
+
+
+
+
+Fielding, et al. Standards Track [Page 25]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A server using chunked transfer-coding in a response MUST NOT use the
+ trailer for any header fields unless at least one of the following is
+ true:
+
+ a)the request included a TE header field that indicates "trailers" is
+ acceptable in the transfer-coding of the response, as described in
+ section 14.39; or,
+
+ b)the server is the origin server for the response, the trailer
+ fields consist entirely of optional metadata, and the recipient
+ could use the message (in a manner acceptable to the origin server)
+ without receiving this metadata. In other words, the origin server
+ is willing to accept the possibility that the trailer fields might
+ be silently discarded along the path to the client.
+
+ This requirement prevents an interoperability failure when the
+ message is being received by an HTTP/1.1 (or later) proxy and
+ forwarded to an HTTP/1.0 recipient. It avoids a situation where
+ compliance with the protocol would have necessitated a possibly
+ infinite buffer on the proxy.
+
+ An example process for decoding a Chunked-Body is presented in
+ appendix 19.4.6.
+
+ All HTTP/1.1 applications MUST be able to receive and decode the
+ "chunked" transfer-coding, and MUST ignore chunk-extension extensions
+ they do not understand.
+
+3.7 Media Types
+
+ HTTP uses Internet Media Types [17] in the Content-Type (section
+ 14.17) and Accept (section 14.1) header fields in order to provide
+ open and extensible data typing and type negotiation.
+
+ media-type = type "/" subtype *( ";" parameter )
+ type = token
+ subtype = token
+
+ Parameters MAY follow the type/subtype in the form of attribute/value
+ pairs (as defined in section 3.6).
+
+ The type, subtype, and parameter attribute names are case-
+ insensitive. Parameter values might or might not be case-sensitive,
+ depending on the semantics of the parameter name. Linear white space
+ (LWS) MUST NOT be used between the type and subtype, nor between an
+ attribute and its value. The presence or absence of a parameter might
+ be significant to the processing of a media-type, depending on its
+ definition within the media type registry.
+
+
+
+Fielding, et al. Standards Track [Page 26]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note that some older HTTP applications do not recognize media type
+ parameters. When sending data to older HTTP applications,
+ implementations SHOULD only use media type parameters when they are
+ required by that type/subtype definition.
+
+ Media-type values are registered with the Internet Assigned Number
+ Authority (IANA [19]). The media type registration process is
+ outlined in RFC 1590 [17]. Use of non-registered media types is
+ discouraged.
+
+3.7.1 Canonicalization and Text Defaults
+
+ Internet media types are registered with a canonical form. An
+ entity-body transferred via HTTP messages MUST be represented in the
+ appropriate canonical form prior to its transmission except for
+ "text" types, as defined in the next paragraph.
+
+ When in canonical form, media subtypes of the "text" type use CRLF as
+ the text line break. HTTP relaxes this requirement and allows the
+ transport of text media with plain CR or LF alone representing a line
+ break when it is done consistently for an entire entity-body. HTTP
+ applications MUST accept CRLF, bare CR, and bare LF as being
+ representative of a line break in text media received via HTTP. In
+ addition, if the text is represented in a character set that does not
+ use octets 13 and 10 for CR and LF respectively, as is the case for
+ some multi-byte character sets, HTTP allows the use of whatever octet
+ sequences are defined by that character set to represent the
+ equivalent of CR and LF for line breaks. This flexibility regarding
+ line breaks applies only to text media in the entity-body; a bare CR
+ or LF MUST NOT be substituted for CRLF within any of the HTTP control
+ structures (such as header fields and multipart boundaries).
+
+ If an entity-body is encoded with a content-coding, the underlying
+ data MUST be in a form defined above prior to being encoded.
+
+ The "charset" parameter is used with some media types to define the
+ character set (section 3.4) of the data. When no explicit charset
+ parameter is provided by the sender, media subtypes of the "text"
+ type are defined to have a default charset value of "ISO-8859-1" when
+ received via HTTP. Data in character sets other than "ISO-8859-1" or
+ its subsets MUST be labeled with an appropriate charset value. See
+ section 3.4.1 for compatibility problems.
+
+3.7.2 Multipart Types
+
+ MIME provides for a number of "multipart" types -- encapsulations of
+ one or more entities within a single message-body. All multipart
+ types share a common syntax, as defined in section 5.1.1 of RFC 2046
+
+
+
+Fielding, et al. Standards Track [Page 27]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [40], and MUST include a boundary parameter as part of the media type
+ value. The message body is itself a protocol element and MUST
+ therefore use only CRLF to represent line breaks between body-parts.
+ Unlike in RFC 2046, the epilogue of any multipart message MUST be
+ empty; HTTP applications MUST NOT transmit the epilogue (even if the
+ original multipart contains an epilogue). These restrictions exist in
+ order to preserve the self-delimiting nature of a multipart message-
+ body, wherein the "end" of the message-body is indicated by the
+ ending multipart boundary.
+
+ In general, HTTP treats a multipart message-body no differently than
+ any other media type: strictly as payload. The one exception is the
+ "multipart/byteranges" type (appendix 19.2) when it appears in a 206
+ (Partial Content) response, which will be interpreted by some HTTP
+ caching mechanisms as described in sections 13.5.4 and 14.16. In all
+ other cases, an HTTP user agent SHOULD follow the same or similar
+ behavior as a MIME user agent would upon receipt of a multipart type.
+ The MIME header fields within each body-part of a multipart message-
+ body do not have any significance to HTTP beyond that defined by
+ their MIME semantics.
+
+ In general, an HTTP user agent SHOULD follow the same or similar
+ behavior as a MIME user agent would upon receipt of a multipart type.
+ If an application receives an unrecognized multipart subtype, the
+ application MUST treat it as being equivalent to "multipart/mixed".
+
+ Note: The "multipart/form-data" type has been specifically defined
+ for carrying form data suitable for processing via the POST
+ request method, as described in RFC 1867 [15].
+
+3.8 Product Tokens
+
+ Product tokens are used to allow communicating applications to
+ identify themselves by software name and version. Most fields using
+ product tokens also allow sub-products which form a significant part
+ of the application to be listed, separated by white space. By
+ convention, the products are listed in order of their significance
+ for identifying the application.
+
+ product = token ["/" product-version]
+ product-version = token
+
+ Examples:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+ Server: Apache/0.8.4
+
+
+
+
+
+Fielding, et al. Standards Track [Page 28]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Product tokens SHOULD be short and to the point. They MUST NOT be
+ used for advertising or other non-essential information. Although any
+ token character MAY appear in a product-version, this token SHOULD
+ only be used for a version identifier (i.e., successive versions of
+ the same product SHOULD only differ in the product-version portion of
+ the product value).
+
+3.9 Quality Values
+
+ HTTP content negotiation (section 12) uses short "floating point"
+ numbers to indicate the relative importance ("weight") of various
+ negotiable parameters. A weight is normalized to a real number in
+ the range 0 through 1, where 0 is the minimum and 1 the maximum
+ value. If a parameter has a quality value of 0, then content with
+ this parameter is `not acceptable' for the client. HTTP/1.1
+ applications MUST NOT generate more than three digits after the
+ decimal point. User configuration of these values SHOULD also be
+ limited in this fashion.
+
+ qvalue = ( "0" [ "." 0*3DIGIT ] )
+ | ( "1" [ "." 0*3("0") ] )
+
+ "Quality values" is a misnomer, since these values merely represent
+ relative degradation in desired quality.
+
+3.10 Language Tags
+
+ A language tag identifies a natural language spoken, written, or
+ otherwise conveyed by human beings for communication of information
+ to other human beings. Computer languages are explicitly excluded.
+ HTTP uses language tags within the Accept-Language and Content-
+ Language fields.
+
+ The syntax and registry of HTTP language tags is the same as that
+ defined by RFC 1766 [1]. In summary, a language tag is composed of 1
+ or more parts: A primary language tag and a possibly empty series of
+ subtags:
+
+ language-tag = primary-tag *( "-" subtag )
+ primary-tag = 1*8ALPHA
+ subtag = 1*8ALPHA
+
+ White space is not allowed within the tag and all tags are case-
+ insensitive. The name space of language tags is administered by the
+ IANA. Example tags include:
+
+ en, en-US, en-cockney, i-cherokee, x-pig-latin
+
+
+
+
+Fielding, et al. Standards Track [Page 29]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ where any two-letter primary-tag is an ISO-639 language abbreviation
+ and any two-letter initial subtag is an ISO-3166 country code. (The
+ last three tags above are not registered tags; all but the last are
+ examples of tags which could be registered in future.)
+
+3.11 Entity Tags
+
+ Entity tags are used for comparing two or more entities from the same
+ requested resource. HTTP/1.1 uses entity tags in the ETag (section
+ 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and
+ If-Range (section 14.27) header fields. The definition of how they
+ are used and compared as cache validators is in section 13.3.3. An
+ entity tag consists of an opaque quoted string, possibly prefixed by
+ a weakness indicator.
+
+ entity-tag = [ weak ] opaque-tag
+ weak = "W/"
+ opaque-tag = quoted-string
+
+ A "strong entity tag" MAY be shared by two entities of a resource
+ only if they are equivalent by octet equality.
+
+ A "weak entity tag," indicated by the "W/" prefix, MAY be shared by
+ two entities of a resource only if the entities are equivalent and
+ could be substituted for each other with no significant change in
+ semantics. A weak entity tag can only be used for weak comparison.
+
+ An entity tag MUST be unique across all versions of all entities
+ associated with a particular resource. A given entity tag value MAY
+ be used for entities obtained by requests on different URIs. The use
+ of the same entity tag value in conjunction with entities obtained by
+ requests on different URIs does not imply the equivalence of those
+ entities.
+
+3.12 Range Units
+
+ HTTP/1.1 allows a client to request that only part (a range of) the
+ response entity be included within the response. HTTP/1.1 uses range
+ units in the Range (section 14.35) and Content-Range (section 14.16)
+ header fields. An entity can be broken down into subranges according
+ to various structural units.
+
+ range-unit = bytes-unit | other-range-unit
+ bytes-unit = "bytes"
+ other-range-unit = token
+
+ The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
+ implementations MAY ignore ranges specified using other units.
+
+
+
+Fielding, et al. Standards Track [Page 30]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 has been designed to allow implementations of applications
+ that do not depend on knowledge of ranges.
+
+4 HTTP Message
+
+4.1 Message Types
+
+ HTTP messages consist of requests from client to server and responses
+ from server to client.
+
+ HTTP-message = Request | Response ; HTTP/1.1 messages
+
+ Request (section 5) and Response (section 6) messages use the generic
+ message format of RFC 822 [9] for transferring entities (the payload
+ of the message). Both types of message consist of a start-line, zero
+ or more header fields (also known as "headers"), an empty line (i.e.,
+ a line with nothing preceding the CRLF) indicating the end of the
+ header fields, and possibly a message-body.
+
+ generic-message = start-line
+ *(message-header CRLF)
+ CRLF
+ [ message-body ]
+ start-line = Request-Line | Status-Line
+
+ In the interest of robustness, servers SHOULD ignore any empty
+ line(s) received where a Request-Line is expected. In other words, if
+ the server is reading the protocol stream at the beginning of a
+ message and receives a CRLF first, it should ignore the CRLF.
+
+ Certain buggy HTTP/1.0 client implementations generate extra CRLF's
+ after a POST request. To restate what is explicitly forbidden by the
+ BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an
+ extra CRLF.
+
+4.2 Message Headers
+
+ HTTP header fields, which include general-header (section 4.5),
+ request-header (section 5.3), response-header (section 6.2), and
+ entity-header (section 7.1) fields, follow the same generic format as
+ that given in Section 3.1 of RFC 822 [9]. Each header field consists
+ of a name followed by a colon (":") and the field value. Field names
+ are case-insensitive. The field value MAY be preceded by any amount
+ of LWS, though a single SP is preferred. Header fields can be
+ extended over multiple lines by preceding each extra line with at
+ least one SP or HT. Applications ought to follow "common form", where
+ one is known or indicated, when generating HTTP constructs, since
+ there might exist some implementations that fail to accept anything
+
+
+
+Fielding, et al. Standards Track [Page 31]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ beyond the common forms.
+
+ message-header = field-name ":" [ field-value ]
+ field-name = token
+ field-value = *( field-content | LWS )
+ field-content = <the OCTETs making up the field-value
+ and consisting of either *TEXT or combinations
+ of token, separators, and quoted-string>
+
+ The field-content does not include any leading or trailing LWS:
+ linear white space occurring before the first non-whitespace
+ character of the field-value or after the last non-whitespace
+ character of the field-value. Such leading or trailing LWS MAY be
+ removed without changing the semantics of the field value. Any LWS
+ that occurs between field-content MAY be replaced with a single SP
+ before interpreting the field value or forwarding the message
+ downstream.
+
+ The order in which header fields with differing field names are
+ received is not significant. However, it is "good practice" to send
+ general-header fields first, followed by request-header or response-
+ header fields, and ending with the entity-header fields.
+
+ Multiple message-header fields with the same field-name MAY be
+ present in a message if and only if the entire field-value for that
+ header field is defined as a comma-separated list [i.e., #(values)].
+ It MUST be possible to combine the multiple header fields into one
+ "field-name: field-value" pair, without changing the semantics of the
+ message, by appending each subsequent field-value to the first, each
+ separated by a comma. The order in which header fields with the same
+ field-name are received is therefore significant to the
+ interpretation of the combined field value, and thus a proxy MUST NOT
+ change the order of these field values when a message is forwarded.
+
+4.3 Message Body
+
+ The message-body (if any) of an HTTP message is used to carry the
+ entity-body associated with the request or response. The message-body
+ differs from the entity-body only when a transfer-coding has been
+ applied, as indicated by the Transfer-Encoding header field (section
+ 14.41).
+
+ message-body = entity-body
+ | <entity-body encoded as per Transfer-Encoding>
+
+ Transfer-Encoding MUST be used to indicate any transfer-codings
+ applied by an application to ensure safe and proper transfer of the
+ message. Transfer-Encoding is a property of the message, not of the
+
+
+
+Fielding, et al. Standards Track [Page 32]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ entity, and thus MAY be added or removed by any application along the
+ request/response chain. (However, section 3.6 places restrictions on
+ when certain transfer-codings may be used.)
+
+ The rules for when a message-body is allowed in a message differ for
+ requests and responses.
+
+ The presence of a message-body in a request is signaled by the
+ inclusion of a Content-Length or Transfer-Encoding header field in
+ the request's message-headers. A message-body MUST NOT be included in
+ a request if the specification of the request method (section 5.1.1)
+ does not allow sending an entity-body in requests. A server SHOULD
+ read and forward a message-body on any request; if the request method
+ does not include defined semantics for an entity-body, then the
+ message-body SHOULD be ignored when handling the request.
+
+ For response messages, whether or not a message-body is included with
+ a message is dependent on both the request method and the response
+ status code (section 6.1.1). All responses to the HEAD request method
+ MUST NOT include a message-body, even though the presence of entity-
+ header fields might lead one to believe they do. All 1xx
+ (informational), 204 (no content), and 304 (not modified) responses
+ MUST NOT include a message-body. All other responses do include a
+ message-body, although it MAY be of zero length.
+
+4.4 Message Length
+
+ The transfer-length of a message is the length of the message-body as
+ it appears in the message; that is, after any transfer-codings have
+ been applied. When a message-body is included with a message, the
+ transfer-length of that body is determined by one of the following
+ (in order of precedence):
+
+ 1.Any response message which "MUST NOT" include a message-body (such
+ as the 1xx, 204, and 304 responses and any response to a HEAD
+ request) is always terminated by the first empty line after the
+ header fields, regardless of the entity-header fields present in
+ the message.
+
+ 2.If a Transfer-Encoding header field (section 14.41) is present and
+ has any value other than "identity", then the transfer-length is
+ defined by use of the "chunked" transfer-coding (section 3.6),
+ unless the message is terminated by closing the connection.
+
+ 3.If a Content-Length header field (section 14.13) is present, its
+ decimal value in OCTETs represents both the entity-length and the
+ transfer-length. The Content-Length header field MUST NOT be sent
+ if these two lengths are different (i.e., if a Transfer-Encoding
+
+
+
+Fielding, et al. Standards Track [Page 33]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ header field is present). If a message is received with both a
+ Transfer-Encoding header field and a Content-Length header field,
+ the latter MUST be ignored.
+
+ 4.If the message uses the media type "multipart/byteranges", and the
+ ransfer-length is not otherwise specified, then this self-
+ elimiting media type defines the transfer-length. This media type
+ UST NOT be used unless the sender knows that the recipient can arse
+ it; the presence in a request of a Range header with ultiple byte-
+ range specifiers from a 1.1 client implies that the lient can parse
+ multipart/byteranges responses.
+
+ A range header might be forwarded by a 1.0 proxy that does not
+ understand multipart/byteranges; in this case the server MUST
+ delimit the message using methods defined in items 1,3 or 5 of
+ this section.
+
+ 5.By the server closing the connection. (Closing the connection
+ cannot be used to indicate the end of a request body, since that
+ would leave no possibility for the server to send back a response.)
+
+ For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
+ containing a message-body MUST include a valid Content-Length header
+ field unless the server is known to be HTTP/1.1 compliant. If a
+ request contains a message-body and a Content-Length is not given,
+ the server SHOULD respond with 400 (bad request) if it cannot
+ determine the length of the message, or with 411 (length required) if
+ it wishes to insist on receiving a valid Content-Length.
+
+ All HTTP/1.1 applications that receive entities MUST accept the
+ "chunked" transfer-coding (section 3.6), thus allowing this mechanism
+ to be used for messages when the message length cannot be determined
+ in advance.
+
+ Messages MUST NOT include both a Content-Length header field and a
+ non-identity transfer-coding. If the message does include a non-
+ identity transfer-coding, the Content-Length MUST be ignored.
+
+ When a Content-Length is given in a message where a message-body is
+ allowed, its field value MUST exactly match the number of OCTETs in
+ the message-body. HTTP/1.1 user agents MUST notify the user when an
+ invalid length is received and detected.
+
+4.5 General Header Fields
+
+ There are a few header fields which have general applicability for
+ both request and response messages, but which do not apply to the
+ entity being transferred. These header fields apply only to the
+
+
+
+Fielding, et al. Standards Track [Page 34]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ message being transmitted.
+
+ general-header = Cache-Control ; Section 14.9
+ | Connection ; Section 14.10
+ | Date ; Section 14.18
+ | Pragma ; Section 14.32
+ | Trailer ; Section 14.40
+ | Transfer-Encoding ; Section 14.41
+ | Upgrade ; Section 14.42
+ | Via ; Section 14.45
+ | Warning ; Section 14.46
+
+ General-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields may be given the semantics of general
+ header fields if all parties in the communication recognize them to
+ be general-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+5 Request
+
+ A request message from a client to a server includes, within the
+ first line of that message, the method to be applied to the resource,
+ the identifier of the resource, and the protocol version in use.
+
+ Request = Request-Line ; Section 5.1
+ *(( general-header ; Section 4.5
+ | request-header ; Section 5.3
+ | entity-header ) CRLF) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 4.3
+
+5.1 Request-Line
+
+ The Request-Line begins with a method token, followed by the
+ Request-URI and the protocol version, and ending with CRLF. The
+ elements are separated by SP characters. No CR or LF is allowed
+ except in the final CRLF sequence.
+
+ Request-Line = Method SP Request-URI SP HTTP-Version CRLF
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 35]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+5.1.1 Method
+
+ The Method token indicates the method to be performed on the
+ resource identified by the Request-URI. The method is case-sensitive.
+
+ Method = "OPTIONS" ; Section 9.2
+ | "GET" ; Section 9.3
+ | "HEAD" ; Section 9.4
+ | "POST" ; Section 9.5
+ | "PUT" ; Section 9.6
+ | "DELETE" ; Section 9.7
+ | "TRACE" ; Section 9.8
+ | "CONNECT" ; Section 9.9
+ | extension-method
+ extension-method = token
+
+ The list of methods allowed by a resource can be specified in an
+ Allow header field (section 14.7). The return code of the response
+ always notifies the client whether a method is currently allowed on a
+ resource, since the set of allowed methods can change dynamically. An
+ origin server SHOULD return the status code 405 (Method Not Allowed)
+ if the method is known by the origin server but not allowed for the
+ requested resource, and 501 (Not Implemented) if the method is
+ unrecognized or not implemented by the origin server. The methods GET
+ and HEAD MUST be supported by all general-purpose servers. All other
+ methods are OPTIONAL; however, if the above methods are implemented,
+ they MUST be implemented with the same semantics as those specified
+ in section 9.
+
+5.1.2 Request-URI
+
+ The Request-URI is a Uniform Resource Identifier (section 3.2) and
+ identifies the resource upon which to apply the request.
+
+ Request-URI = "*" | absoluteURI | abs_path | authority
+
+ The four options for Request-URI are dependent on the nature of the
+ request. The asterisk "*" means that the request does not apply to a
+ particular resource, but to the server itself, and is only allowed
+ when the method used does not necessarily apply to a resource. One
+ example would be
+
+ OPTIONS * HTTP/1.1
+
+ The absoluteURI form is REQUIRED when the request is being made to a
+ proxy. The proxy is requested to forward the request or service it
+ from a valid cache, and return the response. Note that the proxy MAY
+ forward the request on to another proxy or directly to the server
+
+
+
+Fielding, et al. Standards Track [Page 36]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ specified by the absoluteURI. In order to avoid request loops, a
+ proxy MUST be able to recognize all of its server names, including
+ any aliases, local variations, and the numeric IP address. An example
+ Request-Line would be:
+
+ GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1
+
+ To allow for transition to absoluteURIs in all requests in future
+ versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI
+ form in requests, even though HTTP/1.1 clients will only generate
+ them in requests to proxies.
+
+ The authority form is only used by the CONNECT method (section 9.9).
+
+ The most common form of Request-URI is that used to identify a
+ resource on an origin server or gateway. In this case the absolute
+ path of the URI MUST be transmitted (see section 3.2.1, abs_path) as
+ the Request-URI, and the network location of the URI (authority) MUST
+ be transmitted in a Host header field. For example, a client wishing
+ to retrieve the resource above directly from the origin server would
+ create a TCP connection to port 80 of the host "www.w3.org" and send
+ the lines:
+
+ GET /pub/WWW/TheProject.html HTTP/1.1
+ Host: www.w3.org
+
+ followed by the remainder of the Request. Note that the absolute path
+ cannot be empty; if none is present in the original URI, it MUST be
+ given as "/" (the server root).
+
+ The Request-URI is transmitted in the format specified in section
+ 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding
+ [42], the origin server MUST decode the Request-URI in order to
+ properly interpret the request. Servers SHOULD respond to invalid
+ Request-URIs with an appropriate status code.
+
+ A transparent proxy MUST NOT rewrite the "abs_path" part of the
+ received Request-URI when forwarding it to the next inbound server,
+ except as noted above to replace a null abs_path with "/".
+
+ Note: The "no rewrite" rule prevents the proxy from changing the
+ meaning of the request when the origin server is improperly using
+ a non-reserved URI character for a reserved purpose. Implementors
+ should be aware that some pre-HTTP/1.1 proxies have been known to
+ rewrite the Request-URI.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 37]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+5.2 The Resource Identified by a Request
+
+ The exact resource identified by an Internet request is determined by
+ examining both the Request-URI and the Host header field.
+
+ An origin server that does not allow resources to differ by the
+ requested host MAY ignore the Host header field value when
+ determining the resource identified by an HTTP/1.1 request. (But see
+ section 19.6.1.1 for other requirements on Host support in HTTP/1.1.)
+
+ An origin server that does differentiate resources based on the host
+ requested (sometimes referred to as virtual hosts or vanity host
+ names) MUST use the following rules for determining the requested
+ resource on an HTTP/1.1 request:
+
+ 1. If Request-URI is an absoluteURI, the host is part of the
+ Request-URI. Any Host header field value in the request MUST be
+ ignored.
+
+ 2. If the Request-URI is not an absoluteURI, and the request includes
+ a Host header field, the host is determined by the Host header
+ field value.
+
+ 3. If the host as determined by rule 1 or 2 is not a valid host on
+ the server, the response MUST be a 400 (Bad Request) error message.
+
+ Recipients of an HTTP/1.0 request that lacks a Host header field MAY
+ attempt to use heuristics (e.g., examination of the URI path for
+ something unique to a particular host) in order to determine what
+ exact resource is being requested.
+
+5.3 Request Header Fields
+
+ The request-header fields allow the client to pass additional
+ information about the request, and about the client itself, to the
+ server. These fields act as request modifiers, with semantics
+ equivalent to the parameters on a programming language method
+ invocation.
+
+ request-header = Accept ; Section 14.1
+ | Accept-Charset ; Section 14.2
+ | Accept-Encoding ; Section 14.3
+ | Accept-Language ; Section 14.4
+ | Authorization ; Section 14.8
+ | Expect ; Section 14.20
+ | From ; Section 14.22
+ | Host ; Section 14.23
+ | If-Match ; Section 14.24
+
+
+
+Fielding, et al. Standards Track [Page 38]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | If-Modified-Since ; Section 14.25
+ | If-None-Match ; Section 14.26
+ | If-Range ; Section 14.27
+ | If-Unmodified-Since ; Section 14.28
+ | Max-Forwards ; Section 14.31
+ | Proxy-Authorization ; Section 14.34
+ | Range ; Section 14.35
+ | Referer ; Section 14.36
+ | TE ; Section 14.39
+ | User-Agent ; Section 14.43
+
+ Request-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of request-
+ header fields if all parties in the communication recognize them to
+ be request-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+6 Response
+
+ After receiving and interpreting a request message, a server responds
+ with an HTTP response message.
+
+ Response = Status-Line ; Section 6.1
+ *(( general-header ; Section 4.5
+ | response-header ; Section 6.2
+ | entity-header ) CRLF) ; Section 7.1
+ CRLF
+ [ message-body ] ; Section 7.2
+
+6.1 Status-Line
+
+ The first line of a Response message is the Status-Line, consisting
+ of the protocol version followed by a numeric status code and its
+ associated textual phrase, with each element separated by SP
+ characters. No CR or LF is allowed except in the final CRLF sequence.
+
+ Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
+
+6.1.1 Status Code and Reason Phrase
+
+ The Status-Code element is a 3-digit integer result code of the
+ attempt to understand and satisfy the request. These codes are fully
+ defined in section 10. The Reason-Phrase is intended to give a short
+ textual description of the Status-Code. The Status-Code is intended
+ for use by automata and the Reason-Phrase is intended for the human
+ user. The client is not required to examine or display the Reason-
+ Phrase.
+
+
+
+Fielding, et al. Standards Track [Page 39]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The first digit of the Status-Code defines the class of response. The
+ last two digits do not have any categorization role. There are 5
+ values for the first digit:
+
+ - 1xx: Informational - Request received, continuing process
+
+ - 2xx: Success - The action was successfully received,
+ understood, and accepted
+
+ - 3xx: Redirection - Further action must be taken in order to
+ complete the request
+
+ - 4xx: Client Error - The request contains bad syntax or cannot
+ be fulfilled
+
+ - 5xx: Server Error - The server failed to fulfill an apparently
+ valid request
+
+ The individual values of the numeric status codes defined for
+ HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
+ presented below. The reason phrases listed here are only
+ recommendations -- they MAY be replaced by local equivalents without
+ affecting the protocol.
+
+ Status-Code =
+ "100" ; Section 10.1.1: Continue
+ | "101" ; Section 10.1.2: Switching Protocols
+ | "200" ; Section 10.2.1: OK
+ | "201" ; Section 10.2.2: Created
+ | "202" ; Section 10.2.3: Accepted
+ | "203" ; Section 10.2.4: Non-Authoritative Information
+ | "204" ; Section 10.2.5: No Content
+ | "205" ; Section 10.2.6: Reset Content
+ | "206" ; Section 10.2.7: Partial Content
+ | "300" ; Section 10.3.1: Multiple Choices
+ | "301" ; Section 10.3.2: Moved Permanently
+ | "302" ; Section 10.3.3: Found
+ | "303" ; Section 10.3.4: See Other
+ | "304" ; Section 10.3.5: Not Modified
+ | "305" ; Section 10.3.6: Use Proxy
+ | "307" ; Section 10.3.8: Temporary Redirect
+ | "400" ; Section 10.4.1: Bad Request
+ | "401" ; Section 10.4.2: Unauthorized
+ | "402" ; Section 10.4.3: Payment Required
+ | "403" ; Section 10.4.4: Forbidden
+ | "404" ; Section 10.4.5: Not Found
+ | "405" ; Section 10.4.6: Method Not Allowed
+ | "406" ; Section 10.4.7: Not Acceptable
+
+
+
+Fielding, et al. Standards Track [Page 40]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | "407" ; Section 10.4.8: Proxy Authentication Required
+ | "408" ; Section 10.4.9: Request Time-out
+ | "409" ; Section 10.4.10: Conflict
+ | "410" ; Section 10.4.11: Gone
+ | "411" ; Section 10.4.12: Length Required
+ | "412" ; Section 10.4.13: Precondition Failed
+ | "413" ; Section 10.4.14: Request Entity Too Large
+ | "414" ; Section 10.4.15: Request-URI Too Large
+ | "415" ; Section 10.4.16: Unsupported Media Type
+ | "416" ; Section 10.4.17: Requested range not satisfiable
+ | "417" ; Section 10.4.18: Expectation Failed
+ | "500" ; Section 10.5.1: Internal Server Error
+ | "501" ; Section 10.5.2: Not Implemented
+ | "502" ; Section 10.5.3: Bad Gateway
+ | "503" ; Section 10.5.4: Service Unavailable
+ | "504" ; Section 10.5.5: Gateway Time-out
+ | "505" ; Section 10.5.6: HTTP Version not supported
+ | extension-code
+
+ extension-code = 3DIGIT
+ Reason-Phrase = *<TEXT, excluding CR, LF>
+
+ HTTP status codes are extensible. HTTP applications are not required
+ to understand the meaning of all registered status codes, though such
+ understanding is obviously desirable. However, applications MUST
+ understand the class of any status code, as indicated by the first
+ digit, and treat any unrecognized response as being equivalent to the
+ x00 status code of that class, with the exception that an
+ unrecognized response MUST NOT be cached. For example, if an
+ unrecognized status code of 431 is received by the client, it can
+ safely assume that there was something wrong with its request and
+ treat the response as if it had received a 400 status code. In such
+ cases, user agents SHOULD present to the user the entity returned
+ with the response, since that entity is likely to include human-
+ readable information which will explain the unusual status.
+
+6.2 Response Header Fields
+
+ The response-header fields allow the server to pass additional
+ information about the response which cannot be placed in the Status-
+ Line. These header fields give information about the server and about
+ further access to the resource identified by the Request-URI.
+
+ response-header = Accept-Ranges ; Section 14.5
+ | Age ; Section 14.6
+ | ETag ; Section 14.19
+ | Location ; Section 14.30
+ | Proxy-Authenticate ; Section 14.33
+
+
+
+Fielding, et al. Standards Track [Page 41]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ | Retry-After ; Section 14.37
+ | Server ; Section 14.38
+ | Vary ; Section 14.44
+ | WWW-Authenticate ; Section 14.47
+
+ Response-header field names can be extended reliably only in
+ combination with a change in the protocol version. However, new or
+ experimental header fields MAY be given the semantics of response-
+ header fields if all parties in the communication recognize them to
+ be response-header fields. Unrecognized header fields are treated as
+ entity-header fields.
+
+7 Entity
+
+ Request and Response messages MAY transfer an entity if not otherwise
+ restricted by the request method or response status code. An entity
+ consists of entity-header fields and an entity-body, although some
+ responses will only include the entity-headers.
+
+ In this section, both sender and recipient refer to either the client
+ or the server, depending on who sends and who receives the entity.
+
+7.1 Entity Header Fields
+
+ Entity-header fields define metainformation about the entity-body or,
+ if no body is present, about the resource identified by the request.
+ Some of this metainformation is OPTIONAL; some might be REQUIRED by
+ portions of this specification.
+
+ entity-header = Allow ; Section 14.7
+ | Content-Encoding ; Section 14.11
+ | Content-Language ; Section 14.12
+ | Content-Length ; Section 14.13
+ | Content-Location ; Section 14.14
+ | Content-MD5 ; Section 14.15
+ | Content-Range ; Section 14.16
+ | Content-Type ; Section 14.17
+ | Expires ; Section 14.21
+ | Last-Modified ; Section 14.29
+ | extension-header
+
+ extension-header = message-header
+
+ The extension-header mechanism allows additional entity-header fields
+ to be defined without changing the protocol, but these fields cannot
+ be assumed to be recognizable by the recipient. Unrecognized header
+ fields SHOULD be ignored by the recipient and MUST be forwarded by
+ transparent proxies.
+
+
+
+Fielding, et al. Standards Track [Page 42]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+7.2 Entity Body
+
+ The entity-body (if any) sent with an HTTP request or response is in
+ a format and encoding defined by the entity-header fields.
+
+ entity-body = *OCTET
+
+ An entity-body is only present in a message when a message-body is
+ present, as described in section 4.3. The entity-body is obtained
+ from the message-body by decoding any Transfer-Encoding that might
+ have been applied to ensure safe and proper transfer of the message.
+
+7.2.1 Type
+
+ When an entity-body is included with a message, the data type of that
+ body is determined via the header fields Content-Type and Content-
+ Encoding. These define a two-layer, ordered encoding model:
+
+ entity-body := Content-Encoding( Content-Type( data ) )
+
+ Content-Type specifies the media type of the underlying data.
+ Content-Encoding may be used to indicate any additional content
+ codings applied to the data, usually for the purpose of data
+ compression, that are a property of the requested resource. There is
+ no default encoding.
+
+ Any HTTP/1.1 message containing an entity-body SHOULD include a
+ Content-Type header field defining the media type of that body. If
+ and only if the media type is not given by a Content-Type field, the
+ recipient MAY attempt to guess the media type via inspection of its
+ content and/or the name extension(s) of the URI used to identify the
+ resource. If the media type remains unknown, the recipient SHOULD
+ treat it as type "application/octet-stream".
+
+7.2.2 Entity Length
+
+ The entity-length of a message is the length of the message-body
+ before any transfer-codings have been applied. Section 4.4 defines
+ how the transfer-length of a message-body is determined.
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 43]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8 Connections
+
+8.1 Persistent Connections
+
+8.1.1 Purpose
+
+ Prior to persistent connections, a separate TCP connection was
+ established to fetch each URL, increasing the load on HTTP servers
+ and causing congestion on the Internet. The use of inline images and
+ other associated data often require a client to make multiple
+ requests of the same server in a short amount of time. Analysis of
+ these performance problems and results from a prototype
+ implementation are available [26] [30]. Implementation experience and
+ measurements of actual HTTP/1.1 (RFC 2068) implementations show good
+ results [39]. Alternatives have also been explored, for example,
+ T/TCP [27].
+
+ Persistent HTTP connections have a number of advantages:
+
+ - By opening and closing fewer TCP connections, CPU time is saved
+ in routers and hosts (clients, servers, proxies, gateways,
+ tunnels, or caches), and memory used for TCP protocol control
+ blocks can be saved in hosts.
+
+ - HTTP requests and responses can be pipelined on a connection.
+ Pipelining allows a client to make multiple requests without
+ waiting for each response, allowing a single TCP connection to
+ be used much more efficiently, with much lower elapsed time.
+
+ - Network congestion is reduced by reducing the number of packets
+ caused by TCP opens, and by allowing TCP sufficient time to
+ determine the congestion state of the network.
+
+ - Latency on subsequent requests is reduced since there is no time
+ spent in TCP's connection opening handshake.
+
+ - HTTP can evolve more gracefully, since errors can be reported
+ without the penalty of closing the TCP connection. Clients using
+ future versions of HTTP might optimistically try a new feature,
+ but if communicating with an older server, retry with old
+ semantics after an error is reported.
+
+ HTTP implementations SHOULD implement persistent connections.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 44]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.1.2 Overall Operation
+
+ A significant difference between HTTP/1.1 and earlier versions of
+ HTTP is that persistent connections are the default behavior of any
+ HTTP connection. That is, unless otherwise indicated, the client
+ SHOULD assume that the server will maintain a persistent connection,
+ even after error responses from the server.
+
+ Persistent connections provide a mechanism by which a client and a
+ server can signal the close of a TCP connection. This signaling takes
+ place using the Connection header field (section 14.10). Once a close
+ has been signaled, the client MUST NOT send any more requests on that
+ connection.
+
+8.1.2.1 Negotiation
+
+ An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to
+ maintain a persistent connection unless a Connection header including
+ the connection-token "close" was sent in the request. If the server
+ chooses to close the connection immediately after sending the
+ response, it SHOULD send a Connection header including the
+ connection-token close.
+
+ An HTTP/1.1 client MAY expect a connection to remain open, but would
+ decide to keep it open based on whether the response from a server
+ contains a Connection header with the connection-token close. In case
+ the client does not want to maintain a connection for more than that
+ request, it SHOULD send a Connection header including the
+ connection-token close.
+
+ If either the client or the server sends the close token in the
+ Connection header, that request becomes the last one for the
+ connection.
+
+ Clients and servers SHOULD NOT assume that a persistent connection is
+ maintained for HTTP versions less than 1.1 unless it is explicitly
+ signaled. See section 19.6.2 for more information on backward
+ compatibility with HTTP/1.0 clients.
+
+ In order to remain persistent, all messages on the connection MUST
+ have a self-defined message length (i.e., one not defined by closure
+ of the connection), as described in section 4.4.
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 45]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.1.2.2 Pipelining
+
+ A client that supports persistent connections MAY "pipeline" its
+ requests (i.e., send multiple requests without waiting for each
+ response). A server MUST send its responses to those requests in the
+ same order that the requests were received.
+
+ Clients which assume persistent connections and pipeline immediately
+ after connection establishment SHOULD be prepared to retry their
+ connection if the first pipelined attempt fails. If a client does
+ such a retry, it MUST NOT pipeline before it knows the connection is
+ persistent. Clients MUST also be prepared to resend their requests if
+ the server closes the connection before sending all of the
+ corresponding responses.
+
+ Clients SHOULD NOT pipeline requests using non-idempotent methods or
+ non-idempotent sequences of methods (see section 9.1.2). Otherwise, a
+ premature termination of the transport connection could lead to
+ indeterminate results. A client wishing to send a non-idempotent
+ request SHOULD wait to send that request until it has received the
+ response status for the previous request.
+
+8.1.3 Proxy Servers
+
+ It is especially important that proxies correctly implement the
+ properties of the Connection header field as specified in section
+ 14.10.
+
+ The proxy server MUST signal persistent connections separately with
+ its clients and the origin servers (or other proxy servers) that it
+ connects to. Each persistent connection applies to only one transport
+ link.
+
+ A proxy server MUST NOT establish a HTTP/1.1 persistent connection
+ with an HTTP/1.0 client (but see RFC 2068 [33] for information and
+ discussion of the problems with the Keep-Alive header implemented by
+ many HTTP/1.0 clients).
+
+8.1.4 Practical Considerations
+
+ Servers will usually have some time-out value beyond which they will
+ no longer maintain an inactive connection. Proxy servers might make
+ this a higher value since it is likely that the client will be making
+ more connections through the same server. The use of persistent
+ connections places no requirements on the length (or existence) of
+ this time-out for either the client or the server.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 46]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ When a client or server wishes to time-out it SHOULD issue a graceful
+ close on the transport connection. Clients and servers SHOULD both
+ constantly watch for the other side of the transport close, and
+ respond to it as appropriate. If a client or server does not detect
+ the other side's close promptly it could cause unnecessary resource
+ drain on the network.
+
+ A client, server, or proxy MAY close the transport connection at any
+ time. For example, a client might have started to send a new request
+ at the same time that the server has decided to close the "idle"
+ connection. From the server's point of view, the connection is being
+ closed while it was idle, but from the client's point of view, a
+ request is in progress.
+
+ This means that clients, servers, and proxies MUST be able to recover
+ from asynchronous close events. Client software SHOULD reopen the
+ transport connection and retransmit the aborted sequence of requests
+ without user interaction so long as the request sequence is
+ idempotent (see section 9.1.2). Non-idempotent methods or sequences
+ MUST NOT be automatically retried, although user agents MAY offer a
+ human operator the choice of retrying the request(s). Confirmation by
+ user-agent software with semantic understanding of the application
+ MAY substitute for user confirmation. The automatic retry SHOULD NOT
+ be repeated if the second sequence of requests fails.
+
+ Servers SHOULD always respond to at least one request per connection,
+ if at all possible. Servers SHOULD NOT close a connection in the
+ middle of transmitting a response, unless a network or client failure
+ is suspected.
+
+ Clients that use persistent connections SHOULD limit the number of
+ simultaneous connections that they maintain to a given server. A
+ single-user client SHOULD NOT maintain more than 2 connections with
+ any server or proxy. A proxy SHOULD use up to 2*N connections to
+ another server or proxy, where N is the number of simultaneously
+ active users. These guidelines are intended to improve HTTP response
+ times and avoid congestion.
+
+8.2 Message Transmission Requirements
+
+8.2.1 Persistent Connections and Flow Control
+
+ HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's
+ flow control mechanisms to resolve temporary overloads, rather than
+ terminating connections with the expectation that clients will retry.
+ The latter technique can exacerbate network congestion.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 47]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+8.2.2 Monitoring Connections for Error Status Messages
+
+ An HTTP/1.1 (or later) client sending a message-body SHOULD monitor
+ the network connection for an error status while it is transmitting
+ the request. If the client sees an error status, it SHOULD
+ immediately cease transmitting the body. If the body is being sent
+ using a "chunked" encoding (section 3.6), a zero length chunk and
+ empty trailer MAY be used to prematurely mark the end of the message.
+ If the body was preceded by a Content-Length header, the client MUST
+ close the connection.
+
+8.2.3 Use of the 100 (Continue) Status
+
+ The purpose of the 100 (Continue) status (see section 10.1.1) is to
+ allow a client that is sending a request message with a request body
+ to determine if the origin server is willing to accept the request
+ (based on the request headers) before the client sends the request
+ body. In some cases, it might either be inappropriate or highly
+ inefficient for the client to send the body if the server will reject
+ the message without looking at the body.
+
+ Requirements for HTTP/1.1 clients:
+
+ - If a client will wait for a 100 (Continue) response before
+ sending the request body, it MUST send an Expect request-header
+ field (section 14.20) with the "100-continue" expectation.
+
+ - A client MUST NOT send an Expect request-header field (section
+ 14.20) with the "100-continue" expectation if it does not intend
+ to send a request body.
+
+ Because of the presence of older implementations, the protocol allows
+ ambiguous situations in which a client may send "Expect: 100-
+ continue" without receiving either a 417 (Expectation Failed) status
+ or a 100 (Continue) status. Therefore, when a client sends this
+ header field to an origin server (possibly via a proxy) from which it
+ has never seen a 100 (Continue) status, the client SHOULD NOT wait
+ for an indefinite period before sending the request body.
+
+ Requirements for HTTP/1.1 origin servers:
+
+ - Upon receiving a request which includes an Expect request-header
+ field with the "100-continue" expectation, an origin server MUST
+ either respond with 100 (Continue) status and continue to read
+ from the input stream, or respond with a final status code. The
+ origin server MUST NOT wait for the request body before sending
+ the 100 (Continue) response. If it responds with a final status
+ code, it MAY close the transport connection or it MAY continue
+
+
+
+Fielding, et al. Standards Track [Page 48]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ to read and discard the rest of the request. It MUST NOT
+ perform the requested method if it returns a final status code.
+
+ - An origin server SHOULD NOT send a 100 (Continue) response if
+ the request message does not include an Expect request-header
+ field with the "100-continue" expectation, and MUST NOT send a
+ 100 (Continue) response if such a request comes from an HTTP/1.0
+ (or earlier) client. There is an exception to this rule: for
+ compatibility with RFC 2068, a server MAY send a 100 (Continue)
+ status in response to an HTTP/1.1 PUT or POST request that does
+ not include an Expect request-header field with the "100-
+ continue" expectation. This exception, the purpose of which is
+ to minimize any client processing delays associated with an
+ undeclared wait for 100 (Continue) status, applies only to
+ HTTP/1.1 requests, and not to requests with any other HTTP-
+ version value.
+
+ - An origin server MAY omit a 100 (Continue) response if it has
+ already received some or all of the request body for the
+ corresponding request.
+
+ - An origin server that sends a 100 (Continue) response MUST
+ ultimately send a final status code, once the request body is
+ received and processed, unless it terminates the transport
+ connection prematurely.
+
+ - If an origin server receives a request that does not include an
+ Expect request-header field with the "100-continue" expectation,
+ the request includes a request body, and the server responds
+ with a final status code before reading the entire request body
+ from the transport connection, then the server SHOULD NOT close
+ the transport connection until it has read the entire request,
+ or until the client closes the connection. Otherwise, the client
+ might not reliably receive the response message. However, this
+ requirement is not be construed as preventing a server from
+ defending itself against denial-of-service attacks, or from
+ badly broken client implementations.
+
+ Requirements for HTTP/1.1 proxies:
+
+ - If a proxy receives a request that includes an Expect request-
+ header field with the "100-continue" expectation, and the proxy
+ either knows that the next-hop server complies with HTTP/1.1 or
+ higher, or does not know the HTTP version of the next-hop
+ server, it MUST forward the request, including the Expect header
+ field.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 49]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If the proxy knows that the version of the next-hop server is
+ HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST
+ respond with a 417 (Expectation Failed) status.
+
+ - Proxies SHOULD maintain a cache recording the HTTP version
+ numbers received from recently-referenced next-hop servers.
+
+ - A proxy MUST NOT forward a 100 (Continue) response if the
+ request message was received from an HTTP/1.0 (or earlier)
+ client and did not include an Expect request-header field with
+ the "100-continue" expectation. This requirement overrides the
+ general rule for forwarding of 1xx responses (see section 10.1).
+
+8.2.4 Client Behavior if Server Prematurely Closes Connection
+
+ If an HTTP/1.1 client sends a request which includes a request body,
+ but which does not include an Expect request-header field with the
+ "100-continue" expectation, and if the client is not directly
+ connected to an HTTP/1.1 origin server, and if the client sees the
+ connection close before receiving any status from the server, the
+ client SHOULD retry the request. If the client does retry this
+ request, it MAY use the following "binary exponential backoff"
+ algorithm to be assured of obtaining a reliable response:
+
+ 1. Initiate a new connection to the server
+
+ 2. Transmit the request-headers
+
+ 3. Initialize a variable R to the estimated round-trip time to the
+ server (e.g., based on the time it took to establish the
+ connection), or to a constant value of 5 seconds if the round-
+ trip time is not available.
+
+ 4. Compute T = R * (2**N), where N is the number of previous
+ retries of this request.
+
+ 5. Wait either for an error response from the server, or for T
+ seconds (whichever comes first)
+
+ 6. If no error response is received, after T seconds transmit the
+ body of the request.
+
+ 7. If client sees that the connection is closed prematurely,
+ repeat from step 1 until the request is accepted, an error
+ response is received, or the user becomes impatient and
+ terminates the retry process.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 50]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If at any point an error status is received, the client
+
+ - SHOULD NOT continue and
+
+ - SHOULD close the connection if it has not completed sending the
+ request message.
+
+9 Method Definitions
+
+ The set of common methods for HTTP/1.1 is defined below. Although
+ this set can be expanded, additional methods cannot be assumed to
+ share the same semantics for separately extended clients and servers.
+
+ The Host request-header field (section 14.23) MUST accompany all
+ HTTP/1.1 requests.
+
+9.1 Safe and Idempotent Methods
+
+9.1.1 Safe Methods
+
+ Implementors should be aware that the software represents the user in
+ their interactions over the Internet, and should be careful to allow
+ the user to be aware of any actions they might take which may have an
+ unexpected significance to themselves or others.
+
+ In particular, the convention has been established that the GET and
+ HEAD methods SHOULD NOT have the significance of taking an action
+ other than retrieval. These methods ought to be considered "safe".
+ This allows user agents to represent other methods, such as POST, PUT
+ and DELETE, in a special way, so that the user is made aware of the
+ fact that a possibly unsafe action is being requested.
+
+ Naturally, it is not possible to ensure that the server does not
+ generate side-effects as a result of performing a GET request; in
+ fact, some dynamic resources consider that a feature. The important
+ distinction here is that the user did not request the side-effects,
+ so therefore cannot be held accountable for them.
+
+9.1.2 Idempotent Methods
+
+ Methods can also have the property of "idempotence" in that (aside
+ from error or expiration issues) the side-effects of N > 0 identical
+ requests is the same as for a single request. The methods GET, HEAD,
+ PUT and DELETE share this property. Also, the methods OPTIONS and
+ TRACE SHOULD NOT have side effects, and so are inherently idempotent.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 51]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ However, it is possible that a sequence of several requests is non-
+ idempotent, even if all of the methods executed in that sequence are
+ idempotent. (A sequence is idempotent if a single execution of the
+ entire sequence always yields a result that is not changed by a
+ reexecution of all, or part, of that sequence.) For example, a
+ sequence is non-idempotent if its result depends on a value that is
+ later modified in the same sequence.
+
+ A sequence that never has side effects is idempotent, by definition
+ (provided that no concurrent operations are being executed on the
+ same set of resources).
+
+9.2 OPTIONS
+
+ The OPTIONS method represents a request for information about the
+ communication options available on the request/response chain
+ identified by the Request-URI. This method allows the client to
+ determine the options and/or requirements associated with a resource,
+ or the capabilities of a server, without implying a resource action
+ or initiating a resource retrieval.
+
+ Responses to this method are not cacheable.
+
+ If the OPTIONS request includes an entity-body (as indicated by the
+ presence of Content-Length or Transfer-Encoding), then the media type
+ MUST be indicated by a Content-Type field. Although this
+ specification does not define any use for such a body, future
+ extensions to HTTP might use the OPTIONS body to make more detailed
+ queries on the server. A server that does not support such an
+ extension MAY discard the request body.
+
+ If the Request-URI is an asterisk ("*"), the OPTIONS request is
+ intended to apply to the server in general rather than to a specific
+ resource. Since a server's communication options typically depend on
+ the resource, the "*" request is only useful as a "ping" or "no-op"
+ type of method; it does nothing beyond allowing the client to test
+ the capabilities of the server. For example, this can be used to test
+ a proxy for HTTP/1.1 compliance (or lack thereof).
+
+ If the Request-URI is not an asterisk, the OPTIONS request applies
+ only to the options that are available when communicating with that
+ resource.
+
+ A 200 response SHOULD include any header fields that indicate
+ optional features implemented by the server and applicable to that
+ resource (e.g., Allow), possibly including extensions not defined by
+ this specification. The response body, if any, SHOULD also include
+ information about the communication options. The format for such a
+
+
+
+Fielding, et al. Standards Track [Page 52]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ body is not defined by this specification, but might be defined by
+ future extensions to HTTP. Content negotiation MAY be used to select
+ the appropriate response format. If no response body is included, the
+ response MUST include a Content-Length field with a field-value of
+ "0".
+
+ The Max-Forwards request-header field MAY be used to target a
+ specific proxy in the request chain. When a proxy receives an OPTIONS
+ request on an absoluteURI for which request forwarding is permitted,
+ the proxy MUST check for a Max-Forwards field. If the Max-Forwards
+ field-value is zero ("0"), the proxy MUST NOT forward the message;
+ instead, the proxy SHOULD respond with its own communication options.
+ If the Max-Forwards field-value is an integer greater than zero, the
+ proxy MUST decrement the field-value when it forwards the request. If
+ no Max-Forwards field is present in the request, then the forwarded
+ request MUST NOT include a Max-Forwards field.
+
+9.3 GET
+
+ The GET method means retrieve whatever information (in the form of an
+ entity) is identified by the Request-URI. If the Request-URI refers
+ to a data-producing process, it is the produced data which shall be
+ returned as the entity in the response and not the source text of the
+ process, unless that text happens to be the output of the process.
+
+ The semantics of the GET method change to a "conditional GET" if the
+ request message includes an If-Modified-Since, If-Unmodified-Since,
+ If-Match, If-None-Match, or If-Range header field. A conditional GET
+ method requests that the entity be transferred only under the
+ circumstances described by the conditional header field(s). The
+ conditional GET method is intended to reduce unnecessary network
+ usage by allowing cached entities to be refreshed without requiring
+ multiple requests or transferring data already held by the client.
+
+ The semantics of the GET method change to a "partial GET" if the
+ request message includes a Range header field. A partial GET requests
+ that only part of the entity be transferred, as described in section
+ 14.35. The partial GET method is intended to reduce unnecessary
+ network usage by allowing partially-retrieved entities to be
+ completed without transferring data already held by the client.
+
+ The response to a GET request is cacheable if and only if it meets
+ the requirements for HTTP caching described in section 13.
+
+ See section 15.1.3 for security considerations when used for forms.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 53]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+9.4 HEAD
+
+ The HEAD method is identical to GET except that the server MUST NOT
+ return a message-body in the response. The metainformation contained
+ in the HTTP headers in response to a HEAD request SHOULD be identical
+ to the information sent in response to a GET request. This method can
+ be used for obtaining metainformation about the entity implied by the
+ request without transferring the entity-body itself. This method is
+ often used for testing hypertext links for validity, accessibility,
+ and recent modification.
+
+ The response to a HEAD request MAY be cacheable in the sense that the
+ information contained in the response MAY be used to update a
+ previously cached entity from that resource. If the new field values
+ indicate that the cached entity differs from the current entity (as
+ would be indicated by a change in Content-Length, Content-MD5, ETag
+ or Last-Modified), then the cache MUST treat the cache entry as
+ stale.
+
+9.5 POST
+
+ The POST method is used to request that the origin server accept the
+ entity enclosed in the request as a new subordinate of the resource
+ identified by the Request-URI in the Request-Line. POST is designed
+ to allow a uniform method to cover the following functions:
+
+ - Annotation of existing resources;
+
+ - Posting a message to a bulletin board, newsgroup, mailing list,
+ or similar group of articles;
+
+ - Providing a block of data, such as the result of submitting a
+ form, to a data-handling process;
+
+ - Extending a database through an append operation.
+
+ The actual function performed by the POST method is determined by the
+ server and is usually dependent on the Request-URI. The posted entity
+ is subordinate to that URI in the same way that a file is subordinate
+ to a directory containing it, a news article is subordinate to a
+ newsgroup to which it is posted, or a record is subordinate to a
+ database.
+
+ The action performed by the POST method might not result in a
+ resource that can be identified by a URI. In this case, either 200
+ (OK) or 204 (No Content) is the appropriate response status,
+ depending on whether or not the response includes an entity that
+ describes the result.
+
+
+
+Fielding, et al. Standards Track [Page 54]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If a resource has been created on the origin server, the response
+ SHOULD be 201 (Created) and contain an entity which describes the
+ status of the request and refers to the new resource, and a Location
+ header (see section 14.30).
+
+ Responses to this method are not cacheable, unless the response
+ includes appropriate Cache-Control or Expires header fields. However,
+ the 303 (See Other) response can be used to direct the user agent to
+ retrieve a cacheable resource.
+
+ POST requests MUST obey the message transmission requirements set out
+ in section 8.2.
+
+ See section 15.1.3 for security considerations.
+
+9.6 PUT
+
+ The PUT method requests that the enclosed entity be stored under the
+ supplied Request-URI. If the Request-URI refers to an already
+ existing resource, the enclosed entity SHOULD be considered as a
+ modified version of the one residing on the origin server. If the
+ Request-URI does not point to an existing resource, and that URI is
+ capable of being defined as a new resource by the requesting user
+ agent, the origin server can create the resource with that URI. If a
+ new resource is created, the origin server MUST inform the user agent
+ via the 201 (Created) response. If an existing resource is modified,
+ either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
+ to indicate successful completion of the request. If the resource
+ could not be created or modified with the Request-URI, an appropriate
+ error response SHOULD be given that reflects the nature of the
+ problem. The recipient of the entity MUST NOT ignore any Content-*
+ (e.g. Content-Range) headers that it does not understand or implement
+ and MUST return a 501 (Not Implemented) response in such cases.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries SHOULD be
+ treated as stale. Responses to this method are not cacheable.
+
+ The fundamental difference between the POST and PUT requests is
+ reflected in the different meaning of the Request-URI. The URI in a
+ POST request identifies the resource that will handle the enclosed
+ entity. That resource might be a data-accepting process, a gateway to
+ some other protocol, or a separate entity that accepts annotations.
+ In contrast, the URI in a PUT request identifies the entity enclosed
+ with the request -- the user agent knows what URI is intended and the
+ server MUST NOT attempt to apply the request to some other resource.
+ If the server desires that the request be applied to a different URI,
+
+
+
+
+Fielding, et al. Standards Track [Page 55]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ it MUST send a 301 (Moved Permanently) response; the user agent MAY
+ then make its own decision regarding whether or not to redirect the
+ request.
+
+ A single resource MAY be identified by many different URIs. For
+ example, an article might have a URI for identifying "the current
+ version" which is separate from the URI identifying each particular
+ version. In this case, a PUT request on a general URI might result in
+ several other URIs being defined by the origin server.
+
+ HTTP/1.1 does not define how a PUT method affects the state of an
+ origin server.
+
+ PUT requests MUST obey the message transmission requirements set out
+ in section 8.2.
+
+ Unless otherwise specified for a particular entity-header, the
+ entity-headers in the PUT request SHOULD be applied to the resource
+ created or modified by the PUT.
+
+9.7 DELETE
+
+ The DELETE method requests that the origin server delete the resource
+ identified by the Request-URI. This method MAY be overridden by human
+ intervention (or other means) on the origin server. The client cannot
+ be guaranteed that the operation has been carried out, even if the
+ status code returned from the origin server indicates that the action
+ has been completed successfully. However, the server SHOULD NOT
+ indicate success unless, at the time the response is given, it
+ intends to delete the resource or move it to an inaccessible
+ location.
+
+ A successful response SHOULD be 200 (OK) if the response includes an
+ entity describing the status, 202 (Accepted) if the action has not
+ yet been enacted, or 204 (No Content) if the action has been enacted
+ but the response does not include an entity.
+
+ If the request passes through a cache and the Request-URI identifies
+ one or more currently cached entities, those entries SHOULD be
+ treated as stale. Responses to this method are not cacheable.
+
+9.8 TRACE
+
+ The TRACE method is used to invoke a remote, application-layer loop-
+ back of the request message. The final recipient of the request
+ SHOULD reflect the message received back to the client as the
+ entity-body of a 200 (OK) response. The final recipient is either the
+
+
+
+
+Fielding, et al. Standards Track [Page 56]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ origin server or the first proxy or gateway to receive a Max-Forwards
+ value of zero (0) in the request (see section 14.31). A TRACE request
+ MUST NOT include an entity.
+
+ TRACE allows the client to see what is being received at the other
+ end of the request chain and use that data for testing or diagnostic
+ information. The value of the Via header field (section 14.45) is of
+ particular interest, since it acts as a trace of the request chain.
+ Use of the Max-Forwards header field allows the client to limit the
+ length of the request chain, which is useful for testing a chain of
+ proxies forwarding messages in an infinite loop.
+
+ If the request is valid, the response SHOULD contain the entire
+ request message in the entity-body, with a Content-Type of
+ "message/http". Responses to this method MUST NOT be cached.
+
+9.9 CONNECT
+
+ This specification reserves the method name CONNECT for use with a
+ proxy that can dynamically switch to being a tunnel (e.g. SSL
+ tunneling [44]).
+
+10 Status Code Definitions
+
+ Each Status-Code is described below, including a description of which
+ method(s) it can follow and any metainformation required in the
+ response.
+
+10.1 Informational 1xx
+
+ This class of status code indicates a provisional response,
+ consisting only of the Status-Line and optional headers, and is
+ terminated by an empty line. There are no required headers for this
+ class of status code. Since HTTP/1.0 did not define any 1xx status
+ codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client
+ except under experimental conditions.
+
+ A client MUST be prepared to accept one or more 1xx status responses
+ prior to a regular response, even if the client does not expect a 100
+ (Continue) status message. Unexpected 1xx status responses MAY be
+ ignored by a user agent.
+
+ Proxies MUST forward 1xx responses, unless the connection between the
+ proxy and its client has been closed, or unless the proxy itself
+ requested the generation of the 1xx response. (For example, if a
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 57]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ proxy adds a "Expect: 100-continue" field when it forwards a request,
+ then it need not forward the corresponding 100 (Continue)
+ response(s).)
+
+10.1.1 100 Continue
+
+ The client SHOULD continue with its request. This interim response is
+ used to inform the client that the initial part of the request has
+ been received and has not yet been rejected by the server. The client
+ SHOULD continue by sending the remainder of the request or, if the
+ request has already been completed, ignore this response. The server
+ MUST send a final response after the request has been completed. See
+ section 8.2.3 for detailed discussion of the use and handling of this
+ status code.
+
+10.1.2 101 Switching Protocols
+
+ The server understands and is willing to comply with the client's
+ request, via the Upgrade message header field (section 14.42), for a
+ change in the application protocol being used on this connection. The
+ server will switch protocols to those defined by the response's
+ Upgrade header field immediately after the empty line which
+ terminates the 101 response.
+
+ The protocol SHOULD be switched only when it is advantageous to do
+ so. For example, switching to a newer version of HTTP is advantageous
+ over older versions, and switching to a real-time, synchronous
+ protocol might be advantageous when delivering resources that use
+ such features.
+
+10.2 Successful 2xx
+
+ This class of status code indicates that the client's request was
+ successfully received, understood, and accepted.
+
+10.2.1 200 OK
+
+ The request has succeeded. The information returned with the response
+ is dependent on the method used in the request, for example:
+
+ GET an entity corresponding to the requested resource is sent in
+ the response;
+
+ HEAD the entity-header fields corresponding to the requested
+ resource are sent in the response without any message-body;
+
+ POST an entity describing or containing the result of the action;
+
+
+
+
+Fielding, et al. Standards Track [Page 58]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ TRACE an entity containing the request message as received by the
+ end server.
+
+10.2.2 201 Created
+
+ The request has been fulfilled and resulted in a new resource being
+ created. The newly created resource can be referenced by the URI(s)
+ returned in the entity of the response, with the most specific URI
+ for the resource given by a Location header field. The response
+ SHOULD include an entity containing a list of resource
+ characteristics and location(s) from which the user or user agent can
+ choose the one most appropriate. The entity format is specified by
+ the media type given in the Content-Type header field. The origin
+ server MUST create the resource before returning the 201 status code.
+ If the action cannot be carried out immediately, the server SHOULD
+ respond with 202 (Accepted) response instead.
+
+ A 201 response MAY contain an ETag response header field indicating
+ the current value of the entity tag for the requested variant just
+ created, see section 14.19.
+
+10.2.3 202 Accepted
+
+ The request has been accepted for processing, but the processing has
+ not been completed. The request might or might not eventually be
+ acted upon, as it might be disallowed when processing actually takes
+ place. There is no facility for re-sending a status code from an
+ asynchronous operation such as this.
+
+ The 202 response is intentionally non-committal. Its purpose is to
+ allow a server to accept a request for some other process (perhaps a
+ batch-oriented process that is only run once per day) without
+ requiring that the user agent's connection to the server persist
+ until the process is completed. The entity returned with this
+ response SHOULD include an indication of the request's current status
+ and either a pointer to a status monitor or some estimate of when the
+ user can expect the request to be fulfilled.
+
+10.2.4 203 Non-Authoritative Information
+
+ The returned metainformation in the entity-header is not the
+ definitive set as available from the origin server, but is gathered
+ from a local or a third-party copy. The set presented MAY be a subset
+ or superset of the original version. For example, including local
+ annotation information about the resource might result in a superset
+ of the metainformation known by the origin server. Use of this
+ response code is not required and is only appropriate when the
+ response would otherwise be 200 (OK).
+
+
+
+Fielding, et al. Standards Track [Page 59]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.2.5 204 No Content
+
+ The server has fulfilled the request but does not need to return an
+ entity-body, and might want to return updated metainformation. The
+ response MAY include new or updated metainformation in the form of
+ entity-headers, which if present SHOULD be associated with the
+ requested variant.
+
+ If the client is a user agent, it SHOULD NOT change its document view
+ from that which caused the request to be sent. This response is
+ primarily intended to allow input for actions to take place without
+ causing a change to the user agent's active document view, although
+ any new or updated metainformation SHOULD be applied to the document
+ currently in the user agent's active view.
+
+ The 204 response MUST NOT include a message-body, and thus is always
+ terminated by the first empty line after the header fields.
+
+10.2.6 205 Reset Content
+
+ The server has fulfilled the request and the user agent SHOULD reset
+ the document view which caused the request to be sent. This response
+ is primarily intended to allow input for actions to take place via
+ user input, followed by a clearing of the form in which the input is
+ given so that the user can easily initiate another input action. The
+ response MUST NOT include an entity.
+
+10.2.7 206 Partial Content
+
+ The server has fulfilled the partial GET request for the resource.
+ The request MUST have included a Range header field (section 14.35)
+ indicating the desired range, and MAY have included an If-Range
+ header field (section 14.27) to make the request conditional.
+
+ The response MUST include the following header fields:
+
+ - Either a Content-Range header field (section 14.16) indicating
+ the range included with this response, or a multipart/byteranges
+ Content-Type including Content-Range fields for each part. If a
+ Content-Length header field is present in the response, its
+ value MUST match the actual number of OCTETs transmitted in the
+ message-body.
+
+ - Date
+
+ - ETag and/or Content-Location, if the header would have been sent
+ in a 200 response to the same request
+
+
+
+
+Fielding, et al. Standards Track [Page 60]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - Expires, Cache-Control, and/or Vary, if the field-value might
+ differ from that sent in any previous response for the same
+ variant
+
+ If the 206 response is the result of an If-Range request that used a
+ strong cache validator (see section 13.3.3), the response SHOULD NOT
+ include other entity-headers. If the response is the result of an
+ If-Range request that used a weak validator, the response MUST NOT
+ include other entity-headers; this prevents inconsistencies between
+ cached entity-bodies and updated headers. Otherwise, the response
+ MUST include all of the entity-headers that would have been returned
+ with a 200 (OK) response to the same request.
+
+ A cache MUST NOT combine a 206 response with other previously cached
+ content if the ETag or Last-Modified headers do not match exactly,
+ see 13.5.4.
+
+ A cache that does not support the Range and Content-Range headers
+ MUST NOT cache 206 (Partial) responses.
+
+10.3 Redirection 3xx
+
+ This class of status code indicates that further action needs to be
+ taken by the user agent in order to fulfill the request. The action
+ required MAY be carried out by the user agent without interaction
+ with the user if and only if the method used in the second request is
+ GET or HEAD. A client SHOULD detect infinite redirection loops, since
+ such loops generate network traffic for each redirection.
+
+ Note: previous versions of this specification recommended a
+ maximum of five redirections. Content developers should be aware
+ that there might be clients that implement such a fixed
+ limitation.
+
+10.3.1 300 Multiple Choices
+
+ The requested resource corresponds to any one of a set of
+ representations, each with its own specific location, and agent-
+ driven negotiation information (section 12) is being provided so that
+ the user (or user agent) can select a preferred representation and
+ redirect its request to that location.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of resource characteristics and location(s) from
+ which the user or user agent can choose the one most appropriate. The
+ entity format is specified by the media type given in the Content-
+ Type header field. Depending upon the format and the capabilities of
+
+
+
+
+Fielding, et al. Standards Track [Page 61]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the user agent, selection of the most appropriate choice MAY be
+ performed automatically. However, this specification does not define
+ any standard for such automatic selection.
+
+ If the server has a preferred choice of representation, it SHOULD
+ include the specific URI for that representation in the Location
+ field; user agents MAY use the Location field value for automatic
+ redirection. This response is cacheable unless indicated otherwise.
+
+10.3.2 301 Moved Permanently
+
+ The requested resource has been assigned a new permanent URI and any
+ future references to this resource SHOULD use one of the returned
+ URIs. Clients with link editing capabilities ought to automatically
+ re-link references to the Request-URI to one or more of the new
+ references returned by the server, where possible. This response is
+ cacheable unless indicated otherwise.
+
+ The new permanent URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+ If the 301 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: When automatically redirecting a POST request after
+ receiving a 301 status code, some existing HTTP/1.0 user agents
+ will erroneously change it into a GET request.
+
+10.3.3 302 Found
+
+ The requested resource resides temporarily under a different URI.
+ Since the redirection might be altered on occasion, the client SHOULD
+ continue to use the Request-URI for future requests. This response
+ is only cacheable if indicated by a Cache-Control or Expires header
+ field.
+
+ The temporary URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 62]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the 302 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+ Note: RFC 1945 and RFC 2068 specify that the client is not allowed
+ to change the method on the redirected request. However, most
+ existing user agent implementations treat 302 as if it were a 303
+ response, performing a GET on the Location field-value regardless
+ of the original request method. The status codes 303 and 307 have
+ been added for servers that wish to make unambiguously clear which
+ kind of reaction is expected of the client.
+
+10.3.4 303 See Other
+
+ The response to the request can be found under a different URI and
+ SHOULD be retrieved using a GET method on that resource. This method
+ exists primarily to allow the output of a POST-activated script to
+ redirect the user agent to a selected resource. The new URI is not a
+ substitute reference for the originally requested resource. The 303
+ response MUST NOT be cached, but the response to the second
+ (redirected) request might be cacheable.
+
+ The different URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s).
+
+ Note: Many pre-HTTP/1.1 user agents do not understand the 303
+ status. When interoperability with such clients is a concern, the
+ 302 status code may be used instead, since most user agents react
+ to a 302 response as described here for 303.
+
+10.3.5 304 Not Modified
+
+ If the client has performed a conditional GET request and access is
+ allowed, but the document has not been modified, the server SHOULD
+ respond with this status code. The 304 response MUST NOT contain a
+ message-body, and thus is always terminated by the first empty line
+ after the header fields.
+
+ The response MUST include the following header fields:
+
+ - Date, unless its omission is required by section 14.18.1
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 63]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If a clockless origin server obeys these rules, and proxies and
+ clients add their own Date to any response received without one (as
+ already specified by [RFC 2068], section 14.19), caches will operate
+ correctly.
+
+ - ETag and/or Content-Location, if the header would have been sent
+ in a 200 response to the same request
+
+ - Expires, Cache-Control, and/or Vary, if the field-value might
+ differ from that sent in any previous response for the same
+ variant
+
+ If the conditional GET used a strong cache validator (see section
+ 13.3.3), the response SHOULD NOT include other entity-headers.
+ Otherwise (i.e., the conditional GET used a weak validator), the
+ response MUST NOT include other entity-headers; this prevents
+ inconsistencies between cached entity-bodies and updated headers.
+
+ If a 304 response indicates an entity not currently cached, then the
+ cache MUST disregard the response and repeat the request without the
+ conditional.
+
+ If a cache uses a received 304 response to update a cache entry, the
+ cache MUST update the entry to reflect any new field values given in
+ the response.
+
+10.3.6 305 Use Proxy
+
+ The requested resource MUST be accessed through the proxy given by
+ the Location field. The Location field gives the URI of the proxy.
+ The recipient is expected to repeat this single request via the
+ proxy. 305 responses MUST only be generated by origin servers.
+
+ Note: RFC 2068 was not clear that 305 was intended to redirect a
+ single request, and to be generated by origin servers only. Not
+ observing these limitations has significant security consequences.
+
+10.3.7 306 (Unused)
+
+ The 306 status code was used in a previous version of the
+ specification, is no longer used, and the code is reserved.
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 64]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.3.8 307 Temporary Redirect
+
+ The requested resource resides temporarily under a different URI.
+ Since the redirection MAY be altered on occasion, the client SHOULD
+ continue to use the Request-URI for future requests. This response
+ is only cacheable if indicated by a Cache-Control or Expires header
+ field.
+
+ The temporary URI SHOULD be given by the Location field in the
+ response. Unless the request method was HEAD, the entity of the
+ response SHOULD contain a short hypertext note with a hyperlink to
+ the new URI(s) , since many pre-HTTP/1.1 user agents do not
+ understand the 307 status. Therefore, the note SHOULD contain the
+ information necessary for a user to repeat the original request on
+ the new URI.
+
+ If the 307 status code is received in response to a request other
+ than GET or HEAD, the user agent MUST NOT automatically redirect the
+ request unless it can be confirmed by the user, since this might
+ change the conditions under which the request was issued.
+
+10.4 Client Error 4xx
+
+ The 4xx class of status code is intended for cases in which the
+ client seems to have erred. Except when responding to a HEAD request,
+ the server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. These status codes are applicable to any request method.
+ User agents SHOULD display any included entity to the user.
+
+ If the client is sending data, a server implementation using TCP
+ SHOULD be careful to ensure that the client acknowledges receipt of
+ the packet(s) containing the response, before the server closes the
+ input connection. If the client continues sending data to the server
+ after the close, the server's TCP stack will send a reset packet to
+ the client, which may erase the client's unacknowledged input buffers
+ before they can be read and interpreted by the HTTP application.
+
+10.4.1 400 Bad Request
+
+ The request could not be understood by the server due to malformed
+ syntax. The client SHOULD NOT repeat the request without
+ modifications.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 65]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.2 401 Unauthorized
+
+ The request requires user authentication. The response MUST include a
+ WWW-Authenticate header field (section 14.47) containing a challenge
+ applicable to the requested resource. The client MAY repeat the
+ request with a suitable Authorization header field (section 14.8). If
+ the request already included Authorization credentials, then the 401
+ response indicates that authorization has been refused for those
+ credentials. If the 401 response contains the same challenge as the
+ prior response, and the user agent has already attempted
+ authentication at least once, then the user SHOULD be presented the
+ entity that was given in the response, since that entity might
+ include relevant diagnostic information. HTTP access authentication
+ is explained in "HTTP Authentication: Basic and Digest Access
+ Authentication" [43].
+
+10.4.3 402 Payment Required
+
+ This code is reserved for future use.
+
+10.4.4 403 Forbidden
+
+ The server understood the request, but is refusing to fulfill it.
+ Authorization will not help and the request SHOULD NOT be repeated.
+ If the request method was not HEAD and the server wishes to make
+ public why the request has not been fulfilled, it SHOULD describe the
+ reason for the refusal in the entity. If the server does not wish to
+ make this information available to the client, the status code 404
+ (Not Found) can be used instead.
+
+10.4.5 404 Not Found
+
+ The server has not found anything matching the Request-URI. No
+ indication is given of whether the condition is temporary or
+ permanent. The 410 (Gone) status code SHOULD be used if the server
+ knows, through some internally configurable mechanism, that an old
+ resource is permanently unavailable and has no forwarding address.
+ This status code is commonly used when the server does not wish to
+ reveal exactly why the request has been refused, or when no other
+ response is applicable.
+
+10.4.6 405 Method Not Allowed
+
+ The method specified in the Request-Line is not allowed for the
+ resource identified by the Request-URI. The response MUST include an
+ Allow header containing a list of valid methods for the requested
+ resource.
+
+
+
+
+Fielding, et al. Standards Track [Page 66]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.7 406 Not Acceptable
+
+ The resource identified by the request is only capable of generating
+ response entities which have content characteristics not acceptable
+ according to the accept headers sent in the request.
+
+ Unless it was a HEAD request, the response SHOULD include an entity
+ containing a list of available entity characteristics and location(s)
+ from which the user or user agent can choose the one most
+ appropriate. The entity format is specified by the media type given
+ in the Content-Type header field. Depending upon the format and the
+ capabilities of the user agent, selection of the most appropriate
+ choice MAY be performed automatically. However, this specification
+ does not define any standard for such automatic selection.
+
+ Note: HTTP/1.1 servers are allowed to return responses which are
+ not acceptable according to the accept headers sent in the
+ request. In some cases, this may even be preferable to sending a
+ 406 response. User agents are encouraged to inspect the headers of
+ an incoming response to determine if it is acceptable.
+
+ If the response could be unacceptable, a user agent SHOULD
+ temporarily stop receipt of more data and query the user for a
+ decision on further actions.
+
+10.4.8 407 Proxy Authentication Required
+
+ This code is similar to 401 (Unauthorized), but indicates that the
+ client must first authenticate itself with the proxy. The proxy MUST
+ return a Proxy-Authenticate header field (section 14.33) containing a
+ challenge applicable to the proxy for the requested resource. The
+ client MAY repeat the request with a suitable Proxy-Authorization
+ header field (section 14.34). HTTP access authentication is explained
+ in "HTTP Authentication: Basic and Digest Access Authentication"
+ [43].
+
+10.4.9 408 Request Timeout
+
+ The client did not produce a request within the time that the server
+ was prepared to wait. The client MAY repeat the request without
+ modifications at any later time.
+
+10.4.10 409 Conflict
+
+ The request could not be completed due to a conflict with the current
+ state of the resource. This code is only allowed in situations where
+ it is expected that the user might be able to resolve the conflict
+ and resubmit the request. The response body SHOULD include enough
+
+
+
+Fielding, et al. Standards Track [Page 67]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ information for the user to recognize the source of the conflict.
+ Ideally, the response entity would include enough information for the
+ user or user agent to fix the problem; however, that might not be
+ possible and is not required.
+
+ Conflicts are most likely to occur in response to a PUT request. For
+ example, if versioning were being used and the entity being PUT
+ included changes to a resource which conflict with those made by an
+ earlier (third-party) request, the server might use the 409 response
+ to indicate that it can't complete the request. In this case, the
+ response entity would likely contain a list of the differences
+ between the two versions in a format defined by the response
+ Content-Type.
+
+10.4.11 410 Gone
+
+ The requested resource is no longer available at the server and no
+ forwarding address is known. This condition is expected to be
+ considered permanent. Clients with link editing capabilities SHOULD
+ delete references to the Request-URI after user approval. If the
+ server does not know, or has no facility to determine, whether or not
+ the condition is permanent, the status code 404 (Not Found) SHOULD be
+ used instead. This response is cacheable unless indicated otherwise.
+
+ The 410 response is primarily intended to assist the task of web
+ maintenance by notifying the recipient that the resource is
+ intentionally unavailable and that the server owners desire that
+ remote links to that resource be removed. Such an event is common for
+ limited-time, promotional services and for resources belonging to
+ individuals no longer working at the server's site. It is not
+ necessary to mark all permanently unavailable resources as "gone" or
+ to keep the mark for any length of time -- that is left to the
+ discretion of the server owner.
+
+10.4.12 411 Length Required
+
+ The server refuses to accept the request without a defined Content-
+ Length. The client MAY repeat the request if it adds a valid
+ Content-Length header field containing the length of the message-body
+ in the request message.
+
+10.4.13 412 Precondition Failed
+
+ The precondition given in one or more of the request-header fields
+ evaluated to false when it was tested on the server. This response
+ code allows the client to place preconditions on the current resource
+ metainformation (header field data) and thus prevent the requested
+ method from being applied to a resource other than the one intended.
+
+
+
+Fielding, et al. Standards Track [Page 68]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.14 413 Request Entity Too Large
+
+ The server is refusing to process a request because the request
+ entity is larger than the server is willing or able to process. The
+ server MAY close the connection to prevent the client from continuing
+ the request.
+
+ If the condition is temporary, the server SHOULD include a Retry-
+ After header field to indicate that it is temporary and after what
+ time the client MAY try again.
+
+10.4.15 414 Request-URI Too Long
+
+ The server is refusing to service the request because the Request-URI
+ is longer than the server is willing to interpret. This rare
+ condition is only likely to occur when a client has improperly
+ converted a POST request to a GET request with long query
+ information, when the client has descended into a URI "black hole" of
+ redirection (e.g., a redirected URI prefix that points to a suffix of
+ itself), or when the server is under attack by a client attempting to
+ exploit security holes present in some servers using fixed-length
+ buffers for reading or manipulating the Request-URI.
+
+10.4.16 415 Unsupported Media Type
+
+ The server is refusing to service the request because the entity of
+ the request is in a format not supported by the requested resource
+ for the requested method.
+
+10.4.17 416 Requested Range Not Satisfiable
+
+ A server SHOULD return a response with this status code if a request
+ included a Range request-header field (section 14.35), and none of
+ the range-specifier values in this field overlap the current extent
+ of the selected resource, and the request did not include an If-Range
+ request-header field. (For byte-ranges, this means that the first-
+ byte-pos of all of the byte-range-spec values were greater than the
+ current length of the selected resource.)
+
+ When this status code is returned for a byte-range request, the
+ response SHOULD include a Content-Range entity-header field
+ specifying the current length of the selected resource (see section
+ 14.16). This response MUST NOT use the multipart/byteranges content-
+ type.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 69]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.4.18 417 Expectation Failed
+
+ The expectation given in an Expect request-header field (see section
+ 14.20) could not be met by this server, or, if the server is a proxy,
+ the server has unambiguous evidence that the request could not be met
+ by the next-hop server.
+
+10.5 Server Error 5xx
+
+ Response status codes beginning with the digit "5" indicate cases in
+ which the server is aware that it has erred or is incapable of
+ performing the request. Except when responding to a HEAD request, the
+ server SHOULD include an entity containing an explanation of the
+ error situation, and whether it is a temporary or permanent
+ condition. User agents SHOULD display any included entity to the
+ user. These response codes are applicable to any request method.
+
+10.5.1 500 Internal Server Error
+
+ The server encountered an unexpected condition which prevented it
+ from fulfilling the request.
+
+10.5.2 501 Not Implemented
+
+ The server does not support the functionality required to fulfill the
+ request. This is the appropriate response when the server does not
+ recognize the request method and is not capable of supporting it for
+ any resource.
+
+10.5.3 502 Bad Gateway
+
+ The server, while acting as a gateway or proxy, received an invalid
+ response from the upstream server it accessed in attempting to
+ fulfill the request.
+
+10.5.4 503 Service Unavailable
+
+ The server is currently unable to handle the request due to a
+ temporary overloading or maintenance of the server. The implication
+ is that this is a temporary condition which will be alleviated after
+ some delay. If known, the length of the delay MAY be indicated in a
+ Retry-After header. If no Retry-After is given, the client SHOULD
+ handle the response as it would for a 500 response.
+
+ Note: The existence of the 503 status code does not imply that a
+ server must use it when becoming overloaded. Some servers may wish
+ to simply refuse the connection.
+
+
+
+
+Fielding, et al. Standards Track [Page 70]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+10.5.5 504 Gateway Timeout
+
+ The server, while acting as a gateway or proxy, did not receive a
+ timely response from the upstream server specified by the URI (e.g.
+ HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed
+ to access in attempting to complete the request.
+
+ Note: Note to implementors: some deployed proxies are known to
+ return 400 or 500 when DNS lookups time out.
+
+10.5.6 505 HTTP Version Not Supported
+
+ The server does not support, or refuses to support, the HTTP protocol
+ version that was used in the request message. The server is
+ indicating that it is unable or unwilling to complete the request
+ using the same major version as the client, as described in section
+ 3.1, other than with this error message. The response SHOULD contain
+ an entity describing why that version is not supported and what other
+ protocols are supported by that server.
+
+11 Access Authentication
+
+ HTTP provides several OPTIONAL challenge-response authentication
+ mechanisms which can be used by a server to challenge a client
+ request and by a client to provide authentication information. The
+ general framework for access authentication, and the specification of
+ "basic" and "digest" authentication, are specified in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. This
+ specification adopts the definitions of "challenge" and "credentials"
+ from that specification.
+
+12 Content Negotiation
+
+ Most HTTP responses include an entity which contains information for
+ interpretation by a human user. Naturally, it is desirable to supply
+ the user with the "best available" entity corresponding to the
+ request. Unfortunately for servers and caches, not all users have the
+ same preferences for what is "best," and not all user agents are
+ equally capable of rendering all entity types. For that reason, HTTP
+ has provisions for several mechanisms for "content negotiation" --
+ the process of selecting the best representation for a given response
+ when there are multiple representations available.
+
+ Note: This is not called "format negotiation" because the
+ alternate representations may be of the same media type, but use
+ different capabilities of that type, be in different languages,
+ etc.
+
+
+
+
+Fielding, et al. Standards Track [Page 71]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Any response containing an entity-body MAY be subject to negotiation,
+ including error responses.
+
+ There are two kinds of content negotiation which are possible in
+ HTTP: server-driven and agent-driven negotiation. These two kinds of
+ negotiation are orthogonal and thus may be used separately or in
+ combination. One method of combination, referred to as transparent
+ negotiation, occurs when a cache uses the agent-driven negotiation
+ information provided by the origin server in order to provide
+ server-driven negotiation for subsequent requests.
+
+12.1 Server-driven Negotiation
+
+ If the selection of the best representation for a response is made by
+ an algorithm located at the server, it is called server-driven
+ negotiation. Selection is based on the available representations of
+ the response (the dimensions over which it can vary; e.g. language,
+ content-coding, etc.) and the contents of particular header fields in
+ the request message or on other information pertaining to the request
+ (such as the network address of the client).
+
+ Server-driven negotiation is advantageous when the algorithm for
+ selecting from among the available representations is difficult to
+ describe to the user agent, or when the server desires to send its
+ "best guess" to the client along with the first response (hoping to
+ avoid the round-trip delay of a subsequent request if the "best
+ guess" is good enough for the user). In order to improve the server's
+ guess, the user agent MAY include request header fields (Accept,
+ Accept-Language, Accept-Encoding, etc.) which describe its
+ preferences for such a response.
+
+ Server-driven negotiation has disadvantages:
+
+ 1. It is impossible for the server to accurately determine what
+ might be "best" for any given user, since that would require
+ complete knowledge of both the capabilities of the user agent
+ and the intended use for the response (e.g., does the user want
+ to view it on screen or print it on paper?).
+
+ 2. Having the user agent describe its capabilities in every
+ request can be both very inefficient (given that only a small
+ percentage of responses have multiple representations) and a
+ potential violation of the user's privacy.
+
+ 3. It complicates the implementation of an origin server and the
+ algorithms for generating responses to a request.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 72]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 4. It may limit a public cache's ability to use the same response
+ for multiple user's requests.
+
+ HTTP/1.1 includes the following request-header fields for enabling
+ server-driven negotiation through description of user agent
+ capabilities and user preferences: Accept (section 14.1), Accept-
+ Charset (section 14.2), Accept-Encoding (section 14.3), Accept-
+ Language (section 14.4), and User-Agent (section 14.43). However, an
+ origin server is not limited to these dimensions and MAY vary the
+ response based on any aspect of the request, including information
+ outside the request-header fields or within extension header fields
+ not defined by this specification.
+
+ The Vary header field can be used to express the parameters the
+ server uses to select a representation that is subject to server-
+ driven negotiation. See section 13.6 for use of the Vary header field
+ by caches and section 14.44 for use of the Vary header field by
+ servers.
+
+12.2 Agent-driven Negotiation
+
+ With agent-driven negotiation, selection of the best representation
+ for a response is performed by the user agent after receiving an
+ initial response from the origin server. Selection is based on a list
+ of the available representations of the response included within the
+ header fields or entity-body of the initial response, with each
+ representation identified by its own URI. Selection from among the
+ representations may be performed automatically (if the user agent is
+ capable of doing so) or manually by the user selecting from a
+ generated (possibly hypertext) menu.
+
+ Agent-driven negotiation is advantageous when the response would vary
+ over commonly-used dimensions (such as type, language, or encoding),
+ when the origin server is unable to determine a user agent's
+ capabilities from examining the request, and generally when public
+ caches are used to distribute server load and reduce network usage.
+
+ Agent-driven negotiation suffers from the disadvantage of needing a
+ second request to obtain the best alternate representation. This
+ second request is only efficient when caching is used. In addition,
+ this specification does not define any mechanism for supporting
+ automatic selection, though it also does not prevent any such
+ mechanism from being developed as an extension and used within
+ HTTP/1.1.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 73]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable)
+ status codes for enabling agent-driven negotiation when the server is
+ unwilling or unable to provide a varying response using server-driven
+ negotiation.
+
+12.3 Transparent Negotiation
+
+ Transparent negotiation is a combination of both server-driven and
+ agent-driven negotiation. When a cache is supplied with a form of the
+ list of available representations of the response (as in agent-driven
+ negotiation) and the dimensions of variance are completely understood
+ by the cache, then the cache becomes capable of performing server-
+ driven negotiation on behalf of the origin server for subsequent
+ requests on that resource.
+
+ Transparent negotiation has the advantage of distributing the
+ negotiation work that would otherwise be required of the origin
+ server and also removing the second request delay of agent-driven
+ negotiation when the cache is able to correctly guess the right
+ response.
+
+ This specification does not define any mechanism for transparent
+ negotiation, though it also does not prevent any such mechanism from
+ being developed as an extension that could be used within HTTP/1.1.
+
+13 Caching in HTTP
+
+ HTTP is typically used for distributed information systems, where
+ performance can be improved by the use of response caches. The
+ HTTP/1.1 protocol includes a number of elements intended to make
+ caching work as well as possible. Because these elements are
+ inextricable from other aspects of the protocol, and because they
+ interact with each other, it is useful to describe the basic caching
+ design of HTTP separately from the detailed descriptions of methods,
+ headers, response codes, etc.
+
+ Caching would be useless if it did not significantly improve
+ performance. The goal of caching in HTTP/1.1 is to eliminate the need
+ to send requests in many cases, and to eliminate the need to send
+ full responses in many other cases. The former reduces the number of
+ network round-trips required for many operations; we use an
+ "expiration" mechanism for this purpose (see section 13.2). The
+ latter reduces network bandwidth requirements; we use a "validation"
+ mechanism for this purpose (see section 13.3).
+
+ Requirements for performance, availability, and disconnected
+ operation require us to be able to relax the goal of semantic
+ transparency. The HTTP/1.1 protocol allows origin servers, caches,
+
+
+
+Fielding, et al. Standards Track [Page 74]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ and clients to explicitly reduce transparency when necessary.
+ However, because non-transparent operation may confuse non-expert
+ users, and might be incompatible with certain server applications
+ (such as those for ordering merchandise), the protocol requires that
+ transparency be relaxed
+
+ - only by an explicit protocol-level request when relaxed by
+ client or origin server
+
+ - only with an explicit warning to the end user when relaxed by
+ cache or client
+
+ Therefore, the HTTP/1.1 protocol provides these important elements:
+
+ 1. Protocol features that provide full semantic transparency when
+ this is required by all parties.
+
+ 2. Protocol features that allow an origin server or user agent to
+ explicitly request and control non-transparent operation.
+
+ 3. Protocol features that allow a cache to attach warnings to
+ responses that do not preserve the requested approximation of
+ semantic transparency.
+
+ A basic principle is that it must be possible for the clients to
+ detect any potential relaxation of semantic transparency.
+
+ Note: The server, cache, or client implementor might be faced with
+ design decisions not explicitly discussed in this specification.
+ If a decision might affect semantic transparency, the implementor
+ ought to err on the side of maintaining transparency unless a
+ careful and complete analysis shows significant benefits in
+ breaking transparency.
+
+13.1.1 Cache Correctness
+
+ A correct cache MUST respond to a request with the most up-to-date
+ response held by the cache that is appropriate to the request (see
+ sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
+ conditions:
+
+ 1. It has been checked for equivalence with what the origin server
+ would have returned by revalidating the response with the
+ origin server (section 13.3);
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 75]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 2. It is "fresh enough" (see section 13.2). In the default case,
+ this means it meets the least restrictive freshness requirement
+ of the client, origin server, and cache (see section 14.9); if
+ the origin server so specifies, it is the freshness requirement
+ of the origin server alone.
+
+ If a stored response is not "fresh enough" by the most
+ restrictive freshness requirement of both the client and the
+ origin server, in carefully considered circumstances the cache
+ MAY still return the response with the appropriate Warning
+ header (see section 13.1.5 and 14.46), unless such a response
+ is prohibited (e.g., by a "no-store" cache-directive, or by a
+ "no-cache" cache-request-directive; see section 14.9).
+
+ 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect),
+ or error (4xx or 5xx) response message.
+
+ If the cache can not communicate with the origin server, then a
+ correct cache SHOULD respond as above if the response can be
+ correctly served from the cache; if not it MUST return an error or
+ warning indicating that there was a communication failure.
+
+ If a cache receives a response (either an entire response, or a 304
+ (Not Modified) response) that it would normally forward to the
+ requesting client, and the received response is no longer fresh, the
+ cache SHOULD forward it to the requesting client without adding a new
+ Warning (but without removing any existing Warning headers). A cache
+ SHOULD NOT attempt to revalidate a response simply because that
+ response became stale in transit; this might lead to an infinite
+ loop. A user agent that receives a stale response without a Warning
+ MAY display a warning indication to the user.
+
+13.1.2 Warnings
+
+ Whenever a cache returns a response that is neither first-hand nor
+ "fresh enough" (in the sense of condition 2 in section 13.1.1), it
+ MUST attach a warning to that effect, using a Warning general-header.
+ The Warning header and the currently defined warnings are described
+ in section 14.46. The warning allows clients to take appropriate
+ action.
+
+ Warnings MAY be used for other purposes, both cache-related and
+ otherwise. The use of a warning, rather than an error status code,
+ distinguish these responses from true failures.
+
+ Warnings are assigned three digit warn-codes. The first digit
+ indicates whether the Warning MUST or MUST NOT be deleted from a
+ stored cache entry after a successful revalidation:
+
+
+
+Fielding, et al. Standards Track [Page 76]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1xx Warnings that describe the freshness or revalidation status of
+ the response, and so MUST be deleted after a successful
+ revalidation. 1XX warn-codes MAY be generated by a cache only when
+ validating a cached entry. It MUST NOT be generated by clients.
+
+ 2xx Warnings that describe some aspect of the entity body or entity
+ headers that is not rectified by a revalidation (for example, a
+ lossy compression of the entity bodies) and which MUST NOT be
+ deleted after a successful revalidation.
+
+ See section 14.46 for the definitions of the codes themselves.
+
+ HTTP/1.0 caches will cache all Warnings in responses, without
+ deleting the ones in the first category. Warnings in responses that
+ are passed to HTTP/1.0 caches carry an extra warning-date field,
+ which prevents a future HTTP/1.1 recipient from believing an
+ erroneously cached Warning.
+
+ Warnings also carry a warning text. The text MAY be in any
+ appropriate natural language (perhaps based on the client's Accept
+ headers), and include an OPTIONAL indication of what character set is
+ used.
+
+ Multiple warnings MAY be attached to a response (either by the origin
+ server or by a cache), including multiple warnings with the same code
+ number. For example, a server might provide the same warning with
+ texts in both English and Basque.
+
+ When multiple warnings are attached to a response, it might not be
+ practical or reasonable to display all of them to the user. This
+ version of HTTP does not specify strict priority rules for deciding
+ which warnings to display and in what order, but does suggest some
+ heuristics.
+
+13.1.3 Cache-control Mechanisms
+
+ The basic cache mechanisms in HTTP/1.1 (server-specified expiration
+ times and validators) are implicit directives to caches. In some
+ cases, a server or client might need to provide explicit directives
+ to the HTTP caches. We use the Cache-Control header for this purpose.
+
+ The Cache-Control header allows a client or server to transmit a
+ variety of directives in either requests or responses. These
+ directives typically override the default caching algorithms. As a
+ general rule, if there is any apparent conflict between header
+ values, the most restrictive interpretation is applied (that is, the
+ one that is most likely to preserve semantic transparency). However,
+
+
+
+
+Fielding, et al. Standards Track [Page 77]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ in some cases, cache-control directives are explicitly specified as
+ weakening the approximation of semantic transparency (for example,
+ "max-stale" or "public").
+
+ The cache-control directives are described in detail in section 14.9.
+
+13.1.4 Explicit User Agent Warnings
+
+ Many user agents make it possible for users to override the basic
+ caching mechanisms. For example, the user agent might allow the user
+ to specify that cached entities (even explicitly stale ones) are
+ never validated. Or the user agent might habitually add "Cache-
+ Control: max-stale=3600" to every request. The user agent SHOULD NOT
+ default to either non-transparent behavior, or behavior that results
+ in abnormally ineffective caching, but MAY be explicitly configured
+ to do so by an explicit action of the user.
+
+ If the user has overridden the basic caching mechanisms, the user
+ agent SHOULD explicitly indicate to the user whenever this results in
+ the display of information that might not meet the server's
+ transparency requirements (in particular, if the displayed entity is
+ known to be stale). Since the protocol normally allows the user agent
+ to determine if responses are stale or not, this indication need only
+ be displayed when this actually happens. The indication need not be a
+ dialog box; it could be an icon (for example, a picture of a rotting
+ fish) or some other indicator.
+
+ If the user has overridden the caching mechanisms in a way that would
+ abnormally reduce the effectiveness of caches, the user agent SHOULD
+ continually indicate this state to the user (for example, by a
+ display of a picture of currency in flames) so that the user does not
+ inadvertently consume excess resources or suffer from excessive
+ latency.
+
+13.1.5 Exceptions to the Rules and Warnings
+
+ In some cases, the operator of a cache MAY choose to configure it to
+ return stale responses even when not requested by clients. This
+ decision ought not be made lightly, but may be necessary for reasons
+ of availability or performance, especially when the cache is poorly
+ connected to the origin server. Whenever a cache returns a stale
+ response, it MUST mark it as such (using a Warning header) enabling
+ the client software to alert the user that there might be a potential
+ problem.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 78]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ It also allows the user agent to take steps to obtain a first-hand or
+ fresh response. For this reason, a cache SHOULD NOT return a stale
+ response if the client explicitly requests a first-hand or fresh one,
+ unless it is impossible to comply for technical or policy reasons.
+
+13.1.6 Client-controlled Behavior
+
+ While the origin server (and to a lesser extent, intermediate caches,
+ by their contribution to the age of a response) are the primary
+ source of expiration information, in some cases the client might need
+ to control a cache's decision about whether to return a cached
+ response without validating it. Clients do this using several
+ directives of the Cache-Control header.
+
+ A client's request MAY specify the maximum age it is willing to
+ accept of an unvalidated response; specifying a value of zero forces
+ the cache(s) to revalidate all responses. A client MAY also specify
+ the minimum time remaining before a response expires. Both of these
+ options increase constraints on the behavior of caches, and so cannot
+ further relax the cache's approximation of semantic transparency.
+
+ A client MAY also specify that it will accept stale responses, up to
+ some maximum amount of staleness. This loosens the constraints on the
+ caches, and so might violate the origin server's specified
+ constraints on semantic transparency, but might be necessary to
+ support disconnected operation, or high availability in the face of
+ poor connectivity.
+
+13.2 Expiration Model
+
+13.2.1 Server-Specified Expiration
+
+ HTTP caching works best when caches can entirely avoid making
+ requests to the origin server. The primary mechanism for avoiding
+ requests is for an origin server to provide an explicit expiration
+ time in the future, indicating that a response MAY be used to satisfy
+ subsequent requests. In other words, a cache can return a fresh
+ response without first contacting the server.
+
+ Our expectation is that servers will assign future explicit
+ expiration times to responses in the belief that the entity is not
+ likely to change, in a semantically significant way, before the
+ expiration time is reached. This normally preserves semantic
+ transparency, as long as the server's expiration times are carefully
+ chosen.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 79]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The expiration mechanism applies only to responses taken from a cache
+ and not to first-hand responses forwarded immediately to the
+ requesting client.
+
+ If an origin server wishes to force a semantically transparent cache
+ to validate every request, it MAY assign an explicit expiration time
+ in the past. This means that the response is always stale, and so the
+ cache SHOULD validate it before using it for subsequent requests. See
+ section 14.9.4 for a more restrictive way to force revalidation.
+
+ If an origin server wishes to force any HTTP/1.1 cache, no matter how
+ it is configured, to validate every request, it SHOULD use the "must-
+ revalidate" cache-control directive (see section 14.9).
+
+ Servers specify explicit expiration times using either the Expires
+ header, or the max-age directive of the Cache-Control header.
+
+ An expiration time cannot be used to force a user agent to refresh
+ its display or reload a resource; its semantics apply only to caching
+ mechanisms, and such mechanisms need only check a resource's
+ expiration status when a new request for that resource is initiated.
+ See section 13.13 for an explanation of the difference between caches
+ and history mechanisms.
+
+13.2.2 Heuristic Expiration
+
+ Since origin servers do not always provide explicit expiration times,
+ HTTP caches typically assign heuristic expiration times, employing
+ algorithms that use other header values (such as the Last-Modified
+ time) to estimate a plausible expiration time. The HTTP/1.1
+ specification does not provide specific algorithms, but does impose
+ worst-case constraints on their results. Since heuristic expiration
+ times might compromise semantic transparency, they ought to used
+ cautiously, and we encourage origin servers to provide explicit
+ expiration times as much as possible.
+
+13.2.3 Age Calculations
+
+ In order to know if a cached entry is fresh, a cache needs to know if
+ its age exceeds its freshness lifetime. We discuss how to calculate
+ the latter in section 13.2.4; this section describes how to calculate
+ the age of a response or cache entry.
+
+ In this discussion, we use the term "now" to mean "the current value
+ of the clock at the host performing the calculation." Hosts that use
+ HTTP, but especially hosts running origin servers and caches, SHOULD
+ use NTP [28] or some similar protocol to synchronize their clocks to
+ a globally accurate time standard.
+
+
+
+Fielding, et al. Standards Track [Page 80]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ HTTP/1.1 requires origin servers to send a Date header, if possible,
+ with every response, giving the time at which the response was
+ generated (see section 14.18). We use the term "date_value" to denote
+ the value of the Date header, in a form appropriate for arithmetic
+ operations.
+
+ HTTP/1.1 uses the Age response-header to convey the estimated age of
+ the response message when obtained from a cache. The Age field value
+ is the cache's estimate of the amount of time since the response was
+ generated or revalidated by the origin server.
+
+ In essence, the Age value is the sum of the time that the response
+ has been resident in each of the caches along the path from the
+ origin server, plus the amount of time it has been in transit along
+ network paths.
+
+ We use the term "age_value" to denote the value of the Age header, in
+ a form appropriate for arithmetic operations.
+
+ A response's age can be calculated in two entirely independent ways:
+
+ 1. now minus date_value, if the local clock is reasonably well
+ synchronized to the origin server's clock. If the result is
+ negative, the result is replaced by zero.
+
+ 2. age_value, if all of the caches along the response path
+ implement HTTP/1.1.
+
+ Given that we have two independent ways to compute the age of a
+ response when it is received, we can combine these as
+
+ corrected_received_age = max(now - date_value, age_value)
+
+ and as long as we have either nearly synchronized clocks or all-
+ HTTP/1.1 paths, one gets a reliable (conservative) result.
+
+ Because of network-imposed delays, some significant interval might
+ pass between the time that a server generates a response and the time
+ it is received at the next outbound cache or client. If uncorrected,
+ this delay could result in improperly low ages.
+
+ Because the request that resulted in the returned Age value must have
+ been initiated prior to that Age value's generation, we can correct
+ for delays imposed by the network by recording the time at which the
+ request was initiated. Then, when an Age value is received, it MUST
+ be interpreted relative to the time the request was initiated, not
+
+
+
+
+
+Fielding, et al. Standards Track [Page 81]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the time that the response was received. This algorithm results in
+ conservative behavior no matter how much delay is experienced. So, we
+ compute:
+
+ corrected_initial_age = corrected_received_age
+ + (now - request_time)
+
+ where "request_time" is the time (according to the local clock) when
+ the request that elicited this response was sent.
+
+ Summary of age calculation algorithm, when a cache receives a
+ response:
+
+ /*
+ * age_value
+ * is the value of Age: header received by the cache with
+ * this response.
+ * date_value
+ * is the value of the origin server's Date: header
+ * request_time
+ * is the (local) time when the cache made the request
+ * that resulted in this cached response
+ * response_time
+ * is the (local) time when the cache received the
+ * response
+ * now
+ * is the current (local) time
+ */
+
+ apparent_age = max(0, response_time - date_value);
+ corrected_received_age = max(apparent_age, age_value);
+ response_delay = response_time - request_time;
+ corrected_initial_age = corrected_received_age + response_delay;
+ resident_time = now - response_time;
+ current_age = corrected_initial_age + resident_time;
+
+ The current_age of a cache entry is calculated by adding the amount
+ of time (in seconds) since the cache entry was last validated by the
+ origin server to the corrected_initial_age. When a response is
+ generated from a cache entry, the cache MUST include a single Age
+ header field in the response with a value equal to the cache entry's
+ current_age.
+
+ The presence of an Age header field in a response implies that a
+ response is not first-hand. However, the converse is not true, since
+ the lack of an Age header field in a response does not imply that the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 82]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ response is first-hand unless all caches along the request path are
+ compliant with HTTP/1.1 (i.e., older HTTP caches did not implement
+ the Age header field).
+
+13.2.4 Expiration Calculations
+
+ In order to decide whether a response is fresh or stale, we need to
+ compare its freshness lifetime to its age. The age is calculated as
+ described in section 13.2.3; this section describes how to calculate
+ the freshness lifetime, and to determine if a response has expired.
+ In the discussion below, the values can be represented in any form
+ appropriate for arithmetic operations.
+
+ We use the term "expires_value" to denote the value of the Expires
+ header. We use the term "max_age_value" to denote an appropriate
+ value of the number of seconds carried by the "max-age" directive of
+ the Cache-Control header in a response (see section 14.9.3).
+
+ The max-age directive takes priority over Expires, so if max-age is
+ present in a response, the calculation is simply:
+
+ freshness_lifetime = max_age_value
+
+ Otherwise, if Expires is present in the response, the calculation is:
+
+ freshness_lifetime = expires_value - date_value
+
+ Note that neither of these calculations is vulnerable to clock skew,
+ since all of the information comes from the origin server.
+
+ If none of Expires, Cache-Control: max-age, or Cache-Control: s-
+ maxage (see section 14.9.3) appears in the response, and the response
+ does not include other restrictions on caching, the cache MAY compute
+ a freshness lifetime using a heuristic. The cache MUST attach Warning
+ 113 to any response whose age is more than 24 hours if such warning
+ has not already been added.
+
+ Also, if the response does have a Last-Modified time, the heuristic
+ expiration value SHOULD be no more than some fraction of the interval
+ since that time. A typical setting of this fraction might be 10%.
+
+ The calculation to determine if a response has expired is quite
+ simple:
+
+ response_is_fresh = (freshness_lifetime > current_age)
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 83]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.2.5 Disambiguating Expiration Values
+
+ Because expiration values are assigned optimistically, it is possible
+ for two caches to contain fresh values for the same resource that are
+ different.
+
+ If a client performing a retrieval receives a non-first-hand response
+ for a request that was already fresh in its own cache, and the Date
+ header in its existing cache entry is newer than the Date on the new
+ response, then the client MAY ignore the response. If so, it MAY
+ retry the request with a "Cache-Control: max-age=0" directive (see
+ section 14.9), to force a check with the origin server.
+
+ If a cache has two fresh responses for the same representation with
+ different validators, it MUST use the one with the more recent Date
+ header. This situation might arise because the cache is pooling
+ responses from other caches, or because a client has asked for a
+ reload or a revalidation of an apparently fresh cache entry.
+
+13.2.6 Disambiguating Multiple Responses
+
+ Because a client might be receiving responses via multiple paths, so
+ that some responses flow through one set of caches and other
+ responses flow through a different set of caches, a client might
+ receive responses in an order different from that in which the origin
+ server sent them. We would like the client to use the most recently
+ generated response, even if older responses are still apparently
+ fresh.
+
+ Neither the entity tag nor the expiration value can impose an
+ ordering on responses, since it is possible that a later response
+ intentionally carries an earlier expiration time. The Date values are
+ ordered to a granularity of one second.
+
+ When a client tries to revalidate a cache entry, and the response it
+ receives contains a Date header that appears to be older than the one
+ for the existing entry, then the client SHOULD repeat the request
+ unconditionally, and include
+
+ Cache-Control: max-age=0
+
+ to force any intermediate caches to validate their copies directly
+ with the origin server, or
+
+ Cache-Control: no-cache
+
+ to force any intermediate caches to obtain a new copy from the origin
+ server.
+
+
+
+Fielding, et al. Standards Track [Page 84]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the Date values are equal, then the client MAY use either response
+ (or MAY, if it is being extremely prudent, request a new response).
+ Servers MUST NOT depend on clients being able to choose
+ deterministically between responses generated during the same second,
+ if their expiration times overlap.
+
+13.3 Validation Model
+
+ When a cache has a stale entry that it would like to use as a
+ response to a client's request, it first has to check with the origin
+ server (or possibly an intermediate cache with a fresh response) to
+ see if its cached entry is still usable. We call this "validating"
+ the cache entry. Since we do not want to have to pay the overhead of
+ retransmitting the full response if the cached entry is good, and we
+ do not want to pay the overhead of an extra round trip if the cached
+ entry is invalid, the HTTP/1.1 protocol supports the use of
+ conditional methods.
+
+ The key protocol features for supporting conditional methods are
+ those concerned with "cache validators." When an origin server
+ generates a full response, it attaches some sort of validator to it,
+ which is kept with the cache entry. When a client (user agent or
+ proxy cache) makes a conditional request for a resource for which it
+ has a cache entry, it includes the associated validator in the
+ request.
+
+ The server then checks that validator against the current validator
+ for the entity, and, if they match (see section 13.3.3), it responds
+ with a special status code (usually, 304 (Not Modified)) and no
+ entity-body. Otherwise, it returns a full response (including
+ entity-body). Thus, we avoid transmitting the full response if the
+ validator matches, and we avoid an extra round trip if it does not
+ match.
+
+ In HTTP/1.1, a conditional request looks exactly the same as a normal
+ request for the same resource, except that it carries a special
+ header (which includes the validator) that implicitly turns the
+ method (usually, GET) into a conditional.
+
+ The protocol includes both positive and negative senses of cache-
+ validating conditions. That is, it is possible to request either that
+ a method be performed if and only if a validator matches or if and
+ only if no validators match.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 85]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note: a response that lacks a validator may still be cached, and
+ served from cache until it expires, unless this is explicitly
+ prohibited by a cache-control directive. However, a cache cannot
+ do a conditional retrieval if it does not have a validator for the
+ entity, which means it will not be refreshable after it expires.
+
+13.3.1 Last-Modified Dates
+
+ The Last-Modified entity-header field value is often used as a cache
+ validator. In simple terms, a cache entry is considered to be valid
+ if the entity has not been modified since the Last-Modified value.
+
+13.3.2 Entity Tag Cache Validators
+
+ The ETag response-header field value, an entity tag, provides for an
+ "opaque" cache validator. This might allow more reliable validation
+ in situations where it is inconvenient to store modification dates,
+ where the one-second resolution of HTTP date values is not
+ sufficient, or where the origin server wishes to avoid certain
+ paradoxes that might arise from the use of modification dates.
+
+ Entity Tags are described in section 3.11. The headers used with
+ entity tags are described in sections 14.19, 14.24, 14.26 and 14.44.
+
+13.3.3 Weak and Strong Validators
+
+ Since both origin servers and caches will compare two validators to
+ decide if they represent the same or different entities, one normally
+ would expect that if the entity (the entity-body or any entity-
+ headers) changes in any way, then the associated validator would
+ change as well. If this is true, then we call this validator a
+ "strong validator."
+
+ However, there might be cases when a server prefers to change the
+ validator only on semantically significant changes, and not when
+ insignificant aspects of the entity change. A validator that does not
+ always change when the resource changes is a "weak validator."
+
+ Entity tags are normally "strong validators," but the protocol
+ provides a mechanism to tag an entity tag as "weak." One can think of
+ a strong validator as one that changes whenever the bits of an entity
+ changes, while a weak value changes whenever the meaning of an entity
+ changes. Alternatively, one can think of a strong validator as part
+ of an identifier for a specific entity, while a weak validator is
+ part of an identifier for a set of semantically equivalent entities.
+
+ Note: One example of a strong validator is an integer that is
+ incremented in stable storage every time an entity is changed.
+
+
+
+Fielding, et al. Standards Track [Page 86]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An entity's modification time, if represented with one-second
+ resolution, could be a weak validator, since it is possible that
+ the resource might be modified twice during a single second.
+
+ Support for weak validators is optional. However, weak validators
+ allow for more efficient caching of equivalent objects; for
+ example, a hit counter on a site is probably good enough if it is
+ updated every few days or weeks, and any value during that period
+ is likely "good enough" to be equivalent.
+
+ A "use" of a validator is either when a client generates a request
+ and includes the validator in a validating header field, or when a
+ server compares two validators.
+
+ Strong validators are usable in any context. Weak validators are only
+ usable in contexts that do not depend on exact equality of an entity.
+ For example, either kind is usable for a conditional GET of a full
+ entity. However, only a strong validator is usable for a sub-range
+ retrieval, since otherwise the client might end up with an internally
+ inconsistent entity.
+
+ Clients MAY issue simple (non-subrange) GET requests with either weak
+ validators or strong validators. Clients MUST NOT use weak validators
+ in other forms of request.
+
+ The only function that the HTTP/1.1 protocol defines on validators is
+ comparison. There are two validator comparison functions, depending
+ on whether the comparison context allows the use of weak validators
+ or not:
+
+ - The strong comparison function: in order to be considered equal,
+ both validators MUST be identical in every way, and both MUST
+ NOT be weak.
+
+ - The weak comparison function: in order to be considered equal,
+ both validators MUST be identical in every way, but either or
+ both of them MAY be tagged as "weak" without affecting the
+ result.
+
+ An entity tag is strong unless it is explicitly tagged as weak.
+ Section 3.11 gives the syntax for entity tags.
+
+ A Last-Modified time, when used as a validator in a request, is
+ implicitly weak unless it is possible to deduce that it is strong,
+ using the following rules:
+
+ - The validator is being compared by an origin server to the
+ actual current validator for the entity and,
+
+
+
+Fielding, et al. Standards Track [Page 87]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - That origin server reliably knows that the associated entity did
+ not change twice during the second covered by the presented
+ validator.
+
+ or
+
+ - The validator is about to be used by a client in an If-
+ Modified-Since or If-Unmodified-Since header, because the client
+ has a cache entry for the associated entity, and
+
+ - That cache entry includes a Date value, which gives the time
+ when the origin server sent the original response, and
+
+ - The presented Last-Modified time is at least 60 seconds before
+ the Date value.
+
+ or
+
+ - The validator is being compared by an intermediate cache to the
+ validator stored in its cache entry for the entity, and
+
+ - That cache entry includes a Date value, which gives the time
+ when the origin server sent the original response, and
+
+ - The presented Last-Modified time is at least 60 seconds before
+ the Date value.
+
+ This method relies on the fact that if two different responses were
+ sent by the origin server during the same second, but both had the
+ same Last-Modified time, then at least one of those responses would
+ have a Date value equal to its Last-Modified time. The arbitrary 60-
+ second limit guards against the possibility that the Date and Last-
+ Modified values are generated from different clocks, or at somewhat
+ different times during the preparation of the response. An
+ implementation MAY use a value larger than 60 seconds, if it is
+ believed that 60 seconds is too short.
+
+ If a client wishes to perform a sub-range retrieval on a value for
+ which it has only a Last-Modified time and no opaque validator, it
+ MAY do this only if the Last-Modified time is strong in the sense
+ described here.
+
+ A cache or origin server receiving a conditional request, other than
+ a full-body GET request, MUST use the strong comparison function to
+ evaluate the condition.
+
+ These rules allow HTTP/1.1 caches and clients to safely perform sub-
+ range retrievals on values that have been obtained from HTTP/1.0
+
+
+
+Fielding, et al. Standards Track [Page 88]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ servers.
+
+13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates
+
+ We adopt a set of rules and recommendations for origin servers,
+ clients, and caches regarding when various validator types ought to
+ be used, and for what purposes.
+
+ HTTP/1.1 origin servers:
+
+ - SHOULD send an entity tag validator unless it is not feasible to
+ generate one.
+
+ - MAY send a weak entity tag instead of a strong entity tag, if
+ performance considerations support the use of weak entity tags,
+ or if it is unfeasible to send a strong entity tag.
+
+ - SHOULD send a Last-Modified value if it is feasible to send one,
+ unless the risk of a breakdown in semantic transparency that
+ could result from using this date in an If-Modified-Since header
+ would lead to serious problems.
+
+ In other words, the preferred behavior for an HTTP/1.1 origin server
+ is to send both a strong entity tag and a Last-Modified value.
+
+ In order to be legal, a strong entity tag MUST change whenever the
+ associated entity value changes in any way. A weak entity tag SHOULD
+ change whenever the associated entity changes in a semantically
+ significant way.
+
+ Note: in order to provide semantically transparent caching, an
+ origin server must avoid reusing a specific strong entity tag
+ value for two different entities, or reusing a specific weak
+ entity tag value for two semantically different entities. Cache
+ entries might persist for arbitrarily long periods, regardless of
+ expiration times, so it might be inappropriate to expect that a
+ cache will never again attempt to validate an entry using a
+ validator that it obtained at some point in the past.
+
+ HTTP/1.1 clients:
+
+ - If an entity tag has been provided by the origin server, MUST
+ use that entity tag in any cache-conditional request (using If-
+ Match or If-None-Match).
+
+ - If only a Last-Modified value has been provided by the origin
+ server, SHOULD use that value in non-subrange cache-conditional
+ requests (using If-Modified-Since).
+
+
+
+Fielding, et al. Standards Track [Page 89]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If only a Last-Modified value has been provided by an HTTP/1.0
+ origin server, MAY use that value in subrange cache-conditional
+ requests (using If-Unmodified-Since:). The user agent SHOULD
+ provide a way to disable this, in case of difficulty.
+
+ - If both an entity tag and a Last-Modified value have been
+ provided by the origin server, SHOULD use both validators in
+ cache-conditional requests. This allows both HTTP/1.0 and
+ HTTP/1.1 caches to respond appropriately.
+
+ An HTTP/1.1 origin server, upon receiving a conditional request that
+ includes both a Last-Modified date (e.g., in an If-Modified-Since or
+ If-Unmodified-Since header field) and one or more entity tags (e.g.,
+ in an If-Match, If-None-Match, or If-Range header field) as cache
+ validators, MUST NOT return a response status of 304 (Not Modified)
+ unless doing so is consistent with all of the conditional header
+ fields in the request.
+
+ An HTTP/1.1 caching proxy, upon receiving a conditional request that
+ includes both a Last-Modified date and one or more entity tags as
+ cache validators, MUST NOT return a locally cached response to the
+ client unless that cached response is consistent with all of the
+ conditional header fields in the request.
+
+ Note: The general principle behind these rules is that HTTP/1.1
+ servers and clients should transmit as much non-redundant
+ information as is available in their responses and requests.
+ HTTP/1.1 systems receiving this information will make the most
+ conservative assumptions about the validators they receive.
+
+ HTTP/1.0 clients and caches will ignore entity tags. Generally,
+ last-modified values received or used by these systems will
+ support transparent and efficient caching, and so HTTP/1.1 origin
+ servers should provide Last-Modified values. In those rare cases
+ where the use of a Last-Modified value as a validator by an
+ HTTP/1.0 system could result in a serious problem, then HTTP/1.1
+ origin servers should not provide one.
+
+13.3.5 Non-validating Conditionals
+
+ The principle behind entity tags is that only the service author
+ knows the semantics of a resource well enough to select an
+ appropriate cache validation mechanism, and the specification of any
+ validator comparison function more complex than byte-equality would
+ open up a can of worms. Thus, comparisons of any other headers
+ (except Last-Modified, for compatibility with HTTP/1.0) are never
+ used for purposes of validating a cache entry.
+
+
+
+
+Fielding, et al. Standards Track [Page 90]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.4 Response Cacheability
+
+ Unless specifically constrained by a cache-control (section 14.9)
+ directive, a caching system MAY always store a successful response
+ (see section 13.8) as a cache entry, MAY return it without validation
+ if it is fresh, and MAY return it after successful validation. If
+ there is neither a cache validator nor an explicit expiration time
+ associated with a response, we do not expect it to be cached, but
+ certain caches MAY violate this expectation (for example, when little
+ or no network connectivity is available). A client can usually detect
+ that such a response was taken from a cache by comparing the Date
+ header to the current time.
+
+ Note: some HTTP/1.0 caches are known to violate this expectation
+ without providing any Warning.
+
+ However, in some cases it might be inappropriate for a cache to
+ retain an entity, or to return it in response to a subsequent
+ request. This might be because absolute semantic transparency is
+ deemed necessary by the service author, or because of security or
+ privacy considerations. Certain cache-control directives are
+ therefore provided so that the server can indicate that certain
+ resource entities, or portions thereof, are not to be cached
+ regardless of other considerations.
+
+ Note that section 14.8 normally prevents a shared cache from saving
+ and returning a response to a previous request if that request
+ included an Authorization header.
+
+ A response received with a status code of 200, 203, 206, 300, 301 or
+ 410 MAY be stored by a cache and used in reply to a subsequent
+ request, subject to the expiration mechanism, unless a cache-control
+ directive prohibits caching. However, a cache that does not support
+ the Range and Content-Range headers MUST NOT cache 206 (Partial
+ Content) responses.
+
+ A response received with any other status code (e.g. status codes 302
+ and 307) MUST NOT be returned in a reply to a subsequent request
+ unless there are cache-control directives or another header(s) that
+ explicitly allow it. For example, these include the following: an
+ Expires header (section 14.21); a "max-age", "s-maxage", "must-
+ revalidate", "proxy-revalidate", "public" or "private" cache-control
+ directive (section 14.9).
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 91]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5 Constructing Responses From Caches
+
+ The purpose of an HTTP cache is to store information received in
+ response to requests for use in responding to future requests. In
+ many cases, a cache simply returns the appropriate parts of a
+ response to the requester. However, if the cache holds a cache entry
+ based on a previous response, it might have to combine parts of a new
+ response with what is held in the cache entry.
+
+13.5.1 End-to-end and Hop-by-hop Headers
+
+ For the purpose of defining the behavior of caches and non-caching
+ proxies, we divide HTTP headers into two categories:
+
+ - End-to-end headers, which are transmitted to the ultimate
+ recipient of a request or response. End-to-end headers in
+ responses MUST be stored as part of a cache entry and MUST be
+ transmitted in any response formed from a cache entry.
+
+ - Hop-by-hop headers, which are meaningful only for a single
+ transport-level connection, and are not stored by caches or
+ forwarded by proxies.
+
+ The following HTTP/1.1 headers are hop-by-hop headers:
+
+ - Connection
+ - Keep-Alive
+ - Proxy-Authenticate
+ - Proxy-Authorization
+ - TE
+ - Trailers
+ - Transfer-Encoding
+ - Upgrade
+
+ All other headers defined by HTTP/1.1 are end-to-end headers.
+
+ Other hop-by-hop headers MUST be listed in a Connection header,
+ (section 14.10) to be introduced into HTTP/1.1 (or later).
+
+13.5.2 Non-modifiable Headers
+
+ Some features of the HTTP/1.1 protocol, such as Digest
+ Authentication, depend on the value of certain end-to-end headers. A
+ transparent proxy SHOULD NOT modify an end-to-end header unless the
+ definition of that header requires or specifically allows that.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 92]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A transparent proxy MUST NOT modify any of the following fields in a
+ request or response, and it MUST NOT add any of these fields if not
+ already present:
+
+ - Content-Location
+
+ - Content-MD5
+
+ - ETag
+
+ - Last-Modified
+
+ A transparent proxy MUST NOT modify any of the following fields in a
+ response:
+
+ - Expires
+
+ but it MAY add any of these fields if not already present. If an
+ Expires header is added, it MUST be given a field-value identical to
+ that of the Date header in that response.
+
+ A proxy MUST NOT modify or add any of the following fields in a
+ message that contains the no-transform cache-control directive, or in
+ any request:
+
+ - Content-Encoding
+
+ - Content-Range
+
+ - Content-Type
+
+ A non-transparent proxy MAY modify or add these fields to a message
+ that does not include no-transform, but if it does so, it MUST add a
+ Warning 214 (Transformation applied) if one does not already appear
+ in the message (see section 14.46).
+
+ Warning: unnecessary modification of end-to-end headers might
+ cause authentication failures if stronger authentication
+ mechanisms are introduced in later versions of HTTP. Such
+ authentication mechanisms MAY rely on the values of header fields
+ not listed here.
+
+ The Content-Length field of a request or response is added or deleted
+ according to the rules in section 4.4. A transparent proxy MUST
+ preserve the entity-length (section 7.2.2) of the entity-body,
+ although it MAY change the transfer-length (section 4.4).
+
+
+
+
+
+Fielding, et al. Standards Track [Page 93]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5.3 Combining Headers
+
+ When a cache makes a validating request to a server, and the server
+ provides a 304 (Not Modified) response or a 206 (Partial Content)
+ response, the cache then constructs a response to send to the
+ requesting client.
+
+ If the status code is 304 (Not Modified), the cache uses the entity-
+ body stored in the cache entry as the entity-body of this outgoing
+ response. If the status code is 206 (Partial Content) and the ETag or
+ Last-Modified headers match exactly, the cache MAY combine the
+ contents stored in the cache entry with the new contents received in
+ the response and use the result as the entity-body of this outgoing
+ response, (see 13.5.4).
+
+ The end-to-end headers stored in the cache entry are used for the
+ constructed response, except that
+
+ - any stored Warning headers with warn-code 1xx (see section
+ 14.46) MUST be deleted from the cache entry and the forwarded
+ response.
+
+ - any stored Warning headers with warn-code 2xx MUST be retained
+ in the cache entry and the forwarded response.
+
+ - any end-to-end headers provided in the 304 or 206 response MUST
+ replace the corresponding headers from the cache entry.
+
+ Unless the cache decides to remove the cache entry, it MUST also
+ replace the end-to-end headers stored with the cache entry with
+ corresponding headers received in the incoming response, except for
+ Warning headers as described immediately above. If a header field-
+ name in the incoming response matches more than one header in the
+ cache entry, all such old headers MUST be replaced.
+
+ In other words, the set of end-to-end headers received in the
+ incoming response overrides all corresponding end-to-end headers
+ stored with the cache entry (except for stored Warning headers with
+ warn-code 1xx, which are deleted even if not overridden).
+
+ Note: this rule allows an origin server to use a 304 (Not
+ Modified) or a 206 (Partial Content) response to update any header
+ associated with a previous response for the same entity or sub-
+ ranges thereof, although it might not always be meaningful or
+ correct to do so. This rule does not allow an origin server to use
+ a 304 (Not Modified) or a 206 (Partial Content) response to
+ entirely delete a header that it had provided with a previous
+ response.
+
+
+
+Fielding, et al. Standards Track [Page 94]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.5.4 Combining Byte Ranges
+
+ A response might transfer only a subrange of the bytes of an entity-
+ body, either because the request included one or more Range
+ specifications, or because a connection was broken prematurely. After
+ several such transfers, a cache might have received several ranges of
+ the same entity-body.
+
+ If a cache has a stored non-empty set of subranges for an entity, and
+ an incoming response transfers another subrange, the cache MAY
+ combine the new subrange with the existing set if both the following
+ conditions are met:
+
+ - Both the incoming response and the cache entry have a cache
+ validator.
+
+ - The two cache validators match using the strong comparison
+ function (see section 13.3.3).
+
+ If either requirement is not met, the cache MUST use only the most
+ recent partial response (based on the Date values transmitted with
+ every response, and using the incoming response if these values are
+ equal or missing), and MUST discard the other partial information.
+
+13.6 Caching Negotiated Responses
+
+ Use of server-driven content negotiation (section 12.1), as indicated
+ by the presence of a Vary header field in a response, alters the
+ conditions and procedure by which a cache can use the response for
+ subsequent requests. See section 14.44 for use of the Vary header
+ field by servers.
+
+ A server SHOULD use the Vary header field to inform a cache of what
+ request-header fields were used to select among multiple
+ representations of a cacheable response subject to server-driven
+ negotiation. The set of header fields named by the Vary field value
+ is known as the "selecting" request-headers.
+
+ When the cache receives a subsequent request whose Request-URI
+ specifies one or more cache entries including a Vary header field,
+ the cache MUST NOT use such a cache entry to construct a response to
+ the new request unless all of the selecting request-headers present
+ in the new request match the corresponding stored request-headers in
+ the original request.
+
+ The selecting request-headers from two requests are defined to match
+ if and only if the selecting request-headers in the first request can
+ be transformed to the selecting request-headers in the second request
+
+
+
+Fielding, et al. Standards Track [Page 95]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ by adding or removing linear white space (LWS) at places where this
+ is allowed by the corresponding BNF, and/or combining multiple
+ message-header fields with the same field name following the rules
+ about message headers in section 4.2.
+
+ A Vary header field-value of "*" always fails to match and subsequent
+ requests on that resource can only be properly interpreted by the
+ origin server.
+
+ If the selecting request header fields for the cached entry do not
+ match the selecting request header fields of the new request, then
+ the cache MUST NOT use a cached entry to satisfy the request unless
+ it first relays the new request to the origin server in a conditional
+ request and the server responds with 304 (Not Modified), including an
+ entity tag or Content-Location that indicates the entity to be used.
+
+ If an entity tag was assigned to a cached representation, the
+ forwarded request SHOULD be conditional and include the entity tags
+ in an If-None-Match header field from all its cache entries for the
+ resource. This conveys to the server the set of entities currently
+ held by the cache, so that if any one of these entities matches the
+ requested entity, the server can use the ETag header field in its 304
+ (Not Modified) response to tell the cache which entry is appropriate.
+ If the entity-tag of the new response matches that of an existing
+ entry, the new response SHOULD be used to update the header fields of
+ the existing entry, and the result MUST be returned to the client.
+
+ If any of the existing cache entries contains only partial content
+ for the associated entity, its entity-tag SHOULD NOT be included in
+ the If-None-Match header field unless the request is for a range that
+ would be fully satisfied by that entry.
+
+ If a cache receives a successful response whose Content-Location
+ field matches that of an existing cache entry for the same Request-
+ ]URI, whose entity-tag differs from that of the existing entry, and
+ whose Date is more recent than that of the existing entry, the
+ existing entry SHOULD NOT be returned in response to future requests
+ and SHOULD be deleted from the cache.
+
+13.7 Shared and Non-Shared Caches
+
+ For reasons of security and privacy, it is necessary to make a
+ distinction between "shared" and "non-shared" caches. A non-shared
+ cache is one that is accessible only to a single user. Accessibility
+ in this case SHOULD be enforced by appropriate security mechanisms.
+ All other caches are considered to be "shared." Other sections of
+
+
+
+
+
+Fielding, et al. Standards Track [Page 96]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ this specification place certain constraints on the operation of
+ shared caches in order to prevent loss of privacy or failure of
+ access controls.
+
+13.8 Errors or Incomplete Response Cache Behavior
+
+ A cache that receives an incomplete response (for example, with fewer
+ bytes of data than specified in a Content-Length header) MAY store
+ the response. However, the cache MUST treat this as a partial
+ response. Partial responses MAY be combined as described in section
+ 13.5.4; the result might be a full response or might still be
+ partial. A cache MUST NOT return a partial response to a client
+ without explicitly marking it as such, using the 206 (Partial
+ Content) status code. A cache MUST NOT return a partial response
+ using a status code of 200 (OK).
+
+ If a cache receives a 5xx response while attempting to revalidate an
+ entry, it MAY either forward this response to the requesting client,
+ or act as if the server failed to respond. In the latter case, it MAY
+ return a previously received response unless the cached entry
+ includes the "must-revalidate" cache-control directive (see section
+ 14.9).
+
+13.9 Side Effects of GET and HEAD
+
+ Unless the origin server explicitly prohibits the caching of their
+ responses, the application of GET and HEAD methods to any resources
+ SHOULD NOT have side effects that would lead to erroneous behavior if
+ these responses are taken from a cache. They MAY still have side
+ effects, but a cache is not required to consider such side effects in
+ its caching decisions. Caches are always expected to observe an
+ origin server's explicit restrictions on caching.
+
+ We note one exception to this rule: since some applications have
+ traditionally used GETs and HEADs with query URLs (those containing a
+ "?" in the rel_path part) to perform operations with significant side
+ effects, caches MUST NOT treat responses to such URIs as fresh unless
+ the server provides an explicit expiration time. This specifically
+ means that responses from HTTP/1.0 servers for such URIs SHOULD NOT
+ be taken from a cache. See section 9.1.1 for related information.
+
+13.10 Invalidation After Updates or Deletions
+
+ The effect of certain methods performed on a resource at the origin
+ server might cause one or more existing cache entries to become non-
+ transparently invalid. That is, although they might continue to be
+ "fresh," they do not accurately reflect what the origin server would
+ return for a new request on that resource.
+
+
+
+Fielding, et al. Standards Track [Page 97]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ There is no way for the HTTP protocol to guarantee that all such
+ cache entries are marked invalid. For example, the request that
+ caused the change at the origin server might not have gone through
+ the proxy where a cache entry is stored. However, several rules help
+ reduce the likelihood of erroneous behavior.
+
+ In this section, the phrase "invalidate an entity" means that the
+ cache will either remove all instances of that entity from its
+ storage, or will mark these as "invalid" and in need of a mandatory
+ revalidation before they can be returned in response to a subsequent
+ request.
+
+ Some HTTP methods MUST cause a cache to invalidate an entity. This is
+ either the entity referred to by the Request-URI, or by the Location
+ or Content-Location headers (if present). These methods are:
+
+ - PUT
+
+ - DELETE
+
+ - POST
+
+ In order to prevent denial of service attacks, an invalidation based
+ on the URI in a Location or Content-Location header MUST only be
+ performed if the host part is the same as in the Request-URI.
+
+ A cache that passes through requests for methods it does not
+ understand SHOULD invalidate any entities referred to by the
+ Request-URI.
+
+13.11 Write-Through Mandatory
+
+ All methods that might be expected to cause modifications to the
+ origin server's resources MUST be written through to the origin
+ server. This currently includes all methods except for GET and HEAD.
+ A cache MUST NOT reply to such a request from a client before having
+ transmitted the request to the inbound server, and having received a
+ corresponding response from the inbound server. This does not prevent
+ a proxy cache from sending a 100 (Continue) response before the
+ inbound server has sent its final reply.
+
+ The alternative (known as "write-back" or "copy-back" caching) is not
+ allowed in HTTP/1.1, due to the difficulty of providing consistent
+ updates and the problems arising from server, cache, or network
+ failure prior to write-back.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 98]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+13.12 Cache Replacement
+
+ If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
+ response is received from a resource while any existing responses for
+ the same resource are cached, the cache SHOULD use the new response
+ to reply to the current request. It MAY insert it into cache storage
+ and MAY, if it meets all other requirements, use it to respond to any
+ future requests that would previously have caused the old response to
+ be returned. If it inserts the new response into cache storage the
+ rules in section 13.5.3 apply.
+
+ Note: a new response that has an older Date header value than
+ existing cached responses is not cacheable.
+
+13.13 History Lists
+
+ User agents often have history mechanisms, such as "Back" buttons and
+ history lists, which can be used to redisplay an entity retrieved
+ earlier in a session.
+
+ History mechanisms and caches are different. In particular history
+ mechanisms SHOULD NOT try to show a semantically transparent view of
+ the current state of a resource. Rather, a history mechanism is meant
+ to show exactly what the user saw at the time when the resource was
+ retrieved.
+
+ By default, an expiration time does not apply to history mechanisms.
+ If the entity is still in storage, a history mechanism SHOULD display
+ it even if the entity has expired, unless the user has specifically
+ configured the agent to refresh expired history documents.
+
+ This is not to be construed to prohibit the history mechanism from
+ telling the user that a view might be stale.
+
+ Note: if history list mechanisms unnecessarily prevent users from
+ viewing stale resources, this will tend to force service authors
+ to avoid using HTTP expiration controls and cache controls when
+ they would otherwise like to. Service authors may consider it
+ important that users not be presented with error messages or
+ warning messages when they use navigation controls (such as BACK)
+ to view previously fetched resources. Even though sometimes such
+ resources ought not to cached, or ought to expire quickly, user
+ interface considerations may force service authors to resort to
+ other means of preventing caching (e.g. "once-only" URLs) in order
+ not to suffer the effects of improperly functioning history
+ mechanisms.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 99]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14 Header Field Definitions
+
+ This section defines the syntax and semantics of all standard
+ HTTP/1.1 header fields. For entity-header fields, both sender and
+ recipient refer to either the client or the server, depending on who
+ sends and who receives the entity.
+
+14.1 Accept
+
+ The Accept request-header field can be used to specify certain media
+ types which are acceptable for the response. Accept headers can be
+ used to indicate that the request is specifically limited to a small
+ set of desired types, as in the case of a request for an in-line
+ image.
+
+ Accept = "Accept" ":"
+ #( media-range [ accept-params ] )
+
+ media-range = ( "*/*"
+ | ( type "/" "*" )
+ | ( type "/" subtype )
+ ) *( ";" parameter )
+ accept-params = ";" "q" "=" qvalue *( accept-extension )
+ accept-extension = ";" token [ "=" ( token | quoted-string ) ]
+
+ The asterisk "*" character is used to group media types into ranges,
+ with "*/*" indicating all media types and "type/*" indicating all
+ subtypes of that type. The media-range MAY include media type
+ parameters that are applicable to that range.
+
+ Each media-range MAY be followed by one or more accept-params,
+ beginning with the "q" parameter for indicating a relative quality
+ factor. The first "q" parameter (if any) separates the media-range
+ parameter(s) from the accept-params. Quality factors allow the user
+ or user agent to indicate the relative degree of preference for that
+ media-range, using the qvalue scale from 0 to 1 (section 3.9). The
+ default value is q=1.
+
+ Note: Use of the "q" parameter name to separate media type
+ parameters from Accept extension parameters is due to historical
+ practice. Although this prevents any media type parameter named
+ "q" from being used with a media range, such an event is believed
+ to be unlikely given the lack of any "q" parameters in the IANA
+ media type registry and the rare usage of any media type
+ parameters in Accept. Future media types are discouraged from
+ registering any parameter named "q".
+
+
+
+
+
+Fielding, et al. Standards Track [Page 100]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The example
+
+ Accept: audio/*; q=0.2, audio/basic
+
+ SHOULD be interpreted as "I prefer audio/basic, but send me any audio
+ type if it is the best available after an 80% mark-down in quality."
+
+ If no Accept header field is present, then it is assumed that the
+ client accepts all media types. If an Accept header field is present,
+ and if the server cannot send a response which is acceptable
+ according to the combined Accept field value, then the server SHOULD
+ send a 406 (not acceptable) response.
+
+ A more elaborate example is
+
+ Accept: text/plain; q=0.5, text/html,
+ text/x-dvi; q=0.8, text/x-c
+
+ Verbally, this would be interpreted as "text/html and text/x-c are
+ the preferred media types, but if they do not exist, then send the
+ text/x-dvi entity, and if that does not exist, send the text/plain
+ entity."
+
+ Media ranges can be overridden by more specific media ranges or
+ specific media types. If more than one media range applies to a given
+ type, the most specific reference has precedence. For example,
+
+ Accept: text/*, text/html, text/html;level=1, */*
+
+ have the following precedence:
+
+ 1) text/html;level=1
+ 2) text/html
+ 3) text/*
+ 4) */*
+
+ The media type quality factor associated with a given type is
+ determined by finding the media range with the highest precedence
+ which matches that type. For example,
+
+ Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
+ text/html;level=2;q=0.4, */*;q=0.5
+
+ would cause the following values to be associated:
+
+ text/html;level=1 = 1
+ text/html = 0.7
+ text/plain = 0.3
+
+
+
+Fielding, et al. Standards Track [Page 101]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ image/jpeg = 0.5
+ text/html;level=2 = 0.4
+ text/html;level=3 = 0.7
+
+ Note: A user agent might be provided with a default set of quality
+ values for certain media ranges. However, unless the user agent is
+ a closed system which cannot interact with other rendering agents,
+ this default set ought to be configurable by the user.
+
+14.2 Accept-Charset
+
+ The Accept-Charset request-header field can be used to indicate what
+ character sets are acceptable for the response. This field allows
+ clients capable of understanding more comprehensive or special-
+ purpose character sets to signal that capability to a server which is
+ capable of representing documents in those character sets.
+
+ Accept-Charset = "Accept-Charset" ":"
+ 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] )
+
+
+ Character set values are described in section 3.4. Each charset MAY
+ be given an associated quality value which represents the user's
+ preference for that charset. The default value is q=1. An example is
+
+ Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
+
+ The special value "*", if present in the Accept-Charset field,
+ matches every character set (including ISO-8859-1) which is not
+ mentioned elsewhere in the Accept-Charset field. If no "*" is present
+ in an Accept-Charset field, then all character sets not explicitly
+ mentioned get a quality value of 0, except for ISO-8859-1, which gets
+ a quality value of 1 if not explicitly mentioned.
+
+ If no Accept-Charset header is present, the default is that any
+ character set is acceptable. If an Accept-Charset header is present,
+ and if the server cannot send a response which is acceptable
+ according to the Accept-Charset header, then the server SHOULD send
+ an error response with the 406 (not acceptable) status code, though
+ the sending of an unacceptable response is also allowed.
+
+14.3 Accept-Encoding
+
+ The Accept-Encoding request-header field is similar to Accept, but
+ restricts the content-codings (section 3.5) that are acceptable in
+ the response.
+
+ Accept-Encoding = "Accept-Encoding" ":"
+
+
+
+Fielding, et al. Standards Track [Page 102]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1#( codings [ ";" "q" "=" qvalue ] )
+ codings = ( content-coding | "*" )
+
+ Examples of its use are:
+
+ Accept-Encoding: compress, gzip
+ Accept-Encoding:
+ Accept-Encoding: *
+ Accept-Encoding: compress;q=0.5, gzip;q=1.0
+ Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
+
+ A server tests whether a content-coding is acceptable, according to
+ an Accept-Encoding field, using these rules:
+
+ 1. If the content-coding is one of the content-codings listed in
+ the Accept-Encoding field, then it is acceptable, unless it is
+ accompanied by a qvalue of 0. (As defined in section 3.9, a
+ qvalue of 0 means "not acceptable.")
+
+ 2. The special "*" symbol in an Accept-Encoding field matches any
+ available content-coding not explicitly listed in the header
+ field.
+
+ 3. If multiple content-codings are acceptable, then the acceptable
+ content-coding with the highest non-zero qvalue is preferred.
+
+ 4. The "identity" content-coding is always acceptable, unless
+ specifically refused because the Accept-Encoding field includes
+ "identity;q=0", or because the field includes "*;q=0" and does
+ not explicitly include the "identity" content-coding. If the
+ Accept-Encoding field-value is empty, then only the "identity"
+ encoding is acceptable.
+
+ If an Accept-Encoding field is present in a request, and if the
+ server cannot send a response which is acceptable according to the
+ Accept-Encoding header, then the server SHOULD send an error response
+ with the 406 (Not Acceptable) status code.
+
+ If no Accept-Encoding field is present in a request, the server MAY
+ assume that the client will accept any content coding. In this case,
+ if "identity" is one of the available content-codings, then the
+ server SHOULD use the "identity" content-coding, unless it has
+ additional information that a different content-coding is meaningful
+ to the client.
+
+ Note: If the request does not include an Accept-Encoding field,
+ and if the "identity" content-coding is unavailable, then
+ content-codings commonly understood by HTTP/1.0 clients (i.e.,
+
+
+
+Fielding, et al. Standards Track [Page 103]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ "gzip" and "compress") are preferred; some older clients
+ improperly display messages sent with other content-codings. The
+ server might also make this decision based on information about
+ the particular user-agent or client.
+
+ Note: Most HTTP/1.0 applications do not recognize or obey qvalues
+ associated with content-codings. This means that qvalues will not
+ work and are not permitted with x-gzip or x-compress.
+
+14.4 Accept-Language
+
+ The Accept-Language request-header field is similar to Accept, but
+ restricts the set of natural languages that are preferred as a
+ response to the request. Language tags are defined in section 3.10.
+
+ Accept-Language = "Accept-Language" ":"
+ 1#( language-range [ ";" "q" "=" qvalue ] )
+ language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
+
+ Each language-range MAY be given an associated quality value which
+ represents an estimate of the user's preference for the languages
+ specified by that range. The quality value defaults to "q=1". For
+ example,
+
+ Accept-Language: da, en-gb;q=0.8, en;q=0.7
+
+ would mean: "I prefer Danish, but will accept British English and
+ other types of English." A language-range matches a language-tag if
+ it exactly equals the tag, or if it exactly equals a prefix of the
+ tag such that the first tag character following the prefix is "-".
+ The special range "*", if present in the Accept-Language field,
+ matches every tag not matched by any other range present in the
+ Accept-Language field.
+
+ Note: This use of a prefix matching rule does not imply that
+ language tags are assigned to languages in such a way that it is
+ always true that if a user understands a language with a certain
+ tag, then this user will also understand all languages with tags
+ for which this tag is a prefix. The prefix rule simply allows the
+ use of prefix tags if this is the case.
+
+ The language quality factor assigned to a language-tag by the
+ Accept-Language field is the quality value of the longest language-
+ range in the field that matches the language-tag. If no language-
+ range in the field matches the tag, the language quality factor
+ assigned is 0. If no Accept-Language header is present in the
+ request, the server
+
+
+
+
+Fielding, et al. Standards Track [Page 104]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ SHOULD assume that all languages are equally acceptable. If an
+ Accept-Language header is present, then all languages which are
+ assigned a quality factor greater than 0 are acceptable.
+
+ It might be contrary to the privacy expectations of the user to send
+ an Accept-Language header with the complete linguistic preferences of
+ the user in every request. For a discussion of this issue, see
+ section 15.1.4.
+
+ As intelligibility is highly dependent on the individual user, it is
+ recommended that client applications make the choice of linguistic
+ preference available to the user. If the choice is not made
+ available, then the Accept-Language header field MUST NOT be given in
+ the request.
+
+ Note: When making the choice of linguistic preference available to
+ the user, we remind implementors of the fact that users are not
+ familiar with the details of language matching as described above,
+ and should provide appropriate guidance. As an example, users
+ might assume that on selecting "en-gb", they will be served any
+ kind of English document if British English is not available. A
+ user agent might suggest in such a case to add "en" to get the
+ best matching behavior.
+
+14.5 Accept-Ranges
+
+ The Accept-Ranges response-header field allows the server to
+ indicate its acceptance of range requests for a resource:
+
+ Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
+ acceptable-ranges = 1#range-unit | "none"
+
+ Origin servers that accept byte-range requests MAY send
+
+ Accept-Ranges: bytes
+
+ but are not required to do so. Clients MAY generate byte-range
+ requests without having received this header for the resource
+ involved. Range units are defined in section 3.12.
+
+ Servers that do not accept any kind of range request for a
+ resource MAY send
+
+ Accept-Ranges: none
+
+ to advise the client not to attempt a range request.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 105]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.6 Age
+
+ The Age response-header field conveys the sender's estimate of the
+ amount of time since the response (or its revalidation) was
+ generated at the origin server. A cached response is "fresh" if
+ its age does not exceed its freshness lifetime. Age values are
+ calculated as specified in section 13.2.3.
+
+ Age = "Age" ":" age-value
+ age-value = delta-seconds
+
+ Age values are non-negative decimal integers, representing time in
+ seconds.
+
+ If a cache receives a value larger than the largest positive
+ integer it can represent, or if any of its age calculations
+ overflows, it MUST transmit an Age header with a value of
+ 2147483648 (2^31). An HTTP/1.1 server that includes a cache MUST
+ include an Age header field in every response generated from its
+ own cache. Caches SHOULD use an arithmetic type of at least 31
+ bits of range.
+
+14.7 Allow
+
+ The Allow entity-header field lists the set of methods supported
+ by the resource identified by the Request-URI. The purpose of this
+ field is strictly to inform the recipient of valid methods
+ associated with the resource. An Allow header field MUST be
+ present in a 405 (Method Not Allowed) response.
+
+ Allow = "Allow" ":" #Method
+
+ Example of use:
+
+ Allow: GET, HEAD, PUT
+
+ This field cannot prevent a client from trying other methods.
+ However, the indications given by the Allow header field value
+ SHOULD be followed. The actual set of allowed methods is defined
+ by the origin server at the time of each request.
+
+ The Allow header field MAY be provided with a PUT request to
+ recommend the methods to be supported by the new or modified
+ resource. The server is not required to support these methods and
+ SHOULD include an Allow header in the response giving the actual
+ supported methods.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 106]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A proxy MUST NOT modify the Allow header field even if it does not
+ understand all the methods specified, since the user agent might
+ have other means of communicating with the origin server.
+
+14.8 Authorization
+
+ A user agent that wishes to authenticate itself with a server--
+ usually, but not necessarily, after receiving a 401 response--does
+ so by including an Authorization request-header field with the
+ request. The Authorization field value consists of credentials
+ containing the authentication information of the user agent for
+ the realm of the resource being requested.
+
+ Authorization = "Authorization" ":" credentials
+
+ HTTP access authentication is described in "HTTP Authentication:
+ Basic and Digest Access Authentication" [43]. If a request is
+ authenticated and a realm specified, the same credentials SHOULD
+ be valid for all other requests within this realm (assuming that
+ the authentication scheme itself does not require otherwise, such
+ as credentials that vary according to a challenge value or using
+ synchronized clocks).
+
+ When a shared cache (see section 13.7) receives a request
+ containing an Authorization field, it MUST NOT return the
+ corresponding response as a reply to any other request, unless one
+ of the following specific exceptions holds:
+
+ 1. If the response includes the "s-maxage" cache-control
+ directive, the cache MAY use that response in replying to a
+ subsequent request. But (if the specified maximum age has
+ passed) a proxy cache MUST first revalidate it with the origin
+ server, using the request-headers from the new request to allow
+ the origin server to authenticate the new request. (This is the
+ defined behavior for s-maxage.) If the response includes "s-
+ maxage=0", the proxy MUST always revalidate it before re-using
+ it.
+
+ 2. If the response includes the "must-revalidate" cache-control
+ directive, the cache MAY use that response in replying to a
+ subsequent request. But if the response is stale, all caches
+ MUST first revalidate it with the origin server, using the
+ request-headers from the new request to allow the origin server
+ to authenticate the new request.
+
+ 3. If the response includes the "public" cache-control directive,
+ it MAY be returned in reply to any subsequent request.
+
+
+
+
+Fielding, et al. Standards Track [Page 107]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.9 Cache-Control
+
+ The Cache-Control general-header field is used to specify directives
+ that MUST be obeyed by all caching mechanisms along the
+ request/response chain. The directives specify behavior intended to
+ prevent caches from adversely interfering with the request or
+ response. These directives typically override the default caching
+ algorithms. Cache directives are unidirectional in that the presence
+ of a directive in a request does not imply that the same directive is
+ to be given in the response.
+
+ Note that HTTP/1.0 caches might not implement Cache-Control and
+ might only implement Pragma: no-cache (see section 14.32).
+
+ Cache directives MUST be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives might be applicable to all recipients along the
+ request/response chain. It is not possible to specify a cache-
+ directive for a specific cache.
+
+ Cache-Control = "Cache-Control" ":" 1#cache-directive
+
+ cache-directive = cache-request-directive
+ | cache-response-directive
+
+ cache-request-directive =
+ "no-cache" ; Section 14.9.1
+ | "no-store" ; Section 14.9.2
+ | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4
+ | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3
+ | "min-fresh" "=" delta-seconds ; Section 14.9.3
+ | "no-transform" ; Section 14.9.5
+ | "only-if-cached" ; Section 14.9.4
+ | cache-extension ; Section 14.9.6
+
+ cache-response-directive =
+ "public" ; Section 14.9.1
+ | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1
+ | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1
+ | "no-store" ; Section 14.9.2
+ | "no-transform" ; Section 14.9.5
+ | "must-revalidate" ; Section 14.9.4
+ | "proxy-revalidate" ; Section 14.9.4
+ | "max-age" "=" delta-seconds ; Section 14.9.3
+ | "s-maxage" "=" delta-seconds ; Section 14.9.3
+ | cache-extension ; Section 14.9.6
+
+ cache-extension = token [ "=" ( token | quoted-string ) ]
+
+
+
+Fielding, et al. Standards Track [Page 108]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ When a directive appears without any 1#field-name parameter, the
+ directive applies to the entire request or response. When such a
+ directive appears with a 1#field-name parameter, it applies only to
+ the named field or fields, and not to the rest of the request or
+ response. This mechanism supports extensibility; implementations of
+ future versions of the HTTP protocol might apply these directives to
+ header fields not defined in HTTP/1.1.
+
+ The cache-control directives can be broken down into these general
+ categories:
+
+ - Restrictions on what are cacheable; these may only be imposed by
+ the origin server.
+
+ - Restrictions on what may be stored by a cache; these may be
+ imposed by either the origin server or the user agent.
+
+ - Modifications of the basic expiration mechanism; these may be
+ imposed by either the origin server or the user agent.
+
+ - Controls over cache revalidation and reload; these may only be
+ imposed by a user agent.
+
+ - Control over transformation of entities.
+
+ - Extensions to the caching system.
+
+14.9.1 What is Cacheable
+
+ By default, a response is cacheable if the requirements of the
+ request method, request header fields, and the response status
+ indicate that it is cacheable. Section 13.4 summarizes these defaults
+ for cacheability. The following Cache-Control response directives
+ allow an origin server to override the default cacheability of a
+ response:
+
+ public
+ Indicates that the response MAY be cached by any cache, even if it
+ would normally be non-cacheable or cacheable only within a non-
+ shared cache. (See also Authorization, section 14.8, for
+ additional details.)
+
+ private
+ Indicates that all or part of the response message is intended for
+ a single user and MUST NOT be cached by a shared cache. This
+ allows an origin server to state that the specified parts of the
+
+
+
+
+
+Fielding, et al. Standards Track [Page 109]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ response are intended for only one user and are not a valid
+ response for requests by other users. A private (non-shared) cache
+ MAY cache the response.
+
+ Note: This usage of the word private only controls where the
+ response may be cached, and cannot ensure the privacy of the
+ message content.
+
+ no-cache
+ If the no-cache directive does not specify a field-name, then a
+ cache MUST NOT use the response to satisfy a subsequent request
+ without successful revalidation with the origin server. This
+ allows an origin server to prevent caching even by caches that
+ have been configured to return stale responses to client requests.
+
+ If the no-cache directive does specify one or more field-names,
+ then a cache MAY use the response to satisfy a subsequent request,
+ subject to any other restrictions on caching. However, the
+ specified field-name(s) MUST NOT be sent in the response to a
+ subsequent request without successful revalidation with the origin
+ server. This allows an origin server to prevent the re-use of
+ certain header fields in a response, while still allowing caching
+ of the rest of the response.
+
+ Note: Most HTTP/1.0 caches will not recognize or obey this
+ directive.
+
+14.9.2 What May be Stored by Caches
+
+ no-store
+ The purpose of the no-store directive is to prevent the
+ inadvertent release or retention of sensitive information (for
+ example, on backup tapes). The no-store directive applies to the
+ entire message, and MAY be sent either in a response or in a
+ request. If sent in a request, a cache MUST NOT store any part of
+ either this request or any response to it. If sent in a response,
+ a cache MUST NOT store any part of either this response or the
+ request that elicited it. This directive applies to both non-
+ shared and shared caches. "MUST NOT store" in this context means
+ that the cache MUST NOT intentionally store the information in
+ non-volatile storage, and MUST make a best-effort attempt to
+ remove the information from volatile storage as promptly as
+ possible after forwarding it.
+
+ Even when this directive is associated with a response, users
+ might explicitly store such a response outside of the caching
+ system (e.g., with a "Save As" dialog). History buffers MAY store
+ such responses as part of their normal operation.
+
+
+
+Fielding, et al. Standards Track [Page 110]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The purpose of this directive is to meet the stated requirements
+ of certain users and service authors who are concerned about
+ accidental releases of information via unanticipated accesses to
+ cache data structures. While the use of this directive might
+ improve privacy in some cases, we caution that it is NOT in any
+ way a reliable or sufficient mechanism for ensuring privacy. In
+ particular, malicious or compromised caches might not recognize or
+ obey this directive, and communications networks might be
+ vulnerable to eavesdropping.
+
+14.9.3 Modifications of the Basic Expiration Mechanism
+
+ The expiration time of an entity MAY be specified by the origin
+ server using the Expires header (see section 14.21). Alternatively,
+ it MAY be specified using the max-age directive in a response. When
+ the max-age cache-control directive is present in a cached response,
+ the response is stale if its current age is greater than the age
+ value given (in seconds) at the time of a new request for that
+ resource. The max-age directive on a response implies that the
+ response is cacheable (i.e., "public") unless some other, more
+ restrictive cache directive is also present.
+
+ If a response includes both an Expires header and a max-age
+ directive, the max-age directive overrides the Expires header, even
+ if the Expires header is more restrictive. This rule allows an origin
+ server to provide, for a given response, a longer expiration time to
+ an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
+ useful if certain HTTP/1.0 caches improperly calculate ages or
+ expiration times, perhaps due to desynchronized clocks.
+
+ Many HTTP/1.0 cache implementations will treat an Expires value that
+ is less than or equal to the response Date value as being equivalent
+ to the Cache-Control response directive "no-cache". If an HTTP/1.1
+ cache receives such a response, and the response does not include a
+ Cache-Control header field, it SHOULD consider the response to be
+ non-cacheable in order to retain compatibility with HTTP/1.0 servers.
+
+ Note: An origin server might wish to use a relatively new HTTP
+ cache control feature, such as the "private" directive, on a
+ network including older caches that do not understand that
+ feature. The origin server will need to combine the new feature
+ with an Expires field whose value is less than or equal to the
+ Date value. This will prevent older caches from improperly
+ caching the response.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 111]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ s-maxage
+ If a response includes an s-maxage directive, then for a shared
+ cache (but not for a private cache), the maximum age specified by
+ this directive overrides the maximum age specified by either the
+ max-age directive or the Expires header. The s-maxage directive
+ also implies the semantics of the proxy-revalidate directive (see
+ section 14.9.4), i.e., that the shared cache must not use the
+ entry after it becomes stale to respond to a subsequent request
+ without first revalidating it with the origin server. The s-
+ maxage directive is always ignored by a private cache.
+
+ Note that most older caches, not compliant with this specification,
+ do not implement any cache-control directives. An origin server
+ wishing to use a cache-control directive that restricts, but does not
+ prevent, caching by an HTTP/1.1-compliant cache MAY exploit the
+ requirement that the max-age directive overrides the Expires header,
+ and the fact that pre-HTTP/1.1-compliant caches do not observe the
+ max-age directive.
+
+ Other directives allow a user agent to modify the basic expiration
+ mechanism. These directives MAY be specified on a request:
+
+ max-age
+ Indicates that the client is willing to accept a response whose
+ age is no greater than the specified time in seconds. Unless max-
+ stale directive is also included, the client is not willing to
+ accept a stale response.
+
+ min-fresh
+ Indicates that the client is willing to accept a response whose
+ freshness lifetime is no less than its current age plus the
+ specified time in seconds. That is, the client wants a response
+ that will still be fresh for at least the specified number of
+ seconds.
+
+ max-stale
+ Indicates that the client is willing to accept a response that has
+ exceeded its expiration time. If max-stale is assigned a value,
+ then the client is willing to accept a response that has exceeded
+ its expiration time by no more than the specified number of
+ seconds. If no value is assigned to max-stale, then the client is
+ willing to accept a stale response of any age.
+
+ If a cache returns a stale response, either because of a max-stale
+ directive on a request, or because the cache is configured to
+ override the expiration time of a response, the cache MUST attach a
+ Warning header to the stale response, using Warning 110 (Response is
+ stale).
+
+
+
+Fielding, et al. Standards Track [Page 112]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A cache MAY be configured to return stale responses without
+ validation, but only if this does not conflict with any "MUST"-level
+ requirements concerning cache validation (e.g., a "must-revalidate"
+ cache-control directive).
+
+ If both the new request and the cached entry include "max-age"
+ directives, then the lesser of the two values is used for determining
+ the freshness of the cached entry for that request.
+
+14.9.4 Cache Revalidation and Reload Controls
+
+ Sometimes a user agent might want or need to insist that a cache
+ revalidate its cache entry with the origin server (and not just with
+ the next cache along the path to the origin server), or to reload its
+ cache entry from the origin server. End-to-end revalidation might be
+ necessary if either the cache or the origin server has overestimated
+ the expiration time of the cached response. End-to-end reload may be
+ necessary if the cache entry has become corrupted for some reason.
+
+ End-to-end revalidation may be requested either when the client does
+ not have its own local cached copy, in which case we call it
+ "unspecified end-to-end revalidation", or when the client does have a
+ local cached copy, in which case we call it "specific end-to-end
+ revalidation."
+
+ The client can specify these three kinds of action using Cache-
+ Control request directives:
+
+ End-to-end reload
+ The request includes a "no-cache" cache-control directive or, for
+ compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field
+ names MUST NOT be included with the no-cache directive in a
+ request. The server MUST NOT use a cached copy when responding to
+ such a request.
+
+ Specific end-to-end revalidation
+ The request includes a "max-age=0" cache-control directive, which
+ forces each cache along the path to the origin server to
+ revalidate its own entry, if any, with the next cache or server.
+ The initial request includes a cache-validating conditional with
+ the client's current validator.
+
+ Unspecified end-to-end revalidation
+ The request includes "max-age=0" cache-control directive, which
+ forces each cache along the path to the origin server to
+ revalidate its own entry, if any, with the next cache or server.
+ The initial request does not include a cache-validating
+
+
+
+
+Fielding, et al. Standards Track [Page 113]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ conditional; the first cache along the path (if any) that holds a
+ cache entry for this resource includes a cache-validating
+ conditional with its current validator.
+
+ max-age
+ When an intermediate cache is forced, by means of a max-age=0
+ directive, to revalidate its own cache entry, and the client has
+ supplied its own validator in the request, the supplied validator
+ might differ from the validator currently stored with the cache
+ entry. In this case, the cache MAY use either validator in making
+ its own request without affecting semantic transparency.
+
+ However, the choice of validator might affect performance. The
+ best approach is for the intermediate cache to use its own
+ validator when making its request. If the server replies with 304
+ (Not Modified), then the cache can return its now validated copy
+ to the client with a 200 (OK) response. If the server replies with
+ a new entity and cache validator, however, the intermediate cache
+ can compare the returned validator with the one provided in the
+ client's request, using the strong comparison function. If the
+ client's validator is equal to the origin server's, then the
+ intermediate cache simply returns 304 (Not Modified). Otherwise,
+ it returns the new entity with a 200 (OK) response.
+
+ If a request includes the no-cache directive, it SHOULD NOT
+ include min-fresh, max-stale, or max-age.
+
+ only-if-cached
+ In some cases, such as times of extremely poor network
+ connectivity, a client may want a cache to return only those
+ responses that it currently has stored, and not to reload or
+ revalidate with the origin server. To do this, the client may
+ include the only-if-cached directive in a request. If it receives
+ this directive, a cache SHOULD either respond using a cached entry
+ that is consistent with the other constraints of the request, or
+ respond with a 504 (Gateway Timeout) status. However, if a group
+ of caches is being operated as a unified system with good internal
+ connectivity, such a request MAY be forwarded within that group of
+ caches.
+
+ must-revalidate
+ Because a cache MAY be configured to ignore a server's specified
+ expiration time, and because a client request MAY include a max-
+ stale directive (which has a similar effect), the protocol also
+ includes a mechanism for the origin server to require revalidation
+ of a cache entry on any subsequent use. When the must-revalidate
+ directive is present in a response received by a cache, that cache
+ MUST NOT use the entry after it becomes stale to respond to a
+
+
+
+Fielding, et al. Standards Track [Page 114]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ subsequent request without first revalidating it with the origin
+ server. (I.e., the cache MUST do an end-to-end revalidation every
+ time, if, based solely on the origin server's Expires or max-age
+ value, the cached response is stale.)
+
+ The must-revalidate directive is necessary to support reliable
+ operation for certain protocol features. In all circumstances an
+ HTTP/1.1 cache MUST obey the must-revalidate directive; in
+ particular, if the cache cannot reach the origin server for any
+ reason, it MUST generate a 504 (Gateway Timeout) response.
+
+ Servers SHOULD send the must-revalidate directive if and only if
+ failure to revalidate a request on the entity could result in
+ incorrect operation, such as a silently unexecuted financial
+ transaction. Recipients MUST NOT take any automated action that
+ violates this directive, and MUST NOT automatically provide an
+ unvalidated copy of the entity if revalidation fails.
+
+ Although this is not recommended, user agents operating under
+ severe connectivity constraints MAY violate this directive but, if
+ so, MUST explicitly warn the user that an unvalidated response has
+ been provided. The warning MUST be provided on each unvalidated
+ access, and SHOULD require explicit user confirmation.
+
+ proxy-revalidate
+ The proxy-revalidate directive has the same meaning as the must-
+ revalidate directive, except that it does not apply to non-shared
+ user agent caches. It can be used on a response to an
+ authenticated request to permit the user's cache to store and
+ later return the response without needing to revalidate it (since
+ it has already been authenticated once by that user), while still
+ requiring proxies that service many users to revalidate each time
+ (in order to make sure that each user has been authenticated).
+ Note that such authenticated responses also need the public cache
+ control directive in order to allow them to be cached at all.
+
+14.9.5 No-Transform Directive
+
+ no-transform
+ Implementors of intermediate caches (proxies) have found it useful
+ to convert the media type of certain entity bodies. A non-
+ transparent proxy might, for example, convert between image
+ formats in order to save cache space or to reduce the amount of
+ traffic on a slow link.
+
+ Serious operational problems occur, however, when these
+ transformations are applied to entity bodies intended for certain
+ kinds of applications. For example, applications for medical
+
+
+
+Fielding, et al. Standards Track [Page 115]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ imaging, scientific data analysis and those using end-to-end
+ authentication, all depend on receiving an entity body that is bit
+ for bit identical to the original entity-body.
+
+ Therefore, if a message includes the no-transform directive, an
+ intermediate cache or proxy MUST NOT change those headers that are
+ listed in section 13.5.2 as being subject to the no-transform
+ directive. This implies that the cache or proxy MUST NOT change
+ any aspect of the entity-body that is specified by these headers,
+ including the value of the entity-body itself.
+
+14.9.6 Cache Control Extensions
+
+ The Cache-Control header field can be extended through the use of one
+ or more cache-extension tokens, each with an optional assigned value.
+ Informational extensions (those which do not require a change in
+ cache behavior) MAY be added without changing the semantics of other
+ directives. Behavioral extensions are designed to work by acting as
+ modifiers to the existing base of cache directives. Both the new
+ directive and the standard directive are supplied, such that
+ applications which do not understand the new directive will default
+ to the behavior specified by the standard directive, and those that
+ understand the new directive will recognize it as modifying the
+ requirements associated with the standard directive. In this way,
+ extensions to the cache-control directives can be made without
+ requiring changes to the base protocol.
+
+ This extension mechanism depends on an HTTP cache obeying all of the
+ cache-control directives defined for its native HTTP-version, obeying
+ certain extensions, and ignoring all directives that it does not
+ understand.
+
+ For example, consider a hypothetical new response directive called
+ community which acts as a modifier to the private directive. We
+ define this new directive to mean that, in addition to any non-shared
+ cache, any cache which is shared only by members of the community
+ named within its value may cache the response. An origin server
+ wishing to allow the UCI community to use an otherwise private
+ response in their shared cache(s) could do so by including
+
+ Cache-Control: private, community="UCI"
+
+ A cache seeing this header field will act correctly even if the cache
+ does not understand the community cache-extension, since it will also
+ see and understand the private directive and thus default to the safe
+ behavior.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 116]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Unrecognized cache-directives MUST be ignored; it is assumed that any
+ cache-directive likely to be unrecognized by an HTTP/1.1 cache will
+ be combined with standard directives (or the response's default
+ cacheability) such that the cache behavior will remain minimally
+ correct even if the cache does not understand the extension(s).
+
+14.10 Connection
+
+ The Connection general-header field allows the sender to specify
+ options that are desired for that particular connection and MUST NOT
+ be communicated by proxies over further connections.
+
+ The Connection header has the following grammar:
+
+ Connection = "Connection" ":" 1#(connection-token)
+ connection-token = token
+
+ HTTP/1.1 proxies MUST parse the Connection header field before a
+ message is forwarded and, for each connection-token in this field,
+ remove any header field(s) from the message with the same name as the
+ connection-token. Connection options are signaled by the presence of
+ a connection-token in the Connection header field, not by any
+ corresponding additional header field(s), since the additional header
+ field may not be sent if there are no parameters associated with that
+ connection option.
+
+ Message headers listed in the Connection header MUST NOT include
+ end-to-end headers, such as Cache-Control.
+
+ HTTP/1.1 defines the "close" connection option for the sender to
+ signal that the connection will be closed after completion of the
+ response. For example,
+
+ Connection: close
+
+ in either the request or the response header fields indicates that
+ the connection SHOULD NOT be considered `persistent' (section 8.1)
+ after the current request/response is complete.
+
+ HTTP/1.1 applications that do not support persistent connections MUST
+ include the "close" connection option in every message.
+
+ A system receiving an HTTP/1.0 (or lower-version) message that
+ includes a Connection header MUST, for each connection-token in this
+ field, remove and ignore any header field(s) from the message with
+ the same name as the connection-token. This protects against mistaken
+ forwarding of such header fields by pre-HTTP/1.1 proxies. See section
+ 19.6.2.
+
+
+
+Fielding, et al. Standards Track [Page 117]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.11 Content-Encoding
+
+ The Content-Encoding entity-header field is used as a modifier to the
+ media-type. When present, its value indicates what additional content
+ codings have been applied to the entity-body, and thus what decoding
+ mechanisms must be applied in order to obtain the media-type
+ referenced by the Content-Type header field. Content-Encoding is
+ primarily used to allow a document to be compressed without losing
+ the identity of its underlying media type.
+
+ Content-Encoding = "Content-Encoding" ":" 1#content-coding
+
+ Content codings are defined in section 3.5. An example of its use is
+
+ Content-Encoding: gzip
+
+ The content-coding is a characteristic of the entity identified by
+ the Request-URI. Typically, the entity-body is stored with this
+ encoding and is only decoded before rendering or analogous usage.
+ However, a non-transparent proxy MAY modify the content-coding if the
+ new coding is known to be acceptable to the recipient, unless the
+ "no-transform" cache-control directive is present in the message.
+
+ If the content-coding of an entity is not "identity", then the
+ response MUST include a Content-Encoding entity-header (section
+ 14.11) that lists the non-identity content-coding(s) used.
+
+ If the content-coding of an entity in a request message is not
+ acceptable to the origin server, the server SHOULD respond with a
+ status code of 415 (Unsupported Media Type).
+
+ If multiple encodings have been applied to an entity, the content
+ codings MUST be listed in the order in which they were applied.
+ Additional information about the encoding parameters MAY be provided
+ by other entity-header fields not defined by this specification.
+
+14.12 Content-Language
+
+ The Content-Language entity-header field describes the natural
+ language(s) of the intended audience for the enclosed entity. Note
+ that this might not be equivalent to all the languages used within
+ the entity-body.
+
+ Content-Language = "Content-Language" ":" 1#language-tag
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 118]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Language tags are defined in section 3.10. The primary purpose of
+ Content-Language is to allow a user to identify and differentiate
+ entities according to the user's own preferred language. Thus, if the
+ body content is intended only for a Danish-literate audience, the
+ appropriate field is
+
+ Content-Language: da
+
+ If no Content-Language is specified, the default is that the content
+ is intended for all language audiences. This might mean that the
+ sender does not consider it to be specific to any natural language,
+ or that the sender does not know for which language it is intended.
+
+ Multiple languages MAY be listed for content that is intended for
+ multiple audiences. For example, a rendition of the "Treaty of
+ Waitangi," presented simultaneously in the original Maori and English
+ versions, would call for
+
+ Content-Language: mi, en
+
+ However, just because multiple languages are present within an entity
+ does not mean that it is intended for multiple linguistic audiences.
+ An example would be a beginner's language primer, such as "A First
+ Lesson in Latin," which is clearly intended to be used by an
+ English-literate audience. In this case, the Content-Language would
+ properly only include "en".
+
+ Content-Language MAY be applied to any media type -- it is not
+ limited to textual documents.
+
+14.13 Content-Length
+
+ The Content-Length entity-header field indicates the size of the
+ entity-body, in decimal number of OCTETs, sent to the recipient or,
+ in the case of the HEAD method, the size of the entity-body that
+ would have been sent had the request been a GET.
+
+ Content-Length = "Content-Length" ":" 1*DIGIT
+
+ An example is
+
+ Content-Length: 3495
+
+ Applications SHOULD use this field to indicate the transfer-length of
+ the message-body, unless this is prohibited by the rules in section
+ 4.4.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 119]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Any Content-Length greater than or equal to zero is a valid value.
+ Section 4.4 describes how to determine the length of a message-body
+ if a Content-Length is not given.
+
+ Note that the meaning of this field is significantly different from
+ the corresponding definition in MIME, where it is an optional field
+ used within the "message/external-body" content-type. In HTTP, it
+ SHOULD be sent whenever the message's length can be determined prior
+ to being transferred, unless this is prohibited by the rules in
+ section 4.4.
+
+14.14 Content-Location
+
+ The Content-Location entity-header field MAY be used to supply the
+ resource location for the entity enclosed in the message when that
+ entity is accessible from a location separate from the requested
+ resource's URI. A server SHOULD provide a Content-Location for the
+ variant corresponding to the response entity; especially in the case
+ where a resource has multiple entities associated with it, and those
+ entities actually have separate locations by which they might be
+ individually accessed, the server SHOULD provide a Content-Location
+ for the particular variant which is returned.
+
+ Content-Location = "Content-Location" ":"
+ ( absoluteURI | relativeURI )
+
+ The value of Content-Location also defines the base URI for the
+ entity.
+
+ The Content-Location value is not a replacement for the original
+ requested URI; it is only a statement of the location of the resource
+ corresponding to this particular entity at the time of the request.
+ Future requests MAY specify the Content-Location URI as the request-
+ URI if the desire is to identify the source of that particular
+ entity.
+
+ A cache cannot assume that an entity with a Content-Location
+ different from the URI used to retrieve it can be used to respond to
+ later requests on that Content-Location URI. However, the Content-
+ Location can be used to differentiate between multiple entities
+ retrieved from a single requested resource, as described in section
+ 13.6.
+
+ If the Content-Location is a relative URI, the relative URI is
+ interpreted relative to the Request-URI.
+
+ The meaning of the Content-Location header in PUT or POST requests is
+ undefined; servers are free to ignore it in those cases.
+
+
+
+Fielding, et al. Standards Track [Page 120]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.15 Content-MD5
+
+ The Content-MD5 entity-header field, as defined in RFC 1864 [23], is
+ an MD5 digest of the entity-body for the purpose of providing an
+ end-to-end message integrity check (MIC) of the entity-body. (Note: a
+ MIC is good for detecting accidental modification of the entity-body
+ in transit, but is not proof against malicious attacks.)
+
+ Content-MD5 = "Content-MD5" ":" md5-digest
+ md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
+
+ The Content-MD5 header field MAY be generated by an origin server or
+ client to function as an integrity check of the entity-body. Only
+ origin servers or clients MAY generate the Content-MD5 header field;
+ proxies and gateways MUST NOT generate it, as this would defeat its
+ value as an end-to-end integrity check. Any recipient of the entity-
+ body, including gateways and proxies, MAY check that the digest value
+ in this header field matches that of the entity-body as received.
+
+ The MD5 digest is computed based on the content of the entity-body,
+ including any content-coding that has been applied, but not including
+ any transfer-encoding applied to the message-body. If the message is
+ received with a transfer-encoding, that encoding MUST be removed
+ prior to checking the Content-MD5 value against the received entity.
+
+ This has the result that the digest is computed on the octets of the
+ entity-body exactly as, and in the order that, they would be sent if
+ no transfer-encoding were being applied.
+
+ HTTP extends RFC 1864 to permit the digest to be computed for MIME
+ composite media-types (e.g., multipart/* and message/rfc822), but
+ this does not change how the digest is computed as defined in the
+ preceding paragraph.
+
+ There are several consequences of this. The entity-body for composite
+ types MAY contain many body-parts, each with its own MIME and HTTP
+ headers (including Content-MD5, Content-Transfer-Encoding, and
+ Content-Encoding headers). If a body-part has a Content-Transfer-
+ Encoding or Content-Encoding header, it is assumed that the content
+ of the body-part has had the encoding applied, and the body-part is
+ included in the Content-MD5 digest as is -- i.e., after the
+ application. The Transfer-Encoding header field is not allowed within
+ body-parts.
+
+ Conversion of all line breaks to CRLF MUST NOT be done before
+ computing or checking the digest: the line break convention used in
+ the text actually transmitted MUST be left unaltered when computing
+ the digest.
+
+
+
+Fielding, et al. Standards Track [Page 121]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Note: while the definition of Content-MD5 is exactly the same for
+ HTTP as in RFC 1864 for MIME entity-bodies, there are several ways
+ in which the application of Content-MD5 to HTTP entity-bodies
+ differs from its application to MIME entity-bodies. One is that
+ HTTP, unlike MIME, does not use Content-Transfer-Encoding, and
+ does use Transfer-Encoding and Content-Encoding. Another is that
+ HTTP more frequently uses binary content types than MIME, so it is
+ worth noting that, in such cases, the byte order used to compute
+ the digest is the transmission byte order defined for the type.
+ Lastly, HTTP allows transmission of text types with any of several
+ line break conventions and not just the canonical form using CRLF.
+
+14.16 Content-Range
+
+ The Content-Range entity-header is sent with a partial entity-body to
+ specify where in the full entity-body the partial body should be
+ applied. Range units are defined in section 3.12.
+
+ Content-Range = "Content-Range" ":" content-range-spec
+
+ content-range-spec = byte-content-range-spec
+ byte-content-range-spec = bytes-unit SP
+ byte-range-resp-spec "/"
+ ( instance-length | "*" )
+
+ byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
+ | "*"
+ instance-length = 1*DIGIT
+
+ The header SHOULD indicate the total length of the full entity-body,
+ unless this length is unknown or difficult to determine. The asterisk
+ "*" character means that the instance-length is unknown at the time
+ when the response was generated.
+
+ Unlike byte-ranges-specifier values (see section 14.35.1), a byte-
+ range-resp-spec MUST only specify one range, and MUST contain
+ absolute byte positions for both the first and last byte of the
+ range.
+
+ A byte-content-range-spec with a byte-range-resp-spec whose last-
+ byte-pos value is less than its first-byte-pos value, or whose
+ instance-length value is less than or equal to its last-byte-pos
+ value, is invalid. The recipient of an invalid byte-content-range-
+ spec MUST ignore it and any content transferred along with it.
+
+ A server sending a response with status code 416 (Requested range not
+ satisfiable) SHOULD include a Content-Range field with a byte-range-
+ resp-spec of "*". The instance-length specifies the current length of
+
+
+
+Fielding, et al. Standards Track [Page 122]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the selected resource. A response with status code 206 (Partial
+ Content) MUST NOT include a Content-Range field with a byte-range-
+ resp-spec of "*".
+
+ Examples of byte-content-range-spec values, assuming that the entity
+ contains a total of 1234 bytes:
+
+ . The first 500 bytes:
+ bytes 0-499/1234
+
+ . The second 500 bytes:
+ bytes 500-999/1234
+
+ . All except for the first 500 bytes:
+ bytes 500-1233/1234
+
+ . The last 500 bytes:
+ bytes 734-1233/1234
+
+ When an HTTP message includes the content of a single range (for
+ example, a response to a request for a single range, or to a request
+ for a set of ranges that overlap without any holes), this content is
+ transmitted with a Content-Range header, and a Content-Length header
+ showing the number of bytes actually transferred. For example,
+
+ HTTP/1.1 206 Partial content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-Range: bytes 21010-47021/47022
+ Content-Length: 26012
+ Content-Type: image/gif
+
+ When an HTTP message includes the content of multiple ranges (for
+ example, a response to a request for multiple non-overlapping
+ ranges), these are transmitted as a multipart message. The multipart
+ media type used for this purpose is "multipart/byteranges" as defined
+ in appendix 19.2. See appendix 19.6.3 for a compatibility issue.
+
+ A response to a request for a single range MUST NOT be sent using the
+ multipart/byteranges media type. A response to a request for
+ multiple ranges, whose result is a single range, MAY be sent as a
+ multipart/byteranges media type with one part. A client that cannot
+ decode a multipart/byteranges message MUST NOT ask for multiple
+ byte-ranges in a single request.
+
+ When a client requests multiple byte-ranges in one request, the
+ server SHOULD return them in the order that they appeared in the
+ request.
+
+
+
+Fielding, et al. Standards Track [Page 123]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the server ignores a byte-range-spec because it is syntactically
+ invalid, the server SHOULD treat the request as if the invalid Range
+ header field did not exist. (Normally, this means return a 200
+ response containing the full entity).
+
+ If the server receives a request (other than one including an If-
+ Range request-header field) with an unsatisfiable Range request-
+ header field (that is, all of whose byte-range-spec values have a
+ first-byte-pos value greater than the current length of the selected
+ resource), it SHOULD return a response code of 416 (Requested range
+ not satisfiable) (section 10.4.17).
+
+ Note: clients cannot depend on servers to send a 416 (Requested
+ range not satisfiable) response instead of a 200 (OK) response for
+ an unsatisfiable Range request-header, since not all servers
+ implement this request-header.
+
+14.17 Content-Type
+
+ The Content-Type entity-header field indicates the media type of the
+ entity-body sent to the recipient or, in the case of the HEAD method,
+ the media type that would have been sent had the request been a GET.
+
+ Content-Type = "Content-Type" ":" media-type
+
+ Media types are defined in section 3.7. An example of the field is
+
+ Content-Type: text/html; charset=ISO-8859-4
+
+ Further discussion of methods for identifying the media type of an
+ entity is provided in section 7.2.1.
+
+14.18 Date
+
+ The Date general-header field represents the date and time at which
+ the message was originated, having the same semantics as orig-date in
+ RFC 822. The field value is an HTTP-date, as described in section
+ 3.3.1; it MUST be sent in RFC 1123 [8]-date format.
+
+ Date = "Date" ":" HTTP-date
+
+ An example is
+
+ Date: Tue, 15 Nov 1994 08:12:31 GMT
+
+ Origin servers MUST include a Date header field in all responses,
+ except in these cases:
+
+
+
+
+Fielding, et al. Standards Track [Page 124]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 1. If the response status code is 100 (Continue) or 101 (Switching
+ Protocols), the response MAY include a Date header field, at
+ the server's option.
+
+ 2. If the response status code conveys a server error, e.g. 500
+ (Internal Server Error) or 503 (Service Unavailable), and it is
+ inconvenient or impossible to generate a valid Date.
+
+ 3. If the server does not have a clock that can provide a
+ reasonable approximation of the current time, its responses
+ MUST NOT include a Date header field. In this case, the rules
+ in section 14.18.1 MUST be followed.
+
+ A received message that does not have a Date header field MUST be
+ assigned one by the recipient if the message will be cached by that
+ recipient or gatewayed via a protocol which requires a Date. An HTTP
+ implementation without a clock MUST NOT cache responses without
+ revalidating them on every use. An HTTP cache, especially a shared
+ cache, SHOULD use a mechanism, such as NTP [28], to synchronize its
+ clock with a reliable external standard.
+
+ Clients SHOULD only send a Date header field in messages that include
+ an entity-body, as in the case of the PUT and POST requests, and even
+ then it is optional. A client without a clock MUST NOT send a Date
+ header field in a request.
+
+ The HTTP-date sent in a Date header SHOULD NOT represent a date and
+ time subsequent to the generation of the message. It SHOULD represent
+ the best available approximation of the date and time of message
+ generation, unless the implementation has no means of generating a
+ reasonably accurate date and time. In theory, the date ought to
+ represent the moment just before the entity is generated. In
+ practice, the date can be generated at any time during the message
+ origination without affecting its semantic value.
+
+14.18.1 Clockless Origin Server Operation
+
+ Some origin server implementations might not have a clock available.
+ An origin server without a clock MUST NOT assign Expires or Last-
+ Modified values to a response, unless these values were associated
+ with the resource by a system or user with a reliable clock. It MAY
+ assign an Expires value that is known, at or before server
+ configuration time, to be in the past (this allows "pre-expiration"
+ of responses without storing separate Expires values for each
+ resource).
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 125]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.19 ETag
+
+ The ETag response-header field provides the current value of the
+ entity tag for the requested variant. The headers used with entity
+ tags are described in sections 14.24, 14.26 and 14.44. The entity tag
+ MAY be used for comparison with other entities from the same resource
+ (see section 13.3.3).
+
+ ETag = "ETag" ":" entity-tag
+
+ Examples:
+
+ ETag: "xyzzy"
+ ETag: W/"xyzzy"
+ ETag: ""
+
+14.20 Expect
+
+ The Expect request-header field is used to indicate that particular
+ server behaviors are required by the client.
+
+ Expect = "Expect" ":" 1#expectation
+
+ expectation = "100-continue" | expectation-extension
+ expectation-extension = token [ "=" ( token | quoted-string )
+ *expect-params ]
+ expect-params = ";" token [ "=" ( token | quoted-string ) ]
+
+
+ A server that does not understand or is unable to comply with any of
+ the expectation values in the Expect field of a request MUST respond
+ with appropriate error status. The server MUST respond with a 417
+ (Expectation Failed) status if any of the expectations cannot be met
+ or, if there are other problems with the request, some other 4xx
+ status.
+
+ This header field is defined with extensible syntax to allow for
+ future extensions. If a server receives a request containing an
+ Expect field that includes an expectation-extension that it does not
+ support, it MUST respond with a 417 (Expectation Failed) status.
+
+ Comparison of expectation values is case-insensitive for unquoted
+ tokens (including the 100-continue token), and is case-sensitive for
+ quoted-string expectation-extensions.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 126]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST
+ return a 417 (Expectation Failed) status if it receives a request
+ with an expectation that it cannot meet. However, the Expect
+ request-header itself is end-to-end; it MUST be forwarded if the
+ request is forwarded.
+
+ Many older HTTP/1.0 and HTTP/1.1 applications do not understand the
+ Expect header.
+
+ See section 8.2.3 for the use of the 100 (continue) status.
+
+14.21 Expires
+
+ The Expires entity-header field gives the date/time after which the
+ response is considered stale. A stale cache entry may not normally be
+ returned by a cache (either a proxy cache or a user agent cache)
+ unless it is first validated with the origin server (or with an
+ intermediate cache that has a fresh copy of the entity). See section
+ 13.2 for further discussion of the expiration model.
+
+ The presence of an Expires field does not imply that the original
+ resource will change or cease to exist at, before, or after that
+ time.
+
+ The format is an absolute date and time as defined by HTTP-date in
+ section 3.3.1; it MUST be in RFC 1123 date format:
+
+ Expires = "Expires" ":" HTTP-date
+
+ An example of its use is
+
+ Expires: Thu, 01 Dec 1994 16:00:00 GMT
+
+ Note: if a response includes a Cache-Control field with the max-
+ age directive (see section 14.9.3), that directive overrides the
+ Expires field.
+
+ HTTP/1.1 clients and caches MUST treat other invalid date formats,
+ especially including the value "0", as in the past (i.e., "already
+ expired").
+
+ To mark a response as "already expired," an origin server sends an
+ Expires date that is equal to the Date header value. (See the rules
+ for expiration calculations in section 13.2.4.)
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 127]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ To mark a response as "never expires," an origin server sends an
+ Expires date approximately one year from the time the response is
+ sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one
+ year in the future.
+
+ The presence of an Expires header field with a date value of some
+ time in the future on a response that otherwise would by default be
+ non-cacheable indicates that the response is cacheable, unless
+ indicated otherwise by a Cache-Control header field (section 14.9).
+
+14.22 From
+
+ The From request-header field, if given, SHOULD contain an Internet
+ e-mail address for the human user who controls the requesting user
+ agent. The address SHOULD be machine-usable, as defined by "mailbox"
+ in RFC 822 [9] as updated by RFC 1123 [8]:
+
+ From = "From" ":" mailbox
+
+ An example is:
+
+ From: webmaster at w3.org
+
+ This header field MAY be used for logging purposes and as a means for
+ identifying the source of invalid or unwanted requests. It SHOULD NOT
+ be used as an insecure form of access protection. The interpretation
+ of this field is that the request is being performed on behalf of the
+ person given, who accepts responsibility for the method performed. In
+ particular, robot agents SHOULD include this header so that the
+ person responsible for running the robot can be contacted if problems
+ occur on the receiving end.
+
+ The Internet e-mail address in this field MAY be separate from the
+ Internet host which issued the request. For example, when a request
+ is passed through a proxy the original issuer's address SHOULD be
+ used.
+
+ The client SHOULD NOT send the From header field without the user's
+ approval, as it might conflict with the user's privacy interests or
+ their site's security policy. It is strongly recommended that the
+ user be able to disable, enable, and modify the value of this field
+ at any time prior to a request.
+
+14.23 Host
+
+ The Host request-header field specifies the Internet host and port
+ number of the resource being requested, as obtained from the original
+ URI given by the user or referring resource (generally an HTTP URL,
+
+
+
+Fielding, et al. Standards Track [Page 128]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ as described in section 3.2.2). The Host field value MUST represent
+ the naming authority of the origin server or gateway given by the
+ original URL. This allows the origin server or gateway to
+ differentiate between internally-ambiguous URLs, such as the root "/"
+ URL of a server for multiple host names on a single IP address.
+
+ Host = "Host" ":" host [ ":" port ] ; Section 3.2.2
+
+ A "host" without any trailing port information implies the default
+ port for the service requested (e.g., "80" for an HTTP URL). For
+ example, a request on the origin server for
+ <http://www.w3.org/pub/WWW/> would properly include:
+
+ GET /pub/WWW/ HTTP/1.1
+ Host: www.w3.org
+
+ A client MUST include a Host header field in all HTTP/1.1 request
+ messages . If the requested URI does not include an Internet host
+ name for the service being requested, then the Host header field MUST
+ be given with an empty value. An HTTP/1.1 proxy MUST ensure that any
+ request message it forwards does contain an appropriate Host header
+ field that identifies the service being requested by the proxy. All
+ Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request)
+ status code to any HTTP/1.1 request message which lacks a Host header
+ field.
+
+ See sections 5.2 and 19.6.1.1 for other requirements relating to
+ Host.
+
+14.24 If-Match
+
+ The If-Match request-header field is used with a method to make it
+ conditional. A client that has one or more entities previously
+ obtained from the resource can verify that one of those entities is
+ current by including a list of their associated entity tags in the
+ If-Match header field. Entity tags are defined in section 3.11. The
+ purpose of this feature is to allow efficient updates of cached
+ information with a minimum amount of transaction overhead. It is also
+ used, on updating requests, to prevent inadvertent modification of
+ the wrong version of a resource. As a special case, the value "*"
+ matches any current entity of the resource.
+
+ If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-Match header) on that resource, or if "*" is given
+
+
+
+
+Fielding, et al. Standards Track [Page 129]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ and any current entity exists for that resource, then the server MAY
+ perform the requested method as if the If-Match header field did not
+ exist.
+
+ A server MUST use the strong comparison function (see section 13.3.3)
+ to compare the entity tags in If-Match.
+
+ If none of the entity tags match, or if "*" is given and no current
+ entity exists, the server MUST NOT perform the requested method, and
+ MUST return a 412 (Precondition Failed) response. This behavior is
+ most useful when the client wants to prevent an updating method, such
+ as PUT, from modifying a resource that has changed since the client
+ last retrieved it.
+
+ If the request would, without the If-Match header field, result in
+ anything other than a 2xx or 412 status, then the If-Match header
+ MUST be ignored.
+
+ The meaning of "If-Match: *" is that the method SHOULD be performed
+ if the representation selected by the origin server (or by a cache,
+ possibly using the Vary mechanism, see section 14.44) exists, and
+ MUST NOT be performed if the representation does not exist.
+
+ A request intended to update a resource (e.g., a PUT) MAY include an
+ If-Match header field to signal that the request method MUST NOT be
+ applied if the entity corresponding to the If-Match value (a single
+ entity tag) is no longer a representation of that resource. This
+ allows the user to indicate that they do not wish the request to be
+ successful if the resource has been changed without their knowledge.
+ Examples:
+
+ If-Match: "xyzzy"
+ If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-Match: *
+
+ The result of a request having both an If-Match header field and
+ either an If-None-Match or an If-Modified-Since header fields is
+ undefined by this specification.
+
+14.25 If-Modified-Since
+
+ The If-Modified-Since request-header field is used with a method to
+ make it conditional: if the requested variant has not been modified
+ since the time specified in this field, an entity will not be
+ returned from the server; instead, a 304 (not modified) response will
+ be returned without any message-body.
+
+ If-Modified-Since = "If-Modified-Since" ":" HTTP-date
+
+
+
+Fielding, et al. Standards Track [Page 130]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An example of the field is:
+
+ If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ A GET method with an If-Modified-Since header and no Range header
+ requests that the identified entity be transferred only if it has
+ been modified since the date given by the If-Modified-Since header.
+ The algorithm for determining this includes the following cases:
+
+ a) If the request would normally result in anything other than a
+ 200 (OK) status, or if the passed If-Modified-Since date is
+ invalid, the response is exactly the same as for a normal GET.
+ A date which is later than the server's current time is
+ invalid.
+
+ b) If the variant has been modified since the If-Modified-Since
+ date, the response is exactly the same as for a normal GET.
+
+ c) If the variant has not been modified since a valid If-
+ Modified-Since date, the server SHOULD return a 304 (Not
+ Modified) response.
+
+ The purpose of this feature is to allow efficient updates of cached
+ information with a minimum amount of transaction overhead.
+
+ Note: The Range request-header field modifies the meaning of If-
+ Modified-Since; see section 14.35 for full details.
+
+ Note: If-Modified-Since times are interpreted by the server, whose
+ clock might not be synchronized with the client.
+
+ Note: When handling an If-Modified-Since header field, some
+ servers will use an exact date comparison function, rather than a
+ less-than function, for deciding whether to send a 304 (Not
+ Modified) response. To get best results when sending an If-
+ Modified-Since header field for cache validation, clients are
+ advised to use the exact date string received in a previous Last-
+ Modified header field whenever possible.
+
+ Note: If a client uses an arbitrary date in the If-Modified-Since
+ header instead of a date taken from the Last-Modified header for
+ the same request, the client should be aware of the fact that this
+ date is interpreted in the server's understanding of time. The
+ client should consider unsynchronized clocks and rounding problems
+ due to the different encodings of time between the client and
+ server. This includes the possibility of race conditions if the
+ document has changed between the time it was first requested and
+ the If-Modified-Since date of a subsequent request, and the
+
+
+
+Fielding, et al. Standards Track [Page 131]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ possibility of clock-skew-related problems if the If-Modified-
+ Since date is derived from the client's clock without correction
+ to the server's clock. Corrections for different time bases
+ between client and server are at best approximate due to network
+ latency.
+
+ The result of a request having both an If-Modified-Since header field
+ and either an If-Match or an If-Unmodified-Since header fields is
+ undefined by this specification.
+
+14.26 If-None-Match
+
+ The If-None-Match request-header field is used with a method to make
+ it conditional. A client that has one or more entities previously
+ obtained from the resource can verify that none of those entities is
+ current by including a list of their associated entity tags in the
+ If-None-Match header field. The purpose of this feature is to allow
+ efficient updates of cached information with a minimum amount of
+ transaction overhead. It is also used to prevent a method (e.g. PUT)
+ from inadvertently modifying an existing resource when the client
+ believes that the resource does not exist.
+
+ As a special case, the value "*" matches any current entity of the
+ resource.
+
+ If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
+
+ If any of the entity tags match the entity tag of the entity that
+ would have been returned in the response to a similar GET request
+ (without the If-None-Match header) on that resource, or if "*" is
+ given and any current entity exists for that resource, then the
+ server MUST NOT perform the requested method, unless required to do
+ so because the resource's modification date fails to match that
+ supplied in an If-Modified-Since header field in the request.
+ Instead, if the request method was GET or HEAD, the server SHOULD
+ respond with a 304 (Not Modified) response, including the cache-
+ related header fields (particularly ETag) of one of the entities that
+ matched. For all other request methods, the server MUST respond with
+ a status of 412 (Precondition Failed).
+
+ See section 13.3.3 for rules on how to determine if two entities tags
+ match. The weak comparison function can only be used with GET or HEAD
+ requests.
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 132]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If none of the entity tags match, then the server MAY perform the
+ requested method as if the If-None-Match header field did not exist,
+ but MUST also ignore any If-Modified-Since header field(s) in the
+ request. That is, if no entity tags match, then the server MUST NOT
+ return a 304 (Not Modified) response.
+
+ If the request would, without the If-None-Match header field, result
+ in anything other than a 2xx or 304 status, then the If-None-Match
+ header MUST be ignored. (See section 13.3.4 for a discussion of
+ server behavior when both If-Modified-Since and If-None-Match appear
+ in the same request.)
+
+ The meaning of "If-None-Match: *" is that the method MUST NOT be
+ performed if the representation selected by the origin server (or by
+ a cache, possibly using the Vary mechanism, see section 14.44)
+ exists, and SHOULD be performed if the representation does not exist.
+ This feature is intended to be useful in preventing races between PUT
+ operations.
+
+ Examples:
+
+ If-None-Match: "xyzzy"
+ If-None-Match: W/"xyzzy"
+ If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+ If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+ If-None-Match: *
+
+ The result of a request having both an If-None-Match header field and
+ either an If-Match or an If-Unmodified-Since header fields is
+ undefined by this specification.
+
+14.27 If-Range
+
+ If a client has a partial copy of an entity in its cache, and wishes
+ to have an up-to-date copy of the entire entity in its cache, it
+ could use the Range request-header with a conditional GET (using
+ either or both of If-Unmodified-Since and If-Match.) However, if the
+ condition fails because the entity has been modified, the client
+ would then have to make a second request to obtain the entire current
+ entity-body.
+
+ The If-Range header allows a client to "short-circuit" the second
+ request. Informally, its meaning is `if the entity is unchanged, send
+ me the part(s) that I am missing; otherwise, send me the entire new
+ entity'.
+
+ If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
+
+
+
+
+Fielding, et al. Standards Track [Page 133]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the client has no entity tag for an entity, but does have a Last-
+ Modified date, it MAY use that date in an If-Range header. (The
+ server can distinguish between a valid HTTP-date and any form of
+ entity-tag by examining no more than two characters.) The If-Range
+ header SHOULD only be used together with a Range header, and MUST be
+ ignored if the request does not include a Range header, or if the
+ server does not support the sub-range operation.
+
+ If the entity tag given in the If-Range header matches the current
+ entity tag for the entity, then the server SHOULD provide the
+ specified sub-range of the entity using a 206 (Partial content)
+ response. If the entity tag does not match, then the server SHOULD
+ return the entire entity using a 200 (OK) response.
+
+14.28 If-Unmodified-Since
+
+ The If-Unmodified-Since request-header field is used with a method to
+ make it conditional. If the requested resource has not been modified
+ since the time specified in this field, the server SHOULD perform the
+ requested operation as if the If-Unmodified-Since header were not
+ present.
+
+ If the requested variant has been modified since the specified time,
+ the server MUST NOT perform the requested operation, and MUST return
+ a 412 (Precondition Failed).
+
+ If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
+
+ An example of the field is:
+
+ If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
+ If the request normally (i.e., without the If-Unmodified-Since
+ header) would result in anything other than a 2xx or 412 status, the
+ If-Unmodified-Since header SHOULD be ignored.
+
+ If the specified date is invalid, the header is ignored.
+
+ The result of a request having both an If-Unmodified-Since header
+ field and either an If-None-Match or an If-Modified-Since header
+ fields is undefined by this specification.
+
+14.29 Last-Modified
+
+ The Last-Modified entity-header field indicates the date and time at
+ which the origin server believes the variant was last modified.
+
+ Last-Modified = "Last-Modified" ":" HTTP-date
+
+
+
+Fielding, et al. Standards Track [Page 134]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ An example of its use is
+
+ Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
+
+ The exact meaning of this header field depends on the implementation
+ of the origin server and the nature of the original resource. For
+ files, it may be just the file system last-modified time. For
+ entities with dynamically included parts, it may be the most recent
+ of the set of last-modify times for its component parts. For database
+ gateways, it may be the last-update time stamp of the record. For
+ virtual objects, it may be the last time the internal state changed.
+
+ An origin server MUST NOT send a Last-Modified date which is later
+ than the server's time of message origination. In such cases, where
+ the resource's last modification would indicate some time in the
+ future, the server MUST replace that date with the message
+ origination date.
+
+ An origin server SHOULD obtain the Last-Modified value of the entity
+ as close as possible to the time that it generates the Date value of
+ its response. This allows a recipient to make an accurate assessment
+ of the entity's modification time, especially if the entity changes
+ near the time that the response is generated.
+
+ HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
+
+14.30 Location
+
+ The Location response-header field is used to redirect the recipient
+ to a location other than the Request-URI for completion of the
+ request or identification of a new resource. For 201 (Created)
+ responses, the Location is that of the new resource which was created
+ by the request. For 3xx responses, the location SHOULD indicate the
+ server's preferred URI for automatic redirection to the resource. The
+ field value consists of a single absolute URI.
+
+ Location = "Location" ":" absoluteURI
+
+ An example is:
+
+ Location: http://www.w3.org/pub/WWW/People.html
+
+ Note: The Content-Location header field (section 14.14) differs
+ from Location in that the Content-Location identifies the original
+ location of the entity enclosed in the request. It is therefore
+ possible for a response to contain header fields for both Location
+ and Content-Location. Also see section 13.10 for cache
+ requirements of some methods.
+
+
+
+Fielding, et al. Standards Track [Page 135]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.31 Max-Forwards
+
+ The Max-Forwards request-header field provides a mechanism with the
+ TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the
+ number of proxies or gateways that can forward the request to the
+ next inbound server. This can be useful when the client is attempting
+ to trace a request chain which appears to be failing or looping in
+ mid-chain.
+
+ Max-Forwards = "Max-Forwards" ":" 1*DIGIT
+
+ The Max-Forwards value is a decimal integer indicating the remaining
+ number of times this request message may be forwarded.
+
+ Each proxy or gateway recipient of a TRACE or OPTIONS request
+ containing a Max-Forwards header field MUST check and update its
+ value prior to forwarding the request. If the received value is zero
+ (0), the recipient MUST NOT forward the request; instead, it MUST
+ respond as the final recipient. If the received Max-Forwards value is
+ greater than zero, then the forwarded message MUST contain an updated
+ Max-Forwards field with a value decremented by one (1).
+
+ The Max-Forwards header field MAY be ignored for all other methods
+ defined by this specification and for any extension methods for which
+ it is not explicitly referred to as part of that method definition.
+
+14.32 Pragma
+
+ The Pragma general-header field is used to include implementation-
+ specific directives that might apply to any recipient along the
+ request/response chain. All pragma directives specify optional
+ behavior from the viewpoint of the protocol; however, some systems
+ MAY require that behavior be consistent with the directives.
+
+ Pragma = "Pragma" ":" 1#pragma-directive
+ pragma-directive = "no-cache" | extension-pragma
+ extension-pragma = token [ "=" ( token | quoted-string ) ]
+
+ When the no-cache directive is present in a request message, an
+ application SHOULD forward the request toward the origin server even
+ if it has a cached copy of what is being requested. This pragma
+ directive has the same semantics as the no-cache cache-directive (see
+ section 14.9) and is defined here for backward compatibility with
+ HTTP/1.0. Clients SHOULD include both header fields when a no-cache
+ request is sent to a server not known to be HTTP/1.1 compliant.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 136]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Pragma directives MUST be passed through by a proxy or gateway
+ application, regardless of their significance to that application,
+ since the directives might be applicable to all recipients along the
+ request/response chain. It is not possible to specify a pragma for a
+ specific recipient; however, any pragma directive not relevant to a
+ recipient SHOULD be ignored by that recipient.
+
+ HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had
+ sent "Cache-Control: no-cache". No new Pragma directives will be
+ defined in HTTP.
+
+ Note: because the meaning of "Pragma: no-cache as a response
+ header field is not actually specified, it does not provide a
+ reliable replacement for "Cache-Control: no-cache" in a response
+
+14.33 Proxy-Authenticate
+
+ The Proxy-Authenticate response-header field MUST be included as part
+ of a 407 (Proxy Authentication Required) response. The field value
+ consists of a challenge that indicates the authentication scheme and
+ parameters applicable to the proxy for this Request-URI.
+
+ Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. Unlike
+ WWW-Authenticate, the Proxy-Authenticate header field applies only to
+ the current connection and SHOULD NOT be passed on to downstream
+ clients. However, an intermediate proxy might need to obtain its own
+ credentials by requesting them from the downstream client, which in
+ some circumstances will appear as if the proxy is forwarding the
+ Proxy-Authenticate header field.
+
+14.34 Proxy-Authorization
+
+ The Proxy-Authorization request-header field allows the client to
+ identify itself (or its user) to a proxy which requires
+ authentication. The Proxy-Authorization field value consists of
+ credentials containing the authentication information of the user
+ agent for the proxy and/or realm of the resource being requested.
+
+ Proxy-Authorization = "Proxy-Authorization" ":" credentials
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43] . Unlike
+ Authorization, the Proxy-Authorization header field applies only to
+ the next outbound proxy that demanded authentication using the Proxy-
+ Authenticate field. When multiple proxies are used in a chain, the
+
+
+
+Fielding, et al. Standards Track [Page 137]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Proxy-Authorization header field is consumed by the first outbound
+ proxy that was expecting to receive credentials. A proxy MAY relay
+ the credentials from the client request to the next proxy if that is
+ the mechanism by which the proxies cooperatively authenticate a given
+ request.
+
+14.35 Range
+
+14.35.1 Byte Ranges
+
+ Since all HTTP entities are represented in HTTP messages as sequences
+ of bytes, the concept of a byte range is meaningful for any HTTP
+ entity. (However, not all clients and servers need to support byte-
+ range operations.)
+
+ Byte range specifications in HTTP apply to the sequence of bytes in
+ the entity-body (not necessarily the same as the message-body).
+
+ A byte range operation MAY specify a single range of bytes, or a set
+ of ranges within a single entity.
+
+ ranges-specifier = byte-ranges-specifier
+ byte-ranges-specifier = bytes-unit "=" byte-range-set
+ byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec )
+ byte-range-spec = first-byte-pos "-" [last-byte-pos]
+ first-byte-pos = 1*DIGIT
+ last-byte-pos = 1*DIGIT
+
+ The first-byte-pos value in a byte-range-spec gives the byte-offset
+ of the first byte in a range. The last-byte-pos value gives the
+ byte-offset of the last byte in the range; that is, the byte
+ positions specified are inclusive. Byte offsets start at zero.
+
+ If the last-byte-pos value is present, it MUST be greater than or
+ equal to the first-byte-pos in that byte-range-spec, or the byte-
+ range-spec is syntactically invalid. The recipient of a byte-range-
+ set that includes one or more syntactically invalid byte-range-spec
+ values MUST ignore the header field that includes that byte-range-
+ set.
+
+ If the last-byte-pos value is absent, or if the value is greater than
+ or equal to the current length of the entity-body, last-byte-pos is
+ taken to be equal to one less than the current length of the entity-
+ body in bytes.
+
+ By its choice of last-byte-pos, a client can limit the number of
+ bytes retrieved without knowing the size of the entity.
+
+
+
+
+Fielding, et al. Standards Track [Page 138]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ suffix-byte-range-spec = "-" suffix-length
+ suffix-length = 1*DIGIT
+
+ A suffix-byte-range-spec is used to specify the suffix of the
+ entity-body, of a length given by the suffix-length value. (That is,
+ this form specifies the last N bytes of an entity-body.) If the
+ entity is shorter than the specified suffix-length, the entire
+ entity-body is used.
+
+ If a syntactically valid byte-range-set includes at least one byte-
+ range-spec whose first-byte-pos is less than the current length of
+ the entity-body, or at least one suffix-byte-range-spec with a non-
+ zero suffix-length, then the byte-range-set is satisfiable.
+ Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set
+ is unsatisfiable, the server SHOULD return a response with a status
+ of 416 (Requested range not satisfiable). Otherwise, the server
+ SHOULD return a response with a status of 206 (Partial Content)
+ containing the satisfiable ranges of the entity-body.
+
+ Examples of byte-ranges-specifier values (assuming an entity-body of
+ length 10000):
+
+ - The first 500 bytes (byte offsets 0-499, inclusive): bytes=0-
+ 499
+
+ - The second 500 bytes (byte offsets 500-999, inclusive):
+ bytes=500-999
+
+ - The final 500 bytes (byte offsets 9500-9999, inclusive):
+ bytes=-500
+
+ - Or bytes=9500-
+
+ - The first and last bytes only (bytes 0 and 9999): bytes=0-0,-1
+
+ - Several legal but not canonical specifications of the second 500
+ bytes (byte offsets 500-999, inclusive):
+ bytes=500-600,601-999
+ bytes=500-700,601-999
+
+14.35.2 Range Retrieval Requests
+
+ HTTP retrieval requests using conditional or unconditional GET
+ methods MAY request one or more sub-ranges of the entity, instead of
+ the entire entity, using the Range request header, which applies to
+ the entity returned as the result of the request:
+
+ Range = "Range" ":" ranges-specifier
+
+
+
+Fielding, et al. Standards Track [Page 139]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ A server MAY ignore the Range header. However, HTTP/1.1 origin
+ servers and intermediate caches ought to support byte ranges when
+ possible, since Range supports efficient recovery from partially
+ failed transfers, and supports efficient partial retrieval of large
+ entities.
+
+ If the server supports the Range header and the specified range or
+ ranges are appropriate for the entity:
+
+ - The presence of a Range header in an unconditional GET modifies
+ what is returned if the GET is otherwise successful. In other
+ words, the response carries a status code of 206 (Partial
+ Content) instead of 200 (OK).
+
+ - The presence of a Range header in a conditional GET (a request
+ using one or both of If-Modified-Since and If-None-Match, or
+ one or both of If-Unmodified-Since and If-Match) modifies what
+ is returned if the GET is otherwise successful and the
+ condition is true. It does not affect the 304 (Not Modified)
+ response returned if the conditional is false.
+
+ In some cases, it might be more appropriate to use the If-Range
+ header (see section 14.27) in addition to the Range header.
+
+ If a proxy that supports ranges receives a Range request, forwards
+ the request to an inbound server, and receives an entire entity in
+ reply, it SHOULD only return the requested range to its client. It
+ SHOULD store the entire received response in its cache if that is
+ consistent with its cache allocation policies.
+
+14.36 Referer
+
+ The Referer[sic] request-header field allows the client to specify,
+ for the server's benefit, the address (URI) of the resource from
+ which the Request-URI was obtained (the "referrer", although the
+ header field is misspelled.) The Referer request-header allows a
+ server to generate lists of back-links to resources for interest,
+ logging, optimized caching, etc. It also allows obsolete or mistyped
+ links to be traced for maintenance. The Referer field MUST NOT be
+ sent if the Request-URI was obtained from a source that does not have
+ its own URI, such as input from the user keyboard.
+
+ Referer = "Referer" ":" ( absoluteURI | relativeURI )
+
+ Example:
+
+ Referer: http://www.w3.org/hypertext/DataSources/Overview.html
+
+
+
+
+Fielding, et al. Standards Track [Page 140]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If the field value is a relative URI, it SHOULD be interpreted
+ relative to the Request-URI. The URI MUST NOT include a fragment. See
+ section 15.1.3 for security considerations.
+
+14.37 Retry-After
+
+ The Retry-After response-header field can be used with a 503 (Service
+ Unavailable) response to indicate how long the service is expected to
+ be unavailable to the requesting client. This field MAY also be used
+ with any 3xx (Redirection) response to indicate the minimum time the
+ user-agent is asked wait before issuing the redirected request. The
+ value of this field can be either an HTTP-date or an integer number
+ of seconds (in decimal) after the time of the response.
+
+ Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds )
+
+ Two examples of its use are
+
+ Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
+ Retry-After: 120
+
+ In the latter example, the delay is 2 minutes.
+
+14.38 Server
+
+ The Server response-header field contains information about the
+ software used by the origin server to handle the request. The field
+ can contain multiple product tokens (section 3.8) and comments
+ identifying the server and any significant subproducts. The product
+ tokens are listed in order of their significance for identifying the
+ application.
+
+ Server = "Server" ":" 1*( product | comment )
+
+ Example:
+
+ Server: CERN/3.0 libwww/2.17
+
+ If the response is being forwarded through a proxy, the proxy
+ application MUST NOT modify the Server response-header. Instead, it
+ SHOULD include a Via field (as described in section 14.45).
+
+ Note: Revealing the specific software version of the server might
+ allow the server machine to become more vulnerable to attacks
+ against software that is known to contain security holes. Server
+ implementors are encouraged to make this field a configurable
+ option.
+
+
+
+
+Fielding, et al. Standards Track [Page 141]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+14.39 TE
+
+ The TE request-header field indicates what extension transfer-codings
+ it is willing to accept in the response and whether or not it is
+ willing to accept trailer fields in a chunked transfer-coding. Its
+ value may consist of the keyword "trailers" and/or a comma-separated
+ list of extension transfer-coding names with optional accept
+ parameters (as described in section 3.6).
+
+ TE = "TE" ":" #( t-codings )
+ t-codings = "trailers" | ( transfer-extension [ accept-params ] )
+
+ The presence of the keyword "trailers" indicates that the client is
+ willing to accept trailer fields in a chunked transfer-coding, as
+ defined in section 3.6.1. This keyword is reserved for use with
+ transfer-coding values even though it does not itself represent a
+ transfer-coding.
+
+ Examples of its use are:
+
+ TE: deflate
+ TE:
+ TE: trailers, deflate;q=0.5
+
+ The TE header field only applies to the immediate connection.
+ Therefore, the keyword MUST be supplied within a Connection header
+ field (section 14.10) whenever TE is present in an HTTP/1.1 message.
+
+ A server tests whether a transfer-coding is acceptable, according to
+ a TE field, using these rules:
+
+ 1. The "chunked" transfer-coding is always acceptable. If the
+ keyword "trailers" is listed, the client indicates that it is
+ willing to accept trailer fields in the chunked response on
+ behalf of itself and any downstream clients. The implication is
+ that, if given, the client is stating that either all
+ downstream clients are willing to accept trailer fields in the
+ forwarded response, or that it will attempt to buffer the
+ response on behalf of downstream recipients.
+
+ Note: HTTP/1.1 does not define any means to limit the size of a
+ chunked response such that a client can be assured of buffering
+ the entire response.
+
+ 2. If the transfer-coding being tested is one of the transfer-
+ codings listed in the TE field, then it is acceptable unless it
+ is accompanied by a qvalue of 0. (As defined in section 3.9, a
+ qvalue of 0 means "not acceptable.")
+
+
+
+Fielding, et al. Standards Track [Page 142]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 3. If multiple transfer-codings are acceptable, then the
+ acceptable transfer-coding with the highest non-zero qvalue is
+ preferred. The "chunked" transfer-coding always has a qvalue
+ of 1.
+
+ If the TE field-value is empty or if no TE field is present, the only
+ transfer-coding is "chunked". A message with no transfer-coding is
+ always acceptable.
+
+14.40 Trailer
+
+ The Trailer general field value indicates that the given set of
+ header fields is present in the trailer of a message encoded with
+ chunked transfer-coding.
+
+ Trailer = "Trailer" ":" 1#field-name
+
+ An HTTP/1.1 message SHOULD include a Trailer header field in a
+ message using chunked transfer-coding with a non-empty trailer. Doing
+ so allows the recipient to know which header fields to expect in the
+ trailer.
+
+ If no Trailer header field is present, the trailer SHOULD NOT include
+ any header fields. See section 3.6.1 for restrictions on the use of
+ trailer fields in a "chunked" transfer-coding.
+
+ Message header fields listed in the Trailer header field MUST NOT
+ include the following header fields:
+
+ . Transfer-Encoding
+
+ . Content-Length
+
+ . Trailer
+
+14.41 Transfer-Encoding
+
+ The Transfer-Encoding general-header field indicates what (if any)
+ type of transformation has been applied to the message body in order
+ to safely transfer it between the sender and the recipient. This
+ differs from the content-coding in that the transfer-coding is a
+ property of the message, not of the entity.
+
+ Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding
+
+ Transfer-codings are defined in section 3.6. An example is:
+
+ Transfer-Encoding: chunked
+
+
+
+Fielding, et al. Standards Track [Page 143]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ If multiple encodings have been applied to an entity, the transfer-
+ codings MUST be listed in the order in which they were applied.
+ Additional information about the encoding parameters MAY be provided
+ by other entity-header fields not defined by this specification.
+
+ Many older HTTP/1.0 applications do not understand the Transfer-
+ Encoding header.
+
+14.42 Upgrade
+
+ The Upgrade general-header allows the client to specify what
+ additional communication protocols it supports and would like to use
+ if the server finds it appropriate to switch protocols. The server
+ MUST use the Upgrade header field within a 101 (Switching Protocols)
+ response to indicate which protocol(s) are being switched.
+
+ Upgrade = "Upgrade" ":" 1#product
+
+ For example,
+
+ Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
+
+ The Upgrade header field is intended to provide a simple mechanism
+ for transition from HTTP/1.1 to some other, incompatible protocol. It
+ does so by allowing the client to advertise its desire to use another
+ protocol, such as a later version of HTTP with a higher major version
+ number, even though the current request has been made using HTTP/1.1.
+ This eases the difficult transition between incompatible protocols by
+ allowing the client to initiate a request in the more commonly
+ supported protocol while indicating to the server that it would like
+ to use a "better" protocol if available (where "better" is determined
+ by the server, possibly according to the nature of the method and/or
+ resource being requested).
+
+ The Upgrade header field only applies to switching application-layer
+ protocols upon the existing transport-layer connection. Upgrade
+ cannot be used to insist on a protocol change; its acceptance and use
+ by the server is optional. The capabilities and nature of the
+ application-layer communication after the protocol change is entirely
+ dependent upon the new protocol chosen, although the first action
+ after changing the protocol MUST be a response to the initial HTTP
+ request containing the Upgrade header field.
+
+ The Upgrade header field only applies to the immediate connection.
+ Therefore, the upgrade keyword MUST be supplied within a Connection
+ header field (section 14.10) whenever Upgrade is present in an
+ HTTP/1.1 message.
+
+
+
+
+Fielding, et al. Standards Track [Page 144]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Upgrade header field cannot be used to indicate a switch to a
+ protocol on a different connection. For that purpose, it is more
+ appropriate to use a 301, 302, 303, or 305 redirection response.
+
+ This specification only defines the protocol name "HTTP" for use by
+ the family of Hypertext Transfer Protocols, as defined by the HTTP
+ version rules of section 3.1 and future updates to this
+ specification. Any token can be used as a protocol name; however, it
+ will only be useful if both the client and server associate the name
+ with the same protocol.
+
+14.43 User-Agent
+
+ The User-Agent request-header field contains information about the
+ user agent originating the request. This is for statistical purposes,
+ the tracing of protocol violations, and automated recognition of user
+ agents for the sake of tailoring responses to avoid particular user
+ agent limitations. User agents SHOULD include this field with
+ requests. The field can contain multiple product tokens (section 3.8)
+ and comments identifying the agent and any subproducts which form a
+ significant part of the user agent. By convention, the product tokens
+ are listed in order of their significance for identifying the
+ application.
+
+ User-Agent = "User-Agent" ":" 1*( product | comment )
+
+ Example:
+
+ User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+
+14.44 Vary
+
+ The Vary field value indicates the set of request-header fields that
+ fully determines, while the response is fresh, whether a cache is
+ permitted to use the response to reply to a subsequent request
+ without revalidation. For uncacheable or stale responses, the Vary
+ field value advises the user agent about the criteria that were used
+ to select the representation. A Vary field value of "*" implies that
+ a cache cannot determine from the request headers of a subsequent
+ request whether this response is the appropriate representation. See
+ section 13.6 for use of the Vary header field by caches.
+
+ Vary = "Vary" ":" ( "*" | 1#field-name )
+
+ An HTTP/1.1 server SHOULD include a Vary header field with any
+ cacheable response that is subject to server-driven negotiation.
+ Doing so allows a cache to properly interpret future requests on that
+ resource and informs the user agent about the presence of negotiation
+
+
+
+Fielding, et al. Standards Track [Page 145]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ on that resource. A server MAY include a Vary header field with a
+ non-cacheable response that is subject to server-driven negotiation,
+ since this might provide the user agent with useful information about
+ the dimensions over which the response varies at the time of the
+ response.
+
+ A Vary field value consisting of a list of field-names signals that
+ the representation selected for the response is based on a selection
+ algorithm which considers ONLY the listed request-header field values
+ in selecting the most appropriate representation. A cache MAY assume
+ that the same selection will be made for future requests with the
+ same values for the listed field names, for the duration of time for
+ which the response is fresh.
+
+ The field-names given are not limited to the set of standard
+ request-header fields defined by this specification. Field names are
+ case-insensitive.
+
+ A Vary field value of "*" signals that unspecified parameters not
+ limited to the request-headers (e.g., the network address of the
+ client), play a role in the selection of the response representation.
+ The "*" value MUST NOT be generated by a proxy server; it may only be
+ generated by an origin server.
+
+14.45 Via
+
+ The Via general-header field MUST be used by gateways and proxies to
+ indicate the intermediate protocols and recipients between the user
+ agent and the server on requests, and between the origin server and
+ the client on responses. It is analogous to the "Received" field of
+ RFC 822 [9] and is intended to be used for tracking message forwards,
+ avoiding request loops, and identifying the protocol capabilities of
+ all senders along the request/response chain.
+
+ Via = "Via" ":" 1#( received-protocol received-by [ comment ] )
+ received-protocol = [ protocol-name "/" ] protocol-version
+ protocol-name = token
+ protocol-version = token
+ received-by = ( host [ ":" port ] ) | pseudonym
+ pseudonym = token
+
+ The received-protocol indicates the protocol version of the message
+ received by the server or client along each segment of the
+ request/response chain. The received-protocol version is appended to
+ the Via field value when the message is forwarded so that information
+ about the protocol capabilities of upstream applications remains
+ visible to all recipients.
+
+
+
+
+Fielding, et al. Standards Track [Page 146]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The protocol-name is optional if and only if it would be "HTTP". The
+ received-by field is normally the host and optional port number of a
+ recipient server or client that subsequently forwarded the message.
+ However, if the real host is considered to be sensitive information,
+ it MAY be replaced by a pseudonym. If the port is not given, it MAY
+ be assumed to be the default port of the received-protocol.
+
+ Multiple Via field values represents each proxy or gateway that has
+ forwarded the message. Each recipient MUST append its information
+ such that the end result is ordered according to the sequence of
+ forwarding applications.
+
+ Comments MAY be used in the Via header field to identify the software
+ of the recipient proxy or gateway, analogous to the User-Agent and
+ Server header fields. However, all comments in the Via field are
+ optional and MAY be removed by any recipient prior to forwarding the
+ message.
+
+ For example, a request message could be sent from an HTTP/1.0 user
+ agent to an internal proxy code-named "fred", which uses HTTP/1.1 to
+ forward the request to a public proxy at nowhere.com, which completes
+ the request by forwarding it to the origin server at www.ics.uci.edu.
+ The request received by www.ics.uci.edu would then have the following
+ Via header field:
+
+ Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
+
+ Proxies and gateways used as a portal through a network firewall
+ SHOULD NOT, by default, forward the names and ports of hosts within
+ the firewall region. This information SHOULD only be propagated if
+ explicitly enabled. If not enabled, the received-by host of any host
+ behind the firewall SHOULD be replaced by an appropriate pseudonym
+ for that host.
+
+ For organizations that have strong privacy requirements for hiding
+ internal structures, a proxy MAY combine an ordered subsequence of
+ Via header field entries with identical received-protocol values into
+ a single such entry. For example,
+
+ Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
+
+ could be collapsed to
+
+ Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 147]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Applications SHOULD NOT combine multiple entries unless they are all
+ under the same organizational control and the hosts have already been
+ replaced by pseudonyms. Applications MUST NOT combine entries which
+ have different received-protocol values.
+
+14.46 Warning
+
+ The Warning general-header field is used to carry additional
+ information about the status or transformation of a message which
+ might not be reflected in the message. This information is typically
+ used to warn about a possible lack of semantic transparency from
+ caching operations or transformations applied to the entity body of
+ the message.
+
+ Warning headers are sent with responses using:
+
+ Warning = "Warning" ":" 1#warning-value
+
+ warning-value = warn-code SP warn-agent SP warn-text
+ [SP warn-date]
+
+ warn-code = 3DIGIT
+ warn-agent = ( host [ ":" port ] ) | pseudonym
+ ; the name or pseudonym of the server adding
+ ; the Warning header, for use in debugging
+ warn-text = quoted-string
+ warn-date = <"> HTTP-date <">
+
+ A response MAY carry more than one Warning header.
+
+ The warn-text SHOULD be in a natural language and character set that
+ is most likely to be intelligible to the human user receiving the
+ response. This decision MAY be based on any available knowledge, such
+ as the location of the cache or user, the Accept-Language field in a
+ request, the Content-Language field in a response, etc. The default
+ language is English and the default character set is ISO-8859-1.
+
+ If a character set other than ISO-8859-1 is used, it MUST be encoded
+ in the warn-text using the method described in RFC 2047 [14].
+
+ Warning headers can in general be applied to any message, however
+ some specific warn-codes are specific to caches and can only be
+ applied to response messages. New Warning headers SHOULD be added
+ after any existing Warning headers. A cache MUST NOT delete any
+ Warning header that it received with a message. However, if a cache
+ successfully validates a cache entry, it SHOULD remove any Warning
+ headers previously attached to that entry except as specified for
+
+
+
+
+Fielding, et al. Standards Track [Page 148]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ specific Warning codes. It MUST then add any Warning headers received
+ in the validating response. In other words, Warning headers are those
+ that would be attached to the most recent relevant response.
+
+ When multiple Warning headers are attached to a response, the user
+ agent ought to inform the user of as many of them as possible, in the
+ order that they appear in the response. If it is not possible to
+ inform the user of all of the warnings, the user agent SHOULD follow
+ these heuristics:
+
+ - Warnings that appear early in the response take priority over
+ those appearing later in the response.
+
+ - Warnings in the user's preferred character set take priority
+ over warnings in other character sets but with identical warn-
+ codes and warn-agents.
+
+ Systems that generate multiple Warning headers SHOULD order them with
+ this user agent behavior in mind.
+
+ Requirements for the behavior of caches with respect to Warnings are
+ stated in section 13.1.2.
+
+ This is a list of the currently-defined warn-codes, each with a
+ recommended warn-text in English, and a description of its meaning.
+
+ 110 Response is stale
+ MUST be included whenever the returned response is stale.
+
+ 111 Revalidation failed
+ MUST be included if a cache returns a stale response because an
+ attempt to revalidate the response failed, due to an inability to
+ reach the server.
+
+ 112 Disconnected operation
+ SHOULD be included if the cache is intentionally disconnected from
+ the rest of the network for a period of time.
+
+ 113 Heuristic expiration
+ MUST be included if the cache heuristically chose a freshness
+ lifetime greater than 24 hours and the response's age is greater
+ than 24 hours.
+
+ 199 Miscellaneous warning
+ The warning text MAY include arbitrary information to be presented
+ to a human user, or logged. A system receiving this warning MUST
+ NOT take any automated action, besides presenting the warning to
+ the user.
+
+
+
+Fielding, et al. Standards Track [Page 149]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 214 Transformation applied
+ MUST be added by an intermediate cache or proxy if it applies any
+ transformation changing the content-coding (as specified in the
+ Content-Encoding header) or media-type (as specified in the
+ Content-Type header) of the response, or the entity-body of the
+ response, unless this Warning code already appears in the response.
+
+ 299 Miscellaneous persistent warning
+ The warning text MAY include arbitrary information to be presented
+ to a human user, or logged. A system receiving this warning MUST
+ NOT take any automated action.
+
+ If an implementation sends a message with one or more Warning headers
+ whose version is HTTP/1.0 or lower, then the sender MUST include in
+ each warning-value a warn-date that matches the date in the response.
+
+ If an implementation receives a message with a warning-value that
+ includes a warn-date, and that warn-date is different from the Date
+ value in the response, then that warning-value MUST be deleted from
+ the message before storing, forwarding, or using it. (This prevents
+ bad consequences of naive caching of Warning header fields.) If all
+ of the warning-values are deleted for this reason, the Warning header
+ MUST be deleted as well.
+
+14.47 WWW-Authenticate
+
+ The WWW-Authenticate response-header field MUST be included in 401
+ (Unauthorized) response messages. The field value consists of at
+ least one challenge that indicates the authentication scheme(s) and
+ parameters applicable to the Request-URI.
+
+ WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
+
+ The HTTP access authentication process is described in "HTTP
+ Authentication: Basic and Digest Access Authentication" [43]. User
+ agents are advised to take special care in parsing the WWW-
+ Authenticate field value as it might contain more than one challenge,
+ or if more than one WWW-Authenticate header field is provided, the
+ contents of a challenge itself can contain a comma-separated list of
+ authentication parameters.
+
+15 Security Considerations
+
+ This section is meant to inform application developers, information
+ providers, and users of the security limitations in HTTP/1.1 as
+ described by this document. The discussion does not include
+ definitive solutions to the problems revealed, though it does make
+ some suggestions for reducing security risks.
+
+
+
+Fielding, et al. Standards Track [Page 150]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.1 Personal Information
+
+ HTTP clients are often privy to large amounts of personal information
+ (e.g. the user's name, location, mail address, passwords, encryption
+ keys, etc.), and SHOULD be very careful to prevent unintentional
+ leakage of this information via the HTTP protocol to other sources.
+ We very strongly recommend that a convenient interface be provided
+ for the user to control dissemination of such information, and that
+ designers and implementors be particularly careful in this area.
+ History shows that errors in this area often create serious security
+ and/or privacy problems and generate highly adverse publicity for the
+ implementor's company.
+
+15.1.1 Abuse of Server Log Information
+
+ A server is in the position to save personal data about a user's
+ requests which might identify their reading patterns or subjects of
+ interest. This information is clearly confidential in nature and its
+ handling can be constrained by law in certain countries. People using
+ the HTTP protocol to provide data are responsible for ensuring that
+ such material is not distributed without the permission of any
+ individuals that are identifiable by the published results.
+
+15.1.2 Transfer of Sensitive Information
+
+ Like any generic data transfer protocol, HTTP cannot regulate the
+ content of the data that is transferred, nor is there any a priori
+ method of determining the sensitivity of any particular piece of
+ information within the context of any given request. Therefore,
+ applications SHOULD supply as much control over this information as
+ possible to the provider of that information. Four header fields are
+ worth special mention in this context: Server, Via, Referer and From.
+
+ Revealing the specific software version of the server might allow the
+ server machine to become more vulnerable to attacks against software
+ that is known to contain security holes. Implementors SHOULD make the
+ Server header field a configurable option.
+
+ Proxies which serve as a portal through a network firewall SHOULD
+ take special precautions regarding the transfer of header information
+ that identifies the hosts behind the firewall. In particular, they
+ SHOULD remove, or replace with sanitized versions, any Via fields
+ generated behind the firewall.
+
+ The Referer header allows reading patterns to be studied and reverse
+ links drawn. Although it can be very useful, its power can be abused
+ if user details are not separated from the information contained in
+
+
+
+
+Fielding, et al. Standards Track [Page 151]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ the Referer. Even when the personal information has been removed, the
+ Referer header might indicate a private document's URI whose
+ publication would be inappropriate.
+
+ The information sent in the From field might conflict with the user's
+ privacy interests or their site's security policy, and hence it
+ SHOULD NOT be transmitted without the user being able to disable,
+ enable, and modify the contents of the field. The user MUST be able
+ to set the contents of this field within a user preference or
+ application defaults configuration.
+
+ We suggest, though do not require, that a convenient toggle interface
+ be provided for the user to enable or disable the sending of From and
+ Referer information.
+
+ The User-Agent (section 14.43) or Server (section 14.38) header
+ fields can sometimes be used to determine that a specific client or
+ server have a particular security hole which might be exploited.
+ Unfortunately, this same information is often used for other valuable
+ purposes for which HTTP currently has no better mechanism.
+
+15.1.3 Encoding Sensitive Information in URI's
+
+ Because the source of a link might be private information or might
+ reveal an otherwise private information source, it is strongly
+ recommended that the user be able to select whether or not the
+ Referer field is sent. For example, a browser client could have a
+ toggle switch for browsing openly/anonymously, which would
+ respectively enable/disable the sending of Referer and From
+ information.
+
+ Clients SHOULD NOT include a Referer header field in a (non-secure)
+ HTTP request if the referring page was transferred with a secure
+ protocol.
+
+ Authors of services which use the HTTP protocol SHOULD NOT use GET
+ based forms for the submission of sensitive data, because this will
+ cause this data to be encoded in the Request-URI. Many existing
+ servers, proxies, and user agents will log the request URI in some
+ place where it might be visible to third parties. Servers can use
+ POST-based form submission instead
+
+15.1.4 Privacy Issues Connected to Accept Headers
+
+ Accept request-headers can reveal information about the user to all
+ servers which are accessed. The Accept-Language header in particular
+ can reveal information the user would consider to be of a private
+ nature, because the understanding of particular languages is often
+
+
+
+Fielding, et al. Standards Track [Page 152]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ strongly correlated to the membership of a particular ethnic group.
+ User agents which offer the option to configure the contents of an
+ Accept-Language header to be sent in every request are strongly
+ encouraged to let the configuration process include a message which
+ makes the user aware of the loss of privacy involved.
+
+ An approach that limits the loss of privacy would be for a user agent
+ to omit the sending of Accept-Language headers by default, and to ask
+ the user whether or not to start sending Accept-Language headers to a
+ server if it detects, by looking for any Vary response-header fields
+ generated by the server, that such sending could improve the quality
+ of service.
+
+ Elaborate user-customized accept header fields sent in every request,
+ in particular if these include quality values, can be used by servers
+ as relatively reliable and long-lived user identifiers. Such user
+ identifiers would allow content providers to do click-trail tracking,
+ and would allow collaborating content providers to match cross-server
+ click-trails or form submissions of individual users. Note that for
+ many users not behind a proxy, the network address of the host
+ running the user agent will also serve as a long-lived user
+ identifier. In environments where proxies are used to enhance
+ privacy, user agents ought to be conservative in offering accept
+ header configuration options to end users. As an extreme privacy
+ measure, proxies could filter the accept headers in relayed requests.
+ General purpose user agents which provide a high degree of header
+ configurability SHOULD warn users about the loss of privacy which can
+ be involved.
+
+15.2 Attacks Based On File and Path Names
+
+ Implementations of HTTP origin servers SHOULD be careful to restrict
+ the documents returned by HTTP requests to be only those that were
+ intended by the server administrators. If an HTTP server translates
+ HTTP URIs directly into file system calls, the server MUST take
+ special care not to serve files that were not intended to be
+ delivered to HTTP clients. For example, UNIX, Microsoft Windows, and
+ other operating systems use ".." as a path component to indicate a
+ directory level above the current one. On such a system, an HTTP
+ server MUST disallow any such construct in the Request-URI if it
+ would otherwise allow access to a resource outside those intended to
+ be accessible via the HTTP server. Similarly, files intended for
+ reference only internally to the server (such as access control
+ files, configuration files, and script code) MUST be protected from
+ inappropriate retrieval, since they might contain sensitive
+ information. Experience has shown that minor bugs in such HTTP server
+ implementations have turned into security risks.
+
+
+
+
+Fielding, et al. Standards Track [Page 153]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.3 DNS Spoofing
+
+ Clients using HTTP rely heavily on the Domain Name Service, and are
+ thus generally prone to security attacks based on the deliberate
+ mis-association of IP addresses and DNS names. Clients need to be
+ cautious in assuming the continuing validity of an IP number/DNS name
+ association.
+
+ In particular, HTTP clients SHOULD rely on their name resolver for
+ confirmation of an IP number/DNS name association, rather than
+ caching the result of previous host name lookups. Many platforms
+ already can cache host name lookups locally when appropriate, and
+ they SHOULD be configured to do so. It is proper for these lookups to
+ be cached, however, only when the TTL (Time To Live) information
+ reported by the name server makes it likely that the cached
+ information will remain useful.
+
+ If HTTP clients cache the results of host name lookups in order to
+ achieve a performance improvement, they MUST observe the TTL
+ information reported by DNS.
+
+ If HTTP clients do not observe this rule, they could be spoofed when
+ a previously-accessed server's IP address changes. As network
+ renumbering is expected to become increasingly common [24], the
+ possibility of this form of attack will grow. Observing this
+ requirement thus reduces this potential security vulnerability.
+
+ This requirement also improves the load-balancing behavior of clients
+ for replicated servers using the same DNS name and reduces the
+ likelihood of a user's experiencing failure in accessing sites which
+ use that strategy.
+
+15.4 Location Headers and Spoofing
+
+ If a single server supports multiple organizations that do not trust
+ one another, then it MUST check the values of Location and Content-
+ Location headers in responses that are generated under control of
+ said organizations to make sure that they do not attempt to
+ invalidate resources over which they have no authority.
+
+15.5 Content-Disposition Issues
+
+ RFC 1806 [35], from which the often implemented Content-Disposition
+ (see section 19.5.1) header in HTTP is derived, has a number of very
+ serious security considerations. Content-Disposition is not part of
+ the HTTP standard, but since it is widely implemented, we are
+ documenting its use and risks for implementors. See RFC 2183 [49]
+ (which updates RFC 1806) for details.
+
+
+
+Fielding, et al. Standards Track [Page 154]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+15.6 Authentication Credentials and Idle Clients
+
+ Existing HTTP clients and user agents typically retain authentication
+ information indefinitely. HTTP/1.1. does not provide a method for a
+ server to direct clients to discard these cached credentials. This is
+ a significant defect that requires further extensions to HTTP.
+ Circumstances under which credential caching can interfere with the
+ application's security model include but are not limited to:
+
+ - Clients which have been idle for an extended period following
+ which the server might wish to cause the client to reprompt the
+ user for credentials.
+
+ - Applications which include a session termination indication
+ (such as a `logout' or `commit' button on a page) after which
+ the server side of the application `knows' that there is no
+ further reason for the client to retain the credentials.
+
+ This is currently under separate study. There are a number of work-
+ arounds to parts of this problem, and we encourage the use of
+ password protection in screen savers, idle time-outs, and other
+ methods which mitigate the security problems inherent in this
+ problem. In particular, user agents which cache credentials are
+ encouraged to provide a readily accessible mechanism for discarding
+ cached credentials under user control.
+
+15.7 Proxies and Caching
+
+ By their very nature, HTTP proxies are men-in-the-middle, and
+ represent an opportunity for man-in-the-middle attacks. Compromise of
+ the systems on which the proxies run can result in serious security
+ and privacy problems. Proxies have access to security-related
+ information, personal information about individual users and
+ organizations, and proprietary information belonging to users and
+ content providers. A compromised proxy, or a proxy implemented or
+ configured without regard to security and privacy considerations,
+ might be used in the commission of a wide range of potential attacks.
+
+ Proxy operators should protect the systems on which proxies run as
+ they would protect any system that contains or transports sensitive
+ information. In particular, log information gathered at proxies often
+ contains highly sensitive personal information, and/or information
+ about organizations. Log information should be carefully guarded, and
+ appropriate guidelines for use developed and followed. (Section
+ 15.1.1).
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 155]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Caching proxies provide additional potential vulnerabilities, since
+ the contents of the cache represent an attractive target for
+ malicious exploitation. Because cache contents persist after an HTTP
+ request is complete, an attack on the cache can reveal information
+ long after a user believes that the information has been removed from
+ the network. Therefore, cache contents should be protected as
+ sensitive information.
+
+ Proxy implementors should consider the privacy and security
+ implications of their design and coding decisions, and of the
+ configuration options they provide to proxy operators (especially the
+ default configuration).
+
+ Users of a proxy need to be aware that they are no trustworthier than
+ the people who run the proxy; HTTP itself cannot solve this problem.
+
+ The judicious use of cryptography, when appropriate, may suffice to
+ protect against a broad range of security and privacy attacks. Such
+ cryptography is beyond the scope of the HTTP/1.1 specification.
+
+15.7.1 Denial of Service Attacks on Proxies
+
+ They exist. They are hard to defend against. Research continues.
+ Beware.
+
+16 Acknowledgments
+
+ This specification makes heavy use of the augmented BNF and generic
+ constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it
+ reuses many of the definitions provided by Nathaniel Borenstein and
+ Ned Freed for MIME [7]. We hope that their inclusion in this
+ specification will help reduce past confusion over the relationship
+ between HTTP and Internet mail message formats.
+
+ The HTTP protocol has evolved considerably over the years. It has
+ benefited from a large and active developer community--the many
+ people who have participated on the www-talk mailing list--and it is
+ that community which has been most responsible for the success of
+ HTTP and of the World-Wide Web in general. Marc Andreessen, Robert
+ Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois
+ Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob
+ McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc
+ VanHeyningen deserve special recognition for their efforts in
+ defining early aspects of the protocol.
+
+ This document has benefited greatly from the comments of all those
+ participating in the HTTP-WG. In addition to those already mentioned,
+ the following individuals have contributed to this specification:
+
+
+
+Fielding, et al. Standards Track [Page 156]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Gary Adams Ross Patterson
+ Harald Tveit Alvestrand Albert Lunde
+ Keith Ball John C. Mallery
+ Brian Behlendorf Jean-Philippe Martin-Flatin
+ Paul Burchard Mitra
+ Maurizio Codogno David Morris
+ Mike Cowlishaw Gavin Nicol
+ Roman Czyborra Bill Perry
+ Michael A. Dolan Jeffrey Perry
+ David J. Fiander Scott Powers
+ Alan Freier Owen Rees
+ Marc Hedlund Luigi Rizzo
+ Greg Herlihy David Robinson
+ Koen Holtman Marc Salomon
+ Alex Hopmann Rich Salz
+ Bob Jernigan Allan M. Schiffman
+ Shel Kaphan Jim Seidman
+ Rohit Khare Chuck Shotton
+ John Klensin Eric W. Sink
+ Martijn Koster Simon E. Spero
+ Alexei Kosut Richard N. Taylor
+ David M. Kristol Robert S. Thau
+ Daniel LaLiberte Bill (BearHeart) Weinman
+ Ben Laurie Francois Yergeau
+ Paul J. Leach Mary Ellen Zurko
+ Daniel DuBois Josh Cohen
+
+
+ Much of the content and presentation of the caching design is due to
+ suggestions and comments from individuals including: Shel Kaphan,
+ Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
+
+ Most of the specification of ranges is based on work originally done
+ by Ari Luotonen and John Franks, with additional input from Steve
+ Zilles.
+
+ Thanks to the "cave men" of Palo Alto. You know who you are.
+
+ Jim Gettys (the current editor of this document) wishes particularly
+ to thank Roy Fielding, the previous editor of this document, along
+ with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen
+ Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and
+ Larry Masinter for their help. And thanks go particularly to Jeff
+ Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 157]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik
+ Frystyk implemented RFC 2068 early, and we wish to thank them for the
+ discovery of many of the problems that this document attempts to
+ rectify.
+
+17 References
+
+ [1] Alvestrand, H., "Tags for the Identification of Languages", RFC
+ 1766, March 1995.
+
+ [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey,
+ D. and B. Alberti, "The Internet Gopher Protocol (a distributed
+ document search and retrieval protocol)", RFC 1436, March 1993.
+
+ [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", RFC
+ 1630, June 1994.
+
+ [4] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
+ Locators (URL)", RFC 1738, December 1994.
+
+ [5] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language -
+ 2.0", RFC 1866, November 1995.
+
+ [6] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer
+ Protocol -- HTTP/1.0", RFC 1945, May 1996.
+
+ [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message Bodies",
+ RFC 2045, November 1996.
+
+ [8] Braden, R., "Requirements for Internet Hosts -- Communication
+ Layers", STD 3, RFC 1123, October 1989.
+
+ [9] Crocker, D., "Standard for The Format of ARPA Internet Text
+ Messages", STD 11, RFC 822, August 1982.
+
+ [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R.,
+ Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype
+ Functional Specification," (v1.5), Thinking Machines
+ Corporation, April 1990.
+
+ [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808,
+ June 1995.
+
+ [12] Horton, M. and R. Adams, "Standard for Interchange of USENET
+ Messages", RFC 1036, December 1987.
+
+
+
+
+
+Fielding, et al. Standards Track [Page 158]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [13] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC
+ 977, February 1986.
+
+ [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
+ Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
+ November 1996.
+
+ [15] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC
+ 1867, November 1995.
+
+ [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
+ August 1982.
+
+ [17] Postel, J., "Media Type Registration Procedure", RFC 1590,
+ November 1996.
+
+ [18] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC
+ 959, October 1985.
+
+ [19] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700,
+ October 1994.
+
+ [20] Sollins, K. and L. Masinter, "Functional Requirements for
+ Uniform Resource Names", RFC 1737, December 1994.
+
+ [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for
+ Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
+
+ [22] ISO-8859. International Standard -- Information Processing --
+ 8-bit Single-Byte Coded Graphic Character Sets --
+ Part 1: Latin alphabet No. 1, ISO-8859-1:1987.
+ Part 2: Latin alphabet No. 2, ISO-8859-2, 1987.
+ Part 3: Latin alphabet No. 3, ISO-8859-3, 1988.
+ Part 4: Latin alphabet No. 4, ISO-8859-4, 1988.
+ Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988.
+ Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987.
+ Part 7: Latin/Greek alphabet, ISO-8859-7, 1987.
+ Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988.
+ Part 9: Latin alphabet No. 5, ISO-8859-9, 1990.
+
+ [23] Meyers, J. and M. Rose, "The Content-MD5 Header Field", RFC
+ 1864, October 1995.
+
+ [24] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC
+ 1900, February 1996.
+
+ [25] Deutsch, P., "GZIP file format specification version 4.3", RFC
+ 1952, May 1996.
+
+
+
+Fielding, et al. Standards Track [Page 159]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [26] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP
+ Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35,
+ Dec. 1995. Slightly revised version of paper in Proc. 2nd
+ International WWW Conference '94: Mosaic and the Web, Oct. 1994,
+ which is available at
+ http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat
+ ency.html.
+
+ [27] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP
+ Performance", <URL: http://www.isi.edu/touch/pubs/http-perf96/>,
+ ISI Research Report ISI/RR-98-463, (original report dated Aug.
+ 1996), USC/Information Sciences Institute, August 1998.
+
+ [28] Mills, D., "Network Time Protocol (Version 3) Specification,
+ Implementation and Analysis", RFC 1305, March 1992.
+
+ [29] Deutsch, P., "DEFLATE Compressed Data Format Specification
+ version 1.3", RFC 1951, May 1996.
+
+ [30] S. Spero, "Analysis of HTTP Performance Problems,"
+ http://sunsite.unc.edu/mdma-release/http-prob.html.
+
+ [31] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format
+ Specification version 3.3", RFC 1950, May 1996.
+
+ [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
+ Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP:
+ Digest Access Authentication", RFC 2069, January 1997.
+
+ [33] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T.
+ Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC
+ 2068, January 1997.
+
+ [34] Bradner, S., "Key words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+ [35] Troost, R. and Dorner, S., "Communicating Presentation
+ Information in Internet Messages: The Content-Disposition
+ Header", RFC 1806, June 1995.
+
+ [36] Mogul, J., Fielding, R., Gettys, J. and H. Frystyk, "Use and
+ Interpretation of HTTP Version Numbers", RFC 2145, May 1997.
+ [jg639]
+
+ [37] Palme, J., "Common Internet Message Headers", RFC 2076, February
+ 1997. [jg640]
+
+
+
+
+
+Fielding, et al. Standards Track [Page 160]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ [38] Yergeau, F., "UTF-8, a transformation format of Unicode and
+ ISO-10646", RFC 2279, January 1998. [jg641]
+
+ [39] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E.,
+ Lie, H., and C. Lilley. "Network Performance Effects of
+ HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes
+ France, September 1997.[jg642]
+
+ [40] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Two: Media Types", RFC 2046, November
+ 1996. [jg643]
+
+ [41] Alvestrand, H., "IETF Policy on Character Sets and Languages",
+ BCP 18, RFC 2277, January 1998. [jg644]
+
+ [42] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
+ Identifiers (URI): Generic Syntax and Semantics", RFC 2396,
+ August 1998. [jg645]
+
+ [43] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
+ Leach, P., Luotonen, A., Sink, E. and L. Stewart, "HTTP
+ Authentication: Basic and Digest Access Authentication", RFC
+ 2617, June 1999. [jg646]
+
+ [44] Luotonen, A., "Tunneling TCP based protocols through Web proxy
+ servers," Work in Progress. [jg647]
+
+ [45] Palme, J. and A. Hopmann, "MIME E-mail Encapsulation of
+ Aggregate Documents, such as HTML (MHTML)", RFC 2110, March
+ 1997.
+
+ [46] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
+ 9, RFC 2026, October 1996.
+
+ [47] Masinter, L., "Hyper Text Coffee Pot Control Protocol
+ (HTCPCP/1.0)", RFC 2324, 1 April 1998.
+
+ [48] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part Five: Conformance Criteria and Examples",
+ RFC 2049, November 1996.
+
+ [49] Troost, R., Dorner, S. and K. Moore, "Communicating Presentation
+ Information in Internet Messages: The Content-Disposition Header
+ Field", RFC 2183, August 1997.
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 161]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+18 Authors' Addresses
+
+ Roy T. Fielding
+ Information and Computer Science
+ University of California, Irvine
+ Irvine, CA 92697-3425, USA
+
+ Fax: +1 (949) 824-1715
+ EMail: fielding at ics.uci.edu
+
+
+ James Gettys
+ World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+ EMail: jg at w3.org
+
+
+ Jeffrey C. Mogul
+ Western Research Laboratory
+ Compaq Computer Corporation
+ 250 University Avenue
+ Palo Alto, California, 94305, USA
+
+ EMail: mogul at wrl.dec.com
+
+
+ Henrik Frystyk Nielsen
+ World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+ EMail: frystyk at w3.org
+
+
+ Larry Masinter
+ Xerox Corporation
+ 3333 Coyote Hill Road
+ Palo Alto, CA 94034, USA
+
+ EMail: masinter at parc.xerox.com
+
+
+
+
+
+Fielding, et al. Standards Track [Page 162]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Paul J. Leach
+ Microsoft Corporation
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+
+ EMail: paulle at microsoft.com
+
+
+ Tim Berners-Lee
+ Director, World Wide Web Consortium
+ MIT Laboratory for Computer Science
+ 545 Technology Square
+ Cambridge, MA 02139, USA
+
+ Fax: +1 (617) 258 8682
+ EMail: timbl at w3.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 163]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+19 Appendices
+
+19.1 Internet Media Type message/http and application/http
+
+ In addition to defining the HTTP/1.1 protocol, this document serves
+ as the specification for the Internet media type "message/http" and
+ "application/http". The message/http type can be used to enclose a
+ single HTTP request or response message, provided that it obeys the
+ MIME restrictions for all "message" types regarding line length and
+ encodings. The application/http type can be used to enclose a
+ pipeline of one or more HTTP request or response messages (not
+ intermixed). The following is to be registered with IANA [17].
+
+ Media Type name: message
+ Media subtype name: http
+ Required parameters: none
+ Optional parameters: version, msgtype
+ version: The HTTP-Version number of the enclosed message
+ (e.g., "1.1"). If not present, the version can be
+ determined from the first line of the body.
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+ Security considerations: none
+
+ Media Type name: application
+ Media subtype name: http
+ Required parameters: none
+ Optional parameters: version, msgtype
+ version: The HTTP-Version number of the enclosed messages
+ (e.g., "1.1"). If not present, the version can be
+ determined from the first line of the body.
+ msgtype: The message type -- "request" or "response". If not
+ present, the type can be determined from the first
+ line of the body.
+ Encoding considerations: HTTP messages enclosed by this type
+ are in "binary" format; use of an appropriate
+ Content-Transfer-Encoding is required when
+ transmitted via E-mail.
+ Security considerations: none
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 164]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+19.2 Internet Media Type multipart/byteranges
+
+ When an HTTP 206 (Partial Content) response message includes the
+ content of multiple ranges (a response to a request for multiple
+ non-overlapping ranges), these are transmitted as a multipart
+ message-body. The media type for this purpose is called
+ "multipart/byteranges".
+
+ The multipart/byteranges media type includes two or more parts, each
+ with its own Content-Type and Content-Range fields. The required
+ boundary parameter specifies the boundary string used to separate
+ each body-part.
+
+ Media Type name: multipart
+ Media subtype name: byteranges
+ Required parameters: boundary
+ Optional parameters: none
+ Encoding considerations: only "7bit", "8bit", or "binary" are
+ permitted
+ Security considerations: none
+
+
+ For example:
+
+ HTTP/1.1 206 Partial Content
+ Date: Wed, 15 Nov 1995 06:25:24 GMT
+ Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+ Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
+
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 500-999/8000
+
+ ...the first range...
+ --THIS_STRING_SEPARATES
+ Content-type: application/pdf
+ Content-range: bytes 7000-7999/8000
+
+ ...the second range
+ --THIS_STRING_SEPARATES--
+
+ Notes:
+
+ 1) Additional CRLFs may precede the first boundary string in the
+ entity.
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 165]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ 2) Although RFC 2046 [40] permits the boundary string to be
+ quoted, some existing implementations handle a quoted boundary
+ string incorrectly.
+
+ 3) A number of browsers and servers were coded to an early draft
+ of the byteranges specification to use a media type of
+ multipart/x-byteranges, which is almost, but not quite
+ compatible with the version documented in HTTP/1.1.
+
+19.3 Tolerant Applications
+
+ Although this document specifies the requirements for the generation
+ of HTTP/1.1 messages, not all applications will be correct in their
+ implementation. We therefore recommend that operational applications
+ be tolerant of deviations whenever those deviations can be
+ interpreted unambiguously.
+
+ Clients SHOULD be tolerant in parsing the Status-Line and servers
+ tolerant when parsing the Request-Line. In particular, they SHOULD
+ accept any amount of SP or HT characters between fields, even though
+ only a single SP is required.
+
+ The line terminator for message-header fields is the sequence CRLF.
+ However, we recommend that applications, when parsing such headers,
+ recognize a single LF as a line terminator and ignore the leading CR.
+
+ The character set of an entity-body SHOULD be labeled as the lowest
+ common denominator of the character codes used within that body, with
+ the exception that not labeling the entity is preferred over labeling
+ the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1
+ and 3.4.1.
+
+ Additional rules for requirements on parsing and encoding of dates
+ and other potential problems with date encodings include:
+
+ - HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date
+ which appears to be more than 50 years in the future is in fact
+ in the past (this helps solve the "year 2000" problem).
+
+ - An HTTP/1.1 implementation MAY internally represent a parsed
+ Expires date as earlier than the proper value, but MUST NOT
+ internally represent a parsed Expires date as later than the
+ proper value.
+
+ - All expiration-related calculations MUST be done in GMT. The
+ local time zone MUST NOT influence the calculation or comparison
+ of an age or expiration time.
+
+
+
+
+Fielding, et al. Standards Track [Page 166]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - If an HTTP header incorrectly carries a date value with a time
+ zone other than GMT, it MUST be converted into GMT using the
+ most conservative possible conversion.
+
+19.4 Differences Between HTTP Entities and RFC 2045 Entities
+
+ HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC
+ 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to
+ allow entities to be transmitted in an open variety of
+ representations and with extensible mechanisms. However, RFC 2045
+ discusses mail, and HTTP has a few features that are different from
+ those described in RFC 2045. These differences were carefully chosen
+ to optimize performance over binary connections, to allow greater
+ freedom in the use of new media types, to make date comparisons
+ easier, and to acknowledge the practice of some early HTTP servers
+ and clients.
+
+ This appendix describes specific areas where HTTP differs from RFC
+ 2045. Proxies and gateways to strict MIME environments SHOULD be
+ aware of these differences and provide the appropriate conversions
+ where necessary. Proxies and gateways from MIME environments to HTTP
+ also need to be aware of the differences because some conversions
+ might be required.
+
+19.4.1 MIME-Version
+
+ HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY
+ include a single MIME-Version general-header field to indicate what
+ version of the MIME protocol was used to construct the message. Use
+ of the MIME-Version header field indicates that the message is in
+ full compliance with the MIME protocol (as defined in RFC 2045[7]).
+ Proxies/gateways are responsible for ensuring full compliance (where
+ possible) when exporting HTTP messages to strict MIME environments.
+
+ MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT
+
+ MIME version "1.0" is the default for use in HTTP/1.1. However,
+ HTTP/1.1 message parsing and semantics are defined by this document
+ and not the MIME specification.
+
+19.4.2 Conversion to Canonical Form
+
+ RFC 2045 [7] requires that an Internet mail entity be converted to
+ canonical form prior to being transferred, as described in section 4
+ of RFC 2049 [48]. Section 3.7.1 of this document describes the forms
+ allowed for subtypes of the "text" media type when transmitted over
+ HTTP. RFC 2046 requires that content with a type of "text" represent
+ line breaks as CRLF and forbids the use of CR or LF outside of line
+
+
+
+Fielding, et al. Standards Track [Page 167]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a
+ line break within text content when a message is transmitted over
+ HTTP.
+
+ Where it is possible, a proxy or gateway from HTTP to a strict MIME
+ environment SHOULD translate all line breaks within the text media
+ types described in section 3.7.1 of this document to the RFC 2049
+ canonical form of CRLF. Note, however, that this might be complicated
+ by the presence of a Content-Encoding and by the fact that HTTP
+ allows the use of some character sets which do not use octets 13 and
+ 10 to represent CR and LF, as is the case for some multi-byte
+ character sets.
+
+ Implementors should note that conversion will break any cryptographic
+ checksums applied to the original content unless the original content
+ is already in canonical form. Therefore, the canonical form is
+ recommended for any content that uses such checksums in HTTP.
+
+19.4.3 Conversion of Date Formats
+
+ HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to
+ simplify the process of date comparison. Proxies and gateways from
+ other protocols SHOULD ensure that any Date header field present in a
+ message conforms to one of the HTTP/1.1 formats and rewrite the date
+ if necessary.
+
+19.4.4 Introduction of Content-Encoding
+
+ RFC 2045 does not include any concept equivalent to HTTP/1.1's
+ Content-Encoding header field. Since this acts as a modifier on the
+ media type, proxies and gateways from HTTP to MIME-compliant
+ protocols MUST either change the value of the Content-Type header
+ field or decode the entity-body before forwarding the message. (Some
+ experimental applications of Content-Type for Internet mail have used
+ a media-type parameter of ";conversions=<content-coding>" to perform
+ a function equivalent to Content-Encoding. However, this parameter is
+ not part of RFC 2045.)
+
+19.4.5 No Content-Transfer-Encoding
+
+ HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC
+ 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST
+ remove any non-identity CTE ("quoted-printable" or "base64") encoding
+ prior to delivering the response message to an HTTP client.
+
+ Proxies and gateways from HTTP to MIME-compliant protocols are
+ responsible for ensuring that the message is in the correct format
+ and encoding for safe transport on that protocol, where "safe
+
+
+
+Fielding, et al. Standards Track [Page 168]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ transport" is defined by the limitations of the protocol being used.
+ Such a proxy or gateway SHOULD label the data with an appropriate
+ Content-Transfer-Encoding if doing so will improve the likelihood of
+ safe transport over the destination protocol.
+
+19.4.6 Introduction of Transfer-Encoding
+
+ HTTP/1.1 introduces the Transfer-Encoding header field (section
+ 14.41). Proxies/gateways MUST remove any transfer-coding prior to
+ forwarding a message via a MIME-compliant protocol.
+
+ A process for decoding the "chunked" transfer-coding (section 3.6)
+ can be represented in pseudo-code as:
+
+ length := 0
+ read chunk-size, chunk-extension (if any) and CRLF
+ while (chunk-size > 0) {
+ read chunk-data and CRLF
+ append chunk-data to entity-body
+ length := length + chunk-size
+ read chunk-size and CRLF
+ }
+ read entity-header
+ while (entity-header not empty) {
+ append entity-header to existing header fields
+ read entity-header
+ }
+ Content-Length := length
+ Remove "chunked" from Transfer-Encoding
+
+19.4.7 MHTML and Line Length Limitations
+
+ HTTP implementations which share code with MHTML [45] implementations
+ need to be aware of MIME line length limitations. Since HTTP does not
+ have this limitation, HTTP does not fold long lines. MHTML messages
+ being transported by HTTP follow all conventions of MHTML, including
+ line length limitations and folding, canonicalization, etc., since
+ HTTP transports all message-bodies as payload (see section 3.7.2) and
+ does not interpret the content or any MIME header lines that might be
+ contained therein.
+
+19.5 Additional Features
+
+ RFC 1945 and RFC 2068 document protocol elements used by some
+ existing HTTP implementations, but not consistently and correctly
+ across most HTTP/1.1 applications. Implementors are advised to be
+ aware of these features, but cannot rely upon their presence in, or
+ interoperability with, other HTTP/1.1 applications. Some of these
+
+
+
+Fielding, et al. Standards Track [Page 169]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ describe proposed experimental features, and some describe features
+ that experimental deployment found lacking that are now addressed in
+ the base HTTP/1.1 specification.
+
+ A number of other headers, such as Content-Disposition and Title,
+ from SMTP and MIME are also often implemented (see RFC 2076 [37]).
+
+19.5.1 Content-Disposition
+
+ The Content-Disposition response-header field has been proposed as a
+ means for the origin server to suggest a default filename if the user
+ requests that the content is saved to a file. This usage is derived
+ from the definition of Content-Disposition in RFC 1806 [35].
+
+ content-disposition = "Content-Disposition" ":"
+ disposition-type *( ";" disposition-parm )
+ disposition-type = "attachment" | disp-extension-token
+ disposition-parm = filename-parm | disp-extension-parm
+ filename-parm = "filename" "=" quoted-string
+ disp-extension-token = token
+ disp-extension-parm = token "=" ( token | quoted-string )
+
+ An example is
+
+ Content-Disposition: attachment; filename="fname.ext"
+
+ The receiving user agent SHOULD NOT respect any directory path
+ information present in the filename-parm parameter, which is the only
+ parameter believed to apply to HTTP implementations at this time. The
+ filename SHOULD be treated as a terminal component only.
+
+ If this header is used in a response with the application/octet-
+ stream content-type, the implied suggestion is that the user agent
+ should not display the response, but directly enter a `save response
+ as...' dialog.
+
+ See section 15.5 for Content-Disposition security issues.
+
+19.6 Compatibility with Previous Versions
+
+ It is beyond the scope of a protocol specification to mandate
+ compliance with previous versions. HTTP/1.1 was deliberately
+ designed, however, to make supporting previous versions easy. It is
+ worth noting that, at the time of composing this specification
+ (1996), we would expect commercial HTTP/1.1 servers to:
+
+ - recognize the format of the Request-Line for HTTP/0.9, 1.0, and
+ 1.1 requests;
+
+
+
+Fielding, et al. Standards Track [Page 170]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ - understand any valid request in the format of HTTP/0.9, 1.0, or
+ 1.1;
+
+ - respond appropriately with a message in the same major version
+ used by the client.
+
+ And we would expect HTTP/1.1 clients to:
+
+ - recognize the format of the Status-Line for HTTP/1.0 and 1.1
+ responses;
+
+ - understand any valid response in the format of HTTP/0.9, 1.0, or
+ 1.1.
+
+ For most implementations of HTTP/1.0, each connection is established
+ by the client prior to the request and closed by the server after
+ sending the response. Some implementations implement the Keep-Alive
+ version of persistent connections described in section 19.7.1 of RFC
+ 2068 [33].
+
+19.6.1 Changes from HTTP/1.0
+
+ This section summarizes major differences between versions HTTP/1.0
+ and HTTP/1.1.
+
+19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP
+ Addresses
+
+ The requirements that clients and servers support the Host request-
+ header, report an error if the Host request-header (section 14.23) is
+ missing from an HTTP/1.1 request, and accept absolute URIs (section
+ 5.1.2) are among the most important changes defined by this
+ specification.
+
+ Older HTTP/1.0 clients assumed a one-to-one relationship of IP
+ addresses and servers; there was no other established mechanism for
+ distinguishing the intended server of a request than the IP address
+ to which that request was directed. The changes outlined above will
+ allow the Internet, once older HTTP clients are no longer common, to
+ support multiple Web sites from a single IP address, greatly
+ simplifying large operational Web servers, where allocation of many
+ IP addresses to a single host has created serious problems. The
+ Internet will also be able to recover the IP addresses that have been
+ allocated for the sole purpose of allowing special-purpose domain
+ names to be used in root-level HTTP URLs. Given the rate of growth of
+ the Web, and the number of servers already deployed, it is extremely
+
+
+
+
+
+Fielding, et al. Standards Track [Page 171]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ important that all implementations of HTTP (including updates to
+ existing HTTP/1.0 applications) correctly implement these
+ requirements:
+
+ - Both clients and servers MUST support the Host request-header.
+
+ - A client that sends an HTTP/1.1 request MUST send a Host header.
+
+ - Servers MUST report a 400 (Bad Request) error if an HTTP/1.1
+ request does not include a Host request-header.
+
+ - Servers MUST accept absolute URIs.
+
+19.6.2 Compatibility with HTTP/1.0 Persistent Connections
+
+ Some clients and servers might wish to be compatible with some
+ previous implementations of persistent connections in HTTP/1.0
+ clients and servers. Persistent connections in HTTP/1.0 are
+ explicitly negotiated as they are not the default behavior. HTTP/1.0
+ experimental implementations of persistent connections are faulty,
+ and the new facilities in HTTP/1.1 are designed to rectify these
+ problems. The problem was that some existing 1.0 clients may be
+ sending Keep-Alive to a proxy server that doesn't understand
+ Connection, which would then erroneously forward it to the next
+ inbound server, which would establish the Keep-Alive connection and
+ result in a hung HTTP/1.0 proxy waiting for the close on the
+ response. The result is that HTTP/1.0 clients must be prevented from
+ using Keep-Alive when talking to proxies.
+
+ However, talking to proxies is the most important use of persistent
+ connections, so that prohibition is clearly unacceptable. Therefore,
+ we need some other mechanism for indicating a persistent connection
+ is desired, which is safe to use even when talking to an old proxy
+ that ignores Connection. Persistent connections are the default for
+ HTTP/1.1 messages; we introduce a new keyword (Connection: close) for
+ declaring non-persistence. See section 14.10.
+
+ The original HTTP/1.0 form of persistent connections (the Connection:
+ Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33]
+
+19.6.3 Changes from RFC 2068
+
+ This specification has been carefully audited to correct and
+ disambiguate key word usage; RFC 2068 had many problems in respect to
+ the conventions laid out in RFC 2119 [34].
+
+ Clarified which error code should be used for inbound server failures
+ (e.g. DNS failures). (Section 10.5.5).
+
+
+
+Fielding, et al. Standards Track [Page 172]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ CREATE had a race that required an Etag be sent when a resource is
+ first created. (Section 10.2.2).
+
+ Content-Base was deleted from the specification: it was not
+ implemented widely, and there is no simple, safe way to introduce it
+ without a robust extension mechanism. In addition, it is used in a
+ similar, but not identical fashion in MHTML [45].
+
+ Transfer-coding and message lengths all interact in ways that
+ required fixing exactly when chunked encoding is used (to allow for
+ transfer encoding that may not be self delimiting); it was important
+ to straighten out exactly how message lengths are computed. (Sections
+ 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16)
+
+ A content-coding of "identity" was introduced, to solve problems
+ discovered in caching. (section 3.5)
+
+ Quality Values of zero should indicate that "I don't want something"
+ to allow clients to refuse a representation. (Section 3.9)
+
+ The use and interpretation of HTTP version numbers has been clarified
+ by RFC 2145. Require proxies to upgrade requests to highest protocol
+ version they support to deal with problems discovered in HTTP/1.0
+ implementations (Section 3.1)
+
+ Charset wildcarding is introduced to avoid explosion of character set
+ names in accept headers. (Section 14.2)
+
+ A case was missed in the Cache-Control model of HTTP/1.1; s-maxage
+ was introduced to add this missing case. (Sections 13.4, 14.8, 14.9,
+ 14.9.3)
+
+ The Cache-Control: max-age directive was not properly defined for
+ responses. (Section 14.9.3)
+
+ There are situations where a server (especially a proxy) does not
+ know the full length of a response but is capable of serving a
+ byterange request. We therefore need a mechanism to allow byteranges
+ with a content-range not indicating the full length of the message.
+ (Section 14.16)
+
+ Range request responses would become very verbose if all meta-data
+ were always returned; by allowing the server to only send needed
+ headers in a 206 response, this problem can be avoided. (Section
+ 10.2.7, 13.5.3, and 14.27)
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 173]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Fix problem with unsatisfiable range requests; there are two cases:
+ syntactic problems, and range doesn't exist in the document. The 416
+ status code was needed to resolve this ambiguity needed to indicate
+ an error for a byte range request that falls outside of the actual
+ contents of a document. (Section 10.4.17, 14.16)
+
+ Rewrite of message transmission requirements to make it much harder
+ for implementors to get it wrong, as the consequences of errors here
+ can have significant impact on the Internet, and to deal with the
+ following problems:
+
+ 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where
+ this was incorrectly placing a requirement on the behavior of
+ an implementation of a future version of HTTP/1.x
+
+ 2. Made it clear that user-agents should retry requests, not
+ "clients" in general.
+
+ 3. Converted requirements for clients to ignore unexpected 100
+ (Continue) responses, and for proxies to forward 100 responses,
+ into a general requirement for 1xx responses.
+
+ 4. Modified some TCP-specific language, to make it clearer that
+ non-TCP transports are possible for HTTP.
+
+ 5. Require that the origin server MUST NOT wait for the request
+ body before it sends a required 100 (Continue) response.
+
+ 6. Allow, rather than require, a server to omit 100 (Continue) if
+ it has already seen some of the request body.
+
+ 7. Allow servers to defend against denial-of-service attacks and
+ broken clients.
+
+ This change adds the Expect header and 417 status code. The message
+ transmission requirements fixes are in sections 8.2, 10.4.18,
+ 8.1.2.2, 13.11, and 14.20.
+
+ Proxies should be able to add Content-Length when appropriate.
+ (Section 13.5.2)
+
+ Clean up confusion between 403 and 404 responses. (Section 10.4.4,
+ 10.4.5, and 10.4.11)
+
+ Warnings could be cached incorrectly, or not updated appropriately.
+ (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning
+ also needed to be a general header, as PUT or other methods may have
+ need for it in requests.
+
+
+
+Fielding, et al. Standards Track [Page 174]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+ Transfer-coding had significant problems, particularly with
+ interactions with chunked encoding. The solution is that transfer-
+ codings become as full fledged as content-codings. This involves
+ adding an IANA registry for transfer-codings (separate from content
+ codings), a new header field (TE) and enabling trailer headers in the
+ future. Transfer encoding is a major performance benefit, so it was
+ worth fixing [39]. TE also solves another, obscure, downward
+ interoperability problem that could have occurred due to interactions
+ between authentication trailers, chunked encoding and HTTP/1.0
+ clients.(Section 3.6, 3.6.1, and 14.39)
+
+ The PATCH, LINK, UNLINK methods were defined but not commonly
+ implemented in previous versions of this specification. See RFC 2068
+ [33].
+
+ The Alternates, Content-Version, Derived-From, Link, URI, Public and
+ Content-Base header fields were defined in previous versions of this
+ specification, but not commonly implemented. See RFC 2068 [33].
+
+20 Index
+
+ Please see the PostScript version of this RFC for the INDEX.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 175]
+
+RFC 2616 HTTP/1.1 June 1999
+
+
+21. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Fielding, et al. Standards Track [Page 176]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2616.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2616.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2616.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,9859 +0,0 @@
-
-
-
-
-
-
-Network Working Group R. Fielding
-Request for Comments: 2616 UC Irvine
-Obsoletes: 2068 J. Gettys
-Category: Standards Track Compaq/W3C
- J. Mogul
- Compaq
- H. Frystyk
- W3C/MIT
- L. Masinter
- Xerox
- P. Leach
- Microsoft
- T. Berners-Lee
- W3C/MIT
- June 1999
-
-
- Hypertext Transfer Protocol -- HTTP/1.1
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol for distributed, collaborative, hypermedia information
- systems. It is a generic, stateless, protocol which can be used for
- many tasks beyond its use for hypertext, such as name servers and
- distributed object management systems, through extension of its
- request methods, error codes and headers [47]. A feature of HTTP is
- the typing and negotiation of data representation, allowing systems
- to be built independently of the data being transferred.
-
- HTTP has been in use by the World-Wide Web global information
- initiative since 1990. This specification defines the protocol
- referred to as "HTTP/1.1", and is an update to RFC 2068 [33].
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 1]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-Table of Contents
-
- 1 Introduction ...................................................7
- 1.1 Purpose......................................................7
- 1.2 Requirements .................................................8
- 1.3 Terminology ..................................................8
- 1.4 Overall Operation ...........................................12
- 2 Notational Conventions and Generic Grammar ....................14
- 2.1 Augmented BNF ...............................................14
- 2.2 Basic Rules .................................................15
- 3 Protocol Parameters ...........................................17
- 3.1 HTTP Version ................................................17
- 3.2 Uniform Resource Identifiers ................................18
- 3.2.1 General Syntax ...........................................19
- 3.2.2 http URL .................................................19
- 3.2.3 URI Comparison ...........................................20
- 3.3 Date/Time Formats ...........................................20
- 3.3.1 Full Date ................................................20
- 3.3.2 Delta Seconds ............................................21
- 3.4 Character Sets ..............................................21
- 3.4.1 Missing Charset ..........................................22
- 3.5 Content Codings .............................................23
- 3.6 Transfer Codings ............................................24
- 3.6.1 Chunked Transfer Coding ..................................25
- 3.7 Media Types .................................................26
- 3.7.1 Canonicalization and Text Defaults .......................27
- 3.7.2 Multipart Types ..........................................27
- 3.8 Product Tokens ..............................................28
- 3.9 Quality Values ..............................................29
- 3.10 Language Tags ...............................................29
- 3.11 Entity Tags .................................................30
- 3.12 Range Units .................................................30
- 4 HTTP Message ..................................................31
- 4.1 Message Types ...............................................31
- 4.2 Message Headers .............................................31
- 4.3 Message Body ................................................32
- 4.4 Message Length ..............................................33
- 4.5 General Header Fields .......................................34
- 5 Request .......................................................35
- 5.1 Request-Line ................................................35
- 5.1.1 Method ...................................................36
- 5.1.2 Request-URI ..............................................36
- 5.2 The Resource Identified by a Request ........................38
- 5.3 Request Header Fields .......................................38
- 6 Response ......................................................39
- 6.1 Status-Line .................................................39
- 6.1.1 Status Code and Reason Phrase ............................39
- 6.2 Response Header Fields ......................................41
-
-
-
-Fielding, et al. Standards Track [Page 2]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 7 Entity ........................................................42
- 7.1 Entity Header Fields ........................................42
- 7.2 Entity Body .................................................43
- 7.2.1 Type .....................................................43
- 7.2.2 Entity Length ............................................43
- 8 Connections ...................................................44
- 8.1 Persistent Connections ......................................44
- 8.1.1 Purpose ..................................................44
- 8.1.2 Overall Operation ........................................45
- 8.1.3 Proxy Servers ............................................46
- 8.1.4 Practical Considerations .................................46
- 8.2 Message Transmission Requirements ...........................47
- 8.2.1 Persistent Connections and Flow Control ..................47
- 8.2.2 Monitoring Connections for Error Status Messages .........48
- 8.2.3 Use of the 100 (Continue) Status .........................48
- 8.2.4 Client Behavior if Server Prematurely Closes Connection ..50
- 9 Method Definitions ............................................51
- 9.1 Safe and Idempotent Methods .................................51
- 9.1.1 Safe Methods .............................................51
- 9.1.2 Idempotent Methods .......................................51
- 9.2 OPTIONS .....................................................52
- 9.3 GET .........................................................53
- 9.4 HEAD ........................................................54
- 9.5 POST ........................................................54
- 9.6 PUT .........................................................55
- 9.7 DELETE ......................................................56
- 9.8 TRACE .......................................................56
- 9.9 CONNECT .....................................................57
- 10 Status Code Definitions ......................................57
- 10.1 Informational 1xx ...........................................57
- 10.1.1 100 Continue .............................................58
- 10.1.2 101 Switching Protocols ..................................58
- 10.2 Successful 2xx ..............................................58
- 10.2.1 200 OK ...................................................58
- 10.2.2 201 Created ..............................................59
- 10.2.3 202 Accepted .............................................59
- 10.2.4 203 Non-Authoritative Information ........................59
- 10.2.5 204 No Content ...........................................60
- 10.2.6 205 Reset Content ........................................60
- 10.2.7 206 Partial Content ......................................60
- 10.3 Redirection 3xx .............................................61
- 10.3.1 300 Multiple Choices .....................................61
- 10.3.2 301 Moved Permanently ....................................62
- 10.3.3 302 Found ................................................62
- 10.3.4 303 See Other ............................................63
- 10.3.5 304 Not Modified .........................................63
- 10.3.6 305 Use Proxy ............................................64
- 10.3.7 306 (Unused) .............................................64
-
-
-
-Fielding, et al. Standards Track [Page 3]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 10.3.8 307 Temporary Redirect ...................................65
- 10.4 Client Error 4xx ............................................65
- 10.4.1 400 Bad Request .........................................65
- 10.4.2 401 Unauthorized ........................................66
- 10.4.3 402 Payment Required ....................................66
- 10.4.4 403 Forbidden ...........................................66
- 10.4.5 404 Not Found ...........................................66
- 10.4.6 405 Method Not Allowed ..................................66
- 10.4.7 406 Not Acceptable ......................................67
- 10.4.8 407 Proxy Authentication Required .......................67
- 10.4.9 408 Request Timeout .....................................67
- 10.4.10 409 Conflict ............................................67
- 10.4.11 410 Gone ................................................68
- 10.4.12 411 Length Required .....................................68
- 10.4.13 412 Precondition Failed .................................68
- 10.4.14 413 Request Entity Too Large ............................69
- 10.4.15 414 Request-URI Too Long ................................69
- 10.4.16 415 Unsupported Media Type ..............................69
- 10.4.17 416 Requested Range Not Satisfiable .....................69
- 10.4.18 417 Expectation Failed ..................................70
- 10.5 Server Error 5xx ............................................70
- 10.5.1 500 Internal Server Error ................................70
- 10.5.2 501 Not Implemented ......................................70
- 10.5.3 502 Bad Gateway ..........................................70
- 10.5.4 503 Service Unavailable ..................................70
- 10.5.5 504 Gateway Timeout ......................................71
- 10.5.6 505 HTTP Version Not Supported ...........................71
- 11 Access Authentication ........................................71
- 12 Content Negotiation ..........................................71
- 12.1 Server-driven Negotiation ...................................72
- 12.2 Agent-driven Negotiation ....................................73
- 12.3 Transparent Negotiation .....................................74
- 13 Caching in HTTP ..............................................74
- 13.1.1 Cache Correctness ........................................75
- 13.1.2 Warnings .................................................76
- 13.1.3 Cache-control Mechanisms .................................77
- 13.1.4 Explicit User Agent Warnings .............................78
- 13.1.5 Exceptions to the Rules and Warnings .....................78
- 13.1.6 Client-controlled Behavior ...............................79
- 13.2 Expiration Model ............................................79
- 13.2.1 Server-Specified Expiration ..............................79
- 13.2.2 Heuristic Expiration .....................................80
- 13.2.3 Age Calculations .........................................80
- 13.2.4 Expiration Calculations ..................................83
- 13.2.5 Disambiguating Expiration Values .........................84
- 13.2.6 Disambiguating Multiple Responses ........................84
- 13.3 Validation Model ............................................85
- 13.3.1 Last-Modified Dates ......................................86
-
-
-
-Fielding, et al. Standards Track [Page 4]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 13.3.2 Entity Tag Cache Validators ..............................86
- 13.3.3 Weak and Strong Validators ...............................86
- 13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates.89
- 13.3.5 Non-validating Conditionals ..............................90
- 13.4 Response Cacheability .......................................91
- 13.5 Constructing Responses From Caches ..........................92
- 13.5.1 End-to-end and Hop-by-hop Headers ........................92
- 13.5.2 Non-modifiable Headers ...................................92
- 13.5.3 Combining Headers ........................................94
- 13.5.4 Combining Byte Ranges ....................................95
- 13.6 Caching Negotiated Responses ................................95
- 13.7 Shared and Non-Shared Caches ................................96
- 13.8 Errors or Incomplete Response Cache Behavior ................97
- 13.9 Side Effects of GET and HEAD ................................97
- 13.10 Invalidation After Updates or Deletions ...................97
- 13.11 Write-Through Mandatory ...................................98
- 13.12 Cache Replacement .........................................99
- 13.13 History Lists .............................................99
- 14 Header Field Definitions ....................................100
- 14.1 Accept .....................................................100
- 14.2 Accept-Charset .............................................102
- 14.3 Accept-Encoding ............................................102
- 14.4 Accept-Language ............................................104
- 14.5 Accept-Ranges ..............................................105
- 14.6 Age ........................................................106
- 14.7 Allow ......................................................106
- 14.8 Authorization ..............................................107
- 14.9 Cache-Control ..............................................108
- 14.9.1 What is Cacheable .......................................109
- 14.9.2 What May be Stored by Caches ............................110
- 14.9.3 Modifications of the Basic Expiration Mechanism .........111
- 14.9.4 Cache Revalidation and Reload Controls ..................113
- 14.9.5 No-Transform Directive ..................................115
- 14.9.6 Cache Control Extensions ................................116
- 14.10 Connection ...............................................117
- 14.11 Content-Encoding .........................................118
- 14.12 Content-Language .........................................118
- 14.13 Content-Length ...........................................119
- 14.14 Content-Location .........................................120
- 14.15 Content-MD5 ..............................................121
- 14.16 Content-Range ............................................122
- 14.17 Content-Type .............................................124
- 14.18 Date .....................................................124
- 14.18.1 Clockless Origin Server Operation ......................125
- 14.19 ETag .....................................................126
- 14.20 Expect ...................................................126
- 14.21 Expires ..................................................127
- 14.22 From .....................................................128
-
-
-
-Fielding, et al. Standards Track [Page 5]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 14.23 Host .....................................................128
- 14.24 If-Match .................................................129
- 14.25 If-Modified-Since ........................................130
- 14.26 If-None-Match ............................................132
- 14.27 If-Range .................................................133
- 14.28 If-Unmodified-Since ......................................134
- 14.29 Last-Modified ............................................134
- 14.30 Location .................................................135
- 14.31 Max-Forwards .............................................136
- 14.32 Pragma ...................................................136
- 14.33 Proxy-Authenticate .......................................137
- 14.34 Proxy-Authorization ......................................137
- 14.35 Range ....................................................138
- 14.35.1 Byte Ranges ...........................................138
- 14.35.2 Range Retrieval Requests ..............................139
- 14.36 Referer ..................................................140
- 14.37 Retry-After ..............................................141
- 14.38 Server ...................................................141
- 14.39 TE .......................................................142
- 14.40 Trailer ..................................................143
- 14.41 Transfer-Encoding..........................................143
- 14.42 Upgrade ..................................................144
- 14.43 User-Agent ...............................................145
- 14.44 Vary .....................................................145
- 14.45 Via ......................................................146
- 14.46 Warning ..................................................148
- 14.47 WWW-Authenticate .........................................150
- 15 Security Considerations .......................................150
- 15.1 Personal Information....................................151
- 15.1.1 Abuse of Server Log Information .........................151
- 15.1.2 Transfer of Sensitive Information .......................151
- 15.1.3 Encoding Sensitive Information in URI's .................152
- 15.1.4 Privacy Issues Connected to Accept Headers ..............152
- 15.2 Attacks Based On File and Path Names .......................153
- 15.3 DNS Spoofing ...............................................154
- 15.4 Location Headers and Spoofing ..............................154
- 15.5 Content-Disposition Issues .................................154
- 15.6 Authentication Credentials and Idle Clients ................155
- 15.7 Proxies and Caching ........................................155
- 15.7.1 Denial of Service Attacks on Proxies....................156
- 16 Acknowledgments .............................................156
- 17 References ..................................................158
- 18 Authors' Addresses ..........................................162
- 19 Appendices ..................................................164
- 19.1 Internet Media Type message/http and application/http ......164
- 19.2 Internet Media Type multipart/byteranges ...................165
- 19.3 Tolerant Applications ......................................166
- 19.4 Differences Between HTTP Entities and RFC 2045 Entities ....167
-
-
-
-Fielding, et al. Standards Track [Page 6]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 19.4.1 MIME-Version ............................................167
- 19.4.2 Conversion to Canonical Form ............................167
- 19.4.3 Conversion of Date Formats ..............................168
- 19.4.4 Introduction of Content-Encoding ........................168
- 19.4.5 No Content-Transfer-Encoding ............................168
- 19.4.6 Introduction of Transfer-Encoding .......................169
- 19.4.7 MHTML and Line Length Limitations .......................169
- 19.5 Additional Features ........................................169
- 19.5.1 Content-Disposition .....................................170
- 19.6 Compatibility with Previous Versions .......................170
- 19.6.1 Changes from HTTP/1.0 ...................................171
- 19.6.2 Compatibility with HTTP/1.0 Persistent Connections ......172
- 19.6.3 Changes from RFC 2068 ...................................172
- 20 Index .......................................................175
- 21 Full Copyright Statement ....................................176
-
-1 Introduction
-
-1.1 Purpose
-
- The Hypertext Transfer Protocol (HTTP) is an application-level
- protocol for distributed, collaborative, hypermedia information
- systems. HTTP has been in use by the World-Wide Web global
- information initiative since 1990. The first version of HTTP,
- referred to as HTTP/0.9, was a simple protocol for raw data transfer
- across the Internet. HTTP/1.0, as defined by RFC 1945 [6], improved
- the protocol by allowing messages to be in the format of MIME-like
- messages, containing metainformation about the data transferred and
- modifiers on the request/response semantics. However, HTTP/1.0 does
- not sufficiently take into consideration the effects of hierarchical
- proxies, caching, the need for persistent connections, or virtual
- hosts. In addition, the proliferation of incompletely-implemented
- applications calling themselves "HTTP/1.0" has necessitated a
- protocol version change in order for two communicating applications
- to determine each other's true capabilities.
-
- This specification defines the protocol referred to as "HTTP/1.1".
- This protocol includes more stringent requirements than HTTP/1.0 in
- order to ensure reliable implementation of its features.
-
- Practical information systems require more functionality than simple
- retrieval, including search, front-end update, and annotation. HTTP
- allows an open-ended set of methods and headers that indicate the
- purpose of a request [47]. It builds on the discipline of reference
- provided by the Uniform Resource Identifier (URI) [3], as a location
- (URL) [4] or name (URN) [20], for indicating the resource to which a
-
-
-
-
-
-Fielding, et al. Standards Track [Page 7]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- method is to be applied. Messages are passed in a format similar to
- that used by Internet mail [9] as defined by the Multipurpose
- Internet Mail Extensions (MIME) [7].
-
- HTTP is also used as a generic protocol for communication between
- user agents and proxies/gateways to other Internet systems, including
- those supported by the SMTP [16], NNTP [13], FTP [18], Gopher [2],
- and WAIS [10] protocols. In this way, HTTP allows basic hypermedia
- access to resources available from diverse applications.
-
-1.2 Requirements
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119 [34].
-
- An implementation is not compliant if it fails to satisfy one or more
- of the MUST or REQUIRED level requirements for the protocols it
- implements. An implementation that satisfies all the MUST or REQUIRED
- level and all the SHOULD level requirements for its protocols is said
- to be "unconditionally compliant"; one that satisfies all the MUST
- level requirements but not all the SHOULD level requirements for its
- protocols is said to be "conditionally compliant."
-
-1.3 Terminology
-
- This specification uses a number of terms to refer to the roles
- played by participants in, and objects of, the HTTP communication.
-
- connection
- A transport layer virtual circuit established between two programs
- for the purpose of communication.
-
- message
- The basic unit of HTTP communication, consisting of a structured
- sequence of octets matching the syntax defined in section 4 and
- transmitted via the connection.
-
- request
- An HTTP request message, as defined in section 5.
-
- response
- An HTTP response message, as defined in section 6.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 8]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- resource
- A network data object or service that can be identified by a URI,
- as defined in section 3.2. Resources may be available in multiple
- representations (e.g. multiple languages, data formats, size, and
- resolutions) or vary in other ways.
-
- entity
- The information transferred as the payload of a request or
- response. An entity consists of metainformation in the form of
- entity-header fields and content in the form of an entity-body, as
- described in section 7.
-
- representation
- An entity included with a response that is subject to content
- negotiation, as described in section 12. There may exist multiple
- representations associated with a particular response status.
-
- content negotiation
- The mechanism for selecting the appropriate representation when
- servicing a request, as described in section 12. The
- representation of entities in any response can be negotiated
- (including error responses).
-
- variant
- A resource may have one, or more than one, representation(s)
- associated with it at any given instant. Each of these
- representations is termed a `varriant'. Use of the term `variant'
- does not necessarily imply that the resource is subject to content
- negotiation.
-
- client
- A program that establishes connections for the purpose of sending
- requests.
-
- user agent
- The client which initiates a request. These are often browsers,
- editors, spiders (web-traversing robots), or other end user tools.
-
- server
- An application program that accepts connections in order to
- service requests by sending back responses. Any given program may
- be capable of being both a client and a server; our use of these
- terms refers only to the role being performed by the program for a
- particular connection, rather than to the program's capabilities
- in general. Likewise, any server may act as an origin server,
- proxy, gateway, or tunnel, switching behavior based on the nature
- of each request.
-
-
-
-
-Fielding, et al. Standards Track [Page 9]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- origin server
- The server on which a given resource resides or is to be created.
-
- proxy
- An intermediary program which acts as both a server and a client
- for the purpose of making requests on behalf of other clients.
- Requests are serviced internally or by passing them on, with
- possible translation, to other servers. A proxy MUST implement
- both the client and server requirements of this specification. A
- "transparent proxy" is a proxy that does not modify the request or
- response beyond what is required for proxy authentication and
- identification. A "non-transparent proxy" is a proxy that modifies
- the request or response in order to provide some added service to
- the user agent, such as group annotation services, media type
- transformation, protocol reduction, or anonymity filtering. Except
- where either transparent or non-transparent behavior is explicitly
- stated, the HTTP proxy requirements apply to both types of
- proxies.
-
- gateway
- A server which acts as an intermediary for some other server.
- Unlike a proxy, a gateway receives requests as if it were the
- origin server for the requested resource; the requesting client
- may not be aware that it is communicating with a gateway.
-
- tunnel
- An intermediary program which is acting as a blind relay between
- two connections. Once active, a tunnel is not considered a party
- to the HTTP communication, though the tunnel may have been
- initiated by an HTTP request. The tunnel ceases to exist when both
- ends of the relayed connections are closed.
-
- cache
- A program's local store of response messages and the subsystem
- that controls its message storage, retrieval, and deletion. A
- cache stores cacheable responses in order to reduce the response
- time and network bandwidth consumption on future, equivalent
- requests. Any client or server may include a cache, though a cache
- cannot be used by a server that is acting as a tunnel.
-
- cacheable
- A response is cacheable if a cache is allowed to store a copy of
- the response message for use in answering subsequent requests. The
- rules for determining the cacheability of HTTP responses are
- defined in section 13. Even if a resource is cacheable, there may
- be additional constraints on whether a cache can use the cached
- copy for a particular request.
-
-
-
-
-Fielding, et al. Standards Track [Page 10]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- first-hand
- A response is first-hand if it comes directly and without
- unnecessary delay from the origin server, perhaps via one or more
- proxies. A response is also first-hand if its validity has just
- been checked directly with the origin server.
-
- explicit expiration time
- The time at which the origin server intends that an entity should
- no longer be returned by a cache without further validation.
-
- heuristic expiration time
- An expiration time assigned by a cache when no explicit expiration
- time is available.
-
- age
- The age of a response is the time since it was sent by, or
- successfully validated with, the origin server.
-
- freshness lifetime
- The length of time between the generation of a response and its
- expiration time.
-
- fresh
- A response is fresh if its age has not yet exceeded its freshness
- lifetime.
-
- stale
- A response is stale if its age has passed its freshness lifetime.
-
- semantically transparent
- A cache behaves in a "semantically transparent" manner, with
- respect to a particular response, when its use affects neither the
- requesting client nor the origin server, except to improve
- performance. When a cache is semantically transparent, the client
- receives exactly the same response (except for hop-by-hop headers)
- that it would have received had its request been handled directly
- by the origin server.
-
- validator
- A protocol element (e.g., an entity tag or a Last-Modified time)
- that is used to find out whether a cache entry is an equivalent
- copy of an entity.
-
- upstream/downstream
- Upstream and downstream describe the flow of a message: all
- messages flow from upstream to downstream.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 11]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- inbound/outbound
- Inbound and outbound refer to the request and response paths for
- messages: "inbound" means "traveling toward the origin server",
- and "outbound" means "traveling toward the user agent"
-
-1.4 Overall Operation
-
- The HTTP protocol is a request/response protocol. A client sends a
- request to the server in the form of a request method, URI, and
- protocol version, followed by a MIME-like message containing request
- modifiers, client information, and possible body content over a
- connection with a server. The server responds with a status line,
- including the message's protocol version and a success or error code,
- followed by a MIME-like message containing server information, entity
- metainformation, and possible entity-body content. The relationship
- between HTTP and MIME is described in appendix 19.4.
-
- Most HTTP communication is initiated by a user agent and consists of
- a request to be applied to a resource on some origin server. In the
- simplest case, this may be accomplished via a single connection (v)
- between the user agent (UA) and the origin server (O).
-
- request chain ------------------------>
- UA -------------------v------------------- O
- <----------------------- response chain
-
- A more complicated situation occurs when one or more intermediaries
- are present in the request/response chain. There are three common
- forms of intermediary: proxy, gateway, and tunnel. A proxy is a
- forwarding agent, receiving requests for a URI in its absolute form,
- rewriting all or part of the message, and forwarding the reformatted
- request toward the server identified by the URI. A gateway is a
- receiving agent, acting as a layer above some other server(s) and, if
- necessary, translating the requests to the underlying server's
- protocol. A tunnel acts as a relay point between two connections
- without changing the messages; tunnels are used when the
- communication needs to pass through an intermediary (such as a
- firewall) even when the intermediary cannot understand the contents
- of the messages.
-
- request chain -------------------------------------->
- UA -----v----- A -----v----- B -----v----- C -----v----- O
- <------------------------------------- response chain
-
- The figure above shows three intermediaries (A, B, and C) between the
- user agent and origin server. A request or response message that
- travels the whole chain will pass through four separate connections.
- This distinction is important because some HTTP communication options
-
-
-
-Fielding, et al. Standards Track [Page 12]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- may apply only to the connection with the nearest, non-tunnel
- neighbor, only to the end-points of the chain, or to all connections
- along the chain. Although the diagram is linear, each participant may
- be engaged in multiple, simultaneous communications. For example, B
- may be receiving requests from many clients other than A, and/or
- forwarding requests to servers other than C, at the same time that it
- is handling A's request.
-
- Any party to the communication which is not acting as a tunnel may
- employ an internal cache for handling requests. The effect of a cache
- is that the request/response chain is shortened if one of the
- participants along the chain has a cached response applicable to that
- request. The following illustrates the resulting chain if B has a
- cached copy of an earlier response from O (via C) for a request which
- has not been cached by UA or A.
-
- request chain ---------->
- UA -----v----- A -----v----- B - - - - - - C - - - - - - O
- <--------- response chain
-
- Not all responses are usefully cacheable, and some requests may
- contain modifiers which place special requirements on cache behavior.
- HTTP requirements for cache behavior and cacheable responses are
- defined in section 13.
-
- In fact, there are a wide variety of architectures and configurations
- of caches and proxies currently being experimented with or deployed
- across the World Wide Web. These systems include national hierarchies
- of proxy caches to save transoceanic bandwidth, systems that
- broadcast or multicast cache entries, organizations that distribute
- subsets of cached data via CD-ROM, and so on. HTTP systems are used
- in corporate intranets over high-bandwidth links, and for access via
- PDAs with low-power radio links and intermittent connectivity. The
- goal of HTTP/1.1 is to support the wide diversity of configurations
- already deployed while introducing protocol constructs that meet the
- needs of those who build web applications that require high
- reliability and, failing that, at least reliable indications of
- failure.
-
- HTTP communication usually takes place over TCP/IP connections. The
- default port is TCP 80 [19], but other ports can be used. This does
- not preclude HTTP from being implemented on top of any other protocol
- on the Internet, or on other networks. HTTP only presumes a reliable
- transport; any protocol that provides such guarantees can be used;
- the mapping of the HTTP/1.1 request and response structures onto the
- transport data units of the protocol in question is outside the scope
- of this specification.
-
-
-
-
-Fielding, et al. Standards Track [Page 13]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- In HTTP/1.0, most implementations used a new connection for each
- request/response exchange. In HTTP/1.1, a connection may be used for
- one or more request/response exchanges, although connections may be
- closed for a variety of reasons (see section 8.1).
-
-2 Notational Conventions and Generic Grammar
-
-2.1 Augmented BNF
-
- All of the mechanisms specified in this document are described in
- both prose and an augmented Backus-Naur Form (BNF) similar to that
- used by RFC 822 [9]. Implementors will need to be familiar with the
- notation in order to understand this specification. The augmented BNF
- includes the following constructs:
-
- name = definition
- The name of a rule is simply the name itself (without any
- enclosing "<" and ">") and is separated from its definition by the
- equal "=" character. White space is only significant in that
- indentation of continuation lines is used to indicate a rule
- definition that spans more than one line. Certain basic rules are
- in uppercase, such as SP, LWS, HT, CRLF, DIGIT, ALPHA, etc. Angle
- brackets are used within definitions whenever their presence will
- facilitate discerning the use of rule names.
-
- "literal"
- Quotation marks surround literal text. Unless stated otherwise,
- the text is case-insensitive.
-
- rule1 | rule2
- Elements separated by a bar ("|") are alternatives, e.g., "yes |
- no" will accept yes or no.
-
- (rule1 rule2)
- Elements enclosed in parentheses are treated as a single element.
- Thus, "(elem (foo | bar) elem)" allows the token sequences "elem
- foo elem" and "elem bar elem".
-
- *rule
- The character "*" preceding an element indicates repetition. The
- full form is "<n>*<m>element" indicating at least <n> and at most
- <m> occurrences of element. Default values are 0 and infinity so
- that "*(element)" allows any number, including zero; "1*element"
- requires at least one; and "1*2element" allows one or two.
-
- [rule]
- Square brackets enclose optional elements; "[foo bar]" is
- equivalent to "*1(foo bar)".
-
-
-
-Fielding, et al. Standards Track [Page 14]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- N rule
- Specific repetition: "<n>(element)" is equivalent to
- "<n>*<n>(element)"; that is, exactly <n> occurrences of (element).
- Thus 2DIGIT is a 2-digit number, and 3ALPHA is a string of three
- alphabetic characters.
-
- #rule
- A construct "#" is defined, similar to "*", for defining lists of
- elements. The full form is "<n>#<m>element" indicating at least
- <n> and at most <m> elements, each separated by one or more commas
- (",") and OPTIONAL linear white space (LWS). This makes the usual
- form of lists very easy; a rule such as
- ( *LWS element *( *LWS "," *LWS element ))
- can be shown as
- 1#element
- Wherever this construct is used, null elements are allowed, but do
- not contribute to the count of elements present. That is,
- "(element), , (element) " is permitted, but counts as only two
- elements. Therefore, where at least one element is required, at
- least one non-null element MUST be present. Default values are 0
- and infinity so that "#element" allows any number, including zero;
- "1#element" requires at least one; and "1#2element" allows one or
- two.
-
- ; comment
- A semi-colon, set off some distance to the right of rule text,
- starts a comment that continues to the end of line. This is a
- simple way of including useful notes in parallel with the
- specifications.
-
- implied *LWS
- The grammar described by this specification is word-based. Except
- where noted otherwise, linear white space (LWS) can be included
- between any two adjacent words (token or quoted-string), and
- between adjacent words and separators, without changing the
- interpretation of a field. At least one delimiter (LWS and/or
-
- separators) MUST exist between any two tokens (for the definition
- of "token" below), since they would otherwise be interpreted as a
- single token.
-
-2.2 Basic Rules
-
- The following rules are used throughout this specification to
- describe basic parsing constructs. The US-ASCII coded character set
- is defined by ANSI X3.4-1986 [21].
-
-
-
-
-
-Fielding, et al. Standards Track [Page 15]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- OCTET = <any 8-bit sequence of data>
- CHAR = <any US-ASCII character (octets 0 - 127)>
- UPALPHA = <any US-ASCII uppercase letter "A".."Z">
- LOALPHA = <any US-ASCII lowercase letter "a".."z">
- ALPHA = UPALPHA | LOALPHA
- DIGIT = <any US-ASCII digit "0".."9">
- CTL = <any US-ASCII control character
- (octets 0 - 31) and DEL (127)>
- CR = <US-ASCII CR, carriage return (13)>
- LF = <US-ASCII LF, linefeed (10)>
- SP = <US-ASCII SP, space (32)>
- HT = <US-ASCII HT, horizontal-tab (9)>
- <"> = <US-ASCII double-quote mark (34)>
-
- HTTP/1.1 defines the sequence CR LF as the end-of-line marker for all
- protocol elements except the entity-body (see appendix 19.3 for
- tolerant applications). The end-of-line marker within an entity-body
- is defined by its associated media type, as described in section 3.7.
-
- CRLF = CR LF
-
- HTTP/1.1 header field values can be folded onto multiple lines if the
- continuation line begins with a space or horizontal tab. All linear
- white space, including folding, has the same semantics as SP. A
- recipient MAY replace any linear white space with a single SP before
- interpreting the field value or forwarding the message downstream.
-
- LWS = [CRLF] 1*( SP | HT )
-
- The TEXT rule is only used for descriptive field contents and values
- that are not intended to be interpreted by the message parser. Words
- of *TEXT MAY contain characters from character sets other than ISO-
- 8859-1 [22] only when encoded according to the rules of RFC 2047
- [14].
-
- TEXT = <any OCTET except CTLs,
- but including LWS>
-
- A CRLF is allowed in the definition of TEXT only as part of a header
- field continuation. It is expected that the folding LWS will be
- replaced with a single SP before interpretation of the TEXT value.
-
- Hexadecimal numeric characters are used in several protocol elements.
-
- HEX = "A" | "B" | "C" | "D" | "E" | "F"
- | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT
-
-
-
-
-
-Fielding, et al. Standards Track [Page 16]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Many HTTP/1.1 header field values consist of words separated by LWS
- or special characters. These special characters MUST be in a quoted
- string to be used within a parameter value (as defined in section
- 3.6).
-
- token = 1*<any CHAR except CTLs or separators>
- separators = "(" | ")" | "<" | ">" | "@"
- | "," | ";" | ":" | "\" | <">
- | "/" | "[" | "]" | "?" | "="
- | "{" | "}" | SP | HT
-
- Comments can be included in some HTTP header fields by surrounding
- the comment text with parentheses. Comments are only allowed in
- fields containing "comment" as part of their field value definition.
- In all other fields, parentheses are considered part of the field
- value.
-
- comment = "(" *( ctext | quoted-pair | comment ) ")"
- ctext = <any TEXT excluding "(" and ")">
-
- A string of text is parsed as a single word if it is quoted using
- double-quote marks.
-
- quoted-string = ( <"> *(qdtext | quoted-pair ) <"> )
- qdtext = <any TEXT except <">>
-
- The backslash character ("\") MAY be used as a single-character
- quoting mechanism only within quoted-string and comment constructs.
-
- quoted-pair = "\" CHAR
-
-3 Protocol Parameters
-
-3.1 HTTP Version
-
- HTTP uses a "<major>.<minor>" numbering scheme to indicate versions
- of the protocol. The protocol versioning policy is intended to allow
- the sender to indicate the format of a message and its capacity for
- understanding further HTTP communication, rather than the features
- obtained via that communication. No change is made to the version
- number for the addition of message components which do not affect
- communication behavior or which only add to extensible field values.
- The <minor> number is incremented when the changes made to the
- protocol add features which do not change the general message parsing
- algorithm, but which may add to the message semantics and imply
- additional capabilities of the sender. The <major> number is
- incremented when the format of a message within the protocol is
- changed. See RFC 2145 [36] for a fuller explanation.
-
-
-
-Fielding, et al. Standards Track [Page 17]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The version of an HTTP message is indicated by an HTTP-Version field
- in the first line of the message.
-
- HTTP-Version = "HTTP" "/" 1*DIGIT "." 1*DIGIT
-
- Note that the major and minor numbers MUST be treated as separate
- integers and that each MAY be incremented higher than a single digit.
- Thus, HTTP/2.4 is a lower version than HTTP/2.13, which in turn is
- lower than HTTP/12.3. Leading zeros MUST be ignored by recipients and
- MUST NOT be sent.
-
- An application that sends a request or response message that includes
- HTTP-Version of "HTTP/1.1" MUST be at least conditionally compliant
- with this specification. Applications that are at least conditionally
- compliant with this specification SHOULD use an HTTP-Version of
- "HTTP/1.1" in their messages, and MUST do so for any message that is
- not compatible with HTTP/1.0. For more details on when to send
- specific HTTP-Version values, see RFC 2145 [36].
-
- The HTTP version of an application is the highest HTTP version for
- which the application is at least conditionally compliant.
-
- Proxy and gateway applications need to be careful when forwarding
- messages in protocol versions different from that of the application.
- Since the protocol version indicates the protocol capability of the
- sender, a proxy/gateway MUST NOT send a message with a version
- indicator which is greater than its actual version. If a higher
- version request is received, the proxy/gateway MUST either downgrade
- the request version, or respond with an error, or switch to tunnel
- behavior.
-
- Due to interoperability problems with HTTP/1.0 proxies discovered
- since the publication of RFC 2068[33], caching proxies MUST, gateways
- MAY, and tunnels MUST NOT upgrade the request to the highest version
- they support. The proxy/gateway's response to that request MUST be in
- the same major version as the request.
-
- Note: Converting between versions of HTTP may involve modification
- of header fields required or forbidden by the versions involved.
-
-3.2 Uniform Resource Identifiers
-
- URIs have been known by many names: WWW addresses, Universal Document
- Identifiers, Universal Resource Identifiers [3], and finally the
- combination of Uniform Resource Locators (URL) [4] and Names (URN)
- [20]. As far as HTTP is concerned, Uniform Resource Identifiers are
- simply formatted strings which identify--via name, location, or any
- other characteristic--a resource.
-
-
-
-Fielding, et al. Standards Track [Page 18]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-3.2.1 General Syntax
-
- URIs in HTTP can be represented in absolute form or relative to some
- known base URI [11], depending upon the context of their use. The two
- forms are differentiated by the fact that absolute URIs always begin
- with a scheme name followed by a colon. For definitive information on
- URL syntax and semantics, see "Uniform Resource Identifiers (URI):
- Generic Syntax and Semantics," RFC 2396 [42] (which replaces RFCs
- 1738 [4] and RFC 1808 [11]). This specification adopts the
- definitions of "URI-reference", "absoluteURI", "relativeURI", "port",
- "host","abs_path", "rel_path", and "authority" from that
- specification.
-
- The HTTP protocol does not place any a priori limit on the length of
- a URI. Servers MUST be able to handle the URI of any resource they
- serve, and SHOULD be able to handle URIs of unbounded length if they
- provide GET-based forms that could generate such URIs. A server
- SHOULD return 414 (Request-URI Too Long) status if a URI is longer
- than the server can handle (see section 10.4.15).
-
- Note: Servers ought to be cautious about depending on URI lengths
- above 255 bytes, because some older client or proxy
- implementations might not properly support these lengths.
-
-3.2.2 http URL
-
- The "http" scheme is used to locate network resources via the HTTP
- protocol. This section defines the scheme-specific syntax and
- semantics for http URLs.
-
- http_URL = "http:" "//" host [ ":" port ] [ abs_path [ "?" query ]]
-
- If the port is empty or not given, port 80 is assumed. The semantics
- are that the identified resource is located at the server listening
- for TCP connections on that port of that host, and the Request-URI
- for the resource is abs_path (section 5.1.2). The use of IP addresses
- in URLs SHOULD be avoided whenever possible (see RFC 1900 [24]). If
- the abs_path is not present in the URL, it MUST be given as "/" when
- used as a Request-URI for a resource (section 5.1.2). If a proxy
- receives a host name which is not a fully qualified domain name, it
- MAY add its domain to the host name it received. If a proxy receives
- a fully qualified domain name, the proxy MUST NOT change the host
- name.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 19]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-3.2.3 URI Comparison
-
- When comparing two URIs to decide if they match or not, a client
- SHOULD use a case-sensitive octet-by-octet comparison of the entire
- URIs, with these exceptions:
-
- - A port that is empty or not given is equivalent to the default
- port for that URI-reference;
-
- - Comparisons of host names MUST be case-insensitive;
-
- - Comparisons of scheme names MUST be case-insensitive;
-
- - An empty abs_path is equivalent to an abs_path of "/".
-
- Characters other than those in the "reserved" and "unsafe" sets (see
- RFC 2396 [42]) are equivalent to their ""%" HEX HEX" encoding.
-
- For example, the following three URIs are equivalent:
-
- http://abc.com:80/~smith/home.html
- http://ABC.com/%7Esmith/home.html
- http://ABC.com:/%7esmith/home.html
-
-3.3 Date/Time Formats
-
-3.3.1 Full Date
-
- HTTP applications have historically allowed three different formats
- for the representation of date/time stamps:
-
- Sun, 06 Nov 1994 08:49:37 GMT ; RFC 822, updated by RFC 1123
- Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
- Sun Nov 6 08:49:37 1994 ; ANSI C's asctime() format
-
- The first format is preferred as an Internet standard and represents
- a fixed-length subset of that defined by RFC 1123 [8] (an update to
- RFC 822 [9]). The second format is in common use, but is based on the
- obsolete RFC 850 [12] date format and lacks a four-digit year.
- HTTP/1.1 clients and servers that parse the date value MUST accept
- all three formats (for compatibility with HTTP/1.0), though they MUST
- only generate the RFC 1123 format for representing HTTP-date values
- in header fields. See section 19.3 for further information.
-
- Note: Recipients of date values are encouraged to be robust in
- accepting date values that may have been sent by non-HTTP
- applications, as is sometimes the case when retrieving or posting
- messages via proxies/gateways to SMTP or NNTP.
-
-
-
-Fielding, et al. Standards Track [Page 20]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- All HTTP date/time stamps MUST be represented in Greenwich Mean Time
- (GMT), without exception. For the purposes of HTTP, GMT is exactly
- equal to UTC (Coordinated Universal Time). This is indicated in the
- first two formats by the inclusion of "GMT" as the three-letter
- abbreviation for time zone, and MUST be assumed when reading the
- asctime format. HTTP-date is case sensitive and MUST NOT include
- additional LWS beyond that specifically included as SP in the
- grammar.
-
- HTTP-date = rfc1123-date | rfc850-date | asctime-date
- rfc1123-date = wkday "," SP date1 SP time SP "GMT"
- rfc850-date = weekday "," SP date2 SP time SP "GMT"
- asctime-date = wkday SP date3 SP time SP 4DIGIT
- date1 = 2DIGIT SP month SP 4DIGIT
- ; day month year (e.g., 02 Jun 1982)
- date2 = 2DIGIT "-" month "-" 2DIGIT
- ; day-month-year (e.g., 02-Jun-82)
- date3 = month SP ( 2DIGIT | ( SP 1DIGIT ))
- ; month day (e.g., Jun 2)
- time = 2DIGIT ":" 2DIGIT ":" 2DIGIT
- ; 00:00:00 - 23:59:59
- wkday = "Mon" | "Tue" | "Wed"
- | "Thu" | "Fri" | "Sat" | "Sun"
- weekday = "Monday" | "Tuesday" | "Wednesday"
- | "Thursday" | "Friday" | "Saturday" | "Sunday"
- month = "Jan" | "Feb" | "Mar" | "Apr"
- | "May" | "Jun" | "Jul" | "Aug"
- | "Sep" | "Oct" | "Nov" | "Dec"
-
- Note: HTTP requirements for the date/time stamp format apply only
- to their usage within the protocol stream. Clients and servers are
- not required to use these formats for user presentation, request
- logging, etc.
-
-3.3.2 Delta Seconds
-
- Some HTTP header fields allow a time value to be specified as an
- integer number of seconds, represented in decimal, after the time
- that the message was received.
-
- delta-seconds = 1*DIGIT
-
-3.4 Character Sets
-
- HTTP uses the same definition of the term "character set" as that
- described for MIME:
-
-
-
-
-
-Fielding, et al. Standards Track [Page 21]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The term "character set" is used in this document to refer to a
- method used with one or more tables to convert a sequence of octets
- into a sequence of characters. Note that unconditional conversion in
- the other direction is not required, in that not all characters may
- be available in a given character set and a character set may provide
- more than one sequence of octets to represent a particular character.
- This definition is intended to allow various kinds of character
- encoding, from simple single-table mappings such as US-ASCII to
- complex table switching methods such as those that use ISO-2022's
- techniques. However, the definition associated with a MIME character
- set name MUST fully specify the mapping to be performed from octets
- to characters. In particular, use of external profiling information
- to determine the exact mapping is not permitted.
-
- Note: This use of the term "character set" is more commonly
- referred to as a "character encoding." However, since HTTP and
- MIME share the same registry, it is important that the terminology
- also be shared.
-
- HTTP character sets are identified by case-insensitive tokens. The
- complete set of tokens is defined by the IANA Character Set registry
- [19].
-
- charset = token
-
- Although HTTP allows an arbitrary token to be used as a charset
- value, any token that has a predefined value within the IANA
- Character Set registry [19] MUST represent the character set defined
- by that registry. Applications SHOULD limit their use of character
- sets to those defined by the IANA registry.
-
- Implementors should be aware of IETF character set requirements [38]
- [41].
-
-3.4.1 Missing Charset
-
- Some HTTP/1.0 software has interpreted a Content-Type header without
- charset parameter incorrectly to mean "recipient should guess."
- Senders wishing to defeat this behavior MAY include a charset
- parameter even when the charset is ISO-8859-1 and SHOULD do so when
- it is known that it will not confuse the recipient.
-
- Unfortunately, some older HTTP/1.0 clients did not deal properly with
- an explicit charset parameter. HTTP/1.1 recipients MUST respect the
- charset label provided by the sender; and those user agents that have
- a provision to "guess" a charset MUST use the charset from the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 22]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- content-type field if they support that charset, rather than the
- recipient's preference, when initially displaying a document. See
- section 3.7.1.
-
-3.5 Content Codings
-
- Content coding values indicate an encoding transformation that has
- been or can be applied to an entity. Content codings are primarily
- used to allow a document to be compressed or otherwise usefully
- transformed without losing the identity of its underlying media type
- and without loss of information. Frequently, the entity is stored in
- coded form, transmitted directly, and only decoded by the recipient.
-
- content-coding = token
-
- All content-coding values are case-insensitive. HTTP/1.1 uses
- content-coding values in the Accept-Encoding (section 14.3) and
- Content-Encoding (section 14.11) header fields. Although the value
- describes the content-coding, what is more important is that it
- indicates what decoding mechanism will be required to remove the
- encoding.
-
- The Internet Assigned Numbers Authority (IANA) acts as a registry for
- content-coding value tokens. Initially, the registry contains the
- following tokens:
-
- gzip An encoding format produced by the file compression program
- "gzip" (GNU zip) as described in RFC 1952 [25]. This format is a
- Lempel-Ziv coding (LZ77) with a 32 bit CRC.
-
- compress
- The encoding format produced by the common UNIX file compression
- program "compress". This format is an adaptive Lempel-Ziv-Welch
- coding (LZW).
-
- Use of program names for the identification of encoding formats
- is not desirable and is discouraged for future encodings. Their
- use here is representative of historical practice, not good
- design. For compatibility with previous implementations of HTTP,
- applications SHOULD consider "x-gzip" and "x-compress" to be
- equivalent to "gzip" and "compress" respectively.
-
- deflate
- The "zlib" format defined in RFC 1950 [31] in combination with
- the "deflate" compression mechanism described in RFC 1951 [29].
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 23]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- identity
- The default (identity) encoding; the use of no transformation
- whatsoever. This content-coding is used only in the Accept-
- Encoding header, and SHOULD NOT be used in the Content-Encoding
- header.
-
- New content-coding value tokens SHOULD be registered; to allow
- interoperability between clients and servers, specifications of the
- content coding algorithms needed to implement a new value SHOULD be
- publicly available and adequate for independent implementation, and
- conform to the purpose of content coding defined in this section.
-
-3.6 Transfer Codings
-
- Transfer-coding values are used to indicate an encoding
- transformation that has been, can be, or may need to be applied to an
- entity-body in order to ensure "safe transport" through the network.
- This differs from a content coding in that the transfer-coding is a
- property of the message, not of the original entity.
-
- transfer-coding = "chunked" | transfer-extension
- transfer-extension = token *( ";" parameter )
-
- Parameters are in the form of attribute/value pairs.
-
- parameter = attribute "=" value
- attribute = token
- value = token | quoted-string
-
- All transfer-coding values are case-insensitive. HTTP/1.1 uses
- transfer-coding values in the TE header field (section 14.39) and in
- the Transfer-Encoding header field (section 14.41).
-
- Whenever a transfer-coding is applied to a message-body, the set of
- transfer-codings MUST include "chunked", unless the message is
- terminated by closing the connection. When the "chunked" transfer-
- coding is used, it MUST be the last transfer-coding applied to the
- message-body. The "chunked" transfer-coding MUST NOT be applied more
- than once to a message-body. These rules allow the recipient to
- determine the transfer-length of the message (section 4.4).
-
- Transfer-codings are analogous to the Content-Transfer-Encoding
- values of MIME [7], which were designed to enable safe transport of
- binary data over a 7-bit transport service. However, safe transport
- has a different focus for an 8bit-clean transfer protocol. In HTTP,
- the only unsafe characteristic of message-bodies is the difficulty in
- determining the exact body length (section 7.2.2), or the desire to
- encrypt data over a shared transport.
-
-
-
-Fielding, et al. Standards Track [Page 24]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Internet Assigned Numbers Authority (IANA) acts as a registry for
- transfer-coding value tokens. Initially, the registry contains the
- following tokens: "chunked" (section 3.6.1), "identity" (section
- 3.6.2), "gzip" (section 3.5), "compress" (section 3.5), and "deflate"
- (section 3.5).
-
- New transfer-coding value tokens SHOULD be registered in the same way
- as new content-coding value tokens (section 3.5).
-
- A server which receives an entity-body with a transfer-coding it does
- not understand SHOULD return 501 (Unimplemented), and close the
- connection. A server MUST NOT send transfer-codings to an HTTP/1.0
- client.
-
-3.6.1 Chunked Transfer Coding
-
- The chunked encoding modifies the body of a message in order to
- transfer it as a series of chunks, each with its own size indicator,
- followed by an OPTIONAL trailer containing entity-header fields. This
- allows dynamically produced content to be transferred along with the
- information necessary for the recipient to verify that it has
- received the full message.
-
- Chunked-Body = *chunk
- last-chunk
- trailer
- CRLF
-
- chunk = chunk-size [ chunk-extension ] CRLF
- chunk-data CRLF
- chunk-size = 1*HEX
- last-chunk = 1*("0") [ chunk-extension ] CRLF
-
- chunk-extension= *( ";" chunk-ext-name [ "=" chunk-ext-val ] )
- chunk-ext-name = token
- chunk-ext-val = token | quoted-string
- chunk-data = chunk-size(OCTET)
- trailer = *(entity-header CRLF)
-
- The chunk-size field is a string of hex digits indicating the size of
- the chunk. The chunked encoding is ended by any chunk whose size is
- zero, followed by the trailer, which is terminated by an empty line.
-
- The trailer allows the sender to include additional HTTP header
- fields at the end of the message. The Trailer header field can be
- used to indicate which header fields are included in a trailer (see
- section 14.40).
-
-
-
-
-Fielding, et al. Standards Track [Page 25]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- A server using chunked transfer-coding in a response MUST NOT use the
- trailer for any header fields unless at least one of the following is
- true:
-
- a)the request included a TE header field that indicates "trailers" is
- acceptable in the transfer-coding of the response, as described in
- section 14.39; or,
-
- b)the server is the origin server for the response, the trailer
- fields consist entirely of optional metadata, and the recipient
- could use the message (in a manner acceptable to the origin server)
- without receiving this metadata. In other words, the origin server
- is willing to accept the possibility that the trailer fields might
- be silently discarded along the path to the client.
-
- This requirement prevents an interoperability failure when the
- message is being received by an HTTP/1.1 (or later) proxy and
- forwarded to an HTTP/1.0 recipient. It avoids a situation where
- compliance with the protocol would have necessitated a possibly
- infinite buffer on the proxy.
-
- An example process for decoding a Chunked-Body is presented in
- appendix 19.4.6.
-
- All HTTP/1.1 applications MUST be able to receive and decode the
- "chunked" transfer-coding, and MUST ignore chunk-extension extensions
- they do not understand.
-
-3.7 Media Types
-
- HTTP uses Internet Media Types [17] in the Content-Type (section
- 14.17) and Accept (section 14.1) header fields in order to provide
- open and extensible data typing and type negotiation.
-
- media-type = type "/" subtype *( ";" parameter )
- type = token
- subtype = token
-
- Parameters MAY follow the type/subtype in the form of attribute/value
- pairs (as defined in section 3.6).
-
- The type, subtype, and parameter attribute names are case-
- insensitive. Parameter values might or might not be case-sensitive,
- depending on the semantics of the parameter name. Linear white space
- (LWS) MUST NOT be used between the type and subtype, nor between an
- attribute and its value. The presence or absence of a parameter might
- be significant to the processing of a media-type, depending on its
- definition within the media type registry.
-
-
-
-Fielding, et al. Standards Track [Page 26]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note that some older HTTP applications do not recognize media type
- parameters. When sending data to older HTTP applications,
- implementations SHOULD only use media type parameters when they are
- required by that type/subtype definition.
-
- Media-type values are registered with the Internet Assigned Number
- Authority (IANA [19]). The media type registration process is
- outlined in RFC 1590 [17]. Use of non-registered media types is
- discouraged.
-
-3.7.1 Canonicalization and Text Defaults
-
- Internet media types are registered with a canonical form. An
- entity-body transferred via HTTP messages MUST be represented in the
- appropriate canonical form prior to its transmission except for
- "text" types, as defined in the next paragraph.
-
- When in canonical form, media subtypes of the "text" type use CRLF as
- the text line break. HTTP relaxes this requirement and allows the
- transport of text media with plain CR or LF alone representing a line
- break when it is done consistently for an entire entity-body. HTTP
- applications MUST accept CRLF, bare CR, and bare LF as being
- representative of a line break in text media received via HTTP. In
- addition, if the text is represented in a character set that does not
- use octets 13 and 10 for CR and LF respectively, as is the case for
- some multi-byte character sets, HTTP allows the use of whatever octet
- sequences are defined by that character set to represent the
- equivalent of CR and LF for line breaks. This flexibility regarding
- line breaks applies only to text media in the entity-body; a bare CR
- or LF MUST NOT be substituted for CRLF within any of the HTTP control
- structures (such as header fields and multipart boundaries).
-
- If an entity-body is encoded with a content-coding, the underlying
- data MUST be in a form defined above prior to being encoded.
-
- The "charset" parameter is used with some media types to define the
- character set (section 3.4) of the data. When no explicit charset
- parameter is provided by the sender, media subtypes of the "text"
- type are defined to have a default charset value of "ISO-8859-1" when
- received via HTTP. Data in character sets other than "ISO-8859-1" or
- its subsets MUST be labeled with an appropriate charset value. See
- section 3.4.1 for compatibility problems.
-
-3.7.2 Multipart Types
-
- MIME provides for a number of "multipart" types -- encapsulations of
- one or more entities within a single message-body. All multipart
- types share a common syntax, as defined in section 5.1.1 of RFC 2046
-
-
-
-Fielding, et al. Standards Track [Page 27]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- [40], and MUST include a boundary parameter as part of the media type
- value. The message body is itself a protocol element and MUST
- therefore use only CRLF to represent line breaks between body-parts.
- Unlike in RFC 2046, the epilogue of any multipart message MUST be
- empty; HTTP applications MUST NOT transmit the epilogue (even if the
- original multipart contains an epilogue). These restrictions exist in
- order to preserve the self-delimiting nature of a multipart message-
- body, wherein the "end" of the message-body is indicated by the
- ending multipart boundary.
-
- In general, HTTP treats a multipart message-body no differently than
- any other media type: strictly as payload. The one exception is the
- "multipart/byteranges" type (appendix 19.2) when it appears in a 206
- (Partial Content) response, which will be interpreted by some HTTP
- caching mechanisms as described in sections 13.5.4 and 14.16. In all
- other cases, an HTTP user agent SHOULD follow the same or similar
- behavior as a MIME user agent would upon receipt of a multipart type.
- The MIME header fields within each body-part of a multipart message-
- body do not have any significance to HTTP beyond that defined by
- their MIME semantics.
-
- In general, an HTTP user agent SHOULD follow the same or similar
- behavior as a MIME user agent would upon receipt of a multipart type.
- If an application receives an unrecognized multipart subtype, the
- application MUST treat it as being equivalent to "multipart/mixed".
-
- Note: The "multipart/form-data" type has been specifically defined
- for carrying form data suitable for processing via the POST
- request method, as described in RFC 1867 [15].
-
-3.8 Product Tokens
-
- Product tokens are used to allow communicating applications to
- identify themselves by software name and version. Most fields using
- product tokens also allow sub-products which form a significant part
- of the application to be listed, separated by white space. By
- convention, the products are listed in order of their significance
- for identifying the application.
-
- product = token ["/" product-version]
- product-version = token
-
- Examples:
-
- User-Agent: CERN-LineMode/2.15 libwww/2.17b3
- Server: Apache/0.8.4
-
-
-
-
-
-Fielding, et al. Standards Track [Page 28]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Product tokens SHOULD be short and to the point. They MUST NOT be
- used for advertising or other non-essential information. Although any
- token character MAY appear in a product-version, this token SHOULD
- only be used for a version identifier (i.e., successive versions of
- the same product SHOULD only differ in the product-version portion of
- the product value).
-
-3.9 Quality Values
-
- HTTP content negotiation (section 12) uses short "floating point"
- numbers to indicate the relative importance ("weight") of various
- negotiable parameters. A weight is normalized to a real number in
- the range 0 through 1, where 0 is the minimum and 1 the maximum
- value. If a parameter has a quality value of 0, then content with
- this parameter is `not acceptable' for the client. HTTP/1.1
- applications MUST NOT generate more than three digits after the
- decimal point. User configuration of these values SHOULD also be
- limited in this fashion.
-
- qvalue = ( "0" [ "." 0*3DIGIT ] )
- | ( "1" [ "." 0*3("0") ] )
-
- "Quality values" is a misnomer, since these values merely represent
- relative degradation in desired quality.
-
-3.10 Language Tags
-
- A language tag identifies a natural language spoken, written, or
- otherwise conveyed by human beings for communication of information
- to other human beings. Computer languages are explicitly excluded.
- HTTP uses language tags within the Accept-Language and Content-
- Language fields.
-
- The syntax and registry of HTTP language tags is the same as that
- defined by RFC 1766 [1]. In summary, a language tag is composed of 1
- or more parts: A primary language tag and a possibly empty series of
- subtags:
-
- language-tag = primary-tag *( "-" subtag )
- primary-tag = 1*8ALPHA
- subtag = 1*8ALPHA
-
- White space is not allowed within the tag and all tags are case-
- insensitive. The name space of language tags is administered by the
- IANA. Example tags include:
-
- en, en-US, en-cockney, i-cherokee, x-pig-latin
-
-
-
-
-Fielding, et al. Standards Track [Page 29]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- where any two-letter primary-tag is an ISO-639 language abbreviation
- and any two-letter initial subtag is an ISO-3166 country code. (The
- last three tags above are not registered tags; all but the last are
- examples of tags which could be registered in future.)
-
-3.11 Entity Tags
-
- Entity tags are used for comparing two or more entities from the same
- requested resource. HTTP/1.1 uses entity tags in the ETag (section
- 14.19), If-Match (section 14.24), If-None-Match (section 14.26), and
- If-Range (section 14.27) header fields. The definition of how they
- are used and compared as cache validators is in section 13.3.3. An
- entity tag consists of an opaque quoted string, possibly prefixed by
- a weakness indicator.
-
- entity-tag = [ weak ] opaque-tag
- weak = "W/"
- opaque-tag = quoted-string
-
- A "strong entity tag" MAY be shared by two entities of a resource
- only if they are equivalent by octet equality.
-
- A "weak entity tag," indicated by the "W/" prefix, MAY be shared by
- two entities of a resource only if the entities are equivalent and
- could be substituted for each other with no significant change in
- semantics. A weak entity tag can only be used for weak comparison.
-
- An entity tag MUST be unique across all versions of all entities
- associated with a particular resource. A given entity tag value MAY
- be used for entities obtained by requests on different URIs. The use
- of the same entity tag value in conjunction with entities obtained by
- requests on different URIs does not imply the equivalence of those
- entities.
-
-3.12 Range Units
-
- HTTP/1.1 allows a client to request that only part (a range of) the
- response entity be included within the response. HTTP/1.1 uses range
- units in the Range (section 14.35) and Content-Range (section 14.16)
- header fields. An entity can be broken down into subranges according
- to various structural units.
-
- range-unit = bytes-unit | other-range-unit
- bytes-unit = "bytes"
- other-range-unit = token
-
- The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1
- implementations MAY ignore ranges specified using other units.
-
-
-
-Fielding, et al. Standards Track [Page 30]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 has been designed to allow implementations of applications
- that do not depend on knowledge of ranges.
-
-4 HTTP Message
-
-4.1 Message Types
-
- HTTP messages consist of requests from client to server and responses
- from server to client.
-
- HTTP-message = Request | Response ; HTTP/1.1 messages
-
- Request (section 5) and Response (section 6) messages use the generic
- message format of RFC 822 [9] for transferring entities (the payload
- of the message). Both types of message consist of a start-line, zero
- or more header fields (also known as "headers"), an empty line (i.e.,
- a line with nothing preceding the CRLF) indicating the end of the
- header fields, and possibly a message-body.
-
- generic-message = start-line
- *(message-header CRLF)
- CRLF
- [ message-body ]
- start-line = Request-Line | Status-Line
-
- In the interest of robustness, servers SHOULD ignore any empty
- line(s) received where a Request-Line is expected. In other words, if
- the server is reading the protocol stream at the beginning of a
- message and receives a CRLF first, it should ignore the CRLF.
-
- Certain buggy HTTP/1.0 client implementations generate extra CRLF's
- after a POST request. To restate what is explicitly forbidden by the
- BNF, an HTTP/1.1 client MUST NOT preface or follow a request with an
- extra CRLF.
-
-4.2 Message Headers
-
- HTTP header fields, which include general-header (section 4.5),
- request-header (section 5.3), response-header (section 6.2), and
- entity-header (section 7.1) fields, follow the same generic format as
- that given in Section 3.1 of RFC 822 [9]. Each header field consists
- of a name followed by a colon (":") and the field value. Field names
- are case-insensitive. The field value MAY be preceded by any amount
- of LWS, though a single SP is preferred. Header fields can be
- extended over multiple lines by preceding each extra line with at
- least one SP or HT. Applications ought to follow "common form", where
- one is known or indicated, when generating HTTP constructs, since
- there might exist some implementations that fail to accept anything
-
-
-
-Fielding, et al. Standards Track [Page 31]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- beyond the common forms.
-
- message-header = field-name ":" [ field-value ]
- field-name = token
- field-value = *( field-content | LWS )
- field-content = <the OCTETs making up the field-value
- and consisting of either *TEXT or combinations
- of token, separators, and quoted-string>
-
- The field-content does not include any leading or trailing LWS:
- linear white space occurring before the first non-whitespace
- character of the field-value or after the last non-whitespace
- character of the field-value. Such leading or trailing LWS MAY be
- removed without changing the semantics of the field value. Any LWS
- that occurs between field-content MAY be replaced with a single SP
- before interpreting the field value or forwarding the message
- downstream.
-
- The order in which header fields with differing field names are
- received is not significant. However, it is "good practice" to send
- general-header fields first, followed by request-header or response-
- header fields, and ending with the entity-header fields.
-
- Multiple message-header fields with the same field-name MAY be
- present in a message if and only if the entire field-value for that
- header field is defined as a comma-separated list [i.e., #(values)].
- It MUST be possible to combine the multiple header fields into one
- "field-name: field-value" pair, without changing the semantics of the
- message, by appending each subsequent field-value to the first, each
- separated by a comma. The order in which header fields with the same
- field-name are received is therefore significant to the
- interpretation of the combined field value, and thus a proxy MUST NOT
- change the order of these field values when a message is forwarded.
-
-4.3 Message Body
-
- The message-body (if any) of an HTTP message is used to carry the
- entity-body associated with the request or response. The message-body
- differs from the entity-body only when a transfer-coding has been
- applied, as indicated by the Transfer-Encoding header field (section
- 14.41).
-
- message-body = entity-body
- | <entity-body encoded as per Transfer-Encoding>
-
- Transfer-Encoding MUST be used to indicate any transfer-codings
- applied by an application to ensure safe and proper transfer of the
- message. Transfer-Encoding is a property of the message, not of the
-
-
-
-Fielding, et al. Standards Track [Page 32]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- entity, and thus MAY be added or removed by any application along the
- request/response chain. (However, section 3.6 places restrictions on
- when certain transfer-codings may be used.)
-
- The rules for when a message-body is allowed in a message differ for
- requests and responses.
-
- The presence of a message-body in a request is signaled by the
- inclusion of a Content-Length or Transfer-Encoding header field in
- the request's message-headers. A message-body MUST NOT be included in
- a request if the specification of the request method (section 5.1.1)
- does not allow sending an entity-body in requests. A server SHOULD
- read and forward a message-body on any request; if the request method
- does not include defined semantics for an entity-body, then the
- message-body SHOULD be ignored when handling the request.
-
- For response messages, whether or not a message-body is included with
- a message is dependent on both the request method and the response
- status code (section 6.1.1). All responses to the HEAD request method
- MUST NOT include a message-body, even though the presence of entity-
- header fields might lead one to believe they do. All 1xx
- (informational), 204 (no content), and 304 (not modified) responses
- MUST NOT include a message-body. All other responses do include a
- message-body, although it MAY be of zero length.
-
-4.4 Message Length
-
- The transfer-length of a message is the length of the message-body as
- it appears in the message; that is, after any transfer-codings have
- been applied. When a message-body is included with a message, the
- transfer-length of that body is determined by one of the following
- (in order of precedence):
-
- 1.Any response message which "MUST NOT" include a message-body (such
- as the 1xx, 204, and 304 responses and any response to a HEAD
- request) is always terminated by the first empty line after the
- header fields, regardless of the entity-header fields present in
- the message.
-
- 2.If a Transfer-Encoding header field (section 14.41) is present and
- has any value other than "identity", then the transfer-length is
- defined by use of the "chunked" transfer-coding (section 3.6),
- unless the message is terminated by closing the connection.
-
- 3.If a Content-Length header field (section 14.13) is present, its
- decimal value in OCTETs represents both the entity-length and the
- transfer-length. The Content-Length header field MUST NOT be sent
- if these two lengths are different (i.e., if a Transfer-Encoding
-
-
-
-Fielding, et al. Standards Track [Page 33]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- header field is present). If a message is received with both a
- Transfer-Encoding header field and a Content-Length header field,
- the latter MUST be ignored.
-
- 4.If the message uses the media type "multipart/byteranges", and the
- ransfer-length is not otherwise specified, then this self-
- elimiting media type defines the transfer-length. This media type
- UST NOT be used unless the sender knows that the recipient can arse
- it; the presence in a request of a Range header with ultiple byte-
- range specifiers from a 1.1 client implies that the lient can parse
- multipart/byteranges responses.
-
- A range header might be forwarded by a 1.0 proxy that does not
- understand multipart/byteranges; in this case the server MUST
- delimit the message using methods defined in items 1,3 or 5 of
- this section.
-
- 5.By the server closing the connection. (Closing the connection
- cannot be used to indicate the end of a request body, since that
- would leave no possibility for the server to send back a response.)
-
- For compatibility with HTTP/1.0 applications, HTTP/1.1 requests
- containing a message-body MUST include a valid Content-Length header
- field unless the server is known to be HTTP/1.1 compliant. If a
- request contains a message-body and a Content-Length is not given,
- the server SHOULD respond with 400 (bad request) if it cannot
- determine the length of the message, or with 411 (length required) if
- it wishes to insist on receiving a valid Content-Length.
-
- All HTTP/1.1 applications that receive entities MUST accept the
- "chunked" transfer-coding (section 3.6), thus allowing this mechanism
- to be used for messages when the message length cannot be determined
- in advance.
-
- Messages MUST NOT include both a Content-Length header field and a
- non-identity transfer-coding. If the message does include a non-
- identity transfer-coding, the Content-Length MUST be ignored.
-
- When a Content-Length is given in a message where a message-body is
- allowed, its field value MUST exactly match the number of OCTETs in
- the message-body. HTTP/1.1 user agents MUST notify the user when an
- invalid length is received and detected.
-
-4.5 General Header Fields
-
- There are a few header fields which have general applicability for
- both request and response messages, but which do not apply to the
- entity being transferred. These header fields apply only to the
-
-
-
-Fielding, et al. Standards Track [Page 34]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- message being transmitted.
-
- general-header = Cache-Control ; Section 14.9
- | Connection ; Section 14.10
- | Date ; Section 14.18
- | Pragma ; Section 14.32
- | Trailer ; Section 14.40
- | Transfer-Encoding ; Section 14.41
- | Upgrade ; Section 14.42
- | Via ; Section 14.45
- | Warning ; Section 14.46
-
- General-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields may be given the semantics of general
- header fields if all parties in the communication recognize them to
- be general-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-5 Request
-
- A request message from a client to a server includes, within the
- first line of that message, the method to be applied to the resource,
- the identifier of the resource, and the protocol version in use.
-
- Request = Request-Line ; Section 5.1
- *(( general-header ; Section 4.5
- | request-header ; Section 5.3
- | entity-header ) CRLF) ; Section 7.1
- CRLF
- [ message-body ] ; Section 4.3
-
-5.1 Request-Line
-
- The Request-Line begins with a method token, followed by the
- Request-URI and the protocol version, and ending with CRLF. The
- elements are separated by SP characters. No CR or LF is allowed
- except in the final CRLF sequence.
-
- Request-Line = Method SP Request-URI SP HTTP-Version CRLF
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 35]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-5.1.1 Method
-
- The Method token indicates the method to be performed on the
- resource identified by the Request-URI. The method is case-sensitive.
-
- Method = "OPTIONS" ; Section 9.2
- | "GET" ; Section 9.3
- | "HEAD" ; Section 9.4
- | "POST" ; Section 9.5
- | "PUT" ; Section 9.6
- | "DELETE" ; Section 9.7
- | "TRACE" ; Section 9.8
- | "CONNECT" ; Section 9.9
- | extension-method
- extension-method = token
-
- The list of methods allowed by a resource can be specified in an
- Allow header field (section 14.7). The return code of the response
- always notifies the client whether a method is currently allowed on a
- resource, since the set of allowed methods can change dynamically. An
- origin server SHOULD return the status code 405 (Method Not Allowed)
- if the method is known by the origin server but not allowed for the
- requested resource, and 501 (Not Implemented) if the method is
- unrecognized or not implemented by the origin server. The methods GET
- and HEAD MUST be supported by all general-purpose servers. All other
- methods are OPTIONAL; however, if the above methods are implemented,
- they MUST be implemented with the same semantics as those specified
- in section 9.
-
-5.1.2 Request-URI
-
- The Request-URI is a Uniform Resource Identifier (section 3.2) and
- identifies the resource upon which to apply the request.
-
- Request-URI = "*" | absoluteURI | abs_path | authority
-
- The four options for Request-URI are dependent on the nature of the
- request. The asterisk "*" means that the request does not apply to a
- particular resource, but to the server itself, and is only allowed
- when the method used does not necessarily apply to a resource. One
- example would be
-
- OPTIONS * HTTP/1.1
-
- The absoluteURI form is REQUIRED when the request is being made to a
- proxy. The proxy is requested to forward the request or service it
- from a valid cache, and return the response. Note that the proxy MAY
- forward the request on to another proxy or directly to the server
-
-
-
-Fielding, et al. Standards Track [Page 36]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- specified by the absoluteURI. In order to avoid request loops, a
- proxy MUST be able to recognize all of its server names, including
- any aliases, local variations, and the numeric IP address. An example
- Request-Line would be:
-
- GET http://www.w3.org/pub/WWW/TheProject.html HTTP/1.1
-
- To allow for transition to absoluteURIs in all requests in future
- versions of HTTP, all HTTP/1.1 servers MUST accept the absoluteURI
- form in requests, even though HTTP/1.1 clients will only generate
- them in requests to proxies.
-
- The authority form is only used by the CONNECT method (section 9.9).
-
- The most common form of Request-URI is that used to identify a
- resource on an origin server or gateway. In this case the absolute
- path of the URI MUST be transmitted (see section 3.2.1, abs_path) as
- the Request-URI, and the network location of the URI (authority) MUST
- be transmitted in a Host header field. For example, a client wishing
- to retrieve the resource above directly from the origin server would
- create a TCP connection to port 80 of the host "www.w3.org" and send
- the lines:
-
- GET /pub/WWW/TheProject.html HTTP/1.1
- Host: www.w3.org
-
- followed by the remainder of the Request. Note that the absolute path
- cannot be empty; if none is present in the original URI, it MUST be
- given as "/" (the server root).
-
- The Request-URI is transmitted in the format specified in section
- 3.2.1. If the Request-URI is encoded using the "% HEX HEX" encoding
- [42], the origin server MUST decode the Request-URI in order to
- properly interpret the request. Servers SHOULD respond to invalid
- Request-URIs with an appropriate status code.
-
- A transparent proxy MUST NOT rewrite the "abs_path" part of the
- received Request-URI when forwarding it to the next inbound server,
- except as noted above to replace a null abs_path with "/".
-
- Note: The "no rewrite" rule prevents the proxy from changing the
- meaning of the request when the origin server is improperly using
- a non-reserved URI character for a reserved purpose. Implementors
- should be aware that some pre-HTTP/1.1 proxies have been known to
- rewrite the Request-URI.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 37]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-5.2 The Resource Identified by a Request
-
- The exact resource identified by an Internet request is determined by
- examining both the Request-URI and the Host header field.
-
- An origin server that does not allow resources to differ by the
- requested host MAY ignore the Host header field value when
- determining the resource identified by an HTTP/1.1 request. (But see
- section 19.6.1.1 for other requirements on Host support in HTTP/1.1.)
-
- An origin server that does differentiate resources based on the host
- requested (sometimes referred to as virtual hosts or vanity host
- names) MUST use the following rules for determining the requested
- resource on an HTTP/1.1 request:
-
- 1. If Request-URI is an absoluteURI, the host is part of the
- Request-URI. Any Host header field value in the request MUST be
- ignored.
-
- 2. If the Request-URI is not an absoluteURI, and the request includes
- a Host header field, the host is determined by the Host header
- field value.
-
- 3. If the host as determined by rule 1 or 2 is not a valid host on
- the server, the response MUST be a 400 (Bad Request) error message.
-
- Recipients of an HTTP/1.0 request that lacks a Host header field MAY
- attempt to use heuristics (e.g., examination of the URI path for
- something unique to a particular host) in order to determine what
- exact resource is being requested.
-
-5.3 Request Header Fields
-
- The request-header fields allow the client to pass additional
- information about the request, and about the client itself, to the
- server. These fields act as request modifiers, with semantics
- equivalent to the parameters on a programming language method
- invocation.
-
- request-header = Accept ; Section 14.1
- | Accept-Charset ; Section 14.2
- | Accept-Encoding ; Section 14.3
- | Accept-Language ; Section 14.4
- | Authorization ; Section 14.8
- | Expect ; Section 14.20
- | From ; Section 14.22
- | Host ; Section 14.23
- | If-Match ; Section 14.24
-
-
-
-Fielding, et al. Standards Track [Page 38]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- | If-Modified-Since ; Section 14.25
- | If-None-Match ; Section 14.26
- | If-Range ; Section 14.27
- | If-Unmodified-Since ; Section 14.28
- | Max-Forwards ; Section 14.31
- | Proxy-Authorization ; Section 14.34
- | Range ; Section 14.35
- | Referer ; Section 14.36
- | TE ; Section 14.39
- | User-Agent ; Section 14.43
-
- Request-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields MAY be given the semantics of request-
- header fields if all parties in the communication recognize them to
- be request-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-6 Response
-
- After receiving and interpreting a request message, a server responds
- with an HTTP response message.
-
- Response = Status-Line ; Section 6.1
- *(( general-header ; Section 4.5
- | response-header ; Section 6.2
- | entity-header ) CRLF) ; Section 7.1
- CRLF
- [ message-body ] ; Section 7.2
-
-6.1 Status-Line
-
- The first line of a Response message is the Status-Line, consisting
- of the protocol version followed by a numeric status code and its
- associated textual phrase, with each element separated by SP
- characters. No CR or LF is allowed except in the final CRLF sequence.
-
- Status-Line = HTTP-Version SP Status-Code SP Reason-Phrase CRLF
-
-6.1.1 Status Code and Reason Phrase
-
- The Status-Code element is a 3-digit integer result code of the
- attempt to understand and satisfy the request. These codes are fully
- defined in section 10. The Reason-Phrase is intended to give a short
- textual description of the Status-Code. The Status-Code is intended
- for use by automata and the Reason-Phrase is intended for the human
- user. The client is not required to examine or display the Reason-
- Phrase.
-
-
-
-Fielding, et al. Standards Track [Page 39]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The first digit of the Status-Code defines the class of response. The
- last two digits do not have any categorization role. There are 5
- values for the first digit:
-
- - 1xx: Informational - Request received, continuing process
-
- - 2xx: Success - The action was successfully received,
- understood, and accepted
-
- - 3xx: Redirection - Further action must be taken in order to
- complete the request
-
- - 4xx: Client Error - The request contains bad syntax or cannot
- be fulfilled
-
- - 5xx: Server Error - The server failed to fulfill an apparently
- valid request
-
- The individual values of the numeric status codes defined for
- HTTP/1.1, and an example set of corresponding Reason-Phrase's, are
- presented below. The reason phrases listed here are only
- recommendations -- they MAY be replaced by local equivalents without
- affecting the protocol.
-
- Status-Code =
- "100" ; Section 10.1.1: Continue
- | "101" ; Section 10.1.2: Switching Protocols
- | "200" ; Section 10.2.1: OK
- | "201" ; Section 10.2.2: Created
- | "202" ; Section 10.2.3: Accepted
- | "203" ; Section 10.2.4: Non-Authoritative Information
- | "204" ; Section 10.2.5: No Content
- | "205" ; Section 10.2.6: Reset Content
- | "206" ; Section 10.2.7: Partial Content
- | "300" ; Section 10.3.1: Multiple Choices
- | "301" ; Section 10.3.2: Moved Permanently
- | "302" ; Section 10.3.3: Found
- | "303" ; Section 10.3.4: See Other
- | "304" ; Section 10.3.5: Not Modified
- | "305" ; Section 10.3.6: Use Proxy
- | "307" ; Section 10.3.8: Temporary Redirect
- | "400" ; Section 10.4.1: Bad Request
- | "401" ; Section 10.4.2: Unauthorized
- | "402" ; Section 10.4.3: Payment Required
- | "403" ; Section 10.4.4: Forbidden
- | "404" ; Section 10.4.5: Not Found
- | "405" ; Section 10.4.6: Method Not Allowed
- | "406" ; Section 10.4.7: Not Acceptable
-
-
-
-Fielding, et al. Standards Track [Page 40]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- | "407" ; Section 10.4.8: Proxy Authentication Required
- | "408" ; Section 10.4.9: Request Time-out
- | "409" ; Section 10.4.10: Conflict
- | "410" ; Section 10.4.11: Gone
- | "411" ; Section 10.4.12: Length Required
- | "412" ; Section 10.4.13: Precondition Failed
- | "413" ; Section 10.4.14: Request Entity Too Large
- | "414" ; Section 10.4.15: Request-URI Too Large
- | "415" ; Section 10.4.16: Unsupported Media Type
- | "416" ; Section 10.4.17: Requested range not satisfiable
- | "417" ; Section 10.4.18: Expectation Failed
- | "500" ; Section 10.5.1: Internal Server Error
- | "501" ; Section 10.5.2: Not Implemented
- | "502" ; Section 10.5.3: Bad Gateway
- | "503" ; Section 10.5.4: Service Unavailable
- | "504" ; Section 10.5.5: Gateway Time-out
- | "505" ; Section 10.5.6: HTTP Version not supported
- | extension-code
-
- extension-code = 3DIGIT
- Reason-Phrase = *<TEXT, excluding CR, LF>
-
- HTTP status codes are extensible. HTTP applications are not required
- to understand the meaning of all registered status codes, though such
- understanding is obviously desirable. However, applications MUST
- understand the class of any status code, as indicated by the first
- digit, and treat any unrecognized response as being equivalent to the
- x00 status code of that class, with the exception that an
- unrecognized response MUST NOT be cached. For example, if an
- unrecognized status code of 431 is received by the client, it can
- safely assume that there was something wrong with its request and
- treat the response as if it had received a 400 status code. In such
- cases, user agents SHOULD present to the user the entity returned
- with the response, since that entity is likely to include human-
- readable information which will explain the unusual status.
-
-6.2 Response Header Fields
-
- The response-header fields allow the server to pass additional
- information about the response which cannot be placed in the Status-
- Line. These header fields give information about the server and about
- further access to the resource identified by the Request-URI.
-
- response-header = Accept-Ranges ; Section 14.5
- | Age ; Section 14.6
- | ETag ; Section 14.19
- | Location ; Section 14.30
- | Proxy-Authenticate ; Section 14.33
-
-
-
-Fielding, et al. Standards Track [Page 41]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- | Retry-After ; Section 14.37
- | Server ; Section 14.38
- | Vary ; Section 14.44
- | WWW-Authenticate ; Section 14.47
-
- Response-header field names can be extended reliably only in
- combination with a change in the protocol version. However, new or
- experimental header fields MAY be given the semantics of response-
- header fields if all parties in the communication recognize them to
- be response-header fields. Unrecognized header fields are treated as
- entity-header fields.
-
-7 Entity
-
- Request and Response messages MAY transfer an entity if not otherwise
- restricted by the request method or response status code. An entity
- consists of entity-header fields and an entity-body, although some
- responses will only include the entity-headers.
-
- In this section, both sender and recipient refer to either the client
- or the server, depending on who sends and who receives the entity.
-
-7.1 Entity Header Fields
-
- Entity-header fields define metainformation about the entity-body or,
- if no body is present, about the resource identified by the request.
- Some of this metainformation is OPTIONAL; some might be REQUIRED by
- portions of this specification.
-
- entity-header = Allow ; Section 14.7
- | Content-Encoding ; Section 14.11
- | Content-Language ; Section 14.12
- | Content-Length ; Section 14.13
- | Content-Location ; Section 14.14
- | Content-MD5 ; Section 14.15
- | Content-Range ; Section 14.16
- | Content-Type ; Section 14.17
- | Expires ; Section 14.21
- | Last-Modified ; Section 14.29
- | extension-header
-
- extension-header = message-header
-
- The extension-header mechanism allows additional entity-header fields
- to be defined without changing the protocol, but these fields cannot
- be assumed to be recognizable by the recipient. Unrecognized header
- fields SHOULD be ignored by the recipient and MUST be forwarded by
- transparent proxies.
-
-
-
-Fielding, et al. Standards Track [Page 42]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-7.2 Entity Body
-
- The entity-body (if any) sent with an HTTP request or response is in
- a format and encoding defined by the entity-header fields.
-
- entity-body = *OCTET
-
- An entity-body is only present in a message when a message-body is
- present, as described in section 4.3. The entity-body is obtained
- from the message-body by decoding any Transfer-Encoding that might
- have been applied to ensure safe and proper transfer of the message.
-
-7.2.1 Type
-
- When an entity-body is included with a message, the data type of that
- body is determined via the header fields Content-Type and Content-
- Encoding. These define a two-layer, ordered encoding model:
-
- entity-body := Content-Encoding( Content-Type( data ) )
-
- Content-Type specifies the media type of the underlying data.
- Content-Encoding may be used to indicate any additional content
- codings applied to the data, usually for the purpose of data
- compression, that are a property of the requested resource. There is
- no default encoding.
-
- Any HTTP/1.1 message containing an entity-body SHOULD include a
- Content-Type header field defining the media type of that body. If
- and only if the media type is not given by a Content-Type field, the
- recipient MAY attempt to guess the media type via inspection of its
- content and/or the name extension(s) of the URI used to identify the
- resource. If the media type remains unknown, the recipient SHOULD
- treat it as type "application/octet-stream".
-
-7.2.2 Entity Length
-
- The entity-length of a message is the length of the message-body
- before any transfer-codings have been applied. Section 4.4 defines
- how the transfer-length of a message-body is determined.
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 43]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-8 Connections
-
-8.1 Persistent Connections
-
-8.1.1 Purpose
-
- Prior to persistent connections, a separate TCP connection was
- established to fetch each URL, increasing the load on HTTP servers
- and causing congestion on the Internet. The use of inline images and
- other associated data often require a client to make multiple
- requests of the same server in a short amount of time. Analysis of
- these performance problems and results from a prototype
- implementation are available [26] [30]. Implementation experience and
- measurements of actual HTTP/1.1 (RFC 2068) implementations show good
- results [39]. Alternatives have also been explored, for example,
- T/TCP [27].
-
- Persistent HTTP connections have a number of advantages:
-
- - By opening and closing fewer TCP connections, CPU time is saved
- in routers and hosts (clients, servers, proxies, gateways,
- tunnels, or caches), and memory used for TCP protocol control
- blocks can be saved in hosts.
-
- - HTTP requests and responses can be pipelined on a connection.
- Pipelining allows a client to make multiple requests without
- waiting for each response, allowing a single TCP connection to
- be used much more efficiently, with much lower elapsed time.
-
- - Network congestion is reduced by reducing the number of packets
- caused by TCP opens, and by allowing TCP sufficient time to
- determine the congestion state of the network.
-
- - Latency on subsequent requests is reduced since there is no time
- spent in TCP's connection opening handshake.
-
- - HTTP can evolve more gracefully, since errors can be reported
- without the penalty of closing the TCP connection. Clients using
- future versions of HTTP might optimistically try a new feature,
- but if communicating with an older server, retry with old
- semantics after an error is reported.
-
- HTTP implementations SHOULD implement persistent connections.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 44]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.1.2 Overall Operation
-
- A significant difference between HTTP/1.1 and earlier versions of
- HTTP is that persistent connections are the default behavior of any
- HTTP connection. That is, unless otherwise indicated, the client
- SHOULD assume that the server will maintain a persistent connection,
- even after error responses from the server.
-
- Persistent connections provide a mechanism by which a client and a
- server can signal the close of a TCP connection. This signaling takes
- place using the Connection header field (section 14.10). Once a close
- has been signaled, the client MUST NOT send any more requests on that
- connection.
-
-8.1.2.1 Negotiation
-
- An HTTP/1.1 server MAY assume that a HTTP/1.1 client intends to
- maintain a persistent connection unless a Connection header including
- the connection-token "close" was sent in the request. If the server
- chooses to close the connection immediately after sending the
- response, it SHOULD send a Connection header including the
- connection-token close.
-
- An HTTP/1.1 client MAY expect a connection to remain open, but would
- decide to keep it open based on whether the response from a server
- contains a Connection header with the connection-token close. In case
- the client does not want to maintain a connection for more than that
- request, it SHOULD send a Connection header including the
- connection-token close.
-
- If either the client or the server sends the close token in the
- Connection header, that request becomes the last one for the
- connection.
-
- Clients and servers SHOULD NOT assume that a persistent connection is
- maintained for HTTP versions less than 1.1 unless it is explicitly
- signaled. See section 19.6.2 for more information on backward
- compatibility with HTTP/1.0 clients.
-
- In order to remain persistent, all messages on the connection MUST
- have a self-defined message length (i.e., one not defined by closure
- of the connection), as described in section 4.4.
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 45]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.1.2.2 Pipelining
-
- A client that supports persistent connections MAY "pipeline" its
- requests (i.e., send multiple requests without waiting for each
- response). A server MUST send its responses to those requests in the
- same order that the requests were received.
-
- Clients which assume persistent connections and pipeline immediately
- after connection establishment SHOULD be prepared to retry their
- connection if the first pipelined attempt fails. If a client does
- such a retry, it MUST NOT pipeline before it knows the connection is
- persistent. Clients MUST also be prepared to resend their requests if
- the server closes the connection before sending all of the
- corresponding responses.
-
- Clients SHOULD NOT pipeline requests using non-idempotent methods or
- non-idempotent sequences of methods (see section 9.1.2). Otherwise, a
- premature termination of the transport connection could lead to
- indeterminate results. A client wishing to send a non-idempotent
- request SHOULD wait to send that request until it has received the
- response status for the previous request.
-
-8.1.3 Proxy Servers
-
- It is especially important that proxies correctly implement the
- properties of the Connection header field as specified in section
- 14.10.
-
- The proxy server MUST signal persistent connections separately with
- its clients and the origin servers (or other proxy servers) that it
- connects to. Each persistent connection applies to only one transport
- link.
-
- A proxy server MUST NOT establish a HTTP/1.1 persistent connection
- with an HTTP/1.0 client (but see RFC 2068 [33] for information and
- discussion of the problems with the Keep-Alive header implemented by
- many HTTP/1.0 clients).
-
-8.1.4 Practical Considerations
-
- Servers will usually have some time-out value beyond which they will
- no longer maintain an inactive connection. Proxy servers might make
- this a higher value since it is likely that the client will be making
- more connections through the same server. The use of persistent
- connections places no requirements on the length (or existence) of
- this time-out for either the client or the server.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 46]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- When a client or server wishes to time-out it SHOULD issue a graceful
- close on the transport connection. Clients and servers SHOULD both
- constantly watch for the other side of the transport close, and
- respond to it as appropriate. If a client or server does not detect
- the other side's close promptly it could cause unnecessary resource
- drain on the network.
-
- A client, server, or proxy MAY close the transport connection at any
- time. For example, a client might have started to send a new request
- at the same time that the server has decided to close the "idle"
- connection. From the server's point of view, the connection is being
- closed while it was idle, but from the client's point of view, a
- request is in progress.
-
- This means that clients, servers, and proxies MUST be able to recover
- from asynchronous close events. Client software SHOULD reopen the
- transport connection and retransmit the aborted sequence of requests
- without user interaction so long as the request sequence is
- idempotent (see section 9.1.2). Non-idempotent methods or sequences
- MUST NOT be automatically retried, although user agents MAY offer a
- human operator the choice of retrying the request(s). Confirmation by
- user-agent software with semantic understanding of the application
- MAY substitute for user confirmation. The automatic retry SHOULD NOT
- be repeated if the second sequence of requests fails.
-
- Servers SHOULD always respond to at least one request per connection,
- if at all possible. Servers SHOULD NOT close a connection in the
- middle of transmitting a response, unless a network or client failure
- is suspected.
-
- Clients that use persistent connections SHOULD limit the number of
- simultaneous connections that they maintain to a given server. A
- single-user client SHOULD NOT maintain more than 2 connections with
- any server or proxy. A proxy SHOULD use up to 2*N connections to
- another server or proxy, where N is the number of simultaneously
- active users. These guidelines are intended to improve HTTP response
- times and avoid congestion.
-
-8.2 Message Transmission Requirements
-
-8.2.1 Persistent Connections and Flow Control
-
- HTTP/1.1 servers SHOULD maintain persistent connections and use TCP's
- flow control mechanisms to resolve temporary overloads, rather than
- terminating connections with the expectation that clients will retry.
- The latter technique can exacerbate network congestion.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 47]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-8.2.2 Monitoring Connections for Error Status Messages
-
- An HTTP/1.1 (or later) client sending a message-body SHOULD monitor
- the network connection for an error status while it is transmitting
- the request. If the client sees an error status, it SHOULD
- immediately cease transmitting the body. If the body is being sent
- using a "chunked" encoding (section 3.6), a zero length chunk and
- empty trailer MAY be used to prematurely mark the end of the message.
- If the body was preceded by a Content-Length header, the client MUST
- close the connection.
-
-8.2.3 Use of the 100 (Continue) Status
-
- The purpose of the 100 (Continue) status (see section 10.1.1) is to
- allow a client that is sending a request message with a request body
- to determine if the origin server is willing to accept the request
- (based on the request headers) before the client sends the request
- body. In some cases, it might either be inappropriate or highly
- inefficient for the client to send the body if the server will reject
- the message without looking at the body.
-
- Requirements for HTTP/1.1 clients:
-
- - If a client will wait for a 100 (Continue) response before
- sending the request body, it MUST send an Expect request-header
- field (section 14.20) with the "100-continue" expectation.
-
- - A client MUST NOT send an Expect request-header field (section
- 14.20) with the "100-continue" expectation if it does not intend
- to send a request body.
-
- Because of the presence of older implementations, the protocol allows
- ambiguous situations in which a client may send "Expect: 100-
- continue" without receiving either a 417 (Expectation Failed) status
- or a 100 (Continue) status. Therefore, when a client sends this
- header field to an origin server (possibly via a proxy) from which it
- has never seen a 100 (Continue) status, the client SHOULD NOT wait
- for an indefinite period before sending the request body.
-
- Requirements for HTTP/1.1 origin servers:
-
- - Upon receiving a request which includes an Expect request-header
- field with the "100-continue" expectation, an origin server MUST
- either respond with 100 (Continue) status and continue to read
- from the input stream, or respond with a final status code. The
- origin server MUST NOT wait for the request body before sending
- the 100 (Continue) response. If it responds with a final status
- code, it MAY close the transport connection or it MAY continue
-
-
-
-Fielding, et al. Standards Track [Page 48]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- to read and discard the rest of the request. It MUST NOT
- perform the requested method if it returns a final status code.
-
- - An origin server SHOULD NOT send a 100 (Continue) response if
- the request message does not include an Expect request-header
- field with the "100-continue" expectation, and MUST NOT send a
- 100 (Continue) response if such a request comes from an HTTP/1.0
- (or earlier) client. There is an exception to this rule: for
- compatibility with RFC 2068, a server MAY send a 100 (Continue)
- status in response to an HTTP/1.1 PUT or POST request that does
- not include an Expect request-header field with the "100-
- continue" expectation. This exception, the purpose of which is
- to minimize any client processing delays associated with an
- undeclared wait for 100 (Continue) status, applies only to
- HTTP/1.1 requests, and not to requests with any other HTTP-
- version value.
-
- - An origin server MAY omit a 100 (Continue) response if it has
- already received some or all of the request body for the
- corresponding request.
-
- - An origin server that sends a 100 (Continue) response MUST
- ultimately send a final status code, once the request body is
- received and processed, unless it terminates the transport
- connection prematurely.
-
- - If an origin server receives a request that does not include an
- Expect request-header field with the "100-continue" expectation,
- the request includes a request body, and the server responds
- with a final status code before reading the entire request body
- from the transport connection, then the server SHOULD NOT close
- the transport connection until it has read the entire request,
- or until the client closes the connection. Otherwise, the client
- might not reliably receive the response message. However, this
- requirement is not be construed as preventing a server from
- defending itself against denial-of-service attacks, or from
- badly broken client implementations.
-
- Requirements for HTTP/1.1 proxies:
-
- - If a proxy receives a request that includes an Expect request-
- header field with the "100-continue" expectation, and the proxy
- either knows that the next-hop server complies with HTTP/1.1 or
- higher, or does not know the HTTP version of the next-hop
- server, it MUST forward the request, including the Expect header
- field.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 49]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If the proxy knows that the version of the next-hop server is
- HTTP/1.0 or lower, it MUST NOT forward the request, and it MUST
- respond with a 417 (Expectation Failed) status.
-
- - Proxies SHOULD maintain a cache recording the HTTP version
- numbers received from recently-referenced next-hop servers.
-
- - A proxy MUST NOT forward a 100 (Continue) response if the
- request message was received from an HTTP/1.0 (or earlier)
- client and did not include an Expect request-header field with
- the "100-continue" expectation. This requirement overrides the
- general rule for forwarding of 1xx responses (see section 10.1).
-
-8.2.4 Client Behavior if Server Prematurely Closes Connection
-
- If an HTTP/1.1 client sends a request which includes a request body,
- but which does not include an Expect request-header field with the
- "100-continue" expectation, and if the client is not directly
- connected to an HTTP/1.1 origin server, and if the client sees the
- connection close before receiving any status from the server, the
- client SHOULD retry the request. If the client does retry this
- request, it MAY use the following "binary exponential backoff"
- algorithm to be assured of obtaining a reliable response:
-
- 1. Initiate a new connection to the server
-
- 2. Transmit the request-headers
-
- 3. Initialize a variable R to the estimated round-trip time to the
- server (e.g., based on the time it took to establish the
- connection), or to a constant value of 5 seconds if the round-
- trip time is not available.
-
- 4. Compute T = R * (2**N), where N is the number of previous
- retries of this request.
-
- 5. Wait either for an error response from the server, or for T
- seconds (whichever comes first)
-
- 6. If no error response is received, after T seconds transmit the
- body of the request.
-
- 7. If client sees that the connection is closed prematurely,
- repeat from step 1 until the request is accepted, an error
- response is received, or the user becomes impatient and
- terminates the retry process.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 50]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If at any point an error status is received, the client
-
- - SHOULD NOT continue and
-
- - SHOULD close the connection if it has not completed sending the
- request message.
-
-9 Method Definitions
-
- The set of common methods for HTTP/1.1 is defined below. Although
- this set can be expanded, additional methods cannot be assumed to
- share the same semantics for separately extended clients and servers.
-
- The Host request-header field (section 14.23) MUST accompany all
- HTTP/1.1 requests.
-
-9.1 Safe and Idempotent Methods
-
-9.1.1 Safe Methods
-
- Implementors should be aware that the software represents the user in
- their interactions over the Internet, and should be careful to allow
- the user to be aware of any actions they might take which may have an
- unexpected significance to themselves or others.
-
- In particular, the convention has been established that the GET and
- HEAD methods SHOULD NOT have the significance of taking an action
- other than retrieval. These methods ought to be considered "safe".
- This allows user agents to represent other methods, such as POST, PUT
- and DELETE, in a special way, so that the user is made aware of the
- fact that a possibly unsafe action is being requested.
-
- Naturally, it is not possible to ensure that the server does not
- generate side-effects as a result of performing a GET request; in
- fact, some dynamic resources consider that a feature. The important
- distinction here is that the user did not request the side-effects,
- so therefore cannot be held accountable for them.
-
-9.1.2 Idempotent Methods
-
- Methods can also have the property of "idempotence" in that (aside
- from error or expiration issues) the side-effects of N > 0 identical
- requests is the same as for a single request. The methods GET, HEAD,
- PUT and DELETE share this property. Also, the methods OPTIONS and
- TRACE SHOULD NOT have side effects, and so are inherently idempotent.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 51]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- However, it is possible that a sequence of several requests is non-
- idempotent, even if all of the methods executed in that sequence are
- idempotent. (A sequence is idempotent if a single execution of the
- entire sequence always yields a result that is not changed by a
- reexecution of all, or part, of that sequence.) For example, a
- sequence is non-idempotent if its result depends on a value that is
- later modified in the same sequence.
-
- A sequence that never has side effects is idempotent, by definition
- (provided that no concurrent operations are being executed on the
- same set of resources).
-
-9.2 OPTIONS
-
- The OPTIONS method represents a request for information about the
- communication options available on the request/response chain
- identified by the Request-URI. This method allows the client to
- determine the options and/or requirements associated with a resource,
- or the capabilities of a server, without implying a resource action
- or initiating a resource retrieval.
-
- Responses to this method are not cacheable.
-
- If the OPTIONS request includes an entity-body (as indicated by the
- presence of Content-Length or Transfer-Encoding), then the media type
- MUST be indicated by a Content-Type field. Although this
- specification does not define any use for such a body, future
- extensions to HTTP might use the OPTIONS body to make more detailed
- queries on the server. A server that does not support such an
- extension MAY discard the request body.
-
- If the Request-URI is an asterisk ("*"), the OPTIONS request is
- intended to apply to the server in general rather than to a specific
- resource. Since a server's communication options typically depend on
- the resource, the "*" request is only useful as a "ping" or "no-op"
- type of method; it does nothing beyond allowing the client to test
- the capabilities of the server. For example, this can be used to test
- a proxy for HTTP/1.1 compliance (or lack thereof).
-
- If the Request-URI is not an asterisk, the OPTIONS request applies
- only to the options that are available when communicating with that
- resource.
-
- A 200 response SHOULD include any header fields that indicate
- optional features implemented by the server and applicable to that
- resource (e.g., Allow), possibly including extensions not defined by
- this specification. The response body, if any, SHOULD also include
- information about the communication options. The format for such a
-
-
-
-Fielding, et al. Standards Track [Page 52]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- body is not defined by this specification, but might be defined by
- future extensions to HTTP. Content negotiation MAY be used to select
- the appropriate response format. If no response body is included, the
- response MUST include a Content-Length field with a field-value of
- "0".
-
- The Max-Forwards request-header field MAY be used to target a
- specific proxy in the request chain. When a proxy receives an OPTIONS
- request on an absoluteURI for which request forwarding is permitted,
- the proxy MUST check for a Max-Forwards field. If the Max-Forwards
- field-value is zero ("0"), the proxy MUST NOT forward the message;
- instead, the proxy SHOULD respond with its own communication options.
- If the Max-Forwards field-value is an integer greater than zero, the
- proxy MUST decrement the field-value when it forwards the request. If
- no Max-Forwards field is present in the request, then the forwarded
- request MUST NOT include a Max-Forwards field.
-
-9.3 GET
-
- The GET method means retrieve whatever information (in the form of an
- entity) is identified by the Request-URI. If the Request-URI refers
- to a data-producing process, it is the produced data which shall be
- returned as the entity in the response and not the source text of the
- process, unless that text happens to be the output of the process.
-
- The semantics of the GET method change to a "conditional GET" if the
- request message includes an If-Modified-Since, If-Unmodified-Since,
- If-Match, If-None-Match, or If-Range header field. A conditional GET
- method requests that the entity be transferred only under the
- circumstances described by the conditional header field(s). The
- conditional GET method is intended to reduce unnecessary network
- usage by allowing cached entities to be refreshed without requiring
- multiple requests or transferring data already held by the client.
-
- The semantics of the GET method change to a "partial GET" if the
- request message includes a Range header field. A partial GET requests
- that only part of the entity be transferred, as described in section
- 14.35. The partial GET method is intended to reduce unnecessary
- network usage by allowing partially-retrieved entities to be
- completed without transferring data already held by the client.
-
- The response to a GET request is cacheable if and only if it meets
- the requirements for HTTP caching described in section 13.
-
- See section 15.1.3 for security considerations when used for forms.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 53]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-9.4 HEAD
-
- The HEAD method is identical to GET except that the server MUST NOT
- return a message-body in the response. The metainformation contained
- in the HTTP headers in response to a HEAD request SHOULD be identical
- to the information sent in response to a GET request. This method can
- be used for obtaining metainformation about the entity implied by the
- request without transferring the entity-body itself. This method is
- often used for testing hypertext links for validity, accessibility,
- and recent modification.
-
- The response to a HEAD request MAY be cacheable in the sense that the
- information contained in the response MAY be used to update a
- previously cached entity from that resource. If the new field values
- indicate that the cached entity differs from the current entity (as
- would be indicated by a change in Content-Length, Content-MD5, ETag
- or Last-Modified), then the cache MUST treat the cache entry as
- stale.
-
-9.5 POST
-
- The POST method is used to request that the origin server accept the
- entity enclosed in the request as a new subordinate of the resource
- identified by the Request-URI in the Request-Line. POST is designed
- to allow a uniform method to cover the following functions:
-
- - Annotation of existing resources;
-
- - Posting a message to a bulletin board, newsgroup, mailing list,
- or similar group of articles;
-
- - Providing a block of data, such as the result of submitting a
- form, to a data-handling process;
-
- - Extending a database through an append operation.
-
- The actual function performed by the POST method is determined by the
- server and is usually dependent on the Request-URI. The posted entity
- is subordinate to that URI in the same way that a file is subordinate
- to a directory containing it, a news article is subordinate to a
- newsgroup to which it is posted, or a record is subordinate to a
- database.
-
- The action performed by the POST method might not result in a
- resource that can be identified by a URI. In this case, either 200
- (OK) or 204 (No Content) is the appropriate response status,
- depending on whether or not the response includes an entity that
- describes the result.
-
-
-
-Fielding, et al. Standards Track [Page 54]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If a resource has been created on the origin server, the response
- SHOULD be 201 (Created) and contain an entity which describes the
- status of the request and refers to the new resource, and a Location
- header (see section 14.30).
-
- Responses to this method are not cacheable, unless the response
- includes appropriate Cache-Control or Expires header fields. However,
- the 303 (See Other) response can be used to direct the user agent to
- retrieve a cacheable resource.
-
- POST requests MUST obey the message transmission requirements set out
- in section 8.2.
-
- See section 15.1.3 for security considerations.
-
-9.6 PUT
-
- The PUT method requests that the enclosed entity be stored under the
- supplied Request-URI. If the Request-URI refers to an already
- existing resource, the enclosed entity SHOULD be considered as a
- modified version of the one residing on the origin server. If the
- Request-URI does not point to an existing resource, and that URI is
- capable of being defined as a new resource by the requesting user
- agent, the origin server can create the resource with that URI. If a
- new resource is created, the origin server MUST inform the user agent
- via the 201 (Created) response. If an existing resource is modified,
- either the 200 (OK) or 204 (No Content) response codes SHOULD be sent
- to indicate successful completion of the request. If the resource
- could not be created or modified with the Request-URI, an appropriate
- error response SHOULD be given that reflects the nature of the
- problem. The recipient of the entity MUST NOT ignore any Content-*
- (e.g. Content-Range) headers that it does not understand or implement
- and MUST return a 501 (Not Implemented) response in such cases.
-
- If the request passes through a cache and the Request-URI identifies
- one or more currently cached entities, those entries SHOULD be
- treated as stale. Responses to this method are not cacheable.
-
- The fundamental difference between the POST and PUT requests is
- reflected in the different meaning of the Request-URI. The URI in a
- POST request identifies the resource that will handle the enclosed
- entity. That resource might be a data-accepting process, a gateway to
- some other protocol, or a separate entity that accepts annotations.
- In contrast, the URI in a PUT request identifies the entity enclosed
- with the request -- the user agent knows what URI is intended and the
- server MUST NOT attempt to apply the request to some other resource.
- If the server desires that the request be applied to a different URI,
-
-
-
-
-Fielding, et al. Standards Track [Page 55]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- it MUST send a 301 (Moved Permanently) response; the user agent MAY
- then make its own decision regarding whether or not to redirect the
- request.
-
- A single resource MAY be identified by many different URIs. For
- example, an article might have a URI for identifying "the current
- version" which is separate from the URI identifying each particular
- version. In this case, a PUT request on a general URI might result in
- several other URIs being defined by the origin server.
-
- HTTP/1.1 does not define how a PUT method affects the state of an
- origin server.
-
- PUT requests MUST obey the message transmission requirements set out
- in section 8.2.
-
- Unless otherwise specified for a particular entity-header, the
- entity-headers in the PUT request SHOULD be applied to the resource
- created or modified by the PUT.
-
-9.7 DELETE
-
- The DELETE method requests that the origin server delete the resource
- identified by the Request-URI. This method MAY be overridden by human
- intervention (or other means) on the origin server. The client cannot
- be guaranteed that the operation has been carried out, even if the
- status code returned from the origin server indicates that the action
- has been completed successfully. However, the server SHOULD NOT
- indicate success unless, at the time the response is given, it
- intends to delete the resource or move it to an inaccessible
- location.
-
- A successful response SHOULD be 200 (OK) if the response includes an
- entity describing the status, 202 (Accepted) if the action has not
- yet been enacted, or 204 (No Content) if the action has been enacted
- but the response does not include an entity.
-
- If the request passes through a cache and the Request-URI identifies
- one or more currently cached entities, those entries SHOULD be
- treated as stale. Responses to this method are not cacheable.
-
-9.8 TRACE
-
- The TRACE method is used to invoke a remote, application-layer loop-
- back of the request message. The final recipient of the request
- SHOULD reflect the message received back to the client as the
- entity-body of a 200 (OK) response. The final recipient is either the
-
-
-
-
-Fielding, et al. Standards Track [Page 56]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- origin server or the first proxy or gateway to receive a Max-Forwards
- value of zero (0) in the request (see section 14.31). A TRACE request
- MUST NOT include an entity.
-
- TRACE allows the client to see what is being received at the other
- end of the request chain and use that data for testing or diagnostic
- information. The value of the Via header field (section 14.45) is of
- particular interest, since it acts as a trace of the request chain.
- Use of the Max-Forwards header field allows the client to limit the
- length of the request chain, which is useful for testing a chain of
- proxies forwarding messages in an infinite loop.
-
- If the request is valid, the response SHOULD contain the entire
- request message in the entity-body, with a Content-Type of
- "message/http". Responses to this method MUST NOT be cached.
-
-9.9 CONNECT
-
- This specification reserves the method name CONNECT for use with a
- proxy that can dynamically switch to being a tunnel (e.g. SSL
- tunneling [44]).
-
-10 Status Code Definitions
-
- Each Status-Code is described below, including a description of which
- method(s) it can follow and any metainformation required in the
- response.
-
-10.1 Informational 1xx
-
- This class of status code indicates a provisional response,
- consisting only of the Status-Line and optional headers, and is
- terminated by an empty line. There are no required headers for this
- class of status code. Since HTTP/1.0 did not define any 1xx status
- codes, servers MUST NOT send a 1xx response to an HTTP/1.0 client
- except under experimental conditions.
-
- A client MUST be prepared to accept one or more 1xx status responses
- prior to a regular response, even if the client does not expect a 100
- (Continue) status message. Unexpected 1xx status responses MAY be
- ignored by a user agent.
-
- Proxies MUST forward 1xx responses, unless the connection between the
- proxy and its client has been closed, or unless the proxy itself
- requested the generation of the 1xx response. (For example, if a
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 57]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- proxy adds a "Expect: 100-continue" field when it forwards a request,
- then it need not forward the corresponding 100 (Continue)
- response(s).)
-
-10.1.1 100 Continue
-
- The client SHOULD continue with its request. This interim response is
- used to inform the client that the initial part of the request has
- been received and has not yet been rejected by the server. The client
- SHOULD continue by sending the remainder of the request or, if the
- request has already been completed, ignore this response. The server
- MUST send a final response after the request has been completed. See
- section 8.2.3 for detailed discussion of the use and handling of this
- status code.
-
-10.1.2 101 Switching Protocols
-
- The server understands and is willing to comply with the client's
- request, via the Upgrade message header field (section 14.42), for a
- change in the application protocol being used on this connection. The
- server will switch protocols to those defined by the response's
- Upgrade header field immediately after the empty line which
- terminates the 101 response.
-
- The protocol SHOULD be switched only when it is advantageous to do
- so. For example, switching to a newer version of HTTP is advantageous
- over older versions, and switching to a real-time, synchronous
- protocol might be advantageous when delivering resources that use
- such features.
-
-10.2 Successful 2xx
-
- This class of status code indicates that the client's request was
- successfully received, understood, and accepted.
-
-10.2.1 200 OK
-
- The request has succeeded. The information returned with the response
- is dependent on the method used in the request, for example:
-
- GET an entity corresponding to the requested resource is sent in
- the response;
-
- HEAD the entity-header fields corresponding to the requested
- resource are sent in the response without any message-body;
-
- POST an entity describing or containing the result of the action;
-
-
-
-
-Fielding, et al. Standards Track [Page 58]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- TRACE an entity containing the request message as received by the
- end server.
-
-10.2.2 201 Created
-
- The request has been fulfilled and resulted in a new resource being
- created. The newly created resource can be referenced by the URI(s)
- returned in the entity of the response, with the most specific URI
- for the resource given by a Location header field. The response
- SHOULD include an entity containing a list of resource
- characteristics and location(s) from which the user or user agent can
- choose the one most appropriate. The entity format is specified by
- the media type given in the Content-Type header field. The origin
- server MUST create the resource before returning the 201 status code.
- If the action cannot be carried out immediately, the server SHOULD
- respond with 202 (Accepted) response instead.
-
- A 201 response MAY contain an ETag response header field indicating
- the current value of the entity tag for the requested variant just
- created, see section 14.19.
-
-10.2.3 202 Accepted
-
- The request has been accepted for processing, but the processing has
- not been completed. The request might or might not eventually be
- acted upon, as it might be disallowed when processing actually takes
- place. There is no facility for re-sending a status code from an
- asynchronous operation such as this.
-
- The 202 response is intentionally non-committal. Its purpose is to
- allow a server to accept a request for some other process (perhaps a
- batch-oriented process that is only run once per day) without
- requiring that the user agent's connection to the server persist
- until the process is completed. The entity returned with this
- response SHOULD include an indication of the request's current status
- and either a pointer to a status monitor or some estimate of when the
- user can expect the request to be fulfilled.
-
-10.2.4 203 Non-Authoritative Information
-
- The returned metainformation in the entity-header is not the
- definitive set as available from the origin server, but is gathered
- from a local or a third-party copy. The set presented MAY be a subset
- or superset of the original version. For example, including local
- annotation information about the resource might result in a superset
- of the metainformation known by the origin server. Use of this
- response code is not required and is only appropriate when the
- response would otherwise be 200 (OK).
-
-
-
-Fielding, et al. Standards Track [Page 59]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.2.5 204 No Content
-
- The server has fulfilled the request but does not need to return an
- entity-body, and might want to return updated metainformation. The
- response MAY include new or updated metainformation in the form of
- entity-headers, which if present SHOULD be associated with the
- requested variant.
-
- If the client is a user agent, it SHOULD NOT change its document view
- from that which caused the request to be sent. This response is
- primarily intended to allow input for actions to take place without
- causing a change to the user agent's active document view, although
- any new or updated metainformation SHOULD be applied to the document
- currently in the user agent's active view.
-
- The 204 response MUST NOT include a message-body, and thus is always
- terminated by the first empty line after the header fields.
-
-10.2.6 205 Reset Content
-
- The server has fulfilled the request and the user agent SHOULD reset
- the document view which caused the request to be sent. This response
- is primarily intended to allow input for actions to take place via
- user input, followed by a clearing of the form in which the input is
- given so that the user can easily initiate another input action. The
- response MUST NOT include an entity.
-
-10.2.7 206 Partial Content
-
- The server has fulfilled the partial GET request for the resource.
- The request MUST have included a Range header field (section 14.35)
- indicating the desired range, and MAY have included an If-Range
- header field (section 14.27) to make the request conditional.
-
- The response MUST include the following header fields:
-
- - Either a Content-Range header field (section 14.16) indicating
- the range included with this response, or a multipart/byteranges
- Content-Type including Content-Range fields for each part. If a
- Content-Length header field is present in the response, its
- value MUST match the actual number of OCTETs transmitted in the
- message-body.
-
- - Date
-
- - ETag and/or Content-Location, if the header would have been sent
- in a 200 response to the same request
-
-
-
-
-Fielding, et al. Standards Track [Page 60]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - Expires, Cache-Control, and/or Vary, if the field-value might
- differ from that sent in any previous response for the same
- variant
-
- If the 206 response is the result of an If-Range request that used a
- strong cache validator (see section 13.3.3), the response SHOULD NOT
- include other entity-headers. If the response is the result of an
- If-Range request that used a weak validator, the response MUST NOT
- include other entity-headers; this prevents inconsistencies between
- cached entity-bodies and updated headers. Otherwise, the response
- MUST include all of the entity-headers that would have been returned
- with a 200 (OK) response to the same request.
-
- A cache MUST NOT combine a 206 response with other previously cached
- content if the ETag or Last-Modified headers do not match exactly,
- see 13.5.4.
-
- A cache that does not support the Range and Content-Range headers
- MUST NOT cache 206 (Partial) responses.
-
-10.3 Redirection 3xx
-
- This class of status code indicates that further action needs to be
- taken by the user agent in order to fulfill the request. The action
- required MAY be carried out by the user agent without interaction
- with the user if and only if the method used in the second request is
- GET or HEAD. A client SHOULD detect infinite redirection loops, since
- such loops generate network traffic for each redirection.
-
- Note: previous versions of this specification recommended a
- maximum of five redirections. Content developers should be aware
- that there might be clients that implement such a fixed
- limitation.
-
-10.3.1 300 Multiple Choices
-
- The requested resource corresponds to any one of a set of
- representations, each with its own specific location, and agent-
- driven negotiation information (section 12) is being provided so that
- the user (or user agent) can select a preferred representation and
- redirect its request to that location.
-
- Unless it was a HEAD request, the response SHOULD include an entity
- containing a list of resource characteristics and location(s) from
- which the user or user agent can choose the one most appropriate. The
- entity format is specified by the media type given in the Content-
- Type header field. Depending upon the format and the capabilities of
-
-
-
-
-Fielding, et al. Standards Track [Page 61]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- the user agent, selection of the most appropriate choice MAY be
- performed automatically. However, this specification does not define
- any standard for such automatic selection.
-
- If the server has a preferred choice of representation, it SHOULD
- include the specific URI for that representation in the Location
- field; user agents MAY use the Location field value for automatic
- redirection. This response is cacheable unless indicated otherwise.
-
-10.3.2 301 Moved Permanently
-
- The requested resource has been assigned a new permanent URI and any
- future references to this resource SHOULD use one of the returned
- URIs. Clients with link editing capabilities ought to automatically
- re-link references to the Request-URI to one or more of the new
- references returned by the server, where possible. This response is
- cacheable unless indicated otherwise.
-
- The new permanent URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
- If the 301 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
- Note: When automatically redirecting a POST request after
- receiving a 301 status code, some existing HTTP/1.0 user agents
- will erroneously change it into a GET request.
-
-10.3.3 302 Found
-
- The requested resource resides temporarily under a different URI.
- Since the redirection might be altered on occasion, the client SHOULD
- continue to use the Request-URI for future requests. This response
- is only cacheable if indicated by a Cache-Control or Expires header
- field.
-
- The temporary URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 62]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the 302 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
- Note: RFC 1945 and RFC 2068 specify that the client is not allowed
- to change the method on the redirected request. However, most
- existing user agent implementations treat 302 as if it were a 303
- response, performing a GET on the Location field-value regardless
- of the original request method. The status codes 303 and 307 have
- been added for servers that wish to make unambiguously clear which
- kind of reaction is expected of the client.
-
-10.3.4 303 See Other
-
- The response to the request can be found under a different URI and
- SHOULD be retrieved using a GET method on that resource. This method
- exists primarily to allow the output of a POST-activated script to
- redirect the user agent to a selected resource. The new URI is not a
- substitute reference for the originally requested resource. The 303
- response MUST NOT be cached, but the response to the second
- (redirected) request might be cacheable.
-
- The different URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s).
-
- Note: Many pre-HTTP/1.1 user agents do not understand the 303
- status. When interoperability with such clients is a concern, the
- 302 status code may be used instead, since most user agents react
- to a 302 response as described here for 303.
-
-10.3.5 304 Not Modified
-
- If the client has performed a conditional GET request and access is
- allowed, but the document has not been modified, the server SHOULD
- respond with this status code. The 304 response MUST NOT contain a
- message-body, and thus is always terminated by the first empty line
- after the header fields.
-
- The response MUST include the following header fields:
-
- - Date, unless its omission is required by section 14.18.1
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 63]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If a clockless origin server obeys these rules, and proxies and
- clients add their own Date to any response received without one (as
- already specified by [RFC 2068], section 14.19), caches will operate
- correctly.
-
- - ETag and/or Content-Location, if the header would have been sent
- in a 200 response to the same request
-
- - Expires, Cache-Control, and/or Vary, if the field-value might
- differ from that sent in any previous response for the same
- variant
-
- If the conditional GET used a strong cache validator (see section
- 13.3.3), the response SHOULD NOT include other entity-headers.
- Otherwise (i.e., the conditional GET used a weak validator), the
- response MUST NOT include other entity-headers; this prevents
- inconsistencies between cached entity-bodies and updated headers.
-
- If a 304 response indicates an entity not currently cached, then the
- cache MUST disregard the response and repeat the request without the
- conditional.
-
- If a cache uses a received 304 response to update a cache entry, the
- cache MUST update the entry to reflect any new field values given in
- the response.
-
-10.3.6 305 Use Proxy
-
- The requested resource MUST be accessed through the proxy given by
- the Location field. The Location field gives the URI of the proxy.
- The recipient is expected to repeat this single request via the
- proxy. 305 responses MUST only be generated by origin servers.
-
- Note: RFC 2068 was not clear that 305 was intended to redirect a
- single request, and to be generated by origin servers only. Not
- observing these limitations has significant security consequences.
-
-10.3.7 306 (Unused)
-
- The 306 status code was used in a previous version of the
- specification, is no longer used, and the code is reserved.
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 64]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.3.8 307 Temporary Redirect
-
- The requested resource resides temporarily under a different URI.
- Since the redirection MAY be altered on occasion, the client SHOULD
- continue to use the Request-URI for future requests. This response
- is only cacheable if indicated by a Cache-Control or Expires header
- field.
-
- The temporary URI SHOULD be given by the Location field in the
- response. Unless the request method was HEAD, the entity of the
- response SHOULD contain a short hypertext note with a hyperlink to
- the new URI(s) , since many pre-HTTP/1.1 user agents do not
- understand the 307 status. Therefore, the note SHOULD contain the
- information necessary for a user to repeat the original request on
- the new URI.
-
- If the 307 status code is received in response to a request other
- than GET or HEAD, the user agent MUST NOT automatically redirect the
- request unless it can be confirmed by the user, since this might
- change the conditions under which the request was issued.
-
-10.4 Client Error 4xx
-
- The 4xx class of status code is intended for cases in which the
- client seems to have erred. Except when responding to a HEAD request,
- the server SHOULD include an entity containing an explanation of the
- error situation, and whether it is a temporary or permanent
- condition. These status codes are applicable to any request method.
- User agents SHOULD display any included entity to the user.
-
- If the client is sending data, a server implementation using TCP
- SHOULD be careful to ensure that the client acknowledges receipt of
- the packet(s) containing the response, before the server closes the
- input connection. If the client continues sending data to the server
- after the close, the server's TCP stack will send a reset packet to
- the client, which may erase the client's unacknowledged input buffers
- before they can be read and interpreted by the HTTP application.
-
-10.4.1 400 Bad Request
-
- The request could not be understood by the server due to malformed
- syntax. The client SHOULD NOT repeat the request without
- modifications.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 65]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.2 401 Unauthorized
-
- The request requires user authentication. The response MUST include a
- WWW-Authenticate header field (section 14.47) containing a challenge
- applicable to the requested resource. The client MAY repeat the
- request with a suitable Authorization header field (section 14.8). If
- the request already included Authorization credentials, then the 401
- response indicates that authorization has been refused for those
- credentials. If the 401 response contains the same challenge as the
- prior response, and the user agent has already attempted
- authentication at least once, then the user SHOULD be presented the
- entity that was given in the response, since that entity might
- include relevant diagnostic information. HTTP access authentication
- is explained in "HTTP Authentication: Basic and Digest Access
- Authentication" [43].
-
-10.4.3 402 Payment Required
-
- This code is reserved for future use.
-
-10.4.4 403 Forbidden
-
- The server understood the request, but is refusing to fulfill it.
- Authorization will not help and the request SHOULD NOT be repeated.
- If the request method was not HEAD and the server wishes to make
- public why the request has not been fulfilled, it SHOULD describe the
- reason for the refusal in the entity. If the server does not wish to
- make this information available to the client, the status code 404
- (Not Found) can be used instead.
-
-10.4.5 404 Not Found
-
- The server has not found anything matching the Request-URI. No
- indication is given of whether the condition is temporary or
- permanent. The 410 (Gone) status code SHOULD be used if the server
- knows, through some internally configurable mechanism, that an old
- resource is permanently unavailable and has no forwarding address.
- This status code is commonly used when the server does not wish to
- reveal exactly why the request has been refused, or when no other
- response is applicable.
-
-10.4.6 405 Method Not Allowed
-
- The method specified in the Request-Line is not allowed for the
- resource identified by the Request-URI. The response MUST include an
- Allow header containing a list of valid methods for the requested
- resource.
-
-
-
-
-Fielding, et al. Standards Track [Page 66]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.7 406 Not Acceptable
-
- The resource identified by the request is only capable of generating
- response entities which have content characteristics not acceptable
- according to the accept headers sent in the request.
-
- Unless it was a HEAD request, the response SHOULD include an entity
- containing a list of available entity characteristics and location(s)
- from which the user or user agent can choose the one most
- appropriate. The entity format is specified by the media type given
- in the Content-Type header field. Depending upon the format and the
- capabilities of the user agent, selection of the most appropriate
- choice MAY be performed automatically. However, this specification
- does not define any standard for such automatic selection.
-
- Note: HTTP/1.1 servers are allowed to return responses which are
- not acceptable according to the accept headers sent in the
- request. In some cases, this may even be preferable to sending a
- 406 response. User agents are encouraged to inspect the headers of
- an incoming response to determine if it is acceptable.
-
- If the response could be unacceptable, a user agent SHOULD
- temporarily stop receipt of more data and query the user for a
- decision on further actions.
-
-10.4.8 407 Proxy Authentication Required
-
- This code is similar to 401 (Unauthorized), but indicates that the
- client must first authenticate itself with the proxy. The proxy MUST
- return a Proxy-Authenticate header field (section 14.33) containing a
- challenge applicable to the proxy for the requested resource. The
- client MAY repeat the request with a suitable Proxy-Authorization
- header field (section 14.34). HTTP access authentication is explained
- in "HTTP Authentication: Basic and Digest Access Authentication"
- [43].
-
-10.4.9 408 Request Timeout
-
- The client did not produce a request within the time that the server
- was prepared to wait. The client MAY repeat the request without
- modifications at any later time.
-
-10.4.10 409 Conflict
-
- The request could not be completed due to a conflict with the current
- state of the resource. This code is only allowed in situations where
- it is expected that the user might be able to resolve the conflict
- and resubmit the request. The response body SHOULD include enough
-
-
-
-Fielding, et al. Standards Track [Page 67]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- information for the user to recognize the source of the conflict.
- Ideally, the response entity would include enough information for the
- user or user agent to fix the problem; however, that might not be
- possible and is not required.
-
- Conflicts are most likely to occur in response to a PUT request. For
- example, if versioning were being used and the entity being PUT
- included changes to a resource which conflict with those made by an
- earlier (third-party) request, the server might use the 409 response
- to indicate that it can't complete the request. In this case, the
- response entity would likely contain a list of the differences
- between the two versions in a format defined by the response
- Content-Type.
-
-10.4.11 410 Gone
-
- The requested resource is no longer available at the server and no
- forwarding address is known. This condition is expected to be
- considered permanent. Clients with link editing capabilities SHOULD
- delete references to the Request-URI after user approval. If the
- server does not know, or has no facility to determine, whether or not
- the condition is permanent, the status code 404 (Not Found) SHOULD be
- used instead. This response is cacheable unless indicated otherwise.
-
- The 410 response is primarily intended to assist the task of web
- maintenance by notifying the recipient that the resource is
- intentionally unavailable and that the server owners desire that
- remote links to that resource be removed. Such an event is common for
- limited-time, promotional services and for resources belonging to
- individuals no longer working at the server's site. It is not
- necessary to mark all permanently unavailable resources as "gone" or
- to keep the mark for any length of time -- that is left to the
- discretion of the server owner.
-
-10.4.12 411 Length Required
-
- The server refuses to accept the request without a defined Content-
- Length. The client MAY repeat the request if it adds a valid
- Content-Length header field containing the length of the message-body
- in the request message.
-
-10.4.13 412 Precondition Failed
-
- The precondition given in one or more of the request-header fields
- evaluated to false when it was tested on the server. This response
- code allows the client to place preconditions on the current resource
- metainformation (header field data) and thus prevent the requested
- method from being applied to a resource other than the one intended.
-
-
-
-Fielding, et al. Standards Track [Page 68]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.14 413 Request Entity Too Large
-
- The server is refusing to process a request because the request
- entity is larger than the server is willing or able to process. The
- server MAY close the connection to prevent the client from continuing
- the request.
-
- If the condition is temporary, the server SHOULD include a Retry-
- After header field to indicate that it is temporary and after what
- time the client MAY try again.
-
-10.4.15 414 Request-URI Too Long
-
- The server is refusing to service the request because the Request-URI
- is longer than the server is willing to interpret. This rare
- condition is only likely to occur when a client has improperly
- converted a POST request to a GET request with long query
- information, when the client has descended into a URI "black hole" of
- redirection (e.g., a redirected URI prefix that points to a suffix of
- itself), or when the server is under attack by a client attempting to
- exploit security holes present in some servers using fixed-length
- buffers for reading or manipulating the Request-URI.
-
-10.4.16 415 Unsupported Media Type
-
- The server is refusing to service the request because the entity of
- the request is in a format not supported by the requested resource
- for the requested method.
-
-10.4.17 416 Requested Range Not Satisfiable
-
- A server SHOULD return a response with this status code if a request
- included a Range request-header field (section 14.35), and none of
- the range-specifier values in this field overlap the current extent
- of the selected resource, and the request did not include an If-Range
- request-header field. (For byte-ranges, this means that the first-
- byte-pos of all of the byte-range-spec values were greater than the
- current length of the selected resource.)
-
- When this status code is returned for a byte-range request, the
- response SHOULD include a Content-Range entity-header field
- specifying the current length of the selected resource (see section
- 14.16). This response MUST NOT use the multipart/byteranges content-
- type.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 69]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.4.18 417 Expectation Failed
-
- The expectation given in an Expect request-header field (see section
- 14.20) could not be met by this server, or, if the server is a proxy,
- the server has unambiguous evidence that the request could not be met
- by the next-hop server.
-
-10.5 Server Error 5xx
-
- Response status codes beginning with the digit "5" indicate cases in
- which the server is aware that it has erred or is incapable of
- performing the request. Except when responding to a HEAD request, the
- server SHOULD include an entity containing an explanation of the
- error situation, and whether it is a temporary or permanent
- condition. User agents SHOULD display any included entity to the
- user. These response codes are applicable to any request method.
-
-10.5.1 500 Internal Server Error
-
- The server encountered an unexpected condition which prevented it
- from fulfilling the request.
-
-10.5.2 501 Not Implemented
-
- The server does not support the functionality required to fulfill the
- request. This is the appropriate response when the server does not
- recognize the request method and is not capable of supporting it for
- any resource.
-
-10.5.3 502 Bad Gateway
-
- The server, while acting as a gateway or proxy, received an invalid
- response from the upstream server it accessed in attempting to
- fulfill the request.
-
-10.5.4 503 Service Unavailable
-
- The server is currently unable to handle the request due to a
- temporary overloading or maintenance of the server. The implication
- is that this is a temporary condition which will be alleviated after
- some delay. If known, the length of the delay MAY be indicated in a
- Retry-After header. If no Retry-After is given, the client SHOULD
- handle the response as it would for a 500 response.
-
- Note: The existence of the 503 status code does not imply that a
- server must use it when becoming overloaded. Some servers may wish
- to simply refuse the connection.
-
-
-
-
-Fielding, et al. Standards Track [Page 70]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-10.5.5 504 Gateway Timeout
-
- The server, while acting as a gateway or proxy, did not receive a
- timely response from the upstream server specified by the URI (e.g.
- HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed
- to access in attempting to complete the request.
-
- Note: Note to implementors: some deployed proxies are known to
- return 400 or 500 when DNS lookups time out.
-
-10.5.6 505 HTTP Version Not Supported
-
- The server does not support, or refuses to support, the HTTP protocol
- version that was used in the request message. The server is
- indicating that it is unable or unwilling to complete the request
- using the same major version as the client, as described in section
- 3.1, other than with this error message. The response SHOULD contain
- an entity describing why that version is not supported and what other
- protocols are supported by that server.
-
-11 Access Authentication
-
- HTTP provides several OPTIONAL challenge-response authentication
- mechanisms which can be used by a server to challenge a client
- request and by a client to provide authentication information. The
- general framework for access authentication, and the specification of
- "basic" and "digest" authentication, are specified in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. This
- specification adopts the definitions of "challenge" and "credentials"
- from that specification.
-
-12 Content Negotiation
-
- Most HTTP responses include an entity which contains information for
- interpretation by a human user. Naturally, it is desirable to supply
- the user with the "best available" entity corresponding to the
- request. Unfortunately for servers and caches, not all users have the
- same preferences for what is "best," and not all user agents are
- equally capable of rendering all entity types. For that reason, HTTP
- has provisions for several mechanisms for "content negotiation" --
- the process of selecting the best representation for a given response
- when there are multiple representations available.
-
- Note: This is not called "format negotiation" because the
- alternate representations may be of the same media type, but use
- different capabilities of that type, be in different languages,
- etc.
-
-
-
-
-Fielding, et al. Standards Track [Page 71]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Any response containing an entity-body MAY be subject to negotiation,
- including error responses.
-
- There are two kinds of content negotiation which are possible in
- HTTP: server-driven and agent-driven negotiation. These two kinds of
- negotiation are orthogonal and thus may be used separately or in
- combination. One method of combination, referred to as transparent
- negotiation, occurs when a cache uses the agent-driven negotiation
- information provided by the origin server in order to provide
- server-driven negotiation for subsequent requests.
-
-12.1 Server-driven Negotiation
-
- If the selection of the best representation for a response is made by
- an algorithm located at the server, it is called server-driven
- negotiation. Selection is based on the available representations of
- the response (the dimensions over which it can vary; e.g. language,
- content-coding, etc.) and the contents of particular header fields in
- the request message or on other information pertaining to the request
- (such as the network address of the client).
-
- Server-driven negotiation is advantageous when the algorithm for
- selecting from among the available representations is difficult to
- describe to the user agent, or when the server desires to send its
- "best guess" to the client along with the first response (hoping to
- avoid the round-trip delay of a subsequent request if the "best
- guess" is good enough for the user). In order to improve the server's
- guess, the user agent MAY include request header fields (Accept,
- Accept-Language, Accept-Encoding, etc.) which describe its
- preferences for such a response.
-
- Server-driven negotiation has disadvantages:
-
- 1. It is impossible for the server to accurately determine what
- might be "best" for any given user, since that would require
- complete knowledge of both the capabilities of the user agent
- and the intended use for the response (e.g., does the user want
- to view it on screen or print it on paper?).
-
- 2. Having the user agent describe its capabilities in every
- request can be both very inefficient (given that only a small
- percentage of responses have multiple representations) and a
- potential violation of the user's privacy.
-
- 3. It complicates the implementation of an origin server and the
- algorithms for generating responses to a request.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 72]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 4. It may limit a public cache's ability to use the same response
- for multiple user's requests.
-
- HTTP/1.1 includes the following request-header fields for enabling
- server-driven negotiation through description of user agent
- capabilities and user preferences: Accept (section 14.1), Accept-
- Charset (section 14.2), Accept-Encoding (section 14.3), Accept-
- Language (section 14.4), and User-Agent (section 14.43). However, an
- origin server is not limited to these dimensions and MAY vary the
- response based on any aspect of the request, including information
- outside the request-header fields or within extension header fields
- not defined by this specification.
-
- The Vary header field can be used to express the parameters the
- server uses to select a representation that is subject to server-
- driven negotiation. See section 13.6 for use of the Vary header field
- by caches and section 14.44 for use of the Vary header field by
- servers.
-
-12.2 Agent-driven Negotiation
-
- With agent-driven negotiation, selection of the best representation
- for a response is performed by the user agent after receiving an
- initial response from the origin server. Selection is based on a list
- of the available representations of the response included within the
- header fields or entity-body of the initial response, with each
- representation identified by its own URI. Selection from among the
- representations may be performed automatically (if the user agent is
- capable of doing so) or manually by the user selecting from a
- generated (possibly hypertext) menu.
-
- Agent-driven negotiation is advantageous when the response would vary
- over commonly-used dimensions (such as type, language, or encoding),
- when the origin server is unable to determine a user agent's
- capabilities from examining the request, and generally when public
- caches are used to distribute server load and reduce network usage.
-
- Agent-driven negotiation suffers from the disadvantage of needing a
- second request to obtain the best alternate representation. This
- second request is only efficient when caching is used. In addition,
- this specification does not define any mechanism for supporting
- automatic selection, though it also does not prevent any such
- mechanism from being developed as an extension and used within
- HTTP/1.1.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 73]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 defines the 300 (Multiple Choices) and 406 (Not Acceptable)
- status codes for enabling agent-driven negotiation when the server is
- unwilling or unable to provide a varying response using server-driven
- negotiation.
-
-12.3 Transparent Negotiation
-
- Transparent negotiation is a combination of both server-driven and
- agent-driven negotiation. When a cache is supplied with a form of the
- list of available representations of the response (as in agent-driven
- negotiation) and the dimensions of variance are completely understood
- by the cache, then the cache becomes capable of performing server-
- driven negotiation on behalf of the origin server for subsequent
- requests on that resource.
-
- Transparent negotiation has the advantage of distributing the
- negotiation work that would otherwise be required of the origin
- server and also removing the second request delay of agent-driven
- negotiation when the cache is able to correctly guess the right
- response.
-
- This specification does not define any mechanism for transparent
- negotiation, though it also does not prevent any such mechanism from
- being developed as an extension that could be used within HTTP/1.1.
-
-13 Caching in HTTP
-
- HTTP is typically used for distributed information systems, where
- performance can be improved by the use of response caches. The
- HTTP/1.1 protocol includes a number of elements intended to make
- caching work as well as possible. Because these elements are
- inextricable from other aspects of the protocol, and because they
- interact with each other, it is useful to describe the basic caching
- design of HTTP separately from the detailed descriptions of methods,
- headers, response codes, etc.
-
- Caching would be useless if it did not significantly improve
- performance. The goal of caching in HTTP/1.1 is to eliminate the need
- to send requests in many cases, and to eliminate the need to send
- full responses in many other cases. The former reduces the number of
- network round-trips required for many operations; we use an
- "expiration" mechanism for this purpose (see section 13.2). The
- latter reduces network bandwidth requirements; we use a "validation"
- mechanism for this purpose (see section 13.3).
-
- Requirements for performance, availability, and disconnected
- operation require us to be able to relax the goal of semantic
- transparency. The HTTP/1.1 protocol allows origin servers, caches,
-
-
-
-Fielding, et al. Standards Track [Page 74]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- and clients to explicitly reduce transparency when necessary.
- However, because non-transparent operation may confuse non-expert
- users, and might be incompatible with certain server applications
- (such as those for ordering merchandise), the protocol requires that
- transparency be relaxed
-
- - only by an explicit protocol-level request when relaxed by
- client or origin server
-
- - only with an explicit warning to the end user when relaxed by
- cache or client
-
- Therefore, the HTTP/1.1 protocol provides these important elements:
-
- 1. Protocol features that provide full semantic transparency when
- this is required by all parties.
-
- 2. Protocol features that allow an origin server or user agent to
- explicitly request and control non-transparent operation.
-
- 3. Protocol features that allow a cache to attach warnings to
- responses that do not preserve the requested approximation of
- semantic transparency.
-
- A basic principle is that it must be possible for the clients to
- detect any potential relaxation of semantic transparency.
-
- Note: The server, cache, or client implementor might be faced with
- design decisions not explicitly discussed in this specification.
- If a decision might affect semantic transparency, the implementor
- ought to err on the side of maintaining transparency unless a
- careful and complete analysis shows significant benefits in
- breaking transparency.
-
-13.1.1 Cache Correctness
-
- A correct cache MUST respond to a request with the most up-to-date
- response held by the cache that is appropriate to the request (see
- sections 13.2.5, 13.2.6, and 13.12) which meets one of the following
- conditions:
-
- 1. It has been checked for equivalence with what the origin server
- would have returned by revalidating the response with the
- origin server (section 13.3);
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 75]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 2. It is "fresh enough" (see section 13.2). In the default case,
- this means it meets the least restrictive freshness requirement
- of the client, origin server, and cache (see section 14.9); if
- the origin server so specifies, it is the freshness requirement
- of the origin server alone.
-
- If a stored response is not "fresh enough" by the most
- restrictive freshness requirement of both the client and the
- origin server, in carefully considered circumstances the cache
- MAY still return the response with the appropriate Warning
- header (see section 13.1.5 and 14.46), unless such a response
- is prohibited (e.g., by a "no-store" cache-directive, or by a
- "no-cache" cache-request-directive; see section 14.9).
-
- 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect),
- or error (4xx or 5xx) response message.
-
- If the cache can not communicate with the origin server, then a
- correct cache SHOULD respond as above if the response can be
- correctly served from the cache; if not it MUST return an error or
- warning indicating that there was a communication failure.
-
- If a cache receives a response (either an entire response, or a 304
- (Not Modified) response) that it would normally forward to the
- requesting client, and the received response is no longer fresh, the
- cache SHOULD forward it to the requesting client without adding a new
- Warning (but without removing any existing Warning headers). A cache
- SHOULD NOT attempt to revalidate a response simply because that
- response became stale in transit; this might lead to an infinite
- loop. A user agent that receives a stale response without a Warning
- MAY display a warning indication to the user.
-
-13.1.2 Warnings
-
- Whenever a cache returns a response that is neither first-hand nor
- "fresh enough" (in the sense of condition 2 in section 13.1.1), it
- MUST attach a warning to that effect, using a Warning general-header.
- The Warning header and the currently defined warnings are described
- in section 14.46. The warning allows clients to take appropriate
- action.
-
- Warnings MAY be used for other purposes, both cache-related and
- otherwise. The use of a warning, rather than an error status code,
- distinguish these responses from true failures.
-
- Warnings are assigned three digit warn-codes. The first digit
- indicates whether the Warning MUST or MUST NOT be deleted from a
- stored cache entry after a successful revalidation:
-
-
-
-Fielding, et al. Standards Track [Page 76]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1xx Warnings that describe the freshness or revalidation status of
- the response, and so MUST be deleted after a successful
- revalidation. 1XX warn-codes MAY be generated by a cache only when
- validating a cached entry. It MUST NOT be generated by clients.
-
- 2xx Warnings that describe some aspect of the entity body or entity
- headers that is not rectified by a revalidation (for example, a
- lossy compression of the entity bodies) and which MUST NOT be
- deleted after a successful revalidation.
-
- See section 14.46 for the definitions of the codes themselves.
-
- HTTP/1.0 caches will cache all Warnings in responses, without
- deleting the ones in the first category. Warnings in responses that
- are passed to HTTP/1.0 caches carry an extra warning-date field,
- which prevents a future HTTP/1.1 recipient from believing an
- erroneously cached Warning.
-
- Warnings also carry a warning text. The text MAY be in any
- appropriate natural language (perhaps based on the client's Accept
- headers), and include an OPTIONAL indication of what character set is
- used.
-
- Multiple warnings MAY be attached to a response (either by the origin
- server or by a cache), including multiple warnings with the same code
- number. For example, a server might provide the same warning with
- texts in both English and Basque.
-
- When multiple warnings are attached to a response, it might not be
- practical or reasonable to display all of them to the user. This
- version of HTTP does not specify strict priority rules for deciding
- which warnings to display and in what order, but does suggest some
- heuristics.
-
-13.1.3 Cache-control Mechanisms
-
- The basic cache mechanisms in HTTP/1.1 (server-specified expiration
- times and validators) are implicit directives to caches. In some
- cases, a server or client might need to provide explicit directives
- to the HTTP caches. We use the Cache-Control header for this purpose.
-
- The Cache-Control header allows a client or server to transmit a
- variety of directives in either requests or responses. These
- directives typically override the default caching algorithms. As a
- general rule, if there is any apparent conflict between header
- values, the most restrictive interpretation is applied (that is, the
- one that is most likely to preserve semantic transparency). However,
-
-
-
-
-Fielding, et al. Standards Track [Page 77]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- in some cases, cache-control directives are explicitly specified as
- weakening the approximation of semantic transparency (for example,
- "max-stale" or "public").
-
- The cache-control directives are described in detail in section 14.9.
-
-13.1.4 Explicit User Agent Warnings
-
- Many user agents make it possible for users to override the basic
- caching mechanisms. For example, the user agent might allow the user
- to specify that cached entities (even explicitly stale ones) are
- never validated. Or the user agent might habitually add "Cache-
- Control: max-stale=3600" to every request. The user agent SHOULD NOT
- default to either non-transparent behavior, or behavior that results
- in abnormally ineffective caching, but MAY be explicitly configured
- to do so by an explicit action of the user.
-
- If the user has overridden the basic caching mechanisms, the user
- agent SHOULD explicitly indicate to the user whenever this results in
- the display of information that might not meet the server's
- transparency requirements (in particular, if the displayed entity is
- known to be stale). Since the protocol normally allows the user agent
- to determine if responses are stale or not, this indication need only
- be displayed when this actually happens. The indication need not be a
- dialog box; it could be an icon (for example, a picture of a rotting
- fish) or some other indicator.
-
- If the user has overridden the caching mechanisms in a way that would
- abnormally reduce the effectiveness of caches, the user agent SHOULD
- continually indicate this state to the user (for example, by a
- display of a picture of currency in flames) so that the user does not
- inadvertently consume excess resources or suffer from excessive
- latency.
-
-13.1.5 Exceptions to the Rules and Warnings
-
- In some cases, the operator of a cache MAY choose to configure it to
- return stale responses even when not requested by clients. This
- decision ought not be made lightly, but may be necessary for reasons
- of availability or performance, especially when the cache is poorly
- connected to the origin server. Whenever a cache returns a stale
- response, it MUST mark it as such (using a Warning header) enabling
- the client software to alert the user that there might be a potential
- problem.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 78]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- It also allows the user agent to take steps to obtain a first-hand or
- fresh response. For this reason, a cache SHOULD NOT return a stale
- response if the client explicitly requests a first-hand or fresh one,
- unless it is impossible to comply for technical or policy reasons.
-
-13.1.6 Client-controlled Behavior
-
- While the origin server (and to a lesser extent, intermediate caches,
- by their contribution to the age of a response) are the primary
- source of expiration information, in some cases the client might need
- to control a cache's decision about whether to return a cached
- response without validating it. Clients do this using several
- directives of the Cache-Control header.
-
- A client's request MAY specify the maximum age it is willing to
- accept of an unvalidated response; specifying a value of zero forces
- the cache(s) to revalidate all responses. A client MAY also specify
- the minimum time remaining before a response expires. Both of these
- options increase constraints on the behavior of caches, and so cannot
- further relax the cache's approximation of semantic transparency.
-
- A client MAY also specify that it will accept stale responses, up to
- some maximum amount of staleness. This loosens the constraints on the
- caches, and so might violate the origin server's specified
- constraints on semantic transparency, but might be necessary to
- support disconnected operation, or high availability in the face of
- poor connectivity.
-
-13.2 Expiration Model
-
-13.2.1 Server-Specified Expiration
-
- HTTP caching works best when caches can entirely avoid making
- requests to the origin server. The primary mechanism for avoiding
- requests is for an origin server to provide an explicit expiration
- time in the future, indicating that a response MAY be used to satisfy
- subsequent requests. In other words, a cache can return a fresh
- response without first contacting the server.
-
- Our expectation is that servers will assign future explicit
- expiration times to responses in the belief that the entity is not
- likely to change, in a semantically significant way, before the
- expiration time is reached. This normally preserves semantic
- transparency, as long as the server's expiration times are carefully
- chosen.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 79]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The expiration mechanism applies only to responses taken from a cache
- and not to first-hand responses forwarded immediately to the
- requesting client.
-
- If an origin server wishes to force a semantically transparent cache
- to validate every request, it MAY assign an explicit expiration time
- in the past. This means that the response is always stale, and so the
- cache SHOULD validate it before using it for subsequent requests. See
- section 14.9.4 for a more restrictive way to force revalidation.
-
- If an origin server wishes to force any HTTP/1.1 cache, no matter how
- it is configured, to validate every request, it SHOULD use the "must-
- revalidate" cache-control directive (see section 14.9).
-
- Servers specify explicit expiration times using either the Expires
- header, or the max-age directive of the Cache-Control header.
-
- An expiration time cannot be used to force a user agent to refresh
- its display or reload a resource; its semantics apply only to caching
- mechanisms, and such mechanisms need only check a resource's
- expiration status when a new request for that resource is initiated.
- See section 13.13 for an explanation of the difference between caches
- and history mechanisms.
-
-13.2.2 Heuristic Expiration
-
- Since origin servers do not always provide explicit expiration times,
- HTTP caches typically assign heuristic expiration times, employing
- algorithms that use other header values (such as the Last-Modified
- time) to estimate a plausible expiration time. The HTTP/1.1
- specification does not provide specific algorithms, but does impose
- worst-case constraints on their results. Since heuristic expiration
- times might compromise semantic transparency, they ought to used
- cautiously, and we encourage origin servers to provide explicit
- expiration times as much as possible.
-
-13.2.3 Age Calculations
-
- In order to know if a cached entry is fresh, a cache needs to know if
- its age exceeds its freshness lifetime. We discuss how to calculate
- the latter in section 13.2.4; this section describes how to calculate
- the age of a response or cache entry.
-
- In this discussion, we use the term "now" to mean "the current value
- of the clock at the host performing the calculation." Hosts that use
- HTTP, but especially hosts running origin servers and caches, SHOULD
- use NTP [28] or some similar protocol to synchronize their clocks to
- a globally accurate time standard.
-
-
-
-Fielding, et al. Standards Track [Page 80]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- HTTP/1.1 requires origin servers to send a Date header, if possible,
- with every response, giving the time at which the response was
- generated (see section 14.18). We use the term "date_value" to denote
- the value of the Date header, in a form appropriate for arithmetic
- operations.
-
- HTTP/1.1 uses the Age response-header to convey the estimated age of
- the response message when obtained from a cache. The Age field value
- is the cache's estimate of the amount of time since the response was
- generated or revalidated by the origin server.
-
- In essence, the Age value is the sum of the time that the response
- has been resident in each of the caches along the path from the
- origin server, plus the amount of time it has been in transit along
- network paths.
-
- We use the term "age_value" to denote the value of the Age header, in
- a form appropriate for arithmetic operations.
-
- A response's age can be calculated in two entirely independent ways:
-
- 1. now minus date_value, if the local clock is reasonably well
- synchronized to the origin server's clock. If the result is
- negative, the result is replaced by zero.
-
- 2. age_value, if all of the caches along the response path
- implement HTTP/1.1.
-
- Given that we have two independent ways to compute the age of a
- response when it is received, we can combine these as
-
- corrected_received_age = max(now - date_value, age_value)
-
- and as long as we have either nearly synchronized clocks or all-
- HTTP/1.1 paths, one gets a reliable (conservative) result.
-
- Because of network-imposed delays, some significant interval might
- pass between the time that a server generates a response and the time
- it is received at the next outbound cache or client. If uncorrected,
- this delay could result in improperly low ages.
-
- Because the request that resulted in the returned Age value must have
- been initiated prior to that Age value's generation, we can correct
- for delays imposed by the network by recording the time at which the
- request was initiated. Then, when an Age value is received, it MUST
- be interpreted relative to the time the request was initiated, not
-
-
-
-
-
-Fielding, et al. Standards Track [Page 81]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- the time that the response was received. This algorithm results in
- conservative behavior no matter how much delay is experienced. So, we
- compute:
-
- corrected_initial_age = corrected_received_age
- + (now - request_time)
-
- where "request_time" is the time (according to the local clock) when
- the request that elicited this response was sent.
-
- Summary of age calculation algorithm, when a cache receives a
- response:
-
- /*
- * age_value
- * is the value of Age: header received by the cache with
- * this response.
- * date_value
- * is the value of the origin server's Date: header
- * request_time
- * is the (local) time when the cache made the request
- * that resulted in this cached response
- * response_time
- * is the (local) time when the cache received the
- * response
- * now
- * is the current (local) time
- */
-
- apparent_age = max(0, response_time - date_value);
- corrected_received_age = max(apparent_age, age_value);
- response_delay = response_time - request_time;
- corrected_initial_age = corrected_received_age + response_delay;
- resident_time = now - response_time;
- current_age = corrected_initial_age + resident_time;
-
- The current_age of a cache entry is calculated by adding the amount
- of time (in seconds) since the cache entry was last validated by the
- origin server to the corrected_initial_age. When a response is
- generated from a cache entry, the cache MUST include a single Age
- header field in the response with a value equal to the cache entry's
- current_age.
-
- The presence of an Age header field in a response implies that a
- response is not first-hand. However, the converse is not true, since
- the lack of an Age header field in a response does not imply that the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 82]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- response is first-hand unless all caches along the request path are
- compliant with HTTP/1.1 (i.e., older HTTP caches did not implement
- the Age header field).
-
-13.2.4 Expiration Calculations
-
- In order to decide whether a response is fresh or stale, we need to
- compare its freshness lifetime to its age. The age is calculated as
- described in section 13.2.3; this section describes how to calculate
- the freshness lifetime, and to determine if a response has expired.
- In the discussion below, the values can be represented in any form
- appropriate for arithmetic operations.
-
- We use the term "expires_value" to denote the value of the Expires
- header. We use the term "max_age_value" to denote an appropriate
- value of the number of seconds carried by the "max-age" directive of
- the Cache-Control header in a response (see section 14.9.3).
-
- The max-age directive takes priority over Expires, so if max-age is
- present in a response, the calculation is simply:
-
- freshness_lifetime = max_age_value
-
- Otherwise, if Expires is present in the response, the calculation is:
-
- freshness_lifetime = expires_value - date_value
-
- Note that neither of these calculations is vulnerable to clock skew,
- since all of the information comes from the origin server.
-
- If none of Expires, Cache-Control: max-age, or Cache-Control: s-
- maxage (see section 14.9.3) appears in the response, and the response
- does not include other restrictions on caching, the cache MAY compute
- a freshness lifetime using a heuristic. The cache MUST attach Warning
- 113 to any response whose age is more than 24 hours if such warning
- has not already been added.
-
- Also, if the response does have a Last-Modified time, the heuristic
- expiration value SHOULD be no more than some fraction of the interval
- since that time. A typical setting of this fraction might be 10%.
-
- The calculation to determine if a response has expired is quite
- simple:
-
- response_is_fresh = (freshness_lifetime > current_age)
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 83]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.2.5 Disambiguating Expiration Values
-
- Because expiration values are assigned optimistically, it is possible
- for two caches to contain fresh values for the same resource that are
- different.
-
- If a client performing a retrieval receives a non-first-hand response
- for a request that was already fresh in its own cache, and the Date
- header in its existing cache entry is newer than the Date on the new
- response, then the client MAY ignore the response. If so, it MAY
- retry the request with a "Cache-Control: max-age=0" directive (see
- section 14.9), to force a check with the origin server.
-
- If a cache has two fresh responses for the same representation with
- different validators, it MUST use the one with the more recent Date
- header. This situation might arise because the cache is pooling
- responses from other caches, or because a client has asked for a
- reload or a revalidation of an apparently fresh cache entry.
-
-13.2.6 Disambiguating Multiple Responses
-
- Because a client might be receiving responses via multiple paths, so
- that some responses flow through one set of caches and other
- responses flow through a different set of caches, a client might
- receive responses in an order different from that in which the origin
- server sent them. We would like the client to use the most recently
- generated response, even if older responses are still apparently
- fresh.
-
- Neither the entity tag nor the expiration value can impose an
- ordering on responses, since it is possible that a later response
- intentionally carries an earlier expiration time. The Date values are
- ordered to a granularity of one second.
-
- When a client tries to revalidate a cache entry, and the response it
- receives contains a Date header that appears to be older than the one
- for the existing entry, then the client SHOULD repeat the request
- unconditionally, and include
-
- Cache-Control: max-age=0
-
- to force any intermediate caches to validate their copies directly
- with the origin server, or
-
- Cache-Control: no-cache
-
- to force any intermediate caches to obtain a new copy from the origin
- server.
-
-
-
-Fielding, et al. Standards Track [Page 84]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the Date values are equal, then the client MAY use either response
- (or MAY, if it is being extremely prudent, request a new response).
- Servers MUST NOT depend on clients being able to choose
- deterministically between responses generated during the same second,
- if their expiration times overlap.
-
-13.3 Validation Model
-
- When a cache has a stale entry that it would like to use as a
- response to a client's request, it first has to check with the origin
- server (or possibly an intermediate cache with a fresh response) to
- see if its cached entry is still usable. We call this "validating"
- the cache entry. Since we do not want to have to pay the overhead of
- retransmitting the full response if the cached entry is good, and we
- do not want to pay the overhead of an extra round trip if the cached
- entry is invalid, the HTTP/1.1 protocol supports the use of
- conditional methods.
-
- The key protocol features for supporting conditional methods are
- those concerned with "cache validators." When an origin server
- generates a full response, it attaches some sort of validator to it,
- which is kept with the cache entry. When a client (user agent or
- proxy cache) makes a conditional request for a resource for which it
- has a cache entry, it includes the associated validator in the
- request.
-
- The server then checks that validator against the current validator
- for the entity, and, if they match (see section 13.3.3), it responds
- with a special status code (usually, 304 (Not Modified)) and no
- entity-body. Otherwise, it returns a full response (including
- entity-body). Thus, we avoid transmitting the full response if the
- validator matches, and we avoid an extra round trip if it does not
- match.
-
- In HTTP/1.1, a conditional request looks exactly the same as a normal
- request for the same resource, except that it carries a special
- header (which includes the validator) that implicitly turns the
- method (usually, GET) into a conditional.
-
- The protocol includes both positive and negative senses of cache-
- validating conditions. That is, it is possible to request either that
- a method be performed if and only if a validator matches or if and
- only if no validators match.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 85]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note: a response that lacks a validator may still be cached, and
- served from cache until it expires, unless this is explicitly
- prohibited by a cache-control directive. However, a cache cannot
- do a conditional retrieval if it does not have a validator for the
- entity, which means it will not be refreshable after it expires.
-
-13.3.1 Last-Modified Dates
-
- The Last-Modified entity-header field value is often used as a cache
- validator. In simple terms, a cache entry is considered to be valid
- if the entity has not been modified since the Last-Modified value.
-
-13.3.2 Entity Tag Cache Validators
-
- The ETag response-header field value, an entity tag, provides for an
- "opaque" cache validator. This might allow more reliable validation
- in situations where it is inconvenient to store modification dates,
- where the one-second resolution of HTTP date values is not
- sufficient, or where the origin server wishes to avoid certain
- paradoxes that might arise from the use of modification dates.
-
- Entity Tags are described in section 3.11. The headers used with
- entity tags are described in sections 14.19, 14.24, 14.26 and 14.44.
-
-13.3.3 Weak and Strong Validators
-
- Since both origin servers and caches will compare two validators to
- decide if they represent the same or different entities, one normally
- would expect that if the entity (the entity-body or any entity-
- headers) changes in any way, then the associated validator would
- change as well. If this is true, then we call this validator a
- "strong validator."
-
- However, there might be cases when a server prefers to change the
- validator only on semantically significant changes, and not when
- insignificant aspects of the entity change. A validator that does not
- always change when the resource changes is a "weak validator."
-
- Entity tags are normally "strong validators," but the protocol
- provides a mechanism to tag an entity tag as "weak." One can think of
- a strong validator as one that changes whenever the bits of an entity
- changes, while a weak value changes whenever the meaning of an entity
- changes. Alternatively, one can think of a strong validator as part
- of an identifier for a specific entity, while a weak validator is
- part of an identifier for a set of semantically equivalent entities.
-
- Note: One example of a strong validator is an integer that is
- incremented in stable storage every time an entity is changed.
-
-
-
-Fielding, et al. Standards Track [Page 86]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- An entity's modification time, if represented with one-second
- resolution, could be a weak validator, since it is possible that
- the resource might be modified twice during a single second.
-
- Support for weak validators is optional. However, weak validators
- allow for more efficient caching of equivalent objects; for
- example, a hit counter on a site is probably good enough if it is
- updated every few days or weeks, and any value during that period
- is likely "good enough" to be equivalent.
-
- A "use" of a validator is either when a client generates a request
- and includes the validator in a validating header field, or when a
- server compares two validators.
-
- Strong validators are usable in any context. Weak validators are only
- usable in contexts that do not depend on exact equality of an entity.
- For example, either kind is usable for a conditional GET of a full
- entity. However, only a strong validator is usable for a sub-range
- retrieval, since otherwise the client might end up with an internally
- inconsistent entity.
-
- Clients MAY issue simple (non-subrange) GET requests with either weak
- validators or strong validators. Clients MUST NOT use weak validators
- in other forms of request.
-
- The only function that the HTTP/1.1 protocol defines on validators is
- comparison. There are two validator comparison functions, depending
- on whether the comparison context allows the use of weak validators
- or not:
-
- - The strong comparison function: in order to be considered equal,
- both validators MUST be identical in every way, and both MUST
- NOT be weak.
-
- - The weak comparison function: in order to be considered equal,
- both validators MUST be identical in every way, but either or
- both of them MAY be tagged as "weak" without affecting the
- result.
-
- An entity tag is strong unless it is explicitly tagged as weak.
- Section 3.11 gives the syntax for entity tags.
-
- A Last-Modified time, when used as a validator in a request, is
- implicitly weak unless it is possible to deduce that it is strong,
- using the following rules:
-
- - The validator is being compared by an origin server to the
- actual current validator for the entity and,
-
-
-
-Fielding, et al. Standards Track [Page 87]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - That origin server reliably knows that the associated entity did
- not change twice during the second covered by the presented
- validator.
-
- or
-
- - The validator is about to be used by a client in an If-
- Modified-Since or If-Unmodified-Since header, because the client
- has a cache entry for the associated entity, and
-
- - That cache entry includes a Date value, which gives the time
- when the origin server sent the original response, and
-
- - The presented Last-Modified time is at least 60 seconds before
- the Date value.
-
- or
-
- - The validator is being compared by an intermediate cache to the
- validator stored in its cache entry for the entity, and
-
- - That cache entry includes a Date value, which gives the time
- when the origin server sent the original response, and
-
- - The presented Last-Modified time is at least 60 seconds before
- the Date value.
-
- This method relies on the fact that if two different responses were
- sent by the origin server during the same second, but both had the
- same Last-Modified time, then at least one of those responses would
- have a Date value equal to its Last-Modified time. The arbitrary 60-
- second limit guards against the possibility that the Date and Last-
- Modified values are generated from different clocks, or at somewhat
- different times during the preparation of the response. An
- implementation MAY use a value larger than 60 seconds, if it is
- believed that 60 seconds is too short.
-
- If a client wishes to perform a sub-range retrieval on a value for
- which it has only a Last-Modified time and no opaque validator, it
- MAY do this only if the Last-Modified time is strong in the sense
- described here.
-
- A cache or origin server receiving a conditional request, other than
- a full-body GET request, MUST use the strong comparison function to
- evaluate the condition.
-
- These rules allow HTTP/1.1 caches and clients to safely perform sub-
- range retrievals on values that have been obtained from HTTP/1.0
-
-
-
-Fielding, et al. Standards Track [Page 88]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- servers.
-
-13.3.4 Rules for When to Use Entity Tags and Last-Modified Dates
-
- We adopt a set of rules and recommendations for origin servers,
- clients, and caches regarding when various validator types ought to
- be used, and for what purposes.
-
- HTTP/1.1 origin servers:
-
- - SHOULD send an entity tag validator unless it is not feasible to
- generate one.
-
- - MAY send a weak entity tag instead of a strong entity tag, if
- performance considerations support the use of weak entity tags,
- or if it is unfeasible to send a strong entity tag.
-
- - SHOULD send a Last-Modified value if it is feasible to send one,
- unless the risk of a breakdown in semantic transparency that
- could result from using this date in an If-Modified-Since header
- would lead to serious problems.
-
- In other words, the preferred behavior for an HTTP/1.1 origin server
- is to send both a strong entity tag and a Last-Modified value.
-
- In order to be legal, a strong entity tag MUST change whenever the
- associated entity value changes in any way. A weak entity tag SHOULD
- change whenever the associated entity changes in a semantically
- significant way.
-
- Note: in order to provide semantically transparent caching, an
- origin server must avoid reusing a specific strong entity tag
- value for two different entities, or reusing a specific weak
- entity tag value for two semantically different entities. Cache
- entries might persist for arbitrarily long periods, regardless of
- expiration times, so it might be inappropriate to expect that a
- cache will never again attempt to validate an entry using a
- validator that it obtained at some point in the past.
-
- HTTP/1.1 clients:
-
- - If an entity tag has been provided by the origin server, MUST
- use that entity tag in any cache-conditional request (using If-
- Match or If-None-Match).
-
- - If only a Last-Modified value has been provided by the origin
- server, SHOULD use that value in non-subrange cache-conditional
- requests (using If-Modified-Since).
-
-
-
-Fielding, et al. Standards Track [Page 89]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If only a Last-Modified value has been provided by an HTTP/1.0
- origin server, MAY use that value in subrange cache-conditional
- requests (using If-Unmodified-Since:). The user agent SHOULD
- provide a way to disable this, in case of difficulty.
-
- - If both an entity tag and a Last-Modified value have been
- provided by the origin server, SHOULD use both validators in
- cache-conditional requests. This allows both HTTP/1.0 and
- HTTP/1.1 caches to respond appropriately.
-
- An HTTP/1.1 origin server, upon receiving a conditional request that
- includes both a Last-Modified date (e.g., in an If-Modified-Since or
- If-Unmodified-Since header field) and one or more entity tags (e.g.,
- in an If-Match, If-None-Match, or If-Range header field) as cache
- validators, MUST NOT return a response status of 304 (Not Modified)
- unless doing so is consistent with all of the conditional header
- fields in the request.
-
- An HTTP/1.1 caching proxy, upon receiving a conditional request that
- includes both a Last-Modified date and one or more entity tags as
- cache validators, MUST NOT return a locally cached response to the
- client unless that cached response is consistent with all of the
- conditional header fields in the request.
-
- Note: The general principle behind these rules is that HTTP/1.1
- servers and clients should transmit as much non-redundant
- information as is available in their responses and requests.
- HTTP/1.1 systems receiving this information will make the most
- conservative assumptions about the validators they receive.
-
- HTTP/1.0 clients and caches will ignore entity tags. Generally,
- last-modified values received or used by these systems will
- support transparent and efficient caching, and so HTTP/1.1 origin
- servers should provide Last-Modified values. In those rare cases
- where the use of a Last-Modified value as a validator by an
- HTTP/1.0 system could result in a serious problem, then HTTP/1.1
- origin servers should not provide one.
-
-13.3.5 Non-validating Conditionals
-
- The principle behind entity tags is that only the service author
- knows the semantics of a resource well enough to select an
- appropriate cache validation mechanism, and the specification of any
- validator comparison function more complex than byte-equality would
- open up a can of worms. Thus, comparisons of any other headers
- (except Last-Modified, for compatibility with HTTP/1.0) are never
- used for purposes of validating a cache entry.
-
-
-
-
-Fielding, et al. Standards Track [Page 90]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.4 Response Cacheability
-
- Unless specifically constrained by a cache-control (section 14.9)
- directive, a caching system MAY always store a successful response
- (see section 13.8) as a cache entry, MAY return it without validation
- if it is fresh, and MAY return it after successful validation. If
- there is neither a cache validator nor an explicit expiration time
- associated with a response, we do not expect it to be cached, but
- certain caches MAY violate this expectation (for example, when little
- or no network connectivity is available). A client can usually detect
- that such a response was taken from a cache by comparing the Date
- header to the current time.
-
- Note: some HTTP/1.0 caches are known to violate this expectation
- without providing any Warning.
-
- However, in some cases it might be inappropriate for a cache to
- retain an entity, or to return it in response to a subsequent
- request. This might be because absolute semantic transparency is
- deemed necessary by the service author, or because of security or
- privacy considerations. Certain cache-control directives are
- therefore provided so that the server can indicate that certain
- resource entities, or portions thereof, are not to be cached
- regardless of other considerations.
-
- Note that section 14.8 normally prevents a shared cache from saving
- and returning a response to a previous request if that request
- included an Authorization header.
-
- A response received with a status code of 200, 203, 206, 300, 301 or
- 410 MAY be stored by a cache and used in reply to a subsequent
- request, subject to the expiration mechanism, unless a cache-control
- directive prohibits caching. However, a cache that does not support
- the Range and Content-Range headers MUST NOT cache 206 (Partial
- Content) responses.
-
- A response received with any other status code (e.g. status codes 302
- and 307) MUST NOT be returned in a reply to a subsequent request
- unless there are cache-control directives or another header(s) that
- explicitly allow it. For example, these include the following: an
- Expires header (section 14.21); a "max-age", "s-maxage", "must-
- revalidate", "proxy-revalidate", "public" or "private" cache-control
- directive (section 14.9).
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 91]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5 Constructing Responses From Caches
-
- The purpose of an HTTP cache is to store information received in
- response to requests for use in responding to future requests. In
- many cases, a cache simply returns the appropriate parts of a
- response to the requester. However, if the cache holds a cache entry
- based on a previous response, it might have to combine parts of a new
- response with what is held in the cache entry.
-
-13.5.1 End-to-end and Hop-by-hop Headers
-
- For the purpose of defining the behavior of caches and non-caching
- proxies, we divide HTTP headers into two categories:
-
- - End-to-end headers, which are transmitted to the ultimate
- recipient of a request or response. End-to-end headers in
- responses MUST be stored as part of a cache entry and MUST be
- transmitted in any response formed from a cache entry.
-
- - Hop-by-hop headers, which are meaningful only for a single
- transport-level connection, and are not stored by caches or
- forwarded by proxies.
-
- The following HTTP/1.1 headers are hop-by-hop headers:
-
- - Connection
- - Keep-Alive
- - Proxy-Authenticate
- - Proxy-Authorization
- - TE
- - Trailers
- - Transfer-Encoding
- - Upgrade
-
- All other headers defined by HTTP/1.1 are end-to-end headers.
-
- Other hop-by-hop headers MUST be listed in a Connection header,
- (section 14.10) to be introduced into HTTP/1.1 (or later).
-
-13.5.2 Non-modifiable Headers
-
- Some features of the HTTP/1.1 protocol, such as Digest
- Authentication, depend on the value of certain end-to-end headers. A
- transparent proxy SHOULD NOT modify an end-to-end header unless the
- definition of that header requires or specifically allows that.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 92]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- A transparent proxy MUST NOT modify any of the following fields in a
- request or response, and it MUST NOT add any of these fields if not
- already present:
-
- - Content-Location
-
- - Content-MD5
-
- - ETag
-
- - Last-Modified
-
- A transparent proxy MUST NOT modify any of the following fields in a
- response:
-
- - Expires
-
- but it MAY add any of these fields if not already present. If an
- Expires header is added, it MUST be given a field-value identical to
- that of the Date header in that response.
-
- A proxy MUST NOT modify or add any of the following fields in a
- message that contains the no-transform cache-control directive, or in
- any request:
-
- - Content-Encoding
-
- - Content-Range
-
- - Content-Type
-
- A non-transparent proxy MAY modify or add these fields to a message
- that does not include no-transform, but if it does so, it MUST add a
- Warning 214 (Transformation applied) if one does not already appear
- in the message (see section 14.46).
-
- Warning: unnecessary modification of end-to-end headers might
- cause authentication failures if stronger authentication
- mechanisms are introduced in later versions of HTTP. Such
- authentication mechanisms MAY rely on the values of header fields
- not listed here.
-
- The Content-Length field of a request or response is added or deleted
- according to the rules in section 4.4. A transparent proxy MUST
- preserve the entity-length (section 7.2.2) of the entity-body,
- although it MAY change the transfer-length (section 4.4).
-
-
-
-
-
-Fielding, et al. Standards Track [Page 93]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5.3 Combining Headers
-
- When a cache makes a validating request to a server, and the server
- provides a 304 (Not Modified) response or a 206 (Partial Content)
- response, the cache then constructs a response to send to the
- requesting client.
-
- If the status code is 304 (Not Modified), the cache uses the entity-
- body stored in the cache entry as the entity-body of this outgoing
- response. If the status code is 206 (Partial Content) and the ETag or
- Last-Modified headers match exactly, the cache MAY combine the
- contents stored in the cache entry with the new contents received in
- the response and use the result as the entity-body of this outgoing
- response, (see 13.5.4).
-
- The end-to-end headers stored in the cache entry are used for the
- constructed response, except that
-
- - any stored Warning headers with warn-code 1xx (see section
- 14.46) MUST be deleted from the cache entry and the forwarded
- response.
-
- - any stored Warning headers with warn-code 2xx MUST be retained
- in the cache entry and the forwarded response.
-
- - any end-to-end headers provided in the 304 or 206 response MUST
- replace the corresponding headers from the cache entry.
-
- Unless the cache decides to remove the cache entry, it MUST also
- replace the end-to-end headers stored with the cache entry with
- corresponding headers received in the incoming response, except for
- Warning headers as described immediately above. If a header field-
- name in the incoming response matches more than one header in the
- cache entry, all such old headers MUST be replaced.
-
- In other words, the set of end-to-end headers received in the
- incoming response overrides all corresponding end-to-end headers
- stored with the cache entry (except for stored Warning headers with
- warn-code 1xx, which are deleted even if not overridden).
-
- Note: this rule allows an origin server to use a 304 (Not
- Modified) or a 206 (Partial Content) response to update any header
- associated with a previous response for the same entity or sub-
- ranges thereof, although it might not always be meaningful or
- correct to do so. This rule does not allow an origin server to use
- a 304 (Not Modified) or a 206 (Partial Content) response to
- entirely delete a header that it had provided with a previous
- response.
-
-
-
-Fielding, et al. Standards Track [Page 94]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.5.4 Combining Byte Ranges
-
- A response might transfer only a subrange of the bytes of an entity-
- body, either because the request included one or more Range
- specifications, or because a connection was broken prematurely. After
- several such transfers, a cache might have received several ranges of
- the same entity-body.
-
- If a cache has a stored non-empty set of subranges for an entity, and
- an incoming response transfers another subrange, the cache MAY
- combine the new subrange with the existing set if both the following
- conditions are met:
-
- - Both the incoming response and the cache entry have a cache
- validator.
-
- - The two cache validators match using the strong comparison
- function (see section 13.3.3).
-
- If either requirement is not met, the cache MUST use only the most
- recent partial response (based on the Date values transmitted with
- every response, and using the incoming response if these values are
- equal or missing), and MUST discard the other partial information.
-
-13.6 Caching Negotiated Responses
-
- Use of server-driven content negotiation (section 12.1), as indicated
- by the presence of a Vary header field in a response, alters the
- conditions and procedure by which a cache can use the response for
- subsequent requests. See section 14.44 for use of the Vary header
- field by servers.
-
- A server SHOULD use the Vary header field to inform a cache of what
- request-header fields were used to select among multiple
- representations of a cacheable response subject to server-driven
- negotiation. The set of header fields named by the Vary field value
- is known as the "selecting" request-headers.
-
- When the cache receives a subsequent request whose Request-URI
- specifies one or more cache entries including a Vary header field,
- the cache MUST NOT use such a cache entry to construct a response to
- the new request unless all of the selecting request-headers present
- in the new request match the corresponding stored request-headers in
- the original request.
-
- The selecting request-headers from two requests are defined to match
- if and only if the selecting request-headers in the first request can
- be transformed to the selecting request-headers in the second request
-
-
-
-Fielding, et al. Standards Track [Page 95]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- by adding or removing linear white space (LWS) at places where this
- is allowed by the corresponding BNF, and/or combining multiple
- message-header fields with the same field name following the rules
- about message headers in section 4.2.
-
- A Vary header field-value of "*" always fails to match and subsequent
- requests on that resource can only be properly interpreted by the
- origin server.
-
- If the selecting request header fields for the cached entry do not
- match the selecting request header fields of the new request, then
- the cache MUST NOT use a cached entry to satisfy the request unless
- it first relays the new request to the origin server in a conditional
- request and the server responds with 304 (Not Modified), including an
- entity tag or Content-Location that indicates the entity to be used.
-
- If an entity tag was assigned to a cached representation, the
- forwarded request SHOULD be conditional and include the entity tags
- in an If-None-Match header field from all its cache entries for the
- resource. This conveys to the server the set of entities currently
- held by the cache, so that if any one of these entities matches the
- requested entity, the server can use the ETag header field in its 304
- (Not Modified) response to tell the cache which entry is appropriate.
- If the entity-tag of the new response matches that of an existing
- entry, the new response SHOULD be used to update the header fields of
- the existing entry, and the result MUST be returned to the client.
-
- If any of the existing cache entries contains only partial content
- for the associated entity, its entity-tag SHOULD NOT be included in
- the If-None-Match header field unless the request is for a range that
- would be fully satisfied by that entry.
-
- If a cache receives a successful response whose Content-Location
- field matches that of an existing cache entry for the same Request-
- ]URI, whose entity-tag differs from that of the existing entry, and
- whose Date is more recent than that of the existing entry, the
- existing entry SHOULD NOT be returned in response to future requests
- and SHOULD be deleted from the cache.
-
-13.7 Shared and Non-Shared Caches
-
- For reasons of security and privacy, it is necessary to make a
- distinction between "shared" and "non-shared" caches. A non-shared
- cache is one that is accessible only to a single user. Accessibility
- in this case SHOULD be enforced by appropriate security mechanisms.
- All other caches are considered to be "shared." Other sections of
-
-
-
-
-
-Fielding, et al. Standards Track [Page 96]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- this specification place certain constraints on the operation of
- shared caches in order to prevent loss of privacy or failure of
- access controls.
-
-13.8 Errors or Incomplete Response Cache Behavior
-
- A cache that receives an incomplete response (for example, with fewer
- bytes of data than specified in a Content-Length header) MAY store
- the response. However, the cache MUST treat this as a partial
- response. Partial responses MAY be combined as described in section
- 13.5.4; the result might be a full response or might still be
- partial. A cache MUST NOT return a partial response to a client
- without explicitly marking it as such, using the 206 (Partial
- Content) status code. A cache MUST NOT return a partial response
- using a status code of 200 (OK).
-
- If a cache receives a 5xx response while attempting to revalidate an
- entry, it MAY either forward this response to the requesting client,
- or act as if the server failed to respond. In the latter case, it MAY
- return a previously received response unless the cached entry
- includes the "must-revalidate" cache-control directive (see section
- 14.9).
-
-13.9 Side Effects of GET and HEAD
-
- Unless the origin server explicitly prohibits the caching of their
- responses, the application of GET and HEAD methods to any resources
- SHOULD NOT have side effects that would lead to erroneous behavior if
- these responses are taken from a cache. They MAY still have side
- effects, but a cache is not required to consider such side effects in
- its caching decisions. Caches are always expected to observe an
- origin server's explicit restrictions on caching.
-
- We note one exception to this rule: since some applications have
- traditionally used GETs and HEADs with query URLs (those containing a
- "?" in the rel_path part) to perform operations with significant side
- effects, caches MUST NOT treat responses to such URIs as fresh unless
- the server provides an explicit expiration time. This specifically
- means that responses from HTTP/1.0 servers for such URIs SHOULD NOT
- be taken from a cache. See section 9.1.1 for related information.
-
-13.10 Invalidation After Updates or Deletions
-
- The effect of certain methods performed on a resource at the origin
- server might cause one or more existing cache entries to become non-
- transparently invalid. That is, although they might continue to be
- "fresh," they do not accurately reflect what the origin server would
- return for a new request on that resource.
-
-
-
-Fielding, et al. Standards Track [Page 97]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- There is no way for the HTTP protocol to guarantee that all such
- cache entries are marked invalid. For example, the request that
- caused the change at the origin server might not have gone through
- the proxy where a cache entry is stored. However, several rules help
- reduce the likelihood of erroneous behavior.
-
- In this section, the phrase "invalidate an entity" means that the
- cache will either remove all instances of that entity from its
- storage, or will mark these as "invalid" and in need of a mandatory
- revalidation before they can be returned in response to a subsequent
- request.
-
- Some HTTP methods MUST cause a cache to invalidate an entity. This is
- either the entity referred to by the Request-URI, or by the Location
- or Content-Location headers (if present). These methods are:
-
- - PUT
-
- - DELETE
-
- - POST
-
- In order to prevent denial of service attacks, an invalidation based
- on the URI in a Location or Content-Location header MUST only be
- performed if the host part is the same as in the Request-URI.
-
- A cache that passes through requests for methods it does not
- understand SHOULD invalidate any entities referred to by the
- Request-URI.
-
-13.11 Write-Through Mandatory
-
- All methods that might be expected to cause modifications to the
- origin server's resources MUST be written through to the origin
- server. This currently includes all methods except for GET and HEAD.
- A cache MUST NOT reply to such a request from a client before having
- transmitted the request to the inbound server, and having received a
- corresponding response from the inbound server. This does not prevent
- a proxy cache from sending a 100 (Continue) response before the
- inbound server has sent its final reply.
-
- The alternative (known as "write-back" or "copy-back" caching) is not
- allowed in HTTP/1.1, due to the difficulty of providing consistent
- updates and the problems arising from server, cache, or network
- failure prior to write-back.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 98]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-13.12 Cache Replacement
-
- If a new cacheable (see sections 14.9.2, 13.2.5, 13.2.6 and 13.8)
- response is received from a resource while any existing responses for
- the same resource are cached, the cache SHOULD use the new response
- to reply to the current request. It MAY insert it into cache storage
- and MAY, if it meets all other requirements, use it to respond to any
- future requests that would previously have caused the old response to
- be returned. If it inserts the new response into cache storage the
- rules in section 13.5.3 apply.
-
- Note: a new response that has an older Date header value than
- existing cached responses is not cacheable.
-
-13.13 History Lists
-
- User agents often have history mechanisms, such as "Back" buttons and
- history lists, which can be used to redisplay an entity retrieved
- earlier in a session.
-
- History mechanisms and caches are different. In particular history
- mechanisms SHOULD NOT try to show a semantically transparent view of
- the current state of a resource. Rather, a history mechanism is meant
- to show exactly what the user saw at the time when the resource was
- retrieved.
-
- By default, an expiration time does not apply to history mechanisms.
- If the entity is still in storage, a history mechanism SHOULD display
- it even if the entity has expired, unless the user has specifically
- configured the agent to refresh expired history documents.
-
- This is not to be construed to prohibit the history mechanism from
- telling the user that a view might be stale.
-
- Note: if history list mechanisms unnecessarily prevent users from
- viewing stale resources, this will tend to force service authors
- to avoid using HTTP expiration controls and cache controls when
- they would otherwise like to. Service authors may consider it
- important that users not be presented with error messages or
- warning messages when they use navigation controls (such as BACK)
- to view previously fetched resources. Even though sometimes such
- resources ought not to cached, or ought to expire quickly, user
- interface considerations may force service authors to resort to
- other means of preventing caching (e.g. "once-only" URLs) in order
- not to suffer the effects of improperly functioning history
- mechanisms.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 99]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14 Header Field Definitions
-
- This section defines the syntax and semantics of all standard
- HTTP/1.1 header fields. For entity-header fields, both sender and
- recipient refer to either the client or the server, depending on who
- sends and who receives the entity.
-
-14.1 Accept
-
- The Accept request-header field can be used to specify certain media
- types which are acceptable for the response. Accept headers can be
- used to indicate that the request is specifically limited to a small
- set of desired types, as in the case of a request for an in-line
- image.
-
- Accept = "Accept" ":"
- #( media-range [ accept-params ] )
-
- media-range = ( "*/*"
- | ( type "/" "*" )
- | ( type "/" subtype )
- ) *( ";" parameter )
- accept-params = ";" "q" "=" qvalue *( accept-extension )
- accept-extension = ";" token [ "=" ( token | quoted-string ) ]
-
- The asterisk "*" character is used to group media types into ranges,
- with "*/*" indicating all media types and "type/*" indicating all
- subtypes of that type. The media-range MAY include media type
- parameters that are applicable to that range.
-
- Each media-range MAY be followed by one or more accept-params,
- beginning with the "q" parameter for indicating a relative quality
- factor. The first "q" parameter (if any) separates the media-range
- parameter(s) from the accept-params. Quality factors allow the user
- or user agent to indicate the relative degree of preference for that
- media-range, using the qvalue scale from 0 to 1 (section 3.9). The
- default value is q=1.
-
- Note: Use of the "q" parameter name to separate media type
- parameters from Accept extension parameters is due to historical
- practice. Although this prevents any media type parameter named
- "q" from being used with a media range, such an event is believed
- to be unlikely given the lack of any "q" parameters in the IANA
- media type registry and the rare usage of any media type
- parameters in Accept. Future media types are discouraged from
- registering any parameter named "q".
-
-
-
-
-
-Fielding, et al. Standards Track [Page 100]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The example
-
- Accept: audio/*; q=0.2, audio/basic
-
- SHOULD be interpreted as "I prefer audio/basic, but send me any audio
- type if it is the best available after an 80% mark-down in quality."
-
- If no Accept header field is present, then it is assumed that the
- client accepts all media types. If an Accept header field is present,
- and if the server cannot send a response which is acceptable
- according to the combined Accept field value, then the server SHOULD
- send a 406 (not acceptable) response.
-
- A more elaborate example is
-
- Accept: text/plain; q=0.5, text/html,
- text/x-dvi; q=0.8, text/x-c
-
- Verbally, this would be interpreted as "text/html and text/x-c are
- the preferred media types, but if they do not exist, then send the
- text/x-dvi entity, and if that does not exist, send the text/plain
- entity."
-
- Media ranges can be overridden by more specific media ranges or
- specific media types. If more than one media range applies to a given
- type, the most specific reference has precedence. For example,
-
- Accept: text/*, text/html, text/html;level=1, */*
-
- have the following precedence:
-
- 1) text/html;level=1
- 2) text/html
- 3) text/*
- 4) */*
-
- The media type quality factor associated with a given type is
- determined by finding the media range with the highest precedence
- which matches that type. For example,
-
- Accept: text/*;q=0.3, text/html;q=0.7, text/html;level=1,
- text/html;level=2;q=0.4, */*;q=0.5
-
- would cause the following values to be associated:
-
- text/html;level=1 = 1
- text/html = 0.7
- text/plain = 0.3
-
-
-
-Fielding, et al. Standards Track [Page 101]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- image/jpeg = 0.5
- text/html;level=2 = 0.4
- text/html;level=3 = 0.7
-
- Note: A user agent might be provided with a default set of quality
- values for certain media ranges. However, unless the user agent is
- a closed system which cannot interact with other rendering agents,
- this default set ought to be configurable by the user.
-
-14.2 Accept-Charset
-
- The Accept-Charset request-header field can be used to indicate what
- character sets are acceptable for the response. This field allows
- clients capable of understanding more comprehensive or special-
- purpose character sets to signal that capability to a server which is
- capable of representing documents in those character sets.
-
- Accept-Charset = "Accept-Charset" ":"
- 1#( ( charset | "*" )[ ";" "q" "=" qvalue ] )
-
-
- Character set values are described in section 3.4. Each charset MAY
- be given an associated quality value which represents the user's
- preference for that charset. The default value is q=1. An example is
-
- Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
-
- The special value "*", if present in the Accept-Charset field,
- matches every character set (including ISO-8859-1) which is not
- mentioned elsewhere in the Accept-Charset field. If no "*" is present
- in an Accept-Charset field, then all character sets not explicitly
- mentioned get a quality value of 0, except for ISO-8859-1, which gets
- a quality value of 1 if not explicitly mentioned.
-
- If no Accept-Charset header is present, the default is that any
- character set is acceptable. If an Accept-Charset header is present,
- and if the server cannot send a response which is acceptable
- according to the Accept-Charset header, then the server SHOULD send
- an error response with the 406 (not acceptable) status code, though
- the sending of an unacceptable response is also allowed.
-
-14.3 Accept-Encoding
-
- The Accept-Encoding request-header field is similar to Accept, but
- restricts the content-codings (section 3.5) that are acceptable in
- the response.
-
- Accept-Encoding = "Accept-Encoding" ":"
-
-
-
-Fielding, et al. Standards Track [Page 102]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1#( codings [ ";" "q" "=" qvalue ] )
- codings = ( content-coding | "*" )
-
- Examples of its use are:
-
- Accept-Encoding: compress, gzip
- Accept-Encoding:
- Accept-Encoding: *
- Accept-Encoding: compress;q=0.5, gzip;q=1.0
- Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
-
- A server tests whether a content-coding is acceptable, according to
- an Accept-Encoding field, using these rules:
-
- 1. If the content-coding is one of the content-codings listed in
- the Accept-Encoding field, then it is acceptable, unless it is
- accompanied by a qvalue of 0. (As defined in section 3.9, a
- qvalue of 0 means "not acceptable.")
-
- 2. The special "*" symbol in an Accept-Encoding field matches any
- available content-coding not explicitly listed in the header
- field.
-
- 3. If multiple content-codings are acceptable, then the acceptable
- content-coding with the highest non-zero qvalue is preferred.
-
- 4. The "identity" content-coding is always acceptable, unless
- specifically refused because the Accept-Encoding field includes
- "identity;q=0", or because the field includes "*;q=0" and does
- not explicitly include the "identity" content-coding. If the
- Accept-Encoding field-value is empty, then only the "identity"
- encoding is acceptable.
-
- If an Accept-Encoding field is present in a request, and if the
- server cannot send a response which is acceptable according to the
- Accept-Encoding header, then the server SHOULD send an error response
- with the 406 (Not Acceptable) status code.
-
- If no Accept-Encoding field is present in a request, the server MAY
- assume that the client will accept any content coding. In this case,
- if "identity" is one of the available content-codings, then the
- server SHOULD use the "identity" content-coding, unless it has
- additional information that a different content-coding is meaningful
- to the client.
-
- Note: If the request does not include an Accept-Encoding field,
- and if the "identity" content-coding is unavailable, then
- content-codings commonly understood by HTTP/1.0 clients (i.e.,
-
-
-
-Fielding, et al. Standards Track [Page 103]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- "gzip" and "compress") are preferred; some older clients
- improperly display messages sent with other content-codings. The
- server might also make this decision based on information about
- the particular user-agent or client.
-
- Note: Most HTTP/1.0 applications do not recognize or obey qvalues
- associated with content-codings. This means that qvalues will not
- work and are not permitted with x-gzip or x-compress.
-
-14.4 Accept-Language
-
- The Accept-Language request-header field is similar to Accept, but
- restricts the set of natural languages that are preferred as a
- response to the request. Language tags are defined in section 3.10.
-
- Accept-Language = "Accept-Language" ":"
- 1#( language-range [ ";" "q" "=" qvalue ] )
- language-range = ( ( 1*8ALPHA *( "-" 1*8ALPHA ) ) | "*" )
-
- Each language-range MAY be given an associated quality value which
- represents an estimate of the user's preference for the languages
- specified by that range. The quality value defaults to "q=1". For
- example,
-
- Accept-Language: da, en-gb;q=0.8, en;q=0.7
-
- would mean: "I prefer Danish, but will accept British English and
- other types of English." A language-range matches a language-tag if
- it exactly equals the tag, or if it exactly equals a prefix of the
- tag such that the first tag character following the prefix is "-".
- The special range "*", if present in the Accept-Language field,
- matches every tag not matched by any other range present in the
- Accept-Language field.
-
- Note: This use of a prefix matching rule does not imply that
- language tags are assigned to languages in such a way that it is
- always true that if a user understands a language with a certain
- tag, then this user will also understand all languages with tags
- for which this tag is a prefix. The prefix rule simply allows the
- use of prefix tags if this is the case.
-
- The language quality factor assigned to a language-tag by the
- Accept-Language field is the quality value of the longest language-
- range in the field that matches the language-tag. If no language-
- range in the field matches the tag, the language quality factor
- assigned is 0. If no Accept-Language header is present in the
- request, the server
-
-
-
-
-Fielding, et al. Standards Track [Page 104]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- SHOULD assume that all languages are equally acceptable. If an
- Accept-Language header is present, then all languages which are
- assigned a quality factor greater than 0 are acceptable.
-
- It might be contrary to the privacy expectations of the user to send
- an Accept-Language header with the complete linguistic preferences of
- the user in every request. For a discussion of this issue, see
- section 15.1.4.
-
- As intelligibility is highly dependent on the individual user, it is
- recommended that client applications make the choice of linguistic
- preference available to the user. If the choice is not made
- available, then the Accept-Language header field MUST NOT be given in
- the request.
-
- Note: When making the choice of linguistic preference available to
- the user, we remind implementors of the fact that users are not
- familiar with the details of language matching as described above,
- and should provide appropriate guidance. As an example, users
- might assume that on selecting "en-gb", they will be served any
- kind of English document if British English is not available. A
- user agent might suggest in such a case to add "en" to get the
- best matching behavior.
-
-14.5 Accept-Ranges
-
- The Accept-Ranges response-header field allows the server to
- indicate its acceptance of range requests for a resource:
-
- Accept-Ranges = "Accept-Ranges" ":" acceptable-ranges
- acceptable-ranges = 1#range-unit | "none"
-
- Origin servers that accept byte-range requests MAY send
-
- Accept-Ranges: bytes
-
- but are not required to do so. Clients MAY generate byte-range
- requests without having received this header for the resource
- involved. Range units are defined in section 3.12.
-
- Servers that do not accept any kind of range request for a
- resource MAY send
-
- Accept-Ranges: none
-
- to advise the client not to attempt a range request.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 105]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.6 Age
-
- The Age response-header field conveys the sender's estimate of the
- amount of time since the response (or its revalidation) was
- generated at the origin server. A cached response is "fresh" if
- its age does not exceed its freshness lifetime. Age values are
- calculated as specified in section 13.2.3.
-
- Age = "Age" ":" age-value
- age-value = delta-seconds
-
- Age values are non-negative decimal integers, representing time in
- seconds.
-
- If a cache receives a value larger than the largest positive
- integer it can represent, or if any of its age calculations
- overflows, it MUST transmit an Age header with a value of
- 2147483648 (2^31). An HTTP/1.1 server that includes a cache MUST
- include an Age header field in every response generated from its
- own cache. Caches SHOULD use an arithmetic type of at least 31
- bits of range.
-
-14.7 Allow
-
- The Allow entity-header field lists the set of methods supported
- by the resource identified by the Request-URI. The purpose of this
- field is strictly to inform the recipient of valid methods
- associated with the resource. An Allow header field MUST be
- present in a 405 (Method Not Allowed) response.
-
- Allow = "Allow" ":" #Method
-
- Example of use:
-
- Allow: GET, HEAD, PUT
-
- This field cannot prevent a client from trying other methods.
- However, the indications given by the Allow header field value
- SHOULD be followed. The actual set of allowed methods is defined
- by the origin server at the time of each request.
-
- The Allow header field MAY be provided with a PUT request to
- recommend the methods to be supported by the new or modified
- resource. The server is not required to support these methods and
- SHOULD include an Allow header in the response giving the actual
- supported methods.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 106]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- A proxy MUST NOT modify the Allow header field even if it does not
- understand all the methods specified, since the user agent might
- have other means of communicating with the origin server.
-
-14.8 Authorization
-
- A user agent that wishes to authenticate itself with a server--
- usually, but not necessarily, after receiving a 401 response--does
- so by including an Authorization request-header field with the
- request. The Authorization field value consists of credentials
- containing the authentication information of the user agent for
- the realm of the resource being requested.
-
- Authorization = "Authorization" ":" credentials
-
- HTTP access authentication is described in "HTTP Authentication:
- Basic and Digest Access Authentication" [43]. If a request is
- authenticated and a realm specified, the same credentials SHOULD
- be valid for all other requests within this realm (assuming that
- the authentication scheme itself does not require otherwise, such
- as credentials that vary according to a challenge value or using
- synchronized clocks).
-
- When a shared cache (see section 13.7) receives a request
- containing an Authorization field, it MUST NOT return the
- corresponding response as a reply to any other request, unless one
- of the following specific exceptions holds:
-
- 1. If the response includes the "s-maxage" cache-control
- directive, the cache MAY use that response in replying to a
- subsequent request. But (if the specified maximum age has
- passed) a proxy cache MUST first revalidate it with the origin
- server, using the request-headers from the new request to allow
- the origin server to authenticate the new request. (This is the
- defined behavior for s-maxage.) If the response includes "s-
- maxage=0", the proxy MUST always revalidate it before re-using
- it.
-
- 2. If the response includes the "must-revalidate" cache-control
- directive, the cache MAY use that response in replying to a
- subsequent request. But if the response is stale, all caches
- MUST first revalidate it with the origin server, using the
- request-headers from the new request to allow the origin server
- to authenticate the new request.
-
- 3. If the response includes the "public" cache-control directive,
- it MAY be returned in reply to any subsequent request.
-
-
-
-
-Fielding, et al. Standards Track [Page 107]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.9 Cache-Control
-
- The Cache-Control general-header field is used to specify directives
- that MUST be obeyed by all caching mechanisms along the
- request/response chain. The directives specify behavior intended to
- prevent caches from adversely interfering with the request or
- response. These directives typically override the default caching
- algorithms. Cache directives are unidirectional in that the presence
- of a directive in a request does not imply that the same directive is
- to be given in the response.
-
- Note that HTTP/1.0 caches might not implement Cache-Control and
- might only implement Pragma: no-cache (see section 14.32).
-
- Cache directives MUST be passed through by a proxy or gateway
- application, regardless of their significance to that application,
- since the directives might be applicable to all recipients along the
- request/response chain. It is not possible to specify a cache-
- directive for a specific cache.
-
- Cache-Control = "Cache-Control" ":" 1#cache-directive
-
- cache-directive = cache-request-directive
- | cache-response-directive
-
- cache-request-directive =
- "no-cache" ; Section 14.9.1
- | "no-store" ; Section 14.9.2
- | "max-age" "=" delta-seconds ; Section 14.9.3, 14.9.4
- | "max-stale" [ "=" delta-seconds ] ; Section 14.9.3
- | "min-fresh" "=" delta-seconds ; Section 14.9.3
- | "no-transform" ; Section 14.9.5
- | "only-if-cached" ; Section 14.9.4
- | cache-extension ; Section 14.9.6
-
- cache-response-directive =
- "public" ; Section 14.9.1
- | "private" [ "=" <"> 1#field-name <"> ] ; Section 14.9.1
- | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 14.9.1
- | "no-store" ; Section 14.9.2
- | "no-transform" ; Section 14.9.5
- | "must-revalidate" ; Section 14.9.4
- | "proxy-revalidate" ; Section 14.9.4
- | "max-age" "=" delta-seconds ; Section 14.9.3
- | "s-maxage" "=" delta-seconds ; Section 14.9.3
- | cache-extension ; Section 14.9.6
-
- cache-extension = token [ "=" ( token | quoted-string ) ]
-
-
-
-Fielding, et al. Standards Track [Page 108]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- When a directive appears without any 1#field-name parameter, the
- directive applies to the entire request or response. When such a
- directive appears with a 1#field-name parameter, it applies only to
- the named field or fields, and not to the rest of the request or
- response. This mechanism supports extensibility; implementations of
- future versions of the HTTP protocol might apply these directives to
- header fields not defined in HTTP/1.1.
-
- The cache-control directives can be broken down into these general
- categories:
-
- - Restrictions on what are cacheable; these may only be imposed by
- the origin server.
-
- - Restrictions on what may be stored by a cache; these may be
- imposed by either the origin server or the user agent.
-
- - Modifications of the basic expiration mechanism; these may be
- imposed by either the origin server or the user agent.
-
- - Controls over cache revalidation and reload; these may only be
- imposed by a user agent.
-
- - Control over transformation of entities.
-
- - Extensions to the caching system.
-
-14.9.1 What is Cacheable
-
- By default, a response is cacheable if the requirements of the
- request method, request header fields, and the response status
- indicate that it is cacheable. Section 13.4 summarizes these defaults
- for cacheability. The following Cache-Control response directives
- allow an origin server to override the default cacheability of a
- response:
-
- public
- Indicates that the response MAY be cached by any cache, even if it
- would normally be non-cacheable or cacheable only within a non-
- shared cache. (See also Authorization, section 14.8, for
- additional details.)
-
- private
- Indicates that all or part of the response message is intended for
- a single user and MUST NOT be cached by a shared cache. This
- allows an origin server to state that the specified parts of the
-
-
-
-
-
-Fielding, et al. Standards Track [Page 109]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- response are intended for only one user and are not a valid
- response for requests by other users. A private (non-shared) cache
- MAY cache the response.
-
- Note: This usage of the word private only controls where the
- response may be cached, and cannot ensure the privacy of the
- message content.
-
- no-cache
- If the no-cache directive does not specify a field-name, then a
- cache MUST NOT use the response to satisfy a subsequent request
- without successful revalidation with the origin server. This
- allows an origin server to prevent caching even by caches that
- have been configured to return stale responses to client requests.
-
- If the no-cache directive does specify one or more field-names,
- then a cache MAY use the response to satisfy a subsequent request,
- subject to any other restrictions on caching. However, the
- specified field-name(s) MUST NOT be sent in the response to a
- subsequent request without successful revalidation with the origin
- server. This allows an origin server to prevent the re-use of
- certain header fields in a response, while still allowing caching
- of the rest of the response.
-
- Note: Most HTTP/1.0 caches will not recognize or obey this
- directive.
-
-14.9.2 What May be Stored by Caches
-
- no-store
- The purpose of the no-store directive is to prevent the
- inadvertent release or retention of sensitive information (for
- example, on backup tapes). The no-store directive applies to the
- entire message, and MAY be sent either in a response or in a
- request. If sent in a request, a cache MUST NOT store any part of
- either this request or any response to it. If sent in a response,
- a cache MUST NOT store any part of either this response or the
- request that elicited it. This directive applies to both non-
- shared and shared caches. "MUST NOT store" in this context means
- that the cache MUST NOT intentionally store the information in
- non-volatile storage, and MUST make a best-effort attempt to
- remove the information from volatile storage as promptly as
- possible after forwarding it.
-
- Even when this directive is associated with a response, users
- might explicitly store such a response outside of the caching
- system (e.g., with a "Save As" dialog). History buffers MAY store
- such responses as part of their normal operation.
-
-
-
-Fielding, et al. Standards Track [Page 110]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The purpose of this directive is to meet the stated requirements
- of certain users and service authors who are concerned about
- accidental releases of information via unanticipated accesses to
- cache data structures. While the use of this directive might
- improve privacy in some cases, we caution that it is NOT in any
- way a reliable or sufficient mechanism for ensuring privacy. In
- particular, malicious or compromised caches might not recognize or
- obey this directive, and communications networks might be
- vulnerable to eavesdropping.
-
-14.9.3 Modifications of the Basic Expiration Mechanism
-
- The expiration time of an entity MAY be specified by the origin
- server using the Expires header (see section 14.21). Alternatively,
- it MAY be specified using the max-age directive in a response. When
- the max-age cache-control directive is present in a cached response,
- the response is stale if its current age is greater than the age
- value given (in seconds) at the time of a new request for that
- resource. The max-age directive on a response implies that the
- response is cacheable (i.e., "public") unless some other, more
- restrictive cache directive is also present.
-
- If a response includes both an Expires header and a max-age
- directive, the max-age directive overrides the Expires header, even
- if the Expires header is more restrictive. This rule allows an origin
- server to provide, for a given response, a longer expiration time to
- an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This might be
- useful if certain HTTP/1.0 caches improperly calculate ages or
- expiration times, perhaps due to desynchronized clocks.
-
- Many HTTP/1.0 cache implementations will treat an Expires value that
- is less than or equal to the response Date value as being equivalent
- to the Cache-Control response directive "no-cache". If an HTTP/1.1
- cache receives such a response, and the response does not include a
- Cache-Control header field, it SHOULD consider the response to be
- non-cacheable in order to retain compatibility with HTTP/1.0 servers.
-
- Note: An origin server might wish to use a relatively new HTTP
- cache control feature, such as the "private" directive, on a
- network including older caches that do not understand that
- feature. The origin server will need to combine the new feature
- with an Expires field whose value is less than or equal to the
- Date value. This will prevent older caches from improperly
- caching the response.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 111]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- s-maxage
- If a response includes an s-maxage directive, then for a shared
- cache (but not for a private cache), the maximum age specified by
- this directive overrides the maximum age specified by either the
- max-age directive or the Expires header. The s-maxage directive
- also implies the semantics of the proxy-revalidate directive (see
- section 14.9.4), i.e., that the shared cache must not use the
- entry after it becomes stale to respond to a subsequent request
- without first revalidating it with the origin server. The s-
- maxage directive is always ignored by a private cache.
-
- Note that most older caches, not compliant with this specification,
- do not implement any cache-control directives. An origin server
- wishing to use a cache-control directive that restricts, but does not
- prevent, caching by an HTTP/1.1-compliant cache MAY exploit the
- requirement that the max-age directive overrides the Expires header,
- and the fact that pre-HTTP/1.1-compliant caches do not observe the
- max-age directive.
-
- Other directives allow a user agent to modify the basic expiration
- mechanism. These directives MAY be specified on a request:
-
- max-age
- Indicates that the client is willing to accept a response whose
- age is no greater than the specified time in seconds. Unless max-
- stale directive is also included, the client is not willing to
- accept a stale response.
-
- min-fresh
- Indicates that the client is willing to accept a response whose
- freshness lifetime is no less than its current age plus the
- specified time in seconds. That is, the client wants a response
- that will still be fresh for at least the specified number of
- seconds.
-
- max-stale
- Indicates that the client is willing to accept a response that has
- exceeded its expiration time. If max-stale is assigned a value,
- then the client is willing to accept a response that has exceeded
- its expiration time by no more than the specified number of
- seconds. If no value is assigned to max-stale, then the client is
- willing to accept a stale response of any age.
-
- If a cache returns a stale response, either because of a max-stale
- directive on a request, or because the cache is configured to
- override the expiration time of a response, the cache MUST attach a
- Warning header to the stale response, using Warning 110 (Response is
- stale).
-
-
-
-Fielding, et al. Standards Track [Page 112]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- A cache MAY be configured to return stale responses without
- validation, but only if this does not conflict with any "MUST"-level
- requirements concerning cache validation (e.g., a "must-revalidate"
- cache-control directive).
-
- If both the new request and the cached entry include "max-age"
- directives, then the lesser of the two values is used for determining
- the freshness of the cached entry for that request.
-
-14.9.4 Cache Revalidation and Reload Controls
-
- Sometimes a user agent might want or need to insist that a cache
- revalidate its cache entry with the origin server (and not just with
- the next cache along the path to the origin server), or to reload its
- cache entry from the origin server. End-to-end revalidation might be
- necessary if either the cache or the origin server has overestimated
- the expiration time of the cached response. End-to-end reload may be
- necessary if the cache entry has become corrupted for some reason.
-
- End-to-end revalidation may be requested either when the client does
- not have its own local cached copy, in which case we call it
- "unspecified end-to-end revalidation", or when the client does have a
- local cached copy, in which case we call it "specific end-to-end
- revalidation."
-
- The client can specify these three kinds of action using Cache-
- Control request directives:
-
- End-to-end reload
- The request includes a "no-cache" cache-control directive or, for
- compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field
- names MUST NOT be included with the no-cache directive in a
- request. The server MUST NOT use a cached copy when responding to
- such a request.
-
- Specific end-to-end revalidation
- The request includes a "max-age=0" cache-control directive, which
- forces each cache along the path to the origin server to
- revalidate its own entry, if any, with the next cache or server.
- The initial request includes a cache-validating conditional with
- the client's current validator.
-
- Unspecified end-to-end revalidation
- The request includes "max-age=0" cache-control directive, which
- forces each cache along the path to the origin server to
- revalidate its own entry, if any, with the next cache or server.
- The initial request does not include a cache-validating
-
-
-
-
-Fielding, et al. Standards Track [Page 113]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- conditional; the first cache along the path (if any) that holds a
- cache entry for this resource includes a cache-validating
- conditional with its current validator.
-
- max-age
- When an intermediate cache is forced, by means of a max-age=0
- directive, to revalidate its own cache entry, and the client has
- supplied its own validator in the request, the supplied validator
- might differ from the validator currently stored with the cache
- entry. In this case, the cache MAY use either validator in making
- its own request without affecting semantic transparency.
-
- However, the choice of validator might affect performance. The
- best approach is for the intermediate cache to use its own
- validator when making its request. If the server replies with 304
- (Not Modified), then the cache can return its now validated copy
- to the client with a 200 (OK) response. If the server replies with
- a new entity and cache validator, however, the intermediate cache
- can compare the returned validator with the one provided in the
- client's request, using the strong comparison function. If the
- client's validator is equal to the origin server's, then the
- intermediate cache simply returns 304 (Not Modified). Otherwise,
- it returns the new entity with a 200 (OK) response.
-
- If a request includes the no-cache directive, it SHOULD NOT
- include min-fresh, max-stale, or max-age.
-
- only-if-cached
- In some cases, such as times of extremely poor network
- connectivity, a client may want a cache to return only those
- responses that it currently has stored, and not to reload or
- revalidate with the origin server. To do this, the client may
- include the only-if-cached directive in a request. If it receives
- this directive, a cache SHOULD either respond using a cached entry
- that is consistent with the other constraints of the request, or
- respond with a 504 (Gateway Timeout) status. However, if a group
- of caches is being operated as a unified system with good internal
- connectivity, such a request MAY be forwarded within that group of
- caches.
-
- must-revalidate
- Because a cache MAY be configured to ignore a server's specified
- expiration time, and because a client request MAY include a max-
- stale directive (which has a similar effect), the protocol also
- includes a mechanism for the origin server to require revalidation
- of a cache entry on any subsequent use. When the must-revalidate
- directive is present in a response received by a cache, that cache
- MUST NOT use the entry after it becomes stale to respond to a
-
-
-
-Fielding, et al. Standards Track [Page 114]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- subsequent request without first revalidating it with the origin
- server. (I.e., the cache MUST do an end-to-end revalidation every
- time, if, based solely on the origin server's Expires or max-age
- value, the cached response is stale.)
-
- The must-revalidate directive is necessary to support reliable
- operation for certain protocol features. In all circumstances an
- HTTP/1.1 cache MUST obey the must-revalidate directive; in
- particular, if the cache cannot reach the origin server for any
- reason, it MUST generate a 504 (Gateway Timeout) response.
-
- Servers SHOULD send the must-revalidate directive if and only if
- failure to revalidate a request on the entity could result in
- incorrect operation, such as a silently unexecuted financial
- transaction. Recipients MUST NOT take any automated action that
- violates this directive, and MUST NOT automatically provide an
- unvalidated copy of the entity if revalidation fails.
-
- Although this is not recommended, user agents operating under
- severe connectivity constraints MAY violate this directive but, if
- so, MUST explicitly warn the user that an unvalidated response has
- been provided. The warning MUST be provided on each unvalidated
- access, and SHOULD require explicit user confirmation.
-
- proxy-revalidate
- The proxy-revalidate directive has the same meaning as the must-
- revalidate directive, except that it does not apply to non-shared
- user agent caches. It can be used on a response to an
- authenticated request to permit the user's cache to store and
- later return the response without needing to revalidate it (since
- it has already been authenticated once by that user), while still
- requiring proxies that service many users to revalidate each time
- (in order to make sure that each user has been authenticated).
- Note that such authenticated responses also need the public cache
- control directive in order to allow them to be cached at all.
-
-14.9.5 No-Transform Directive
-
- no-transform
- Implementors of intermediate caches (proxies) have found it useful
- to convert the media type of certain entity bodies. A non-
- transparent proxy might, for example, convert between image
- formats in order to save cache space or to reduce the amount of
- traffic on a slow link.
-
- Serious operational problems occur, however, when these
- transformations are applied to entity bodies intended for certain
- kinds of applications. For example, applications for medical
-
-
-
-Fielding, et al. Standards Track [Page 115]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- imaging, scientific data analysis and those using end-to-end
- authentication, all depend on receiving an entity body that is bit
- for bit identical to the original entity-body.
-
- Therefore, if a message includes the no-transform directive, an
- intermediate cache or proxy MUST NOT change those headers that are
- listed in section 13.5.2 as being subject to the no-transform
- directive. This implies that the cache or proxy MUST NOT change
- any aspect of the entity-body that is specified by these headers,
- including the value of the entity-body itself.
-
-14.9.6 Cache Control Extensions
-
- The Cache-Control header field can be extended through the use of one
- or more cache-extension tokens, each with an optional assigned value.
- Informational extensions (those which do not require a change in
- cache behavior) MAY be added without changing the semantics of other
- directives. Behavioral extensions are designed to work by acting as
- modifiers to the existing base of cache directives. Both the new
- directive and the standard directive are supplied, such that
- applications which do not understand the new directive will default
- to the behavior specified by the standard directive, and those that
- understand the new directive will recognize it as modifying the
- requirements associated with the standard directive. In this way,
- extensions to the cache-control directives can be made without
- requiring changes to the base protocol.
-
- This extension mechanism depends on an HTTP cache obeying all of the
- cache-control directives defined for its native HTTP-version, obeying
- certain extensions, and ignoring all directives that it does not
- understand.
-
- For example, consider a hypothetical new response directive called
- community which acts as a modifier to the private directive. We
- define this new directive to mean that, in addition to any non-shared
- cache, any cache which is shared only by members of the community
- named within its value may cache the response. An origin server
- wishing to allow the UCI community to use an otherwise private
- response in their shared cache(s) could do so by including
-
- Cache-Control: private, community="UCI"
-
- A cache seeing this header field will act correctly even if the cache
- does not understand the community cache-extension, since it will also
- see and understand the private directive and thus default to the safe
- behavior.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 116]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Unrecognized cache-directives MUST be ignored; it is assumed that any
- cache-directive likely to be unrecognized by an HTTP/1.1 cache will
- be combined with standard directives (or the response's default
- cacheability) such that the cache behavior will remain minimally
- correct even if the cache does not understand the extension(s).
-
-14.10 Connection
-
- The Connection general-header field allows the sender to specify
- options that are desired for that particular connection and MUST NOT
- be communicated by proxies over further connections.
-
- The Connection header has the following grammar:
-
- Connection = "Connection" ":" 1#(connection-token)
- connection-token = token
-
- HTTP/1.1 proxies MUST parse the Connection header field before a
- message is forwarded and, for each connection-token in this field,
- remove any header field(s) from the message with the same name as the
- connection-token. Connection options are signaled by the presence of
- a connection-token in the Connection header field, not by any
- corresponding additional header field(s), since the additional header
- field may not be sent if there are no parameters associated with that
- connection option.
-
- Message headers listed in the Connection header MUST NOT include
- end-to-end headers, such as Cache-Control.
-
- HTTP/1.1 defines the "close" connection option for the sender to
- signal that the connection will be closed after completion of the
- response. For example,
-
- Connection: close
-
- in either the request or the response header fields indicates that
- the connection SHOULD NOT be considered `persistent' (section 8.1)
- after the current request/response is complete.
-
- HTTP/1.1 applications that do not support persistent connections MUST
- include the "close" connection option in every message.
-
- A system receiving an HTTP/1.0 (or lower-version) message that
- includes a Connection header MUST, for each connection-token in this
- field, remove and ignore any header field(s) from the message with
- the same name as the connection-token. This protects against mistaken
- forwarding of such header fields by pre-HTTP/1.1 proxies. See section
- 19.6.2.
-
-
-
-Fielding, et al. Standards Track [Page 117]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.11 Content-Encoding
-
- The Content-Encoding entity-header field is used as a modifier to the
- media-type. When present, its value indicates what additional content
- codings have been applied to the entity-body, and thus what decoding
- mechanisms must be applied in order to obtain the media-type
- referenced by the Content-Type header field. Content-Encoding is
- primarily used to allow a document to be compressed without losing
- the identity of its underlying media type.
-
- Content-Encoding = "Content-Encoding" ":" 1#content-coding
-
- Content codings are defined in section 3.5. An example of its use is
-
- Content-Encoding: gzip
-
- The content-coding is a characteristic of the entity identified by
- the Request-URI. Typically, the entity-body is stored with this
- encoding and is only decoded before rendering or analogous usage.
- However, a non-transparent proxy MAY modify the content-coding if the
- new coding is known to be acceptable to the recipient, unless the
- "no-transform" cache-control directive is present in the message.
-
- If the content-coding of an entity is not "identity", then the
- response MUST include a Content-Encoding entity-header (section
- 14.11) that lists the non-identity content-coding(s) used.
-
- If the content-coding of an entity in a request message is not
- acceptable to the origin server, the server SHOULD respond with a
- status code of 415 (Unsupported Media Type).
-
- If multiple encodings have been applied to an entity, the content
- codings MUST be listed in the order in which they were applied.
- Additional information about the encoding parameters MAY be provided
- by other entity-header fields not defined by this specification.
-
-14.12 Content-Language
-
- The Content-Language entity-header field describes the natural
- language(s) of the intended audience for the enclosed entity. Note
- that this might not be equivalent to all the languages used within
- the entity-body.
-
- Content-Language = "Content-Language" ":" 1#language-tag
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 118]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Language tags are defined in section 3.10. The primary purpose of
- Content-Language is to allow a user to identify and differentiate
- entities according to the user's own preferred language. Thus, if the
- body content is intended only for a Danish-literate audience, the
- appropriate field is
-
- Content-Language: da
-
- If no Content-Language is specified, the default is that the content
- is intended for all language audiences. This might mean that the
- sender does not consider it to be specific to any natural language,
- or that the sender does not know for which language it is intended.
-
- Multiple languages MAY be listed for content that is intended for
- multiple audiences. For example, a rendition of the "Treaty of
- Waitangi," presented simultaneously in the original Maori and English
- versions, would call for
-
- Content-Language: mi, en
-
- However, just because multiple languages are present within an entity
- does not mean that it is intended for multiple linguistic audiences.
- An example would be a beginner's language primer, such as "A First
- Lesson in Latin," which is clearly intended to be used by an
- English-literate audience. In this case, the Content-Language would
- properly only include "en".
-
- Content-Language MAY be applied to any media type -- it is not
- limited to textual documents.
-
-14.13 Content-Length
-
- The Content-Length entity-header field indicates the size of the
- entity-body, in decimal number of OCTETs, sent to the recipient or,
- in the case of the HEAD method, the size of the entity-body that
- would have been sent had the request been a GET.
-
- Content-Length = "Content-Length" ":" 1*DIGIT
-
- An example is
-
- Content-Length: 3495
-
- Applications SHOULD use this field to indicate the transfer-length of
- the message-body, unless this is prohibited by the rules in section
- 4.4.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 119]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Any Content-Length greater than or equal to zero is a valid value.
- Section 4.4 describes how to determine the length of a message-body
- if a Content-Length is not given.
-
- Note that the meaning of this field is significantly different from
- the corresponding definition in MIME, where it is an optional field
- used within the "message/external-body" content-type. In HTTP, it
- SHOULD be sent whenever the message's length can be determined prior
- to being transferred, unless this is prohibited by the rules in
- section 4.4.
-
-14.14 Content-Location
-
- The Content-Location entity-header field MAY be used to supply the
- resource location for the entity enclosed in the message when that
- entity is accessible from a location separate from the requested
- resource's URI. A server SHOULD provide a Content-Location for the
- variant corresponding to the response entity; especially in the case
- where a resource has multiple entities associated with it, and those
- entities actually have separate locations by which they might be
- individually accessed, the server SHOULD provide a Content-Location
- for the particular variant which is returned.
-
- Content-Location = "Content-Location" ":"
- ( absoluteURI | relativeURI )
-
- The value of Content-Location also defines the base URI for the
- entity.
-
- The Content-Location value is not a replacement for the original
- requested URI; it is only a statement of the location of the resource
- corresponding to this particular entity at the time of the request.
- Future requests MAY specify the Content-Location URI as the request-
- URI if the desire is to identify the source of that particular
- entity.
-
- A cache cannot assume that an entity with a Content-Location
- different from the URI used to retrieve it can be used to respond to
- later requests on that Content-Location URI. However, the Content-
- Location can be used to differentiate between multiple entities
- retrieved from a single requested resource, as described in section
- 13.6.
-
- If the Content-Location is a relative URI, the relative URI is
- interpreted relative to the Request-URI.
-
- The meaning of the Content-Location header in PUT or POST requests is
- undefined; servers are free to ignore it in those cases.
-
-
-
-Fielding, et al. Standards Track [Page 120]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.15 Content-MD5
-
- The Content-MD5 entity-header field, as defined in RFC 1864 [23], is
- an MD5 digest of the entity-body for the purpose of providing an
- end-to-end message integrity check (MIC) of the entity-body. (Note: a
- MIC is good for detecting accidental modification of the entity-body
- in transit, but is not proof against malicious attacks.)
-
- Content-MD5 = "Content-MD5" ":" md5-digest
- md5-digest = <base64 of 128 bit MD5 digest as per RFC 1864>
-
- The Content-MD5 header field MAY be generated by an origin server or
- client to function as an integrity check of the entity-body. Only
- origin servers or clients MAY generate the Content-MD5 header field;
- proxies and gateways MUST NOT generate it, as this would defeat its
- value as an end-to-end integrity check. Any recipient of the entity-
- body, including gateways and proxies, MAY check that the digest value
- in this header field matches that of the entity-body as received.
-
- The MD5 digest is computed based on the content of the entity-body,
- including any content-coding that has been applied, but not including
- any transfer-encoding applied to the message-body. If the message is
- received with a transfer-encoding, that encoding MUST be removed
- prior to checking the Content-MD5 value against the received entity.
-
- This has the result that the digest is computed on the octets of the
- entity-body exactly as, and in the order that, they would be sent if
- no transfer-encoding were being applied.
-
- HTTP extends RFC 1864 to permit the digest to be computed for MIME
- composite media-types (e.g., multipart/* and message/rfc822), but
- this does not change how the digest is computed as defined in the
- preceding paragraph.
-
- There are several consequences of this. The entity-body for composite
- types MAY contain many body-parts, each with its own MIME and HTTP
- headers (including Content-MD5, Content-Transfer-Encoding, and
- Content-Encoding headers). If a body-part has a Content-Transfer-
- Encoding or Content-Encoding header, it is assumed that the content
- of the body-part has had the encoding applied, and the body-part is
- included in the Content-MD5 digest as is -- i.e., after the
- application. The Transfer-Encoding header field is not allowed within
- body-parts.
-
- Conversion of all line breaks to CRLF MUST NOT be done before
- computing or checking the digest: the line break convention used in
- the text actually transmitted MUST be left unaltered when computing
- the digest.
-
-
-
-Fielding, et al. Standards Track [Page 121]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Note: while the definition of Content-MD5 is exactly the same for
- HTTP as in RFC 1864 for MIME entity-bodies, there are several ways
- in which the application of Content-MD5 to HTTP entity-bodies
- differs from its application to MIME entity-bodies. One is that
- HTTP, unlike MIME, does not use Content-Transfer-Encoding, and
- does use Transfer-Encoding and Content-Encoding. Another is that
- HTTP more frequently uses binary content types than MIME, so it is
- worth noting that, in such cases, the byte order used to compute
- the digest is the transmission byte order defined for the type.
- Lastly, HTTP allows transmission of text types with any of several
- line break conventions and not just the canonical form using CRLF.
-
-14.16 Content-Range
-
- The Content-Range entity-header is sent with a partial entity-body to
- specify where in the full entity-body the partial body should be
- applied. Range units are defined in section 3.12.
-
- Content-Range = "Content-Range" ":" content-range-spec
-
- content-range-spec = byte-content-range-spec
- byte-content-range-spec = bytes-unit SP
- byte-range-resp-spec "/"
- ( instance-length | "*" )
-
- byte-range-resp-spec = (first-byte-pos "-" last-byte-pos)
- | "*"
- instance-length = 1*DIGIT
-
- The header SHOULD indicate the total length of the full entity-body,
- unless this length is unknown or difficult to determine. The asterisk
- "*" character means that the instance-length is unknown at the time
- when the response was generated.
-
- Unlike byte-ranges-specifier values (see section 14.35.1), a byte-
- range-resp-spec MUST only specify one range, and MUST contain
- absolute byte positions for both the first and last byte of the
- range.
-
- A byte-content-range-spec with a byte-range-resp-spec whose last-
- byte-pos value is less than its first-byte-pos value, or whose
- instance-length value is less than or equal to its last-byte-pos
- value, is invalid. The recipient of an invalid byte-content-range-
- spec MUST ignore it and any content transferred along with it.
-
- A server sending a response with status code 416 (Requested range not
- satisfiable) SHOULD include a Content-Range field with a byte-range-
- resp-spec of "*". The instance-length specifies the current length of
-
-
-
-Fielding, et al. Standards Track [Page 122]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- the selected resource. A response with status code 206 (Partial
- Content) MUST NOT include a Content-Range field with a byte-range-
- resp-spec of "*".
-
- Examples of byte-content-range-spec values, assuming that the entity
- contains a total of 1234 bytes:
-
- . The first 500 bytes:
- bytes 0-499/1234
-
- . The second 500 bytes:
- bytes 500-999/1234
-
- . All except for the first 500 bytes:
- bytes 500-1233/1234
-
- . The last 500 bytes:
- bytes 734-1233/1234
-
- When an HTTP message includes the content of a single range (for
- example, a response to a request for a single range, or to a request
- for a set of ranges that overlap without any holes), this content is
- transmitted with a Content-Range header, and a Content-Length header
- showing the number of bytes actually transferred. For example,
-
- HTTP/1.1 206 Partial content
- Date: Wed, 15 Nov 1995 06:25:24 GMT
- Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
- Content-Range: bytes 21010-47021/47022
- Content-Length: 26012
- Content-Type: image/gif
-
- When an HTTP message includes the content of multiple ranges (for
- example, a response to a request for multiple non-overlapping
- ranges), these are transmitted as a multipart message. The multipart
- media type used for this purpose is "multipart/byteranges" as defined
- in appendix 19.2. See appendix 19.6.3 for a compatibility issue.
-
- A response to a request for a single range MUST NOT be sent using the
- multipart/byteranges media type. A response to a request for
- multiple ranges, whose result is a single range, MAY be sent as a
- multipart/byteranges media type with one part. A client that cannot
- decode a multipart/byteranges message MUST NOT ask for multiple
- byte-ranges in a single request.
-
- When a client requests multiple byte-ranges in one request, the
- server SHOULD return them in the order that they appeared in the
- request.
-
-
-
-Fielding, et al. Standards Track [Page 123]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the server ignores a byte-range-spec because it is syntactically
- invalid, the server SHOULD treat the request as if the invalid Range
- header field did not exist. (Normally, this means return a 200
- response containing the full entity).
-
- If the server receives a request (other than one including an If-
- Range request-header field) with an unsatisfiable Range request-
- header field (that is, all of whose byte-range-spec values have a
- first-byte-pos value greater than the current length of the selected
- resource), it SHOULD return a response code of 416 (Requested range
- not satisfiable) (section 10.4.17).
-
- Note: clients cannot depend on servers to send a 416 (Requested
- range not satisfiable) response instead of a 200 (OK) response for
- an unsatisfiable Range request-header, since not all servers
- implement this request-header.
-
-14.17 Content-Type
-
- The Content-Type entity-header field indicates the media type of the
- entity-body sent to the recipient or, in the case of the HEAD method,
- the media type that would have been sent had the request been a GET.
-
- Content-Type = "Content-Type" ":" media-type
-
- Media types are defined in section 3.7. An example of the field is
-
- Content-Type: text/html; charset=ISO-8859-4
-
- Further discussion of methods for identifying the media type of an
- entity is provided in section 7.2.1.
-
-14.18 Date
-
- The Date general-header field represents the date and time at which
- the message was originated, having the same semantics as orig-date in
- RFC 822. The field value is an HTTP-date, as described in section
- 3.3.1; it MUST be sent in RFC 1123 [8]-date format.
-
- Date = "Date" ":" HTTP-date
-
- An example is
-
- Date: Tue, 15 Nov 1994 08:12:31 GMT
-
- Origin servers MUST include a Date header field in all responses,
- except in these cases:
-
-
-
-
-Fielding, et al. Standards Track [Page 124]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 1. If the response status code is 100 (Continue) or 101 (Switching
- Protocols), the response MAY include a Date header field, at
- the server's option.
-
- 2. If the response status code conveys a server error, e.g. 500
- (Internal Server Error) or 503 (Service Unavailable), and it is
- inconvenient or impossible to generate a valid Date.
-
- 3. If the server does not have a clock that can provide a
- reasonable approximation of the current time, its responses
- MUST NOT include a Date header field. In this case, the rules
- in section 14.18.1 MUST be followed.
-
- A received message that does not have a Date header field MUST be
- assigned one by the recipient if the message will be cached by that
- recipient or gatewayed via a protocol which requires a Date. An HTTP
- implementation without a clock MUST NOT cache responses without
- revalidating them on every use. An HTTP cache, especially a shared
- cache, SHOULD use a mechanism, such as NTP [28], to synchronize its
- clock with a reliable external standard.
-
- Clients SHOULD only send a Date header field in messages that include
- an entity-body, as in the case of the PUT and POST requests, and even
- then it is optional. A client without a clock MUST NOT send a Date
- header field in a request.
-
- The HTTP-date sent in a Date header SHOULD NOT represent a date and
- time subsequent to the generation of the message. It SHOULD represent
- the best available approximation of the date and time of message
- generation, unless the implementation has no means of generating a
- reasonably accurate date and time. In theory, the date ought to
- represent the moment just before the entity is generated. In
- practice, the date can be generated at any time during the message
- origination without affecting its semantic value.
-
-14.18.1 Clockless Origin Server Operation
-
- Some origin server implementations might not have a clock available.
- An origin server without a clock MUST NOT assign Expires or Last-
- Modified values to a response, unless these values were associated
- with the resource by a system or user with a reliable clock. It MAY
- assign an Expires value that is known, at or before server
- configuration time, to be in the past (this allows "pre-expiration"
- of responses without storing separate Expires values for each
- resource).
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 125]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.19 ETag
-
- The ETag response-header field provides the current value of the
- entity tag for the requested variant. The headers used with entity
- tags are described in sections 14.24, 14.26 and 14.44. The entity tag
- MAY be used for comparison with other entities from the same resource
- (see section 13.3.3).
-
- ETag = "ETag" ":" entity-tag
-
- Examples:
-
- ETag: "xyzzy"
- ETag: W/"xyzzy"
- ETag: ""
-
-14.20 Expect
-
- The Expect request-header field is used to indicate that particular
- server behaviors are required by the client.
-
- Expect = "Expect" ":" 1#expectation
-
- expectation = "100-continue" | expectation-extension
- expectation-extension = token [ "=" ( token | quoted-string )
- *expect-params ]
- expect-params = ";" token [ "=" ( token | quoted-string ) ]
-
-
- A server that does not understand or is unable to comply with any of
- the expectation values in the Expect field of a request MUST respond
- with appropriate error status. The server MUST respond with a 417
- (Expectation Failed) status if any of the expectations cannot be met
- or, if there are other problems with the request, some other 4xx
- status.
-
- This header field is defined with extensible syntax to allow for
- future extensions. If a server receives a request containing an
- Expect field that includes an expectation-extension that it does not
- support, it MUST respond with a 417 (Expectation Failed) status.
-
- Comparison of expectation values is case-insensitive for unquoted
- tokens (including the 100-continue token), and is case-sensitive for
- quoted-string expectation-extensions.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 126]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Expect mechanism is hop-by-hop: that is, an HTTP/1.1 proxy MUST
- return a 417 (Expectation Failed) status if it receives a request
- with an expectation that it cannot meet. However, the Expect
- request-header itself is end-to-end; it MUST be forwarded if the
- request is forwarded.
-
- Many older HTTP/1.0 and HTTP/1.1 applications do not understand the
- Expect header.
-
- See section 8.2.3 for the use of the 100 (continue) status.
-
-14.21 Expires
-
- The Expires entity-header field gives the date/time after which the
- response is considered stale. A stale cache entry may not normally be
- returned by a cache (either a proxy cache or a user agent cache)
- unless it is first validated with the origin server (or with an
- intermediate cache that has a fresh copy of the entity). See section
- 13.2 for further discussion of the expiration model.
-
- The presence of an Expires field does not imply that the original
- resource will change or cease to exist at, before, or after that
- time.
-
- The format is an absolute date and time as defined by HTTP-date in
- section 3.3.1; it MUST be in RFC 1123 date format:
-
- Expires = "Expires" ":" HTTP-date
-
- An example of its use is
-
- Expires: Thu, 01 Dec 1994 16:00:00 GMT
-
- Note: if a response includes a Cache-Control field with the max-
- age directive (see section 14.9.3), that directive overrides the
- Expires field.
-
- HTTP/1.1 clients and caches MUST treat other invalid date formats,
- especially including the value "0", as in the past (i.e., "already
- expired").
-
- To mark a response as "already expired," an origin server sends an
- Expires date that is equal to the Date header value. (See the rules
- for expiration calculations in section 13.2.4.)
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 127]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- To mark a response as "never expires," an origin server sends an
- Expires date approximately one year from the time the response is
- sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one
- year in the future.
-
- The presence of an Expires header field with a date value of some
- time in the future on a response that otherwise would by default be
- non-cacheable indicates that the response is cacheable, unless
- indicated otherwise by a Cache-Control header field (section 14.9).
-
-14.22 From
-
- The From request-header field, if given, SHOULD contain an Internet
- e-mail address for the human user who controls the requesting user
- agent. The address SHOULD be machine-usable, as defined by "mailbox"
- in RFC 822 [9] as updated by RFC 1123 [8]:
-
- From = "From" ":" mailbox
-
- An example is:
-
- From: webmaster at w3.org
-
- This header field MAY be used for logging purposes and as a means for
- identifying the source of invalid or unwanted requests. It SHOULD NOT
- be used as an insecure form of access protection. The interpretation
- of this field is that the request is being performed on behalf of the
- person given, who accepts responsibility for the method performed. In
- particular, robot agents SHOULD include this header so that the
- person responsible for running the robot can be contacted if problems
- occur on the receiving end.
-
- The Internet e-mail address in this field MAY be separate from the
- Internet host which issued the request. For example, when a request
- is passed through a proxy the original issuer's address SHOULD be
- used.
-
- The client SHOULD NOT send the From header field without the user's
- approval, as it might conflict with the user's privacy interests or
- their site's security policy. It is strongly recommended that the
- user be able to disable, enable, and modify the value of this field
- at any time prior to a request.
-
-14.23 Host
-
- The Host request-header field specifies the Internet host and port
- number of the resource being requested, as obtained from the original
- URI given by the user or referring resource (generally an HTTP URL,
-
-
-
-Fielding, et al. Standards Track [Page 128]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- as described in section 3.2.2). The Host field value MUST represent
- the naming authority of the origin server or gateway given by the
- original URL. This allows the origin server or gateway to
- differentiate between internally-ambiguous URLs, such as the root "/"
- URL of a server for multiple host names on a single IP address.
-
- Host = "Host" ":" host [ ":" port ] ; Section 3.2.2
-
- A "host" without any trailing port information implies the default
- port for the service requested (e.g., "80" for an HTTP URL). For
- example, a request on the origin server for
- <http://www.w3.org/pub/WWW/> would properly include:
-
- GET /pub/WWW/ HTTP/1.1
- Host: www.w3.org
-
- A client MUST include a Host header field in all HTTP/1.1 request
- messages . If the requested URI does not include an Internet host
- name for the service being requested, then the Host header field MUST
- be given with an empty value. An HTTP/1.1 proxy MUST ensure that any
- request message it forwards does contain an appropriate Host header
- field that identifies the service being requested by the proxy. All
- Internet-based HTTP/1.1 servers MUST respond with a 400 (Bad Request)
- status code to any HTTP/1.1 request message which lacks a Host header
- field.
-
- See sections 5.2 and 19.6.1.1 for other requirements relating to
- Host.
-
-14.24 If-Match
-
- The If-Match request-header field is used with a method to make it
- conditional. A client that has one or more entities previously
- obtained from the resource can verify that one of those entities is
- current by including a list of their associated entity tags in the
- If-Match header field. Entity tags are defined in section 3.11. The
- purpose of this feature is to allow efficient updates of cached
- information with a minimum amount of transaction overhead. It is also
- used, on updating requests, to prevent inadvertent modification of
- the wrong version of a resource. As a special case, the value "*"
- matches any current entity of the resource.
-
- If-Match = "If-Match" ":" ( "*" | 1#entity-tag )
-
- If any of the entity tags match the entity tag of the entity that
- would have been returned in the response to a similar GET request
- (without the If-Match header) on that resource, or if "*" is given
-
-
-
-
-Fielding, et al. Standards Track [Page 129]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- and any current entity exists for that resource, then the server MAY
- perform the requested method as if the If-Match header field did not
- exist.
-
- A server MUST use the strong comparison function (see section 13.3.3)
- to compare the entity tags in If-Match.
-
- If none of the entity tags match, or if "*" is given and no current
- entity exists, the server MUST NOT perform the requested method, and
- MUST return a 412 (Precondition Failed) response. This behavior is
- most useful when the client wants to prevent an updating method, such
- as PUT, from modifying a resource that has changed since the client
- last retrieved it.
-
- If the request would, without the If-Match header field, result in
- anything other than a 2xx or 412 status, then the If-Match header
- MUST be ignored.
-
- The meaning of "If-Match: *" is that the method SHOULD be performed
- if the representation selected by the origin server (or by a cache,
- possibly using the Vary mechanism, see section 14.44) exists, and
- MUST NOT be performed if the representation does not exist.
-
- A request intended to update a resource (e.g., a PUT) MAY include an
- If-Match header field to signal that the request method MUST NOT be
- applied if the entity corresponding to the If-Match value (a single
- entity tag) is no longer a representation of that resource. This
- allows the user to indicate that they do not wish the request to be
- successful if the resource has been changed without their knowledge.
- Examples:
-
- If-Match: "xyzzy"
- If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-Match: *
-
- The result of a request having both an If-Match header field and
- either an If-None-Match or an If-Modified-Since header fields is
- undefined by this specification.
-
-14.25 If-Modified-Since
-
- The If-Modified-Since request-header field is used with a method to
- make it conditional: if the requested variant has not been modified
- since the time specified in this field, an entity will not be
- returned from the server; instead, a 304 (not modified) response will
- be returned without any message-body.
-
- If-Modified-Since = "If-Modified-Since" ":" HTTP-date
-
-
-
-Fielding, et al. Standards Track [Page 130]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- An example of the field is:
-
- If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- A GET method with an If-Modified-Since header and no Range header
- requests that the identified entity be transferred only if it has
- been modified since the date given by the If-Modified-Since header.
- The algorithm for determining this includes the following cases:
-
- a) If the request would normally result in anything other than a
- 200 (OK) status, or if the passed If-Modified-Since date is
- invalid, the response is exactly the same as for a normal GET.
- A date which is later than the server's current time is
- invalid.
-
- b) If the variant has been modified since the If-Modified-Since
- date, the response is exactly the same as for a normal GET.
-
- c) If the variant has not been modified since a valid If-
- Modified-Since date, the server SHOULD return a 304 (Not
- Modified) response.
-
- The purpose of this feature is to allow efficient updates of cached
- information with a minimum amount of transaction overhead.
-
- Note: The Range request-header field modifies the meaning of If-
- Modified-Since; see section 14.35 for full details.
-
- Note: If-Modified-Since times are interpreted by the server, whose
- clock might not be synchronized with the client.
-
- Note: When handling an If-Modified-Since header field, some
- servers will use an exact date comparison function, rather than a
- less-than function, for deciding whether to send a 304 (Not
- Modified) response. To get best results when sending an If-
- Modified-Since header field for cache validation, clients are
- advised to use the exact date string received in a previous Last-
- Modified header field whenever possible.
-
- Note: If a client uses an arbitrary date in the If-Modified-Since
- header instead of a date taken from the Last-Modified header for
- the same request, the client should be aware of the fact that this
- date is interpreted in the server's understanding of time. The
- client should consider unsynchronized clocks and rounding problems
- due to the different encodings of time between the client and
- server. This includes the possibility of race conditions if the
- document has changed between the time it was first requested and
- the If-Modified-Since date of a subsequent request, and the
-
-
-
-Fielding, et al. Standards Track [Page 131]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- possibility of clock-skew-related problems if the If-Modified-
- Since date is derived from the client's clock without correction
- to the server's clock. Corrections for different time bases
- between client and server are at best approximate due to network
- latency.
-
- The result of a request having both an If-Modified-Since header field
- and either an If-Match or an If-Unmodified-Since header fields is
- undefined by this specification.
-
-14.26 If-None-Match
-
- The If-None-Match request-header field is used with a method to make
- it conditional. A client that has one or more entities previously
- obtained from the resource can verify that none of those entities is
- current by including a list of their associated entity tags in the
- If-None-Match header field. The purpose of this feature is to allow
- efficient updates of cached information with a minimum amount of
- transaction overhead. It is also used to prevent a method (e.g. PUT)
- from inadvertently modifying an existing resource when the client
- believes that the resource does not exist.
-
- As a special case, the value "*" matches any current entity of the
- resource.
-
- If-None-Match = "If-None-Match" ":" ( "*" | 1#entity-tag )
-
- If any of the entity tags match the entity tag of the entity that
- would have been returned in the response to a similar GET request
- (without the If-None-Match header) on that resource, or if "*" is
- given and any current entity exists for that resource, then the
- server MUST NOT perform the requested method, unless required to do
- so because the resource's modification date fails to match that
- supplied in an If-Modified-Since header field in the request.
- Instead, if the request method was GET or HEAD, the server SHOULD
- respond with a 304 (Not Modified) response, including the cache-
- related header fields (particularly ETag) of one of the entities that
- matched. For all other request methods, the server MUST respond with
- a status of 412 (Precondition Failed).
-
- See section 13.3.3 for rules on how to determine if two entities tags
- match. The weak comparison function can only be used with GET or HEAD
- requests.
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 132]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If none of the entity tags match, then the server MAY perform the
- requested method as if the If-None-Match header field did not exist,
- but MUST also ignore any If-Modified-Since header field(s) in the
- request. That is, if no entity tags match, then the server MUST NOT
- return a 304 (Not Modified) response.
-
- If the request would, without the If-None-Match header field, result
- in anything other than a 2xx or 304 status, then the If-None-Match
- header MUST be ignored. (See section 13.3.4 for a discussion of
- server behavior when both If-Modified-Since and If-None-Match appear
- in the same request.)
-
- The meaning of "If-None-Match: *" is that the method MUST NOT be
- performed if the representation selected by the origin server (or by
- a cache, possibly using the Vary mechanism, see section 14.44)
- exists, and SHOULD be performed if the representation does not exist.
- This feature is intended to be useful in preventing races between PUT
- operations.
-
- Examples:
-
- If-None-Match: "xyzzy"
- If-None-Match: W/"xyzzy"
- If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
- If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
- If-None-Match: *
-
- The result of a request having both an If-None-Match header field and
- either an If-Match or an If-Unmodified-Since header fields is
- undefined by this specification.
-
-14.27 If-Range
-
- If a client has a partial copy of an entity in its cache, and wishes
- to have an up-to-date copy of the entire entity in its cache, it
- could use the Range request-header with a conditional GET (using
- either or both of If-Unmodified-Since and If-Match.) However, if the
- condition fails because the entity has been modified, the client
- would then have to make a second request to obtain the entire current
- entity-body.
-
- The If-Range header allows a client to "short-circuit" the second
- request. Informally, its meaning is `if the entity is unchanged, send
- me the part(s) that I am missing; otherwise, send me the entire new
- entity'.
-
- If-Range = "If-Range" ":" ( entity-tag | HTTP-date )
-
-
-
-
-Fielding, et al. Standards Track [Page 133]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the client has no entity tag for an entity, but does have a Last-
- Modified date, it MAY use that date in an If-Range header. (The
- server can distinguish between a valid HTTP-date and any form of
- entity-tag by examining no more than two characters.) The If-Range
- header SHOULD only be used together with a Range header, and MUST be
- ignored if the request does not include a Range header, or if the
- server does not support the sub-range operation.
-
- If the entity tag given in the If-Range header matches the current
- entity tag for the entity, then the server SHOULD provide the
- specified sub-range of the entity using a 206 (Partial content)
- response. If the entity tag does not match, then the server SHOULD
- return the entire entity using a 200 (OK) response.
-
-14.28 If-Unmodified-Since
-
- The If-Unmodified-Since request-header field is used with a method to
- make it conditional. If the requested resource has not been modified
- since the time specified in this field, the server SHOULD perform the
- requested operation as if the If-Unmodified-Since header were not
- present.
-
- If the requested variant has been modified since the specified time,
- the server MUST NOT perform the requested operation, and MUST return
- a 412 (Precondition Failed).
-
- If-Unmodified-Since = "If-Unmodified-Since" ":" HTTP-date
-
- An example of the field is:
-
- If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
-
- If the request normally (i.e., without the If-Unmodified-Since
- header) would result in anything other than a 2xx or 412 status, the
- If-Unmodified-Since header SHOULD be ignored.
-
- If the specified date is invalid, the header is ignored.
-
- The result of a request having both an If-Unmodified-Since header
- field and either an If-None-Match or an If-Modified-Since header
- fields is undefined by this specification.
-
-14.29 Last-Modified
-
- The Last-Modified entity-header field indicates the date and time at
- which the origin server believes the variant was last modified.
-
- Last-Modified = "Last-Modified" ":" HTTP-date
-
-
-
-Fielding, et al. Standards Track [Page 134]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- An example of its use is
-
- Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
-
- The exact meaning of this header field depends on the implementation
- of the origin server and the nature of the original resource. For
- files, it may be just the file system last-modified time. For
- entities with dynamically included parts, it may be the most recent
- of the set of last-modify times for its component parts. For database
- gateways, it may be the last-update time stamp of the record. For
- virtual objects, it may be the last time the internal state changed.
-
- An origin server MUST NOT send a Last-Modified date which is later
- than the server's time of message origination. In such cases, where
- the resource's last modification would indicate some time in the
- future, the server MUST replace that date with the message
- origination date.
-
- An origin server SHOULD obtain the Last-Modified value of the entity
- as close as possible to the time that it generates the Date value of
- its response. This allows a recipient to make an accurate assessment
- of the entity's modification time, especially if the entity changes
- near the time that the response is generated.
-
- HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
-
-14.30 Location
-
- The Location response-header field is used to redirect the recipient
- to a location other than the Request-URI for completion of the
- request or identification of a new resource. For 201 (Created)
- responses, the Location is that of the new resource which was created
- by the request. For 3xx responses, the location SHOULD indicate the
- server's preferred URI for automatic redirection to the resource. The
- field value consists of a single absolute URI.
-
- Location = "Location" ":" absoluteURI
-
- An example is:
-
- Location: http://www.w3.org/pub/WWW/People.html
-
- Note: The Content-Location header field (section 14.14) differs
- from Location in that the Content-Location identifies the original
- location of the entity enclosed in the request. It is therefore
- possible for a response to contain header fields for both Location
- and Content-Location. Also see section 13.10 for cache
- requirements of some methods.
-
-
-
-Fielding, et al. Standards Track [Page 135]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.31 Max-Forwards
-
- The Max-Forwards request-header field provides a mechanism with the
- TRACE (section 9.8) and OPTIONS (section 9.2) methods to limit the
- number of proxies or gateways that can forward the request to the
- next inbound server. This can be useful when the client is attempting
- to trace a request chain which appears to be failing or looping in
- mid-chain.
-
- Max-Forwards = "Max-Forwards" ":" 1*DIGIT
-
- The Max-Forwards value is a decimal integer indicating the remaining
- number of times this request message may be forwarded.
-
- Each proxy or gateway recipient of a TRACE or OPTIONS request
- containing a Max-Forwards header field MUST check and update its
- value prior to forwarding the request. If the received value is zero
- (0), the recipient MUST NOT forward the request; instead, it MUST
- respond as the final recipient. If the received Max-Forwards value is
- greater than zero, then the forwarded message MUST contain an updated
- Max-Forwards field with a value decremented by one (1).
-
- The Max-Forwards header field MAY be ignored for all other methods
- defined by this specification and for any extension methods for which
- it is not explicitly referred to as part of that method definition.
-
-14.32 Pragma
-
- The Pragma general-header field is used to include implementation-
- specific directives that might apply to any recipient along the
- request/response chain. All pragma directives specify optional
- behavior from the viewpoint of the protocol; however, some systems
- MAY require that behavior be consistent with the directives.
-
- Pragma = "Pragma" ":" 1#pragma-directive
- pragma-directive = "no-cache" | extension-pragma
- extension-pragma = token [ "=" ( token | quoted-string ) ]
-
- When the no-cache directive is present in a request message, an
- application SHOULD forward the request toward the origin server even
- if it has a cached copy of what is being requested. This pragma
- directive has the same semantics as the no-cache cache-directive (see
- section 14.9) and is defined here for backward compatibility with
- HTTP/1.0. Clients SHOULD include both header fields when a no-cache
- request is sent to a server not known to be HTTP/1.1 compliant.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 136]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Pragma directives MUST be passed through by a proxy or gateway
- application, regardless of their significance to that application,
- since the directives might be applicable to all recipients along the
- request/response chain. It is not possible to specify a pragma for a
- specific recipient; however, any pragma directive not relevant to a
- recipient SHOULD be ignored by that recipient.
-
- HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had
- sent "Cache-Control: no-cache". No new Pragma directives will be
- defined in HTTP.
-
- Note: because the meaning of "Pragma: no-cache as a response
- header field is not actually specified, it does not provide a
- reliable replacement for "Cache-Control: no-cache" in a response
-
-14.33 Proxy-Authenticate
-
- The Proxy-Authenticate response-header field MUST be included as part
- of a 407 (Proxy Authentication Required) response. The field value
- consists of a challenge that indicates the authentication scheme and
- parameters applicable to the proxy for this Request-URI.
-
- Proxy-Authenticate = "Proxy-Authenticate" ":" 1#challenge
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. Unlike
- WWW-Authenticate, the Proxy-Authenticate header field applies only to
- the current connection and SHOULD NOT be passed on to downstream
- clients. However, an intermediate proxy might need to obtain its own
- credentials by requesting them from the downstream client, which in
- some circumstances will appear as if the proxy is forwarding the
- Proxy-Authenticate header field.
-
-14.34 Proxy-Authorization
-
- The Proxy-Authorization request-header field allows the client to
- identify itself (or its user) to a proxy which requires
- authentication. The Proxy-Authorization field value consists of
- credentials containing the authentication information of the user
- agent for the proxy and/or realm of the resource being requested.
-
- Proxy-Authorization = "Proxy-Authorization" ":" credentials
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43] . Unlike
- Authorization, the Proxy-Authorization header field applies only to
- the next outbound proxy that demanded authentication using the Proxy-
- Authenticate field. When multiple proxies are used in a chain, the
-
-
-
-Fielding, et al. Standards Track [Page 137]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Proxy-Authorization header field is consumed by the first outbound
- proxy that was expecting to receive credentials. A proxy MAY relay
- the credentials from the client request to the next proxy if that is
- the mechanism by which the proxies cooperatively authenticate a given
- request.
-
-14.35 Range
-
-14.35.1 Byte Ranges
-
- Since all HTTP entities are represented in HTTP messages as sequences
- of bytes, the concept of a byte range is meaningful for any HTTP
- entity. (However, not all clients and servers need to support byte-
- range operations.)
-
- Byte range specifications in HTTP apply to the sequence of bytes in
- the entity-body (not necessarily the same as the message-body).
-
- A byte range operation MAY specify a single range of bytes, or a set
- of ranges within a single entity.
-
- ranges-specifier = byte-ranges-specifier
- byte-ranges-specifier = bytes-unit "=" byte-range-set
- byte-range-set = 1#( byte-range-spec | suffix-byte-range-spec )
- byte-range-spec = first-byte-pos "-" [last-byte-pos]
- first-byte-pos = 1*DIGIT
- last-byte-pos = 1*DIGIT
-
- The first-byte-pos value in a byte-range-spec gives the byte-offset
- of the first byte in a range. The last-byte-pos value gives the
- byte-offset of the last byte in the range; that is, the byte
- positions specified are inclusive. Byte offsets start at zero.
-
- If the last-byte-pos value is present, it MUST be greater than or
- equal to the first-byte-pos in that byte-range-spec, or the byte-
- range-spec is syntactically invalid. The recipient of a byte-range-
- set that includes one or more syntactically invalid byte-range-spec
- values MUST ignore the header field that includes that byte-range-
- set.
-
- If the last-byte-pos value is absent, or if the value is greater than
- or equal to the current length of the entity-body, last-byte-pos is
- taken to be equal to one less than the current length of the entity-
- body in bytes.
-
- By its choice of last-byte-pos, a client can limit the number of
- bytes retrieved without knowing the size of the entity.
-
-
-
-
-Fielding, et al. Standards Track [Page 138]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- suffix-byte-range-spec = "-" suffix-length
- suffix-length = 1*DIGIT
-
- A suffix-byte-range-spec is used to specify the suffix of the
- entity-body, of a length given by the suffix-length value. (That is,
- this form specifies the last N bytes of an entity-body.) If the
- entity is shorter than the specified suffix-length, the entire
- entity-body is used.
-
- If a syntactically valid byte-range-set includes at least one byte-
- range-spec whose first-byte-pos is less than the current length of
- the entity-body, or at least one suffix-byte-range-spec with a non-
- zero suffix-length, then the byte-range-set is satisfiable.
- Otherwise, the byte-range-set is unsatisfiable. If the byte-range-set
- is unsatisfiable, the server SHOULD return a response with a status
- of 416 (Requested range not satisfiable). Otherwise, the server
- SHOULD return a response with a status of 206 (Partial Content)
- containing the satisfiable ranges of the entity-body.
-
- Examples of byte-ranges-specifier values (assuming an entity-body of
- length 10000):
-
- - The first 500 bytes (byte offsets 0-499, inclusive): bytes=0-
- 499
-
- - The second 500 bytes (byte offsets 500-999, inclusive):
- bytes=500-999
-
- - The final 500 bytes (byte offsets 9500-9999, inclusive):
- bytes=-500
-
- - Or bytes=9500-
-
- - The first and last bytes only (bytes 0 and 9999): bytes=0-0,-1
-
- - Several legal but not canonical specifications of the second 500
- bytes (byte offsets 500-999, inclusive):
- bytes=500-600,601-999
- bytes=500-700,601-999
-
-14.35.2 Range Retrieval Requests
-
- HTTP retrieval requests using conditional or unconditional GET
- methods MAY request one or more sub-ranges of the entity, instead of
- the entire entity, using the Range request header, which applies to
- the entity returned as the result of the request:
-
- Range = "Range" ":" ranges-specifier
-
-
-
-Fielding, et al. Standards Track [Page 139]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- A server MAY ignore the Range header. However, HTTP/1.1 origin
- servers and intermediate caches ought to support byte ranges when
- possible, since Range supports efficient recovery from partially
- failed transfers, and supports efficient partial retrieval of large
- entities.
-
- If the server supports the Range header and the specified range or
- ranges are appropriate for the entity:
-
- - The presence of a Range header in an unconditional GET modifies
- what is returned if the GET is otherwise successful. In other
- words, the response carries a status code of 206 (Partial
- Content) instead of 200 (OK).
-
- - The presence of a Range header in a conditional GET (a request
- using one or both of If-Modified-Since and If-None-Match, or
- one or both of If-Unmodified-Since and If-Match) modifies what
- is returned if the GET is otherwise successful and the
- condition is true. It does not affect the 304 (Not Modified)
- response returned if the conditional is false.
-
- In some cases, it might be more appropriate to use the If-Range
- header (see section 14.27) in addition to the Range header.
-
- If a proxy that supports ranges receives a Range request, forwards
- the request to an inbound server, and receives an entire entity in
- reply, it SHOULD only return the requested range to its client. It
- SHOULD store the entire received response in its cache if that is
- consistent with its cache allocation policies.
-
-14.36 Referer
-
- The Referer[sic] request-header field allows the client to specify,
- for the server's benefit, the address (URI) of the resource from
- which the Request-URI was obtained (the "referrer", although the
- header field is misspelled.) The Referer request-header allows a
- server to generate lists of back-links to resources for interest,
- logging, optimized caching, etc. It also allows obsolete or mistyped
- links to be traced for maintenance. The Referer field MUST NOT be
- sent if the Request-URI was obtained from a source that does not have
- its own URI, such as input from the user keyboard.
-
- Referer = "Referer" ":" ( absoluteURI | relativeURI )
-
- Example:
-
- Referer: http://www.w3.org/hypertext/DataSources/Overview.html
-
-
-
-
-Fielding, et al. Standards Track [Page 140]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If the field value is a relative URI, it SHOULD be interpreted
- relative to the Request-URI. The URI MUST NOT include a fragment. See
- section 15.1.3 for security considerations.
-
-14.37 Retry-After
-
- The Retry-After response-header field can be used with a 503 (Service
- Unavailable) response to indicate how long the service is expected to
- be unavailable to the requesting client. This field MAY also be used
- with any 3xx (Redirection) response to indicate the minimum time the
- user-agent is asked wait before issuing the redirected request. The
- value of this field can be either an HTTP-date or an integer number
- of seconds (in decimal) after the time of the response.
-
- Retry-After = "Retry-After" ":" ( HTTP-date | delta-seconds )
-
- Two examples of its use are
-
- Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
- Retry-After: 120
-
- In the latter example, the delay is 2 minutes.
-
-14.38 Server
-
- The Server response-header field contains information about the
- software used by the origin server to handle the request. The field
- can contain multiple product tokens (section 3.8) and comments
- identifying the server and any significant subproducts. The product
- tokens are listed in order of their significance for identifying the
- application.
-
- Server = "Server" ":" 1*( product | comment )
-
- Example:
-
- Server: CERN/3.0 libwww/2.17
-
- If the response is being forwarded through a proxy, the proxy
- application MUST NOT modify the Server response-header. Instead, it
- SHOULD include a Via field (as described in section 14.45).
-
- Note: Revealing the specific software version of the server might
- allow the server machine to become more vulnerable to attacks
- against software that is known to contain security holes. Server
- implementors are encouraged to make this field a configurable
- option.
-
-
-
-
-Fielding, et al. Standards Track [Page 141]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-14.39 TE
-
- The TE request-header field indicates what extension transfer-codings
- it is willing to accept in the response and whether or not it is
- willing to accept trailer fields in a chunked transfer-coding. Its
- value may consist of the keyword "trailers" and/or a comma-separated
- list of extension transfer-coding names with optional accept
- parameters (as described in section 3.6).
-
- TE = "TE" ":" #( t-codings )
- t-codings = "trailers" | ( transfer-extension [ accept-params ] )
-
- The presence of the keyword "trailers" indicates that the client is
- willing to accept trailer fields in a chunked transfer-coding, as
- defined in section 3.6.1. This keyword is reserved for use with
- transfer-coding values even though it does not itself represent a
- transfer-coding.
-
- Examples of its use are:
-
- TE: deflate
- TE:
- TE: trailers, deflate;q=0.5
-
- The TE header field only applies to the immediate connection.
- Therefore, the keyword MUST be supplied within a Connection header
- field (section 14.10) whenever TE is present in an HTTP/1.1 message.
-
- A server tests whether a transfer-coding is acceptable, according to
- a TE field, using these rules:
-
- 1. The "chunked" transfer-coding is always acceptable. If the
- keyword "trailers" is listed, the client indicates that it is
- willing to accept trailer fields in the chunked response on
- behalf of itself and any downstream clients. The implication is
- that, if given, the client is stating that either all
- downstream clients are willing to accept trailer fields in the
- forwarded response, or that it will attempt to buffer the
- response on behalf of downstream recipients.
-
- Note: HTTP/1.1 does not define any means to limit the size of a
- chunked response such that a client can be assured of buffering
- the entire response.
-
- 2. If the transfer-coding being tested is one of the transfer-
- codings listed in the TE field, then it is acceptable unless it
- is accompanied by a qvalue of 0. (As defined in section 3.9, a
- qvalue of 0 means "not acceptable.")
-
-
-
-Fielding, et al. Standards Track [Page 142]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 3. If multiple transfer-codings are acceptable, then the
- acceptable transfer-coding with the highest non-zero qvalue is
- preferred. The "chunked" transfer-coding always has a qvalue
- of 1.
-
- If the TE field-value is empty or if no TE field is present, the only
- transfer-coding is "chunked". A message with no transfer-coding is
- always acceptable.
-
-14.40 Trailer
-
- The Trailer general field value indicates that the given set of
- header fields is present in the trailer of a message encoded with
- chunked transfer-coding.
-
- Trailer = "Trailer" ":" 1#field-name
-
- An HTTP/1.1 message SHOULD include a Trailer header field in a
- message using chunked transfer-coding with a non-empty trailer. Doing
- so allows the recipient to know which header fields to expect in the
- trailer.
-
- If no Trailer header field is present, the trailer SHOULD NOT include
- any header fields. See section 3.6.1 for restrictions on the use of
- trailer fields in a "chunked" transfer-coding.
-
- Message header fields listed in the Trailer header field MUST NOT
- include the following header fields:
-
- . Transfer-Encoding
-
- . Content-Length
-
- . Trailer
-
-14.41 Transfer-Encoding
-
- The Transfer-Encoding general-header field indicates what (if any)
- type of transformation has been applied to the message body in order
- to safely transfer it between the sender and the recipient. This
- differs from the content-coding in that the transfer-coding is a
- property of the message, not of the entity.
-
- Transfer-Encoding = "Transfer-Encoding" ":" 1#transfer-coding
-
- Transfer-codings are defined in section 3.6. An example is:
-
- Transfer-Encoding: chunked
-
-
-
-Fielding, et al. Standards Track [Page 143]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- If multiple encodings have been applied to an entity, the transfer-
- codings MUST be listed in the order in which they were applied.
- Additional information about the encoding parameters MAY be provided
- by other entity-header fields not defined by this specification.
-
- Many older HTTP/1.0 applications do not understand the Transfer-
- Encoding header.
-
-14.42 Upgrade
-
- The Upgrade general-header allows the client to specify what
- additional communication protocols it supports and would like to use
- if the server finds it appropriate to switch protocols. The server
- MUST use the Upgrade header field within a 101 (Switching Protocols)
- response to indicate which protocol(s) are being switched.
-
- Upgrade = "Upgrade" ":" 1#product
-
- For example,
-
- Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11
-
- The Upgrade header field is intended to provide a simple mechanism
- for transition from HTTP/1.1 to some other, incompatible protocol. It
- does so by allowing the client to advertise its desire to use another
- protocol, such as a later version of HTTP with a higher major version
- number, even though the current request has been made using HTTP/1.1.
- This eases the difficult transition between incompatible protocols by
- allowing the client to initiate a request in the more commonly
- supported protocol while indicating to the server that it would like
- to use a "better" protocol if available (where "better" is determined
- by the server, possibly according to the nature of the method and/or
- resource being requested).
-
- The Upgrade header field only applies to switching application-layer
- protocols upon the existing transport-layer connection. Upgrade
- cannot be used to insist on a protocol change; its acceptance and use
- by the server is optional. The capabilities and nature of the
- application-layer communication after the protocol change is entirely
- dependent upon the new protocol chosen, although the first action
- after changing the protocol MUST be a response to the initial HTTP
- request containing the Upgrade header field.
-
- The Upgrade header field only applies to the immediate connection.
- Therefore, the upgrade keyword MUST be supplied within a Connection
- header field (section 14.10) whenever Upgrade is present in an
- HTTP/1.1 message.
-
-
-
-
-Fielding, et al. Standards Track [Page 144]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Upgrade header field cannot be used to indicate a switch to a
- protocol on a different connection. For that purpose, it is more
- appropriate to use a 301, 302, 303, or 305 redirection response.
-
- This specification only defines the protocol name "HTTP" for use by
- the family of Hypertext Transfer Protocols, as defined by the HTTP
- version rules of section 3.1 and future updates to this
- specification. Any token can be used as a protocol name; however, it
- will only be useful if both the client and server associate the name
- with the same protocol.
-
-14.43 User-Agent
-
- The User-Agent request-header field contains information about the
- user agent originating the request. This is for statistical purposes,
- the tracing of protocol violations, and automated recognition of user
- agents for the sake of tailoring responses to avoid particular user
- agent limitations. User agents SHOULD include this field with
- requests. The field can contain multiple product tokens (section 3.8)
- and comments identifying the agent and any subproducts which form a
- significant part of the user agent. By convention, the product tokens
- are listed in order of their significance for identifying the
- application.
-
- User-Agent = "User-Agent" ":" 1*( product | comment )
-
- Example:
-
- User-Agent: CERN-LineMode/2.15 libwww/2.17b3
-
-14.44 Vary
-
- The Vary field value indicates the set of request-header fields that
- fully determines, while the response is fresh, whether a cache is
- permitted to use the response to reply to a subsequent request
- without revalidation. For uncacheable or stale responses, the Vary
- field value advises the user agent about the criteria that were used
- to select the representation. A Vary field value of "*" implies that
- a cache cannot determine from the request headers of a subsequent
- request whether this response is the appropriate representation. See
- section 13.6 for use of the Vary header field by caches.
-
- Vary = "Vary" ":" ( "*" | 1#field-name )
-
- An HTTP/1.1 server SHOULD include a Vary header field with any
- cacheable response that is subject to server-driven negotiation.
- Doing so allows a cache to properly interpret future requests on that
- resource and informs the user agent about the presence of negotiation
-
-
-
-Fielding, et al. Standards Track [Page 145]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- on that resource. A server MAY include a Vary header field with a
- non-cacheable response that is subject to server-driven negotiation,
- since this might provide the user agent with useful information about
- the dimensions over which the response varies at the time of the
- response.
-
- A Vary field value consisting of a list of field-names signals that
- the representation selected for the response is based on a selection
- algorithm which considers ONLY the listed request-header field values
- in selecting the most appropriate representation. A cache MAY assume
- that the same selection will be made for future requests with the
- same values for the listed field names, for the duration of time for
- which the response is fresh.
-
- The field-names given are not limited to the set of standard
- request-header fields defined by this specification. Field names are
- case-insensitive.
-
- A Vary field value of "*" signals that unspecified parameters not
- limited to the request-headers (e.g., the network address of the
- client), play a role in the selection of the response representation.
- The "*" value MUST NOT be generated by a proxy server; it may only be
- generated by an origin server.
-
-14.45 Via
-
- The Via general-header field MUST be used by gateways and proxies to
- indicate the intermediate protocols and recipients between the user
- agent and the server on requests, and between the origin server and
- the client on responses. It is analogous to the "Received" field of
- RFC 822 [9] and is intended to be used for tracking message forwards,
- avoiding request loops, and identifying the protocol capabilities of
- all senders along the request/response chain.
-
- Via = "Via" ":" 1#( received-protocol received-by [ comment ] )
- received-protocol = [ protocol-name "/" ] protocol-version
- protocol-name = token
- protocol-version = token
- received-by = ( host [ ":" port ] ) | pseudonym
- pseudonym = token
-
- The received-protocol indicates the protocol version of the message
- received by the server or client along each segment of the
- request/response chain. The received-protocol version is appended to
- the Via field value when the message is forwarded so that information
- about the protocol capabilities of upstream applications remains
- visible to all recipients.
-
-
-
-
-Fielding, et al. Standards Track [Page 146]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The protocol-name is optional if and only if it would be "HTTP". The
- received-by field is normally the host and optional port number of a
- recipient server or client that subsequently forwarded the message.
- However, if the real host is considered to be sensitive information,
- it MAY be replaced by a pseudonym. If the port is not given, it MAY
- be assumed to be the default port of the received-protocol.
-
- Multiple Via field values represents each proxy or gateway that has
- forwarded the message. Each recipient MUST append its information
- such that the end result is ordered according to the sequence of
- forwarding applications.
-
- Comments MAY be used in the Via header field to identify the software
- of the recipient proxy or gateway, analogous to the User-Agent and
- Server header fields. However, all comments in the Via field are
- optional and MAY be removed by any recipient prior to forwarding the
- message.
-
- For example, a request message could be sent from an HTTP/1.0 user
- agent to an internal proxy code-named "fred", which uses HTTP/1.1 to
- forward the request to a public proxy at nowhere.com, which completes
- the request by forwarding it to the origin server at www.ics.uci.edu.
- The request received by www.ics.uci.edu would then have the following
- Via header field:
-
- Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1)
-
- Proxies and gateways used as a portal through a network firewall
- SHOULD NOT, by default, forward the names and ports of hosts within
- the firewall region. This information SHOULD only be propagated if
- explicitly enabled. If not enabled, the received-by host of any host
- behind the firewall SHOULD be replaced by an appropriate pseudonym
- for that host.
-
- For organizations that have strong privacy requirements for hiding
- internal structures, a proxy MAY combine an ordered subsequence of
- Via header field entries with identical received-protocol values into
- a single such entry. For example,
-
- Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
-
- could be collapsed to
-
- Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 147]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Applications SHOULD NOT combine multiple entries unless they are all
- under the same organizational control and the hosts have already been
- replaced by pseudonyms. Applications MUST NOT combine entries which
- have different received-protocol values.
-
-14.46 Warning
-
- The Warning general-header field is used to carry additional
- information about the status or transformation of a message which
- might not be reflected in the message. This information is typically
- used to warn about a possible lack of semantic transparency from
- caching operations or transformations applied to the entity body of
- the message.
-
- Warning headers are sent with responses using:
-
- Warning = "Warning" ":" 1#warning-value
-
- warning-value = warn-code SP warn-agent SP warn-text
- [SP warn-date]
-
- warn-code = 3DIGIT
- warn-agent = ( host [ ":" port ] ) | pseudonym
- ; the name or pseudonym of the server adding
- ; the Warning header, for use in debugging
- warn-text = quoted-string
- warn-date = <"> HTTP-date <">
-
- A response MAY carry more than one Warning header.
-
- The warn-text SHOULD be in a natural language and character set that
- is most likely to be intelligible to the human user receiving the
- response. This decision MAY be based on any available knowledge, such
- as the location of the cache or user, the Accept-Language field in a
- request, the Content-Language field in a response, etc. The default
- language is English and the default character set is ISO-8859-1.
-
- If a character set other than ISO-8859-1 is used, it MUST be encoded
- in the warn-text using the method described in RFC 2047 [14].
-
- Warning headers can in general be applied to any message, however
- some specific warn-codes are specific to caches and can only be
- applied to response messages. New Warning headers SHOULD be added
- after any existing Warning headers. A cache MUST NOT delete any
- Warning header that it received with a message. However, if a cache
- successfully validates a cache entry, it SHOULD remove any Warning
- headers previously attached to that entry except as specified for
-
-
-
-
-Fielding, et al. Standards Track [Page 148]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- specific Warning codes. It MUST then add any Warning headers received
- in the validating response. In other words, Warning headers are those
- that would be attached to the most recent relevant response.
-
- When multiple Warning headers are attached to a response, the user
- agent ought to inform the user of as many of them as possible, in the
- order that they appear in the response. If it is not possible to
- inform the user of all of the warnings, the user agent SHOULD follow
- these heuristics:
-
- - Warnings that appear early in the response take priority over
- those appearing later in the response.
-
- - Warnings in the user's preferred character set take priority
- over warnings in other character sets but with identical warn-
- codes and warn-agents.
-
- Systems that generate multiple Warning headers SHOULD order them with
- this user agent behavior in mind.
-
- Requirements for the behavior of caches with respect to Warnings are
- stated in section 13.1.2.
-
- This is a list of the currently-defined warn-codes, each with a
- recommended warn-text in English, and a description of its meaning.
-
- 110 Response is stale
- MUST be included whenever the returned response is stale.
-
- 111 Revalidation failed
- MUST be included if a cache returns a stale response because an
- attempt to revalidate the response failed, due to an inability to
- reach the server.
-
- 112 Disconnected operation
- SHOULD be included if the cache is intentionally disconnected from
- the rest of the network for a period of time.
-
- 113 Heuristic expiration
- MUST be included if the cache heuristically chose a freshness
- lifetime greater than 24 hours and the response's age is greater
- than 24 hours.
-
- 199 Miscellaneous warning
- The warning text MAY include arbitrary information to be presented
- to a human user, or logged. A system receiving this warning MUST
- NOT take any automated action, besides presenting the warning to
- the user.
-
-
-
-Fielding, et al. Standards Track [Page 149]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 214 Transformation applied
- MUST be added by an intermediate cache or proxy if it applies any
- transformation changing the content-coding (as specified in the
- Content-Encoding header) or media-type (as specified in the
- Content-Type header) of the response, or the entity-body of the
- response, unless this Warning code already appears in the response.
-
- 299 Miscellaneous persistent warning
- The warning text MAY include arbitrary information to be presented
- to a human user, or logged. A system receiving this warning MUST
- NOT take any automated action.
-
- If an implementation sends a message with one or more Warning headers
- whose version is HTTP/1.0 or lower, then the sender MUST include in
- each warning-value a warn-date that matches the date in the response.
-
- If an implementation receives a message with a warning-value that
- includes a warn-date, and that warn-date is different from the Date
- value in the response, then that warning-value MUST be deleted from
- the message before storing, forwarding, or using it. (This prevents
- bad consequences of naive caching of Warning header fields.) If all
- of the warning-values are deleted for this reason, the Warning header
- MUST be deleted as well.
-
-14.47 WWW-Authenticate
-
- The WWW-Authenticate response-header field MUST be included in 401
- (Unauthorized) response messages. The field value consists of at
- least one challenge that indicates the authentication scheme(s) and
- parameters applicable to the Request-URI.
-
- WWW-Authenticate = "WWW-Authenticate" ":" 1#challenge
-
- The HTTP access authentication process is described in "HTTP
- Authentication: Basic and Digest Access Authentication" [43]. User
- agents are advised to take special care in parsing the WWW-
- Authenticate field value as it might contain more than one challenge,
- or if more than one WWW-Authenticate header field is provided, the
- contents of a challenge itself can contain a comma-separated list of
- authentication parameters.
-
-15 Security Considerations
-
- This section is meant to inform application developers, information
- providers, and users of the security limitations in HTTP/1.1 as
- described by this document. The discussion does not include
- definitive solutions to the problems revealed, though it does make
- some suggestions for reducing security risks.
-
-
-
-Fielding, et al. Standards Track [Page 150]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.1 Personal Information
-
- HTTP clients are often privy to large amounts of personal information
- (e.g. the user's name, location, mail address, passwords, encryption
- keys, etc.), and SHOULD be very careful to prevent unintentional
- leakage of this information via the HTTP protocol to other sources.
- We very strongly recommend that a convenient interface be provided
- for the user to control dissemination of such information, and that
- designers and implementors be particularly careful in this area.
- History shows that errors in this area often create serious security
- and/or privacy problems and generate highly adverse publicity for the
- implementor's company.
-
-15.1.1 Abuse of Server Log Information
-
- A server is in the position to save personal data about a user's
- requests which might identify their reading patterns or subjects of
- interest. This information is clearly confidential in nature and its
- handling can be constrained by law in certain countries. People using
- the HTTP protocol to provide data are responsible for ensuring that
- such material is not distributed without the permission of any
- individuals that are identifiable by the published results.
-
-15.1.2 Transfer of Sensitive Information
-
- Like any generic data transfer protocol, HTTP cannot regulate the
- content of the data that is transferred, nor is there any a priori
- method of determining the sensitivity of any particular piece of
- information within the context of any given request. Therefore,
- applications SHOULD supply as much control over this information as
- possible to the provider of that information. Four header fields are
- worth special mention in this context: Server, Via, Referer and From.
-
- Revealing the specific software version of the server might allow the
- server machine to become more vulnerable to attacks against software
- that is known to contain security holes. Implementors SHOULD make the
- Server header field a configurable option.
-
- Proxies which serve as a portal through a network firewall SHOULD
- take special precautions regarding the transfer of header information
- that identifies the hosts behind the firewall. In particular, they
- SHOULD remove, or replace with sanitized versions, any Via fields
- generated behind the firewall.
-
- The Referer header allows reading patterns to be studied and reverse
- links drawn. Although it can be very useful, its power can be abused
- if user details are not separated from the information contained in
-
-
-
-
-Fielding, et al. Standards Track [Page 151]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- the Referer. Even when the personal information has been removed, the
- Referer header might indicate a private document's URI whose
- publication would be inappropriate.
-
- The information sent in the From field might conflict with the user's
- privacy interests or their site's security policy, and hence it
- SHOULD NOT be transmitted without the user being able to disable,
- enable, and modify the contents of the field. The user MUST be able
- to set the contents of this field within a user preference or
- application defaults configuration.
-
- We suggest, though do not require, that a convenient toggle interface
- be provided for the user to enable or disable the sending of From and
- Referer information.
-
- The User-Agent (section 14.43) or Server (section 14.38) header
- fields can sometimes be used to determine that a specific client or
- server have a particular security hole which might be exploited.
- Unfortunately, this same information is often used for other valuable
- purposes for which HTTP currently has no better mechanism.
-
-15.1.3 Encoding Sensitive Information in URI's
-
- Because the source of a link might be private information or might
- reveal an otherwise private information source, it is strongly
- recommended that the user be able to select whether or not the
- Referer field is sent. For example, a browser client could have a
- toggle switch for browsing openly/anonymously, which would
- respectively enable/disable the sending of Referer and From
- information.
-
- Clients SHOULD NOT include a Referer header field in a (non-secure)
- HTTP request if the referring page was transferred with a secure
- protocol.
-
- Authors of services which use the HTTP protocol SHOULD NOT use GET
- based forms for the submission of sensitive data, because this will
- cause this data to be encoded in the Request-URI. Many existing
- servers, proxies, and user agents will log the request URI in some
- place where it might be visible to third parties. Servers can use
- POST-based form submission instead
-
-15.1.4 Privacy Issues Connected to Accept Headers
-
- Accept request-headers can reveal information about the user to all
- servers which are accessed. The Accept-Language header in particular
- can reveal information the user would consider to be of a private
- nature, because the understanding of particular languages is often
-
-
-
-Fielding, et al. Standards Track [Page 152]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- strongly correlated to the membership of a particular ethnic group.
- User agents which offer the option to configure the contents of an
- Accept-Language header to be sent in every request are strongly
- encouraged to let the configuration process include a message which
- makes the user aware of the loss of privacy involved.
-
- An approach that limits the loss of privacy would be for a user agent
- to omit the sending of Accept-Language headers by default, and to ask
- the user whether or not to start sending Accept-Language headers to a
- server if it detects, by looking for any Vary response-header fields
- generated by the server, that such sending could improve the quality
- of service.
-
- Elaborate user-customized accept header fields sent in every request,
- in particular if these include quality values, can be used by servers
- as relatively reliable and long-lived user identifiers. Such user
- identifiers would allow content providers to do click-trail tracking,
- and would allow collaborating content providers to match cross-server
- click-trails or form submissions of individual users. Note that for
- many users not behind a proxy, the network address of the host
- running the user agent will also serve as a long-lived user
- identifier. In environments where proxies are used to enhance
- privacy, user agents ought to be conservative in offering accept
- header configuration options to end users. As an extreme privacy
- measure, proxies could filter the accept headers in relayed requests.
- General purpose user agents which provide a high degree of header
- configurability SHOULD warn users about the loss of privacy which can
- be involved.
-
-15.2 Attacks Based On File and Path Names
-
- Implementations of HTTP origin servers SHOULD be careful to restrict
- the documents returned by HTTP requests to be only those that were
- intended by the server administrators. If an HTTP server translates
- HTTP URIs directly into file system calls, the server MUST take
- special care not to serve files that were not intended to be
- delivered to HTTP clients. For example, UNIX, Microsoft Windows, and
- other operating systems use ".." as a path component to indicate a
- directory level above the current one. On such a system, an HTTP
- server MUST disallow any such construct in the Request-URI if it
- would otherwise allow access to a resource outside those intended to
- be accessible via the HTTP server. Similarly, files intended for
- reference only internally to the server (such as access control
- files, configuration files, and script code) MUST be protected from
- inappropriate retrieval, since they might contain sensitive
- information. Experience has shown that minor bugs in such HTTP server
- implementations have turned into security risks.
-
-
-
-
-Fielding, et al. Standards Track [Page 153]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.3 DNS Spoofing
-
- Clients using HTTP rely heavily on the Domain Name Service, and are
- thus generally prone to security attacks based on the deliberate
- mis-association of IP addresses and DNS names. Clients need to be
- cautious in assuming the continuing validity of an IP number/DNS name
- association.
-
- In particular, HTTP clients SHOULD rely on their name resolver for
- confirmation of an IP number/DNS name association, rather than
- caching the result of previous host name lookups. Many platforms
- already can cache host name lookups locally when appropriate, and
- they SHOULD be configured to do so. It is proper for these lookups to
- be cached, however, only when the TTL (Time To Live) information
- reported by the name server makes it likely that the cached
- information will remain useful.
-
- If HTTP clients cache the results of host name lookups in order to
- achieve a performance improvement, they MUST observe the TTL
- information reported by DNS.
-
- If HTTP clients do not observe this rule, they could be spoofed when
- a previously-accessed server's IP address changes. As network
- renumbering is expected to become increasingly common [24], the
- possibility of this form of attack will grow. Observing this
- requirement thus reduces this potential security vulnerability.
-
- This requirement also improves the load-balancing behavior of clients
- for replicated servers using the same DNS name and reduces the
- likelihood of a user's experiencing failure in accessing sites which
- use that strategy.
-
-15.4 Location Headers and Spoofing
-
- If a single server supports multiple organizations that do not trust
- one another, then it MUST check the values of Location and Content-
- Location headers in responses that are generated under control of
- said organizations to make sure that they do not attempt to
- invalidate resources over which they have no authority.
-
-15.5 Content-Disposition Issues
-
- RFC 1806 [35], from which the often implemented Content-Disposition
- (see section 19.5.1) header in HTTP is derived, has a number of very
- serious security considerations. Content-Disposition is not part of
- the HTTP standard, but since it is widely implemented, we are
- documenting its use and risks for implementors. See RFC 2183 [49]
- (which updates RFC 1806) for details.
-
-
-
-Fielding, et al. Standards Track [Page 154]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-15.6 Authentication Credentials and Idle Clients
-
- Existing HTTP clients and user agents typically retain authentication
- information indefinitely. HTTP/1.1. does not provide a method for a
- server to direct clients to discard these cached credentials. This is
- a significant defect that requires further extensions to HTTP.
- Circumstances under which credential caching can interfere with the
- application's security model include but are not limited to:
-
- - Clients which have been idle for an extended period following
- which the server might wish to cause the client to reprompt the
- user for credentials.
-
- - Applications which include a session termination indication
- (such as a `logout' or `commit' button on a page) after which
- the server side of the application `knows' that there is no
- further reason for the client to retain the credentials.
-
- This is currently under separate study. There are a number of work-
- arounds to parts of this problem, and we encourage the use of
- password protection in screen savers, idle time-outs, and other
- methods which mitigate the security problems inherent in this
- problem. In particular, user agents which cache credentials are
- encouraged to provide a readily accessible mechanism for discarding
- cached credentials under user control.
-
-15.7 Proxies and Caching
-
- By their very nature, HTTP proxies are men-in-the-middle, and
- represent an opportunity for man-in-the-middle attacks. Compromise of
- the systems on which the proxies run can result in serious security
- and privacy problems. Proxies have access to security-related
- information, personal information about individual users and
- organizations, and proprietary information belonging to users and
- content providers. A compromised proxy, or a proxy implemented or
- configured without regard to security and privacy considerations,
- might be used in the commission of a wide range of potential attacks.
-
- Proxy operators should protect the systems on which proxies run as
- they would protect any system that contains or transports sensitive
- information. In particular, log information gathered at proxies often
- contains highly sensitive personal information, and/or information
- about organizations. Log information should be carefully guarded, and
- appropriate guidelines for use developed and followed. (Section
- 15.1.1).
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 155]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Caching proxies provide additional potential vulnerabilities, since
- the contents of the cache represent an attractive target for
- malicious exploitation. Because cache contents persist after an HTTP
- request is complete, an attack on the cache can reveal information
- long after a user believes that the information has been removed from
- the network. Therefore, cache contents should be protected as
- sensitive information.
-
- Proxy implementors should consider the privacy and security
- implications of their design and coding decisions, and of the
- configuration options they provide to proxy operators (especially the
- default configuration).
-
- Users of a proxy need to be aware that they are no trustworthier than
- the people who run the proxy; HTTP itself cannot solve this problem.
-
- The judicious use of cryptography, when appropriate, may suffice to
- protect against a broad range of security and privacy attacks. Such
- cryptography is beyond the scope of the HTTP/1.1 specification.
-
-15.7.1 Denial of Service Attacks on Proxies
-
- They exist. They are hard to defend against. Research continues.
- Beware.
-
-16 Acknowledgments
-
- This specification makes heavy use of the augmented BNF and generic
- constructs defined by David H. Crocker for RFC 822 [9]. Similarly, it
- reuses many of the definitions provided by Nathaniel Borenstein and
- Ned Freed for MIME [7]. We hope that their inclusion in this
- specification will help reduce past confusion over the relationship
- between HTTP and Internet mail message formats.
-
- The HTTP protocol has evolved considerably over the years. It has
- benefited from a large and active developer community--the many
- people who have participated on the www-talk mailing list--and it is
- that community which has been most responsible for the success of
- HTTP and of the World-Wide Web in general. Marc Andreessen, Robert
- Cailliau, Daniel W. Connolly, Bob Denny, John Franks, Jean-Francois
- Groff, Phillip M. Hallam-Baker, Hakon W. Lie, Ari Luotonen, Rob
- McCool, Lou Montulli, Dave Raggett, Tony Sanders, and Marc
- VanHeyningen deserve special recognition for their efforts in
- defining early aspects of the protocol.
-
- This document has benefited greatly from the comments of all those
- participating in the HTTP-WG. In addition to those already mentioned,
- the following individuals have contributed to this specification:
-
-
-
-Fielding, et al. Standards Track [Page 156]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Gary Adams Ross Patterson
- Harald Tveit Alvestrand Albert Lunde
- Keith Ball John C. Mallery
- Brian Behlendorf Jean-Philippe Martin-Flatin
- Paul Burchard Mitra
- Maurizio Codogno David Morris
- Mike Cowlishaw Gavin Nicol
- Roman Czyborra Bill Perry
- Michael A. Dolan Jeffrey Perry
- David J. Fiander Scott Powers
- Alan Freier Owen Rees
- Marc Hedlund Luigi Rizzo
- Greg Herlihy David Robinson
- Koen Holtman Marc Salomon
- Alex Hopmann Rich Salz
- Bob Jernigan Allan M. Schiffman
- Shel Kaphan Jim Seidman
- Rohit Khare Chuck Shotton
- John Klensin Eric W. Sink
- Martijn Koster Simon E. Spero
- Alexei Kosut Richard N. Taylor
- David M. Kristol Robert S. Thau
- Daniel LaLiberte Bill (BearHeart) Weinman
- Ben Laurie Francois Yergeau
- Paul J. Leach Mary Ellen Zurko
- Daniel DuBois Josh Cohen
-
-
- Much of the content and presentation of the caching design is due to
- suggestions and comments from individuals including: Shel Kaphan,
- Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
-
- Most of the specification of ranges is based on work originally done
- by Ari Luotonen and John Franks, with additional input from Steve
- Zilles.
-
- Thanks to the "cave men" of Palo Alto. You know who you are.
-
- Jim Gettys (the current editor of this document) wishes particularly
- to thank Roy Fielding, the previous editor of this document, along
- with John Klensin, Jeff Mogul, Paul Leach, Dave Kristol, Koen
- Holtman, John Franks, Josh Cohen, Alex Hopmann, Scott Lawrence, and
- Larry Masinter for their help. And thanks go particularly to Jeff
- Mogul and Scott Lawrence for performing the "MUST/MAY/SHOULD" audit.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 157]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- The Apache Group, Anselm Baird-Smith, author of Jigsaw, and Henrik
- Frystyk implemented RFC 2068 early, and we wish to thank them for the
- discovery of many of the problems that this document attempts to
- rectify.
-
-17 References
-
- [1] Alvestrand, H., "Tags for the Identification of Languages", RFC
- 1766, March 1995.
-
- [2] Anklesaria, F., McCahill, M., Lindner, P., Johnson, D., Torrey,
- D. and B. Alberti, "The Internet Gopher Protocol (a distributed
- document search and retrieval protocol)", RFC 1436, March 1993.
-
- [3] Berners-Lee, T., "Universal Resource Identifiers in WWW", RFC
- 1630, June 1994.
-
- [4] Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform Resource
- Locators (URL)", RFC 1738, December 1994.
-
- [5] Berners-Lee, T. and D. Connolly, "Hypertext Markup Language -
- 2.0", RFC 1866, November 1995.
-
- [6] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext Transfer
- Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [7] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, November 1996.
-
- [8] Braden, R., "Requirements for Internet Hosts -- Communication
- Layers", STD 3, RFC 1123, October 1989.
-
- [9] Crocker, D., "Standard for The Format of ARPA Internet Text
- Messages", STD 11, RFC 822, August 1982.
-
- [10] Davis, F., Kahle, B., Morris, H., Salem, J., Shen, T., Wang, R.,
- Sui, J., and M. Grinbaum, "WAIS Interface Protocol Prototype
- Functional Specification," (v1.5), Thinking Machines
- Corporation, April 1990.
-
- [11] Fielding, R., "Relative Uniform Resource Locators", RFC 1808,
- June 1995.
-
- [12] Horton, M. and R. Adams, "Standard for Interchange of USENET
- Messages", RFC 1036, December 1987.
-
-
-
-
-
-Fielding, et al. Standards Track [Page 158]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- [13] Kantor, B. and P. Lapsley, "Network News Transfer Protocol", RFC
- 977, February 1986.
-
- [14] Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part
- Three: Message Header Extensions for Non-ASCII Text", RFC 2047,
- November 1996.
-
- [15] Nebel, E. and L. Masinter, "Form-based File Upload in HTML", RFC
- 1867, November 1995.
-
- [16] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821,
- August 1982.
-
- [17] Postel, J., "Media Type Registration Procedure", RFC 1590,
- November 1996.
-
- [18] Postel, J. and J. Reynolds, "File Transfer Protocol", STD 9, RFC
- 959, October 1985.
-
- [19] Reynolds, J. and J. Postel, "Assigned Numbers", STD 2, RFC 1700,
- October 1994.
-
- [20] Sollins, K. and L. Masinter, "Functional Requirements for
- Uniform Resource Names", RFC 1737, December 1994.
-
- [21] US-ASCII. Coded Character Set - 7-Bit American Standard Code for
- Information Interchange. Standard ANSI X3.4-1986, ANSI, 1986.
-
- [22] ISO-8859. International Standard -- Information Processing --
- 8-bit Single-Byte Coded Graphic Character Sets --
- Part 1: Latin alphabet No. 1, ISO-8859-1:1987.
- Part 2: Latin alphabet No. 2, ISO-8859-2, 1987.
- Part 3: Latin alphabet No. 3, ISO-8859-3, 1988.
- Part 4: Latin alphabet No. 4, ISO-8859-4, 1988.
- Part 5: Latin/Cyrillic alphabet, ISO-8859-5, 1988.
- Part 6: Latin/Arabic alphabet, ISO-8859-6, 1987.
- Part 7: Latin/Greek alphabet, ISO-8859-7, 1987.
- Part 8: Latin/Hebrew alphabet, ISO-8859-8, 1988.
- Part 9: Latin alphabet No. 5, ISO-8859-9, 1990.
-
- [23] Meyers, J. and M. Rose, "The Content-MD5 Header Field", RFC
- 1864, October 1995.
-
- [24] Carpenter, B. and Y. Rekhter, "Renumbering Needs Work", RFC
- 1900, February 1996.
-
- [25] Deutsch, P., "GZIP file format specification version 4.3", RFC
- 1952, May 1996.
-
-
-
-Fielding, et al. Standards Track [Page 159]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- [26] Venkata N. Padmanabhan, and Jeffrey C. Mogul. "Improving HTTP
- Latency", Computer Networks and ISDN Systems, v. 28, pp. 25-35,
- Dec. 1995. Slightly revised version of paper in Proc. 2nd
- International WWW Conference '94: Mosaic and the Web, Oct. 1994,
- which is available at
- http://www.ncsa.uiuc.edu/SDG/IT94/Proceedings/DDay/mogul/HTTPLat
- ency.html.
-
- [27] Joe Touch, John Heidemann, and Katia Obraczka. "Analysis of HTTP
- Performance", <URL: http://www.isi.edu/touch/pubs/http-perf96/>,
- ISI Research Report ISI/RR-98-463, (original report dated Aug.
- 1996), USC/Information Sciences Institute, August 1998.
-
- [28] Mills, D., "Network Time Protocol (Version 3) Specification,
- Implementation and Analysis", RFC 1305, March 1992.
-
- [29] Deutsch, P., "DEFLATE Compressed Data Format Specification
- version 1.3", RFC 1951, May 1996.
-
- [30] S. Spero, "Analysis of HTTP Performance Problems,"
- http://sunsite.unc.edu/mdma-release/http-prob.html.
-
- [31] Deutsch, P. and J. Gailly, "ZLIB Compressed Data Format
- Specification version 3.3", RFC 1950, May 1996.
-
- [32] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
- Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP:
- Digest Access Authentication", RFC 2069, January 1997.
-
- [33] Fielding, R., Gettys, J., Mogul, J., Frystyk, H. and T.
- Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC
- 2068, January 1997.
-
- [34] Bradner, S., "Key words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
- [35] Troost, R. and Dorner, S., "Communicating Presentation
- Information in Internet Messages: The Content-Disposition
- Header", RFC 1806, June 1995.
-
- [36] Mogul, J., Fielding, R., Gettys, J. and H. Frystyk, "Use and
- Interpretation of HTTP Version Numbers", RFC 2145, May 1997.
- [jg639]
-
- [37] Palme, J., "Common Internet Message Headers", RFC 2076, February
- 1997. [jg640]
-
-
-
-
-
-Fielding, et al. Standards Track [Page 160]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- [38] Yergeau, F., "UTF-8, a transformation format of Unicode and
- ISO-10646", RFC 2279, January 1998. [jg641]
-
- [39] Nielsen, H.F., Gettys, J., Baird-Smith, A., Prud'hommeaux, E.,
- Lie, H., and C. Lilley. "Network Performance Effects of
- HTTP/1.1, CSS1, and PNG," Proceedings of ACM SIGCOMM '97, Cannes
- France, September 1997.[jg642]
-
- [40] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Two: Media Types", RFC 2046, November
- 1996. [jg643]
-
- [41] Alvestrand, H., "IETF Policy on Character Sets and Languages",
- BCP 18, RFC 2277, January 1998. [jg644]
-
- [42] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI): Generic Syntax and Semantics", RFC 2396,
- August 1998. [jg645]
-
- [43] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
- Leach, P., Luotonen, A., Sink, E. and L. Stewart, "HTTP
- Authentication: Basic and Digest Access Authentication", RFC
- 2617, June 1999. [jg646]
-
- [44] Luotonen, A., "Tunneling TCP based protocols through Web proxy
- servers," Work in Progress. [jg647]
-
- [45] Palme, J. and A. Hopmann, "MIME E-mail Encapsulation of
- Aggregate Documents, such as HTML (MHTML)", RFC 2110, March
- 1997.
-
- [46] Bradner, S., "The Internet Standards Process -- Revision 3", BCP
- 9, RFC 2026, October 1996.
-
- [47] Masinter, L., "Hyper Text Coffee Pot Control Protocol
- (HTCPCP/1.0)", RFC 2324, 1 April 1998.
-
- [48] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) Part Five: Conformance Criteria and Examples",
- RFC 2049, November 1996.
-
- [49] Troost, R., Dorner, S. and K. Moore, "Communicating Presentation
- Information in Internet Messages: The Content-Disposition Header
- Field", RFC 2183, August 1997.
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 161]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-18 Authors' Addresses
-
- Roy T. Fielding
- Information and Computer Science
- University of California, Irvine
- Irvine, CA 92697-3425, USA
-
- Fax: +1 (949) 824-1715
- EMail: fielding at ics.uci.edu
-
-
- James Gettys
- World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: jg at w3.org
-
-
- Jeffrey C. Mogul
- Western Research Laboratory
- Compaq Computer Corporation
- 250 University Avenue
- Palo Alto, California, 94305, USA
-
- EMail: mogul at wrl.dec.com
-
-
- Henrik Frystyk Nielsen
- World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: frystyk at w3.org
-
-
- Larry Masinter
- Xerox Corporation
- 3333 Coyote Hill Road
- Palo Alto, CA 94034, USA
-
- EMail: masinter at parc.xerox.com
-
-
-
-
-
-Fielding, et al. Standards Track [Page 162]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Paul J. Leach
- Microsoft Corporation
- 1 Microsoft Way
- Redmond, WA 98052, USA
-
- EMail: paulle at microsoft.com
-
-
- Tim Berners-Lee
- Director, World Wide Web Consortium
- MIT Laboratory for Computer Science
- 545 Technology Square
- Cambridge, MA 02139, USA
-
- Fax: +1 (617) 258 8682
- EMail: timbl at w3.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 163]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-19 Appendices
-
-19.1 Internet Media Type message/http and application/http
-
- In addition to defining the HTTP/1.1 protocol, this document serves
- as the specification for the Internet media type "message/http" and
- "application/http". The message/http type can be used to enclose a
- single HTTP request or response message, provided that it obeys the
- MIME restrictions for all "message" types regarding line length and
- encodings. The application/http type can be used to enclose a
- pipeline of one or more HTTP request or response messages (not
- intermixed). The following is to be registered with IANA [17].
-
- Media Type name: message
- Media subtype name: http
- Required parameters: none
- Optional parameters: version, msgtype
- version: The HTTP-Version number of the enclosed message
- (e.g., "1.1"). If not present, the version can be
- determined from the first line of the body.
- msgtype: The message type -- "request" or "response". If not
- present, the type can be determined from the first
- line of the body.
- Encoding considerations: only "7bit", "8bit", or "binary" are
- permitted
- Security considerations: none
-
- Media Type name: application
- Media subtype name: http
- Required parameters: none
- Optional parameters: version, msgtype
- version: The HTTP-Version number of the enclosed messages
- (e.g., "1.1"). If not present, the version can be
- determined from the first line of the body.
- msgtype: The message type -- "request" or "response". If not
- present, the type can be determined from the first
- line of the body.
- Encoding considerations: HTTP messages enclosed by this type
- are in "binary" format; use of an appropriate
- Content-Transfer-Encoding is required when
- transmitted via E-mail.
- Security considerations: none
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 164]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-19.2 Internet Media Type multipart/byteranges
-
- When an HTTP 206 (Partial Content) response message includes the
- content of multiple ranges (a response to a request for multiple
- non-overlapping ranges), these are transmitted as a multipart
- message-body. The media type for this purpose is called
- "multipart/byteranges".
-
- The multipart/byteranges media type includes two or more parts, each
- with its own Content-Type and Content-Range fields. The required
- boundary parameter specifies the boundary string used to separate
- each body-part.
-
- Media Type name: multipart
- Media subtype name: byteranges
- Required parameters: boundary
- Optional parameters: none
- Encoding considerations: only "7bit", "8bit", or "binary" are
- permitted
- Security considerations: none
-
-
- For example:
-
- HTTP/1.1 206 Partial Content
- Date: Wed, 15 Nov 1995 06:25:24 GMT
- Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
- Content-type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
-
- --THIS_STRING_SEPARATES
- Content-type: application/pdf
- Content-range: bytes 500-999/8000
-
- ...the first range...
- --THIS_STRING_SEPARATES
- Content-type: application/pdf
- Content-range: bytes 7000-7999/8000
-
- ...the second range
- --THIS_STRING_SEPARATES--
-
- Notes:
-
- 1) Additional CRLFs may precede the first boundary string in the
- entity.
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 165]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- 2) Although RFC 2046 [40] permits the boundary string to be
- quoted, some existing implementations handle a quoted boundary
- string incorrectly.
-
- 3) A number of browsers and servers were coded to an early draft
- of the byteranges specification to use a media type of
- multipart/x-byteranges, which is almost, but not quite
- compatible with the version documented in HTTP/1.1.
-
-19.3 Tolerant Applications
-
- Although this document specifies the requirements for the generation
- of HTTP/1.1 messages, not all applications will be correct in their
- implementation. We therefore recommend that operational applications
- be tolerant of deviations whenever those deviations can be
- interpreted unambiguously.
-
- Clients SHOULD be tolerant in parsing the Status-Line and servers
- tolerant when parsing the Request-Line. In particular, they SHOULD
- accept any amount of SP or HT characters between fields, even though
- only a single SP is required.
-
- The line terminator for message-header fields is the sequence CRLF.
- However, we recommend that applications, when parsing such headers,
- recognize a single LF as a line terminator and ignore the leading CR.
-
- The character set of an entity-body SHOULD be labeled as the lowest
- common denominator of the character codes used within that body, with
- the exception that not labeling the entity is preferred over labeling
- the entity with the labels US-ASCII or ISO-8859-1. See section 3.7.1
- and 3.4.1.
-
- Additional rules for requirements on parsing and encoding of dates
- and other potential problems with date encodings include:
-
- - HTTP/1.1 clients and caches SHOULD assume that an RFC-850 date
- which appears to be more than 50 years in the future is in fact
- in the past (this helps solve the "year 2000" problem).
-
- - An HTTP/1.1 implementation MAY internally represent a parsed
- Expires date as earlier than the proper value, but MUST NOT
- internally represent a parsed Expires date as later than the
- proper value.
-
- - All expiration-related calculations MUST be done in GMT. The
- local time zone MUST NOT influence the calculation or comparison
- of an age or expiration time.
-
-
-
-
-Fielding, et al. Standards Track [Page 166]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - If an HTTP header incorrectly carries a date value with a time
- zone other than GMT, it MUST be converted into GMT using the
- most conservative possible conversion.
-
-19.4 Differences Between HTTP Entities and RFC 2045 Entities
-
- HTTP/1.1 uses many of the constructs defined for Internet Mail (RFC
- 822 [9]) and the Multipurpose Internet Mail Extensions (MIME [7]) to
- allow entities to be transmitted in an open variety of
- representations and with extensible mechanisms. However, RFC 2045
- discusses mail, and HTTP has a few features that are different from
- those described in RFC 2045. These differences were carefully chosen
- to optimize performance over binary connections, to allow greater
- freedom in the use of new media types, to make date comparisons
- easier, and to acknowledge the practice of some early HTTP servers
- and clients.
-
- This appendix describes specific areas where HTTP differs from RFC
- 2045. Proxies and gateways to strict MIME environments SHOULD be
- aware of these differences and provide the appropriate conversions
- where necessary. Proxies and gateways from MIME environments to HTTP
- also need to be aware of the differences because some conversions
- might be required.
-
-19.4.1 MIME-Version
-
- HTTP is not a MIME-compliant protocol. However, HTTP/1.1 messages MAY
- include a single MIME-Version general-header field to indicate what
- version of the MIME protocol was used to construct the message. Use
- of the MIME-Version header field indicates that the message is in
- full compliance with the MIME protocol (as defined in RFC 2045[7]).
- Proxies/gateways are responsible for ensuring full compliance (where
- possible) when exporting HTTP messages to strict MIME environments.
-
- MIME-Version = "MIME-Version" ":" 1*DIGIT "." 1*DIGIT
-
- MIME version "1.0" is the default for use in HTTP/1.1. However,
- HTTP/1.1 message parsing and semantics are defined by this document
- and not the MIME specification.
-
-19.4.2 Conversion to Canonical Form
-
- RFC 2045 [7] requires that an Internet mail entity be converted to
- canonical form prior to being transferred, as described in section 4
- of RFC 2049 [48]. Section 3.7.1 of this document describes the forms
- allowed for subtypes of the "text" media type when transmitted over
- HTTP. RFC 2046 requires that content with a type of "text" represent
- line breaks as CRLF and forbids the use of CR or LF outside of line
-
-
-
-Fielding, et al. Standards Track [Page 167]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- break sequences. HTTP allows CRLF, bare CR, and bare LF to indicate a
- line break within text content when a message is transmitted over
- HTTP.
-
- Where it is possible, a proxy or gateway from HTTP to a strict MIME
- environment SHOULD translate all line breaks within the text media
- types described in section 3.7.1 of this document to the RFC 2049
- canonical form of CRLF. Note, however, that this might be complicated
- by the presence of a Content-Encoding and by the fact that HTTP
- allows the use of some character sets which do not use octets 13 and
- 10 to represent CR and LF, as is the case for some multi-byte
- character sets.
-
- Implementors should note that conversion will break any cryptographic
- checksums applied to the original content unless the original content
- is already in canonical form. Therefore, the canonical form is
- recommended for any content that uses such checksums in HTTP.
-
-19.4.3 Conversion of Date Formats
-
- HTTP/1.1 uses a restricted set of date formats (section 3.3.1) to
- simplify the process of date comparison. Proxies and gateways from
- other protocols SHOULD ensure that any Date header field present in a
- message conforms to one of the HTTP/1.1 formats and rewrite the date
- if necessary.
-
-19.4.4 Introduction of Content-Encoding
-
- RFC 2045 does not include any concept equivalent to HTTP/1.1's
- Content-Encoding header field. Since this acts as a modifier on the
- media type, proxies and gateways from HTTP to MIME-compliant
- protocols MUST either change the value of the Content-Type header
- field or decode the entity-body before forwarding the message. (Some
- experimental applications of Content-Type for Internet mail have used
- a media-type parameter of ";conversions=<content-coding>" to perform
- a function equivalent to Content-Encoding. However, this parameter is
- not part of RFC 2045.)
-
-19.4.5 No Content-Transfer-Encoding
-
- HTTP does not use the Content-Transfer-Encoding (CTE) field of RFC
- 2045. Proxies and gateways from MIME-compliant protocols to HTTP MUST
- remove any non-identity CTE ("quoted-printable" or "base64") encoding
- prior to delivering the response message to an HTTP client.
-
- Proxies and gateways from HTTP to MIME-compliant protocols are
- responsible for ensuring that the message is in the correct format
- and encoding for safe transport on that protocol, where "safe
-
-
-
-Fielding, et al. Standards Track [Page 168]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- transport" is defined by the limitations of the protocol being used.
- Such a proxy or gateway SHOULD label the data with an appropriate
- Content-Transfer-Encoding if doing so will improve the likelihood of
- safe transport over the destination protocol.
-
-19.4.6 Introduction of Transfer-Encoding
-
- HTTP/1.1 introduces the Transfer-Encoding header field (section
- 14.41). Proxies/gateways MUST remove any transfer-coding prior to
- forwarding a message via a MIME-compliant protocol.
-
- A process for decoding the "chunked" transfer-coding (section 3.6)
- can be represented in pseudo-code as:
-
- length := 0
- read chunk-size, chunk-extension (if any) and CRLF
- while (chunk-size > 0) {
- read chunk-data and CRLF
- append chunk-data to entity-body
- length := length + chunk-size
- read chunk-size and CRLF
- }
- read entity-header
- while (entity-header not empty) {
- append entity-header to existing header fields
- read entity-header
- }
- Content-Length := length
- Remove "chunked" from Transfer-Encoding
-
-19.4.7 MHTML and Line Length Limitations
-
- HTTP implementations which share code with MHTML [45] implementations
- need to be aware of MIME line length limitations. Since HTTP does not
- have this limitation, HTTP does not fold long lines. MHTML messages
- being transported by HTTP follow all conventions of MHTML, including
- line length limitations and folding, canonicalization, etc., since
- HTTP transports all message-bodies as payload (see section 3.7.2) and
- does not interpret the content or any MIME header lines that might be
- contained therein.
-
-19.5 Additional Features
-
- RFC 1945 and RFC 2068 document protocol elements used by some
- existing HTTP implementations, but not consistently and correctly
- across most HTTP/1.1 applications. Implementors are advised to be
- aware of these features, but cannot rely upon their presence in, or
- interoperability with, other HTTP/1.1 applications. Some of these
-
-
-
-Fielding, et al. Standards Track [Page 169]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- describe proposed experimental features, and some describe features
- that experimental deployment found lacking that are now addressed in
- the base HTTP/1.1 specification.
-
- A number of other headers, such as Content-Disposition and Title,
- from SMTP and MIME are also often implemented (see RFC 2076 [37]).
-
-19.5.1 Content-Disposition
-
- The Content-Disposition response-header field has been proposed as a
- means for the origin server to suggest a default filename if the user
- requests that the content is saved to a file. This usage is derived
- from the definition of Content-Disposition in RFC 1806 [35].
-
- content-disposition = "Content-Disposition" ":"
- disposition-type *( ";" disposition-parm )
- disposition-type = "attachment" | disp-extension-token
- disposition-parm = filename-parm | disp-extension-parm
- filename-parm = "filename" "=" quoted-string
- disp-extension-token = token
- disp-extension-parm = token "=" ( token | quoted-string )
-
- An example is
-
- Content-Disposition: attachment; filename="fname.ext"
-
- The receiving user agent SHOULD NOT respect any directory path
- information present in the filename-parm parameter, which is the only
- parameter believed to apply to HTTP implementations at this time. The
- filename SHOULD be treated as a terminal component only.
-
- If this header is used in a response with the application/octet-
- stream content-type, the implied suggestion is that the user agent
- should not display the response, but directly enter a `save response
- as...' dialog.
-
- See section 15.5 for Content-Disposition security issues.
-
-19.6 Compatibility with Previous Versions
-
- It is beyond the scope of a protocol specification to mandate
- compliance with previous versions. HTTP/1.1 was deliberately
- designed, however, to make supporting previous versions easy. It is
- worth noting that, at the time of composing this specification
- (1996), we would expect commercial HTTP/1.1 servers to:
-
- - recognize the format of the Request-Line for HTTP/0.9, 1.0, and
- 1.1 requests;
-
-
-
-Fielding, et al. Standards Track [Page 170]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- - understand any valid request in the format of HTTP/0.9, 1.0, or
- 1.1;
-
- - respond appropriately with a message in the same major version
- used by the client.
-
- And we would expect HTTP/1.1 clients to:
-
- - recognize the format of the Status-Line for HTTP/1.0 and 1.1
- responses;
-
- - understand any valid response in the format of HTTP/0.9, 1.0, or
- 1.1.
-
- For most implementations of HTTP/1.0, each connection is established
- by the client prior to the request and closed by the server after
- sending the response. Some implementations implement the Keep-Alive
- version of persistent connections described in section 19.7.1 of RFC
- 2068 [33].
-
-19.6.1 Changes from HTTP/1.0
-
- This section summarizes major differences between versions HTTP/1.0
- and HTTP/1.1.
-
-19.6.1.1 Changes to Simplify Multi-homed Web Servers and Conserve IP
- Addresses
-
- The requirements that clients and servers support the Host request-
- header, report an error if the Host request-header (section 14.23) is
- missing from an HTTP/1.1 request, and accept absolute URIs (section
- 5.1.2) are among the most important changes defined by this
- specification.
-
- Older HTTP/1.0 clients assumed a one-to-one relationship of IP
- addresses and servers; there was no other established mechanism for
- distinguishing the intended server of a request than the IP address
- to which that request was directed. The changes outlined above will
- allow the Internet, once older HTTP clients are no longer common, to
- support multiple Web sites from a single IP address, greatly
- simplifying large operational Web servers, where allocation of many
- IP addresses to a single host has created serious problems. The
- Internet will also be able to recover the IP addresses that have been
- allocated for the sole purpose of allowing special-purpose domain
- names to be used in root-level HTTP URLs. Given the rate of growth of
- the Web, and the number of servers already deployed, it is extremely
-
-
-
-
-
-Fielding, et al. Standards Track [Page 171]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- important that all implementations of HTTP (including updates to
- existing HTTP/1.0 applications) correctly implement these
- requirements:
-
- - Both clients and servers MUST support the Host request-header.
-
- - A client that sends an HTTP/1.1 request MUST send a Host header.
-
- - Servers MUST report a 400 (Bad Request) error if an HTTP/1.1
- request does not include a Host request-header.
-
- - Servers MUST accept absolute URIs.
-
-19.6.2 Compatibility with HTTP/1.0 Persistent Connections
-
- Some clients and servers might wish to be compatible with some
- previous implementations of persistent connections in HTTP/1.0
- clients and servers. Persistent connections in HTTP/1.0 are
- explicitly negotiated as they are not the default behavior. HTTP/1.0
- experimental implementations of persistent connections are faulty,
- and the new facilities in HTTP/1.1 are designed to rectify these
- problems. The problem was that some existing 1.0 clients may be
- sending Keep-Alive to a proxy server that doesn't understand
- Connection, which would then erroneously forward it to the next
- inbound server, which would establish the Keep-Alive connection and
- result in a hung HTTP/1.0 proxy waiting for the close on the
- response. The result is that HTTP/1.0 clients must be prevented from
- using Keep-Alive when talking to proxies.
-
- However, talking to proxies is the most important use of persistent
- connections, so that prohibition is clearly unacceptable. Therefore,
- we need some other mechanism for indicating a persistent connection
- is desired, which is safe to use even when talking to an old proxy
- that ignores Connection. Persistent connections are the default for
- HTTP/1.1 messages; we introduce a new keyword (Connection: close) for
- declaring non-persistence. See section 14.10.
-
- The original HTTP/1.0 form of persistent connections (the Connection:
- Keep-Alive and Keep-Alive header) is documented in RFC 2068. [33]
-
-19.6.3 Changes from RFC 2068
-
- This specification has been carefully audited to correct and
- disambiguate key word usage; RFC 2068 had many problems in respect to
- the conventions laid out in RFC 2119 [34].
-
- Clarified which error code should be used for inbound server failures
- (e.g. DNS failures). (Section 10.5.5).
-
-
-
-Fielding, et al. Standards Track [Page 172]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- CREATE had a race that required an Etag be sent when a resource is
- first created. (Section 10.2.2).
-
- Content-Base was deleted from the specification: it was not
- implemented widely, and there is no simple, safe way to introduce it
- without a robust extension mechanism. In addition, it is used in a
- similar, but not identical fashion in MHTML [45].
-
- Transfer-coding and message lengths all interact in ways that
- required fixing exactly when chunked encoding is used (to allow for
- transfer encoding that may not be self delimiting); it was important
- to straighten out exactly how message lengths are computed. (Sections
- 3.6, 4.4, 7.2.2, 13.5.2, 14.13, 14.16)
-
- A content-coding of "identity" was introduced, to solve problems
- discovered in caching. (section 3.5)
-
- Quality Values of zero should indicate that "I don't want something"
- to allow clients to refuse a representation. (Section 3.9)
-
- The use and interpretation of HTTP version numbers has been clarified
- by RFC 2145. Require proxies to upgrade requests to highest protocol
- version they support to deal with problems discovered in HTTP/1.0
- implementations (Section 3.1)
-
- Charset wildcarding is introduced to avoid explosion of character set
- names in accept headers. (Section 14.2)
-
- A case was missed in the Cache-Control model of HTTP/1.1; s-maxage
- was introduced to add this missing case. (Sections 13.4, 14.8, 14.9,
- 14.9.3)
-
- The Cache-Control: max-age directive was not properly defined for
- responses. (Section 14.9.3)
-
- There are situations where a server (especially a proxy) does not
- know the full length of a response but is capable of serving a
- byterange request. We therefore need a mechanism to allow byteranges
- with a content-range not indicating the full length of the message.
- (Section 14.16)
-
- Range request responses would become very verbose if all meta-data
- were always returned; by allowing the server to only send needed
- headers in a 206 response, this problem can be avoided. (Section
- 10.2.7, 13.5.3, and 14.27)
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 173]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Fix problem with unsatisfiable range requests; there are two cases:
- syntactic problems, and range doesn't exist in the document. The 416
- status code was needed to resolve this ambiguity needed to indicate
- an error for a byte range request that falls outside of the actual
- contents of a document. (Section 10.4.17, 14.16)
-
- Rewrite of message transmission requirements to make it much harder
- for implementors to get it wrong, as the consequences of errors here
- can have significant impact on the Internet, and to deal with the
- following problems:
-
- 1. Changing "HTTP/1.1 or later" to "HTTP/1.1", in contexts where
- this was incorrectly placing a requirement on the behavior of
- an implementation of a future version of HTTP/1.x
-
- 2. Made it clear that user-agents should retry requests, not
- "clients" in general.
-
- 3. Converted requirements for clients to ignore unexpected 100
- (Continue) responses, and for proxies to forward 100 responses,
- into a general requirement for 1xx responses.
-
- 4. Modified some TCP-specific language, to make it clearer that
- non-TCP transports are possible for HTTP.
-
- 5. Require that the origin server MUST NOT wait for the request
- body before it sends a required 100 (Continue) response.
-
- 6. Allow, rather than require, a server to omit 100 (Continue) if
- it has already seen some of the request body.
-
- 7. Allow servers to defend against denial-of-service attacks and
- broken clients.
-
- This change adds the Expect header and 417 status code. The message
- transmission requirements fixes are in sections 8.2, 10.4.18,
- 8.1.2.2, 13.11, and 14.20.
-
- Proxies should be able to add Content-Length when appropriate.
- (Section 13.5.2)
-
- Clean up confusion between 403 and 404 responses. (Section 10.4.4,
- 10.4.5, and 10.4.11)
-
- Warnings could be cached incorrectly, or not updated appropriately.
- (Section 13.1.2, 13.2.4, 13.5.2, 13.5.3, 14.9.3, and 14.46) Warning
- also needed to be a general header, as PUT or other methods may have
- need for it in requests.
-
-
-
-Fielding, et al. Standards Track [Page 174]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
- Transfer-coding had significant problems, particularly with
- interactions with chunked encoding. The solution is that transfer-
- codings become as full fledged as content-codings. This involves
- adding an IANA registry for transfer-codings (separate from content
- codings), a new header field (TE) and enabling trailer headers in the
- future. Transfer encoding is a major performance benefit, so it was
- worth fixing [39]. TE also solves another, obscure, downward
- interoperability problem that could have occurred due to interactions
- between authentication trailers, chunked encoding and HTTP/1.0
- clients.(Section 3.6, 3.6.1, and 14.39)
-
- The PATCH, LINK, UNLINK methods were defined but not commonly
- implemented in previous versions of this specification. See RFC 2068
- [33].
-
- The Alternates, Content-Version, Derived-From, Link, URI, Public and
- Content-Base header fields were defined in previous versions of this
- specification, but not commonly implemented. See RFC 2068 [33].
-
-20 Index
-
- Please see the PostScript version of this RFC for the INDEX.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 175]
-
-RFC 2616 HTTP/1.1 June 1999
-
-
-21. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Fielding, et al. Standards Track [Page 176]
-
Copied: CalendarServer/trunk/doc/RFC/rfc2617-HTTP Auth.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc2617.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2617-HTTP Auth.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc2617-HTTP Auth.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,1907 @@
+
+
+
+
+
+
+Network Working Group J. Franks
+Request for Comments: 2617 Northwestern University
+Obsoletes: 2069 P. Hallam-Baker
+Category: Standards Track Verisign, Inc.
+ J. Hostetler
+ AbiSource, Inc.
+ S. Lawrence
+ Agranat Systems, Inc.
+ P. Leach
+ Microsoft Corporation
+ A. Luotonen
+ Netscape Communications Corporation
+ L. Stewart
+ Open Market, Inc.
+ June 1999
+
+
+ HTTP Authentication: Basic and Digest Access Authentication
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+Abstract
+
+ "HTTP/1.0", includes the specification for a Basic Access
+ Authentication scheme. This scheme is not considered to be a secure
+ method of user authentication (unless used in conjunction with some
+ external secure system such as SSL [5]), as the user name and
+ password are passed over the network as cleartext.
+
+ This document also provides the specification for HTTP's
+ authentication framework, the original Basic authentication scheme
+ and a scheme based on cryptographic hashes, referred to as "Digest
+ Access Authentication". It is therefore also intended to serve as a
+ replacement for RFC 2069 [6]. Some optional elements specified by
+ RFC 2069 have been removed from this specification due to problems
+ found since its publication; other new elements have been added for
+ compatibility, those new elements have been made optional, but are
+ strongly recommended.
+
+
+
+Franks, et al. Standards Track [Page 1]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ Like Basic, Digest access authentication verifies that both parties
+ to a communication know a shared secret (a password); unlike Basic,
+ this verification can be done without sending the password in the
+ clear, which is Basic's biggest weakness. As with most other
+ authentication protocols, the greatest sources of risks are usually
+ found not in the core protocol itself but in policies and procedures
+ surrounding its use.
+
+Table of Contents
+
+ 1 Access Authentication................................ 3
+ 1.1 Reliance on the HTTP/1.1 Specification............ 3
+ 1.2 Access Authentication Framework................... 3
+ 2 Basic Authentication Scheme.......................... 5
+ 3 Digest Access Authentication Scheme.................. 6
+ 3.1 Introduction...................................... 6
+ 3.1.1 Purpose......................................... 6
+ 3.1.2 Overall Operation............................... 6
+ 3.1.3 Representation of digest values................. 7
+ 3.1.4 Limitations..................................... 7
+ 3.2 Specification of Digest Headers................... 7
+ 3.2.1 The WWW-Authenticate Response Header............ 8
+ 3.2.2 The Authorization Request Header................ 11
+ 3.2.3 The Authentication-Info Header.................. 15
+ 3.3 Digest Operation.................................. 17
+ 3.4 Security Protocol Negotiation..................... 18
+ 3.5 Example........................................... 18
+ 3.6 Proxy-Authentication and Proxy-Authorization...... 19
+ 4 Security Considerations.............................. 19
+ 4.1 Authentication of Clients using Basic
+ Authentication.................................... 19
+ 4.2 Authentication of Clients using Digest
+ Authentication.................................... 20
+ 4.3 Limited Use Nonce Values.......................... 21
+ 4.4 Comparison of Digest with Basic Authentication.... 22
+ 4.5 Replay Attacks.................................... 22
+ 4.6 Weakness Created by Multiple Authentication
+ Schemes........................................... 23
+ 4.7 Online dictionary attacks......................... 23
+ 4.8 Man in the Middle................................. 24
+ 4.9 Chosen plaintext attacks.......................... 24
+ 4.10 Precomputed dictionary attacks.................... 25
+ 4.11 Batch brute force attacks......................... 25
+ 4.12 Spoofing by Counterfeit Servers................... 25
+ 4.13 Storing passwords................................. 26
+ 4.14 Summary........................................... 26
+ 5 Sample implementation................................ 27
+ 6 Acknowledgments...................................... 31
+
+
+
+Franks, et al. Standards Track [Page 2]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ 7 References........................................... 31
+ 8 Authors' Addresses................................... 32
+ 9 Full Copyright Statement............................. 34
+
+1 Access Authentication
+
+1.1 Reliance on the HTTP/1.1 Specification
+
+ This specification is a companion to the HTTP/1.1 specification [2].
+ It uses the augmented BNF section 2.1 of that document, and relies on
+ both the non-terminals defined in that document and other aspects of
+ the HTTP/1.1 specification.
+
+1.2 Access Authentication Framework
+
+ HTTP provides a simple challenge-response authentication mechanism
+ that MAY be used by a server to challenge a client request and by a
+ client to provide authentication information. It uses an extensible,
+ case-insensitive token to identify the authentication scheme,
+ followed by a comma-separated list of attribute-value pairs which
+ carry the parameters necessary for achieving authentication via that
+ scheme.
+
+ auth-scheme = token
+ auth-param = token "=" ( token | quoted-string )
+
+ The 401 (Unauthorized) response message is used by an origin server
+ to challenge the authorization of a user agent. This response MUST
+ include a WWW-Authenticate header field containing at least one
+ challenge applicable to the requested resource. The 407 (Proxy
+ Authentication Required) response message is used by a proxy to
+ challenge the authorization of a client and MUST include a Proxy-
+ Authenticate header field containing at least one challenge
+ applicable to the proxy for the requested resource.
+
+ challenge = auth-scheme 1*SP 1#auth-param
+
+ Note: User agents will need to take special care in parsing the WWW-
+ Authenticate or Proxy-Authenticate header field value if it contains
+ more than one challenge, or if more than one WWW-Authenticate header
+ field is provided, since the contents of a challenge may itself
+ contain a comma-separated list of authentication parameters.
+
+ The authentication parameter realm is defined for all authentication
+ schemes:
+
+ realm = "realm" "=" realm-value
+ realm-value = quoted-string
+
+
+
+Franks, et al. Standards Track [Page 3]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ The realm directive (case-insensitive) is required for all
+ authentication schemes that issue a challenge. The realm value
+ (case-sensitive), in combination with the canonical root URL (the
+ absoluteURI for the server whose abs_path is empty; see section 5.1.2
+ of [2]) of the server being accessed, defines the protection space.
+ These realms allow the protected resources on a server to be
+ partitioned into a set of protection spaces, each with its own
+ authentication scheme and/or authorization database. The realm value
+ is a string, generally assigned by the origin server, which may have
+ additional semantics specific to the authentication scheme. Note that
+ there may be multiple challenges with the same auth-scheme but
+ different realms.
+
+ A user agent that wishes to authenticate itself with an origin
+ server--usually, but not necessarily, after receiving a 401
+ (Unauthorized)--MAY do so by including an Authorization header field
+ with the request. A client that wishes to authenticate itself with a
+ proxy--usually, but not necessarily, after receiving a 407 (Proxy
+ Authentication Required)--MAY do so by including a Proxy-
+ Authorization header field with the request. Both the Authorization
+ field value and the Proxy-Authorization field value consist of
+ credentials containing the authentication information of the client
+ for the realm of the resource being requested. The user agent MUST
+ choose to use one of the challenges with the strongest auth-scheme it
+ understands and request credentials from the user based upon that
+ challenge.
+
+ credentials = auth-scheme #auth-param
+
+ Note that many browsers will only recognize Basic and will require
+ that it be the first auth-scheme presented. Servers should only
+ include Basic if it is minimally acceptable.
+
+ The protection space determines the domain over which credentials can
+ be automatically applied. If a prior request has been authorized, the
+ same credentials MAY be reused for all other requests within that
+ protection space for a period of time determined by the
+ authentication scheme, parameters, and/or user preference. Unless
+ otherwise defined by the authentication scheme, a single protection
+ space cannot extend outside the scope of its server.
+
+ If the origin server does not wish to accept the credentials sent
+ with a request, it SHOULD return a 401 (Unauthorized) response. The
+ response MUST include a WWW-Authenticate header field containing at
+ least one (possibly new) challenge applicable to the requested
+ resource. If a proxy does not accept the credentials sent with a
+ request, it SHOULD return a 407 (Proxy Authentication Required). The
+ response MUST include a Proxy-Authenticate header field containing a
+
+
+
+Franks, et al. Standards Track [Page 4]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ (possibly new) challenge applicable to the proxy for the requested
+ resource.
+
+ The HTTP protocol does not restrict applications to this simple
+ challenge-response mechanism for access authentication. Additional
+ mechanisms MAY be used, such as encryption at the transport level or
+ via message encapsulation, and with additional header fields
+ specifying authentication information. However, these additional
+ mechanisms are not defined by this specification.
+
+ Proxies MUST be completely transparent regarding user agent
+ authentication by origin servers. That is, they must forward the
+ WWW-Authenticate and Authorization headers untouched, and follow the
+ rules found in section 14.8 of [2]. Both the Proxy-Authenticate and
+ the Proxy-Authorization header fields are hop-by-hop headers (see
+ section 13.5.1 of [2]).
+
+2 Basic Authentication Scheme
+
+ The "basic" authentication scheme is based on the model that the
+ client must authenticate itself with a user-ID and a password for
+ each realm. The realm value should be considered an opaque string
+ which can only be compared for equality with other realms on that
+ server. The server will service the request only if it can validate
+ the user-ID and password for the protection space of the Request-URI.
+ There are no optional authentication parameters.
+
+ For Basic, the framework above is utilized as follows:
+
+ challenge = "Basic" realm
+ credentials = "Basic" basic-credentials
+
+ Upon receipt of an unauthorized request for a URI within the
+ protection space, the origin server MAY respond with a challenge like
+ the following:
+
+ WWW-Authenticate: Basic realm="WallyWorld"
+
+ where "WallyWorld" is the string assigned by the server to identify
+ the protection space of the Request-URI. A proxy may respond with the
+ same challenge using the Proxy-Authenticate header field.
+
+ To receive authorization, the client sends the userid and password,
+ separated by a single colon (":") character, within a base64 [7]
+ encoded string in the credentials.
+
+ basic-credentials = base64-user-pass
+ base64-user-pass = <base64 [4] encoding of user-pass,
+
+
+
+Franks, et al. Standards Track [Page 5]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ except not limited to 76 char/line>
+ user-pass = userid ":" password
+ userid = *<TEXT excluding ":">
+ password = *TEXT
+
+ Userids might be case sensitive.
+
+ If the user agent wishes to send the userid "Aladdin" and password
+ "open sesame", it would use the following header field:
+
+ Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
+
+ A client SHOULD assume that all paths at or deeper than the depth of
+ the last symbolic element in the path field of the Request-URI also
+ are within the protection space specified by the Basic realm value of
+ the current challenge. A client MAY preemptively send the
+ corresponding Authorization header with requests for resources in
+ that space without receipt of another challenge from the server.
+ Similarly, when a client sends a request to a proxy, it may reuse a
+ userid and password in the Proxy-Authorization header field without
+ receiving another challenge from the proxy server. See section 4 for
+ security considerations associated with Basic authentication.
+
+3 Digest Access Authentication Scheme
+
+3.1 Introduction
+
+3.1.1 Purpose
+
+ The protocol referred to as "HTTP/1.0" includes the specification for
+ a Basic Access Authentication scheme[1]. That scheme is not
+ considered to be a secure method of user authentication, as the user
+ name and password are passed over the network in an unencrypted form.
+ This section provides the specification for a scheme that does not
+ send the password in cleartext, referred to as "Digest Access
+ Authentication".
+
+ The Digest Access Authentication scheme is not intended to be a
+ complete answer to the need for security in the World Wide Web. This
+ scheme provides no encryption of message content. The intent is
+ simply to create an access authentication method that avoids the most
+ serious flaws of Basic authentication.
+
+3.1.2 Overall Operation
+
+ Like Basic Access Authentication, the Digest scheme is based on a
+ simple challenge-response paradigm. The Digest scheme challenges
+ using a nonce value. A valid response contains a checksum (by
+
+
+
+Franks, et al. Standards Track [Page 6]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ default, the MD5 checksum) of the username, the password, the given
+ nonce value, the HTTP method, and the requested URI. In this way, the
+ password is never sent in the clear. Just as with the Basic scheme,
+ the username and password must be prearranged in some fashion not
+ addressed by this document.
+
+3.1.3 Representation of digest values
+
+ An optional header allows the server to specify the algorithm used to
+ create the checksum or digest. By default the MD5 algorithm is used
+ and that is the only algorithm described in this document.
+
+ For the purposes of this document, an MD5 digest of 128 bits is
+ represented as 32 ASCII printable characters. The bits in the 128 bit
+ digest are converted from most significant to least significant bit,
+ four bits at a time to their ASCII presentation as follows. Each four
+ bits is represented by its familiar hexadecimal notation from the
+ characters 0123456789abcdef. That is, binary 0000 gets represented by
+ the character '0', 0001, by '1', and so on up to the representation
+ of 1111 as 'f'.
+
+3.1.4 Limitations
+
+ The Digest authentication scheme described in this document suffers
+ from many known limitations. It is intended as a replacement for
+ Basic authentication and nothing more. It is a password-based system
+ and (on the server side) suffers from all the same problems of any
+ password system. In particular, no provision is made in this protocol
+ for the initial secure arrangement between user and server to
+ establish the user's password.
+
+ Users and implementors should be aware that this protocol is not as
+ secure as Kerberos, and not as secure as any client-side private-key
+ scheme. Nevertheless it is better than nothing, better than what is
+ commonly used with telnet and ftp, and better than Basic
+ authentication.
+
+3.2 Specification of Digest Headers
+
+ The Digest Access Authentication scheme is conceptually similar to
+ the Basic scheme. The formats of the modified WWW-Authenticate header
+ line and the Authorization header line are specified below. In
+ addition, a new header, Authentication-Info, is specified.
+
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 7]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+3.2.1 The WWW-Authenticate Response Header
+
+ If a server receives a request for an access-protected object, and an
+ acceptable Authorization header is not sent, the server responds with
+ a "401 Unauthorized" status code, and a WWW-Authenticate header as
+ per the framework defined above, which for the digest scheme is
+ utilized as follows:
+
+ challenge = "Digest" digest-challenge
+
+ digest-challenge = 1#( realm | [ domain ] | nonce |
+ [ opaque ] |[ stale ] | [ algorithm ] |
+ [ qop-options ] | [auth-param] )
+
+
+ domain = "domain" "=" <"> URI ( 1*SP URI ) <">
+ URI = absoluteURI | abs_path
+ nonce = "nonce" "=" nonce-value
+ nonce-value = quoted-string
+ opaque = "opaque" "=" quoted-string
+ stale = "stale" "=" ( "true" | "false" )
+ algorithm = "algorithm" "=" ( "MD5" | "MD5-sess" |
+ token )
+ qop-options = "qop" "=" <"> 1#qop-value <">
+ qop-value = "auth" | "auth-int" | token
+
+ The meanings of the values of the directives used above are as
+ follows:
+
+ realm
+ A string to be displayed to users so they know which username and
+ password to use. This string should contain at least the name of
+ the host performing the authentication and might additionally
+ indicate the collection of users who might have access. An example
+ might be "registered_users at gotham.news.com".
+
+ domain
+ A quoted, space-separated list of URIs, as specified in RFC XURI
+ [7], that define the protection space. If a URI is an abs_path, it
+ is relative to the canonical root URL (see section 1.2 above) of
+ the server being accessed. An absoluteURI in this list may refer to
+ a different server than the one being accessed. The client can use
+ this list to determine the set of URIs for which the same
+ authentication information may be sent: any URI that has a URI in
+ this list as a prefix (after both have been made absolute) may be
+ assumed to be in the same protection space. If this directive is
+ omitted or its value is empty, the client should assume that the
+ protection space consists of all URIs on the responding server.
+
+
+
+Franks, et al. Standards Track [Page 8]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ This directive is not meaningful in Proxy-Authenticate headers, for
+ which the protection space is always the entire proxy; if present
+ it should be ignored.
+
+ nonce
+ A server-specified data string which should be uniquely generated
+ each time a 401 response is made. It is recommended that this
+ string be base64 or hexadecimal data. Specifically, since the
+ string is passed in the header lines as a quoted string, the
+ double-quote character is not allowed.
+
+ The contents of the nonce are implementation dependent. The quality
+ of the implementation depends on a good choice. A nonce might, for
+ example, be constructed as the base 64 encoding of
+
+ time-stamp H(time-stamp ":" ETag ":" private-key)
+
+ where time-stamp is a server-generated time or other non-repeating
+ value, ETag is the value of the HTTP ETag header associated with
+ the requested entity, and private-key is data known only to the
+ server. With a nonce of this form a server would recalculate the
+ hash portion after receiving the client authentication header and
+ reject the request if it did not match the nonce from that header
+ or if the time-stamp value is not recent enough. In this way the
+ server can limit the time of the nonce's validity. The inclusion of
+ the ETag prevents a replay request for an updated version of the
+ resource. (Note: including the IP address of the client in the
+ nonce would appear to offer the server the ability to limit the
+ reuse of the nonce to the same client that originally got it.
+ However, that would break proxy farms, where requests from a single
+ user often go through different proxies in the farm. Also, IP
+ address spoofing is not that hard.)
+
+ An implementation might choose not to accept a previously used
+ nonce or a previously used digest, in order to protect against a
+ replay attack. Or, an implementation might choose to use one-time
+ nonces or digests for POST or PUT requests and a time-stamp for GET
+ requests. For more details on the issues involved see section 4.
+ of this document.
+
+ The nonce is opaque to the client.
+
+ opaque
+ A string of data, specified by the server, which should be returned
+ by the client unchanged in the Authorization header of subsequent
+ requests with URIs in the same protection space. It is recommended
+ that this string be base64 or hexadecimal data.
+
+
+
+
+Franks, et al. Standards Track [Page 9]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ stale
+ A flag, indicating that the previous request from the client was
+ rejected because the nonce value was stale. If stale is TRUE
+ (case-insensitive), the client may wish to simply retry the request
+ with a new encrypted response, without reprompting the user for a
+ new username and password. The server should only set stale to TRUE
+ if it receives a request for which the nonce is invalid but with a
+ valid digest for that nonce (indicating that the client knows the
+ correct username/password). If stale is FALSE, or anything other
+ than TRUE, or the stale directive is not present, the username
+ and/or password are invalid, and new values must be obtained.
+
+ algorithm
+ A string indicating a pair of algorithms used to produce the digest
+ and a checksum. If this is not present it is assumed to be "MD5".
+ If the algorithm is not understood, the challenge should be ignored
+ (and a different one used, if there is more than one).
+
+ In this document the string obtained by applying the digest
+ algorithm to the data "data" with secret "secret" will be denoted
+ by KD(secret, data), and the string obtained by applying the
+ checksum algorithm to the data "data" will be denoted H(data). The
+ notation unq(X) means the value of the quoted-string X without the
+ surrounding quotes.
+
+ For the "MD5" and "MD5-sess" algorithms
+
+ H(data) = MD5(data)
+
+ and
+
+ KD(secret, data) = H(concat(secret, ":", data))
+
+ i.e., the digest is the MD5 of the secret concatenated with a colon
+ concatenated with the data. The "MD5-sess" algorithm is intended to
+ allow efficient 3rd party authentication servers; for the
+ difference in usage, see the description in section 3.2.2.2.
+
+ qop-options
+ This directive is optional, but is made so only for backward
+ compatibility with RFC 2069 [6]; it SHOULD be used by all
+ implementations compliant with this version of the Digest scheme.
+ If present, it is a quoted string of one or more tokens indicating
+ the "quality of protection" values supported by the server. The
+ value "auth" indicates authentication; the value "auth-int"
+ indicates authentication with integrity protection; see the
+
+
+
+
+
+Franks, et al. Standards Track [Page 10]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ descriptions below for calculating the response directive value for
+ the application of this choice. Unrecognized options MUST be
+ ignored.
+
+ auth-param
+ This directive allows for future extensions. Any unrecognized
+ directive MUST be ignored.
+
+3.2.2 The Authorization Request Header
+
+ The client is expected to retry the request, passing an Authorization
+ header line, which is defined according to the framework above,
+ utilized as follows.
+
+ credentials = "Digest" digest-response
+ digest-response = 1#( username | realm | nonce | digest-uri
+ | response | [ algorithm ] | [cnonce] |
+ [opaque] | [message-qop] |
+ [nonce-count] | [auth-param] )
+
+ username = "username" "=" username-value
+ username-value = quoted-string
+ digest-uri = "uri" "=" digest-uri-value
+ digest-uri-value = request-uri ; As specified by HTTP/1.1
+ message-qop = "qop" "=" qop-value
+ cnonce = "cnonce" "=" cnonce-value
+ cnonce-value = nonce-value
+ nonce-count = "nc" "=" nc-value
+ nc-value = 8LHEX
+ response = "response" "=" request-digest
+ request-digest = <"> 32LHEX <">
+ LHEX = "0" | "1" | "2" | "3" |
+ "4" | "5" | "6" | "7" |
+ "8" | "9" | "a" | "b" |
+ "c" | "d" | "e" | "f"
+
+ The values of the opaque and algorithm fields must be those supplied
+ in the WWW-Authenticate response header for the entity being
+ requested.
+
+ response
+ A string of 32 hex digits computed as defined below, which proves
+ that the user knows a password
+
+ username
+ The user's name in the specified realm.
+
+
+
+
+
+Franks, et al. Standards Track [Page 11]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ digest-uri
+ The URI from Request-URI of the Request-Line; duplicated here
+ because proxies are allowed to change the Request-Line in transit.
+
+ qop
+ Indicates what "quality of protection" the client has applied to
+ the message. If present, its value MUST be one of the alternatives
+ the server indicated it supports in the WWW-Authenticate header.
+ These values affect the computation of the request-digest. Note
+ that this is a single token, not a quoted list of alternatives as
+ in WWW- Authenticate. This directive is optional in order to
+ preserve backward compatibility with a minimal implementation of
+ RFC 2069 [6], but SHOULD be used if the server indicated that qop
+ is supported by providing a qop directive in the WWW-Authenticate
+ header field.
+
+ cnonce
+ This MUST be specified if a qop directive is sent (see above), and
+ MUST NOT be specified if the server did not send a qop directive in
+ the WWW-Authenticate header field. The cnonce-value is an opaque
+ quoted string value provided by the client and used by both client
+ and server to avoid chosen plaintext attacks, to provide mutual
+ authentication, and to provide some message integrity protection.
+ See the descriptions below of the calculation of the response-
+ digest and request-digest values.
+
+ nonce-count
+ This MUST be specified if a qop directive is sent (see above), and
+ MUST NOT be specified if the server did not send a qop directive in
+ the WWW-Authenticate header field. The nc-value is the hexadecimal
+ count of the number of requests (including the current request)
+ that the client has sent with the nonce value in this request. For
+ example, in the first request sent in response to a given nonce
+ value, the client sends "nc=00000001". The purpose of this
+ directive is to allow the server to detect request replays by
+ maintaining its own copy of this count - if the same nc-value is
+ seen twice, then the request is a replay. See the description
+ below of the construction of the request-digest value.
+
+ auth-param
+ This directive allows for future extensions. Any unrecognized
+ directive MUST be ignored.
+
+ If a directive or its value is improper, or required directives are
+ missing, the proper response is 400 Bad Request. If the request-
+ digest is invalid, then a login failure should be logged, since
+ repeated login failures from a single client may indicate an attacker
+ attempting to guess passwords.
+
+
+
+Franks, et al. Standards Track [Page 12]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ The definition of request-digest above indicates the encoding for its
+ value. The following definitions show how the value is computed.
+
+3.2.2.1 Request-Digest
+
+ If the "qop" value is "auth" or "auth-int":
+
+ request-digest = <"> < KD ( H(A1), unq(nonce-value)
+ ":" nc-value
+ ":" unq(cnonce-value)
+ ":" unq(qop-value)
+ ":" H(A2)
+ ) <">
+
+ If the "qop" directive is not present (this construction is for
+ compatibility with RFC 2069):
+
+ request-digest =
+ <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) >
+ <">
+
+ See below for the definitions for A1 and A2.
+
+3.2.2.2 A1
+
+ If the "algorithm" directive's value is "MD5" or is unspecified, then
+ A1 is:
+
+ A1 = unq(username-value) ":" unq(realm-value) ":" passwd
+
+ where
+
+ passwd = < user's password >
+
+ If the "algorithm" directive's value is "MD5-sess", then A1 is
+ calculated only once - on the first request by the client following
+ receipt of a WWW-Authenticate challenge from the server. It uses the
+ server nonce from that challenge, and the first client nonce value to
+ construct A1 as follows:
+
+ A1 = H( unq(username-value) ":" unq(realm-value)
+ ":" passwd )
+ ":" unq(nonce-value) ":" unq(cnonce-value)
+
+ This creates a 'session key' for the authentication of subsequent
+ requests and responses which is different for each "authentication
+ session", thus limiting the amount of material hashed with any one
+ key. (Note: see further discussion of the authentication session in
+
+
+
+Franks, et al. Standards Track [Page 13]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ section 3.3.) Because the server need only use the hash of the user
+ credentials in order to create the A1 value, this construction could
+ be used in conjunction with a third party authentication service so
+ that the web server would not need the actual password value. The
+ specification of such a protocol is beyond the scope of this
+ specification.
+
+3.2.2.3 A2
+
+ If the "qop" directive's value is "auth" or is unspecified, then A2
+ is:
+
+ A2 = Method ":" digest-uri-value
+
+ If the "qop" value is "auth-int", then A2 is:
+
+ A2 = Method ":" digest-uri-value ":" H(entity-body)
+
+3.2.2.4 Directive values and quoted-string
+
+ Note that the value of many of the directives, such as "username-
+ value", are defined as a "quoted-string". However, the "unq" notation
+ indicates that surrounding quotation marks are removed in forming the
+ string A1. Thus if the Authorization header includes the fields
+
+ username="Mufasa", realm=myhost at testrealm.com
+
+ and the user Mufasa has password "Circle Of Life" then H(A1) would be
+ H(Mufasa:myhost at testrealm.com:Circle Of Life) with no quotation marks
+ in the digested string.
+
+ No white space is allowed in any of the strings to which the digest
+ function H() is applied unless that white space exists in the quoted
+ strings or entity body whose contents make up the string to be
+ digested. For example, the string A1 illustrated above must be
+
+ Mufasa:myhost at testrealm.com:Circle Of Life
+
+ with no white space on either side of the colons, but with the white
+ space between the words used in the password value. Likewise, the
+ other strings digested by H() must not have white space on either
+ side of the colons which delimit their fields unless that white space
+ was in the quoted strings or entity body being digested.
+
+ Also note that if integrity protection is applied (qop=auth-int), the
+ H(entity-body) is the hash of the entity body, not the message body -
+ it is computed before any transfer encoding is applied by the sender
+
+
+
+
+Franks, et al. Standards Track [Page 14]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ and after it has been removed by the recipient. Note that this
+ includes multipart boundaries and embedded headers in each part of
+ any multipart content-type.
+
+3.2.2.5 Various considerations
+
+ The "Method" value is the HTTP request method as specified in section
+ 5.1.1 of [2]. The "request-uri" value is the Request-URI from the
+ request line as specified in section 5.1.2 of [2]. This may be "*",
+ an "absoluteURL" or an "abs_path" as specified in section 5.1.2 of
+ [2], but it MUST agree with the Request-URI. In particular, it MUST
+ be an "absoluteURL" if the Request-URI is an "absoluteURL". The
+ "cnonce-value" is an optional client-chosen value whose purpose is
+ to foil chosen plaintext attacks.
+
+ The authenticating server must assure that the resource designated by
+ the "uri" directive is the same as the resource specified in the
+ Request-Line; if they are not, the server SHOULD return a 400 Bad
+ Request error. (Since this may be a symptom of an attack, server
+ implementers may want to consider logging such errors.) The purpose
+ of duplicating information from the request URL in this field is to
+ deal with the possibility that an intermediate proxy may alter the
+ client's Request-Line. This altered (but presumably semantically
+ equivalent) request would not result in the same digest as that
+ calculated by the client.
+
+ Implementers should be aware of how authenticated transactions
+ interact with shared caches. The HTTP/1.1 protocol specifies that
+ when a shared cache (see section 13.7 of [2]) has received a request
+ containing an Authorization header and a response from relaying that
+ request, it MUST NOT return that response as a reply to any other
+ request, unless one of two Cache-Control (see section 14.9 of [2])
+ directives was present in the response. If the original response
+ included the "must-revalidate" Cache-Control directive, the cache MAY
+ use the entity of that response in replying to a subsequent request,
+ but MUST first revalidate it with the origin server, using the
+ request headers from the new request to allow the origin server to
+ authenticate the new request. Alternatively, if the original response
+ included the "public" Cache-Control directive, the response entity
+ MAY be returned in reply to any subsequent request.
+
+3.2.3 The Authentication-Info Header
+
+ The Authentication-Info header is used by the server to communicate
+ some information regarding the successful authentication in the
+ response.
+
+
+
+
+
+Franks, et al. Standards Track [Page 15]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ AuthenticationInfo = "Authentication-Info" ":" auth-info
+ auth-info = 1#(nextnonce | [ message-qop ]
+ | [ response-auth ] | [ cnonce ]
+ | [nonce-count] )
+ nextnonce = "nextnonce" "=" nonce-value
+ response-auth = "rspauth" "=" response-digest
+ response-digest = <"> *LHEX <">
+
+ The value of the nextnonce directive is the nonce the server wishes
+ the client to use for a future authentication response. The server
+ may send the Authentication-Info header with a nextnonce field as a
+ means of implementing one-time or otherwise changing nonces. If the
+ nextnonce field is present the client SHOULD use it when constructing
+ the Authorization header for its next request. Failure of the client
+ to do so may result in a request to re-authenticate from the server
+ with the "stale=TRUE".
+
+ Server implementations should carefully consider the performance
+ implications of the use of this mechanism; pipelined requests will
+ not be possible if every response includes a nextnonce directive
+ that must be used on the next request received by the server.
+ Consideration should be given to the performance vs. security
+ tradeoffs of allowing an old nonce value to be used for a limited
+ time to permit request pipelining. Use of the nonce-count can
+ retain most of the security advantages of a new server nonce
+ without the deleterious affects on pipelining.
+
+ message-qop
+ Indicates the "quality of protection" options applied to the
+ response by the server. The value "auth" indicates authentication;
+ the value "auth-int" indicates authentication with integrity
+ protection. The server SHOULD use the same value for the message-
+ qop directive in the response as was sent by the client in the
+ corresponding request.
+
+ The optional response digest in the "response-auth" directive
+ supports mutual authentication -- the server proves that it knows the
+ user's secret, and with qop=auth-int also provides limited integrity
+ protection of the response. The "response-digest" value is calculated
+ as for the "request-digest" in the Authorization header, except that
+ if "qop=auth" or is not specified in the Authorization header for the
+ request, A2 is
+
+ A2 = ":" digest-uri-value
+
+ and if "qop=auth-int", then A2 is
+
+ A2 = ":" digest-uri-value ":" H(entity-body)
+
+
+
+Franks, et al. Standards Track [Page 16]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ where "digest-uri-value" is the value of the "uri" directive on the
+ Authorization header in the request. The "cnonce-value" and "nc-
+ value" MUST be the ones for the client request to which this message
+ is the response. The "response-auth", "cnonce", and "nonce-count"
+ directives MUST BE present if "qop=auth" or "qop=auth-int" is
+ specified.
+
+ The Authentication-Info header is allowed in the trailer of an HTTP
+ message transferred via chunked transfer-coding.
+
+3.3 Digest Operation
+
+ Upon receiving the Authorization header, the server may check its
+ validity by looking up the password that corresponds to the submitted
+ username. Then, the server must perform the same digest operation
+ (e.g., MD5) performed by the client, and compare the result to the
+ given request-digest value.
+
+ Note that the HTTP server does not actually need to know the user's
+ cleartext password. As long as H(A1) is available to the server, the
+ validity of an Authorization header may be verified.
+
+ The client response to a WWW-Authenticate challenge for a protection
+ space starts an authentication session with that protection space.
+ The authentication session lasts until the client receives another
+ WWW-Authenticate challenge from any server in the protection space. A
+ client should remember the username, password, nonce, nonce count and
+ opaque values associated with an authentication session to use to
+ construct the Authorization header in future requests within that
+ protection space. The Authorization header may be included
+ preemptively; doing so improves server efficiency and avoids extra
+ round trips for authentication challenges. The server may choose to
+ accept the old Authorization header information, even though the
+ nonce value included might not be fresh. Alternatively, the server
+ may return a 401 response with a new nonce value, causing the client
+ to retry the request; by specifying stale=TRUE with this response,
+ the server tells the client to retry with the new nonce, but without
+ prompting for a new username and password.
+
+ Because the client is required to return the value of the opaque
+ directive given to it by the server for the duration of a session,
+ the opaque data may be used to transport authentication session state
+ information. (Note that any such use can also be accomplished more
+ easily and safely by including the state in the nonce.) For example,
+ a server could be responsible for authenticating content that
+ actually sits on another server. It would achieve this by having the
+ first 401 response include a domain directive whose value includes a
+ URI on the second server, and an opaque directive whose value
+
+
+
+Franks, et al. Standards Track [Page 17]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ contains the state information. The client will retry the request, at
+ which time the server might respond with a 301/302 redirection,
+ pointing to the URI on the second server. The client will follow the
+ redirection, and pass an Authorization header , including the
+ <opaque> data.
+
+ As with the basic scheme, proxies must be completely transparent in
+ the Digest access authentication scheme. That is, they must forward
+ the WWW-Authenticate, Authentication-Info and Authorization headers
+ untouched. If a proxy wants to authenticate a client before a request
+ is forwarded to the server, it can be done using the Proxy-
+ Authenticate and Proxy-Authorization headers described in section 3.6
+ below.
+
+3.4 Security Protocol Negotiation
+
+ It is useful for a server to be able to know which security schemes a
+ client is capable of handling.
+
+ It is possible that a server may want to require Digest as its
+ authentication method, even if the server does not know that the
+ client supports it. A client is encouraged to fail gracefully if the
+ server specifies only authentication schemes it cannot handle.
+
+3.5 Example
+
+ The following example assumes that an access-protected document is
+ being requested from the server via a GET request. The URI of the
+ document is "http://www.nowhere.org/dir/index.html". Both client and
+ server know that the username for this document is "Mufasa", and the
+ password is "Circle Of Life" (with one space between each of the
+ three words).
+
+ The first time the client requests the document, no Authorization
+ header is sent, so the server responds with:
+
+ HTTP/1.1 401 Unauthorized
+ WWW-Authenticate: Digest
+ realm="testrealm at host.com",
+ qop="auth,auth-int",
+ nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
+ opaque="5ccc069c403ebaf9f0171e9517f40e41"
+
+ The client may prompt the user for the username and password, after
+ which it will respond with a new request, including the following
+ Authorization header:
+
+
+
+
+
+Franks, et al. Standards Track [Page 18]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ Authorization: Digest username="Mufasa",
+ realm="testrealm at host.com",
+ nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
+ uri="/dir/index.html",
+ qop=auth,
+ nc=00000001,
+ cnonce="0a4f113b",
+ response="6629fae49393a05397450978507c4ef1",
+ opaque="5ccc069c403ebaf9f0171e9517f40e41"
+
+3.6 Proxy-Authentication and Proxy-Authorization
+
+ The digest authentication scheme may also be used for authenticating
+ users to proxies, proxies to proxies, or proxies to origin servers by
+ use of the Proxy-Authenticate and Proxy-Authorization headers. These
+ headers are instances of the Proxy-Authenticate and Proxy-
+ Authorization headers specified in sections 10.33 and 10.34 of the
+ HTTP/1.1 specification [2] and their behavior is subject to
+ restrictions described there. The transactions for proxy
+ authentication are very similar to those already described. Upon
+ receiving a request which requires authentication, the proxy/server
+ must issue the "407 Proxy Authentication Required" response with a
+ "Proxy-Authenticate" header. The digest-challenge used in the
+ Proxy-Authenticate header is the same as that for the WWW-
+ Authenticate header as defined above in section 3.2.1.
+
+ The client/proxy must then re-issue the request with a Proxy-
+ Authorization header, with directives as specified for the
+ Authorization header in section 3.2.2 above.
+
+ On subsequent responses, the server sends Proxy-Authentication-Info
+ with directives the same as those for the Authentication-Info header
+ field.
+
+ Note that in principle a client could be asked to authenticate itself
+ to both a proxy and an end-server, but never in the same response.
+
+4 Security Considerations
+
+4.1 Authentication of Clients using Basic Authentication
+
+ The Basic authentication scheme is not a secure method of user
+ authentication, nor does it in any way protect the entity, which is
+ transmitted in cleartext across the physical network used as the
+ carrier. HTTP does not prevent additional authentication schemes and
+ encryption mechanisms from being employed to increase security or the
+ addition of enhancements (such as schemes to use one-time passwords)
+ to Basic authentication.
+
+
+
+Franks, et al. Standards Track [Page 19]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ The most serious flaw in Basic authentication is that it results in
+ the essentially cleartext transmission of the user's password over
+ the physical network. It is this problem which Digest Authentication
+ attempts to address.
+
+ Because Basic authentication involves the cleartext transmission of
+ passwords it SHOULD NOT be used (without enhancements) to protect
+ sensitive or valuable information.
+
+ A common use of Basic authentication is for identification purposes
+ -- requiring the user to provide a user name and password as a means
+ of identification, for example, for purposes of gathering accurate
+ usage statistics on a server. When used in this way it is tempting to
+ think that there is no danger in its use if illicit access to the
+ protected documents is not a major concern. This is only correct if
+ the server issues both user name and password to the users and in
+ particular does not allow the user to choose his or her own password.
+ The danger arises because naive users frequently reuse a single
+ password to avoid the task of maintaining multiple passwords.
+
+ If a server permits users to select their own passwords, then the
+ threat is not only unauthorized access to documents on the server but
+ also unauthorized access to any other resources on other systems that
+ the user protects with the same password. Furthermore, in the
+ server's password database, many of the passwords may also be users'
+ passwords for other sites. The owner or administrator of such a
+ system could therefore expose all users of the system to the risk of
+ unauthorized access to all those sites if this information is not
+ maintained in a secure fashion.
+
+ Basic Authentication is also vulnerable to spoofing by counterfeit
+ servers. If a user can be led to believe that he is connecting to a
+ host containing information protected by Basic authentication when,
+ in fact, he is connecting to a hostile server or gateway, then the
+ attacker can request a password, store it for later use, and feign an
+ error. This type of attack is not possible with Digest
+ Authentication. Server implementers SHOULD guard against the
+ possibility of this sort of counterfeiting by gateways or CGI
+ scripts. In particular it is very dangerous for a server to simply
+ turn over a connection to a gateway. That gateway can then use the
+ persistent connection mechanism to engage in multiple transactions
+ with the client while impersonating the original server in a way that
+ is not detectable by the client.
+
+4.2 Authentication of Clients using Digest Authentication
+
+ Digest Authentication does not provide a strong authentication
+ mechanism, when compared to public key based mechanisms, for example.
+
+
+
+Franks, et al. Standards Track [Page 20]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ However, it is significantly stronger than (e.g.) CRAM-MD5, which has
+ been proposed for use with LDAP [10], POP and IMAP (see RFC 2195
+ [9]). It is intended to replace the much weaker and even more
+ dangerous Basic mechanism.
+
+ Digest Authentication offers no confidentiality protection beyond
+ protecting the actual password. All of the rest of the request and
+ response are available to an eavesdropper.
+
+ Digest Authentication offers only limited integrity protection for
+ the messages in either direction. If qop=auth-int mechanism is used,
+ those parts of the message used in the calculation of the WWW-
+ Authenticate and Authorization header field response directive values
+ (see section 3.2 above) are protected. Most header fields and their
+ values could be modified as a part of a man-in-the-middle attack.
+
+ Many needs for secure HTTP transactions cannot be met by Digest
+ Authentication. For those needs TLS or SHTTP are more appropriate
+ protocols. In particular Digest authentication cannot be used for any
+ transaction requiring confidentiality protection. Nevertheless many
+ functions remain for which Digest authentication is both useful and
+ appropriate. Any service in present use that uses Basic should be
+ switched to Digest as soon as practical.
+
+4.3 Limited Use Nonce Values
+
+ The Digest scheme uses a server-specified nonce to seed the
+ generation of the request-digest value (as specified in section
+ 3.2.2.1 above). As shown in the example nonce in section 3.2.1, the
+ server is free to construct the nonce such that it may only be used
+ from a particular client, for a particular resource, for a limited
+ period of time or number of uses, or any other restrictions. Doing
+ so strengthens the protection provided against, for example, replay
+ attacks (see 4.5). However, it should be noted that the method
+ chosen for generating and checking the nonce also has performance and
+ resource implications. For example, a server may choose to allow
+ each nonce value to be used only once by maintaining a record of
+ whether or not each recently issued nonce has been returned and
+ sending a next-nonce directive in the Authentication-Info header
+ field of every response. This protects against even an immediate
+ replay attack, but has a high cost checking nonce values, and perhaps
+ more important will cause authentication failures for any pipelined
+ requests (presumably returning a stale nonce indication). Similarly,
+ incorporating a request-specific element such as the Etag value for a
+ resource limits the use of the nonce to that version of the resource
+ and also defeats pipelining. Thus it may be useful to do so for
+ methods with side effects but have unacceptable performance for those
+ that do not.
+
+
+
+Franks, et al. Standards Track [Page 21]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+4.4 Comparison of Digest with Basic Authentication
+
+ Both Digest and Basic Authentication are very much on the weak end of
+ the security strength spectrum. But a comparison between the two
+ points out the utility, even necessity, of replacing Basic by Digest.
+
+ The greatest threat to the type of transactions for which these
+ protocols are used is network snooping. This kind of transaction
+ might involve, for example, online access to a database whose use is
+ restricted to paying subscribers. With Basic authentication an
+ eavesdropper can obtain the password of the user. This not only
+ permits him to access anything in the database, but, often worse,
+ will permit access to anything else the user protects with the same
+ password.
+
+ By contrast, with Digest Authentication the eavesdropper only gets
+ access to the transaction in question and not to the user's password.
+ The information gained by the eavesdropper would permit a replay
+ attack, but only with a request for the same document, and even that
+ may be limited by the server's choice of nonce.
+
+4.5 Replay Attacks
+
+ A replay attack against Digest authentication would usually be
+ pointless for a simple GET request since an eavesdropper would
+ already have seen the only document he could obtain with a replay.
+ This is because the URI of the requested document is digested in the
+ client request and the server will only deliver that document. By
+ contrast under Basic Authentication once the eavesdropper has the
+ user's password, any document protected by that password is open to
+ him.
+
+ Thus, for some purposes, it is necessary to protect against replay
+ attacks. A good Digest implementation can do this in various ways.
+ The server created "nonce" value is implementation dependent, but if
+ it contains a digest of the client IP, a time-stamp, the resource
+ ETag, and a private server key (as recommended above) then a replay
+ attack is not simple. An attacker must convince the server that the
+ request is coming from a false IP address and must cause the server
+ to deliver the document to an IP address different from the address
+ to which it believes it is sending the document. An attack can only
+ succeed in the period before the time-stamp expires. Digesting the
+ client IP and time-stamp in the nonce permits an implementation which
+ does not maintain state between transactions.
+
+ For applications where no possibility of replay attack can be
+ tolerated the server can use one-time nonce values which will not be
+ honored for a second use. This requires the overhead of the server
+
+
+
+Franks, et al. Standards Track [Page 22]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ remembering which nonce values have been used until the nonce time-
+ stamp (and hence the digest built with it) has expired, but it
+ effectively protects against replay attacks.
+
+ An implementation must give special attention to the possibility of
+ replay attacks with POST and PUT requests. Unless the server employs
+ one-time or otherwise limited-use nonces and/or insists on the use of
+ the integrity protection of qop=auth-int, an attacker could replay
+ valid credentials from a successful request with counterfeit form
+ data or other message body. Even with the use of integrity protection
+ most metadata in header fields is not protected. Proper nonce
+ generation and checking provides some protection against replay of
+ previously used valid credentials, but see 4.8.
+
+4.6 Weakness Created by Multiple Authentication Schemes
+
+ An HTTP/1.1 server may return multiple challenges with a 401
+ (Authenticate) response, and each challenge may use a different
+ auth-scheme. A user agent MUST choose to use the strongest auth-
+ scheme it understands and request credentials from the user based
+ upon that challenge.
+
+ Note that many browsers will only recognize Basic and will require
+ that it be the first auth-scheme presented. Servers should only
+ include Basic if it is minimally acceptable.
+
+ When the server offers choices of authentication schemes using the
+ WWW-Authenticate header, the strength of the resulting authentication
+ is only as good as that of the of the weakest of the authentication
+ schemes. See section 4.8 below for discussion of particular attack
+ scenarios that exploit multiple authentication schemes.
+
+4.7 Online dictionary attacks
+
+ If the attacker can eavesdrop, then it can test any overheard
+ nonce/response pairs against a list of common words. Such a list is
+ usually much smaller than the total number of possible passwords. The
+ cost of computing the response for each password on the list is paid
+ once for each challenge.
+
+ The server can mitigate this attack by not allowing users to select
+ passwords that are in a dictionary.
+
+
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 23]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+4.8 Man in the Middle
+
+ Both Basic and Digest authentication are vulnerable to "man in the
+ middle" (MITM) attacks, for example, from a hostile or compromised
+ proxy. Clearly, this would present all the problems of eavesdropping.
+ But it also offers some additional opportunities to the attacker.
+
+ A possible man-in-the-middle attack would be to add a weak
+ authentication scheme to the set of choices, hoping that the client
+ will use one that exposes the user's credentials (e.g. password). For
+ this reason, the client should always use the strongest scheme that
+ it understands from the choices offered.
+
+ An even better MITM attack would be to remove all offered choices,
+ replacing them with a challenge that requests only Basic
+ authentication, then uses the cleartext credentials from the Basic
+ authentication to authenticate to the origin server using the
+ stronger scheme it requested. A particularly insidious way to mount
+ such a MITM attack would be to offer a "free" proxy caching service
+ to gullible users.
+
+ User agents should consider measures such as presenting a visual
+ indication at the time of the credentials request of what
+ authentication scheme is to be used, or remembering the strongest
+ authentication scheme ever requested by a server and produce a
+ warning message before using a weaker one. It might also be a good
+ idea for the user agent to be configured to demand Digest
+ authentication in general, or from specific sites.
+
+ Or, a hostile proxy might spoof the client into making a request the
+ attacker wanted rather than one the client wanted. Of course, this is
+ still much harder than a comparable attack against Basic
+ Authentication.
+
+4.9 Chosen plaintext attacks
+
+ With Digest authentication, a MITM or a malicious server can
+ arbitrarily choose the nonce that the client will use to compute the
+ response. This is called a "chosen plaintext" attack. The ability to
+ choose the nonce is known to make cryptanalysis much easier [8].
+
+ However, no way to analyze the MD5 one-way function used by Digest
+ using chosen plaintext is currently known.
+
+ The countermeasure against this attack is for clients to be
+ configured to require the use of the optional "cnonce" directive;
+ this allows the client to vary the input to the hash in a way not
+ chosen by the attacker.
+
+
+
+Franks, et al. Standards Track [Page 24]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+4.10 Precomputed dictionary attacks
+
+ With Digest authentication, if the attacker can execute a chosen
+ plaintext attack, the attacker can precompute the response for many
+ common words to a nonce of its choice, and store a dictionary of
+ (response, password) pairs. Such precomputation can often be done in
+ parallel on many machines. It can then use the chosen plaintext
+ attack to acquire a response corresponding to that challenge, and
+ just look up the password in the dictionary. Even if most passwords
+ are not in the dictionary, some might be. Since the attacker gets to
+ pick the challenge, the cost of computing the response for each
+ password on the list can be amortized over finding many passwords. A
+ dictionary with 100 million password/response pairs would take about
+ 3.2 gigabytes of disk storage.
+
+ The countermeasure against this attack is to for clients to be
+ configured to require the use of the optional "cnonce" directive.
+
+4.11 Batch brute force attacks
+
+ With Digest authentication, a MITM can execute a chosen plaintext
+ attack, and can gather responses from many users to the same nonce.
+ It can then find all the passwords within any subset of password
+ space that would generate one of the nonce/response pairs in a single
+ pass over that space. It also reduces the time to find the first
+ password by a factor equal to the number of nonce/response pairs
+ gathered. This search of the password space can often be done in
+ parallel on many machines, and even a single machine can search large
+ subsets of the password space very quickly -- reports exist of
+ searching all passwords with six or fewer letters in a few hours.
+
+ The countermeasure against this attack is to for clients to be
+ configured to require the use of the optional "cnonce" directive.
+
+4.12 Spoofing by Counterfeit Servers
+
+ Basic Authentication is vulnerable to spoofing by counterfeit
+ servers. If a user can be led to believe that she is connecting to a
+ host containing information protected by a password she knows, when
+ in fact she is connecting to a hostile server, then the hostile
+ server can request a password, store it away for later use, and feign
+ an error. This type of attack is more difficult with Digest
+ Authentication -- but the client must know to demand that Digest
+ authentication be used, perhaps using some of the techniques
+ described above to counter "man-in-the-middle" attacks. Again, the
+ user can be helped in detecting this attack by a visual indication of
+ the authentication mechanism in use with appropriate guidance in
+ interpreting the implications of each scheme.
+
+
+
+Franks, et al. Standards Track [Page 25]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+4.13 Storing passwords
+
+ Digest authentication requires that the authenticating agent (usually
+ the server) store some data derived from the user's name and password
+ in a "password file" associated with a given realm. Normally this
+ might contain pairs consisting of username and H(A1), where H(A1) is
+ the digested value of the username, realm, and password as described
+ above.
+
+ The security implications of this are that if this password file is
+ compromised, then an attacker gains immediate access to documents on
+ the server using this realm. Unlike, say a standard UNIX password
+ file, this information need not be decrypted in order to access
+ documents in the server realm associated with this file. On the other
+ hand, decryption, or more likely a brute force attack, would be
+ necessary to obtain the user's password. This is the reason that the
+ realm is part of the digested data stored in the password file. It
+ means that if one Digest authentication password file is compromised,
+ it does not automatically compromise others with the same username
+ and password (though it does expose them to brute force attack).
+
+ There are two important security consequences of this. First the
+ password file must be protected as if it contained unencrypted
+ passwords, because for the purpose of accessing documents in its
+ realm, it effectively does.
+
+ A second consequence of this is that the realm string should be
+ unique among all realms which any single user is likely to use. In
+ particular a realm string should include the name of the host doing
+ the authentication. The inability of the client to authenticate the
+ server is a weakness of Digest Authentication.
+
+4.14 Summary
+
+ By modern cryptographic standards Digest Authentication is weak. But
+ for a large range of purposes it is valuable as a replacement for
+ Basic Authentication. It remedies some, but not all, weaknesses of
+ Basic Authentication. Its strength may vary depending on the
+ implementation. In particular the structure of the nonce (which is
+ dependent on the server implementation) may affect the ease of
+ mounting a replay attack. A range of server options is appropriate
+ since, for example, some implementations may be willing to accept the
+ server overhead of one-time nonces or digests to eliminate the
+ possibility of replay. Others may satisfied with a nonce like the one
+ recommended above restricted to a single IP address and a single ETag
+ or with a limited lifetime.
+
+
+
+
+
+Franks, et al. Standards Track [Page 26]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ The bottom line is that *any* compliant implementation will be
+ relatively weak by cryptographic standards, but *any* compliant
+ implementation will be far superior to Basic Authentication.
+
+5 Sample implementation
+
+ The following code implements the calculations of H(A1), H(A2),
+ request-digest and response-digest, and a test program which computes
+ the values used in the example of section 3.5. It uses the MD5
+ implementation from RFC 1321.
+
+ File "digcalc.h":
+
+#define HASHLEN 16
+typedef char HASH[HASHLEN];
+#define HASHHEXLEN 32
+typedef char HASHHEX[HASHHEXLEN+1];
+#define IN
+#define OUT
+
+/* calculate H(A1) as per HTTP Digest spec */
+void DigestCalcHA1(
+ IN char * pszAlg,
+ IN char * pszUserName,
+ IN char * pszRealm,
+ IN char * pszPassword,
+ IN char * pszNonce,
+ IN char * pszCNonce,
+ OUT HASHHEX SessionKey
+ );
+
+/* calculate request-digest/response-digest as per HTTP Digest spec */
+void DigestCalcResponse(
+ IN HASHHEX HA1, /* H(A1) */
+ IN char * pszNonce, /* nonce from server */
+ IN char * pszNonceCount, /* 8 hex digits */
+ IN char * pszCNonce, /* client nonce */
+ IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
+ IN char * pszMethod, /* method from the request */
+ IN char * pszDigestUri, /* requested URL */
+ IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
+ OUT HASHHEX Response /* request-digest or response-digest */
+ );
+
+File "digcalc.c":
+
+#include <global.h>
+#include <md5.h>
+
+
+
+Franks, et al. Standards Track [Page 27]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+#include <string.h>
+#include "digcalc.h"
+
+void CvtHex(
+ IN HASH Bin,
+ OUT HASHHEX Hex
+ )
+{
+ unsigned short i;
+ unsigned char j;
+
+ for (i = 0; i < HASHLEN; i++) {
+ j = (Bin[i] >> 4) & 0xf;
+ if (j <= 9)
+ Hex[i*2] = (j + '0');
+ else
+ Hex[i*2] = (j + 'a' - 10);
+ j = Bin[i] & 0xf;
+ if (j <= 9)
+ Hex[i*2+1] = (j + '0');
+ else
+ Hex[i*2+1] = (j + 'a' - 10);
+ };
+ Hex[HASHHEXLEN] = '\0';
+};
+
+/* calculate H(A1) as per spec */
+void DigestCalcHA1(
+ IN char * pszAlg,
+ IN char * pszUserName,
+ IN char * pszRealm,
+ IN char * pszPassword,
+ IN char * pszNonce,
+ IN char * pszCNonce,
+ OUT HASHHEX SessionKey
+ )
+{
+ MD5_CTX Md5Ctx;
+ HASH HA1;
+
+ MD5Init(&Md5Ctx);
+ MD5Update(&Md5Ctx, pszUserName, strlen(pszUserName));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszRealm, strlen(pszRealm));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszPassword, strlen(pszPassword));
+ MD5Final(HA1, &Md5Ctx);
+ if (stricmp(pszAlg, "md5-sess") == 0) {
+
+
+
+Franks, et al. Standards Track [Page 28]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ MD5Init(&Md5Ctx);
+ MD5Update(&Md5Ctx, HA1, HASHLEN);
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
+ MD5Final(HA1, &Md5Ctx);
+ };
+ CvtHex(HA1, SessionKey);
+};
+
+/* calculate request-digest/response-digest as per HTTP Digest spec */
+void DigestCalcResponse(
+ IN HASHHEX HA1, /* H(A1) */
+ IN char * pszNonce, /* nonce from server */
+ IN char * pszNonceCount, /* 8 hex digits */
+ IN char * pszCNonce, /* client nonce */
+ IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
+ IN char * pszMethod, /* method from the request */
+ IN char * pszDigestUri, /* requested URL */
+ IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
+ OUT HASHHEX Response /* request-digest or response-digest */
+ )
+{
+ MD5_CTX Md5Ctx;
+ HASH HA2;
+ HASH RespHash;
+ HASHHEX HA2Hex;
+
+ // calculate H(A2)
+ MD5Init(&Md5Ctx);
+ MD5Update(&Md5Ctx, pszMethod, strlen(pszMethod));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszDigestUri, strlen(pszDigestUri));
+ if (stricmp(pszQop, "auth-int") == 0) {
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, HEntity, HASHHEXLEN);
+ };
+ MD5Final(HA2, &Md5Ctx);
+ CvtHex(HA2, HA2Hex);
+
+ // calculate response
+ MD5Init(&Md5Ctx);
+ MD5Update(&Md5Ctx, HA1, HASHHEXLEN);
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
+ MD5Update(&Md5Ctx, ":", 1);
+ if (*pszQop) {
+
+
+
+Franks, et al. Standards Track [Page 29]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ MD5Update(&Md5Ctx, pszNonceCount, strlen(pszNonceCount));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
+ MD5Update(&Md5Ctx, ":", 1);
+ MD5Update(&Md5Ctx, pszQop, strlen(pszQop));
+ MD5Update(&Md5Ctx, ":", 1);
+ };
+ MD5Update(&Md5Ctx, HA2Hex, HASHHEXLEN);
+ MD5Final(RespHash, &Md5Ctx);
+ CvtHex(RespHash, Response);
+};
+
+File "digtest.c":
+
+
+#include <stdio.h>
+#include "digcalc.h"
+
+void main(int argc, char ** argv) {
+
+ char * pszNonce = "dcd98b7102dd2f0e8b11d0f600bfb0c093";
+ char * pszCNonce = "0a4f113b";
+ char * pszUser = "Mufasa";
+ char * pszRealm = "testrealm at host.com";
+ char * pszPass = "Circle Of Life";
+ char * pszAlg = "md5";
+ char szNonceCount[9] = "00000001";
+ char * pszMethod = "GET";
+ char * pszQop = "auth";
+ char * pszURI = "/dir/index.html";
+ HASHHEX HA1;
+ HASHHEX HA2 = "";
+ HASHHEX Response;
+
+ DigestCalcHA1(pszAlg, pszUser, pszRealm, pszPass, pszNonce,
+pszCNonce, HA1);
+ DigestCalcResponse(HA1, pszNonce, szNonceCount, pszCNonce, pszQop,
+ pszMethod, pszURI, HA2, Response);
+ printf("Response = %s\n", Response);
+};
+
+
+
+
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 30]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+6 Acknowledgments
+
+ Eric W. Sink, of AbiSource, Inc., was one of the original authors
+ before the specification underwent substantial revision.
+
+ In addition to the authors, valuable discussion instrumental in
+ creating this document has come from Peter J. Churchyard, Ned Freed,
+ and David M. Kristol.
+
+ Jim Gettys and Larry Masinter edited this document for update.
+
+7 References
+
+ [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext
+ Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
+
+ [2] Fielding, R., Gettys, J., Mogul, J., Frysyk, H., Masinter, L.,
+ Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
+ HTTP/1.1", RFC 2616, June 1999.
+
+ [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
+ 1992.
+
+ [4] Freed, N. and N. Borenstein. "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message Bodies",
+ RFC 2045, November 1996.
+
+ [5] Dierks, T. and C. Allen "The TLS Protocol, Version 1.0", RFC
+ 2246, January 1999.
+
+ [6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
+ Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP :
+ Digest Access Authentication", RFC 2069, January 1997.
+
+ [7] Berners Lee, T, Fielding, R. and L. Masinter, "Uniform Resource
+ Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
+
+ [8] Kaliski, B.,Robshaw, M., "Message Authentication with MD5",
+ CryptoBytes, Sping 1995, RSA Inc,
+ (http://www.rsa.com/rsalabs/pubs/cryptobytes/spring95/md5.htm)
+
+ [9] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP AUTHorize
+ Extension for Simple Challenge/Response", RFC 2195, September
+ 1997.
+
+ [10] Morgan, B., Alvestrand, H., Hodges, J., Wahl, M.,
+ "Authentication Methods for LDAP", Work in Progress.
+
+
+
+
+Franks, et al. Standards Track [Page 31]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+8 Authors' Addresses
+
+ John Franks
+ Professor of Mathematics
+ Department of Mathematics
+ Northwestern University
+ Evanston, IL 60208-2730, USA
+
+ EMail: john at math.nwu.edu
+
+
+ Phillip M. Hallam-Baker
+ Principal Consultant
+ Verisign Inc.
+ 301 Edgewater Place
+ Suite 210
+ Wakefield MA 01880, USA
+
+ EMail: pbaker at verisign.com
+
+
+ Jeffery L. Hostetler
+ Software Craftsman
+ AbiSource, Inc.
+ 6 Dunlap Court
+ Savoy, IL 61874
+
+ EMail: jeff at AbiSource.com
+
+
+ Scott D. Lawrence
+ Agranat Systems, Inc.
+ 5 Clocktower Place, Suite 400
+ Maynard, MA 01754, USA
+
+ EMail: lawrence at agranat.com
+
+
+ Paul J. Leach
+ Microsoft Corporation
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+
+ EMail: paulle at microsoft.com
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 32]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+ Ari Luotonen
+ Member of Technical Staff
+ Netscape Communications Corporation
+ 501 East Middlefield Road
+ Mountain View, CA 94043, USA
+
+
+ Lawrence C. Stewart
+ Open Market, Inc.
+ 215 First Street
+ Cambridge, MA 02142, USA
+
+ EMail: stewart at OpenMarket.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 33]
+
+RFC 2617 HTTP Authentication June 1999
+
+
+9. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Franks, et al. Standards Track [Page 34]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc2617.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc2617.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc2617.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,1907 +0,0 @@
-
-
-
-
-
-
-Network Working Group J. Franks
-Request for Comments: 2617 Northwestern University
-Obsoletes: 2069 P. Hallam-Baker
-Category: Standards Track Verisign, Inc.
- J. Hostetler
- AbiSource, Inc.
- S. Lawrence
- Agranat Systems, Inc.
- P. Leach
- Microsoft Corporation
- A. Luotonen
- Netscape Communications Corporation
- L. Stewart
- Open Market, Inc.
- June 1999
-
-
- HTTP Authentication: Basic and Digest Access Authentication
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
-Abstract
-
- "HTTP/1.0", includes the specification for a Basic Access
- Authentication scheme. This scheme is not considered to be a secure
- method of user authentication (unless used in conjunction with some
- external secure system such as SSL [5]), as the user name and
- password are passed over the network as cleartext.
-
- This document also provides the specification for HTTP's
- authentication framework, the original Basic authentication scheme
- and a scheme based on cryptographic hashes, referred to as "Digest
- Access Authentication". It is therefore also intended to serve as a
- replacement for RFC 2069 [6]. Some optional elements specified by
- RFC 2069 have been removed from this specification due to problems
- found since its publication; other new elements have been added for
- compatibility, those new elements have been made optional, but are
- strongly recommended.
-
-
-
-Franks, et al. Standards Track [Page 1]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- Like Basic, Digest access authentication verifies that both parties
- to a communication know a shared secret (a password); unlike Basic,
- this verification can be done without sending the password in the
- clear, which is Basic's biggest weakness. As with most other
- authentication protocols, the greatest sources of risks are usually
- found not in the core protocol itself but in policies and procedures
- surrounding its use.
-
-Table of Contents
-
- 1 Access Authentication................................ 3
- 1.1 Reliance on the HTTP/1.1 Specification............ 3
- 1.2 Access Authentication Framework................... 3
- 2 Basic Authentication Scheme.......................... 5
- 3 Digest Access Authentication Scheme.................. 6
- 3.1 Introduction...................................... 6
- 3.1.1 Purpose......................................... 6
- 3.1.2 Overall Operation............................... 6
- 3.1.3 Representation of digest values................. 7
- 3.1.4 Limitations..................................... 7
- 3.2 Specification of Digest Headers................... 7
- 3.2.1 The WWW-Authenticate Response Header............ 8
- 3.2.2 The Authorization Request Header................ 11
- 3.2.3 The Authentication-Info Header.................. 15
- 3.3 Digest Operation.................................. 17
- 3.4 Security Protocol Negotiation..................... 18
- 3.5 Example........................................... 18
- 3.6 Proxy-Authentication and Proxy-Authorization...... 19
- 4 Security Considerations.............................. 19
- 4.1 Authentication of Clients using Basic
- Authentication.................................... 19
- 4.2 Authentication of Clients using Digest
- Authentication.................................... 20
- 4.3 Limited Use Nonce Values.......................... 21
- 4.4 Comparison of Digest with Basic Authentication.... 22
- 4.5 Replay Attacks.................................... 22
- 4.6 Weakness Created by Multiple Authentication
- Schemes........................................... 23
- 4.7 Online dictionary attacks......................... 23
- 4.8 Man in the Middle................................. 24
- 4.9 Chosen plaintext attacks.......................... 24
- 4.10 Precomputed dictionary attacks.................... 25
- 4.11 Batch brute force attacks......................... 25
- 4.12 Spoofing by Counterfeit Servers................... 25
- 4.13 Storing passwords................................. 26
- 4.14 Summary........................................... 26
- 5 Sample implementation................................ 27
- 6 Acknowledgments...................................... 31
-
-
-
-Franks, et al. Standards Track [Page 2]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- 7 References........................................... 31
- 8 Authors' Addresses................................... 32
- 9 Full Copyright Statement............................. 34
-
-1 Access Authentication
-
-1.1 Reliance on the HTTP/1.1 Specification
-
- This specification is a companion to the HTTP/1.1 specification [2].
- It uses the augmented BNF section 2.1 of that document, and relies on
- both the non-terminals defined in that document and other aspects of
- the HTTP/1.1 specification.
-
-1.2 Access Authentication Framework
-
- HTTP provides a simple challenge-response authentication mechanism
- that MAY be used by a server to challenge a client request and by a
- client to provide authentication information. It uses an extensible,
- case-insensitive token to identify the authentication scheme,
- followed by a comma-separated list of attribute-value pairs which
- carry the parameters necessary for achieving authentication via that
- scheme.
-
- auth-scheme = token
- auth-param = token "=" ( token | quoted-string )
-
- The 401 (Unauthorized) response message is used by an origin server
- to challenge the authorization of a user agent. This response MUST
- include a WWW-Authenticate header field containing at least one
- challenge applicable to the requested resource. The 407 (Proxy
- Authentication Required) response message is used by a proxy to
- challenge the authorization of a client and MUST include a Proxy-
- Authenticate header field containing at least one challenge
- applicable to the proxy for the requested resource.
-
- challenge = auth-scheme 1*SP 1#auth-param
-
- Note: User agents will need to take special care in parsing the WWW-
- Authenticate or Proxy-Authenticate header field value if it contains
- more than one challenge, or if more than one WWW-Authenticate header
- field is provided, since the contents of a challenge may itself
- contain a comma-separated list of authentication parameters.
-
- The authentication parameter realm is defined for all authentication
- schemes:
-
- realm = "realm" "=" realm-value
- realm-value = quoted-string
-
-
-
-Franks, et al. Standards Track [Page 3]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- The realm directive (case-insensitive) is required for all
- authentication schemes that issue a challenge. The realm value
- (case-sensitive), in combination with the canonical root URL (the
- absoluteURI for the server whose abs_path is empty; see section 5.1.2
- of [2]) of the server being accessed, defines the protection space.
- These realms allow the protected resources on a server to be
- partitioned into a set of protection spaces, each with its own
- authentication scheme and/or authorization database. The realm value
- is a string, generally assigned by the origin server, which may have
- additional semantics specific to the authentication scheme. Note that
- there may be multiple challenges with the same auth-scheme but
- different realms.
-
- A user agent that wishes to authenticate itself with an origin
- server--usually, but not necessarily, after receiving a 401
- (Unauthorized)--MAY do so by including an Authorization header field
- with the request. A client that wishes to authenticate itself with a
- proxy--usually, but not necessarily, after receiving a 407 (Proxy
- Authentication Required)--MAY do so by including a Proxy-
- Authorization header field with the request. Both the Authorization
- field value and the Proxy-Authorization field value consist of
- credentials containing the authentication information of the client
- for the realm of the resource being requested. The user agent MUST
- choose to use one of the challenges with the strongest auth-scheme it
- understands and request credentials from the user based upon that
- challenge.
-
- credentials = auth-scheme #auth-param
-
- Note that many browsers will only recognize Basic and will require
- that it be the first auth-scheme presented. Servers should only
- include Basic if it is minimally acceptable.
-
- The protection space determines the domain over which credentials can
- be automatically applied. If a prior request has been authorized, the
- same credentials MAY be reused for all other requests within that
- protection space for a period of time determined by the
- authentication scheme, parameters, and/or user preference. Unless
- otherwise defined by the authentication scheme, a single protection
- space cannot extend outside the scope of its server.
-
- If the origin server does not wish to accept the credentials sent
- with a request, it SHOULD return a 401 (Unauthorized) response. The
- response MUST include a WWW-Authenticate header field containing at
- least one (possibly new) challenge applicable to the requested
- resource. If a proxy does not accept the credentials sent with a
- request, it SHOULD return a 407 (Proxy Authentication Required). The
- response MUST include a Proxy-Authenticate header field containing a
-
-
-
-Franks, et al. Standards Track [Page 4]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- (possibly new) challenge applicable to the proxy for the requested
- resource.
-
- The HTTP protocol does not restrict applications to this simple
- challenge-response mechanism for access authentication. Additional
- mechanisms MAY be used, such as encryption at the transport level or
- via message encapsulation, and with additional header fields
- specifying authentication information. However, these additional
- mechanisms are not defined by this specification.
-
- Proxies MUST be completely transparent regarding user agent
- authentication by origin servers. That is, they must forward the
- WWW-Authenticate and Authorization headers untouched, and follow the
- rules found in section 14.8 of [2]. Both the Proxy-Authenticate and
- the Proxy-Authorization header fields are hop-by-hop headers (see
- section 13.5.1 of [2]).
-
-2 Basic Authentication Scheme
-
- The "basic" authentication scheme is based on the model that the
- client must authenticate itself with a user-ID and a password for
- each realm. The realm value should be considered an opaque string
- which can only be compared for equality with other realms on that
- server. The server will service the request only if it can validate
- the user-ID and password for the protection space of the Request-URI.
- There are no optional authentication parameters.
-
- For Basic, the framework above is utilized as follows:
-
- challenge = "Basic" realm
- credentials = "Basic" basic-credentials
-
- Upon receipt of an unauthorized request for a URI within the
- protection space, the origin server MAY respond with a challenge like
- the following:
-
- WWW-Authenticate: Basic realm="WallyWorld"
-
- where "WallyWorld" is the string assigned by the server to identify
- the protection space of the Request-URI. A proxy may respond with the
- same challenge using the Proxy-Authenticate header field.
-
- To receive authorization, the client sends the userid and password,
- separated by a single colon (":") character, within a base64 [7]
- encoded string in the credentials.
-
- basic-credentials = base64-user-pass
- base64-user-pass = <base64 [4] encoding of user-pass,
-
-
-
-Franks, et al. Standards Track [Page 5]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- except not limited to 76 char/line>
- user-pass = userid ":" password
- userid = *<TEXT excluding ":">
- password = *TEXT
-
- Userids might be case sensitive.
-
- If the user agent wishes to send the userid "Aladdin" and password
- "open sesame", it would use the following header field:
-
- Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
-
- A client SHOULD assume that all paths at or deeper than the depth of
- the last symbolic element in the path field of the Request-URI also
- are within the protection space specified by the Basic realm value of
- the current challenge. A client MAY preemptively send the
- corresponding Authorization header with requests for resources in
- that space without receipt of another challenge from the server.
- Similarly, when a client sends a request to a proxy, it may reuse a
- userid and password in the Proxy-Authorization header field without
- receiving another challenge from the proxy server. See section 4 for
- security considerations associated with Basic authentication.
-
-3 Digest Access Authentication Scheme
-
-3.1 Introduction
-
-3.1.1 Purpose
-
- The protocol referred to as "HTTP/1.0" includes the specification for
- a Basic Access Authentication scheme[1]. That scheme is not
- considered to be a secure method of user authentication, as the user
- name and password are passed over the network in an unencrypted form.
- This section provides the specification for a scheme that does not
- send the password in cleartext, referred to as "Digest Access
- Authentication".
-
- The Digest Access Authentication scheme is not intended to be a
- complete answer to the need for security in the World Wide Web. This
- scheme provides no encryption of message content. The intent is
- simply to create an access authentication method that avoids the most
- serious flaws of Basic authentication.
-
-3.1.2 Overall Operation
-
- Like Basic Access Authentication, the Digest scheme is based on a
- simple challenge-response paradigm. The Digest scheme challenges
- using a nonce value. A valid response contains a checksum (by
-
-
-
-Franks, et al. Standards Track [Page 6]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- default, the MD5 checksum) of the username, the password, the given
- nonce value, the HTTP method, and the requested URI. In this way, the
- password is never sent in the clear. Just as with the Basic scheme,
- the username and password must be prearranged in some fashion not
- addressed by this document.
-
-3.1.3 Representation of digest values
-
- An optional header allows the server to specify the algorithm used to
- create the checksum or digest. By default the MD5 algorithm is used
- and that is the only algorithm described in this document.
-
- For the purposes of this document, an MD5 digest of 128 bits is
- represented as 32 ASCII printable characters. The bits in the 128 bit
- digest are converted from most significant to least significant bit,
- four bits at a time to their ASCII presentation as follows. Each four
- bits is represented by its familiar hexadecimal notation from the
- characters 0123456789abcdef. That is, binary 0000 gets represented by
- the character '0', 0001, by '1', and so on up to the representation
- of 1111 as 'f'.
-
-3.1.4 Limitations
-
- The Digest authentication scheme described in this document suffers
- from many known limitations. It is intended as a replacement for
- Basic authentication and nothing more. It is a password-based system
- and (on the server side) suffers from all the same problems of any
- password system. In particular, no provision is made in this protocol
- for the initial secure arrangement between user and server to
- establish the user's password.
-
- Users and implementors should be aware that this protocol is not as
- secure as Kerberos, and not as secure as any client-side private-key
- scheme. Nevertheless it is better than nothing, better than what is
- commonly used with telnet and ftp, and better than Basic
- authentication.
-
-3.2 Specification of Digest Headers
-
- The Digest Access Authentication scheme is conceptually similar to
- the Basic scheme. The formats of the modified WWW-Authenticate header
- line and the Authorization header line are specified below. In
- addition, a new header, Authentication-Info, is specified.
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 7]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-3.2.1 The WWW-Authenticate Response Header
-
- If a server receives a request for an access-protected object, and an
- acceptable Authorization header is not sent, the server responds with
- a "401 Unauthorized" status code, and a WWW-Authenticate header as
- per the framework defined above, which for the digest scheme is
- utilized as follows:
-
- challenge = "Digest" digest-challenge
-
- digest-challenge = 1#( realm | [ domain ] | nonce |
- [ opaque ] |[ stale ] | [ algorithm ] |
- [ qop-options ] | [auth-param] )
-
-
- domain = "domain" "=" <"> URI ( 1*SP URI ) <">
- URI = absoluteURI | abs_path
- nonce = "nonce" "=" nonce-value
- nonce-value = quoted-string
- opaque = "opaque" "=" quoted-string
- stale = "stale" "=" ( "true" | "false" )
- algorithm = "algorithm" "=" ( "MD5" | "MD5-sess" |
- token )
- qop-options = "qop" "=" <"> 1#qop-value <">
- qop-value = "auth" | "auth-int" | token
-
- The meanings of the values of the directives used above are as
- follows:
-
- realm
- A string to be displayed to users so they know which username and
- password to use. This string should contain at least the name of
- the host performing the authentication and might additionally
- indicate the collection of users who might have access. An example
- might be "registered_users at gotham.news.com".
-
- domain
- A quoted, space-separated list of URIs, as specified in RFC XURI
- [7], that define the protection space. If a URI is an abs_path, it
- is relative to the canonical root URL (see section 1.2 above) of
- the server being accessed. An absoluteURI in this list may refer to
- a different server than the one being accessed. The client can use
- this list to determine the set of URIs for which the same
- authentication information may be sent: any URI that has a URI in
- this list as a prefix (after both have been made absolute) may be
- assumed to be in the same protection space. If this directive is
- omitted or its value is empty, the client should assume that the
- protection space consists of all URIs on the responding server.
-
-
-
-Franks, et al. Standards Track [Page 8]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- This directive is not meaningful in Proxy-Authenticate headers, for
- which the protection space is always the entire proxy; if present
- it should be ignored.
-
- nonce
- A server-specified data string which should be uniquely generated
- each time a 401 response is made. It is recommended that this
- string be base64 or hexadecimal data. Specifically, since the
- string is passed in the header lines as a quoted string, the
- double-quote character is not allowed.
-
- The contents of the nonce are implementation dependent. The quality
- of the implementation depends on a good choice. A nonce might, for
- example, be constructed as the base 64 encoding of
-
- time-stamp H(time-stamp ":" ETag ":" private-key)
-
- where time-stamp is a server-generated time or other non-repeating
- value, ETag is the value of the HTTP ETag header associated with
- the requested entity, and private-key is data known only to the
- server. With a nonce of this form a server would recalculate the
- hash portion after receiving the client authentication header and
- reject the request if it did not match the nonce from that header
- or if the time-stamp value is not recent enough. In this way the
- server can limit the time of the nonce's validity. The inclusion of
- the ETag prevents a replay request for an updated version of the
- resource. (Note: including the IP address of the client in the
- nonce would appear to offer the server the ability to limit the
- reuse of the nonce to the same client that originally got it.
- However, that would break proxy farms, where requests from a single
- user often go through different proxies in the farm. Also, IP
- address spoofing is not that hard.)
-
- An implementation might choose not to accept a previously used
- nonce or a previously used digest, in order to protect against a
- replay attack. Or, an implementation might choose to use one-time
- nonces or digests for POST or PUT requests and a time-stamp for GET
- requests. For more details on the issues involved see section 4.
- of this document.
-
- The nonce is opaque to the client.
-
- opaque
- A string of data, specified by the server, which should be returned
- by the client unchanged in the Authorization header of subsequent
- requests with URIs in the same protection space. It is recommended
- that this string be base64 or hexadecimal data.
-
-
-
-
-Franks, et al. Standards Track [Page 9]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- stale
- A flag, indicating that the previous request from the client was
- rejected because the nonce value was stale. If stale is TRUE
- (case-insensitive), the client may wish to simply retry the request
- with a new encrypted response, without reprompting the user for a
- new username and password. The server should only set stale to TRUE
- if it receives a request for which the nonce is invalid but with a
- valid digest for that nonce (indicating that the client knows the
- correct username/password). If stale is FALSE, or anything other
- than TRUE, or the stale directive is not present, the username
- and/or password are invalid, and new values must be obtained.
-
- algorithm
- A string indicating a pair of algorithms used to produce the digest
- and a checksum. If this is not present it is assumed to be "MD5".
- If the algorithm is not understood, the challenge should be ignored
- (and a different one used, if there is more than one).
-
- In this document the string obtained by applying the digest
- algorithm to the data "data" with secret "secret" will be denoted
- by KD(secret, data), and the string obtained by applying the
- checksum algorithm to the data "data" will be denoted H(data). The
- notation unq(X) means the value of the quoted-string X without the
- surrounding quotes.
-
- For the "MD5" and "MD5-sess" algorithms
-
- H(data) = MD5(data)
-
- and
-
- KD(secret, data) = H(concat(secret, ":", data))
-
- i.e., the digest is the MD5 of the secret concatenated with a colon
- concatenated with the data. The "MD5-sess" algorithm is intended to
- allow efficient 3rd party authentication servers; for the
- difference in usage, see the description in section 3.2.2.2.
-
- qop-options
- This directive is optional, but is made so only for backward
- compatibility with RFC 2069 [6]; it SHOULD be used by all
- implementations compliant with this version of the Digest scheme.
- If present, it is a quoted string of one or more tokens indicating
- the "quality of protection" values supported by the server. The
- value "auth" indicates authentication; the value "auth-int"
- indicates authentication with integrity protection; see the
-
-
-
-
-
-Franks, et al. Standards Track [Page 10]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- descriptions below for calculating the response directive value for
- the application of this choice. Unrecognized options MUST be
- ignored.
-
- auth-param
- This directive allows for future extensions. Any unrecognized
- directive MUST be ignored.
-
-3.2.2 The Authorization Request Header
-
- The client is expected to retry the request, passing an Authorization
- header line, which is defined according to the framework above,
- utilized as follows.
-
- credentials = "Digest" digest-response
- digest-response = 1#( username | realm | nonce | digest-uri
- | response | [ algorithm ] | [cnonce] |
- [opaque] | [message-qop] |
- [nonce-count] | [auth-param] )
-
- username = "username" "=" username-value
- username-value = quoted-string
- digest-uri = "uri" "=" digest-uri-value
- digest-uri-value = request-uri ; As specified by HTTP/1.1
- message-qop = "qop" "=" qop-value
- cnonce = "cnonce" "=" cnonce-value
- cnonce-value = nonce-value
- nonce-count = "nc" "=" nc-value
- nc-value = 8LHEX
- response = "response" "=" request-digest
- request-digest = <"> 32LHEX <">
- LHEX = "0" | "1" | "2" | "3" |
- "4" | "5" | "6" | "7" |
- "8" | "9" | "a" | "b" |
- "c" | "d" | "e" | "f"
-
- The values of the opaque and algorithm fields must be those supplied
- in the WWW-Authenticate response header for the entity being
- requested.
-
- response
- A string of 32 hex digits computed as defined below, which proves
- that the user knows a password
-
- username
- The user's name in the specified realm.
-
-
-
-
-
-Franks, et al. Standards Track [Page 11]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- digest-uri
- The URI from Request-URI of the Request-Line; duplicated here
- because proxies are allowed to change the Request-Line in transit.
-
- qop
- Indicates what "quality of protection" the client has applied to
- the message. If present, its value MUST be one of the alternatives
- the server indicated it supports in the WWW-Authenticate header.
- These values affect the computation of the request-digest. Note
- that this is a single token, not a quoted list of alternatives as
- in WWW- Authenticate. This directive is optional in order to
- preserve backward compatibility with a minimal implementation of
- RFC 2069 [6], but SHOULD be used if the server indicated that qop
- is supported by providing a qop directive in the WWW-Authenticate
- header field.
-
- cnonce
- This MUST be specified if a qop directive is sent (see above), and
- MUST NOT be specified if the server did not send a qop directive in
- the WWW-Authenticate header field. The cnonce-value is an opaque
- quoted string value provided by the client and used by both client
- and server to avoid chosen plaintext attacks, to provide mutual
- authentication, and to provide some message integrity protection.
- See the descriptions below of the calculation of the response-
- digest and request-digest values.
-
- nonce-count
- This MUST be specified if a qop directive is sent (see above), and
- MUST NOT be specified if the server did not send a qop directive in
- the WWW-Authenticate header field. The nc-value is the hexadecimal
- count of the number of requests (including the current request)
- that the client has sent with the nonce value in this request. For
- example, in the first request sent in response to a given nonce
- value, the client sends "nc=00000001". The purpose of this
- directive is to allow the server to detect request replays by
- maintaining its own copy of this count - if the same nc-value is
- seen twice, then the request is a replay. See the description
- below of the construction of the request-digest value.
-
- auth-param
- This directive allows for future extensions. Any unrecognized
- directive MUST be ignored.
-
- If a directive or its value is improper, or required directives are
- missing, the proper response is 400 Bad Request. If the request-
- digest is invalid, then a login failure should be logged, since
- repeated login failures from a single client may indicate an attacker
- attempting to guess passwords.
-
-
-
-Franks, et al. Standards Track [Page 12]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- The definition of request-digest above indicates the encoding for its
- value. The following definitions show how the value is computed.
-
-3.2.2.1 Request-Digest
-
- If the "qop" value is "auth" or "auth-int":
-
- request-digest = <"> < KD ( H(A1), unq(nonce-value)
- ":" nc-value
- ":" unq(cnonce-value)
- ":" unq(qop-value)
- ":" H(A2)
- ) <">
-
- If the "qop" directive is not present (this construction is for
- compatibility with RFC 2069):
-
- request-digest =
- <"> < KD ( H(A1), unq(nonce-value) ":" H(A2) ) >
- <">
-
- See below for the definitions for A1 and A2.
-
-3.2.2.2 A1
-
- If the "algorithm" directive's value is "MD5" or is unspecified, then
- A1 is:
-
- A1 = unq(username-value) ":" unq(realm-value) ":" passwd
-
- where
-
- passwd = < user's password >
-
- If the "algorithm" directive's value is "MD5-sess", then A1 is
- calculated only once - on the first request by the client following
- receipt of a WWW-Authenticate challenge from the server. It uses the
- server nonce from that challenge, and the first client nonce value to
- construct A1 as follows:
-
- A1 = H( unq(username-value) ":" unq(realm-value)
- ":" passwd )
- ":" unq(nonce-value) ":" unq(cnonce-value)
-
- This creates a 'session key' for the authentication of subsequent
- requests and responses which is different for each "authentication
- session", thus limiting the amount of material hashed with any one
- key. (Note: see further discussion of the authentication session in
-
-
-
-Franks, et al. Standards Track [Page 13]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- section 3.3.) Because the server need only use the hash of the user
- credentials in order to create the A1 value, this construction could
- be used in conjunction with a third party authentication service so
- that the web server would not need the actual password value. The
- specification of such a protocol is beyond the scope of this
- specification.
-
-3.2.2.3 A2
-
- If the "qop" directive's value is "auth" or is unspecified, then A2
- is:
-
- A2 = Method ":" digest-uri-value
-
- If the "qop" value is "auth-int", then A2 is:
-
- A2 = Method ":" digest-uri-value ":" H(entity-body)
-
-3.2.2.4 Directive values and quoted-string
-
- Note that the value of many of the directives, such as "username-
- value", are defined as a "quoted-string". However, the "unq" notation
- indicates that surrounding quotation marks are removed in forming the
- string A1. Thus if the Authorization header includes the fields
-
- username="Mufasa", realm=myhost at testrealm.com
-
- and the user Mufasa has password "Circle Of Life" then H(A1) would be
- H(Mufasa:myhost at testrealm.com:Circle Of Life) with no quotation marks
- in the digested string.
-
- No white space is allowed in any of the strings to which the digest
- function H() is applied unless that white space exists in the quoted
- strings or entity body whose contents make up the string to be
- digested. For example, the string A1 illustrated above must be
-
- Mufasa:myhost at testrealm.com:Circle Of Life
-
- with no white space on either side of the colons, but with the white
- space between the words used in the password value. Likewise, the
- other strings digested by H() must not have white space on either
- side of the colons which delimit their fields unless that white space
- was in the quoted strings or entity body being digested.
-
- Also note that if integrity protection is applied (qop=auth-int), the
- H(entity-body) is the hash of the entity body, not the message body -
- it is computed before any transfer encoding is applied by the sender
-
-
-
-
-Franks, et al. Standards Track [Page 14]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- and after it has been removed by the recipient. Note that this
- includes multipart boundaries and embedded headers in each part of
- any multipart content-type.
-
-3.2.2.5 Various considerations
-
- The "Method" value is the HTTP request method as specified in section
- 5.1.1 of [2]. The "request-uri" value is the Request-URI from the
- request line as specified in section 5.1.2 of [2]. This may be "*",
- an "absoluteURL" or an "abs_path" as specified in section 5.1.2 of
- [2], but it MUST agree with the Request-URI. In particular, it MUST
- be an "absoluteURL" if the Request-URI is an "absoluteURL". The
- "cnonce-value" is an optional client-chosen value whose purpose is
- to foil chosen plaintext attacks.
-
- The authenticating server must assure that the resource designated by
- the "uri" directive is the same as the resource specified in the
- Request-Line; if they are not, the server SHOULD return a 400 Bad
- Request error. (Since this may be a symptom of an attack, server
- implementers may want to consider logging such errors.) The purpose
- of duplicating information from the request URL in this field is to
- deal with the possibility that an intermediate proxy may alter the
- client's Request-Line. This altered (but presumably semantically
- equivalent) request would not result in the same digest as that
- calculated by the client.
-
- Implementers should be aware of how authenticated transactions
- interact with shared caches. The HTTP/1.1 protocol specifies that
- when a shared cache (see section 13.7 of [2]) has received a request
- containing an Authorization header and a response from relaying that
- request, it MUST NOT return that response as a reply to any other
- request, unless one of two Cache-Control (see section 14.9 of [2])
- directives was present in the response. If the original response
- included the "must-revalidate" Cache-Control directive, the cache MAY
- use the entity of that response in replying to a subsequent request,
- but MUST first revalidate it with the origin server, using the
- request headers from the new request to allow the origin server to
- authenticate the new request. Alternatively, if the original response
- included the "public" Cache-Control directive, the response entity
- MAY be returned in reply to any subsequent request.
-
-3.2.3 The Authentication-Info Header
-
- The Authentication-Info header is used by the server to communicate
- some information regarding the successful authentication in the
- response.
-
-
-
-
-
-Franks, et al. Standards Track [Page 15]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- AuthenticationInfo = "Authentication-Info" ":" auth-info
- auth-info = 1#(nextnonce | [ message-qop ]
- | [ response-auth ] | [ cnonce ]
- | [nonce-count] )
- nextnonce = "nextnonce" "=" nonce-value
- response-auth = "rspauth" "=" response-digest
- response-digest = <"> *LHEX <">
-
- The value of the nextnonce directive is the nonce the server wishes
- the client to use for a future authentication response. The server
- may send the Authentication-Info header with a nextnonce field as a
- means of implementing one-time or otherwise changing nonces. If the
- nextnonce field is present the client SHOULD use it when constructing
- the Authorization header for its next request. Failure of the client
- to do so may result in a request to re-authenticate from the server
- with the "stale=TRUE".
-
- Server implementations should carefully consider the performance
- implications of the use of this mechanism; pipelined requests will
- not be possible if every response includes a nextnonce directive
- that must be used on the next request received by the server.
- Consideration should be given to the performance vs. security
- tradeoffs of allowing an old nonce value to be used for a limited
- time to permit request pipelining. Use of the nonce-count can
- retain most of the security advantages of a new server nonce
- without the deleterious affects on pipelining.
-
- message-qop
- Indicates the "quality of protection" options applied to the
- response by the server. The value "auth" indicates authentication;
- the value "auth-int" indicates authentication with integrity
- protection. The server SHOULD use the same value for the message-
- qop directive in the response as was sent by the client in the
- corresponding request.
-
- The optional response digest in the "response-auth" directive
- supports mutual authentication -- the server proves that it knows the
- user's secret, and with qop=auth-int also provides limited integrity
- protection of the response. The "response-digest" value is calculated
- as for the "request-digest" in the Authorization header, except that
- if "qop=auth" or is not specified in the Authorization header for the
- request, A2 is
-
- A2 = ":" digest-uri-value
-
- and if "qop=auth-int", then A2 is
-
- A2 = ":" digest-uri-value ":" H(entity-body)
-
-
-
-Franks, et al. Standards Track [Page 16]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- where "digest-uri-value" is the value of the "uri" directive on the
- Authorization header in the request. The "cnonce-value" and "nc-
- value" MUST be the ones for the client request to which this message
- is the response. The "response-auth", "cnonce", and "nonce-count"
- directives MUST BE present if "qop=auth" or "qop=auth-int" is
- specified.
-
- The Authentication-Info header is allowed in the trailer of an HTTP
- message transferred via chunked transfer-coding.
-
-3.3 Digest Operation
-
- Upon receiving the Authorization header, the server may check its
- validity by looking up the password that corresponds to the submitted
- username. Then, the server must perform the same digest operation
- (e.g., MD5) performed by the client, and compare the result to the
- given request-digest value.
-
- Note that the HTTP server does not actually need to know the user's
- cleartext password. As long as H(A1) is available to the server, the
- validity of an Authorization header may be verified.
-
- The client response to a WWW-Authenticate challenge for a protection
- space starts an authentication session with that protection space.
- The authentication session lasts until the client receives another
- WWW-Authenticate challenge from any server in the protection space. A
- client should remember the username, password, nonce, nonce count and
- opaque values associated with an authentication session to use to
- construct the Authorization header in future requests within that
- protection space. The Authorization header may be included
- preemptively; doing so improves server efficiency and avoids extra
- round trips for authentication challenges. The server may choose to
- accept the old Authorization header information, even though the
- nonce value included might not be fresh. Alternatively, the server
- may return a 401 response with a new nonce value, causing the client
- to retry the request; by specifying stale=TRUE with this response,
- the server tells the client to retry with the new nonce, but without
- prompting for a new username and password.
-
- Because the client is required to return the value of the opaque
- directive given to it by the server for the duration of a session,
- the opaque data may be used to transport authentication session state
- information. (Note that any such use can also be accomplished more
- easily and safely by including the state in the nonce.) For example,
- a server could be responsible for authenticating content that
- actually sits on another server. It would achieve this by having the
- first 401 response include a domain directive whose value includes a
- URI on the second server, and an opaque directive whose value
-
-
-
-Franks, et al. Standards Track [Page 17]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- contains the state information. The client will retry the request, at
- which time the server might respond with a 301/302 redirection,
- pointing to the URI on the second server. The client will follow the
- redirection, and pass an Authorization header , including the
- <opaque> data.
-
- As with the basic scheme, proxies must be completely transparent in
- the Digest access authentication scheme. That is, they must forward
- the WWW-Authenticate, Authentication-Info and Authorization headers
- untouched. If a proxy wants to authenticate a client before a request
- is forwarded to the server, it can be done using the Proxy-
- Authenticate and Proxy-Authorization headers described in section 3.6
- below.
-
-3.4 Security Protocol Negotiation
-
- It is useful for a server to be able to know which security schemes a
- client is capable of handling.
-
- It is possible that a server may want to require Digest as its
- authentication method, even if the server does not know that the
- client supports it. A client is encouraged to fail gracefully if the
- server specifies only authentication schemes it cannot handle.
-
-3.5 Example
-
- The following example assumes that an access-protected document is
- being requested from the server via a GET request. The URI of the
- document is "http://www.nowhere.org/dir/index.html". Both client and
- server know that the username for this document is "Mufasa", and the
- password is "Circle Of Life" (with one space between each of the
- three words).
-
- The first time the client requests the document, no Authorization
- header is sent, so the server responds with:
-
- HTTP/1.1 401 Unauthorized
- WWW-Authenticate: Digest
- realm="testrealm at host.com",
- qop="auth,auth-int",
- nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
- opaque="5ccc069c403ebaf9f0171e9517f40e41"
-
- The client may prompt the user for the username and password, after
- which it will respond with a new request, including the following
- Authorization header:
-
-
-
-
-
-Franks, et al. Standards Track [Page 18]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- Authorization: Digest username="Mufasa",
- realm="testrealm at host.com",
- nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
- uri="/dir/index.html",
- qop=auth,
- nc=00000001,
- cnonce="0a4f113b",
- response="6629fae49393a05397450978507c4ef1",
- opaque="5ccc069c403ebaf9f0171e9517f40e41"
-
-3.6 Proxy-Authentication and Proxy-Authorization
-
- The digest authentication scheme may also be used for authenticating
- users to proxies, proxies to proxies, or proxies to origin servers by
- use of the Proxy-Authenticate and Proxy-Authorization headers. These
- headers are instances of the Proxy-Authenticate and Proxy-
- Authorization headers specified in sections 10.33 and 10.34 of the
- HTTP/1.1 specification [2] and their behavior is subject to
- restrictions described there. The transactions for proxy
- authentication are very similar to those already described. Upon
- receiving a request which requires authentication, the proxy/server
- must issue the "407 Proxy Authentication Required" response with a
- "Proxy-Authenticate" header. The digest-challenge used in the
- Proxy-Authenticate header is the same as that for the WWW-
- Authenticate header as defined above in section 3.2.1.
-
- The client/proxy must then re-issue the request with a Proxy-
- Authorization header, with directives as specified for the
- Authorization header in section 3.2.2 above.
-
- On subsequent responses, the server sends Proxy-Authentication-Info
- with directives the same as those for the Authentication-Info header
- field.
-
- Note that in principle a client could be asked to authenticate itself
- to both a proxy and an end-server, but never in the same response.
-
-4 Security Considerations
-
-4.1 Authentication of Clients using Basic Authentication
-
- The Basic authentication scheme is not a secure method of user
- authentication, nor does it in any way protect the entity, which is
- transmitted in cleartext across the physical network used as the
- carrier. HTTP does not prevent additional authentication schemes and
- encryption mechanisms from being employed to increase security or the
- addition of enhancements (such as schemes to use one-time passwords)
- to Basic authentication.
-
-
-
-Franks, et al. Standards Track [Page 19]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- The most serious flaw in Basic authentication is that it results in
- the essentially cleartext transmission of the user's password over
- the physical network. It is this problem which Digest Authentication
- attempts to address.
-
- Because Basic authentication involves the cleartext transmission of
- passwords it SHOULD NOT be used (without enhancements) to protect
- sensitive or valuable information.
-
- A common use of Basic authentication is for identification purposes
- -- requiring the user to provide a user name and password as a means
- of identification, for example, for purposes of gathering accurate
- usage statistics on a server. When used in this way it is tempting to
- think that there is no danger in its use if illicit access to the
- protected documents is not a major concern. This is only correct if
- the server issues both user name and password to the users and in
- particular does not allow the user to choose his or her own password.
- The danger arises because naive users frequently reuse a single
- password to avoid the task of maintaining multiple passwords.
-
- If a server permits users to select their own passwords, then the
- threat is not only unauthorized access to documents on the server but
- also unauthorized access to any other resources on other systems that
- the user protects with the same password. Furthermore, in the
- server's password database, many of the passwords may also be users'
- passwords for other sites. The owner or administrator of such a
- system could therefore expose all users of the system to the risk of
- unauthorized access to all those sites if this information is not
- maintained in a secure fashion.
-
- Basic Authentication is also vulnerable to spoofing by counterfeit
- servers. If a user can be led to believe that he is connecting to a
- host containing information protected by Basic authentication when,
- in fact, he is connecting to a hostile server or gateway, then the
- attacker can request a password, store it for later use, and feign an
- error. This type of attack is not possible with Digest
- Authentication. Server implementers SHOULD guard against the
- possibility of this sort of counterfeiting by gateways or CGI
- scripts. In particular it is very dangerous for a server to simply
- turn over a connection to a gateway. That gateway can then use the
- persistent connection mechanism to engage in multiple transactions
- with the client while impersonating the original server in a way that
- is not detectable by the client.
-
-4.2 Authentication of Clients using Digest Authentication
-
- Digest Authentication does not provide a strong authentication
- mechanism, when compared to public key based mechanisms, for example.
-
-
-
-Franks, et al. Standards Track [Page 20]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- However, it is significantly stronger than (e.g.) CRAM-MD5, which has
- been proposed for use with LDAP [10], POP and IMAP (see RFC 2195
- [9]). It is intended to replace the much weaker and even more
- dangerous Basic mechanism.
-
- Digest Authentication offers no confidentiality protection beyond
- protecting the actual password. All of the rest of the request and
- response are available to an eavesdropper.
-
- Digest Authentication offers only limited integrity protection for
- the messages in either direction. If qop=auth-int mechanism is used,
- those parts of the message used in the calculation of the WWW-
- Authenticate and Authorization header field response directive values
- (see section 3.2 above) are protected. Most header fields and their
- values could be modified as a part of a man-in-the-middle attack.
-
- Many needs for secure HTTP transactions cannot be met by Digest
- Authentication. For those needs TLS or SHTTP are more appropriate
- protocols. In particular Digest authentication cannot be used for any
- transaction requiring confidentiality protection. Nevertheless many
- functions remain for which Digest authentication is both useful and
- appropriate. Any service in present use that uses Basic should be
- switched to Digest as soon as practical.
-
-4.3 Limited Use Nonce Values
-
- The Digest scheme uses a server-specified nonce to seed the
- generation of the request-digest value (as specified in section
- 3.2.2.1 above). As shown in the example nonce in section 3.2.1, the
- server is free to construct the nonce such that it may only be used
- from a particular client, for a particular resource, for a limited
- period of time or number of uses, or any other restrictions. Doing
- so strengthens the protection provided against, for example, replay
- attacks (see 4.5). However, it should be noted that the method
- chosen for generating and checking the nonce also has performance and
- resource implications. For example, a server may choose to allow
- each nonce value to be used only once by maintaining a record of
- whether or not each recently issued nonce has been returned and
- sending a next-nonce directive in the Authentication-Info header
- field of every response. This protects against even an immediate
- replay attack, but has a high cost checking nonce values, and perhaps
- more important will cause authentication failures for any pipelined
- requests (presumably returning a stale nonce indication). Similarly,
- incorporating a request-specific element such as the Etag value for a
- resource limits the use of the nonce to that version of the resource
- and also defeats pipelining. Thus it may be useful to do so for
- methods with side effects but have unacceptable performance for those
- that do not.
-
-
-
-Franks, et al. Standards Track [Page 21]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-4.4 Comparison of Digest with Basic Authentication
-
- Both Digest and Basic Authentication are very much on the weak end of
- the security strength spectrum. But a comparison between the two
- points out the utility, even necessity, of replacing Basic by Digest.
-
- The greatest threat to the type of transactions for which these
- protocols are used is network snooping. This kind of transaction
- might involve, for example, online access to a database whose use is
- restricted to paying subscribers. With Basic authentication an
- eavesdropper can obtain the password of the user. This not only
- permits him to access anything in the database, but, often worse,
- will permit access to anything else the user protects with the same
- password.
-
- By contrast, with Digest Authentication the eavesdropper only gets
- access to the transaction in question and not to the user's password.
- The information gained by the eavesdropper would permit a replay
- attack, but only with a request for the same document, and even that
- may be limited by the server's choice of nonce.
-
-4.5 Replay Attacks
-
- A replay attack against Digest authentication would usually be
- pointless for a simple GET request since an eavesdropper would
- already have seen the only document he could obtain with a replay.
- This is because the URI of the requested document is digested in the
- client request and the server will only deliver that document. By
- contrast under Basic Authentication once the eavesdropper has the
- user's password, any document protected by that password is open to
- him.
-
- Thus, for some purposes, it is necessary to protect against replay
- attacks. A good Digest implementation can do this in various ways.
- The server created "nonce" value is implementation dependent, but if
- it contains a digest of the client IP, a time-stamp, the resource
- ETag, and a private server key (as recommended above) then a replay
- attack is not simple. An attacker must convince the server that the
- request is coming from a false IP address and must cause the server
- to deliver the document to an IP address different from the address
- to which it believes it is sending the document. An attack can only
- succeed in the period before the time-stamp expires. Digesting the
- client IP and time-stamp in the nonce permits an implementation which
- does not maintain state between transactions.
-
- For applications where no possibility of replay attack can be
- tolerated the server can use one-time nonce values which will not be
- honored for a second use. This requires the overhead of the server
-
-
-
-Franks, et al. Standards Track [Page 22]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- remembering which nonce values have been used until the nonce time-
- stamp (and hence the digest built with it) has expired, but it
- effectively protects against replay attacks.
-
- An implementation must give special attention to the possibility of
- replay attacks with POST and PUT requests. Unless the server employs
- one-time or otherwise limited-use nonces and/or insists on the use of
- the integrity protection of qop=auth-int, an attacker could replay
- valid credentials from a successful request with counterfeit form
- data or other message body. Even with the use of integrity protection
- most metadata in header fields is not protected. Proper nonce
- generation and checking provides some protection against replay of
- previously used valid credentials, but see 4.8.
-
-4.6 Weakness Created by Multiple Authentication Schemes
-
- An HTTP/1.1 server may return multiple challenges with a 401
- (Authenticate) response, and each challenge may use a different
- auth-scheme. A user agent MUST choose to use the strongest auth-
- scheme it understands and request credentials from the user based
- upon that challenge.
-
- Note that many browsers will only recognize Basic and will require
- that it be the first auth-scheme presented. Servers should only
- include Basic if it is minimally acceptable.
-
- When the server offers choices of authentication schemes using the
- WWW-Authenticate header, the strength of the resulting authentication
- is only as good as that of the of the weakest of the authentication
- schemes. See section 4.8 below for discussion of particular attack
- scenarios that exploit multiple authentication schemes.
-
-4.7 Online dictionary attacks
-
- If the attacker can eavesdrop, then it can test any overheard
- nonce/response pairs against a list of common words. Such a list is
- usually much smaller than the total number of possible passwords. The
- cost of computing the response for each password on the list is paid
- once for each challenge.
-
- The server can mitigate this attack by not allowing users to select
- passwords that are in a dictionary.
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 23]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-4.8 Man in the Middle
-
- Both Basic and Digest authentication are vulnerable to "man in the
- middle" (MITM) attacks, for example, from a hostile or compromised
- proxy. Clearly, this would present all the problems of eavesdropping.
- But it also offers some additional opportunities to the attacker.
-
- A possible man-in-the-middle attack would be to add a weak
- authentication scheme to the set of choices, hoping that the client
- will use one that exposes the user's credentials (e.g. password). For
- this reason, the client should always use the strongest scheme that
- it understands from the choices offered.
-
- An even better MITM attack would be to remove all offered choices,
- replacing them with a challenge that requests only Basic
- authentication, then uses the cleartext credentials from the Basic
- authentication to authenticate to the origin server using the
- stronger scheme it requested. A particularly insidious way to mount
- such a MITM attack would be to offer a "free" proxy caching service
- to gullible users.
-
- User agents should consider measures such as presenting a visual
- indication at the time of the credentials request of what
- authentication scheme is to be used, or remembering the strongest
- authentication scheme ever requested by a server and produce a
- warning message before using a weaker one. It might also be a good
- idea for the user agent to be configured to demand Digest
- authentication in general, or from specific sites.
-
- Or, a hostile proxy might spoof the client into making a request the
- attacker wanted rather than one the client wanted. Of course, this is
- still much harder than a comparable attack against Basic
- Authentication.
-
-4.9 Chosen plaintext attacks
-
- With Digest authentication, a MITM or a malicious server can
- arbitrarily choose the nonce that the client will use to compute the
- response. This is called a "chosen plaintext" attack. The ability to
- choose the nonce is known to make cryptanalysis much easier [8].
-
- However, no way to analyze the MD5 one-way function used by Digest
- using chosen plaintext is currently known.
-
- The countermeasure against this attack is for clients to be
- configured to require the use of the optional "cnonce" directive;
- this allows the client to vary the input to the hash in a way not
- chosen by the attacker.
-
-
-
-Franks, et al. Standards Track [Page 24]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-4.10 Precomputed dictionary attacks
-
- With Digest authentication, if the attacker can execute a chosen
- plaintext attack, the attacker can precompute the response for many
- common words to a nonce of its choice, and store a dictionary of
- (response, password) pairs. Such precomputation can often be done in
- parallel on many machines. It can then use the chosen plaintext
- attack to acquire a response corresponding to that challenge, and
- just look up the password in the dictionary. Even if most passwords
- are not in the dictionary, some might be. Since the attacker gets to
- pick the challenge, the cost of computing the response for each
- password on the list can be amortized over finding many passwords. A
- dictionary with 100 million password/response pairs would take about
- 3.2 gigabytes of disk storage.
-
- The countermeasure against this attack is to for clients to be
- configured to require the use of the optional "cnonce" directive.
-
-4.11 Batch brute force attacks
-
- With Digest authentication, a MITM can execute a chosen plaintext
- attack, and can gather responses from many users to the same nonce.
- It can then find all the passwords within any subset of password
- space that would generate one of the nonce/response pairs in a single
- pass over that space. It also reduces the time to find the first
- password by a factor equal to the number of nonce/response pairs
- gathered. This search of the password space can often be done in
- parallel on many machines, and even a single machine can search large
- subsets of the password space very quickly -- reports exist of
- searching all passwords with six or fewer letters in a few hours.
-
- The countermeasure against this attack is to for clients to be
- configured to require the use of the optional "cnonce" directive.
-
-4.12 Spoofing by Counterfeit Servers
-
- Basic Authentication is vulnerable to spoofing by counterfeit
- servers. If a user can be led to believe that she is connecting to a
- host containing information protected by a password she knows, when
- in fact she is connecting to a hostile server, then the hostile
- server can request a password, store it away for later use, and feign
- an error. This type of attack is more difficult with Digest
- Authentication -- but the client must know to demand that Digest
- authentication be used, perhaps using some of the techniques
- described above to counter "man-in-the-middle" attacks. Again, the
- user can be helped in detecting this attack by a visual indication of
- the authentication mechanism in use with appropriate guidance in
- interpreting the implications of each scheme.
-
-
-
-Franks, et al. Standards Track [Page 25]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-4.13 Storing passwords
-
- Digest authentication requires that the authenticating agent (usually
- the server) store some data derived from the user's name and password
- in a "password file" associated with a given realm. Normally this
- might contain pairs consisting of username and H(A1), where H(A1) is
- the digested value of the username, realm, and password as described
- above.
-
- The security implications of this are that if this password file is
- compromised, then an attacker gains immediate access to documents on
- the server using this realm. Unlike, say a standard UNIX password
- file, this information need not be decrypted in order to access
- documents in the server realm associated with this file. On the other
- hand, decryption, or more likely a brute force attack, would be
- necessary to obtain the user's password. This is the reason that the
- realm is part of the digested data stored in the password file. It
- means that if one Digest authentication password file is compromised,
- it does not automatically compromise others with the same username
- and password (though it does expose them to brute force attack).
-
- There are two important security consequences of this. First the
- password file must be protected as if it contained unencrypted
- passwords, because for the purpose of accessing documents in its
- realm, it effectively does.
-
- A second consequence of this is that the realm string should be
- unique among all realms which any single user is likely to use. In
- particular a realm string should include the name of the host doing
- the authentication. The inability of the client to authenticate the
- server is a weakness of Digest Authentication.
-
-4.14 Summary
-
- By modern cryptographic standards Digest Authentication is weak. But
- for a large range of purposes it is valuable as a replacement for
- Basic Authentication. It remedies some, but not all, weaknesses of
- Basic Authentication. Its strength may vary depending on the
- implementation. In particular the structure of the nonce (which is
- dependent on the server implementation) may affect the ease of
- mounting a replay attack. A range of server options is appropriate
- since, for example, some implementations may be willing to accept the
- server overhead of one-time nonces or digests to eliminate the
- possibility of replay. Others may satisfied with a nonce like the one
- recommended above restricted to a single IP address and a single ETag
- or with a limited lifetime.
-
-
-
-
-
-Franks, et al. Standards Track [Page 26]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- The bottom line is that *any* compliant implementation will be
- relatively weak by cryptographic standards, but *any* compliant
- implementation will be far superior to Basic Authentication.
-
-5 Sample implementation
-
- The following code implements the calculations of H(A1), H(A2),
- request-digest and response-digest, and a test program which computes
- the values used in the example of section 3.5. It uses the MD5
- implementation from RFC 1321.
-
- File "digcalc.h":
-
-#define HASHLEN 16
-typedef char HASH[HASHLEN];
-#define HASHHEXLEN 32
-typedef char HASHHEX[HASHHEXLEN+1];
-#define IN
-#define OUT
-
-/* calculate H(A1) as per HTTP Digest spec */
-void DigestCalcHA1(
- IN char * pszAlg,
- IN char * pszUserName,
- IN char * pszRealm,
- IN char * pszPassword,
- IN char * pszNonce,
- IN char * pszCNonce,
- OUT HASHHEX SessionKey
- );
-
-/* calculate request-digest/response-digest as per HTTP Digest spec */
-void DigestCalcResponse(
- IN HASHHEX HA1, /* H(A1) */
- IN char * pszNonce, /* nonce from server */
- IN char * pszNonceCount, /* 8 hex digits */
- IN char * pszCNonce, /* client nonce */
- IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
- IN char * pszMethod, /* method from the request */
- IN char * pszDigestUri, /* requested URL */
- IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
- OUT HASHHEX Response /* request-digest or response-digest */
- );
-
-File "digcalc.c":
-
-#include <global.h>
-#include <md5.h>
-
-
-
-Franks, et al. Standards Track [Page 27]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-#include <string.h>
-#include "digcalc.h"
-
-void CvtHex(
- IN HASH Bin,
- OUT HASHHEX Hex
- )
-{
- unsigned short i;
- unsigned char j;
-
- for (i = 0; i < HASHLEN; i++) {
- j = (Bin[i] >> 4) & 0xf;
- if (j <= 9)
- Hex[i*2] = (j + '0');
- else
- Hex[i*2] = (j + 'a' - 10);
- j = Bin[i] & 0xf;
- if (j <= 9)
- Hex[i*2+1] = (j + '0');
- else
- Hex[i*2+1] = (j + 'a' - 10);
- };
- Hex[HASHHEXLEN] = '\0';
-};
-
-/* calculate H(A1) as per spec */
-void DigestCalcHA1(
- IN char * pszAlg,
- IN char * pszUserName,
- IN char * pszRealm,
- IN char * pszPassword,
- IN char * pszNonce,
- IN char * pszCNonce,
- OUT HASHHEX SessionKey
- )
-{
- MD5_CTX Md5Ctx;
- HASH HA1;
-
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, pszUserName, strlen(pszUserName));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszRealm, strlen(pszRealm));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszPassword, strlen(pszPassword));
- MD5Final(HA1, &Md5Ctx);
- if (stricmp(pszAlg, "md5-sess") == 0) {
-
-
-
-Franks, et al. Standards Track [Page 28]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, HA1, HASHLEN);
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
- MD5Final(HA1, &Md5Ctx);
- };
- CvtHex(HA1, SessionKey);
-};
-
-/* calculate request-digest/response-digest as per HTTP Digest spec */
-void DigestCalcResponse(
- IN HASHHEX HA1, /* H(A1) */
- IN char * pszNonce, /* nonce from server */
- IN char * pszNonceCount, /* 8 hex digits */
- IN char * pszCNonce, /* client nonce */
- IN char * pszQop, /* qop-value: "", "auth", "auth-int" */
- IN char * pszMethod, /* method from the request */
- IN char * pszDigestUri, /* requested URL */
- IN HASHHEX HEntity, /* H(entity body) if qop="auth-int" */
- OUT HASHHEX Response /* request-digest or response-digest */
- )
-{
- MD5_CTX Md5Ctx;
- HASH HA2;
- HASH RespHash;
- HASHHEX HA2Hex;
-
- // calculate H(A2)
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, pszMethod, strlen(pszMethod));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszDigestUri, strlen(pszDigestUri));
- if (stricmp(pszQop, "auth-int") == 0) {
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, HEntity, HASHHEXLEN);
- };
- MD5Final(HA2, &Md5Ctx);
- CvtHex(HA2, HA2Hex);
-
- // calculate response
- MD5Init(&Md5Ctx);
- MD5Update(&Md5Ctx, HA1, HASHHEXLEN);
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszNonce, strlen(pszNonce));
- MD5Update(&Md5Ctx, ":", 1);
- if (*pszQop) {
-
-
-
-Franks, et al. Standards Track [Page 29]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- MD5Update(&Md5Ctx, pszNonceCount, strlen(pszNonceCount));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszCNonce, strlen(pszCNonce));
- MD5Update(&Md5Ctx, ":", 1);
- MD5Update(&Md5Ctx, pszQop, strlen(pszQop));
- MD5Update(&Md5Ctx, ":", 1);
- };
- MD5Update(&Md5Ctx, HA2Hex, HASHHEXLEN);
- MD5Final(RespHash, &Md5Ctx);
- CvtHex(RespHash, Response);
-};
-
-File "digtest.c":
-
-
-#include <stdio.h>
-#include "digcalc.h"
-
-void main(int argc, char ** argv) {
-
- char * pszNonce = "dcd98b7102dd2f0e8b11d0f600bfb0c093";
- char * pszCNonce = "0a4f113b";
- char * pszUser = "Mufasa";
- char * pszRealm = "testrealm at host.com";
- char * pszPass = "Circle Of Life";
- char * pszAlg = "md5";
- char szNonceCount[9] = "00000001";
- char * pszMethod = "GET";
- char * pszQop = "auth";
- char * pszURI = "/dir/index.html";
- HASHHEX HA1;
- HASHHEX HA2 = "";
- HASHHEX Response;
-
- DigestCalcHA1(pszAlg, pszUser, pszRealm, pszPass, pszNonce,
-pszCNonce, HA1);
- DigestCalcResponse(HA1, pszNonce, szNonceCount, pszCNonce, pszQop,
- pszMethod, pszURI, HA2, Response);
- printf("Response = %s\n", Response);
-};
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 30]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-6 Acknowledgments
-
- Eric W. Sink, of AbiSource, Inc., was one of the original authors
- before the specification underwent substantial revision.
-
- In addition to the authors, valuable discussion instrumental in
- creating this document has come from Peter J. Churchyard, Ned Freed,
- and David M. Kristol.
-
- Jim Gettys and Larry Masinter edited this document for update.
-
-7 References
-
- [1] Berners-Lee, T., Fielding, R. and H. Frystyk, "Hypertext
- Transfer Protocol -- HTTP/1.0", RFC 1945, May 1996.
-
- [2] Fielding, R., Gettys, J., Mogul, J., Frysyk, H., Masinter, L.,
- Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
- HTTP/1.1", RFC 2616, June 1999.
-
- [3] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April
- 1992.
-
- [4] Freed, N. and N. Borenstein. "Multipurpose Internet Mail
- Extensions (MIME) Part One: Format of Internet Message Bodies",
- RFC 2045, November 1996.
-
- [5] Dierks, T. and C. Allen "The TLS Protocol, Version 1.0", RFC
- 2246, January 1999.
-
- [6] Franks, J., Hallam-Baker, P., Hostetler, J., Leach, P.,
- Luotonen, A., Sink, E. and L. Stewart, "An Extension to HTTP :
- Digest Access Authentication", RFC 2069, January 1997.
-
- [7] Berners Lee, T, Fielding, R. and L. Masinter, "Uniform Resource
- Identifiers (URI): Generic Syntax", RFC 2396, August 1998.
-
- [8] Kaliski, B.,Robshaw, M., "Message Authentication with MD5",
- CryptoBytes, Sping 1995, RSA Inc,
- (http://www.rsa.com/rsalabs/pubs/cryptobytes/spring95/md5.htm)
-
- [9] Klensin, J., Catoe, R. and P. Krumviede, "IMAP/POP AUTHorize
- Extension for Simple Challenge/Response", RFC 2195, September
- 1997.
-
- [10] Morgan, B., Alvestrand, H., Hodges, J., Wahl, M.,
- "Authentication Methods for LDAP", Work in Progress.
-
-
-
-
-Franks, et al. Standards Track [Page 31]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-8 Authors' Addresses
-
- John Franks
- Professor of Mathematics
- Department of Mathematics
- Northwestern University
- Evanston, IL 60208-2730, USA
-
- EMail: john at math.nwu.edu
-
-
- Phillip M. Hallam-Baker
- Principal Consultant
- Verisign Inc.
- 301 Edgewater Place
- Suite 210
- Wakefield MA 01880, USA
-
- EMail: pbaker at verisign.com
-
-
- Jeffery L. Hostetler
- Software Craftsman
- AbiSource, Inc.
- 6 Dunlap Court
- Savoy, IL 61874
-
- EMail: jeff at AbiSource.com
-
-
- Scott D. Lawrence
- Agranat Systems, Inc.
- 5 Clocktower Place, Suite 400
- Maynard, MA 01754, USA
-
- EMail: lawrence at agranat.com
-
-
- Paul J. Leach
- Microsoft Corporation
- 1 Microsoft Way
- Redmond, WA 98052, USA
-
- EMail: paulle at microsoft.com
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 32]
-
-RFC 2617 HTTP Authentication June 1999
-
-
- Ari Luotonen
- Member of Technical Staff
- Netscape Communications Corporation
- 501 East Middlefield Road
- Mountain View, CA 94043, USA
-
-
- Lawrence C. Stewart
- Open Market, Inc.
- 215 First Street
- Cambridge, MA 02142, USA
-
- EMail: stewart at OpenMarket.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 33]
-
-RFC 2617 HTTP Authentication June 1999
-
-
-9. Full Copyright Statement
-
- Copyright (C) The Internet Society (1999). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Franks, et al. Standards Track [Page 34]
-
Copied: CalendarServer/trunk/doc/RFC/rfc3253-DeltaV.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc3253.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3253-DeltaV.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc3253-DeltaV.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,6611 @@
+
+
+
+
+
+
+Network Working Group G. Clemm
+Request for Comments: 3253 Rational Software
+Category: Standards Track J. Amsden
+ T. Ellison
+ IBM
+ C. Kaler
+ Microsoft
+ J. Whitehead
+ U.C. Santa Cruz
+ March 2002
+
+
+ Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ This document specifies a set of methods, headers, and resource types
+ that define the WebDAV (Web Distributed Authoring and Versioning)
+ versioning extensions to the HTTP/1.1 protocol. WebDAV versioning
+ will minimize the complexity of clients that are capable of
+ interoperating with a variety of versioning repository managers, to
+ facilitate widespread deployment of applications capable of utilizing
+ the WebDAV Versioning services. WebDAV versioning includes automatic
+ versioning for versioning-unaware clients, version history
+ management, workspace management, baseline management, activity
+ management, and URL namespace versioning.
+
+Table of Contents
+
+ 1 Introduction.................................................... 6
+ 1.1 Relationship to WebDAV........................................ 7
+ 1.2 Notational Conventions........................................ 8
+ 1.3 Terms......................................................... 8
+ 1.4 Property Values............................................... 11
+ 1.4.1 Initial Property Value..................................... 11
+
+
+
+Clemm, et al. Standards Track [Page 1]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 1.4.2 Protected Property Value................................... 12
+ 1.4.3 Computed Property Value.................................... 12
+ 1.4.4 Boolean Property Value..................................... 12
+ 1.4.5 DAV:href Property Value.................................... 12
+ 1.5 DAV Namespace XML Elements.................................... 12
+ 1.6 Method Preconditions and Postconditions....................... 12
+ 1.6.1 Example - CHECKOUT request................................. 13
+ 1.7 Clarification of COPY Semantics with Overwrite:T.............. 13
+ 1.8 Versioning Methods and Write Locks............................ 14
+ 2 Basic Versioning Features....................................... 14
+ 2.1 Basic Versioning Packages..................................... 14
+ 2.2 Basic Versioning Semantics.................................... 16
+ 2.2.1 Creating a Version-Controlled Resource..................... 16
+ 2.2.2 Modifying a Version-Controlled Resource.................... 17
+ 2.2.3 Reporting.................................................. 19
+ 3 Version-Control Feature......................................... 20
+ 3.1 Additional Resource Properties................................ 20
+ 3.1.1 DAV:comment................................................ 20
+ 3.1.2 DAV:creator-displayname.................................... 20
+ 3.1.3 DAV:supported-method-set (protected)....................... 20
+ 3.1.4 DAV:supported-live-property-set (protected)................ 21
+ 3.1.5 DAV:supported-report-set (protected)....................... 21
+ 3.2 Version-Controlled Resource Properties........................ 21
+ 3.2.1 DAV:checked-in (protected)................................. 21
+ 3.2.2 DAV:auto-version........................................... 22
+ 3.3 Checked-Out Resource Properties............................... 22
+ 3.3.1 DAV:checked-out (protected)................................ 23
+ 3.3.2 DAV:predecessor-set........................................ 23
+ 3.4 Version Properties............................................ 23
+ 3.4.1 DAV:predecessor-set (protected)............................ 23
+ 3.4.2 DAV:successor-set (computed)............................... 23
+ 3.4.3 DAV:checkout-set (computed)................................ 23
+ 3.4.4 DAV:version-name (protected)............................... 24
+ 3.5 VERSION-CONTROL Method........................................ 24
+ 3.5.1 Example - VERSION-CONTROL.................................. 25
+ 3.6 REPORT Method................................................. 25
+ 3.7 DAV:version-tree Report....................................... 26
+ 3.7.1 Example - DAV:version-tree Report.......................... 27
+ 3.8 DAV:expand-property Report.................................... 29
+ 3.8.1 Example - DAV:expand-property.............................. 30
+ 3.9 Additional OPTIONS Semantics.................................. 31
+ 3.10 Additional PUT Semantics..................................... 31
+ 3.11 Additional PROPFIND Semantics................................ 32
+ 3.12 Additional PROPPATCH Semantics............................... 33
+ 3.13 Additional DELETE Semantics.................................. 33
+ 3.14 Additional COPY Semantics.................................... 34
+ 3.15 Additional MOVE Semantics.................................... 34
+ 3.16 Additional UNLOCK Semantics.................................. 35
+
+
+
+Clemm, et al. Standards Track [Page 2]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 4 Checkout-In-Place Feature....................................... 35
+ 4.1 Additional Version Properties................................. 35
+ 4.1.1 DAV:checkout-fork.......................................... 36
+ 4.1.2 DAV:checkin-fork........................................... 36
+ 4.2 Checked-Out Resource Properties............................... 36
+ 4.2.1 DAV:checkout-fork.......................................... 36
+ 4.2.2 DAV:checkin-fork........................................... 37
+ 4.3 CHECKOUT Method............................................... 37
+ 4.3.1 Example - CHECKOUT......................................... 38
+ 4.4 CHECKIN Method................................................ 38
+ 4.4.1 Example - CHECKIN.......................................... 40
+ 4.5 UNCHECKOUT Method............................................. 40
+ 4.5.1 Example - UNCHECKOUT....................................... 41
+ 4.6 Additional OPTIONS Semantics.................................. 42
+ 5 Version-History Feature......................................... 42
+ 5.1 Version History Properties.................................... 42
+ 5.1.1 DAV:version-set (protected)................................ 42
+ 5.1.2 DAV:root-version (computed)................................ 42
+ 5.2 Additional Version-Controlled Resource Properties............. 42
+ 5.2.1 DAV:version-history (computed)............................. 43
+ 5.3 Additional Version Properties................................. 43
+ 5.3.1 DAV:version-history (computed)............................. 43
+ 5.4 DAV:locate-by-history Report.................................. 43
+ 5.4.1 Example - DAV:locate-by-history Report..................... 44
+ 5.5 Additional OPTIONS Semantics.................................. 45
+ 5.6 Additional DELETE Semantics................................... 46
+ 5.7 Additional COPY Semantics..................................... 46
+ 5.8 Additional MOVE Semantics..................................... 46
+ 5.9 Additional VERSION-CONTROL Semantics.......................... 46
+ 5.10 Additional CHECKIN Semantics................................. 47
+ 6 Workspace Feature............................................... 47
+ 6.1 Workspace Properties.......................................... 48
+ 6.1.1 DAV:workspace-checkout-set (computed)...................... 48
+ 6.2 Additional Resource Properties................................ 48
+ 6.2.1 DAV:workspace (protected).................................. 48
+ 6.3 MKWORKSPACE Method............................................ 48
+ 6.3.1 Example - MKWORKSPACE...................................... 49
+ 6.4 Additional OPTIONS Semantics.................................. 49
+ 6.4.1 Example - OPTIONS.......................................... 51
+ 6.5 Additional DELETE Semantics................................... 51
+ 6.6 Additional MOVE Semantics..................................... 52
+ 6.7 Additional VERSION-CONTROL Semantics.......................... 52
+ 6.7.1 Example - VERSION-CONTROL.................................. 53
+ 7 Update Feature.................................................. 53
+ 7.1 UPDATE Method................................................. 53
+ 7.1.1 Example - UPDATE........................................... 55
+ 7.2 Additional OPTIONS Semantics.................................. 55
+ 8 Label Feature................................................... 56
+
+
+
+Clemm, et al. Standards Track [Page 3]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 8.1 Additional Version Properties................................. 56
+ 8.1.1 DAV:label-name-set (protected)............................. 56
+ 8.2 LABEL Method.................................................. 56
+ 8.2.1 Example - Setting a label.................................. 58
+ 8.3 Label Header.................................................. 58
+ 8.4 Additional OPTIONS Semantics.................................. 59
+ 8.5 Additional GET Semantics...................................... 59
+ 8.6 Additional PROPFIND Semantics................................. 59
+ 8.7 Additional COPY Semantics..................................... 60
+ 8.8 Additional CHECKOUT Semantics................................. 60
+ 8.9 Additional UPDATE Semantics................................... 61
+ 9 Working-Resource Feature........................................ 62
+ 9.1 Additional Version Properties................................. 62
+ 9.1.1 DAV:checkout-fork.......................................... 62
+ 9.1.2 DAV:checkin-fork........................................... 63
+ 9.2 Working Resource Properties................................... 63
+ 9.2.1 DAV:auto-update (protected)................................ 63
+ 9.2.2 DAV:checkout-fork.......................................... 63
+ 9.2.3 DAV:checkin-fork........................................... 63
+ 9.3 CHECKOUT Method (applied to a version)........................ 63
+ 9.3.1 Example - CHECKOUT of a version............................ 65
+ 9.4 CHECKIN Method (applied to a working resource)................ 65
+ 9.4.1 Example - CHECKIN of a working resource.................... 66
+ 9.5 Additional OPTIONS Semantics.................................. 67
+ 9.6 Additional COPY Semantics..................................... 67
+ 9.7 Additional MOVE Semantics..................................... 67
+ 10 Advanced Versioning Features.................................. 67
+ 10.1 Advanced Versioning Packages................................. 68
+ 10.2 Advanced Versioning Terms.................................... 68
+ 11 MERGE Feature................................................. 70
+ 11.1 Additional Checked-Out Resource Properties................... 70
+ 11.1.1 DAV:merge-set............................................. 70
+ 11.1.2 DAV:auto-merge-set........................................ 71
+ 11.2 MERGE Method................................................. 71
+ 11.2.1 Example - MERGE........................................... 74
+ 11.3 DAV:merge-preview Report..................................... 75
+ 11.3.1 Example - DAV:merge-preview Report........................ 76
+ 11.4 Additional OPTIONS Semantics................................. 77
+ 11.5 Additional DELETE Semantics.................................. 77
+ 11.6 Additional CHECKIN Semantics................................. 77
+ 12 Baseline Feature.............................................. 77
+ 12.1 Version-Controlled Configuration Properties.................. 78
+ 12.1.1 DAV:baseline-controlled-collection (protected)............ 78
+ 12.2 Checked-Out Configuration Properties......................... 78
+ 12.2.1 DAV:subbaseline-set....................................... 78
+ 12.3 Baseline Properties.......................................... 78
+ 12.3.1 DAV:baseline-collection (protected)....................... 79
+ 12.3.2 DAV:subbaseline-set (protected)........................... 79
+
+
+
+Clemm, et al. Standards Track [Page 4]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 12.4 Additional Resource Properties............................... 79
+ 12.4.1 DAV:version-controlled-configuration (computed)........... 79
+ 12.5 Additional Workspace Properties.............................. 80
+ 12.5.1 DAV:baseline-controlled-collection-set (computed)......... 80
+ 12.6 BASELINE-CONTROL Method...................................... 80
+ 12.6.1 Example - BASELINE-CONTROL................................ 82
+ 12.7 DAV:compare-baseline Report.................................. 84
+ 12.7.1 Example - DAV:compare-baseline Report..................... 85
+ 12.8 Additional OPTIONS Semantics................................. 86
+ 12.9 Additional MKCOL Semantics................................... 86
+ 12.10 Additional COPY Semantics................................... 86
+ 12.11 Additional CHECKOUT Semantics............................... 86
+ 12.12 Additional CHECKIN Semantics................................ 86
+ 12.13 Additional UPDATE Semantics................................. 87
+ 12.14 Additional MERGE Semantics.................................. 89
+ 13 Activity Feature.............................................. 90
+ 13.1 Activity Properties.......................................... 91
+ 13.1.1 DAV:activity-version-set (computed)....................... 91
+ 13.1.2 DAV:activity-checkout-set (computed)...................... 92
+ 13.1.3 DAV:subactivity-set....................................... 92
+ 13.1.4 DAV:current-workspace-set (computed)...................... 92
+ 13.2 Additional Version Properties................................ 92
+ 13.2.1 DAV:activity-set.......................................... 93
+ 13.3 Additional Checked-Out Resource Properties................... 93
+ 13.3.1 DAV:unreserved............................................ 93
+ 13.3.2 DAV:activity-set.......................................... 93
+ 13.4 Additional Workspace Properties.............................. 93
+ 13.4.1 DAV:current-activity-set.................................. 94
+ 13.5 MKACTIVITY Method............................................ 94
+ 13.5.1 Example - MKACTIVITY...................................... 95
+ 13.6 DAV:latest-activity-version Report........................... 95
+ 13.7 Additional OPTIONS Semantics................................. 96
+ 13.8 Additional DELETE Semantics.................................. 96
+ 13.9 Additional MOVE Semantics.................................... 97
+ 13.10 Additional CHECKOUT Semantics............................... 97
+ 13.10.1 Example - CHECKOUT with an activity...................... 98
+ 13.11 Additional CHECKIN Semantics................................ 99
+ 13.12 Additional MERGE Semantics.................................. 99
+ 14 Version-Controlled-Collection Feature.........................100
+ 14.1 Version-Controlled Collection Properties.....................102
+ 14.1.1 DAV:eclipsed-set (computed)...............................102
+ 14.2 Collection Version Properties................................103
+ 14.2.1 DAV:version-controlled-binding-set (protected)............103
+ 14.3 Additional OPTIONS Semantics.................................103
+ 14.4 Additional DELETE Semantics..................................103
+ 14.5 Additional MKCOL Semantics...................................104
+ 14.6 Additional COPY Semantics....................................104
+ 14.7 Additional MOVE Semantics....................................104
+
+
+
+Clemm, et al. Standards Track [Page 5]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ 14.8 Additional VERSION-CONTROL Semantics.........................104
+ 14.9 Additional CHECKOUT Semantics................................105
+ 14.10 Additional CHECKIN Semantics................................105
+ 14.11 Additional UPDATE and MERGE Semantics.......................106
+ 15 Internationalization Considerations...........................106
+ 16 Security Considerations.......................................107
+ 16.1 Auditing and Traceability....................................107
+ 16.2 Increased Need for Access Control............................108
+ 16.3 Security Through Obscurity...................................108
+ 16.4 Denial of Service............................................108
+ 17 IANA Considerations...........................................109
+ 18 Intellectual Property.........................................109
+ 19 Acknowledgements..............................................109
+ 20 References....................................................110
+ Appendix A - Resource Classification..............................111
+ A.1 DeltaV-Compliant Unmapped URL.................................111
+ A.2 DeltaV-Compliant Resource.....................................111
+ A.3 DeltaV-Compliant Collection...................................112
+ A.4 Versionable Resource..........................................112
+ A.5 Version-Controlled Resource...................................112
+ A.6 Version.......................................................113
+ A.7 Checked-In Version-Controlled Resource........................113
+ A.8 Checked-Out Resource..........................................113
+ A.9 Checked-Out Version-Controlled Resource.......................114
+ A.10 Working Resource.............................................114
+ A.11 Version History..............................................114
+ A.12 Workspace....................................................115
+ A.13 Activity.....................................................115
+ A.14 Version-Controlled Collection................................115
+ A.15 Collection Version...........................................115
+ A.16 Version-Controlled Configuration.............................116
+ A.17 Baseline.....................................................116
+ A.18 Checked-Out Version-Controlled Configuration.................116
+ Authors' Addresses................................................117
+ Full Copyright Statement..........................................118
+
+1 Introduction
+
+ This document specifies a set of methods, headers, and properties
+ that define the WebDAV (Web Distributed Authoring and Versioning)
+ versioning extensions to the HTTP/1.1 protocol. Versioning is
+ concerned with tracking and accessing the history of important states
+ of a web resource, such as a standalone web page. The benefits of
+ versioning in the context of the worldwide web include:
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 6]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ - A resource has an explicit history and a persistent identity
+ across the various states it has had during the course of that
+ history. It allows browsing through past and alternative versions
+ of a resource. Frequently the modification and authorship history
+ of a resource is critical information in itself.
+
+ - Resource states (versions) are given stable names that can support
+ externally stored links for annotation and link server support.
+ Both annotation and link servers frequently need to store stable
+ references to portions of resources that are not under their
+ direct control. By providing stable states of resources, version
+ control systems allow not only stable pointers into those
+ resources, but also well defined methods to determine the
+ relationships of those states of a resource.
+
+ WebDAV Versioning defines both basic and advanced versioning
+ functionality.
+
+ Basic versioning allows users to:
+
+ - Put a resource under version control
+ - Determine whether a resource is under version control
+ - Determine whether a resource update will automatically be captured
+ as a new version
+ - Create and access distinct versions of a resource
+
+ Advanced versioning provides additional functionality for parallel
+ development and configuration management of sets of web resources.
+
+ This document will first define the properties and method semantics
+ for the basic versioning features, and then define the additional
+ properties and method semantics for the advanced versioning features.
+ An implementer that is only interested in basic versioning should
+ skip the advanced versioning sections (Section 10 to Section 14).
+
+1.1 Relationship to WebDAV
+
+ To maximize interoperability and the use of existing protocol
+ functionality, versioning support is designed as extensions to the
+ WebDAV protocol [RFC2518], which itself is an extension to the HTTP
+ protocol [RFC2616]. All method marshalling and postconditions
+ defined by RFC 2518 and RFC 2616 continue to hold, to ensure that
+ versioning unaware clients can interoperate successfully with
+ versioning servers. Although the versioning extensions are designed
+ to be orthogonal to most aspects of the WebDAV and HTTP protocols, a
+ clarification to RFC 2518 is required for effective interoperable
+ versioning. This clarification is described in Section 1.7.
+
+
+
+
+Clemm, et al. Standards Track [Page 7]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+1.2 Notational Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in RFC 2119.
+
+ The term "protected" is placed in parentheses following the
+ definition of a protected property (see Section 1.4.2).
+
+ The term "computed" is placed in parentheses following the definition
+ of a computed property (see Section 1.4.3).
+
+ When an XML element type in the "DAV:" namespace is referenced in
+ this document outside of the context of an XML fragment, the string
+ "DAV:" will be prefixed to the element type.
+
+ When a method is defined in this document, a list of preconditions
+ and postconditions will be defined for that method. If the semantics
+ of an existing method is being extended, a list of additional
+ preconditions and postconditions will be defined. A precondition or
+ postcondition is prefixed by a parenthesized XML element type that
+ identifies that precondition or postcondition (see Section 1.6).
+
+1.3 Terms
+
+ This document uses the terms defined in RFC 2616, in RFC 2518, and in
+ this section. Section 2.2 defines the semantic versioning model
+ underlying this terminology.
+
+ Version Control, Checked-In, Checked-Out
+
+ "Version control" is a set of constraints on how a resource can be
+ updated. A resource under version control is either in a
+ "checked-in" or "checked-out" state, and the version control
+ constraints apply only while the resource is in the checked-in
+ state.
+
+ Versionable Resource
+
+ A "versionable resource" is a resource that can be put under
+ version control.
+
+ Version-Controlled Resource
+
+ When a versionable resource is put under version control, it
+ becomes a "version-controlled resource". A version-controlled
+ resource can be "checked out" to allow modification of its content
+ or dead properties by standard HTTP and WebDAV methods.
+
+
+
+Clemm, et al. Standards Track [Page 8]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Checked-Out Resource
+
+ A "checked-out resource" is a resource under version control that
+ is in the checked-out state.
+
+ Version Resource
+
+ A "version resource", or simply "version", is a resource that
+ contains a copy of a particular state (content and dead
+ properties) of a version-controlled resource. A version is
+ created by "checking in" a checked-out resource. The server
+ allocates a distinct new URL for each new version, and this URL
+ will never be used to identify any resource other than that
+ version. The content and dead properties of a version never
+ change.
+
+ Version History Resource
+
+ A "version history resource", or simply "version history", is a
+ resource that contains all the versions of a particular version-
+ controlled resource.
+
+ Version Name
+
+ A "version name" is a string chosen by the server to distinguish
+ one version of a version history from the other versions of that
+ version history. Versions from different version histories may
+ have the same version name.
+
+ Predecessor, Successor, Ancestor, Descendant
+
+ When a version-controlled resource is checked out and then
+ subsequently checked in, the version that was checked out becomes
+ a "predecessor" of the version created by the checkin. A client
+ can specify multiple predecessors for a new version if the new
+ version is logically a merge of those predecessors. When a
+ version is connected to another version by traversing one or more
+ predecessor relations, it is called an "ancestor" of that version.
+ The inverse of the predecessor and ancestor relations are the
+ "successor" and "descendant" relations. Therefore, if X is a
+ predecessor of Y, then Y is a successor of X, and if X is an
+ ancestor of Y, then Y is a descendant of X.
+
+ Root Version Resource
+
+ The "root version resource", or simply "root version", is the
+ version in a version history that is an ancestor of every other
+ version in that version history.
+
+
+
+Clemm, et al. Standards Track [Page 9]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Workspace Resource
+
+ A "workspace resource", or simply "workspace", is a collection
+ that contains at most one version-controlled resource for a given
+ version history (see Section 6).
+
+ Working Resource
+
+ A "working resource" is a checked-out resource created by the
+ server at a server-defined URL when a version (instead of a
+ version-controlled resource) is checked out. Unlike a checked-out
+ version-controlled resource, a working resource is deleted when it
+ is checked in.
+
+ Fork, Merge
+
+ When a second successor is added to a version, this creates a
+ "fork" in the version history. When a version is created with
+ multiple predecessors, this creates a "merge" in the version
+ history. A server may restrict the version history to be linear
+ (with no forks or merges), but an interoperable versioning client
+ should be prepared to deal with both forks and merges in the
+ version history.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 10]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The following diagram illustrates several of the previous
+ definitions. Each box represents a version and each line between two
+ boxes represents a predecessor/successor relationship. For example,
+ it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is an
+ ancestor of V4, and V7 is a descendant of V4. It also shows that
+ there is a fork at version V2 and a merge at version V7.
+
+ History of foo.html
+
+ +---+
+ Root Version -------> | | V1
+ +---+ ^
+ | |
+ | |
+ +---+ |
+ Version Name ----> V2 | | | Ancestor
+ +---+ |
+ / \ |
+ / \ |
+ +---+ +---+
+ | | V3 | | V4
+ ^ +---+ +---+
+ | | | |
+ Predecessor | | | |
+ +---+ +---+ |
+ | | V5 | | V6 | Descendant
+ +---+ +---+ |
+ Successor | \ / |
+ | \ / |
+ v +---+ v
+ | | V7
+ +---+
+
+ Label
+
+ A "label" is a name that can be used to select a version from a
+ version history. A label can be assigned by either a client or
+ the server. The same label can be used in different version
+ histories.
+
+1.4 Property Values
+
+1.4.1 Initial Property Value
+
+ Unless an initial value of a property of a given type is defined by
+ this document, the initial value of a property of that type is
+ implementation dependent.
+
+
+
+
+Clemm, et al. Standards Track [Page 11]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+1.4.2 Protected Property Value
+
+ When a property of a specific kind of resource is "protected", the
+ property value cannot be updated on that kind of resource except by a
+ method explicitly defined as updating that specific property. In
+ particular, a protected property cannot be updated with a PROPPATCH
+ request. Note that a given property can be protected on one kind of
+ resource, but not protected on another kind of resource.
+
+1.4.3 Computed Property Value
+
+ When a property is "computed", its value is defined in terms of a
+ computation based on the content and other properties of that
+ resource, or even of some other resource. When the semantics of a
+ method is defined in this document, the effect of that method on
+ non-computed properties will be specified; the effect of that method
+ on computed properties will not be specified, but can be inferred
+ from the computation defined for those properties. A computed
+ property is always a protected property.
+
+1.4.4 Boolean Property Value
+
+ Some properties take a Boolean value of either "false" or "true".
+
+1.4.5 DAV:href Property Value
+
+ The DAV:href XML element is defined in RFC 2518, Section 12.3.
+
+1.5 DAV Namespace XML Elements in Request and Response Bodies
+
+ Although WebDAV request and response bodies can be extended by
+ arbitrary XML elements, which can be ignored by the message
+ recipient, an XML element in the DAV namespace MUST NOT be used in
+ the request or response body of a versioning method unless that XML
+ element is explicitly defined in an IETF RFC.
+
+1.6 Method Preconditions and Postconditions
+
+ A "precondition" of a method describes the state of the server that
+ must be true for that method to be performed. A "postcondition" of a
+ method describes the state of the server that must be true after that
+ method has been completed. If a method precondition or postcondition
+ for a request is not satisfied, the response status of the request
+ MUST be either 403 (Forbidden) if the request should not be repeated
+ because it will always fail, or 409 (Conflict) if it is expected that
+ the user might be able to resolve the conflict and resubmit the
+ request.
+
+
+
+
+Clemm, et al. Standards Track [Page 12]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In order to allow better client handling of 403 and 409 responses, a
+ distinct XML element type is associated with each method precondition
+ and postcondition of a request. When a particular precondition is
+ not satisfied or a particular postcondition cannot be achieved, the
+ appropriate XML element MUST be returned as the child of a top-level
+ DAV:error element in the response body, unless otherwise negotiated
+ by the request. In a 207 Multi-Status response, the DAV:error
+ element would appear in the appropriate DAV:responsedescription
+ element.
+
+1.6.1 Example - CHECKOUT request with DAV:must-be-checked-in response
+
+ >>REQUEST
+
+ CHECKOUT /foo.html HTTP/1.1
+ Host: www.webdav.org
+
+ >>RESPONSE
+
+ HTTP/1.1 409 Conflict
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:must-be-checked-in/>
+ </D:error>
+
+ In this example, the request to CHECKOUT /foo.html fails because
+ /foo.html is not checked in.
+
+1.7 Clarification of COPY Semantics with Overwrite:T
+
+ RFC 2518, Section 8.8.4 states:
+
+ "If a resource exists at the destination and the Overwrite header is
+ "T" then prior to performing the copy the server MUST perform a
+ DELETE with "Depth: infinity" on the destination resource."
+
+ The purpose of this sentence is to ensure that following a COPY, all
+ destination resources have the same content and dead properties as
+ the corresponding resources identified by the request-URL (where a
+ resource with a given name relative to the Destination URL
+ "corresponds" to a resource with the same name relative to the
+ request-URL). If at the time of the request, there already is a
+ resource at the destination that has the same resource type as the
+ corresponding resource at the request-URL, that resource MUST NOT be
+ deleted, but MUST be updated to have the content and dead properties
+
+
+
+Clemm, et al. Standards Track [Page 13]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ of its corresponding member. If a client wishes all resources at the
+ destination to be deleted prior to the COPY, it MUST explicitly issue
+ a DELETE request.
+
+ The difference between updating a resource and replacing a resource
+ with a new resource is especially important when resource history is
+ being maintained (the former adds to an existing history, while the
+ latter creates a new history). In addition, locking and access
+ control constraints might allow you to update a resource, but not
+ allow you to delete it and create a new one in its place.
+
+ Note that this clarification does not apply to a MOVE request. A
+ MOVE request with Overwrite:T MUST perform the DELETE with
+ "Depth:infinity" on the destination resource prior to performing the
+ MOVE.
+
+1.8 Versioning Methods and Write Locks
+
+ If a write-locked resource has a non-computed property defined by
+ this document, the property value MUST NOT be changed by a request
+ unless the appropriate lock token is included in the request. Since
+ every method introduced in this document other than REPORT modifies
+ at least one property defined by this document, every versioning
+ method other than REPORT is affected by a write lock. In particular,
+ the method MUST fail with a 423 (Locked) status if the resource is
+ write-locked and the appropriate token is not specified in an If
+ request header.
+
+2 Basic Versioning Features
+
+ Each basic versioning feature defines extensions to existing HTTP and
+ WebDAV methods, as well as new resource types, live properties, and
+ methods.
+
+2.1 Basic Versioning Packages
+
+ A server MAY support any combination of versioning features.
+ However, in order to minimize the complexity of a WebDAV basic
+ versioning client, a WebDAV basic versioning server SHOULD support
+ one of the following three "packages" (feature sets):
+
+ - Core-Versioning Package: version-control
+ - Basic-Server-Workspace Package: version-control, workspace,
+ version-history, checkout
+ - Basic-Client-Workspace Package: version-control, working-
+ resource, update, label
+
+
+
+
+
+Clemm, et al. Standards Track [Page 14]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The core-versioning package supports linear versioning by both
+ versioning-aware and versioning-unaware clients. A versioning-aware
+ client can use reports and properties to access previous versions of
+ a version-controlled resource.
+
+ The basic workspace packages support parallel development of
+ version-controlled resources. Each client has its own configuration
+ of the shared version-controlled resources, and can make changes to
+ its configuration without disturbing that of another client.
+
+ In the basic-server-workspace package, all persistent state is
+ maintained on the server. Each client has its own workspace resource
+ allocated on the server, where each workspace identifies a
+ configuration of the shared version-controlled resources. Each
+ client makes changes to its workspace, and can transfer changes when
+ appropriate from one workspace to another. The server workspace
+ package is appropriate for clients with no local persistent state, or
+ for clients that wish to expose their working configurations to other
+ clients.
+
+ In the basic-client-workspace package, each client maintains in local
+ persistent storage the state for its configuration of the shared
+ version-controlled resources. When a client is ready to make its
+ changes visible to other clients, it allocates a set of "working
+ resources" on the server, updates the content and dead properties of
+ these working resources, and then uses the set of working resources
+ to update the version-controlled resources. The working resources
+ are used, instead of directly updating the version-controlled
+ resources, so that sets of consistent updates can be prepared in
+ parallel by multiple clients. Also, a working resource allows a
+ client to prepare a single update that requires multiple server
+ requests (e.g. updating both the content and dead properties of a
+ resource requires both a PUT and a PROPPATCH). The client workspace
+ package simplifies the server implementation by requiring each client
+ to maintain its own namespace, but this requires that the clients
+ have local persistent state, and does not allow clients to expose
+ their working configurations to other clients.
+
+ A server that supports both basic workspace packages will
+ interoperate with all basic versioning clients.
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 15]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+2.2 Basic Versioning Semantics
+
+2.2.1 Creating a Version-Controlled Resource
+
+ In order to track the history of the content and dead properties of a
+ versionable resource, a user can put the resource under version
+ control with a VERSION-CONTROL request. A VERSION-CONTROL request
+ performs three distinct operations:
+
+ 1) It creates a new "version history resource". In basic versioning,
+ a version history resource is not assigned a URL, and hence is not
+ visible in the http scheme URL space. However, when the version-
+ history feature (see Section 5) is supported, this changes, and
+ each version history resource is assigned a new distinct and
+ unique server-defined URL.
+
+ 2) It creates a new "version resource" and adds it to the new version
+ history resource. The body and dead properties of the new version
+ resource are a copy of those of the versionable resource.
+
+ The server assigns the new version resource a new distinct and
+ unique URL.
+
+ 3) It converts the versionable resource into a "version-controlled
+ resource". The version-controlled resource continues to be
+ identified by the same URL that identified it as a versionable
+ resource. As part of this conversion, it adds a DAV:checked-in
+ property, whose value contains the URL of the new version
+ resource.
+
+ Note that a versionable resource and a version-controlled resource
+ are not new types of resources (i.e. they introduce no new
+ DAV:resourcetype), but rather they are any type of resource that
+ supports the methods and live properties defined for them in this
+ document, in addition to all the methods and live properties implied
+ by their DAV:resourcetype. For example, a collection (whose
+ DAV:resourcetype is DAV:collection) is a versionable resource if it
+ supports the VERSION-CONTROL method, and is a version-controlled
+ resource if it supports the version-controlled resource methods and
+ live properties.
+
+ In the following example, foo.html is a versionable resource that is
+ put under version control. After the VERSION-CONTROL request
+ succeeds, there are two additional resources: a new version history
+ resource and a new version resource in that version history. The
+ versionable resource is converted into a version-controlled resource,
+ whose DAV:checked-in property identifies the new version resource.
+
+
+
+
+Clemm, et al. Standards Track [Page 16]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The content and dead properties of a resource are represented by the
+ symbol appearing inside the box for that resource (e.g., "S1" in the
+ following example).
+
+ ===VERSION-CONTROL==>
+
+ | +----+ version
+ | version- | | history
+ versionable | controlled +----+ resource
+ resource | resource |
+ /foo.html | /foo.html |
+ | v
+ +----+ | +----+ checked-in +----+ version
+ | S1 | | | S1 |----------->| S1 | resource
+ +----+ | +----+ +----+ /his/73/ver/1
+
+ Thus, whereas before the VERSION-CONTROL request there was only one,
+ non-version-controlled resource, after VERSION-CONTROL there are
+ three separate, distinct resources, each containing its own state and
+ properties: the version-controlled resource, the version resource,
+ and the version history resource. Since the version-controlled
+ resource and the version resource are separate, distinct resources,
+ when a method is applied to a version-controlled resource, it is only
+ applied to that version-controlled resource, and is not applied to
+ the version resource that is currently identified by the
+ DAV:checked-in property of that version-controlled resource.
+ Although the content and dead properties of a checked-in version-
+ controlled resource are required to be the same as those of its
+ current DAV:checked-in version, its live properties may differ. An
+ implementation may optimize storage by retrieving the content and
+ dead properties of a checked-in version-controlled resource from its
+ current DAV:checked-in version rather than storing them in the
+ version-controlled resource, but this is just an implementation
+ optimization.
+
+ Normally, a resource is placed under version control with an explicit
+ VERSION-CONTROL request. A server MAY automatically place every new
+ versionable resource under version control. In this case, the
+ resulting state on the server MUST be the same as if the client had
+ explicitly applied a VERSION-CONTROL request to the versionable
+ resource.
+
+2.2.2 Modifying a Version-Controlled Resource
+
+ In order to use methods like PUT and PROPPATCH to directly modify the
+ content or dead properties of a version-controlled resource, the
+ version-controlled resource must first be checked out. When the
+ checked-out resource is checked in, a new version is created in the
+
+
+
+Clemm, et al. Standards Track [Page 17]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ version history of that version-controlled resource. The version
+ that was checked out is remembered as the predecessor of the new
+ version.
+
+ The DAV:auto-version property (see Sections 3.2.2) of a checked-in
+ version-controlled resource determines how it responds to a method
+ that attempts to modify its content or dead properties. Possible
+ responses include:
+
+ - Fail the request. The resource requires an explicit CHECKOUT
+ request for it to be modified (see Sections 4 and 9.2.1).
+
+ - Automatically checkout the resource, perform the modification, and
+ automatically checkin the resource. This ensures that every state
+ of the resource is tracked by the server, but can result in an
+ excessive number of versions being created.
+
+ - Automatically checkout the resource, perform the modification, and
+ then if the resource is not write-locked, automatically checkin
+ the resource. If the resource is write-locked, it remains
+ checked-out until the write-lock is removed (either explicitly
+ through a subsequent UNLOCK request or implicitly through a time-
+ out of the write-lock). This helps a locking client avoid the
+ proliferation of versions, while still allowing a non-locking
+ client to update the resource.
+
+ - Automatically checkout the resource, perform the modification, and
+ then leave the resource checked out. If the resource is write-
+ locked, it will be automatically checked in when the write-lock is
+ removed, but an explicit CHECKIN operation (see Section 4.4) is
+ required for a non-write-locked resource. This minimizes the
+ number of new versions that will be created by a versioning
+ unaware client, but only a versioning aware client can create new
+ versions of a non-write-locked resource.
+
+ - Fail the request unless the resource is write-locked. If it is
+ write-locked, automatically checkout the resource and perform the
+ modification. The resource is automatically checked in when the
+ write-lock is removed. This minimizes the number of new versions
+ that will be created by a versioning unaware client, but never
+ automatically checks out a resource that will not subsequently be
+ automatically checked in.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 18]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The following diagram illustrates the effect of the checkout/checkin
+ process on a version-controlled resource and its version history.
+ The symbol inside a box (S1, S2, S3) represents the current content
+ and dead properties of the resource represented by that box. The
+ symbol next to a box (V1, V2, V3) represents the URL for that
+ resource.
+
+ ===checkout==> ===PUT==> ===checkin==>
+
+
+ /foo.html (version-controlled resource)
+
+ +----+ | +----+ | +----+ | +----+
+ | S2 | | | S2 | | | S3 | | | S3 |
+ +----+ | +----+ | +----+ | +----+
+ Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3
+
+
+ /his/73 (version history for /foo.html)
+
+ +----+ | +----+ | +----+ | +----+
+ | S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
+ +----+ | +----+ | +----+ | +----+
+ | | | | | | |
+ | | | | | | |
+ +----+ | +----+ | +----+ | +----+
+ | S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
+ +----+ | +----+ | +----+ | +----+
+ | | | |
+ | | | |
+ | | | +----+
+ | | | | S3 | V3
+ | | | +----+
+
+ Note that a version captures only a defined subset of the state of a
+ resource. In particular, a version of a basic resource captures its
+ content and dead properties, but not its live properties.
+
+2.2.3 Reporting
+
+ Some versioning information about a resource requires that parameters
+ be specified along with that request for information. Included in
+ basic versioning is the required support for an extensible reporting
+ mechanism, which includes a REPORT method as well as a live property
+ for determining what reports are supported by a particular resource.
+ The REPORT method is required by versioning, but it can be used in
+ non-versioning WebDAV extensions.
+
+
+
+
+Clemm, et al. Standards Track [Page 19]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ To allow a client to query the properties of all versions in the
+ version history of a specified version-controlled resource, basic
+ versioning provides the DAV:version-tree report (see Section 3.7). A
+ more powerful version history reporting mechanism is provided by
+ applying the DAV:expand-property report (see Section 3.8) to a
+ version history resource (see Section 5).
+
+3 Version-Control Feature
+
+ The version-control feature provides support for putting a resource
+ under version control, creating an associated version-controlled
+ resource and version history resource as described in Section 2.2.1.
+ A server indicates that it supports the version-control feature by
+ including the string "version-control" as a field in the DAV header
+ in the response to an OPTIONS request. The version-control feature
+ MUST be supported if any other versioning feature is supported.
+
+3.1 Additional Resource Properties
+
+ The version-control feature introduces the following REQUIRED
+ properties for any WebDAV resource.
+
+3.1.1 DAV:comment
+
+ This property is used to track a brief comment about a resource that
+ is suitable for presentation to a user. The DAV:comment of a version
+ can be used to indicate why that version was created.
+
+ <!ELEMENT comment (#PCDATA)>
+ PCDATA value: string
+
+3.1.2 DAV:creator-displayname
+
+ This property contains a description of the creator of the resource
+ that is suitable for presentation to a user. The DAV:creator-
+ displayname of a version can be used to indicate who created that
+ version.
+
+ <!ELEMENT creator-displayname (#PCDATA)>
+ PCDATA value: string
+
+3.1.3 DAV:supported-method-set (protected)
+
+ This property identifies the methods that are supported by the
+ resource. A method is supported by a resource if there is some state
+ of that resource for which an application of that method will
+
+
+
+
+
+Clemm, et al. Standards Track [Page 20]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ successfully satisfy all postconditions of that method, including any
+ additional postconditions added by the features supported by that
+ resource.
+
+ <!ELEMENT supported-method-set (supported-method*)>
+ <!ELEMENT supported-method ANY>
+ <!ATTLIST supported-method name NMTOKEN #REQUIRED>
+ name value: a method name
+
+3.1.4 DAV:supported-live-property-set (protected)
+
+ This property identifies the live properties that are supported by
+ the resource. A live property is supported by a resource if that
+ property has the semantics defined for that property. The value of
+ this property MUST identify all live properties defined by this
+ document that are supported by the resource, and SHOULD identify all
+ live properties that are supported by the resource.
+
+ <!ELEMENT supported-live-property-set (supported-live-property*)>
+ <!ELEMENT supported-live-property name>
+ <!ELEMENT prop ANY>
+ ANY value: a property element type
+
+3.1.5 DAV:supported-report-set (protected)
+
+ This property identifies the reports that are supported by the
+ resource.
+
+ <!ELEMENT supported-report-set (supported-report*)>
+ <!ELEMENT supported-report report>
+ <!ELEMENT report ANY>
+ ANY value: a report element type
+
+3.2 Version-Controlled Resource Properties
+
+ The version-control feature introduces the following REQUIRED
+ properties for a version-controlled resource.
+
+3.2.1 DAV:checked-in (protected)
+
+ This property appears on a checked-in version-controlled resource,
+ and identifies a version that has the same content and dead
+ properties as the version-controlled resource. This property is
+ removed when the resource is checked out, and then added back
+ (identifying a new version) when the resource is checked back in.
+
+ <!ELEMENT checked-in (href)>
+
+
+
+
+Clemm, et al. Standards Track [Page 21]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.2.2 DAV:auto-version
+
+ If the DAV:auto-version value is DAV:checkout-checkin, when a
+ modification request (such as PUT/PROPPATCH) is applied to a
+ checked-in version-controlled resource, the request is automatically
+ preceded by a checkout and followed by a checkin operation.
+
+ If the DAV:auto-version value is DAV:checkout-unlocked-checkin, when
+ a modification request is applied to a checked-in version-controlled
+ resource, the request is automatically preceded by a checkout
+ operation. If the resource is not write-locked, the request is
+ automatically followed by a checkin operation.
+
+ If the DAV:auto-version value is DAV:checkout, when a modification
+ request is applied to a checked-in version-controlled resource, the
+ request is automatically preceded by a checkout operation.
+
+ If the DAV:auto-version value is DAV:locked-checkout, when a
+ modification request is applied to a write-locked checked-in
+ version-controlled resource, the request is automatically preceded by
+ a checkout operation.
+
+ If an update to a write-locked checked-in resource is automatically
+ preceded by a checkout of that resource, the checkout is associated
+ with the write lock. When this write lock is removed (e.g. from an
+ UNLOCK or a lock timeout), if the resource has not yet been checked
+ in, the removal of the write lock is automatically preceded by a
+ checkin operation.
+
+ A server MAY refuse to allow the value of the DAV:auto-version
+ property to be modified, or MAY only support values from a subset of
+ the valid values.
+
+ <!ELEMENT auto-version (checkout-checkin | checkout-unlocked-checkin
+ | checkout | locked-checkout)? >
+ <!ELEMENT checkout-checkin EMPTY>
+ <!ELEMENT checkout-unlocked-checkin EMPTY>
+ <!ELEMENT checkout EMPTY>
+ <!ELEMENT locked-checkout EMPTY>
+
+3.3 Checked-Out Resource Properties
+
+ The version-control feature introduces the following REQUIRED
+ properties for a checked-out resource.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 22]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.3.1 DAV:checked-out (protected)
+
+ This property identifies the version that was identified by the
+ DAV:checked-in property at the time the resource was checked out.
+ This property is removed when the resource is checked in.
+
+ <!ELEMENT checked-out (href)>
+
+3.3.2 DAV:predecessor-set
+
+ This property determines the DAV:predecessor-set property of the
+ version that results from checking in this resource.
+
+ A server MAY reject attempts to modify the DAV:predecessor-set of a
+ version-controlled resource.
+
+ <!ELEMENT predecessor-set (href+)>
+
+3.4 Version Properties
+
+ The version-control feature introduces the following REQUIRED
+ properties for a version.
+
+3.4.1 DAV:predecessor-set (protected)
+
+ This property identifies each predecessor of this version. Except
+ for the root version, which has no predecessors, each version has at
+ least one predecessor.
+
+ <!ELEMENT predecessor-set (href*)>
+
+3.4.2 DAV:successor-set (computed)
+
+ This property identifies each version whose DAV:predecessor-set
+ identifies this version.
+
+ <!ELEMENT successor-set (href*)>
+
+3.4.3 DAV:checkout-set (computed)
+
+ This property identifies each checked-out resource whose
+ DAV:checked-out property identifies this version.
+
+ <!ELEMENT checkout-set (href*)>
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 23]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.4.4 DAV:version-name (protected)
+
+ This property contains a server-defined string that is different for
+ each version in a given version history. This string is intended for
+ display for a user, unlike the URL of a version, which is normally
+ only used by a client and not displayed for a user.
+
+ <!ELEMENT version-name (#PCDATA)>
+ PCDATA value: string
+
+3.5 VERSION-CONTROL Method
+
+ A VERSION-CONTROL request can be used to create a version-controlled
+ resource at the request-URL. It can be applied to a versionable
+ resource or to a version-controlled resource.
+
+ If the request-URL identifies a versionable resource, a new version
+ history resource is created, a new version is created whose content
+ and dead properties are copied from the versionable resource, and the
+ resource is given a DAV:checked-in property that is initialized to
+ identify this new version.
+
+ If the request-URL identifies a version-controlled resource, the
+ resource just remains under version-control. This allows a client to
+ be unaware of whether or not a server automatically puts a resource
+ under version control when it is created.
+
+ If a VERSION-CONTROL request fails, the server state preceding the
+ request MUST be restored.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:version-control
+ XML element.
+
+ <!ELEMENT version-control ANY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:version-control-response XML element. Note that this
+ document does not define any elements for the VERSION-CONTROL
+ response body, but the DAV:version-control-response element is
+ defined to ensure interoperability between future extensions that
+ do define elements for the VERSION-CONTROL response body.
+
+ <!ELEMENT version-control-response ANY>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 24]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Postconditions:
+
+ (DAV:put-under-version-control): If the request-URL identified a
+ versionable resource at the time of the request, the request MUST
+ have created a new version history and MUST have created a new
+ version resource in that version history. The resource MUST have
+ a DAV:checked-in property that identifies the new version. The
+ content, dead properties, and DAV:resourcetype of the new version
+ MUST be the same as those of the resource. Note that an
+ implementation can choose to locate the version history and
+ version resources anywhere that it wishes. In particular, it
+ could locate them on the same host and server as the version-
+ controlled resource, on a different virtual host maintained by the
+ same server, on the same host maintained by a different server, or
+ on a different host maintained by a different server.
+
+ (DAV:must-not-change-existing-checked-in-out): If the request-URL
+ identified a resource already under version control at the time of
+ the request, the request MUST NOT change the DAV:checked-in or
+ DAV:checked-out property of that version-controlled resource.
+
+3.5.1 Example - VERSION-CONTROL
+
+ >>REQUEST
+
+ VERSION-CONTROL /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+
+ In this example, /foo.html is put under version control. A new
+ version history is created for it, and a new version is created that
+ has a copy of the content and dead properties of /foo.html. The
+ DAV:checked-in property of /foo.html identifies this new version.
+
+3.6 REPORT Method
+
+ A REPORT request is an extensible mechanism for obtaining information
+ about a resource. Unlike a resource property, which has a single
+ value, the value of a report can depend on additional information
+ specified in the REPORT request body and in the REPORT request
+ headers.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 25]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Marshalling:
+
+ The body of a REPORT request specifies which report is being
+ requested, as well as any additional information that will be used
+ to customize the report.
+
+ The request MAY include a Depth header. If no Depth header is
+ included, Depth:0 is assumed.
+
+ The response body for a successful request MUST contain the
+ requested report.
+
+ If a Depth request header is included, the response MUST be a 207
+ Multi-Status. The request MUST be applied separately to the
+ collection itself and to all members of the collection that
+ satisfy the Depth value. The DAV:prop element of a DAV:response
+ for a given resource MUST contain the requested report for that
+ resource.
+
+ Preconditions:
+
+ (DAV:supported-report): The specified report MUST be supported by
+ the resource identified by the request-URL.
+
+ Postconditions:
+
+ (DAV:no-modification): The REPORT method MUST NOT have changed the
+ content or dead properties of any resource.
+
+3.7 DAV:version-tree Report
+
+ The DAV:version-tree report describes the requested properties of all
+ the versions in the version history of a version. If the report is
+ requested for a version-controlled resource, it is redirected to its
+ DAV:checked-in or DAV:checked-out version.
+
+ The DAV:version-tree report MUST be supported by all version
+ resources and all version-controlled resources.
+
+ Marshalling:
+
+ The request body MUST be a DAV:version-tree XML element.
+
+ <!ELEMENT version-tree ANY>
+ ANY value: a sequence of zero or more elements, with at most one
+ DAV:prop element.
+ prop: see RFC 2518, Section 12.11
+
+
+
+
+Clemm, et al. Standards Track [Page 26]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response body for a successful DAV:version-tree REPORT request
+ MUST contain a DAV:response element for each version in the
+ version history of the version identified by the request-URL.
+
+3.7.1 Example - DAV:version-tree Report
+
+ The version history drawn below would produce the following version
+ tree report.
+
+ foo.html History
+
+ +---+
+ | | V1
+ +---+
+ / \
+ / \
+ +---+ +---+
+ | | V2 | | V2.1.1
+ +---+ +---+
+
+ >>REQUEST
+
+ REPORT /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:version-tree xmlns:D="DAV:">
+ <D:prop>
+ <D:version-name/>
+ <D:creator-displayname/>
+ <D:successor-set/>
+ </D:prop>
+ </D:version-tree>
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 27]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-name>V1</D:version-name>
+ <D:creator-displayname>Fred</D:creator-displayname>
+ <D:successor-set>
+ <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
+ <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
+ </D:successor-set>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-name>V2</D:version-name>
+ <D:creator-displayname>Fred</D:creator-displayname>
+ <D:successor-set/>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-name>V2.1.1</D:version-name>
+ <D:creator-displayname>Sally</D:creator-displayname>
+ <D:successor-set/>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 28]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.8 DAV:expand-property Report
+
+ Many property values are defined as a DAV:href, or a set of DAV:href
+ elements. The DAV:expand-property report provides a mechanism for
+ retrieving in one request the properties from the resources
+ identified by those DAV:href elements. This report not only
+ decreases the number of requests required, but also allows the server
+ to minimize the number of separate read transactions required on the
+ underlying versioning store.
+
+ The DAV:expand-property report SHOULD be supported by all resources
+ that support the REPORT method.
+
+ Marshalling:
+
+ The request body MUST be a DAV:expand-property XML element.
+
+ <!ELEMENT expand-property (property*)>
+ <!ELEMENT property (property*)>
+ <!ATTLIST property name NMTOKEN #REQUIRED>
+ name value: a property element type
+ <!ATTLIST property namespace NMTOKEN "DAV:">
+ namespace value: an XML namespace
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The properties reported in the DAV:prop elements of the
+ DAV:multistatus element MUST be those identified by the
+ DAV:property elements in the DAV:expand-property element. If
+ there are DAV:property elements nested within a DAV:property
+ element, then every DAV:href in the value of the corresponding
+ property is replaced by a DAV:response element whose DAV:prop
+ elements report the values of the properties identified by the
+ nested DAV:property elements. The nested DAV:property elements
+ can in turn contain DAV:property elements, so that multiple levels
+ of DAV:href expansion can be requested.
+
+ Note that a validating parser MUST be aware that the DAV:expand-
+ property report effectively modifies the DTD of every property by
+ replacing every occurrence of "href" in the DTD with "href |
+ response".
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 29]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.8.1 Example - DAV:expand-property
+
+ This example describes how to query a version-controlled resource to
+ determine the DAV:creator-display-name and DAV:activity-set of every
+ version in the version history of that version-controlled resource.
+ This example assumes that the server supports the version-history
+ feature (see Section 5).
+
+ >>REQUEST
+
+ REPORT /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:expand-property xmlns:D="DAV:">
+ <D:property name="version-history">
+ <D:property name="version-set">
+ <D:property name="creator-displayname"/>
+ <D:property name="activity-set"/>
+ </D:property>
+ </D:property>
+ </D:expand-property>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/foo.html</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-history>
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-set>
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23/ver/1</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:creator-displayname>Fred</D:creator-displayname>
+
+
+
+Clemm, et al. Standards Track [Page 30]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <D:activity-set> <D:href>
+ http://www.webdav.org/ws/dev/sally
+ </D:href> </D:activity-set> </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat> </D:response>
+ <D:response>
+ <D:href>http://repo.webdav.org/his/23/ver/2</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:creator-displayname>Sally</D:creator-displayname>
+ <D:activity-set>
+ <D:href>http://repo.webdav.org/act/add-refresh-cmd</D:href>
+ </D:activity-set> </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat> </D:response>
+ </D:version-set> </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat> </D:response>
+ </D:version-history> </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat> </D:response>
+ </D:multistatus>
+
+ In this example, the DAV:creator-displayname and DAV:activity-set
+ properties of the versions in the DAV:version-set of the
+ DAV:version-history of http://www.webdav.org/foo.html are reported.
+
+3.9 Additional OPTIONS Semantics
+
+ If the server supports the version-control feature, it MUST include
+ "version-control" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any versioning
+ properties, reports, or methods.
+
+3.10 Additional PUT Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-version-controlled-content): If the request-URL
+ identifies a resource with a DAV:checked-in property, the request
+ MUST fail unless DAV:auto-version semantics will automatically
+ check out the resource.
+
+ (DAV:cannot-modify-version): If the request-URL identifies a
+ version, the request MUST fail.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 31]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ If the request creates a new resource that is automatically placed
+ under version control, all preconditions for VERSION-CONTROL apply
+ to the request.
+
+ Additional Postconditions:
+
+ (DAV:auto-checkout): If the resource was a checked-in version-
+ controlled resource whose DAV:auto-version property indicates it
+ should be automatically checked out but not automatically checked
+ in for a modification request, then the server MUST have
+ automatically checked out the resource prior to executing the
+ request. In particular, the value of the DAV:checked-out property
+ of the resource MUST be that of the DAV:checked-in property prior
+ to the request, the DAV:checked-in property MUST have been
+ removed, and the DAV:predecessor-set property MUST be initialized
+ to be the same as the DAV:checked-out property. If any part of
+ the checkout/update sequence failed, the status from the failed
+ part of the request MUST be returned, and the server state
+ preceding the request sequence MUST be restored.
+
+ (DAV:auto-checkout-checkin): If the resource was a checked-in
+ version-controlled resource whose DAV:auto-version property
+ indicates it should be automatically checked out and automatically
+ checked in for a modification request, then the server MUST have
+ automatically checked out the resource prior to executing the
+ request and automatically checked it in after the request. In
+ particular, the DAV:checked-in property of the resource MUST
+ identify a new version whose content and dead properties are the
+ same as those of the resource. The DAV:predecessor-set of the new
+ version MUST identify the version identified by the DAV:checked-in
+ property prior to the request. If any part of the
+ checkout/update/checkin sequence failed, the status from the
+ failed part of the request MUST be returned, and the server state
+ preceding the request sequence MUST be restored.
+
+ If the request creates a new resource, the new resource MAY have
+ automatically been placed under version control, and all
+ postconditions for VERSION-CONTROL apply to the request.
+
+3.11 Additional PROPFIND Semantics
+
+ A DAV:allprop PROPFIND request SHOULD NOT return any of the
+ properties defined by this document. This allows a versioning server
+ to perform efficiently when a naive client, which does not understand
+ the cost of asking a server to compute all possible live properties,
+ issues a DAV:allprop PROPFIND request.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 32]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Preconditions:
+
+ (DAV:supported-live-property): If the request attempts to access a
+ property defined by this document, the semantics of that property
+ MUST be supported by the server.
+
+3.12 Additional PROPPATCH Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-version-controlled-property): If the request
+ attempts to modify a dead property, same semantics as PUT (see
+ Section 3.10).
+
+ (DAV:cannot-modify-version): If the request attempts to modify a
+ dead property, same semantics as PUT (see Section 3.10).
+
+ (DAV:cannot-modify-protected-property): An attempt to modify a
+ property that is defined by this document, as being protected for
+ that kind of resource, MUST fail.
+
+ (DAV:supported-live-property): An attempt to modify a property
+ defined by this document, but whose semantics are not enforced by
+ the server, MUST fail. This helps ensure that a client will be
+ notified when it is trying to use a property whose semantics are
+ not supported by the server.
+
+ Additional Postconditions:
+
+ (DAV:auto-checkout): If the request modified a dead property, same
+ semantics as PUT (see Section 3.10).
+
+ (DAV:auto-checkout-checkin): If the request modified a dead
+ property, same semantics as PUT (see Section 3.10).
+
+3.13 Additional DELETE Semantics
+
+ Additional Preconditions:
+
+ (DAV:no-version-delete): A server MAY fail an attempt to DELETE a
+ version.
+
+ Additional Postconditions:
+
+ (DAV:update-predecessor-set): If a version was deleted, the server
+ MUST have replaced any reference to that version in a
+ DAV:predecessor-set by a copy of the DAV:predecessor-set of the
+ deleted version.
+
+
+
+Clemm, et al. Standards Track [Page 33]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.14 Additional COPY Semantics
+
+ Additional Preconditions:
+
+ If the request creates a new resource that is automatically placed
+ under version control, all preconditions for VERSION-CONTROL apply
+ to the request.
+
+ Additional Postconditions:
+
+ (DAV:must-not-copy-versioning-property): A property defined by
+ this document MUST NOT have been copied to the new resource
+ created by this request, but instead that property of the new
+ resource MUST have the default initial value it would have had if
+ the new resource had been created by a non-versioning method such
+ as PUT or a MKCOL.
+
+ (DAV:auto-checkout): If the destination is a version-controlled
+ resource, same semantics as PUT (see Section 3.10).
+
+ (DAV:auto-checkout-checkin): If the destination is a version-
+ controlled resource, same semantics as PUT (see Section 3.10).
+
+ (DAV:copy-creates-new-resource): If the source of a COPY is a
+ version-controlled resource or version, and if there is no
+ resource at the destination of the COPY, then the COPY creates a
+ new non-version-controlled resource at the destination of the
+ COPY. The new resource MAY automatically be put under version
+ control, but the resulting version-controlled resource MUST be
+ associated with a new version history created for that new
+ version-controlled resource, and all postconditions for
+ VERSION-CONTROL apply to the request.
+
+3.15 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-rename-version): If the request-URL identifies a
+ version, the request MUST fail.
+
+ Additional Postconditions:
+
+ (DAV:preserve-versioning-properties): When a resource is moved
+ from a source URL to a destination URL, a property defined by this
+ document MUST have the same value at the destination URL as it had
+ at the source URL.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 34]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+3.16 Additional UNLOCK Semantics
+
+ Note that these semantics apply both to an explicit UNLOCK request,
+ as well as to the removal of a lock because of a lock timeout. If a
+ precondition or postcondition cannot be satisfied, the lock timeout
+ MUST NOT occur.
+
+ Additional Preconditions:
+
+ (DAV:version-history-is-tree): If the request-URL identifies a
+ checked-out version-controlled resource that will be automatically
+ checked in when the lock is removed, then the versions identified
+ by the DAV:predecessor-set of the checked-out resource MUST be
+ descendants of the root version of the version history for the
+ DAV:checked-out version.
+
+ Additional Postconditions:
+
+ (DAV:auto-checkin): If the request-URL identified a checked-out
+ version-controlled resource that had been automatically checked
+ out because of its DAV:auto-version property, the request MUST
+ have created a new version in the version history of the
+ DAV:checked-out version. The request MUST have allocated a URL
+ for the version that MUST NOT have previously identified any other
+ resource, and MUST NOT ever identify a resource other than this
+ version. The content, dead properties, DAV:resourcetype, and
+ DAV:predecessor-set of the new version MUST be copied from the
+ checked-out resource. The DAV:version-name of the new version
+ MUST be set to a server-defined value distinct from all other
+ DAV:version-name values of other versions in the same version
+ history. The request MUST have removed the DAV:checked-out
+ property of the version-controlled resource, and MUST have added a
+ DAV:checked-in property that identifies the new version.
+
+4 CHECKOUT-IN-PLACE FEATURE
+
+ With the version-control feature, WebDAV locking can be used to avoid
+ the proliferation of versions that would result if every modification
+ to a version-controlled resource produced a new version. The
+ checkout-in-place feature provides an alternative mechanism that
+ allows a client to explicitly check out and check in a resource to
+ create a new version.
+
+4.1 Additional Version Properties
+
+ The checkout-in-place feature introduces the following REQUIRED
+ properties for a version.
+
+
+
+
+Clemm, et al. Standards Track [Page 35]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+4.1.1 DAV:checkout-fork
+
+ This property controls the behavior of CHECKOUT when a version
+ already is checked out or has a successor. If the DAV:checkout-fork
+ of a version is DAV:forbidden, a CHECKOUT request MUST fail if it
+ would result in that version appearing in the DAV:predecessor-set or
+ DAV:checked-out property of more than one version or checked-out
+ resource. If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT
+ request MUST fail unless DAV:fork-ok is specified in the CHECKOUT
+ request body.
+
+ A server MAY reject attempts to modify the DAV:checkout-fork of a
+ version.
+
+ <!ELEMENT checkout-fork ANY>
+ ANY value: A sequence of elements with at most one DAV:discouraged
+ or DAV:forbidden element.
+ <!ELEMENT discouraged EMPTY>
+ <!ELEMENT forbidden EMPTY>
+
+4.1.2 DAV:checkin-fork
+
+ This property controls the behavior of CHECKIN when a version already
+ has a successor. If the DAV:checkin-fork of a version is
+ DAV:forbidden, a CHECKIN request MUST fail if it would result in that
+ version appearing in the DAV:predecessor-set of more than one
+ version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN
+ request MUST fail unless DAV:fork-ok is specified in the CHECKIN
+ request body.
+
+ A server MAY reject attempts to modify the DAV:checkout-fork of a
+ version.
+
+ <!ELEMENT checkin-fork ANY>
+ ANY value: A sequence of elements with at most one DAV:discouraged
+ or DAV:forbidden element.
+ <!ELEMENT discouraged EMPTY>
+ <!ELEMENT forbidden EMPTY>
+
+4.2 Checked-Out Resource Properties
+
+ The checkout-in-place feature introduces the following REQUIRED
+ properties for a checked-out resource.
+
+4.2.1 DAV:checkout-fork
+
+ This property determines the DAV:checkout-fork property of the
+ version that results from checking in this resource.
+
+
+
+Clemm, et al. Standards Track [Page 36]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+4.2.2 DAV:checkin-fork
+
+ This property determines the DAV:checkin-fork property of the version
+ that results from checking in this resource.
+
+4.3 CHECKOUT Method (applied to a version-controlled resource)
+
+ A CHECKOUT request can be applied to a checked-in version-controlled
+ resource to allow modifications to the content and dead properties of
+ that version-controlled resource.
+
+ If a CHECKOUT request fails, the server state preceding the request
+ MUST be restored.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkout XML
+ element.
+
+ <!ELEMENT checkout ANY>
+
+ ANY value: A sequence of elements with at most one DAV:fork-ok
+ element.
+
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:checkout-response XML element.
+
+ <!ELEMENT checkout-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:must-be-checked-in): If a version-controlled resource is
+ being checked out, it MUST have a DAV:checked-in property.
+
+ (DAV:checkout-of-version-with-descendant-is-forbidden): If the
+ DAV:checkout-fork property of the version being checked out is
+ DAV:forbidden, the request MUST fail if a version identifies that
+ version in its DAV:predecessor-set.
+
+ (DAV:checkout-of-version-with-descendant-is-discouraged): If the
+ DAV:checkout-fork property of the version being checked out is
+ DAV:discouraged, the request MUST fail if a version identifies
+ that version in its DAV:predecessor-set unless DAV:fork-ok is
+ specified in the request body.
+
+
+
+Clemm, et al. Standards Track [Page 37]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:checkout-of-checked-out-version-is-forbidden): If the
+ DAV:checkout-fork property of the version being checked out is
+ DAV:forbidden, the request MUST fail if a checked-out resource
+ identifies that version in its DAV:checked-out property.
+
+ (DAV:checkout-of-checked-out-version-is-discouraged): If the
+ DAV:checkout-fork property of the version being checked out is
+ DAV:discouraged, the request MUST fail if a checked-out resource
+ identifies that version in its DAV:checked-out property unless
+ DAV:fork-ok is specified in the request body.
+
+ Postconditions:
+
+ (DAV:is-checked-out): The checked-out resource MUST have a
+ DAV:checked-out property that identifies the DAV:checked-in
+ version preceding the checkout. The version-controlled resource
+ MUST NOT have a DAV:checked-in property.
+
+ (DAV:initialize-predecessor-set): The DAV:predecessor-set property
+ of the checked-out resource MUST be initialized to be the
+ DAV:checked-out version.
+
+4.3.1 Example - CHECKOUT of a version-controlled resource
+
+ >>REQUEST
+
+ CHECKOUT /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the version-controlled resource /foo.html is checked
+ out.
+
+4.4 CHECKIN Method (applied to a version-controlled resource)
+
+ A CHECKIN request can be applied to a checked-out version-controlled
+ resource to produce a new version whose content and dead properties
+ are copied from the checked-out resource.
+
+ If a CHECKIN request fails, the server state preceding the request
+ MUST be restored.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 38]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkin XML
+ element.
+
+ <!ELEMENT checkin ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:keep-checked-out element and at most one DAV:fork-ok element.
+
+ <!ELEMENT keep-checked-out EMPTY>
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:checkin-response XML element.
+
+ <!ELEMENT checkin-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:must-be-checked-out): The request-URL MUST identify a
+ resource with a DAV:checked-out property.
+
+ (DAV:version-history-is-tree) The versions identified by the
+ DAV:predecessor-set of the checked-out resource MUST be
+ descendants of the root version of the version history for the
+ DAV:checked-out version.
+
+ (DAV:checkin-fork-forbidden): A CHECKIN request MUST fail if it
+ would cause a version whose DAV:checkin-fork is DAV:forbidden to
+ appear in the DAV:predecessor-set of more than one version.
+
+ (DAV:checkin-fork-discouraged): A CHECKIN request MUST fail if it
+ would cause a version whose DAV:checkin-fork is DAV:discouraged to
+ appear in the DAV:predecessor-set of more than one version, unless
+ DAV:fork-ok is specified in the request body.
+
+ Postconditions:
+
+ (DAV:create-version): The request MUST have created a new version
+ in the version history of the DAV:checked-out version. The
+ request MUST have allocated a distinct new URL for the new
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 39]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ version, and that URL MUST NOT ever identify any resource other
+ than that version. The URL for the new version MUST be returned in
+ a Location response header.
+
+ (DAV:initialize-version-content-and-properties): The content, dead
+ properties, DAV:resourcetype, and DAV:predecessor-set of the new
+ version MUST be copied from the checked-out resource. The
+ DAV:version-name of the new version MUST be set to a server-
+ defined value distinct from all other DAV:version-name values of
+ other versions in the same version history.
+
+ (DAV:checked-in): If the request-URL identifies a version-
+ controlled resource and DAV:keep-checked-out is not specified in
+ the request body, the DAV:checked-out property of the version-
+ controlled resource MUST have been removed and a DAV:checked-in
+ property that identifies the new version MUST have been added.
+
+ (DAV:keep-checked-out): If DAV:keep-checked-out is specified in
+ the request body, the DAV:checked-out property of the checked-out
+ resource MUST have been updated to identify the new version.
+
+4.4.1 Example - CHECKIN
+
+ >>REQUEST
+
+ CHECKIN /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Location: http://repo.webdav.org/his/23/ver/32
+ Cache-Control: no-cache
+
+ In this example, version-controlled resource /foo.html is checked in,
+ and a new version is created at http://repo.webdav.org/his/23/ver/32.
+
+4.5 UNCHECKOUT Method
+
+ An UNCHECKOUT request can be applied to a checked-out version-
+ controlled resource to cancel the CHECKOUT and restore the pre-
+ CHECKOUT state of the version-controlled resource.
+
+ If an UNCHECKOUT request fails, the server MUST undo any partial
+ effects of the UNCHECKOUT request.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 40]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:uncheckout XML
+ element.
+
+ <!ELEMENT uncheckout ANY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:uncheckout-response XML element.
+
+ <!ELEMENT uncheckout-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:must-be-checked-out-version-controlled-resource): The
+ request-URL MUST identify a version-controlled resource with a
+ DAV:checked-out property.
+
+ Postconditions:
+
+ (DAV:cancel-checked-out): The value of the DAV:checked-in property
+ is that of the DAV:checked-out property prior to the request, and
+ the DAV:checked-out property has been removed.
+
+ (DAV:restore-content-and-dead-properties): The content and dead
+ properties of the version-controlled resource are copies of its
+ DAV:checked-in version.
+
+4.5.1 Example - UNCHECKOUT
+
+ >>REQUEST
+
+ UNCHECKOUT /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the content and dead properties of the version-
+ controlled resource identified by http://www.webdav.org/foo.html are
+ restored to their values preceding the most recent CHECKOUT of that
+ version-controlled resource.
+
+
+
+
+Clemm, et al. Standards Track [Page 41]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+4.6 Additional OPTIONS Semantics
+
+ If a server supports the checkout-in-place feature, it MUST include
+ "checkout-in-place" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any versioning
+ properties, reports, or methods.
+
+5 Version-History Feature
+
+ It is often useful to have access to a version history even after all
+ version-controlled resources for that version history have been
+ deleted. A server can provide this functionality by supporting
+ version history resources. A version history resource is a resource
+ that exists in a server defined namespace and therefore is unaffected
+ by any deletion or movement of version-controlled resources. A
+ version history resource is an appropriate place to add a property
+ that logically applies to all states of a resource. The DAV:expand-
+ property report (see Section 3.8) can be applied to the DAV:version-
+ set of a version history resource to provide a variety of useful
+ reports on all versions in that version history.
+
+5.1 Version History Properties
+
+ The DAV:resourcetype of a version history MUST be DAV:version-
+ history.
+
+ The version-history feature introduces the following REQUIRED
+ properties for a version history.
+
+5.1.1 DAV:version-set (protected)
+
+ This property identifies each version of this version history.
+
+ <!ELEMENT version-set (href+)>
+
+5.1.2 DAV:root-version (computed)
+
+ This property identifies the root version of this version history.
+
+ <!ELEMENT root-version (href)>
+
+5.2 Additional Version-Controlled Resource Properties
+
+ The version-history feature introduces the following REQUIRED
+ property for a version-controlled resource.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 42]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+5.2.1 DAV:version-history (computed)
+
+ This property identifies the version history resource for the
+ DAV:checked-in or DAV:checked-out version of this version-controlled
+ resource.
+
+ <!ELEMENT version-history (href)>
+
+5.3 Additional Version Properties
+
+ The version-history feature introduces the following REQUIRED
+ property for a version.
+
+5.3.1 DAV:version-history (computed)
+
+ This property identifies the version history that contains this
+ version.
+
+ <!ELEMENT version-history (href)>
+
+5.4 DAV:locate-by-history Report
+
+ Many properties identify a version from some version history. It is
+ often useful to be able to efficiently locate a version-controlled
+ resource for that version history. The DAV:locate-by-history report
+ can be applied to a collection to locate the collection member that
+ is a version-controlled resource for a specified version history
+ resource.
+
+ Marshalling:
+
+ The request body MUST be a DAV:locate-by-history XML element.
+
+ <!ELEMENT locate-by-history (version-history-set, prop)>
+ <!ELEMENT version-history-set (href+)>
+ prop: see RFC 2518, Section 12.11
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element containing every version-controlled
+ resource that is a member of the collection identified by the
+ request-URL, and whose DAV:version-history property identifies one
+ of the version history resources identified by the request body.
+ The DAV:prop element in the request body identifies which
+ properties should be reported in the DAV:prop elements in the
+ response body.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 43]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:must-be-version-history): Each member of the DAV:version-
+ history-set element in the request body MUST identify a version
+ history resource.
+
+5.4.1 Example - DAV:locate-by-history Report
+
+ >>REQUEST
+
+ REPORT /ws/public HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:locate-by-history xmlns:D="DAV:">
+ <D:version-history-set>
+ <D:href>http://repo.webdav.org/his/23</D:href>
+ <D:href>http://repo.webdav.org/his/84</D:href>
+ <D:href>http://repo.webdav.org/his/129</D:href>
+ <D:version-history-set/>
+ <D:prop>
+ </D:version-history>
+ </D:prop>
+ </D:locate-by-history>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/ws/public/x/test.html</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:version-history>
+ <D:href>http://repo.webdav.org/his/23</D:href>
+ </D:version-history>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Clemm, et al. Standards Track [Page 44]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, there is only one version-controlled member of
+ /ws/public that is a version-controlled resource for one of the three
+ specified version history resources. In particular,
+ /ws/public/x/test.html is the version-controlled resource for
+ http://repo.webdav.org/his/23.
+
+5.5 Additional OPTIONS Semantics
+
+ If the server supports the version-history feature, it MUST include
+ "version-history" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any versioning
+ properties, reports, or methods.
+
+ A DAV:version-history-collection-set element MAY be included in the
+ request body to identify collections that may contain version history
+ resources.
+
+ Additional Marshalling:
+
+ If an XML request body is included, it MUST be a DAV:options XML
+ element.
+
+ <!ELEMENT options ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:version-history-collection-set element.
+
+ If an XML response body for a successful request is included, it
+ MUST be a DAV:options-response XML element.
+
+ <!ELEMENT options-response ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:version-history-collection-set element.
+
+ <!ELEMENT version-history-collection-set (href*)>
+
+ If DAV:version-history-collection-set is included in the request
+ body, the response body for a successful request MUST contain a
+ DAV:version-history-collection-set element identifying collections
+ that may contain version histories. An identified collection MAY
+ be the root collection of a tree of collections, all of which may
+ contain version histories. Since different servers can control
+ different parts of the URL namespace, different resources on the
+ same host MAY have different DAV:version-history-collection-set
+ values. The identified collections MAY be located on different
+ hosts from the resource.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 45]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+5.6 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-version-set): If the request deleted a version
+ history, the request MUST have deleted all versions in the
+ DAV:version-set of that version history, and MUST have satisfied
+ the postconditions for version deletion (see Section 3.13).
+
+ (DAV:version-history-has-root): If the request deleted the root
+ version of a version history, the request MUST have updated the
+ DAV:root-version of the version history to refer to another
+ version that is an ancestor of all other remaining versions in
+ that version history. A result of this postcondition is that
+ every version history will have at least one version, and the only
+ way to delete all versions is to delete the version history
+ resource.
+
+5.7 Additional COPY Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-copy-history): If the request-URL identifies a version
+ history, the request MUST fail. In order to create another
+ version history whose versions have the same content and dead
+ properties, the appropriate sequence of VERSION-CONTROL, CHECKOUT,
+ PUT, PROPPATCH, and CHECKIN requests must be made.
+
+5.8 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-rename-history): If the request-URL identifies a
+ version history, the request MUST fail.
+
+5.9 Additional VERSION-CONTROL Semantics
+
+ Additional Postconditions:
+
+ (DAV:new-version-history): If the request created a new version
+ history, the request MUST have allocated a new server-defined URL
+ for that version history that MUST NOT have previously identified
+ any other resource, and MUST NOT ever identify a resource other
+ than this version history.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 46]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+5.10 Additional CHECKIN Semantics
+
+ Additional Postconditions:
+
+ (DAV:add-to-history): A URL for the new version resource MUST have
+ been added to the DAV:version-set of the version history of the
+ DAV:checked-out version.
+
+6 Workspace Feature
+
+ In order to allow multiple users to work concurrently on adding
+ versions to the same version history, it is necessary to allocate on
+ the server multiple checked-out resources for the same version
+ history. Even if only one user is making changes to a resource, that
+ user will sometimes wish to create a "private" version, and then to
+ expose that version at a later time. One way to provide this
+ functionality depends on the client keeping track of its current set
+ of checked-out resources. This is the working-resource feature
+ defined in Section 8. The other way to provide this functionality
+ avoids the need for persistent state on the client, and instead has
+ the server maintain a human meaningful namespace for related sets of
+ checked-out resources. This is the workspace feature defined in this
+ section.
+
+ The workspace feature introduces a "workspace resource". A workspace
+ resource is a collection whose members are related version-controlled
+ and non-version-controlled resources. Multiple workspaces may be
+ used to expose different versions and configurations of a set of
+ version-controlled resources concurrently. In order to make changes
+ to a version-controlled resource in one workspace visible in another
+ workspace, that version-controlled resource must be checked in, and
+ then the corresponding version-controlled resource in the other
+ workspace can be updated to display the content and dead properties
+ of the new version.
+
+ In order to ensure unambiguous merging (see Section 11) and
+ baselining (see Section 12) semantics, a workspace may contain at
+ most one version-controlled resource for a given version history.
+ This is required for unambiguous merging because the MERGE method
+ must identify which version-controlled resource is to be the merge
+ target of a given version. This is required for unambiguous
+ baselining because a baseline can only select one version for a given
+ version-controlled resource.
+
+ Initially, an empty workspace can be created. Non-version-controlled
+ resources can then be added to the workspace with standard WebDAV
+ requests such as PUT and MKCOL. Version-controlled resources can be
+ added to the workspace with VERSION-CONTROL requests. If the
+
+
+
+Clemm, et al. Standards Track [Page 47]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ baseline feature is supported, collections in the workspace can be
+ placed under baseline control, and then initialized by existing
+ baselines.
+
+6.1 Workspace Properties
+
+ The workspace feature introduces the following REQUIRED property for
+ a workspace.
+
+6.1.1 DAV:workspace-checkout-set (computed)
+
+ This property identifies each checked-out resource whose
+ DAV:workspace property identifies this workspace.
+
+ <!ELEMENT workspace-checkout-set (href*)>
+
+6.2 Additional Resource Properties
+
+ The workspace feature introduces the following REQUIRED property for
+ a WebDAV resource.
+
+6.2.1 DAV:workspace (protected)
+
+ The DAV:workspace property of a workspace resource MUST identify
+ itself. The DAV:workspace property of any other type of resource
+ MUST be the same as the DAV:workspace of its parent collection.
+
+ <!ELEMENT workspace (href)>
+
+6.3 MKWORKSPACE Method
+
+ A MKWORKSPACE request creates a new workspace resource. A server MAY
+ restrict workspace creation to particular collections, but a client
+ can determine the location of these collections from a
+ DAV:workspace-collection-set OPTIONS request (see Section 6.4).
+
+ If a MKWORKSPACE request fails, the server state preceding the
+ request MUST be restored.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:mkworkspace XML
+ element.
+
+ <!ELEMENT mkworkspace ANY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:mkworkspace-response XML element.
+
+
+
+Clemm, et al. Standards Track [Page 48]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT mkworkspace-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:resource-must-be-null): A resource MUST NOT exist at the
+ request-URL.
+
+ (DAV:workspace-location-ok): The request-URL MUST identify a
+ location where a workspace can be created.
+
+ Postconditions:
+
+ (DAV:initialize-workspace): A new workspace exists at the
+ request-URL. The DAV:resourcetype of the workspace MUST be
+ DAV:collection. The DAV:workspace of the workspace MUST identify
+ the workspace.
+
+6.3.1 Example - MKWORKSPACE
+
+ >>REQUEST
+
+ MKWORKSPACE /ws/public HTTP/1.1
+ Host: www.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+
+ In this example, a new workspace is created at
+ http://www.webdav.org/ws/public.
+
+6.4 Additional OPTIONS Semantics
+
+ If a server supports the workspace feature, it MUST include
+ "workspace" as a field in the DAV response header from an OPTIONS
+ request on any resource that supports any versioning properties,
+ reports, or methods.
+
+ If a server supports the workspace feature, it MUST also support the
+ checkout-in-place feature and the version-history feature.
+
+ A DAV:workspace-collection-set element MAY be included in the request
+ body to identify collections that may contain workspace resources.
+
+
+
+
+Clemm, et al. Standards Track [Page 49]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Marshalling:
+
+ If an XML request body is included, it MUST be a DAV:options XML
+ element.
+
+ <!ELEMENT options ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:workspace-collection-set element.
+
+ If an XML response body for a successful request is included, it
+ MUST be a DAV:options-response XML element.
+
+ <!ELEMENT options-response ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:workspace-collection-set element.
+
+ <!ELEMENT workspace-collection-set (href*)>
+
+ If DAV:workspace-collection-set is included in the request body,
+ the response body for a successful request MUST contain a
+ DAV:workspace-collection-set element identifying collections that
+ may contain workspaces. An identified collection MAY be the root
+ collection of a tree of collections, all of which may contain
+ workspaces. Since different servers can control different parts
+ of the URL namespace, different resources on the same host MAY
+ have different DAV:workspace-collection-set values. The
+ identified collections MAY be located on different hosts from the
+ resource.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 50]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+6.4.1 Example - OPTIONS
+
+ >>REQUEST
+
+ OPTIONS /doc HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:options xmlns:D="DAV:">
+ <D:version-history-collection-set/>
+ <D:workspace-collection-set/>
+ </D:options>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ DAV: 1
+ DAV: version-control,checkout-in-place,version-history,workspace
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:options-response xmlns:D="DAV:">
+ <D:version-history-collection-set>
+ <D:href>http://repo.webdav.org/his</D:href>
+ </D:version-history-collection-set>
+ <D:workspace-collection-set>
+ <D:href>http://www.webdav.org/public/ws</D:href>
+ <D:href>http://www.webdav.org/private/ws</D:href>
+ </D:workspace-collection-set>
+ </D:options-response>
+
+ In this example, the server indicates that it provides Class 1 DAV
+ support and basic-server-workspace versioning support. In addition,
+ the server indicates the requested locations of the version history
+ resources and the workspace resources.
+
+6.5 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-workspace-members): If a workspace is deleted, any
+ resource that identifies that workspace in its DAV:workspace
+ property MUST be deleted.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 51]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+6.6 Additional MOVE Semantics
+
+ Additional Postconditions:
+
+ (DAV:workspace-member-moved): If the request-URL did not identify
+ a workspace, the DAV:workspace of the destination MUST have been
+ updated to have the same value as the DAV:workspace of the parent
+ collection of the destination.
+
+ (DAV:workspace-moved): If the request-URL identified a workspace,
+ any reference to that workspace in a DAV:workspace property MUST
+ have been updated to refer to the new location of that workspace.
+
+6.7 Additional VERSION-CONTROL Semantics
+
+ A VERSION-CONTROL request can be used to create a new version-
+ controlled resource for an existing version history. This allows the
+ creation of version-controlled resources for the same version history
+ in multiple workspaces.
+
+ Additional Marshalling:
+
+ <!ELEMENT version-control ANY>
+ ANY value: A sequence of elements with at most one DAV:version
+ element.
+
+ <!ELEMENT version (href)>
+
+ Additional Preconditions:
+
+ (DAV:cannot-add-to-existing-history): If the DAV:version-control
+ request body element contains a DAV:version element, the request-
+ URL MUST NOT identify a resource.
+
+ (DAV:must-be-version): The DAV:href of the DAV:version element
+ MUST identify a version.
+
+ (DAV:one-version-controlled-resource-per-history-per-workspace):
+ If the DAV:version-control request body specifies a version, and
+ if the request-URL is a member of a workspace, then there MUST NOT
+ already be a version-controlled member of that workspace whose
+ DAV:checked-in or DAV:checked-out property identifies any version
+ from the version history of the version specified in the request
+ body.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 52]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:new-version-controlled-resource): If the request-URL did NOT
+ identify a resource, a new version-controlled resource exists at
+ the request-URL whose content and dead properties are initialized
+ by those of the version in the request body, and whose
+ DAV:checked-in property identifies that version.
+
+6.7.1 Example - VERSION-CONTROL (using an existing version history)
+
+ >>REQUEST
+
+ VERSION-CONTROL /ws/public/bar.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:version-control xmlns:D="DAV:">
+ <D:version>
+ <D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
+ </D:version>
+ </D:version-control>
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+
+ In this example, a new version-controlled resource is created at
+ /ws/public/bar.html. The content and dead properties of the new
+ version-controlled resource are initialized to be the same as those
+ of the version identified by http://repo.webdav.org/his/12/ver/V3.
+
+7 UPDATE Feature
+
+ The update feature provides a mechanism for changing the state of a
+ checked-in version-controlled resource to be that of another version
+ from the version history of that resource.
+
+7.1 UPDATE Method
+
+ The UPDATE method modifies the content and dead properties of a
+ checked-in version-controlled resource (the "update target") to be
+ those of a specified version (the "update source") from the version
+ history of that version-controlled resource.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 53]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The response to an UPDATE request identifies the resources modified
+ by the request, so that a client can efficiently update any cached
+ state it is maintaining. Extensions to the UPDATE method allow
+ multiple resources to be modified from a single UPDATE request (see
+ Section 12.13).
+
+ Marshalling:
+
+ The request body MUST be a DAV:update element.
+
+ <!ELEMENT update ANY>
+ ANY value: A sequence of elements with at most one DAV:version
+ element and at most one DAV:prop element.
+ <!ELEMENT version (href)>
+ prop: see RFC 2518, Section 12.11
+
+ The response for a successful request MUST be a 207 Multi-Status,
+ where the DAV:multistatus XML element in the response body
+ identifies all resources that have been modified by the request.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Postconditions:
+
+ (DAV:update-content-and-properties): If the DAV:version element in
+ the request body identified a version that is in the same version
+ history as the DAV:checked-in version of a version-controlled
+ resource identified by the request-URL, then the content and dead
+ properties of that version-controlled resource MUST be the same as
+ those of the version specified by the DAV:version element, and the
+ DAV:checked-in property of the version-controlled resource MUST
+ identify that version. The request-URL MUST appear in a
+ DAV:response element in the response body.
+
+ (DAV:report-properties): If DAV:prop is specified in the request
+ body, the properties specified in the DAV:prop element MUST be
+ reported in the DAV:response elements in the response body.
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 54]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+7.1.1 Example - UPDATE
+
+ >>REQUEST
+
+ UPDATE /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:update xmlns:D="DAV:">
+ <D:version>
+ <D:href>http://repo.webdav.org/his/23/ver/33</D:href>
+ </D:version>
+ </D:update>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Cache-Control: no-cache
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/foo.html</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+
+ In this example, the content and dead properties of
+ http://repo.webdav.org/his/23/ver/33 are copied to the version-
+ controlled resource /foo.html, and the DAV:checked-in property of
+ /foo.html is updated to refer to
+ http://repo.webdav.org/his/23/ver/33.
+
+7.2 Additional OPTIONS Semantics
+
+ If the server supports the update feature, it MUST include "update"
+ as a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 55]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+8 Label Feature
+
+ A version "label" is a string that distinguishes one version in a
+ version history from all other versions in that version history. A
+ label can automatically be assigned by a server, or it can be
+ assigned by a client in order to provide a meaningful name for that
+ version. A given version label can be assigned to at most one
+ version of a given version history, but client assigned labels can be
+ reassigned to another version at any time. Note that although a
+ given label can be applied to at most one version from the same
+ version history, the same label can be applied to versions from
+ different version histories.
+
+ For certain methods, if the request-URL identifies a version-
+ controlled resource, a label can be specified in a Label request
+ header (see Section 8.3) to cause the method to be applied to the
+ version selected by that label from the version history of that
+ version-controlled resource.
+
+8.1 Additional Version Properties
+
+ The label feature introduces the following REQUIRED property for a
+ version.
+
+8.1.1 DAV:label-name-set (protected)
+
+ This property contains the labels that currently select this version.
+
+ <!ELEMENT label-name-set (label-name*)>
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+8.2 LABEL Method
+
+ A LABEL request can be applied to a version to modify the labels that
+ select that version. The case of a label name MUST be preserved when
+ it is stored and retrieved. When comparing two label names to decide
+ if they match or not, a server SHOULD use a case-sensitive URL-
+ escaped UTF-8 encoded comparison of the two label names.
+
+ If a LABEL request is applied to a checked in version-controlled
+ resource, the operation MUST be applied to the DAV:checked-in version
+ of that version-controlled resource.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 56]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Marshalling:
+
+ The request body MUST be a DAV:label element.
+
+ <!ELEMENT label ANY>
+ ANY value: A sequence of elements with at most one DAV:add,
+ DAV:set, or DAV:remove element.
+
+ <!ELEMENT add (label-name)>
+ <!ELEMENT set (label-name)>
+ <!ELEMENT remove (label-name)>
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+ The request MAY include a Label header.
+
+ The request MAY include a Depth header. If no Depth header is
+ included, Depth:0 is assumed. Standard depth semantics apply, and
+ the request is applied to the collection identified by the
+ request-URL and to all members of the collection that satisfy the
+ Depth value. If a Depth header is included and the request fails
+ on any resource, the response MUST be a 207 Multi-Status that
+ identifies all resources for which the request has failed.
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:label-response XML element.
+
+ <!ELEMENT label-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:must-be-checked-in): If the request-URL identifies a
+ version-controlled resource, the version-controlled resource MUST
+ be checked in.
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ (DAV:add-must-be-new-label): If DAV:add is specified in the
+ request body, the specified label MUST NOT appear in the
+ DAV:label-name-set of any version in the version history of that
+ version-controlled resource.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 57]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:label-must-exist): If DAV:remove is specified in the request
+ body, the specified label MUST appear in the DAV:label-name-set of
+ that version.
+
+ Postconditions:
+
+ (DAV:add-or-set-label): If DAV:add or DAV:set is specified in the
+ request body, the specified label MUST appear in the DAV:label-
+ name-set of the specified version, and MUST NOT appear in the
+ DAV:label-name-set of any other version in the version history of
+ that version.
+
+ (DAV:remove-label): If DAV:remove is specified in the request
+ body, the specified label MUST NOT appear in the DAV:label-name-
+ set of any version in the version history of that version.
+
+8.2.1 Example - Setting a label
+
+ >>REQUEST
+
+ LABEL /foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:label xmlns:D="DAV:">
+ <D:set>
+ <D:label-name>default</D:label-name>
+ </D:set>
+ </D:label>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the label "default" is applied to the DAV:checked-in
+ version of /foo.html.
+
+8.3 Label Header
+
+ For certain methods (e.g. GET, PROPFIND), if the request-URL
+ identifies a version-controlled resource, a label can be specified in
+ a Label request header to cause the method to be applied to the
+ version selected by that label from the version history of that
+ version-controlled resource.
+
+
+
+
+Clemm, et al. Standards Track [Page 58]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The value of a label header is the name of a label, encoded using
+ URL-escaped UTF-8. For example, the label "release B.3" is
+ identified by the following header:
+
+ Label: release%20B.3
+
+ A Label header MUST have no effect on a request whose request-URL
+ does not identify a version-controlled resource. In particular, it
+ MUST have no effect on a request whose request-URL identifies a
+ version or a version history.
+
+ A server MUST return an HTTP-1.1 Vary header containing Label in a
+ successful response to a cacheable request (e.g., GET) that includes
+ a Label header.
+
+8.4 Additional OPTIONS Semantics
+
+ If the server supports the label feature, it MUST include "label" as
+ a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+8.5 Additional GET Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the response MUST contain the content of the
+ specified version rather than that of the version-controlled
+ resource.
+
+8.6 Additional PROPFIND Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+
+
+Clemm, et al. Standards Track [Page 59]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the response MUST contain the properties of
+ the specified version rather than that of the version-controlled
+ resource.
+
+8.7 Additional COPY Semantics
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a version-controlled resource and a Label request
+ header is included, the request MUST have copied the properties
+ and content of the specified version rather than that of the
+ version-controlled resource.
+
+8.8 Additional CHECKOUT Semantics
+
+ If the server supports the working-resource option, a LABEL header
+ may be included to check out the version selected by the specified
+ label.
+
+ Additional Marshalling:
+
+ The request MAY include a Label header.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 60]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If a Label request header is
+ included and the request-URL identifies a version-controlled
+ resource, the specified label MUST select a version in the version
+ history of the version-controlled resource.
+
+ (DAV:must-not-have-label-and-apply-to-version): If a Label request
+ header is included, the request body MUST NOT contain a
+ DAV:apply-to-version element.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If the request-URL
+ identifies a checked-in version-controlled resource, and a Label
+ request header is included, the CHECKOUT MUST have been applied to
+ the version selected by the specified label, and not to the
+ version-controlled resource itself.
+
+8.9 Additional UPDATE Semantics
+
+ If the request body of an UPDATE request contains a DAV:label-name
+ element, the update target is the resource identified by the
+ request-URL, and the update source is the version selected by the
+ specified label from the version history of the update target.
+
+ Additional Marshalling:
+
+ <!ELEMENT update ANY>
+ ANY value: A sequence of elements with at most one DAV:label-name
+ or DAV:version element (but not both).
+ <!ELEMENT label-name (#PCDATA)>
+ PCDATA value: string
+
+ The request MAY include a Depth header. If no Depth header is
+ included, Depth:0 is assumed. Standard depth semantics apply, and
+ the request is applied to the collection identified by the
+ request-URL and to all members of the collection that satisfy the
+ Depth value. If a Depth header is included and the request fails
+ on any resource, the response MUST be a 207 Multi-Status that
+ identifies all resources for which the request has failed.
+
+ Additional Preconditions:
+
+ (DAV:must-select-version-in-history): If the request includes a
+ DAV:label-name element in the request body, the label MUST select
+ a version in the version history of the version-controlled
+ resource identified by the request-URL.
+
+
+
+Clemm, et al. Standards Track [Page 61]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:depth-update): If the request includes a Depth header,
+ standard depth semantics apply, and the request is applied to the
+ collection identified by the request-URL and to all members of the
+ collection that satisfy the Depth value. The request MUST be
+ applied to a collection before being applied to any members of
+ that collection, since an update of a version-controlled
+ collection might change the membership of that collection.
+
+ Additional Postconditions:
+
+ (DAV:apply-request-to-labeled-version): If a DAV:label-name
+ element appears in the request body, the content and dead
+ properties of the version-controlled resource must have been
+ updated to be those of the version selected by that label.
+
+9 Working-Resource Feature
+
+ The working-resource feature provides an alternative to the workspace
+ feature for supporting parallel development. Unlike the workspace
+ feature, where the desired configuration of versions and checked-out
+ resources is maintained on the server, the working-resource feature
+ maintains the configuration on the client. This simplifies the
+ server implementation, but does not allow a user to access the
+ configuration from clients in different physical locations, such as
+ from another office, from home, or while traveling. Another
+ difference is that the workspace feature isolates clients from a
+ logical change that involves renaming shared resources, until that
+ logical change is complete and tested; with the working resource
+ feature, all clients use a common set of shared version-controlled
+ resources and every client sees the result of a MOVE as soon as it
+ occurs.
+
+ If a server supports the working-resource feature but not the
+ checkout-in-place feature, a CHECKOUT request can only be used to
+ create a working resource, and cannot be used to check out a
+ version-controlled resource. If a server supports the checkout-in-
+ place feature, but not the working-resource feature, a CHECKOUT can
+ only be used to change the state of a version-controlled resource
+ from checked-in to checked-out.
+
+9.1 Additional Version Properties
+
+ The working-resource feature introduces the following REQUIRED
+ properties for a version.
+
+9.1.1 DAV:checkout-fork
+
+ This property is defined in Section 4.1.1.
+
+
+
+Clemm, et al. Standards Track [Page 62]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+9.1.2 DAV:checkin-fork
+
+ This property is defined in Section 4.1.2.
+
+9.2 Working Resource Properties
+
+ The working-resource feature introduces the following REQUIRED
+ properties for a working resource. Since a working resource is a
+ checked-out resource, it also has any property defined in this
+ document for a checked-out resource.
+
+9.2.1 DAV:auto-update (protected)
+
+ This property identifies the version-controlled resource that will be
+ updated when the working resource is checked in.
+
+ <!ELEMENT auto-update (href)>
+
+9.2.2 DAV:checkout-fork
+
+ This property is defined in Section 4.2.1.
+
+9.2.3 DAV:checkin-fork
+
+ This property is defined in Section 4.2.2.
+
+9.3 CHECKOUT Method (applied to a version)
+
+ A CHECKOUT request can be applied to a version to create a new
+ working resource. The content and dead properties of the working
+ resource are a copy of the version that was checked out.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkout XML
+ element.
+
+ <!ELEMENT checkout ANY>
+
+ ANY value: A sequence of elements with at most one DAV:apply-to-
+ version and at most one DAV:fork-ok element.
+
+ <!ELEMENT apply-to-version EMPTY>
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included,
+ it MUST be a DAV:checkout-response XML element.
+
+
+
+
+Clemm, et al. Standards Track [Page 63]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT checkout-response ANY>
+
+ The response MUST include a Location header.
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:checkout-of-version-with-descendant-is-forbidden): See
+ Section 4.3.
+
+ (DAV:checkout-of-version-with-descendant-is-discouraged): See
+ Section 4.3.
+
+ (DAV:checkout-of-checked-out-version-is-forbidden): See Section
+ 4.3.
+
+ (DAV:checkout-of-checked-out-version-is-discouraged): See Section
+ 4.3.
+
+ Postconditions:
+
+ (DAV:create-working-resource): If the request-URL identified a
+ version, the Location response header MUST contain the URL of a
+ new working resource. The DAV:checked-out property of the new
+ working resource MUST identify the version that was checked out.
+ The content and dead properties of the working resource MUST be
+ copies of the content and dead properties of the DAV:checked-out
+ version. The DAV:predecessor-set property of the working resource
+ MUST be initialized to be the version identified by the request-
+ URL. The DAV:auto-update property of the working resource MUST
+ NOT exist.
+
+ (DAV:create-working-resource-from-checked-in-version): If the
+ request-URL identified a version-controlled resource, and
+ DAV:apply-to-version is specified in the request body, the
+ CHECKOUT is applied to the DAV:checked-in version of the version-
+ controlled resource, and not the version-controlled resource
+ itself. A new working resource is created and the version-
+ controlled resource remains checked-in. The DAV:auto-update
+ property of the working resource MUST identify the version-
+ controlled resource.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 64]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+9.3.1 Example - CHECKOUT of a version
+
+ >>REQUEST
+
+ CHECKOUT /his/12/ver/V3 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Location: http://repo.webdav.org/wr/157
+ Cache-Control: no-cache
+
+ In this example, the version identified by
+ http://repo.webdav.org/his/12/ver/V3 is checked out, and the new
+ working resource is located at http://repo.webdav.org/wr/157.
+
+9.4 CHECKIN Method (applied to a working resource)
+
+ A CHECKIN request can be applied to a working resource to produce a
+ new version whose content and dead properties are a copy of those of
+ the working resource. If the DAV:auto-update property of the working
+ resource was set because the working resource was created by applying
+ a CHECKOUT with the DAV:apply-to-version flag to a version-controlled
+ resource, the CHECKIN request will also update the content and dead
+ properties of that version-controlled resource to be those of the new
+ version.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:checkin XML
+ element.
+
+ <!ELEMENT checkin ANY>
+ ANY value: A sequence of elements with at most one DAV:fork-ok
+ element.
+
+ <!ELEMENT fork-ok EMPTY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:checkin-response XML element.
+
+ <!ELEMENT checkin-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 65]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:must-be-checked-out): See Section 4.4.
+
+ (DAV:version-history-is-tree) See Section 4.4.
+
+ (DAV:checkin-fork-forbidden): See Section 4.4.
+
+ (DAV:checkin-fork-discouraged): See Section 4.4.
+
+ (DAV:no-overwrite-by-auto-update): If the DAV:auto-update property
+ for the checked-out resource identifies a version-controlled
+ resource, at least one of the versions identified by the
+ DAV:predecessor-set property of the checked-out resource MUST
+ identify a version that is either the same as or a descendant of
+ the version identified by the DAV:checked-in property of that
+ version-controlled resource.
+
+ Postconditions:
+
+ (DAV:create-version): See Section 4.4.
+
+ (DAV:initialize-version-content-and-properties): See Section 4.4.
+
+ (DAV:auto-update): If the DAV:auto-update property of the
+ checked-out resource identified a version-controlled resource, an
+ UPDATE request with the new version MUST have been applied to that
+ version-controlled resource.
+
+ (DAV:delete-working-resource): If the request-URL identifies a
+ working resource and if DAV:keep-checked-out is not specified in
+ the request body, the working resource is deleted.
+
+9.4.1 Example - CHECKIN of a working resource
+
+ >>REQUEST
+
+ CHECKIN /wr/157 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Location: http://repo.webdav.org/his/23/ver/15
+ Cache-Control: no-cache
+
+
+
+
+
+Clemm, et al. Standards Track [Page 66]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the working resource /wr/157 checked in, and a new
+ version is created at http://repo.webdav.org/his/23/ver/15.
+
+9.5 Additional OPTIONS Semantics
+
+ If the server supports the working-resource feature, it MUST include
+ "working-resource" as a field in the DAV response header from an
+ OPTIONS request on any resource that supports any versioning
+ properties, reports, or methods.
+
+9.6 Additional COPY Semantics
+
+ Additional Postconditions:
+
+ (DAV:copy-creates-new-resource): The result of copying a working
+ resource is a new non-version-controlled resource at the
+ destination of the COPY. The new resource MAY automatically be
+ put under version control, but the resulting version-controlled
+ resource MUST be associated with a new version history created for
+ that new version-controlled resource.
+
+9.7 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-rename-working-resource): If the request-URL
+ identifies a working resource, the request MUST fail.
+
+ Additional Postconditions:
+
+ (DAV:update-auto-update): If the request-URL identified a
+ version-controlled resource, any DAV:auto-update properties that
+ identified that version-controlled resource MUST have been updated
+ to contain the new location of that version-controlled resource.
+
+10 Advanced Versioning Features
+
+ Advanced versioning addresses the problems of parallel development
+ and configuration management of multiple sets of interrelated
+ resources. Traditionally, artifacts of software development,
+ including requirements, design documents, code, and test cases, have
+ been a focus of configuration management. Web sites, comprising
+ multiple inter-linked resources (HTML, graphics, sound, CGI, and
+ others), are another class of complex information artifacts that
+ benefit from the application of configuration management. The
+ advanced versioning capabilities for coordinating concurrent change
+ provide the infrastructure for efficient and controlled management of
+ large evolving web sites.
+
+
+
+Clemm, et al. Standards Track [Page 67]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+10.1 Advanced Versioning Packages
+
+ Although a server MAY support any combination of advanced versioning
+ features, in order to minimize the complexity of a WebDAV advanced
+ versioning client, a WebDAV advanced versioning server SHOULD support
+ one of the following packages:
+
+ Advanced-Server-Workspace Package: basic-server-workspace package
+ plus all advanced features
+
+ Advanced-Client-Workspace Package: basic-client-workspace package
+ plus all advanced features
+
+ The advanced-server-workspace package supports advanced versioning
+ capabilities for a client with no persistent state. The advanced-
+ client-workspace package supports advanced versioning capabilities
+ for a client that maintains configuration state on the client. A
+ server that supports both advanced workspace packages will
+ interoperate with all versioning clients.
+
+10.2 Advanced Versioning Terms
+
+ The following additional terms are used by the advanced versioning
+ features.
+
+ Collection
+
+ A "collection" is a resource whose state consists of not only
+ content and properties, but also a set of named "bindings", where
+ a binding identifies what RFC 2518 calls an "internal member" of
+ the collection. Note that a binding is not a resource, but rather
+ is a part of the state of a collection that defines a mapping from
+ a binding name (a URL segment) to a resource (an internal member
+ of the collection).
+
+ Collection Version Resource
+
+ A "collection version resource", or simply "collection version",
+ captures the dead properties of a version-controlled collection,
+ as well as the names of its version-controlled bindings (see
+ Section 14). A version-controlled binding is a binding to a
+ version-controlled resource. If the checkout-in-place feature is
+ supported, a collection version can be created by checking out and
+ then checking in a version-controlled collection. If the
+ working-resource feature is supported, a collection version can be
+ created by checking out a collection version (to create a "working
+ collection") and then checking in the working collection.
+
+
+
+
+Clemm, et al. Standards Track [Page 68]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Configuration
+
+ A "configuration" is a set of resources that consists of a root
+ collection and all members (not just internal members) of that
+ root collection that are not members of another configuration.
+ The root collection is called the "configuration root", and the
+ members of this set are called the "members of the configuration".
+ Note that a collection (which is a single resource) is very
+ different from a configuration (which is a set of resources).
+
+ Baseline Resource
+
+ A "baseline resource", or simply "baseline", of a collection is a
+ version of the configuration that is rooted at that collection
+ (see Section 12). In particular, a baseline captures the
+ DAV:checked-in version of every version-controlled member of that
+ configuration. Note that a collection version (which captures the
+ state of a single resource) is very different from a collection
+ baseline (which captures the state of a set of resources).
+
+ Baseline-Controlled Collection
+
+ A "baseline-controlled collection" is a collection from which
+ baselines can be created (see Section 12).
+
+ Version-Controlled Configuration Resource
+
+ A "version-controlled configuration resource", or simply
+ "version-controlled configuration", is a special kind of version-
+ controlled resource that is associated with a baseline-controlled
+ collection, and is used to create and access baselines of that
+ collection (see Section 12). When a collection is both version-
+ controlled and baseline-controlled, a client can create a new
+ version of the collection by checking out and checking in that
+ collection, and it can create a new baseline of that collection by
+ checking out and checking in the version-controlled configuration
+ of that collection.
+
+ Activity Resource
+
+ An "activity resource", or simply "activity", is a resource that
+ selects a set of versions that correspond to a single logical
+ change, where the versions selected from a given version history
+ form a single line of descent through that version history (see
+ Section 13).
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 69]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+11 Merge Feature
+
+ When a user wants to accept the changes (new versions) created by
+ someone else, it is important not just to update the version-
+ controlled resources in the user's workspace with those new versions,
+ since this could result in "backing out" changes the user has made to
+ those version-controlled resources. Instead, the versions created in
+ another workspace should be "merged" into the user's version-
+ controlled resources.
+
+ The version history of a version-controlled resource provides the
+ information needed to determine the result of the merge. In
+ particular, the merge should select whichever version is later in the
+ line of descent from the root version. In case the versions to be
+ merged are on different lines of descent (neither version is a
+ descendant of the other), neither version should be selected, but
+ instead, a new version should be created that contains the logical
+ merge of the content and dead properties of those versions. The
+ MERGE request can be used to check out each version-controlled
+ resource that requires such a merge, and set the DAV:merge-set
+ property of each checked-out resource to identify the version to be
+ merged. The user is responsible for modifying the content and dead
+ properties of the checked-out resource so that it represents the
+ logical merge of that version, and then adding that version to the
+ DAV:predecessor-set of the checked-out resource.
+
+ If the server is capable of automatically performing the merge, it
+ MAY update the content, dead properties, and DAV:predecessor-set of
+ the checked-out resource itself. Before checking in the
+ automatically merged resource, the user is responsible for verifying
+ that the automatic merge is correct.
+
+11.1 Additional Checked-Out Resource Properties
+
+ The merge feature introduces the following REQUIRED properties for a
+ checked-out resource.
+
+11.1.1 DAV:merge-set
+
+ This property identifies each version that is to be merged into this
+ checked-out resource.
+
+ <!ELEMENT merge-set (href*)>
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 70]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+11.1.2 DAV:auto-merge-set
+
+ This property identifies each version that the server has merged into
+ this checked-out resource. The client should confirm that the merge
+ has been performed correctly before moving a URL from the DAV:auto-
+ merge-set to the DAV:predecessor-set of a checked-out resource.
+
+ <!ELEMENT auto-merge-set (href*)>
+
+11.2 MERGE Method
+
+ The MERGE method performs the logical merge of a specified version
+ (the "merge source") into a specified version-controlled resource
+ (the "merge target"). If the merge source is neither an ancestor nor
+ a descendant of the DAV:checked-in or DAV:checked-out version of the
+ merge target, the MERGE checks out the merge target (if it is not
+ already checked out) and adds the URL of the merge source to the
+ DAV:merge-set of the merge target. It is then the client's
+ responsibility to update the content and dead properties of the
+ checked-out merge target so that it reflects the logical merge of the
+ merge source into the current state of the merge target. The client
+ indicates that it has completed the update of the merge target, by
+ deleting the merge source URL from the DAV:merge-set of the checked-
+ out merge target, and adding it to the DAV:predecessor-set. As an
+ error check for a client forgetting to complete a merge, the server
+ MUST fail an attempt to CHECKIN a version-controlled resource with a
+ non-empty DAV:merge-set.
+
+ When a server has the ability to automatically update the content and
+ dead properties of the merge target to reflect the logical merge of
+ the merge source, it may do so unless DAV:no-auto-merge is specified
+ in the MERGE request body. In order to notify the client that a
+ merge source has been automatically merged, the MERGE request MUST
+ add the URL of the auto-merged source to the DAV:auto-merge-set
+ property of the merge target, and not to the DAV:merge-set property.
+ The client indicates that it has verified that the auto-merge is
+ valid, by deleting the merge source URL from the DAV:auto-merge-set,
+ and adding it to the DAV:predecessor-set.
+
+ Multiple merge sources can be specified in a single MERGE request.
+ The set of merge sources for a MERGE request is determined from the
+ DAV:source element of the MERGE request body as follows:
+
+ - If DAV:source identifies a version, that version is a merge
+ source.
+ - If DAV:source identifies a version-controlled resource, the
+ DAV:checked-in version of that version-controlled resource is a
+ merge source.
+
+
+
+Clemm, et al. Standards Track [Page 71]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ - If DAV:source identifies a collection, the DAV:checked-in version
+ of each version-controlled resource that is a member of that
+ collection is a merge source.
+
+ The request-URL identifies the set of possible merge targets. If the
+ request-URL identifies a collection, any member of the configuration
+ rooted at the request-URL is a possible merge target. The merge
+ target of a particular merge source is the version-controlled or
+ checked-out resource whose DAV:checked-in or DAV:checked-out version
+ is from the same version history as the merge source. If a merge
+ source has no merge target, that merge source is ignored.
+
+ The MERGE response identifies the resources that a client must modify
+ to complete the merge. It also identifies the resources modified by
+ the request, so that a client can efficiently update any cached state
+ it is maintaining.
+
+ Marshalling:
+
+ The request body MUST be a DAV:merge element.
+
+ The set of merge sources is determined by the DAV:source element
+ in the request body.
+
+ <!ELEMENT merge ANY>
+ ANY value: A sequence of elements with one DAV:source element, at
+ most one DAV:no-auto-merge element, at most one DAV:no-checkout
+ element, at most one DAV:prop element, and any legal set of
+ elements that can occur in a DAV:checkout element.
+ <!ELEMENT source (href+)>
+ <!ELEMENT no-auto-merge EMPTY>
+ <!ELEMENT no-checkout EMPTY>
+ prop: see RFC 2518, Section 12.11
+
+ The response for a successful request MUST be a 207 Multi-Status,
+ where the DAV:multistatus XML element in the response body
+ identifies all resources that have been modified by the request.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response to a successful request MUST include a Location
+ header containing the URL for the new version created by the
+ checkin.
+
+ The response MUST include a Cache-Control:no-cache header.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 72]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:cannot-merge-checked-out-resource): The DAV:source element
+ MUST NOT identify a checked-out resource. If the DAV:source
+ element identifies a collection, the collection MUST NOT have a
+ member that is a checked-out resource.
+
+ (DAV:checkout-not-allowed): If DAV:no-checkout is specified in the
+ request body, it MUST be possible to perform the merge without
+ checking out any of the merge targets.
+
+ All preconditions of the CHECKOUT operation apply to the checkouts
+ performed by the request.
+
+ Postconditions:
+
+ (DAV:ancestor-version): If a merge target is a version-controlled
+ or checked-out resource whose DAV:checked-in version or
+ DAV:checked-out version is the merge source or is a descendant of
+ the merge source, the merge target MUST NOT have been modified by
+ the MERGE.
+
+ (DAV:descendant-version): If the merge target was a checked-in
+ version-controlled resource whose DAV:checked-in version was an
+ ancestor of the merge source, an UPDATE operation MUST have been
+ applied to the merge target to set its content and dead properties
+ to be those of the merge source. If the UPDATE method is not
+ supported, the merge target MUST have been checked out, the
+ content and dead properties of the merge target MUST have been set
+ to those of the merge source, and the merge source MUST have been
+ added to the DAV:auto-merge-set of the merge target. The merge
+ target MUST appear in a DAV:response XML element in the response
+ body.
+
+ (DAV:checked-out-for-merge): If the merge target was a checked-in
+ version-controlled resource whose DAV:checked-in version was
+ neither a descendant nor an ancestor of the merge source, a
+ CHECKOUT MUST have been applied to the merge target. All XML
+ elements in the DAV:merge XML element that could appear in a
+ DAV:checkout XML element MUST have been used as arguments to the
+ CHECKOUT request. The merge target MUST appear in a DAV:response
+ XML element in the response body.
+
+ (DAV:update-merge-set): If the DAV:checked-out version of the
+ merge target is neither equal to nor a descendant of the merge
+ source, the merge source MUST be added to either the DAV:merge-set
+ or the DAV:auto-merge-set of the merge target. The merge target
+ MUST appear in a DAV:response XML element in the response body.
+
+
+
+Clemm, et al. Standards Track [Page 73]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ If a merge source has been added to the DAV:auto-merge-set, the
+ content and dead properties of the merge target MUST have been
+ modified by the server to reflect the result of a logical merge of
+ the merge source and the merge target. If a merge source has been
+ added to the DAV:merge-set, the content and dead properties of the
+ merge target MUST NOT have been modified by the server. If
+ DAV:no-auto-merge is specified in the request body, the merge
+ source MUST NOT have been added to the DAV:auto-merge-set.
+
+ (DAV:report-properties): If DAV:prop is specified in the request
+ body, the properties specified in the DAV:prop element MUST be
+ reported in the DAV:response elements in the response body.
+
+11.2.1 Example - MERGE
+
+ >>REQUEST
+
+ MERGE /ws/public HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:merge xmlns:D="DAV:">
+ <D:source>
+ <D:href>http://www.webdav.org/ws/dev/sally</D:href>
+ </D:source>
+ </D:merge>
+
+ >>RESPONSE
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Cache-Control: no-cache
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.webdav.org/ws/public/src/parse.c</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://www.webdav.org/ws/public/doc/parse.html</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Clemm, et al. Standards Track [Page 74]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the DAV:checked-in versions from the workspace
+ http://www.webdav.org/ws/dev/sally are merged into the version-
+ controlled resources in the workspace
+ http://www.webdav.org/ws/public. The resources
+ /ws/public/src/parse.c and /ws/public/doc/parse.html were modified by
+ the request.
+
+11.3 DAV:merge-preview Report
+
+ A merge preview describes the changes that would result if the
+ versions specified by the DAV:source element in the request body were
+ to be merged into the resource identified by the request-URL
+ (commonly, a collection).
+
+ Marshalling:
+
+ The request body MUST be a DAV:merge-preview XML element.
+
+ <!ELEMENT merge-preview (source)>
+ <!ELEMENT source (href)>
+
+ The response body for a successful request MUST be a
+ DAV:merge-preview-report XML element.
+
+ <!ELEMENT merge-preview-report
+ (update-preview | conflict-preview | ignore-preview)*>
+
+ A DAV:update-preview element identifies a merge target whose
+ DAV:checked-in property would change as a result of the MERGE, and
+ identifies the merge source for that merge target.
+
+ <!ELEMENT update-preview (target, version)>
+ <!ELEMENT target (href)>
+ <!ELEMENT version (href)>
+
+ A DAV:conflict-preview element identifies a merge target that
+ requires a merge.
+
+ <!ELEMENT conflict-preview (target, common-ancestor, version)>
+
+ A DAV:common-ancestor element identifies the version that is a
+ common ancestor of both the merge source and the DAV:checked-in or
+ DAV:checked-out version of the merge target.
+
+ <!ELEMENT common-ancestor (href)>
+
+ A DAV:ignore-preview element identifies a version that has no
+ merge target and therefore would be ignored by the merge.
+
+
+
+Clemm, et al. Standards Track [Page 75]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT ignore-preview (version)>
+
+11.3.1 Example - DAV:merge-preview Report
+
+ >>REQUEST
+
+ REPORT /ws/public HTTP/1.1
+ Host: www.webdav.org
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:merge-preview xmlns:D="DAV:">
+ <D:source>
+ <D:href>http://www.webdav.org/ws/dev/fred</D:href>
+ </D:source>
+ </D:merge-preview>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:merge-preview-report xmlns:D="DAV:">
+ <D:conflict-preview>
+ <D:target>
+ <D:href>http://www.webdav.org/ws/public/foo.html</D:href>
+ </D:target>
+ <D:common-ancestor>
+ <D:href>http://repo.webdav.org/his/23/ver/18</D:href>
+ </D:common-ancestor>
+ <D:version>
+ <D:href>http://repo.webdav.org/his/23/ver/42</D:href>
+ </D:version>
+ </D:conflict-preview>
+ <D:update-preview>
+ <D:target>
+ <D:href>http://www.webdav.org/ws/public/bar.html</D:href>
+ </D:target>
+ <D:version>
+ <D:href>http://www.repo/his/42/ver/3</D:href>
+ </D:version>
+ </D:update-preview>
+ </D:merge-preview-report>
+
+
+
+
+
+Clemm, et al. Standards Track [Page 76]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the merge preview report indicates that version
+ /his/23/ver/42 would be merged in /ws/public/foo.html, and version
+ /his/42/ver/3 would update /ws/public/bar.html if the workspace
+ http://www.webdav.org/ws/dev/fred was merged into the workspace
+ http://www.webdav.org/ws/public.
+
+11.4 Additional OPTIONS Semantics
+
+ If the server supports the merge feature, it MUST include "merge" as
+ a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+11.5 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-version-reference): If a version is deleted, any
+ reference to that version in a DAV:merge-set or DAV:auto-merge-set
+ property MUST be removed.
+
+11.6 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:merge-must-be-complete): The DAV:merge-set and DAV:auto-
+ merge-set of the checked-out resource MUST be empty or not exist.
+
+12 Baseline Feature
+
+ A configuration is a set of resources that consists of a root
+ collection and all members of that root collection except those
+ resources that are members of another configuration. A configuration
+ that contains a large number of resources can consume a large amount
+ of space on a server. This can make it prohibitively expensive to
+ remember the state of an existing configuration by creating a
+ Depth:infinity copy of its root collection.
+
+ A baseline is a version resource that captures the state of each
+ version-controlled member of a configuration. A baseline history is
+ a version history whose versions are baselines. New baselines are
+ created by checking out and then checking in a special kind of
+ version-controlled resource called a version-controlled
+ configuration.
+
+ A collection that is under baseline control is called a baseline-
+ controlled collection. In order to allow efficient baseline
+ implementation, the state of a baseline of a collection is limited to
+
+
+
+Clemm, et al. Standards Track [Page 77]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ be a set of versions and their names relative to the collection, and
+ the operations on a baseline are limited to the creation of a
+ baseline from a collection, and restoring or merging the baseline
+ back into a collection. A server MAY automatically put a collection
+ under baseline control when it is created, or a client can use the
+ BASELINE-CONTROL method to put a specified collection under baseline
+ control.
+
+ As a configuration gets large, it is often useful to break it up into
+ a set of smaller configurations that form the logical "components" of
+ that configuration. In order to capture the fact that a baseline of
+ a configuration is logically extended by a component configuration
+ baseline, the component configuration baseline is captured as a
+ "subbaseline" of the baseline.
+
+ The root collection of a configuration is unconstrained with respect
+ to its relationship to the root collection of any of its components.
+ In particular, the root collection of a configuration can have a
+ member that is the root collection of one of its components (e.g.,
+ configuration /sys/x can have a component /sys/x/foo), can be a
+ member of the root collection of one of its components (e.g.,
+ configuration /sys/y/z can have a component /sys/y), or neither
+ (e.g., configuration /sys/x can have a component /comp/bar).
+
+12.1 Version-Controlled Configuration Properties
+
+ Since a version-controlled configuration is a version-controlled
+ resource, it has all the properties of a version-controlled resource.
+ In addition, the baseline feature introduces the following REQUIRED
+ property for a version-controlled configuration.
+
+12.1.1 DAV:baseline-controlled-collection (protected)
+
+ This property identifies the collection that contains the version-
+ controlled resources whose DAV:checked-in versions are being tracked
+ by this version-controlled configuration. The DAV:version-
+ controlled-configuration of the DAV:baseline-controlled-collection of
+ a version-controlled configuration MUST identify that version-
+ controlled configuration.
+
+ <!ELEMENT baseline-controlled-collection (href)>
+
+12.2 Checked-Out Configuration Properties
+
+ Since a checked-out configuration is a checked-out resource, it has
+ all the properties of a checked-out resource. In addition, the
+ baseline feature introduces the following REQUIRED property for a
+ checked-out configuration.
+
+
+
+Clemm, et al. Standards Track [Page 78]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+12.2.1 DAV:subbaseline-set
+
+ This property determines the DAV:subbaseline-set property of the
+ baseline that results from checking in this resource.
+
+ A server MAY reject attempts to modify the DAV:subbaseline-set of a
+ checked-out configuration.
+
+ <!ELEMENT subbaseline-set (href*)>
+
+12.3 Baseline Properties
+
+ The DAV:resourcetype of a baseline MUST be DAV:baseline. Since a
+ baseline is a version resource, it has all the properties of a
+ version resource. In addition, the baseline feature introduces the
+ following REQUIRED properties for a baseline.
+
+12.3.1 DAV:baseline-collection (protected)
+
+ This property contains a server-defined URL for a collection, where
+ each member of this collection MUST either be a version-controlled
+ resource with the same DAV:checked-in version and relative name as a
+ version-controlled member of the baseline-controlled collection at
+ the time the baseline was created, or be a collection needed to
+ provide the relative name for a version-controlled resource.
+
+ <!ELEMENT baseline-collection (href)>
+
+12.3.2 DAV:subbaseline-set (protected)
+
+ The URLs in the DAV:subbaseline-set property MUST identify a set of
+ other baselines. The subbaselines of a baseline are the baselines
+ identified by its DAV:subbaseline-set and all subbaselines of the
+ baselines identified by its DAV:subbaseline-set.
+
+ <!ELEMENT subbaseline-set (href*)>
+
+12.4 Additional Resource Properties
+
+ The baseline feature introduces the following REQUIRED property for a
+ resource.
+
+12.4.1 DAV:version-controlled-configuration (computed)
+
+ If the resource is a member of a version-controlled configuration
+ (i.e. the resource is a collection under baseline control or is a
+ member of a collection under baseline control), this property
+ identifies that version-controlled configuration.
+
+
+
+Clemm, et al. Standards Track [Page 79]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT version-controlled-configuration (href)>
+
+12.5 Additional Workspace Properties
+
+ The baseline feature introduces the following REQUIRED property for a
+ workspace.
+
+12.5.1 DAV:baseline-controlled-collection-set (computed)
+
+ This property identifies each member of the workspace that is a
+ collection under baseline control (as well as the workspace itself,
+ if it is under baseline control).
+
+ <!ELEMENT baseline-controlled-collection-set (href*)>
+
+12.6 BASELINE-CONTROL Method
+
+ A collection can be placed under baseline control with a
+ BASELINE-CONTROL request. When a collection is placed under baseline
+ control, the DAV:version-controlled-configuration property of the
+ collection is set to identify a new version-controlled configuration.
+ This version-controlled configuration can be checked out and then
+ checked in to create a new baseline for that collection.
+
+ If a baseline is specified in the request body, the DAV:checked-in
+ version of the new version-controlled configuration will be that
+ baseline, and the collection is initialized to contain version-
+ controlled members whose DAV:checked-in versions and relative names
+ are determined by the specified baseline.
+
+ If no baseline is specified, a new baseline history is created
+ containing a baseline that captures the state of the version-
+ controlled members of the collection, and the DAV:checked-in version
+ of the version-controlled configuration will be that baseline.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:baseline-control
+ XML element.
+
+ <!ELEMENT baseline-control ANY>
+ ANY value: A sequence of elements with at most one DAV:baseline
+ element.
+
+ <!ELEMENT baseline (href)>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:baseline-control-response XML element.
+
+
+
+Clemm, et al. Standards Track [Page 80]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ <!ELEMENT baseline-control-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:version-controlled-configuration-must-not-exist): The
+ DAV:version-controlled-configuration property of the collection
+ identified by the request-URL MUST not exist.
+
+ (DAV:must-be-baseline): The DAV:href of the DAV:baseline element
+ in the request body MUST identify a baseline.
+
+ (DAV:must-have-no-version-controlled-members): If a DAV:baseline
+ element is specified in the request body, the collection
+ identified by the request-URL MUST have no version-controlled
+ members.
+
+ (DAV:one-baseline-controlled-collection-per-history-per-
+ workspace): If the request-URL identifies a workspace or a member
+ of a workspace, and if a baseline is specified in a DAV:baseline
+ element in the request body, then there MUST NOT be another
+ collection in that workspace whose DAV:version-controlled-
+ configuration property identifies a version-controlled
+ configuration for the baseline history of that baseline.
+
+ Postconditions:
+
+ (DAV:create-version-controlled-configuration): A new version-
+ controlled configuration is created, whose DAV:baseline-
+ controlled-collection property identifies the collection.
+
+ (DAV:reference-version-controlled-configuration): The
+ DAV:version-controlled-configuration of the collection identifies
+ the new version-controlled configuration.
+
+ (DAV:select-existing-baseline): If the request body specifies a
+ baseline, the DAV:checked-in property of the new version-
+ controlled configuration MUST have been set to identify this
+ baseline. A version-controlled member of the collection will be
+ created for each version in the baseline, where the version-
+ controlled member will have the content and dead properties of
+ that version, and will have the same name relative to the
+ collection as the corresponding version-controlled resource had
+ when the baseline was created. Any nested collections that are
+ needed to provide the appropriate name for a version-controlled
+ member will be created.
+
+
+
+
+Clemm, et al. Standards Track [Page 81]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:create-new-baseline): If no baseline is specified in the
+ request body, the request MUST have created a new baseline history
+ at a server-defined URL, and MUST have created a new baseline in
+ that baseline history. The DAV:baseline-collection of the new
+ baseline MUST identify a collection whose members have the same
+ relative name and DAV:checked-in version as the version-controlled
+ members of the request collection. The DAV:checked-in property of
+ the new version-controlled configuration MUST identify the new
+ baseline.
+
+12.6.1 Example - BASELINE-CONTROL
+
+ >>REQUEST
+
+ BASELINE-CONTROL /src HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:baseline-control xmlns:D="DAV:">
+ <D:href>http://www.webdav.org/repo/blh/13/ver/8</D:href>
+ </D:baseline-control>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+ Content-Length: 0
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 82]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In this example, the collection /src is placed under baseline
+ control, and is populated with members from an existing baseline. A
+ new version-controlled configuration (/repo/vcc/128) is created and
+ associated with /src, and /src is initialized with version-controlled
+ members whose DAV:checked-in versions are those selected by the
+ DAV:baseline-collection (/repo/bc/15) of the specified baseline
+ (/repo/blh/13/ver/8). The following diagram illustrates the
+ resulting state on the server.
+
+ +-------------------------------------+
+ |Baseline-Controlled Collection |<------+
+ |/src | |
+ |-------------------------------------| |
+ |DAV:version-controlled-configuration +---+ |
+ +-------------------------------------+ | |
+ | |
+ | |
+ +-------------------------------------+ | |
+ |Version-Controlled Configuration |<--+ |
+ |/repo/vcc/128 | |
+ |-------------------------------------| |
+ |DAV:baseline-controlled-collection +-------+
+ |-------------------------------------|
+ |DAV:checked-in +-------+
+ +-------------------------------------+ |
+ |DAV:version-history +---+ |
+ +-------------------------------------+ | |
+ | |
+ | |
+ +------------------------+ | |
+ |Baseline History |<---------------+ |
+ |/repo/blh/13 | |
+ |------------------------+ |
+ |DAV:version-set +----------------+ |
+ +------------------------+ | | | | |
+ v | v v |
+ | |
+ +------------------------+ | |
+ |Baseline |<-------+-----------+
+ |/repo/blh/13/ver/8 |
+ |------------------------+ +--------------+
+ |DAV:baseline-collection +---->|Collection |
+ +------------------------+ |/repo/bc/15 |
+ +--------------+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 83]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ In order to create new baselines of /src, /repo/vcc/128 can be
+ checked out, new versions can be created or selected by the version-
+ controlled members of /src, and then /repo/vcc/128 can be checked in
+ to capture the current state of those version-controlled members.
+
+12.7 DAV:compare-baseline Report
+
+ A DAV:compare-baseline report contains the differences between the
+ baseline identified by the request-URL (the "request baseline") and
+ the baseline specified in the request body (the "compare baseline").
+
+ Marshalling:
+
+ The request body MUST be a DAV:compare-baseline XML element.
+
+ <!ELEMENT compare-baseline (href)>
+
+ The response body for a successful request MUST be a DAV:compare-
+ baseline-report XML element.
+
+ <!ELEMENT compare-baseline-report
+ (added-version | deleted-version | changed-version)*>
+
+ A DAV:added-version element identifies a version that is the
+ DAV:checked-in version of a member of the DAV:baseline-collection
+ of the compare baseline, but no version in the version history of
+ that version is the DAV:checked-in version of a member of the
+ DAV:baseline-collection of the request baseline.
+
+ <!ELEMENT added-version (href)>
+
+ A DAV:deleted-version element identifies a version that is the
+ DAV:checked-in version of a member of the DAV:baseline-collection
+ of the request baseline, but no version in the version history of
+ that version is the DAV:checked-in version of a member of the
+ DAV:baseline-collection of the compare baseline.
+
+ <!ELEMENT deleted-version (href)>
+
+ A DAV:changed-version element identifies two different versions
+ from the same version history that are the DAV:checked-in version
+ of the DAV:baseline-collection of the request baseline and the
+ compare baseline, respectively.
+
+ <!ELEMENT changed-version (href, href)>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 84]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Preconditions:
+
+ (DAV:must-be-baseline): The DAV:href in the request body MUST
+ identify a baseline.
+
+ (DAV:baselines-from-same-history): A server MAY require that the
+ baselines being compared be from the same baseline history.
+
+12.7.1 Example - DAV:compare-baseline Report
+
+ >>REQUEST
+
+ REPORT /bl-his/12/bl/14 HTTP/1.1
+ Host: repo.webdav.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:compare-baseline xmlns:D="DAV:">
+ <D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
+ </D:compare-baseline>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:compare-baseline-report xmlns:D="DAV:">
+ <D:added-version>
+ <D:href>http://repo.webdav.org/his/23/ver/8</D:href>
+ </D:added-version>
+ <D:changed-version>
+ <D:href>http://repo.webdav.org/his/29/ver/12</D:href>
+ <D:href>http://repo.webdav.org/his/29/ver/19</D:href>
+ </D:changed-version>
+ <D:deleted-version>
+ <D:href>http://repo.webdav.org/his/12/ver/4</D:href>
+ </D:deleted-version>
+ </D:compare-baseline-report>
+
+ In this example, the differences between baseline 14 and baseline 15
+ of http://repo.webdav.org/bl-his/12 are identified.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 85]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+12.8 Additional OPTIONS Semantics
+
+ If a server supports the baseline feature, it MUST include "baseline"
+ as a field in the DAV response header from an OPTIONS request on any
+ resource that supports any versioning properties, reports, or
+ methods.
+
+12.9 Additional MKCOL Semantics
+
+ Additional Postconditions:
+
+ If a server automatically puts a newly created collection under
+ baseline control, all postconditions for BASELINE-CONTROL apply to
+ the MKCOL.
+
+12.10 Additional COPY Semantics
+
+ Additional Postconditions:
+
+ If the request creates a new collection at the Destination, and a
+ server automatically puts a newly created collection under
+ baseline control, all postconditions for BASELINE-CONTROL apply to
+ the COPY.
+
+12.11 Additional CHECKOUT Semantics
+
+ Additional Preconditions:
+
+ (DAV:must-not-update-baseline-collection): If the request-URL
+ identifies a member of the configuration rooted at the
+ DAV:baseline-collection of a baseline, the request MUST fail.
+
+12.12 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:no-checked-out-baseline-controlled-collection-members): If
+ the request-URL identifies a version-controlled configuration, all
+ version-controlled members of the DAV:baseline-controlled-
+ collection of the version-controlled configuration MUST be
+ checked-in.
+
+ (DAV:one-version-per-history-per-baseline): If the request-URL
+ identifies a version-controlled configuration, the set of versions
+ selected by that version-controlled configuration MUST contain at
+ most one version from any version history, where a version is
+ selected by a version-controlled configuration if the version is
+ identified by the DAV:checked-in property of any member of the
+
+
+
+Clemm, et al. Standards Track [Page 86]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ configuration rooted at the DAV:baseline-controlled collection of
+ that version-controlled configuration, or is identified by the
+ DAV:checked-in property of any member of the configuration rooted
+ at the DAV:baseline-collection of any subbaseline of that
+ version-controlled configuration.
+
+ (DAV:cannot-modify-version-controlled-configuration): If the
+ request-URL identifies a version-controlled member of a baseline-
+ controlled collection whose version-controlled configuration is
+ checked-in, the request MUST fail unless the DAV:auto-version
+ property of the version-controlled configuration will
+ automatically check out that version-controlled configuration when
+ it is modified.
+
+ Additional Postconditions:
+
+ (DAV:create-baseline-collection): If the request-URL identifies a
+ version-controlled configuration, the DAV:baseline-collection of
+ the new baseline identifies a collection whose members have the
+ same relative name and DAV:checked-in version as the members of
+ the DAV:baseline-controlled-collection of the version-controlled
+ configuration at the time of the request.
+
+ (DAV:modify-configuration): If the request-URL identifies a
+ version-controlled member of a baseline-controlled collection,
+ this is a modification to the version-controlled configuration of
+ that baseline-controlled collection, and standard auto-versioning
+ semantics apply.
+
+12.13 Additional UPDATE Semantics
+
+ Additional Preconditions:
+
+ (DAV:baseline-controlled-members-must-be-checked-in): If the
+ request-URL identifies a version-controlled configuration, then
+ all version-controlled members of the DAV:baseline-controlled-
+ collection of that version-controlled configuration MUST be
+ checked-in.
+
+ (DAV:must-not-update-baseline-collection): If the request-URL
+ identifies a member of the configuration rooted at the
+ DAV:baseline-collection of a baseline, the request MUST fail.
+
+ (DAV:cannot-modify-version-controlled-configuration): If the
+ request updates the DAV:checked-in property of any version-
+ controlled member of a baseline-controlled collection whose
+ version-controlled configuration is checked-in, the request MUST
+
+
+
+
+Clemm, et al. Standards Track [Page 87]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ fail unless the DAV:auto-version property of the version-
+ controlled configuration will automatically check out that
+ version-controlled configuration when it is modified.
+
+ Additional Postconditions:
+
+ (DAV:set-baseline-controlled-collection-members): If the request
+ updated the DAV:checked-in property of a version-controlled
+ configuration, then the version-controlled members of the
+ DAV:baseline-controlled-collection of that version-controlled
+ configuration MUST have been updated so that they have the same
+ relative name, content, and dead properties as the members of the
+ DAV:baseline-collection of the baseline. In particular:
+
+ - A version-controlled member for a given version history MUST
+ have been deleted if there is no version-controlled member for
+ that version history in the DAV:baseline-collection of the
+ baseline.
+ - A version-controlled member for a given version history MUST
+ have been renamed if its name relative to the baseline-
+ controlled collection is different from that of the version-
+ controlled member for that version history in the
+ DAV:baseline-collection of the baseline.
+ - A new version-controlled member MUST have been created for each
+ member of the DAV:baseline-collection of the baseline for which
+ there is no corresponding version-controlled member in the
+ baseline-controlled collection.
+ - An UPDATE request MUST have been applied to each version-
+ controlled member for a given version history whose
+ DAV:checked-in version is not the same as that of the version-
+ controlled member for that version history in the
+ DAV:baseline-collection of the baseline.
+
+ (DAV:update-subbaselines): If the request updated a version-
+ controlled configuration whose DAV:baseline-controlled-collection
+ contains a baseline-controlled member for one of the subbaselines
+ of the request baseline, then the DAV:checked-in property of the
+ version-controlled configuration of that baseline-controlled
+ member MUST have been updated to be that subbaseline. If the
+ request updated a version-controlled configuration whose
+ DAV:baseline-controlled-collection is a member of a workspace that
+ contains a baseline-controlled member for one of the subbaselines
+ of the request baseline, then the DAV:checked-in property of the
+ version-controlled configuration of that baseline-controlled
+ member MUST have been updated to be that subbaseline.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 88]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:modify-configuration): If the request updated the
+ DAV:checked-in property of any version-controlled member of a
+ baseline-controlled collection, and if this DAV:checked-in
+ property differs from the DAV:checked-in property of the
+ corresponding version-controlled member of the DAV:baseline-
+ collection of the DAV:checked-in baseline of the DAV:version-
+ controlled-configuration of the baseline-controlled collection,
+ then this is a modification to that version-controlled
+ configuration, and standard auto-versioning semantics apply.
+
+12.14 Additional MERGE Semantics
+
+ If the merge source is a baseline, the merge target is a version-
+ controlled configuration for the baseline history of that baseline,
+ where the baseline-controlled collection of that version-controlled
+ configuration is a member of the collection identified by the
+ request-URL.
+
+ Additional Preconditions:
+
+ (DAV:must-not-update-baseline-collection): Same semantics as
+ UPDATE (see Section 12.13).
+
+ (DAV:cannot-modify-version-controlled-configuration): Same
+ semantics as UPDATE (see Section 12.13).
+
+ Additional Postconditions:
+
+ (DAV:merge-baseline): If the merge target is a version-controlled
+ configuration whose DAV:checked-out baseline is not a descendant
+ of the merge baseline, then the merge baseline MUST have been
+ added to the DAV:auto-merge-set of a version-controlled
+ configuration. The DAV:checked-in version of each member of the
+ DAV:baseline-collection of that baseline MUST have been merged
+ into the DAV:baseline-controlled-collection of that version-
+ controlled configuration.
+
+ (DAV:merge-subbaselines): If the merge target is a version-
+ controlled configuration whose DAV:baseline-controlled-collection
+ contains a baseline-controlled member for one of the subbaselines
+ of the merge baseline, then that subbaseline MUST have been merged
+ into the version-controlled configuration of that baseline-
+ controlled member. If the merge target is a version-controlled
+ configuration whose DAV:baseline-controlled-collection is a member
+ of a workspace that contains a baseline-controlled member for one
+ of the subbaselines of the merge baseline, then that subbaseline
+ MUST have been merged into the version-controlled configuration of
+ that baseline-controlled member.
+
+
+
+Clemm, et al. Standards Track [Page 89]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ (DAV:set-baseline-controlled-collection-members): Same semantics
+ as UPDATE (see Section 12.13).
+
+ (DAV:modify-configuration): Same semantics as UPDATE (see Section
+ 12.13).
+
+13 Activity Feature
+
+ An activity is a resource that selects a set of versions that are on
+ a single "line of descent", where a line of descent is a sequence of
+ versions connected by successor relationships. If an activity
+ selects versions from multiple version histories, the versions
+ selected in each version history must be on a single line of descent.
+
+ A common problem that motivates the use of activities is that it is
+ often desirable to perform several different logical changes in a
+ single workspace, and then selectively merge a subset of those
+ logical changes to other workspaces. An activity can be used to
+ represent a single logical change, where an activity tracks all the
+ resources that were modified to effect that single logical change.
+ When a version-controlled resource is checked out, the user specifies
+ which activity should be associated with a new version that will be
+ created when that version-controlled resource is checked in. It is
+ then possible to select a particular logical change for merging into
+ another workspace, by specifying the appropriate activity in a MERGE
+ request.
+
+ Another common problem is that although a version-controlled resource
+ may need to have multiple lines of descent, all work done by members
+ of a given team must be on a single line of descent (to avoid merging
+ between team members). An activity resource provides the mechanism
+ for addressing this problem. When a version-controlled resource is
+ checked out, a client can request that an existing activity be used
+ or that a new activity be created. Activity semantics then ensure
+ that all versions in a given version history that are associated with
+ an activity are on a single line of descent. If all members of a
+ team share a common activity (or sub-activities of a common
+ activity), then all changes made by members of that team will be on a
+ single line of descent.
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 90]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ The following diagram illustrates activities. Version V5 is the
+ latest version of foo.html selected by activity Act-2, and version V8
+ is the latest version of bar.html selected by activity Act-2.
+
+ foo.html History bar.html History
+
+ +---+ +---+
+ Act-1| |V1 Act-1| |V6
+ +---+ +---+
+ | |
+ | |
+ +---+ +---+
+ Act-1| |V2 Act-2| |V7
+ +---+ +---+
+ / \ |
+ / \ |
+ +---+ +---+ +---+
+ Act-1| |V3 Act-2| |V4 Act-2| |V8
+ +---+ +---+ +---+
+ | |
+ | |
+ +---+ +---+
+ Act-2| |V5 Act-3| |V9
+ +---+ +---+
+
+ Activities appear under a variety of names in existing versioning
+ systems. When an activity is used to capture a logical change, it is
+ commonly called a "change set". When an activity is used to capture
+ a line of descent, it is commonly called a "branch". When a system
+ supports both branches and change sets, it is often useful to require
+ that a particular change set occur on a particular branch. This
+ relationship can be captured by making the change set activity be a
+ "subactivity" of the branch activity.
+
+13.1 Activity Properties
+
+ The DAV:resourcetype of an activity MUST be DAV:activity.
+
+ The activity feature introduces the following REQUIRED properties for
+ an activity.
+
+13.1.1 DAV:activity-version-set (computed)
+
+ This property identifies each version whose DAV:activity-set property
+ identifies this activity. Multiple versions of a single version
+ history can be selected by an activity's DAV:activity-version-set
+
+
+
+
+
+Clemm, et al. Standards Track [Page 91]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ property, but all DAV:activity-version-set versions from a given
+ version history must be on a single line of descent from the root
+ version of that version history.
+
+ <!ELEMENT activity-version-set (href*)>
+
+13.1.2 DAV:activity-checkout-set (computed)
+
+ This property identifies each checked-out resource whose
+ DAV:activity-set identifies this activity.
+
+ <!ELEMENT activity-checkout-set (href*)>
+
+13.1.3 DAV:subactivity-set
+
+ This property identifies each activity that forms a part of the
+ logical change being captured by this activity. An activity behaves
+ as if its DAV:activity-version-set is extended by the DAV:activity-
+ version-set of each activity identified in the DAV:subactivity-set.
+ In particular, the versions in this extended set MUST be on a single
+ line of descent, and when an activity selects a version for merging,
+ the latest version in this extended set is the one that will be
+ merged.
+
+ A server MAY reject attempts to modify the DAV:subactivity-set of an
+ activity.
+
+ <!ELEMENT subactivity-set (href*)>
+
+13.1.4 DAV:current-workspace-set (computed)
+
+ This property identifies each workspace whose DAV:current-activity-
+ set identifies this activity.
+
+ <!ELEMENT current-workspace-set (href*)>
+
+13.2 Additional Version Properties
+
+ The activity feature introduces the following REQUIRED property for a
+ version.
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 92]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.2.1 DAV:activity-set
+
+ This property identifies the activities that determine to which
+ logical changes this version contributes, and on which lines of
+ descent this version appears. A server MAY restrict the
+ DAV:activity-set to identify a single activity. A server MAY refuse
+ to allow the value of the DAV:activity-set property of a version to
+ be modified.
+
+ <!ELEMENT activity-set (href*)>
+
+13.3 Additional Checked-Out Resource Properties
+
+ The activity feature introduces the following REQUIRED properties for
+ a checked-out resource.
+
+13.3.1 DAV:unreserved
+
+ This property of a checked-out resource indicates whether the
+ DAV:activity-set of another checked-out resource associated with the
+ version history of this version-controlled resource can have an
+ activity that is in the DAV:activity-set property of this checked-out
+ resource.
+
+ A result of the requirement that an activity must form a single line
+ of descent through a given version history is that if multiple
+ checked-out resources for a given version history are checked out
+ unreserved into a single activity, only the first CHECKIN will
+ succeed. Before another of these checked-out resources can be
+ checked in, the user will first have to merge into that checked-out
+ resource the latest version selected by that activity from that
+ version history, and then modify the DAV:predecessor-set of that
+ checked-out resource to identify that version.
+
+ <!ELEMENT unreserved (#PCDATA)>
+ PCDATA value: boolean
+
+13.3.2 DAV:activity-set
+
+ This property of a checked-out resource determines the DAV:activity-
+ set property of the version that results from checking in this
+ resource.
+
+13.4 Additional Workspace Properties
+
+ The activity feature introduces the following REQUIRED property for a
+ workspace.
+
+
+
+
+Clemm, et al. Standards Track [Page 93]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.4.1 DAV:current-activity-set
+
+ This property identifies the activities that currently are being
+ performed in this workspace. When a member of this workspace is
+ checked out, if no activity is specified in the checkout request, the
+ DAV:current-activity-set will be used. This allows an activity-
+ unaware client to update a workspace in which activity tracking is
+ required. The DAV:current-activity-set MAY be restricted to identify
+ at most one activity.
+
+ <!ELEMENT current-activity-set (href*)>
+
+13.5 MKACTIVITY Method
+
+ A MKACTIVITY request creates a new activity resource. A server MAY
+ restrict activity creation to particular collections, but a client
+ can determine the location of these collections from a DAV:activity-
+ collection-set OPTIONS request.
+
+ Marshalling:
+
+ If a request body is included, it MUST be a DAV:mkactivity XML
+ element.
+
+ <!ELEMENT mkactivity ANY>
+
+ If a response body for a successful request is included, it MUST
+ be a DAV:mkactivity-response XML element.
+
+ <!ELEMENT mkactivity-response ANY>
+
+ The response MUST include a Cache-Control:no-cache header.
+
+ Preconditions:
+
+ (DAV:resource-must-be-null): A resource MUST NOT exist at the
+ request-URL.
+
+ (DAV:activity-location-ok): The request-URL MUST identify a
+ location where an activity can be created.
+
+ Postconditions:
+
+ (DAV:initialize-activity): A new activity exists at the request-
+ URL. The DAV:resourcetype of the activity MUST be DAV:activity.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 94]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.5.1 Example - MKACTIVITY
+
+ >>REQUEST
+
+ MKACTIVITY /act/test-23 HTTP/1.1
+ Host: repo.webdav.org
+ Content-Length: 0
+
+ >>RESPONSE
+
+ HTTP/1.1 201 Created
+ Cache-Control: no-cache
+
+ In this example, a new activity is created at
+ http://repo.webdav.org/act/test-23.
+
+13.6 DAV:latest-activity-version Report
+
+ The DAV:latest-activity-version report can be applied to a version
+ history to identify the latest version that is selected from that
+ version history by a given activity.
+
+ Marshalling:
+
+ The request body MUST be a DAV:latest-activity-version XML
+ element.
+
+ <!ELEMENT latest-activity-version (href)>
+
+ The response body for a successful request MUST be a DAV:latest-
+ activity-version-report XML element.
+
+ <!ELEMENT latest-activity-version-report (href)>
+
+ The DAV:href of the response body MUST identify the version of the
+ given version history that is a member of the DAV:activity-
+ version-set of the given activity and has no descendant that is a
+ member of the DAV:activity-version-set of that activity.
+
+ Preconditions:
+
+ (DAV:must-be-activity): The DAV:href in the request body MUST
+ identify an activity.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 95]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.7 Additional OPTIONS Semantics
+
+ If the server supports the activity feature, it MUST include
+ "activity" as a field in the DAV response header from an OPTIONS
+ request on any resource that supports any versioning properties,
+ reports, or methods.
+
+ A DAV:activity-collection-set element MAY be included in the request
+ body to identify collections that may contain activity resources.
+
+ Additional Marshalling:
+
+ If an XML request body is included, it MUST be a DAV:options XML
+ element.
+
+ <!ELEMENT options ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:activity-collection-set element.
+
+ If an XML response body for a successful request is included, it
+ MUST be a DAV:options-response XML element.
+
+ <!ELEMENT options-response ANY>
+ ANY value: A sequence of elements with at most one
+ DAV:activity-collection-set element.
+
+ <!ELEMENT activity-collection-set (href*)>
+
+ If DAV:activity-collection-set is included in the request body,
+ the response body for a successful request MUST contain a
+ DAV:activity-collection-set element identifying collections that
+ may contain activities. An identified collection MAY be the root
+ collection of a tree of collections, all of which may contain
+ activities. Since different servers can control different parts
+ of the URL namespace, different resources on the same host MAY
+ have different DAV:activity-collection-set values. The identified
+ collections MAY be located on different hosts from the resource.
+
+13.8 Additional DELETE Semantics
+
+ Additional Postconditions:
+
+ (DAV:delete-activity-reference): If an activity is deleted, any
+ reference to that activity in a DAV:activity-set,
+ DAV:subactivity-set, or DAV:current-activity-set MUST be removed.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 96]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.9 Additional MOVE Semantics
+
+ Additional Postconditions:
+
+ (DAV:update-checked-out-reference): If a checked-out resource is
+ moved, any reference to that resource in a DAV:activity-checkout-
+ set property MUST be updated to refer to the new location of that
+ resource.
+
+ (DAV:update-activity-reference): If the request-URL identifies an
+ activity, any reference to that activity in a DAV:activity-set,
+ DAV:subactivity-set, or DAV:current-activity-set MUST be updated
+ to refer to the new location of that activity.
+
+ (DAV:update-workspace-reference): If the request-URL identifies a
+ workspace, any reference to that workspace in a DAV:current-
+ workspace-set property MUST be updated to refer to the new
+ location of that workspace.
+
+13.10 Additional CHECKOUT Semantics
+
+ A CHECKOUT request MAY specify the DAV:activity-set for the checked-
+ out resource.
+
+ Additional Marshalling:
+
+ <!ELEMENT checkout ANY> ANY value: A sequence of elements with at
+ most one DAV:activity-set and at most one DAV:unreserved.
+
+ <!ELEMENT activity-set (href+ | new)>
+ <!ELEMENT new EMPTY>
+ <!ELEMENT unreserved EMPTY>
+
+ Additional Preconditions:
+
+ (DAV:one-checkout-per-activity-per-history): If there is a request
+ activity set, unless DAV:unreserved is specified, another checkout
+ from a version of that version history MUST NOT select an activity
+ in that activity set.
+
+ (DAV:linear-activity): If there is a request activity set, unless
+ DAV:unreserved is specified, the selected version MUST be a
+ descendant of all other versions of that version history that
+ select that activity.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 97]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:initialize-activity-set): The DAV:activity-set of the
+ checked-out resource is set as follows:
+
+ - If DAV:new is specified as the DAV:activity-set in the request
+ body, then a new activity created by the server is used.
+ - Otherwise, if activities are specified in the request body,
+ then those activities are used.
+ - Otherwise, if the version-controlled resource is a member of a
+ workspace and the DAV:current-activity-set of the workspace is
+ set, then those activities are used.
+ - Otherwise, the DAV:activity-set of the DAV:checked-out version
+ is used.
+
+ (DAV:initialize-unreserved): If DAV:unreserved was specified in
+ the request body, then the DAV:unreserved property of the
+ checked-out resource MUST be "true".
+
+13.10.1 Example - CHECKOUT with an activity
+
+ >>REQUEST
+
+ CHECKOUT /ws/public/foo.html HTTP/1.1
+ Host: www.webdav.org
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:checkout xmlns:D="DAV:">
+ <D:activity-set>
+ <D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
+ </D:activity-set>
+ </D:checkout>
+
+ >>RESPONSE
+
+ HTTP/1.1 200 OK
+ Cache-Control: no-cache
+
+ In this example, the CHECKOUT is being performed in the
+ http://repo.webdav.org/act/fix-bug-23 activity.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 98]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+13.11 Additional CHECKIN Semantics
+
+ Additional Preconditions:
+
+ (DAV:linear-activity): Any version which is in the version history
+ of the checked-out resource and whose DAV:activity-set identifies
+ an activity from the DAV:activity-set of the checked-out resource
+ MUST be an ancestor of the checked-out resource.
+
+ (DAV:atomic-activity-checkin): If the request-URL identifies an
+ activity, the server MAY fail the request if any of the checked-
+ out resources in the DAV:activity-checkout-set of either that
+ activity or any subactivity of that activity cannot be checked in.
+
+ Additional Postconditions:
+
+ (DAV:initialize-activity-set): The DAV:activity-set of the new
+ version MUST have been initialized to be the same as the
+ DAV:activity-set of the checked-out resource.
+
+ (DAV:activity-checkin): If the request-URL identified an activity,
+ the server MUST have successfully applied the CHECKIN request to
+ each checked-out resource in the DAV:activity-checkout-set of both
+ that activity and any subactivity of that activity.
+
+13.12 Additional MERGE Semantics
+
+ If the DAV:source element of the request body identifies an activity,
+ then for each version history containing a version selected by that
+ activity, the latest version selected by that activity is a merge
+ source. Note that the versions selected by an activity are the
+ versions in its DAV:activity-version-set unioned with the versions
+ selected by the activities in its DAV:subactivity-set.
+
+ Additional Marshalling:
+
+ <!ELEMENT checkin-activity EMPTY>
+
+ Additional Postconditions:
+
+ (DAV:checkin-activity): If DAV:checkin-activity is specified in
+ the request body, and if the DAV:source element in the request
+ body identifies an activity, a CHECKIN request MUST have been
+ successfully applied to that activity before the merge sources
+ were determined.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 99]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+14 Version-Controlled-Collection Feature
+
+ As with any versionable resource, when a collection is put under
+ version control, a version history resource is created to contain
+ versions for that version-controlled collection. In order to
+ preserve standard versioning semantics (a version of a collection
+ should not be modifiable), a collection version only records
+ information about the version-controlled bindings of that collection.
+
+ In order to cleanly separate a modification to the namespace from a
+ modification to content or dead properties, a version of a collection
+ has no members, but instead records in its DAV:version-controlled-
+ binding-set property the binding name and version history resource of
+ each version-controlled internal member of that collection. If,
+ instead, a collection version contained bindings to other versions,
+ creating a new version of a resource would require creating a new
+ version of all the collection versions that contain that resource,
+ which would cause activities to become entangled. For example,
+ suppose a "feature-12" activity created a new version of /x/y/a.html.
+ If a collection version contained bindings to versions of its
+ members, a new version of /x/y would have to be created to contain
+ the new version of /x/y/a.html, and a new version of /x would have to
+ be created to contain the new version of /x/y. Now suppose a
+ "bugfix-47" activity created a new version of /x/z/b.html. Again, a
+ new version of /x/z and a new version of /x would have to be created
+ to contain the new version of /x/y/b.html. But now it is impossible
+ to merge just "bugfix-47" into another workspace without "feature-
+ 12", because the version of /x that contains the desired version of
+ /x/z/b.html also contains version of /x/y/a.html created for
+ "feature-12". If, instead, a collection version just records the
+ binding name and version history resource of each version-controlled
+ internal member, changing the version selected by a member of that
+ collection would not require a new version of the collection. The
+ new version is still in the same version history so no new collection
+ version is required, and "feature-12" and "bugfix-47" would not
+ become entangled.
+
+ In the following example, there are three version histories, named
+ VH14, VH19, and VH24, where VH14 contains versions of a collection.
+ The version-controlled collection /x has version V2 of version
+ history VH14 as its DAV:checked-in version. Since V2 has recorded
+ two version controlled bindings, one with binding name "a" to version
+ history VH19, and the other with binding name "b" to version history
+ VH24, /x MUST have two version-controlled bindings, one named "a" to
+ a version-controlled resource for history VH19, and the other named
+ "b" to a version-controlled resource for history VH24. The version-
+
+
+
+
+
+Clemm, et al. Standards Track [Page 100]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ controlled resource /x/a currently has V4 of VH19 as its
+ DAV:checked-in version, while /x/b has V8 of VH24 as its
+ DAV:checked-in version.
+
+ VH19
+ +---------+
+ | +---+ |
+ | | |V4 |
+ | +---+ |
+ | | |
+ | | |
+ | +---+ |
+ | | |V5 |
+ VH14 | +---+ |
+ +---------+ | | |
+ | +---+ | | | |
+ a +---+ | | |V1 | | +---+ |
+ ---->| |checked-in=V4 | +---+ | a | | |V6 |
+ / +---+ | | ------>| +---+ |
+ / | | / | +---------+
+ +---+ | +---+ |
+ /x | |checked-in=V2 | | |V2 |
+ +---+ | +---+ | VH24
+ \ | | \ | b +---------+
+ \ b +---+ | | ------>| +---+ |
+ ---->| |checked-in=V8 | +---+ | | | |V7 |
+ +---+ | | |V3 | | +---+ |
+ | +---+ | | | |
+ +---------+ | | |
+ | +---+ |
+ | | |V8 |
+ | +---+ |
+ | | |
+ | | |
+ | +---+ |
+ | | |V9 |
+ | +---+ |
+ +---------+
+
+ For any request (e.g., DELETE, MOVE, COPY) that modifies a version-
+ controlled binding of a checked-in version-controlled collection, the
+ request MUST fail unless the version-controlled collection has a
+ DAV:auto-version property that will automatically check out the
+ version-controlled collection when it is modified.
+
+ Although a collection version only records the version-controlled
+ bindings of a collection, a version-controlled collection MAY contain
+ both version-controlled and non-version-controlled bindings. Non-
+
+
+
+Clemm, et al. Standards Track [Page 101]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ version-controlled bindings are not under version control, and
+ therefore can be added or deleted without checking out the version-
+ controlled collection.
+
+ Note that a collection version captures only a defined subset of the
+ state of a collection. In particular, a version of a collection
+ captures its dead properties and its bindings to version-controlled
+ resources, but not its live properties or bindings to non-version-
+ controlled resources.
+
+ When a server supports the working-resource feature, a client can
+ check out a collection version to create a working collection.
+ Unlike a version-controlled collection, which contains bindings to
+ version-controlled resources and non-version-controlled resources, a
+ working collection contains bindings to version history resources and
+ non-version-controlled resources. In particular, a working
+ collection is initialized to contain bindings to the version history
+ resources specified by the DAV:version-controlled-binding-set of the
+ checked out collection version. The members of a working collection
+ can then be deleted or moved to another working collection. Non-
+ version-controlled resources can be added to a working collection
+ with methods such as PUT, COPY, and MKCOL. When a working collection
+ is checked in, a VERSION-CONTROL request is automatically applied to
+ every non-version-controlled member of the working collection, and
+ each non-version-controlled member is replaced by its newly created
+ version history. The DAV:version-controlled-binding-set of the new
+ version resulting from checking in a working collection contains the
+ binding name and version history URL for each member of the working
+ collection.
+
+14.1 Version-Controlled Collection Properties
+
+ A version-controlled collection has all the properties of a
+ collection and of a version-controlled resource. In addition, the
+ version-controlled-collection feature introduces the following
+ REQUIRED property for a version-controlled collection.
+
+14.1.1 DAV:eclipsed-set (computed)
+
+ This property identifies the non-version-controlled internal members
+ of the collection that currently are eclipsing a version-controlled
+ internal member of the collection.
+
+ !ELEMENT eclipsed-set (binding-name*)>
+ <!ELEMENT binding-name (#PCDATA)>
+ PCDATA value: URL segment
+
+
+
+
+
+Clemm, et al. Standards Track [Page 102]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ An UPDATE or MERGE request can give a version-controlled collection a
+ version-controlled internal member that has the same name as an
+ existing non-version-controlled internal member. In this case, the
+ non-version-controlled internal member takes precedence and is said
+ to "eclipse" the new versioned-controlled internal member. If the
+ non-version-controlled internal member is removed (e.g., by a DELETE
+ or MOVE), the version-controlled internal member is exposed.
+
+14.2 Collection Version Properties
+
+ A collection version has all the properties of a version. In
+ addition, the version-controlled-collection feature introduces the
+ following REQUIRED property for a collection version.
+
+14.2.1 DAV:version-controlled-binding-set (protected)
+
+ This property captures the name and version-history of each version-
+ controlled internal member of a collection.
+
+ <!ELEMENT version-controlled-binding-set
+ (version-controlled-binding*)>
+ <!ELEMENT version-controlled-binding
+ (binding-name, version-history)>
+ <!ELEMENT binding-name (#PCDATA)>
+ PCDATA value: URL segment
+ <!ELEMENT version-history (href)>
+
+14.3 Additional OPTIONS Semantics
+
+ If the server supports the version-controlled-collection feature, it
+ MUST include "version-controlled-collection" as a field in the DAV
+ response header from an OPTIONS request on any resource that supports
+ any versioning properties, reports, or methods.
+
+14.4 Additional DELETE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the request-URL
+ identifies a version-controlled resource, the DELETE MUST fail
+ when the collection containing the version-controlled resource is
+ a checked-in version-controlled collection, unless DAV:auto-
+ version semantics will automatically check out the version-
+ controlled collection.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 103]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+14.5 Additional MKCOL Semantics
+
+ Additional Preconditions:
+
+ If the request creates a new resource that is automatically placed
+ under version control, all preconditions for VERSION-CONTROL apply
+ to the request.
+
+ Additional Postconditions:
+
+ If the new collection is automatically put under version control,
+ all postconditions for VERSION-CONTROL apply to the request.
+
+14.6 Additional COPY Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-copy-collection-version): If the source of the request
+ is a collection version, the request MUST fail.
+
+14.7 Additional MOVE Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the source of the
+ request is a version-controlled resource, the request MUST fail
+ when the collection containing the source is a checked-in
+ version-controlled collection, unless DAV:auto-version semantics
+ will automatically check out that version-controlled collection.
+
+ (DAV:cannot-modify-destination-checked-in-parent): If the source
+ of the request is a version-controlled resource, the request MUST
+ fail when the collection containing the destination is a checked-
+ in version-controlled collection, unless DAV:auto-version
+ semantics will automatically check out that version-controlled
+ collection.
+
+14.8 Additional VERSION-CONTROL Semantics
+
+ Additional Preconditions:
+
+ (DAV:cannot-modify-checked-in-parent): If the parent of the
+ request-URL is a checked-in version-controlled collection, the
+ request MUST fail unless DAV:auto-version semantics will
+ automatically check out that version-controlled collection.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 104]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Additional Postconditions:
+
+ (DAV:new-version-controlled-collection): If the request body
+ identified a collection version, the collection at the request-URL
+ MUST contain a version-controlled internal member for each
+ DAV:version-controlled-binding specified in the DAV:version-
+ controlled-binding-set of the collection version, where the name
+ and DAV:version-history of the internal member MUST be the
+ DAV:binding-name and the DAV:version-history specified by the
+ DAV:version-controlled-binding. If the internal member is a
+ member of a workspace, and there is another member of the
+ workspace for the same version history, those two members MUST
+ identify the same version-controlled resource; otherwise, a
+ VERSION-CONTROL request with a server selected version of the
+ version history MUST have been applied to the URL for that
+ internal member.
+
+14.9 Additional CHECKOUT Semantics
+
+ Additional Postconditions:
+
+ (DAV:initialize-version-history-bindings): If the request has been
+ applied to a collection version, the new working collection MUST
+ be initialized to contain a binding to each of the history
+ resources identified in the DAV:version-controlled-binding-set of
+ that collection version.
+
+14.10 Additional CHECKIN Semantics
+
+ Additional Postconditions:
+
+ (DAV:initialize-version-controlled-bindings): If the request-URL
+ identified a version-controlled collection, then the DAV:version-
+ controlled-binding-set of the new collection version MUST contain
+ a DAV:version-controlled-binding that identifies the binding name
+ and version history for each version-controlled binding of the
+ version- controlled collection.
+
+ (DAV:version-control-working-collection-members): If the request-
+ URL identified a working collection, a VERSION-CONTROL request
+ MUST have been automatically applied to every non-version-
+ controlled member of the working collection, and each non-
+ version-controlled member MUST have been replaced by its newly
+ created version history. If a working collection member was a
+ non-version-controlled collection, every member of the non-
+ version-controlled collection MUST have been placed under version
+
+
+
+
+
+Clemm, et al. Standards Track [Page 105]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ control before the non-version-controlled collection was placed
+ under version control. The DAV:version-controlled-binding-set of
+ the new collection version MUST contain a DAV:version-controlled-
+ binding that identifies the binding name and the version history
+ URL for each member of the working collection.
+
+14.11 Additional UPDATE and MERGE Semantics
+
+ Additional Postconditions:
+
+ (DAV:update-version-controlled-collection-members): If the request
+ modified the DAV:checked-in version of a version-controlled
+ collection, then the version-controlled members of that version-
+ controlled collection MUST have been updated. In particular:
+
+ - A version-controlled internal member MUST have been deleted if
+ its version history is not identified by the DAV:version-
+ controlled-binding-set of the new DAV:checked-in version.
+ - A version-controlled internal member for a given version
+ history MUST have been renamed if its binding name differs from
+ the DAV:binding-name for that version history in the
+ DAV:version-controlled-binding-set of the new DAV:checked-in
+ version.
+ - A new version-controlled internal member MUST have been created
+ when a version history is identified by the DAV:version-
+ controlled-binding-set of the DAV:checked-in version, but there
+ was no member of the version-controlled collection for that
+ version history. If a new version-controlled member is in a
+ workspace that already has a version-controlled resource for
+ that version history, then the new version-controlled member
+ MUST be just a binding (i.e., another name for) that existing
+ version-controlled resource. Otherwise, the content and dead
+ properties of the new version-controlled member MUST have been
+ initialized to be those of the version specified for that
+ version history by the request. If no version is specified for
+ that version history by the request, the version selected is
+ server defined.
+
+15 Internationalization Considerations
+
+ This specification has been designed to be compliant with the IETF
+ Policy on Character Sets and Languages [RFC2277]. Specifically,
+ where human-readable strings exist in the protocol, either their
+ charset is explicitly stated, or XML mechanisms are used to specify
+ the charset used. Additionally, these human-readable strings all
+ have the ability to express the natural language of the string.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 106]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Most of the human-readable strings in this protocol appear in
+ properties, such as DAV:creator-displayname. As defined by RFC 2518,
+ properties have their values marshaled as XML. XML has explicit
+ provisions for character set tagging and encoding, and requires that
+ XML processors read XML elements encoded, at minimum, using the UTF-8
+ [RFC2279] encoding of the ISO 10646 multilingual plane. The charset
+ parameter of the Content-Type header, together with the XML
+ "encoding" attribute, provide charset identification information for
+ MIME and XML processors. Proper use of the charset header with XML
+ is described in RFC 3023. XML also provides a language tagging
+ capability for specifying the language of the contents of a
+ particular XML element. XML uses either IANA registered language
+ tags (see RFC 3066) or ISO 639 language tags in the "xml:lang"
+ attribute of an XML element to identify the language of its content
+ and attributes.
+
+ DeltaV applications, since they build upon WebDAV, are subject to the
+ internationalization requirements specified in RFC 2518, Section 16.
+ In brief, these requirements mandate the use of XML character set
+ tagging, character set encoding, and language tagging capabilities.
+ Additionally, they strongly recommend reading RFC 3023 for
+ instruction on the use of MIME media types for XML transport and the
+ use of the charset header.
+
+ Within this specification, a label is a human-readable string that is
+ marshaled in the Label header and as XML in request entity bodies.
+ When used in the Label header, the value of the label is URL-escaped
+ and encoded using UTF-8.
+
+16 Security Considerations
+
+ All of the security considerations of WebDAV discussed in RFC 2518,
+ Section 17 also apply to WebDAV versioning. Some aspects of the
+ versioning protocol help address security risks introduced by WebDAV,
+ but other aspects can increase these security risks. These issues
+ are detailed below.
+
+16.1 Auditing and Traceability
+
+ WebDAV increases the ease with which a remote client can modify
+ resources on a web site, but this also increases the risk of
+ important information being overwritten and lost, either through user
+ error or user maliciousness. The use of WebDAV versioning can help
+ address this problem by guaranteeing that previous information is
+ saved in the form of immutable versions, and therefore is easily
+ available for retrieval or restoration. In addition, the version
+ history provides a log of when changes were made, and by whom. When
+ requests are appropriately authenticated, the history mechanism
+
+
+
+Clemm, et al. Standards Track [Page 107]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ provides a clear audit trail for changes to web resources. This can
+ often significantly improve the ability to identify the source of the
+ security problem, and thereby help guard against it in the future.
+
+16.2 Increased Need for Access Control
+
+ WebDAV versioning provides a variety of links between related pieces
+ of information. This can increase the risk that authentication or
+ authorization errors allow a client to locate sensitive information.
+ For example, if version history is not appropriately protected by
+ access control, a client can use the version history of a public
+ resource to identify later versions of that resource that the user
+ intended to keep private. This increases the need for reliable
+ authentication and accurate authorization.
+
+ A WebDAV versioning client should be designed to handle a mixture of
+ 200 (OK) and 403 (Forbidden) responses on attempts to access the
+ properties and reports that are supported by a resource. For
+ example, a particular user may be authorized to access the content
+ and dead properties of a version-controlled resource, but not be
+ authorized to access the DAV:checked-in, DAV:checked-out, or
+ DAV:version-history properties of that resource.
+
+16.3 Security Through Obscurity
+
+ While it is acknowledged that "obscurity" is not an effective means
+ of security, it is often a good technique to keep honest people
+ honest. Within this protocol, version URLs, version history URLs,
+ and working resource URLs are generated by the server and can be
+ properly obfuscated so as not to draw attention to them. For
+ example, a version of "http://foobar.com/reviews/salaries.html" might
+ be assigned a URL such as "http://foobar.com/repo/4934943".
+
+16.4 Denial of Service
+
+ The auto-versioning mechanism provided by WebDAV can result in a
+ large number of resources being created on the server, since each
+ update to a resource could potentially result in the creation of a
+ new version resource. This increases the risk of a denial of service
+ attack that exhausts the storage capability of a server. This risk
+ is especially significant because it can be an unintentional result
+ of something like an aggressive auto-save feature provided by an
+ editing client. A server can decrease this risk by using delta
+ storage techniques to minimize the cost of additional versions, and
+ by limiting auto-versioning to a locking client, and thereby
+ decreasing the number of inadvertent version creations.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 108]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+17 IANA Considerations
+
+ This document uses the namespace defined by RFC 2518 for XML
+ elements. All other IANA considerations from RFC 2518 are also
+ applicable to WebDAV Versioning.
+
+18 Intellectual Property
+
+ The following notice is copied from RFC 2026, Section 10.4, and
+ describes the position of the IETF concerning intellectual property
+ claims made against this document.
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+ pertain to the implementation or use other technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; neither does it represent that it
+ has made any effort to identify any such rights. Information on the
+ procedures of the IETF with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such
+ proprietary rights by implementers or users of this specification can
+ be obtained from the IETF Secretariat.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+
+19 Acknowledgements
+
+ This protocol is the collaborative product of the authors and the
+ rest of the DeltaV design team: Boris Bokowski, Bruce Cragun
+ (Novell), Jim Doubek (Macromedia), David Durand (INSO), Lisa
+ Dusseault (Xythos), Chuck Fay (FileNet), Yaron Goland, Mark Hale
+ (Interwoven), Henry Harbury (Merant), James Hunt, Jeff McAffer (OTI),
+ Peter Raymond (Merant), Juergen Reuter, Edgar Schwarz (Marconi), Eric
+ Sedlar (Oracle), Bradley Sergeant, Greg Stein, and John Vasta
+ (Rational). We would like to acknowledge the foundation laid for us
+ by the authors of the WebDAV and HTTP protocols upon which this
+ protocol is layered, and the invaluable feedback from the WebDAV and
+ DeltaV working groups.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 109]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+20 References
+
+ [ISO639] ISO, "Code for the representation of names of languages",
+ ISO 639:1988, 1998.
+
+ [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
+ 3", BCP 9, RFC 2026, October 1996.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
+ Languages", BCP 18, RFC 2277, January 1998.
+
+ [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
+ RFC 2279, January 1998.
+
+ [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
+ Resource Identifiers (URI): Generic Syntax", RFC 2396,
+ August 1998.
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D.
+ Jensen, "HTTP Extensions for Distributed Authoring -
+ WEBDAV", RFC 2518, February 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.
+
+ [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types",
+ RFC 3023, January 2001.
+
+ [RFC3066] Alvestrand, H., "Tags for the Identification of Languages",
+ BCP 47, RFC 3066, January 2001.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 110]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Appendix A - Resource Classification
+
+ This document introduces several different kinds of versioning
+ resources, such as version-controlled resources, versions, checked-
+ out resources, and version history resources. As clients discover
+ resources on a server, they may find it useful to classify those
+ resources (for example, to make UI decisions on choice of icon and
+ menu options).
+
+ Clients should classify a resource by examining the values of the
+ DAV:supported-method-set (see Section 3.1.3) and DAV:supported-live-
+ property-set (see Section 3.1.4) properties of that resource.
+
+ The following list shows the supported live properties and methods
+ for each kind of versioning resource. Where an optional feature
+ introduces a new kind of versioning resource, that feature is noted
+ in parentheses following the name of that kind of versioning
+ resource. If a live property or method is optional for a kind of
+ versioning resource, the feature that introduces that live property
+ or method is noted in parentheses following the live property or
+ method name.
+
+A.1 DeltaV-Compliant Unmapped URL (a URL that identifies no resource)
+
+ Supported methods:
+
+ - PUT [RFC2616]
+ - MKCOL [RFC2518]
+ - MKACTIVITY (activity)
+ - VERSION-CONTROL (workspace)
+ - MKWORKSPACE (workspace)
+
+A.2 DeltaV-Compliant Resource
+
+ Supported live properties:
+
+ - DAV:comment
+ - DAV:creator-displayname
+ - DAV:supported-method-set
+ - DAV:supported-live-property-set
+ - DAV:supported-report-set
+ - all properties defined in WebDAV [RFC2518].
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 111]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Supported methods:
+
+ - REPORT
+ - all methods defined in WebDAV [RFC2518]
+ - all methods defined in HTTP/1.1 [RFC2616].
+
+A.3 DeltaV-Compliant Collection
+
+ Supported live properties:
+
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - BASELINE-CONTROL (baseline)
+ - all DeltaV-compliant resource methods.
+
+A.4 Versionable Resource
+
+ Supported live properties:
+
+ - DAV:workspace (workspace)
+ - DAV:version-controlled-configuration (baseline)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - VERSION-CONTROL
+ - all DeltaV-compliant resource methods.
+
+A.5 Version-Controlled Resource
+
+ Supported live properties:
+
+ - DAV:auto-version
+ - DAV:version-history (version-history)
+ - DAV:workspace (workspace)
+ - DAV:version-controlled-configuration (baseline)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - VERSION-CONTROL
+ - MERGE (merge)
+ - all DeltaV-compliant resource methods.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 112]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.6 Version
+
+ Supported live properties:
+
+ - DAV:predecessor-set
+ - DAV:successor-set
+ - DAV:checkout-set
+ - DAV:version-name
+ - DAV:checkout-fork (in-place-checkout or working resource)
+ - DAV:checkin-fork (in-place-checkout or working resource)
+ - DAV:version-history (version-history)
+ - DAV:label-name-set (label)
+ - DAV:activity-set (activity)
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - LABEL (label)
+ - CHECKOUT (working-resource)
+ - all DeltaV-compliant resource methods.
+
+A.7 Checked-In Version-Controlled Resource
+
+ Supported live properties:
+
+ - DAV:checked-in
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - CHECKOUT (checkout-in-place)
+ - UPDATE (update)
+ - all version-controlled resource methods.
+
+A.8 Checked-Out Resource
+
+ Supported live properties:
+
+ - DAV:checked-out
+ - DAV:predecessor-set
+ - DAV:checkout-fork (in-place-checkout or working resource)
+ - DAV:checkin-fork (in-place-checkout or working resource)
+ - DAV:merge-set (merge)
+ - DAV:auto-merge-set (merge)
+ - DAV:unreserved (activity)
+ - DAV:activity-set (activity)
+
+
+
+
+
+Clemm, et al. Standards Track [Page 113]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+ Supported methods:
+
+ - CHECKIN (checkout-in-place or working-resource)
+ - all DeltaV-compliant resource methods.
+
+A.9 Checked-Out Version-Controlled Resource (checkout-in-place)
+
+ Supported live properties:
+
+ - all version-controlled resource properties.
+ - all checked-out resource properties.
+
+ Supported methods:
+
+ - UNCHECKOUT
+ - all version-controlled resource methods.
+ - all checked-out resource methods.
+
+A.10 Working Resource (working-resource)
+
+ Supported live properties:
+
+ - all DeltaV-compliant resource properties
+ - all checked-out resource properties
+ - DAV:auto-update.
+
+ Supported methods:
+
+ - all checked-out resource methods.
+
+A.11 Version History (version-history)
+
+ Supported live properties:
+
+ - DAV:version-set
+ - DAV:root-version
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant resource methods.
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 114]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.12 Workspace (workspace)
+
+ Supported live properties:
+
+ - DAV:workspace-checkout-set
+ - DAV:baseline-controlled-collection-set (baseline)
+ - DAV:current-activity-set (activity)
+ - all DeltaV-compliant collection properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant collection methods.
+
+A.13 Activity (activity)
+
+ Supported live properties:
+
+ - DAV:activity-version-set
+ - DAV:activity-checkout-set
+ - DAV:subactivity-set
+ - DAV:current-workspace-set
+ - all DeltaV-compliant resource properties.
+
+ Supported methods:
+
+ - all DeltaV-compliant resource methods.
+
+A.14 Version-Controlled Collection (version-controlled-collection)
+
+ Supported live properties:
+
+ - DAV:eclipsed-set
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - all version-controlled resource methods.
+
+A.15 Collection Version (version-controlled-collection)
+
+ Supported live properties:
+
+ - DAV:version-controlled-binding-set
+ - all version properties.
+
+ Supported methods:
+
+ - all version methods.
+
+
+
+Clemm, et al. Standards Track [Page 115]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+A.16 Version-Controlled Configuration (baseline)
+
+ Supported live properties:
+
+ - DAV:baseline-controlled-collection
+ - all version-controlled resource properties.
+
+ Supported methods:
+
+ - all version-controlled resource methods.
+
+A.17 Baseline (baseline)
+
+ Supported live properties:
+
+ - DAV:baseline-collection
+ - DAV:subbaseline-set
+ - all version properties.
+
+ Supported methods:
+
+ - all version methods.
+
+A.18 Checked-Out Version-Controlled Configuration (baseline)
+
+ Supported live properties:
+
+ - DAV:subbaseline-set
+ - all version-controlled configuration properties.
+
+ Supported methods:
+
+ - all version-controlled configuration methods.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 116]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Authors' Addresses
+
+ Geoffrey Clemm
+ Rational Software
+ 20 Maguire Road, Lexington, MA 02421
+
+ EMail: geoffrey.clemm at rational.com
+
+
+ Jim Amsden
+ IBM
+ 3039 Cornwallis, Research Triangle Park, NC 27709
+
+ EMail: jamsden at us.ibm.com
+
+
+ Tim Ellison
+ IBM
+ Hursley Park, Winchester, UK S021 2JN
+
+ EMail: tim_ellison at uk.ibm.com
+
+
+ Christopher Kaler
+ Microsoft
+ One Microsoft Way, Redmond, WA 90852
+
+ EMail: ckaler at microsoft.com
+
+
+ Jim Whitehead
+ UC Santa Cruz, Dept. of Computer Science
+ 1156 High Street, Santa Cruz, CA 95064
+
+ EMail: ejw at cse.ucsc.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 117]
+
+RFC 3253 Versioning Extensions to WebDAV March 2002
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 118]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc3253.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3253.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc3253.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,6611 +0,0 @@
-
-
-
-
-
-
-Network Working Group G. Clemm
-Request for Comments: 3253 Rational Software
-Category: Standards Track J. Amsden
- T. Ellison
- IBM
- C. Kaler
- Microsoft
- J. Whitehead
- U.C. Santa Cruz
- March 2002
-
-
- Versioning Extensions to WebDAV
- (Web Distributed Authoring and Versioning)
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document specifies a set of methods, headers, and resource types
- that define the WebDAV (Web Distributed Authoring and Versioning)
- versioning extensions to the HTTP/1.1 protocol. WebDAV versioning
- will minimize the complexity of clients that are capable of
- interoperating with a variety of versioning repository managers, to
- facilitate widespread deployment of applications capable of utilizing
- the WebDAV Versioning services. WebDAV versioning includes automatic
- versioning for versioning-unaware clients, version history
- management, workspace management, baseline management, activity
- management, and URL namespace versioning.
-
-Table of Contents
-
- 1 Introduction.................................................... 6
- 1.1 Relationship to WebDAV........................................ 7
- 1.2 Notational Conventions........................................ 8
- 1.3 Terms......................................................... 8
- 1.4 Property Values............................................... 11
- 1.4.1 Initial Property Value..................................... 11
-
-
-
-Clemm, et al. Standards Track [Page 1]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- 1.4.2 Protected Property Value................................... 12
- 1.4.3 Computed Property Value.................................... 12
- 1.4.4 Boolean Property Value..................................... 12
- 1.4.5 DAV:href Property Value.................................... 12
- 1.5 DAV Namespace XML Elements.................................... 12
- 1.6 Method Preconditions and Postconditions....................... 12
- 1.6.1 Example - CHECKOUT request................................. 13
- 1.7 Clarification of COPY Semantics with Overwrite:T.............. 13
- 1.8 Versioning Methods and Write Locks............................ 14
- 2 Basic Versioning Features....................................... 14
- 2.1 Basic Versioning Packages..................................... 14
- 2.2 Basic Versioning Semantics.................................... 16
- 2.2.1 Creating a Version-Controlled Resource..................... 16
- 2.2.2 Modifying a Version-Controlled Resource.................... 17
- 2.2.3 Reporting.................................................. 19
- 3 Version-Control Feature......................................... 20
- 3.1 Additional Resource Properties................................ 20
- 3.1.1 DAV:comment................................................ 20
- 3.1.2 DAV:creator-displayname.................................... 20
- 3.1.3 DAV:supported-method-set (protected)....................... 20
- 3.1.4 DAV:supported-live-property-set (protected)................ 21
- 3.1.5 DAV:supported-report-set (protected)....................... 21
- 3.2 Version-Controlled Resource Properties........................ 21
- 3.2.1 DAV:checked-in (protected)................................. 21
- 3.2.2 DAV:auto-version........................................... 22
- 3.3 Checked-Out Resource Properties............................... 22
- 3.3.1 DAV:checked-out (protected)................................ 23
- 3.3.2 DAV:predecessor-set........................................ 23
- 3.4 Version Properties............................................ 23
- 3.4.1 DAV:predecessor-set (protected)............................ 23
- 3.4.2 DAV:successor-set (computed)............................... 23
- 3.4.3 DAV:checkout-set (computed)................................ 23
- 3.4.4 DAV:version-name (protected)............................... 24
- 3.5 VERSION-CONTROL Method........................................ 24
- 3.5.1 Example - VERSION-CONTROL.................................. 25
- 3.6 REPORT Method................................................. 25
- 3.7 DAV:version-tree Report....................................... 26
- 3.7.1 Example - DAV:version-tree Report.......................... 27
- 3.8 DAV:expand-property Report.................................... 29
- 3.8.1 Example - DAV:expand-property.............................. 30
- 3.9 Additional OPTIONS Semantics.................................. 31
- 3.10 Additional PUT Semantics..................................... 31
- 3.11 Additional PROPFIND Semantics................................ 32
- 3.12 Additional PROPPATCH Semantics............................... 33
- 3.13 Additional DELETE Semantics.................................. 33
- 3.14 Additional COPY Semantics.................................... 34
- 3.15 Additional MOVE Semantics.................................... 34
- 3.16 Additional UNLOCK Semantics.................................. 35
-
-
-
-Clemm, et al. Standards Track [Page 2]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- 4 Checkout-In-Place Feature....................................... 35
- 4.1 Additional Version Properties................................. 35
- 4.1.1 DAV:checkout-fork.......................................... 36
- 4.1.2 DAV:checkin-fork........................................... 36
- 4.2 Checked-Out Resource Properties............................... 36
- 4.2.1 DAV:checkout-fork.......................................... 36
- 4.2.2 DAV:checkin-fork........................................... 37
- 4.3 CHECKOUT Method............................................... 37
- 4.3.1 Example - CHECKOUT......................................... 38
- 4.4 CHECKIN Method................................................ 38
- 4.4.1 Example - CHECKIN.......................................... 40
- 4.5 UNCHECKOUT Method............................................. 40
- 4.5.1 Example - UNCHECKOUT....................................... 41
- 4.6 Additional OPTIONS Semantics.................................. 42
- 5 Version-History Feature......................................... 42
- 5.1 Version History Properties.................................... 42
- 5.1.1 DAV:version-set (protected)................................ 42
- 5.1.2 DAV:root-version (computed)................................ 42
- 5.2 Additional Version-Controlled Resource Properties............. 42
- 5.2.1 DAV:version-history (computed)............................. 43
- 5.3 Additional Version Properties................................. 43
- 5.3.1 DAV:version-history (computed)............................. 43
- 5.4 DAV:locate-by-history Report.................................. 43
- 5.4.1 Example - DAV:locate-by-history Report..................... 44
- 5.5 Additional OPTIONS Semantics.................................. 45
- 5.6 Additional DELETE Semantics................................... 46
- 5.7 Additional COPY Semantics..................................... 46
- 5.8 Additional MOVE Semantics..................................... 46
- 5.9 Additional VERSION-CONTROL Semantics.......................... 46
- 5.10 Additional CHECKIN Semantics................................. 47
- 6 Workspace Feature............................................... 47
- 6.1 Workspace Properties.......................................... 48
- 6.1.1 DAV:workspace-checkout-set (computed)...................... 48
- 6.2 Additional Resource Properties................................ 48
- 6.2.1 DAV:workspace (protected).................................. 48
- 6.3 MKWORKSPACE Method............................................ 48
- 6.3.1 Example - MKWORKSPACE...................................... 49
- 6.4 Additional OPTIONS Semantics.................................. 49
- 6.4.1 Example - OPTIONS.......................................... 51
- 6.5 Additional DELETE Semantics................................... 51
- 6.6 Additional MOVE Semantics..................................... 52
- 6.7 Additional VERSION-CONTROL Semantics.......................... 52
- 6.7.1 Example - VERSION-CONTROL.................................. 53
- 7 Update Feature.................................................. 53
- 7.1 UPDATE Method................................................. 53
- 7.1.1 Example - UPDATE........................................... 55
- 7.2 Additional OPTIONS Semantics.................................. 55
- 8 Label Feature................................................... 56
-
-
-
-Clemm, et al. Standards Track [Page 3]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- 8.1 Additional Version Properties................................. 56
- 8.1.1 DAV:label-name-set (protected)............................. 56
- 8.2 LABEL Method.................................................. 56
- 8.2.1 Example - Setting a label.................................. 58
- 8.3 Label Header.................................................. 58
- 8.4 Additional OPTIONS Semantics.................................. 59
- 8.5 Additional GET Semantics...................................... 59
- 8.6 Additional PROPFIND Semantics................................. 59
- 8.7 Additional COPY Semantics..................................... 60
- 8.8 Additional CHECKOUT Semantics................................. 60
- 8.9 Additional UPDATE Semantics................................... 61
- 9 Working-Resource Feature........................................ 62
- 9.1 Additional Version Properties................................. 62
- 9.1.1 DAV:checkout-fork.......................................... 62
- 9.1.2 DAV:checkin-fork........................................... 63
- 9.2 Working Resource Properties................................... 63
- 9.2.1 DAV:auto-update (protected)................................ 63
- 9.2.2 DAV:checkout-fork.......................................... 63
- 9.2.3 DAV:checkin-fork........................................... 63
- 9.3 CHECKOUT Method (applied to a version)........................ 63
- 9.3.1 Example - CHECKOUT of a version............................ 65
- 9.4 CHECKIN Method (applied to a working resource)................ 65
- 9.4.1 Example - CHECKIN of a working resource.................... 66
- 9.5 Additional OPTIONS Semantics.................................. 67
- 9.6 Additional COPY Semantics..................................... 67
- 9.7 Additional MOVE Semantics..................................... 67
- 10 Advanced Versioning Features.................................. 67
- 10.1 Advanced Versioning Packages................................. 68
- 10.2 Advanced Versioning Terms.................................... 68
- 11 MERGE Feature................................................. 70
- 11.1 Additional Checked-Out Resource Properties................... 70
- 11.1.1 DAV:merge-set............................................. 70
- 11.1.2 DAV:auto-merge-set........................................ 71
- 11.2 MERGE Method................................................. 71
- 11.2.1 Example - MERGE........................................... 74
- 11.3 DAV:merge-preview Report..................................... 75
- 11.3.1 Example - DAV:merge-preview Report........................ 76
- 11.4 Additional OPTIONS Semantics................................. 77
- 11.5 Additional DELETE Semantics.................................. 77
- 11.6 Additional CHECKIN Semantics................................. 77
- 12 Baseline Feature.............................................. 77
- 12.1 Version-Controlled Configuration Properties.................. 78
- 12.1.1 DAV:baseline-controlled-collection (protected)............ 78
- 12.2 Checked-Out Configuration Properties......................... 78
- 12.2.1 DAV:subbaseline-set....................................... 78
- 12.3 Baseline Properties.......................................... 78
- 12.3.1 DAV:baseline-collection (protected)....................... 79
- 12.3.2 DAV:subbaseline-set (protected)........................... 79
-
-
-
-Clemm, et al. Standards Track [Page 4]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- 12.4 Additional Resource Properties............................... 79
- 12.4.1 DAV:version-controlled-configuration (computed)........... 79
- 12.5 Additional Workspace Properties.............................. 80
- 12.5.1 DAV:baseline-controlled-collection-set (computed)......... 80
- 12.6 BASELINE-CONTROL Method...................................... 80
- 12.6.1 Example - BASELINE-CONTROL................................ 82
- 12.7 DAV:compare-baseline Report.................................. 84
- 12.7.1 Example - DAV:compare-baseline Report..................... 85
- 12.8 Additional OPTIONS Semantics................................. 86
- 12.9 Additional MKCOL Semantics................................... 86
- 12.10 Additional COPY Semantics................................... 86
- 12.11 Additional CHECKOUT Semantics............................... 86
- 12.12 Additional CHECKIN Semantics................................ 86
- 12.13 Additional UPDATE Semantics................................. 87
- 12.14 Additional MERGE Semantics.................................. 89
- 13 Activity Feature.............................................. 90
- 13.1 Activity Properties.......................................... 91
- 13.1.1 DAV:activity-version-set (computed)....................... 91
- 13.1.2 DAV:activity-checkout-set (computed)...................... 92
- 13.1.3 DAV:subactivity-set....................................... 92
- 13.1.4 DAV:current-workspace-set (computed)...................... 92
- 13.2 Additional Version Properties................................ 92
- 13.2.1 DAV:activity-set.......................................... 93
- 13.3 Additional Checked-Out Resource Properties................... 93
- 13.3.1 DAV:unreserved............................................ 93
- 13.3.2 DAV:activity-set.......................................... 93
- 13.4 Additional Workspace Properties.............................. 93
- 13.4.1 DAV:current-activity-set.................................. 94
- 13.5 MKACTIVITY Method............................................ 94
- 13.5.1 Example - MKACTIVITY...................................... 95
- 13.6 DAV:latest-activity-version Report........................... 95
- 13.7 Additional OPTIONS Semantics................................. 96
- 13.8 Additional DELETE Semantics.................................. 96
- 13.9 Additional MOVE Semantics.................................... 97
- 13.10 Additional CHECKOUT Semantics............................... 97
- 13.10.1 Example - CHECKOUT with an activity...................... 98
- 13.11 Additional CHECKIN Semantics................................ 99
- 13.12 Additional MERGE Semantics.................................. 99
- 14 Version-Controlled-Collection Feature.........................100
- 14.1 Version-Controlled Collection Properties.....................102
- 14.1.1 DAV:eclipsed-set (computed)...............................102
- 14.2 Collection Version Properties................................103
- 14.2.1 DAV:version-controlled-binding-set (protected)............103
- 14.3 Additional OPTIONS Semantics.................................103
- 14.4 Additional DELETE Semantics..................................103
- 14.5 Additional MKCOL Semantics...................................104
- 14.6 Additional COPY Semantics....................................104
- 14.7 Additional MOVE Semantics....................................104
-
-
-
-Clemm, et al. Standards Track [Page 5]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- 14.8 Additional VERSION-CONTROL Semantics.........................104
- 14.9 Additional CHECKOUT Semantics................................105
- 14.10 Additional CHECKIN Semantics................................105
- 14.11 Additional UPDATE and MERGE Semantics.......................106
- 15 Internationalization Considerations...........................106
- 16 Security Considerations.......................................107
- 16.1 Auditing and Traceability....................................107
- 16.2 Increased Need for Access Control............................108
- 16.3 Security Through Obscurity...................................108
- 16.4 Denial of Service............................................108
- 17 IANA Considerations...........................................109
- 18 Intellectual Property.........................................109
- 19 Acknowledgements..............................................109
- 20 References....................................................110
- Appendix A - Resource Classification..............................111
- A.1 DeltaV-Compliant Unmapped URL.................................111
- A.2 DeltaV-Compliant Resource.....................................111
- A.3 DeltaV-Compliant Collection...................................112
- A.4 Versionable Resource..........................................112
- A.5 Version-Controlled Resource...................................112
- A.6 Version.......................................................113
- A.7 Checked-In Version-Controlled Resource........................113
- A.8 Checked-Out Resource..........................................113
- A.9 Checked-Out Version-Controlled Resource.......................114
- A.10 Working Resource.............................................114
- A.11 Version History..............................................114
- A.12 Workspace....................................................115
- A.13 Activity.....................................................115
- A.14 Version-Controlled Collection................................115
- A.15 Collection Version...........................................115
- A.16 Version-Controlled Configuration.............................116
- A.17 Baseline.....................................................116
- A.18 Checked-Out Version-Controlled Configuration.................116
- Authors' Addresses................................................117
- Full Copyright Statement..........................................118
-
-1 Introduction
-
- This document specifies a set of methods, headers, and properties
- that define the WebDAV (Web Distributed Authoring and Versioning)
- versioning extensions to the HTTP/1.1 protocol. Versioning is
- concerned with tracking and accessing the history of important states
- of a web resource, such as a standalone web page. The benefits of
- versioning in the context of the worldwide web include:
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 6]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- - A resource has an explicit history and a persistent identity
- across the various states it has had during the course of that
- history. It allows browsing through past and alternative versions
- of a resource. Frequently the modification and authorship history
- of a resource is critical information in itself.
-
- - Resource states (versions) are given stable names that can support
- externally stored links for annotation and link server support.
- Both annotation and link servers frequently need to store stable
- references to portions of resources that are not under their
- direct control. By providing stable states of resources, version
- control systems allow not only stable pointers into those
- resources, but also well defined methods to determine the
- relationships of those states of a resource.
-
- WebDAV Versioning defines both basic and advanced versioning
- functionality.
-
- Basic versioning allows users to:
-
- - Put a resource under version control
- - Determine whether a resource is under version control
- - Determine whether a resource update will automatically be captured
- as a new version
- - Create and access distinct versions of a resource
-
- Advanced versioning provides additional functionality for parallel
- development and configuration management of sets of web resources.
-
- This document will first define the properties and method semantics
- for the basic versioning features, and then define the additional
- properties and method semantics for the advanced versioning features.
- An implementer that is only interested in basic versioning should
- skip the advanced versioning sections (Section 10 to Section 14).
-
-1.1 Relationship to WebDAV
-
- To maximize interoperability and the use of existing protocol
- functionality, versioning support is designed as extensions to the
- WebDAV protocol [RFC2518], which itself is an extension to the HTTP
- protocol [RFC2616]. All method marshalling and postconditions
- defined by RFC 2518 and RFC 2616 continue to hold, to ensure that
- versioning unaware clients can interoperate successfully with
- versioning servers. Although the versioning extensions are designed
- to be orthogonal to most aspects of the WebDAV and HTTP protocols, a
- clarification to RFC 2518 is required for effective interoperable
- versioning. This clarification is described in Section 1.7.
-
-
-
-
-Clemm, et al. Standards Track [Page 7]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-1.2 Notational Conventions
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in RFC 2119.
-
- The term "protected" is placed in parentheses following the
- definition of a protected property (see Section 1.4.2).
-
- The term "computed" is placed in parentheses following the definition
- of a computed property (see Section 1.4.3).
-
- When an XML element type in the "DAV:" namespace is referenced in
- this document outside of the context of an XML fragment, the string
- "DAV:" will be prefixed to the element type.
-
- When a method is defined in this document, a list of preconditions
- and postconditions will be defined for that method. If the semantics
- of an existing method is being extended, a list of additional
- preconditions and postconditions will be defined. A precondition or
- postcondition is prefixed by a parenthesized XML element type that
- identifies that precondition or postcondition (see Section 1.6).
-
-1.3 Terms
-
- This document uses the terms defined in RFC 2616, in RFC 2518, and in
- this section. Section 2.2 defines the semantic versioning model
- underlying this terminology.
-
- Version Control, Checked-In, Checked-Out
-
- "Version control" is a set of constraints on how a resource can be
- updated. A resource under version control is either in a
- "checked-in" or "checked-out" state, and the version control
- constraints apply only while the resource is in the checked-in
- state.
-
- Versionable Resource
-
- A "versionable resource" is a resource that can be put under
- version control.
-
- Version-Controlled Resource
-
- When a versionable resource is put under version control, it
- becomes a "version-controlled resource". A version-controlled
- resource can be "checked out" to allow modification of its content
- or dead properties by standard HTTP and WebDAV methods.
-
-
-
-Clemm, et al. Standards Track [Page 8]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Checked-Out Resource
-
- A "checked-out resource" is a resource under version control that
- is in the checked-out state.
-
- Version Resource
-
- A "version resource", or simply "version", is a resource that
- contains a copy of a particular state (content and dead
- properties) of a version-controlled resource. A version is
- created by "checking in" a checked-out resource. The server
- allocates a distinct new URL for each new version, and this URL
- will never be used to identify any resource other than that
- version. The content and dead properties of a version never
- change.
-
- Version History Resource
-
- A "version history resource", or simply "version history", is a
- resource that contains all the versions of a particular version-
- controlled resource.
-
- Version Name
-
- A "version name" is a string chosen by the server to distinguish
- one version of a version history from the other versions of that
- version history. Versions from different version histories may
- have the same version name.
-
- Predecessor, Successor, Ancestor, Descendant
-
- When a version-controlled resource is checked out and then
- subsequently checked in, the version that was checked out becomes
- a "predecessor" of the version created by the checkin. A client
- can specify multiple predecessors for a new version if the new
- version is logically a merge of those predecessors. When a
- version is connected to another version by traversing one or more
- predecessor relations, it is called an "ancestor" of that version.
- The inverse of the predecessor and ancestor relations are the
- "successor" and "descendant" relations. Therefore, if X is a
- predecessor of Y, then Y is a successor of X, and if X is an
- ancestor of Y, then Y is a descendant of X.
-
- Root Version Resource
-
- The "root version resource", or simply "root version", is the
- version in a version history that is an ancestor of every other
- version in that version history.
-
-
-
-Clemm, et al. Standards Track [Page 9]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Workspace Resource
-
- A "workspace resource", or simply "workspace", is a collection
- that contains at most one version-controlled resource for a given
- version history (see Section 6).
-
- Working Resource
-
- A "working resource" is a checked-out resource created by the
- server at a server-defined URL when a version (instead of a
- version-controlled resource) is checked out. Unlike a checked-out
- version-controlled resource, a working resource is deleted when it
- is checked in.
-
- Fork, Merge
-
- When a second successor is added to a version, this creates a
- "fork" in the version history. When a version is created with
- multiple predecessors, this creates a "merge" in the version
- history. A server may restrict the version history to be linear
- (with no forks or merges), but an interoperable versioning client
- should be prepared to deal with both forks and merges in the
- version history.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 10]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The following diagram illustrates several of the previous
- definitions. Each box represents a version and each line between two
- boxes represents a predecessor/successor relationship. For example,
- it shows V3 is a predecessor of V5, V7 is a successor of V5, V1 is an
- ancestor of V4, and V7 is a descendant of V4. It also shows that
- there is a fork at version V2 and a merge at version V7.
-
- History of foo.html
-
- +---+
- Root Version -------> | | V1
- +---+ ^
- | |
- | |
- +---+ |
- Version Name ----> V2 | | | Ancestor
- +---+ |
- / \ |
- / \ |
- +---+ +---+
- | | V3 | | V4
- ^ +---+ +---+
- | | | |
- Predecessor | | | |
- +---+ +---+ |
- | | V5 | | V6 | Descendant
- +---+ +---+ |
- Successor | \ / |
- | \ / |
- v +---+ v
- | | V7
- +---+
-
- Label
-
- A "label" is a name that can be used to select a version from a
- version history. A label can be assigned by either a client or
- the server. The same label can be used in different version
- histories.
-
-1.4 Property Values
-
-1.4.1 Initial Property Value
-
- Unless an initial value of a property of a given type is defined by
- this document, the initial value of a property of that type is
- implementation dependent.
-
-
-
-
-Clemm, et al. Standards Track [Page 11]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-1.4.2 Protected Property Value
-
- When a property of a specific kind of resource is "protected", the
- property value cannot be updated on that kind of resource except by a
- method explicitly defined as updating that specific property. In
- particular, a protected property cannot be updated with a PROPPATCH
- request. Note that a given property can be protected on one kind of
- resource, but not protected on another kind of resource.
-
-1.4.3 Computed Property Value
-
- When a property is "computed", its value is defined in terms of a
- computation based on the content and other properties of that
- resource, or even of some other resource. When the semantics of a
- method is defined in this document, the effect of that method on
- non-computed properties will be specified; the effect of that method
- on computed properties will not be specified, but can be inferred
- from the computation defined for those properties. A computed
- property is always a protected property.
-
-1.4.4 Boolean Property Value
-
- Some properties take a Boolean value of either "false" or "true".
-
-1.4.5 DAV:href Property Value
-
- The DAV:href XML element is defined in RFC 2518, Section 12.3.
-
-1.5 DAV Namespace XML Elements in Request and Response Bodies
-
- Although WebDAV request and response bodies can be extended by
- arbitrary XML elements, which can be ignored by the message
- recipient, an XML element in the DAV namespace MUST NOT be used in
- the request or response body of a versioning method unless that XML
- element is explicitly defined in an IETF RFC.
-
-1.6 Method Preconditions and Postconditions
-
- A "precondition" of a method describes the state of the server that
- must be true for that method to be performed. A "postcondition" of a
- method describes the state of the server that must be true after that
- method has been completed. If a method precondition or postcondition
- for a request is not satisfied, the response status of the request
- MUST be either 403 (Forbidden) if the request should not be repeated
- because it will always fail, or 409 (Conflict) if it is expected that
- the user might be able to resolve the conflict and resubmit the
- request.
-
-
-
-
-Clemm, et al. Standards Track [Page 12]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In order to allow better client handling of 403 and 409 responses, a
- distinct XML element type is associated with each method precondition
- and postcondition of a request. When a particular precondition is
- not satisfied or a particular postcondition cannot be achieved, the
- appropriate XML element MUST be returned as the child of a top-level
- DAV:error element in the response body, unless otherwise negotiated
- by the request. In a 207 Multi-Status response, the DAV:error
- element would appear in the appropriate DAV:responsedescription
- element.
-
-1.6.1 Example - CHECKOUT request with DAV:must-be-checked-in response
-
- >>REQUEST
-
- CHECKOUT /foo.html HTTP/1.1
- Host: www.webdav.org
-
- >>RESPONSE
-
- HTTP/1.1 409 Conflict
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:must-be-checked-in/>
- </D:error>
-
- In this example, the request to CHECKOUT /foo.html fails because
- /foo.html is not checked in.
-
-1.7 Clarification of COPY Semantics with Overwrite:T
-
- RFC 2518, Section 8.8.4 states:
-
- "If a resource exists at the destination and the Overwrite header is
- "T" then prior to performing the copy the server MUST perform a
- DELETE with "Depth: infinity" on the destination resource."
-
- The purpose of this sentence is to ensure that following a COPY, all
- destination resources have the same content and dead properties as
- the corresponding resources identified by the request-URL (where a
- resource with a given name relative to the Destination URL
- "corresponds" to a resource with the same name relative to the
- request-URL). If at the time of the request, there already is a
- resource at the destination that has the same resource type as the
- corresponding resource at the request-URL, that resource MUST NOT be
- deleted, but MUST be updated to have the content and dead properties
-
-
-
-Clemm, et al. Standards Track [Page 13]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- of its corresponding member. If a client wishes all resources at the
- destination to be deleted prior to the COPY, it MUST explicitly issue
- a DELETE request.
-
- The difference between updating a resource and replacing a resource
- with a new resource is especially important when resource history is
- being maintained (the former adds to an existing history, while the
- latter creates a new history). In addition, locking and access
- control constraints might allow you to update a resource, but not
- allow you to delete it and create a new one in its place.
-
- Note that this clarification does not apply to a MOVE request. A
- MOVE request with Overwrite:T MUST perform the DELETE with
- "Depth:infinity" on the destination resource prior to performing the
- MOVE.
-
-1.8 Versioning Methods and Write Locks
-
- If a write-locked resource has a non-computed property defined by
- this document, the property value MUST NOT be changed by a request
- unless the appropriate lock token is included in the request. Since
- every method introduced in this document other than REPORT modifies
- at least one property defined by this document, every versioning
- method other than REPORT is affected by a write lock. In particular,
- the method MUST fail with a 423 (Locked) status if the resource is
- write-locked and the appropriate token is not specified in an If
- request header.
-
-2 Basic Versioning Features
-
- Each basic versioning feature defines extensions to existing HTTP and
- WebDAV methods, as well as new resource types, live properties, and
- methods.
-
-2.1 Basic Versioning Packages
-
- A server MAY support any combination of versioning features.
- However, in order to minimize the complexity of a WebDAV basic
- versioning client, a WebDAV basic versioning server SHOULD support
- one of the following three "packages" (feature sets):
-
- - Core-Versioning Package: version-control
- - Basic-Server-Workspace Package: version-control, workspace,
- version-history, checkout
- - Basic-Client-Workspace Package: version-control, working-
- resource, update, label
-
-
-
-
-
-Clemm, et al. Standards Track [Page 14]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The core-versioning package supports linear versioning by both
- versioning-aware and versioning-unaware clients. A versioning-aware
- client can use reports and properties to access previous versions of
- a version-controlled resource.
-
- The basic workspace packages support parallel development of
- version-controlled resources. Each client has its own configuration
- of the shared version-controlled resources, and can make changes to
- its configuration without disturbing that of another client.
-
- In the basic-server-workspace package, all persistent state is
- maintained on the server. Each client has its own workspace resource
- allocated on the server, where each workspace identifies a
- configuration of the shared version-controlled resources. Each
- client makes changes to its workspace, and can transfer changes when
- appropriate from one workspace to another. The server workspace
- package is appropriate for clients with no local persistent state, or
- for clients that wish to expose their working configurations to other
- clients.
-
- In the basic-client-workspace package, each client maintains in local
- persistent storage the state for its configuration of the shared
- version-controlled resources. When a client is ready to make its
- changes visible to other clients, it allocates a set of "working
- resources" on the server, updates the content and dead properties of
- these working resources, and then uses the set of working resources
- to update the version-controlled resources. The working resources
- are used, instead of directly updating the version-controlled
- resources, so that sets of consistent updates can be prepared in
- parallel by multiple clients. Also, a working resource allows a
- client to prepare a single update that requires multiple server
- requests (e.g. updating both the content and dead properties of a
- resource requires both a PUT and a PROPPATCH). The client workspace
- package simplifies the server implementation by requiring each client
- to maintain its own namespace, but this requires that the clients
- have local persistent state, and does not allow clients to expose
- their working configurations to other clients.
-
- A server that supports both basic workspace packages will
- interoperate with all basic versioning clients.
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 15]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-2.2 Basic Versioning Semantics
-
-2.2.1 Creating a Version-Controlled Resource
-
- In order to track the history of the content and dead properties of a
- versionable resource, a user can put the resource under version
- control with a VERSION-CONTROL request. A VERSION-CONTROL request
- performs three distinct operations:
-
- 1) It creates a new "version history resource". In basic versioning,
- a version history resource is not assigned a URL, and hence is not
- visible in the http scheme URL space. However, when the version-
- history feature (see Section 5) is supported, this changes, and
- each version history resource is assigned a new distinct and
- unique server-defined URL.
-
- 2) It creates a new "version resource" and adds it to the new version
- history resource. The body and dead properties of the new version
- resource are a copy of those of the versionable resource.
-
- The server assigns the new version resource a new distinct and
- unique URL.
-
- 3) It converts the versionable resource into a "version-controlled
- resource". The version-controlled resource continues to be
- identified by the same URL that identified it as a versionable
- resource. As part of this conversion, it adds a DAV:checked-in
- property, whose value contains the URL of the new version
- resource.
-
- Note that a versionable resource and a version-controlled resource
- are not new types of resources (i.e. they introduce no new
- DAV:resourcetype), but rather they are any type of resource that
- supports the methods and live properties defined for them in this
- document, in addition to all the methods and live properties implied
- by their DAV:resourcetype. For example, a collection (whose
- DAV:resourcetype is DAV:collection) is a versionable resource if it
- supports the VERSION-CONTROL method, and is a version-controlled
- resource if it supports the version-controlled resource methods and
- live properties.
-
- In the following example, foo.html is a versionable resource that is
- put under version control. After the VERSION-CONTROL request
- succeeds, there are two additional resources: a new version history
- resource and a new version resource in that version history. The
- versionable resource is converted into a version-controlled resource,
- whose DAV:checked-in property identifies the new version resource.
-
-
-
-
-Clemm, et al. Standards Track [Page 16]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The content and dead properties of a resource are represented by the
- symbol appearing inside the box for that resource (e.g., "S1" in the
- following example).
-
- ===VERSION-CONTROL==>
-
- | +----+ version
- | version- | | history
- versionable | controlled +----+ resource
- resource | resource |
- /foo.html | /foo.html |
- | v
- +----+ | +----+ checked-in +----+ version
- | S1 | | | S1 |----------->| S1 | resource
- +----+ | +----+ +----+ /his/73/ver/1
-
- Thus, whereas before the VERSION-CONTROL request there was only one,
- non-version-controlled resource, after VERSION-CONTROL there are
- three separate, distinct resources, each containing its own state and
- properties: the version-controlled resource, the version resource,
- and the version history resource. Since the version-controlled
- resource and the version resource are separate, distinct resources,
- when a method is applied to a version-controlled resource, it is only
- applied to that version-controlled resource, and is not applied to
- the version resource that is currently identified by the
- DAV:checked-in property of that version-controlled resource.
- Although the content and dead properties of a checked-in version-
- controlled resource are required to be the same as those of its
- current DAV:checked-in version, its live properties may differ. An
- implementation may optimize storage by retrieving the content and
- dead properties of a checked-in version-controlled resource from its
- current DAV:checked-in version rather than storing them in the
- version-controlled resource, but this is just an implementation
- optimization.
-
- Normally, a resource is placed under version control with an explicit
- VERSION-CONTROL request. A server MAY automatically place every new
- versionable resource under version control. In this case, the
- resulting state on the server MUST be the same as if the client had
- explicitly applied a VERSION-CONTROL request to the versionable
- resource.
-
-2.2.2 Modifying a Version-Controlled Resource
-
- In order to use methods like PUT and PROPPATCH to directly modify the
- content or dead properties of a version-controlled resource, the
- version-controlled resource must first be checked out. When the
- checked-out resource is checked in, a new version is created in the
-
-
-
-Clemm, et al. Standards Track [Page 17]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- version history of that version-controlled resource. The version
- that was checked out is remembered as the predecessor of the new
- version.
-
- The DAV:auto-version property (see Sections 3.2.2) of a checked-in
- version-controlled resource determines how it responds to a method
- that attempts to modify its content or dead properties. Possible
- responses include:
-
- - Fail the request. The resource requires an explicit CHECKOUT
- request for it to be modified (see Sections 4 and 9.2.1).
-
- - Automatically checkout the resource, perform the modification, and
- automatically checkin the resource. This ensures that every state
- of the resource is tracked by the server, but can result in an
- excessive number of versions being created.
-
- - Automatically checkout the resource, perform the modification, and
- then if the resource is not write-locked, automatically checkin
- the resource. If the resource is write-locked, it remains
- checked-out until the write-lock is removed (either explicitly
- through a subsequent UNLOCK request or implicitly through a time-
- out of the write-lock). This helps a locking client avoid the
- proliferation of versions, while still allowing a non-locking
- client to update the resource.
-
- - Automatically checkout the resource, perform the modification, and
- then leave the resource checked out. If the resource is write-
- locked, it will be automatically checked in when the write-lock is
- removed, but an explicit CHECKIN operation (see Section 4.4) is
- required for a non-write-locked resource. This minimizes the
- number of new versions that will be created by a versioning
- unaware client, but only a versioning aware client can create new
- versions of a non-write-locked resource.
-
- - Fail the request unless the resource is write-locked. If it is
- write-locked, automatically checkout the resource and perform the
- modification. The resource is automatically checked in when the
- write-lock is removed. This minimizes the number of new versions
- that will be created by a versioning unaware client, but never
- automatically checks out a resource that will not subsequently be
- automatically checked in.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 18]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The following diagram illustrates the effect of the checkout/checkin
- process on a version-controlled resource and its version history.
- The symbol inside a box (S1, S2, S3) represents the current content
- and dead properties of the resource represented by that box. The
- symbol next to a box (V1, V2, V3) represents the URL for that
- resource.
-
- ===checkout==> ===PUT==> ===checkin==>
-
-
- /foo.html (version-controlled resource)
-
- +----+ | +----+ | +----+ | +----+
- | S2 | | | S2 | | | S3 | | | S3 |
- +----+ | +----+ | +----+ | +----+
- Checked-In=V2|Checked-Out=V2|Checked-Out=V2|Checked-In=V3
-
-
- /his/73 (version history for /foo.html)
-
- +----+ | +----+ | +----+ | +----+
- | S1 | V1 | | S1 | V1 | | S1 | V1 | | S1 | V1
- +----+ | +----+ | +----+ | +----+
- | | | | | | |
- | | | | | | |
- +----+ | +----+ | +----+ | +----+
- | S2 | V2 | | S2 | V2 | | S2 | V2 | | S2 | V2
- +----+ | +----+ | +----+ | +----+
- | | | |
- | | | |
- | | | +----+
- | | | | S3 | V3
- | | | +----+
-
- Note that a version captures only a defined subset of the state of a
- resource. In particular, a version of a basic resource captures its
- content and dead properties, but not its live properties.
-
-2.2.3 Reporting
-
- Some versioning information about a resource requires that parameters
- be specified along with that request for information. Included in
- basic versioning is the required support for an extensible reporting
- mechanism, which includes a REPORT method as well as a live property
- for determining what reports are supported by a particular resource.
- The REPORT method is required by versioning, but it can be used in
- non-versioning WebDAV extensions.
-
-
-
-
-Clemm, et al. Standards Track [Page 19]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- To allow a client to query the properties of all versions in the
- version history of a specified version-controlled resource, basic
- versioning provides the DAV:version-tree report (see Section 3.7). A
- more powerful version history reporting mechanism is provided by
- applying the DAV:expand-property report (see Section 3.8) to a
- version history resource (see Section 5).
-
-3 Version-Control Feature
-
- The version-control feature provides support for putting a resource
- under version control, creating an associated version-controlled
- resource and version history resource as described in Section 2.2.1.
- A server indicates that it supports the version-control feature by
- including the string "version-control" as a field in the DAV header
- in the response to an OPTIONS request. The version-control feature
- MUST be supported if any other versioning feature is supported.
-
-3.1 Additional Resource Properties
-
- The version-control feature introduces the following REQUIRED
- properties for any WebDAV resource.
-
-3.1.1 DAV:comment
-
- This property is used to track a brief comment about a resource that
- is suitable for presentation to a user. The DAV:comment of a version
- can be used to indicate why that version was created.
-
- <!ELEMENT comment (#PCDATA)>
- PCDATA value: string
-
-3.1.2 DAV:creator-displayname
-
- This property contains a description of the creator of the resource
- that is suitable for presentation to a user. The DAV:creator-
- displayname of a version can be used to indicate who created that
- version.
-
- <!ELEMENT creator-displayname (#PCDATA)>
- PCDATA value: string
-
-3.1.3 DAV:supported-method-set (protected)
-
- This property identifies the methods that are supported by the
- resource. A method is supported by a resource if there is some state
- of that resource for which an application of that method will
-
-
-
-
-
-Clemm, et al. Standards Track [Page 20]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- successfully satisfy all postconditions of that method, including any
- additional postconditions added by the features supported by that
- resource.
-
- <!ELEMENT supported-method-set (supported-method*)>
- <!ELEMENT supported-method ANY>
- <!ATTLIST supported-method name NMTOKEN #REQUIRED>
- name value: a method name
-
-3.1.4 DAV:supported-live-property-set (protected)
-
- This property identifies the live properties that are supported by
- the resource. A live property is supported by a resource if that
- property has the semantics defined for that property. The value of
- this property MUST identify all live properties defined by this
- document that are supported by the resource, and SHOULD identify all
- live properties that are supported by the resource.
-
- <!ELEMENT supported-live-property-set (supported-live-property*)>
- <!ELEMENT supported-live-property name>
- <!ELEMENT prop ANY>
- ANY value: a property element type
-
-3.1.5 DAV:supported-report-set (protected)
-
- This property identifies the reports that are supported by the
- resource.
-
- <!ELEMENT supported-report-set (supported-report*)>
- <!ELEMENT supported-report report>
- <!ELEMENT report ANY>
- ANY value: a report element type
-
-3.2 Version-Controlled Resource Properties
-
- The version-control feature introduces the following REQUIRED
- properties for a version-controlled resource.
-
-3.2.1 DAV:checked-in (protected)
-
- This property appears on a checked-in version-controlled resource,
- and identifies a version that has the same content and dead
- properties as the version-controlled resource. This property is
- removed when the resource is checked out, and then added back
- (identifying a new version) when the resource is checked back in.
-
- <!ELEMENT checked-in (href)>
-
-
-
-
-Clemm, et al. Standards Track [Page 21]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.2.2 DAV:auto-version
-
- If the DAV:auto-version value is DAV:checkout-checkin, when a
- modification request (such as PUT/PROPPATCH) is applied to a
- checked-in version-controlled resource, the request is automatically
- preceded by a checkout and followed by a checkin operation.
-
- If the DAV:auto-version value is DAV:checkout-unlocked-checkin, when
- a modification request is applied to a checked-in version-controlled
- resource, the request is automatically preceded by a checkout
- operation. If the resource is not write-locked, the request is
- automatically followed by a checkin operation.
-
- If the DAV:auto-version value is DAV:checkout, when a modification
- request is applied to a checked-in version-controlled resource, the
- request is automatically preceded by a checkout operation.
-
- If the DAV:auto-version value is DAV:locked-checkout, when a
- modification request is applied to a write-locked checked-in
- version-controlled resource, the request is automatically preceded by
- a checkout operation.
-
- If an update to a write-locked checked-in resource is automatically
- preceded by a checkout of that resource, the checkout is associated
- with the write lock. When this write lock is removed (e.g. from an
- UNLOCK or a lock timeout), if the resource has not yet been checked
- in, the removal of the write lock is automatically preceded by a
- checkin operation.
-
- A server MAY refuse to allow the value of the DAV:auto-version
- property to be modified, or MAY only support values from a subset of
- the valid values.
-
- <!ELEMENT auto-version (checkout-checkin | checkout-unlocked-checkin
- | checkout | locked-checkout)? >
- <!ELEMENT checkout-checkin EMPTY>
- <!ELEMENT checkout-unlocked-checkin EMPTY>
- <!ELEMENT checkout EMPTY>
- <!ELEMENT locked-checkout EMPTY>
-
-3.3 Checked-Out Resource Properties
-
- The version-control feature introduces the following REQUIRED
- properties for a checked-out resource.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 22]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.3.1 DAV:checked-out (protected)
-
- This property identifies the version that was identified by the
- DAV:checked-in property at the time the resource was checked out.
- This property is removed when the resource is checked in.
-
- <!ELEMENT checked-out (href)>
-
-3.3.2 DAV:predecessor-set
-
- This property determines the DAV:predecessor-set property of the
- version that results from checking in this resource.
-
- A server MAY reject attempts to modify the DAV:predecessor-set of a
- version-controlled resource.
-
- <!ELEMENT predecessor-set (href+)>
-
-3.4 Version Properties
-
- The version-control feature introduces the following REQUIRED
- properties for a version.
-
-3.4.1 DAV:predecessor-set (protected)
-
- This property identifies each predecessor of this version. Except
- for the root version, which has no predecessors, each version has at
- least one predecessor.
-
- <!ELEMENT predecessor-set (href*)>
-
-3.4.2 DAV:successor-set (computed)
-
- This property identifies each version whose DAV:predecessor-set
- identifies this version.
-
- <!ELEMENT successor-set (href*)>
-
-3.4.3 DAV:checkout-set (computed)
-
- This property identifies each checked-out resource whose
- DAV:checked-out property identifies this version.
-
- <!ELEMENT checkout-set (href*)>
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 23]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.4.4 DAV:version-name (protected)
-
- This property contains a server-defined string that is different for
- each version in a given version history. This string is intended for
- display for a user, unlike the URL of a version, which is normally
- only used by a client and not displayed for a user.
-
- <!ELEMENT version-name (#PCDATA)>
- PCDATA value: string
-
-3.5 VERSION-CONTROL Method
-
- A VERSION-CONTROL request can be used to create a version-controlled
- resource at the request-URL. It can be applied to a versionable
- resource or to a version-controlled resource.
-
- If the request-URL identifies a versionable resource, a new version
- history resource is created, a new version is created whose content
- and dead properties are copied from the versionable resource, and the
- resource is given a DAV:checked-in property that is initialized to
- identify this new version.
-
- If the request-URL identifies a version-controlled resource, the
- resource just remains under version-control. This allows a client to
- be unaware of whether or not a server automatically puts a resource
- under version control when it is created.
-
- If a VERSION-CONTROL request fails, the server state preceding the
- request MUST be restored.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:version-control
- XML element.
-
- <!ELEMENT version-control ANY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:version-control-response XML element. Note that this
- document does not define any elements for the VERSION-CONTROL
- response body, but the DAV:version-control-response element is
- defined to ensure interoperability between future extensions that
- do define elements for the VERSION-CONTROL response body.
-
- <!ELEMENT version-control-response ANY>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 24]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Postconditions:
-
- (DAV:put-under-version-control): If the request-URL identified a
- versionable resource at the time of the request, the request MUST
- have created a new version history and MUST have created a new
- version resource in that version history. The resource MUST have
- a DAV:checked-in property that identifies the new version. The
- content, dead properties, and DAV:resourcetype of the new version
- MUST be the same as those of the resource. Note that an
- implementation can choose to locate the version history and
- version resources anywhere that it wishes. In particular, it
- could locate them on the same host and server as the version-
- controlled resource, on a different virtual host maintained by the
- same server, on the same host maintained by a different server, or
- on a different host maintained by a different server.
-
- (DAV:must-not-change-existing-checked-in-out): If the request-URL
- identified a resource already under version control at the time of
- the request, the request MUST NOT change the DAV:checked-in or
- DAV:checked-out property of that version-controlled resource.
-
-3.5.1 Example - VERSION-CONTROL
-
- >>REQUEST
-
- VERSION-CONTROL /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
-
- In this example, /foo.html is put under version control. A new
- version history is created for it, and a new version is created that
- has a copy of the content and dead properties of /foo.html. The
- DAV:checked-in property of /foo.html identifies this new version.
-
-3.6 REPORT Method
-
- A REPORT request is an extensible mechanism for obtaining information
- about a resource. Unlike a resource property, which has a single
- value, the value of a report can depend on additional information
- specified in the REPORT request body and in the REPORT request
- headers.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 25]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Marshalling:
-
- The body of a REPORT request specifies which report is being
- requested, as well as any additional information that will be used
- to customize the report.
-
- The request MAY include a Depth header. If no Depth header is
- included, Depth:0 is assumed.
-
- The response body for a successful request MUST contain the
- requested report.
-
- If a Depth request header is included, the response MUST be a 207
- Multi-Status. The request MUST be applied separately to the
- collection itself and to all members of the collection that
- satisfy the Depth value. The DAV:prop element of a DAV:response
- for a given resource MUST contain the requested report for that
- resource.
-
- Preconditions:
-
- (DAV:supported-report): The specified report MUST be supported by
- the resource identified by the request-URL.
-
- Postconditions:
-
- (DAV:no-modification): The REPORT method MUST NOT have changed the
- content or dead properties of any resource.
-
-3.7 DAV:version-tree Report
-
- The DAV:version-tree report describes the requested properties of all
- the versions in the version history of a version. If the report is
- requested for a version-controlled resource, it is redirected to its
- DAV:checked-in or DAV:checked-out version.
-
- The DAV:version-tree report MUST be supported by all version
- resources and all version-controlled resources.
-
- Marshalling:
-
- The request body MUST be a DAV:version-tree XML element.
-
- <!ELEMENT version-tree ANY>
- ANY value: a sequence of zero or more elements, with at most one
- DAV:prop element.
- prop: see RFC 2518, Section 12.11
-
-
-
-
-Clemm, et al. Standards Track [Page 26]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The response body for a successful request MUST be a
- DAV:multistatus XML element.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response body for a successful DAV:version-tree REPORT request
- MUST contain a DAV:response element for each version in the
- version history of the version identified by the request-URL.
-
-3.7.1 Example - DAV:version-tree Report
-
- The version history drawn below would produce the following version
- tree report.
-
- foo.html History
-
- +---+
- | | V1
- +---+
- / \
- / \
- +---+ +---+
- | | V2 | | V2.1.1
- +---+ +---+
-
- >>REQUEST
-
- REPORT /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:version-tree xmlns:D="DAV:">
- <D:prop>
- <D:version-name/>
- <D:creator-displayname/>
- <D:successor-set/>
- </D:prop>
- </D:version-tree>
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 27]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- >>RESPONSE
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://repo.webdav.org/his/23/ver/V1</D:href>
- <D:propstat>
- <D:prop>
- <D:version-name>V1</D:version-name>
- <D:creator-displayname>Fred</D:creator-displayname>
- <D:successor-set>
- <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
- <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
- </D:successor-set>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://repo.webdav.org/his/23/ver/V2</D:href>
- <D:propstat>
- <D:prop>
- <D:version-name>V2</D:version-name>
- <D:creator-displayname>Fred</D:creator-displayname>
- <D:successor-set/>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://repo.webdav.org/his/23/ver/V2.1.1</D:href>
- <D:propstat>
- <D:prop>
- <D:version-name>V2.1.1</D:version-name>
- <D:creator-displayname>Sally</D:creator-displayname>
- <D:successor-set/>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 28]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.8 DAV:expand-property Report
-
- Many property values are defined as a DAV:href, or a set of DAV:href
- elements. The DAV:expand-property report provides a mechanism for
- retrieving in one request the properties from the resources
- identified by those DAV:href elements. This report not only
- decreases the number of requests required, but also allows the server
- to minimize the number of separate read transactions required on the
- underlying versioning store.
-
- The DAV:expand-property report SHOULD be supported by all resources
- that support the REPORT method.
-
- Marshalling:
-
- The request body MUST be a DAV:expand-property XML element.
-
- <!ELEMENT expand-property (property*)>
- <!ELEMENT property (property*)>
- <!ATTLIST property name NMTOKEN #REQUIRED>
- name value: a property element type
- <!ATTLIST property namespace NMTOKEN "DAV:">
- namespace value: an XML namespace
-
- The response body for a successful request MUST be a
- DAV:multistatus XML element.
-
- multistatus: see RFC 2518, Section 12.9
-
- The properties reported in the DAV:prop elements of the
- DAV:multistatus element MUST be those identified by the
- DAV:property elements in the DAV:expand-property element. If
- there are DAV:property elements nested within a DAV:property
- element, then every DAV:href in the value of the corresponding
- property is replaced by a DAV:response element whose DAV:prop
- elements report the values of the properties identified by the
- nested DAV:property elements. The nested DAV:property elements
- can in turn contain DAV:property elements, so that multiple levels
- of DAV:href expansion can be requested.
-
- Note that a validating parser MUST be aware that the DAV:expand-
- property report effectively modifies the DTD of every property by
- replacing every occurrence of "href" in the DTD with "href |
- response".
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 29]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.8.1 Example - DAV:expand-property
-
- This example describes how to query a version-controlled resource to
- determine the DAV:creator-display-name and DAV:activity-set of every
- version in the version history of that version-controlled resource.
- This example assumes that the server supports the version-history
- feature (see Section 5).
-
- >>REQUEST
-
- REPORT /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:expand-property xmlns:D="DAV:">
- <D:property name="version-history">
- <D:property name="version-set">
- <D:property name="creator-displayname"/>
- <D:property name="activity-set"/>
- </D:property>
- </D:property>
- </D:expand-property>
-
- >>RESPONSE
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.webdav.org/foo.html</D:href>
- <D:propstat>
- <D:prop>
- <D:version-history>
- <D:response>
- <D:href>http://repo.webdav.org/his/23</D:href>
- <D:propstat>
- <D:prop>
- <D:version-set>
- <D:response>
- <D:href>http://repo.webdav.org/his/23/ver/1</D:href>
- <D:propstat>
- <D:prop>
- <D:creator-displayname>Fred</D:creator-displayname>
-
-
-
-Clemm, et al. Standards Track [Page 30]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <D:activity-set> <D:href>
- http://www.webdav.org/ws/dev/sally
- </D:href> </D:activity-set> </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat> </D:response>
- <D:response>
- <D:href>http://repo.webdav.org/his/23/ver/2</D:href>
- <D:propstat>
- <D:prop>
- <D:creator-displayname>Sally</D:creator-displayname>
- <D:activity-set>
- <D:href>http://repo.webdav.org/act/add-refresh-cmd</D:href>
- </D:activity-set> </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat> </D:response>
- </D:version-set> </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat> </D:response>
- </D:version-history> </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat> </D:response>
- </D:multistatus>
-
- In this example, the DAV:creator-displayname and DAV:activity-set
- properties of the versions in the DAV:version-set of the
- DAV:version-history of http://www.webdav.org/foo.html are reported.
-
-3.9 Additional OPTIONS Semantics
-
- If the server supports the version-control feature, it MUST include
- "version-control" as a field in the DAV response header from an
- OPTIONS request on any resource that supports any versioning
- properties, reports, or methods.
-
-3.10 Additional PUT Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-modify-version-controlled-content): If the request-URL
- identifies a resource with a DAV:checked-in property, the request
- MUST fail unless DAV:auto-version semantics will automatically
- check out the resource.
-
- (DAV:cannot-modify-version): If the request-URL identifies a
- version, the request MUST fail.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 31]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- If the request creates a new resource that is automatically placed
- under version control, all preconditions for VERSION-CONTROL apply
- to the request.
-
- Additional Postconditions:
-
- (DAV:auto-checkout): If the resource was a checked-in version-
- controlled resource whose DAV:auto-version property indicates it
- should be automatically checked out but not automatically checked
- in for a modification request, then the server MUST have
- automatically checked out the resource prior to executing the
- request. In particular, the value of the DAV:checked-out property
- of the resource MUST be that of the DAV:checked-in property prior
- to the request, the DAV:checked-in property MUST have been
- removed, and the DAV:predecessor-set property MUST be initialized
- to be the same as the DAV:checked-out property. If any part of
- the checkout/update sequence failed, the status from the failed
- part of the request MUST be returned, and the server state
- preceding the request sequence MUST be restored.
-
- (DAV:auto-checkout-checkin): If the resource was a checked-in
- version-controlled resource whose DAV:auto-version property
- indicates it should be automatically checked out and automatically
- checked in for a modification request, then the server MUST have
- automatically checked out the resource prior to executing the
- request and automatically checked it in after the request. In
- particular, the DAV:checked-in property of the resource MUST
- identify a new version whose content and dead properties are the
- same as those of the resource. The DAV:predecessor-set of the new
- version MUST identify the version identified by the DAV:checked-in
- property prior to the request. If any part of the
- checkout/update/checkin sequence failed, the status from the
- failed part of the request MUST be returned, and the server state
- preceding the request sequence MUST be restored.
-
- If the request creates a new resource, the new resource MAY have
- automatically been placed under version control, and all
- postconditions for VERSION-CONTROL apply to the request.
-
-3.11 Additional PROPFIND Semantics
-
- A DAV:allprop PROPFIND request SHOULD NOT return any of the
- properties defined by this document. This allows a versioning server
- to perform efficiently when a naive client, which does not understand
- the cost of asking a server to compute all possible live properties,
- issues a DAV:allprop PROPFIND request.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 32]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Preconditions:
-
- (DAV:supported-live-property): If the request attempts to access a
- property defined by this document, the semantics of that property
- MUST be supported by the server.
-
-3.12 Additional PROPPATCH Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-modify-version-controlled-property): If the request
- attempts to modify a dead property, same semantics as PUT (see
- Section 3.10).
-
- (DAV:cannot-modify-version): If the request attempts to modify a
- dead property, same semantics as PUT (see Section 3.10).
-
- (DAV:cannot-modify-protected-property): An attempt to modify a
- property that is defined by this document, as being protected for
- that kind of resource, MUST fail.
-
- (DAV:supported-live-property): An attempt to modify a property
- defined by this document, but whose semantics are not enforced by
- the server, MUST fail. This helps ensure that a client will be
- notified when it is trying to use a property whose semantics are
- not supported by the server.
-
- Additional Postconditions:
-
- (DAV:auto-checkout): If the request modified a dead property, same
- semantics as PUT (see Section 3.10).
-
- (DAV:auto-checkout-checkin): If the request modified a dead
- property, same semantics as PUT (see Section 3.10).
-
-3.13 Additional DELETE Semantics
-
- Additional Preconditions:
-
- (DAV:no-version-delete): A server MAY fail an attempt to DELETE a
- version.
-
- Additional Postconditions:
-
- (DAV:update-predecessor-set): If a version was deleted, the server
- MUST have replaced any reference to that version in a
- DAV:predecessor-set by a copy of the DAV:predecessor-set of the
- deleted version.
-
-
-
-Clemm, et al. Standards Track [Page 33]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.14 Additional COPY Semantics
-
- Additional Preconditions:
-
- If the request creates a new resource that is automatically placed
- under version control, all preconditions for VERSION-CONTROL apply
- to the request.
-
- Additional Postconditions:
-
- (DAV:must-not-copy-versioning-property): A property defined by
- this document MUST NOT have been copied to the new resource
- created by this request, but instead that property of the new
- resource MUST have the default initial value it would have had if
- the new resource had been created by a non-versioning method such
- as PUT or a MKCOL.
-
- (DAV:auto-checkout): If the destination is a version-controlled
- resource, same semantics as PUT (see Section 3.10).
-
- (DAV:auto-checkout-checkin): If the destination is a version-
- controlled resource, same semantics as PUT (see Section 3.10).
-
- (DAV:copy-creates-new-resource): If the source of a COPY is a
- version-controlled resource or version, and if there is no
- resource at the destination of the COPY, then the COPY creates a
- new non-version-controlled resource at the destination of the
- COPY. The new resource MAY automatically be put under version
- control, but the resulting version-controlled resource MUST be
- associated with a new version history created for that new
- version-controlled resource, and all postconditions for
- VERSION-CONTROL apply to the request.
-
-3.15 Additional MOVE Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-rename-version): If the request-URL identifies a
- version, the request MUST fail.
-
- Additional Postconditions:
-
- (DAV:preserve-versioning-properties): When a resource is moved
- from a source URL to a destination URL, a property defined by this
- document MUST have the same value at the destination URL as it had
- at the source URL.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 34]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-3.16 Additional UNLOCK Semantics
-
- Note that these semantics apply both to an explicit UNLOCK request,
- as well as to the removal of a lock because of a lock timeout. If a
- precondition or postcondition cannot be satisfied, the lock timeout
- MUST NOT occur.
-
- Additional Preconditions:
-
- (DAV:version-history-is-tree): If the request-URL identifies a
- checked-out version-controlled resource that will be automatically
- checked in when the lock is removed, then the versions identified
- by the DAV:predecessor-set of the checked-out resource MUST be
- descendants of the root version of the version history for the
- DAV:checked-out version.
-
- Additional Postconditions:
-
- (DAV:auto-checkin): If the request-URL identified a checked-out
- version-controlled resource that had been automatically checked
- out because of its DAV:auto-version property, the request MUST
- have created a new version in the version history of the
- DAV:checked-out version. The request MUST have allocated a URL
- for the version that MUST NOT have previously identified any other
- resource, and MUST NOT ever identify a resource other than this
- version. The content, dead properties, DAV:resourcetype, and
- DAV:predecessor-set of the new version MUST be copied from the
- checked-out resource. The DAV:version-name of the new version
- MUST be set to a server-defined value distinct from all other
- DAV:version-name values of other versions in the same version
- history. The request MUST have removed the DAV:checked-out
- property of the version-controlled resource, and MUST have added a
- DAV:checked-in property that identifies the new version.
-
-4 CHECKOUT-IN-PLACE FEATURE
-
- With the version-control feature, WebDAV locking can be used to avoid
- the proliferation of versions that would result if every modification
- to a version-controlled resource produced a new version. The
- checkout-in-place feature provides an alternative mechanism that
- allows a client to explicitly check out and check in a resource to
- create a new version.
-
-4.1 Additional Version Properties
-
- The checkout-in-place feature introduces the following REQUIRED
- properties for a version.
-
-
-
-
-Clemm, et al. Standards Track [Page 35]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-4.1.1 DAV:checkout-fork
-
- This property controls the behavior of CHECKOUT when a version
- already is checked out or has a successor. If the DAV:checkout-fork
- of a version is DAV:forbidden, a CHECKOUT request MUST fail if it
- would result in that version appearing in the DAV:predecessor-set or
- DAV:checked-out property of more than one version or checked-out
- resource. If DAV:checkout-fork is DAV:discouraged, such a CHECKOUT
- request MUST fail unless DAV:fork-ok is specified in the CHECKOUT
- request body.
-
- A server MAY reject attempts to modify the DAV:checkout-fork of a
- version.
-
- <!ELEMENT checkout-fork ANY>
- ANY value: A sequence of elements with at most one DAV:discouraged
- or DAV:forbidden element.
- <!ELEMENT discouraged EMPTY>
- <!ELEMENT forbidden EMPTY>
-
-4.1.2 DAV:checkin-fork
-
- This property controls the behavior of CHECKIN when a version already
- has a successor. If the DAV:checkin-fork of a version is
- DAV:forbidden, a CHECKIN request MUST fail if it would result in that
- version appearing in the DAV:predecessor-set of more than one
- version. If DAV:checkin-fork is DAV:discouraged, such a CHECKIN
- request MUST fail unless DAV:fork-ok is specified in the CHECKIN
- request body.
-
- A server MAY reject attempts to modify the DAV:checkout-fork of a
- version.
-
- <!ELEMENT checkin-fork ANY>
- ANY value: A sequence of elements with at most one DAV:discouraged
- or DAV:forbidden element.
- <!ELEMENT discouraged EMPTY>
- <!ELEMENT forbidden EMPTY>
-
-4.2 Checked-Out Resource Properties
-
- The checkout-in-place feature introduces the following REQUIRED
- properties for a checked-out resource.
-
-4.2.1 DAV:checkout-fork
-
- This property determines the DAV:checkout-fork property of the
- version that results from checking in this resource.
-
-
-
-Clemm, et al. Standards Track [Page 36]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-4.2.2 DAV:checkin-fork
-
- This property determines the DAV:checkin-fork property of the version
- that results from checking in this resource.
-
-4.3 CHECKOUT Method (applied to a version-controlled resource)
-
- A CHECKOUT request can be applied to a checked-in version-controlled
- resource to allow modifications to the content and dead properties of
- that version-controlled resource.
-
- If a CHECKOUT request fails, the server state preceding the request
- MUST be restored.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:checkout XML
- element.
-
- <!ELEMENT checkout ANY>
-
- ANY value: A sequence of elements with at most one DAV:fork-ok
- element.
-
- <!ELEMENT fork-ok EMPTY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:checkout-response XML element.
-
- <!ELEMENT checkout-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:must-be-checked-in): If a version-controlled resource is
- being checked out, it MUST have a DAV:checked-in property.
-
- (DAV:checkout-of-version-with-descendant-is-forbidden): If the
- DAV:checkout-fork property of the version being checked out is
- DAV:forbidden, the request MUST fail if a version identifies that
- version in its DAV:predecessor-set.
-
- (DAV:checkout-of-version-with-descendant-is-discouraged): If the
- DAV:checkout-fork property of the version being checked out is
- DAV:discouraged, the request MUST fail if a version identifies
- that version in its DAV:predecessor-set unless DAV:fork-ok is
- specified in the request body.
-
-
-
-Clemm, et al. Standards Track [Page 37]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:checkout-of-checked-out-version-is-forbidden): If the
- DAV:checkout-fork property of the version being checked out is
- DAV:forbidden, the request MUST fail if a checked-out resource
- identifies that version in its DAV:checked-out property.
-
- (DAV:checkout-of-checked-out-version-is-discouraged): If the
- DAV:checkout-fork property of the version being checked out is
- DAV:discouraged, the request MUST fail if a checked-out resource
- identifies that version in its DAV:checked-out property unless
- DAV:fork-ok is specified in the request body.
-
- Postconditions:
-
- (DAV:is-checked-out): The checked-out resource MUST have a
- DAV:checked-out property that identifies the DAV:checked-in
- version preceding the checkout. The version-controlled resource
- MUST NOT have a DAV:checked-in property.
-
- (DAV:initialize-predecessor-set): The DAV:predecessor-set property
- of the checked-out resource MUST be initialized to be the
- DAV:checked-out version.
-
-4.3.1 Example - CHECKOUT of a version-controlled resource
-
- >>REQUEST
-
- CHECKOUT /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Cache-Control: no-cache
-
- In this example, the version-controlled resource /foo.html is checked
- out.
-
-4.4 CHECKIN Method (applied to a version-controlled resource)
-
- A CHECKIN request can be applied to a checked-out version-controlled
- resource to produce a new version whose content and dead properties
- are copied from the checked-out resource.
-
- If a CHECKIN request fails, the server state preceding the request
- MUST be restored.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 38]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:checkin XML
- element.
-
- <!ELEMENT checkin ANY>
- ANY value: A sequence of elements with at most one
- DAV:keep-checked-out element and at most one DAV:fork-ok element.
-
- <!ELEMENT keep-checked-out EMPTY>
- <!ELEMENT fork-ok EMPTY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:checkin-response XML element.
-
- <!ELEMENT checkin-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:must-be-checked-out): The request-URL MUST identify a
- resource with a DAV:checked-out property.
-
- (DAV:version-history-is-tree) The versions identified by the
- DAV:predecessor-set of the checked-out resource MUST be
- descendants of the root version of the version history for the
- DAV:checked-out version.
-
- (DAV:checkin-fork-forbidden): A CHECKIN request MUST fail if it
- would cause a version whose DAV:checkin-fork is DAV:forbidden to
- appear in the DAV:predecessor-set of more than one version.
-
- (DAV:checkin-fork-discouraged): A CHECKIN request MUST fail if it
- would cause a version whose DAV:checkin-fork is DAV:discouraged to
- appear in the DAV:predecessor-set of more than one version, unless
- DAV:fork-ok is specified in the request body.
-
- Postconditions:
-
- (DAV:create-version): The request MUST have created a new version
- in the version history of the DAV:checked-out version. The
- request MUST have allocated a distinct new URL for the new
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 39]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- version, and that URL MUST NOT ever identify any resource other
- than that version. The URL for the new version MUST be returned in
- a Location response header.
-
- (DAV:initialize-version-content-and-properties): The content, dead
- properties, DAV:resourcetype, and DAV:predecessor-set of the new
- version MUST be copied from the checked-out resource. The
- DAV:version-name of the new version MUST be set to a server-
- defined value distinct from all other DAV:version-name values of
- other versions in the same version history.
-
- (DAV:checked-in): If the request-URL identifies a version-
- controlled resource and DAV:keep-checked-out is not specified in
- the request body, the DAV:checked-out property of the version-
- controlled resource MUST have been removed and a DAV:checked-in
- property that identifies the new version MUST have been added.
-
- (DAV:keep-checked-out): If DAV:keep-checked-out is specified in
- the request body, the DAV:checked-out property of the checked-out
- resource MUST have been updated to identify the new version.
-
-4.4.1 Example - CHECKIN
-
- >>REQUEST
-
- CHECKIN /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Location: http://repo.webdav.org/his/23/ver/32
- Cache-Control: no-cache
-
- In this example, version-controlled resource /foo.html is checked in,
- and a new version is created at http://repo.webdav.org/his/23/ver/32.
-
-4.5 UNCHECKOUT Method
-
- An UNCHECKOUT request can be applied to a checked-out version-
- controlled resource to cancel the CHECKOUT and restore the pre-
- CHECKOUT state of the version-controlled resource.
-
- If an UNCHECKOUT request fails, the server MUST undo any partial
- effects of the UNCHECKOUT request.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 40]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:uncheckout XML
- element.
-
- <!ELEMENT uncheckout ANY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:uncheckout-response XML element.
-
- <!ELEMENT uncheckout-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:must-be-checked-out-version-controlled-resource): The
- request-URL MUST identify a version-controlled resource with a
- DAV:checked-out property.
-
- Postconditions:
-
- (DAV:cancel-checked-out): The value of the DAV:checked-in property
- is that of the DAV:checked-out property prior to the request, and
- the DAV:checked-out property has been removed.
-
- (DAV:restore-content-and-dead-properties): The content and dead
- properties of the version-controlled resource are copies of its
- DAV:checked-in version.
-
-4.5.1 Example - UNCHECKOUT
-
- >>REQUEST
-
- UNCHECKOUT /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Cache-Control: no-cache
-
- In this example, the content and dead properties of the version-
- controlled resource identified by http://www.webdav.org/foo.html are
- restored to their values preceding the most recent CHECKOUT of that
- version-controlled resource.
-
-
-
-
-Clemm, et al. Standards Track [Page 41]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-4.6 Additional OPTIONS Semantics
-
- If a server supports the checkout-in-place feature, it MUST include
- "checkout-in-place" as a field in the DAV response header from an
- OPTIONS request on any resource that supports any versioning
- properties, reports, or methods.
-
-5 Version-History Feature
-
- It is often useful to have access to a version history even after all
- version-controlled resources for that version history have been
- deleted. A server can provide this functionality by supporting
- version history resources. A version history resource is a resource
- that exists in a server defined namespace and therefore is unaffected
- by any deletion or movement of version-controlled resources. A
- version history resource is an appropriate place to add a property
- that logically applies to all states of a resource. The DAV:expand-
- property report (see Section 3.8) can be applied to the DAV:version-
- set of a version history resource to provide a variety of useful
- reports on all versions in that version history.
-
-5.1 Version History Properties
-
- The DAV:resourcetype of a version history MUST be DAV:version-
- history.
-
- The version-history feature introduces the following REQUIRED
- properties for a version history.
-
-5.1.1 DAV:version-set (protected)
-
- This property identifies each version of this version history.
-
- <!ELEMENT version-set (href+)>
-
-5.1.2 DAV:root-version (computed)
-
- This property identifies the root version of this version history.
-
- <!ELEMENT root-version (href)>
-
-5.2 Additional Version-Controlled Resource Properties
-
- The version-history feature introduces the following REQUIRED
- property for a version-controlled resource.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 42]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-5.2.1 DAV:version-history (computed)
-
- This property identifies the version history resource for the
- DAV:checked-in or DAV:checked-out version of this version-controlled
- resource.
-
- <!ELEMENT version-history (href)>
-
-5.3 Additional Version Properties
-
- The version-history feature introduces the following REQUIRED
- property for a version.
-
-5.3.1 DAV:version-history (computed)
-
- This property identifies the version history that contains this
- version.
-
- <!ELEMENT version-history (href)>
-
-5.4 DAV:locate-by-history Report
-
- Many properties identify a version from some version history. It is
- often useful to be able to efficiently locate a version-controlled
- resource for that version history. The DAV:locate-by-history report
- can be applied to a collection to locate the collection member that
- is a version-controlled resource for a specified version history
- resource.
-
- Marshalling:
-
- The request body MUST be a DAV:locate-by-history XML element.
-
- <!ELEMENT locate-by-history (version-history-set, prop)>
- <!ELEMENT version-history-set (href+)>
- prop: see RFC 2518, Section 12.11
-
- The response body for a successful request MUST be a
- DAV:multistatus XML element containing every version-controlled
- resource that is a member of the collection identified by the
- request-URL, and whose DAV:version-history property identifies one
- of the version history resources identified by the request body.
- The DAV:prop element in the request body identifies which
- properties should be reported in the DAV:prop elements in the
- response body.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 43]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Preconditions:
-
- (DAV:must-be-version-history): Each member of the DAV:version-
- history-set element in the request body MUST identify a version
- history resource.
-
-5.4.1 Example - DAV:locate-by-history Report
-
- >>REQUEST
-
- REPORT /ws/public HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:locate-by-history xmlns:D="DAV:">
- <D:version-history-set>
- <D:href>http://repo.webdav.org/his/23</D:href>
- <D:href>http://repo.webdav.org/his/84</D:href>
- <D:href>http://repo.webdav.org/his/129</D:href>
- <D:version-history-set/>
- <D:prop>
- </D:version-history>
- </D:prop>
- </D:locate-by-history>
-
- >>RESPONSE
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.webdav.org/ws/public/x/test.html</D:href>
- <D:propstat>
- <D:prop>
- <D:version-history>
- <D:href>http://repo.webdav.org/his/23</D:href>
- </D:version-history>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-Clemm, et al. Standards Track [Page 44]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In this example, there is only one version-controlled member of
- /ws/public that is a version-controlled resource for one of the three
- specified version history resources. In particular,
- /ws/public/x/test.html is the version-controlled resource for
- http://repo.webdav.org/his/23.
-
-5.5 Additional OPTIONS Semantics
-
- If the server supports the version-history feature, it MUST include
- "version-history" as a field in the DAV response header from an
- OPTIONS request on any resource that supports any versioning
- properties, reports, or methods.
-
- A DAV:version-history-collection-set element MAY be included in the
- request body to identify collections that may contain version history
- resources.
-
- Additional Marshalling:
-
- If an XML request body is included, it MUST be a DAV:options XML
- element.
-
- <!ELEMENT options ANY>
- ANY value: A sequence of elements with at most one
- DAV:version-history-collection-set element.
-
- If an XML response body for a successful request is included, it
- MUST be a DAV:options-response XML element.
-
- <!ELEMENT options-response ANY>
- ANY value: A sequence of elements with at most one
- DAV:version-history-collection-set element.
-
- <!ELEMENT version-history-collection-set (href*)>
-
- If DAV:version-history-collection-set is included in the request
- body, the response body for a successful request MUST contain a
- DAV:version-history-collection-set element identifying collections
- that may contain version histories. An identified collection MAY
- be the root collection of a tree of collections, all of which may
- contain version histories. Since different servers can control
- different parts of the URL namespace, different resources on the
- same host MAY have different DAV:version-history-collection-set
- values. The identified collections MAY be located on different
- hosts from the resource.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 45]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-5.6 Additional DELETE Semantics
-
- Additional Postconditions:
-
- (DAV:delete-version-set): If the request deleted a version
- history, the request MUST have deleted all versions in the
- DAV:version-set of that version history, and MUST have satisfied
- the postconditions for version deletion (see Section 3.13).
-
- (DAV:version-history-has-root): If the request deleted the root
- version of a version history, the request MUST have updated the
- DAV:root-version of the version history to refer to another
- version that is an ancestor of all other remaining versions in
- that version history. A result of this postcondition is that
- every version history will have at least one version, and the only
- way to delete all versions is to delete the version history
- resource.
-
-5.7 Additional COPY Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-copy-history): If the request-URL identifies a version
- history, the request MUST fail. In order to create another
- version history whose versions have the same content and dead
- properties, the appropriate sequence of VERSION-CONTROL, CHECKOUT,
- PUT, PROPPATCH, and CHECKIN requests must be made.
-
-5.8 Additional MOVE Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-rename-history): If the request-URL identifies a
- version history, the request MUST fail.
-
-5.9 Additional VERSION-CONTROL Semantics
-
- Additional Postconditions:
-
- (DAV:new-version-history): If the request created a new version
- history, the request MUST have allocated a new server-defined URL
- for that version history that MUST NOT have previously identified
- any other resource, and MUST NOT ever identify a resource other
- than this version history.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 46]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-5.10 Additional CHECKIN Semantics
-
- Additional Postconditions:
-
- (DAV:add-to-history): A URL for the new version resource MUST have
- been added to the DAV:version-set of the version history of the
- DAV:checked-out version.
-
-6 Workspace Feature
-
- In order to allow multiple users to work concurrently on adding
- versions to the same version history, it is necessary to allocate on
- the server multiple checked-out resources for the same version
- history. Even if only one user is making changes to a resource, that
- user will sometimes wish to create a "private" version, and then to
- expose that version at a later time. One way to provide this
- functionality depends on the client keeping track of its current set
- of checked-out resources. This is the working-resource feature
- defined in Section 8. The other way to provide this functionality
- avoids the need for persistent state on the client, and instead has
- the server maintain a human meaningful namespace for related sets of
- checked-out resources. This is the workspace feature defined in this
- section.
-
- The workspace feature introduces a "workspace resource". A workspace
- resource is a collection whose members are related version-controlled
- and non-version-controlled resources. Multiple workspaces may be
- used to expose different versions and configurations of a set of
- version-controlled resources concurrently. In order to make changes
- to a version-controlled resource in one workspace visible in another
- workspace, that version-controlled resource must be checked in, and
- then the corresponding version-controlled resource in the other
- workspace can be updated to display the content and dead properties
- of the new version.
-
- In order to ensure unambiguous merging (see Section 11) and
- baselining (see Section 12) semantics, a workspace may contain at
- most one version-controlled resource for a given version history.
- This is required for unambiguous merging because the MERGE method
- must identify which version-controlled resource is to be the merge
- target of a given version. This is required for unambiguous
- baselining because a baseline can only select one version for a given
- version-controlled resource.
-
- Initially, an empty workspace can be created. Non-version-controlled
- resources can then be added to the workspace with standard WebDAV
- requests such as PUT and MKCOL. Version-controlled resources can be
- added to the workspace with VERSION-CONTROL requests. If the
-
-
-
-Clemm, et al. Standards Track [Page 47]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- baseline feature is supported, collections in the workspace can be
- placed under baseline control, and then initialized by existing
- baselines.
-
-6.1 Workspace Properties
-
- The workspace feature introduces the following REQUIRED property for
- a workspace.
-
-6.1.1 DAV:workspace-checkout-set (computed)
-
- This property identifies each checked-out resource whose
- DAV:workspace property identifies this workspace.
-
- <!ELEMENT workspace-checkout-set (href*)>
-
-6.2 Additional Resource Properties
-
- The workspace feature introduces the following REQUIRED property for
- a WebDAV resource.
-
-6.2.1 DAV:workspace (protected)
-
- The DAV:workspace property of a workspace resource MUST identify
- itself. The DAV:workspace property of any other type of resource
- MUST be the same as the DAV:workspace of its parent collection.
-
- <!ELEMENT workspace (href)>
-
-6.3 MKWORKSPACE Method
-
- A MKWORKSPACE request creates a new workspace resource. A server MAY
- restrict workspace creation to particular collections, but a client
- can determine the location of these collections from a
- DAV:workspace-collection-set OPTIONS request (see Section 6.4).
-
- If a MKWORKSPACE request fails, the server state preceding the
- request MUST be restored.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:mkworkspace XML
- element.
-
- <!ELEMENT mkworkspace ANY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:mkworkspace-response XML element.
-
-
-
-Clemm, et al. Standards Track [Page 48]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <!ELEMENT mkworkspace-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:resource-must-be-null): A resource MUST NOT exist at the
- request-URL.
-
- (DAV:workspace-location-ok): The request-URL MUST identify a
- location where a workspace can be created.
-
- Postconditions:
-
- (DAV:initialize-workspace): A new workspace exists at the
- request-URL. The DAV:resourcetype of the workspace MUST be
- DAV:collection. The DAV:workspace of the workspace MUST identify
- the workspace.
-
-6.3.1 Example - MKWORKSPACE
-
- >>REQUEST
-
- MKWORKSPACE /ws/public HTTP/1.1
- Host: www.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Cache-Control: no-cache
-
- In this example, a new workspace is created at
- http://www.webdav.org/ws/public.
-
-6.4 Additional OPTIONS Semantics
-
- If a server supports the workspace feature, it MUST include
- "workspace" as a field in the DAV response header from an OPTIONS
- request on any resource that supports any versioning properties,
- reports, or methods.
-
- If a server supports the workspace feature, it MUST also support the
- checkout-in-place feature and the version-history feature.
-
- A DAV:workspace-collection-set element MAY be included in the request
- body to identify collections that may contain workspace resources.
-
-
-
-
-Clemm, et al. Standards Track [Page 49]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Marshalling:
-
- If an XML request body is included, it MUST be a DAV:options XML
- element.
-
- <!ELEMENT options ANY>
- ANY value: A sequence of elements with at most one
- DAV:workspace-collection-set element.
-
- If an XML response body for a successful request is included, it
- MUST be a DAV:options-response XML element.
-
- <!ELEMENT options-response ANY>
- ANY value: A sequence of elements with at most one
- DAV:workspace-collection-set element.
-
- <!ELEMENT workspace-collection-set (href*)>
-
- If DAV:workspace-collection-set is included in the request body,
- the response body for a successful request MUST contain a
- DAV:workspace-collection-set element identifying collections that
- may contain workspaces. An identified collection MAY be the root
- collection of a tree of collections, all of which may contain
- workspaces. Since different servers can control different parts
- of the URL namespace, different resources on the same host MAY
- have different DAV:workspace-collection-set values. The
- identified collections MAY be located on different hosts from the
- resource.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 50]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-6.4.1 Example - OPTIONS
-
- >>REQUEST
-
- OPTIONS /doc HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:options xmlns:D="DAV:">
- <D:version-history-collection-set/>
- <D:workspace-collection-set/>
- </D:options>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- DAV: 1
- DAV: version-control,checkout-in-place,version-history,workspace
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:options-response xmlns:D="DAV:">
- <D:version-history-collection-set>
- <D:href>http://repo.webdav.org/his</D:href>
- </D:version-history-collection-set>
- <D:workspace-collection-set>
- <D:href>http://www.webdav.org/public/ws</D:href>
- <D:href>http://www.webdav.org/private/ws</D:href>
- </D:workspace-collection-set>
- </D:options-response>
-
- In this example, the server indicates that it provides Class 1 DAV
- support and basic-server-workspace versioning support. In addition,
- the server indicates the requested locations of the version history
- resources and the workspace resources.
-
-6.5 Additional DELETE Semantics
-
- Additional Postconditions:
-
- (DAV:delete-workspace-members): If a workspace is deleted, any
- resource that identifies that workspace in its DAV:workspace
- property MUST be deleted.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 51]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-6.6 Additional MOVE Semantics
-
- Additional Postconditions:
-
- (DAV:workspace-member-moved): If the request-URL did not identify
- a workspace, the DAV:workspace of the destination MUST have been
- updated to have the same value as the DAV:workspace of the parent
- collection of the destination.
-
- (DAV:workspace-moved): If the request-URL identified a workspace,
- any reference to that workspace in a DAV:workspace property MUST
- have been updated to refer to the new location of that workspace.
-
-6.7 Additional VERSION-CONTROL Semantics
-
- A VERSION-CONTROL request can be used to create a new version-
- controlled resource for an existing version history. This allows the
- creation of version-controlled resources for the same version history
- in multiple workspaces.
-
- Additional Marshalling:
-
- <!ELEMENT version-control ANY>
- ANY value: A sequence of elements with at most one DAV:version
- element.
-
- <!ELEMENT version (href)>
-
- Additional Preconditions:
-
- (DAV:cannot-add-to-existing-history): If the DAV:version-control
- request body element contains a DAV:version element, the request-
- URL MUST NOT identify a resource.
-
- (DAV:must-be-version): The DAV:href of the DAV:version element
- MUST identify a version.
-
- (DAV:one-version-controlled-resource-per-history-per-workspace):
- If the DAV:version-control request body specifies a version, and
- if the request-URL is a member of a workspace, then there MUST NOT
- already be a version-controlled member of that workspace whose
- DAV:checked-in or DAV:checked-out property identifies any version
- from the version history of the version specified in the request
- body.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 52]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Postconditions:
-
- (DAV:new-version-controlled-resource): If the request-URL did NOT
- identify a resource, a new version-controlled resource exists at
- the request-URL whose content and dead properties are initialized
- by those of the version in the request body, and whose
- DAV:checked-in property identifies that version.
-
-6.7.1 Example - VERSION-CONTROL (using an existing version history)
-
- >>REQUEST
-
- VERSION-CONTROL /ws/public/bar.html HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:version-control xmlns:D="DAV:">
- <D:version>
- <D:href>http://repo.webdav.org/his/12/ver/V3</D:href>
- </D:version>
- </D:version-control>
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Cache-Control: no-cache
-
- In this example, a new version-controlled resource is created at
- /ws/public/bar.html. The content and dead properties of the new
- version-controlled resource are initialized to be the same as those
- of the version identified by http://repo.webdav.org/his/12/ver/V3.
-
-7 UPDATE Feature
-
- The update feature provides a mechanism for changing the state of a
- checked-in version-controlled resource to be that of another version
- from the version history of that resource.
-
-7.1 UPDATE Method
-
- The UPDATE method modifies the content and dead properties of a
- checked-in version-controlled resource (the "update target") to be
- those of a specified version (the "update source") from the version
- history of that version-controlled resource.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 53]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The response to an UPDATE request identifies the resources modified
- by the request, so that a client can efficiently update any cached
- state it is maintaining. Extensions to the UPDATE method allow
- multiple resources to be modified from a single UPDATE request (see
- Section 12.13).
-
- Marshalling:
-
- The request body MUST be a DAV:update element.
-
- <!ELEMENT update ANY>
- ANY value: A sequence of elements with at most one DAV:version
- element and at most one DAV:prop element.
- <!ELEMENT version (href)>
- prop: see RFC 2518, Section 12.11
-
- The response for a successful request MUST be a 207 Multi-Status,
- where the DAV:multistatus XML element in the response body
- identifies all resources that have been modified by the request.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response MUST include a Cache-Control:no-cache header.
-
- Postconditions:
-
- (DAV:update-content-and-properties): If the DAV:version element in
- the request body identified a version that is in the same version
- history as the DAV:checked-in version of a version-controlled
- resource identified by the request-URL, then the content and dead
- properties of that version-controlled resource MUST be the same as
- those of the version specified by the DAV:version element, and the
- DAV:checked-in property of the version-controlled resource MUST
- identify that version. The request-URL MUST appear in a
- DAV:response element in the response body.
-
- (DAV:report-properties): If DAV:prop is specified in the request
- body, the properties specified in the DAV:prop element MUST be
- reported in the DAV:response elements in the response body.
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 54]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-7.1.1 Example - UPDATE
-
- >>REQUEST
-
- UPDATE /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:update xmlns:D="DAV:">
- <D:version>
- <D:href>http://repo.webdav.org/his/23/ver/33</D:href>
- </D:version>
- </D:update>
-
- >>RESPONSE
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Cache-Control: no-cache
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.webdav.org/foo.html</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:response>
-
- In this example, the content and dead properties of
- http://repo.webdav.org/his/23/ver/33 are copied to the version-
- controlled resource /foo.html, and the DAV:checked-in property of
- /foo.html is updated to refer to
- http://repo.webdav.org/his/23/ver/33.
-
-7.2 Additional OPTIONS Semantics
-
- If the server supports the update feature, it MUST include "update"
- as a field in the DAV response header from an OPTIONS request on any
- resource that supports any versioning properties, reports, or
- methods.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 55]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-8 Label Feature
-
- A version "label" is a string that distinguishes one version in a
- version history from all other versions in that version history. A
- label can automatically be assigned by a server, or it can be
- assigned by a client in order to provide a meaningful name for that
- version. A given version label can be assigned to at most one
- version of a given version history, but client assigned labels can be
- reassigned to another version at any time. Note that although a
- given label can be applied to at most one version from the same
- version history, the same label can be applied to versions from
- different version histories.
-
- For certain methods, if the request-URL identifies a version-
- controlled resource, a label can be specified in a Label request
- header (see Section 8.3) to cause the method to be applied to the
- version selected by that label from the version history of that
- version-controlled resource.
-
-8.1 Additional Version Properties
-
- The label feature introduces the following REQUIRED property for a
- version.
-
-8.1.1 DAV:label-name-set (protected)
-
- This property contains the labels that currently select this version.
-
- <!ELEMENT label-name-set (label-name*)>
- <!ELEMENT label-name (#PCDATA)>
- PCDATA value: string
-
-8.2 LABEL Method
-
- A LABEL request can be applied to a version to modify the labels that
- select that version. The case of a label name MUST be preserved when
- it is stored and retrieved. When comparing two label names to decide
- if they match or not, a server SHOULD use a case-sensitive URL-
- escaped UTF-8 encoded comparison of the two label names.
-
- If a LABEL request is applied to a checked in version-controlled
- resource, the operation MUST be applied to the DAV:checked-in version
- of that version-controlled resource.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 56]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Marshalling:
-
- The request body MUST be a DAV:label element.
-
- <!ELEMENT label ANY>
- ANY value: A sequence of elements with at most one DAV:add,
- DAV:set, or DAV:remove element.
-
- <!ELEMENT add (label-name)>
- <!ELEMENT set (label-name)>
- <!ELEMENT remove (label-name)>
- <!ELEMENT label-name (#PCDATA)>
- PCDATA value: string
-
- The request MAY include a Label header.
-
- The request MAY include a Depth header. If no Depth header is
- included, Depth:0 is assumed. Standard depth semantics apply, and
- the request is applied to the collection identified by the
- request-URL and to all members of the collection that satisfy the
- Depth value. If a Depth header is included and the request fails
- on any resource, the response MUST be a 207 Multi-Status that
- identifies all resources for which the request has failed.
-
- If a response body for a successful request is included, it MUST
- be a DAV:label-response XML element.
-
- <!ELEMENT label-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:must-be-checked-in): If the request-URL identifies a
- version-controlled resource, the version-controlled resource MUST
- be checked in.
-
- (DAV:must-select-version-in-history): If a Label request header is
- included and the request-URL identifies a version-controlled
- resource, the specified label MUST select a version in the version
- history of the version-controlled resource.
-
- (DAV:add-must-be-new-label): If DAV:add is specified in the
- request body, the specified label MUST NOT appear in the
- DAV:label-name-set of any version in the version history of that
- version-controlled resource.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 57]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:label-must-exist): If DAV:remove is specified in the request
- body, the specified label MUST appear in the DAV:label-name-set of
- that version.
-
- Postconditions:
-
- (DAV:add-or-set-label): If DAV:add or DAV:set is specified in the
- request body, the specified label MUST appear in the DAV:label-
- name-set of the specified version, and MUST NOT appear in the
- DAV:label-name-set of any other version in the version history of
- that version.
-
- (DAV:remove-label): If DAV:remove is specified in the request
- body, the specified label MUST NOT appear in the DAV:label-name-
- set of any version in the version history of that version.
-
-8.2.1 Example - Setting a label
-
- >>REQUEST
-
- LABEL /foo.html HTTP/1.1
- Host: www.webdav.org
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:label xmlns:D="DAV:">
- <D:set>
- <D:label-name>default</D:label-name>
- </D:set>
- </D:label>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Cache-Control: no-cache
-
- In this example, the label "default" is applied to the DAV:checked-in
- version of /foo.html.
-
-8.3 Label Header
-
- For certain methods (e.g. GET, PROPFIND), if the request-URL
- identifies a version-controlled resource, a label can be specified in
- a Label request header to cause the method to be applied to the
- version selected by that label from the version history of that
- version-controlled resource.
-
-
-
-
-Clemm, et al. Standards Track [Page 58]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The value of a label header is the name of a label, encoded using
- URL-escaped UTF-8. For example, the label "release B.3" is
- identified by the following header:
-
- Label: release%20B.3
-
- A Label header MUST have no effect on a request whose request-URL
- does not identify a version-controlled resource. In particular, it
- MUST have no effect on a request whose request-URL identifies a
- version or a version history.
-
- A server MUST return an HTTP-1.1 Vary header containing Label in a
- successful response to a cacheable request (e.g., GET) that includes
- a Label header.
-
-8.4 Additional OPTIONS Semantics
-
- If the server supports the label feature, it MUST include "label" as
- a field in the DAV response header from an OPTIONS request on any
- resource that supports any versioning properties, reports, or
- methods.
-
-8.5 Additional GET Semantics
-
- Additional Marshalling:
-
- The request MAY include a Label header.
-
- Additional Preconditions:
-
- (DAV:must-select-version-in-history): If a Label request header is
- included and the request-URL identifies a version-controlled
- resource, the specified label MUST select a version in the version
- history of the version-controlled resource.
-
- Additional Postconditions:
-
- (DAV:apply-request-to-labeled-version): If the request-URL
- identifies a version-controlled resource and a Label request
- header is included, the response MUST contain the content of the
- specified version rather than that of the version-controlled
- resource.
-
-8.6 Additional PROPFIND Semantics
-
- Additional Marshalling:
-
- The request MAY include a Label header.
-
-
-
-Clemm, et al. Standards Track [Page 59]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Preconditions:
-
- (DAV:must-select-version-in-history): If a Label request header is
- included and the request-URL identifies a version-controlled
- resource, the specified label MUST select a version in the version
- history of the version-controlled resource.
-
- Additional Postconditions:
-
- (DAV:apply-request-to-labeled-version): If the request-URL
- identifies a version-controlled resource and a Label request
- header is included, the response MUST contain the properties of
- the specified version rather than that of the version-controlled
- resource.
-
-8.7 Additional COPY Semantics
-
- Additional Marshalling:
-
- The request MAY include a Label header.
-
- Additional Preconditions:
-
- (DAV:must-select-version-in-history): If a Label request header is
- included and the request-URL identifies a version-controlled
- resource, the specified label MUST select a version in the version
- history of the version-controlled resource.
-
- Additional Postconditions:
-
- (DAV:apply-request-to-labeled-version): If the request-URL
- identifies a version-controlled resource and a Label request
- header is included, the request MUST have copied the properties
- and content of the specified version rather than that of the
- version-controlled resource.
-
-8.8 Additional CHECKOUT Semantics
-
- If the server supports the working-resource option, a LABEL header
- may be included to check out the version selected by the specified
- label.
-
- Additional Marshalling:
-
- The request MAY include a Label header.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 60]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Preconditions:
-
- (DAV:must-select-version-in-history): If a Label request header is
- included and the request-URL identifies a version-controlled
- resource, the specified label MUST select a version in the version
- history of the version-controlled resource.
-
- (DAV:must-not-have-label-and-apply-to-version): If a Label request
- header is included, the request body MUST NOT contain a
- DAV:apply-to-version element.
-
- Additional Postconditions:
-
- (DAV:apply-request-to-labeled-version): If the request-URL
- identifies a checked-in version-controlled resource, and a Label
- request header is included, the CHECKOUT MUST have been applied to
- the version selected by the specified label, and not to the
- version-controlled resource itself.
-
-8.9 Additional UPDATE Semantics
-
- If the request body of an UPDATE request contains a DAV:label-name
- element, the update target is the resource identified by the
- request-URL, and the update source is the version selected by the
- specified label from the version history of the update target.
-
- Additional Marshalling:
-
- <!ELEMENT update ANY>
- ANY value: A sequence of elements with at most one DAV:label-name
- or DAV:version element (but not both).
- <!ELEMENT label-name (#PCDATA)>
- PCDATA value: string
-
- The request MAY include a Depth header. If no Depth header is
- included, Depth:0 is assumed. Standard depth semantics apply, and
- the request is applied to the collection identified by the
- request-URL and to all members of the collection that satisfy the
- Depth value. If a Depth header is included and the request fails
- on any resource, the response MUST be a 207 Multi-Status that
- identifies all resources for which the request has failed.
-
- Additional Preconditions:
-
- (DAV:must-select-version-in-history): If the request includes a
- DAV:label-name element in the request body, the label MUST select
- a version in the version history of the version-controlled
- resource identified by the request-URL.
-
-
-
-Clemm, et al. Standards Track [Page 61]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:depth-update): If the request includes a Depth header,
- standard depth semantics apply, and the request is applied to the
- collection identified by the request-URL and to all members of the
- collection that satisfy the Depth value. The request MUST be
- applied to a collection before being applied to any members of
- that collection, since an update of a version-controlled
- collection might change the membership of that collection.
-
- Additional Postconditions:
-
- (DAV:apply-request-to-labeled-version): If a DAV:label-name
- element appears in the request body, the content and dead
- properties of the version-controlled resource must have been
- updated to be those of the version selected by that label.
-
-9 Working-Resource Feature
-
- The working-resource feature provides an alternative to the workspace
- feature for supporting parallel development. Unlike the workspace
- feature, where the desired configuration of versions and checked-out
- resources is maintained on the server, the working-resource feature
- maintains the configuration on the client. This simplifies the
- server implementation, but does not allow a user to access the
- configuration from clients in different physical locations, such as
- from another office, from home, or while traveling. Another
- difference is that the workspace feature isolates clients from a
- logical change that involves renaming shared resources, until that
- logical change is complete and tested; with the working resource
- feature, all clients use a common set of shared version-controlled
- resources and every client sees the result of a MOVE as soon as it
- occurs.
-
- If a server supports the working-resource feature but not the
- checkout-in-place feature, a CHECKOUT request can only be used to
- create a working resource, and cannot be used to check out a
- version-controlled resource. If a server supports the checkout-in-
- place feature, but not the working-resource feature, a CHECKOUT can
- only be used to change the state of a version-controlled resource
- from checked-in to checked-out.
-
-9.1 Additional Version Properties
-
- The working-resource feature introduces the following REQUIRED
- properties for a version.
-
-9.1.1 DAV:checkout-fork
-
- This property is defined in Section 4.1.1.
-
-
-
-Clemm, et al. Standards Track [Page 62]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-9.1.2 DAV:checkin-fork
-
- This property is defined in Section 4.1.2.
-
-9.2 Working Resource Properties
-
- The working-resource feature introduces the following REQUIRED
- properties for a working resource. Since a working resource is a
- checked-out resource, it also has any property defined in this
- document for a checked-out resource.
-
-9.2.1 DAV:auto-update (protected)
-
- This property identifies the version-controlled resource that will be
- updated when the working resource is checked in.
-
- <!ELEMENT auto-update (href)>
-
-9.2.2 DAV:checkout-fork
-
- This property is defined in Section 4.2.1.
-
-9.2.3 DAV:checkin-fork
-
- This property is defined in Section 4.2.2.
-
-9.3 CHECKOUT Method (applied to a version)
-
- A CHECKOUT request can be applied to a version to create a new
- working resource. The content and dead properties of the working
- resource are a copy of the version that was checked out.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:checkout XML
- element.
-
- <!ELEMENT checkout ANY>
-
- ANY value: A sequence of elements with at most one DAV:apply-to-
- version and at most one DAV:fork-ok element.
-
- <!ELEMENT apply-to-version EMPTY>
- <!ELEMENT fork-ok EMPTY>
-
- If a response body for a successful request is included,
- it MUST be a DAV:checkout-response XML element.
-
-
-
-
-Clemm, et al. Standards Track [Page 63]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <!ELEMENT checkout-response ANY>
-
- The response MUST include a Location header.
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:checkout-of-version-with-descendant-is-forbidden): See
- Section 4.3.
-
- (DAV:checkout-of-version-with-descendant-is-discouraged): See
- Section 4.3.
-
- (DAV:checkout-of-checked-out-version-is-forbidden): See Section
- 4.3.
-
- (DAV:checkout-of-checked-out-version-is-discouraged): See Section
- 4.3.
-
- Postconditions:
-
- (DAV:create-working-resource): If the request-URL identified a
- version, the Location response header MUST contain the URL of a
- new working resource. The DAV:checked-out property of the new
- working resource MUST identify the version that was checked out.
- The content and dead properties of the working resource MUST be
- copies of the content and dead properties of the DAV:checked-out
- version. The DAV:predecessor-set property of the working resource
- MUST be initialized to be the version identified by the request-
- URL. The DAV:auto-update property of the working resource MUST
- NOT exist.
-
- (DAV:create-working-resource-from-checked-in-version): If the
- request-URL identified a version-controlled resource, and
- DAV:apply-to-version is specified in the request body, the
- CHECKOUT is applied to the DAV:checked-in version of the version-
- controlled resource, and not the version-controlled resource
- itself. A new working resource is created and the version-
- controlled resource remains checked-in. The DAV:auto-update
- property of the working resource MUST identify the version-
- controlled resource.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 64]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-9.3.1 Example - CHECKOUT of a version
-
- >>REQUEST
-
- CHECKOUT /his/12/ver/V3 HTTP/1.1
- Host: repo.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Location: http://repo.webdav.org/wr/157
- Cache-Control: no-cache
-
- In this example, the version identified by
- http://repo.webdav.org/his/12/ver/V3 is checked out, and the new
- working resource is located at http://repo.webdav.org/wr/157.
-
-9.4 CHECKIN Method (applied to a working resource)
-
- A CHECKIN request can be applied to a working resource to produce a
- new version whose content and dead properties are a copy of those of
- the working resource. If the DAV:auto-update property of the working
- resource was set because the working resource was created by applying
- a CHECKOUT with the DAV:apply-to-version flag to a version-controlled
- resource, the CHECKIN request will also update the content and dead
- properties of that version-controlled resource to be those of the new
- version.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:checkin XML
- element.
-
- <!ELEMENT checkin ANY>
- ANY value: A sequence of elements with at most one DAV:fork-ok
- element.
-
- <!ELEMENT fork-ok EMPTY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:checkin-response XML element.
-
- <!ELEMENT checkin-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 65]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Preconditions:
-
- (DAV:must-be-checked-out): See Section 4.4.
-
- (DAV:version-history-is-tree) See Section 4.4.
-
- (DAV:checkin-fork-forbidden): See Section 4.4.
-
- (DAV:checkin-fork-discouraged): See Section 4.4.
-
- (DAV:no-overwrite-by-auto-update): If the DAV:auto-update property
- for the checked-out resource identifies a version-controlled
- resource, at least one of the versions identified by the
- DAV:predecessor-set property of the checked-out resource MUST
- identify a version that is either the same as or a descendant of
- the version identified by the DAV:checked-in property of that
- version-controlled resource.
-
- Postconditions:
-
- (DAV:create-version): See Section 4.4.
-
- (DAV:initialize-version-content-and-properties): See Section 4.4.
-
- (DAV:auto-update): If the DAV:auto-update property of the
- checked-out resource identified a version-controlled resource, an
- UPDATE request with the new version MUST have been applied to that
- version-controlled resource.
-
- (DAV:delete-working-resource): If the request-URL identifies a
- working resource and if DAV:keep-checked-out is not specified in
- the request body, the working resource is deleted.
-
-9.4.1 Example - CHECKIN of a working resource
-
- >>REQUEST
-
- CHECKIN /wr/157 HTTP/1.1
- Host: repo.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Location: http://repo.webdav.org/his/23/ver/15
- Cache-Control: no-cache
-
-
-
-
-
-Clemm, et al. Standards Track [Page 66]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In this example, the working resource /wr/157 checked in, and a new
- version is created at http://repo.webdav.org/his/23/ver/15.
-
-9.5 Additional OPTIONS Semantics
-
- If the server supports the working-resource feature, it MUST include
- "working-resource" as a field in the DAV response header from an
- OPTIONS request on any resource that supports any versioning
- properties, reports, or methods.
-
-9.6 Additional COPY Semantics
-
- Additional Postconditions:
-
- (DAV:copy-creates-new-resource): The result of copying a working
- resource is a new non-version-controlled resource at the
- destination of the COPY. The new resource MAY automatically be
- put under version control, but the resulting version-controlled
- resource MUST be associated with a new version history created for
- that new version-controlled resource.
-
-9.7 Additional MOVE Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-rename-working-resource): If the request-URL
- identifies a working resource, the request MUST fail.
-
- Additional Postconditions:
-
- (DAV:update-auto-update): If the request-URL identified a
- version-controlled resource, any DAV:auto-update properties that
- identified that version-controlled resource MUST have been updated
- to contain the new location of that version-controlled resource.
-
-10 Advanced Versioning Features
-
- Advanced versioning addresses the problems of parallel development
- and configuration management of multiple sets of interrelated
- resources. Traditionally, artifacts of software development,
- including requirements, design documents, code, and test cases, have
- been a focus of configuration management. Web sites, comprising
- multiple inter-linked resources (HTML, graphics, sound, CGI, and
- others), are another class of complex information artifacts that
- benefit from the application of configuration management. The
- advanced versioning capabilities for coordinating concurrent change
- provide the infrastructure for efficient and controlled management of
- large evolving web sites.
-
-
-
-Clemm, et al. Standards Track [Page 67]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-10.1 Advanced Versioning Packages
-
- Although a server MAY support any combination of advanced versioning
- features, in order to minimize the complexity of a WebDAV advanced
- versioning client, a WebDAV advanced versioning server SHOULD support
- one of the following packages:
-
- Advanced-Server-Workspace Package: basic-server-workspace package
- plus all advanced features
-
- Advanced-Client-Workspace Package: basic-client-workspace package
- plus all advanced features
-
- The advanced-server-workspace package supports advanced versioning
- capabilities for a client with no persistent state. The advanced-
- client-workspace package supports advanced versioning capabilities
- for a client that maintains configuration state on the client. A
- server that supports both advanced workspace packages will
- interoperate with all versioning clients.
-
-10.2 Advanced Versioning Terms
-
- The following additional terms are used by the advanced versioning
- features.
-
- Collection
-
- A "collection" is a resource whose state consists of not only
- content and properties, but also a set of named "bindings", where
- a binding identifies what RFC 2518 calls an "internal member" of
- the collection. Note that a binding is not a resource, but rather
- is a part of the state of a collection that defines a mapping from
- a binding name (a URL segment) to a resource (an internal member
- of the collection).
-
- Collection Version Resource
-
- A "collection version resource", or simply "collection version",
- captures the dead properties of a version-controlled collection,
- as well as the names of its version-controlled bindings (see
- Section 14). A version-controlled binding is a binding to a
- version-controlled resource. If the checkout-in-place feature is
- supported, a collection version can be created by checking out and
- then checking in a version-controlled collection. If the
- working-resource feature is supported, a collection version can be
- created by checking out a collection version (to create a "working
- collection") and then checking in the working collection.
-
-
-
-
-Clemm, et al. Standards Track [Page 68]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Configuration
-
- A "configuration" is a set of resources that consists of a root
- collection and all members (not just internal members) of that
- root collection that are not members of another configuration.
- The root collection is called the "configuration root", and the
- members of this set are called the "members of the configuration".
- Note that a collection (which is a single resource) is very
- different from a configuration (which is a set of resources).
-
- Baseline Resource
-
- A "baseline resource", or simply "baseline", of a collection is a
- version of the configuration that is rooted at that collection
- (see Section 12). In particular, a baseline captures the
- DAV:checked-in version of every version-controlled member of that
- configuration. Note that a collection version (which captures the
- state of a single resource) is very different from a collection
- baseline (which captures the state of a set of resources).
-
- Baseline-Controlled Collection
-
- A "baseline-controlled collection" is a collection from which
- baselines can be created (see Section 12).
-
- Version-Controlled Configuration Resource
-
- A "version-controlled configuration resource", or simply
- "version-controlled configuration", is a special kind of version-
- controlled resource that is associated with a baseline-controlled
- collection, and is used to create and access baselines of that
- collection (see Section 12). When a collection is both version-
- controlled and baseline-controlled, a client can create a new
- version of the collection by checking out and checking in that
- collection, and it can create a new baseline of that collection by
- checking out and checking in the version-controlled configuration
- of that collection.
-
- Activity Resource
-
- An "activity resource", or simply "activity", is a resource that
- selects a set of versions that correspond to a single logical
- change, where the versions selected from a given version history
- form a single line of descent through that version history (see
- Section 13).
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 69]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-11 Merge Feature
-
- When a user wants to accept the changes (new versions) created by
- someone else, it is important not just to update the version-
- controlled resources in the user's workspace with those new versions,
- since this could result in "backing out" changes the user has made to
- those version-controlled resources. Instead, the versions created in
- another workspace should be "merged" into the user's version-
- controlled resources.
-
- The version history of a version-controlled resource provides the
- information needed to determine the result of the merge. In
- particular, the merge should select whichever version is later in the
- line of descent from the root version. In case the versions to be
- merged are on different lines of descent (neither version is a
- descendant of the other), neither version should be selected, but
- instead, a new version should be created that contains the logical
- merge of the content and dead properties of those versions. The
- MERGE request can be used to check out each version-controlled
- resource that requires such a merge, and set the DAV:merge-set
- property of each checked-out resource to identify the version to be
- merged. The user is responsible for modifying the content and dead
- properties of the checked-out resource so that it represents the
- logical merge of that version, and then adding that version to the
- DAV:predecessor-set of the checked-out resource.
-
- If the server is capable of automatically performing the merge, it
- MAY update the content, dead properties, and DAV:predecessor-set of
- the checked-out resource itself. Before checking in the
- automatically merged resource, the user is responsible for verifying
- that the automatic merge is correct.
-
-11.1 Additional Checked-Out Resource Properties
-
- The merge feature introduces the following REQUIRED properties for a
- checked-out resource.
-
-11.1.1 DAV:merge-set
-
- This property identifies each version that is to be merged into this
- checked-out resource.
-
- <!ELEMENT merge-set (href*)>
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 70]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-11.1.2 DAV:auto-merge-set
-
- This property identifies each version that the server has merged into
- this checked-out resource. The client should confirm that the merge
- has been performed correctly before moving a URL from the DAV:auto-
- merge-set to the DAV:predecessor-set of a checked-out resource.
-
- <!ELEMENT auto-merge-set (href*)>
-
-11.2 MERGE Method
-
- The MERGE method performs the logical merge of a specified version
- (the "merge source") into a specified version-controlled resource
- (the "merge target"). If the merge source is neither an ancestor nor
- a descendant of the DAV:checked-in or DAV:checked-out version of the
- merge target, the MERGE checks out the merge target (if it is not
- already checked out) and adds the URL of the merge source to the
- DAV:merge-set of the merge target. It is then the client's
- responsibility to update the content and dead properties of the
- checked-out merge target so that it reflects the logical merge of the
- merge source into the current state of the merge target. The client
- indicates that it has completed the update of the merge target, by
- deleting the merge source URL from the DAV:merge-set of the checked-
- out merge target, and adding it to the DAV:predecessor-set. As an
- error check for a client forgetting to complete a merge, the server
- MUST fail an attempt to CHECKIN a version-controlled resource with a
- non-empty DAV:merge-set.
-
- When a server has the ability to automatically update the content and
- dead properties of the merge target to reflect the logical merge of
- the merge source, it may do so unless DAV:no-auto-merge is specified
- in the MERGE request body. In order to notify the client that a
- merge source has been automatically merged, the MERGE request MUST
- add the URL of the auto-merged source to the DAV:auto-merge-set
- property of the merge target, and not to the DAV:merge-set property.
- The client indicates that it has verified that the auto-merge is
- valid, by deleting the merge source URL from the DAV:auto-merge-set,
- and adding it to the DAV:predecessor-set.
-
- Multiple merge sources can be specified in a single MERGE request.
- The set of merge sources for a MERGE request is determined from the
- DAV:source element of the MERGE request body as follows:
-
- - If DAV:source identifies a version, that version is a merge
- source.
- - If DAV:source identifies a version-controlled resource, the
- DAV:checked-in version of that version-controlled resource is a
- merge source.
-
-
-
-Clemm, et al. Standards Track [Page 71]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- - If DAV:source identifies a collection, the DAV:checked-in version
- of each version-controlled resource that is a member of that
- collection is a merge source.
-
- The request-URL identifies the set of possible merge targets. If the
- request-URL identifies a collection, any member of the configuration
- rooted at the request-URL is a possible merge target. The merge
- target of a particular merge source is the version-controlled or
- checked-out resource whose DAV:checked-in or DAV:checked-out version
- is from the same version history as the merge source. If a merge
- source has no merge target, that merge source is ignored.
-
- The MERGE response identifies the resources that a client must modify
- to complete the merge. It also identifies the resources modified by
- the request, so that a client can efficiently update any cached state
- it is maintaining.
-
- Marshalling:
-
- The request body MUST be a DAV:merge element.
-
- The set of merge sources is determined by the DAV:source element
- in the request body.
-
- <!ELEMENT merge ANY>
- ANY value: A sequence of elements with one DAV:source element, at
- most one DAV:no-auto-merge element, at most one DAV:no-checkout
- element, at most one DAV:prop element, and any legal set of
- elements that can occur in a DAV:checkout element.
- <!ELEMENT source (href+)>
- <!ELEMENT no-auto-merge EMPTY>
- <!ELEMENT no-checkout EMPTY>
- prop: see RFC 2518, Section 12.11
-
- The response for a successful request MUST be a 207 Multi-Status,
- where the DAV:multistatus XML element in the response body
- identifies all resources that have been modified by the request.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response to a successful request MUST include a Location
- header containing the URL for the new version created by the
- checkin.
-
- The response MUST include a Cache-Control:no-cache header.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 72]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Preconditions:
-
- (DAV:cannot-merge-checked-out-resource): The DAV:source element
- MUST NOT identify a checked-out resource. If the DAV:source
- element identifies a collection, the collection MUST NOT have a
- member that is a checked-out resource.
-
- (DAV:checkout-not-allowed): If DAV:no-checkout is specified in the
- request body, it MUST be possible to perform the merge without
- checking out any of the merge targets.
-
- All preconditions of the CHECKOUT operation apply to the checkouts
- performed by the request.
-
- Postconditions:
-
- (DAV:ancestor-version): If a merge target is a version-controlled
- or checked-out resource whose DAV:checked-in version or
- DAV:checked-out version is the merge source or is a descendant of
- the merge source, the merge target MUST NOT have been modified by
- the MERGE.
-
- (DAV:descendant-version): If the merge target was a checked-in
- version-controlled resource whose DAV:checked-in version was an
- ancestor of the merge source, an UPDATE operation MUST have been
- applied to the merge target to set its content and dead properties
- to be those of the merge source. If the UPDATE method is not
- supported, the merge target MUST have been checked out, the
- content and dead properties of the merge target MUST have been set
- to those of the merge source, and the merge source MUST have been
- added to the DAV:auto-merge-set of the merge target. The merge
- target MUST appear in a DAV:response XML element in the response
- body.
-
- (DAV:checked-out-for-merge): If the merge target was a checked-in
- version-controlled resource whose DAV:checked-in version was
- neither a descendant nor an ancestor of the merge source, a
- CHECKOUT MUST have been applied to the merge target. All XML
- elements in the DAV:merge XML element that could appear in a
- DAV:checkout XML element MUST have been used as arguments to the
- CHECKOUT request. The merge target MUST appear in a DAV:response
- XML element in the response body.
-
- (DAV:update-merge-set): If the DAV:checked-out version of the
- merge target is neither equal to nor a descendant of the merge
- source, the merge source MUST be added to either the DAV:merge-set
- or the DAV:auto-merge-set of the merge target. The merge target
- MUST appear in a DAV:response XML element in the response body.
-
-
-
-Clemm, et al. Standards Track [Page 73]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- If a merge source has been added to the DAV:auto-merge-set, the
- content and dead properties of the merge target MUST have been
- modified by the server to reflect the result of a logical merge of
- the merge source and the merge target. If a merge source has been
- added to the DAV:merge-set, the content and dead properties of the
- merge target MUST NOT have been modified by the server. If
- DAV:no-auto-merge is specified in the request body, the merge
- source MUST NOT have been added to the DAV:auto-merge-set.
-
- (DAV:report-properties): If DAV:prop is specified in the request
- body, the properties specified in the DAV:prop element MUST be
- reported in the DAV:response elements in the response body.
-
-11.2.1 Example - MERGE
-
- >>REQUEST
-
- MERGE /ws/public HTTP/1.1
- Host: www.webdav.org
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:merge xmlns:D="DAV:">
- <D:source>
- <D:href>http://www.webdav.org/ws/dev/sally</D:href>
- </D:source>
- </D:merge>
-
- >>RESPONSE
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Cache-Control: no-cache
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.webdav.org/ws/public/src/parse.c</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:response>
- <D:response>
- <D:href>http://www.webdav.org/ws/public/doc/parse.html</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:response>
- </D:multistatus>
-
-
-
-
-Clemm, et al. Standards Track [Page 74]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In this example, the DAV:checked-in versions from the workspace
- http://www.webdav.org/ws/dev/sally are merged into the version-
- controlled resources in the workspace
- http://www.webdav.org/ws/public. The resources
- /ws/public/src/parse.c and /ws/public/doc/parse.html were modified by
- the request.
-
-11.3 DAV:merge-preview Report
-
- A merge preview describes the changes that would result if the
- versions specified by the DAV:source element in the request body were
- to be merged into the resource identified by the request-URL
- (commonly, a collection).
-
- Marshalling:
-
- The request body MUST be a DAV:merge-preview XML element.
-
- <!ELEMENT merge-preview (source)>
- <!ELEMENT source (href)>
-
- The response body for a successful request MUST be a
- DAV:merge-preview-report XML element.
-
- <!ELEMENT merge-preview-report
- (update-preview | conflict-preview | ignore-preview)*>
-
- A DAV:update-preview element identifies a merge target whose
- DAV:checked-in property would change as a result of the MERGE, and
- identifies the merge source for that merge target.
-
- <!ELEMENT update-preview (target, version)>
- <!ELEMENT target (href)>
- <!ELEMENT version (href)>
-
- A DAV:conflict-preview element identifies a merge target that
- requires a merge.
-
- <!ELEMENT conflict-preview (target, common-ancestor, version)>
-
- A DAV:common-ancestor element identifies the version that is a
- common ancestor of both the merge source and the DAV:checked-in or
- DAV:checked-out version of the merge target.
-
- <!ELEMENT common-ancestor (href)>
-
- A DAV:ignore-preview element identifies a version that has no
- merge target and therefore would be ignored by the merge.
-
-
-
-Clemm, et al. Standards Track [Page 75]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <!ELEMENT ignore-preview (version)>
-
-11.3.1 Example - DAV:merge-preview Report
-
- >>REQUEST
-
- REPORT /ws/public HTTP/1.1
- Host: www.webdav.org
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:merge-preview xmlns:D="DAV:">
- <D:source>
- <D:href>http://www.webdav.org/ws/dev/fred</D:href>
- </D:source>
- </D:merge-preview>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:merge-preview-report xmlns:D="DAV:">
- <D:conflict-preview>
- <D:target>
- <D:href>http://www.webdav.org/ws/public/foo.html</D:href>
- </D:target>
- <D:common-ancestor>
- <D:href>http://repo.webdav.org/his/23/ver/18</D:href>
- </D:common-ancestor>
- <D:version>
- <D:href>http://repo.webdav.org/his/23/ver/42</D:href>
- </D:version>
- </D:conflict-preview>
- <D:update-preview>
- <D:target>
- <D:href>http://www.webdav.org/ws/public/bar.html</D:href>
- </D:target>
- <D:version>
- <D:href>http://www.repo/his/42/ver/3</D:href>
- </D:version>
- </D:update-preview>
- </D:merge-preview-report>
-
-
-
-
-
-Clemm, et al. Standards Track [Page 76]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In this example, the merge preview report indicates that version
- /his/23/ver/42 would be merged in /ws/public/foo.html, and version
- /his/42/ver/3 would update /ws/public/bar.html if the workspace
- http://www.webdav.org/ws/dev/fred was merged into the workspace
- http://www.webdav.org/ws/public.
-
-11.4 Additional OPTIONS Semantics
-
- If the server supports the merge feature, it MUST include "merge" as
- a field in the DAV response header from an OPTIONS request on any
- resource that supports any versioning properties, reports, or
- methods.
-
-11.5 Additional DELETE Semantics
-
- Additional Postconditions:
-
- (DAV:delete-version-reference): If a version is deleted, any
- reference to that version in a DAV:merge-set or DAV:auto-merge-set
- property MUST be removed.
-
-11.6 Additional CHECKIN Semantics
-
- Additional Preconditions:
-
- (DAV:merge-must-be-complete): The DAV:merge-set and DAV:auto-
- merge-set of the checked-out resource MUST be empty or not exist.
-
-12 Baseline Feature
-
- A configuration is a set of resources that consists of a root
- collection and all members of that root collection except those
- resources that are members of another configuration. A configuration
- that contains a large number of resources can consume a large amount
- of space on a server. This can make it prohibitively expensive to
- remember the state of an existing configuration by creating a
- Depth:infinity copy of its root collection.
-
- A baseline is a version resource that captures the state of each
- version-controlled member of a configuration. A baseline history is
- a version history whose versions are baselines. New baselines are
- created by checking out and then checking in a special kind of
- version-controlled resource called a version-controlled
- configuration.
-
- A collection that is under baseline control is called a baseline-
- controlled collection. In order to allow efficient baseline
- implementation, the state of a baseline of a collection is limited to
-
-
-
-Clemm, et al. Standards Track [Page 77]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- be a set of versions and their names relative to the collection, and
- the operations on a baseline are limited to the creation of a
- baseline from a collection, and restoring or merging the baseline
- back into a collection. A server MAY automatically put a collection
- under baseline control when it is created, or a client can use the
- BASELINE-CONTROL method to put a specified collection under baseline
- control.
-
- As a configuration gets large, it is often useful to break it up into
- a set of smaller configurations that form the logical "components" of
- that configuration. In order to capture the fact that a baseline of
- a configuration is logically extended by a component configuration
- baseline, the component configuration baseline is captured as a
- "subbaseline" of the baseline.
-
- The root collection of a configuration is unconstrained with respect
- to its relationship to the root collection of any of its components.
- In particular, the root collection of a configuration can have a
- member that is the root collection of one of its components (e.g.,
- configuration /sys/x can have a component /sys/x/foo), can be a
- member of the root collection of one of its components (e.g.,
- configuration /sys/y/z can have a component /sys/y), or neither
- (e.g., configuration /sys/x can have a component /comp/bar).
-
-12.1 Version-Controlled Configuration Properties
-
- Since a version-controlled configuration is a version-controlled
- resource, it has all the properties of a version-controlled resource.
- In addition, the baseline feature introduces the following REQUIRED
- property for a version-controlled configuration.
-
-12.1.1 DAV:baseline-controlled-collection (protected)
-
- This property identifies the collection that contains the version-
- controlled resources whose DAV:checked-in versions are being tracked
- by this version-controlled configuration. The DAV:version-
- controlled-configuration of the DAV:baseline-controlled-collection of
- a version-controlled configuration MUST identify that version-
- controlled configuration.
-
- <!ELEMENT baseline-controlled-collection (href)>
-
-12.2 Checked-Out Configuration Properties
-
- Since a checked-out configuration is a checked-out resource, it has
- all the properties of a checked-out resource. In addition, the
- baseline feature introduces the following REQUIRED property for a
- checked-out configuration.
-
-
-
-Clemm, et al. Standards Track [Page 78]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-12.2.1 DAV:subbaseline-set
-
- This property determines the DAV:subbaseline-set property of the
- baseline that results from checking in this resource.
-
- A server MAY reject attempts to modify the DAV:subbaseline-set of a
- checked-out configuration.
-
- <!ELEMENT subbaseline-set (href*)>
-
-12.3 Baseline Properties
-
- The DAV:resourcetype of a baseline MUST be DAV:baseline. Since a
- baseline is a version resource, it has all the properties of a
- version resource. In addition, the baseline feature introduces the
- following REQUIRED properties for a baseline.
-
-12.3.1 DAV:baseline-collection (protected)
-
- This property contains a server-defined URL for a collection, where
- each member of this collection MUST either be a version-controlled
- resource with the same DAV:checked-in version and relative name as a
- version-controlled member of the baseline-controlled collection at
- the time the baseline was created, or be a collection needed to
- provide the relative name for a version-controlled resource.
-
- <!ELEMENT baseline-collection (href)>
-
-12.3.2 DAV:subbaseline-set (protected)
-
- The URLs in the DAV:subbaseline-set property MUST identify a set of
- other baselines. The subbaselines of a baseline are the baselines
- identified by its DAV:subbaseline-set and all subbaselines of the
- baselines identified by its DAV:subbaseline-set.
-
- <!ELEMENT subbaseline-set (href*)>
-
-12.4 Additional Resource Properties
-
- The baseline feature introduces the following REQUIRED property for a
- resource.
-
-12.4.1 DAV:version-controlled-configuration (computed)
-
- If the resource is a member of a version-controlled configuration
- (i.e. the resource is a collection under baseline control or is a
- member of a collection under baseline control), this property
- identifies that version-controlled configuration.
-
-
-
-Clemm, et al. Standards Track [Page 79]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <!ELEMENT version-controlled-configuration (href)>
-
-12.5 Additional Workspace Properties
-
- The baseline feature introduces the following REQUIRED property for a
- workspace.
-
-12.5.1 DAV:baseline-controlled-collection-set (computed)
-
- This property identifies each member of the workspace that is a
- collection under baseline control (as well as the workspace itself,
- if it is under baseline control).
-
- <!ELEMENT baseline-controlled-collection-set (href*)>
-
-12.6 BASELINE-CONTROL Method
-
- A collection can be placed under baseline control with a
- BASELINE-CONTROL request. When a collection is placed under baseline
- control, the DAV:version-controlled-configuration property of the
- collection is set to identify a new version-controlled configuration.
- This version-controlled configuration can be checked out and then
- checked in to create a new baseline for that collection.
-
- If a baseline is specified in the request body, the DAV:checked-in
- version of the new version-controlled configuration will be that
- baseline, and the collection is initialized to contain version-
- controlled members whose DAV:checked-in versions and relative names
- are determined by the specified baseline.
-
- If no baseline is specified, a new baseline history is created
- containing a baseline that captures the state of the version-
- controlled members of the collection, and the DAV:checked-in version
- of the version-controlled configuration will be that baseline.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:baseline-control
- XML element.
-
- <!ELEMENT baseline-control ANY>
- ANY value: A sequence of elements with at most one DAV:baseline
- element.
-
- <!ELEMENT baseline (href)>
-
- If a response body for a successful request is included, it MUST
- be a DAV:baseline-control-response XML element.
-
-
-
-Clemm, et al. Standards Track [Page 80]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- <!ELEMENT baseline-control-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:version-controlled-configuration-must-not-exist): The
- DAV:version-controlled-configuration property of the collection
- identified by the request-URL MUST not exist.
-
- (DAV:must-be-baseline): The DAV:href of the DAV:baseline element
- in the request body MUST identify a baseline.
-
- (DAV:must-have-no-version-controlled-members): If a DAV:baseline
- element is specified in the request body, the collection
- identified by the request-URL MUST have no version-controlled
- members.
-
- (DAV:one-baseline-controlled-collection-per-history-per-
- workspace): If the request-URL identifies a workspace or a member
- of a workspace, and if a baseline is specified in a DAV:baseline
- element in the request body, then there MUST NOT be another
- collection in that workspace whose DAV:version-controlled-
- configuration property identifies a version-controlled
- configuration for the baseline history of that baseline.
-
- Postconditions:
-
- (DAV:create-version-controlled-configuration): A new version-
- controlled configuration is created, whose DAV:baseline-
- controlled-collection property identifies the collection.
-
- (DAV:reference-version-controlled-configuration): The
- DAV:version-controlled-configuration of the collection identifies
- the new version-controlled configuration.
-
- (DAV:select-existing-baseline): If the request body specifies a
- baseline, the DAV:checked-in property of the new version-
- controlled configuration MUST have been set to identify this
- baseline. A version-controlled member of the collection will be
- created for each version in the baseline, where the version-
- controlled member will have the content and dead properties of
- that version, and will have the same name relative to the
- collection as the corresponding version-controlled resource had
- when the baseline was created. Any nested collections that are
- needed to provide the appropriate name for a version-controlled
- member will be created.
-
-
-
-
-Clemm, et al. Standards Track [Page 81]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:create-new-baseline): If no baseline is specified in the
- request body, the request MUST have created a new baseline history
- at a server-defined URL, and MUST have created a new baseline in
- that baseline history. The DAV:baseline-collection of the new
- baseline MUST identify a collection whose members have the same
- relative name and DAV:checked-in version as the version-controlled
- members of the request collection. The DAV:checked-in property of
- the new version-controlled configuration MUST identify the new
- baseline.
-
-12.6.1 Example - BASELINE-CONTROL
-
- >>REQUEST
-
- BASELINE-CONTROL /src HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:baseline-control xmlns:D="DAV:">
- <D:href>http://www.webdav.org/repo/blh/13/ver/8</D:href>
- </D:baseline-control>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Cache-Control: no-cache
- Content-Length: 0
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 82]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In this example, the collection /src is placed under baseline
- control, and is populated with members from an existing baseline. A
- new version-controlled configuration (/repo/vcc/128) is created and
- associated with /src, and /src is initialized with version-controlled
- members whose DAV:checked-in versions are those selected by the
- DAV:baseline-collection (/repo/bc/15) of the specified baseline
- (/repo/blh/13/ver/8). The following diagram illustrates the
- resulting state on the server.
-
- +-------------------------------------+
- |Baseline-Controlled Collection |<------+
- |/src | |
- |-------------------------------------| |
- |DAV:version-controlled-configuration +---+ |
- +-------------------------------------+ | |
- | |
- | |
- +-------------------------------------+ | |
- |Version-Controlled Configuration |<--+ |
- |/repo/vcc/128 | |
- |-------------------------------------| |
- |DAV:baseline-controlled-collection +-------+
- |-------------------------------------|
- |DAV:checked-in +-------+
- +-------------------------------------+ |
- |DAV:version-history +---+ |
- +-------------------------------------+ | |
- | |
- | |
- +------------------------+ | |
- |Baseline History |<---------------+ |
- |/repo/blh/13 | |
- |------------------------+ |
- |DAV:version-set +----------------+ |
- +------------------------+ | | | | |
- v | v v |
- | |
- +------------------------+ | |
- |Baseline |<-------+-----------+
- |/repo/blh/13/ver/8 |
- |------------------------+ +--------------+
- |DAV:baseline-collection +---->|Collection |
- +------------------------+ |/repo/bc/15 |
- +--------------+
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 83]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- In order to create new baselines of /src, /repo/vcc/128 can be
- checked out, new versions can be created or selected by the version-
- controlled members of /src, and then /repo/vcc/128 can be checked in
- to capture the current state of those version-controlled members.
-
-12.7 DAV:compare-baseline Report
-
- A DAV:compare-baseline report contains the differences between the
- baseline identified by the request-URL (the "request baseline") and
- the baseline specified in the request body (the "compare baseline").
-
- Marshalling:
-
- The request body MUST be a DAV:compare-baseline XML element.
-
- <!ELEMENT compare-baseline (href)>
-
- The response body for a successful request MUST be a DAV:compare-
- baseline-report XML element.
-
- <!ELEMENT compare-baseline-report
- (added-version | deleted-version | changed-version)*>
-
- A DAV:added-version element identifies a version that is the
- DAV:checked-in version of a member of the DAV:baseline-collection
- of the compare baseline, but no version in the version history of
- that version is the DAV:checked-in version of a member of the
- DAV:baseline-collection of the request baseline.
-
- <!ELEMENT added-version (href)>
-
- A DAV:deleted-version element identifies a version that is the
- DAV:checked-in version of a member of the DAV:baseline-collection
- of the request baseline, but no version in the version history of
- that version is the DAV:checked-in version of a member of the
- DAV:baseline-collection of the compare baseline.
-
- <!ELEMENT deleted-version (href)>
-
- A DAV:changed-version element identifies two different versions
- from the same version history that are the DAV:checked-in version
- of the DAV:baseline-collection of the request baseline and the
- compare baseline, respectively.
-
- <!ELEMENT changed-version (href, href)>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 84]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Preconditions:
-
- (DAV:must-be-baseline): The DAV:href in the request body MUST
- identify a baseline.
-
- (DAV:baselines-from-same-history): A server MAY require that the
- baselines being compared be from the same baseline history.
-
-12.7.1 Example - DAV:compare-baseline Report
-
- >>REQUEST
-
- REPORT /bl-his/12/bl/14 HTTP/1.1
- Host: repo.webdav.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:compare-baseline xmlns:D="DAV:">
- <D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
- </D:compare-baseline>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:compare-baseline-report xmlns:D="DAV:">
- <D:added-version>
- <D:href>http://repo.webdav.org/his/23/ver/8</D:href>
- </D:added-version>
- <D:changed-version>
- <D:href>http://repo.webdav.org/his/29/ver/12</D:href>
- <D:href>http://repo.webdav.org/his/29/ver/19</D:href>
- </D:changed-version>
- <D:deleted-version>
- <D:href>http://repo.webdav.org/his/12/ver/4</D:href>
- </D:deleted-version>
- </D:compare-baseline-report>
-
- In this example, the differences between baseline 14 and baseline 15
- of http://repo.webdav.org/bl-his/12 are identified.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 85]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-12.8 Additional OPTIONS Semantics
-
- If a server supports the baseline feature, it MUST include "baseline"
- as a field in the DAV response header from an OPTIONS request on any
- resource that supports any versioning properties, reports, or
- methods.
-
-12.9 Additional MKCOL Semantics
-
- Additional Postconditions:
-
- If a server automatically puts a newly created collection under
- baseline control, all postconditions for BASELINE-CONTROL apply to
- the MKCOL.
-
-12.10 Additional COPY Semantics
-
- Additional Postconditions:
-
- If the request creates a new collection at the Destination, and a
- server automatically puts a newly created collection under
- baseline control, all postconditions for BASELINE-CONTROL apply to
- the COPY.
-
-12.11 Additional CHECKOUT Semantics
-
- Additional Preconditions:
-
- (DAV:must-not-update-baseline-collection): If the request-URL
- identifies a member of the configuration rooted at the
- DAV:baseline-collection of a baseline, the request MUST fail.
-
-12.12 Additional CHECKIN Semantics
-
- Additional Preconditions:
-
- (DAV:no-checked-out-baseline-controlled-collection-members): If
- the request-URL identifies a version-controlled configuration, all
- version-controlled members of the DAV:baseline-controlled-
- collection of the version-controlled configuration MUST be
- checked-in.
-
- (DAV:one-version-per-history-per-baseline): If the request-URL
- identifies a version-controlled configuration, the set of versions
- selected by that version-controlled configuration MUST contain at
- most one version from any version history, where a version is
- selected by a version-controlled configuration if the version is
- identified by the DAV:checked-in property of any member of the
-
-
-
-Clemm, et al. Standards Track [Page 86]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- configuration rooted at the DAV:baseline-controlled collection of
- that version-controlled configuration, or is identified by the
- DAV:checked-in property of any member of the configuration rooted
- at the DAV:baseline-collection of any subbaseline of that
- version-controlled configuration.
-
- (DAV:cannot-modify-version-controlled-configuration): If the
- request-URL identifies a version-controlled member of a baseline-
- controlled collection whose version-controlled configuration is
- checked-in, the request MUST fail unless the DAV:auto-version
- property of the version-controlled configuration will
- automatically check out that version-controlled configuration when
- it is modified.
-
- Additional Postconditions:
-
- (DAV:create-baseline-collection): If the request-URL identifies a
- version-controlled configuration, the DAV:baseline-collection of
- the new baseline identifies a collection whose members have the
- same relative name and DAV:checked-in version as the members of
- the DAV:baseline-controlled-collection of the version-controlled
- configuration at the time of the request.
-
- (DAV:modify-configuration): If the request-URL identifies a
- version-controlled member of a baseline-controlled collection,
- this is a modification to the version-controlled configuration of
- that baseline-controlled collection, and standard auto-versioning
- semantics apply.
-
-12.13 Additional UPDATE Semantics
-
- Additional Preconditions:
-
- (DAV:baseline-controlled-members-must-be-checked-in): If the
- request-URL identifies a version-controlled configuration, then
- all version-controlled members of the DAV:baseline-controlled-
- collection of that version-controlled configuration MUST be
- checked-in.
-
- (DAV:must-not-update-baseline-collection): If the request-URL
- identifies a member of the configuration rooted at the
- DAV:baseline-collection of a baseline, the request MUST fail.
-
- (DAV:cannot-modify-version-controlled-configuration): If the
- request updates the DAV:checked-in property of any version-
- controlled member of a baseline-controlled collection whose
- version-controlled configuration is checked-in, the request MUST
-
-
-
-
-Clemm, et al. Standards Track [Page 87]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- fail unless the DAV:auto-version property of the version-
- controlled configuration will automatically check out that
- version-controlled configuration when it is modified.
-
- Additional Postconditions:
-
- (DAV:set-baseline-controlled-collection-members): If the request
- updated the DAV:checked-in property of a version-controlled
- configuration, then the version-controlled members of the
- DAV:baseline-controlled-collection of that version-controlled
- configuration MUST have been updated so that they have the same
- relative name, content, and dead properties as the members of the
- DAV:baseline-collection of the baseline. In particular:
-
- - A version-controlled member for a given version history MUST
- have been deleted if there is no version-controlled member for
- that version history in the DAV:baseline-collection of the
- baseline.
- - A version-controlled member for a given version history MUST
- have been renamed if its name relative to the baseline-
- controlled collection is different from that of the version-
- controlled member for that version history in the
- DAV:baseline-collection of the baseline.
- - A new version-controlled member MUST have been created for each
- member of the DAV:baseline-collection of the baseline for which
- there is no corresponding version-controlled member in the
- baseline-controlled collection.
- - An UPDATE request MUST have been applied to each version-
- controlled member for a given version history whose
- DAV:checked-in version is not the same as that of the version-
- controlled member for that version history in the
- DAV:baseline-collection of the baseline.
-
- (DAV:update-subbaselines): If the request updated a version-
- controlled configuration whose DAV:baseline-controlled-collection
- contains a baseline-controlled member for one of the subbaselines
- of the request baseline, then the DAV:checked-in property of the
- version-controlled configuration of that baseline-controlled
- member MUST have been updated to be that subbaseline. If the
- request updated a version-controlled configuration whose
- DAV:baseline-controlled-collection is a member of a workspace that
- contains a baseline-controlled member for one of the subbaselines
- of the request baseline, then the DAV:checked-in property of the
- version-controlled configuration of that baseline-controlled
- member MUST have been updated to be that subbaseline.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 88]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:modify-configuration): If the request updated the
- DAV:checked-in property of any version-controlled member of a
- baseline-controlled collection, and if this DAV:checked-in
- property differs from the DAV:checked-in property of the
- corresponding version-controlled member of the DAV:baseline-
- collection of the DAV:checked-in baseline of the DAV:version-
- controlled-configuration of the baseline-controlled collection,
- then this is a modification to that version-controlled
- configuration, and standard auto-versioning semantics apply.
-
-12.14 Additional MERGE Semantics
-
- If the merge source is a baseline, the merge target is a version-
- controlled configuration for the baseline history of that baseline,
- where the baseline-controlled collection of that version-controlled
- configuration is a member of the collection identified by the
- request-URL.
-
- Additional Preconditions:
-
- (DAV:must-not-update-baseline-collection): Same semantics as
- UPDATE (see Section 12.13).
-
- (DAV:cannot-modify-version-controlled-configuration): Same
- semantics as UPDATE (see Section 12.13).
-
- Additional Postconditions:
-
- (DAV:merge-baseline): If the merge target is a version-controlled
- configuration whose DAV:checked-out baseline is not a descendant
- of the merge baseline, then the merge baseline MUST have been
- added to the DAV:auto-merge-set of a version-controlled
- configuration. The DAV:checked-in version of each member of the
- DAV:baseline-collection of that baseline MUST have been merged
- into the DAV:baseline-controlled-collection of that version-
- controlled configuration.
-
- (DAV:merge-subbaselines): If the merge target is a version-
- controlled configuration whose DAV:baseline-controlled-collection
- contains a baseline-controlled member for one of the subbaselines
- of the merge baseline, then that subbaseline MUST have been merged
- into the version-controlled configuration of that baseline-
- controlled member. If the merge target is a version-controlled
- configuration whose DAV:baseline-controlled-collection is a member
- of a workspace that contains a baseline-controlled member for one
- of the subbaselines of the merge baseline, then that subbaseline
- MUST have been merged into the version-controlled configuration of
- that baseline-controlled member.
-
-
-
-Clemm, et al. Standards Track [Page 89]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- (DAV:set-baseline-controlled-collection-members): Same semantics
- as UPDATE (see Section 12.13).
-
- (DAV:modify-configuration): Same semantics as UPDATE (see Section
- 12.13).
-
-13 Activity Feature
-
- An activity is a resource that selects a set of versions that are on
- a single "line of descent", where a line of descent is a sequence of
- versions connected by successor relationships. If an activity
- selects versions from multiple version histories, the versions
- selected in each version history must be on a single line of descent.
-
- A common problem that motivates the use of activities is that it is
- often desirable to perform several different logical changes in a
- single workspace, and then selectively merge a subset of those
- logical changes to other workspaces. An activity can be used to
- represent a single logical change, where an activity tracks all the
- resources that were modified to effect that single logical change.
- When a version-controlled resource is checked out, the user specifies
- which activity should be associated with a new version that will be
- created when that version-controlled resource is checked in. It is
- then possible to select a particular logical change for merging into
- another workspace, by specifying the appropriate activity in a MERGE
- request.
-
- Another common problem is that although a version-controlled resource
- may need to have multiple lines of descent, all work done by members
- of a given team must be on a single line of descent (to avoid merging
- between team members). An activity resource provides the mechanism
- for addressing this problem. When a version-controlled resource is
- checked out, a client can request that an existing activity be used
- or that a new activity be created. Activity semantics then ensure
- that all versions in a given version history that are associated with
- an activity are on a single line of descent. If all members of a
- team share a common activity (or sub-activities of a common
- activity), then all changes made by members of that team will be on a
- single line of descent.
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 90]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- The following diagram illustrates activities. Version V5 is the
- latest version of foo.html selected by activity Act-2, and version V8
- is the latest version of bar.html selected by activity Act-2.
-
- foo.html History bar.html History
-
- +---+ +---+
- Act-1| |V1 Act-1| |V6
- +---+ +---+
- | |
- | |
- +---+ +---+
- Act-1| |V2 Act-2| |V7
- +---+ +---+
- / \ |
- / \ |
- +---+ +---+ +---+
- Act-1| |V3 Act-2| |V4 Act-2| |V8
- +---+ +---+ +---+
- | |
- | |
- +---+ +---+
- Act-2| |V5 Act-3| |V9
- +---+ +---+
-
- Activities appear under a variety of names in existing versioning
- systems. When an activity is used to capture a logical change, it is
- commonly called a "change set". When an activity is used to capture
- a line of descent, it is commonly called a "branch". When a system
- supports both branches and change sets, it is often useful to require
- that a particular change set occur on a particular branch. This
- relationship can be captured by making the change set activity be a
- "subactivity" of the branch activity.
-
-13.1 Activity Properties
-
- The DAV:resourcetype of an activity MUST be DAV:activity.
-
- The activity feature introduces the following REQUIRED properties for
- an activity.
-
-13.1.1 DAV:activity-version-set (computed)
-
- This property identifies each version whose DAV:activity-set property
- identifies this activity. Multiple versions of a single version
- history can be selected by an activity's DAV:activity-version-set
-
-
-
-
-
-Clemm, et al. Standards Track [Page 91]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- property, but all DAV:activity-version-set versions from a given
- version history must be on a single line of descent from the root
- version of that version history.
-
- <!ELEMENT activity-version-set (href*)>
-
-13.1.2 DAV:activity-checkout-set (computed)
-
- This property identifies each checked-out resource whose
- DAV:activity-set identifies this activity.
-
- <!ELEMENT activity-checkout-set (href*)>
-
-13.1.3 DAV:subactivity-set
-
- This property identifies each activity that forms a part of the
- logical change being captured by this activity. An activity behaves
- as if its DAV:activity-version-set is extended by the DAV:activity-
- version-set of each activity identified in the DAV:subactivity-set.
- In particular, the versions in this extended set MUST be on a single
- line of descent, and when an activity selects a version for merging,
- the latest version in this extended set is the one that will be
- merged.
-
- A server MAY reject attempts to modify the DAV:subactivity-set of an
- activity.
-
- <!ELEMENT subactivity-set (href*)>
-
-13.1.4 DAV:current-workspace-set (computed)
-
- This property identifies each workspace whose DAV:current-activity-
- set identifies this activity.
-
- <!ELEMENT current-workspace-set (href*)>
-
-13.2 Additional Version Properties
-
- The activity feature introduces the following REQUIRED property for a
- version.
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 92]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.2.1 DAV:activity-set
-
- This property identifies the activities that determine to which
- logical changes this version contributes, and on which lines of
- descent this version appears. A server MAY restrict the
- DAV:activity-set to identify a single activity. A server MAY refuse
- to allow the value of the DAV:activity-set property of a version to
- be modified.
-
- <!ELEMENT activity-set (href*)>
-
-13.3 Additional Checked-Out Resource Properties
-
- The activity feature introduces the following REQUIRED properties for
- a checked-out resource.
-
-13.3.1 DAV:unreserved
-
- This property of a checked-out resource indicates whether the
- DAV:activity-set of another checked-out resource associated with the
- version history of this version-controlled resource can have an
- activity that is in the DAV:activity-set property of this checked-out
- resource.
-
- A result of the requirement that an activity must form a single line
- of descent through a given version history is that if multiple
- checked-out resources for a given version history are checked out
- unreserved into a single activity, only the first CHECKIN will
- succeed. Before another of these checked-out resources can be
- checked in, the user will first have to merge into that checked-out
- resource the latest version selected by that activity from that
- version history, and then modify the DAV:predecessor-set of that
- checked-out resource to identify that version.
-
- <!ELEMENT unreserved (#PCDATA)>
- PCDATA value: boolean
-
-13.3.2 DAV:activity-set
-
- This property of a checked-out resource determines the DAV:activity-
- set property of the version that results from checking in this
- resource.
-
-13.4 Additional Workspace Properties
-
- The activity feature introduces the following REQUIRED property for a
- workspace.
-
-
-
-
-Clemm, et al. Standards Track [Page 93]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.4.1 DAV:current-activity-set
-
- This property identifies the activities that currently are being
- performed in this workspace. When a member of this workspace is
- checked out, if no activity is specified in the checkout request, the
- DAV:current-activity-set will be used. This allows an activity-
- unaware client to update a workspace in which activity tracking is
- required. The DAV:current-activity-set MAY be restricted to identify
- at most one activity.
-
- <!ELEMENT current-activity-set (href*)>
-
-13.5 MKACTIVITY Method
-
- A MKACTIVITY request creates a new activity resource. A server MAY
- restrict activity creation to particular collections, but a client
- can determine the location of these collections from a DAV:activity-
- collection-set OPTIONS request.
-
- Marshalling:
-
- If a request body is included, it MUST be a DAV:mkactivity XML
- element.
-
- <!ELEMENT mkactivity ANY>
-
- If a response body for a successful request is included, it MUST
- be a DAV:mkactivity-response XML element.
-
- <!ELEMENT mkactivity-response ANY>
-
- The response MUST include a Cache-Control:no-cache header.
-
- Preconditions:
-
- (DAV:resource-must-be-null): A resource MUST NOT exist at the
- request-URL.
-
- (DAV:activity-location-ok): The request-URL MUST identify a
- location where an activity can be created.
-
- Postconditions:
-
- (DAV:initialize-activity): A new activity exists at the request-
- URL. The DAV:resourcetype of the activity MUST be DAV:activity.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 94]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.5.1 Example - MKACTIVITY
-
- >>REQUEST
-
- MKACTIVITY /act/test-23 HTTP/1.1
- Host: repo.webdav.org
- Content-Length: 0
-
- >>RESPONSE
-
- HTTP/1.1 201 Created
- Cache-Control: no-cache
-
- In this example, a new activity is created at
- http://repo.webdav.org/act/test-23.
-
-13.6 DAV:latest-activity-version Report
-
- The DAV:latest-activity-version report can be applied to a version
- history to identify the latest version that is selected from that
- version history by a given activity.
-
- Marshalling:
-
- The request body MUST be a DAV:latest-activity-version XML
- element.
-
- <!ELEMENT latest-activity-version (href)>
-
- The response body for a successful request MUST be a DAV:latest-
- activity-version-report XML element.
-
- <!ELEMENT latest-activity-version-report (href)>
-
- The DAV:href of the response body MUST identify the version of the
- given version history that is a member of the DAV:activity-
- version-set of the given activity and has no descendant that is a
- member of the DAV:activity-version-set of that activity.
-
- Preconditions:
-
- (DAV:must-be-activity): The DAV:href in the request body MUST
- identify an activity.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 95]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.7 Additional OPTIONS Semantics
-
- If the server supports the activity feature, it MUST include
- "activity" as a field in the DAV response header from an OPTIONS
- request on any resource that supports any versioning properties,
- reports, or methods.
-
- A DAV:activity-collection-set element MAY be included in the request
- body to identify collections that may contain activity resources.
-
- Additional Marshalling:
-
- If an XML request body is included, it MUST be a DAV:options XML
- element.
-
- <!ELEMENT options ANY>
- ANY value: A sequence of elements with at most one
- DAV:activity-collection-set element.
-
- If an XML response body for a successful request is included, it
- MUST be a DAV:options-response XML element.
-
- <!ELEMENT options-response ANY>
- ANY value: A sequence of elements with at most one
- DAV:activity-collection-set element.
-
- <!ELEMENT activity-collection-set (href*)>
-
- If DAV:activity-collection-set is included in the request body,
- the response body for a successful request MUST contain a
- DAV:activity-collection-set element identifying collections that
- may contain activities. An identified collection MAY be the root
- collection of a tree of collections, all of which may contain
- activities. Since different servers can control different parts
- of the URL namespace, different resources on the same host MAY
- have different DAV:activity-collection-set values. The identified
- collections MAY be located on different hosts from the resource.
-
-13.8 Additional DELETE Semantics
-
- Additional Postconditions:
-
- (DAV:delete-activity-reference): If an activity is deleted, any
- reference to that activity in a DAV:activity-set,
- DAV:subactivity-set, or DAV:current-activity-set MUST be removed.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 96]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.9 Additional MOVE Semantics
-
- Additional Postconditions:
-
- (DAV:update-checked-out-reference): If a checked-out resource is
- moved, any reference to that resource in a DAV:activity-checkout-
- set property MUST be updated to refer to the new location of that
- resource.
-
- (DAV:update-activity-reference): If the request-URL identifies an
- activity, any reference to that activity in a DAV:activity-set,
- DAV:subactivity-set, or DAV:current-activity-set MUST be updated
- to refer to the new location of that activity.
-
- (DAV:update-workspace-reference): If the request-URL identifies a
- workspace, any reference to that workspace in a DAV:current-
- workspace-set property MUST be updated to refer to the new
- location of that workspace.
-
-13.10 Additional CHECKOUT Semantics
-
- A CHECKOUT request MAY specify the DAV:activity-set for the checked-
- out resource.
-
- Additional Marshalling:
-
- <!ELEMENT checkout ANY> ANY value: A sequence of elements with at
- most one DAV:activity-set and at most one DAV:unreserved.
-
- <!ELEMENT activity-set (href+ | new)>
- <!ELEMENT new EMPTY>
- <!ELEMENT unreserved EMPTY>
-
- Additional Preconditions:
-
- (DAV:one-checkout-per-activity-per-history): If there is a request
- activity set, unless DAV:unreserved is specified, another checkout
- from a version of that version history MUST NOT select an activity
- in that activity set.
-
- (DAV:linear-activity): If there is a request activity set, unless
- DAV:unreserved is specified, the selected version MUST be a
- descendant of all other versions of that version history that
- select that activity.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 97]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Postconditions:
-
- (DAV:initialize-activity-set): The DAV:activity-set of the
- checked-out resource is set as follows:
-
- - If DAV:new is specified as the DAV:activity-set in the request
- body, then a new activity created by the server is used.
- - Otherwise, if activities are specified in the request body,
- then those activities are used.
- - Otherwise, if the version-controlled resource is a member of a
- workspace and the DAV:current-activity-set of the workspace is
- set, then those activities are used.
- - Otherwise, the DAV:activity-set of the DAV:checked-out version
- is used.
-
- (DAV:initialize-unreserved): If DAV:unreserved was specified in
- the request body, then the DAV:unreserved property of the
- checked-out resource MUST be "true".
-
-13.10.1 Example - CHECKOUT with an activity
-
- >>REQUEST
-
- CHECKOUT /ws/public/foo.html HTTP/1.1
- Host: www.webdav.org
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:checkout xmlns:D="DAV:">
- <D:activity-set>
- <D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
- </D:activity-set>
- </D:checkout>
-
- >>RESPONSE
-
- HTTP/1.1 200 OK
- Cache-Control: no-cache
-
- In this example, the CHECKOUT is being performed in the
- http://repo.webdav.org/act/fix-bug-23 activity.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 98]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-13.11 Additional CHECKIN Semantics
-
- Additional Preconditions:
-
- (DAV:linear-activity): Any version which is in the version history
- of the checked-out resource and whose DAV:activity-set identifies
- an activity from the DAV:activity-set of the checked-out resource
- MUST be an ancestor of the checked-out resource.
-
- (DAV:atomic-activity-checkin): If the request-URL identifies an
- activity, the server MAY fail the request if any of the checked-
- out resources in the DAV:activity-checkout-set of either that
- activity or any subactivity of that activity cannot be checked in.
-
- Additional Postconditions:
-
- (DAV:initialize-activity-set): The DAV:activity-set of the new
- version MUST have been initialized to be the same as the
- DAV:activity-set of the checked-out resource.
-
- (DAV:activity-checkin): If the request-URL identified an activity,
- the server MUST have successfully applied the CHECKIN request to
- each checked-out resource in the DAV:activity-checkout-set of both
- that activity and any subactivity of that activity.
-
-13.12 Additional MERGE Semantics
-
- If the DAV:source element of the request body identifies an activity,
- then for each version history containing a version selected by that
- activity, the latest version selected by that activity is a merge
- source. Note that the versions selected by an activity are the
- versions in its DAV:activity-version-set unioned with the versions
- selected by the activities in its DAV:subactivity-set.
-
- Additional Marshalling:
-
- <!ELEMENT checkin-activity EMPTY>
-
- Additional Postconditions:
-
- (DAV:checkin-activity): If DAV:checkin-activity is specified in
- the request body, and if the DAV:source element in the request
- body identifies an activity, a CHECKIN request MUST have been
- successfully applied to that activity before the merge sources
- were determined.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 99]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-14 Version-Controlled-Collection Feature
-
- As with any versionable resource, when a collection is put under
- version control, a version history resource is created to contain
- versions for that version-controlled collection. In order to
- preserve standard versioning semantics (a version of a collection
- should not be modifiable), a collection version only records
- information about the version-controlled bindings of that collection.
-
- In order to cleanly separate a modification to the namespace from a
- modification to content or dead properties, a version of a collection
- has no members, but instead records in its DAV:version-controlled-
- binding-set property the binding name and version history resource of
- each version-controlled internal member of that collection. If,
- instead, a collection version contained bindings to other versions,
- creating a new version of a resource would require creating a new
- version of all the collection versions that contain that resource,
- which would cause activities to become entangled. For example,
- suppose a "feature-12" activity created a new version of /x/y/a.html.
- If a collection version contained bindings to versions of its
- members, a new version of /x/y would have to be created to contain
- the new version of /x/y/a.html, and a new version of /x would have to
- be created to contain the new version of /x/y. Now suppose a
- "bugfix-47" activity created a new version of /x/z/b.html. Again, a
- new version of /x/z and a new version of /x would have to be created
- to contain the new version of /x/y/b.html. But now it is impossible
- to merge just "bugfix-47" into another workspace without "feature-
- 12", because the version of /x that contains the desired version of
- /x/z/b.html also contains version of /x/y/a.html created for
- "feature-12". If, instead, a collection version just records the
- binding name and version history resource of each version-controlled
- internal member, changing the version selected by a member of that
- collection would not require a new version of the collection. The
- new version is still in the same version history so no new collection
- version is required, and "feature-12" and "bugfix-47" would not
- become entangled.
-
- In the following example, there are three version histories, named
- VH14, VH19, and VH24, where VH14 contains versions of a collection.
- The version-controlled collection /x has version V2 of version
- history VH14 as its DAV:checked-in version. Since V2 has recorded
- two version controlled bindings, one with binding name "a" to version
- history VH19, and the other with binding name "b" to version history
- VH24, /x MUST have two version-controlled bindings, one named "a" to
- a version-controlled resource for history VH19, and the other named
- "b" to a version-controlled resource for history VH24. The version-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 100]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- controlled resource /x/a currently has V4 of VH19 as its
- DAV:checked-in version, while /x/b has V8 of VH24 as its
- DAV:checked-in version.
-
- VH19
- +---------+
- | +---+ |
- | | |V4 |
- | +---+ |
- | | |
- | | |
- | +---+ |
- | | |V5 |
- VH14 | +---+ |
- +---------+ | | |
- | +---+ | | | |
- a +---+ | | |V1 | | +---+ |
- ---->| |checked-in=V4 | +---+ | a | | |V6 |
- / +---+ | | ------>| +---+ |
- / | | / | +---------+
- +---+ | +---+ |
- /x | |checked-in=V2 | | |V2 |
- +---+ | +---+ | VH24
- \ | | \ | b +---------+
- \ b +---+ | | ------>| +---+ |
- ---->| |checked-in=V8 | +---+ | | | |V7 |
- +---+ | | |V3 | | +---+ |
- | +---+ | | | |
- +---------+ | | |
- | +---+ |
- | | |V8 |
- | +---+ |
- | | |
- | | |
- | +---+ |
- | | |V9 |
- | +---+ |
- +---------+
-
- For any request (e.g., DELETE, MOVE, COPY) that modifies a version-
- controlled binding of a checked-in version-controlled collection, the
- request MUST fail unless the version-controlled collection has a
- DAV:auto-version property that will automatically check out the
- version-controlled collection when it is modified.
-
- Although a collection version only records the version-controlled
- bindings of a collection, a version-controlled collection MAY contain
- both version-controlled and non-version-controlled bindings. Non-
-
-
-
-Clemm, et al. Standards Track [Page 101]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- version-controlled bindings are not under version control, and
- therefore can be added or deleted without checking out the version-
- controlled collection.
-
- Note that a collection version captures only a defined subset of the
- state of a collection. In particular, a version of a collection
- captures its dead properties and its bindings to version-controlled
- resources, but not its live properties or bindings to non-version-
- controlled resources.
-
- When a server supports the working-resource feature, a client can
- check out a collection version to create a working collection.
- Unlike a version-controlled collection, which contains bindings to
- version-controlled resources and non-version-controlled resources, a
- working collection contains bindings to version history resources and
- non-version-controlled resources. In particular, a working
- collection is initialized to contain bindings to the version history
- resources specified by the DAV:version-controlled-binding-set of the
- checked out collection version. The members of a working collection
- can then be deleted or moved to another working collection. Non-
- version-controlled resources can be added to a working collection
- with methods such as PUT, COPY, and MKCOL. When a working collection
- is checked in, a VERSION-CONTROL request is automatically applied to
- every non-version-controlled member of the working collection, and
- each non-version-controlled member is replaced by its newly created
- version history. The DAV:version-controlled-binding-set of the new
- version resulting from checking in a working collection contains the
- binding name and version history URL for each member of the working
- collection.
-
-14.1 Version-Controlled Collection Properties
-
- A version-controlled collection has all the properties of a
- collection and of a version-controlled resource. In addition, the
- version-controlled-collection feature introduces the following
- REQUIRED property for a version-controlled collection.
-
-14.1.1 DAV:eclipsed-set (computed)
-
- This property identifies the non-version-controlled internal members
- of the collection that currently are eclipsing a version-controlled
- internal member of the collection.
-
- !ELEMENT eclipsed-set (binding-name*)>
- <!ELEMENT binding-name (#PCDATA)>
- PCDATA value: URL segment
-
-
-
-
-
-Clemm, et al. Standards Track [Page 102]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- An UPDATE or MERGE request can give a version-controlled collection a
- version-controlled internal member that has the same name as an
- existing non-version-controlled internal member. In this case, the
- non-version-controlled internal member takes precedence and is said
- to "eclipse" the new versioned-controlled internal member. If the
- non-version-controlled internal member is removed (e.g., by a DELETE
- or MOVE), the version-controlled internal member is exposed.
-
-14.2 Collection Version Properties
-
- A collection version has all the properties of a version. In
- addition, the version-controlled-collection feature introduces the
- following REQUIRED property for a collection version.
-
-14.2.1 DAV:version-controlled-binding-set (protected)
-
- This property captures the name and version-history of each version-
- controlled internal member of a collection.
-
- <!ELEMENT version-controlled-binding-set
- (version-controlled-binding*)>
- <!ELEMENT version-controlled-binding
- (binding-name, version-history)>
- <!ELEMENT binding-name (#PCDATA)>
- PCDATA value: URL segment
- <!ELEMENT version-history (href)>
-
-14.3 Additional OPTIONS Semantics
-
- If the server supports the version-controlled-collection feature, it
- MUST include "version-controlled-collection" as a field in the DAV
- response header from an OPTIONS request on any resource that supports
- any versioning properties, reports, or methods.
-
-14.4 Additional DELETE Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-modify-checked-in-parent): If the request-URL
- identifies a version-controlled resource, the DELETE MUST fail
- when the collection containing the version-controlled resource is
- a checked-in version-controlled collection, unless DAV:auto-
- version semantics will automatically check out the version-
- controlled collection.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 103]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-14.5 Additional MKCOL Semantics
-
- Additional Preconditions:
-
- If the request creates a new resource that is automatically placed
- under version control, all preconditions for VERSION-CONTROL apply
- to the request.
-
- Additional Postconditions:
-
- If the new collection is automatically put under version control,
- all postconditions for VERSION-CONTROL apply to the request.
-
-14.6 Additional COPY Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-copy-collection-version): If the source of the request
- is a collection version, the request MUST fail.
-
-14.7 Additional MOVE Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-modify-checked-in-parent): If the source of the
- request is a version-controlled resource, the request MUST fail
- when the collection containing the source is a checked-in
- version-controlled collection, unless DAV:auto-version semantics
- will automatically check out that version-controlled collection.
-
- (DAV:cannot-modify-destination-checked-in-parent): If the source
- of the request is a version-controlled resource, the request MUST
- fail when the collection containing the destination is a checked-
- in version-controlled collection, unless DAV:auto-version
- semantics will automatically check out that version-controlled
- collection.
-
-14.8 Additional VERSION-CONTROL Semantics
-
- Additional Preconditions:
-
- (DAV:cannot-modify-checked-in-parent): If the parent of the
- request-URL is a checked-in version-controlled collection, the
- request MUST fail unless DAV:auto-version semantics will
- automatically check out that version-controlled collection.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 104]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Additional Postconditions:
-
- (DAV:new-version-controlled-collection): If the request body
- identified a collection version, the collection at the request-URL
- MUST contain a version-controlled internal member for each
- DAV:version-controlled-binding specified in the DAV:version-
- controlled-binding-set of the collection version, where the name
- and DAV:version-history of the internal member MUST be the
- DAV:binding-name and the DAV:version-history specified by the
- DAV:version-controlled-binding. If the internal member is a
- member of a workspace, and there is another member of the
- workspace for the same version history, those two members MUST
- identify the same version-controlled resource; otherwise, a
- VERSION-CONTROL request with a server selected version of the
- version history MUST have been applied to the URL for that
- internal member.
-
-14.9 Additional CHECKOUT Semantics
-
- Additional Postconditions:
-
- (DAV:initialize-version-history-bindings): If the request has been
- applied to a collection version, the new working collection MUST
- be initialized to contain a binding to each of the history
- resources identified in the DAV:version-controlled-binding-set of
- that collection version.
-
-14.10 Additional CHECKIN Semantics
-
- Additional Postconditions:
-
- (DAV:initialize-version-controlled-bindings): If the request-URL
- identified a version-controlled collection, then the DAV:version-
- controlled-binding-set of the new collection version MUST contain
- a DAV:version-controlled-binding that identifies the binding name
- and version history for each version-controlled binding of the
- version- controlled collection.
-
- (DAV:version-control-working-collection-members): If the request-
- URL identified a working collection, a VERSION-CONTROL request
- MUST have been automatically applied to every non-version-
- controlled member of the working collection, and each non-
- version-controlled member MUST have been replaced by its newly
- created version history. If a working collection member was a
- non-version-controlled collection, every member of the non-
- version-controlled collection MUST have been placed under version
-
-
-
-
-
-Clemm, et al. Standards Track [Page 105]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- control before the non-version-controlled collection was placed
- under version control. The DAV:version-controlled-binding-set of
- the new collection version MUST contain a DAV:version-controlled-
- binding that identifies the binding name and the version history
- URL for each member of the working collection.
-
-14.11 Additional UPDATE and MERGE Semantics
-
- Additional Postconditions:
-
- (DAV:update-version-controlled-collection-members): If the request
- modified the DAV:checked-in version of a version-controlled
- collection, then the version-controlled members of that version-
- controlled collection MUST have been updated. In particular:
-
- - A version-controlled internal member MUST have been deleted if
- its version history is not identified by the DAV:version-
- controlled-binding-set of the new DAV:checked-in version.
- - A version-controlled internal member for a given version
- history MUST have been renamed if its binding name differs from
- the DAV:binding-name for that version history in the
- DAV:version-controlled-binding-set of the new DAV:checked-in
- version.
- - A new version-controlled internal member MUST have been created
- when a version history is identified by the DAV:version-
- controlled-binding-set of the DAV:checked-in version, but there
- was no member of the version-controlled collection for that
- version history. If a new version-controlled member is in a
- workspace that already has a version-controlled resource for
- that version history, then the new version-controlled member
- MUST be just a binding (i.e., another name for) that existing
- version-controlled resource. Otherwise, the content and dead
- properties of the new version-controlled member MUST have been
- initialized to be those of the version specified for that
- version history by the request. If no version is specified for
- that version history by the request, the version selected is
- server defined.
-
-15 Internationalization Considerations
-
- This specification has been designed to be compliant with the IETF
- Policy on Character Sets and Languages [RFC2277]. Specifically,
- where human-readable strings exist in the protocol, either their
- charset is explicitly stated, or XML mechanisms are used to specify
- the charset used. Additionally, these human-readable strings all
- have the ability to express the natural language of the string.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 106]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Most of the human-readable strings in this protocol appear in
- properties, such as DAV:creator-displayname. As defined by RFC 2518,
- properties have their values marshaled as XML. XML has explicit
- provisions for character set tagging and encoding, and requires that
- XML processors read XML elements encoded, at minimum, using the UTF-8
- [RFC2279] encoding of the ISO 10646 multilingual plane. The charset
- parameter of the Content-Type header, together with the XML
- "encoding" attribute, provide charset identification information for
- MIME and XML processors. Proper use of the charset header with XML
- is described in RFC 3023. XML also provides a language tagging
- capability for specifying the language of the contents of a
- particular XML element. XML uses either IANA registered language
- tags (see RFC 3066) or ISO 639 language tags in the "xml:lang"
- attribute of an XML element to identify the language of its content
- and attributes.
-
- DeltaV applications, since they build upon WebDAV, are subject to the
- internationalization requirements specified in RFC 2518, Section 16.
- In brief, these requirements mandate the use of XML character set
- tagging, character set encoding, and language tagging capabilities.
- Additionally, they strongly recommend reading RFC 3023 for
- instruction on the use of MIME media types for XML transport and the
- use of the charset header.
-
- Within this specification, a label is a human-readable string that is
- marshaled in the Label header and as XML in request entity bodies.
- When used in the Label header, the value of the label is URL-escaped
- and encoded using UTF-8.
-
-16 Security Considerations
-
- All of the security considerations of WebDAV discussed in RFC 2518,
- Section 17 also apply to WebDAV versioning. Some aspects of the
- versioning protocol help address security risks introduced by WebDAV,
- but other aspects can increase these security risks. These issues
- are detailed below.
-
-16.1 Auditing and Traceability
-
- WebDAV increases the ease with which a remote client can modify
- resources on a web site, but this also increases the risk of
- important information being overwritten and lost, either through user
- error or user maliciousness. The use of WebDAV versioning can help
- address this problem by guaranteeing that previous information is
- saved in the form of immutable versions, and therefore is easily
- available for retrieval or restoration. In addition, the version
- history provides a log of when changes were made, and by whom. When
- requests are appropriately authenticated, the history mechanism
-
-
-
-Clemm, et al. Standards Track [Page 107]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- provides a clear audit trail for changes to web resources. This can
- often significantly improve the ability to identify the source of the
- security problem, and thereby help guard against it in the future.
-
-16.2 Increased Need for Access Control
-
- WebDAV versioning provides a variety of links between related pieces
- of information. This can increase the risk that authentication or
- authorization errors allow a client to locate sensitive information.
- For example, if version history is not appropriately protected by
- access control, a client can use the version history of a public
- resource to identify later versions of that resource that the user
- intended to keep private. This increases the need for reliable
- authentication and accurate authorization.
-
- A WebDAV versioning client should be designed to handle a mixture of
- 200 (OK) and 403 (Forbidden) responses on attempts to access the
- properties and reports that are supported by a resource. For
- example, a particular user may be authorized to access the content
- and dead properties of a version-controlled resource, but not be
- authorized to access the DAV:checked-in, DAV:checked-out, or
- DAV:version-history properties of that resource.
-
-16.3 Security Through Obscurity
-
- While it is acknowledged that "obscurity" is not an effective means
- of security, it is often a good technique to keep honest people
- honest. Within this protocol, version URLs, version history URLs,
- and working resource URLs are generated by the server and can be
- properly obfuscated so as not to draw attention to them. For
- example, a version of "http://foobar.com/reviews/salaries.html" might
- be assigned a URL such as "http://foobar.com/repo/4934943".
-
-16.4 Denial of Service
-
- The auto-versioning mechanism provided by WebDAV can result in a
- large number of resources being created on the server, since each
- update to a resource could potentially result in the creation of a
- new version resource. This increases the risk of a denial of service
- attack that exhausts the storage capability of a server. This risk
- is especially significant because it can be an unintentional result
- of something like an aggressive auto-save feature provided by an
- editing client. A server can decrease this risk by using delta
- storage techniques to minimize the cost of additional versions, and
- by limiting auto-versioning to a locking client, and thereby
- decreasing the number of inadvertent version creations.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 108]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-17 IANA Considerations
-
- This document uses the namespace defined by RFC 2518 for XML
- elements. All other IANA considerations from RFC 2518 are also
- applicable to WebDAV Versioning.
-
-18 Intellectual Property
-
- The following notice is copied from RFC 2026, Section 10.4, and
- describes the position of the IETF concerning intellectual property
- claims made against this document.
-
- The IETF takes no position regarding the validity or scope of any
- intellectual property or other rights that might be claimed to
- pertain to the implementation or use other technology described in
- this document or the extent to which any license under such rights
- might or might not be available; neither does it represent that it
- has made any effort to identify any such rights. Information on the
- procedures of the IETF with respect to rights in standards-track and
- standards-related documentation can be found in BCP-11. Copies of
- claims of rights made available for publication and any assurances of
- licenses to be made available, or the result of an attempt made to
- obtain a general license or permission for the use of such
- proprietary rights by implementers or users of this specification can
- be obtained from the IETF Secretariat.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to practice
- this standard. Please address the information to the IETF Executive
- Director.
-
-19 Acknowledgements
-
- This protocol is the collaborative product of the authors and the
- rest of the DeltaV design team: Boris Bokowski, Bruce Cragun
- (Novell), Jim Doubek (Macromedia), David Durand (INSO), Lisa
- Dusseault (Xythos), Chuck Fay (FileNet), Yaron Goland, Mark Hale
- (Interwoven), Henry Harbury (Merant), James Hunt, Jeff McAffer (OTI),
- Peter Raymond (Merant), Juergen Reuter, Edgar Schwarz (Marconi), Eric
- Sedlar (Oracle), Bradley Sergeant, Greg Stein, and John Vasta
- (Rational). We would like to acknowledge the foundation laid for us
- by the authors of the WebDAV and HTTP protocols upon which this
- protocol is layered, and the invaluable feedback from the WebDAV and
- DeltaV working groups.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 109]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-20 References
-
- [ISO639] ISO, "Code for the representation of names of languages",
- ISO 639:1988, 1998.
-
- [RFC2026] Bradner, S., "The Internet Standards Process -- Revision
- 3", BCP 9, RFC 2026, October 1996.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
- Languages", BCP 18, RFC 2277, January 1998.
-
- [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 10646",
- RFC 2279, January 1998.
-
- [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
- Resource Identifiers (URI): Generic Syntax", RFC 2396,
- August 1998.
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S. and D.
- Jensen, "HTTP Extensions for Distributed Authoring -
- WEBDAV", RFC 2518, February 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.
-
- [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media Types",
- RFC 3023, January 2001.
-
- [RFC3066] Alvestrand, H., "Tags for the Identification of Languages",
- BCP 47, RFC 3066, January 2001.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 110]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-Appendix A - Resource Classification
-
- This document introduces several different kinds of versioning
- resources, such as version-controlled resources, versions, checked-
- out resources, and version history resources. As clients discover
- resources on a server, they may find it useful to classify those
- resources (for example, to make UI decisions on choice of icon and
- menu options).
-
- Clients should classify a resource by examining the values of the
- DAV:supported-method-set (see Section 3.1.3) and DAV:supported-live-
- property-set (see Section 3.1.4) properties of that resource.
-
- The following list shows the supported live properties and methods
- for each kind of versioning resource. Where an optional feature
- introduces a new kind of versioning resource, that feature is noted
- in parentheses following the name of that kind of versioning
- resource. If a live property or method is optional for a kind of
- versioning resource, the feature that introduces that live property
- or method is noted in parentheses following the live property or
- method name.
-
-A.1 DeltaV-Compliant Unmapped URL (a URL that identifies no resource)
-
- Supported methods:
-
- - PUT [RFC2616]
- - MKCOL [RFC2518]
- - MKACTIVITY (activity)
- - VERSION-CONTROL (workspace)
- - MKWORKSPACE (workspace)
-
-A.2 DeltaV-Compliant Resource
-
- Supported live properties:
-
- - DAV:comment
- - DAV:creator-displayname
- - DAV:supported-method-set
- - DAV:supported-live-property-set
- - DAV:supported-report-set
- - all properties defined in WebDAV [RFC2518].
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 111]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Supported methods:
-
- - REPORT
- - all methods defined in WebDAV [RFC2518]
- - all methods defined in HTTP/1.1 [RFC2616].
-
-A.3 DeltaV-Compliant Collection
-
- Supported live properties:
-
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - BASELINE-CONTROL (baseline)
- - all DeltaV-compliant resource methods.
-
-A.4 Versionable Resource
-
- Supported live properties:
-
- - DAV:workspace (workspace)
- - DAV:version-controlled-configuration (baseline)
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - VERSION-CONTROL
- - all DeltaV-compliant resource methods.
-
-A.5 Version-Controlled Resource
-
- Supported live properties:
-
- - DAV:auto-version
- - DAV:version-history (version-history)
- - DAV:workspace (workspace)
- - DAV:version-controlled-configuration (baseline)
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - VERSION-CONTROL
- - MERGE (merge)
- - all DeltaV-compliant resource methods.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 112]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-A.6 Version
-
- Supported live properties:
-
- - DAV:predecessor-set
- - DAV:successor-set
- - DAV:checkout-set
- - DAV:version-name
- - DAV:checkout-fork (in-place-checkout or working resource)
- - DAV:checkin-fork (in-place-checkout or working resource)
- - DAV:version-history (version-history)
- - DAV:label-name-set (label)
- - DAV:activity-set (activity)
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - LABEL (label)
- - CHECKOUT (working-resource)
- - all DeltaV-compliant resource methods.
-
-A.7 Checked-In Version-Controlled Resource
-
- Supported live properties:
-
- - DAV:checked-in
- - all version-controlled resource properties.
-
- Supported methods:
-
- - CHECKOUT (checkout-in-place)
- - UPDATE (update)
- - all version-controlled resource methods.
-
-A.8 Checked-Out Resource
-
- Supported live properties:
-
- - DAV:checked-out
- - DAV:predecessor-set
- - DAV:checkout-fork (in-place-checkout or working resource)
- - DAV:checkin-fork (in-place-checkout or working resource)
- - DAV:merge-set (merge)
- - DAV:auto-merge-set (merge)
- - DAV:unreserved (activity)
- - DAV:activity-set (activity)
-
-
-
-
-
-Clemm, et al. Standards Track [Page 113]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
- Supported methods:
-
- - CHECKIN (checkout-in-place or working-resource)
- - all DeltaV-compliant resource methods.
-
-A.9 Checked-Out Version-Controlled Resource (checkout-in-place)
-
- Supported live properties:
-
- - all version-controlled resource properties.
- - all checked-out resource properties.
-
- Supported methods:
-
- - UNCHECKOUT
- - all version-controlled resource methods.
- - all checked-out resource methods.
-
-A.10 Working Resource (working-resource)
-
- Supported live properties:
-
- - all DeltaV-compliant resource properties
- - all checked-out resource properties
- - DAV:auto-update.
-
- Supported methods:
-
- - all checked-out resource methods.
-
-A.11 Version History (version-history)
-
- Supported live properties:
-
- - DAV:version-set
- - DAV:root-version
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - all DeltaV-compliant resource methods.
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 114]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-A.12 Workspace (workspace)
-
- Supported live properties:
-
- - DAV:workspace-checkout-set
- - DAV:baseline-controlled-collection-set (baseline)
- - DAV:current-activity-set (activity)
- - all DeltaV-compliant collection properties.
-
- Supported methods:
-
- - all DeltaV-compliant collection methods.
-
-A.13 Activity (activity)
-
- Supported live properties:
-
- - DAV:activity-version-set
- - DAV:activity-checkout-set
- - DAV:subactivity-set
- - DAV:current-workspace-set
- - all DeltaV-compliant resource properties.
-
- Supported methods:
-
- - all DeltaV-compliant resource methods.
-
-A.14 Version-Controlled Collection (version-controlled-collection)
-
- Supported live properties:
-
- - DAV:eclipsed-set
- - all version-controlled resource properties.
-
- Supported methods:
-
- - all version-controlled resource methods.
-
-A.15 Collection Version (version-controlled-collection)
-
- Supported live properties:
-
- - DAV:version-controlled-binding-set
- - all version properties.
-
- Supported methods:
-
- - all version methods.
-
-
-
-Clemm, et al. Standards Track [Page 115]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-A.16 Version-Controlled Configuration (baseline)
-
- Supported live properties:
-
- - DAV:baseline-controlled-collection
- - all version-controlled resource properties.
-
- Supported methods:
-
- - all version-controlled resource methods.
-
-A.17 Baseline (baseline)
-
- Supported live properties:
-
- - DAV:baseline-collection
- - DAV:subbaseline-set
- - all version properties.
-
- Supported methods:
-
- - all version methods.
-
-A.18 Checked-Out Version-Controlled Configuration (baseline)
-
- Supported live properties:
-
- - DAV:subbaseline-set
- - all version-controlled configuration properties.
-
- Supported methods:
-
- - all version-controlled configuration methods.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 116]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-Authors' Addresses
-
- Geoffrey Clemm
- Rational Software
- 20 Maguire Road, Lexington, MA 02421
-
- EMail: geoffrey.clemm at rational.com
-
-
- Jim Amsden
- IBM
- 3039 Cornwallis, Research Triangle Park, NC 27709
-
- EMail: jamsden at us.ibm.com
-
-
- Tim Ellison
- IBM
- Hursley Park, Winchester, UK S021 2JN
-
- EMail: tim_ellison at uk.ibm.com
-
-
- Christopher Kaler
- Microsoft
- One Microsoft Way, Redmond, WA 90852
-
- EMail: ckaler at microsoft.com
-
-
- Jim Whitehead
- UC Santa Cruz, Dept. of Computer Science
- 1156 High Street, Santa Cruz, CA 95064
-
- EMail: ejw at cse.ucsc.edu
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 117]
-
-RFC 3253 Versioning Extensions to WebDAV March 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 118]
-
Copied: CalendarServer/trunk/doc/RFC/rfc3283-Calendaring.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc3283.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3283-Calendaring.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc3283-Calendaring.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,899 @@
+
+
+
+
+
+
+Network Working Group B. Mahoney
+Request for Comments: 3283 MIT
+Category: Informational G. Babics
+ Steltor
+ A. Taler
+ June 2002
+
+
+ Guide to Internet Calendaring
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+Abstract
+
+ This document describes the various Internet calendaring and
+ scheduling standards and works in progress, and the relationships
+ between them. Its intent is to provide a context for these
+ documents, assist in their understanding, and potentially aid in the
+ design of standards-based calendaring and scheduling systems. The
+ standards addressed are RFC 2445 (iCalendar), RFC 2446 (iTIP), and
+ RFC 2447 (iMIP). The work in progress addressed is "Calendar Access
+ Protocol" (CAP). This document also describes issues and problems
+ that are not solved by these protocols, and that could be targets for
+ future work.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.2 Concepts and Relationships . . . . . . . . . . . . . . . . . 4
+ 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2.1 Fundamental Needs . . . . . . . . . . . . . . . . . . . . . 4
+ 2.2 Protocol Requirements . . . . . . . . . . . . . . . . . . . 5
+ 3. Solutions . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+ 3.2 Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 3.2.1 Standalone Single-user System . . . . . . . . . . . . . . . 8
+ 3.2.2 Single-user Systems Communicating . . . . . . . . . . . . . 8
+ 3.2.3 Single-user with Multiple CUAs . . . . . . . . . . . . . . . 9
+ 3.2.4 Single-user with Multiple Calendars . . . . . . . . . . . . 9
+
+
+
+Mahoney, et. al. Informational [Page 1]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ 3.2.5 Users Communicating on a Multi-user System . . . . . . . . . 10
+ 3.2.6 Users Communicating through Different Multi-user Systems . . 10
+ 4. Important Aspects . . . . . . . . . . . . . . . . . . . . . 10
+ 4.1 Timezones . . . . . . . . . . . . . . . . . . . . . . . . . 10
+ 4.2 Choice of Transport . . . . . . . . . . . . . . . . . . . . 11
+ 4.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 4.4 Amount of data . . . . . . . . . . . . . . . . . . . . . . . 11
+ 4.5 Recurring Components . . . . . . . . . . . . . . . . . . . . 11
+ 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . 11
+ 5.1 Scheduling People, not Calendars . . . . . . . . . . . . . . 12
+ 5.2 Administration . . . . . . . . . . . . . . . . . . . . . . . 12
+ 5.3 Notification . . . . . . . . . . . . . . . . . . . . . . . . 12
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . 12
+ 6.1 Access Control . . . . . . . . . . . . . . . . . . . . . . . 12
+ 6.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . 12
+ 6.3 Using E-mail . . . . . . . . . . . . . . . . . . . . . . . . 13
+ 6.4 Other Issues . . . . . . . . . . . . . . . . . . . . . . . . 13
+ Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 13
+ References . . . . . . . . . . . . . . . . . . . . . . . . . 14
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 15
+ Full Copyright Statement . . . . . . . . . . . . . . . . . . 16
+
+1. Introduction
+
+ Calendaring and scheduling protocols are intended to aid individuals
+ in obtaining calendaring information and scheduling meetings across
+ the Internet, to aid organizations in providing calendaring
+ information on the Internet, and to provide for organizations looking
+ for a calendaring and scheduling solution to deploy internally.
+
+ It is the intent of this document to provide a context for these
+ documents, assist in their understanding, and potentially help in the
+ design of standards-based calendaring and scheduling systems.
+
+ Problems not solved by these protocols, as well as security issues to
+ be kept in mind, are discussed at the end of the document.
+
+1.1 Terminology
+
+ This memo uses much of the same terminology as iCalendar [RFC-2445],
+ iTIP [RFC-2446], iMIP [RFC-2447], and [CAP]. The following
+ definitions are provided as an introduction; the definitions in the
+ protocol specifications themselves should be considered canonical.
+
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 2]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ Calendar
+
+ A collection of events, to-dos, journal entries, etc. A calendar
+ could be the content of a person or resource's agenda; it could
+ also be a collection of data serving a more specialized need.
+ Calendars are the basic storage containers for calendaring
+ information.
+
+ Calendar Access Rights
+
+ A set of rules defining who may perform what operations, such as
+ reading or writing information, on a given calendar.
+
+ Calendar Service
+
+ A running server application that provides access to a number of
+ calendar stores.
+
+ Calendar Store (CS)
+
+ A data store of a calendar service. A calendar service may have
+ several calendar stores, and each store may contain several
+ calendars, as well as properties and components outside of those
+ calendars.
+
+ Calendar User (CU)
+
+ An entity (often a human) that accesses calendar information.
+
+ Calendar User Agent (CUA)
+
+ Software with which the calendar user communicates with a calendar
+ service or local calendar store to access calendar information.
+
+ Component
+
+ A piece of calendar data such as an event, a to-do or an alarm.
+ Information about components is stored as properties of those
+ components.
+
+ Delegator
+
+ A calendar user who has assigned his or her participation in a
+ scheduled calendar component (e.g. a VEVENT) to another calendar
+ user (sometimes called the delegate or delegatee). An example of
+ a delegator is a busy executive sending an employee to a meeting
+ in his or her place.
+
+
+
+
+Mahoney, et. al. Informational [Page 3]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ Delegate
+
+ A calendar user (sometimes called the delegatee) who has been
+ assigned to participate in a scheduled calendar component (e.g. a
+ VEVENT) in place of one of the attendees in that component
+ (sometimes called the delegator). An example of a delegate is a
+ team member sent to a particular meeting.
+
+ Designate
+
+ A calendar user authorized to act on behalf of another calendar
+ user. An example of a designate is an assistant scheduling
+ meetings for his or her superior.
+
+ Local Store
+
+ A CS that is on the same device as the CUA.
+
+ Property
+
+ A description of some element of a component, such as a start
+ time, title or location.
+
+ Remote Store
+
+ A CS that is not on the same device as the CUA.
+
+1.2 Concepts and Relationships
+
+ iCalendar is the language used to describe calendar objects. iTIP
+ describes a way to use the iCalendar language to do scheduling. iMIP
+ describes how to do iTIP scheduling via e-mail. CAP describes a way
+ to use the iCalendar language to access a calendar store in real-
+ time.
+
+ The relationship between calendaring protocols is similar to that
+ between e-mail protocols. In those terms, iCalendar is analogous to
+ RFC 2822, iTIP and iMIP are analogous to the Simple Mail Transfer
+ Protocol (SMTP), and CAP is analogous to the Post Office Protocol
+ (POP) or Internet Message Access Protocol (IMAP).
+
+2. Requirements
+
+2.1 Fundamental Needs
+
+ The following scenarios illustrate people and organizations' basic
+ calendaring and scheduling needs:
+
+
+
+
+Mahoney, et. al. Informational [Page 4]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ a] A doctor wishes to keep track of all her appointments.
+
+ Need: To read and manipulate one's own calendar with only one CUA.
+
+ b] A busy musician wants to maintain her schedule with multiple
+ devices, such as through an Internet-based agenda and with a PDA.
+
+ Need: To read and manipulate one's own calendar, possibly with
+ solutions from different vendors.
+
+ c] A software development team wishes to more effectively schedule
+ their time through viewing each other's calendar information.
+
+ Need: To share calendar information between users of the same
+ calendar service.
+
+ d] A teacher wants his students to schedule appointments during
+ his office hours.
+
+ Need: To schedule calendar events, to-dos and journals with other
+ users of the same calendar service.
+
+ e] A movie theater wants to publish its schedule for prospective
+ customers.
+
+ Need: To share calendar information with users of other calendar
+ services, possibly from a number of different vendors.
+
+ f] A social club wants to schedule calendar entries effectively
+ with its members.
+
+ Need: To schedule calendar events and to-dos with users of other
+ calendar services, possibly from a number of different vendors.
+
+2.2 Protocol Requirements
+
+ Some of these needs can be met by proprietary solutions (a, c, d),
+ but others can not (b, e, f). These latter scenarios show that
+ standard protocols are required for accessing information in a
+ calendar store and scheduling calendar entries. In addition, these
+ protocols require a common data format for representing calendar
+ information.
+
+ These requirements are met by the following protocol specifications.
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 5]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ - Data format: iCalendar [RFC-2445]
+
+ iCalendar [RFC-2445] provides a data format for representing
+ calendar information, to be used and exchanged by other protocols.
+ iCalendar [RFC-2445] can also be used in other contexts, such as a
+ drag-and-drop interface, or an export/import feature. All the
+ other calendaring protocols depend on iCalendar [RFC-2445], so all
+ elements of a standards-based calendaring and scheduling systems
+ will have to be able to interpret iCalendar [RFC-2445].
+
+ - Scheduling protocol: iTIP [RFC-2446]
+
+ iTIP [RFC-2446] describes the messages used to schedule calendar
+ events. Within iTIP messages, events are represented in iCalendar
+ [RFC-2445] format, and have semantics that identify the message as
+ being an invitation to a meeting, an acceptance of an invitation,
+ or the assignment of a task.
+
+ iTIP [RFC-2446] messages are used in the scheduling workflow,
+ where users exchange messages in order to organize things such as
+ events and to-dos. CUAs generate and interpret iTIP [RFC-2446]
+ messages at the direction of the calendar user. With iTIP [RFC-
+ 2446] users can create, modify, delete, reply to, counter, and
+ decline counters to the various iCalendar [RFC-2445] components.
+ Furthermore, users can also request the free/busy time of other
+ people.
+
+ iTIP [RFC-2446] is transport-independent, and has one specified
+ transport binding: iMIP [RFC-2447] binds iTIP to e-mail. In
+ addition [CAP] will provide a real-time binding of iTIP [RFC-
+ 2446], allowing CUAs to perform calendar management and scheduling
+ over a single connection.
+
+ - Calendar management protocol: [CAP]
+
+ [CAP] describes the messages used to manage calendars on a
+ calendar store. These messages use iCalendar [RFC-2445] to
+ describe various components such as events and to-dos. These
+ messages make it possible to perform iTIP [RFC-2446] operations,
+ as well as other operations relating to a calendar store such as
+ searching, creating calendars, specifying calendar properties, and
+ specifying calendar access rights.
+
+
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 6]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+3. Solutions
+
+3.1 Examples
+
+ Returning to the scenarios presented in section 2.1, the calendaring
+ protocols can be used in the following ways:
+
+ a] The doctor can use a proprietary CUA with a local store, and
+ perhaps use iCalendar [RFC-2445] as a storage mechanism. This
+ would allow her to easily import her data store into another
+ application that supports iCalendar [RFC-2445].
+
+ b] The musician who wishes to access her agenda from anywhere can
+ use a [CAP]-enabled calendar service accessible over the Internet.
+ She can then use any available [CAP] clients to access the data.
+
+ A proprietary system that provides access through a Web-based
+ interface could also be employed, but the use of [CAP] would be
+ superior in that it would allow the use of third party
+ applications, such as PDA synchronization tools.
+
+ c] The development team can use a calendar service which supports
+ [CAP], and each member can use a [CAP]-enabled CUA of their
+ choice.
+
+ Alternatively, each member could use an iMIP [RFC-2447]-enabled
+ CUA, and they could book meetings over e-mail. This solution has
+ the drawback that it is difficult to examine other users' agendas,
+ making the organization of meetings more difficult.
+
+ Proprietary solutions are also available, but they require that
+ all members use clients by the same vendor, and disallow the use
+ of third party applications.
+
+ d] The teacher can set up a calendar service, and have students
+ book time through any of the iTIP [RFC-2446] bindings. [CAP]
+ provides real-time access, but could require additional
+ configuration. iMIP [RFC-2447] would be the easiest to configure,
+ but may require more e-mail processing.
+
+ If [CAP] access is provided then determining the state of the
+ teacher's schedule is straightforward. If not, this can be
+ determined through iTIP [RFC-2446] free/busy requests. Non-
+ standard methods could also be employed, such as serving up
+ iCalendar [RFC-2445], HTML, or XML over HTTP.
+
+ A proprietary system could also be used, but would require that
+ all students be able to use software from a specific vendor.
+
+
+
+Mahoney, et. al. Informational [Page 7]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ e] [CAP] would be preferred for publishing a movie theater's
+ schedule, since it provides advanced access and search
+ capabilities. It also allows easy integration with customers'
+ calendar systems.
+
+ Non-standard methods such as serving data over HTTP could also be
+ employed, but would be harder to integrate with customers'
+ systems.
+
+ Using a completely proprietary solution would be very difficult,
+ if not impossible, since it would require every user to install
+ and use the proprietary software.
+
+ f] The social club could distribute meeting information in the
+ form of iTIP [RFC-2446] messages, sent via e-mail using iMIP
+ [RFC-2447]. The club could distribute meeting invitations, as
+ well as a full published agenda.
+
+ Alternatively, the club could provide access to a [CAP]-enabled
+ calendar service. However, this solution would be more expensive
+ since it requires the maintenance of a server.
+
+3.2 Systems
+
+ The following diagrams illustrate possible systems and their usage of
+ the various protocols.
+
+3.2.1 Standalone Single-user System
+
+ A single user system that does not communicate with other systems
+ need not employ any of the protocols. However, it may use iCalendar
+ [RFC-2445] as a data format in some places.
+
+ ----------- O
+ | CUA w/ | -+- user
+ |local store| A
+ ----------- / \
+
+3.2.2 Single-user Systems Communicating
+
+ Users with single-user systems may schedule meetings with each others
+ using iTIP [RFC-2446]. The easiest binding of iTIP [RFC-2446] to use
+ would be iMIP [RFC-2447], since messages can be held in the users'
+ mail queues, which we assume to already exist. [CAP] could also be
+ used.
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 8]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ O ----------- ----------- O
+ -+- | CUA w/ | -----[iMIP]----- | CUA w/ | -+- user
+ A |local store| Internet |local store| A
+ / \ ----------- ----------- / \
+
+3.2.3 Single-user with Multiple CUAs
+
+ A single user may use more than one CUA to access his or her
+ calendar. The user may use a PDA, a Web client, a PC, or some other
+ device, depending on accessibility. Some of these clients may have
+ local stores and others may not. Those with local stores need to
+ synchronize the data on the CUA with the data on the CS.
+
+ -----------
+ | CUA w | -----[CAP]----------+
+ |local store| |
+ O ----------- ----------
+ -+- | CS |
+ A | |
+ / \ ----------
+ ----------- |
+ | CUA w/o | -----[CAP]----------+
+ |local store|
+ -----------
+
+3.2.4 Single-user with Multiple Calendars
+
+ A single user may have many independent calendars; for example, one
+ may contain work-related information and another personal
+ information. The CUA may or may not have a local store. If it does,
+ then it needs to synchronize the data of the CUA with the data on
+ both of the CS.
+
+ ----------
+ +------------[CAP]------ | CS |
+ | | |
+ O ----------- ----------
+ -+- | CUA |
+ A | |
+ / \ -----------
+ | ----------
+ +------------[CAP]------ | CS |
+ | |
+ ----------
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 9]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+3.2.5 Users Communicating on a Multi-user System
+
+ Users on a multi-user system may schedule meetings with each other
+ using [CAP]-enabled CUAs and services. The CUAs may or may not have
+ local stores. Those with local stores need to synchronize the data
+ on the CUAs with the data on the CS.
+
+ O -----------
+ -+- | CUA w | -----[CAP]----------+
+ A |local store| |
+ / \ ----------- ----------
+ | CS |
+ | |
+ ----------
+ O ----------- |
+ -+- | CUA w/o | -----[CAP]----------+
+ A |local store|
+ / \ -----------
+
+3.2.6 Users Communicating through Different Multi-user Systems
+
+ Users on a multi-user system may need to schedule meetings with users
+ on a different multi-user system. The services can communicate using
+ [CAP] or iMIP [RFC-2447].
+
+ O ----------- ----------
+ -+- | CUA w | -----[CAP]-------| CS |
+ A |local store| | |
+ / \ ----------- ----------
+ |
+ [CAP] or [iMIP]
+ |
+ O ----------- ----------
+ -+- | CUA w/o | -----[CAP]-------| CS |
+ A |local store| | |
+ / \ ----------- ----------
+
+4. Important Aspects
+
+ There are a number of important aspects of these calendaring
+ standards of which people, especially implementers, should be aware.
+
+4.1 Timezones
+
+ The dates and times in components can refer to a specific time zone.
+ Time zones can be defined in a central store, or they may be defined
+ by a user to fit his or her needs. All users and applications should
+ be aware of time zones and time zone differences. New time zones may
+
+
+
+Mahoney, et. al. Informational [Page 10]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ need to be added, and others removed. Two different vendors may
+ describe the same time zone differently (such as by using a different
+ name).
+
+4.2 Choice of Transport
+
+ There are issues to be aware of in choosing between a network
+ protocol such as [CAP], or a store and forward protocol, such as iMIP
+ [RFC-2447].
+
+ The use of a network ("on-the-wire") mechanism may require some
+ organizations to make provisions to allow calendaring traffic to
+ traverse a corporate firewall on the required ports. Depending on
+ the organizational culture, this may be a challenging social
+ exercise.
+
+ The use of an email-based mechanism exposes time-sensitive data to
+ unbounded latency. Large or heavily utilized mail systems may
+ experience an unacceptable delay in message receipt.
+
+4.3 Security
+
+ See the "Security Considerations" (Section 6) section below.
+
+4.4 Amount of data
+
+ In some cases, a component may be very large, for instance, a
+ component with a very large attachment. Some applications may be
+ low-bandwidth or may be limited in the amount of data they can store.
+ Maximum component size may be set in [CAP]. It can also be
+ controlled in iMIP [RFC-2447] by restricting the maximum size of the
+ e-mail that the application can download.
+
+4.5 Recurring Components
+
+ In iCAL [RFC-2445], one can specify complex recurrence rules for
+ VEVENTs, VTODOs, and VJOURNALs. One must be careful to correctly
+ interpret these recurrence rules and pay extra attention to being
+ able to interoperate using them.
+
+5. Open Issues
+
+ Many issues are not currently resolved by these protocols, and many
+ desirable features are not yet provided. Some of the more prominent
+ ones are outlined below.
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 11]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+5.1 Scheduling People, not Calendars
+
+ Meetings are scheduled with people; however, people may have many
+ calendars, and may store these calendars in many places. There may
+ also be many routes to contact them. The calendaring protocols do
+ not attempt to provide unique access for contacting a given person.
+ Instead, 'calendar addresses' are booked, which may be e-mail
+ addresses or individual calendars. It is up to the users themselves
+ to orchestrate mechanisms to ensure that the bookings go to the right
+ place.
+
+5.2 Administration
+
+ The calendaring protocols do not address the issues of administering
+ users and calendars on a calendar service. This must be handled by
+ proprietary mechanisms for each implementation.
+
+5.3 Notification
+
+ People often wish to be notified of upcoming events, new events, or
+ changes to existing events. The calendaring protocols do not attempt
+ to address these needs in a real-time system. Instead, the ability
+ to store alarm information on events is provided, which can be used
+ to provide client-side notification of upcoming events. To organize
+ notification of new or changed events, clients have to poll the data
+ store.
+
+6. Security Considerations
+
+6.1 Access Control
+
+ There has to be reasonable granularity in the configuration options
+ for access to data through [CAP], so that what should be released to
+ requesters is released, and what shouldn't is not. Details of
+ handling this are described in [CAP].
+
+6.2 Authentication
+
+ Access control must be coupled with a good authentication system, so
+ that the right people get the right information. For [CAP], this
+ means requiring authentication before any database access can be
+ performed, and checking access rights and authentication credentials
+ before releasing information. [CAP] uses the Simple Authentication
+ Security Layer (SASL) for this authentication. In iMIP [RFC-2447],
+ this may present some challenges, as authentication is often not a
+ consideration in store-and-forward protocols.
+
+
+
+
+
+Mahoney, et. al. Informational [Page 12]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+ Authentication is also important for scheduling, in that receivers of
+ scheduling messages should be able to validate the apparent sender.
+ Since scheduling messages are wrapped in MIME [RFC-2045], signing and
+ encryption are freely available. For messages transmitted over mail,
+ this is the only available alternative. It is suggested that
+ developers take care in implementing the security features in iMIP
+ [RFC-2447], bearing in mind that the concept and need may be foreign
+ or non-obvious to users, yet essential for the system to function as
+ they might expect.
+
+ The real-time protocols provide for the authentication of users, and
+ the preservation of that authentication information, allowing for
+ validation by the receiving end-user or server.
+
+6.3 Using E-mail
+
+ Because scheduling information can be transmitted over mail without
+ any authentication information, e-mail spoofing is extremely easy if
+ the receiver is not checking for authentication. It is suggested
+ that implementers consider requiring authentication as a default,
+ using mechanisms such as are described in Section 3 of iMIP [RFC-
+ 2447]. The use of e-mail, and the potential for anonymous
+ connections, means that 'calendar spam' is possible. Developers
+ should consider this threat when designing systems, particularly
+ those that allow for automated request processing.
+
+6.4 Other Issues
+
+ The current security context should be obvious to users. Because the
+ underlying mechanisms may not be clear to users, efforts to make
+ clear the current state in the UI should be made. One example of
+ this is the 'lock' icon used in some Web browsers during secure
+ connections.
+
+ With both iMIP [RFC-2447] and [CAP], the possibilities of Denial of
+ Service attacks must be considered. The ability to flood a calendar
+ system with bogus requests is likely to be exploited once these
+ systems become widely deployed, and detection and recovery methods
+ will need to be considered.
+
+Acknowledgments
+
+ Thanks to the following, who have participated in the development of
+ this document:
+
+ Eric Busboom, Pat Egen, David Madeo, Shawn Packwood, Bruce Kahn,
+ Alan Davies, Robb Surridge.
+
+
+
+
+Mahoney, et. al. Informational [Page 13]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+References
+
+ [RFC-2445] Dawson, F. and D. Stenerson, "Internet Calendaring and
+ Scheduling Core Object Specification - iCalendar", RFC
+ 2445, November 1998.
+
+ [RFC-2446] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
+ "iCalendar Transport-Independent Interoperability Protocol
+ (iTIP): Scheduling Events, Busy Time, To-dos and Journal
+ Entries", RFC 2446, November 1998.
+
+ [RFC-2447] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
+ Message-Based Interoperability Protocol - iMIP", RFC 2447,
+ November 1998.
+
+ [RFC-2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) - Part One: Format of Internet Message
+ Bodies", RFC 2045, November 1996.
+
+ [CAP] Mansour, S., Royer, D., Babics, G., and Hill, P.,
+ "Calendar Access Protocol (CAP)", Work in Progress.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 14]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+Authors' Addresses
+
+ Bob Mahoney
+ MIT
+ E40-327
+ 77 Massachusetts Avenue
+ Cambridge, MA 02139
+ US
+
+ Phone: (617) 253-0774
+ EMail: bobmah at mit.edu
+
+
+ George Babics
+ Steltor
+ 2000 Peel Street
+ Montreal, Quebec H3A 2W5
+ CA
+
+ Phone: (514) 733-8500 x4201
+ EMail: georgeb at steltor.com
+
+
+ Alexander Taler
+
+ EMail: alex at 0--0.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 15]
+
+RFC 3283 Guide to Internet Calendaring June 2002
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2002). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Mahoney, et. al. Informational [Page 16]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc3283.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3283.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc3283.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,899 +0,0 @@
-
-
-
-
-
-
-Network Working Group B. Mahoney
-Request for Comments: 3283 MIT
-Category: Informational G. Babics
- Steltor
- A. Taler
- June 2002
-
-
- Guide to Internet Calendaring
-
-Status of this Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
-Abstract
-
- This document describes the various Internet calendaring and
- scheduling standards and works in progress, and the relationships
- between them. Its intent is to provide a context for these
- documents, assist in their understanding, and potentially aid in the
- design of standards-based calendaring and scheduling systems. The
- standards addressed are RFC 2445 (iCalendar), RFC 2446 (iTIP), and
- RFC 2447 (iMIP). The work in progress addressed is "Calendar Access
- Protocol" (CAP). This document also describes issues and problems
- that are not solved by these protocols, and that could be targets for
- future work.
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
- 1.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 2
- 1.2 Concepts and Relationships . . . . . . . . . . . . . . . . . 4
- 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . 4
- 2.1 Fundamental Needs . . . . . . . . . . . . . . . . . . . . . 4
- 2.2 Protocol Requirements . . . . . . . . . . . . . . . . . . . 5
- 3. Solutions . . . . . . . . . . . . . . . . . . . . . . . . . 7
- 3.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7
- 3.2 Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 8
- 3.2.1 Standalone Single-user System . . . . . . . . . . . . . . . 8
- 3.2.2 Single-user Systems Communicating . . . . . . . . . . . . . 8
- 3.2.3 Single-user with Multiple CUAs . . . . . . . . . . . . . . . 9
- 3.2.4 Single-user with Multiple Calendars . . . . . . . . . . . . 9
-
-
-
-Mahoney, et. al. Informational [Page 1]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- 3.2.5 Users Communicating on a Multi-user System . . . . . . . . . 10
- 3.2.6 Users Communicating through Different Multi-user Systems . . 10
- 4. Important Aspects . . . . . . . . . . . . . . . . . . . . . 10
- 4.1 Timezones . . . . . . . . . . . . . . . . . . . . . . . . . 10
- 4.2 Choice of Transport . . . . . . . . . . . . . . . . . . . . 11
- 4.3 Security . . . . . . . . . . . . . . . . . . . . . . . . . . 11
- 4.4 Amount of data . . . . . . . . . . . . . . . . . . . . . . . 11
- 4.5 Recurring Components . . . . . . . . . . . . . . . . . . . . 11
- 5. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . 11
- 5.1 Scheduling People, not Calendars . . . . . . . . . . . . . . 12
- 5.2 Administration . . . . . . . . . . . . . . . . . . . . . . . 12
- 5.3 Notification . . . . . . . . . . . . . . . . . . . . . . . . 12
- 6. Security Considerations . . . . . . . . . . . . . . . . . . 12
- 6.1 Access Control . . . . . . . . . . . . . . . . . . . . . . . 12
- 6.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . 12
- 6.3 Using E-mail . . . . . . . . . . . . . . . . . . . . . . . . 13
- 6.4 Other Issues . . . . . . . . . . . . . . . . . . . . . . . . 13
- Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 13
- References . . . . . . . . . . . . . . . . . . . . . . . . . 14
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 15
- Full Copyright Statement . . . . . . . . . . . . . . . . . . 16
-
-1. Introduction
-
- Calendaring and scheduling protocols are intended to aid individuals
- in obtaining calendaring information and scheduling meetings across
- the Internet, to aid organizations in providing calendaring
- information on the Internet, and to provide for organizations looking
- for a calendaring and scheduling solution to deploy internally.
-
- It is the intent of this document to provide a context for these
- documents, assist in their understanding, and potentially help in the
- design of standards-based calendaring and scheduling systems.
-
- Problems not solved by these protocols, as well as security issues to
- be kept in mind, are discussed at the end of the document.
-
-1.1 Terminology
-
- This memo uses much of the same terminology as iCalendar [RFC-2445],
- iTIP [RFC-2446], iMIP [RFC-2447], and [CAP]. The following
- definitions are provided as an introduction; the definitions in the
- protocol specifications themselves should be considered canonical.
-
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 2]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- Calendar
-
- A collection of events, to-dos, journal entries, etc. A calendar
- could be the content of a person or resource's agenda; it could
- also be a collection of data serving a more specialized need.
- Calendars are the basic storage containers for calendaring
- information.
-
- Calendar Access Rights
-
- A set of rules defining who may perform what operations, such as
- reading or writing information, on a given calendar.
-
- Calendar Service
-
- A running server application that provides access to a number of
- calendar stores.
-
- Calendar Store (CS)
-
- A data store of a calendar service. A calendar service may have
- several calendar stores, and each store may contain several
- calendars, as well as properties and components outside of those
- calendars.
-
- Calendar User (CU)
-
- An entity (often a human) that accesses calendar information.
-
- Calendar User Agent (CUA)
-
- Software with which the calendar user communicates with a calendar
- service or local calendar store to access calendar information.
-
- Component
-
- A piece of calendar data such as an event, a to-do or an alarm.
- Information about components is stored as properties of those
- components.
-
- Delegator
-
- A calendar user who has assigned his or her participation in a
- scheduled calendar component (e.g. a VEVENT) to another calendar
- user (sometimes called the delegate or delegatee). An example of
- a delegator is a busy executive sending an employee to a meeting
- in his or her place.
-
-
-
-
-Mahoney, et. al. Informational [Page 3]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- Delegate
-
- A calendar user (sometimes called the delegatee) who has been
- assigned to participate in a scheduled calendar component (e.g. a
- VEVENT) in place of one of the attendees in that component
- (sometimes called the delegator). An example of a delegate is a
- team member sent to a particular meeting.
-
- Designate
-
- A calendar user authorized to act on behalf of another calendar
- user. An example of a designate is an assistant scheduling
- meetings for his or her superior.
-
- Local Store
-
- A CS that is on the same device as the CUA.
-
- Property
-
- A description of some element of a component, such as a start
- time, title or location.
-
- Remote Store
-
- A CS that is not on the same device as the CUA.
-
-1.2 Concepts and Relationships
-
- iCalendar is the language used to describe calendar objects. iTIP
- describes a way to use the iCalendar language to do scheduling. iMIP
- describes how to do iTIP scheduling via e-mail. CAP describes a way
- to use the iCalendar language to access a calendar store in real-
- time.
-
- The relationship between calendaring protocols is similar to that
- between e-mail protocols. In those terms, iCalendar is analogous to
- RFC 2822, iTIP and iMIP are analogous to the Simple Mail Transfer
- Protocol (SMTP), and CAP is analogous to the Post Office Protocol
- (POP) or Internet Message Access Protocol (IMAP).
-
-2. Requirements
-
-2.1 Fundamental Needs
-
- The following scenarios illustrate people and organizations' basic
- calendaring and scheduling needs:
-
-
-
-
-Mahoney, et. al. Informational [Page 4]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- a] A doctor wishes to keep track of all her appointments.
-
- Need: To read and manipulate one's own calendar with only one CUA.
-
- b] A busy musician wants to maintain her schedule with multiple
- devices, such as through an Internet-based agenda and with a PDA.
-
- Need: To read and manipulate one's own calendar, possibly with
- solutions from different vendors.
-
- c] A software development team wishes to more effectively schedule
- their time through viewing each other's calendar information.
-
- Need: To share calendar information between users of the same
- calendar service.
-
- d] A teacher wants his students to schedule appointments during
- his office hours.
-
- Need: To schedule calendar events, to-dos and journals with other
- users of the same calendar service.
-
- e] A movie theater wants to publish its schedule for prospective
- customers.
-
- Need: To share calendar information with users of other calendar
- services, possibly from a number of different vendors.
-
- f] A social club wants to schedule calendar entries effectively
- with its members.
-
- Need: To schedule calendar events and to-dos with users of other
- calendar services, possibly from a number of different vendors.
-
-2.2 Protocol Requirements
-
- Some of these needs can be met by proprietary solutions (a, c, d),
- but others can not (b, e, f). These latter scenarios show that
- standard protocols are required for accessing information in a
- calendar store and scheduling calendar entries. In addition, these
- protocols require a common data format for representing calendar
- information.
-
- These requirements are met by the following protocol specifications.
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 5]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- - Data format: iCalendar [RFC-2445]
-
- iCalendar [RFC-2445] provides a data format for representing
- calendar information, to be used and exchanged by other protocols.
- iCalendar [RFC-2445] can also be used in other contexts, such as a
- drag-and-drop interface, or an export/import feature. All the
- other calendaring protocols depend on iCalendar [RFC-2445], so all
- elements of a standards-based calendaring and scheduling systems
- will have to be able to interpret iCalendar [RFC-2445].
-
- - Scheduling protocol: iTIP [RFC-2446]
-
- iTIP [RFC-2446] describes the messages used to schedule calendar
- events. Within iTIP messages, events are represented in iCalendar
- [RFC-2445] format, and have semantics that identify the message as
- being an invitation to a meeting, an acceptance of an invitation,
- or the assignment of a task.
-
- iTIP [RFC-2446] messages are used in the scheduling workflow,
- where users exchange messages in order to organize things such as
- events and to-dos. CUAs generate and interpret iTIP [RFC-2446]
- messages at the direction of the calendar user. With iTIP [RFC-
- 2446] users can create, modify, delete, reply to, counter, and
- decline counters to the various iCalendar [RFC-2445] components.
- Furthermore, users can also request the free/busy time of other
- people.
-
- iTIP [RFC-2446] is transport-independent, and has one specified
- transport binding: iMIP [RFC-2447] binds iTIP to e-mail. In
- addition [CAP] will provide a real-time binding of iTIP [RFC-
- 2446], allowing CUAs to perform calendar management and scheduling
- over a single connection.
-
- - Calendar management protocol: [CAP]
-
- [CAP] describes the messages used to manage calendars on a
- calendar store. These messages use iCalendar [RFC-2445] to
- describe various components such as events and to-dos. These
- messages make it possible to perform iTIP [RFC-2446] operations,
- as well as other operations relating to a calendar store such as
- searching, creating calendars, specifying calendar properties, and
- specifying calendar access rights.
-
-
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 6]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-3. Solutions
-
-3.1 Examples
-
- Returning to the scenarios presented in section 2.1, the calendaring
- protocols can be used in the following ways:
-
- a] The doctor can use a proprietary CUA with a local store, and
- perhaps use iCalendar [RFC-2445] as a storage mechanism. This
- would allow her to easily import her data store into another
- application that supports iCalendar [RFC-2445].
-
- b] The musician who wishes to access her agenda from anywhere can
- use a [CAP]-enabled calendar service accessible over the Internet.
- She can then use any available [CAP] clients to access the data.
-
- A proprietary system that provides access through a Web-based
- interface could also be employed, but the use of [CAP] would be
- superior in that it would allow the use of third party
- applications, such as PDA synchronization tools.
-
- c] The development team can use a calendar service which supports
- [CAP], and each member can use a [CAP]-enabled CUA of their
- choice.
-
- Alternatively, each member could use an iMIP [RFC-2447]-enabled
- CUA, and they could book meetings over e-mail. This solution has
- the drawback that it is difficult to examine other users' agendas,
- making the organization of meetings more difficult.
-
- Proprietary solutions are also available, but they require that
- all members use clients by the same vendor, and disallow the use
- of third party applications.
-
- d] The teacher can set up a calendar service, and have students
- book time through any of the iTIP [RFC-2446] bindings. [CAP]
- provides real-time access, but could require additional
- configuration. iMIP [RFC-2447] would be the easiest to configure,
- but may require more e-mail processing.
-
- If [CAP] access is provided then determining the state of the
- teacher's schedule is straightforward. If not, this can be
- determined through iTIP [RFC-2446] free/busy requests. Non-
- standard methods could also be employed, such as serving up
- iCalendar [RFC-2445], HTML, or XML over HTTP.
-
- A proprietary system could also be used, but would require that
- all students be able to use software from a specific vendor.
-
-
-
-Mahoney, et. al. Informational [Page 7]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- e] [CAP] would be preferred for publishing a movie theater's
- schedule, since it provides advanced access and search
- capabilities. It also allows easy integration with customers'
- calendar systems.
-
- Non-standard methods such as serving data over HTTP could also be
- employed, but would be harder to integrate with customers'
- systems.
-
- Using a completely proprietary solution would be very difficult,
- if not impossible, since it would require every user to install
- and use the proprietary software.
-
- f] The social club could distribute meeting information in the
- form of iTIP [RFC-2446] messages, sent via e-mail using iMIP
- [RFC-2447]. The club could distribute meeting invitations, as
- well as a full published agenda.
-
- Alternatively, the club could provide access to a [CAP]-enabled
- calendar service. However, this solution would be more expensive
- since it requires the maintenance of a server.
-
-3.2 Systems
-
- The following diagrams illustrate possible systems and their usage of
- the various protocols.
-
-3.2.1 Standalone Single-user System
-
- A single user system that does not communicate with other systems
- need not employ any of the protocols. However, it may use iCalendar
- [RFC-2445] as a data format in some places.
-
- ----------- O
- | CUA w/ | -+- user
- |local store| A
- ----------- / \
-
-3.2.2 Single-user Systems Communicating
-
- Users with single-user systems may schedule meetings with each others
- using iTIP [RFC-2446]. The easiest binding of iTIP [RFC-2446] to use
- would be iMIP [RFC-2447], since messages can be held in the users'
- mail queues, which we assume to already exist. [CAP] could also be
- used.
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 8]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- O ----------- ----------- O
- -+- | CUA w/ | -----[iMIP]----- | CUA w/ | -+- user
- A |local store| Internet |local store| A
- / \ ----------- ----------- / \
-
-3.2.3 Single-user with Multiple CUAs
-
- A single user may use more than one CUA to access his or her
- calendar. The user may use a PDA, a Web client, a PC, or some other
- device, depending on accessibility. Some of these clients may have
- local stores and others may not. Those with local stores need to
- synchronize the data on the CUA with the data on the CS.
-
- -----------
- | CUA w | -----[CAP]----------+
- |local store| |
- O ----------- ----------
- -+- | CS |
- A | |
- / \ ----------
- ----------- |
- | CUA w/o | -----[CAP]----------+
- |local store|
- -----------
-
-3.2.4 Single-user with Multiple Calendars
-
- A single user may have many independent calendars; for example, one
- may contain work-related information and another personal
- information. The CUA may or may not have a local store. If it does,
- then it needs to synchronize the data of the CUA with the data on
- both of the CS.
-
- ----------
- +------------[CAP]------ | CS |
- | | |
- O ----------- ----------
- -+- | CUA |
- A | |
- / \ -----------
- | ----------
- +------------[CAP]------ | CS |
- | |
- ----------
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 9]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-3.2.5 Users Communicating on a Multi-user System
-
- Users on a multi-user system may schedule meetings with each other
- using [CAP]-enabled CUAs and services. The CUAs may or may not have
- local stores. Those with local stores need to synchronize the data
- on the CUAs with the data on the CS.
-
- O -----------
- -+- | CUA w | -----[CAP]----------+
- A |local store| |
- / \ ----------- ----------
- | CS |
- | |
- ----------
- O ----------- |
- -+- | CUA w/o | -----[CAP]----------+
- A |local store|
- / \ -----------
-
-3.2.6 Users Communicating through Different Multi-user Systems
-
- Users on a multi-user system may need to schedule meetings with users
- on a different multi-user system. The services can communicate using
- [CAP] or iMIP [RFC-2447].
-
- O ----------- ----------
- -+- | CUA w | -----[CAP]-------| CS |
- A |local store| | |
- / \ ----------- ----------
- |
- [CAP] or [iMIP]
- |
- O ----------- ----------
- -+- | CUA w/o | -----[CAP]-------| CS |
- A |local store| | |
- / \ ----------- ----------
-
-4. Important Aspects
-
- There are a number of important aspects of these calendaring
- standards of which people, especially implementers, should be aware.
-
-4.1 Timezones
-
- The dates and times in components can refer to a specific time zone.
- Time zones can be defined in a central store, or they may be defined
- by a user to fit his or her needs. All users and applications should
- be aware of time zones and time zone differences. New time zones may
-
-
-
-Mahoney, et. al. Informational [Page 10]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- need to be added, and others removed. Two different vendors may
- describe the same time zone differently (such as by using a different
- name).
-
-4.2 Choice of Transport
-
- There are issues to be aware of in choosing between a network
- protocol such as [CAP], or a store and forward protocol, such as iMIP
- [RFC-2447].
-
- The use of a network ("on-the-wire") mechanism may require some
- organizations to make provisions to allow calendaring traffic to
- traverse a corporate firewall on the required ports. Depending on
- the organizational culture, this may be a challenging social
- exercise.
-
- The use of an email-based mechanism exposes time-sensitive data to
- unbounded latency. Large or heavily utilized mail systems may
- experience an unacceptable delay in message receipt.
-
-4.3 Security
-
- See the "Security Considerations" (Section 6) section below.
-
-4.4 Amount of data
-
- In some cases, a component may be very large, for instance, a
- component with a very large attachment. Some applications may be
- low-bandwidth or may be limited in the amount of data they can store.
- Maximum component size may be set in [CAP]. It can also be
- controlled in iMIP [RFC-2447] by restricting the maximum size of the
- e-mail that the application can download.
-
-4.5 Recurring Components
-
- In iCAL [RFC-2445], one can specify complex recurrence rules for
- VEVENTs, VTODOs, and VJOURNALs. One must be careful to correctly
- interpret these recurrence rules and pay extra attention to being
- able to interoperate using them.
-
-5. Open Issues
-
- Many issues are not currently resolved by these protocols, and many
- desirable features are not yet provided. Some of the more prominent
- ones are outlined below.
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 11]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-5.1 Scheduling People, not Calendars
-
- Meetings are scheduled with people; however, people may have many
- calendars, and may store these calendars in many places. There may
- also be many routes to contact them. The calendaring protocols do
- not attempt to provide unique access for contacting a given person.
- Instead, 'calendar addresses' are booked, which may be e-mail
- addresses or individual calendars. It is up to the users themselves
- to orchestrate mechanisms to ensure that the bookings go to the right
- place.
-
-5.2 Administration
-
- The calendaring protocols do not address the issues of administering
- users and calendars on a calendar service. This must be handled by
- proprietary mechanisms for each implementation.
-
-5.3 Notification
-
- People often wish to be notified of upcoming events, new events, or
- changes to existing events. The calendaring protocols do not attempt
- to address these needs in a real-time system. Instead, the ability
- to store alarm information on events is provided, which can be used
- to provide client-side notification of upcoming events. To organize
- notification of new or changed events, clients have to poll the data
- store.
-
-6. Security Considerations
-
-6.1 Access Control
-
- There has to be reasonable granularity in the configuration options
- for access to data through [CAP], so that what should be released to
- requesters is released, and what shouldn't is not. Details of
- handling this are described in [CAP].
-
-6.2 Authentication
-
- Access control must be coupled with a good authentication system, so
- that the right people get the right information. For [CAP], this
- means requiring authentication before any database access can be
- performed, and checking access rights and authentication credentials
- before releasing information. [CAP] uses the Simple Authentication
- Security Layer (SASL) for this authentication. In iMIP [RFC-2447],
- this may present some challenges, as authentication is often not a
- consideration in store-and-forward protocols.
-
-
-
-
-
-Mahoney, et. al. Informational [Page 12]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
- Authentication is also important for scheduling, in that receivers of
- scheduling messages should be able to validate the apparent sender.
- Since scheduling messages are wrapped in MIME [RFC-2045], signing and
- encryption are freely available. For messages transmitted over mail,
- this is the only available alternative. It is suggested that
- developers take care in implementing the security features in iMIP
- [RFC-2447], bearing in mind that the concept and need may be foreign
- or non-obvious to users, yet essential for the system to function as
- they might expect.
-
- The real-time protocols provide for the authentication of users, and
- the preservation of that authentication information, allowing for
- validation by the receiving end-user or server.
-
-6.3 Using E-mail
-
- Because scheduling information can be transmitted over mail without
- any authentication information, e-mail spoofing is extremely easy if
- the receiver is not checking for authentication. It is suggested
- that implementers consider requiring authentication as a default,
- using mechanisms such as are described in Section 3 of iMIP [RFC-
- 2447]. The use of e-mail, and the potential for anonymous
- connections, means that 'calendar spam' is possible. Developers
- should consider this threat when designing systems, particularly
- those that allow for automated request processing.
-
-6.4 Other Issues
-
- The current security context should be obvious to users. Because the
- underlying mechanisms may not be clear to users, efforts to make
- clear the current state in the UI should be made. One example of
- this is the 'lock' icon used in some Web browsers during secure
- connections.
-
- With both iMIP [RFC-2447] and [CAP], the possibilities of Denial of
- Service attacks must be considered. The ability to flood a calendar
- system with bogus requests is likely to be exploited once these
- systems become widely deployed, and detection and recovery methods
- will need to be considered.
-
-Acknowledgments
-
- Thanks to the following, who have participated in the development of
- this document:
-
- Eric Busboom, Pat Egen, David Madeo, Shawn Packwood, Bruce Kahn,
- Alan Davies, Robb Surridge.
-
-
-
-
-Mahoney, et. al. Informational [Page 13]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-References
-
- [RFC-2445] Dawson, F. and D. Stenerson, "Internet Calendaring and
- Scheduling Core Object Specification - iCalendar", RFC
- 2445, November 1998.
-
- [RFC-2446] Silverberg, S., Mansour, S., Dawson, F. and R. Hopson,
- "iCalendar Transport-Independent Interoperability Protocol
- (iTIP): Scheduling Events, Busy Time, To-dos and Journal
- Entries", RFC 2446, November 1998.
-
- [RFC-2447] Dawson, F., Mansour, S. and S. Silverberg, "iCalendar
- Message-Based Interoperability Protocol - iMIP", RFC 2447,
- November 1998.
-
- [RFC-2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
- Extensions (MIME) - Part One: Format of Internet Message
- Bodies", RFC 2045, November 1996.
-
- [CAP] Mansour, S., Royer, D., Babics, G., and Hill, P.,
- "Calendar Access Protocol (CAP)", Work in Progress.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 14]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-Authors' Addresses
-
- Bob Mahoney
- MIT
- E40-327
- 77 Massachusetts Avenue
- Cambridge, MA 02139
- US
-
- Phone: (617) 253-0774
- EMail: bobmah at mit.edu
-
-
- George Babics
- Steltor
- 2000 Peel Street
- Montreal, Quebec H3A 2W5
- CA
-
- Phone: (514) 733-8500 x4201
- EMail: georgeb at steltor.com
-
-
- Alexander Taler
-
- EMail: alex at 0--0.org
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 15]
-
-RFC 3283 Guide to Internet Calendaring June 2002
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2002). All Rights Reserved.
-
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published
- and distributed, in whole or in part, without restriction of any
- kind, provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be
- followed, or as required to translate it into languages other than
- English.
-
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
-
- This document and the information contained herein is provided on an
- "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
- TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
- BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
- HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Mahoney, et. al. Informational [Page 16]
-
Copied: CalendarServer/trunk/doc/RFC/rfc3744-WebDAV ACL.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc3744.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3744-WebDAV ACL.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc3744-WebDAV ACL.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,4035 @@
+
+
+
+
+
+
+Network Working Group G. Clemm
+Request for Comments: 3744 IBM
+Category: Standards Track J. Reschke
+ greenbytes
+ E. Sedlar
+ Oracle Corporation
+ J. Whitehead
+ U.C. Santa Cruz
+ May 2004
+
+
+ Web Distributed Authoring and Versioning (WebDAV)
+ Access Control Protocol
+
+Status of this Memo
+
+ This document specifies an Internet standards track protocol for the
+ Internet community, and requests discussion and suggestions for
+ improvements. Please refer to the current edition of the "Internet
+ Official Protocol Standards" (STD 1) for the standardization state
+ and status of this protocol. Distribution of this memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2004). All Rights Reserved.
+
+Abstract
+
+ This document specifies a set of methods, headers, message bodies,
+ properties, and reports that define Access Control extensions to the
+ WebDAV Distributed Authoring Protocol. This protocol permits a
+ client to read and modify access control lists that instruct a server
+ whether to allow or deny operations upon a resource (such as
+ HyperText Transfer Protocol (HTTP) method invocations) by a given
+ principal. A lightweight representation of principals as Web
+ resources supports integration of a wide range of user management
+ repositories. Search operations allow discovery and manipulation of
+ principals using human names.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 1]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
+ 1.1. Terms. . . . . . . . . . . . . . . . . . . . . . . . . . 6
+ 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 8
+ 2. Principals . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 3. Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . 8
+ 3.1. DAV:read Privilege . . . . . . . . . . . . . . . . . . . 10
+ 3.2. DAV:write Privilege. . . . . . . . . . . . . . . . . . . 10
+ 3.3. DAV:write-properties Privilege . . . . . . . . . . . . . 10
+ 3.4. DAV:write-content Privilege. . . . . . . . . . . . . . . 11
+ 3.5. DAV:unlock Privilege . . . . . . . . . . . . . . . . . . 11
+ 3.6. DAV:read-acl Privilege . . . . . . . . . . . . . . . . . 11
+ 3.7. DAV:read-current-user-privilege-set Privilege. . . . . . 12
+ 3.8. DAV:write-acl Privilege. . . . . . . . . . . . . . . . . 12
+ 3.9. DAV:bind Privilege . . . . . . . . . . . . . . . . . . . 12
+ 3.10. DAV:unbind Privilege . . . . . . . . . . . . . . . . . . 12
+ 3.11. DAV:all Privilege. . . . . . . . . . . . . . . . . . . . 13
+ 3.12. Aggregation of Predefined Privileges . . . . . . . . . . 13
+ 4. Principal Properties . . . . . . . . . . . . . . . . . . . . . 13
+ 4.1. DAV:alternate-URI-set. . . . . . . . . . . . . . . . . . 14
+ 4.2. DAV:principal-URL. . . . . . . . . . . . . . . . . . . . 14
+ 4.3. DAV:group-member-set . . . . . . . . . . . . . . . . . . 14
+ 4.4. DAV:group-membership . . . . . . . . . . . . . . . . . . 14
+ 5. Access Control Properties. . . . . . . . . . . . . . . . . . . 15
+ 5.1. DAV:owner. . . . . . . . . . . . . . . . . . . . . . . . 15
+ 5.1.1. Example: Retrieving DAV:owner . . . . . . . . . . 15
+ 5.1.2. Example: An Attempt to Set DAV:owner. . . . . . . 16
+ 5.2. DAV:group. . . . . . . . . . . . . . . . . . . . . . . . 18
+ 5.3. DAV:supported-privilege-set. . . . . . . . . . . . . . . 18
+ 5.3.1. Example: Retrieving a List of Privileges
+ Supported on a Resource . . . . . . . . . . . . . 19
+ 5.4. DAV:current-user-privilege-set . . . . . . . . . . . . . 21
+ 5.4.1. Example: Retrieving the User's Current Set of
+ Assigned Privileges . . . . . . . . . . . . . . . 22
+ 5.5. DAV:acl. . . . . . . . . . . . . . . . . . . . . . . . . 23
+ 5.5.1. ACE Principal . . . . . . . . . . . . . . . . . . 23
+ 5.5.2. ACE Grant and Deny. . . . . . . . . . . . . . . . 25
+ 5.5.3. ACE Protection. . . . . . . . . . . . . . . . . . 25
+ 5.5.4. ACE Inheritance . . . . . . . . . . . . . . . . . 25
+ 5.5.5. Example: Retrieving a Resource's Access Control
+ List. . . . . . . . . . . . . . . . . . . . . . . 25
+ 5.6. DAV:acl-restrictions . . . . . . . . . . . . . . . . . . 27
+ 5.6.1. DAV:grant-only. . . . . . . . . . . . . . . . . . 27
+ 5.6.2. DAV:no-invert ACE Constraint. . . . . . . . . . . 28
+ 5.6.3. DAV:deny-before-grant . . . . . . . . . . . . . . 28
+ 5.6.4. Required Principals . . . . . . . . . . . . . . . 28
+ 5.6.5. Example: Retrieving DAV:acl-restrictions. . . . . 28
+
+
+
+Clemm, et al. Standards Track [Page 2]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ 5.7. DAV:inherited-acl-set. . . . . . . . . . . . . . . . . . 29
+ 5.8. DAV:principal-collection-set . . . . . . . . . . . . . . 30
+ 5.8.1. Example: Retrieving DAV:principal-collection-set. 30
+ 5.9. Example: PROPFIND to retrieve access control properties. 32
+ 6. ACL Evaluation . . . . . . . . . . . . . . . . . . . . . . . . 36
+ 7. Access Control and existing methods. . . . . . . . . . . . . . 37
+ 7.1. Any HTTP method. . . . . . . . . . . . . . . . . . . . . 37
+ 7.1.1. Error Handling. . . . . . . . . . . . . . . . . . 37
+ 7.2. OPTIONS. . . . . . . . . . . . . . . . . . . . . . . . . 38
+ 7.2.1. Example - OPTIONS . . . . . . . . . . . . . . . . 39
+ 7.3. MOVE . . . . . . . . . . . . . . . . . . . . . . . . . . 39
+ 7.4. COPY . . . . . . . . . . . . . . . . . . . . . . . . . . 39
+ 7.5. LOCK . . . . . . . . . . . . . . . . . . . . . . . . . . 39
+ 8. Access Control Methods . . . . . . . . . . . . . . . . . . . . 40
+ 8.1. ACL. . . . . . . . . . . . . . . . . . . . . . . . . . . 40
+ 8.1.1. ACL Preconditions . . . . . . . . . . . . . . . . 40
+ 8.1.2. Example: the ACL method . . . . . . . . . . . . . 42
+ 8.1.3. Example: ACL method failure due to protected
+ ACE conflict. . . . . . . . . . . . . . . . . . . 43
+ 8.1.4. Example: ACL method failure due to an
+ inherited ACE conflict. . . . . . . . . . . . . . 44
+ 8.1.5. Example: ACL method failure due to an attempt
+ to set grant and deny in a single ACE . . . . . . 45
+ 9. Access Control Reports . . . . . . . . . . . . . . . . . . . . 46
+ 9.1. REPORT Method. . . . . . . . . . . . . . . . . . . . . . 46
+ 9.2. DAV:acl-principal-prop-set Report. . . . . . . . . . . . 47
+ 9.2.1. Example: DAV:acl-principal-prop-set Report. . . . 48
+ 9.3. DAV:principal-match REPORT . . . . . . . . . . . . . . . 49
+ 9.3.1. Example: DAV:principal-match REPORT . . . . . . . 50
+ 9.4. DAV:principal-property-search REPORT . . . . . . . . . . 51
+ 9.4.1. Matching. . . . . . . . . . . . . . . . . . . . . 53
+ 9.4.2. Example: successful DAV:principal-property-search
+ REPORT. . . . . . . . . . . . . . . . . . . . . . 54
+ 9.5. DAV:principal-search-property-set REPORT . . . . . . . . 56
+ 9.5.1. Example: DAV:principal-search-property-set
+ REPORT. . . . . . . . . . . . . . . . . . . . . . 58
+ 10. XML Processing . . . . . . . . . . . . . . . . . . . . . . . . 59
+ 11. Internationalization Considerations. . . . . . . . . . . . . . 59
+ 12. Security Considerations. . . . . . . . . . . . . . . . . . . . 60
+ 12.1. Increased Risk of Compromised Users. . . . . . . . . . . 60
+ 12.2. Risks of the DAV:read-acl and
+ DAV:current-user-privilege-set Privileges. . . . . . . . 60
+ 12.3. No Foreknowledge of Initial ACL. . . . . . . . . . . . . 61
+ 13. Authentication . . . . . . . . . . . . . . . . . . . . . . . . 61
+ 14. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 62
+ 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 62
+
+
+
+
+
+Clemm, et al. Standards Track [Page 3]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 62
+ 16.1. Normative References . . . . . . . . . . . . . . . . . . 62
+ 16.2. Informative References . . . . . . . . . . . . . . . . . 63
+ Appendices
+ A. WebDAV XML Document Type Definition Addendum . . . . . . . . . 64
+ B. WebDAV Method Privilege Table (Normative). . . . . . . . . . . 67
+ Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 71
+ Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 72
+
+1. Introduction
+
+ The goal of the WebDAV access control extensions is to provide an
+ interoperable mechanism for handling discretionary access control for
+ content and metadata managed by WebDAV servers. WebDAV access
+ control can be implemented on content repositories with security as
+ simple as that of a UNIX file system, as well as more sophisticated
+ models. The underlying principle of access control is that who you
+ are determines what operations you can perform on a resource. The
+ "who you are" is defined by a "principal" identifier; users, client
+ software, servers, and groups of the previous have principal
+ identifiers. The "operations you can perform" are determined by a
+ single "access control list" (ACL) associated with a resource. An
+ ACL contains a set of "access control entries" (ACEs), where each ACE
+ specifies a principal and a set of privileges that are either granted
+ or denied to that principal. When a principal submits an operation
+ (such as an HTTP or WebDAV method) to a resource for execution, the
+ server evaluates the ACEs in the ACL to determine if the principal
+ has permission for that operation.
+
+ Since every ACE contains the identifier of a principal, client
+ software operated by a human must provide a mechanism for selecting
+ this principal. This specification uses http(s) scheme URLs to
+ identify principals, which are represented as WebDAV-capable
+ resources. There is no guarantee that the URLs identifying
+ principals will be meaningful to a human. For example,
+ http://www.example.com/u/256432 and
+ http://www.example.com/people/Greg.Stein are both valid URLs that
+ could be used to identify the same principal. To remedy this, every
+ principal resource has the DAV:displayname property containing a
+ human-readable name for the principal.
+
+ Since a principal can be identified by multiple URLs, it raises the
+ problem of determining exactly which principal is being referenced in
+ a given ACE. It is impossible for a client to determine that an ACE
+ granting the read privilege to http://www.example.com/people/
+ Greg.Stein also affects the principal at http://www.example.com/u/
+ 256432. That is, a client has no mechanism for determining that two
+
+
+
+Clemm, et al. Standards Track [Page 4]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ URLs identify the same principal resource. As a result, this
+ specification requires clients to use just one of the many possible
+ URLs for a principal when creating ACEs. A client can discover which
+ URL to use by retrieving the DAV:principal-URL property (Section 4.2)
+ from a principal resource. No matter which of the principal's URLs
+ is used with PROPFIND, the property always returns the same URL.
+
+ With a system having hundreds to thousands of principals, the problem
+ arises of how to allow a human operator of client software to select
+ just one of these principals. One approach is to use broad
+ collection hierarchies to spread the principals over a large number
+ of collections, yielding few principals per collection. An example
+ of this is a two level hierarchy with the first level containing 36
+ collections (a-z, 0-9), and the second level being another 36,
+ creating collections /a/a/, /a/b/, ..., /a/z/, such that a principal
+ with last name "Stein" would appear at /s/t/Stein. In effect, this
+ pre-computes a common query, search on last name, and encodes it into
+ a hierarchy. The drawback with this scheme is that it handles only a
+ small set of predefined queries, and drilling down through the
+ collection hierarchy adds unnecessary steps (navigate down/up) when
+ the user already knows the principal's name. While organizing
+ principal URLs into a hierarchy is a valid namespace organization,
+ users should not be forced to navigate this hierarchy to select a
+ principal.
+
+ This specification provides the capability to perform substring
+ searches over a small set of properties on the resources representing
+ principals. This permits searches based on last name, first name,
+ user name, job title, etc. Two separate searches are supported, both
+ via the REPORT method, one to search principal resources
+ (DAV:principal-property-search, Section 9.4), the other to determine
+ which properties may be searched at all (DAV:principal-search-
+ property-set, Section 9.5).
+
+ Once a principal has been identified in an ACE, a server evaluating
+ that ACE must know the identity of the principal making a protocol
+ request, and must validate that that principal is who they claim to
+ be, a process known as authentication. This specification
+ intentionally omits discussion of authentication, as the HTTP
+ protocol already has a number of authentication mechanisms [RFC2617].
+ Some authentication mechanism (such as HTTP Digest Authentication,
+ which all WebDAV compliant implementations are required to support)
+ must be available to validate the identity of a principal.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 5]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The following issues are out of scope for this document:
+
+ o Access control that applies only to a particular property on a
+ resource (excepting the access control properties DAV:acl and
+ DAV:current-user-privilege-set), rather than the entire resource,
+
+ o Role-based security (where a role can be seen as a dynamically
+ defined group of principals),
+
+ o Specification of the ways an ACL on a resource is initialized,
+
+ o Specification of an ACL that applies globally to all resources,
+ rather than to a particular resource.
+
+ o Creation and maintenance of resources representing people or
+ computational agents (principals), and groups of these.
+
+ This specification is organized as follows. Section 1.1 defines key
+ concepts used throughout the specification, and is followed by a more
+ in-depth discussion of principals (Section 2), and privileges
+ (Section 3). Properties defined on principals are specified in
+ Section 4, and access control properties for content resources are
+ specified in Section 5. The ways ACLs are to be evaluated is
+ described in Section 6. Client discovery of access control
+ capability using OPTIONS is described in Section 7.2. Interactions
+ between access control functionality and existing HTTP and WebDAV
+ methods are described in the remainder of Section 7. The access
+ control setting method, ACL, is specified in Section 8. Four reports
+ that provide limited server-side searching capabilities are described
+ in Section 9. Sections on XML processing (Section 10),
+ Internationalization considerations (Section 11), security
+ considerations (Section 12), and authentication (Section 13) round
+ out the specification. An appendix (Appendix A) provides an XML
+ Document Type Definition (DTD) for the XML elements defined in the
+ specification.
+
+1.1. Terms
+
+ This document uses the terms defined in HTTP [RFC2616] and WebDAV
+ [RFC2518]. In addition, the following terms are defined:
+
+ principal
+
+ A "principal" is a distinct human or computational actor that
+ initiates access to network resources. In this protocol, a
+ principal is an HTTP resource that represents such an actor.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 6]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ group
+
+ A "group" is a principal that represents a set of other
+ principals.
+
+ privilege
+
+ A "privilege" controls access to a particular set of HTTP
+ operations on a resource.
+
+ aggregate privilege
+
+ An "aggregate privilege" is a privilege that contains a set of
+ other privileges.
+
+ abstract privilege
+
+ The modifier "abstract", when applied to a privilege on a
+ resource, means the privilege cannot be set in an access control
+ element (ACE) on that resource.
+
+ access control list (ACL)
+
+ An "ACL" is a list of access control elements that define access
+ control to a particular resource.
+
+ access control element (ACE)
+
+ An "ACE" either grants or denies a particular set of (non-
+ abstract) privileges for a particular principal.
+
+ inherited ACE
+
+ An "inherited ACE" is an ACE that is dynamically shared from the
+ ACL of another resource. When a shared ACE changes on the primary
+ resource, it is also changed on inheriting resources.
+
+ protected property
+
+ A "protected property" is one whose value cannot be updated except
+ by a method explicitly defined as updating that specific property.
+ In particular, a protected property cannot be updated with a
+ PROPPATCH request.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 7]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+1.2. Notational Conventions
+
+ The augmented BNF used by this document to describe protocol elements
+ is described in Section 2.1 of [RFC2616]. Because this augmented BNF
+ uses the basic production rules provided in Section 2.2 of [RFC2616],
+ those rules apply to this document as well.
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [RFC2119].
+
+ Definitions of XML elements in this document use XML element type
+ declarations (as found in XML Document Type Declarations), described
+ in Section 3.2 of [REC-XML]. When an XML element type in the "DAV:"
+ namespace is referenced in this document outside of the context of an
+ XML fragment, the string "DAV:" will be prefixed to the element name.
+
+2. Principals
+
+ A principal is a network resource that represents a distinct human or
+ computational actor that initiates access to network resources.
+ Users and groups are represented as principals in many
+ implementations; other types of principals are also possible. A URI
+ of any scheme MAY be used to identify a principal resource. However,
+ servers implementing this specification MUST expose principal
+ resources at an http(s) URL, which is a privileged scheme that points
+ to resources that have additional properties, as described in Section
+ 4. So, a principal resource can have multiple URIs, one of which has
+ to be an http(s) scheme URL. Although an implementation SHOULD
+ support PROPFIND and MAY support PROPPATCH to access and modify
+ information about a principal, it is not required to do so.
+
+ A principal resource may be a group, where a group is a principal
+ that represents a set of other principals, called the members of the
+ group. If a person or computational agent matches a principal
+ resource that is a member of a group, they also match the group.
+ Membership in a group is recursive, so if a principal is a member of
+ group GRPA, and GRPA is a member of group GRPB, then the principal is
+ also a member of GRPB.
+
+3. Privileges
+
+ Ability to perform a given method on a resource MUST be controlled by
+ one or more privileges. Authors of protocol extensions that define
+ new HTTP methods SHOULD specify which privileges (by defining new
+ privileges, or mapping to ones below) are required to perform the
+ method. A principal with no privileges to a resource MUST be denied
+ any HTTP access to that resource, unless the principal matches an ACE
+
+
+
+Clemm, et al. Standards Track [Page 8]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ constructed using the DAV:all, DAV:authenticated, or
+ DAV:unauthenticated pseudo-principals (see Section 5.5.1). Servers
+ MUST report a 403 "Forbidden" error if access is denied, except in
+ the case where the privilege restricts the ability to know the
+ resource exists, in which case 404 "Not Found" may be returned.
+
+ Privileges may be containers of other privileges, in which case they
+ are termed "aggregate privileges". If a principal is granted or
+ denied an aggregate privilege, it is semantically equivalent to
+ granting or denying each of the aggregated privileges individually.
+ For example, an implementation may define add-member and remove-
+ member privileges that control the ability to add and remove a member
+ of a group. Since these privileges control the ability to update the
+ state of a group, these privileges would be aggregated by the
+ DAV:write privilege on a group, and granting the DAV:write privilege
+ on a group would also grant the add-member and remove-member
+ privileges.
+
+ Privileges may be declared to be "abstract" for a given resource, in
+ which case they cannot be set in an ACE on that resource. Aggregate
+ and non-aggregate privileges are both capable of being abstract.
+ Abstract privileges are useful for modeling privileges that otherwise
+ would not be exposed via the protocol. Abstract privileges also
+ provide server implementations with flexibility in implementing the
+ privileges defined in this specification. For example, if a server
+ is incapable of separating the read resource capability from the read
+ ACL capability, it can still model the DAV:read and DAV:read-acl
+ privileges defined in this specification by declaring them abstract,
+ and containing them within a non-abstract aggregate privilege (say,
+ read-all) that holds DAV:read, and DAV:read-acl. In this way, it is
+ possible to set the aggregate privilege, read-all, thus coupling the
+ setting of DAV:read and DAV:read-acl, but it is not possible to set
+ DAV:read, or DAV:read-acl individually. Since aggregate privileges
+ can be abstract, it is also possible to use abstract privileges to
+ group or organize non-abstract privileges. Privilege containment
+ loops are not allowed; therefore, a privilege MUST NOT contain
+ itself. For example, DAV:read cannot contain DAV:read.
+
+ The set of privileges that apply to a particular resource may vary
+ with the DAV:resourcetype of the resource, as well as between
+ different server implementations. To promote interoperability,
+ however, this specification defines a set of well-known privileges
+ (e.g., DAV:read, DAV:write, DAV:read-acl, DAV:write-acl, DAV:read-
+ current-user-privilege-set, and DAV:all), which can at least be used
+ to classify the other privileges defined on a particular resource.
+ The access permissions on null resources (defined in [RFC2518],
+ Section 3) are solely those they inherit (if any), and they are not
+ discoverable (i.e., the access control properties specified in
+
+
+
+Clemm, et al. Standards Track [Page 9]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Section 5 are not defined on null resources). On the transition from
+ null to stateful resource, the initial access control list is set by
+ the server's default ACL value policy (if any).
+
+ Server implementations MAY define new privileges beyond those defined
+ in this specification. Privileges defined by individual
+ implementations MUST NOT use the DAV: namespace, and instead should
+ use a namespace that they control, such as an http scheme URL.
+
+3.1. DAV:read Privilege
+
+ The read privilege controls methods that return information about the
+ state of the resource, including the resource's properties. Affected
+ methods include GET and PROPFIND. Any implementation-defined
+ privilege that also controls access to GET and PROPFIND must be
+ aggregated under DAV:read - if an ACL grants access to DAV:read, the
+ client may expect that no other privilege needs to be granted to have
+ access to GET and PROPFIND. Additionally, the read privilege MUST
+ control the OPTIONS method.
+
+ <!ELEMENT read EMPTY>
+
+3.2. DAV:write Privilege
+
+ The write privilege controls methods that lock a resource or modify
+ the content, dead properties, or (in the case of a collection)
+ membership of the resource, such as PUT and PROPPATCH. Note that
+ state modification is also controlled via locking (see section 5.3 of
+ [RFC2518]), so effective write access requires that both write
+ privileges and write locking requirements are satisfied. Any
+ implementation-defined privilege that also controls access to methods
+ modifying content, dead properties or collection membership must be
+ aggregated under DAV:write, e.g., if an ACL grants access to
+ DAV:write, the client may expect that no other privilege needs to be
+ granted to have access to PUT and PROPPATCH.
+
+ <!ELEMENT write EMPTY>
+
+3.3. DAV:write-properties Privilege
+
+ The DAV:write-properties privilege controls methods that modify the
+ dead properties of the resource, such as PROPPATCH. Whether this
+ privilege may be used to control access to any live properties is
+ determined by the implementation. Any implementation-defined
+ privilege that also controls access to methods modifying dead
+ properties must be aggregated under DAV:write-properties - e.g., if
+
+
+
+
+
+Clemm, et al. Standards Track [Page 10]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ an ACL grants access to DAV:write-properties, the client can safely
+ expect that no other privilege needs to be granted to have access to
+ PROPPATCH.
+
+ <!ELEMENT write-properties EMPTY>
+
+3.4. DAV:write-content Privilege
+
+ The DAV:write-content privilege controls methods that modify the
+ content of an existing resource, such as PUT. Any implementation-
+ defined privilege that also controls access to content must be
+ aggregated under DAV:write-content - e.g., if an ACL grants access to
+ DAV:write-content, the client can safely expect that no other
+ privilege needs to be granted to have access to PUT. Note that PUT -
+ when applied to an unmapped URI - creates a new resource and
+ therefore is controlled by the DAV:bind privilege on the parent
+ collection.
+
+ <!ELEMENT write-content EMPTY>
+
+3.5. DAV:unlock Privilege
+
+ The DAV:unlock privilege controls the use of the UNLOCK method by a
+ principal other than the lock owner (the principal that created a
+ lock can always perform an UNLOCK). While the set of users who may
+ lock a resource is most commonly the same set of users who may modify
+ a resource, servers may allow various kinds of administrators to
+ unlock resources locked by others. Any privilege controlling access
+ by non-lock owners to UNLOCK MUST be aggregated under DAV:unlock.
+
+ A lock owner can always remove a lock by issuing an UNLOCK with the
+ correct lock token and authentication credentials. That is, even if
+ a principal does not have DAV:unlock privilege, they can still remove
+ locks they own. Principals other than the lock owner can remove a
+ lock only if they have DAV:unlock privilege and they issue an UNLOCK
+ with the correct lock token. Lock timeout is not affected by the
+ DAV:unlock privilege.
+
+ <!ELEMENT unlock EMPTY>
+
+3.6. DAV:read-acl Privilege
+
+ The DAV:read-acl privilege controls the use of PROPFIND to retrieve
+ the DAV:acl property of the resource.
+
+ <!ELEMENT read-acl EMPTY>
+
+
+
+
+
+Clemm, et al. Standards Track [Page 11]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+3.7. DAV:read-current-user-privilege-set Privilege
+
+ The DAV:read-current-user-privilege-set privilege controls the use of
+ PROPFIND to retrieve the DAV:current-user-privilege-set property of
+ the resource.
+
+ Clients are intended to use this property to visually indicate in
+ their UI items that are dependent on the permissions of a resource,
+ for example, by graying out resources that are not writable.
+
+ This privilege is separate from DAV:read-acl because there is a need
+ to allow most users access to the privileges permitted the current
+ user (due to its use in creating the UI), while the full ACL contains
+ information that may not be appropriate for the current authenticated
+ user. As a result, the set of users who can view the full ACL is
+ expected to be much smaller than those who can read the current user
+ privilege set, and hence distinct privileges are needed for each.
+
+ <!ELEMENT read-current-user-privilege-set EMPTY>
+
+3.8. DAV:write-acl Privilege
+
+ The DAV:write-acl privilege controls use of the ACL method to modify
+ the DAV:acl property of the resource.
+
+ <!ELEMENT write-acl EMPTY>
+
+3.9. DAV:bind Privilege
+
+ The DAV:bind privilege allows a method to add a new member URL to the
+ specified collection (for example via PUT or MKCOL). It is ignored
+ for resources that are not collections.
+
+ <!ELEMENT bind EMPTY>
+
+3.10. DAV:unbind Privilege
+
+ The DAV:unbind privilege allows a method to remove a member URL from
+ the specified collection (for example via DELETE or MOVE). It is
+ ignored for resources that are not collections.
+
+ <!ELEMENT unbind EMPTY>
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 12]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+3.11. DAV:all Privilege
+
+ DAV:all is an aggregate privilege that contains the entire set of
+ privileges that can be applied to the resource.
+
+ <!ELEMENT all EMPTY>
+
+3.12. Aggregation of Predefined Privileges
+
+ Server implementations are free to aggregate the predefined
+ privileges (defined above in Sections 3.1-3.10) subject to the
+ following limitations:
+
+ DAV:read-acl MUST NOT contain DAV:read, DAV:write, DAV:write-acl,
+ DAV:write-properties, DAV:write-content, or DAV:read-current-user-
+ privilege-set.
+
+ DAV:write-acl MUST NOT contain DAV:write, DAV:read, DAV:read-acl, or
+ DAV:read-current-user-privilege-set.
+
+ DAV:read-current-user-privilege-set MUST NOT contain DAV:write,
+ DAV:read, DAV:read-acl, or DAV:write-acl.
+
+ DAV:write MUST NOT contain DAV:read, DAV:read-acl, or DAV:read-
+ current-user-privilege-set.
+
+ DAV:read MUST NOT contain DAV:write, DAV:write-acl, DAV:write-
+ properties, or DAV:write-content.
+
+ DAV:write MUST contain DAV:bind, DAV:unbind, DAV:write-properties and
+ DAV:write-content.
+
+4. Principal Properties
+
+ Principals are manifested to clients as a WebDAV resource, identified
+ by a URL. A principal MUST have a non-empty DAV:displayname property
+ (defined in Section 13.2 of [RFC2518]), and a DAV:resourcetype
+ property (defined in Section 13.9 of [RFC2518]). Additionally, a
+ principal MUST report the DAV:principal XML element in the value of
+ the DAV:resourcetype property. The element type declaration for
+ DAV:principal is:
+
+ <!ELEMENT principal EMPTY>
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 13]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ This protocol defines the following additional properties for a
+ principal. Since it can be expensive for a server to retrieve access
+ control information, the name and value of these properties SHOULD
+ NOT be returned by a PROPFIND allprop request (as defined in Section
+ 12.14.1 of [RFC2518]).
+
+4.1. DAV:alternate-URI-set
+
+ This protected property, if non-empty, contains the URIs of network
+ resources with additional descriptive information about the
+ principal. This property identifies additional network resources
+ (i.e., it contains one or more URIs) that may be consulted by a
+ client to gain additional knowledge concerning a principal. One
+ expected use for this property is the storage of an LDAP [RFC2255]
+ scheme URL. A user-agent encountering an LDAP URL could use LDAP
+ [RFC2251] to retrieve additional machine-readable directory
+ information about the principal, and display that information in its
+ user interface. Support for this property is REQUIRED, and the value
+ is empty if no alternate URI exists for the principal.
+
+ <!ELEMENT alternate-URI-set (href*)>
+
+4.2. DAV:principal-URL
+
+ A principal may have many URLs, but there must be one "principal URL"
+ that clients can use to uniquely identify a principal. This
+ protected property contains the URL that MUST be used to identify
+ this principal in an ACL request. Support for this property is
+ REQUIRED.
+
+ <!ELEMENT principal-URL (href)>
+
+4.3. DAV:group-member-set
+
+ This property of a group principal identifies the principals that are
+ direct members of this group. Since a group may be a member of
+ another group, a group may also have indirect members (i.e., the
+ members of its direct members). A URL in the DAV:group-member-set
+ for a principal MUST be the DAV:principal-URL of that principal.
+
+ <!ELEMENT group-member-set (href*)>
+
+4.4. DAV:group-membership
+
+ This protected property identifies the groups in which the principal
+ is directly a member. Note that a server may allow a group to be a
+ member of another group, in which case the DAV:group-membership of
+
+
+
+
+Clemm, et al. Standards Track [Page 14]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ those other groups would need to be queried in order to determine the
+ groups in which the principal is indirectly a member. Support for
+ this property is REQUIRED.
+
+ <!ELEMENT group-membership (href*)>
+
+5. Access Control Properties
+
+ This specification defines a number of new properties for WebDAV
+ resources. Access control properties may be retrieved just like
+ other WebDAV properties, using the PROPFIND method. Since it is
+ expensive, for many servers, to retrieve access control information,
+ a PROPFIND allprop request (as defined in Section 12.14.1 of
+ [RFC2518]) SHOULD NOT return the names and values of the properties
+ defined in this section.
+
+ Access control properties (especially DAV:acl and DAV:inherited-acl-
+ set) are defined on the resource identified by the Request-URI of a
+ PROPFIND request. A direct consequence is that if the resource is
+ accessible via multiple URI, the value of access control properties
+ is the same across these URI.
+
+ HTTP resources that support the WebDAV Access Control Protocol MUST
+ contain the following properties. Null resources (described in
+ Section 3 of [RFC2518]) MUST NOT contain the following properties.
+
+5.1. DAV:owner
+
+ This property identifies a particular principal as being the "owner"
+ of the resource. Since the owner of a resource often has special
+ access control capabilities (e.g., the owner frequently has permanent
+ DAV:write-acl privilege), clients might display the resource owner in
+ their user interface.
+
+ Servers MAY implement DAV:owner as protected property and MAY return
+ an empty DAV:owner element as property value in case no owner
+ information is available.
+
+ <!ELEMENT owner (href?)>
+
+5.1.1. Example: Retrieving DAV:owner
+
+ This example shows a client request for the value of the DAV:owner
+ property from a collection resource with URL http://www.example.com/
+ papers/. The principal making the request is authenticated using
+ Digest authentication. The value of DAV:owner is the URL http://
+ www.example.com/acl/users/gstein, wrapped in the DAV:href XML
+ element.
+
+
+
+Clemm, et al. Standards Track [Page 15]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="jim",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:owner/>
+ </D:prop>
+ </D:propfind>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:owner>
+ <D:href>http://www.example.com/acl/users/gstein</D:href>
+ </D:owner>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+5.1.2. Example: An Attempt to Set DAV:owner
+
+ The following example shows a client request to modify the value of
+ the DAV:owner property on the resource with URL <http://
+ www.example.com/papers>. Since DAV:owner is a protected property on
+ this particular server, it responds with a 207 (Multi-Status)
+ response that contains a 403 (Forbidden) status code for the act of
+ setting DAV:owner. Section 8.2.1 of [RFC2518] describes PROPPATCH
+ status code information, Section 11 of [RFC2518] describes the
+
+
+
+Clemm, et al. Standards Track [Page 16]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Multi-Status response and Sections 1.6 and 3.12 of [RFC3253] describe
+ additional error marshaling for PROPPATCH attempts on protected
+ properties.
+
+ >> Request <<
+
+ PROPPATCH /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="jim",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propertyupdate xmlns:D="DAV:">
+ <D:set>
+ <D:prop>
+ <D:owner>
+ <D:href>http://www.example.com/acl/users/jim</D:href>
+ </D:owner>
+ </D:prop>
+ </D:set>
+ </D:propertyupdate>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop><D:owner/></D:prop>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:responsedescription>
+ <D:error><D:cannot-modify-protected-property/></D:error>
+ Failure to set protected property (DAV:owner)
+ </D:responsedescription>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+
+Clemm, et al. Standards Track [Page 17]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.2. DAV:group
+
+ This property identifies a particular principal as being the "group"
+ of the resource. This property is commonly found on repositories
+ that implement the Unix privileges model.
+
+ Servers MAY implement DAV:group as protected property and MAY return
+ an empty DAV:group element as property value in case no group
+ information is available.
+
+ <!ELEMENT group (href?)>
+
+5.3. DAV:supported-privilege-set
+
+ This is a protected property that identifies the privileges defined
+ for the resource.
+
+ <!ELEMENT supported-privilege-set (supported-privilege*)>
+
+ Each privilege appears as an XML element, where aggregate privileges
+ list as sub-elements all of the privileges that they aggregate.
+
+ <!ELEMENT supported-privilege
+ (privilege, abstract?, description, supported-privilege*)>
+ <!ELEMENT privilege ANY>
+
+ An abstract privilege MUST NOT be used in an ACE for that resource.
+ Servers MUST fail an attempt to set an abstract privilege.
+
+ <!ELEMENT abstract EMPTY>
+
+ A description is a human-readable description of what this privilege
+ controls access to. Servers MUST indicate the human language of the
+ description using the xml:lang attribute and SHOULD consider the HTTP
+ Accept-Language request header when selecting one of multiple
+ available languages.
+
+ <!ELEMENT description #PCDATA>
+
+ It is envisioned that a WebDAV ACL-aware administrative client would
+ list the supported privileges in a dialog box, and allow the user to
+ choose non-abstract privileges to apply in an ACE. The privileges
+ tree is useful programmatically to map well-known privileges (defined
+ by WebDAV or other standards groups) into privileges that are
+ supported by any particular server implementation. The privilege
+ tree also serves to hide complexity in implementations allowing large
+ number of privileges to be defined by displaying aggregates to the
+ user.
+
+
+
+Clemm, et al. Standards Track [Page 18]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.3.1. Example: Retrieving a List of Privileges Supported on a Resource
+
+ This example shows a client request for the DAV:supported-privilege-
+ set property on the resource http://www.example.com/papers/. The
+ value of the DAV:supported-privilege-set property is a tree of
+ supported privileges (using "[XML Namespace , localname]" to identify
+ each privilege):
+
+ [DAV:, all] (aggregate, abstract)
+ |
+ +-- [DAV:, read] (aggregate)
+ |
+ +-- [DAV:, read-acl] (abstract)
+ +-- [DAV:, read-current-user-privilege-set] (abstract)
+ |
+ +-- [DAV:, write] (aggregate)
+ |
+ +-- [DAV:, write-acl] (abstract)
+ +-- [DAV:, write-properties]
+ +-- [DAV:, write-content]
+ |
+ +-- [DAV:, unlock]
+
+ This privilege tree is not normative (except that it reflects the
+ normative aggregation rules given in Section 3.12), and many possible
+ privilege trees are possible.
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="gclemm",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:supported-privilege-set/>
+ </D:prop>
+ </D:propfind>
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 19]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:supported-privilege-set>
+ <D:supported-privilege>
+ <D:privilege><D:all/></D:privilege>
+ <D:abstract/>
+ <D:description xml:lang="en">
+ Any operation
+ </D:description>
+ <D:supported-privilege>
+ <D:privilege><D:read/></D:privilege>
+ <D:description xml:lang="en">
+ Read any object
+ </D:description>
+ <D:supported-privilege>
+ <D:privilege><D:read-acl/></D:privilege>
+ <D:abstract/>
+ <D:description xml:lang="en">Read ACL</D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege>
+ <D:read-current-user-privilege-set/>
+ </D:privilege>
+ <D:abstract/>
+ <D:description xml:lang="en">
+ Read current user privilege set property
+ </D:description>
+ </D:supported-privilege>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:write/></D:privilege>
+ <D:description xml:lang="en">
+ Write any object
+ </D:description>
+ <D:supported-privilege>
+ <D:privilege><D:write-acl/></D:privilege>
+ <D:description xml:lang="en">
+
+
+
+Clemm, et al. Standards Track [Page 20]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Write ACL
+ </D:description>
+ <D:abstract/>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:write-properties/></D:privilege>
+ <D:description xml:lang="en">
+ Write properties
+ </D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:write-content/></D:privilege>
+ <D:description xml:lang="en">
+ Write resource content
+ </D:description>
+ </D:supported-privilege>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:unlock/></D:privilege>
+ <D:description xml:lang="en">
+ Unlock resource
+ </D:description>
+ </D:supported-privilege>
+ </D:supported-privilege>
+ </D:supported-privilege-set>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+5.4. DAV:current-user-privilege-set
+
+ DAV:current-user-privilege-set is a protected property containing the
+ exact set of privileges (as computed by the server) granted to the
+ currently authenticated HTTP user. Aggregate privileges and their
+ contained privileges are listed. A user-agent can use the value of
+ this property to adjust its user interface to make actions
+ inaccessible (e.g., by graying out a menu item or button) for which
+ the current principal does not have permission. This property is
+ also useful for determining what operations the current principal can
+ perform, without having to actually execute an operation.
+
+ <!ELEMENT current-user-privilege-set (privilege*)>
+ <!ELEMENT privilege ANY>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 21]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ If the current user is granted a specific privilege, that privilege
+ must belong to the set of privileges that may be set on this
+ resource. Therefore, each element in the DAV:current-user-
+ privilege-set property MUST identify a non-abstract privilege from
+ the DAV:supported-privilege-set property.
+
+5.4.1. Example: Retrieving the User's Current Set of Assigned
+ Privileges
+
+ Continuing the example from Section 5.3.1, this example shows a
+ client requesting the DAV:current-user-privilege-set property from
+ the resource with URL http://www.example.com/papers/. The username
+ of the principal making the request is "khare", and Digest
+ authentication is used in the request. The principal with username
+ "khare" has been granted the DAV:read privilege. Since the DAV:read
+ privilege contains the DAV:read-acl and DAV:read-current-user-
+ privilege-set privileges (see Section 5.3.1), the principal with
+ username "khare" can read the ACL property, and the DAV:current-
+ user-privilege-set property. However, the DAV:all, DAV:read-acl,
+ DAV:write-acl and DAV:read-current-user-privilege-set privileges are
+ not listed in the value of DAV:current-user-privilege-set, since (for
+ this example) they are abstract privileges. DAV:write is not listed
+ since the principal with username "khare" is not listed in an ACE
+ granting that principal write permission.
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="khare",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:current-user-privilege-set/>
+ </D:prop>
+ </D:propfind>
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 22]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:current-user-privilege-set>
+ <D:privilege><D:read/></D:privilege>
+ </D:current-user-privilege-set>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+5.5. DAV:acl
+
+ This is a protected property that specifies the list of access
+ control entries (ACEs), which define what principals are to get what
+ privileges for this resource.
+
+ <!ELEMENT acl (ace*) >
+
+ Each DAV:ace element specifies the set of privileges to be either
+ granted or denied to a single principal. If the DAV:acl property is
+ empty, no principal is granted any privilege.
+
+ <!ELEMENT ace ((principal | invert), (grant|deny), protected?,
+ inherited?)>
+
+5.5.1. ACE Principal
+
+ The DAV:principal element identifies the principal to which this ACE
+ applies.
+
+ <!ELEMENT principal (href | all | authenticated | unauthenticated
+ | property | self)>
+
+ The current user matches DAV:href only if that user is authenticated
+ as being (or being a member of) the principal identified by the URL
+ contained by that DAV:href.
+
+
+
+
+Clemm, et al. Standards Track [Page 23]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The current user always matches DAV:all.
+
+ <!ELEMENT all EMPTY>
+
+ The current user matches DAV:authenticated only if authenticated.
+
+ <!ELEMENT authenticated EMPTY>
+
+ The current user matches DAV:unauthenticated only if not
+ authenticated.
+
+ <!ELEMENT unauthenticated EMPTY>
+
+ DAV:all is the union of DAV:authenticated, and DAV:unauthenticated.
+ For a given request, the user matches either DAV:authenticated, or
+ DAV:unauthenticated, but not both (that is, DAV:authenticated and
+ DAV:unauthenticated are disjoint sets).
+
+ The current user matches a DAV:property principal in a DAV:acl
+ property of a resource only if the value of the identified property
+ of that resource contains at most one DAV:href XML element, the URI
+ value of DAV:href identifies a principal, and the current user is
+ authenticated as being (or being a member of) that principal. For
+ example, if the DAV:property element contained <DAV:owner/>, the
+ current user would match the DAV:property principal only if the
+ current user is authenticated as matching the principal identified by
+ the DAV:owner property of the resource.
+
+ <!ELEMENT property ANY>
+
+ The current user matches DAV:self in a DAV:acl property of the
+ resource only if that resource is a principal and that principal
+ matches the current user or, if the principal is a group, a member of
+ that group matches the current user.
+
+ <!ELEMENT self EMPTY>
+
+ Some servers may support ACEs applying to those users NOT matching
+ the current principal, e.g., all users not in a particular group.
+ This can be done by wrapping the DAV:principal element with
+ DAV:invert.
+
+ <!ELEMENT invert principal>
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 24]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.5.2. ACE Grant and Deny
+
+ Each DAV:grant or DAV:deny element specifies the set of privileges to
+ be either granted or denied to the specified principal. A DAV:grant
+ or DAV:deny element of the DAV:acl of a resource MUST only contain
+ non-abstract elements specified in the DAV:supported-privilege-set of
+ that resource.
+
+ <!ELEMENT grant (privilege+)>
+ <!ELEMENT deny (privilege+)>
+ <!ELEMENT privilege ANY>
+
+5.5.3. ACE Protection
+
+ A server indicates an ACE is protected by including the DAV:protected
+ element in the ACE. If the ACL of a resource contains an ACE with a
+ DAV:protected element, an attempt to remove that ACE from the ACL
+ MUST fail.
+
+ <!ELEMENT protected EMPTY>
+
+5.5.4. ACE Inheritance
+
+ The presence of a DAV:inherited element indicates that this ACE is
+ inherited from another resource that is identified by the URL
+ contained in a DAV:href element. An inherited ACE cannot be modified
+ directly, but instead the ACL on the resource from which it is
+ inherited must be modified.
+
+ Note that ACE inheritance is not the same as ACL initialization. ACL
+ initialization defines the ACL that a newly created resource will use
+ (if not specified). ACE inheritance refers to an ACE that is
+ logically shared - where an update to the resource containing an ACE
+ will affect the ACE of each resource that inherits that ACE. The
+ method by which ACLs are initialized or by which ACEs are inherited
+ is not defined by this document.
+
+ <!ELEMENT inherited (href)>
+
+5.5.5. Example: Retrieving a Resource's Access Control List
+
+ Continuing the example from Sections 5.3.1 and 5.4.1, this example
+ shows a client requesting the DAV:acl property from the resource with
+ URL http://www.example.com/papers/. There are two ACEs defined in
+ this ACL:
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 25]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ ACE #1: The group identified by URL http://www.example.com/acl/
+ groups/maintainers (the group of site maintainers) is granted
+ DAV:write privilege. Since (for this example) DAV:write contains the
+ DAV:write-acl privilege (see Section 5.3.1), this means the
+ "maintainers" group can also modify the access control list.
+
+ ACE #2: All principals (DAV:all) are granted the DAV:read privilege.
+ Since (for this example) DAV:read contains DAV:read-acl and
+ DAV:read-current-user-privilege-set, this means all users (including
+ all members of the "maintainers" group) can read the DAV:acl property
+ and the DAV:current-user-privilege-set property.
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="masinter",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:acl/>
+ </D:prop>
+ </D:propfind>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:acl>
+ <D:ace>
+ <D:principal>
+ <D:href
+ >http://www.example.com/acl/groups/maintainers</D:href>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:write/></D:privilege>
+
+
+
+Clemm, et al. Standards Track [Page 26]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ </D:grant>
+ </D:ace>
+ <D:ace>
+ <D:principal>
+ <D:all/>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ </D:grant>
+ </D:ace>
+ </D:acl>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+5.6. DAV:acl-restrictions
+
+ This protected property defines the types of ACLs supported by this
+ server, to avoid clients needlessly getting errors. When a client
+ tries to set an ACL via the ACL method, the server may reject the
+ attempt to set the ACL as specified. The following properties
+ indicate the restrictions the client must observe before setting an
+ ACL:
+
+ <grant-only> Deny ACEs are not supported
+
+ <no-invert> Inverted ACEs are not supported
+
+ <deny-before-grant> All deny ACEs must occur before any grant ACEs
+
+ <required-principal> Indicates which principals are required to be
+ present
+
+
+ <!ELEMENT acl-restrictions (grant-only?, no-invert?,
+ deny-before-grant?,
+ required-principal?)>
+
+5.6.1. DAV:grant-only
+
+ This element indicates that ACEs with deny clauses are not allowed.
+
+ <!ELEMENT grant-only EMPTY>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 27]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.6.2. DAV:no-invert ACE Constraint
+
+ This element indicates that ACEs with the <invert> element are not
+ allowed.
+
+ <!ELEMENT no-invert EMPTY>
+
+5.6.3. DAV:deny-before-grant
+
+ This element indicates that all deny ACEs must precede all grant
+ ACEs.
+
+ <!ELEMENT deny-before-grant EMPTY>
+
+5.6.4. Required Principals
+
+ The required principal elements identify which principals must have
+ an ACE defined in the ACL.
+
+ <!ELEMENT required-principal
+ (all? | authenticated? | unauthenticated? | self? | href* |
+ property*)>
+
+ For example, the following element requires that the ACL contain a
+
+ DAV:owner property ACE:
+
+ <D:required-principal xmlns:D="DAV:">
+ <D:property><D:owner/></D:property>
+ </D:required-principal>
+
+5.6.5. Example: Retrieving DAV:acl-restrictions
+
+ In this example, the client requests the value of the DAV:acl-
+ restrictions property. Digest authentication provides credentials
+ for the principal operating the client.
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="srcarter",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+
+
+
+Clemm, et al. Standards Track [Page 28]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:acl-restrictions/>
+ </D:prop>
+ </D:propfind>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:acl-restrictions>
+ <D:grant-only/>
+ <D:required-principal>
+ <D:all/>
+ </D:required-principal>
+ </D:acl-restrictions>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+5.7. DAV:inherited-acl-set
+
+ This protected property contains a set of URLs that identify other
+ resources that also control the access to this resource. To have a
+ privilege on a resource, not only must the ACL on that resource
+ (specified in the DAV:acl property of that resource) grant the
+ privilege, but so must the ACL of each resource identified in the
+ DAV:inherited-acl-set property of that resource. Effectively, the
+ privileges granted by the current ACL are ANDed with the privileges
+ granted by each inherited ACL.
+
+ <!ELEMENT inherited-acl-set (href*)>
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 29]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.8. DAV:principal-collection-set
+
+ This protected property of a resource contains a set of URLs that
+ identify the root collections that contain the principals that are
+ available on the server that implements this resource. A WebDAV
+ Access Control Protocol user agent could use the contents of
+ DAV:principal-collection-set to retrieve the DAV:displayname property
+ (specified in Section 13.2 of [RFC2518]) of all principals on that
+ server, thereby yielding human-readable names for each principal that
+ could be displayed in a user interface.
+
+ <!ELEMENT principal-collection-set (href*)>
+
+ Since different servers can control different parts of the URL
+ namespace, different resources on the same host MAY have different
+ DAV:principal-collection-set values. The collections specified in
+ the DAV:principal-collection-set MAY be located on different hosts
+ from the resource. The URLs in DAV:principal-collection-set SHOULD be
+ http or https scheme URLs. For security and scalability reasons, a
+ server MAY report only a subset of the entire set of known principal
+ collections, and therefore clients should not assume they have
+ retrieved an exhaustive listing. Additionally, a server MAY elect to
+ report none of the principal collections it knows about, in which
+ case the property value would be empty.
+
+ The value of DAV:principal-collection-set gives the scope of the
+ DAV:principal-property-search REPORT (defined in Section 9.4).
+ Clients use the DAV:principal-property-search REPORT to populate
+ their user interface with a list of principals. Therefore, servers
+ that limit a client's ability to obtain principal information will
+ interfere with the client's ability to manipulate access control
+ lists, due to the difficulty of getting the URL of a principal for
+ use in an ACE.
+
+5.8.1. Example: Retrieving DAV:principal-collection-set
+
+ In this example, the client requests the value of the DAV:principal-
+ collection-set property on the collection resource identified by URL
+ http://www.example.com/papers/. The property contains the two URLs,
+ http://www.example.com/acl/users/ and http://
+ www.example.com/acl/groups/, both wrapped in DAV:href XML elements.
+ Digest authentication provides credentials for the principal
+ operating the client.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 30]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The client might reasonably follow this request with two separate
+ PROPFIND requests to retrieve the DAV:displayname property of the
+ members of the two collections (/acl/users and /acl/groups). This
+ information could be used when displaying a user interface for
+ creating access control entries.
+
+ >> Request <<
+
+ PROPFIND /papers/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="yarong",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:principal-collection-set/>
+ </D:prop>
+ </D:propfind>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/papers/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:principal-collection-set>
+ <D:href>http://www.example.com/acl/users/</D:href>
+ <D:href>http://www.example.com/acl/groups/</D:href>
+ </D:principal-collection-set>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 31]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+5.9. Example: PROPFIND to retrieve access control properties
+
+ The following example shows how access control information can be
+ retrieved by using the PROPFIND method to fetch the values of the
+ DAV:owner, DAV:supported-privilege-set, DAV:current-user-privilege-
+ set, and DAV:acl properties.
+
+ >> Request <<
+
+ PROPFIND /top/container/ HTTP/1.1
+ Host: www.example.com
+ Content-type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Depth: 0
+ Authorization: Digest username="ejw",
+ realm="users at example.com", nonce="...",
+ uri="/top/container/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:propfind xmlns:D="DAV:">
+ <D:prop>
+ <D:owner/>
+ <D:supported-privilege-set/>
+ <D:current-user-privilege-set/>
+ <D:acl/>
+ </D:prop>
+ </D:propfind>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:"
+ xmlns:A="http://www.example.com/acl/">
+ <D:response>
+ <D:href>http://www.example.com/top/container/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:owner>
+ <D:href>http://www.example.com/users/gclemm</D:href>
+ </D:owner>
+ <D:supported-privilege-set>
+ <D:supported-privilege>
+ <D:privilege><D:all/></D:privilege>
+ <D:abstract/>
+
+
+
+Clemm, et al. Standards Track [Page 32]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:description xml:lang="en">
+ Any operation
+ </D:description>
+ <D:supported-privilege>
+ <D:privilege><D:read/></D:privilege>
+ <D:description xml:lang="en">
+ Read any object
+ </D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:write/></D:privilege>
+ <D:abstract/>
+ <D:description xml:lang="en">
+ Write any object
+ </D:description>
+ <D:supported-privilege>
+ <D:privilege><A:create/></D:privilege>
+ <D:description xml:lang="en">
+ Create an object
+ </D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><A:update/></D:privilege>
+ <D:description xml:lang="en">
+ Update an object
+ </D:description>
+ </D:supported-privilege>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><A:delete/></D:privilege>
+ <D:description xml:lang="en">
+ Delete an object
+ </D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:read-acl/></D:privilege>
+ <D:description xml:lang="en">
+ Read the ACL
+ </D:description>
+ </D:supported-privilege>
+ <D:supported-privilege>
+ <D:privilege><D:write-acl/></D:privilege>
+ <D:description xml:lang="en">
+ Write the ACL
+ </D:description>
+ </D:supported-privilege>
+ </D:supported-privilege>
+ </D:supported-privilege-set>
+
+
+
+Clemm, et al. Standards Track [Page 33]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:current-user-privilege-set>
+ <D:privilege><D:read/></D:privilege>
+ <D:privilege><D:read-acl/></D:privilege>
+ </D:current-user-privilege-set>
+ <D:acl>
+ <D:ace>
+ <D:principal>
+ <D:href>http://www.example.com/users/esedlar</D:href>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ <D:privilege><D:write/></D:privilege>
+ <D:privilege><D:read-acl/></D:privilege>
+ </D:grant>
+ </D:ace>
+ <D:ace>
+ <D:principal>
+ <D:href>http://www.example.com/groups/mrktng</D:href>
+ </D:principal>
+ <D:deny>
+ <D:privilege><D:read/></D:privilege>
+ </D:deny>
+ </D:ace>
+ <D:ace>
+ <D:principal>
+ <D:property><D:owner/></D:property>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read-acl/></D:privilege>
+ <D:privilege><D:write-acl/></D:privilege>
+ </D:grant>
+ </D:ace>
+ <D:ace>
+ <D:principal><D:all/></D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ </D:grant>
+ <D:inherited>
+ <D:href>http://www.example.com/top</D:href>
+ </D:inherited>
+ </D:ace>
+ </D:acl>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+
+
+
+Clemm, et al. Standards Track [Page 34]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The value of the DAV:owner property is a single DAV:href XML element
+ containing the URL of the principal that owns this resource.
+
+ The value of the DAV:supported-privilege-set property is a tree of
+ supported privileges (using "[XML Namespace , localname]" to identify
+ each privilege):
+
+ [DAV:, all] (aggregate, abstract)
+ |
+ +-- [DAV:, read]
+ +-- [DAV:, write] (aggregate, abstract)
+ |
+ +-- [http://www.example.com/acl, create]
+ +-- [http://www.example.com/acl, update]
+ +-- [http://www.example.com/acl, delete]
+ +-- [DAV:, read-acl]
+ +-- [DAV:, write-acl]
+
+ The DAV:current-user-privilege-set property contains two privileges,
+ DAV:read, and DAV:read-acl. This indicates that the current
+ authenticated user only has the ability to read the resource, and
+ read the DAV:acl property on the resource. The DAV:acl property
+ contains a set of four ACEs:
+
+ ACE #1: The principal identified by the URL http://www.example.com/
+ users/esedlar is granted the DAV:read, DAV:write, and DAV:read-acl
+ privileges.
+
+ ACE #2: The principals identified by the URL http://www.example.com/
+ groups/mrktng are denied the DAV:read privilege. In this example,
+ the principal URL identifies a group.
+
+ ACE #3: In this ACE, the principal is a property principal,
+ specifically the DAV:owner property. When evaluating this ACE, the
+ value of the DAV:owner property is retrieved, and is examined to see
+ if it contains a DAV:href XML element. If so, the URL within the
+ DAV:href element is read, and identifies a principal. In this ACE,
+ the owner is granted DAV:read-acl, and DAV:write-acl privileges.
+
+ ACE #4: This ACE grants the DAV:all principal (all users) the
+ DAV:read privilege. This ACE is inherited from the resource http://
+ www.example.com/top, the parent collection of this resource.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 35]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+6. ACL Evaluation
+
+ WebDAV ACLs are evaluated in similar manner as ACLs on Windows NT and
+ in NFSv4 [RFC3530]). An ACL is evaluated to determine whether or not
+ access will be granted for a WebDAV request. ACEs are maintained in
+ a particular order, and are evaluated until all of the permissions
+ required by the current request have been granted, at which point the
+ ACL evaluation is terminated and access is granted. If, during ACL
+ evaluation, a <deny> ACE (matching the current user) is encountered
+ for a privilege which has not yet been granted, the ACL evaluation is
+ terminated and access is denied. Failure to have all required
+ privileges granted results in access being denied.
+
+ Note that the semantics of many other existing ACL systems may be
+ represented via this mechanism, by mixing deny and grant ACEs. For
+ example, consider the standard "rwx" privilege scheme used by UNIX.
+ In this scheme, if the current user is the owner of the file, access
+ is granted if the corresponding privilege bit is set and denied if
+ not set, regardless of the permissions set on the file's group and
+ for the world. An ACL for UNIX permissions of "r--rw-r--" might be
+ constructed like:
+
+ <D:acl>
+ <D:ace>
+ <D:principal>
+ <D:property><D:owner/></D:property>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ </D:grant>
+ </D:ace>
+ <D:ace>
+ <D:principal>
+ <D:property><D:owner/></D:property>
+ </D:principal>
+ <D:deny>
+ <D:privilege><D:all/></D:privilege>
+ </D:deny>
+ </D:ace>
+ <D:ace>
+ <D:principal>
+ <D:property><D:group/></D:property>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ <D:privilege><D:write/></D:privilege>
+ </D:grant>
+ </D:ace>
+
+
+
+Clemm, et al. Standards Track [Page 36]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:ace>
+ <D:principal>
+ <D:property><D:group/></D:property>
+ </D:principal>
+ <D:deny>
+ <D:privilege><D:all/></D:privilege>
+ </D:deny>
+ </D:ace>
+ <D:ace>
+ <D:principal><D:all></D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ </D:grant>
+ </D:ace>
+ </D:acl>
+
+ and the <acl-restrictions> would be defined as:
+
+ <D:no-invert/>
+ <D:required-principal>
+ <D:all/>
+ <D:property><D:owner/></D:property>
+ <D:property><D:group/><D:group/>
+ </D:required-principal>
+
+ Note that the client can still get errors from a UNIX server in spite
+ of obeying the <acl-restrictions>, including <D:allowed-principal>
+ (adding an ACE specifying a principal other than the ones in the ACL
+ above) or <D:ace-conflict> (by trying to reorder the ACEs in the
+ example above), as these particular implementation semantics are too
+ complex to be captured with the simple (but general) declarative
+ restrictions.
+
+7. Access Control and existing methods
+
+ This section defines the impact of access control functionality on
+ existing methods.
+
+7.1. Any HTTP method
+
+7.1.1. Error Handling
+
+ The WebDAV ACL mechanism requires the usage of HTTP method
+ "preconditions" as described in section 1.6 of RFC3253 for ALL HTTP
+ methods. All HTTP methods have an additional precondition called
+ DAV:need-privileges. If an HTTP method fails due to insufficient
+ privileges, the response body to the "403 Forbidden" error MUST
+ contain the <DAV:error> element, which in turn contains the
+
+
+
+Clemm, et al. Standards Track [Page 37]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <DAV:need-privileges> element, which contains one or more
+ <DAV:resource> elements indicating which resource had insufficient
+ privileges, and what the lacking privileges were:
+
+ <!ELEMENT need-privileges (resource)* >
+ <!ELEMENT resource ( href , privilege ) >
+
+ Since some methods require multiple permissions on multiple
+ resources, this information is needed to resolve any ambiguity.
+ There is no requirement that all privilege violations be reported -
+ for implementation reasons, some servers may only report the first
+ privilege violation. For example:
+
+ >> Request <<
+
+ MOVE /a/b/ HTTP/1.1
+ Host: www.example.com
+ Destination: http://www.example.com/c/d
+
+ >> Response <<
+
+ HTTP/1.1 403 Forbidden
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <D:error xmlns:D="DAV:">
+ <D:need-privileges>
+ <D:resource>
+ <D:href>/a</D:href>
+ <D:privilege><D:unbind/></D:privilege>
+ </D:resource>
+ <D:resource>
+ <D:href>/c</D:href>
+ <D:privilege><D:bind/></D:privilege>
+ </D:resource>
+ </D:need-privileges>
+ </D:error>
+
+7.2. OPTIONS
+
+ If the server supports access control, it MUST return "access-
+ control" as a field in the DAV response header from an OPTIONS
+ request on any resource implemented by that server. A value of
+ "access-control" in the DAV header MUST indicate that the server
+ supports all MUST level requirements and REQUIRED features specified
+ in this document.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 38]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+7.2.1. Example - OPTIONS
+
+ >> Request <<
+
+ OPTIONS /foo.html HTTP/1.1
+ Host: www.example.com
+ Content-Length: 0
+
+ >> Response <<
+
+ HTTP/1.1 200 OK
+ DAV: 1, 2, access-control
+ Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, ACL
+
+ In this example, the OPTIONS response indicates that the server
+ supports access control and that /foo.html can have its access
+ control list modified by the ACL method.
+
+7.3. MOVE
+
+ When a resource is moved from one location to another due to a MOVE
+ request, the non-inherited and non-protected ACEs in the DAV:acl
+ property of the resource MUST NOT be modified, or the MOVE request
+ fails. Handling of inherited and protected ACEs is intentionally
+ undefined to give server implementations flexibility in how they
+ implement ACE inheritance and protection.
+
+7.4. COPY
+
+ The DAV:acl property on the resource at the destination of a COPY
+ MUST be the same as if the resource was created by an individual
+ resource creation request (e.g., MKCOL, PUT). Clients wishing to
+ preserve the DAV:acl property across a copy need to read the DAV:acl
+ property prior to the COPY, then perform an ACL operation on the new
+ resource at the destination to restore, insofar as this is possible,
+ the original access control list.
+
+7.5. LOCK
+
+ A lock on a resource ensures that only the lock owner can modify ACEs
+ that are not inherited and not protected (these are the only ACEs
+ that a client can modify with an ACL request). A lock does not
+ protect inherited or protected ACEs, since a client cannot modify
+ them with an ACL request on that resource.
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 39]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+8. Access Control Methods
+
+8.1. ACL
+
+ The ACL method modifies the access control list (which can be read
+ via the DAV:acl property) of a resource. Specifically, the ACL
+ method only permits modification to ACEs that are not inherited, and
+ are not protected. An ACL method invocation modifies all non-
+ inherited and non-protected ACEs in a resource's access control list
+ to exactly match the ACEs contained within in the DAV:acl XML element
+ (specified in Section 5.5) of the request body. An ACL request body
+ MUST contain only one DAV:acl XML element. Unless the non-inherited
+ and non-protected ACEs of the DAV:acl property of the resource can be
+ updated to be exactly the value specified in the ACL request, the ACL
+ request MUST fail.
+
+ It is possible that the ACEs visible to the current user in the
+ DAV:acl property may only be a portion of the complete set of ACEs on
+ that resource. If this is the case, an ACL request only modifies the
+ set of ACEs visible to the current user, and does not affect any
+ non-visible ACE.
+
+ In order to avoid overwriting DAV:acl changes by another client, a
+ client SHOULD acquire a WebDAV lock on the resource before retrieving
+ the DAV:acl property of a resource that it intends on updating.
+
+ Implementation Note: Two common operations are to add or remove an
+ ACE from an existing access control list. To accomplish this, a
+ client uses the PROPFIND method to retrieve the value of the
+ DAV:acl property, then parses the returned access control list to
+ remove all inherited and protected ACEs (these ACEs are tagged
+ with the DAV:inherited and DAV:protected XML elements). In the
+ remaining set of non-inherited, non-protected ACEs, the client can
+ add or remove one or more ACEs before submitting the final ACE set
+ in the request body of the ACL method.
+
+8.1.1. ACL Preconditions
+
+ An implementation MUST enforce the following constraints on an ACL
+ request. If the constraint is violated, a 403 (Forbidden) or 409
+ (Conflict) response MUST be returned and the indicated XML element
+ MUST be returned as a child of a top level DAV:error element in an
+ XML response body.
+
+ Though these status elements are generally expressed as empty XML
+ elements (and are defined as EMPTY in the DTD), implementations MAY
+ return additional descriptive XML elements as children of the status
+
+
+
+
+Clemm, et al. Standards Track [Page 40]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ element. Clients MUST be able to accept children of these status
+ elements. Clients that do not understand the additional XML elements
+ should ignore them.
+
+ (DAV:no-ace-conflict): The ACEs submitted in the ACL request MUST NOT
+ conflict with each other. This is a catchall error code indicating
+ that an implementation-specific ACL restriction has been violated.
+
+ (DAV:no-protected-ace-conflict): The ACEs submitted in the ACL
+ request MUST NOT conflict with the protected ACEs on the resource.
+ For example, if the resource has a protected ACE granting DAV:write
+ to a given principal, then it would not be consistent if the ACL
+ request submitted an ACE denying DAV:write to the same principal.
+
+ (DAV:no-inherited-ace-conflict): The ACEs submitted in the ACL
+ request MUST NOT conflict with the inherited ACEs on the resource.
+ For example, if the resource inherits an ACE from its parent
+ collection granting DAV:write to a given principal, then it would not
+ be consistent if the ACL request submitted an ACE denying DAV:write
+ to the same principal. Note that reporting of this error will be
+ implementation-dependent. Implementations MUST either report this
+ error or allow the ACE to be set, and then let normal ACE evaluation
+ rules determine whether the new ACE has any impact on the privileges
+ available to a specific principal.
+
+ (DAV:limited-number-of-aces): The number of ACEs submitted in the ACL
+ request MUST NOT exceed the number of ACEs allowed on that resource.
+ However, ACL-compliant servers MUST support at least one ACE granting
+ privileges to a single principal, and one ACE granting privileges to
+ a group.
+
+ (DAV:deny-before-grant): All non-inherited deny ACEs MUST precede all
+ non-inherited grant ACEs.
+
+ (DAV:grant-only): The ACEs submitted in the ACL request MUST NOT
+ include a deny ACE. This precondition applies only when the ACL
+ restrictions of the resource include the DAV:grant-only constraint
+ (defined in Section 5.6.1).
+
+ (DAV:no-invert): The ACL request MUST NOT include a DAV:invert
+ element. This precondition applies only when the ACL semantics of
+ the resource includes the DAV:no-invert constraint (defined in
+ Section 5.6.2).
+
+ (DAV:no-abstract): The ACL request MUST NOT attempt to grant or deny
+ an abstract privilege (see Section 5.3).
+
+
+
+
+
+Clemm, et al. Standards Track [Page 41]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ (DAV:not-supported-privilege): The ACEs submitted in the ACL request
+ MUST be supported by the resource.
+
+ (DAV:missing-required-principal): The result of the ACL request MUST
+ have at least one ACE for each principal identified in a
+ DAV:required-principal XML element in the ACL semantics of that
+ resource (see Section 5.5).
+
+ (DAV:recognized-principal): Every principal URL in the ACL request
+ MUST identify a principal resource.
+
+ (DAV:allowed-principal): The principals specified in the ACEs
+ submitted in the ACL request MUST be allowed as principals for the
+ resource. For example, a server where only authenticated principals
+ can access resources would not allow the DAV:all or
+ DAV:unauthenticated principals to be used in an ACE, since these
+ would allow unauthenticated access to resources.
+
+8.1.2. Example: the ACL method
+
+ In the following example, user "fielding", authenticated by
+ information in the Authorization header, grants the principal
+ identified by the URL http://www.example.com/users/esedlar (i.e., the
+ user "esedlar") read and write privileges, grants the owner of the
+ resource read-acl and write-acl privileges, and grants everyone read
+ privileges.
+
+ >> Request <<
+
+ ACL /top/container/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="fielding",
+ realm="users at example.com", nonce="...",
+ uri="/top/container/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:acl xmlns:D="DAV:">
+ <D:ace>
+ <D:principal>
+ <D:href>http://www.example.com/users/esedlar</D:href>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ <D:privilege><D:write/></D:privilege>
+ </D:grant>
+ </D:ace>
+
+
+
+Clemm, et al. Standards Track [Page 42]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:ace>
+ <D:principal>
+ <D:property><D:owner/></D:property>
+ </D:principal>
+ <D:grant>
+ <D:privilege><D:read-acl/></D:privilege>
+ <D:privilege><D:write-acl/></D:privilege>
+ </D:grant>
+ </D:ace>
+ <D:ace>
+ <D:principal><D:all/></D:principal>
+ <D:grant>
+ <D:privilege><D:read/></D:privilege>
+ </D:grant>
+ </D:ace>
+ </D:acl>
+
+ >> Response <<
+
+ HTTP/1.1 200 OK
+
+8.1.3. Example: ACL method failure due to protected ACE conflict
+
+ In the following request, user "fielding", authenticated by
+ information in the Authorization header, attempts to deny the
+ principal identified by the URL http://www.example.com/users/esedlar
+ (i.e., the user "esedlar") write privileges. Prior to the request,
+ the DAV:acl property on the resource contained a protected ACE (see
+ Section 5.5.3) granting DAV:owner the DAV:read and DAV:write
+ privileges. The principal identified by URL http://www.example.com/
+ users/esedlar is the owner of the resource. The ACL method
+ invocation fails because the submitted ACE conflicts with the
+ protected ACE, thus violating the semantics of ACE protection.
+
+ >> Request <<
+
+ ACL /top/container/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="fielding",
+ realm="users at example.com", nonce="...",
+ uri="/top/container/", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:acl xmlns:D="DAV:">
+ <D:ace>
+ <D:principal>
+
+
+
+Clemm, et al. Standards Track [Page 43]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:href>http://www.example.com/users/esedlar</D:href>
+ </D:principal>
+ <D:deny>
+ <D:privilege><D:write/></D:privilege>
+ </D:deny>
+ </D:ace>
+ </D:acl>
+
+ >> Response <<
+
+ HTTP/1.1 403 Forbidden
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:no-protected-ace-conflict/>
+ </D:error>
+
+8.1.4. Example: ACL method failure due to an inherited ACE conflict
+
+ In the following request, user "ejw", authenticated by information in
+ the Authorization header, tries to change the access control list on
+ the resource http://www.example.com/top/index.html. This resource
+ has two inherited ACEs.
+
+ Inherited ACE #1 grants the principal identified by URL http://
+ www.example.com/users/ejw (i.e., the user "ejw") http://
+ www.example.com/privs/write-all and DAV:read-acl privileges. On this
+ server, http://www.example.com/privs/write-all is an aggregate
+ privilege containing DAV:write, and DAV:write-acl.
+
+ Inherited ACE #2 grants principal DAV:all the DAV:read privilege.
+
+ The request attempts to set a (non-inherited) ACE, denying the
+ principal identified by the URL http://www.example.com/users/ejw
+ (i.e., the user "ejw") DAV:write permission. This conflicts with
+ inherited ACE #1. Note that the decision to report an inherited ACE
+ conflict is specific to this server implementation. Another server
+ implementation could have allowed the new ACE to be set, and then
+ used normal ACE evaluation rules to determine whether the new ACE has
+ any impact on the privileges available to a principal.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 44]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Request <<
+
+ ACL /top/index.html HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ejw",
+ realm="users at example.com", nonce="...",
+ uri="/top/index.html", response="...", opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:acl xmlns:D="DAV:" xmlns:F="http://www.example.com/privs/">
+ <D:ace>
+ <D:principal>
+ <D:href>http://www.example.com/users/ejw</D:href>
+ </D:principal>
+ <D:grant><D:write/></D:grant>
+ </D:ace>
+ </D:acl>
+
+ >> Response <<
+
+ HTTP/1.1 403 Forbidden
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:error xmlns:D="DAV:">
+ <D:no-inherited-ace-conflict/>
+ </D:error>
+
+8.1.5. Example: ACL method failure due to an attempt to set grant and
+ deny in a single ACE
+
+ In this example, user "ygoland", authenticated by information in the
+ Authorization header, tries to change the access control list on the
+ resource http://www.example.com/diamond/engagement-ring.gif. The ACL
+ request includes a single, syntactically and semantically incorrect
+ ACE, which attempts to grant the group identified by the URL http://
+ www.example.com/users/friends DAV:read privilege and deny the
+ principal identified by URL http://www.example.com/users/ygoland-so
+ (i.e., the user "ygoland-so") DAV:read privilege. However, it is
+ illegal to have multiple principal elements, as well as both a grant
+ and deny element in the same ACE, so the request fails due to poor
+ syntax.
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 45]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Request <<
+
+ ACL /diamond/engagement-ring.gif HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Authorization: Digest username="ygoland",
+ realm="users at example.com", nonce="...",
+ uri="/diamond/engagement-ring.gif", response="...",
+ opaque="..."
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:acl xmlns:D="DAV:">
+ <D:ace>
+ <D:principal>
+ <D:href>http://www.example.com/users/friends</D:href>
+ </D:principal>
+ <D:grant><D:read/></D:grant>
+ <D:principal>
+ <D:href>http://www.example.com/users/ygoland-so</D:href>
+ </D:principal>
+ <D:deny><D:read/></D:deny>
+ </D:ace>
+ </D:acl>
+
+ >> Response <<
+
+ HTTP/1.1 400 Bad Request
+ Content-Length: 0
+
+ Note that if the request had been divided into two ACEs, one to
+ grant, and one to deny, the request would have been syntactically
+ well formed.
+
+9. Access Control Reports
+
+9.1. REPORT Method
+
+ The REPORT method (defined in Section 3.6 of [RFC3253]) provides an
+ extensible mechanism for obtaining information about a resource.
+ Unlike the PROPFIND method, which returns the value of one or more
+ named properties, the REPORT method can involve more complex
+ processing. REPORT is valuable in cases where the server has access
+ to all of the information needed to perform the complex request (such
+ as a query), and where it would require multiple requests for the
+ client to retrieve the information needed to perform the same
+ request.
+
+
+
+
+Clemm, et al. Standards Track [Page 46]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ A server that supports the WebDAV Access Control Protocol MUST
+ support the DAV:expand-property report (defined in Section 3.8 of
+ [RFC3253]).
+
+9.2. DAV:acl-principal-prop-set Report
+
+ The DAV:acl-principal-prop-set report returns, for all principals in
+ the DAV:acl property (of the Request-URI) that are identified by
+ http(s) URLs or by a DAV:property principal, the value of the
+ properties specified in the REPORT request body. In the case where a
+ principal URL appears multiple times, the DAV:acl-principal-prop-set
+ report MUST return the properties for that principal only once.
+ Support for this report is REQUIRED.
+
+ One expected use of this report is to retrieve the human readable
+ name (found in the DAV:displayname property) of each principal found
+ in an ACL. This is useful for constructing user interfaces that show
+ each ACE in a human readable form.
+
+ Marshalling
+
+ The request body MUST be a DAV:acl-principal-prop-set XML element.
+
+ <!ELEMENT acl-principal-prop-set ANY>
+ ANY value: a sequence of one or more elements, with at most one
+ DAV:prop element.
+ prop: see RFC 2518, Section 12.11
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0".
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element (i.e., the response uses the same
+ format as the response for PROPFIND). In the case where there are
+ no response elements, the returned multistatus XML element is
+ empty.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response body for a successful DAV:acl-principal-prop-set
+ REPORT request MUST contain a DAV:response element for each
+ principal identified by an http(s) URL listed in a DAV:principal
+ XML element of an ACE within the DAV:acl property of the resource
+ identified by the Request-URI.
+
+
+
+
+
+Clemm, et al. Standards Track [Page 47]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Postconditions:
+
+ (DAV:number-of-matches-within-limits): The number of matching
+ principals must fall within server-specific, predefined limits.
+ For example, this condition might be triggered if a search
+ specification would cause the return of an extremely large number
+ of responses.
+
+9.2.1. Example: DAV:acl-principal-prop-set Report
+
+ Resource http://www.example.com/index.html has an ACL with three
+ ACEs:
+
+ ACE #1: All principals (DAV:all) have DAV:read and DAV:read-current-
+ user-privilege-set access.
+
+ ACE #2: The principal identified by http://www.example.com/people/
+ gstein (the user "gstein") is granted DAV:write, DAV:write-acl,
+ DAV:read-acl privileges.
+
+ ACE #3: The group identified by http://www.example.com/groups/authors
+ (the "authors" group) is granted DAV:write and DAV:read-acl
+ privileges.
+
+ The following example shows a DAV:acl-principal-prop-set report
+ requesting the DAV:displayname property. It returns the value of
+ DAV:displayname for resources http://www.example.com/people/gstein
+ and http://www.example.com/groups/authors , but not for DAV:all,
+ since this is not an http(s) URL.
+
+ >> Request <<
+
+ REPORT /index.html HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Depth: 0
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:acl-principal-prop-set xmlns:D="DAV:">
+ <D:prop>
+ <D:displayname/>
+ </D:prop>
+ </D:acl-principal-prop-set>
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 48]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/people/gstein</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:displayname>Greg Stein</D:displayname>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://www.example.com/groups/authors</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:displayname>Site authors</D:displayname>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+9.3. DAV:principal-match REPORT
+
+ The DAV:principal-match REPORT is used to identify all members (at
+ any depth) of the collection identified by the Request-URI that are
+ principals and that match the current user. In particular, if the
+ collection contains principals, the report can be used to identify
+ all members of the collection that match the current user.
+ Alternatively, if the collection contains resources that have a
+ property that identifies a principal (e.g., DAV:owner), the report
+ can be used to identify all members of the collection whose property
+ identifies a principal that matches the current user. For example,
+ this report can return all of the resources in a collection hierarchy
+ that are owned by the current user. Support for this report is
+ REQUIRED.
+
+ Marshalling:
+
+ The request body MUST be a DAV:principal-match XML element.
+ <!ELEMENT principal-match ((principal-property | self), prop?)>
+ <!ELEMENT principal-property ANY>
+
+
+
+Clemm, et al. Standards Track [Page 49]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ ANY value: an element whose value identifies a property. The
+ expectation is the value of the named property typically contains
+ an href element that contains the URI of a principal
+ <!ELEMENT self EMPTY>
+ prop: see RFC 2518, Section 12.11
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0". The response body for
+ a successful request MUST be a DAV:multistatus XML element. In
+ the case where there are no response elements, the returned
+ multistatus XML element is empty.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response body for a successful DAV:principal-match REPORT
+ request MUST contain a DAV:response element for each member of the
+ collection that matches the current user. When the
+ DAV:principal-property element is used, a match occurs if the
+ current user is matched by the principal identified by the URI
+ found in the DAV:href element of the property identified by the
+ DAV:principal-property element. When the DAV:self element is used
+ in a DAV:principal-match report issued against a group, it matches
+ the group if a member identifies the same principal as the current
+ user.
+
+ If DAV:prop is specified in the request body, the properties
+ specified in the DAV:prop element MUST be reported in the
+ DAV:response elements.
+
+9.3.1. Example: DAV:principal-match REPORT
+
+ The following example identifies the members of the collection
+ identified by the URL http://www.example.com/doc that are owned by
+ the current user. The current user ("gclemm") is authenticated using
+ Digest authentication.
+
+ >> Request <<
+
+ REPORT /doc/ HTTP/1.1
+ Host: www.example.com
+ Authorization: Digest username="gclemm",
+ realm="users at example.com", nonce="...",
+ uri="/papers/", response="...", opaque="..."
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+ Depth: 0
+
+
+
+Clemm, et al. Standards Track [Page 50]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-match xmlns:D="DAV:">
+ <D:principal-property>
+ <D:owner/>
+ </D:principal-property>
+ </D:principal-match>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:">
+ <D:response>
+ <D:href>http://www.example.com/doc/foo.html</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ <D:response>
+ <D:href>http://www.example.com/doc/img/bar.gif</D:href>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:response>
+ </D:multistatus>
+
+9.4. DAV:principal-property-search REPORT
+
+ The DAV:principal-property-search REPORT performs a search for all
+ principals whose properties contain character data that matches the
+ search criteria specified in the request. One expected use of this
+ report is to discover the URL of a principal associated with a given
+ person or group by searching for them by name. This is done by
+ searching over DAV:displayname, which is defined on all principals.
+
+ The actual search method (exact matching vs. substring matching vs,
+ prefix-matching, case-sensitivity) deliberately is left to the server
+ implementation to allow implementation on a wide set of possible user
+ management systems. In cases where the implementation of
+ DAV:principal-property-search is not constrained by the semantics of
+ an underlying user management repository, preferred default semantics
+ are caseless substring matches.
+
+ For implementation efficiency, servers do not typically support
+ searching on all properties. A search requesting properties that are
+ not searchable for a particular principal will not match that
+ principal.
+
+ Support for the DAV:principal-property-search report is REQUIRED.
+
+
+
+Clemm, et al. Standards Track [Page 51]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Implementation Note: The value of a WebDAV property is a sequence
+ of well-formed XML, and hence can include any character in the
+ Unicode/ISO-10646 standard, that is, most known characters in
+ human languages. Due to the idiosyncrasies of case mapping across
+ human languages, implementation of case-insensitive matching is
+ non-trivial. Implementors of servers that do perform substring
+ matching are strongly encouraged to consult "The Unicode Standard"
+ [UNICODE4], especially Section 5.18, Subsection "Caseless
+ Matching", for guidance when implementing their case-insensitive
+ matching algorithms.
+
+ Implementation Note: Some implementations of this protocol will
+ use an LDAP repository for storage of principal metadata. The
+ schema describing each attribute (akin to a WebDAV property) in an
+ LDAP repository specifies whether it supports case-sensitive or
+ caseless searching. One of the benefits of leaving the search
+ method to the discretion of the server implementation is the
+ default LDAP attribute search behavior can be used when
+ implementing the DAV:principal-property-search report.
+
+ Marshalling:
+
+ The request body MUST be a DAV:principal-property-search XML
+ element containing a search specification and an optional list of
+ properties. For every principal that matches the search
+ specification, the response will contain the value of the
+ requested properties on that principal.
+
+ <!ELEMENT principal-property-search
+ ((property-search+), prop?, apply-to-principal-collection-set?) >
+
+ By default, the report searches all members (at any depth) of the
+ collection identified by the Request-URI. If DAV:apply-to-
+ principal-collection-set is specified in the request body, the
+ request is applied instead to each collection identified by the
+ DAV:principal-collection-set property of the resource identified
+ by the Request-URI.
+
+ The DAV:property-search element contains a prop element
+ enumerating the properties to be searched and a match element,
+ containing the search string.
+
+ <!ELEMENT property-search (prop, match) >
+ prop: see RFC 2518, Section 12.11
+
+ <!ELEMENT match #PCDATA >
+
+
+
+
+
+Clemm, et al. Standards Track [Page 52]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Multiple property-search elements or multiple elements within a
+ DAV:prop element will be interpreted with a logical AND.
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0".
+
+ The response body for a successful request MUST be a
+ DAV:multistatus XML element. In the case where there are no
+ response elements, the returned multistatus XML element is empty.
+
+ multistatus: see RFC 2518, Section 12.9
+
+ The response body for a successful DAV:principal-property-search
+ REPORT request MUST contain a DAV:response element for each
+ principal whose property values satisfy the search specification
+ given in DAV:principal-property-search.
+
+ If DAV:prop is specified in the request body, the properties
+ specified in the DAV:prop element MUST be reported in the
+ DAV:response elements.
+
+ Preconditions:
+
+ None
+
+ Postconditions:
+
+ (DAV:number-of-matches-within-limits): The number of matching
+ principals must fall within server-specific, predefined limits.
+ For example, this condition might be triggered if a search
+ specification would cause the return of an extremely large number
+ of responses.
+
+9.4.1. Matching
+
+ There are several cases to consider when matching strings. The
+ easiest case is when a property value is "simple" and has only
+ character information item content (see [REC-XML-INFOSET]). For
+ example, the search string "julian" would match the DAV:displayname
+ property with value "Julian Reschke". Note that the on-the-wire
+ marshaling of DAV:displayname in this case is:
+
+ <D:displayname xmlns:D="DAV:">Julian Reschke</D:displayname>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 53]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The name of the property is encoded into the XML element information
+ item, and the character information item content of the property is
+ "Julian Reschke".
+
+ A more complicated case occurs when properties have mixed content
+ (that is, compound values consisting of multiple child element items,
+ other types of information items, and character information item
+ content). Consider the property "aprop" in the namespace "http://
+ www.example.com/props/", marshaled as:
+
+ <W:aprop xmlns:W="http://www.example.com/props/">
+ {cdata 0}<W:elem1>{cdata 1}</W:elem1>
+ <W:elem2>{cdata 2}</W:elem2>{cdata 3}
+ </W:aprop>
+
+ In this case, matching is performed on each individual contiguous
+ sequence of character information items. In the example above, a
+ search string would be compared to the four following strings:
+
+ {cdata 0}
+ {cdata 1}
+ {cdata 2}
+ {cdata 3}
+
+ That is, four individual matches would be performed, one each for
+ {cdata 0}, {cdata 1}, {cdata 2}, and {cdata 3}.
+
+9.4.2. Example: successful DAV:principal-property-search REPORT
+
+ In this example, the client requests the principal URLs of all users
+ whose DAV:displayname property contains the substring "doE" and whose
+ "title" property in the namespace "http://BigCorp.com/ns/" (that is,
+ their professional title) contains "Sales". In addition, the client
+ requests five properties to be returned with the matching principals:
+
+ In the DAV: namespace: displayname
+
+ In the http://www.example.com/ns/ namespace: department, phone,
+ office, salary
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 54]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The response shows that two principal resources meet the search
+ specification, "John Doe" and "Zygdoebert Smith". The property
+ "salary" in namespace "http://www.example.com/ns/" is not returned,
+ since the principal making the request does not have sufficient
+ access permissions to read this property.
+
+ >> Request <<
+
+ REPORT /users/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset=utf-8
+ Content-Length: xxxx
+ Depth: 0
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-property-search xmlns:D="DAV:">
+ <D:property-search>
+ <D:prop>
+ <D:displayname/>
+ </D:prop>
+ <D:match>doE</D:match>
+ </D:property-search>
+ <D:property-search>
+ <D:prop xmlns:B="http://www.example.com/ns/">
+ <B:title/>
+ </D:prop>
+ <D:match>Sales</D:match>
+ </D:property-search>
+ <D:prop xmlns:B="http://www.example.com/ns/">
+ <D:displayname/>
+ <B:department/>
+ <B:phone/>
+ <B:office/>
+ <B:salary/>
+ </D:prop>
+ </D:principal-property-search>
+
+ >> Response <<
+
+ HTTP/1.1 207 Multi-Status
+ Content-Type: text/xml; charset=utf-8
+ Content-Length: xxxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:multistatus xmlns:D="DAV:" xmlns:B="http://BigCorp.com/ns/">
+ <D:response>
+ <D:href>http://www.example.com/users/jdoe</D:href>
+ <D:propstat>
+
+
+
+Clemm, et al. Standards Track [Page 55]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <D:prop>
+ <D:displayname>John Doe</D:displayname>
+ <B:department>Widget Sales</B:department>
+ <B:phone>234-4567</B:phone>
+ <B:office>209</B:office>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <B:salary/>
+ </D:prop>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>http://www.example.com/users/zsmith</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:displayname>Zygdoebert Smith</D:displayname>
+ <B:department>Gadget Sales</B:department>
+ <B:phone>234-7654</B:phone>
+ <B:office>114</B:office>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ <D:propstat>
+ <D:prop>
+ <B:salary/>
+ </D:prop>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ </D:propstat>
+ </D:response>
+ </D:multistatus>
+
+9.5. DAV:principal-search-property-set REPORT
+
+ The DAV:principal-search-property-set REPORT identifies those
+ properties that may be searched using the DAV:principal-property-
+ search REPORT (defined in Section 9.4).
+
+ Servers MUST support the DAV:principal-search-property-set REPORT on
+ all collections identified in the value of a DAV:principal-
+ collection-set property.
+
+ An access control protocol user agent could use the results of the
+ DAV:principal-search-property-set REPORT to present a query interface
+ to the user for retrieving principals.
+
+
+
+Clemm, et al. Standards Track [Page 56]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ Support for this report is REQUIRED.
+
+ Implementation Note: Some clients will have only limited screen
+ real estate for the display of lists of searchable properties. In
+ this case, a user might appreciate having the most frequently
+ searched properties be displayed on-screen, rather than having to
+ scroll through a long list of searchable properties. One
+ mechanism for signaling the most frequently searched properties is
+ to return them towards the start of a list of properties. A
+ client can then preferentially display the list of properties in
+ order, increasing the likelihood that the most frequently searched
+ properties will appear on-screen, and will not require scrolling
+ for their selection.
+
+ Marshalling:
+
+ The request body MUST be an empty DAV:principal-search-property-
+ set XML element.
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0".
+
+ The response body MUST be a DAV:principal-search-property-set XML
+ element, containing a DAV:principal-search-property XML element
+ for each property that may be searched with the DAV:principal-
+ property-search REPORT. A server MAY limit its response to just a
+ subset of the searchable properties, such as those likely to be
+ useful to an interactive access control client.
+
+ <!ELEMENT principal-search-property-set
+ (principal-search-property*) >
+
+ Each DAV:principal-search-property XML element contains exactly
+ one searchable property, and a description of the property.
+
+ <!ELEMENT principal-search-property (prop, description) >
+
+ The DAV:prop element contains one principal property on which the
+ server is able to perform a DAV:principal-property-search REPORT.
+
+ prop: see RFC 2518, Section 12.11
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 57]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ The description element is a human-readable description of what
+ information this property represents. Servers MUST indicate the
+ human language of the description using the xml:lang attribute and
+ SHOULD consider the HTTP Accept-Language request header when
+ selecting one of multiple available languages.
+
+ <!ELEMENT description #PCDATA >
+
+9.5.1. Example: DAV:principal-search-property-set REPORT
+
+ In this example, the client determines the set of searchable
+ principal properties by requesting the DAV:principal-search-
+ property-set REPORT on the root of the server's principal URL
+ collection set, identified by http://www.example.com/users/.
+
+ >> Request <<
+
+ REPORT /users/ HTTP/1.1
+ Host: www.example.com
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+ Accept-Language: en, de
+ Authorization: BASIC d2FubmFtYWs6cGFzc3dvcmQ=
+ Depth: 0
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-search-property-set xmlns:D="DAV:"/>
+
+ >> Response <<
+
+ HTTP/1.1 200 OK
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxx
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:principal-search-property-set xmlns:D="DAV:">
+ <D:principal-search-property>
+ <D:prop>
+ <D:displayname/>
+ </D:prop>
+ <D:description xml:lang="en">Full name</D:description>
+ </D:principal-search-property>
+ <D:principal-search-property>
+ <D:prop xmlns:B="http://BigCorp.com/ns/">
+ <B:title/>
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 58]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ </D:prop>
+ <D:description xml:lang="en">Job title</D:description>
+ </D:principal-search-property>
+ </D:principal-search-property-set>
+
+10. XML Processing
+
+ Implementations of this specification MUST support the XML element
+ ignore rule, as specified in Section 23.3.2 of [RFC2518], and the XML
+ Namespace recommendation [REC-XML-NAMES].
+
+ Note that use of the DAV namespace is reserved for XML elements and
+ property names defined in a standards-track or Experimental IETF RFC.
+
+11. Internationalization Considerations
+
+ In this specification, the only human-readable content can be found
+ in the description XML element, found within the DAV:supported-
+ privilege-set property. This element contains a human-readable
+ description of the capabilities controlled by a privilege. As a
+ result, the description element must be capable of representing
+ descriptions in multiple character sets. Since the description
+ element is found within a WebDAV property, it is represented on the
+ wire as XML [REC-XML], and hence can leverage XML's language tagging
+ and character set encoding capabilities. Specifically, XML
+ processors at minimum must be able to read XML elements encoded using
+ the UTF-8 [RFC3629] encoding of the ISO 10646 multilingual plane.
+ XML examples in this specification demonstrate use of the charset
+ parameter of the Content-Type header, as defined in [RFC3023], as
+ well as the XML "encoding" attribute, which together provide charset
+ identification information for MIME and XML processors. Furthermore,
+ this specification requires server implementations to tag description
+ fields with the xml:lang attribute (see Section 2.12 of [REC-XML]),
+ which specifies the human language of the description. Additionally,
+ server implementations should take into account the value of the
+ Accept-Language HTTP header to determine which description string to
+ return.
+
+ For XML elements other than the description element, it is expected
+ that implementations will treat the property names, privilege names,
+ and values as tokens, and convert these tokens into human-readable
+ text in the user's language and character set when displayed to a
+ person. Only a generic WebDAV property display utility would display
+ these values in their raw form to a human user.
+
+ For error reporting, we follow the convention of HTTP/1.1 status
+ codes, including with each status code a short, English description
+ of the code (e.g., 200 (OK)). While the possibility exists that a
+
+
+
+Clemm, et al. Standards Track [Page 59]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ poorly crafted user agent would display this message to a user,
+ internationalized applications will ignore this message, and display
+ an appropriate message in the user's language and character set.
+
+ Further internationalization considerations for this protocol are
+ described in the WebDAV Distributed Authoring protocol specification
+ [RFC2518].
+
+12. Security Considerations
+
+ Applications and users of this access control protocol should be
+ aware of several security considerations, detailed below. In
+ addition to the discussion in this document, the security
+ considerations detailed in the HTTP/1.1 specification [RFC2616], the
+ WebDAV Distributed Authoring Protocol specification [RFC2518], and
+ the XML Media Types specification [RFC3023] should be considered in a
+ security analysis of this protocol.
+
+12.1. Increased Risk of Compromised Users
+
+ In the absence of a mechanism for remotely manipulating access
+ control lists, if a single user's authentication credentials are
+ compromised, only those resources for which the user has access
+ permission can be read, modified, moved, or deleted. With the
+ introduction of this access control protocol, if a single compromised
+ user has the ability to change ACLs for a broad range of other users
+ (e.g., a super-user), the number of resources that could be altered
+ by a single compromised user increases. This risk can be mitigated
+ by limiting the number of people who have write-acl privileges across
+ a broad range of resources.
+
+12.2. Risks of the DAV:read-acl and DAV:current-user-privilege-set
+ Privileges
+
+ The ability to read the access privileges (stored in the DAV:acl
+ property), or the privileges permitted the currently authenticated
+ user (stored in the DAV:current-user-privilege-set property) on a
+ resource may seem innocuous, since reading an ACL cannot possibly
+ affect the resource's state. However, if all resources have world-
+ readable ACLs, it is possible to perform an exhaustive search for
+ those resources that have inadvertently left themselves in a
+ vulnerable state, such as being world-writable. In particular, the
+ property retrieval method PROPFIND, executed with Depth infinity on
+ an entire hierarchy, is a very efficient way to retrieve the DAV:acl
+ or DAV:current-user-privilege-set properties. Once found, this
+ vulnerability can be exploited by a denial of service attack in which
+ the open resource is repeatedly overwritten. Alternately, writable
+ resources can be modified in undesirable ways.
+
+
+
+Clemm, et al. Standards Track [Page 60]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ To reduce this risk, read-acl privileges should not be granted to
+ unauthenticated principals, and restrictions on read-acl and read-
+ current-user-privilege-set privileges for authenticated principals
+ should be carefully analyzed when deploying this protocol. Access to
+ the current-user-privilege-set property will involve a tradeoff of
+ usability versus security. When the current-user-privilege-set is
+ visible, user interfaces are expected to provide enhanced information
+ concerning permitted and restricted operations, yet this information
+ may also indicate a vulnerability that could be exploited.
+ Deployment of this protocol will need to evaluate this tradeoff in
+ light of the requirements of the deployment environment.
+
+12.3. No Foreknowledge of Initial ACL
+
+ In an effort to reduce protocol complexity, this protocol
+ specification intentionally does not address the issue of how to
+ manage or discover the initial ACL that is placed upon a resource
+ when it is created. The only way to discover the initial ACL is to
+ create a new resource, then retrieve the value of the DAV:acl
+ property. This assumes the principal creating the resource also has
+ been granted the DAV:read-acl privilege.
+
+ As a result, it is possible that a principal could create a resource,
+ and then discover that its ACL grants privileges that are
+ undesirable. Furthermore, this protocol makes it possible (though
+ unlikely) that the creating principal could be unable to modify the
+ ACL, or even delete the resource. Even when the ACL can be modified,
+ there will be a short period of time when the resource exists with
+ the initial ACL before its new ACL can be set.
+
+ Several factors mitigate this risk. Human principals are often aware
+ of the default access permissions in their editing environments and
+ take this into account when writing information. Furthermore,
+ default privilege policies are usually very conservative, limiting
+ the privileges granted by the initial ACL.
+
+13. Authentication
+
+ Authentication mechanisms defined for use with HTTP and WebDAV also
+ apply to this WebDAV Access Control Protocol, in particular the Basic
+ and Digest authentication mechanisms defined in [RFC2617].
+ Implementation of the ACL spec requires that Basic authentication, if
+ used, MUST only be supported over secure transport such as TLS.
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 61]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+14. IANA Considerations
+
+ This document uses the namespace defined by [RFC2518] for XML
+ elements. That is, this specification uses the "DAV:" URI namespace,
+ previously registered in the URI schemes registry. All other IANA
+ considerations mentioned in [RFC2518] are also applicable to this
+ specification.
+
+15. Acknowledgements
+
+ This protocol is the collaborative product of the WebDAV ACL design
+ team: Bernard Chester, Geoff Clemm, Anne Hopkins, Barry Lind, Sean
+ Lyndersay, Eric Sedlar, Greg Stein, and Jim Whitehead. The authors
+ are grateful for the detailed review and comments provided by Jim
+ Amsden, Dylan Barrell, Gino Basso, Murthy Chintalapati, Lisa
+ Dusseault, Stefan Eissing, Tim Ellison, Yaron Goland, Dennis
+ Hamilton, Laurie Harper, Eckehard Hermann, Ron Jacobs, Chris Knight,
+ Remy Maucherat, Larry Masinter, Joe Orton, Peter Raymond, and Keith
+ Wannamaker. We thank Keith Wannamaker for the initial text of the
+ principal property search sections. Prior work on WebDAV access
+ control protocols has been performed by Yaron Goland, Paul Leach,
+ Lisa Dusseault, Howard Palmer, and Jon Radoff. We would like to
+ acknowledge the foundation laid for us by the authors of the DeltaV,
+ WebDAV and HTTP protocols upon which this protocol is layered, and
+ the invaluable feedback from the WebDAV working group.
+
+16. References
+
+16.1. Normative References
+
+ [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E.
+ Maler, "Extensible Markup Language (XML) 1.0
+ ((Third ed)", W3C REC REC-xml-20040204, February
+ 2004, <http://www.w3.org/TR/2004/REC-xml-20040204>.
+
+ [REC-XML-INFOSET] Cowan, J. and R. Tobin, "XML Information Set
+ (Second Edition)", W3C REC REC-xml-infoset-
+ 20040204, February 2004,
+ <http://www.w3.org/TR/2004/REC-xml-infoset-
+ 20040204/>.
+
+ [REC-XML-NAMES] Bray, T., Hollander, D. and A. Layman, "Namespaces
+ in XML", W3C REC REC-xml-names-19990114, January
+ 1999, <http://www.w3.org/TR/1999/REC-xml-names-
+ 19990114>.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+
+
+Clemm, et al. Standards Track [Page 62]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.
+ and D. Jensen, "HTTP Extensions for Distributed
+ Authoring -- WEBDAV", RFC 2518, February 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.
+
+ [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media
+ Types", RFC 3023, January 2001.
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and
+ J. Whitehead, "Versioning Extensions to WebDAV",
+ RFC 3253, March 2002.
+
+ [RFC3530] Shepler, S., Ed., Callaghan, B., Robinson, D.,
+ Thurlow, R., Beame, C., Eisler, M. and D. Noveck,
+ "Network File System (NFS) version 4 Protocol", RFC
+ 3530, April 2003.
+
+ [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
+ 10646", STD 63, RFC 3629 November 2003.
+
+16.2. Informative References
+
+ [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight
+ Directory Access Protocol (v3)", RFC 2251, December
+ 1997.
+
+ [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC
+ 2255, December 1997.
+
+ [UNICODE4] The Unicode Consortium, "The Unicode Standard -
+ Version 4.0", Addison-Wesley , August 2003,
+ <http://www.unicode.org/versions/Unicode4.0.0/>.
+ ISBN 0321185781.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 63]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+Appendix A. WebDAV XML Document Type Definition Addendum
+
+ All XML elements defined in this Document Type Definition (DTD)
+ belong to the DAV namespace. This DTD should be viewed as an addendum
+ to the DTD provided in [RFC2518], section 23.1.
+
+ <!-- Privileges -- (Section 3)>
+
+ <!ELEMENT read EMPTY>
+ <!ELEMENT write EMPTY>
+ <!ELEMENT write-properties EMPTY>
+ <!ELEMENT write-content EMPTY>
+ <!ELEMENT unlock EMPTY>
+ <!ELEMENT read-acl EMPTY>
+ <!ELEMENT read-current-user-privilege-set EMPTY>
+ <!ELEMENT write-acl EMPTY>
+ <!ELEMENT bind EMPTY>
+ <!ELEMENT unbind EMPTY>
+ <!ELEMENT all EMPTY>
+
+ <!-- Principal Properties (Section 4) -->
+
+ <!ELEMENT principal EMPTY>
+
+ <!ELEMENT alternate-URI-set (href*)>
+ <!ELEMENT principal-URL (href)>
+ <!ELEMENT group-member-set (href*)>
+ <!ELEMENT group-membership (href*)>
+
+ <!-- Access Control Properties (Section 5) -->
+
+ <!-- DAV:owner Property (Section 5.1) -->
+
+ <!ELEMENT owner (href?)>
+
+ <!-- DAV:group Property (Section 5.2) -->
+
+ <!ELEMENT group (href?)>
+
+ <!-- DAV:supported-privilege-set Property (Section 5.3) -->
+
+ <!ELEMENT supported-privilege-set (supported-privilege*)>
+ <!ELEMENT supported-privilege
+ (privilege, abstract?, description, supported-privilege*)>
+
+ <!ELEMENT privilege ANY>
+ <!ELEMENT abstract EMPTY>
+ <!ELEMENT description #PCDATA>
+
+
+
+Clemm, et al. Standards Track [Page 64]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <!-- DAV:current-user-privilege-set Property (Section 5.4) -->
+
+ <!ELEMENT current-user-privilege-set (privilege*)>
+
+ <!-- DAV:acl Property (Section 5.5) -->
+
+ <!ELEMENT acl (ace)* >
+ <!ELEMENT ace ((principal | invert), (grant|deny), protected?,
+ inherited?)>
+
+ <!ELEMENT principal (href)
+ | all | authenticated | unauthenticated
+ | property | self)>
+
+ <!ELEMENT all EMPTY>
+ <!ELEMENT authenticated EMPTY>
+ <!ELEMENT unauthenticated EMPTY>
+ <!ELEMENT property ANY>
+ <!ELEMENT self EMPTY>
+
+ <!ELEMENT invert principal>
+
+ <!ELEMENT grant (privilege+)>
+ <!ELEMENT deny (privilege+)>
+ <!ELEMENT privilege ANY>
+
+ <!ELEMENT protected EMPTY>
+
+ <!ELEMENT inherited (href)>
+
+ <!-- DAV:acl-restrictions Property (Section 5.6) -->
+
+ <!ELEMENT acl-restrictions (grant-only?, no-invert?,
+ deny-before-grant?, required-principal?)>
+
+ <!ELEMENT grant-only EMPTY>
+ <!ELEMENT no-invert EMPTY>
+ <!ELEMENT deny-before-grant EMPTY>
+
+ <!ELEMENT required-principal
+ (all? | authenticated? | unauthenticated? | self? | href*
+ |property*)>
+
+ <!-- DAV:inherited-acl-set Property (Section 5.7) -->
+
+ <!ELEMENT inherited-acl-set (href*)>
+
+ <!-- DAV:principal-collection-set Property (Section 5.8) -->
+
+
+
+Clemm, et al. Standards Track [Page 65]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ <!ELEMENT principal-collection-set (href*)>
+
+ <!-- Access Control and Existing Methods (Section 7) -->
+
+ <!ELEMENT need-privileges (resource)* >
+ <!ELEMENT resource ( href, privilege )
+
+ <!-- ACL method preconditions (Section 8.1.1) -->
+
+ <!ELEMENT no-ace-conflict EMPTY>
+ <!ELEMENT no-protected-ace-conflict EMPTY>
+ <!ELEMENT no-inherited-ace-conflict EMPTY>
+ <!ELEMENT limited-number-of-aces EMPTY>
+ <!ELEMENT grant-only EMPTY>
+ <!ELEMENT no-invert EMPTY>
+ <!ELEMENT deny-before-grant EMPTY>
+ <!ELEMENT no-abstract EMPTY>
+ <!ELEMENT not-supported-privilege EMPTY>
+ <!ELEMENT missing-required-principal EMPTY>
+ <!ELEMENT recognized-principal EMPTY>
+ <!ELEMENT allowed-principal EMPTY>
+
+ <!-- REPORTs (Section 9) -->
+
+ <!ELEMENT acl-principal-prop-set ANY>
+ ANY value: a sequence of one or more elements, with at most one
+ DAV:prop element.
+
+ <!ELEMENT principal-match ((principal-property | self), prop?)>
+ <!ELEMENT principal-property ANY>
+ ANY value: an element whose value identifies a property. The
+ expectation is the value of the named property typically contains
+ an href element that contains the URI of a principal
+ <!ELEMENT self EMPTY>
+
+ <!ELEMENT principal-property-search ((property-search+), prop?) >
+ <!ELEMENT property-search (prop, match) >
+ <!ELEMENT match #PCDATA >
+
+ <!ELEMENT principal-search-property-set (
+ principal-search-property*) >
+ <!ELEMENT principal-search-property (prop, description) >
+ <!ELEMENT description #PCDATA >
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 66]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+Appendix B. WebDAV Method Privilege Table (Normative)
+
+ The following table of WebDAV methods (as defined in RFC 2518, 2616,
+ and 3253) clarifies which privileges are required for access for each
+ method. Note that the privileges listed, if denied, MUST cause
+ access to be denied. However, given that a specific implementation
+ MAY define an additional custom privilege to control access to
+ existing methods, having all of the indicated privileges does not
+ mean that access will be granted. Note that lack of the indicated
+ privileges does not imply that access will be denied, since a
+ particular implementation may use a sub-privilege aggregated under
+ the indicated privilege to control access. Privileges required refer
+ to the current resource being processed unless otherwise specified.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 67]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ +---------------------------------+---------------------------------+
+ | METHOD | PRIVILEGES |
+ +---------------------------------+---------------------------------+
+ | GET | <D:read> |
+ | HEAD | <D:read> |
+ | OPTIONS | <D:read> |
+ | PUT (target exists) | <D:write-content> on target |
+ | | resource |
+ | PUT (no target exists) | <D:bind> on parent collection |
+ | | of target |
+ | PROPPATCH | <D:write-properties> |
+ | ACL | <D:write-acl> |
+ | PROPFIND | <D:read> (plus <D:read-acl> and |
+ | | <D:read-current-user-privilege- |
+ | | set> as needed) |
+ | COPY (target exists) | <D:read>, <D:write-content> and |
+ | | <D:write-properties> on target |
+ | | resource |
+ | COPY (no target exists) | <D:read>, <D:bind> on target |
+ | | collection |
+ | MOVE (no target exists) | <D:unbind> on source collection |
+ | | and <D:bind> on target |
+ | | collection |
+ | MOVE (target exists) | As above, plus <D:unbind> on |
+ | | the target collection |
+ | DELETE | <D:unbind> on parent collection |
+ | LOCK (target exists) | <D:write-content> |
+ | LOCK (no target exists) | <D:bind> on parent collection |
+ | MKCOL | <D:bind> on parent collection |
+ | UNLOCK | <D:unlock> |
+ | CHECKOUT | <D:write-properties> |
+ | CHECKIN | <D:write-properties> |
+ | REPORT | <D:read> (on all referenced |
+ | | resources) |
+ | VERSION-CONTROL | <D:write-properties> |
+ | MERGE | <D:write-content> |
+ | MKWORKSPACE | <D:write-content> on parent |
+ | | collection |
+ | BASELINE-CONTROL | <D:write-properties> and |
+ | | <D:write-content> |
+ | MKACTIVITY | <D:write-content> on parent |
+ | | collection |
+ +---------------------------------+---------------------------------+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 68]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+Index
+
+ A
+ ACL method 40
+
+ C
+ Condition Names
+ DAV:allowed-principal (pre) 42
+ DAV:deny-before-grant (pre) 41
+ DAV:grant-only (pre) 41
+ DAV:limited-number-of-aces (pre) 41
+ DAV:missing-required-principal (pre) 42
+ DAV:no-abstract (pre) 41
+ DAV:no-ace-conflict (pre) 41
+ DAV:no-inherited-ace-conflict (pre) 41
+ DAV:no-invert (pre) 41
+ DAV:no-protected-ace-conflict (pre) 41
+ DAV:not-supported-privilege (pre) 42
+ DAV:number-of-matches-within-limits (post) 48, 53
+ DAV:recognized-principal (pre) 42
+
+ D
+ DAV header
+ compliance class 'access-control' 38
+ DAV:acl property 23
+ DAV:acl-principal-prop-set report 48
+ DAV:acl-restrictions property 27
+ DAV:all privilege 13
+ DAV:allowed-principal precondition 42
+ DAV:alternate-URI-set property 14
+ DAV:bind privilege 12
+ DAV:current-user-privilege-set property 21
+ DAV:deny-before-grant precondition 41
+ DAV:grant-only precondition 41
+ DAV:group property 18
+ DAV:group-member-set property 14
+ DAV:group-membership property 14
+ DAV:inherited-acl-set property 29
+ DAV:limited-number-of-aces precondition 41
+ DAV:missing-required-principal precondition 42
+ DAV:no-abstract precondition 41
+ DAV:no-ace-conflict precondition 41
+ DAV:no-inherited-ace-conflict precondition 41
+ DAV:no-invert precondition 41
+ DAV:no-protected-ace-conflict precondition 41
+ DAV:not-supported-privilege precondition 42
+ DAV:number-of-matches-within-limits postcondition 48, 53
+ DAV:owner property 15
+
+
+
+Clemm, et al. Standards Track [Page 69]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ DAV:principal resource type 13
+ DAV:principal-collection-set property 30
+ DAV:principal-match report 50
+ DAV:principal-property-search 51
+ DAV:principal-search-property-set 56
+ DAV:principal-URL property 14
+ DAV:read privilege 10
+ DAV:read-acl privilege 11
+ DAV:read-current-user-privilege-set privilege 12
+ DAV:recognized-principal precondition 42
+ DAV:supported-privilege-set property 18
+ DAV:unbind privilege 12
+ DAV:unlock privilege 11
+ DAV:write privilege 10
+ DAV:write-acl privilege 12
+ DAV:write-content privilege 10
+ DAV:write-properties privilege 10
+
+ M
+ Methods
+ ACL 40
+
+ P
+ Privileges
+ DAV:all 13
+ DAV:bind 12
+ DAV:read 10
+ DAV:read-acl 11
+ DAV:read-current-user-privilege-set 12
+ DAV:unbind 12
+ DAV:unlock 11
+ DAV:write 10
+ DAV:write-acl 12
+ DAV:write-content 11
+ DAV:write-properties 10
+ Properties
+ DAV:acl 23
+ DAV:acl-restrictions 27
+ DAV:alternate-URI-set 14
+ DAV:current-user-privilege-set 21
+ DAV:group 18
+ DAV:group-member-set 14
+ DAV:group-membership 14
+ DAV:inherited-acl-set 29
+ DAV:owner 15
+ DAV:principal-collection-set 30
+ DAV:principal-URL 14
+ DAV:supported-privilege-set 18
+
+
+
+Clemm, et al. Standards Track [Page 70]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+ R
+ Reports
+ DAV:acl-principal-prop-set 47
+ DAV:principal-match 49
+ DAV:principal-property-search 51
+ DAV:principal-search-property-set 56
+ Resource Types
+ DAV:principal 13
+
+Authors' Addresses
+
+ Geoffrey Clemm
+ IBM
+ 20 Maguire Road
+ Lexington, MA 02421
+
+ EMail: geoffrey.clemm at us.ibm.com
+
+
+ Julian F. Reschke
+ greenbytes GmbH
+ Salzmannstrasse 152
+ Muenster, NW 48159
+ Germany
+
+ EMail: julian.reschke at greenbytes.de
+
+
+ Eric Sedlar
+ Oracle Corporation
+ 500 Oracle Parkway
+ Redwood Shores, CA 94065
+
+ EMail: eric.sedlar at oracle.com
+
+
+ Jim Whitehead
+ U.C. Santa Cruz, Dept. of Computer Science
+ 1156 High Street
+ Santa Cruz, CA 95064
+
+ EMail: ejw at cse.ucsc.edu
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 71]
+
+RFC 3744 WebDAV Access Control Protocol May 2004
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2004). This document is subject
+ to the rights, licenses and restrictions contained in BCP 78, and
+ except as set forth therein, the authors retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
+ REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
+ INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
+ THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed
+ to pertain to the implementation or use of the technology
+ described in this document or the extent to which any license
+ under such rights might or might not be available; nor does it
+ represent that it has made any independent effort to identify any
+ such rights. Information on the procedures with respect to
+ rights in RFC documents can be found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use
+ of such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository
+ at http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention
+ any copyrights, patents or patent applications, or other
+ proprietary rights that may cover technology that may be required
+ to implement this standard. Please address the information to the
+ IETF at ietf-ipr at ietf.org.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+Clemm, et al. Standards Track [Page 72]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc3744.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc3744.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc3744.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,4035 +0,0 @@
-
-
-
-
-
-
-Network Working Group G. Clemm
-Request for Comments: 3744 IBM
-Category: Standards Track J. Reschke
- greenbytes
- E. Sedlar
- Oracle Corporation
- J. Whitehead
- U.C. Santa Cruz
- May 2004
-
-
- Web Distributed Authoring and Versioning (WebDAV)
- Access Control Protocol
-
-Status of this Memo
-
- This document specifies an Internet standards track protocol for the
- Internet community, and requests discussion and suggestions for
- improvements. Please refer to the current edition of the "Internet
- Official Protocol Standards" (STD 1) for the standardization state
- and status of this protocol. Distribution of this memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2004). All Rights Reserved.
-
-Abstract
-
- This document specifies a set of methods, headers, message bodies,
- properties, and reports that define Access Control extensions to the
- WebDAV Distributed Authoring Protocol. This protocol permits a
- client to read and modify access control lists that instruct a server
- whether to allow or deny operations upon a resource (such as
- HyperText Transfer Protocol (HTTP) method invocations) by a given
- principal. A lightweight representation of principals as Web
- resources supports integration of a wide range of user management
- repositories. Search operations allow discovery and manipulation of
- principals using human names.
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 1]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-Table of Contents
-
- 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 1.1. Terms. . . . . . . . . . . . . . . . . . . . . . . . . . 6
- 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 8
- 2. Principals . . . . . . . . . . . . . . . . . . . . . . . . . . 8
- 3. Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . 8
- 3.1. DAV:read Privilege . . . . . . . . . . . . . . . . . . . 10
- 3.2. DAV:write Privilege. . . . . . . . . . . . . . . . . . . 10
- 3.3. DAV:write-properties Privilege . . . . . . . . . . . . . 10
- 3.4. DAV:write-content Privilege. . . . . . . . . . . . . . . 11
- 3.5. DAV:unlock Privilege . . . . . . . . . . . . . . . . . . 11
- 3.6. DAV:read-acl Privilege . . . . . . . . . . . . . . . . . 11
- 3.7. DAV:read-current-user-privilege-set Privilege. . . . . . 12
- 3.8. DAV:write-acl Privilege. . . . . . . . . . . . . . . . . 12
- 3.9. DAV:bind Privilege . . . . . . . . . . . . . . . . . . . 12
- 3.10. DAV:unbind Privilege . . . . . . . . . . . . . . . . . . 12
- 3.11. DAV:all Privilege. . . . . . . . . . . . . . . . . . . . 13
- 3.12. Aggregation of Predefined Privileges . . . . . . . . . . 13
- 4. Principal Properties . . . . . . . . . . . . . . . . . . . . . 13
- 4.1. DAV:alternate-URI-set. . . . . . . . . . . . . . . . . . 14
- 4.2. DAV:principal-URL. . . . . . . . . . . . . . . . . . . . 14
- 4.3. DAV:group-member-set . . . . . . . . . . . . . . . . . . 14
- 4.4. DAV:group-membership . . . . . . . . . . . . . . . . . . 14
- 5. Access Control Properties. . . . . . . . . . . . . . . . . . . 15
- 5.1. DAV:owner. . . . . . . . . . . . . . . . . . . . . . . . 15
- 5.1.1. Example: Retrieving DAV:owner . . . . . . . . . . 15
- 5.1.2. Example: An Attempt to Set DAV:owner. . . . . . . 16
- 5.2. DAV:group. . . . . . . . . . . . . . . . . . . . . . . . 18
- 5.3. DAV:supported-privilege-set. . . . . . . . . . . . . . . 18
- 5.3.1. Example: Retrieving a List of Privileges
- Supported on a Resource . . . . . . . . . . . . . 19
- 5.4. DAV:current-user-privilege-set . . . . . . . . . . . . . 21
- 5.4.1. Example: Retrieving the User's Current Set of
- Assigned Privileges . . . . . . . . . . . . . . . 22
- 5.5. DAV:acl. . . . . . . . . . . . . . . . . . . . . . . . . 23
- 5.5.1. ACE Principal . . . . . . . . . . . . . . . . . . 23
- 5.5.2. ACE Grant and Deny. . . . . . . . . . . . . . . . 25
- 5.5.3. ACE Protection. . . . . . . . . . . . . . . . . . 25
- 5.5.4. ACE Inheritance . . . . . . . . . . . . . . . . . 25
- 5.5.5. Example: Retrieving a Resource's Access Control
- List. . . . . . . . . . . . . . . . . . . . . . . 25
- 5.6. DAV:acl-restrictions . . . . . . . . . . . . . . . . . . 27
- 5.6.1. DAV:grant-only. . . . . . . . . . . . . . . . . . 27
- 5.6.2. DAV:no-invert ACE Constraint. . . . . . . . . . . 28
- 5.6.3. DAV:deny-before-grant . . . . . . . . . . . . . . 28
- 5.6.4. Required Principals . . . . . . . . . . . . . . . 28
- 5.6.5. Example: Retrieving DAV:acl-restrictions. . . . . 28
-
-
-
-Clemm, et al. Standards Track [Page 2]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- 5.7. DAV:inherited-acl-set. . . . . . . . . . . . . . . . . . 29
- 5.8. DAV:principal-collection-set . . . . . . . . . . . . . . 30
- 5.8.1. Example: Retrieving DAV:principal-collection-set. 30
- 5.9. Example: PROPFIND to retrieve access control properties. 32
- 6. ACL Evaluation . . . . . . . . . . . . . . . . . . . . . . . . 36
- 7. Access Control and existing methods. . . . . . . . . . . . . . 37
- 7.1. Any HTTP method. . . . . . . . . . . . . . . . . . . . . 37
- 7.1.1. Error Handling. . . . . . . . . . . . . . . . . . 37
- 7.2. OPTIONS. . . . . . . . . . . . . . . . . . . . . . . . . 38
- 7.2.1. Example - OPTIONS . . . . . . . . . . . . . . . . 39
- 7.3. MOVE . . . . . . . . . . . . . . . . . . . . . . . . . . 39
- 7.4. COPY . . . . . . . . . . . . . . . . . . . . . . . . . . 39
- 7.5. LOCK . . . . . . . . . . . . . . . . . . . . . . . . . . 39
- 8. Access Control Methods . . . . . . . . . . . . . . . . . . . . 40
- 8.1. ACL. . . . . . . . . . . . . . . . . . . . . . . . . . . 40
- 8.1.1. ACL Preconditions . . . . . . . . . . . . . . . . 40
- 8.1.2. Example: the ACL method . . . . . . . . . . . . . 42
- 8.1.3. Example: ACL method failure due to protected
- ACE conflict. . . . . . . . . . . . . . . . . . . 43
- 8.1.4. Example: ACL method failure due to an
- inherited ACE conflict. . . . . . . . . . . . . . 44
- 8.1.5. Example: ACL method failure due to an attempt
- to set grant and deny in a single ACE . . . . . . 45
- 9. Access Control Reports . . . . . . . . . . . . . . . . . . . . 46
- 9.1. REPORT Method. . . . . . . . . . . . . . . . . . . . . . 46
- 9.2. DAV:acl-principal-prop-set Report. . . . . . . . . . . . 47
- 9.2.1. Example: DAV:acl-principal-prop-set Report. . . . 48
- 9.3. DAV:principal-match REPORT . . . . . . . . . . . . . . . 49
- 9.3.1. Example: DAV:principal-match REPORT . . . . . . . 50
- 9.4. DAV:principal-property-search REPORT . . . . . . . . . . 51
- 9.4.1. Matching. . . . . . . . . . . . . . . . . . . . . 53
- 9.4.2. Example: successful DAV:principal-property-search
- REPORT. . . . . . . . . . . . . . . . . . . . . . 54
- 9.5. DAV:principal-search-property-set REPORT . . . . . . . . 56
- 9.5.1. Example: DAV:principal-search-property-set
- REPORT. . . . . . . . . . . . . . . . . . . . . . 58
- 10. XML Processing . . . . . . . . . . . . . . . . . . . . . . . . 59
- 11. Internationalization Considerations. . . . . . . . . . . . . . 59
- 12. Security Considerations. . . . . . . . . . . . . . . . . . . . 60
- 12.1. Increased Risk of Compromised Users. . . . . . . . . . . 60
- 12.2. Risks of the DAV:read-acl and
- DAV:current-user-privilege-set Privileges. . . . . . . . 60
- 12.3. No Foreknowledge of Initial ACL. . . . . . . . . . . . . 61
- 13. Authentication . . . . . . . . . . . . . . . . . . . . . . . . 61
- 14. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 62
- 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 62
-
-
-
-
-
-Clemm, et al. Standards Track [Page 3]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 62
- 16.1. Normative References . . . . . . . . . . . . . . . . . . 62
- 16.2. Informative References . . . . . . . . . . . . . . . . . 63
- Appendices
- A. WebDAV XML Document Type Definition Addendum . . . . . . . . . 64
- B. WebDAV Method Privilege Table (Normative). . . . . . . . . . . 67
- Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 71
- Full Copyright Statement. . . . . . . . . . . . . . . . . . . . . 72
-
-1. Introduction
-
- The goal of the WebDAV access control extensions is to provide an
- interoperable mechanism for handling discretionary access control for
- content and metadata managed by WebDAV servers. WebDAV access
- control can be implemented on content repositories with security as
- simple as that of a UNIX file system, as well as more sophisticated
- models. The underlying principle of access control is that who you
- are determines what operations you can perform on a resource. The
- "who you are" is defined by a "principal" identifier; users, client
- software, servers, and groups of the previous have principal
- identifiers. The "operations you can perform" are determined by a
- single "access control list" (ACL) associated with a resource. An
- ACL contains a set of "access control entries" (ACEs), where each ACE
- specifies a principal and a set of privileges that are either granted
- or denied to that principal. When a principal submits an operation
- (such as an HTTP or WebDAV method) to a resource for execution, the
- server evaluates the ACEs in the ACL to determine if the principal
- has permission for that operation.
-
- Since every ACE contains the identifier of a principal, client
- software operated by a human must provide a mechanism for selecting
- this principal. This specification uses http(s) scheme URLs to
- identify principals, which are represented as WebDAV-capable
- resources. There is no guarantee that the URLs identifying
- principals will be meaningful to a human. For example,
- http://www.example.com/u/256432 and
- http://www.example.com/people/Greg.Stein are both valid URLs that
- could be used to identify the same principal. To remedy this, every
- principal resource has the DAV:displayname property containing a
- human-readable name for the principal.
-
- Since a principal can be identified by multiple URLs, it raises the
- problem of determining exactly which principal is being referenced in
- a given ACE. It is impossible for a client to determine that an ACE
- granting the read privilege to http://www.example.com/people/
- Greg.Stein also affects the principal at http://www.example.com/u/
- 256432. That is, a client has no mechanism for determining that two
-
-
-
-Clemm, et al. Standards Track [Page 4]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- URLs identify the same principal resource. As a result, this
- specification requires clients to use just one of the many possible
- URLs for a principal when creating ACEs. A client can discover which
- URL to use by retrieving the DAV:principal-URL property (Section 4.2)
- from a principal resource. No matter which of the principal's URLs
- is used with PROPFIND, the property always returns the same URL.
-
- With a system having hundreds to thousands of principals, the problem
- arises of how to allow a human operator of client software to select
- just one of these principals. One approach is to use broad
- collection hierarchies to spread the principals over a large number
- of collections, yielding few principals per collection. An example
- of this is a two level hierarchy with the first level containing 36
- collections (a-z, 0-9), and the second level being another 36,
- creating collections /a/a/, /a/b/, ..., /a/z/, such that a principal
- with last name "Stein" would appear at /s/t/Stein. In effect, this
- pre-computes a common query, search on last name, and encodes it into
- a hierarchy. The drawback with this scheme is that it handles only a
- small set of predefined queries, and drilling down through the
- collection hierarchy adds unnecessary steps (navigate down/up) when
- the user already knows the principal's name. While organizing
- principal URLs into a hierarchy is a valid namespace organization,
- users should not be forced to navigate this hierarchy to select a
- principal.
-
- This specification provides the capability to perform substring
- searches over a small set of properties on the resources representing
- principals. This permits searches based on last name, first name,
- user name, job title, etc. Two separate searches are supported, both
- via the REPORT method, one to search principal resources
- (DAV:principal-property-search, Section 9.4), the other to determine
- which properties may be searched at all (DAV:principal-search-
- property-set, Section 9.5).
-
- Once a principal has been identified in an ACE, a server evaluating
- that ACE must know the identity of the principal making a protocol
- request, and must validate that that principal is who they claim to
- be, a process known as authentication. This specification
- intentionally omits discussion of authentication, as the HTTP
- protocol already has a number of authentication mechanisms [RFC2617].
- Some authentication mechanism (such as HTTP Digest Authentication,
- which all WebDAV compliant implementations are required to support)
- must be available to validate the identity of a principal.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 5]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The following issues are out of scope for this document:
-
- o Access control that applies only to a particular property on a
- resource (excepting the access control properties DAV:acl and
- DAV:current-user-privilege-set), rather than the entire resource,
-
- o Role-based security (where a role can be seen as a dynamically
- defined group of principals),
-
- o Specification of the ways an ACL on a resource is initialized,
-
- o Specification of an ACL that applies globally to all resources,
- rather than to a particular resource.
-
- o Creation and maintenance of resources representing people or
- computational agents (principals), and groups of these.
-
- This specification is organized as follows. Section 1.1 defines key
- concepts used throughout the specification, and is followed by a more
- in-depth discussion of principals (Section 2), and privileges
- (Section 3). Properties defined on principals are specified in
- Section 4, and access control properties for content resources are
- specified in Section 5. The ways ACLs are to be evaluated is
- described in Section 6. Client discovery of access control
- capability using OPTIONS is described in Section 7.2. Interactions
- between access control functionality and existing HTTP and WebDAV
- methods are described in the remainder of Section 7. The access
- control setting method, ACL, is specified in Section 8. Four reports
- that provide limited server-side searching capabilities are described
- in Section 9. Sections on XML processing (Section 10),
- Internationalization considerations (Section 11), security
- considerations (Section 12), and authentication (Section 13) round
- out the specification. An appendix (Appendix A) provides an XML
- Document Type Definition (DTD) for the XML elements defined in the
- specification.
-
-1.1. Terms
-
- This document uses the terms defined in HTTP [RFC2616] and WebDAV
- [RFC2518]. In addition, the following terms are defined:
-
- principal
-
- A "principal" is a distinct human or computational actor that
- initiates access to network resources. In this protocol, a
- principal is an HTTP resource that represents such an actor.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 6]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- group
-
- A "group" is a principal that represents a set of other
- principals.
-
- privilege
-
- A "privilege" controls access to a particular set of HTTP
- operations on a resource.
-
- aggregate privilege
-
- An "aggregate privilege" is a privilege that contains a set of
- other privileges.
-
- abstract privilege
-
- The modifier "abstract", when applied to a privilege on a
- resource, means the privilege cannot be set in an access control
- element (ACE) on that resource.
-
- access control list (ACL)
-
- An "ACL" is a list of access control elements that define access
- control to a particular resource.
-
- access control element (ACE)
-
- An "ACE" either grants or denies a particular set of (non-
- abstract) privileges for a particular principal.
-
- inherited ACE
-
- An "inherited ACE" is an ACE that is dynamically shared from the
- ACL of another resource. When a shared ACE changes on the primary
- resource, it is also changed on inheriting resources.
-
- protected property
-
- A "protected property" is one whose value cannot be updated except
- by a method explicitly defined as updating that specific property.
- In particular, a protected property cannot be updated with a
- PROPPATCH request.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 7]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-1.2. Notational Conventions
-
- The augmented BNF used by this document to describe protocol elements
- is described in Section 2.1 of [RFC2616]. Because this augmented BNF
- uses the basic production rules provided in Section 2.2 of [RFC2616],
- those rules apply to this document as well.
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in [RFC2119].
-
- Definitions of XML elements in this document use XML element type
- declarations (as found in XML Document Type Declarations), described
- in Section 3.2 of [REC-XML]. When an XML element type in the "DAV:"
- namespace is referenced in this document outside of the context of an
- XML fragment, the string "DAV:" will be prefixed to the element name.
-
-2. Principals
-
- A principal is a network resource that represents a distinct human or
- computational actor that initiates access to network resources.
- Users and groups are represented as principals in many
- implementations; other types of principals are also possible. A URI
- of any scheme MAY be used to identify a principal resource. However,
- servers implementing this specification MUST expose principal
- resources at an http(s) URL, which is a privileged scheme that points
- to resources that have additional properties, as described in Section
- 4. So, a principal resource can have multiple URIs, one of which has
- to be an http(s) scheme URL. Although an implementation SHOULD
- support PROPFIND and MAY support PROPPATCH to access and modify
- information about a principal, it is not required to do so.
-
- A principal resource may be a group, where a group is a principal
- that represents a set of other principals, called the members of the
- group. If a person or computational agent matches a principal
- resource that is a member of a group, they also match the group.
- Membership in a group is recursive, so if a principal is a member of
- group GRPA, and GRPA is a member of group GRPB, then the principal is
- also a member of GRPB.
-
-3. Privileges
-
- Ability to perform a given method on a resource MUST be controlled by
- one or more privileges. Authors of protocol extensions that define
- new HTTP methods SHOULD specify which privileges (by defining new
- privileges, or mapping to ones below) are required to perform the
- method. A principal with no privileges to a resource MUST be denied
- any HTTP access to that resource, unless the principal matches an ACE
-
-
-
-Clemm, et al. Standards Track [Page 8]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- constructed using the DAV:all, DAV:authenticated, or
- DAV:unauthenticated pseudo-principals (see Section 5.5.1). Servers
- MUST report a 403 "Forbidden" error if access is denied, except in
- the case where the privilege restricts the ability to know the
- resource exists, in which case 404 "Not Found" may be returned.
-
- Privileges may be containers of other privileges, in which case they
- are termed "aggregate privileges". If a principal is granted or
- denied an aggregate privilege, it is semantically equivalent to
- granting or denying each of the aggregated privileges individually.
- For example, an implementation may define add-member and remove-
- member privileges that control the ability to add and remove a member
- of a group. Since these privileges control the ability to update the
- state of a group, these privileges would be aggregated by the
- DAV:write privilege on a group, and granting the DAV:write privilege
- on a group would also grant the add-member and remove-member
- privileges.
-
- Privileges may be declared to be "abstract" for a given resource, in
- which case they cannot be set in an ACE on that resource. Aggregate
- and non-aggregate privileges are both capable of being abstract.
- Abstract privileges are useful for modeling privileges that otherwise
- would not be exposed via the protocol. Abstract privileges also
- provide server implementations with flexibility in implementing the
- privileges defined in this specification. For example, if a server
- is incapable of separating the read resource capability from the read
- ACL capability, it can still model the DAV:read and DAV:read-acl
- privileges defined in this specification by declaring them abstract,
- and containing them within a non-abstract aggregate privilege (say,
- read-all) that holds DAV:read, and DAV:read-acl. In this way, it is
- possible to set the aggregate privilege, read-all, thus coupling the
- setting of DAV:read and DAV:read-acl, but it is not possible to set
- DAV:read, or DAV:read-acl individually. Since aggregate privileges
- can be abstract, it is also possible to use abstract privileges to
- group or organize non-abstract privileges. Privilege containment
- loops are not allowed; therefore, a privilege MUST NOT contain
- itself. For example, DAV:read cannot contain DAV:read.
-
- The set of privileges that apply to a particular resource may vary
- with the DAV:resourcetype of the resource, as well as between
- different server implementations. To promote interoperability,
- however, this specification defines a set of well-known privileges
- (e.g., DAV:read, DAV:write, DAV:read-acl, DAV:write-acl, DAV:read-
- current-user-privilege-set, and DAV:all), which can at least be used
- to classify the other privileges defined on a particular resource.
- The access permissions on null resources (defined in [RFC2518],
- Section 3) are solely those they inherit (if any), and they are not
- discoverable (i.e., the access control properties specified in
-
-
-
-Clemm, et al. Standards Track [Page 9]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Section 5 are not defined on null resources). On the transition from
- null to stateful resource, the initial access control list is set by
- the server's default ACL value policy (if any).
-
- Server implementations MAY define new privileges beyond those defined
- in this specification. Privileges defined by individual
- implementations MUST NOT use the DAV: namespace, and instead should
- use a namespace that they control, such as an http scheme URL.
-
-3.1. DAV:read Privilege
-
- The read privilege controls methods that return information about the
- state of the resource, including the resource's properties. Affected
- methods include GET and PROPFIND. Any implementation-defined
- privilege that also controls access to GET and PROPFIND must be
- aggregated under DAV:read - if an ACL grants access to DAV:read, the
- client may expect that no other privilege needs to be granted to have
- access to GET and PROPFIND. Additionally, the read privilege MUST
- control the OPTIONS method.
-
- <!ELEMENT read EMPTY>
-
-3.2. DAV:write Privilege
-
- The write privilege controls methods that lock a resource or modify
- the content, dead properties, or (in the case of a collection)
- membership of the resource, such as PUT and PROPPATCH. Note that
- state modification is also controlled via locking (see section 5.3 of
- [RFC2518]), so effective write access requires that both write
- privileges and write locking requirements are satisfied. Any
- implementation-defined privilege that also controls access to methods
- modifying content, dead properties or collection membership must be
- aggregated under DAV:write, e.g., if an ACL grants access to
- DAV:write, the client may expect that no other privilege needs to be
- granted to have access to PUT and PROPPATCH.
-
- <!ELEMENT write EMPTY>
-
-3.3. DAV:write-properties Privilege
-
- The DAV:write-properties privilege controls methods that modify the
- dead properties of the resource, such as PROPPATCH. Whether this
- privilege may be used to control access to any live properties is
- determined by the implementation. Any implementation-defined
- privilege that also controls access to methods modifying dead
- properties must be aggregated under DAV:write-properties - e.g., if
-
-
-
-
-
-Clemm, et al. Standards Track [Page 10]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- an ACL grants access to DAV:write-properties, the client can safely
- expect that no other privilege needs to be granted to have access to
- PROPPATCH.
-
- <!ELEMENT write-properties EMPTY>
-
-3.4. DAV:write-content Privilege
-
- The DAV:write-content privilege controls methods that modify the
- content of an existing resource, such as PUT. Any implementation-
- defined privilege that also controls access to content must be
- aggregated under DAV:write-content - e.g., if an ACL grants access to
- DAV:write-content, the client can safely expect that no other
- privilege needs to be granted to have access to PUT. Note that PUT -
- when applied to an unmapped URI - creates a new resource and
- therefore is controlled by the DAV:bind privilege on the parent
- collection.
-
- <!ELEMENT write-content EMPTY>
-
-3.5. DAV:unlock Privilege
-
- The DAV:unlock privilege controls the use of the UNLOCK method by a
- principal other than the lock owner (the principal that created a
- lock can always perform an UNLOCK). While the set of users who may
- lock a resource is most commonly the same set of users who may modify
- a resource, servers may allow various kinds of administrators to
- unlock resources locked by others. Any privilege controlling access
- by non-lock owners to UNLOCK MUST be aggregated under DAV:unlock.
-
- A lock owner can always remove a lock by issuing an UNLOCK with the
- correct lock token and authentication credentials. That is, even if
- a principal does not have DAV:unlock privilege, they can still remove
- locks they own. Principals other than the lock owner can remove a
- lock only if they have DAV:unlock privilege and they issue an UNLOCK
- with the correct lock token. Lock timeout is not affected by the
- DAV:unlock privilege.
-
- <!ELEMENT unlock EMPTY>
-
-3.6. DAV:read-acl Privilege
-
- The DAV:read-acl privilege controls the use of PROPFIND to retrieve
- the DAV:acl property of the resource.
-
- <!ELEMENT read-acl EMPTY>
-
-
-
-
-
-Clemm, et al. Standards Track [Page 11]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-3.7. DAV:read-current-user-privilege-set Privilege
-
- The DAV:read-current-user-privilege-set privilege controls the use of
- PROPFIND to retrieve the DAV:current-user-privilege-set property of
- the resource.
-
- Clients are intended to use this property to visually indicate in
- their UI items that are dependent on the permissions of a resource,
- for example, by graying out resources that are not writable.
-
- This privilege is separate from DAV:read-acl because there is a need
- to allow most users access to the privileges permitted the current
- user (due to its use in creating the UI), while the full ACL contains
- information that may not be appropriate for the current authenticated
- user. As a result, the set of users who can view the full ACL is
- expected to be much smaller than those who can read the current user
- privilege set, and hence distinct privileges are needed for each.
-
- <!ELEMENT read-current-user-privilege-set EMPTY>
-
-3.8. DAV:write-acl Privilege
-
- The DAV:write-acl privilege controls use of the ACL method to modify
- the DAV:acl property of the resource.
-
- <!ELEMENT write-acl EMPTY>
-
-3.9. DAV:bind Privilege
-
- The DAV:bind privilege allows a method to add a new member URL to the
- specified collection (for example via PUT or MKCOL). It is ignored
- for resources that are not collections.
-
- <!ELEMENT bind EMPTY>
-
-3.10. DAV:unbind Privilege
-
- The DAV:unbind privilege allows a method to remove a member URL from
- the specified collection (for example via DELETE or MOVE). It is
- ignored for resources that are not collections.
-
- <!ELEMENT unbind EMPTY>
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 12]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-3.11. DAV:all Privilege
-
- DAV:all is an aggregate privilege that contains the entire set of
- privileges that can be applied to the resource.
-
- <!ELEMENT all EMPTY>
-
-3.12. Aggregation of Predefined Privileges
-
- Server implementations are free to aggregate the predefined
- privileges (defined above in Sections 3.1-3.10) subject to the
- following limitations:
-
- DAV:read-acl MUST NOT contain DAV:read, DAV:write, DAV:write-acl,
- DAV:write-properties, DAV:write-content, or DAV:read-current-user-
- privilege-set.
-
- DAV:write-acl MUST NOT contain DAV:write, DAV:read, DAV:read-acl, or
- DAV:read-current-user-privilege-set.
-
- DAV:read-current-user-privilege-set MUST NOT contain DAV:write,
- DAV:read, DAV:read-acl, or DAV:write-acl.
-
- DAV:write MUST NOT contain DAV:read, DAV:read-acl, or DAV:read-
- current-user-privilege-set.
-
- DAV:read MUST NOT contain DAV:write, DAV:write-acl, DAV:write-
- properties, or DAV:write-content.
-
- DAV:write MUST contain DAV:bind, DAV:unbind, DAV:write-properties and
- DAV:write-content.
-
-4. Principal Properties
-
- Principals are manifested to clients as a WebDAV resource, identified
- by a URL. A principal MUST have a non-empty DAV:displayname property
- (defined in Section 13.2 of [RFC2518]), and a DAV:resourcetype
- property (defined in Section 13.9 of [RFC2518]). Additionally, a
- principal MUST report the DAV:principal XML element in the value of
- the DAV:resourcetype property. The element type declaration for
- DAV:principal is:
-
- <!ELEMENT principal EMPTY>
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 13]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- This protocol defines the following additional properties for a
- principal. Since it can be expensive for a server to retrieve access
- control information, the name and value of these properties SHOULD
- NOT be returned by a PROPFIND allprop request (as defined in Section
- 12.14.1 of [RFC2518]).
-
-4.1. DAV:alternate-URI-set
-
- This protected property, if non-empty, contains the URIs of network
- resources with additional descriptive information about the
- principal. This property identifies additional network resources
- (i.e., it contains one or more URIs) that may be consulted by a
- client to gain additional knowledge concerning a principal. One
- expected use for this property is the storage of an LDAP [RFC2255]
- scheme URL. A user-agent encountering an LDAP URL could use LDAP
- [RFC2251] to retrieve additional machine-readable directory
- information about the principal, and display that information in its
- user interface. Support for this property is REQUIRED, and the value
- is empty if no alternate URI exists for the principal.
-
- <!ELEMENT alternate-URI-set (href*)>
-
-4.2. DAV:principal-URL
-
- A principal may have many URLs, but there must be one "principal URL"
- that clients can use to uniquely identify a principal. This
- protected property contains the URL that MUST be used to identify
- this principal in an ACL request. Support for this property is
- REQUIRED.
-
- <!ELEMENT principal-URL (href)>
-
-4.3. DAV:group-member-set
-
- This property of a group principal identifies the principals that are
- direct members of this group. Since a group may be a member of
- another group, a group may also have indirect members (i.e., the
- members of its direct members). A URL in the DAV:group-member-set
- for a principal MUST be the DAV:principal-URL of that principal.
-
- <!ELEMENT group-member-set (href*)>
-
-4.4. DAV:group-membership
-
- This protected property identifies the groups in which the principal
- is directly a member. Note that a server may allow a group to be a
- member of another group, in which case the DAV:group-membership of
-
-
-
-
-Clemm, et al. Standards Track [Page 14]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- those other groups would need to be queried in order to determine the
- groups in which the principal is indirectly a member. Support for
- this property is REQUIRED.
-
- <!ELEMENT group-membership (href*)>
-
-5. Access Control Properties
-
- This specification defines a number of new properties for WebDAV
- resources. Access control properties may be retrieved just like
- other WebDAV properties, using the PROPFIND method. Since it is
- expensive, for many servers, to retrieve access control information,
- a PROPFIND allprop request (as defined in Section 12.14.1 of
- [RFC2518]) SHOULD NOT return the names and values of the properties
- defined in this section.
-
- Access control properties (especially DAV:acl and DAV:inherited-acl-
- set) are defined on the resource identified by the Request-URI of a
- PROPFIND request. A direct consequence is that if the resource is
- accessible via multiple URI, the value of access control properties
- is the same across these URI.
-
- HTTP resources that support the WebDAV Access Control Protocol MUST
- contain the following properties. Null resources (described in
- Section 3 of [RFC2518]) MUST NOT contain the following properties.
-
-5.1. DAV:owner
-
- This property identifies a particular principal as being the "owner"
- of the resource. Since the owner of a resource often has special
- access control capabilities (e.g., the owner frequently has permanent
- DAV:write-acl privilege), clients might display the resource owner in
- their user interface.
-
- Servers MAY implement DAV:owner as protected property and MAY return
- an empty DAV:owner element as property value in case no owner
- information is available.
-
- <!ELEMENT owner (href?)>
-
-5.1.1. Example: Retrieving DAV:owner
-
- This example shows a client request for the value of the DAV:owner
- property from a collection resource with URL http://www.example.com/
- papers/. The principal making the request is authenticated using
- Digest authentication. The value of DAV:owner is the URL http://
- www.example.com/acl/users/gstein, wrapped in the DAV:href XML
- element.
-
-
-
-Clemm, et al. Standards Track [Page 15]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="jim",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:owner/>
- </D:prop>
- </D:propfind>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:owner>
- <D:href>http://www.example.com/acl/users/gstein</D:href>
- </D:owner>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-5.1.2. Example: An Attempt to Set DAV:owner
-
- The following example shows a client request to modify the value of
- the DAV:owner property on the resource with URL <http://
- www.example.com/papers>. Since DAV:owner is a protected property on
- this particular server, it responds with a 207 (Multi-Status)
- response that contains a 403 (Forbidden) status code for the act of
- setting DAV:owner. Section 8.2.1 of [RFC2518] describes PROPPATCH
- status code information, Section 11 of [RFC2518] describes the
-
-
-
-Clemm, et al. Standards Track [Page 16]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Multi-Status response and Sections 1.6 and 3.12 of [RFC3253] describe
- additional error marshaling for PROPPATCH attempts on protected
- properties.
-
- >> Request <<
-
- PROPPATCH /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="jim",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propertyupdate xmlns:D="DAV:">
- <D:set>
- <D:prop>
- <D:owner>
- <D:href>http://www.example.com/acl/users/jim</D:href>
- </D:owner>
- </D:prop>
- </D:set>
- </D:propertyupdate>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop><D:owner/></D:prop>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- <D:responsedescription>
- <D:error><D:cannot-modify-protected-property/></D:error>
- Failure to set protected property (DAV:owner)
- </D:responsedescription>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-
-Clemm, et al. Standards Track [Page 17]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.2. DAV:group
-
- This property identifies a particular principal as being the "group"
- of the resource. This property is commonly found on repositories
- that implement the Unix privileges model.
-
- Servers MAY implement DAV:group as protected property and MAY return
- an empty DAV:group element as property value in case no group
- information is available.
-
- <!ELEMENT group (href?)>
-
-5.3. DAV:supported-privilege-set
-
- This is a protected property that identifies the privileges defined
- for the resource.
-
- <!ELEMENT supported-privilege-set (supported-privilege*)>
-
- Each privilege appears as an XML element, where aggregate privileges
- list as sub-elements all of the privileges that they aggregate.
-
- <!ELEMENT supported-privilege
- (privilege, abstract?, description, supported-privilege*)>
- <!ELEMENT privilege ANY>
-
- An abstract privilege MUST NOT be used in an ACE for that resource.
- Servers MUST fail an attempt to set an abstract privilege.
-
- <!ELEMENT abstract EMPTY>
-
- A description is a human-readable description of what this privilege
- controls access to. Servers MUST indicate the human language of the
- description using the xml:lang attribute and SHOULD consider the HTTP
- Accept-Language request header when selecting one of multiple
- available languages.
-
- <!ELEMENT description #PCDATA>
-
- It is envisioned that a WebDAV ACL-aware administrative client would
- list the supported privileges in a dialog box, and allow the user to
- choose non-abstract privileges to apply in an ACE. The privileges
- tree is useful programmatically to map well-known privileges (defined
- by WebDAV or other standards groups) into privileges that are
- supported by any particular server implementation. The privilege
- tree also serves to hide complexity in implementations allowing large
- number of privileges to be defined by displaying aggregates to the
- user.
-
-
-
-Clemm, et al. Standards Track [Page 18]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.3.1. Example: Retrieving a List of Privileges Supported on a Resource
-
- This example shows a client request for the DAV:supported-privilege-
- set property on the resource http://www.example.com/papers/. The
- value of the DAV:supported-privilege-set property is a tree of
- supported privileges (using "[XML Namespace , localname]" to identify
- each privilege):
-
- [DAV:, all] (aggregate, abstract)
- |
- +-- [DAV:, read] (aggregate)
- |
- +-- [DAV:, read-acl] (abstract)
- +-- [DAV:, read-current-user-privilege-set] (abstract)
- |
- +-- [DAV:, write] (aggregate)
- |
- +-- [DAV:, write-acl] (abstract)
- +-- [DAV:, write-properties]
- +-- [DAV:, write-content]
- |
- +-- [DAV:, unlock]
-
- This privilege tree is not normative (except that it reflects the
- normative aggregation rules given in Section 3.12), and many possible
- privilege trees are possible.
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="gclemm",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:supported-privilege-set/>
- </D:prop>
- </D:propfind>
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 19]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
-
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:supported-privilege-set>
- <D:supported-privilege>
- <D:privilege><D:all/></D:privilege>
- <D:abstract/>
- <D:description xml:lang="en">
- Any operation
- </D:description>
- <D:supported-privilege>
- <D:privilege><D:read/></D:privilege>
- <D:description xml:lang="en">
- Read any object
- </D:description>
- <D:supported-privilege>
- <D:privilege><D:read-acl/></D:privilege>
- <D:abstract/>
- <D:description xml:lang="en">Read ACL</D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege>
- <D:read-current-user-privilege-set/>
- </D:privilege>
- <D:abstract/>
- <D:description xml:lang="en">
- Read current user privilege set property
- </D:description>
- </D:supported-privilege>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:write/></D:privilege>
- <D:description xml:lang="en">
- Write any object
- </D:description>
- <D:supported-privilege>
- <D:privilege><D:write-acl/></D:privilege>
- <D:description xml:lang="en">
-
-
-
-Clemm, et al. Standards Track [Page 20]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Write ACL
- </D:description>
- <D:abstract/>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:write-properties/></D:privilege>
- <D:description xml:lang="en">
- Write properties
- </D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:write-content/></D:privilege>
- <D:description xml:lang="en">
- Write resource content
- </D:description>
- </D:supported-privilege>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:unlock/></D:privilege>
- <D:description xml:lang="en">
- Unlock resource
- </D:description>
- </D:supported-privilege>
- </D:supported-privilege>
- </D:supported-privilege-set>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-5.4. DAV:current-user-privilege-set
-
- DAV:current-user-privilege-set is a protected property containing the
- exact set of privileges (as computed by the server) granted to the
- currently authenticated HTTP user. Aggregate privileges and their
- contained privileges are listed. A user-agent can use the value of
- this property to adjust its user interface to make actions
- inaccessible (e.g., by graying out a menu item or button) for which
- the current principal does not have permission. This property is
- also useful for determining what operations the current principal can
- perform, without having to actually execute an operation.
-
- <!ELEMENT current-user-privilege-set (privilege*)>
- <!ELEMENT privilege ANY>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 21]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- If the current user is granted a specific privilege, that privilege
- must belong to the set of privileges that may be set on this
- resource. Therefore, each element in the DAV:current-user-
- privilege-set property MUST identify a non-abstract privilege from
- the DAV:supported-privilege-set property.
-
-5.4.1. Example: Retrieving the User's Current Set of Assigned
- Privileges
-
- Continuing the example from Section 5.3.1, this example shows a
- client requesting the DAV:current-user-privilege-set property from
- the resource with URL http://www.example.com/papers/. The username
- of the principal making the request is "khare", and Digest
- authentication is used in the request. The principal with username
- "khare" has been granted the DAV:read privilege. Since the DAV:read
- privilege contains the DAV:read-acl and DAV:read-current-user-
- privilege-set privileges (see Section 5.3.1), the principal with
- username "khare" can read the ACL property, and the DAV:current-
- user-privilege-set property. However, the DAV:all, DAV:read-acl,
- DAV:write-acl and DAV:read-current-user-privilege-set privileges are
- not listed in the value of DAV:current-user-privilege-set, since (for
- this example) they are abstract privileges. DAV:write is not listed
- since the principal with username "khare" is not listed in an ACE
- granting that principal write permission.
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="khare",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:current-user-privilege-set/>
- </D:prop>
- </D:propfind>
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 22]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:current-user-privilege-set>
- <D:privilege><D:read/></D:privilege>
- </D:current-user-privilege-set>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-5.5. DAV:acl
-
- This is a protected property that specifies the list of access
- control entries (ACEs), which define what principals are to get what
- privileges for this resource.
-
- <!ELEMENT acl (ace*) >
-
- Each DAV:ace element specifies the set of privileges to be either
- granted or denied to a single principal. If the DAV:acl property is
- empty, no principal is granted any privilege.
-
- <!ELEMENT ace ((principal | invert), (grant|deny), protected?,
- inherited?)>
-
-5.5.1. ACE Principal
-
- The DAV:principal element identifies the principal to which this ACE
- applies.
-
- <!ELEMENT principal (href | all | authenticated | unauthenticated
- | property | self)>
-
- The current user matches DAV:href only if that user is authenticated
- as being (or being a member of) the principal identified by the URL
- contained by that DAV:href.
-
-
-
-
-Clemm, et al. Standards Track [Page 23]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The current user always matches DAV:all.
-
- <!ELEMENT all EMPTY>
-
- The current user matches DAV:authenticated only if authenticated.
-
- <!ELEMENT authenticated EMPTY>
-
- The current user matches DAV:unauthenticated only if not
- authenticated.
-
- <!ELEMENT unauthenticated EMPTY>
-
- DAV:all is the union of DAV:authenticated, and DAV:unauthenticated.
- For a given request, the user matches either DAV:authenticated, or
- DAV:unauthenticated, but not both (that is, DAV:authenticated and
- DAV:unauthenticated are disjoint sets).
-
- The current user matches a DAV:property principal in a DAV:acl
- property of a resource only if the value of the identified property
- of that resource contains at most one DAV:href XML element, the URI
- value of DAV:href identifies a principal, and the current user is
- authenticated as being (or being a member of) that principal. For
- example, if the DAV:property element contained <DAV:owner/>, the
- current user would match the DAV:property principal only if the
- current user is authenticated as matching the principal identified by
- the DAV:owner property of the resource.
-
- <!ELEMENT property ANY>
-
- The current user matches DAV:self in a DAV:acl property of the
- resource only if that resource is a principal and that principal
- matches the current user or, if the principal is a group, a member of
- that group matches the current user.
-
- <!ELEMENT self EMPTY>
-
- Some servers may support ACEs applying to those users NOT matching
- the current principal, e.g., all users not in a particular group.
- This can be done by wrapping the DAV:principal element with
- DAV:invert.
-
- <!ELEMENT invert principal>
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 24]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.5.2. ACE Grant and Deny
-
- Each DAV:grant or DAV:deny element specifies the set of privileges to
- be either granted or denied to the specified principal. A DAV:grant
- or DAV:deny element of the DAV:acl of a resource MUST only contain
- non-abstract elements specified in the DAV:supported-privilege-set of
- that resource.
-
- <!ELEMENT grant (privilege+)>
- <!ELEMENT deny (privilege+)>
- <!ELEMENT privilege ANY>
-
-5.5.3. ACE Protection
-
- A server indicates an ACE is protected by including the DAV:protected
- element in the ACE. If the ACL of a resource contains an ACE with a
- DAV:protected element, an attempt to remove that ACE from the ACL
- MUST fail.
-
- <!ELEMENT protected EMPTY>
-
-5.5.4. ACE Inheritance
-
- The presence of a DAV:inherited element indicates that this ACE is
- inherited from another resource that is identified by the URL
- contained in a DAV:href element. An inherited ACE cannot be modified
- directly, but instead the ACL on the resource from which it is
- inherited must be modified.
-
- Note that ACE inheritance is not the same as ACL initialization. ACL
- initialization defines the ACL that a newly created resource will use
- (if not specified). ACE inheritance refers to an ACE that is
- logically shared - where an update to the resource containing an ACE
- will affect the ACE of each resource that inherits that ACE. The
- method by which ACLs are initialized or by which ACEs are inherited
- is not defined by this document.
-
- <!ELEMENT inherited (href)>
-
-5.5.5. Example: Retrieving a Resource's Access Control List
-
- Continuing the example from Sections 5.3.1 and 5.4.1, this example
- shows a client requesting the DAV:acl property from the resource with
- URL http://www.example.com/papers/. There are two ACEs defined in
- this ACL:
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 25]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- ACE #1: The group identified by URL http://www.example.com/acl/
- groups/maintainers (the group of site maintainers) is granted
- DAV:write privilege. Since (for this example) DAV:write contains the
- DAV:write-acl privilege (see Section 5.3.1), this means the
- "maintainers" group can also modify the access control list.
-
- ACE #2: All principals (DAV:all) are granted the DAV:read privilege.
- Since (for this example) DAV:read contains DAV:read-acl and
- DAV:read-current-user-privilege-set, this means all users (including
- all members of the "maintainers" group) can read the DAV:acl property
- and the DAV:current-user-privilege-set property.
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="masinter",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:acl/>
- </D:prop>
- </D:propfind>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:acl>
- <D:ace>
- <D:principal>
- <D:href
- >http://www.example.com/acl/groups/maintainers</D:href>
- </D:principal>
- <D:grant>
- <D:privilege><D:write/></D:privilege>
-
-
-
-Clemm, et al. Standards Track [Page 26]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- </D:grant>
- </D:ace>
- <D:ace>
- <D:principal>
- <D:all/>
- </D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- </D:grant>
- </D:ace>
- </D:acl>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-5.6. DAV:acl-restrictions
-
- This protected property defines the types of ACLs supported by this
- server, to avoid clients needlessly getting errors. When a client
- tries to set an ACL via the ACL method, the server may reject the
- attempt to set the ACL as specified. The following properties
- indicate the restrictions the client must observe before setting an
- ACL:
-
- <grant-only> Deny ACEs are not supported
-
- <no-invert> Inverted ACEs are not supported
-
- <deny-before-grant> All deny ACEs must occur before any grant ACEs
-
- <required-principal> Indicates which principals are required to be
- present
-
-
- <!ELEMENT acl-restrictions (grant-only?, no-invert?,
- deny-before-grant?,
- required-principal?)>
-
-5.6.1. DAV:grant-only
-
- This element indicates that ACEs with deny clauses are not allowed.
-
- <!ELEMENT grant-only EMPTY>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 27]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.6.2. DAV:no-invert ACE Constraint
-
- This element indicates that ACEs with the <invert> element are not
- allowed.
-
- <!ELEMENT no-invert EMPTY>
-
-5.6.3. DAV:deny-before-grant
-
- This element indicates that all deny ACEs must precede all grant
- ACEs.
-
- <!ELEMENT deny-before-grant EMPTY>
-
-5.6.4. Required Principals
-
- The required principal elements identify which principals must have
- an ACE defined in the ACL.
-
- <!ELEMENT required-principal
- (all? | authenticated? | unauthenticated? | self? | href* |
- property*)>
-
- For example, the following element requires that the ACL contain a
-
- DAV:owner property ACE:
-
- <D:required-principal xmlns:D="DAV:">
- <D:property><D:owner/></D:property>
- </D:required-principal>
-
-5.6.5. Example: Retrieving DAV:acl-restrictions
-
- In this example, the client requests the value of the DAV:acl-
- restrictions property. Digest authentication provides credentials
- for the principal operating the client.
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="srcarter",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
-
-
-
-Clemm, et al. Standards Track [Page 28]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:acl-restrictions/>
- </D:prop>
- </D:propfind>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:acl-restrictions>
- <D:grant-only/>
- <D:required-principal>
- <D:all/>
- </D:required-principal>
- </D:acl-restrictions>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-5.7. DAV:inherited-acl-set
-
- This protected property contains a set of URLs that identify other
- resources that also control the access to this resource. To have a
- privilege on a resource, not only must the ACL on that resource
- (specified in the DAV:acl property of that resource) grant the
- privilege, but so must the ACL of each resource identified in the
- DAV:inherited-acl-set property of that resource. Effectively, the
- privileges granted by the current ACL are ANDed with the privileges
- granted by each inherited ACL.
-
- <!ELEMENT inherited-acl-set (href*)>
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 29]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.8. DAV:principal-collection-set
-
- This protected property of a resource contains a set of URLs that
- identify the root collections that contain the principals that are
- available on the server that implements this resource. A WebDAV
- Access Control Protocol user agent could use the contents of
- DAV:principal-collection-set to retrieve the DAV:displayname property
- (specified in Section 13.2 of [RFC2518]) of all principals on that
- server, thereby yielding human-readable names for each principal that
- could be displayed in a user interface.
-
- <!ELEMENT principal-collection-set (href*)>
-
- Since different servers can control different parts of the URL
- namespace, different resources on the same host MAY have different
- DAV:principal-collection-set values. The collections specified in
- the DAV:principal-collection-set MAY be located on different hosts
- from the resource. The URLs in DAV:principal-collection-set SHOULD be
- http or https scheme URLs. For security and scalability reasons, a
- server MAY report only a subset of the entire set of known principal
- collections, and therefore clients should not assume they have
- retrieved an exhaustive listing. Additionally, a server MAY elect to
- report none of the principal collections it knows about, in which
- case the property value would be empty.
-
- The value of DAV:principal-collection-set gives the scope of the
- DAV:principal-property-search REPORT (defined in Section 9.4).
- Clients use the DAV:principal-property-search REPORT to populate
- their user interface with a list of principals. Therefore, servers
- that limit a client's ability to obtain principal information will
- interfere with the client's ability to manipulate access control
- lists, due to the difficulty of getting the URL of a principal for
- use in an ACE.
-
-5.8.1. Example: Retrieving DAV:principal-collection-set
-
- In this example, the client requests the value of the DAV:principal-
- collection-set property on the collection resource identified by URL
- http://www.example.com/papers/. The property contains the two URLs,
- http://www.example.com/acl/users/ and http://
- www.example.com/acl/groups/, both wrapped in DAV:href XML elements.
- Digest authentication provides credentials for the principal
- operating the client.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 30]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The client might reasonably follow this request with two separate
- PROPFIND requests to retrieve the DAV:displayname property of the
- members of the two collections (/acl/users and /acl/groups). This
- information could be used when displaying a user interface for
- creating access control entries.
-
- >> Request <<
-
- PROPFIND /papers/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="yarong",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:principal-collection-set/>
- </D:prop>
- </D:propfind>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/papers/</D:href>
- <D:propstat>
- <D:prop>
- <D:principal-collection-set>
- <D:href>http://www.example.com/acl/users/</D:href>
- <D:href>http://www.example.com/acl/groups/</D:href>
- </D:principal-collection-set>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 31]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-5.9. Example: PROPFIND to retrieve access control properties
-
- The following example shows how access control information can be
- retrieved by using the PROPFIND method to fetch the values of the
- DAV:owner, DAV:supported-privilege-set, DAV:current-user-privilege-
- set, and DAV:acl properties.
-
- >> Request <<
-
- PROPFIND /top/container/ HTTP/1.1
- Host: www.example.com
- Content-type: text/xml; charset="utf-8"
- Content-Length: xxx
- Depth: 0
- Authorization: Digest username="ejw",
- realm="users at example.com", nonce="...",
- uri="/top/container/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:propfind xmlns:D="DAV:">
- <D:prop>
- <D:owner/>
- <D:supported-privilege-set/>
- <D:current-user-privilege-set/>
- <D:acl/>
- </D:prop>
- </D:propfind>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:"
- xmlns:A="http://www.example.com/acl/">
- <D:response>
- <D:href>http://www.example.com/top/container/</D:href>
- <D:propstat>
- <D:prop>
- <D:owner>
- <D:href>http://www.example.com/users/gclemm</D:href>
- </D:owner>
- <D:supported-privilege-set>
- <D:supported-privilege>
- <D:privilege><D:all/></D:privilege>
- <D:abstract/>
-
-
-
-Clemm, et al. Standards Track [Page 32]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:description xml:lang="en">
- Any operation
- </D:description>
- <D:supported-privilege>
- <D:privilege><D:read/></D:privilege>
- <D:description xml:lang="en">
- Read any object
- </D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:write/></D:privilege>
- <D:abstract/>
- <D:description xml:lang="en">
- Write any object
- </D:description>
- <D:supported-privilege>
- <D:privilege><A:create/></D:privilege>
- <D:description xml:lang="en">
- Create an object
- </D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><A:update/></D:privilege>
- <D:description xml:lang="en">
- Update an object
- </D:description>
- </D:supported-privilege>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><A:delete/></D:privilege>
- <D:description xml:lang="en">
- Delete an object
- </D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:read-acl/></D:privilege>
- <D:description xml:lang="en">
- Read the ACL
- </D:description>
- </D:supported-privilege>
- <D:supported-privilege>
- <D:privilege><D:write-acl/></D:privilege>
- <D:description xml:lang="en">
- Write the ACL
- </D:description>
- </D:supported-privilege>
- </D:supported-privilege>
- </D:supported-privilege-set>
-
-
-
-Clemm, et al. Standards Track [Page 33]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:current-user-privilege-set>
- <D:privilege><D:read/></D:privilege>
- <D:privilege><D:read-acl/></D:privilege>
- </D:current-user-privilege-set>
- <D:acl>
- <D:ace>
- <D:principal>
- <D:href>http://www.example.com/users/esedlar</D:href>
- </D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- <D:privilege><D:write/></D:privilege>
- <D:privilege><D:read-acl/></D:privilege>
- </D:grant>
- </D:ace>
- <D:ace>
- <D:principal>
- <D:href>http://www.example.com/groups/mrktng</D:href>
- </D:principal>
- <D:deny>
- <D:privilege><D:read/></D:privilege>
- </D:deny>
- </D:ace>
- <D:ace>
- <D:principal>
- <D:property><D:owner/></D:property>
- </D:principal>
- <D:grant>
- <D:privilege><D:read-acl/></D:privilege>
- <D:privilege><D:write-acl/></D:privilege>
- </D:grant>
- </D:ace>
- <D:ace>
- <D:principal><D:all/></D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- </D:grant>
- <D:inherited>
- <D:href>http://www.example.com/top</D:href>
- </D:inherited>
- </D:ace>
- </D:acl>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-
-
-
-Clemm, et al. Standards Track [Page 34]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The value of the DAV:owner property is a single DAV:href XML element
- containing the URL of the principal that owns this resource.
-
- The value of the DAV:supported-privilege-set property is a tree of
- supported privileges (using "[XML Namespace , localname]" to identify
- each privilege):
-
- [DAV:, all] (aggregate, abstract)
- |
- +-- [DAV:, read]
- +-- [DAV:, write] (aggregate, abstract)
- |
- +-- [http://www.example.com/acl, create]
- +-- [http://www.example.com/acl, update]
- +-- [http://www.example.com/acl, delete]
- +-- [DAV:, read-acl]
- +-- [DAV:, write-acl]
-
- The DAV:current-user-privilege-set property contains two privileges,
- DAV:read, and DAV:read-acl. This indicates that the current
- authenticated user only has the ability to read the resource, and
- read the DAV:acl property on the resource. The DAV:acl property
- contains a set of four ACEs:
-
- ACE #1: The principal identified by the URL http://www.example.com/
- users/esedlar is granted the DAV:read, DAV:write, and DAV:read-acl
- privileges.
-
- ACE #2: The principals identified by the URL http://www.example.com/
- groups/mrktng are denied the DAV:read privilege. In this example,
- the principal URL identifies a group.
-
- ACE #3: In this ACE, the principal is a property principal,
- specifically the DAV:owner property. When evaluating this ACE, the
- value of the DAV:owner property is retrieved, and is examined to see
- if it contains a DAV:href XML element. If so, the URL within the
- DAV:href element is read, and identifies a principal. In this ACE,
- the owner is granted DAV:read-acl, and DAV:write-acl privileges.
-
- ACE #4: This ACE grants the DAV:all principal (all users) the
- DAV:read privilege. This ACE is inherited from the resource http://
- www.example.com/top, the parent collection of this resource.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 35]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-6. ACL Evaluation
-
- WebDAV ACLs are evaluated in similar manner as ACLs on Windows NT and
- in NFSv4 [RFC3530]). An ACL is evaluated to determine whether or not
- access will be granted for a WebDAV request. ACEs are maintained in
- a particular order, and are evaluated until all of the permissions
- required by the current request have been granted, at which point the
- ACL evaluation is terminated and access is granted. If, during ACL
- evaluation, a <deny> ACE (matching the current user) is encountered
- for a privilege which has not yet been granted, the ACL evaluation is
- terminated and access is denied. Failure to have all required
- privileges granted results in access being denied.
-
- Note that the semantics of many other existing ACL systems may be
- represented via this mechanism, by mixing deny and grant ACEs. For
- example, consider the standard "rwx" privilege scheme used by UNIX.
- In this scheme, if the current user is the owner of the file, access
- is granted if the corresponding privilege bit is set and denied if
- not set, regardless of the permissions set on the file's group and
- for the world. An ACL for UNIX permissions of "r--rw-r--" might be
- constructed like:
-
- <D:acl>
- <D:ace>
- <D:principal>
- <D:property><D:owner/></D:property>
- </D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- </D:grant>
- </D:ace>
- <D:ace>
- <D:principal>
- <D:property><D:owner/></D:property>
- </D:principal>
- <D:deny>
- <D:privilege><D:all/></D:privilege>
- </D:deny>
- </D:ace>
- <D:ace>
- <D:principal>
- <D:property><D:group/></D:property>
- </D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- <D:privilege><D:write/></D:privilege>
- </D:grant>
- </D:ace>
-
-
-
-Clemm, et al. Standards Track [Page 36]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:ace>
- <D:principal>
- <D:property><D:group/></D:property>
- </D:principal>
- <D:deny>
- <D:privilege><D:all/></D:privilege>
- </D:deny>
- </D:ace>
- <D:ace>
- <D:principal><D:all></D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- </D:grant>
- </D:ace>
- </D:acl>
-
- and the <acl-restrictions> would be defined as:
-
- <D:no-invert/>
- <D:required-principal>
- <D:all/>
- <D:property><D:owner/></D:property>
- <D:property><D:group/><D:group/>
- </D:required-principal>
-
- Note that the client can still get errors from a UNIX server in spite
- of obeying the <acl-restrictions>, including <D:allowed-principal>
- (adding an ACE specifying a principal other than the ones in the ACL
- above) or <D:ace-conflict> (by trying to reorder the ACEs in the
- example above), as these particular implementation semantics are too
- complex to be captured with the simple (but general) declarative
- restrictions.
-
-7. Access Control and existing methods
-
- This section defines the impact of access control functionality on
- existing methods.
-
-7.1. Any HTTP method
-
-7.1.1. Error Handling
-
- The WebDAV ACL mechanism requires the usage of HTTP method
- "preconditions" as described in section 1.6 of RFC3253 for ALL HTTP
- methods. All HTTP methods have an additional precondition called
- DAV:need-privileges. If an HTTP method fails due to insufficient
- privileges, the response body to the "403 Forbidden" error MUST
- contain the <DAV:error> element, which in turn contains the
-
-
-
-Clemm, et al. Standards Track [Page 37]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <DAV:need-privileges> element, which contains one or more
- <DAV:resource> elements indicating which resource had insufficient
- privileges, and what the lacking privileges were:
-
- <!ELEMENT need-privileges (resource)* >
- <!ELEMENT resource ( href , privilege ) >
-
- Since some methods require multiple permissions on multiple
- resources, this information is needed to resolve any ambiguity.
- There is no requirement that all privilege violations be reported -
- for implementation reasons, some servers may only report the first
- privilege violation. For example:
-
- >> Request <<
-
- MOVE /a/b/ HTTP/1.1
- Host: www.example.com
- Destination: http://www.example.com/c/d
-
- >> Response <<
-
- HTTP/1.1 403 Forbidden
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <D:error xmlns:D="DAV:">
- <D:need-privileges>
- <D:resource>
- <D:href>/a</D:href>
- <D:privilege><D:unbind/></D:privilege>
- </D:resource>
- <D:resource>
- <D:href>/c</D:href>
- <D:privilege><D:bind/></D:privilege>
- </D:resource>
- </D:need-privileges>
- </D:error>
-
-7.2. OPTIONS
-
- If the server supports access control, it MUST return "access-
- control" as a field in the DAV response header from an OPTIONS
- request on any resource implemented by that server. A value of
- "access-control" in the DAV header MUST indicate that the server
- supports all MUST level requirements and REQUIRED features specified
- in this document.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 38]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-7.2.1. Example - OPTIONS
-
- >> Request <<
-
- OPTIONS /foo.html HTTP/1.1
- Host: www.example.com
- Content-Length: 0
-
- >> Response <<
-
- HTTP/1.1 200 OK
- DAV: 1, 2, access-control
- Allow: OPTIONS, GET, PUT, PROPFIND, PROPPATCH, ACL
-
- In this example, the OPTIONS response indicates that the server
- supports access control and that /foo.html can have its access
- control list modified by the ACL method.
-
-7.3. MOVE
-
- When a resource is moved from one location to another due to a MOVE
- request, the non-inherited and non-protected ACEs in the DAV:acl
- property of the resource MUST NOT be modified, or the MOVE request
- fails. Handling of inherited and protected ACEs is intentionally
- undefined to give server implementations flexibility in how they
- implement ACE inheritance and protection.
-
-7.4. COPY
-
- The DAV:acl property on the resource at the destination of a COPY
- MUST be the same as if the resource was created by an individual
- resource creation request (e.g., MKCOL, PUT). Clients wishing to
- preserve the DAV:acl property across a copy need to read the DAV:acl
- property prior to the COPY, then perform an ACL operation on the new
- resource at the destination to restore, insofar as this is possible,
- the original access control list.
-
-7.5. LOCK
-
- A lock on a resource ensures that only the lock owner can modify ACEs
- that are not inherited and not protected (these are the only ACEs
- that a client can modify with an ACL request). A lock does not
- protect inherited or protected ACEs, since a client cannot modify
- them with an ACL request on that resource.
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 39]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-8. Access Control Methods
-
-8.1. ACL
-
- The ACL method modifies the access control list (which can be read
- via the DAV:acl property) of a resource. Specifically, the ACL
- method only permits modification to ACEs that are not inherited, and
- are not protected. An ACL method invocation modifies all non-
- inherited and non-protected ACEs in a resource's access control list
- to exactly match the ACEs contained within in the DAV:acl XML element
- (specified in Section 5.5) of the request body. An ACL request body
- MUST contain only one DAV:acl XML element. Unless the non-inherited
- and non-protected ACEs of the DAV:acl property of the resource can be
- updated to be exactly the value specified in the ACL request, the ACL
- request MUST fail.
-
- It is possible that the ACEs visible to the current user in the
- DAV:acl property may only be a portion of the complete set of ACEs on
- that resource. If this is the case, an ACL request only modifies the
- set of ACEs visible to the current user, and does not affect any
- non-visible ACE.
-
- In order to avoid overwriting DAV:acl changes by another client, a
- client SHOULD acquire a WebDAV lock on the resource before retrieving
- the DAV:acl property of a resource that it intends on updating.
-
- Implementation Note: Two common operations are to add or remove an
- ACE from an existing access control list. To accomplish this, a
- client uses the PROPFIND method to retrieve the value of the
- DAV:acl property, then parses the returned access control list to
- remove all inherited and protected ACEs (these ACEs are tagged
- with the DAV:inherited and DAV:protected XML elements). In the
- remaining set of non-inherited, non-protected ACEs, the client can
- add or remove one or more ACEs before submitting the final ACE set
- in the request body of the ACL method.
-
-8.1.1. ACL Preconditions
-
- An implementation MUST enforce the following constraints on an ACL
- request. If the constraint is violated, a 403 (Forbidden) or 409
- (Conflict) response MUST be returned and the indicated XML element
- MUST be returned as a child of a top level DAV:error element in an
- XML response body.
-
- Though these status elements are generally expressed as empty XML
- elements (and are defined as EMPTY in the DTD), implementations MAY
- return additional descriptive XML elements as children of the status
-
-
-
-
-Clemm, et al. Standards Track [Page 40]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- element. Clients MUST be able to accept children of these status
- elements. Clients that do not understand the additional XML elements
- should ignore them.
-
- (DAV:no-ace-conflict): The ACEs submitted in the ACL request MUST NOT
- conflict with each other. This is a catchall error code indicating
- that an implementation-specific ACL restriction has been violated.
-
- (DAV:no-protected-ace-conflict): The ACEs submitted in the ACL
- request MUST NOT conflict with the protected ACEs on the resource.
- For example, if the resource has a protected ACE granting DAV:write
- to a given principal, then it would not be consistent if the ACL
- request submitted an ACE denying DAV:write to the same principal.
-
- (DAV:no-inherited-ace-conflict): The ACEs submitted in the ACL
- request MUST NOT conflict with the inherited ACEs on the resource.
- For example, if the resource inherits an ACE from its parent
- collection granting DAV:write to a given principal, then it would not
- be consistent if the ACL request submitted an ACE denying DAV:write
- to the same principal. Note that reporting of this error will be
- implementation-dependent. Implementations MUST either report this
- error or allow the ACE to be set, and then let normal ACE evaluation
- rules determine whether the new ACE has any impact on the privileges
- available to a specific principal.
-
- (DAV:limited-number-of-aces): The number of ACEs submitted in the ACL
- request MUST NOT exceed the number of ACEs allowed on that resource.
- However, ACL-compliant servers MUST support at least one ACE granting
- privileges to a single principal, and one ACE granting privileges to
- a group.
-
- (DAV:deny-before-grant): All non-inherited deny ACEs MUST precede all
- non-inherited grant ACEs.
-
- (DAV:grant-only): The ACEs submitted in the ACL request MUST NOT
- include a deny ACE. This precondition applies only when the ACL
- restrictions of the resource include the DAV:grant-only constraint
- (defined in Section 5.6.1).
-
- (DAV:no-invert): The ACL request MUST NOT include a DAV:invert
- element. This precondition applies only when the ACL semantics of
- the resource includes the DAV:no-invert constraint (defined in
- Section 5.6.2).
-
- (DAV:no-abstract): The ACL request MUST NOT attempt to grant or deny
- an abstract privilege (see Section 5.3).
-
-
-
-
-
-Clemm, et al. Standards Track [Page 41]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- (DAV:not-supported-privilege): The ACEs submitted in the ACL request
- MUST be supported by the resource.
-
- (DAV:missing-required-principal): The result of the ACL request MUST
- have at least one ACE for each principal identified in a
- DAV:required-principal XML element in the ACL semantics of that
- resource (see Section 5.5).
-
- (DAV:recognized-principal): Every principal URL in the ACL request
- MUST identify a principal resource.
-
- (DAV:allowed-principal): The principals specified in the ACEs
- submitted in the ACL request MUST be allowed as principals for the
- resource. For example, a server where only authenticated principals
- can access resources would not allow the DAV:all or
- DAV:unauthenticated principals to be used in an ACE, since these
- would allow unauthenticated access to resources.
-
-8.1.2. Example: the ACL method
-
- In the following example, user "fielding", authenticated by
- information in the Authorization header, grants the principal
- identified by the URL http://www.example.com/users/esedlar (i.e., the
- user "esedlar") read and write privileges, grants the owner of the
- resource read-acl and write-acl privileges, and grants everyone read
- privileges.
-
- >> Request <<
-
- ACL /top/container/ HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="fielding",
- realm="users at example.com", nonce="...",
- uri="/top/container/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:acl xmlns:D="DAV:">
- <D:ace>
- <D:principal>
- <D:href>http://www.example.com/users/esedlar</D:href>
- </D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- <D:privilege><D:write/></D:privilege>
- </D:grant>
- </D:ace>
-
-
-
-Clemm, et al. Standards Track [Page 42]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:ace>
- <D:principal>
- <D:property><D:owner/></D:property>
- </D:principal>
- <D:grant>
- <D:privilege><D:read-acl/></D:privilege>
- <D:privilege><D:write-acl/></D:privilege>
- </D:grant>
- </D:ace>
- <D:ace>
- <D:principal><D:all/></D:principal>
- <D:grant>
- <D:privilege><D:read/></D:privilege>
- </D:grant>
- </D:ace>
- </D:acl>
-
- >> Response <<
-
- HTTP/1.1 200 OK
-
-8.1.3. Example: ACL method failure due to protected ACE conflict
-
- In the following request, user "fielding", authenticated by
- information in the Authorization header, attempts to deny the
- principal identified by the URL http://www.example.com/users/esedlar
- (i.e., the user "esedlar") write privileges. Prior to the request,
- the DAV:acl property on the resource contained a protected ACE (see
- Section 5.5.3) granting DAV:owner the DAV:read and DAV:write
- privileges. The principal identified by URL http://www.example.com/
- users/esedlar is the owner of the resource. The ACL method
- invocation fails because the submitted ACE conflicts with the
- protected ACE, thus violating the semantics of ACE protection.
-
- >> Request <<
-
- ACL /top/container/ HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="fielding",
- realm="users at example.com", nonce="...",
- uri="/top/container/", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:acl xmlns:D="DAV:">
- <D:ace>
- <D:principal>
-
-
-
-Clemm, et al. Standards Track [Page 43]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:href>http://www.example.com/users/esedlar</D:href>
- </D:principal>
- <D:deny>
- <D:privilege><D:write/></D:privilege>
- </D:deny>
- </D:ace>
- </D:acl>
-
- >> Response <<
-
- HTTP/1.1 403 Forbidden
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:no-protected-ace-conflict/>
- </D:error>
-
-8.1.4. Example: ACL method failure due to an inherited ACE conflict
-
- In the following request, user "ejw", authenticated by information in
- the Authorization header, tries to change the access control list on
- the resource http://www.example.com/top/index.html. This resource
- has two inherited ACEs.
-
- Inherited ACE #1 grants the principal identified by URL http://
- www.example.com/users/ejw (i.e., the user "ejw") http://
- www.example.com/privs/write-all and DAV:read-acl privileges. On this
- server, http://www.example.com/privs/write-all is an aggregate
- privilege containing DAV:write, and DAV:write-acl.
-
- Inherited ACE #2 grants principal DAV:all the DAV:read privilege.
-
- The request attempts to set a (non-inherited) ACE, denying the
- principal identified by the URL http://www.example.com/users/ejw
- (i.e., the user "ejw") DAV:write permission. This conflicts with
- inherited ACE #1. Note that the decision to report an inherited ACE
- conflict is specific to this server implementation. Another server
- implementation could have allowed the new ACE to be set, and then
- used normal ACE evaluation rules to determine whether the new ACE has
- any impact on the privileges available to a principal.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 44]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Request <<
-
- ACL /top/index.html HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ejw",
- realm="users at example.com", nonce="...",
- uri="/top/index.html", response="...", opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:acl xmlns:D="DAV:" xmlns:F="http://www.example.com/privs/">
- <D:ace>
- <D:principal>
- <D:href>http://www.example.com/users/ejw</D:href>
- </D:principal>
- <D:grant><D:write/></D:grant>
- </D:ace>
- </D:acl>
-
- >> Response <<
-
- HTTP/1.1 403 Forbidden
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:error xmlns:D="DAV:">
- <D:no-inherited-ace-conflict/>
- </D:error>
-
-8.1.5. Example: ACL method failure due to an attempt to set grant and
- deny in a single ACE
-
- In this example, user "ygoland", authenticated by information in the
- Authorization header, tries to change the access control list on the
- resource http://www.example.com/diamond/engagement-ring.gif. The ACL
- request includes a single, syntactically and semantically incorrect
- ACE, which attempts to grant the group identified by the URL http://
- www.example.com/users/friends DAV:read privilege and deny the
- principal identified by URL http://www.example.com/users/ygoland-so
- (i.e., the user "ygoland-so") DAV:read privilege. However, it is
- illegal to have multiple principal elements, as well as both a grant
- and deny element in the same ACE, so the request fails due to poor
- syntax.
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 45]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Request <<
-
- ACL /diamond/engagement-ring.gif HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Authorization: Digest username="ygoland",
- realm="users at example.com", nonce="...",
- uri="/diamond/engagement-ring.gif", response="...",
- opaque="..."
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:acl xmlns:D="DAV:">
- <D:ace>
- <D:principal>
- <D:href>http://www.example.com/users/friends</D:href>
- </D:principal>
- <D:grant><D:read/></D:grant>
- <D:principal>
- <D:href>http://www.example.com/users/ygoland-so</D:href>
- </D:principal>
- <D:deny><D:read/></D:deny>
- </D:ace>
- </D:acl>
-
- >> Response <<
-
- HTTP/1.1 400 Bad Request
- Content-Length: 0
-
- Note that if the request had been divided into two ACEs, one to
- grant, and one to deny, the request would have been syntactically
- well formed.
-
-9. Access Control Reports
-
-9.1. REPORT Method
-
- The REPORT method (defined in Section 3.6 of [RFC3253]) provides an
- extensible mechanism for obtaining information about a resource.
- Unlike the PROPFIND method, which returns the value of one or more
- named properties, the REPORT method can involve more complex
- processing. REPORT is valuable in cases where the server has access
- to all of the information needed to perform the complex request (such
- as a query), and where it would require multiple requests for the
- client to retrieve the information needed to perform the same
- request.
-
-
-
-
-Clemm, et al. Standards Track [Page 46]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- A server that supports the WebDAV Access Control Protocol MUST
- support the DAV:expand-property report (defined in Section 3.8 of
- [RFC3253]).
-
-9.2. DAV:acl-principal-prop-set Report
-
- The DAV:acl-principal-prop-set report returns, for all principals in
- the DAV:acl property (of the Request-URI) that are identified by
- http(s) URLs or by a DAV:property principal, the value of the
- properties specified in the REPORT request body. In the case where a
- principal URL appears multiple times, the DAV:acl-principal-prop-set
- report MUST return the properties for that principal only once.
- Support for this report is REQUIRED.
-
- One expected use of this report is to retrieve the human readable
- name (found in the DAV:displayname property) of each principal found
- in an ACL. This is useful for constructing user interfaces that show
- each ACE in a human readable form.
-
- Marshalling
-
- The request body MUST be a DAV:acl-principal-prop-set XML element.
-
- <!ELEMENT acl-principal-prop-set ANY>
- ANY value: a sequence of one or more elements, with at most one
- DAV:prop element.
- prop: see RFC 2518, Section 12.11
-
- This report is only defined when the Depth header has value "0";
- other values result in a 400 (Bad Request) error response. Note
- that [RFC3253], Section 3.6, states that if the Depth header is
- not present, it defaults to a value of "0".
-
- The response body for a successful request MUST be a
- DAV:multistatus XML element (i.e., the response uses the same
- format as the response for PROPFIND). In the case where there are
- no response elements, the returned multistatus XML element is
- empty.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response body for a successful DAV:acl-principal-prop-set
- REPORT request MUST contain a DAV:response element for each
- principal identified by an http(s) URL listed in a DAV:principal
- XML element of an ACE within the DAV:acl property of the resource
- identified by the Request-URI.
-
-
-
-
-
-Clemm, et al. Standards Track [Page 47]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Postconditions:
-
- (DAV:number-of-matches-within-limits): The number of matching
- principals must fall within server-specific, predefined limits.
- For example, this condition might be triggered if a search
- specification would cause the return of an extremely large number
- of responses.
-
-9.2.1. Example: DAV:acl-principal-prop-set Report
-
- Resource http://www.example.com/index.html has an ACL with three
- ACEs:
-
- ACE #1: All principals (DAV:all) have DAV:read and DAV:read-current-
- user-privilege-set access.
-
- ACE #2: The principal identified by http://www.example.com/people/
- gstein (the user "gstein") is granted DAV:write, DAV:write-acl,
- DAV:read-acl privileges.
-
- ACE #3: The group identified by http://www.example.com/groups/authors
- (the "authors" group) is granted DAV:write and DAV:read-acl
- privileges.
-
- The following example shows a DAV:acl-principal-prop-set report
- requesting the DAV:displayname property. It returns the value of
- DAV:displayname for resources http://www.example.com/people/gstein
- and http://www.example.com/groups/authors , but not for DAV:all,
- since this is not an http(s) URL.
-
- >> Request <<
-
- REPORT /index.html HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Depth: 0
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:acl-principal-prop-set xmlns:D="DAV:">
- <D:prop>
- <D:displayname/>
- </D:prop>
- </D:acl-principal-prop-set>
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 48]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/people/gstein</D:href>
- <D:propstat>
- <D:prop>
- <D:displayname>Greg Stein</D:displayname>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://www.example.com/groups/authors</D:href>
- <D:propstat>
- <D:prop>
- <D:displayname>Site authors</D:displayname>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-9.3. DAV:principal-match REPORT
-
- The DAV:principal-match REPORT is used to identify all members (at
- any depth) of the collection identified by the Request-URI that are
- principals and that match the current user. In particular, if the
- collection contains principals, the report can be used to identify
- all members of the collection that match the current user.
- Alternatively, if the collection contains resources that have a
- property that identifies a principal (e.g., DAV:owner), the report
- can be used to identify all members of the collection whose property
- identifies a principal that matches the current user. For example,
- this report can return all of the resources in a collection hierarchy
- that are owned by the current user. Support for this report is
- REQUIRED.
-
- Marshalling:
-
- The request body MUST be a DAV:principal-match XML element.
- <!ELEMENT principal-match ((principal-property | self), prop?)>
- <!ELEMENT principal-property ANY>
-
-
-
-Clemm, et al. Standards Track [Page 49]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- ANY value: an element whose value identifies a property. The
- expectation is the value of the named property typically contains
- an href element that contains the URI of a principal
- <!ELEMENT self EMPTY>
- prop: see RFC 2518, Section 12.11
-
- This report is only defined when the Depth header has value "0";
- other values result in a 400 (Bad Request) error response. Note
- that [RFC3253], Section 3.6, states that if the Depth header is
- not present, it defaults to a value of "0". The response body for
- a successful request MUST be a DAV:multistatus XML element. In
- the case where there are no response elements, the returned
- multistatus XML element is empty.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response body for a successful DAV:principal-match REPORT
- request MUST contain a DAV:response element for each member of the
- collection that matches the current user. When the
- DAV:principal-property element is used, a match occurs if the
- current user is matched by the principal identified by the URI
- found in the DAV:href element of the property identified by the
- DAV:principal-property element. When the DAV:self element is used
- in a DAV:principal-match report issued against a group, it matches
- the group if a member identifies the same principal as the current
- user.
-
- If DAV:prop is specified in the request body, the properties
- specified in the DAV:prop element MUST be reported in the
- DAV:response elements.
-
-9.3.1. Example: DAV:principal-match REPORT
-
- The following example identifies the members of the collection
- identified by the URL http://www.example.com/doc that are owned by
- the current user. The current user ("gclemm") is authenticated using
- Digest authentication.
-
- >> Request <<
-
- REPORT /doc/ HTTP/1.1
- Host: www.example.com
- Authorization: Digest username="gclemm",
- realm="users at example.com", nonce="...",
- uri="/papers/", response="...", opaque="..."
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
- Depth: 0
-
-
-
-Clemm, et al. Standards Track [Page 50]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:principal-match xmlns:D="DAV:">
- <D:principal-property>
- <D:owner/>
- </D:principal-property>
- </D:principal-match>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:">
- <D:response>
- <D:href>http://www.example.com/doc/foo.html</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:response>
- <D:response>
- <D:href>http://www.example.com/doc/img/bar.gif</D:href>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:response>
- </D:multistatus>
-
-9.4. DAV:principal-property-search REPORT
-
- The DAV:principal-property-search REPORT performs a search for all
- principals whose properties contain character data that matches the
- search criteria specified in the request. One expected use of this
- report is to discover the URL of a principal associated with a given
- person or group by searching for them by name. This is done by
- searching over DAV:displayname, which is defined on all principals.
-
- The actual search method (exact matching vs. substring matching vs,
- prefix-matching, case-sensitivity) deliberately is left to the server
- implementation to allow implementation on a wide set of possible user
- management systems. In cases where the implementation of
- DAV:principal-property-search is not constrained by the semantics of
- an underlying user management repository, preferred default semantics
- are caseless substring matches.
-
- For implementation efficiency, servers do not typically support
- searching on all properties. A search requesting properties that are
- not searchable for a particular principal will not match that
- principal.
-
- Support for the DAV:principal-property-search report is REQUIRED.
-
-
-
-Clemm, et al. Standards Track [Page 51]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Implementation Note: The value of a WebDAV property is a sequence
- of well-formed XML, and hence can include any character in the
- Unicode/ISO-10646 standard, that is, most known characters in
- human languages. Due to the idiosyncrasies of case mapping across
- human languages, implementation of case-insensitive matching is
- non-trivial. Implementors of servers that do perform substring
- matching are strongly encouraged to consult "The Unicode Standard"
- [UNICODE4], especially Section 5.18, Subsection "Caseless
- Matching", for guidance when implementing their case-insensitive
- matching algorithms.
-
- Implementation Note: Some implementations of this protocol will
- use an LDAP repository for storage of principal metadata. The
- schema describing each attribute (akin to a WebDAV property) in an
- LDAP repository specifies whether it supports case-sensitive or
- caseless searching. One of the benefits of leaving the search
- method to the discretion of the server implementation is the
- default LDAP attribute search behavior can be used when
- implementing the DAV:principal-property-search report.
-
- Marshalling:
-
- The request body MUST be a DAV:principal-property-search XML
- element containing a search specification and an optional list of
- properties. For every principal that matches the search
- specification, the response will contain the value of the
- requested properties on that principal.
-
- <!ELEMENT principal-property-search
- ((property-search+), prop?, apply-to-principal-collection-set?) >
-
- By default, the report searches all members (at any depth) of the
- collection identified by the Request-URI. If DAV:apply-to-
- principal-collection-set is specified in the request body, the
- request is applied instead to each collection identified by the
- DAV:principal-collection-set property of the resource identified
- by the Request-URI.
-
- The DAV:property-search element contains a prop element
- enumerating the properties to be searched and a match element,
- containing the search string.
-
- <!ELEMENT property-search (prop, match) >
- prop: see RFC 2518, Section 12.11
-
- <!ELEMENT match #PCDATA >
-
-
-
-
-
-Clemm, et al. Standards Track [Page 52]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Multiple property-search elements or multiple elements within a
- DAV:prop element will be interpreted with a logical AND.
-
- This report is only defined when the Depth header has value "0";
- other values result in a 400 (Bad Request) error response. Note
- that [RFC3253], Section 3.6, states that if the Depth header is
- not present, it defaults to a value of "0".
-
- The response body for a successful request MUST be a
- DAV:multistatus XML element. In the case where there are no
- response elements, the returned multistatus XML element is empty.
-
- multistatus: see RFC 2518, Section 12.9
-
- The response body for a successful DAV:principal-property-search
- REPORT request MUST contain a DAV:response element for each
- principal whose property values satisfy the search specification
- given in DAV:principal-property-search.
-
- If DAV:prop is specified in the request body, the properties
- specified in the DAV:prop element MUST be reported in the
- DAV:response elements.
-
- Preconditions:
-
- None
-
- Postconditions:
-
- (DAV:number-of-matches-within-limits): The number of matching
- principals must fall within server-specific, predefined limits.
- For example, this condition might be triggered if a search
- specification would cause the return of an extremely large number
- of responses.
-
-9.4.1. Matching
-
- There are several cases to consider when matching strings. The
- easiest case is when a property value is "simple" and has only
- character information item content (see [REC-XML-INFOSET]). For
- example, the search string "julian" would match the DAV:displayname
- property with value "Julian Reschke". Note that the on-the-wire
- marshaling of DAV:displayname in this case is:
-
- <D:displayname xmlns:D="DAV:">Julian Reschke</D:displayname>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 53]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The name of the property is encoded into the XML element information
- item, and the character information item content of the property is
- "Julian Reschke".
-
- A more complicated case occurs when properties have mixed content
- (that is, compound values consisting of multiple child element items,
- other types of information items, and character information item
- content). Consider the property "aprop" in the namespace "http://
- www.example.com/props/", marshaled as:
-
- <W:aprop xmlns:W="http://www.example.com/props/">
- {cdata 0}<W:elem1>{cdata 1}</W:elem1>
- <W:elem2>{cdata 2}</W:elem2>{cdata 3}
- </W:aprop>
-
- In this case, matching is performed on each individual contiguous
- sequence of character information items. In the example above, a
- search string would be compared to the four following strings:
-
- {cdata 0}
- {cdata 1}
- {cdata 2}
- {cdata 3}
-
- That is, four individual matches would be performed, one each for
- {cdata 0}, {cdata 1}, {cdata 2}, and {cdata 3}.
-
-9.4.2. Example: successful DAV:principal-property-search REPORT
-
- In this example, the client requests the principal URLs of all users
- whose DAV:displayname property contains the substring "doE" and whose
- "title" property in the namespace "http://BigCorp.com/ns/" (that is,
- their professional title) contains "Sales". In addition, the client
- requests five properties to be returned with the matching principals:
-
- In the DAV: namespace: displayname
-
- In the http://www.example.com/ns/ namespace: department, phone,
- office, salary
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 54]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The response shows that two principal resources meet the search
- specification, "John Doe" and "Zygdoebert Smith". The property
- "salary" in namespace "http://www.example.com/ns/" is not returned,
- since the principal making the request does not have sufficient
- access permissions to read this property.
-
- >> Request <<
-
- REPORT /users/ HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset=utf-8
- Content-Length: xxxx
- Depth: 0
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:principal-property-search xmlns:D="DAV:">
- <D:property-search>
- <D:prop>
- <D:displayname/>
- </D:prop>
- <D:match>doE</D:match>
- </D:property-search>
- <D:property-search>
- <D:prop xmlns:B="http://www.example.com/ns/">
- <B:title/>
- </D:prop>
- <D:match>Sales</D:match>
- </D:property-search>
- <D:prop xmlns:B="http://www.example.com/ns/">
- <D:displayname/>
- <B:department/>
- <B:phone/>
- <B:office/>
- <B:salary/>
- </D:prop>
- </D:principal-property-search>
-
- >> Response <<
-
- HTTP/1.1 207 Multi-Status
- Content-Type: text/xml; charset=utf-8
- Content-Length: xxxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:multistatus xmlns:D="DAV:" xmlns:B="http://BigCorp.com/ns/">
- <D:response>
- <D:href>http://www.example.com/users/jdoe</D:href>
- <D:propstat>
-
-
-
-Clemm, et al. Standards Track [Page 55]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <D:prop>
- <D:displayname>John Doe</D:displayname>
- <B:department>Widget Sales</B:department>
- <B:phone>234-4567</B:phone>
- <B:office>209</B:office>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop>
- <B:salary/>
- </D:prop>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>http://www.example.com/users/zsmith</D:href>
- <D:propstat>
- <D:prop>
- <D:displayname>Zygdoebert Smith</D:displayname>
- <B:department>Gadget Sales</B:department>
- <B:phone>234-7654</B:phone>
- <B:office>114</B:office>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- <D:propstat>
- <D:prop>
- <B:salary/>
- </D:prop>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- </D:propstat>
- </D:response>
- </D:multistatus>
-
-9.5. DAV:principal-search-property-set REPORT
-
- The DAV:principal-search-property-set REPORT identifies those
- properties that may be searched using the DAV:principal-property-
- search REPORT (defined in Section 9.4).
-
- Servers MUST support the DAV:principal-search-property-set REPORT on
- all collections identified in the value of a DAV:principal-
- collection-set property.
-
- An access control protocol user agent could use the results of the
- DAV:principal-search-property-set REPORT to present a query interface
- to the user for retrieving principals.
-
-
-
-Clemm, et al. Standards Track [Page 56]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- Support for this report is REQUIRED.
-
- Implementation Note: Some clients will have only limited screen
- real estate for the display of lists of searchable properties. In
- this case, a user might appreciate having the most frequently
- searched properties be displayed on-screen, rather than having to
- scroll through a long list of searchable properties. One
- mechanism for signaling the most frequently searched properties is
- to return them towards the start of a list of properties. A
- client can then preferentially display the list of properties in
- order, increasing the likelihood that the most frequently searched
- properties will appear on-screen, and will not require scrolling
- for their selection.
-
- Marshalling:
-
- The request body MUST be an empty DAV:principal-search-property-
- set XML element.
-
- This report is only defined when the Depth header has value "0";
- other values result in a 400 (Bad Request) error response. Note
- that [RFC3253], Section 3.6, states that if the Depth header is
- not present, it defaults to a value of "0".
-
- The response body MUST be a DAV:principal-search-property-set XML
- element, containing a DAV:principal-search-property XML element
- for each property that may be searched with the DAV:principal-
- property-search REPORT. A server MAY limit its response to just a
- subset of the searchable properties, such as those likely to be
- useful to an interactive access control client.
-
- <!ELEMENT principal-search-property-set
- (principal-search-property*) >
-
- Each DAV:principal-search-property XML element contains exactly
- one searchable property, and a description of the property.
-
- <!ELEMENT principal-search-property (prop, description) >
-
- The DAV:prop element contains one principal property on which the
- server is able to perform a DAV:principal-property-search REPORT.
-
- prop: see RFC 2518, Section 12.11
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 57]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- The description element is a human-readable description of what
- information this property represents. Servers MUST indicate the
- human language of the description using the xml:lang attribute and
- SHOULD consider the HTTP Accept-Language request header when
- selecting one of multiple available languages.
-
- <!ELEMENT description #PCDATA >
-
-9.5.1. Example: DAV:principal-search-property-set REPORT
-
- In this example, the client determines the set of searchable
- principal properties by requesting the DAV:principal-search-
- property-set REPORT on the root of the server's principal URL
- collection set, identified by http://www.example.com/users/.
-
- >> Request <<
-
- REPORT /users/ HTTP/1.1
- Host: www.example.com
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
- Accept-Language: en, de
- Authorization: BASIC d2FubmFtYWs6cGFzc3dvcmQ=
- Depth: 0
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:principal-search-property-set xmlns:D="DAV:"/>
-
- >> Response <<
-
- HTTP/1.1 200 OK
- Content-Type: text/xml; charset="utf-8"
- Content-Length: xxx
-
- <?xml version="1.0" encoding="utf-8" ?>
- <D:principal-search-property-set xmlns:D="DAV:">
- <D:principal-search-property>
- <D:prop>
- <D:displayname/>
- </D:prop>
- <D:description xml:lang="en">Full name</D:description>
- </D:principal-search-property>
- <D:principal-search-property>
- <D:prop xmlns:B="http://BigCorp.com/ns/">
- <B:title/>
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 58]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- </D:prop>
- <D:description xml:lang="en">Job title</D:description>
- </D:principal-search-property>
- </D:principal-search-property-set>
-
-10. XML Processing
-
- Implementations of this specification MUST support the XML element
- ignore rule, as specified in Section 23.3.2 of [RFC2518], and the XML
- Namespace recommendation [REC-XML-NAMES].
-
- Note that use of the DAV namespace is reserved for XML elements and
- property names defined in a standards-track or Experimental IETF RFC.
-
-11. Internationalization Considerations
-
- In this specification, the only human-readable content can be found
- in the description XML element, found within the DAV:supported-
- privilege-set property. This element contains a human-readable
- description of the capabilities controlled by a privilege. As a
- result, the description element must be capable of representing
- descriptions in multiple character sets. Since the description
- element is found within a WebDAV property, it is represented on the
- wire as XML [REC-XML], and hence can leverage XML's language tagging
- and character set encoding capabilities. Specifically, XML
- processors at minimum must be able to read XML elements encoded using
- the UTF-8 [RFC3629] encoding of the ISO 10646 multilingual plane.
- XML examples in this specification demonstrate use of the charset
- parameter of the Content-Type header, as defined in [RFC3023], as
- well as the XML "encoding" attribute, which together provide charset
- identification information for MIME and XML processors. Furthermore,
- this specification requires server implementations to tag description
- fields with the xml:lang attribute (see Section 2.12 of [REC-XML]),
- which specifies the human language of the description. Additionally,
- server implementations should take into account the value of the
- Accept-Language HTTP header to determine which description string to
- return.
-
- For XML elements other than the description element, it is expected
- that implementations will treat the property names, privilege names,
- and values as tokens, and convert these tokens into human-readable
- text in the user's language and character set when displayed to a
- person. Only a generic WebDAV property display utility would display
- these values in their raw form to a human user.
-
- For error reporting, we follow the convention of HTTP/1.1 status
- codes, including with each status code a short, English description
- of the code (e.g., 200 (OK)). While the possibility exists that a
-
-
-
-Clemm, et al. Standards Track [Page 59]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- poorly crafted user agent would display this message to a user,
- internationalized applications will ignore this message, and display
- an appropriate message in the user's language and character set.
-
- Further internationalization considerations for this protocol are
- described in the WebDAV Distributed Authoring protocol specification
- [RFC2518].
-
-12. Security Considerations
-
- Applications and users of this access control protocol should be
- aware of several security considerations, detailed below. In
- addition to the discussion in this document, the security
- considerations detailed in the HTTP/1.1 specification [RFC2616], the
- WebDAV Distributed Authoring Protocol specification [RFC2518], and
- the XML Media Types specification [RFC3023] should be considered in a
- security analysis of this protocol.
-
-12.1. Increased Risk of Compromised Users
-
- In the absence of a mechanism for remotely manipulating access
- control lists, if a single user's authentication credentials are
- compromised, only those resources for which the user has access
- permission can be read, modified, moved, or deleted. With the
- introduction of this access control protocol, if a single compromised
- user has the ability to change ACLs for a broad range of other users
- (e.g., a super-user), the number of resources that could be altered
- by a single compromised user increases. This risk can be mitigated
- by limiting the number of people who have write-acl privileges across
- a broad range of resources.
-
-12.2. Risks of the DAV:read-acl and DAV:current-user-privilege-set
- Privileges
-
- The ability to read the access privileges (stored in the DAV:acl
- property), or the privileges permitted the currently authenticated
- user (stored in the DAV:current-user-privilege-set property) on a
- resource may seem innocuous, since reading an ACL cannot possibly
- affect the resource's state. However, if all resources have world-
- readable ACLs, it is possible to perform an exhaustive search for
- those resources that have inadvertently left themselves in a
- vulnerable state, such as being world-writable. In particular, the
- property retrieval method PROPFIND, executed with Depth infinity on
- an entire hierarchy, is a very efficient way to retrieve the DAV:acl
- or DAV:current-user-privilege-set properties. Once found, this
- vulnerability can be exploited by a denial of service attack in which
- the open resource is repeatedly overwritten. Alternately, writable
- resources can be modified in undesirable ways.
-
-
-
-Clemm, et al. Standards Track [Page 60]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- To reduce this risk, read-acl privileges should not be granted to
- unauthenticated principals, and restrictions on read-acl and read-
- current-user-privilege-set privileges for authenticated principals
- should be carefully analyzed when deploying this protocol. Access to
- the current-user-privilege-set property will involve a tradeoff of
- usability versus security. When the current-user-privilege-set is
- visible, user interfaces are expected to provide enhanced information
- concerning permitted and restricted operations, yet this information
- may also indicate a vulnerability that could be exploited.
- Deployment of this protocol will need to evaluate this tradeoff in
- light of the requirements of the deployment environment.
-
-12.3. No Foreknowledge of Initial ACL
-
- In an effort to reduce protocol complexity, this protocol
- specification intentionally does not address the issue of how to
- manage or discover the initial ACL that is placed upon a resource
- when it is created. The only way to discover the initial ACL is to
- create a new resource, then retrieve the value of the DAV:acl
- property. This assumes the principal creating the resource also has
- been granted the DAV:read-acl privilege.
-
- As a result, it is possible that a principal could create a resource,
- and then discover that its ACL grants privileges that are
- undesirable. Furthermore, this protocol makes it possible (though
- unlikely) that the creating principal could be unable to modify the
- ACL, or even delete the resource. Even when the ACL can be modified,
- there will be a short period of time when the resource exists with
- the initial ACL before its new ACL can be set.
-
- Several factors mitigate this risk. Human principals are often aware
- of the default access permissions in their editing environments and
- take this into account when writing information. Furthermore,
- default privilege policies are usually very conservative, limiting
- the privileges granted by the initial ACL.
-
-13. Authentication
-
- Authentication mechanisms defined for use with HTTP and WebDAV also
- apply to this WebDAV Access Control Protocol, in particular the Basic
- and Digest authentication mechanisms defined in [RFC2617].
- Implementation of the ACL spec requires that Basic authentication, if
- used, MUST only be supported over secure transport such as TLS.
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 61]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-14. IANA Considerations
-
- This document uses the namespace defined by [RFC2518] for XML
- elements. That is, this specification uses the "DAV:" URI namespace,
- previously registered in the URI schemes registry. All other IANA
- considerations mentioned in [RFC2518] are also applicable to this
- specification.
-
-15. Acknowledgements
-
- This protocol is the collaborative product of the WebDAV ACL design
- team: Bernard Chester, Geoff Clemm, Anne Hopkins, Barry Lind, Sean
- Lyndersay, Eric Sedlar, Greg Stein, and Jim Whitehead. The authors
- are grateful for the detailed review and comments provided by Jim
- Amsden, Dylan Barrell, Gino Basso, Murthy Chintalapati, Lisa
- Dusseault, Stefan Eissing, Tim Ellison, Yaron Goland, Dennis
- Hamilton, Laurie Harper, Eckehard Hermann, Ron Jacobs, Chris Knight,
- Remy Maucherat, Larry Masinter, Joe Orton, Peter Raymond, and Keith
- Wannamaker. We thank Keith Wannamaker for the initial text of the
- principal property search sections. Prior work on WebDAV access
- control protocols has been performed by Yaron Goland, Paul Leach,
- Lisa Dusseault, Howard Palmer, and Jon Radoff. We would like to
- acknowledge the foundation laid for us by the authors of the DeltaV,
- WebDAV and HTTP protocols upon which this protocol is layered, and
- the invaluable feedback from the WebDAV working group.
-
-16. References
-
-16.1. Normative References
-
- [REC-XML] Bray, T., Paoli, J., Sperberg-McQueen, C. and E.
- Maler, "Extensible Markup Language (XML) 1.0
- ((Third ed)", W3C REC REC-xml-20040204, February
- 2004, <http://www.w3.org/TR/2004/REC-xml-20040204>.
-
- [REC-XML-INFOSET] Cowan, J. and R. Tobin, "XML Information Set
- (Second Edition)", W3C REC REC-xml-infoset-
- 20040204, February 2004,
- <http://www.w3.org/TR/2004/REC-xml-infoset-
- 20040204/>.
-
- [REC-XML-NAMES] Bray, T., Hollander, D. and A. Layman, "Namespaces
- in XML", W3C REC REC-xml-names-19990114, January
- 1999, <http://www.w3.org/TR/1999/REC-xml-names-
- 19990114>.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
-
-
-Clemm, et al. Standards Track [Page 62]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S.
- and D. Jensen, "HTTP Extensions for Distributed
- Authoring -- WEBDAV", RFC 2518, February 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.
-
- [RFC3023] Murata, M., St.Laurent, S. and D. Kohn, "XML Media
- Types", RFC 3023, January 2001.
-
- [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C. and
- J. Whitehead, "Versioning Extensions to WebDAV",
- RFC 3253, March 2002.
-
- [RFC3530] Shepler, S., Ed., Callaghan, B., Robinson, D.,
- Thurlow, R., Beame, C., Eisler, M. and D. Noveck,
- "Network File System (NFS) version 4 Protocol", RFC
- 3530, April 2003.
-
- [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
- 10646", STD 63, RFC 3629 November 2003.
-
-16.2. Informative References
-
- [RFC2251] Wahl, M., Howes, T. and S. Kille, "Lightweight
- Directory Access Protocol (v3)", RFC 2251, December
- 1997.
-
- [RFC2255] Howes, T. and M. Smith, "The LDAP URL Format", RFC
- 2255, December 1997.
-
- [UNICODE4] The Unicode Consortium, "The Unicode Standard -
- Version 4.0", Addison-Wesley , August 2003,
- <http://www.unicode.org/versions/Unicode4.0.0/>.
- ISBN 0321185781.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 63]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-Appendix A. WebDAV XML Document Type Definition Addendum
-
- All XML elements defined in this Document Type Definition (DTD)
- belong to the DAV namespace. This DTD should be viewed as an addendum
- to the DTD provided in [RFC2518], section 23.1.
-
- <!-- Privileges -- (Section 3)>
-
- <!ELEMENT read EMPTY>
- <!ELEMENT write EMPTY>
- <!ELEMENT write-properties EMPTY>
- <!ELEMENT write-content EMPTY>
- <!ELEMENT unlock EMPTY>
- <!ELEMENT read-acl EMPTY>
- <!ELEMENT read-current-user-privilege-set EMPTY>
- <!ELEMENT write-acl EMPTY>
- <!ELEMENT bind EMPTY>
- <!ELEMENT unbind EMPTY>
- <!ELEMENT all EMPTY>
-
- <!-- Principal Properties (Section 4) -->
-
- <!ELEMENT principal EMPTY>
-
- <!ELEMENT alternate-URI-set (href*)>
- <!ELEMENT principal-URL (href)>
- <!ELEMENT group-member-set (href*)>
- <!ELEMENT group-membership (href*)>
-
- <!-- Access Control Properties (Section 5) -->
-
- <!-- DAV:owner Property (Section 5.1) -->
-
- <!ELEMENT owner (href?)>
-
- <!-- DAV:group Property (Section 5.2) -->
-
- <!ELEMENT group (href?)>
-
- <!-- DAV:supported-privilege-set Property (Section 5.3) -->
-
- <!ELEMENT supported-privilege-set (supported-privilege*)>
- <!ELEMENT supported-privilege
- (privilege, abstract?, description, supported-privilege*)>
-
- <!ELEMENT privilege ANY>
- <!ELEMENT abstract EMPTY>
- <!ELEMENT description #PCDATA>
-
-
-
-Clemm, et al. Standards Track [Page 64]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <!-- DAV:current-user-privilege-set Property (Section 5.4) -->
-
- <!ELEMENT current-user-privilege-set (privilege*)>
-
- <!-- DAV:acl Property (Section 5.5) -->
-
- <!ELEMENT acl (ace)* >
- <!ELEMENT ace ((principal | invert), (grant|deny), protected?,
- inherited?)>
-
- <!ELEMENT principal (href)
- | all | authenticated | unauthenticated
- | property | self)>
-
- <!ELEMENT all EMPTY>
- <!ELEMENT authenticated EMPTY>
- <!ELEMENT unauthenticated EMPTY>
- <!ELEMENT property ANY>
- <!ELEMENT self EMPTY>
-
- <!ELEMENT invert principal>
-
- <!ELEMENT grant (privilege+)>
- <!ELEMENT deny (privilege+)>
- <!ELEMENT privilege ANY>
-
- <!ELEMENT protected EMPTY>
-
- <!ELEMENT inherited (href)>
-
- <!-- DAV:acl-restrictions Property (Section 5.6) -->
-
- <!ELEMENT acl-restrictions (grant-only?, no-invert?,
- deny-before-grant?, required-principal?)>
-
- <!ELEMENT grant-only EMPTY>
- <!ELEMENT no-invert EMPTY>
- <!ELEMENT deny-before-grant EMPTY>
-
- <!ELEMENT required-principal
- (all? | authenticated? | unauthenticated? | self? | href*
- |property*)>
-
- <!-- DAV:inherited-acl-set Property (Section 5.7) -->
-
- <!ELEMENT inherited-acl-set (href*)>
-
- <!-- DAV:principal-collection-set Property (Section 5.8) -->
-
-
-
-Clemm, et al. Standards Track [Page 65]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- <!ELEMENT principal-collection-set (href*)>
-
- <!-- Access Control and Existing Methods (Section 7) -->
-
- <!ELEMENT need-privileges (resource)* >
- <!ELEMENT resource ( href, privilege )
-
- <!-- ACL method preconditions (Section 8.1.1) -->
-
- <!ELEMENT no-ace-conflict EMPTY>
- <!ELEMENT no-protected-ace-conflict EMPTY>
- <!ELEMENT no-inherited-ace-conflict EMPTY>
- <!ELEMENT limited-number-of-aces EMPTY>
- <!ELEMENT grant-only EMPTY>
- <!ELEMENT no-invert EMPTY>
- <!ELEMENT deny-before-grant EMPTY>
- <!ELEMENT no-abstract EMPTY>
- <!ELEMENT not-supported-privilege EMPTY>
- <!ELEMENT missing-required-principal EMPTY>
- <!ELEMENT recognized-principal EMPTY>
- <!ELEMENT allowed-principal EMPTY>
-
- <!-- REPORTs (Section 9) -->
-
- <!ELEMENT acl-principal-prop-set ANY>
- ANY value: a sequence of one or more elements, with at most one
- DAV:prop element.
-
- <!ELEMENT principal-match ((principal-property | self), prop?)>
- <!ELEMENT principal-property ANY>
- ANY value: an element whose value identifies a property. The
- expectation is the value of the named property typically contains
- an href element that contains the URI of a principal
- <!ELEMENT self EMPTY>
-
- <!ELEMENT principal-property-search ((property-search+), prop?) >
- <!ELEMENT property-search (prop, match) >
- <!ELEMENT match #PCDATA >
-
- <!ELEMENT principal-search-property-set (
- principal-search-property*) >
- <!ELEMENT principal-search-property (prop, description) >
- <!ELEMENT description #PCDATA >
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 66]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-Appendix B. WebDAV Method Privilege Table (Normative)
-
- The following table of WebDAV methods (as defined in RFC 2518, 2616,
- and 3253) clarifies which privileges are required for access for each
- method. Note that the privileges listed, if denied, MUST cause
- access to be denied. However, given that a specific implementation
- MAY define an additional custom privilege to control access to
- existing methods, having all of the indicated privileges does not
- mean that access will be granted. Note that lack of the indicated
- privileges does not imply that access will be denied, since a
- particular implementation may use a sub-privilege aggregated under
- the indicated privilege to control access. Privileges required refer
- to the current resource being processed unless otherwise specified.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 67]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- +---------------------------------+---------------------------------+
- | METHOD | PRIVILEGES |
- +---------------------------------+---------------------------------+
- | GET | <D:read> |
- | HEAD | <D:read> |
- | OPTIONS | <D:read> |
- | PUT (target exists) | <D:write-content> on target |
- | | resource |
- | PUT (no target exists) | <D:bind> on parent collection |
- | | of target |
- | PROPPATCH | <D:write-properties> |
- | ACL | <D:write-acl> |
- | PROPFIND | <D:read> (plus <D:read-acl> and |
- | | <D:read-current-user-privilege- |
- | | set> as needed) |
- | COPY (target exists) | <D:read>, <D:write-content> and |
- | | <D:write-properties> on target |
- | | resource |
- | COPY (no target exists) | <D:read>, <D:bind> on target |
- | | collection |
- | MOVE (no target exists) | <D:unbind> on source collection |
- | | and <D:bind> on target |
- | | collection |
- | MOVE (target exists) | As above, plus <D:unbind> on |
- | | the target collection |
- | DELETE | <D:unbind> on parent collection |
- | LOCK (target exists) | <D:write-content> |
- | LOCK (no target exists) | <D:bind> on parent collection |
- | MKCOL | <D:bind> on parent collection |
- | UNLOCK | <D:unlock> |
- | CHECKOUT | <D:write-properties> |
- | CHECKIN | <D:write-properties> |
- | REPORT | <D:read> (on all referenced |
- | | resources) |
- | VERSION-CONTROL | <D:write-properties> |
- | MERGE | <D:write-content> |
- | MKWORKSPACE | <D:write-content> on parent |
- | | collection |
- | BASELINE-CONTROL | <D:write-properties> and |
- | | <D:write-content> |
- | MKACTIVITY | <D:write-content> on parent |
- | | collection |
- +---------------------------------+---------------------------------+
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 68]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-Index
-
- A
- ACL method 40
-
- C
- Condition Names
- DAV:allowed-principal (pre) 42
- DAV:deny-before-grant (pre) 41
- DAV:grant-only (pre) 41
- DAV:limited-number-of-aces (pre) 41
- DAV:missing-required-principal (pre) 42
- DAV:no-abstract (pre) 41
- DAV:no-ace-conflict (pre) 41
- DAV:no-inherited-ace-conflict (pre) 41
- DAV:no-invert (pre) 41
- DAV:no-protected-ace-conflict (pre) 41
- DAV:not-supported-privilege (pre) 42
- DAV:number-of-matches-within-limits (post) 48, 53
- DAV:recognized-principal (pre) 42
-
- D
- DAV header
- compliance class 'access-control' 38
- DAV:acl property 23
- DAV:acl-principal-prop-set report 48
- DAV:acl-restrictions property 27
- DAV:all privilege 13
- DAV:allowed-principal precondition 42
- DAV:alternate-URI-set property 14
- DAV:bind privilege 12
- DAV:current-user-privilege-set property 21
- DAV:deny-before-grant precondition 41
- DAV:grant-only precondition 41
- DAV:group property 18
- DAV:group-member-set property 14
- DAV:group-membership property 14
- DAV:inherited-acl-set property 29
- DAV:limited-number-of-aces precondition 41
- DAV:missing-required-principal precondition 42
- DAV:no-abstract precondition 41
- DAV:no-ace-conflict precondition 41
- DAV:no-inherited-ace-conflict precondition 41
- DAV:no-invert precondition 41
- DAV:no-protected-ace-conflict precondition 41
- DAV:not-supported-privilege precondition 42
- DAV:number-of-matches-within-limits postcondition 48, 53
- DAV:owner property 15
-
-
-
-Clemm, et al. Standards Track [Page 69]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- DAV:principal resource type 13
- DAV:principal-collection-set property 30
- DAV:principal-match report 50
- DAV:principal-property-search 51
- DAV:principal-search-property-set 56
- DAV:principal-URL property 14
- DAV:read privilege 10
- DAV:read-acl privilege 11
- DAV:read-current-user-privilege-set privilege 12
- DAV:recognized-principal precondition 42
- DAV:supported-privilege-set property 18
- DAV:unbind privilege 12
- DAV:unlock privilege 11
- DAV:write privilege 10
- DAV:write-acl privilege 12
- DAV:write-content privilege 10
- DAV:write-properties privilege 10
-
- M
- Methods
- ACL 40
-
- P
- Privileges
- DAV:all 13
- DAV:bind 12
- DAV:read 10
- DAV:read-acl 11
- DAV:read-current-user-privilege-set 12
- DAV:unbind 12
- DAV:unlock 11
- DAV:write 10
- DAV:write-acl 12
- DAV:write-content 11
- DAV:write-properties 10
- Properties
- DAV:acl 23
- DAV:acl-restrictions 27
- DAV:alternate-URI-set 14
- DAV:current-user-privilege-set 21
- DAV:group 18
- DAV:group-member-set 14
- DAV:group-membership 14
- DAV:inherited-acl-set 29
- DAV:owner 15
- DAV:principal-collection-set 30
- DAV:principal-URL 14
- DAV:supported-privilege-set 18
-
-
-
-Clemm, et al. Standards Track [Page 70]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
- R
- Reports
- DAV:acl-principal-prop-set 47
- DAV:principal-match 49
- DAV:principal-property-search 51
- DAV:principal-search-property-set 56
- Resource Types
- DAV:principal 13
-
-Authors' Addresses
-
- Geoffrey Clemm
- IBM
- 20 Maguire Road
- Lexington, MA 02421
-
- EMail: geoffrey.clemm at us.ibm.com
-
-
- Julian F. Reschke
- greenbytes GmbH
- Salzmannstrasse 152
- Muenster, NW 48159
- Germany
-
- EMail: julian.reschke at greenbytes.de
-
-
- Eric Sedlar
- Oracle Corporation
- 500 Oracle Parkway
- Redwood Shores, CA 94065
-
- EMail: eric.sedlar at oracle.com
-
-
- Jim Whitehead
- U.C. Santa Cruz, Dept. of Computer Science
- 1156 High Street
- Santa Cruz, CA 95064
-
- EMail: ejw at cse.ucsc.edu
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 71]
-
-RFC 3744 WebDAV Access Control Protocol May 2004
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2004). This document is subject
- to the rights, licenses and restrictions contained in BCP 78, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
- REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE
- INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR
- IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
- THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed
- to pertain to the implementation or use of the technology
- described in this document or the extent to which any license
- under such rights might or might not be available; nor does it
- represent that it has made any independent effort to identify any
- such rights. Information on the procedures with respect to
- rights in RFC documents can be found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use
- of such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository
- at http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention
- any copyrights, patents or patent applications, or other
- proprietary rights that may cover technology that may be required
- to implement this standard. Please address the information to the
- IETF at ietf-ipr at ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is currently provided by the
- Internet Society.
-
-
-
-
-
-
-
-
-
-Clemm, et al. Standards Track [Page 72]
-
Copied: CalendarServer/trunk/doc/RFC/rfc4559-SPNEGO.txt (from rev 172, CalendarServer/trunk/doc/RFC/rfc4559.txt)
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc4559-SPNEGO.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc4559-SPNEGO.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -0,0 +1,451 @@
+
+
+
+
+
+
+Network Working Group K. Jaganathan
+Request for Comments: 4559 L. Zhu
+Category: Informational J. Brezak
+ Microsoft Corporation
+ June 2006
+
+
+ SPNEGO-based Kerberos and NTLM HTTP Authentication
+ in Microsoft Windows
+
+
+Status of This Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2006).
+
+Abstract
+
+ This document describes how the Microsoft Internet Explorer (MSIE)
+ and Internet Information Services (IIS) incorporated in Microsoft
+ Windows 2000 use Kerberos for security enhancements of web
+ transactions. The Hypertext Transport Protocol (HTTP) auth-scheme of
+ "negotiate" is defined here; when the negotiation results in the
+ selection of Kerberos, the security services of authentication and,
+ optionally, impersonation (the IIS server assumes the windows
+ identity of the principal that has been authenticated) are performed.
+ This document explains how HTTP authentication utilizes the Simple
+ and Protected GSS-API Negotiation mechanism. Details of Simple And
+ Protected Negotiate (SPNEGO) implementation are not provided in this
+ document.
+
+Table of Contents
+
+ 1. Introduction ....................................................2
+ 2. Conventions Used in This Document ...............................2
+ 3. Access Authentication ...........................................2
+ 3.1. Reliance on the HTTP/1.1 Specification .....................2
+ 4. HTTP Negotiate Authentication Scheme ............................2
+ 4.1. The WWW-Authenticate Response Header .......................2
+ 5. Negotiate Operation Example .....................................4
+ 6. Security Considerations .........................................5
+ 7. Normative References ............................................6
+
+
+
+
+Jaganathan, et al. Informational [Page 1]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+1. Introduction
+
+ Microsoft has provided support for Kerberos authentication in
+ Microsoft Internet Explorer (MSIE) and Internet Information Services
+ (IIS), in addition to other mechanisms. This provides the benefits
+ of the Kerberos v5 protocol for Web applications.
+
+ Support for Kerberos authentication is based on other previously
+ defined mechanisms, such as SPNEGO Simple And Protected Negotiate
+ (SPNEGO) [RFC4178] and the Generic Security Services Application
+ Program Interface(GSSAPI).
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
+ be interpreted as described in [RFC2119].
+
+3. Access Authentication
+
+3.1. Reliance on the HTTP/1.1 Specification
+
+ This specification is a companion to the HTTP/1.1 specification
+ [RFC2616], and it builds on the authentication mechanisms defined in
+ [RFC2617]. It uses the augmented BNF section of that document (2.1),
+ and it relies on both the non-terminals defined in that document and
+ other aspects of the HTTP/1.1 specification.
+
+4. HTTP Negotiate Authentication Scheme
+
+ Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".
+ The auth-params exchanged use data formats defined for use with the
+ GSS-API [RFC2743]. In particular, they follow the formats set for
+ the SPNEGO [RFC4178] and Kerberos [RFC4121] mechanisms for GSSAPI.
+ The "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens
+ that the specific mechanism type specifies.
+
+ The current implementation of this protocol is limited to the use of
+ SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM
+ protocols.
+
+4.1. The WWW-Authenticate Response Header
+
+ If the server receives a request for an access-protected object, and
+ if an acceptable Authorization header has not been sent, the server
+ responds with a "401 Unauthorized" status code, and a "WWW-
+ Authenticate:" header as per the framework described in [RFC2616].
+ The initial WWW-Authenticate header will not carry any gssapi-data.
+
+
+
+Jaganathan, et al. Informational [Page 2]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+ The negotiate scheme will operate as follows:
+
+ challenge = "Negotiate" auth-data
+ auth-data = 1#( [gssapi-data] )
+
+ The meanings of the values of the directives used above are as
+ follows:
+
+ gssapi-data
+
+ If the gss_accept_security_context returns a token for the client,
+ this directive contains the base64 encoding of an
+ initialContextToken, as defined in [RFC2743]. This is not present in
+ the initial response from the server.
+
+ A status code 200 status response can also carry a "WWW-Authenticate"
+ response header containing the final leg of an authentication. In
+ this case, the gssapi-data will be present. Before using the
+ contents of the response, the gssapi-data should be processed by
+ gss_init_security_context to determine the state of the security
+ context. If this function indicates success, the response can be
+ used by the application. Otherwise, an appropriate action, based on
+ the authentication status, should be taken.
+
+ For example, the authentication could have failed on the final leg if
+ mutual authentication was requested and the server was not able to
+ prove its identity. In this case, the returned results are suspect.
+ It is not always possible to mutually authenticate the server before
+ the HTTP operation. POST methods are in this category.
+
+ When the Kerberos Version 5 GSSAPI mechanism [RFC4121] is being used,
+ the HTTP server will be using a principal name of the form of
+ "HTTP/hostname".
+
+4.2. The Authorization Request Header
+
+ Upon receipt of the response containing a "WWW-Authenticate" header
+ from the server, the client is expected to retry the HTTP request,
+ passing a HTTP "Authorization" header line. This is defined
+ according to the framework described in [RFC2616] and is utilized as
+ follows:
+
+ credentials = "Negotiate" auth-data2
+ auth-data2 = 1#( gssapi-data )
+
+ gssapi-data
+
+
+
+
+
+Jaganathan, et al. Informational [Page 3]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+ This directive contains the base64 encoding of an
+ InitialContextToken, as defined in [RFC2743].
+
+ Any returned code other than a success 2xx code represents an
+ authentication error. If a 401 containing a "WWW-Authenticate"
+ header with "Negotiate" and gssapi-data is returned from the server,
+ it is a continuation of the authentication request.
+
+ A client may initiate a connection to the server with an
+ "Authorization" header containing the initial token for the server.
+ This form will bypass the initial 401 error from the server when the
+ client knows that the server will accept the Negotiate HTTP
+ authentication type.
+
+5. Negotiate Operation Example
+
+ The client requests an access-protected document from server via a
+ GET method request. The URI of the document is
+ "http://www.nowhere.org/dir/index.html".
+
+ C: GET dir/index.html
+
+ The first time the client requests the document, no Authorization
+ header is sent, so the server responds with
+
+ S: HTTP/1.1 401 Unauthorized
+ S: WWW-Authenticate: Negotiate
+
+ The client will obtain the user credentials using the SPNEGO GSSAPI
+ mechanism type to identify generate a GSSAPI message to be sent to
+ the server with a new request, including the following Authorization
+ header:
+
+ C: GET dir/index.html
+ C: Authorization: Negotiate a87421000492aa874209af8bc028
+
+ The server will decode the gssapi-data and pass this to the SPNEGO
+ GSSAPI mechanism in the gss_accept_security_context function. If the
+ context is not complete, the server will respond with a 401 status
+ code with a WWW-Authenticate header containing the gssapi-data.
+
+ S: HTTP/1.1 401 Unauthorized
+ S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
+
+ The client will decode the gssapi-data, pass this into
+ Gss_Init_security_context, and return the new gssapi-data to the
+ server.
+
+
+
+
+Jaganathan, et al. Informational [Page 4]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+ C: GET dir/index.html
+ C: Authorization: Negotiate 89a8742aa8729a8b028
+
+ This cycle can continue until the security context is complete. When
+ the return value from the gss_accept_security_context function
+ indicates that the security context is complete, it may supply final
+ authentication data to be returned to the client. If the server has
+ more gssapi data to send to the client to complete the context, it is
+ to be carried in a WWW-Authenticate header with the final response
+ containing the HTTP body.
+
+ S: HTTP/1.1 200 Success
+ S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
+
+ The client will decode the gssapi-data and supply it to
+ gss_init_security_context using the context for this server. If the
+ status is successful from the final gss_init_security_context, the
+ response can be used by the application.
+
+6. Security Considerations
+
+ The SPNEGO HTTP authentication facility is only used to provide
+ authentication of a user to a server. It provides no facilities for
+ protecting the HTTP headers or data including the Authorization and
+ WWW-Authenticate headers that are used to implement this mechanism.
+
+ Alternate mechanisms such as TLS can be used to provide
+ confidentiality. Hashes of the TLS certificates can be used as
+ channel bindings to secure the channel. In this case clients would
+ need to enforce that the channel binding information is valid. Note
+ that Kerb-TLS [RFC2712] could be used to provide both authentication
+ and confidentiality, but this requires a change to the TLS provider.
+
+ This mechanism is not used for HTTP authentication to HTTP proxies.
+
+ If an HTTP proxy is used between the client and server, it must take
+ care to not share authenticated connections between different
+ authenticated clients to the same server. If this is not honored,
+ then the server can easily lose track of security context
+ associations. A proxy that correctly honors client to server
+ authentication integrity will supply the "Proxy-support: Session-
+ Based-Authentication" HTTP header to the client in HTTP responses
+ from the proxy. The client MUST NOT utilize the SPNEGO HTTP
+ authentication mechanism through a proxy unless the proxy supplies
+ this header with the "401 Unauthorized" response from the server.
+
+
+
+
+
+
+Jaganathan, et al. Informational [Page 5]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+ When using the SPNEGO HTTP authentication facility with client-
+ supplied data such as PUT and POST, the authentication should be
+ complete between the client and server before sending the user data.
+ The return status from the gss_init_security_context will indicate
+ that the security context is complete. At this point, the data can
+ be sent to the server.
+
+7. Normative References
+
+ [RFC2743] Linn, J., "Generic Security Service Application Program
+ Interface Version 2", 2, Update 1", 2743, January 2000.
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
+ Simple and Protected GSS-API Generic Security Service
+ Application Program Interface (GSS-API) Negotiation
+ Mechanism", 4178, October 2005.
+
+ [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.
+
+ [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher
+ Suites to Transport Layer Security (TLS)", RFC 2712,
+ October 1999.
+
+ [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
+ Version 5 Generic Security Service Application Program
+ Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
+ 2005.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jaganathan, et al. Informational [Page 6]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+Authors' Addresses
+
+ Karthik Jaganathan
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052
+ US
+
+ EMail: karthikj at microsoft.com
+
+
+ Larry Zhu
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052
+ US
+
+ EMail: lzhu at microsoft.com
+
+
+ John Brezak
+ Microsoft Corporation
+ One Microsoft Way
+ Redmond, WA 98052
+ US
+
+ EMail: jbrezak at microsoft.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Jaganathan, et al. Informational [Page 7]
+
+RFC 4559 HTTP Authentication in Microsoft Windows June 2006
+
+
+Full Copyright Statement
+
+ Copyright (C) The Internet Society (2006).
+
+ This document is subject to the rights, licenses and restrictions
+ contained in BCP 78 and at www.rfc-editor.org/copyright.html, and
+ except as set forth therein, the authors retain all their rights.
+
+ This document and the information contained herein are provided on an
+ "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
+ OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
+ ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
+ INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
+ INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
+ WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+Intellectual Property
+
+ The IETF takes no position regarding the validity or scope of any
+ Intellectual Property Rights or other rights that might be claimed to
+ pertain to the implementation or use of the technology described in
+ this document or the extent to which any license under such rights
+ might or might not be available; nor does it represent that it has
+ made any independent effort to identify any such rights. Information
+ on the procedures with respect to rights in RFC documents can be
+ found in BCP 78 and BCP 79.
+
+ Copies of IPR disclosures made to the IETF Secretariat and any
+ assurances of licenses to be made available, or the result of an
+ attempt made to obtain a general license or permission for the use of
+ such proprietary rights by implementers or users of this
+ specification can be obtained from the IETF on-line IPR repository at
+ http://www.ietf.org/ipr.
+
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights that may cover technology that may be required to implement
+ this standard. Please address the information to the IETF at
+ ietf-ipr at ietf.org.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is provided by the IETF
+ Administrative Support Activity (IASA).
+
+
+
+
+
+
+
+Jaganathan, et al. Informational [Page 8]
+
Deleted: CalendarServer/trunk/doc/RFC/rfc4559.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc4559.txt 2006-09-22 18:43:06 UTC (rev 187)
+++ CalendarServer/trunk/doc/RFC/rfc4559.txt 2006-09-22 20:38:58 UTC (rev 188)
@@ -1,451 +0,0 @@
-
-
-
-
-
-
-Network Working Group K. Jaganathan
-Request for Comments: 4559 L. Zhu
-Category: Informational J. Brezak
- Microsoft Corporation
- June 2006
-
-
- SPNEGO-based Kerberos and NTLM HTTP Authentication
- in Microsoft Windows
-
-
-Status of This Memo
-
- This memo provides information for the Internet community. It does
- not specify an Internet standard of any kind. Distribution of this
- memo is unlimited.
-
-Copyright Notice
-
- Copyright (C) The Internet Society (2006).
-
-Abstract
-
- This document describes how the Microsoft Internet Explorer (MSIE)
- and Internet Information Services (IIS) incorporated in Microsoft
- Windows 2000 use Kerberos for security enhancements of web
- transactions. The Hypertext Transport Protocol (HTTP) auth-scheme of
- "negotiate" is defined here; when the negotiation results in the
- selection of Kerberos, the security services of authentication and,
- optionally, impersonation (the IIS server assumes the windows
- identity of the principal that has been authenticated) are performed.
- This document explains how HTTP authentication utilizes the Simple
- and Protected GSS-API Negotiation mechanism. Details of Simple And
- Protected Negotiate (SPNEGO) implementation are not provided in this
- document.
-
-Table of Contents
-
- 1. Introduction ....................................................2
- 2. Conventions Used in This Document ...............................2
- 3. Access Authentication ...........................................2
- 3.1. Reliance on the HTTP/1.1 Specification .....................2
- 4. HTTP Negotiate Authentication Scheme ............................2
- 4.1. The WWW-Authenticate Response Header .......................2
- 5. Negotiate Operation Example .....................................4
- 6. Security Considerations .........................................5
- 7. Normative References ............................................6
-
-
-
-
-Jaganathan, et al. Informational [Page 1]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
-1. Introduction
-
- Microsoft has provided support for Kerberos authentication in
- Microsoft Internet Explorer (MSIE) and Internet Information Services
- (IIS), in addition to other mechanisms. This provides the benefits
- of the Kerberos v5 protocol for Web applications.
-
- Support for Kerberos authentication is based on other previously
- defined mechanisms, such as SPNEGO Simple And Protected Negotiate
- (SPNEGO) [RFC4178] and the Generic Security Services Application
- Program Interface(GSSAPI).
-
-2. Conventions Used in This Document
-
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to
- be interpreted as described in [RFC2119].
-
-3. Access Authentication
-
-3.1. Reliance on the HTTP/1.1 Specification
-
- This specification is a companion to the HTTP/1.1 specification
- [RFC2616], and it builds on the authentication mechanisms defined in
- [RFC2617]. It uses the augmented BNF section of that document (2.1),
- and it relies on both the non-terminals defined in that document and
- other aspects of the HTTP/1.1 specification.
-
-4. HTTP Negotiate Authentication Scheme
-
- Use of Kerberos is wrapped in an HTTP auth-scheme of "Negotiate".
- The auth-params exchanged use data formats defined for use with the
- GSS-API [RFC2743]. In particular, they follow the formats set for
- the SPNEGO [RFC4178] and Kerberos [RFC4121] mechanisms for GSSAPI.
- The "Negotiate" auth-scheme calls for the use of SPNEGO GSSAPI tokens
- that the specific mechanism type specifies.
-
- The current implementation of this protocol is limited to the use of
- SPNEGO with the Kerberos and Microsoft(NT Lan Manager) NTLM
- protocols.
-
-4.1. The WWW-Authenticate Response Header
-
- If the server receives a request for an access-protected object, and
- if an acceptable Authorization header has not been sent, the server
- responds with a "401 Unauthorized" status code, and a "WWW-
- Authenticate:" header as per the framework described in [RFC2616].
- The initial WWW-Authenticate header will not carry any gssapi-data.
-
-
-
-Jaganathan, et al. Informational [Page 2]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- The negotiate scheme will operate as follows:
-
- challenge = "Negotiate" auth-data
- auth-data = 1#( [gssapi-data] )
-
- The meanings of the values of the directives used above are as
- follows:
-
- gssapi-data
-
- If the gss_accept_security_context returns a token for the client,
- this directive contains the base64 encoding of an
- initialContextToken, as defined in [RFC2743]. This is not present in
- the initial response from the server.
-
- A status code 200 status response can also carry a "WWW-Authenticate"
- response header containing the final leg of an authentication. In
- this case, the gssapi-data will be present. Before using the
- contents of the response, the gssapi-data should be processed by
- gss_init_security_context to determine the state of the security
- context. If this function indicates success, the response can be
- used by the application. Otherwise, an appropriate action, based on
- the authentication status, should be taken.
-
- For example, the authentication could have failed on the final leg if
- mutual authentication was requested and the server was not able to
- prove its identity. In this case, the returned results are suspect.
- It is not always possible to mutually authenticate the server before
- the HTTP operation. POST methods are in this category.
-
- When the Kerberos Version 5 GSSAPI mechanism [RFC4121] is being used,
- the HTTP server will be using a principal name of the form of
- "HTTP/hostname".
-
-4.2. The Authorization Request Header
-
- Upon receipt of the response containing a "WWW-Authenticate" header
- from the server, the client is expected to retry the HTTP request,
- passing a HTTP "Authorization" header line. This is defined
- according to the framework described in [RFC2616] and is utilized as
- follows:
-
- credentials = "Negotiate" auth-data2
- auth-data2 = 1#( gssapi-data )
-
- gssapi-data
-
-
-
-
-
-Jaganathan, et al. Informational [Page 3]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- This directive contains the base64 encoding of an
- InitialContextToken, as defined in [RFC2743].
-
- Any returned code other than a success 2xx code represents an
- authentication error. If a 401 containing a "WWW-Authenticate"
- header with "Negotiate" and gssapi-data is returned from the server,
- it is a continuation of the authentication request.
-
- A client may initiate a connection to the server with an
- "Authorization" header containing the initial token for the server.
- This form will bypass the initial 401 error from the server when the
- client knows that the server will accept the Negotiate HTTP
- authentication type.
-
-5. Negotiate Operation Example
-
- The client requests an access-protected document from server via a
- GET method request. The URI of the document is
- "http://www.nowhere.org/dir/index.html".
-
- C: GET dir/index.html
-
- The first time the client requests the document, no Authorization
- header is sent, so the server responds with
-
- S: HTTP/1.1 401 Unauthorized
- S: WWW-Authenticate: Negotiate
-
- The client will obtain the user credentials using the SPNEGO GSSAPI
- mechanism type to identify generate a GSSAPI message to be sent to
- the server with a new request, including the following Authorization
- header:
-
- C: GET dir/index.html
- C: Authorization: Negotiate a87421000492aa874209af8bc028
-
- The server will decode the gssapi-data and pass this to the SPNEGO
- GSSAPI mechanism in the gss_accept_security_context function. If the
- context is not complete, the server will respond with a 401 status
- code with a WWW-Authenticate header containing the gssapi-data.
-
- S: HTTP/1.1 401 Unauthorized
- S: WWW-Authenticate: Negotiate 749efa7b23409c20b92356
-
- The client will decode the gssapi-data, pass this into
- Gss_Init_security_context, and return the new gssapi-data to the
- server.
-
-
-
-
-Jaganathan, et al. Informational [Page 4]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- C: GET dir/index.html
- C: Authorization: Negotiate 89a8742aa8729a8b028
-
- This cycle can continue until the security context is complete. When
- the return value from the gss_accept_security_context function
- indicates that the security context is complete, it may supply final
- authentication data to be returned to the client. If the server has
- more gssapi data to send to the client to complete the context, it is
- to be carried in a WWW-Authenticate header with the final response
- containing the HTTP body.
-
- S: HTTP/1.1 200 Success
- S: WWW-Authenticate: Negotiate ade0234568a4209af8bc0280289eca
-
- The client will decode the gssapi-data and supply it to
- gss_init_security_context using the context for this server. If the
- status is successful from the final gss_init_security_context, the
- response can be used by the application.
-
-6. Security Considerations
-
- The SPNEGO HTTP authentication facility is only used to provide
- authentication of a user to a server. It provides no facilities for
- protecting the HTTP headers or data including the Authorization and
- WWW-Authenticate headers that are used to implement this mechanism.
-
- Alternate mechanisms such as TLS can be used to provide
- confidentiality. Hashes of the TLS certificates can be used as
- channel bindings to secure the channel. In this case clients would
- need to enforce that the channel binding information is valid. Note
- that Kerb-TLS [RFC2712] could be used to provide both authentication
- and confidentiality, but this requires a change to the TLS provider.
-
- This mechanism is not used for HTTP authentication to HTTP proxies.
-
- If an HTTP proxy is used between the client and server, it must take
- care to not share authenticated connections between different
- authenticated clients to the same server. If this is not honored,
- then the server can easily lose track of security context
- associations. A proxy that correctly honors client to server
- authentication integrity will supply the "Proxy-support: Session-
- Based-Authentication" HTTP header to the client in HTTP responses
- from the proxy. The client MUST NOT utilize the SPNEGO HTTP
- authentication mechanism through a proxy unless the proxy supplies
- this header with the "401 Unauthorized" response from the server.
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 5]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
- When using the SPNEGO HTTP authentication facility with client-
- supplied data such as PUT and POST, the authentication should be
- complete between the client and server before sending the user data.
- The return status from the gss_init_security_context will indicate
- that the security context is complete. At this point, the data can
- be sent to the server.
-
-7. Normative References
-
- [RFC2743] Linn, J., "Generic Security Service Application Program
- Interface Version 2", 2, Update 1", 2743, January 2000.
-
- [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14, RFC 2119, March 1997.
-
- [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
- Simple and Protected GSS-API Generic Security Service
- Application Program Interface (GSS-API) Negotiation
- Mechanism", 4178, October 2005.
-
- [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.
-
- [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher
- Suites to Transport Layer Security (TLS)", RFC 2712,
- October 1999.
-
- [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
- Version 5 Generic Security Service Application Program
- Interface (GSS-API) Mechanism: Version 2", RFC 4121, July
- 2005.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 6]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
-Authors' Addresses
-
- Karthik Jaganathan
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: karthikj at microsoft.com
-
-
- Larry Zhu
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: lzhu at microsoft.com
-
-
- John Brezak
- Microsoft Corporation
- One Microsoft Way
- Redmond, WA 98052
- US
-
- EMail: jbrezak at microsoft.com
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 7]
-
-RFC 4559 HTTP Authentication in Microsoft Windows June 2006
-
-
-Full Copyright Statement
-
- Copyright (C) The Internet Society (2006).
-
- This document is subject to the rights, licenses and restrictions
- contained in BCP 78 and at www.rfc-editor.org/copyright.html, and
- except as set forth therein, the authors retain all their rights.
-
- This document and the information contained herein are provided on an
- "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
- OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-
-Intellectual Property
-
- The IETF takes no position regarding the validity or scope of any
- Intellectual Property Rights or other rights that might be claimed to
- pertain to the implementation or use of the technology described in
- this document or the extent to which any license under such rights
- might or might not be available; nor does it represent that it has
- made any independent effort to identify any such rights. Information
- on the procedures with respect to rights in RFC documents can be
- found in BCP 78 and BCP 79.
-
- Copies of IPR disclosures made to the IETF Secretariat and any
- assurances of licenses to be made available, or the result of an
- attempt made to obtain a general license or permission for the use of
- such proprietary rights by implementers or users of this
- specification can be obtained from the IETF on-line IPR repository at
- http://www.ietf.org/ipr.
-
- The IETF invites any interested party to bring to its attention any
- copyrights, patents or patent applications, or other proprietary
- rights that may cover technology that may be required to implement
- this standard. Please address the information to the IETF at
- ietf-ipr at ietf.org.
-
-Acknowledgement
-
- Funding for the RFC Editor function is provided by the IETF
- Administrative Support Activity (IASA).
-
-
-
-
-
-
-
-Jaganathan, et al. Informational [Page 8]
-
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20060922/62a53cae/attachment.html
More information about the calendarserver-changes
mailing list