WebDAV Resource Sharing

A server that supports the features described in this document MUST include "resource-sharing" as a field in the DAV response header from an OPTIONS request on any resource that supports these features. A response to this OPTIONS request might look as follows:

A server that supports sharing on a specific resource, MUST enforce this using the "DAV:share" privilege. Privileges are defined in . The privilege MAY be abstract and MAY be protected. This privilege MUST appear in the DAV:supported-privilege-set property for resources that may be shared. In addition, it MUST appear in the DAV:current-user-privilege-set property, if the user is in fact allowed to share the resource. This mechanism is also used by a client to discover sharing capabilities on specific resources.

To share a resource or revoke access to a shared resource, the client must issue a POST request to the resource that the user wants to share. The POST request MUST contain an XML document as its body, with the root element being DAV:share-resource. The POST request MUST contain a Content-Type HTTP header, which MUST contain "application/davsharing+xml" as its value. Servers SHOULD reject the request if this is not the case. The DAV:share-resource element can contain one or more DAV:sharee elements. Each DAV:sharee element MUST at least have a DAV:href element containing a URI identifying the sharee. The URI in DAV:href may be a principal-URL referring to a sharee hosted on the same server, an email address or any other URI identifying a user. In the case of the latter two, the sharee might not be a user on the same server - though in that case how invitations are sent or access is enabled is out of scope for this specification. The DAV:prop element is optional, and can be used to provide more information about the sharee. The server MAY use this information and later return it when information is requested about the list of sharees. Any valid WebDAV property might be provided here, but it's up to the discretion of the server what to support. A client SHOULD provide at least a DAV:displayname property as a human- readable string identifying the user. The DAV:share-access element is required. It MUST contain one of the following elements: When present this indicates that sharees can read information from the resource, but cannot change it. This applies to the resource, but if the shared resource is a collection, it also applies to the collection's children. When present this indicates that sharees can read and write information from the resource. When present this indicates that access to the resource is revoked for the sharee. Lastly, you may add the optional DAV:comment element. This element may contain some information about the intent of the share, for the sharee, this allows the sharee to send a short message.

The following example grants read-write access to a resource identified by "/calendars/users/cyrus/shared" to a sharee with email address "mailto:eric@example.com".

mailto:eric@example.com Eric York Shared workspace

]]> If the operation was successful, the server MUST respond with a 204 No Content HTTP status.

This example shows how multiple sharee's can be manipulated in a single request. The sharee with email address "mailto:eric@example.com" has their access downgraded to DAV:read, whilst another sharee is removed from the access list entirely.

mailto:eric@example.com

mailto:wilfredo@example.com

]]>

The following new or modified WebDAV properties are defined for resources and used to view or manipulate shared resources features.

share-access DAV: Allows a client to see if a resource is a shared resource and the access level. This property MUST be protected. This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of ). This property value MUST be preserved in MOVE operations, but MUST NOT be preserved in COPY operations. Resources that are shared must have a DAV:share-access property. It's value should be one of four elements: DAV:not-shared: Used to indicate that the resource is not shared. This is the default, which means that if the DAV:share-access is omitted, this value is implied. DAV:shared-owner: used to indicate that the resource is owned by the current user and is being shared by them. DAV:read-write: used to indicate that the resource is shared, and the current instance is the 'shared instance' which has read-write access. DAV:read: used to indicate that the resource is shared, and the current instance is the 'shared instance', and only read access is provided.

invite DAV: Used to show to whom a resource has been shared. This property MUST be protected. This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of ). This property value MUST be preserved in MOVE operations, but MUST NOT be preserved in COPY operations. This WebDAV property is present on a resource that has been shared by the owner, or on the resources for the sharees. It provides a list of users to whom the resource has been shared, along with the "status" of the sharing invites sent to each user. In addition, servers SHOULD include a DAV:principal XML element on resources of the sharees to provide clients with a fast way to determine who the sharer is. A server's local privacy policy may prevent sharees from knowing about other sharees on a shared calendar. In those cases a server may hide information about other sharees.

share-resource-uri DAV: A unique URI that identifies the shared resource. This property MUST be protected. This property SHOULD NOT be returned by a PROPFIND allprop request (as defined in Section 14.2 of ). This property value MUST be preserved in COPY and MOVE operations. This WebDAV property SHOULD be present on a shared resource. Its content is a single DAV:href element whose value is the URL of the sharer's resource being shared. The property MUST contain a URI that uniquely identifies the original shared resource. The URI MAY refer to a resource hosted on the same server, but MAY also refer to a URN. A key requirement is that this URI remains stable during the life-time of a share.

