Network Working Group M. Douglass Internet-Draft Spherical Cow Group Intended status: Standards Track April 17, 2016 Expires: October 19, 2016 DAV Server Information Object draft-douglass-server-info-03 Abstract This specification describes a new XML object that can be retrieved from hosts to discover applications, 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 October 19, 2016. Copyright Notice Copyright (c) 2016 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 October 19, 2016 [Page 1] Internet-Draft Dav Server Information Object April 2016 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2.1. Application . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Feature . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Server Information Document Use . . . . . . . . . . . . . . . 4 3.1. Server Information Location and Retrieval . . . . . . . . 4 3.1.1. Server Information Retrieval . . . . . . . . . . . . 4 3.1.2. Server Information Synchronization . . . . . . . . . 5 3.1.2.1. Header Field: server-info-token . . . . . . . . . 5 3.1.2.2. Header Field: link . . . . . . . . . . . . . . . 5 4. Server Information Document Structure . . . . . . . . . . . . 6 4.1. Server Information server-info element . . . . . . . . . 6 4.2. Server Information server element . . . . . . . . . . . . 7 4.3. Server Information applications element . . . . . . . . . 7 4.3.1. Server Information application element . . . . . . . 7 4.4. Server Information features element . . . . . . . . . . . 8 4.4.1. Server Information feature element . . . . . . . . . 8 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 9 5.1. server-info XML element . . . . . . . . . . . . . . . . . 9 5.2. token XML element . . . . . . . . . . . . . . . . . . . . 9 5.3. server-instance-info XML element . . . . . . . . . . . . 9 5.4. name XML element . . . . . . . . . . . . . . . . . . . . 10 5.5. version XML element . . . . . . . . . . . . . . . . . . . 10 5.6. applications XML element . . . . . . . . . . . . . . . . 10 5.7. application XML element . . . . . . . . . . . . . . . . . 10 5.8. features XML element . . . . . . . . . . . . . . . . . . 11 6. WebDAV Features . . . . . . . . . . . . . . . . . . . . . . . 11 6.1. DAV class-1 feature XML element . . . . . . . . . . . . . 11 6.2. DAV class-2 feature XML element . . . . . . . . . . . . . 12 6.3. DAV class-3 feature XML element . . . . . . . . . . . . . 12 6.4. DAV access control feature XML element . . . . . . . . . 12 6.5. DAV version control feature XML element . . . . . . . . . 13 6.6. DAV Extended mkcol feature XML element . . . . . . . . . 13 6.7. DAV bind feature XML element . . . . . . . . . . . . . . 13 6.8. DAV search feature XML element . . . . . . . . . . . . . 14 6.9. DAV quota feature XML element . . . . . . . . . . . . . . 14 6.10. DAV Sync Collection feature XML element . . . . . . . . . 14 6.11. DAV Add Member feature XML element . . . . . . . . . . . 15 7. CalDAV Features . . . . . . . . . . . . . . . . . . . . . . . 15 7.1. CalDAV calendar-access feature XML element . . . . . . . 15 7.2. CalDAV calendar-auto-schedule feature XML element . . . . 16 7.3. CalDAV calendar-no-timezone feature XML element . . . . . 16 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 16 8.1. WebDAV server information . . . . . . . . . . . . . . . . 16 9. Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 10. Security Considerations . . . . . . . . . . . . . . . . . . . 17 Douglass Expires October 19, 2016 [Page 2] Internet-Draft Dav Server Information Object April 2016 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 11.1. MIME media type Registrations . . . . . . . . . . . . . 17 11.2. New Link reltype Registration . . . . . . . . . . . . . 18 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 13. Normative References . . . . . . . . . . . . . . . . . . . . 18 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 1. Introduction Any given host on a network may support a number of applications. Each will have limits or optional features. The advertising and discovery of applications, features and limits is often through the use of properties and headers. As the number of applications 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 application 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 applications. The schema as described here only handles basic DAV applications. Other specifications will extend this specification to define elements for other DAV based applications. 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. Application An application running on one or more hosts at the network application layer and above. The application may provide data storage, manipulation, presentation, communication or other capabilities. The application may use a well defined protocol and is often implemented with a client-server relationship. A application will usually implement one or more features which may be defined by standard specifications. Applications and features may also be constrained by various limits. Examples of applications are o caldav Douglass Expires October 19, 2016 [Page 3] Internet-Draft Dav Server Information Object April 2016 o email o File servers 2.2. Feature A feature is some functionality provided by a application. For example, a DAV based application may provide the versioning feature. Applications need not support all features that are defined as an optional part of that application. 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 applications. If a document provides information for more than one application it SHOULD contain information allowing clients to obtain information about each individual application only. This allows a client to determine what the actual limits and features are for the specific application. 3.1. Server Information Location and Retrieval 3.1.1. Server Information Retrieval The document may be retrieved from the server by including the server-info-token header field with a value of "*" any request to the server. The server MUST respond to such a request by including a LINK header field with a reltype of "server-info", a token parameter with the current token value and the url being the location of the document.. Douglass Expires October 19, 2016 [Page 4] Internet-Draft Dav Server Information Object April 2016 Following that a GET may be executed by the client against that URL, specifying a content type in the ACCEPT header field of "application/ server-info+xml". Clients SHOULD retrieve the document in the context of a session and applications 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 application. 3.1.2. 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 server feature changes is undesirable so this specification allows clients to check for such changes during normal operations. Clients SHOULD include the server-info-token header field with the current stored value of the token from the document in requests to the server The server MUST add the link header field to the response when the tokens do not match. 3.1.2.1. Header Field: server-info-token The server-info-token header field takes as a value the current value of the token element in the server-info document or the value "*". This header field may be included in a request at any time a client feels appropriate. 3.1.2.2. Header Field: link The link header field is defined in [RFC5988]. The target IRI as defined by that specification will be the location of the server information document. The "reltype" parameter will have the value "server-info". Additionally, there will be a "token" parameter which has a quoted token as the value. This header field may be included in a response at any time a server feels appropriate. The link header field MUST be returned in response to: Douglass Expires October 19, 2016 [Page 5] Internet-Draft Dav Server Information Object April 2016 o An OPTIONS request where the server-info-token header is absent or it's value does not match. o Any request with the server-info-token header field where the value of the header field does not math the current token value. The link header field SHOULD be returned when a client o Attempts to use an unsupported feature. o Misuses a feature according to the server info document. o Exceeds a limit defined in the document. If the server returns a link header field as part of the response it is an indication to the client that it SHOULD fetch a new copy of the server information document. The following is an example of a link header field - folded to fit on the page Link: ; rel="server-info"; token="7140903ee1b57d0752a7d8da774a398b10de5868" 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 an "applications" element Douglass Expires October 19, 2016 [Page 6] Internet-Draft Dav Server Information Object April 2016 ... ... ... ... ... If a "features" element appears inside the "server-info" element then the features apply to all applications. 4.2. Server Information server element The optional "server" element appears once and contains a name and version for the server. The values for both those elements is server specific. 4.3. Server Information applications element The "applications" element appears once and contains 0 or more "application" elements each of which provides information about a application. NOTE: do the applications have to be on the same host? I think not. 4.3.1. Server Information application element The "application" element contains the name and information about the location of that application and how to obtain a application specific server-info document. It may also contain a "features" element which lists features implemented by that application. For example: Douglass Expires October 19, 2016 [Page 7] Internet-Draft Dav Server Information Object April 2016 caldav 4.4. Server Information features element The "features" element contains 0 or more elements each specifying a feature supported by that application. The "features" element may appear within the "server-info" element - in which case it applies to all applications or it may appear inside a "application" element in which case it only applies to that application. When a single application is specified the features named SHOULD be accessible for the same authentication and authorization level. 4.4.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 field. Some features have no corresponding DAV header field element. This may be because the feature is not available on all resources. The occurrence of a such a feature simply advertises the availability of that feature on some resources. For an application supporting this specification, the absence of a feature means that this feature is NOT supported on any resource. For example, a calendar application may return the following which specifies a global set of features: Douglass Expires October 19, 2016 [Page 8] Internet-Draft Dav Server Information Object April 2016 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 server. Definition: 5.2. token XML element Name: token Purpose: Contains an opaque token which changes when the document changes.. Definition: 5.3. server-instance-info XML element Name: server-instance-info Purpose: Contains name and version information for a server. Definition: Douglass Expires October 19, 2016 [Page 9] Internet-Draft Dav Server Information Object April 2016 * product name * product version * product bug tracker link (or just link) * system administrator contact ("mailto:", "tel:" an embedded vcard or a link to a vcard?) * operating system info (string like the result of "uname -a" on POSIX systems) 5.4. name XML element Name: name Purpose: Within an application or feature element provides the registered name of that application or feature. Within a server element the value of the name element is any text string. Definition: 5.5. version XML element Name: version Purpose: Within a server element the value of the version element is any text string. Definition: 5.6. applications XML element Name: applications Purpose: Contains information about all applications on a host. Definition: 5.7. application XML element Name: application Douglass Expires October 19, 2016 [Page 10] Internet-Draft Dav Server Information Object April 2016 Purpose: Contains information about a specific application on a host. Definition: 5.8. features XML element Name: features Purpose: Contains information about all application features on a host. Definition: 6. WebDAV Features Here we define the feature elements for features defined in the various DAV related specifications. 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 | bind | [RFC5842] | | DAV | search | [RFC5323] | | DAV | sync-collection | [RFC6578] | | DAV | add-member | [RFC5995] | +------------+-----------------+-------------------------+ 6.1. DAV class-1 feature XML element Namespace: DAV Name: class-1 Douglass Expires October 19, 2016 [Page 11] Internet-Draft Dav Server Information Object April 2016 DAV Header Name: 1 Reference: [RFC4918]: section 18.1 Description: Class 1 compliant resource Definition: 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: 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: 6.4. DAV access control feature XML element Namespace: DAV Name: access-control Douglass Expires October 19, 2016 [Page 12] Internet-Draft Dav Server Information Object April 2016 DAV Header Name: access-control Reference: [RFC3744]: section 7.2 Description: WebDAV ACL Definition: 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: 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: 6.7. DAV bind feature XML element Namespace: DAV Name: bind Douglass Expires October 19, 2016 [Page 13] Internet-Draft Dav Server Information Object April 2016 DAV Header Name: bind Reference: [RFC5842] Description: Binding extensions Definition: 6.8. DAV search feature XML element Namespace: DAV Name: search Reference: [RFC5323] Description: Search extensions Definition: 6.9. 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: 6.10. DAV Sync Collection feature XML element Namespace: DAV Name: sync-collection Reference: [RFC6578] Douglass Expires October 19, 2016 [Page 14] Internet-Draft Dav Server Information Object April 2016 Description: Collection synchronization report. May not apply to all resources. Absence of this feature implies no support on any resource. Definition: 6.11. 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: 7. CalDAV Features Here we define the feature elements for features defined in the various CalDAV related specifications. All of these are under the CalDAV namespace urn:ietf:params:xml:ns:caldav +------------------------+------------+ | Name | Reference | +------------------------+------------+ | calendar-access | [RFC4791] | | calendar-auto-schedule | [RFC6638] | | calendar-no-timezone | RFC???? | +------------------------+------------+ 7.1. CalDAV calendar-access feature XML element Namespace: urn:ietf:params:xml:ns:caldav Name: calendar-access Reference: [RFC4791] Douglass Expires October 19, 2016 [Page 15] Internet-Draft Dav Server Information Object April 2016 Description: Calendar access Definition: 7.2. CalDAV calendar-auto-schedule feature XML element Namespace: urn:ietf:params:xml:ns:caldav Name: calendar-auto-schedule Reference: [RFC4791] Description: CalDAV implicit scheduling Definition: 7.3. CalDAV calendar-no-timezone feature XML element Namespace: urn:ietf:params:xml:ns:caldav Name: calendar-no-timezone Reference: [RFC4791] Description: CalDAV implicit timezones Definition: 8. Examples 8.1. WebDAV server information TBD. 9. 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 application 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 Douglass Expires October 19, 2016 [Page 16] Internet-Draft Dav Server Information Object April 2016 appropriate. Caching by intermediaries might be an issue Server info may vary by user-agent. * product name * product version * product bug tracker link (or just link) * system administrator contact ("mailto:", "tel:" an embedded vcard or a link to a vcard?) * operating system info (string like the result of "uname -a" on POSIX systems) Add something about rscale - calendar-rscale element 10. Security Considerations TBD. Something about not sending server name + version. Opaque version code. 11. IANA Considerations 11.1. MIME media type Registrations Media Type: This section defines the MIME media type for use with the server information document. Type name: application Subtype name: server-info+xml Required parameters: None Optional parameters: charset as defined for application/xml in [RFC3023]; per [RFC3023], use of the charset property parameter with the value "utf-8" is STRONGLY RECOMMENDED. Encoding considerations: Same as encoding considerations of application/xml as specified in [RFC3023]. Security considerations: See previous section. Interoperability considerations: This media type provides an alternative format for iCalendar data based on XML. Published specification: This specification. Additional information: Magic number(s): None Douglass Expires October 19, 2016 [Page 17] Internet-Draft Dav Server Information Object April 2016 File extension(s): xml Macintosh file type code(s): None specified. Person & email address to contact for further information: calsify@ietf.org Intended usage: COMMON Restrictions on usage: There are no restrictions on where this media type can be used. Author: See the "Authors' Addresses" section of this document. Change controller: IETF 11.2. New Link reltype Registration The link relation type "server-info" has been added to the Reference Types Registry defined in Section 6.2 of [RFC5988] wilt the following values o Relation Name: server-info o Description: Provides the location of and current token for the server information document o Reference: This specification 12. 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. 13. 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, DOI 10.17487/RFC2119, March 1997, . Douglass Expires October 19, 2016 [Page 18] Internet-Draft Dav Server Information Object April 2016 [RFC2518] Goland, Y., Whitehead, E., Faizi, A., Carter, S., and D. Jensen, "HTTP Extensions for Distributed Authoring -- WEBDAV", RFC 2518, DOI 10.17487/RFC2518, 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, DOI 10.17487/RFC3253, March 2002, . [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, . [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. Whitehead, "Web Distributed Authoring and Versioning (WebDAV) Access Control Protocol", RFC 3744, DOI 10.17487/RFC3744, May 2004, . [RFC4331] Korver, B. and L. Dusseault, "Quota and Size Properties for Distributed Authoring and Versioning (DAV) Collections", RFC 4331, DOI 10.17487/RFC4331, February 2006, . [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, DOI 10.17487/RFC4791, March 2007, . [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, June 2007, . [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, "Web Distributed Authoring and Versioning (WebDAV) SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, . [RFC5689] Daboo, C., "Extended MKCOL for Web Distributed Authoring and Versioning (WebDAV)", RFC 5689, DOI 10.17487/RFC5689, September 2009, . Douglass Expires October 19, 2016 [Page 19] Internet-Draft Dav Server Information Object April 2016 [RFC5842] Clemm, G., Crawford, J., Reschke, J., Ed., and J. Whitehead, "Binding Extensions to Web Distributed Authoring and Versioning (WebDAV)", RFC 5842, DOI 10.17487/RFC5842, April 2010, . [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, . [RFC5995] Reschke, J., "Using POST to Add Members to Web Distributed Authoring and Versioning (WebDAV) Collections", RFC 5995, DOI 10.17487/RFC5995, September 2010, . [RFC6578] Daboo, C. and A. Quillaud, "Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)", RFC 6578, DOI 10.17487/RFC6578, March 2012, . [RFC6638] Daboo, C. and B. Desruisseaux, "Scheduling Extensions to CalDAV", RFC 6638, DOI 10.17487/RFC6638, June 2012, . 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 October 19, 2016 [Page 20]