DAV Server Information Object
draft-douglass-server-info-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Author | Michael Douglass | ||
| Last updated | 2015-05-13 | ||
| RFC stream | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-douglass-server-info-00
Network Working Group M. Douglass
Internet-Draft Spherical Cow Group
Intended status: Standards Track May 13, 2015
Expires: November 14, 2015
DAV Server Information Object
draft-douglass-server-info-00
Abstract
This specification describes a new XML object that can be retrieved
from hosts to discover services, features and limits for that host or
domain.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 14, 2015.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Douglass Expires November 14, 2015 [Page 1]
Internet-Draft Dav Server Information Object May 2015
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
2.1. Service . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Feature . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Server Information Document Use . . . . . . . . . . . . . . . 4
3.1. Server Information Location and Retrieval . . . . . . . . 4
3.1.1. DAV:server-info-href property . . . . . . . . . . . . 4
3.1.2. Server Information Retrieval . . . . . . . . . . . . 5
3.1.3. Server Information Synchronization . . . . . . . . . 5
3.1.3.1. Header: server-info-token . . . . . . . . . . . . 5
3.1.3.2. Header: if-not-server-info-token . . . . . . . . 6
4. Server Information Document Structure . . . . . . . . . . . . 6
4.1. Server Information server-info element . . . . . . . . . 6
4.2. Server Information services element . . . . . . . . . . . 6
4.2.1. Server Information service element . . . . . . . . . 6
4.3. Server Information features element . . . . . . . . . . . 7
4.3.1. Server Information feature element . . . . . . . . . 7
5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 8
5.1. server-info XML element . . . . . . . . . . . . . . . . . 8
5.2. token XML element . . . . . . . . . . . . . . . . . . . . 8
5.3. services XML element . . . . . . . . . . . . . . . . . . 8
5.4. service XML element . . . . . . . . . . . . . . . . . . . 9
5.5. name XML element . . . . . . . . . . . . . . . . . . . . 9
5.6. href XML element . . . . . . . . . . . . . . . . . . . . 9
5.7. features XML element . . . . . . . . . . . . . . . . . . 9
6. WebDAV Features . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. DAV class-1 feature XML element . . . . . . . . . . . . . 10
6.2. DAV class-2 feature XML element . . . . . . . . . . . . . 10
6.3. DAV class-3 feature XML element . . . . . . . . . . . . . 11
6.4. DAV access control feature XML element . . . . . . . . . 11
6.5. DAV version control feature XML element . . . . . . . . . 11
6.6. DAV Extended mkcol feature XML element . . . . . . . . . 12
6.7. DAV quota feature XML element . . . . . . . . . . . . . . 12
6.8. DAV Sync Collection feature XML element . . . . . . . . . 12
6.9. DAV Add Member feature XML element . . . . . . . . . . . 13
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1. WebDAV server information . . . . . . . . . . . . . . . . 13
8. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
9. Security Considerations . . . . . . . . . . . . . . . . . . . 13
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13
12. Normative References . . . . . . . . . . . . . . . . . . . . 14
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
Douglass Expires November 14, 2015 [Page 2]
Internet-Draft Dav Server Information Object May 2015
1. Introduction
Any given host on a network may support a number of services. Each
of those services will have limits or optional features. The
advertising and discovery of services, features and limits is often
through the use of properties and headers. As the number of services
and features grows the amount of data and complexity of the requests
grows.
Additionally, headers and properties don't allow for caching
mechanisms based on etags. A client has to fetch all the information
and compare with its stored copies to determine if a service change
has taken place.
This specification defines a new XML document type which can be
retrieved from a host and is easily extended to allow the description
of complex services. The schema as described here only handles basic
DAV services. Other specifications will extend this specification to
define elements for other DAV based services.
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
2.1. Service
By service we mean an application running on one or more hosts at the
network application layer and above. The service may provide data
storage, manipulation, presentation, communication or other
capabilities. The service may use a well defined protocol and is
often implemented with a client-server relationship.
A service will usually implement one or more features which may be
defined by standard specifications. Services and features may also
be constrained by various limits.
Examples of services are
o caldav
o email
o File servers
Douglass Expires November 14, 2015 [Page 3]
Internet-Draft Dav Server Information Object May 2015
2.2. Feature
A feature is some functionality provided by a service. For example,
a DAV based service may provide the versioning feature.
Services need not support all features that are defined as an
optional part of that service. Some features may depend on the
authenticated state and/or the authorization of the authenticated
principal.
Examples of features are
o DAV versioning.
o DAV access control.
o CalDAV scheduling.
3. Server Information Document Use
A host will make the document available through one or more methods.
Depending upon the endpoint and method of retrieval the retrieved
document may describe one or more services.
If a document provides information for more than one service it
SHOULD contain information allowing clients to obtain information
about each individual service only. This allows a client to
determine what the actual limits and features are for the specific
service.
3.1. Server Information Location and Retrieval
3.1.1. DAV:server-info-href property
Name: server-info-href
Namespace: DAV
Purpose: To define the location of the server-info document.
Protected: This property MAY be protected.
PROPFIND behavior: This property SHOULD NOT be returned by a
PROPFIND DAV:allprop request (as defined in Section 14.2 of
[RFC4918]).
COPY/MOVE behavior: This property value SHOULD be preserved in COPY
and MOVE operations.
Douglass Expires November 14, 2015 [Page 4]
Internet-Draft Dav Server Information Object May 2015
Description: This property is needed for a client to determine where
the server information document is located. If not present, then
no document is available for the server.
Definition:
<!ELEMENT server-info-href (DAV:href)>
3.1.2. Server Information Retrieval
The document may be retrieved from the server by doing a PROPFIND on
the .well_known (or any location on the service) for the D:server-
info-href property defined above.
Clients SHOULD retrieve the document in the context of a session and
services SHOULD ensure the context is appropriate. Values in the
returned document may differ depending on who is authenticated so a
server SHOULD require authentication before returning server
information for an authenticated service.
3.1.3. Server Information Synchronization
While server features may not change frequently it may be important
for clients to react rapidly when server features or limits change.
Polling for changes is undesirable so this specification allows for
informing clients when the server information has changed.
The returned server-info document contains an opaque token which the
client can use to determine if the server copy is different. This
token is used in a number of places to aid client synchronization.
3.1.3.1. Header: server-info-token
The server-info-token header takes as a value the current value of
the token element in the server-info document.
This header may be returned with a response at any time a server
feels appropriate. It MAY be returned in response to a request
containing an if-not-server-info-token header.
The server-info-token header MUST be returned for an OPTIONS request.
It SHOULD be returned if a client attempts to use an unsupported
feature or misuse a feature or exceed a limit.
Douglass Expires November 14, 2015 [Page 5]
Internet-Draft Dav Server Information Object May 2015
3.1.3.2. Header: if-not-server-info-token
The if-not-server-info-token header takes as a value the current
token stored by the client. If that value matches the value stored
by the server it SHOULD NOT return a server-info-token header. If
they do not match the server MUST return a server-info-token header
with the current value.
If a new value is returned by the server the client should refetch a
copy of the server info document.
4. Server Information Document Structure
This specification defines a new XML document type "server-info".
All XML elements in this specification are in the DAV name space.
4.1. Server Information server-info element
At the top level of the document is a "server-info" element which
encloses a change token, an optional "features" element and a
"services" element
<?xml version="1.0" encoding="utf-8"?>
<server-info xmlns="DAV">
<token>...</token>
<features>
...
</features>
<services>
...
</services>
</server-info>
If a "features" element appears inside the "server-info" element then
the features apply to all services.
4.2. Server Information services element
The "services" element appears once and contains 0 or more "service"
elements each of which provides information about a service.
NOTE: do the service have to be on the same host? I think not.
4.2.1. Server Information service element
The "service" element contains the name and information about the
location of that service and how to obtain a service specific server-
info document.
Douglass Expires November 14, 2015 [Page 6]
Internet-Draft Dav Server Information Object May 2015
It may also contain a "features" element which lists features
implemented by that service.
For example:
<services>
<features>
<DAV:class-1 />
<DAV:class-2 />
<DAV:access-control />
</features>
<service>
<name>caldav</name>
<href>https:cal.example.org//.well-known/caldav</href>
<features>
<CALDAV:calendar-access />
<CS:sharing>
<CS:no-scheduling />
</CS:sharing>
</features>
</service>
</services>
4.3. Server Information features element
The "features" element contains 0 or more elements each specifying a
feature supported by that service.
The "features" element may appear within the "server-info" element -
in which case it applies to all services or it may appear inside a
"service" element in which case it only applies to that service.
When a single service is specified the features named SHOULD be
accessible for the same authentication and authorization level.
4.3.1. Server Information feature element
A feature is specified by an element defined in this document or by
an element defined in the specification for that feature.
WebDAV feature elements correspond to, but are not exactly the same
as, the elements returned in the DAV header.
Some features have no corresponding DAV header element. This may be
because the feature is not available on all resources. The
occurrence of a such a feature simple advertises the availability of
that feature on some resources.
Douglass Expires November 14, 2015 [Page 7]
Internet-Draft Dav Server Information Object May 2015
For a service supporting this specification, the absence of a feature
means that feature is NOT supported on any resource.
For example, a calendar service may return the following which
specifies a global set of features:
<features>
<DAV:class-1 />
<DAV:class-2 />
<DAV:access-control />
<CALDAV:calendar-access />
<CALDAV:calendar-availability />
<CALDAV:calendar-auto-schedule />
</features>
5. XML Element Definitions
All elements defined here are in the "DAV:" namespace.
5.1. server-info XML element
Name: server-info
Purpose: Contains information about a single service.
Definition:
<!ELEMENT server-info (token, services?, features?) >
5.2. token XML element
Name: token
Purpose: Contains an opaque token which changes when the document
changes..
Definition:
<!ELEMENT token (#PCDATA) >
5.3. services XML element
Name: services
Purpose: Contains information about all services on a host.
Definition:
Douglass Expires November 14, 2015 [Page 8]
Internet-Draft Dav Server Information Object May 2015
<!ELEMENT services (service*) >
5.4. service XML element
Name: service
Purpose: Contains information about a specific service on a host.
Definition:
<!ELEMENT service (name, href?) >
5.5. name XML element
Name: name
Purpose: Within a service or feature element provides the registered
name of that service or feature.
Definition:
<!ELEMENT feature (#PCDATA) >
5.6. href XML element
Name: href
Purpose: Contains location of a specific service.
Definition:
<!ELEMENT href (#PCDATA) >
5.7. features XML element
Name: features
Purpose: Contains information about all service features on a host.
Definition:
<!ELEMENT features ANY* >
6. WebDAV Features
Here we define the feature elements for features defined in the
various DAV related specifications.
Douglass Expires November 14, 2015 [Page 9]
Internet-Draft Dav Server Information Object May 2015
Specifications which extend this specification should define
additions to this table. In addition, they may define the XML
specification for that element.
+------------+-----------------+-------------------------+
| Namespace | Name | Reference |
+------------+-----------------+-------------------------+
| DAV | class-1 | [RFC4918]: section 18.1 |
| DAV | class-2 | [RFC4918]: section 18.2 |
| DAV | class-3 | [RFC4918]: section 18.3 |
| DAV | access-control | [RFC3744]: section 7.2 |
| DAV | version-control | [RFC3253]: section 3 |
| DAV | extended-mkcol | [RFC5689]: section 3.1 |
| DAV | quota | [RFC4331] |
| DAV | sync-collection | [RFC6578] |
| DAV | add-member | [RFC5995] |
+------------+-----------------+-------------------------+
6.1. DAV class-1 feature XML element
Namespace: DAV
Name: class-1
DAV Header Name: 1
Reference: [RFC4918]: section 18.1
Description: Class 1 compliant resource
Definition:
<!ELEMENT class-1 >
6.2. DAV class-2 feature XML element
Namespace: DAV
Name: class-2
DAV Header Name: 2
Reference: [RFC4918]: section 18.2
Description: Class 2 compliant resource
Definition:
Douglass Expires November 14, 2015 [Page 10]
Internet-Draft Dav Server Information Object May 2015
<!ELEMENT class-2 >
6.3. DAV class-3 feature XML element
Namespace: DAV
Name: class-3
DAV Header Name: 3
Reference: [RFC4918]: section 18.3
Description: Class 3 compliant resource
Definition:
<!ELEMENT class-3 >
6.4. DAV access control feature XML element
Namespace: DAV
Name: access-control
DAV Header Name: access-control
Reference: [RFC3744]: section 7.2
Description: WebDAV ACL
Definition:
<!ELEMENT access-control >
6.5. DAV version control feature XML element
Namespace: DAV
Name: version-control
DAV Header Name: version-control
Reference: [RFC3253]: section 3
Description: WebDAV DeltaV
Definition:
Douglass Expires November 14, 2015 [Page 11]
Internet-Draft Dav Server Information Object May 2015
<!ELEMENT version-control >
6.6. DAV Extended mkcol feature XML element
Namespace: DAV
Name: extended-mkcol
DAV Header Name: extended-mkcol
Reference: [RFC5689]: section 3.1
Description: Extended mkcol
Definition:
<!ELEMENT extended-mkcol >
6.7. DAV quota feature XML element
Namespace: DAV
Name: quota
Reference: [RFC4331]
Description: DAV quotas. May not apply to all resources. Absence
of this feature implies no support on any resource.
Definition:
<!ELEMENT quota >
6.8. DAV Sync Collection feature XML element
Namespace: DAV
Name: sync-collection
Reference: [RFC6578]
Description: Collection synchronization report. May not apply to
all resources. Absence of this feature implies no support on any
resource.
Definition:
<!ELEMENT sync-collection >
Douglass Expires November 14, 2015 [Page 12]
Internet-Draft Dav Server Information Object May 2015
6.9. DAV Add Member feature XML element
Namespace: DAV
Name: add-member
Reference: [RFC6578]
Description: Using POST to add a member to a collection. May not
apply to all resources. Absence of this feature implies no
support on any resource.
Definition:
<!ELEMENT add-member >
7. Examples
7.1. WebDAV server information
TBD.
8. Notes
Tag enabling synchronization Document location (section 3) server-
info token in DAV header returned as part of OPTIONS response Clients
that see that and do not have a server-info document for that service
should do a propfind to discover document href. Authenticated v
unauth Clients may fetch the si doc in an unauth mode. When they
auth they must recheck their token and refetch if appropriate.
Caching by intermediaries might be an issue Server info may vary by
user-agent.
9. Security Considerations
TBD.
10. IANA Considerations
TBD.
11. Acknowledgments
This specification is a result of discussions that took place within
the Calendaring and Scheduling Consortium's CalDAV Technical
Committee. The author thanks the participants of that group.
Douglass Expires November 14, 2015 [Page 13]
Internet-Draft Dav Server Information Object May 2015
12. Normative References
[ISO.8601.2004]
International Organization for Standardization, "Data
elements and interchange formats -- Information
interchange -- Representation of dates and times", 2004.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D.
Jensen, "HTTP Extensions for Distributed Authoring --
WEBDAV", RFC 2518, February 1999.
[RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
Whitehead, "Versioning Extensions to WebDAV
(Web Distributed Authoring and Versioning)", RFC 3253,
March 2002.
[RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the
Internet: Timestamps", RFC 3339, July 2002.
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web
Distributed Authoring and Versioning (WebDAV)
AccessA ControlA Protocol", RFC 3744, May 2004.
[RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties fo
r Distributed Authoring and Versioning (DAV) Collections",
RFC 4331, February 2006.
[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed
Authoring and Versioning (WebDAV)", RFC 4918, June 2007.
[RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring
and Versioning (WebDAV)", RFC 5689, September 2009.
[RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed
Authoring and Versioning (WebDAV) Collections", RFC 5995,
September 2010.
[RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for
Web Distributed Authoring and Versioning (WebDAV)", RFC
6578, March 2012.
Douglass Expires November 14, 2015 [Page 14]
Internet-Draft Dav Server Information Object May 2015
Author's Address
Michael Douglass
Spherical Cow Group
226 3rd Street
Troy, NY 12180
USA
EMail: mdouglass@sphericalcowgroup.com
URI: http://sphericalcowgroup.com
Douglass Expires November 14, 2015 [Page 15]