This specification supports two major processes for sharing a resource. The server can either immediately set up the newly shared resource, or the server can provide an invitation process. The former might be useful in small trusted team settings, whereas the invitation process might be used in public servers, where it's desirable for users to explicitly opt-in to getting access to newly shared resources. This specification provides a invitation and notification mechanism. It might also be possible that servers provide their own out-of-band mechanism for this, but this should not affect clients.

If the server opts to support the standard invitation process, the server MUST support WebDAV notifications. Sharees for a resource MUST appear up in the DAV:invite property. Each sharee will have one of the following elements: The sharee was invited, but has not yet responded to the invite. The sharee has accepted the invite. The sharee has declined the invite. The invitation was invalid or could not be delivered. When sharees are initially invited, they will get the DAV:invite-noresponse status. When a sharee's access has been changed, they will retain their existing status. When a sharee's access has been revoked, they will no longer appear in the DAV:invite property. After any of these mutations, sharees receive an share-invite-notification in their notification collection. After the sharee has accepted or declined the invite, their status will reflect this response.

Implementing the invitation process is optional. It's also possible for servers to immediately apply changes. The effect is that no notifications may be needed, and the server behaves as if sharees immediately accept invitations. Sharees listed in DAV:invite might immediately receive a DAV:invite-accepted status.

In order to facilitate the process of sharing invitations, this specification uses WebDAV notifications, and defines several new notification types.

When a sharer adds a new sharee to a resource, or updates a sharee, an invite notification is added to the sharee's notification collection. The notification contains information about the shared resource, the owner and how to respond to the invitation.

This is an example of a response to a GET request on a correct reply invite notification. Note that several HTTP response headers have been removed for brevity.

2014-08-05T13:38:02Z /principals/users/evert/

/calendars/users/evert/offdays/

Vacation days!!

?invite-reply

]]> In this notification, DAV:principal indicates which principal is the sharer for the resource. The notification MUST contain DAV:invite-accepted or DAV:invite-noresponse to indicate the current invitation status of the sharee in the shared resource. New invites to shares would carry the DAV:invite-noresponse status. In case the sharee had accepted an earlier invite, but it's access was changed or revoked, the invitation will have a DAV:invite-accepted status. DAV:sharer-resource-uri refers to the DAV:sharer-resource-uri that the shared resource will have, and can be used to identify which invitation refers to which existing shared resource. The element MAY refer to the URI of the original shared resource, but may also be a urn, or any other unique URI. DAV:share-access MUST be one of DAV:read-write, DAV:read or DAV:no-access. This indicates that the invitee either has read-write access, read-only access or no access at all respectively. DAV:reply-url appears for invitations to new shared resources. The url in this property can be used for a sharee to accept or decline the invite. DAV:reply-url only appears for sharees with the DAV:invite-noresponse status, and does not appear when DAV:share-access is DAV:no-access. The DAV:prop element is optional, and may contain a list of WebDAV properties associated with the shared resource. Servers SHOULD at least set the DAV:resourcetype, if available. This will allow a client to know what kind of resource is being shared. Some clients may only support responding to invites of certain kinds of resources. For example, a calendaring user agent may only support CalDAV calendars. The DAV:comment element is also optional, and may return a brief message from the sharer to the sharee. The sharer is able to specify this in the original DAV:share-resource POST request.

After a sharee has accepted or declined an invitation, the sharer receives a share-reply-notification in their notification collection. This notification contains information about which collection this relates to, and who responded to the invite.

This is an example of a response to a GET request on a correct invite notification. Note that several HTTP response headers have been removed for brevity.

2014-09-03T02:30:00Z mailto:john@example.org

/calendars/users/evert/offdays/ Sorry, I'm not interested ]]> In this notification, the DAV:sharee element MUST appear and contains information about the updated status of the sharee in the shared resource. The DAV:href element MUST appear and refers to the resource the sharer originally shared. The DAV:comment element is optional, and may contain a message that the sharee specified when responding to the invite.

