Cosmo 0.2 Specification

Overview

Goals and Objectives

Cosmo 0.2 has four primary goals:

1. Support for Chandler 0.6 sharing features
2. An interface for end users to sign up for and manage their own accounts
3. Basic standards-based interoperability with calendar clients other than Chandler
4. Windows platform support
5. Special support for Apple iCal so that their calendar sharing format (which is iCalendar, but not CalDAV) can be translated from (and possibly to) the format used by CalDAV/Chandler.

Brian Moseley

Spec owner, development lead

Background

The initial version of Cosmo focused on securely providing basic sharing support for multiple users in a single repository. Sharing in Cosmo 0.1 is performed solely by WebDAV; there are no calendar-specific features. A user can synchronize a collection across multiple instances of Chandler by storing opaque data files in the user's Cosmo home directory. However, Cosmo 0.1 does not provide a mechanism for allowing a second user to view or edit the collection.

In Cosmo 0.1, an administrator has to log into the "admin console" web user interface to provision an account for an end user and then email or otherwise communicate the account details to the user. This is a significant barrier to usage of Chandler's sharing and synchronization features, especially considering that OSAF (and perhaps other organizations) will in the future host a public Cosmo server for users who are not part of a workgroup with a dedicated Cosmo installation and administrator.

One of the primary goals for the eventual Cosmo 1.0 is interoperability with standards-based calendar clients via CalDAV. A staged approach toward CalDAV implementation allows the realization of primary interoperability use cases in early Cosmo and Chandler versions. Furthermore, Cosmo should make special allowance for Apple's iCal, which uses the "first generation" technique of publishing and subscribing to monolithic iCalendar resources (events, timezones, and calendar bundled into a single WebDAV resource) rather than the single-iCalendar-object-per-resource approach of CalDAV.

Use Cases

• A Chandler user attempts to share his calendar for the first time. Lacking a WebDAV account, he is given a link to a Cosmo web page where he can sign up for an account.
• A user is entering WebDAV information for an existing Cosmo account into a Chandler installation on a second computer, but he has forgotten his username.
• A user is entering WebDAV information for an existing Cosmo account into a Chandler installation on a second computer, but he has forgotten his password.
• A user changes his username, email address, and/or password via a Cosmo web page.
• A Chandler user shares a calendar with a set of friends who also use Chandler. Some of the friends are allowed to update the calendar, while the others can only view the calendar.
• A Chandler user shares a calendar with a friend who subscribes to it with iCal.
• A Chandler user subscribes to a calendar published by a friend who uses iCal.

Requirements

Tickets (Access control)

Cosmo must accept a ticket specified in the URL of a WebDAV resource in preference to other authentication schemes and access control procedures (e.g. Basic authentication, ACL-based authorization) as per Ticket-Based Access Control Extension to WebDAV (see link at bottom). In addition, must be able to accept ticket-creation requests.

Cosmo 0.2 will not support any mechanisms for controlling access to a user's home directory by another user other than tickets. A future version will allow a user to assign permissions on his home directory to other users (probably only on the same server) via WebDAV ACL and a web user interface.

iCalendar (RFC2445) and CalDAV Interoperability

Cosmo must be able to store iCalendar calendar and event objects in its repository in such a way as to facilitate CalDAV queries, even though those queries are not supported by this version of Cosmo. Addressing this requirement eliminates a significant risk early in Cosmo's development (that of not knowing how much effort it will take to make the repository aware of calendar content) and reduces the amount of data migration necessary when upgrading to future versions.

Cosmo 0.2 must validate new or updated event resources for correct syntax and semantics on each PUT request. GET and DELETE will be handled normally for event resources.

Cosmo will support CalDAV's MKCALENDAR request. Cosmo will advertise support for CalDAV even though not all of CalDAV will be interoperable in 0.2.

Cosmo 0.2 will support PROPFIND on calendar collections, listing individual event resources, but not the special CalDAV REPORTs.

Apple's iCal Interoperability

Basic client/server interoperability with Apple's iCal client will be supported for Cosmo 0.2. Apple's iCal works with calendar data at a granularity of one file per calendar and expects to be able to GET, PUT and DELETE whole-calendar iCalendar resources (iCal does not understand CalDAV collections or single-event resources). Cosmo will translate to and from this format for both read and write operations as follows.

• iCal expects to be able to use a single resource with a URL ending in .ics and a certain MIME type (text/calendar). Cosmo will handle these URLs, managing a dynamic resource that will appear alongside a CalDAV calendar collection URL, in the same parent collection.
• A GET request to the URL used by iCAL will be handled by the Cosmo server bundling the calendar data into a single .ics file for the response.
• A DELETE request will remove the calendar collection as well as the monolithic calendar resource.
• A PUT request will be interpreted and individual event resources in the calendar collection will be added, overwritten or deleted as appropriate (not overwritten wholesale). More on this in protocol interactions section.

Chandler share data

