Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3744

Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol

Pages: 72
Proposed Standard
Errata
Part 3 of 4 – Pages 40 to 60
First   Prev   Next

Top   ToC   RFC3744 - Page 40   prevText

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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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   ToC   RFC3744 - 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 Section