When a sharee is invited to a shared resource they can accept or decline the invite by issuing a POST request to the url specified in the DAV:reply-url element, in the invitation notification. The POST request MUST contain an XML document as its body with the root element being DAV:invite-reply. The POST request MUST contain a Content-Type HTTP header, which MUST contain "application/davsharing+xml" as its value. Servers SHOULD reject the request if this is not the case. The DAV:invite-reply element in the POST request specifies the accept or decline action via the DAV:invite-accepted or DAV:invite-declined elements, and an optional DAV:comment element. IF the invite was accepted, the body MUST also contain a DAV:create-in element. This element contains a single DAV:href element, which content is a URI that will be used as the parent for the new shared resource. The client MAY also provide a DAV:slug property. The server MAY use the contents of this property to determine the name of the new resource. All usual preconditions for creating a resource at the DAV:create-in target collection need to be taken into consideration. Note that some servers may restrict where certain types of resources may be created. A CalDAV server for instance, may only allow calendars to be created in collections identified by the CALDAV:calendar-home-set WebDAV property. The client MAY also provide a small comment in the DAV:comment element. This comment will be sent back to the sharer. Support for DAV:comment is optional. A successful response to an accepted invitation, SHOULD have a HTTP 201 status code, and MUST have a HTTP Location header, containing the full url to the newly created resource. A successful response to a declined invitation, SHOULD contain a 200 or 204 HTTP status code. When the sharee replies to an invite, the server SHOULD send a notification to the sharer to update them on the change in the sharee state. This is accomplished by sending a DAV:share-reply-notification notification to the sharer. After the sharee has issued a reply, the server SHOULD also remove the notification that contained the initial invite.

This is an example of a request that the sharee would send to accept an invitation.

/calendars/users/evert/

Tech meetups Thanks for the share!

]]>

For privacy reasons, sharees need to be able to remove invitations without notifiying the sharer. When the sharee issues a DELETE on an share-invite-notification, the server MUST remove the notification, and MUST NOT let the sharer know about this. As a result, from the sharers perspective, the invitation status for that principal will always remain as DAV:invite-noreply.

Any changes that a sharee makes to a shared resource should also be reflected in the sharers instance of the resource. If the shared resource is a collection, any resources in the collection, or in the collection's child-collections MUST also appear in the sharers instance.

To remove a shared resource a DELETE request is targeted at the shared resource URI. When such a request is received the server MUST remove the shared collection and automatically update the sharee's status in the sharer's DAV:invite property.

Servers MUST support "per-instance" WebDAV properties on shared resource and MAY support them on resources within shared collections. A "per-instance" WebDAV property is one whose value can be set and retrieved on an instance of a resource, but is not automatically propagated to other instances of the same shared resource. For example, a sharee may change a property on their instance of a shared resource, but the instance of the owner of the resource will not see this updated value. For shared resources, the server MUST allow all users to write "per-instance" WebDAV properties on the shared resources and MAY allow property writes on resources within the shared resources. This is required even in the case where the sharee has been granted read access only (i.e., the ability to change the resource is disallowed). This requirement ensures that sharees can always change "personal" properties such as display names. Servers MAY treat any dead property as per-instance. Servers MUST NOT treat live properties as per-instance.

A point that may not be immediately obvious, is that there is a separation between sharees and shared instances. Sharees (and sharers) are effectively only 'actors' in the sharing process and allow shared instances to be created and modified. The sharing "role" or access level that a user has when performing an opteration on a shared resource, is dependent on which intance they are accessing, not who the currently logged in principal is. To illustrate, take the DAV:share-access WebDAV property. This property should always describe the access-level of the instance, not the current user accessing the property. An implication is that if an owner of a shared resource also has direct access to a shared instance of a sharee (via normal WebDAV ACL controls for example), requesting the share-access property on that shared resource should always indicate DAV:read or DAV:read-write, but never DAV:shared-owner. Likewise, if a sharee also has direct access to the original shared (owner) instance on the same server, the DAV:share-access property should always return DAV:shared-owner. This philosophy must be considered when designing the underlying data-model of the server, and every feature in this specification. That is: the sharing-role a user has when accessing a shared-resource, is generally dependent on the resource being accessed, not the current principal.

This document describes a way for a user to grant access to other resources, sidestepping WebDAV ACL. WebDAV ACL is still relevant though. The DAV:share ACL privilege is used to indicate that a user is allowed to share a resource. This specification uses the DAV:read and DAV:read-write access levels to indicate the access level of the shared resource. These privileges don't directly correlate to ACL privileges. It's left up to the implementor to decide which ACL privileges are the most appropriate for both DAV:read and DAV:read-write. The following is a suggestion: Sharees with a DAV:read share-access level, may typically at least expect DAV:read, DAV:write-properties, DAV:read-current-user-privilege set. For DAV:read-write, this also includes DAV:write, DAV:write-content, and if the shared resource is a collection, DAV:bind and DAV:unbind. These privileges are typically applied to the shared resource and all its child resources (if any). There is no requirement for the shared instance to have a DAV:owner element that refers to the original sharer. In fact, it SHOULD probably be the sharee. Likewise, there is also no requirement for the original sharer to have any privileges to any of the sharee instances.