Abstract

This document defines a standardized form of Freebusy read URL to improve interoperability between client and server implementations, while extending the functionality and utility through the use of optional parameters.

Foreword

This document incorporates by reference the CalConnect Intellectual Property Rights, Appropriate Usage, Trademarks and Disclaimer of Warranty for External (Public) Documents as located at

http://www.calconnect.org/documents/disclaimerpublic.pdf.

1.  References

2.  Conventions Used in This Document

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in IETF RFC 2119.

3.  Freebusy Read URL

The read URL is used to get Freebusy information for a single user. (Note this document does not define a read URL to get the Freebusy information for a group.) A client or user could use this URL by putting it into an FBURL property of a VCARD as defined in IETF RFC 2739, Section 2.3.1, or it could be published in a calFBURL attribute of an LDAP directory record for a user as defined in IETF RFC 2739, Section 2.4.4.2.

This document does not address how the URL is obtained, either by the owner of the Freebusy information or by the user of that information.

It is assumed that the owner has some means of obtaining a URL from the calendaring client and that they can transfer it to interested users through some means, such as email.

When the content of a Freebusy URL is accessed, Freebusy information can be returned as VFREEBUSY iCalendar components, as defined by IETF RFC 2445. Such a VFREEBUSY iCalendar component is not meant to conform to the requirements of VFREEBUSY components in IETF RFC 2446. The VFREEBUSY component SHOULD conform to section “4.6.4 Free/Busy Component” of IETF RFC 2445. The VFREEBUSY component SHOULD NOT have a METHOD property, a client MUST ignore the METHOD property, if one is present. The VFREEBUSY component MAY follow the publish setting in regards to the ORGANIZER field. A client SHOULD ignore the ORGANIZER field. Since a Freebusy URL can only refer to a single user, a client will already know how to match the requested VFREEBUSY component to a user. A server MUST only return a single VFREEBUSY component.

4.  URL Query Parameters

These are the recognized parameters for the Freebusy read URL which relate to the desired range and format of the returned data.

None of these parameters are required except for the conditions noted below. Appropriate defaults will be supplied by the server.

Implementation Notes: Date-only start and end times, i.e. a date/time value without a time component (e.g. 20080101), are not supported because time zone support would be required.

5.  URL Identity Parameters

These are the recognized parameters for the Freebusy read URL which deal with the identity of the requestor and the user for whom Freebusy data is being requested and the security of the transaction. These parameters may be encoded in a URL or as query parameters as defined in Clause 8

Some services may require the presence of a token and/or the user parameter as a form of low-level security.

6.  HTTP Operations

The server SHOULD return an Etag response header for a successful GET request targeting a Freebusy read URL. Clients MAY use the ETag response header value to do subsequent “conditional” GET requests that will avoid re-sending the Freebusy data again if it has not changed. The read URL is only valid when used with an HTTP GET IETF RFC 2616.

7.  Examples

The following are examples of URLs used to retrieve Freebusy data for a user:

The following are examples of URLs used to retrieve Freebusy data for a user where the userid has been obfuscated:

Some Request/Response Examples:

GET /freebusy/bernard/ HTTP/1.1
Host: www.example.com

HTTP/1.1 200 OK
Content-Type: text/calendar; charset="utf-8"
Content-Length: xxxx

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VFREEBUSY
ORGANIZER;CN="Bernard
Desruisseaux":mailto:bernard@example.com
UID:76ef34-54a3d2@example.com
DTSTAMP:20050530T123421Z
DTSTART:20060101T000000Z
DTEND:20060108T000000Z
FREEBUSY:20050531T230000Z/20050601T010000Z
FREEBUSY;FBTYPE=BUSYTENTATIVE:
20060102T100000Z/20060102T120000Z
FREEBUSY:20060103T100000Z/20060103T120000Z
FREEBUSY:20060104T100000Z/20060104T120000Z
FREEBUSY;FBTYPE=BUSYUNAVAILABLE:
20060105T100000Z/20060105T120000Z
FREEBUSY:20060106T100000Z/20060106T120000Z
END:VFREEBUSY
END:VCALENDAR

GET /freebusy/user1@example.com?start=2007-09-
01T00:00:00-08:00&end=2007-09-31T00:00:00-08:00
HTTP/1.1
Host: www.example.com

HTTP/1.1 200 OK
Content-Type: text/calendar; charset="utf-8"
Content-Length: xxxx

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example Corp.//CalDAV Client//EN
BEGIN:VFREEBUSY
ORGANIZER:
UID:76ef34-54a3d3@example.com
DTSTAMP:20070905T100000Z
DTSTART:20070901T080000Z
DTEND:20070931T080000Z
FREEBUSY:20070903T230000Z/20070904T010000Z
FREEBUSY;FBTYPE=BUSYTENTATIVE:
20070906T100000Z/20070906T120000Z
FREEBUSY:20070908T100000Z/20070908T120000Z
FREEBUSY:20070909T100000Z/20070909T120000Z
FREEBUSY;FBTYPE=BUSYUNAVAILABLE:
20070915T100000Z/20070917T120000Z
FREEBUSY:20070920T100000Z/20070922T120000Z
END:VFREEBUSY
END:VCALENDAR

GET /freebusy/user1@example.com?start=2012-12-
01T00:00:00-08:00&end=2012-12-31T00:00:00-08:00
HTTP/1.1
Host: www.example.com

HTTP/1.1 404 No Data

8.  Template URLs

In some cases, it may be useful for a client to understand the structure of the read URLs. One such example is a CalDAV server that publishes Freebusy data for an entire group of users.

Template URLs are defined in a draft specification available at URI-Templates. A client can request a read template URL that the client can then use to create normal, i.e. non template, URLs for different users on the same Freebusy server. The following table defines those keys clients must understand to successfully build a URL from a template.

9.  IANA Considerations

This document does not require any actions on the part of IANA.

10.  Security Considerations

For servers using the token approach for authentication, the token should be considered private. A client should take steps to safeguard the token. The token approach isn’t perfect security; a token could become more widely distributed than intended or anticipated.

Servers SHOULD provide a means for token values to be automatically or manually expired. Services SHOULD consider obfuscating the userid in a Freebusy URL. A service SHOULD prevent a client from probing for valid userids which might reveal private information about users such as their email address. A server MAY return an HTTP 404 error rather than an HTTP 403 error when the requester does not have permission to view the Freebusy information of the requested user.

Servers MAY support HTTP Authentication IETF RFC 2616 for access to the Freebusy URL content.

HTTP protocol transactions are sent in the clear over the network unless protection from snooping is negotiated. This can be accomplished by use of TLS, as defined in IETF RFC 2818. In particular, HTTP Basic authentication, as defined in IETF RFC 2616, MUST NOT be used unless TLS is in effect.

Servers MUST take adequate precautions to ensure that clients cannot consume excessive server resources (CPU, memory, disk, etc.) through intentionally malicious requests. For example, a request may be made for an inappropriate amount of time, e.g. 100 years. A server is free to fail such a request.

When rolling up Freebusy information, more information than necessary about a user’s events is exposed if busy periods overlap or are adjacent (this tells the client requesting the Freebusy information that the calendar owner has at least two events, rather than knowing only that the calendar owner has one or more events during the busy period).

Thus, a conservative approach to calendar data privacy would have servers always coalesce such busy periods when they are the same type. Security considerations described in iCalendar IETF RFC 2445 and iTIP IETF RFC 2446 are also applicable.