tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 3744

 
 
 

Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol

Part 3 of 4, p. 40 to 60
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 40 
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

Top      Up      ToC       Page 41 
   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).

Top      Up      ToC       Page 42 
   (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@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>

Top      Up      ToC       Page 43 
     <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@example.com", nonce="...",
     uri="/top/container/", response="...", opaque="..."

   <?xml version="1.0" encoding="utf-8" ?>
   <D:acl xmlns:D="DAV:">
     <D:ace>
       <D:principal>

Top      Up      ToC       Page 44 
         <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.

Top      Up      ToC       Page 45 
   >> 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@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.

Top      Up      ToC       Page 46 
   >> 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@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.

Top      Up      ToC       Page 47 
   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.

Top      Up      ToC       Page 48 
   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>

Top      Up      ToC       Page 49 
   >> 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>

Top      Up      ToC       Page 50 
      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@example.com", nonce="...",
     uri="/papers/", response="...", opaque="..."
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx
   Depth: 0

Top      Up      ToC       Page 51 
   <?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.

Top      Up      ToC       Page 52 
      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 >

Top      Up      ToC       Page 53 
      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>

Top      Up      ToC       Page 54 
   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

Top      Up      ToC       Page 55 
   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>

Top      Up      ToC       Page 56 
         <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.

Top      Up      ToC       Page 57 
   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

Top      Up      ToC       Page 58 
      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/>

Top      Up      ToC       Page 59 
       </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

Top      Up      ToC       Page 60 
   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].



(page 60 continued on part 4)

Next RFC Part