Cosmo must allow Chandler to store arbitrary data files within a calendar collection. When sharing an ItemCollection, Chandler will create a calendar collection in the user's home directory to contain iCalendar resources and beneath that a regular collection to contain the shared ContentItems in Chandler's internal format. Cosmo does not have to understand the names or formats of any of the resources within the subcollection. The subcollection itself does not have to follow any particular naming policy; because CalDAV specifies that calendar collections may not contain other calendar collections, Cosmo can ignore any subcollections of a calendar collection when generating an iCalendar view of a calendar collection.

Assumptions

• The CalDAV server timezone collection functionality is being removed from CalDAV in draft version 06 therefore Cosmo will not support it.
• Tickets do not necessarily represent unique individuals; a ticket can be given to and used by multiple persons.
• Tickets will not be used in the timeframe of Cosmo 0.2 to access the web user interface.
• We are making certain assumptions about Apple's iCal client functionality that will need to be confirmed through interoperability testing or other testing. If our assumptions turn out to be incorrect we'll update the design decisions described here.
• Chandler 0.6 schedule currently includes work for Chandler to support the iCalendar format for event resources and to use it to create resources. This work is required in order to interoperate with Apple iCal and with Cosmo's support for iCal. Morgen confirmed that this is on his 0.6 schedule.

High-level Decisions

Chandler 0.6 will provide a link to a Cosmo account signup page whenever a user is prompted to enter WebDAV account information. A future version will support a Cosmo API for automated account creation.

Terminology

Calendar collection

A WebDAV collection that advertises to clients that it may contain calendar resources; may contain non-calendar resources and collections but may not contain calendar collections.

ContentItem

A piece of information stored by Chandler such as a calendar, event, or email message; not shareable itself, only as part of an ItemCollection

Individual iCalendar resource

An HTTP resource containing an iCalendar representation of a single calendar object (calendar, event, or timezone)

ItemCollection

A group of Chandler ContentItems that can be shared between Chandler users; the fundamental unit of sharing for Chandler

Monolithic iCalendar resource

An HTTP resource containing an iCalendar representation of a calendar and its constituent events and timezones

WebDAV collection

A resource on a WebDAV server that can contain other resources; roughly equivalent to a directory or folder in a file system

User Interface / Interaction

Account Signup

This page has a form with these fields:

• username (required, must be unique, 3-32 chars long, legal chars are letters, numbers, underscores, spaces, periods, hyphens, apostrophes)
• email address (required, must be unique, 1-32 chars long)
• password (required, 5-16 chars long)
• password confirmation (required, must match password)
• Full name (required, 1-100 chars long)

The user registration form captures full name so that later on we can use this information in places like access logs, interfaces to browse peoples' calendars, etc. If we don't capture full name now then there will be accounts created on test and trial servers which don't have this information. Asking for full name is appropriate for the dogfood usage expected in 0.2 timeframe although later in hosting situations we might find some resistance from users who don't want to reveal full names.

The email address is required to be unique so that we can look up accounts even when login IDs are forgotten. It is easier to change our minds later and relax this requirement than it is to go the other way.

When the form is submitted, the server validates the input.

• If validation fails, the form is redisplayed including a message for each error
• Otherwise the server creates the account, sends a confirmation email to the specified address, logs in the user and displays the Welcome Page.

Account Management

This page has a form with the same fields as on the Account Signup page. The validation rules are slightly different in that the password and confirmation are not required if the password is not being changed (but both are required if the password is being changed).

When the form is submitted, the server validates the input.

• If validation fails, the form is redisplayed including a message for each error.
• Otherwise the server updates the account and redisplays the Account Management Page.

Forgotten Username or password

This popup has a form containing a single email address field.

When the form is submitted, the server validates the given address.

• If an account does not exist with the address, the form is redisplayed including an error message.
• Otherwise, the server sends an email to the address containing the username of the associated account and redisplays the Login Page.

Forgotten Password

This popup has a form containing a single username field.

When the form is submitted, the server validates the given username.

• If an account does not exist with the username, the form is redisplayed including an error message.
• Otherwise, the server sends an email containing the password of the associated account to the account's address and redisplays the Login Page.

Protocol Interactions

Tickets

Cosmo will implement the MKTICKET and DELTICKET methods defined in Ticket-Based Access Control Extension to WebDAV (see link at bottom). The response to a MKTICKET request will include only the tickets owned by the user sending the request (including the one just created). Cosmo will fully support ticket timeouts. Cosmo will not support PROPFIND requests for the ticketdiscovery property.

Deviations from Spec

The Xythos ticket implementation differs from the specification in numerous ways. In order to promote interoperability, Cosmo will align with the Xythos implementation as much as possible, looking forward to a new version of the spec in the near future.

• Visit limits are not supported (and will likely be removed from future versions of the spec). Cosmo will always return the value infinity for the visits element.
• The custom XML namespace http://www.xythos.com/namespaces/StorageServer is used for the ticketdiscovery, ticketinfo, id and timeout elements.
• Valid values for the timeout element are infinity for tickets that never time out and strings of the form Seconds-xxxx where xxxx is the lifetime of the ticket in seconds.
• If different tickets are included in the request headers and URL, the ticket in the URL is used.
• If a DELTICKET request is received for a resource or ticket on which the requesting principal does not have access privileges, Cosmo returns a 403 (Forbidden) response. Example: user A owns resource X and creates ticket 123 on it. user B does not have privileges on resource X but attempts to delete the ticket.

