RFC 3744
Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol
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
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).
(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>
<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>
<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.
>> 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.
>> 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.
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.
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>
>> 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>
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
<?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.
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 >
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>
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
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>
<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.
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
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/>
</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
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)
