Internet-Draft 07/18/96 draft-oleary-icap-00.txt Expires 01/18/97 ------------------------------------------------------------------------------- Internet Calendar Access Protocol (ICAP) Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF) , its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. 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." To learn the current status of any Internet-Draft, please check the "lid- abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe) , munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract This Internet Calendar Access Protocol (ICAP) allows a client to access, manipulate and store Calendar information on a server. ICAP can be used either as a set of capability extensions to IMAP4 [1] to create a server which supports both messaging and calendaring functions, or as a standalone protocol for a server dedicated to calendaring only. ICAP employs the vCalendar format [2] for interchange of calendaring information. ICAP includes operations for creating Calendar stores on a server, opening them and retrieving information about them. When a Calendar store has been opened, it can be bounded by start and end times so that the client can act on a smaller subset of Calendar information for more efficient operation. ICAP allows users to store new Calendar entries into their own Calendar store and Calendar stores owned by other users with a single operation. NOTE FOR DRAFT VERSION: The IMAP4 specification [1] requires that capabilities that are not part of a standards track revision to the IMAP4 spec, and all commands and responses associated with such "experimental" extensions, be prefixed with an "X". This DRAFT version of the ICAP spec does not use this prefix for purposes of clarity since ICAP can also be used in a standalone mode. The "X" prefix should be inferred whenever a new command or response is added as a capability extension to IMAP4. ------------------------------------------------------------------------------- Page: 1 ------------------------------------------------------------------------------- Overview The Internet Calendar Access Protocol (ICAP) allows clients to access a Calendar store on a server via a network connection like TCP/IP. The operation of ICAP is based on that of the Internet Message Access Protocol Version 4 [1]. This was done so that ICAP could be used in conjunction with IMAP whenever it made sense to closely tie together electronic mail and calendar services. This document specifies a protocol for Calendaring, it does not specify a text-based format for Calendar information interchange. ICAP uses the versit Consortium's vCalendar specification [2] for Calendar information interchange. ICAP is intended to be used in two different ways: first, as a set of capability extensions to IMAP 4 and second as a standalone protocol server. An IMAP server which is also a Calendar server must return ICAP as a capability when queried using the CAPABILITY command. Example: C: a001 CAPABILITY S: * CAPABILITY IMAP ICAP S: a001 OK CAPABILITY completed When ICAP is added as a set of protocol extensions to IMAP4 via TCP, the server listens on port 143, as is the case with IMAP4. In this case, it is essential that the ICAP/IMAP server support all functions and operations of both protocols. When ICAP is used as a standalone protocol, the server listens on TCP port 7668 (subject to change) and states a greeting similar to IMAP: S: * OK ICAP Server ready. Throughout this document, reference will be made to "IMAP/ICAP" servers and "ICAP" servers. "IMAP/ICAP" refers to a server which implements the IMAP4 protocol described in [1] and the protocol defined in this document. "ICAP" refers to a server which implements the protocol defined in this document. IMAP defines 4 states: Non-Authenticated, Authenticated, Selected and Logout. An ICAP/IMAP server must support all of these states as described in [1]. An ICAP server must support all of these states except Selected. When a server supports both ICAP and IMAP, Selected is equivalent to "Mailbox Selected" as Calendar selection is ------------------------------------------------------------------------------- Page: 2 ------------------------------------------------------------------------------- distinct from mailbox access. The ICAP server adds one additional state to the states already defined for IMAP4. The ICAP server supports a state called CalendarSelected, which can be entered via the CALSELECT command. A server which supports IMAP and ICAP can be in both the Selected and CalendarSelected state at the same time. Data Formats Refer to the discussion of "Data Formats" in [1]. All dates given in this document are in the ISO8601 format: yyyymmddThhmmss. A "Z" may be appended to indicate Zulu time (that's GMT to most people). Any date not given in GMT is assumed to be in the time zone of the server. Clients can test and set the time zone using the CALSETTINGS command (see below). ICAP Commands - Any State CAPABILITY Command Arguments: None. Mandatory untagged response: CAPABILITY The ICAP or IMAP/ICAP server must respond with a list of capabilities in a format like that of an IMAP server. The servers must respond with both "IMAP4" and "ICAP", or with just "ICAP", as appropriate. Example 1, IMAP/ICAP server: C: a001 CAPABILITY S: * CAPABILITY IMAP4 ICAP S: a001 OK CAPABILITY completed Example 2, ICAP only server: C: a001 CAPABILITY S: * CAPABILITY ICAP S: a001 OK CAPABILITY completed NOOP Command Arguments: None An ICAP/IMAP server must support the NOOP command as described in [1]. An ICAP server must support this command. In both cases, ------------------------------------------------------------------------------- Page: 3 ------------------------------------------------------------------------------- ICAP responses can be returned along with IMAP specific responses. LOGOUT Command Arguments: None An ICAP/IMAP server must support the LOGOUT command as described in [1]. An ICAP server must support this command, closing all open selected Calendars and disconnecting. CALSETTINGS Command Arguments: Optional keyword "QUERY" Allows the client to set session-level options that apply to all subsequent Calendar operations. Options are given in the form: option_name ":" option_setting [CRLF] After all options have been given, a single period "." followed by a CRLF is given, signifying the end of the options list. After this completion line has been given, the server must send untagged status responses back to the client corresponding to the options given. These responses can specify whether or not the given option was set correctly. The status responses must contain the response code CALSETTINGS. OK responses should also include the option name and option setting. NO responses must contain the option name not set. Mandatory options and their defaults are as follows. Implementation specific extensions to these options may be added. Any option extension which is not part of this standard or is not intended to be part of this standard must be prefixed with an "X". The current options correspond to vCalendar properties, see [2]: LANGUAGE "en-US" (US English) CHARSET "ASCII" ENCODING "7BIT" TZ "00" (GMT) In this example, the client attempts to set 3 options the standard "ENCODING" and "TZ" the implementation specific option "XFOO". The server accepts the first two options and rejects the last: C: A001 CALSETTINGS C: ENCODING: BASE64 C: TZ: -06 ------------------------------------------------------------------------------- Page: 4 ------------------------------------------------------------------------------- C: XFOO: BAR C: . S: * OK [CALSETTING ENCODING BASE64] S: * OK [CALSETTING TZ -06] S: * NO [CALSETTING XFOO] S: A001 OK CALSETTINGS The keyword "QUERY" can be given on the same line as the CALSETTINGS command to query all existing settings. In this case, no additional lines must be sent by the client. The server replies with an untagged response for each setting. Example: C: A001 CALSETTINGS QUERY S: * OK [CALSETTING ENCODING 7BIT] S: * OK [CALSETTING TZ -09] S: * OK [CALSETTING CHARSET ASCII] S: * OK [CALSETTING LANGUAGE en-US] S: A001 OK CALSETTINGS ICAP Commands - Non-Authenticated State AUTHENTICATE Command Arguments: Authentication mechanism name. Both ICAP/IMAP and ICAP servers must support the AUTHENTICATE command as described in [1]. LOGIN Command Arguments: User name and password. Both ICAP/IMAP and ICAP servers must support the AUTHENTICATE command as described in [1]. ICAP Commands - Authenticated State CALSELECT Command Arguments: Name of the Calendar store to select. Data: Mandatory untagged response: CALFLAGS, CALEXISTS Optional untagged response: CALRECENT ------------------------------------------------------------------------------- Page: 5 ------------------------------------------------------------------------------- Result: OK - now in CalendarSelected state NO - no such Calendar store, can't access Calendar store The CALSELECT command selects the Calendar store for the current user so that Calendar entries can be queried and retrieved. CALSELECT is different in one major respect from the SELECT command in IMAP [1] in that multiple Calendar stores can be selected by reissuing the CALSELECT command. In this way, a composite view of the Calendar stores can be created. This composite calendar can then be used to allow browsing of group calendars and creating of group meetings (see below). The name parameter can be the name of a Calendar and optionally a user name. If a user name is given, then it is bracketed with angle braces "<" and ">" and added before the Calendar store name. The default Calendar store of a user can be selected by using only the user's name bracketed by angles. The default calendar store of the current user can be selected by using angles"<>". All commands which take a Calendar store name as a parameter can accept a user name in this manner. Which Calendar store is selected as a default is implementation dependent. It is recommended that the default store be whichever Calendar store most accurately represents the user's actual schedule, so that it can be queried to find freetime (see the CALFREE command below). The user name is specified as <"username"@"hostname">. If "hostname" is the name of the current host machine, then "hostname" may be omitted and the form is: <"username">. If "hostname" is included, and it is different from the current host machine name, the server can either reject the name with a NO response or attempt to connect to the specified host machine on behalf of the user and issue an OK response if successful. If a NO response is given by the server because the given user's calendar information is not located on the host but the server knows where, a reference name in angle brackets may be included as part of the response. The CALEXISTS response should return the number of entries currently selected. The CALRECENT response should be given if new Calendar entries have appear in the selected Calendar since it was last selected. This may occur when someone else's Calendar store is selected or possibly when someone else - an assistant perhaps - modifies the user's Calendar The CALFLAGS response should list the flags supported by this ------------------------------------------------------------------------------- Page: 6 ------------------------------------------------------------------------------- Calendar store. Note that when multiple Calendar stores are selected, the CALFLAGS supported should be the intersection of those supported by all the Calendars. Flags current supported are: \Deleted - Entry is marked for deletion. \Recent - Entry has been added since the last time that this Calendar store was selected. \Repeating - Entry is one of a repeating set of entries. Example interactions: C: A001 CALSELECT S: * 123 CALEXISTS S: * CALFLAGS (\Deleted \Recent \Repeating) S: A001 OK CALSELECT Completed C: A002 CALRANGE 19960101T000000 19960130T235959 This sequence selects the current user's default Calendar store. It then sends a CalendarSelected state command called CALRANGE (see below). C: A001 CALSELECT <>Section1 S: * 45 CALEXISTS S: * CALFLAGS (\Deleted \Recent \Repeating) S: A001 OK CALSELECT completed C: A002 CALRANGE 19960101T000000 19960130T235959 This sequence selects the current user's Calendar store called "Section1". It then sends a CalendarSelected state command called CALRANGE. C: A001 CALSELECT <> S: * 23 CALEXISTS S: * CALFLAGS (\Deleted \Recent \Repeating) S: A001 OK CALSELECT completed C: A002 CALSELECT S: * 56 CALEXISTS S: * CALFLAGS (\Deleted \Recent \Repeating) S: A002 OK CALSELECT completed C: A003 CALSELECT S: * 123 CALEXISTS S: * CALFLAGS (\Deleted \Recent \Repeating) S: A003 OK CALSELECT completed This sequence uses multiple CALSELECT commands to open the current user's default Calendar store plus the default Calendar stores ------------------------------------------------------------------------------- Page: 7 ------------------------------------------------------------------------------- of Bob and Sally. Note that the CALEXISTS response from the command contains the number of Calendar entries in all of the Calendars currently selected. C: A001 CALSELECT S: A001 NO CALSELECT No such user. C: A001 CALSELECT S: A001 NO CALSELECT Try These sequences demonstrate how a server might handle a CALSELECT command where the given user's Calendar store is not on the current host. In the second example, the server knows the location of the user's Calendar host and supplies that information to the client. CALEXAMINE Command This command is identical to CALSELECT except that the selected Calendar store is returned read only. CALCREATE Command Arguments: Name of Calendar store to create. Result: OK - Calendar store created. NO - Calendar store not created. BAD - Invalid arguments. Creates a new Calendar store with the given name. Calendar store names must begin with an alphabetic character and consist of alphanumeric characters. Calendar names are not case sensitive. It is illegal to create more than one Calendar store with the same name. CALDELETE Command Arguments: Name of Calendar store to delete. Result: OK - Calendar store deleted. NO - Calendar store not deleted. BAD - Invalid arguments. Deletes the Calendar store with the given name. CALRENAME Command Arguments: Name of Calendar store to rename. New Calendar store name. ------------------------------------------------------------------------------- Page: 8 ------------------------------------------------------------------------------- Result: OK - Calendar store renamed NO - Calendar store not renamed. BAD - Invalid arguments Renames the specified Calendar store. CALLIST Command Arguments: Calendar name pattern, possibly with "*" as a wildcard character. Data: Untagged responses: CALLIST Result: OK - List complete. NO - List failed, no Calendars found that match the given pattern. BAD - What did that pattern mean anyway? The CALLIST command returns a list of all Calendars that the current user has access to. "*" is the only wildcard character supported and can be used more than once in the same pattern. The Calendar name parameter can be prefixed with a user name in angle brackets, as described in the CALSELECT command. Examples of CALLIST patterns and their meaning: "*" All of the current user's Calendar stores and any publicly available Calendar stores. "<*>" The name of all users that can be accessed by this server. Example: C: A001 CALLIST <*> S: * CALLIST S: * CALLIST S: * CALLIST S: A001 OK CALLIST Completed. C: A001 CALLIST * S: * CALLIST Business S: * CALLIST Private S: * CALLIST CorporateEvents S: A001 OK CALLIST Completed. ICAP Commands - CalendarSelected State ------------------------------------------------------------------------------- Page: 9 ------------------------------------------------------------------------------- CALSELECT Command As described above, the CALSELECT command can be given from the CalendarSelected state as well as the AUTHENTICATED state. CALCLOSE Command Arguments: Optional name of user and or Calendar store. Result: OK BAD - Calendar name or user is not selected. The CALCLOSE closes the currently selected Calendar store or one of the Calendar stores currently selected. When no parameter is supplied, all currently selected Calendars are closed. When a parameter is supplied, it should be of the same form for Calendar names given in the CALSELECT command. If the user has not previously issued a CALSELECT command with the exact name given in the CALCLOSE command, a BAD response is returned. CALRANGE Command Arguments: Start date/time in ISO8601 format End date/time in ISO8601 format. Mandatory untagged response: CALEXISTS Result: OK - Command completed successfully, date range has been set NO - An error occurred while setting the date range BAD - Bad date format The CALRANGE command sets a date/time range for the currently selected Calendars and returns a CALEXISTS response with the number of items in the range. All subsequent calls that require an item number will be bound by the given date range. CHECK Command Arguments: None An IMAP server which implements ICAP should perform housekeeping operations on the currently selected Calendar store in addition the current mail store. As with IMAP [1], the server is not required to return any untagged response with this command. CALEXPUNGE Command ------------------------------------------------------------------------------- Page: 10 ------------------------------------------------------------------------------- Arguments: None Mandatory untagged response: CALEXPUNGE Like the IMAP EXPUNGE command [1], CALEXPUNGE permanently removes all Calendar items marked with the \Deleted flag. An untagged CALEXPUNGE response is returned for each item removed. CALFETCH Command Arguments: Set of calendar entries to fetch. Item names. Data: Untagged responses: CALFETCH Result: OK - fetch completed NO - fetch error BAD - command unknown or invalid arguments Fetches for all the specified calendar entries the data specified using the following item names: CALFLAGS The flags associated with this calendar entry VCAL vCalendar Simplegram format. VCAL.SIZE The size of the vCalendar Simplegram, in octets. VCAL.REQUIRED Only required vCalendar field information in Simplegram format. VCAL.BRIEF Only DTSTART and DTEND fields in Simplegram format. Note that items returned by CALFETCH should always be returned in ascending chronological order, even when multiple Calendar stores are selected. Example: C: A001 CALFETCH 1 CALFLAGS S: * 1 CALFETCH CALFLAGS (\Deleted \Seen) S: A001 OK CALFETCH C: A001 CALFETCH 1 (CALFLAGS VCAL.REQUIRED) S: * 1 CALFETCH (CALFLAGS (\Deleted \Seen) VCAL.REQUIRED {96} S: BEGIN: vCalendar S: BEGIN: vEvent ------------------------------------------------------------------------------- Page: 11 ------------------------------------------------------------------------------- S: DTBEGIN: 19960701T0300Z S: DTEND: 19960701T0400Z S: DESCRIPTION: Test meeting S: END: vEvent S: END: vCalendar S: ) S: A001 OK CALFETCH CALSTORE Command Arguments: Calendar entry set Calendar entry data item name Calendar entry data item value Calendar data items: +CALFLAGS Set the flag list of the given Calendar entries. -CALFLAGS Remove the flag argument from the flags of the given Calendar entries. VCAL Updates the vCalendar data associated with this Calendar entry. When this form of the CALSTORE command is used, the Calendar data item must be supplied as a literal. The data must be a vCalendar Simplegram. If a value of "0" is given for the Calendar entry set, then a new entry is created in the current CalendarSelected object. If there is more than one Calendar store selected in the given CalendarSelected object, then the CALSTORE command will add the new entry to all of the Calendar stores. The server can send an optional untagged response for each user or calendar that is currently selected. The response can be used to indicate that the store failed in a certain user's calendar with a response code of "REFUSED" followed by the name of the calendar refusing. New Calendar entries added to a Calendar store must contain all required vCalendar fields. Updates to existing Calendar entries need only contain the actual data to be updated. ------------------------------------------------------------------------------- Page: 12 ------------------------------------------------------------------------------- Examples: C: A001 CALSTORE 23 (+CALFLAGS \Repeating VCAL {102} C: BEGIN: vCalendar C: BEGIN: vEvent C: DTSTART: 19960606T140000 C: DTEND: 19960606T150000 C: DESCRIPTION: Meeting with Pete. C: END: vEvent C: END: vCalendar C: ) S: A001 OK CALSTORE completed C: A001 CALSTORE 23 VCAL {102} C: BEGIN: vCalendar C: BEGIN: vEvent C: DTSTART: 19960606T140000 C: DTEND: 19960606T150000 C: DESCRIPTION: Meeting with Pete. C: END: vEvent C: END: vCalendar S: * NO [REFUSED ] Alice doesn't like you. S: A001 OK CALSTORE completed This sequence modifies Calendar entry number 23 with a new start and end date/time. Also in this sequence, an untagged response from the server indicates that updating the Calendar entry in the user "alice" Calendar has failed. CALFREE Command Arguments: Start of search range in ISO8601 format End of search range in ISO8601 format Length of time, in minutes Mandatory untagged response: CALFETCH The CALFREE command searches the currently selected Calendar, bounded by a start and end time, and returns a list of intervals during which an event of the given length of time can be scheduled. See below under "Example Sessions" for and example of the use of the CALFREE command. The freetime data is returned in an untagged CALFETCH response as VCAL.BRIEF. CALCOPY Command ------------------------------------------------------------------------------- Page: 13 ------------------------------------------------------------------------------- CALMOVE Command Arguments: Calendar entry set Name of Calendar to move or copy to Result: OK - Calendar entries moved. NO - Calendar entries not moved. BAD - Bad date format given. CALCOPY and CALMOVE transfer a given set of entries to a different Calendar store. In the case of the CALMOVE command, the entries are removed from the current Calendar. CALMOVE must fail if the user does not have permission to remove an entry from the selected Calendar. Example: C: A001 CALCOPY 1 Section1 S: A001 OK CALCOPY Completed. Server Responses CALLIST Response S: * CALLIST Section1 S: * CALLIST S: * CALLIST CALEXISTS Response This response is similar to the EXISTS response defined in IMAP4 [1] except that it applies to the selected Calendar store. Example: S: * 23 CALEXISTS CALRECENT Response This response is similar to the RECENT response defined in IMAP4 [1] except that it applies to the selected Calendar store. Example: S: * 1 CALRECENT CALEXPUNGE Response ------------------------------------------------------------------------------- Page: 14 ------------------------------------------------------------------------------- This response is similar to the EXPUNGE response defined in IMAP4 [1] except that it applies to the selected Calendar store. Example: S: * 1 CALEXPUNGE CALFETCH Response This response is similar to the FETCH response defined in IMAP4 [1] except that it applies to the selected Calendar store. S: * 1 CALFETCH VCAL.REQUIRED {96} S: BEGIN: vCalendar S: BEGIN: vEvent S: DTBEGIN: 19960701T0300Z S: DTEND: 19960701T0400Z S: DESCRIPTION: Test meeting S: END: vEvent S: END: vCalendar S: ) CALFLAGS Response This response is similar to the FLAGS response defined in IMAP4 [1] except that it applies to the selected Calendar store. S: * 1 CALFLAGS (\Deleted) Formal Syntax This will be included in a later draft of this specification. Example Sessions Here is an example of a client using guest access to query the freetime of three individuals: S: * OK ICAP Server ready. C: A001 LOGIN guest pete@clearblue.com S: A001 OK LOGIN Anonymous access granted. C: A002 CALEXAMINE S: * 12 CALEXISTS S: A002 OK CALEXAMINE C: A003 CALEXAMINE S: * 22 CALEXISTS S: A003 OK CALEXAMINE C: A004 CALEXAMINE ------------------------------------------------------------------------------- Page: 15 ------------------------------------------------------------------------------- S: * 36 CALEXISTS S: A004 OK CALEXAMINE C: A005 CALFREE 19960701T0300Z 19960701T1200Z 60 S: * 1 CALFETCH VCAL.BRIEF {200} S: BEGIN: vCalendar S: BEGIN: vEvent S: DTBEGIN: 19960701T0300Z S: DTEND: 19960701T0400Z S: END: vEvent S: BEGIN: vEvent S: DTBEGIN: 19960701T1000Z S: DTEND: 19960701T1100Z S: END: vEvent S: END: vCalendar S: A005 OK CALFREE C: A006 LOGOUT S: * BYE ICAP Server terminating connection. S: A006 OK LOGOUT Open Issues/Work in Progress How should a user's Calendar server be located? For example, given a mail address like how should a client locate the Calendar server. Hierarchical Calendar store names are not currently specified. No subscribe/unsubscribe capabilities are currently defined, although these could be very useful. Calendar searching is not yet defined. Need some input on the best way to handle searching through vCalendar Simplegrams. Repeating events are not defined in this specification except for the \Repeating flag. Do we need special treatment of repeating events here? References [1] Crispin, M. "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4", RFC 1730, Dec 1994, http://andrew2.andrew.cmu.edu/cyrus/email/standards-IMAP.html [2] versit Consortium, "Electronic Calendaring and Scheduling (vCalendar) Specification", 03/29/1996, http://www.versit.com/ Security Considerations The user name and password arguments of the LOGIN command are ------------------------------------------------------------------------------- Page: 16 07/18/96 Expires 01/18/97 ------------------------------------------------------------------------------- sent in clear text over most transport protocols. Servers should implement access control mechanisms for the Calendar store. Author's Address The author is currently relocating to California after barely surviving the worst winter on record in Massachusetts. Contact information after August 1st: Peter O'Leary Clear Blue Network Systems, Inc. 1028 Cowper St. Palo Alto, CA 94043 (415) 323-3380 E-mail: poleary@clearblue.com ------------------------------------------------------------------------------- Page: 17