CalDAV

Cosmo will implement individually-addressable calendar objects and the MKCALENDAR method as per Calendaring Extensions to WebDAV (CalDAV) (see link at bottom). It will also support WebDAV Class 1 except for PROPPATCH, SSL, and strong ETags, but not WebDAV ACL or the REPORTs defined by CalDAV.

iCal's usage

Although iCal uses normal HTTP and WebDAV requests (PUT, GET in particular), its data model is inconsistent with that of CalDAV and that used by Chandler. Thus, Cosmo will require special handling of certain requests from iCal.

Handling iCal GET requests is expected to be rather straightforward. Cosmo will take all the event resources in the calendar collection (the one with the same base name as the URL used by iCal) and wrap those events up into one iCalendar file with START:VCALENDAR and END:VCALENDAR around it. For 0.2, where performance isn't likely to be a problem, Cosmo can concatenate event data either in memory or while streaming over the wire.

Handling iCal PUT requests requires a little more care.

• Parse the entire iCalendar file and reject the PUT request if it can't be parsed.
• Compare the list of events from iCal to the list of events in the calendar collection. If the calendar collection doesn't yet exist, create it and all the event resources inside it. If it does already exist, figure out which events are new in the iCal data and which resources are absent in the iCal data (deleted).
• For each event that is new in the iCal data, create a new event resource in the calendar collection, preserving all the data provided.
• For each event that is absent in the iCal data, delete the event resource in the calendar collection.
• For events that appear in both the iCal data and the existing calendar collection, determine if the event data is identical or has been changed. See note.
• For events that have not been changed, leave the event resource untouched so that the ETag doesn't change and Chandler synchronization works better.
• For events that have changed, update the event resource.

Note: One concern with this plan is what to do if Apple iCal alters event data routinely. For example, Chandler wishes to preserve timezone information for each event but it's conceivable that iCal might translate all events to UTC and lose that information. If we run into any of these kinds of issues we may or may not be able to deal with it easily.

Special Considerations

QA / Test

Cosmo will provide a full suite of unit and integration tests for every subsystem so that QA can focus on functional and security testing. This should involve verifying the behaviors described in the "User Interface/Interaction" section above and attempting to compromise the system (see "Security" below).

As we do not have any explicit performance or scalability goals at this time, tests in those areas should probably be limited to establishing a baseline which can be used to compare the qualities of successive versions.

API / Developer Platform

Cosmo 0.2 will not support any external APIs.

Security

Historically many web sites and applications have been susceptible to URL hacking, SQL injection, cross site scripting, and similar attacks. A professional web application in 2005 has no excuse for these sorts of vulnerabilities.

Other security concerns include verifying that a generated ticket has exactly the requested set of permissions (read or read/write) on the associated resource only (the ticket should not allow access to any other resource) and assuring that the tickets cannot be forged or spoofed.

Unfortunately the ticket scheme is inherently insecure, even more so due to Chandler 0.6's policy of using non-expiring, infinite-use tickets. This means that a ticket-bearing URL placed on a web page could be indexed by Google, for instance, making the ticketed resource available to the world at large. The only way to guarantee the security of a ticket in a sharing notification is by exchanging the URL in a fully encrypted fashion (via S/MIME, for example) and not exposing it to unauthorized or untrusted clients.

Furthermore, Chandler 0.5 does not support WebDAV over SSL, so tickets are exposed as soon as they are generated by the server and sent to the client. Chandler 0.6, however, will support WebDAV over SSL.

Cosmo 0.2 will only support Basic authentication and ticket access control. A future version will add Digest support in preference to Basic.

Internationalization / Localization

JSTL and Java message resource bundles will be used to provide an internationalized web user interface. The web interface will be designed to be as locale-independent as possible (avoiding intermixing widgets and text, using coarse-grained message resources, etc). The only shipped localization will be US English, but we will obviously accept localizations in this area.

Exceptions and other messages written to the Cosmo logs will be in US English. There are no plans to provide localized log messages in future versions of Cosmo, although we are open to debate on this issue.

Questions of internationalization of the data stored in the Cosmo repository are deferred to a later version.

Accessibility

Not enough is known about web user interface accessibility at this time. It is anticipated that future versions of Cosmo will provide keyboard shortcuts and utilize other XHTML accessibility mechanisms as appropriate. Community discussions on this topic are welcomed.

Build / Install

Cosmo's build system will be migrated from Ant to Maven, and the source code will be moved from CVS to Subversion.

Deferred Features

• scalability improvements to admin console
• formal graphic and interaction design
• migrate from Tiles to SiteMesh
• extended CalDAV interop (OPTIONS, misc spec compliance sections 3-6)
• web browser interop (GET HTML view of calendar collection)
• digest authen for WebDAV/CalDAV
• external auth API
• reference external auth plugin
• auth mgmt service
• auth mgmt command line tool
• advanced Windows support (run as service)
• migrate from RDBMS to JCR for auth info