idnits 2.17.1 draft-ietf-calsch-cap-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 4357 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC2445]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 338: '...example, "events MUST be scheduled in ...' RFC 2119 keyword, line 449: '...flict, the realm SHOULD be postfixed w...' RFC 2119 keyword, line 516: '... CS1 MAY play the role of a CUA an...' RFC 2119 keyword, line 517: '... CS1 MAY be able to play the role ...' RFC 2119 keyword, line 519: '... CS1 MUST be able play the role of a CUA and use [RFC2447] to...' (31 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 2389 has weird spacing: '...encoded binar...' == Line 2587 has weird spacing: '...the informati...' == Line 2588 has weird spacing: '... be how a CU...' == Line 2589 has weird spacing: '...chooses to q...' == Line 2590 has weird spacing: '...ake any sense...' == (1 more instance...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 5, 1999) is 9028 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'RFC2445' on line 3563 looks like a reference -- Missing reference section? 'RFC2119' on line 235 looks like a reference -- Missing reference section? 'RFC2446' on line 3566 looks like a reference -- Missing reference section? 'RFC2447' on line 3569 looks like a reference -- Missing reference section? 'RFC2396' on line 3560 looks like a reference -- Missing reference section? 'TLS' on line 3558 looks like a reference -- Missing reference section? 'TBD' on line 657 looks like a reference -- Missing reference section? 'CAP' on line 2590 looks like a reference -- Missing reference section? 'SQL' on line 3572 looks like a reference -- Missing reference section? 'SASL' on line 1210 looks like a reference -- Missing reference section? 'SQLCOM' on line 3575 looks like a reference -- Missing reference section? 'RFC2426' on line 3535 looks like a reference -- Missing reference section? 'RFC1521' on line 3553 looks like a reference -- Missing reference section? 'UNICODE' on line 3578 looks like a reference -- Missing reference section? 'US-ASCII' on line 3582 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 18 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group Steve Mansour/Netscape 2 Internet Draft Frank Dawson/Lotus 3 Doug Royer/Sun Microsystems 4 Alexander Taler/CS&T 5 Paul Hill/MIT 6 Expires six months from: August 5, 1999 8 Calendar Access Protocol (CAP) 10 This memo is an Internet-Draft and is in full conformance with all 11 provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering Task 14 Force (IETF), its areas, and its working groups. Note that other groups 15 may also distribute working documents as Internet-Drafts. Internet- 16 Drafts are draft documents valid for a maximum of six months and may be 17 updated, replaced, or obsoleted by other documents at any time. It is 18 inappropriate to use Internet- Drafts as reference material or to cite 19 them other than as "work in progress." 21 The list of current Internet-Drafts can be accessed at 22 http://www.ietf.org/ietf/1id-abstracts.txt. 24 The list of Internet-Draft Shadow Directories can be accessed at 25 http://www.ietf.org/shadow.html. 27 Distribution of this document is unlimited. 29 Copyright Statement 31 Copyright (C) The Internet Society 1999. All Rights Reserved. 33 Abstract 35 The Calendar Access Protocol (CAP) is an Internet protocol that permits 36 a Calendar User (CU) to utilize a Calendar User Agent (CUA) to access an 37 [RFC2445] based Calendar Store (CS). This memo defines the CAP 38 specification.The CAP definition is based on requirements identified by 39 the Internet Engineering Task Force (IETF) Calendaring and Scheduling 40 (CALSCH) Working Group. More information about the IETF CALSCH Working 41 Group activities can be found on the IMC web site at 42 http://www.imc.org/ietf-calendar, and at the IETF web site at 43 http://www.ietf.org/html.charters/calsch-charter.html. Refer to the 44 references within this memo for further information on how to access 45 these various documents. 47 Mansour/Dawson/Royer 1 Expires February 2000 48 Taler/Hill 49 Table of Contents 51 1. Introduction........................................................6 53 1.1 Formatting Conventions ...........................................6 55 1.2 Related Documents ................................................6 57 1.3 Definitions ......................................................7 59 2. CAP Design.........................................................10 61 2.1 System Model ....................................................10 63 2.2 Calendar Store Object Model .....................................11 65 2.3 Protocol Model ..................................................12 67 2.4 Roles ...........................................................13 69 2.5 Calendar User ...................................................13 70 2.5.1 UPNs and Certificates ........................................14 71 2.5.2 CAP session identity .........................................14 73 2.6 Calendar Addresses ..............................................15 75 2.7 Finding CAP Servers .............................................15 77 2.8 Extensions to iCalendar .........................................16 79 2.9 Relationship of RFC 2446 (ITIP) to CAP ..........................16 81 2.10 VCalendar Access Rights (VCARs) ................................16 83 2.11 Query Schema ...................................................17 85 3. State Diagram......................................................17 87 4. Protocol Framework.................................................18 89 4.1 CAP Application Layer ...........................................18 91 4.2 CAP Transport Layer .............................................18 93 4.3 Response Format .................................................18 95 4.4 Auto-logout Timer ...............................................19 97 4.5 Bounded Latency .................................................19 99 Mansour/Dawson/Royer 2 Expires February 2000 100 Taler/Hill 101 4.6 Data Elements ...................................................19 103 5. Formal Command Syntax..............................................20 105 5.1 Searching and Filtering .........................................20 106 5.1.1 Grammar For Search Mechanism .................................20 108 6. Access Rights......................................................21 110 6.1 VCAR Inheritance ................................................21 112 7. Commands and Responses.............................................21 114 7.1 Transport Protocol Commands .....................................22 115 7.1.1 Initial Connection ...........................................22 116 7.1.2 ABORT Command ................................................22 117 7.1.3 AUTHENTICATE Command .........................................23 118 7.1.4 CONTINUE Command .............................................26 119 7.1.5 DISCONNECT Command ...........................................27 120 7.1.6 IDENTIFY Command .............................................27 121 7.1.7 SENDDATA Command .............................................27 122 7.1.8 STARTTLS Command .............................................27 124 7.2 Application Protocol Commands ...................................28 125 7.2.1 Calendaring Commands .........................................28 126 7.2.1.1 CREATE Method ............................................28 127 7.2.1.1.1 Creating New Calendars ................................29 128 7.2.1.2 DELETE Method ............................................30 129 7.2.1.3 GENERATEUID Method .......................................31 130 7.2.1.4 MODIFY Method ............................................31 131 7.2.1.5 MOVE Method ..............................................32 132 7.2.1.6 READ Method ..............................................32 133 7.2.2 Scheduling Commands ..........................................36 134 7.2.2.1 PUBLISH ..................................................36 135 7.2.2.2 REQUEST ..................................................36 136 7.2.2.3 REPLY ....................................................36 137 7.2.2.4 ADD ......................................................36 138 7.2.2.5 CANCEL ...................................................36 139 7.2.2.6 REFRESH ..................................................36 140 7.2.2.7 COUNTER ..................................................36 141 7.2.2.8 DECLINECOUNTER ...........................................36 142 7.2.3 iTIP Examples ................................................36 143 7.2.3.1 Sending and Receiving an iTIP request ....................36 144 7.2.3.2 Handling an iTIP refresh .................................39 145 7.2.3.3 Sending and accepting an iTIP counter ....................40 146 7.2.3.4 Declining an iTIP counter ................................41 148 8. Response Codes.....................................................42 150 9. Detailed SQL Schema................................................44 152 Mansour/Dawson/Royer 3 Expires February 2000 153 Taler/Hill 154 9.1 iCalendar Store Schema ..........................................45 156 10. Examples..........................................................50 158 10.1 Authentication Examples ........................................50 159 10.1.1 Login Using Kerberos V4 .....................................50 160 10.1.2 Error Scenarios .............................................50 162 10.2 Read Examples ..................................................51 163 10.2.1 Read From A Single Calendar .................................51 164 10.2.2 Read From Multiple Calendars ................................52 165 10.2.3 Timeouts ....................................................53 166 10.2.4 Using the Calendar Parent, Children Properties ..............54 167 10.2.5 An example that depends on VEVENT.DTSTART and VALARM.DTSTART 54 169 11. Implementation Issues.............................................54 171 12. Properties........................................................54 173 12.1 Calendar Store Properties ......................................54 175 12.2 Calendar Properties ............................................54 177 13. Security Considerations...........................................55 179 14. Changes to iCalendar..............................................56 181 14.1 RIGHTS Value Type ..............................................56 183 14.2 VCAR Calendar Component ........................................59 185 14.3 GRANT Component Property .......................................60 187 14.4 DENY Component Property ........................................61 189 14.5 VCAR Identifier Component Property .............................61 191 14.6 REQUEST-STATUS property ........................................62 193 15. CAP Entities Registration.........................................63 195 15.1 Registration of New and Modified CAP Entities ..................63 197 15.2 Registration of New Entities ...................................63 198 15.2.1 Define the Entity ...........................................63 199 15.2.2 Post the entity definition ..................................64 200 15.2.3 Allow a comment period ......................................64 201 15.2.4 Submit the entity for approval ..............................64 203 Mansour/Dawson/Royer 4 Expires February 2000 204 Taler/Hill 205 15.3 Property Change Control ........................................65 207 16. IANA Considerations...............................................65 209 17. Acknowledgments...................................................65 211 18. Bibliography......................................................66 213 19. Author's Address..................................................66 215 20. Full Copyright Statement..........................................67 217 Mansour/Dawson/Royer 5 Expires February 2000 218 Taler/Hill 219 1. Introduction 220 This document specifies how a Calendar User Agent (CUA) interacts with a 221 Calendar Store (CS) to manage calendar information. In particular, it 222 specifies how to query, create, modify, and delete iCalendar components 223 (e.g., events, to-dos, or daily journal entries). It further specifies 224 how to search for available busy time information. 226 This protocol is based on request/response form of protocol data units, 227 sent from a client CUA to a calendar server. The protocol data units 228 leverage the standard iCalendar format [RFC2445] for conveying CS 229 related information. 231 1.1 Formatting Conventions 232 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 233 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this 234 document are to be interpreted as described in [RFC2119]. 236 Calendaring and scheduling roles are referred to in quoted-strings of 237 text with the first character of each word in upper case. For example, 238 "Organizer" refers to a role of a "Calendar User" (CU) within the 239 protocol defined by this memo. Calendar components defined by [RFC2445] 240 are referred to with capitalized, quoted-strings of text. All calendar 241 components start with the letter "V". For example, "VEVENT" refers to 242 the event calendar component, "VTODO" refers to the to-do calendar 243 component and "VJOURNAL" refers to the daily journal calendar component. 244 Calendar access methods defined by this memo, as well as scheduling 245 methods defined by [RFC2446], are referred to with capitalized, quoted- 246 strings of text. For example, "CREATE" refers to the method for creating 247 a calendar component on a calendar, "READ" refers to the method for 248 reading calendar components. 250 Properties defined by this memo are referred to with capitalized, 251 quoted-strings of text, followed by the word "property". For example, 252 "ATTENDEE" property refers to the iCalendar property used to convey the 253 calendar address of a "Calendar User". Property parameters defined by 254 this memo are referred to with lower case, quoted-strings of text, 255 followed by the word "parameter". For example, "value" parameter refers 256 to the iCalendar property parameter used to override the default data 257 type for a property value. Enumerated values defined by this memo are 258 referred to with capitalized text, either alone or followed by the word 259 "value". 261 In tables, the quoted-string text is specified without quotes in order 262 to minimize the table length. 264 1.2 Related Documents 265 Implementers will need to be familiar with several other memos that, 266 along with this one, describe the Internet calendaring and scheduling 267 standards. This document, 269 Mansour/Dawson/Royer 6 Expires February 2000 270 Taler/Hill 271 [RFC2445] specifies the objects, data types, properties and property 272 parameters used in the protocols, along with the methods for 273 representing and encoding them; 275 [RFC2446] specifies an interoperability protocol for scheduling between 276 different implementations. The related documents are: 278 [RFC2447] specifies an Internet email binding for [RFC2446]. 280 [iRIP] specifies a real-time binding for [to be published]. 282 This memo does not attempt to repeat the specification of concepts or 283 definitions from these other memos. Where possible, references are made 284 to the memo that provides for the specification of these concepts or 285 definitions. 287 1.3 Definitions 288 Authentication ID (AuthID) 289 A tuple of username, realm, and authentication method, used by the 290 Calendar Service internally to identify a successfully 291 authenticated CAP session. 293 Calendar 294 A collection of logically related objects or entities each of which 295 may be associated with a calendar date and possibly time of day. 296 These entities can include other calendar properties or calendar 297 components. In addition, a calendar might be hierarchically related 298 to other sub-calendars. A calendar is identified by its unique 299 calendar identifier. The [RFC2445] defines calendar properties, 300 calendar components and component properties that make up the 301 content of a calendar. 303 Calendar Access Protocol (CAP) 304 The standard Internet protocol that permits a Calendar User Agent 305 to access and manipulate a calendar residing on a Calendar Store. 307 Calendar Access Rights (CAR) 308 The mechanism for specifying the CAP operations ("ACTIONS") that a 309 particular calendar user ("UPN") are granted or denied permission 310 to perform on a given calendar entity ("OBJECT"). The calendar 311 access rights are specified with the "VCAR" calendar components 312 within a CS and calendar. 314 Calendar Component 315 An entity within a calendar. Some types of calendar components 316 include events, to-dos, journals, alarms, time zones and freebusy 317 data. A calendar component consists of component properties and 318 possibly other sub-components. For example, an event may contain an 319 alarm component. 321 Calendar Component Properties 322 An attribute of a particular calendar component. Some calendar 323 component properties are applicable to different types of calendar 324 components. For example, DTSTART is applicable to VEVENT, VTODO, 326 Mansour/Dawson/Royer 7 Expires February 2000 327 Taler/Hill 328 VJOURNAL calendar components. Other calendar components are 329 applicable only to an individual type of calendar component. For 330 example, TZURL is only applicable to VTIMEZONE calendar components. 332 Calendar Identifier (CalID) 333 A globally unique identifier associated with a calendar. Calendars 334 reside within a CS. See Qualified Calendar Identifier and Relative 335 Calendar Identifier. 336 Calendar Policy 337 A CAP operational restriction on the access or manipulation of a 338 calendar. For example, "events MUST be scheduled in unit intervals 339 of one hour". 340 Calendar Properties 341 An attribute of a calendar. The attribute applies to the calendar, 342 as a whole. For example, CALSCALE specifies the calendar scale 343 (e.g., GREGORIAN) for the whole calendar. 345 Calendar Service 346 An implementation of a Calendar Store that manages one or more 347 calendars. 349 Calendar Store (CS) 350 The data and service model definition for a Calendar Service. 352 Calendar Store Identifier (CSID) 353 The globally unique identifier for an individual CS. A CSID 354 consists of the host and port portions of a "Common Internet Scheme 355 Syntax" part of a URL, as defined by [RFC2396]. 357 Calendar Store Components 358 Components maintained in a CS specify a grouping of calendar store- 359 wide information. Calendar store components can be accessed using 360 CAP. 362 Calendar Store Properties 363 Properties maintained in a Calendar Store calendar store-wide 364 information. Calendar store properties can be accessed using CAP. 366 Calendar User (CU) 367 An entity (often biological) that uses a calendaring system. 369 Calendar User Agent (CUA) 370 The CUA is the client application that a CU utilizes to access and 371 manipulate a calendar. 373 Calendaring and Scheduling System 374 The computer sub-system that provides the services for accessing, 375 manipulating calendars and scheduling calendar components. 377 CAP Session 378 An open communication channel between a CAP CUA and a CAP CS. 380 Connected Mode 382 Mansour/Dawson/Royer 8 Expires February 2000 383 Taler/Hill 384 A mobile computing mode where the CUA is directly connected to the 385 CS. 387 Delegate 388 Is a calendar user (sometimes called the delegatee) who has been 389 assigned participation in a scheduled calendar component (e.g., 390 VEVENT) by one of the attendees in the scheduled calendar 391 component (sometimes called the delegator). An example of a 392 delegate is a team member told to go to a particular meeting. 394 Designate 395 Is a calendar user who is authorized to act on behalf of another 396 calendar user. An example of a designate is an assistant. 398 Disconnected Mode 399 A mobile computing mode where a CUA can be disconnected from a CS. 400 When the CUA is disconnected, it is in the disconnected mode. 402 Fan Out 403 The calendaring and scheduling process by which a calendar 404 operation on one calendar is also performed on every other calendar 405 specified in the operation. This may include the calendar 406 associated with TARGET calendar property. 408 Hierarchical Calendars 409 A CS feature where a calendar have a hierarchical relationship with 410 another calendar in the CS. The top-most calendar in the 411 hierarchical relationship has the CS as its parent. There may be 412 multiple top-most calendars in a given CS. Within a given 413 hierarchical relationship, all sub-calendars have a calendar with a 414 "parent" topographical relationship. In addition, sub-calendars may 415 have a relationship with another calendar that has a "child" 416 topographical relationship. In addition, a calendar may have a 417 relationship such that one or more calendars have a "sibling" 418 topographical relationship with the calendar. The hierarchical 419 calendar feature is not a storage relationship of the calendars 420 within the CS. Instead it is a feature that relates access control 421 rights to calendar content between different calendars in the CS. 422 The hierarchical relationship of a calendar is specified in the 423 "PARENT" and "CHILDREN" calendar properties. 425 High Bandwidth Connection 426 A communications connection supporting high transfer rates; 427 transfer rates commonly found within a LAN. 429 Local Store 430 A CS which is on the same platform as the CUA. 432 Low Bandwidth Connection 433 A communications connection supporting slow transfer rates; 434 transfer rates commonly found in remote access technology. 436 Owner 438 Mansour/Dawson/Royer 9 Expires February 2000 439 Taler/Hill 440 A CU or CUs that have "OWNER" calendar access rights for a 441 calendar. The owner is specified in the "OWNER" calendar property. 443 Qualified Calendar Identifier (Qualified CalID) 444 A CalID where both the and are present. 446 Realm 447 A collection of calendar user accounts, identified by a string. The 448 name of the realm is only used in UPNs. In order to avoid namespace 449 conflict, the realm SHOULD be postfixed with an appropriate DNS 450 domain name. (eg: the foobar realm could be called 451 foobar.example.com). 453 Relative Calendar Identifier (Relative CalID) 454 An identifier for an individual calendar in a calendar store. It is 455 unique within a calendar store. It is recommended to be globally 456 unique. A Relative CalID consists of the portion of the "scheme 457 part" of a Qualified CalID following the Calendar Store Identifier. 458 This is the same as the "URL path" of the "Common Internet Scheme 459 Syntax" portion of a URL, as defined by [RFC2396]. 461 Remote Store 462 A CS which is not on the same platform as the CUA. 464 Session Identity 465 A UPN associated with a CAP session. A session gains an identity 466 after successful authentication. The identity is used in 467 combination with CAR to determine access to data in the CS. 469 Sub-calendars 470 Calendars that have a "child" hierarchical relationship with 471 another calendar, its "parent". 473 User Name 474 A name which denotes a Calendar User within a realm. This is part 475 of a UPN. 477 User Principal Name (UPN) 478 An identifier that denotes a unique CU. A UPN strongly resembles an 479 RFC 822 style email address and in some cases it may be identical 480 to the email address for the CU. It consists of a realm in the form 481 of a DNS domain name and a username. It may also have an optional 482 instance. In it's simplest form it looks like "user@example.com". 484 2. CAP Design 486 2.1 System Model 488 The system model describes the high level components of a calendar 489 system and how they interact with each other. 491 CAP is used by a "Calendar User Agent" (CUA) to send commands to and 492 receive responses from a "Calendar Service" (CS). The CUA prepares an 494 Mansour/Dawson/Royer 10 Expires February 2000 495 Taler/Hill 496 MIME encapsulated iCalendar object containing a command, sends it to the 497 CS, and receives an iCalendar object as a response. There are two 498 distinct protocols in operation to accomplish this exchange. The 499 Transport Protocol is used to move iCalendar objects between a CUA and a 500 CS. The Application Protocol defines the content and semantics of the 501 iCalendar objects sent between the CUA and the CS. This document defines 502 both the Transport Protocol and the Application Protocol. 504 In the diagram below, a user uses CUA1 to communicate with CS1 using 505 CAP. The CUA must authenticate the Calendar User (CU) so that access to 506 calendars on CS1 can be controlled. The CUA can then view, create, edit, 507 and delete calendars, calendar properties, and calendar components 508 subject to the access rights. 510 CAP servers support fanout. Fanout allows a CUA to communicate with a 511 single CS to perform scheduling operations with calendars on multiple 512 CSs. That is, a Calendar User (CU) can book events on or read events 513 from calendars on other calendar stores. To accomplish this, a CAP 514 server has several options: 516 CS1 MAY play the role of a CUA and use CAP to access CS2; 517 CS1 MAY be able to play the role of a CUA and use [iRIP] to 518 interoperate with the possible iRIP support in CS2; 519 CS1 MUST be able play the role of a CUA and use [RFC2447] to 520 interoperate with other CUAs. 521 Storage Agent 523 +-----+ +-----+ 524 | | CAP | | CAP 525 CUA1 ------| CS1 |-----------| CS2 |--------- CUA2 526 | | | | A 527 | | | | | 528 | | | | | 529 +-----+ +-----+ | 530 | IMIP | 531 +---------------------------------+ 533 Note that the fanout feature in CAP is a convenience to the CUA. It is 534 perfectly valid for the CUA to assume the responsibility for fanout if 535 it wishes. That is, [RFC2447] messages could also be sent from CUA1 to 536 CUA2. 538 2.2 Calendar Store Object Model 539 The conceptual model for a calendar store is shown below. The calendar 540 store contains calendars, VTIMEZONEs, VCARs, and calendar store 541 properties. 543 Calendars contain VEVENTs, VTODOs, VJOURNALs, VALARMs, VCARs, and 544 calendar properties. Calendars may also contain other calendars. 546 +---------Calendar Store-----------------------------+ 547 | | 548 | | 550 Mansour/Dawson/Royer 11 Expires February 2000 551 Taler/Hill 552 | VCARs | 553 | +--calendars-------------------------+ | 554 | Properties | | | 555 | | +--calendars--------+ VEVENTs | | 556 | VTIMEZONEs | | | VTODOs | | 557 | | | VEVENTs | VJOURNALs | | 558 | | | VCARs | VALARMs | | 559 | | | +---+ VTODOs | VCARs | | 560 | | | | | VALARMs | Calendar | | 561 | | | +---+ VJOURNALs | Properties | | 562 | | | VTIMEZONEs | VTIMEZONEs | | 563 | | | Calendar | VSCHEDULE | | 564 | | | Properties | | | 565 | | | VSCHEDULE | | | 566 | | +-------------------+ | | 567 | +------------------------------------+ | 568 +----------------------------------------------------+ 570 Calendars within a Calendar Store are identified by their Relative 571 CALID. 573 In this model, VSCHEDULE is a queue of scheduling messages that have not 574 yet been applied to the calendar. Items in VSCHEDULE are discussed in 575 more detail below. 577 2.3 Protocol Model 578 A generic transport, Calendar Server Transport Protocol (CSTP), is used 579 to move data objects between a CUA and the CS. CSTP commands are listed 580 below and their usage and semantics are defined in section 7 of this 581 document. 583 CSTP Commands 584 ----------------------------------------------------------------------- 585 Command Description 586 ------------ -------------------------------------------------------- 587 ABORT Stop a command whose latency time has been exceeded. 588 AUTHENTICATE Authenticate a UPN. 589 CONTINUE Continue the execution of a command whose latency 590 time has been exceeded. 591 IDENTIFY Set a new identity for calendar access. 592 DISCONNECT Terminate a connection with the server. 593 SENDDATA Send a data object MIME encapsulated iCalendar. 594 STARTTLS Negotiate transport level security using [TLS] 596 Application-level commands are used to manipulate data on the calendar 597 store. They are listed below and discussed in detail in section 7. 599 CAP Calendaring Commands 600 ----------------------------------------------------------------------- 601 Command Description 602 ------------ -------------------------------------------------------- 603 CREATE Create a new calendar or component 605 Mansour/Dawson/Royer 12 Expires February 2000 606 Taler/Hill 607 DELETE Delete a calendar or component 608 GENERATEUID Generate one or more unique ids 609 MODIFY Change a calendar or component 610 MOVE Move a calendar 611 READ Read a calendar properties or components 613 CAP Scheduling Commands 614 ----------------------------------------------------------------------- 615 Command Description 616 ------------ -------------------------------------------------------- 617 PUBLISH publish a calendar entry to one or more calendars 618 REQUEST schedule a calendar entry with one or more calendars 619 REPLY response to a scheduling request 620 ADD add one or more instances to an existing calendar entry 621 CANCEL cancel one or more instances to an existing calendar 622 entry 623 REFRESH a request for the latest version of a calendar entry 624 COUNTER a request for a change (a counter-proposal) to a 625 calendar entry 626 DECLINECOUNTER decline a counter proposal 628 2.4 Roles 629 CAP defines methods for managing [RFC2445] objects on a Calendar Store 630 and exchanging [RFC2445] objects for the purposes of group calendaring 631 and scheduling between "Calendar Users" (CUs). There are two distinct 632 roles taken on by CUs in CAP. The CU who creates an initial event or to- 633 do and invites other CUs as attendees takes on the role of "Organizer". 634 The CUs asked to participate in the group event or to-do take on the 635 role of "Attendee". Note that "role" is also a descriptive parameter to 636 the "ATTENDEE" property. Its use is to convey descriptive context to an 637 "Attendee" such as "chair", "REQ-PARTICIPANT" or NON-PARTICIPANT" and 638 has nothing to do with the scheduling workflow. 640 2.5 Calendar User 641 A Calendar User (CU) is an entity that can be authenticated. It is 642 represented in CAP as a UPN. A UPN is the owner of a calendar and the 643 subject of access rights. 645 Examples: 646 user@example.com 647 user/cap@example.com 649 The UPN representation is independent of the authentication mechanism 650 used during a particular CUA / CS interaction. A CU may use one 651 mechanism while using one CUA but the same user may use a different 652 authentication mechanism when using a different CUA, or while connecting 653 from a different location. 655 For Calendaring and Scheduling systems that are integrated with a 656 directory system the UPN SHOULD be stored in the attribute [TBD] with 657 OID [TBD]. This enables a clear mapping between a UPN and a 658 Distinguished Name. [note: Microsoft's Active Directory is storing UPNs 660 Mansour/Dawson/Royer 13 Expires February 2000 661 Taler/Hill 662 as the userPrincipalName.] Within a directory service a UPN is a single 663 valued property. 665 2.5.1 UPNs and Certificates 667 When using certificates for purposes of CAP authentication, the 668 SubjectName field of the user's certificate SHOULD contain the user's 669 UPN (for example, "juser@example.com") as the value of the "CN=" 670 component, and the user's email address (often the same as the UPN) as 671 the value of the "E=" component . The altSubjectName will contain the DN 672 of the user's account object in the DS. The Issuer field must be that of 673 a root CA trusted to issue login certificates, or the DN of a lower 674 level CA whose certificate includes an "AuthorizedNamingContext" field 675 that authorizes it to issue certificates for "example.com" (exact field 676 name and validation mechanism TBD). 678 Note: If a server is validating data received via iMIP, if the 679 "ORGANIZER" or "ATTENDEE" property said (e.g.) "ATTENDEE;CN=Joe Random 680 User:juser@example.com" then the "juser@example.com" part should be 681 checked against the altSubjectName field of the certificate, and the 682 "Joe Random User" part should be checked against the CN component of the 683 altSubjectName DN. This is so the "ATTENDEE" property couldn't be munged 684 to something misleading like "ATTENDEE;CN=Joe Rictus 685 User:juser@example.com" and have it pass validation. This validation 686 will also defeat other attempts at confusion. 688 2.5.2 CAP session identity 690 A CAP session has an assocatied set of authentication credentials, from 691 which is derived a UPN. This UPN is the identity of the CAP session, and 692 is used to determine access rights for the session. 694 The CUA may change the identity of a CAP session by calling the 695 "IDENTIFY" command. The Calendar Service only permits the operation if 696 the session's authentication credentials are good for the requested 697 identity. The method of checking this permission is implementation 698 dependant, but may be thought of as a mapping from authentication 699 credentials to UPNs. The "IDENTIFY" command allows a single set of 700 authentication credentials to choose from multiple identities, and 701 allows multiple sets of authentication credentials to assume the same 702 identity. 704 For anonymous access the identity of the session is "@", a UPN with a 705 null username and null realm. A UPN with a null username, but non-null 706 realm, such as "@foo.com" may be used to mean any identity from that 707 realm, which is useful to grant access rights to all users in a given 708 realm. A UPN with a non-null username and null realm, such as "bob@" 709 could be a security risk and must not be used. 711 Since the UPN includes realm information it may be used to govern 712 calendar store access rights across realms. However, governing access 713 rights across realms is only useful if login access is available. This 715 Mansour/Dawson/Royer 14 Expires February 2000 716 Taler/Hill 717 could be done through a trusted server relationship or a temporary 718 account. 720 The "IDENTIFY" command provides for a weak group implementation. By 721 allowing multiple sets of authentication credentials belonging to 722 different users to identify as the same UPN, that UPN essentially 723 identifies a group of people, and may be used for group calendar 724 ownership, or the granting of access rights to a group. 726 2.6 Calendar Addresses 728 Calendar addresses are URIs that are modeled after [RFC2396]. CAP uses 729 the following forms of URI. 731 [[]://[:]/] 733 where: 735 is "cap" 736 is the Calendar Store ID. It is the network address of the 737 computer on which the CAP server is running 738 is optional. Its default value is 5229. The port must be 739 present if the CAP server does not listen on the default port. 740 is an identifier that uniquely identifies the 741 calendar on a particular calendar store. There is no implied 742 structure in a Relative CALID. It is an arbitrary string of 7 bit 743 ASCII characters. It may refer to the calendar of a user or of a 744 resource such as a conference room. It MUST be unique within the 745 calendar store. It is recommended that the Relative CALID be 746 globally unique. 748 If the and are present the calendar address is said to 749 be "qualified". Senders are required to supply the 750 portion of the address. A qualified calendar address is required when 751 the of the target calendar address differs from that of the CAP 752 server receiving the command. 754 Examples: 756 cap://calendar.example.com/user1 757 ://calendar.example.com/user1 758 user1 759 cap://calendar.example.com/conferenceRoomA 760 cap://calendar.example.com/89798-098-zytytasd 762 For a user currently authenticated to a CAP server on 763 calendar.example.com, the first three addresses refer to the same 764 calendar. 766 2.7 Finding CAP Servers 767 Using DNS 768 Using SLP 769 Request-Status _ optional text (second field) 771 Mansour/Dawson/Royer 15 Expires February 2000 772 Taler/Hill 773 2.8 Extensions to iCalendar 774 In mapping the CAP command set, query feature, and access rights onto 775 the iCalendar format, several extended iCalendar methods and components 776 are defined by this memo. 778 The search function is specified with the new iCalendar QUERY 779 method. The QUERY method makes use of a new component, called 780 VQUERY, that contains the search filter. The component consists of 781 a set of new properties: SCOPE, MAXRESULTS, MAXRESULTSSIZE, QUERY 782 and QUERYNAME, that define the search filter. 783 Access control is specified the the new iCalendar VCAR component. 784 The iCalendar METHOD property format has been updated with new 785 values. 786 A new iCalendar component, VCOMMAND, has been added. VCOMMANDs are 787 needed to fully specify CAP commands. 788 TARGET is a new property within the VCOMMAND component. It 789 indicates a 791 2.9 Relationship of RFC 2446 (ITIP) to CAP 792 [RFC2446] describes scheduling methods which result in indirect 793 manipulation of calendar components. CAP methods provide direct 794 manipuation of calendar components. In the CAP calendar store model, 795 scheduling messages are kept separate from other calendar components. 796 This is modeled with the VSCHEDULE queue. Note that this is a conceptual 797 model, the actual storage details are left to implementations. The model 798 is shown pictorially as follows: 800 +-----------------VCALENDAR-------------------+ 801 | | 802 | +-----------+ +-------VSCHEDULE---------+ | 803 | | VEVENTs | | PUBLISH messages | | 804 | | VTODOs | | REQUEST messages | | 805 | | VJOURNALs | | REPLY messages | | 806 | | | | ADD messages | | 807 | | | | CANCEL messages | | 808 | | | | REFRESH messages | | 809 | | | | COUNTER messages | | 810 | | | | DECLINECOUNTER messages | | 811 | +-----------+ +-------------------------+ | 812 +---------------------------------------------+ 814 The METHOD is saved along with components. Scheduled components become 815 booked components when the METHOD changes from an ITIP method to the CAP 816 storage method. For example, a component whose METHOD is "REQUEST" is 817 scheduled. The component becomes booked when the METHOD is changed to 818 "CREATED". 820 [ed note: need to clean up the terminology here. We haven't discussed 821 "booked"] 823 2.10 VCalendar Access Rights (VCARs) 824 In simple terms, VCARs are used to grant or deny access to a calendar 825 for a Calendar User. Specifically, they grant User Principal Names 827 Mansour/Dawson/Royer 16 Expires February 2000 828 Taler/Hill 829 (UPNs) the rights to read and write components, properties, and 830 parameters on calendars within a calendar store. 832 The model does not put any restriction on the sequence in which the 833 object and access rights are created. That is, an event associated with 834 a particular VCAR might be created before or after the actual VCAR is 835 defined. In addition, the VCAR and VEVENT definition might be created in 836 the same iCalendar object and passed together in a single SENDDATA 837 command. 839 2.11 Query Schema 841 3. State Diagram 842 This section describes the states of the transport connection between a 843 CUA and a CS. The state diagram is shown below. State names shown with 844 first letter capitalized. The commands used to switch between states are 845 shown next to an arrow connecting the states. The commands are listed in 846 all capital letters. A condition that causes a state to change is shown 847 in lower case letters. 849 CAPABILITY +-----+ 850 +-------+ | | CAPABILITY 851 | | +---------------+ | 852 | +-----------+ AUTHENTICATE | |<-+ 853 +-->| Connected |-------------->| Authenticated |<----+ 854 +-----------+ +--------| | | 855 | | +---------------+ | command 856 |DISCONNECT | | | completes 857 V |DISCONNECT | | 858 +--------------+ | |SENDDATA | 859 | Disconnected |<--+ | | 860 +--------------+ | | ABORT 861 A | | 862 | V | 863 | DISCONNECT +---------------+ | 864 +--------------------| Receive |--------+ 865 | |<--+ 866 +---------------+ | 867 | | CONTINUTE 868 +----+ 870 The connection begins the Connected state when a CUA connects to a CAP 871 server. The capabilities of the CS are reported in the response from the 872 CS. From this state, the CUA can issue the DISCONNECT command to 873 terminate the connection, the CAPABILITY command, or the AUTHENTICATE 874 command to authenticate a Calendar User. The capabilities of the CS in 875 the authenticated state are returned in the response from the CS. One 876 use of the CAPABILITY command at this stage is to determine the 877 supported authentication mechanisms supported by the server. 879 If an AUTHENTICATE command is successful, the connection enters the 880 Authenticated state. From here the CUA can issue the CAPABILITY command. 882 Mansour/Dawson/Royer 17 Expires February 2000 883 Taler/Hill 884 The capabilities the server offers in the Authenticated state may be 885 different than those in the Connected state. The connection remains in 886 the Authenticated state after the CAPABILITY command completes. The CUA 887 can issue the DISCONNECT command to terminate the connection. The 888 SENDDATA command can be used to send a request to read, write, modify, 889 or delete data on the server. 891 After the SENDDATA command has been issued the connection enters the 892 Receive state while the CUA awaits and reads a server reply. Normally, 893 the server handles the command, sends a reply which is read by the CUA 894 and the connection returns to the Authenticated state. The CUA may have 895 issued the SENDATA command with a maximum latency time. This informs the 896 server that the CUA expects a response within the maximum latency time, 897 even if the command was not completed. When the server is unable to 898 complete the command in the maximum latency time, it issues an 899 appropriate reply code and waits for the CUA to tell it how to proceed. 900 If the CUA issues a CONTINUE command the server continues processing the 901 command and the connection remains in the Receive state. If the CUA 902 issues the ABORT command the server need not process the command any 903 further and the connection returns to the Authenticated state. The 904 DISCONNECT command can also be issued from the Receive state. 906 4. Protocol Framework 908 4.1 CAP Application Layer 910 The CAP application layer is used for the manipulation of the calendar 911 store. Commands and responses are transmitted between the CUA and CS 912 inside "VCALENDAR" component wrappers. Commands are specified as the 913 value of a "METHOD" property, and responses are specified as the value 914 of a "REQUEST-STATUS" property. 916 4.2 CAP Transport Layer 918 The CAP transport layer handles the transmission of CAP application 919 layer messages. 921 CAP transport layer commands are transmitted across the underlying 922 transport. The transport used is a TCP/IP socket connection between the 923 CUA and the CS. The CS listens for connections on port . 925 Messages sent between the CUA and CS are formatted as a command followed 926 by any associated data: 928 [] 930 4.3 Response Format 931 Server responses consist of a response code and any parameters: 933 [; debug text ; more text] 934 [].CRLF> 936 Mansour/Dawson/Royer 18 Expires February 2000 937 Taler/Hill 938 The response codes are defined in Section 8. The debug text is human- 939 readable information for protocol debugging. 941 The optional application-data begins on the next line. 943 The response is terminated with a "." sequence. Any 944 "." sequences which appear in the transmitted data must be quoted by 945 placing an additional "." between the and the ".". For example, 946 the following sequences of characters in the application data: 948 . 949 ..2 950 ...3 952 are quoted as follows: 954 .. 955 ...2 956 ....3 958 No other tagged command sequence can be sent until the special 959 terminating character sequence . has been sent. 961 4.4 Auto-logout Timer 963 If a server has an inactivity auto-logout timer, that timer MUST be of 964 at least minutes duration. The receipt of ANY 965 command from the client during that interval MUST suffice to reset the 966 auto-logout timer. 968 When a timeout occurs, the server drops the connection to the CUA. 970 4.5 Bounded Latency 972 [CAP] is designed so that the CUA can either obtain an immediate 973 response from a request or discover within a specified amount of time 974 that the request could not be completed in the requested amount of time. 975 When the CUA initiates a command that the server cannot complete within 976 the specified latency time, the server returns an appropriate response 977 code. The CUA then issues either a CONTINUE or ABORT command. The ABORT 978 command immediately terminates the command in progress and the 979 connection returns to the Authenticated state. The CONTINUE command 980 instructs the server to continue processing the command. 982 4.6 Data Elements 983 The data elements for CAP are MIME encapsulated iCalendar objects. 985 Mansour/Dawson/Royer 19 Expires February 2000 986 Taler/Hill 987 5. Formal Command Syntax 989 5.1 Searching and Filtering 990 This section describes CAPs searching and filtering entities within a 991 remote store. It is based on the Standard Query Language (SQL) defined 992 by [SQL]. 994 The QUERY property value MUST be a valid QUERY value type. This new 995 value type is defined to be a "name=value" value type grammar, similar 996 in syntax to the format already in use for the iCalendar RECUR value 997 type. Each "name" is the name of a valid SQL statement component (e.g., 998 SELECT, WHERE, etc.). Each "value" is valid string associated with one 999 of these SQL statement components. 1001 [Editor's note: We need to precisely define what part of SQL we're using 1002 and why we chose what we did.] 1004 Examples needed: 1005 Grant someone access to June events 1006 Grant someone access to events during the month of June. (i.e., based on 1007 the current system date, if it's prior to June or after June you don't 1008 have access) 1010 Example for denying access to a specific property: 1012 DENY:UPN=FOO;ACTION=*;OBJECT=CLASS 1014 *scope vcar to a component 1015 *scope Grant, Deny of a VCAR 1017 5.1.1 Grammar For Search Mechanism 1019 SEARCH = "BEGIN:VQUERY" CRLF 1020 [scope] [maxresults] [maxsize] querycomp 1021 "END:VQUERY" CRLF 1023 scope = "SCOPE:" comp-name ("," comp-name)* 1025 comp-name = "VEVENT" / "VTODO" / "VJOURNAL" / "VTIMEZONE" 1026 / "VALARM" / "VFREEBUSY" / iana-name / x-name 1028 maxresults = integer 1030 maxsize = integer 1032 querycomp = (query) / (queryname query) / queryname 1034 queryname = "QUERYNAME:" text 1036 query = "QUERY:" queryrule 1038 queryrule = select where orderby ... 1040 select = 1042 Mansour/Dawson/Royer 20 Expires February 2000 1043 Taler/Hill 1044 where = 1046 orderby = 1049 6. Access Rights 1050 Access rights within CAP are specified with the "VCAR" calendar 1051 component, "RIGHTS" value type and the "GRANT", "DENY" and "CARID" 1052 component properties. 1054 Individual calendar access rights MUST be specifically granted to an 1055 authenticated calendar user (i.e., UPN); all rights are denied unless 1056 specifically granted. 1058 Properties within an iCalendar object are unordered. This also is the 1059 case for the "GRANT", "DENY" and "CARID" properties. Likewise, there is 1060 no implied ordering required for components of a "RIGHTS" value type 1061 other than that specified by the ABNF. 1063 6.1 VCAR Inheritance 1065 Calendar access rights specified in a calendar store are inherited as 1066 default calendar access rights for any calendar in the parent calendar 1067 store. Likewise, any calendar access rights specified in a root calendar 1068 are inherited as default calendar access rights for any sub-calendar to 1069 the root calendar. By implication, calendar access rights specified in a 1070 sub-calendar are inherited as default calendar access rights for any 1071 calendars that are hierarchically below the sub-calendar. 1073 Calendar access rights specified in a calendar override any default 1074 calendar access rights. Calendar access rights specified within a sub- 1075 calendar override any default calendar access rights. 1077 7. Commands and Responses 1078 CAP commands and responses are described in this section. 1079 Command arguments, identified by "Arguments:" in the command 1080 descriptions below, are described by function, not by syntax. The 1081 precise syntax of command arguments is described in the Formal Syntax 1082 section. 1084 Some commands cause specific server data to be returned; these are 1085 identified by "Data:" in the command descriptions below. See the 1086 response descriptions in the Responses section for information on these 1087 responses, and the Formal Syntax section for the precise syntax of these 1088 responses. 1090 The "Result:" in the command description refers to the possible status 1091 responses to a command, and any special interpretation of these status 1092 responses. 1094 Mansour/Dawson/Royer 21 Expires February 2000 1095 Taler/Hill 1096 Commands have the general form: 1098 [arguments...] 1100 where is a command listed in the table above. A command MAY 1101 have arguments. Arguments are defined in the detailed command 1102 definitions below. 1104 Responses to commands have the following general form: 1106 responseCode [sep transportDescr sep [applicationDescr]] 1107 CRLF "." CRLF 1109 In the examples below, lines preceded with "S:" refer to the sender and 1110 lines preceded with "R:" refer to the receiver. Lines in which the first 1111 non-whitespace character is a "#" are editorial comments and are not 1112 part of the protocol. 1114 7.1 Transport Protocol Commands 1116 7.1.1 Initial Connection 1118 Arguments: none 1119 Data: noneResult: 2.0 _ success. 1120 8.1 _ server too busy 1122 Upon session startup, the server sends a response of 2.0 to indicate 1123 that it is ready to receive commands. A response of 8.1 indicates that 1124 the server is too busy to accept the connection. In addition, the 1125 general capabilities of the CS are reported in the response from the CS. 1126 These capabilities may be different than those reported in the 1127 authenticated state. 1129 The supported AUTHentication mechanisms. There may be 1 or more. 1130 CAPVERSION 1131 IRIPVERSION 1133 7.1.2 ABORT Command 1134 Arguments: none 1136 Data: none 1138 Result: 2.0 _ success 1139 2.2 _ no command is in progres 1141 The ABORT command is issued by the CUA to stop a command whoselatency 1142 time has been exceeded. When the latency time is specified onthe SENDATA 1143 command, the CS must issue a reply to the CUA 1144 within the specified time. It may be a reply code indicating 1145 that the CS has not yet processed the request. The CUA must 1146 then tell the server whether to continue or abort. 1148 Mansour/Dawson/Royer 22 Expires February 2000 1149 Taler/Hill 1150 The CUA can issue the ABORT command at any time after the SENDATA 1151 command has been completed but before receiving a reply. 1153 7.1.3 AUTHENTICATE Command 1155 Arguments: [] 1157 Data: continuation data may be requested 1159 Result: 2.0 - Authenticate completed, now in authenticated state 1160 6.0 - Failed authentication 1161 6.1 - Authorization identity refused. 1162 6.2 - Sender aborted authentication, authentication 1163 exchange cancelled 1164 6.3 - Unsupported Authentication Mechanism 1165 9.1 - Unexpected command. 1167 The capabilities of the CS in the authenticated state are reported in 1168 the response from the CS. These may be different than the capabilities 1169 in the Connected, but unauthenticated state. 1171 The AUTHENTICATE command is used by the CUA to identify the user to the 1172 CS. CAP uses the [SASL] specification for authentication. The desired 1173 SASL mechanism is specified as the initial argument. 1175 is a registered SASL authentication mechanism. 1176 (Refer to [SASL] for information on obtaining a list of currently 1177 registered mechanisms.) CS Supported authentication mechanisms can be 1178 discovered using the CAPABILITY command. All implementations MUST 1179 support Digest-MD5 authentication using DES and 3DES, as well as DES-56 1180 for link level encryption. Implementations MUST support the SASL 1181 Anonymous mechanism, although this may be disabled in installations. 1182 Implementations SHOULD implement the External SASL mechanism and the 1183 command STARTTLS. 1185 is an optional parameter which can be used for mechanisms 1186 which require an initial response from the CUA. 1188 The AUTHENTICATE command is followed by an authentication protocol 1189 exchange, in the form of a series of CS challenges and CUA responses. 1190 These challenges and responses are encoded in Base64 and transmitted 1191 with a terminating CRLF. The CS terminates the exchange with a "." 1192 sequence followed by a reply code. ("." is not a legal Base64 1193 character.) Possible reply codes are listed above. 1195 CAP does not provide support for SASL authorization identities. If a CUA 1196 attempts to use an authorization identity the Calendar Service must 1197 return the reply code indicating that the authorization identity was 1198 refused. 1200 Mansour/Dawson/Royer 23 Expires February 2000 1201 Taler/Hill 1202 If the CUA wishes to cancel an authentication exchange it may do so by 1203 issuing a "." sequence. Upon receipt of such a sequence the CS 1204 MUST terminate the exchange and return the appropriate reply code. 1206 If a security layer was negotiated it comes into effect for the CS 1207 starting with the first octet transmitted after the CRLF which follows 1208 the 2.0 reply code, and for the CUA starting with the first octet after 1209 the CRLF of its last response in the authentication exchange. Encrypted 1210 data is transmitted as described in [SASL]. 1212 The service name specified by this protocol's profile of SASL is 1213 "cap". 1215 The result of the AUTHENTICATE command includes data indicating the 1216 identity which has been assigned to the session, derived from the 1217 supplied authentication credentials. 1219 A CAP session does not have an identity until the CUA has issued the 1220 "AUTHENTCATE" command. 1222 The CUA may not issue the "AUTHENTCATE" command multiple times, even if 1223 the first attempt was aborted. If a CUA attempts to do this the CS must 1224 terminate the session. 1226 Data returned in response to a successful logon is: 1228 Client implementations SHOULD NOT require any capability name beyond 1229 those defined in this specification, and MAY ignore any non-standard, 1230 experimental capability names. Non-standard capability names are 1231 prefixed with the text "X-". The prefix SHOULD also include a short 1232 character vendor identifier For example, "X-FOO-BARCAPABILITY", for the 1233 non-standard "BARCAPABILITY" capability of the implementor "FOO". This 1234 command may return different results in the Connected state versus the 1235 Authenticated state. It may also return different results depending on 1236 the UPN. 1238 Capability Occurs Description 1239 --------------------- ------- ---------------------------------- 1240 CAPrev1 1 Revision of CAP, must be 1241 "CAPrev1" 1243 IRIPrev1 0 or 1 Revision of IRIP, MAY be present. 1244 If present, it MUST be "IRIPrev1" 1246 CAR 0 or 1 Indicates level of CAR support CAR0, 1247 CAR1, CAR2, CAR3 1249 MAXICALOBJECTSIZE 0 or 1 An integer value that specifies 1250 The largest ICAL object the server 1251 will accept. Objects larger than 1252 this will be rejected. 1254 MAXDATE 0 or 1 The datetime value beyond which 1256 Mansour/Dawson/Royer 24 Expires February 2000 1257 Taler/Hill 1258 the server cannot accept. 1260 MINDATE 0 or 1 The datetime value prior to which 1261 the server cannot accept. 1263 The following examples illustrate the various possiblities for an 1264 authentication protocol exchange. 1266 Here are examples of a successful authentication: 1268 C: AUTHENTICATE KERBEROS_V4 1269 S: AmFYig== 1270 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1271 S: or//EoAADZI= 1272 C: DiAF5A4gA+oOIALuBkAAmw== 1273 S: 2.0 1274 S: Content-Type:text/calendar; method=REQUEST; charset=US-ASCII 1275 S: Content-Transfer-Encoding: 7bit 1276 S: 1277 S: BEGIN:VCALENDAR 1278 S: PRODID:-//ACME/CAPserver//EN 1279 S: VERSION:2.1 1280 S: IDENTITY=bill@example.com 1281 S: CAPVERSION=1.0 1282 S: ITIPVERSION=1.0 1283 S: AUTH=KERBEROS_V4 1284 S: AUTH=DIGEST_MD5 1285 S: CAR=CAR1 appl 1286 S: MINDATE=19700101T000000Z appl 1287 S: MAXDATE=20370201T000000Z 1288 S: END:VCALENDAR 1289 S: . 1291 C: AUTHENTICATE ANONYMOUS 1292 S: 2.0 1293 S: Content-Type:text/calendar; method=REQUEST; charset=US-ASCII 1294 S: Content-Transfer-Encoding: 7bit 1295 S: 1296 S: BEGIN:VCALENDAR 1297 S: PRODID:-//ACME/CAPserver//EN 1298 S: VERSION:2.1 1299 S: CAPVERSION=1.0 1300 S: ITIPVERSION=1.0 1301 S: AUTH=KERBEROS_V4 1302 S: AUTH=DIGEST_MD5 1303 S: CAR=CAR1 1304 S: MINDATE=19700101T000000Z 1305 S: MAXDATE=20370201T000000Z 1306 S: END:VCALENDAR 1307 S: . 1309 This example shows a failed authentication: 1311 Mansour/Dawson/Royer 25 Expires February 2000 1312 Taler/Hill 1313 C: AUTHENTICATE KERBEROS_V4 1314 S: AmFYig== 1315 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1316 S: . 1317 S: 6.0 1319 7.1.4 CONTINUE Command 1321 Arguments: latency time in seconds (optional) 1322 Data: noneResult: results from the command in progress 1323 2.0.2 _ reply pending. 1325 The CONTINUE command is issued by the client in response to a SENDATA 1326 timeout. When a timeout value is specified on the SENDDATA command, the 1327 server must issue a reply to the client within the specified time. If 1328 the latency time has elapsed prior to the server completing the command 1329 it returns a timeout response code. If the client wants the server to 1330 continue processing the command it responds with the CONTINUE command. 1332 If latencyTime is present, it must be a positive integer that specifies 1333 the maximum number of seconds the client will wait for the next 1334 response. If it is omitted, the receiver waits an indefinite period of 1335 time for the response. 1337 In this example, the client requests a response from the server every 10 1338 seconds. 1340 ... 1341 C: SENDDATA:10 1342 C: Content-Type:text/calendar; method=READ; component=VEVENT 1343 C: 1344 C: BEGIN:VCALENDAR 1345 # etc 1346 C: END:VCALENDAR 1347 C: . 1348 # after 10 seconds... 1349 S: . 1350 S: 2.0.2 1351 C: CONTINUE:10 1352 S: 2.0 1353 S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA; 1354 S: Optinfo=VERSION:2.1 1355 S: 1356 S: BEGIN:VCALENDAR 1357 S: VERSION:2.1 1358 S: CALID:cap://cal.example.com/relcal2 1359 # etc. 1360 S: END:VCALENDAR 1361 S: . 1363 Mansour/Dawson/Royer 26 Expires February 2000 1364 Taler/Hill 1365 7.1.5 DISCONNECT Command 1367 Arguments: none 1368 Data: 1370 Result: 2.0 1371 The DISCONNECT command is used by a client to terminate a connection. It 1372 always succeeds. 1373 Example: 1375 C: DISCONNECT 1376 # [ed. Note: should the client now wait for a response from the server 1377 # before disconnecting? ]S: 2.0 1378 C: 1379 S: 1381 7.1.6 IDENTIFY Command 1383 Arguments: Identity to assume 1385 Data: None 1387 Result: 2.0 1388 6.4 Identity not permitted 1390 The "IDENTIFY" command allows the CUA to select a new identity to be 1391 used for calendar access. This command may only be called in the 1392 Authenticated State. 1394 The CS determines through an internal mechanism if the credentials 1395 supplied at authentication permit the assumption of the selected the 1396 identity. If they do the session assumes the new identity, otherwise a 1397 security error is returned. 1399 7.1.7 SENDDATA Command 1400 Arguments: [latencyTime] 1402 Data: a MIME encapsulated iCalendar object 1404 Result: 2.0.1 - Server will now accept input until . 1405 is encountered. 1407 The SENDDATA command is used to send calendar requests and commands to 1408 the server. After a response code of 2.0.1 is issued the CUA sends a 1409 MIME encapsulated iCalendar object to the server. The end of this MIME 1410 data is signaleled by the special sequence . . 1412 7.1.8 STARTTLS Command 1413 Arguments: None 1415 Data: None 1417 Result: 2.0 1419 Mansour/Dawson/Royer 27 Expires February 2000 1420 Taler/Hill 1421 6.5 TLS not supported 1423 The "STARTTLS" command is issued by the CUA to indicate to the CS that 1424 it wishes to negotiate transport level security using [TLS]. If the CS 1425 does not support TLS it returns status code 6.5. If the CS supports TLS 1426 it issues an initial response of 2.0.12 indicating that the CUA should 1427 proceed with TLS negotiation. Once the TLS negotiation is complete the 1428 server returns the response code 2.0. 1430 After issuing the "STARTTLS" command the CUA issues the "AUTHENTICATE" 1431 command. The SASL external mechanism may be used if the CUA wishes to 1432 use the authentication id which was used in the TLS negotiation. If an 1433 authentication id was determined during TLS negotiations it MUST NOT be 1434 used for the purpose of granting a CAP session identity unless the CUA 1435 authenticates using the SASL external mechanism. 1437 The CUA MUST NOT issue a "STARTTLS" if it has already issued an 1438 "AUTHENTICATE" or "STARTTLS" command in this session. If a CUA does this 1439 the CS must terminate the session. 1441 The following examples illustrate the use of the "STARTTLS" command: 1443 Unsupported TLS: 1445 C: STARTTLS 1446 S: 6.5 1448 Supported TLS: 1450 C: STARTTLS 1451 S: 2.0.12 1452 1453 S: 2.0 1455 7.2 Application Protocol Commands 1457 7.2.1 Calendaring Commands 1458 The following methods provide a set of calendaring commands in CAP. 1459 Calendaring commands (or methods) allow a CU to directly manipulate a 1460 calendar. 1462 Calendar access rights can be granted for the more generalized access 1463 provided by the calendar commands. 1465 7.2.1.1 CREATE Method 1467 Arguments: objtype 1468 Data: no specific data for this command 1469 Result: 2.0 - successfully created the component or calendar 1470 6.0 _ Permission denied 1471 6.1 - Container(s) not found 6.2 - Calendar or 1472 component already exists 1473 Bad args 1475 Mansour/Dawson/Royer 28 Expires February 2000 1476 Taler/Hill 1477 The CREATE method is used to create a new iCalendar object of type 1478 objtype. ContainerId1 through ContainerIdn specify the container(s) for 1479 the create. When creating a new calendar at the top level, the CSID is 1480 specified. Otherwise the container will be a CalID. 1482 7.2.1.1.1 Creating New Calendars 1483 Example to create a new calendar named "Bill's Soccer Team" in several 1484 different containers. In the following example, the client is in the 1485 Authenticated state with CS cal.example.com. 1487 C: SENDDATA 1488 C: CONTENT-TYPE: text/calendar;method=CREATE;component=VCOMMAND 1489 C: Content-Transfer-Encoding:7bit 1490 C: 1491 C: BEGIN:VCALENDAR 1492 C: VERSION:2.1 1493 C: BEGIN:VCOMMAND 1494 C: METHOD:CREATE;VCALENDAR 1495 C: TARGET:cap://cal.example.com/ 1496 C: TARGET:relcal4 1497 C: TARGET://bobo.ex.com/ 1498 C: TARGET:relcal5 1499 C: TARGET:cap://cal.example.com/relcal8 1500 C: TARGET:relcal9 1501 C: BEGIN:VCALENDAR 1502 C: RELCALID:relcalz 1503 C: NAME:CHARSET=us-ascii;LANGUAGE=EN-us:Bill's Soccer Team 1504 C: OWNER:capcar:bill 1505 C: OWNER:capcar:mary 1506 C: CALMASTER:mailto:bill@example.com 1507 C: PREFERRED-TZID:US_PST 1508 C: BEGIN:VCAR 1509 C: CARID:12345 1510 C: GRANT;CN="Bill Jones":UPN=capcar:bill;ACTION=ALL;OBJECT=all 1511 C: GRANT;CN="Mary Jones":UPN=capcar:mary;ACTION=read;OBJECT=all 1512 C: END:VCAR 1513 C: END:VCALENDAR 1514 C: END:VCOMMAND 1515 C: END:VCALENDAR 1516 C: . 1517 S: 6.0 cap://cal.example.com/ 1518 S: 2.0 cap://cal.example.com/relcal4 cap://cal.example.com/relcalz 1519 S: 3.1.4 cap://bobo.ex.com/ 1520 S: 6.2 cap://cal.example.com/relcal5 1521 S: 3.1.5 cap://cal.example.com/relcal8 1522 S: 7.0 cap://cal.example.com/relcal9 1524 If the example above, the Relative CALID is specified. The values for 1525 this property must be unique on a CS. That is the reason for the 3.1.5 1526 error response. 1528 In the example below, the Relative CalID is not specified. So, the CAP 1529 server will generate one for each calendar successfully created. The 1531 Mansour/Dawson/Royer 29 Expires February 2000 1532 Taler/Hill 1533 value of the Relative CalID appears as the second parameter on the 1534 response code. 1536 S: 6.0 cap://cal.example.com/ 1537 S: 2.0 cap://cal.example.com/relcal4 cap://cal.example.com/rand123 1538 S: 3.1.4 cap://bobo.ex.com/ 1539 S: 6.2 cap://cal.example.com/relcal5 1540 S: 3.1.4 cap://cal.example.com/relcal8 1541 S: 2.0 cap://cal.example.com/relcal9 cap://cal.example.com/rand456 1543 Example to create a new component. 1545 C: SENDDATA 1546 C: Content-Type:text/calendar; method=CREATE; charset=US-ASCII 1547 C: Content-Transfer-Encoding:7bit 1548 C: 1549 C: BEGIN:VCALENDAR 1550 C: VERSION:2.1 1551 C: CMDID:abcde 1552 C: METHOD:CREATE 1553 C: TARGET:cap://cal.foo.com/relcal1 1554 C: TARGET:relcal2 1555 C: BEGIN:VEVENT 1556 C: DTSTART:19990307T180000Z 1557 C: UID:abcd12345 1558 C: DTEND:19990307T190000Z 1559 C: SUMMARY:Important Meeting 1560 C: END:VEVENT 1561 C: END:VCALENDAR 1562 C: . 1563 S: 2.0 1564 S: Content-Type:text/calendar; method=RESPONSE; OPTINFO="CMDID:abcde" 1565 S: 1566 S: BEGIN:VCALENDAR 1567 S: VERSION:2.1 1568 S: CMDID:abcde 1569 S: METHOD:RESPONSE 1570 S: BEGIN:VEVENT 1571 S: REQUEST-STATUS:2.0;cap://cal.foo.com/relcal1 abcd12345 1572 S: REQUEST-STATUS:2.0;cap://cal.foo.com/relcal2 abcd12345 1573 S: END:VEVENT 1574 S: END:VCALENDAR 1576 [Editors Note: this returns the calendar and UID? Is this right? It 1577 could also be UID and RecurrenceID ? what about if the event has an 1578 RRULE?] 1580 7.2.1.2 DELETE Method 1582 Arguments: ContainerId1 [;...ContainerIdn] 1583 Data: no specific data for this command 1584 Result: 2.0 - successfully deleted the component or calendar 1585 Permission 1586 Calendar or component not found 1588 Mansour/Dawson/Royer 30 Expires February 2000 1589 Taler/Hill 1590 Bad args 1591 Container(s) not found 1592 The DELETE method is used to delete a calendar or component. 1593 ContainerId1 through ContainerIdn specify the container(s) for the 1594 delete. When deleting a calendar at the top level, the CSID is 1595 specified. Otherwise the container will be a CalID. 1597 Example to delete a calendar at the top level: 1599 C: SENDDATA 1600 C: Content-Type:text/calendar; method=DELETE; component=VCOMMAND 1601 C: Content-Transfer-Encoding:7bit 1602 C: 1603 C: BEGIN:VCALENDAR 1604 C: BEGIN:VCOMMAND 1605 C: METHOD:DELETE 1606 C: TARGET:cap://cal.foo.com/bill 1607 C: BEGIN:VQUERY 1608 C: SCOPE:VEVENT 1609 C: QUERY SELECT="UID" 1610 C: WHERE (UID EQ abcd12345) 1611 C: END:VQUERY 1612 C: END:VCOMMAND 1613 C: END:VCALENDAR 1614 C: . 1615 S: 2.0 cap://cal.foo.com/bill 1617 7.2.1.3 GENERATEUID Method 1619 Arguments: number of uids to generate 1620 Data: new uids 1622 Result: 2.0 1623 GENERATEUID returns one or more new unique identifier which MUST be 1624 unique on the server's calendar store. It is recommended that the return 1625 value be a globally unique id. 1626 Example: 1627 C: GENERATEUID 2 1628 S: 2.0 abcde1234567-asdf-lkhh abcde1234567-asdf-3455 1630 7.2.1.4 MODIFY Method 1632 Arguments: ContainerId1 [...ContainerIdn] 1633 Data: no specific data for this command 1634 Result: 2.0 - successfully modified the component or calendar 1635 Permission 1636 Calendar or component not found 1637 Bad args 1638 Container(s) not found 1639 The MODIFY method is used to change an existing calendar or component. 1640 ContainerId1 through ContainerIdn specify the container(s) of the 1641 modification. When modifying a calendar at the top level, the CSID is 1642 specified. Otherwise the container will be a CalID. 1644 Mansour/Dawson/Royer 31 Expires February 2000 1645 Taler/Hill 1646 In the example below, the start and end time of the event with UID 1647 abcd12345 is changed and the LOCATION property is removed. 1649 C: SENDDATA 1650 C: Content-type:text/calendar; Method=MODIFY; Component=VCOMMAND 1651 C: 1652 C: BEGIN:VCALENDAR 1653 C: VERSION:2.1 1654 C: METHOD:MODIFY;VEVENT 1655 C: TARGET:relcal2 1656 C: BEGIN:VCOMMAND 1657 C: BEGIN:VQUERY 1658 C: SCOPE:VEVENT 1659 C: QUERY SELECT="UID" 1660 C: WHERE (UID EQ abcd12345) 1661 C: END:VQUERY 1662 C: BEGIN:VOLD 1663 C: DTSTART:19990421T160000Z 1664 C: DTEND:19990421T163000Z 1665 C: LOCATION:Joe's Diner 1666 C: END:VOLD 1667 C: BEGIN:VNEW 1668 C: DTSTART:19990421T160000Z 1669 C: DTEND:19990421T163000Z 1670 C: END:VNEW 1671 C: END:VCOMMAND 1672 C: END:VCALENDAR 1673 C: . 1674 S: 2.0 cap://cal.example.com/relcal2 1676 7.2.1.5 MOVE Method 1678 Arguments: ContainerId 1679 Data: data as described below 1681 Result: 2.0 _ success 1682 2.2 _ will attempt operation on the remote cap server 1683 Permission 1684 Calendar already exists 1685 Bad args 1686 Parent Calendar(s) not found 1687 This method is used to move a calendar within the CS's hierarchy of 1688 calendars. 1690 [Editors Note: there could be VCAR issues with this... if a VCAR's scope 1691 of influence is limited to a calendar, we're probably OK. We should 1692 discuss this one] 1694 7.2.1.6 READ Method 1696 Arguments: ContainerId 1697 Data: data as described below 1699 Result: 2.0 _ successful and the requested data follows 1701 Mansour/Dawson/Royer 32 Expires February 2000 1702 Taler/Hill 1703 2.2 _ will attempt read on the remote cap server 1704 Permission 1705 Calendar already exists 1706 Bad args 1707 Parent Calendar(s) not found 1709 Read Events 1710 In the example below events on March 10,1999 between 080000Z and 190000Z 1711 are read. In this case only 4 properties for each event are returned. 1712 Two calendars are specified. In the example, the CAP server is capable 1713 of 1715 C: SENDDATA 1716 C: Content-type:text/calendar; Method=READ; Component=VQUERY 1717 C: 1718 C: BEGIN:VCALENDAR 1719 C: VERSION:2.1 1720 C: METHOD:READ 1721 C: CMDID:xyz12345 1722 C: TARGET:relcal2 1723 C: TARGET:cap://bobo.ex.com/relcal3 1724 C: BEGIN:VQUERY 1725 C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID); 1726 C: FROM VEVENT; 1727 C: WHERE (DTEND >= 19990310T080000Z AND 1728 C: DTSTART <= 19990310T190000Z); 1729 C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY) 1730 C: END:VQUERY 1731 C: END:VCALENDAR 1732 C: . 1733 S: 2.0 cap://cal.example.com/relcal2 1734 S: Content-type:text/calendar; Method=RESPONSE; 1735 S: Optinfo=VERSION:2.1 1736 S: Content-Transfer-Encoding: 7bit 1737 S: 1738 S: BEGIN:VCALENDAR 1739 S: VERSION:2.1 1740 S: METHOD:RESPONSE 1741 S: BEGIN:VEVENT 1742 S: DTSTART:19990310T090000Z 1743 S: DTEND:19990310T100000Z 1744 S: UID:abcxyz12345 1745 S: SUMMARY:Meet with Sir Elton 1746 S: END:VEVENT 1747 S: BEGIN:VEVENT 1748 S: DTSTART:19990310T130000Z 1749 S: DTEND:19990310T133000Z 1750 S: UID:abcxyz8999 1751 S: SUMMARY:Meet with brave brave Sir Robin 1752 S: END:VEVENT 1753 S: END:VCALENDAR 1754 S: . 1755 S: 2.0 cap://bobo.ex.com/relcal3 1756 S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA; 1758 Mansour/Dawson/Royer 33 Expires February 2000 1759 Taler/Hill 1760 S: Optinfo=VERSION:2.1 1761 S: Content-Transfer-Encoding: 7bit 1762 S: 1763 S: BEGIN:VCALENDAR 1764 S: VERSION:2.1 1765 S: METHOD:RESPONSE 1766 S: BEGIN:VDATA 1767 S: BEGIN:VEVENT 1768 S: DTSTART:19990310T140000Z 1769 S: DTEND:19990310T150000Z 1770 S: UID:123456asdf 1771 S: SUMMARY:Summer Budget 1772 S: END:VEVENT 1773 S: END:VDATA 1774 S: END:VCALENDAR 1775 S: . 1777 The return values are subject to VCAR filtering. That is, if the request 1778 contains properties to which the UPN does not have access, those 1779 properties will not appear in the return values. If the UPN has access 1780 to at least one property of events, but has been denied access to all 1781 properties called out in the request, the response will contain a single 1782 RESPONSE-CODE property indicating the error. That is, the VEVENT 1783 components will be the following: 1785 S: 2.0 cap://bobo.ex.com/sally 1786 S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA; 1787 S: Optinfo=VERSION:2.1 1788 S: Content-Transfer-Encoding: 7bit 1789 S: 1790 S: BEGIN:VCALENDAR 1791 S: VERSION:2.1 1792 S: BEGIN:VDATA 1793 S: BEGIN:VEVENT 1794 S: RESPONSE-CODE:3.8 1795 S: END:VEVENT 1796 S: END:VDATA 1797 S: END:VCALENDAR 1798 S: . 1800 If the UPN has no access to any events at all, the response will simply 1801 be an empty data set. The response looks the same if there are 1802 particular events to which the requester has been denied access. 1804 S: 2.0 cap://bobo.ex.com/sally 1805 S: Content-type:text/calendar; Method=RESPONSE;Component=VDATA; 1806 S: Optinfo=VERSION:2.1 1807 S: Content-Transfer-Encoding: 7bit 1808 S: 1809 S: BEGIN:VCALENDAR 1810 S: VERSION:2.1 1811 S: BEGIN:VDATA 1812 S: END:VDATA 1813 S: END:VCALENDAR 1815 Mansour/Dawson/Royer 34 Expires February 2000 1816 Taler/Hill 1817 S: . 1819 Find alarms within a range of time. 1820 C: SENDDATA 1821 C: Content-type:text/calendar; Method=READ; Component=VQUERY 1822 C: 1823 C: BEGIN:VCALENDAR 1824 C: VERSION:2.1 1825 C: METHOD:READ 1826 C: CMDID:xyz12345 1827 C: TARGET:relcal2 1828 C: TARGET:cap://bobo.ex.com/relcal3 1829 C: BEGIN:VQUERY 1830 C: QUERY:SELECT (VEVENT.DTSTART, 1831 VEVENT.DTEND,VEVENT.SUMMARY, VEVENT.UID, 1832 VALARM.*); 1833 C: FROM VEVENT,VTODO; 1834 C: WHERE (VALARM.TRIGGER >= 19990310T080000Z AND 1835 C: VALARM.TRIGGER <= 19990310T190000Z); 1836 C: ORDERBY (VALARM.TRIGGER ASC) 1837 C: END:VQUERY 1838 C: END:VCALENDAR 1839 C: . 1840 S: 2.0 cap://bobo.ex.com/relcal3 1841 S: Content-type:text/calendar; Method=RESPONSE; 1842 S: Optinfo=VERSION:2.1 1843 S: Content-Transfer-Encoding: 7bit 1844 S: 1845 S: BEGIN:VCALENDAR 1846 S: VERSION:2.1 1847 S: METHOD:RESPONSE 1848 S: CMDID:xyz12345 1849 S: TARGET:cap://bobo.ex.com/relcal3 1850 S: BEGIN:VEVENT 1851 S: DTSTART:19990310T130000Z 1852 S: DTEND:19990310T133000Z 1853 S: UID:abcxyz8999 1854 S: SUMMARY:Meet with brave brave Sir Robin 1855 S: BEGIN:VALARM 1856 S: TRIGGER:19990310T132500Z 1857 S: SUMMARY:Almost time.. 1858 S: ACTION:DISPLAY 1859 S: END:VALARM 1860 S: END:VEVENT 1861 S: END:VCALENDAR 1862 S: . 1863 S: 2.0 cap://bobo.ex.com/relcal2 1864 S: Content-type:text/calendar; Method=RESPONSE; 1865 S: Optinfo=VERSION:2.1 1866 S: Content-Transfer-Encoding: 7bit 1867 S: 1868 S: BEGIN:VCALENDAR 1869 S: VERSION:2.1 1870 S: METHOD:RESPONSE 1872 Mansour/Dawson/Royer 35 Expires February 2000 1873 Taler/Hill 1874 S: CMDID:xyz12345 1875 S: TARGET:cap://bobo.ex.com/relcal2 1876 S: BEGIN:VEVENT 1877 S: REQUEST-STATUS:2.0 1878 S: END:VEVENT 1879 S: END:VCALENDAR 1880 S: . 1882 7.2.2 Scheduling Commands 1883 The following provide a set of scheduling commands (or methods) in CAP. 1884 Scheduling commands allow a CU to indirectly manipulate a calendar by 1885 asking another CU to perform an operation on their calendar. For 1886 example, CU-A can request CU-B to add a meeting to their calendar; in 1887 effect inviting CU-B to the meeting. 1889 Calendar access rights can be granted for scheduling commands without 1890 granting rights for more generalized access with the calendar commands. 1892 [Editors Note: This section needs to be completed by adding the 1893 restriction tables for each of these iTIP methods. The basis for the 1894 text is to be taken from [RFC2446].] 1896 7.2.2.1 PUBLISH 1898 7.2.2.2 REQUEST 1900 7.2.2.3 REPLY 1902 7.2.2.4 ADD 1904 7.2.2.5 CANCEL 1906 7.2.2.6 REFRESH 1908 7.2.2.7 COUNTER 1910 7.2.2.8 DECLINECOUNTER 1912 7.2.3 iTIP Examples 1913 The following examples describe scenarios for the handling of incoming 1914 iTIP data. An appropriate sort-order for the handling of icoming iTIP is 1915 by UID, Recurrence-id, sequence, dtstamp. This processing may be 1916 optimized, for instance, REFRESHs could be processed last. 1918 As an update to [RFC2446], data with the "COUNTER" method should be 1919 processed even if the Seqeunce number is stale. 1921 7.2.3.1 Sending and Receiving an iTIP request 1923 In this example A invites B and C to a meeting, B accepts the meeting 1924 and C rejects it. The calendars for A, B and C are relcal1, relcal2 1926 Mansour/Dawson/Royer 36 Expires February 2000 1927 Taler/Hill 1928 and relcal3 respectively, and are all on the same server, "cal.foo.com". 1929 A lot of these described actions are performed by the CUAs and not the 1930 users themselves, the CUAs are called A-c, B-c and C-c respectively. 1932 A wishes to create a meeting with B and C, so A-c uses CAP to send the 1933 following iTIP request to relcal2 and relcal3, while logged in to 1934 "cal.foo.com". 1936 BEGIN:VCALENDAR 1937 VERSION:2.1 1938 CMDID:xhj-dd 1939 METHOD:REQUEST 1940 TARGET:cap://cal.foo.com/relcal2 1941 TARGET:relcal3 1942 BEGIN:VEVENT 1943 UID:abcd12345 1944 DTSTART:19990307T180000Z 1945 DTEND:19990307T190000Z 1946 ORGANIZER:cap://cal.foo.com/relcal1 1947 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2 1948 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3 1949 SUMMARY:Important Meeting 1950 END:VEVENT 1951 END:VCALENDAR 1953 An incoming event (indicated by the value of the "METHOD" property) 1954 then appears in relcal2 and relcal3, with the following data: 1956 BEGIN:VEVENT 1957 METHOD:REQUEST 1958 UID:abcd12345 1959 DTSTART:19990307T180000Z 1960 DTEND:19990307T190000Z 1961 ORGANIZER:cap://cal.foo.com/relcal1 1962 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2 1963 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3 1964 SUMMARY:Important Meeting 1965 END:VEVENT 1967 B-c and C-c must search for such incoming events, they do so using the 1968 following CAP search: 1970 BEGIN:VCALENDAR 1971 VERSION:2.1 1972 METHOD:READ 1973 CMDID:xhr-de 1974 TARGET:relcal2 1975 # or TARGET:relcal3 1976 BEGIN:VQUERY 1977 QUERY:SELECT (ALL); 1978 FROM VEVENT; 1979 WHERE (METHOD == REQUEST); 1980 END:VQUERY 1981 END:VCALENDAR 1983 Mansour/Dawson/Royer 37 Expires February 2000 1984 Taler/Hill 1985 In response to this search they get the above event. B-c and C-c must 1986 then crack open the VEVENT, find the UID and determine if there is 1987 already an event on their calendar with that UID. To do this they use 1988 the following search: 1990 BEGIN:VCALENDAR 1991 VERSION:2.1 1992 METHOD:READ 1993 CMDID:xhr-df 1994 TARGET:relcal2 1995 BEGIN:VQUERY 1996 QUERY:SELECT (ALL); 1997 FROM VEVENT; 1998 WHERE (UID == abcd12345); 1999 END:VQUERY 2000 END:VCALENDAR 2002 We assume that the event is not already in their relcal2 or relcal3, so 2003 the read they only returns the original incoming iTIP (the UID matched), 2004 but this can be ignored since it is incoming. 2006 B-c prompts B who decides to accept the meeting request, and B-c creates 2007 a copy of the event in relcal2, with the "PARTSTAT" parameter set to 2008 ACCEPTED. B-c also sends this copy to the Organizer at relcal1 as an 2009 iTIP REPLY, preserving the CMDID: 2011 BEGIN:VCALENDAR 2012 VERSION:2.1 2013 CMDID:xhj-dd 2014 METHOD:REPLY 2015 TARGET:cap://cal.foo.com/relcal1 2016 BEGIN:VEVENT 2017 UID:abcd12345 2018 DTSTART:19990307T180000Z 2019 DTEND:19990307T190000Z 2020 ORGANIZER:cap://cal.foo.com/relcal1 2021 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 2022 SUMMARY:Important Meeting 2023 END:VEVENT 2024 END:VCALENDAR 2026 C, on the other hand, decides to decline the meeting, and C-c sends a 2027 reply to the Organizer to that effect, as follows: 2029 BEGIN:VCALENDAR 2030 VERSION:2.1 2031 CMDID:xhj-dd 2032 METHOD:REPLY 2033 TARGET:cap://cal.foo.com/relcal1 2034 BEGIN:VEVENT 2035 UID:abcd12345 2036 DTSTART:19990307T180000Z 2037 DTEND:19990307T190000Z 2039 Mansour/Dawson/Royer 38 Expires February 2000 2040 Taler/Hill 2041 ORGANIZER:cap://cal.foo.com/relcal1 2042 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 2043 SUMMARY:Important Meeting 2044 END:VEVENT 2045 END:VCALENDAR 2047 It is preferable that C-c store the event in relcal3 even though it has 2048 been declined. Storing the event in relcal3 allows subsequent iTIP 2049 messages to be interpreted correctly. The "PARTSTAT" parameter 2050 indicates that the event was refused, and a tombstone property may be 2051 necessary if the user wishes to delete the event. 2053 After receiving the replies from relcal2 and relcal3, A-c updates the 2054 version of the event in relcal1 to indicate the new participation 2055 statii: 2057 BEGIN:VEVENT 2058 METHOD:REQUEST 2059 UID:abcd12345 2060 DTSTART:19990307T180000Z 2061 DTEND:19990307T190000Z 2062 ORGANIZER:cap://cal.foo.com/relcal1 2063 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 2064 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 2065 SUMMARY:Important Meeting 2066 END:VEVENT 2068 A-c then sends a new iTIP request to relcal2 only, indicating the 2069 updated information. 2071 7.2.3.2 Handling an iTIP refresh 2073 A little bit later, C is thinking about accepting the event in the 2074 previous example, but first wants to check the current state of the 2075 event. To find the current state C-c uses the iTIP "REFRESH" method, 2076 sending the following to relcal1: 2078 BEGIN:VCALENDAR 2079 VERSION:2.1 2080 CMDID:xud-pn 2081 METHOD:REFRESH 2082 TARGET:cap://cal.foo.com/relcal1 2083 BEGIN:VEVENT 2084 UID:abcd12345 2085 ORGANIZER:cap://cal.foo.com/relcal1 2086 ATTENDEE:cap://cal.foo.com/relcal3 2087 DTSTAMP:19990306T202333Z 2088 END:VEVENT 2089 END:VCALENDAR 2091 A-c finds the refresh as an incoming iTIP, and searches for the 2092 corresponding event. Having found the event (with no changes since the 2093 last example) A-c then verifies that relcal3 is in fact an Attendee of 2094 the event and is thus allowed to request a refresh. (In the case of a 2096 Mansour/Dawson/Royer 39 Expires February 2000 2097 Taler/Hill 2098 published event things are more complicated.) A-c packages the event up 2099 as an iTIP request and sends it to relcal3: 2101 BEGIN:VCALENDAR 2102 VERSION:2.1 2103 CMDID: xud-pn 2104 METHOD:REQUEST 2105 TARGET:cap://cal.foo.com/relcal3 2106 BEGIN:VEVENT 2107 UID:abcd12345 2108 DTSTART:19990307T180000Z 2109 DTEND:19990307T190000Z 2110 ORGANIZER:cap://cal.foo.com/relcal1 2111 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 2112 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 2113 SUMMARY:Important Meeting 2114 SEQUENCE:0 2115 DTSTAMP:19990306T204333Z 2116 END:VEVENT 2117 END:VCALENDAR 2119 [Ed. - should the CMDID match that of the REFRESH?] 2121 7.2.3.3 Sending and accepting an iTIP counter 2123 Having received the latest copy of the event C wishes to propose a 2124 venue for the event, using an iTIP COUNTER. To do this C-c sends the 2125 following to relcal1: 2127 BEGIN:VCALENDAR 2128 VERSION:2.1 2129 CMDID:zzykjjk 2130 METHOD:COUNTER 2131 TARGET:cap://cal.foo.com/relcal1 2132 BEGIN:VEVENT 2133 UID:abcd12345 2134 DTSTART:19990307T180000Z 2135 DTEND:19990307T190000Z 2136 ORGANIZER:cap://cal.foo.com/relcal1 2137 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 2138 SUMMARY:Important Meeting 2139 LOCATION:La Belle Province 2140 COMMENT:My favourite restaurant\, I'll definitely go if it's there. 2141 END:VEVENT 2142 END:VCALENDAR 2144 Having sent the information to relcal1, C-c shouldn't store the new 2145 details in relcal3. If C-c updated the version in relcal3 and relcal1 2146 did not reply to the counter, then relcal3 would have incorrect 2147 information. Instead C-c preserves the correct information and waits 2148 for a response from relcal1. A CUA implementation may wish to 2149 preserve this information itself, externally to the CS. 2151 Mansour/Dawson/Royer 40 Expires February 2000 2152 Taler/Hill 2153 In order to receive an iTIP counter A-c follows the same search as for 2154 other iTIP data, first find the incoming message, next find any 2155 matching events in the calendar store. 2157 Having found the matching event, A reviews the proposed changes and 2158 decides to accept the COUNTER. To do this, A-c modifies the version 2159 in relcal1 (bumping the sequence number) to: 2161 BEGIN:VEVENT 2162 METHOD:CREATE 2163 UID:abcd12345 2164 DTSTART:19990307T180000Z 2165 DTEND:19990307T190000Z 2166 ORGANIZER:cap://cal.foo.com/relcal1 2167 ATTENDEE;PARTSTAT=ACCEPTED:cap://cal.foo.com/relcal2 2168 ATTENDEE;PARTSTAT=DECLINED:cap://cal.foo.com/relcal3 2169 SUMMARY:Important Meeting 2170 LOCATION:La Belle Province 2171 SEQUENCE:1 2172 END:VEVENT 2174 A-c then sends the updated version as a request to both relcal2 and 2175 relcal3: 2177 BEGIN:VCALENDAR 2178 VERSION:2.1 2179 CMDID:xup-po 2180 METHOD:REQUEST 2181 TARGET:cap://cal.foo.com/relcal2 2182 TARGET:cap://cal.foo.com/relcal3 2183 BEGIN:VEVENT 2184 UID:abcd12345 2185 DTSTART:19990307T180000Z 2186 DTEND:19990307T190000Z 2187 ORGANIZER:cap://cal.foo.com/relcal1 2188 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal2 2189 ATTENDEE;RSVP=TRUE;PARTSTAT=NEEDS-ACTION:cap://cal.foo.com/relcal3 2190 SUMMARY:Important Meeting 2191 LOCATION:La Belle Province 2192 SEQUENCE:1 2193 DTSTAMP:19990307T054339Z 2194 END:VEVENT 2195 END:VCALENDAR 2197 7.2.3.4 Declining an iTIP counter 2199 B does not like the new location and also counters the event, B-c 2200 sends the following iTIP: 2202 BEGIN:VCALENDAR 2203 VERSION:2.1 2204 CMDID:xim-ef 2205 METHOD:COUNTER 2207 Mansour/Dawson/Royer 41 Expires February 2000 2208 Taler/Hill 2209 TARGET:cap://cal.foo.com/relcal1 2210 BEGIN:VEVENT 2211 UID:abcd12345 2212 DTSTART:19990307T180000Z 2213 DTEND:19990307T190000Z 2214 ORGANIZER:cap://cal.foo.com/relcal1 2215 ATTENDEE:cap://cal.foo.com/relcal2 2216 SUMMARY:Important Meeting 2217 LOCATION:Au Coin Dor=E9 2218 END:VEVENT 2219 END:VCALENDAR 2221 However, C does not accept the counter, and C-c replies with a decline 2222 counter: 2224 BEGIN:VCALENDAR 2225 VERSION:2.1 2226 CMDID:xim-ef 2227 METHOD:DECLINE-COUNTER 2228 TARGET:cap://cal.foo.com/relcal2 2229 BEGIN:VEVENT 2230 DTSTAMP:19990307T093245Z 2231 UID:abcd12345 2232 ORGANIZER:cap://cal.foo.com/relcal1 2233 SEQUENCE:1 2234 END:VEVENT 2235 END:VCALENDAR 2237 Fortunately B-c kept the original information when sending the 2238 counter, and there is no problem when no information is returned in 2239 the DECLINE-COUNTER. 2241 8. Response Codes 2242 Numeric response codes are returned at both the transport and 2243 application layer. The same set of codes is used in both cases. 2245 [Editors Note: Do we want to use the same set of codes?] 2247 The format of these codes is described in [RFC2445], and extend in 2248 [RFC2446] and [RFC2447]. The following describes new codes added to this 2249 set. 2251 At the application layer response codes are returned as the value of a 2252 "REQUEST-STATUS" property. The value type of this property is modified 2253 from that defined in [RFC2445], to make the accompanying text optional. 2255 Code Params Description 2256 -------------------------------------------------------------------- 2257 2.0 varies Success. The parameters vary with the operation 2258 and are specified 2260 2.0.1 none Success, send data, terminate with 2262 Mansour/Dawson/Royer 42 Expires February 2000 2263 Taler/Hill 2264 . 2266 2.0.2 A reply is pending. It could not be completed in 2267 the specified amount of time. The server awaits 2268 a CONTINUE or ABORT command. 2270 2.0.3 In response to the client issuing an ABORT 2271 command, this reply code indicates that any 2272 command currently underway was successfully 2273 aborted. 2275 2.0.6 An operation is being attempted on a remote 2276 server. This response indicates that the server 2277 has not yet been contacted but an attempt will 2278 be made to contact it after the command has been 2279 sent. 2281 3.1.4 Capability not supported 2283 4.1 Calendar store access denied 2285 6.1 authenticate failure: unsupported authentication 2286 mechanism, credentials rejected 2288 6.2 Sender aborted authentication, authentication 2289 exchange cancelled 2291 7.0 A timeout has occurred. The server was unable 2292 to complete the operation in the requested time. 2294 8.0 A failure has occurred in the Receiver that 2295 prevents the operation from succeeding. 2297 8.1 Sent when a session cannot be established because 2298 the CAP Server is too busy. 2300 8.2 Used to signal that an ICAL object has exceeded 2301 the server's size limit. 2303 8.3 A DATETIME value was too large to be represented 2304 on this Calendar. 2306 8.4 A DATETIME value was too far in the past to be 2307 represented on this Calendar. 2309 8.5 An attempt was made to create a new object but 2310 the unique id specified is already in use. 2312 8.6 ID clash 2314 9.0 An unrecongnized command was received. 2316 10.1 Accompanied by an alternate address. The 2318 Mansour/Dawson/Royer 43 Expires February 2000 2319 Taler/Hill 2320 RECIPIENT specified should be contacted at the 2321 given alternate address. The referral address 2322 MUST follow the reply code. 2324 10.2 The server is shutting down. 2326 10.4 The operation has not be performed because it 2327 would cause the resources (memory, disk,CPU, etc) 2328 to exceed the allocated quota. 2330 10.5 The ITIP message has been queued too too long. 2331 Delivery has been aborted. 2333 9. Detailed SQL Schema 2334 This section describes a conceptual schema for object model in CAP. It 2335 is used as the basis for querying data managed by the CS. This is only a 2336 conceptual schema. Implementations can use any schema they like so long 2337 as they are prepared to map CAP queries that are expressed in this 2338 conceptual schema. Implementations are not required to use SQL database 2339 technology. The protocol is designed such that a CUA does not need to 2340 handle these queries. 2342 This schema is based on SQL-92 [SQL] along with the [SQLCOM] 2343 corrections. 2345 Properties than can occur multiple times are intended to be put in 2346 separate tables. For example 2348 BEGIN:VEVENT 2349 UID:1 2350 DTSTART:19990326T201400Z 2351 ORGANIZER:mailto:sam@abc.COM 2352 SUMMARY:I have 2 attachments 2353 ATTACHMENT;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell.au 2354 ATTACHMENT;FMTTYPE=audio/basic:ftp://host.com/pub/sounds/bell2.au 2355 END:VEVENT 2357 There are two ATTACHMENT properties each having a unique value. These 2358 are kept in separate tables. This is diagrammed below. The diagram is 2359 not a complete representation of the VEVENT table. It is an abbreviated 2360 table used to illustrate how properties that can occur multiple times 2361 are intended to be represented. 2363 ABBREVIATED VEVENT TABLE 2365 UID DTSTART ORGANIZER SUMMARY ATTACH_LIST 2366 +----+----------------+-------------------+------------+------------+ 2367 |1 |19990326T201400Z|mailto:sam@abc.com |I have 2 | 123 | 2368 | | | |attachments | | 2369 +----+----------------+-------------------+------------+------------+ 2370 |999 |19700101T000000Z|mailto:usr@host.com|I have no | | 2371 | | | |attachments | | 2373 Mansour/Dawson/Royer 44 Expires February 2000 2374 Taler/Hill 2375 +----+----------------+-------------------+------------+------------+ 2377 ABBREVIATED ATTACH_LIST TABLE 2379 ATTACH_LIST VALUE INLINE_BLOB 2380 +------------+------------------------------------+-----------------+ 2381 |123 | ftp://host.com/pub/sounds/bell.au | | 2382 +------------+------------------------------------+-----------------+ 2383 |123 | ftp://host.com/pub/sounds/bell2.au| | 2384 +------------+------------------------------------+-----------------+ 2385 |234 | | MIICajCCAdO- | 2386 | | | gAwIBAgICBEU | 2387 | | | <...remainder | 2388 | | | of "BASE64"| 2389 | | | encoded binary| 2390 | | | data...> | 2391 +------------+------------------------------------+-----------------+ 2393 9.1 iCalendar Store Schema 2394 The following defines the schema for an iCalendar object and the 2395 components, properties, and parameters defined in [RFC2445]. 2397 Create table VCALENDAR { 2398 RELATIVECALID VARCHAR(256) PRIMARY KEY, 2399 CALMASTER VARCHAR(256), 2400 CHARSET VARCHAR(256), 2401 CHILDREN VARCHAR(256) 2402 LANGUAGE CHAR(5) 2403 LAST_MODIFIED 2404 NAME VARCHAR(256), 2405 OWNERS 2406 PARENT CHAR(16), 2407 PATH 2408 SCHEDULABLE_HOURS 2409 TOMBSTONE 2410 TZID 2411 LAST_MODIFIED_BY 2412 }; 2414 create table VEVENT { 2415 ATTACH_LIST INTEGER, 2416 ATTENDEE_LIST INTEGER, 2417 /* CATEGORIES may contain a comma seperated list */ 2418 CATEGORIES VARCHAR(len?), 2419 CLASS INTEGER, 2420 CLASS_PARAMS INTEGER, 2421 COMMENT VARCHA, 2422 COMMENT_PARAMS INTEGER, 2423 CONTACT_LIST INTEGER, 2424 CREATED TIMESTAMP NOT NULL DEFAULT 2425 CURRENT_DATE, 2426 CREATED_PARAMS INTEGER, 2427 DESCRIPTION VARCHAR(len?), 2429 Mansour/Dawson/Royer 45 Expires February 2000 2430 Taler/Hill 2431 DESCRIPTION_PARAMS INTEGER, 2432 DTEND TIMESTAMP, 2433 DTEND_PARAMS INTEGER, 2434 DTSTAMP TIMESTAMP NOT NULL, 2435 DTSTAMP_PARAMS INTEGER, 2436 DTSTART TIMESTAMP NOT NULL, 2437 DTSTART_PARAMS INTEGER, 2438 DURATION , 2439 DURATION_PARAMS INTEGER, 2440 EXDATE_LIST INTEGER, 2441 EXRULE_LIST INTEGER, 2442 GEO_LAT NUMBER, 2443 GEO_LON NUMBER, 2444 GEO_PARAMS INTEGER, 2445 LAST_MODIFIED TIMESTAMP NOT NULL DEFAULT 2446 CURRENT_DATE, 2447 LAST_MODIFIED_PARAMS INTEGER, 2448 LOCATION VARCHA, 2449 LOCATION_PARAMS INTEGER, 2450 METHOD VARCHAR(len20?), 2451 ORGANIZER VARCHAR(len?) NOT NULL, 2452 ORGANIZER_PARAMS INTEGER, 2453 PRIORITY INTEGER, 2454 PRIORITY_PARAMS CHAR(1), 2455 RECURRENCE_ID VARCHAR(len?), 2456 RECURRENCE_ID_PARAMS INTEGER, 2457 RDATE_LIST INTEGER, 2458 RELATED_TO_LIST INTEGER, 2459 /* RESOURCES may contain a comma seperated list */ 2460 RESOURCES VARCHAR(len?), 2461 RESOURCES_PARAMS INTEGER, 2462 RRULE_LIST INTEGER, 2463 SUMMARY VARCHAR(len?) NOT NULL DEFAULT "", 2464 SUMMARY_PARAMS INTEGER, 2465 SEQUENCE INTEGER NOT NULL DEFAULT 0, 2466 SEQUENCE_PARAMS INTEGER, 2467 STATUS INTEGER, 2468 STATUS_PARAMS CHAR(1), 2469 TRANSP CHAR(1), 2470 TRANSP_PARAMS INTEGER, 2471 UID VARCHAR(len?) NOT NULL, 2472 UID_PARAMS INTEGER, 2473 URL VARCHA, 2474 URL_PARAMS INTEGER, 2475 X_PROP_LIST INTEGER, 2476 VALARM_LIST INTEGER, 2477 }; 2479 create table VTODO { 2480 ATTENDEE_LISTINTEGER, 2481 ATTACH_LIST INTEGER, 2482 /* CATEGORIES may contain a comma separated list */ 2483 CATEGORIES VARCHAR(len?), 2484 CLASS INTEGER, 2486 Mansour/Dawson/Royer 46 Expires February 2000 2487 Taler/Hill 2488 CLASS_PARAMS INTEGER, 2489 COMMENT VARCHAR(len?), 2490 COMMENT_PARAMS INTEGER, 2491 CONTACT_LIST INTEGER, 2492 CREATED TIMESTAMP NOT NULL DEFAULT 2493 CURRENT_DATE, 2494 CREATED_PARAMS INTEGER, 2495 DESCRIPTION VARCHAR(len?), 2496 DESCRIPTION_PARAMS INTEGER, 2497 DTSTAMP TIMESTAMP NOT NULL, 2498 DTSTAMP_PARAMS INTEGER, 2499 DTSTART TIMESTAMP NOT NULL, 2500 DTSTART_PARAMS INTEGER, 2501 DUE TIMESTAMP, 2502 DUE_PARAMS INTEGER, 2503 DURATION , 2504 DURATION_PARAMS INTEGER, 2505 EXDATE_LIST INTEGER, 2506 EXRULE_LIST INTEGER, 2507 GEO_LAT NUMBER, 2508 GEO_LON NUMBER, 2509 GEO_PARAMS INTEGER, 2510 LAST_MODIFIED TIMESTAMP NOT NULL DEFAULT 2511 CURRENT_DATE, 2512 LAST_MODIFIED_PARAMS INTEGER, 2513 LOCATION VARCHA, 2514 LOCATION_PARAMS INTEGER, 2515 METHOD VARCHAR(len20?), 2516 ORGANIZER VARCHAR(len?) NOT NULL, 2517 ORGANIZER_PARAMS INTEGER, 2518 PERCENT_COMPLETE INTEGER, 2519 PERCENT_COMPLETE_PARAMSLETE INTEGER 2520 PRIORITY INTEGER NOT NULL, 2521 PRIORITY_PARAMS INTEGER, 2522 RDATE_LIST INTEGER, 2523 RECURRENCE_ID VARCHAR(len?), 2524 RECURRENCE_ID_PARAMS INTEGER, 2525 /* RESOURCES may contain a comma seperated list */ 2526 RESOURCES VARCHAR(len?), 2527 RESOURCES_PARAMS INTEGER, 2528 RRULE_LIST INTEGER, 2529 SEQUENCE INTEGER NOT NULL DEFAULT 0, 2530 SEQUENCE_PARAMS INTEGER, 2531 SUMMARY VARCHAR(len?) NOT NULL DEFAULT "", 2532 SUMMARY_PARAMS INTEGER, 2533 UID VARCHAR(len?) NOT NULL, 2534 UID_PARAMS INTEGER, 2535 URL VARCHAR(len?) 2536 URL_PARAMS INTEGER, 2537 X_PROP_LIST INTEGER 2538 VALARM_LIST INTEGER, 2539 }; 2541 create table VJOURNAL { 2543 Mansour/Dawson/Royer 47 Expires February 2000 2544 Taler/Hill 2545 ATTACH_LIST INTEGER, 2546 /* CATEGORIES may contain a comma seperated list */ 2547 CATEGORIES VARCHAR(len?), 2548 CLASS INTEGER, 2549 CLASS_PARAMS INTEGER, 2550 COMMENT VARCHAR(len?), 2551 COMMENT_PARAMS INTEGER, 2552 CONTACT_LIST INTEGER, 2553 CREATED TIMESTAMP NOT NULL DEFAULT 2554 CURRENT_DATE, 2555 CREATED_PARAMS INTEGER, 2556 DESCRIPTION VARCHAR(len?) NOT NULL DEFAUT "", 2557 DESCRIPTION_PARAMS INTEGER, 2558 DTSTAMP TIMESTAMP NOT NULL, 2559 DTSTAMP_PARAMS INTEGER, 2560 DTSTART TIMESTAMP NOT NULL, 2561 DTSTART_PARAMS INTEGER, 2562 EXDATE_LIST INTEGER, 2563 EXRULE_LIST INTEGER, 2564 LAST_MODIFIED TIMESTAMP NOT NULL DEFAULT 2565 CURRENT_DATE, 2566 METHOD VARCHAR(len20?), 2567 LAST_MODIFIED_PARAMS INTEGER, 2568 ORGANIZER VARCHAR(len?) NOT NULL, 2569 ORGANIZER_PARAMS INTEGER, 2570 RDATE_LIST INTEGER, 2571 RECURRENCE_ID VARCHAR(len?), 2572 RECURRENCE_ID_PARAMS INTEGER, 2573 RELATED_TO_LIST INTEGER, 2574 RRULE_LIST INTEGER, 2575 SEQUENCE INTEGER NOT NULL DEFAULT 0, 2576 SEQUENCE_PARAMS INTEGER, 2577 STATUS INTEGER, 2578 STATUS_PARAMS CHAR(1), 2579 SUMMARY VARCHAR(len?) NOT NULL DEFAULT "", 2580 SUMMARY_PARAMS INTEGER, 2581 UID VARCHAR(len?) NOT NULL, 2582 UID_PARAMS INTEGER, 2583 X_PROP_LIST INTEGER 2584 }; 2586 An implementation may not actually have a VFREEBUSY table as 2587 the information may be produced dynamicly. However a CS 2588 MUST appear to provide this table as this may be how a CUA 2589 chooses to query for VFREEBUSY information while using 2590 [CAP]. Example, it probabily would not make any sense for 2591 ATTENDEE to exist in this table, yet a CUA may wish to ask 2592 for the VFREEBUSY for an ATTENDEE. 2594 create table VFREEBUSY { 2595 ATTENDEE_LIST VARCHAR(len?), 2596 COMMENT VARCHAR(len?), 2597 COMMENT_PARAMS INTEGER, 2598 CONTACT_LIST INTEGER, 2600 Mansour/Dawson/Royer 48 Expires February 2000 2601 Taler/Hill 2602 DTEND TIMESTAMP NOT NULL, 2603 DTEND_PARAMS INTEGER, 2604 DTSTAMP TIMESTAMP NOT NULL, 2605 DTSTAMP_PARAMS INTEGER, 2606 DTSTART TIMESTAMP NOT NULL, 2607 DTSTART_PARAMS INTEGER, 2608 FREEBUSY_LIST INTEGER NOT NULL, 2609 METHOD VARCHAR(len20?), 2610 ORGANIZER VARCHAR(len?) NOT NULL, 2611 ORGANIZER_PARAMS INTEGER, 2612 X_PROP_LIST INTEGER 2613 URL VARCHAR(len?) 2614 }; 2616 create table VTIMEZONE { 2617 DAYLIGHT_LIST INTEGER, /* In TZ_LIST table */ 2618 STANDARD_LIST INTEGER, /* In TZ_LIST table */ 2619 TZID VARCHAR(len?) NOT NULL, 2620 TZID_PARAM INTEGER, 2621 TZURL VARCHAR(len?) NOT NULL, 2622 TZURL_PARAM INTEGER, 2623 X_PROP_LIST INTEGER 2624 }; 2626 create table TZ_LIST { 2627 /* Maps to DAYLIGHT_LIST or STANDARD_LIST in VTIMEZONE table */ 2628 TZ_KEY INTEGER, 2629 COMMENT VARCHAR(len?), 2630 COMMENT_PARAMS INTEGER, 2631 DTSTART TIMESTAMP NOT NULL, 2632 DTSTART_PARAMS INTEGER, 2633 LAST_MODIFIED TIMESTAMP NOT NULL DEFAULT 2634 CURRENT_DATE, 2635 LAST_MODIFIED_PARAMS INTEGER, 2636 RDATE_LIST INTEGER, 2637 RRULE_LIST INTEGER, 2638 TZNAME VARCHAR(len?), 2639 TZOFFSET NOT NULL, 2640 TZOFFSETFROM NOT NULL, 2641 TZOFFSETTO NOT NULL, 2642 }; 2644 create table VALARM_LIST { 2645 /* Maps to VALARM_LIST in other tables */ 2646 VALARM_KEY INTEGER, 2647 ACTION INTEGER NOT NULL, 2648 ACTION_PARAMS INTEGER, 2649 ATTACH_LIST INTEGER, 2650 DESCRIPTION VARCHAR(len?) NOT NULL DEFAUT "", 2651 DESCRIPTION_PARAMS INTEGER, 2652 DURATION , 2653 DURATION_PARAMS INTEGER, 2654 REPEAT INTEGER, 2655 REPEAT_PARAMS INTEGER, 2657 Mansour/Dawson/Royer 49 Expires February 2000 2658 Taler/Hill 2659 SUMMARY VARCHAR(len?) NOT NULL DEFAULT "", 2660 SUMMARY_PARAMS INTEGER, 2661 TRIGGER_DT TIMESTAMP, 2662 TRIGGER_DURATION , 2663 X_PROP_LIST INTEGER 2664 }; 2666 10. Examples 2667 For all the examples in this section, the authenticated user is 2668 user@example.com. 2670 10.1 Authentication Examples 2672 10.1.1 Login Using Kerberos V4 2673 Use Kerberos V4 to authenticate as bill@example.com to the CAP server on 2674 cal.example.com. 2676 C: 2677 S: 2.0 2678 S: CAPVERSION=1.0 2679 S: ITIPVERSION=1.0 2680 S: AUTH=KERBEROS_V4 2681 S: AUTH=DIGEST_MD5 2682 S: . 2683 C: AUTHENTICATE KERBEROS_V4 2684 S: AmFYig== 2685 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 2686 S: or//EoAADZI= 2687 C: DiAF5A4gA+oOIALuBkAAmw== 2688 S: 2.0 2689 S: IDENTITY=bill@example.com 2690 S: CAPVERSION=1.0 2691 S: ITIPVERSION=1.0 2692 S: AUTH=KERBEROS_V4 2693 S: AUTH=DIGEST_MD5 2694 S: CAR=CAR1 appl 2695 S: MINDATE=19700101T000000Z appl 2696 # who knows this date (end of the 32 bit number)? 2697 S: MAXDATE=20370201T000000Z 2698 S: . 2700 10.1.2 Error Scenarios 2701 Use of SASL Authorization Identity is not supported. Use the IDENTITY 2702 command instead. If you attempt to use the Authorization Identity, an 2703 error status will be returned. 2705 C: AUTHENTICATE KERBEROS_V4 2706 S: AmFYig== 2707 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 2708 S: or//EoAADZI= 2709 C: DiAF5A4gA+oOIALuBkAAmw== 2710 S: 6.1 2712 Mansour/Dawson/Royer 50 Expires February 2000 2713 Taler/Hill 2714 S: . 2716 Sender aborted authentication: 2718 C: AUTHENTICATE KERBEROS_V4 2719 S: AmFYig== 2720 C: . 2721 S: 6.2 2722 S: . 2724 Unsupported mechanism: 2726 C: AUTHENTICATE Experimental_Auth 2727 S: 6.3 2728 S: . 2730 10.2 Read Examples 2732 10.2.1 Read From A Single Calendar 2733 In this example bill@example.com reads a day's worth of events from 2734 cap://cal.example.com/opaqueid99. 2736 C: SENDDATA 2737 C: Content-type:text/calendar; Method=READ; Component=VQUERY 2738 C: 2739 C: BEGIN:VCALENDAR 2740 C: VERSION:2.1 2741 C: METHOD:READ 2742 C: CMDID:xyz12345 2743 C: TARGET:cap://cal.example.com/opaqueid99 2744 C: BEGIN:VQUERY 2745 C: QUERY:SELECT (VEVENT.DTSTART,VEVENT.DTEND,SUMMARY,UID); 2746 C: FROM VEVENTTABLE; 2747 C: WHERE (VEVENT.DTEND >= 19990714T080000Z AND 2748 C: VEVENT.DTSTART <= 19990715T080000Z); 2749 C: ORDERBY (VEVENT.DTSTART ASC, VEVENT.DTEND, UID, SUMMARY) 2750 C: END:VQUERY 2751 C: END:VCALENDAR 2752 C: . 2754 # this response code means that the transport successfully 2755 # delivered the data. 2756 S: 2.0 ; got the request OK ; I swear 2757 S: Content-type:text/calendar; Method=RESPONSE; 2758 S: Optinfo=VERSION:2.1 2759 S: Content-Transfer-Encoding: 7bit 2760 S: 2761 S: BEGIN:VCALENDAR 2762 S: VERSION:2.1 2763 S: METHOD:RESPONSE 2764 S: TARGET:cap://cal.example.com/opaqueid99 2765 S: CMDID:xyz12345 2767 Mansour/Dawson/Royer 51 Expires February 2000 2768 Taler/Hill 2769 # we have not yet discussed response-status 2771 S: RESPONSE-STATUS:2.0 2772 S: BEGIN:VEVENT 2773 S: DTSTART:19990714T200000Z 2774 S: DTEND:19990714T210000Z 2775 S: UID:000444888929922 2776 S: SUMMARY:Blah bla 2777 S: END:VEVENT 2778 S: BEGIN:VEVENT 2779 S: UID:0034848098038888989443 2780 S: SUMMARY:meeting 2781 S: DTEND:19990714T233000Z 2782 S: DTSTART:19990714T223000Z 2783 S: END:VEVENT 2784 S: END:VCALENDAR 2785 S: . 2787 10.2.2 Read From Multiple Calendars 2788 In this example bill@example.com reads a day's worth of events from 2789 cap://cal.example.com/opaqueid101 and cap://cal.example.com/opaqueid103 2791 C: SENDDATA 2792 C: Content-type:text/calendar; Method=READ; Component=VQUERY 2793 C: 2794 C: BEGIN:VCALENDAR 2795 C: VERSION:2.1 2796 C: METHOD:READ 2797 C: CMDID:xyz12346 2798 C: TARGET:cap://cal.example.com/opaqueid101 2799 C: TARGET:opaqueid103 2800 C: BEGIN:VQUERY 2801 C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID); 2802 C: FROM VEVENT; 2803 C: WHERE (DTEND >= 19990714T080000Z AND 2804 C: DTSTART <= 19990715T080000Z); 2805 C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY) 2806 C: END:VQUERY 2807 C: END:VCALENDAR 2808 C: . 2809 S: 2.0 2810 S: Content-Type:multipart/mixed;boundary="--FEE3790DC7E35189CA67" 2811 S: 2812 S: ----FEE3790DC7E35189CA67 2813 S: Content-type:text/calendar; Method=RESPONSE; 2814 S: Optinfo=VERSION:2.1 2815 S: Content-Transfer-Encoding: 7bit 2816 S: 2817 S: BEGIN:VCALENDAR 2818 S: VERSION:2.1 2819 S: METHOD:RESPONSE 2820 S: TARGET:cap://cal.example.com/opaqueid103 2821 S: CMDID:xyz12346 2822 S: RESPONSE-CODE:2.0 2824 Mansour/Dawson/Royer 52 Expires February 2000 2825 Taler/Hill 2826 S: BEGIN:VEVENT 2827 S: UID:0034848098038888989443 2828 S: SUMMARY:meeting 2829 S: DTEND:19990714T233000Z 2830 S: DTSTART:19990714T223000Z 2831 S: END:VEVENT 2832 S: END:VCALENDAR 2833 S: 2834 S: ----FEE3790DC7E35189CA67CE2C 2835 S: Content-type:text/calendar; Method=RESPONSE; 2836 S: Optinfo=VERSION:2.1 2837 S: Content-Transfer-Encoding: 7bit 2838 S: 2839 S: BEGIN:VCALENDAR 2840 S: VERSION:2.1 2841 S: METHOD:RESPONSE 2842 S: TARGET:cap://cal.example.com/opaqueid101 2843 S: CMDID:xyz12346 2844 S: RESPONSE-CODE:4.1 ; access denied 2845 S: END:VCALENDAR 2846 S: 2847 S: ----FEE3790DC7E35189CA67CE2C 2848 S: . 2850 10.2.3 Timeouts 2851 In this example bill@example.com attempts to read a calendar but the 2852 latency time he supplies is not sufficient for the server to complete 2853 the command. 2855 C: SENDDATA 3 2856 C: Content-type:text/calendar; Method=READ; Component=VQUERY 2857 C: 2858 C: BEGIN:VCALENDAR 2859 C: VERSION:2.1 2860 C: METHOD:READ 2861 C: CMDID:xyz12346 2862 C: TARGET:cap://cal.example.com/opaqueid101 2863 C: TARGET:opaqueid103 2864 C: BEGIN:VQUERY 2865 C: QUERY:SELECT (DTSTART,DTEND,SUMMARY,UID); 2866 C: FROM VEVENT; 2867 C: WHERE (DTEND >= 19990714T080000Z AND 2868 C: DTSTART <= 19990715T080000Z); 2869 C: ORDERBY (DTSTART ASC, DTEND, UID, SUMMARY) 2870 C: END:VQUERY 2871 C: END:VCALENDAR 2872 C: . 2873 S: 7.0 ; timeout 2874 S: . 2876 If Bill wants to continue and give the server more time he would issue a 2877 CONTINUE command: 2879 C: CONTINUE 10 2881 Mansour/Dawson/Royer 53 Expires February 2000 2882 Taler/Hill 2883 If Bill wants to abort the command and not wait any further he would 2884 issue an ABORT command: 2886 C: ABORT 2887 S: 2.0 2888 S: . 2890 10.2.4 Using the Calendar Parent, Children Properties 2892 10.2.5 An example that depends on VEVENT.DTSTART and VALARM.DTSTART 2894 11. Implementation Issues 2895 1. What are the minimum component properties set required to create a 2896 new VEVENT, VTODO and VJOURNAL?. PROPOSAL: DTSTART, SUMMARY and UID. 2898 2. What is the state of all undefined properties? PROPOSAL: Not defined. 2899 So a query will not return them, if they are selected. 2901 12. Properties 2902 [Editors Note: These extensions/changes to iCalendar need to be 2903 reformatted to conform to the IANA registration process defined in 2904 section 7 of [RFC2445].] 2906 12.1 Calendar Store Properties 2907 Read 2908 Name Only Description 2909 ------------- ---- --------------------------------------------------- 2910 DEFAULT-VCARS N The default VCARs for newly created toplevel 2911 calendars 2913 MAXDATE Y The date/time in the future beyond which 2914 the server cannot represent. 2916 MINDATE Y The date/time in the past prior to which 2917 the server cannot represent. 2919 TIME Y Current server time. This is returned as a 2920 localtime and TZID 2922 [Editors Note: Should there be something here about how the server 2923 handles RRULES and EXRULES? For example, can/MUST the server unzip 2924 RRULES/EXRULES? Does it even support RRULES? Can it deal with unbounded 2925 RRULES?] 2927 12.2 Calendar Properties 2929 Read 2930 Name Only Description 2931 ------------- ---- -------------------------------------------------- 2932 CHARSET N the default charset for localized strings in this 2933 calendar 2935 CHILDREN Y the sub-calendars belonging to this calendar. 2937 Mansour/Dawson/Royer 54 Expires February 2000 2938 Taler/Hill 2939 CREATED Y the timestamp of the calendar's create date 2941 LANGUAGE N the default language for localizable strings in 2942 this calendar 2944 LAST-MODIFIED N the timestamp when the properties of the calendar 2945 were last updated. 2947 NAME N the display name for this calendar. It is 2948 a localizable string. 2950 OWNERS N a multi instanced property indicating the 2951 calendar owner. 2953 PARENT N maintained by a CAP server. 2955 PATH Y ?? human readable path of name. ?? 2956 [editors note: I think this is going to be 2957 really problematic. Can we do away with 2958 this? Or perhaps make it optional? ] 2960 RELATIVECALID N a unique name for the calendar. It is made 2961 up of 7 bit ASCII characters. 2963 SCHEDULABLE- N the preferred time range for scheduling 2964 HOURS events on this calendar. 2966 TOMBSTONE N a marker indicating that this calendar has been 2967 Deleted. 2969 TZID N the id of the timezone associated with this 2970 calendar 2972 LAST-MODIFIED-BY Y UPN of the person or process that 2973 last modified the calendar properties. 2975 13. Security Considerations 2976 For the mandatory SASL mechanism that CAP specifies, the mechanism 2977 support is: 2979 MUST authentication 2980 MUST authorization 2981 MAY impersonation 2983 The security issue: 2985 +---------+ +----------+ 2986 CUA1 ------ | CS1 |--------CAP----------| CS2 |-----CUA2 2987 | calF | | calA | 2988 +---------+ +----------+ 2990 UserListX is not an owner of calF 2992 Mansour/Dawson/Royer 55 Expires February 2000 2993 Taler/Hill 2994 UserListX has been given ACTONBEHALF of rights to calF by an owner 2995 of calF, UserY 2996 UserX authenticates to CS1 as UserX 2997 UserX wants to update the attendee status of an event on calA 2998 An owner of calA has granted access to UserY to update an event 2999 they have been invited to 3000 How do we grant UserX access to do this? 3002 [Editors Note: This needs further work and examples.] 3004 14. Changes to iCalendar 3005 [Editors Note: These extensions/changes to iCalendar need to be 3006 reformatted to conform to the IANA registration process defined in 3007 section 7 of [RFC2445].] 3009 14.1 RIGHTS Value Type 3011 Value Name: RIGHTS 3013 Purpose: This value type is used to identify properties whose value is a 3014 calendar access rights. 3016 Formal Definition: The value type is defined by the following notation: 3018 rights = [princ] (policy / carref / cardef) CRLF 3020 princ = "UPN" "=" (text / all / "OWNER" / "NONOWNER") 3022 policy = ";" "POLICY" "=" policyname 3024 policyname = "READBUSYTIMEINFO" / "ACTONBEHALFOF" / 3025 "REQUESTONLY" 3026 / "UPDATEPARTSTATUS" / "OWNER" / iana-name 3028 carref = ";" "CARREF" "=" text *("," text) 3030 cardef = action object 3032 action = ";" "ACTION" "=" act-type *("," act-type) 3034 act-type = ("CREATE" / "MODIFY" / "DELETE" / "READ" / all) 3036 object = ";" "OBJECT" "=" (csprop *("," csprop) [propvalue]) 3037 / (calprop *("," calprop) [propvalue]) 3038 / (component *("," component)) [compvalue] 3039 / (compprop *("," compprop) [propvalue]) 3040 / (compparam *("," compparam) [paramvalue]) 3042 csprop = csprop2 / all / iana-name 3044 csprop2 = 3046 propvalue = propvalue2 / all / iana-name 3048 Mansour/Dawson/Royer 56 Expires February 2000 3049 Taler/Hill 3050 propvalue2 = 3052 calprop = calprop2 / all / iana-name 3054 calprop2 = 3057 component = component2 / all / iana-name 3059 component2 = 3062 compprop = compprop2 / all / iana-name 3064 compprop2 = 3067 compparam = compparm2 / all / iana-name 3069 compparm2 = 3072 compvalue = ";" "VALUE" "=" ((component2 *("," component2)) 3073 / all / iana-name) 3075 paramvalue = paramvalue2 / all / iana-name 3077 paramvalue2 = 3079 all = "ALL" 3081 iana-name = 3083 Description: The value type is a structured value consisting of a list 3084 of one or more access control rights rule parts. Each rule part is 3085 defined by a "NAME=VALUE" pair. The rule parts are separated from each 3086 other by the SEMICOLON character (US-ASCII decimal 59). The rule parts 3087 are not ordered in any particular sequence, unless otherwise specified 3088 by the ABNF. Individual rule parts MUST only be specified once. 3090 The UPN rule part specifies the authenticated calendar user that the 3091 calendar access rights applies to. The value of this rule part is either 3092 a quoted text specifying a UPN or an unquoted text specifying a keyword 3093 enumerating a standard authenticated user type. If the value is the 3094 keyword is ALL, then the rule applies to all authenticated calendar 3095 users (i.e., all UPNs). If the value is the keyword OWNER, then the rule 3096 applies to any of the owners of the calendar store or calendar. If the 3097 value is the keyword NONOWNER, then the rule applies to a UPN that is 3098 not the owner of the calendar store or calendar. If this rule part is 3099 not specified in the value, then the calendar access rights do not apply 3100 to any UPN. In this case, the calendar access rights can be defined for 3101 reference by another instance of a calendar access rights. For example, 3102 a complex set of calendar access rights can be defined once and 3104 Mansour/Dawson/Royer 57 Expires February 2000 3105 Taler/Hill 3106 referenced many times in the rights specified for individual calendar 3107 users. 3109 The POLICY rule part specifies a standard calendar access policy. 3110 Calendar access policies are individual sets of well-defined calendar 3111 access rights that can be referenced by their policy name. 3113 NOTE: Possible calendar access policy that may be standardized by CAP 3114 include: 3116 READBUSYTIMEINFO - Specifies rights for reading busy time data. 3118 ACTONBEHALFOF - Specifies rights for any CAP function taken on 3119 PUBLIC or PRIVATE calendar components. However, no CAP function 3120 can be taken on CONFIDENTIAL classified calendar components. 3122 REQUESTONLY - Specifies rights for creating new event invitations, 3123 to-do assignments and journal entries. 3125 UPDATEPARTSTATUS - Specifies rights for modifying ones own 3126 participation status. 3128 OWNER - Specifies the same rights given to the owner of the 3129 calendar store or calendar. 3131 The CARREF rule part specifies a reference to a particular "VCAR" 3132 calendar component. The text is matched to a CARID property value within 3133 a "VCAR" calendar component. This allows for a particular set of 3134 calendar access rights to be defined once and referenced multiple times. 3135 The "VCAR" identifier specified by this rule part is unique to the 3136 calendar store. 3138 The ACTION rule part defines one or more CAP actions that are allowed 3139 for the UPN. The valid values are CREATE, COPY, DELETE, MODIFY, MOVE, 3140 READ, corresponding to the calendar commands; PUBLISH, REQUEST, REPLY, 3141 ADD, CANCEL, REFRESH, COUNTER, DECLINECOUNTER, corresponding to the 3142 scheduling commands; and ALL, meaning all of calendaring commands and 3143 scheduling commands. Multiple ACTION enumerations can be specified as a 3144 COMMA character (US-ASCII decimal 44) separated list of ACTION 3145 enumerated values. The text ALL is the same as specifying the enumerated 3146 values "CREATE, MODIFY, DELETE, READ". 3148 The OBJECT rule part defines the calendar store property, calendar 3149 property, calendar component, component property, or parameter that the 3150 ACTION is restricted to. Multiple OBJECT enumerations can be specified 3151 as a COMMA character (US-ASCII decimal 44) separated list of OBJECT 3152 enumerated values. The value ALL specifies any and all valid objects. 3154 The VALUE rule part specifies the restricted values for the OBJECT rule 3155 part. Multiple VALUE strings can be specified as a COMMA character (US- 3156 ASCII decimal 44) separated list of VALUE strings. The text ALL 3157 specifies any and all valid values. If an OBJECT rule part is specified 3158 but no corresponding VALUE rule part is specified, then the rule applies 3159 to any and all valid values of the specified OBJECT(s). 3161 Mansour/Dawson/Royer 58 Expires February 2000 3162 Taler/Hill 3163 Example: The following is a rule which specifies access rights for "foo" 3164 calendar user to read busy time values: 3166 UPN="foo@host.com";ACTION=READ;OBJECT=DTSTART,DTEND 3168 14.2 VCAR Calendar Component 3170 Component Name: "VCAR" 3172 Purpose: Provide a grouping of calendar access rights. 3174 Format Definition: A "VCAR" calendar component is defined by the 3175 following notation: 3177 aclc = "BEGIN" ":" "VCAR" CRLF 3178 carprop 3179 "END" ":" "VCAR" CRLF 3181 carprop = carid 1*(grant / deny) 3183 Description: A "VCAR" calendar component is a grouping of calendar 3184 access rights component properties. 3186 The "CARID" property specifies the local identifier for the "VCAR" 3187 calendar component. The "GRANT" property specifies calendar access 3188 rights granted to an UPN. The "DENY" property specifies calendar access 3189 rights denied from an UPN. 3191 Example: In the following example, the UPN "foo@host.com" has read 3192 access to the "DTSTART" and "DTEND" calendar properties. No other access 3193 is specified: 3195 BEGIN:VCAR 3196 CARID:"View Start and End Times" 3197 GRANT:UPN="foo@host.com";ACTION="READ";OBJECT=DTSTART,DTEND 3198 END:VEVENT 3200 In this example, all UPNs are given read access to "DTSTART" and 3201 "DTEND". "All CUs" is specified by the UPN value "ALL". Note that this 3202 enumerated UPN value is not in quotes.: 3204 BEGIN:VCAR 3205 CARID:"View Start and End Times 2" 3206 GRANT:UPN=ALL;ACTION=READ;OBJECT=DTSTART,DTEND 3207 END:VCAR 3209 In this example, rights are specified for all UPNs to read components 3210 classified as PUBLIC: 3212 BEGIN:VCAR 3213 CARID:"View PUBLIC Start and End Times" 3215 Mansour/Dawson/Royer 59 Expires February 2000 3216 Taler/Hill 3217 GRANT:UPN=ALL;ACTION=READ;OBJECT=DTSTART;DTEND 3218 DENY:UPN=ALL;ACTION=READ;OBJECT=CLASS;VALUE=PUBLIC, 3219 CONFIDENTIAL 3220 END:VCAR 3222 In this example, rights are specified for all UPNs to read or modify 3223 existing components classified as PUBLIC: 3225 BEGIN:VCAR 3226 CARID:"Read and Modify PUBLIC Calendar Entries" 3227 GRANT:UPN=ALL;ACTION=READ,MODIFY;OBJECT=ALL 3228 DENY:UPN=ALL;ACTION=READ,MODIFY;OBJECT=CLASS;VALUE=PRIVATE, 3229 CONFIDENTIAL 3230 END:VCAR 3232 In this example, rights are given to a standard calendar access right 3233 policy of "viewing" (i.e., READ) busy time information: 3235 BEGIN:VCAR 3236 CARID:"View Busy Time Information" 3237 GRANT:UPN=ALL;POLICY=READBUSYTIMEINFO 3238 END:VCAR 3240 In this example, full calendar access rights are given to the OWNER and 3241 a hypothetical administrator is given access rights to specify calendar 3242 access rights. If no other rights are specified, only these two UPNs can 3243 specify calendar access rights: 3245 BEGIN:VCAR 3246 CARID:"Only OWNER or ADMIN Settable CARs" 3247 GRANT:UPN=OWNER;ACTION=ALL;OBJECT=ALL 3248 GRANT:UPN="cal-admin@host.com";ACTION=ALL; 3249 OBJECT=VCAR,CARID,GRANT,DENY 3250 END:VCAR 3252 In this example, rights to create, read, modify or delete calendar 3253 access rights are denied to all UPNs. This example would disable 3254 providing different access rights to the calendar store or calendar. 3255 This calendar access rights should not be specified, as they the ability 3256 to change calendar access; even for the owner or administrator: 3258 BEGIN:VCAR 3259 CARID:"No CAR At All" 3260 DENY:UPN=ALL;OBJECT=VCAR,CARID,GRANT,DENY 3262 14.3 GRANT Component Property 3264 Property Name: GRANT 3266 Purpose: This property specifies those access rights granted to a UPN. 3268 Value Type: RIGHTS 3270 Mansour/Dawson/Royer 60 Expires February 2000 3271 Taler/Hill 3272 Property Parameters: Only non-standard property parameters can be 3273 specified on this property. 3275 Conformance: This property can only be specified in "VCAR" calendar 3276 component. 3278 Description: This property is used to grant calendar access rights to a 3279 UPN. 3281 Format Definition: The property is defined by the following notation: 3283 grant = "GRANT" rightsparam ":" rights CRLF 3284 rightparam = *(";" xparam) 3286 Example: In the following example, a hypothetical "guest@host.com" UPN 3287 is granted rights to view busy time information. These rights are 3288 specified by referencing a standard calendar access rights policy, by 3289 name: 3291 GRANT:UPN="guest@host.com";POLICY="READBUSYTIMEINFO" 3293 14.4 DENY Component Property 3295 Property Name: DENY 3297 Purpose: This property specifies those access rights denied from a UPN. 3299 Value Type: RIGHTS 3301 Property Parameters: Only non-standard property parameters can be 3302 specified on this property. 3304 Conformance: This property can only be specified in "VCAR" calendar 3305 component. 3307 Description: This property is used to deny calendar access rights to a 3308 UPN. 3310 Format Definition: The property is defined by the following notation: 3312 DENY = "DENY" rightsparam ":" rights CRLF 3313 rightsparam = *(";" xparam) 3315 Example: In the following example, any UPN who is not the owner is 3316 denied rights to create, modify or delete entries: 3318 DENY:UPN=NONOWNER;ACTION=CREATE,MODIFY,DELETE;OBJECT=ALL 3320 14.5 VCAR Identifier Component Property 3322 Property Name: CARID 3324 Mansour/Dawson/Royer 61 Expires February 2000 3325 Taler/Hill 3326 Purpose: This property specifies the identifier for a "VCAR" calendar 3327 component. 3329 Value Type: TEXT 3331 Property Parameters: Non-standard property parameters can be specified 3332 on this property. 3334 Conformance: This property can be specified in "VCAR" calendar 3335 component. 3337 Description: This property permits previously defined sets of calendar 3338 access rights to be specified with a reference. This capability 3339 facilitates repetitively specifying calendar access rights. 3341 Format Definition: The property is defined by the following notation: 3343 CARID = "CARID" textparam ":" text CRLF 3345 Example: The following is an example of this property: 3347 CARID:"Restrict Guests From Creating ALARMs On Events" 3349 14.6 REQUEST-STATUS property 3351 This description is a revision of the REQUEST-STATUS property for 3352 VCALENDAR version 2.1. 3354 rstatus = "REQUEST-STATUS" rstatparam ":" 3355 statcode [";" statdesc [";" extdata]] 3357 rstatparam = *( 3358 ; the following is optional, 3359 ; but MUST NOT occur more than once 3360 (";" languageparm) / 3362 ; the following is optional, 3363 ; and MAY occur more than once 3365 (";" xparam) 3367 ) 3369 statcode = 1*DIGIT *("." 1*DIGIT) 3370 ;Hierarchical, numeric return status code 3372 statdesc = text 3373 ;An optional textual status description, content is 3374 ;decided by the implementor. May be empty. 3376 extdata = text 3377 ;Textual exception data. For example, the offending property 3379 Mansour/Dawson/Royer 62 Expires February 2000 3380 Taler/Hill 3381 ;name and value or complete property line. 3383 Example: The following are some possible examples of this property. The 3384 COMMA and SEMICOLON separator characters in the property value are 3385 BACKSLASH character escaped because they appear in a text value. 3387 REQUEST-STATUS:2.0;Success 3389 REQUEST-STATUS:2.0;Success despite braindead LDAP implementation 3391 REQUEST-STATUS:3.1;Invalid property value;DTSTART:96-Apr-01 3393 REQUEST-STATUS:2.8; Success\, repeating event ignored. Scheduled 3394 as a single event.;RRULE:FREQ=WEEKLY\;INTERVAL=2 3396 REQUEST-STATUS:4.1;Event conflict. Date/time is busy. 3398 REQUEST-STATUS:3.7;Invalid calendar user;ATTENDEE: 3399 MAILTO:jsmith@host.com 3401 REQUEST-STATUS:3.7;;ATTENDEE:MAILTO:jsmith@host.com 3403 REQUEST-STATUS:10.4;Help! That really shouldn't have happened. 3405 15. CAP Entities Registration 3406 This section provides the process for registration of new or modified 3407 CAP entities. 3409 15.1 Registration of New and Modified CAP Entities 3410 New CAP entities are registered by the publication of an IETF Request 3411 for Comment (RFC). Changes to a CAP entity are registered by the 3412 publication of a revision of the RFC defining the method. 3414 15.2 Registration of New Entities 3415 This section defines procedures by which new entities (i.e., components, 3416 properties, parameters, enumerated values or restriction tables) for a 3417 CAP entity can be registered with the IANA. 3419 Non-standard, experimental entities can be used by bilateral agreement, 3420 provided the associated properties names follow the "X-" convention. 3421 Such non-standard entities are non-IANA entities and need not be 3422 registered using this process. 3424 The procedures defined here are designed to allow public comment and 3425 review of new CAP entities, while posing only a small impediment to the 3426 definition of new properties. 3428 Registration of a new CAP entity is accomplished by the following steps. 3430 15.2.1 Define the Entity 3431 A CAP entity is defined by completing the following template. 3433 To: ietf-calendar@imc.org 3435 Mansour/Dawson/Royer 63 Expires February 2000 3436 Taler/Hill 3437 Subject: Registration of CAP entity XXX 3438 Entity name: 3439 Entity purpose: 3440 Description: 3441 CAP terminology changes: 3442 CAP data model changes: 3443 CAP system model changes: 3444 Conformance considerations: 3445 Format definition: 3446 Examples: 3448 The meaning of each field in the template is as follows. 3450 Entity name: The name of the entity. 3452 Entity purpose: The purpose of the entity (e.g., Extends the CAP command 3453 set to poll for notifications, etc.). Give a short but clear 3454 description. 3456 Description: Any special notes about the entity, how it is to be used, 3457 etc. 3459 CAP terminology changes: Any change or additions to the existing CAP 3460 terminology needs to be specified. 3462 CAP data model changes: Any of the valid property parameters for the 3463 property needs to be specified. 3465 CAP system model changes: 3467 Conformance: A clear summary of how and where this CAP entity extension 3468 MUST, MAY, SHOULD or can be used. Any changes or impact to the existing 3469 conformance definition for CAP should be explained. The impact to 3470 implmentations conforming to the existing CAP specification should be 3471 clearly described. 3473 Format definition: The ABNF for each element of the CAP entity needs to 3474 be specified. 3476 Examples: One or more examples of instances of the CAP entity and each 3477 of its usage scenarios needs to be specified. 3479 15.2.2 Post the entity definition 3480 The entity description MUST be posted to the new entity discussion list, 3481 ietf-calendar@imc.org. 3483 15.2.3 Allow a comment period 3484 Discussion on the new entity MUST be allowed to take place on the list 3485 for a minimum of two weeks. Consensus MUST be reached on the property 3486 before proceeding to the next step. 3488 15.2.4 Submit the entity for approval 3489 Once the two-week comment period has elapsed, and the proposer is 3490 convinced consensus has been reached on the entity, the registration 3492 Mansour/Dawson/Royer 64 Expires February 2000 3493 Taler/Hill 3494 application should be submitted to the Method Reviewer for approval. The 3495 Method Reviewer is appointed by the Application Area Directors and can 3496 either accept or reject the entity registration. An accepted 3497 registration should be passed on by the Method Reviewer to the IANA for 3498 inclusion in the official IANA method registry. The registration can be 3499 rejected for any of the following reasons. 1) Insufficient comment 3500 period; 2) Consensus not reached; 3) Technical deficiencies raised on 3501 the list or elsewhere have not been addressed. The Method Reviewer's 3502 decision to reject an entity can be appealed by the proposer to the 3503 IESG, or the objections raised can be addressed by the proposer and the 3504 entity resubmitted. 3506 [Ed note: John Stracke to review any updates] 3508 15.3 Property Change Control 3509 Existing CAP entities can be changed using the same process by which 3510 they were registered. 3512 1. 3513 Define the change 3514 2. 3515 Post the change 3516 3. 3517 Allow a comment period 3518 4. 3519 Submit the entity for approval 3521 Note that the original author or any other interested party can propose 3522 a change to an existing CAP entity, but that such changes should only be 3523 proposed when there are serious omissions or errors in the published 3524 memo. The Method Reviewer can object to a change if it is not backward 3525 compatible, but is not required to do so. 3527 CAP entity definitions can never be deleted from the IANA registry, but 3528 entities which are no longer believed to be useful can be declared 3529 OBSOLETE by adding this text to their "Entity purpose" field. 3531 16. IANA Considerations 3533 This memo defines IANA registered extensions to the attributes defined 3534 by iCalendar, as defined in [RFC2445], and iTIP, as defined in 3535 [RFC2426]. 3537 IANA registration proposals for iCalendar and iTIP are to be emailed to 3538 the registration agent for the "text/calendar" MIME content-type, 3539 using the format defined in section 7 of 3540 [RFC2445]. 3542 17. Acknowledgments 3543 The following have individuals were major contributors in the drafting 3544 and discussion of this memo: 3546 Mario Bonin, Andre Courtemanche, Dave Crocker, Pat Egen, Gilles Fortin, 3547 Alex Hoppman, Bruce Kahn, Lisa Lippert, David Madeo, Bob Mahoney, Pete 3548 O'Leary, Richard Shusterman, Tony Small, John Stracke. 3550 Mansour/Dawson/Royer 65 Expires February 2000 3551 Taler/Hill 3552 18. Bibliography 3553 [RFC1521] N. Borenstein and N. Freed, "MIME (Multipurpose Internet Mail 3554 Extensions) Part One: Mechanisms for Internet Draft UTF-825 July 1996 3555 Specifying and Describing the Format of Internet Message Bodies", RFC 3556 1521, Bellcore, Innosoft, September 1993. 3558 [TLS] Dierks, Allen, "The TLS Protocol", RFC 2246, January 1999 3560 [RFC2396] Berners-Lee, Fielding, Masinter, "Uniform Resource Identifiers 3561 (URI): Generic Syntax", RFC 2396, August 1998. 3563 [RFC2445] Dawson, Stenerson, "Internet Calendaring and Scheduling Core 3564 Object Specification (iCalendar)", RFC 2445, November 1998 3566 [RFC2446] Silverberg, Mansour, Dawson, Hopson, "iCalendar Transport- 3567 Independent Interoperability Protocol (iTIP)", RFC 2446, November 1998 3569 [RFC2447] Dawson, Mansour, Silverberg, "iCalendar Message-Based 3570 Interoperability Protocol (iMIP)", RFC 2445, November 1998 3572 [SQL] "Database Language _ SQL", ANSI/ISO/IEC 9075: 1992, aka ANSI 3573 X3.135-1992, aka FiPS PUB 127-2 3575 [SQLCOM] ANSI/ISO/IEC 9075:1992/TC-1-1995, Technical corrigendum 1 to 3576 ISO/IEC 9075: 1992, also adopted as Amendment 1 to ANSI X3.135.1992 3578 [UNICODE] The Unicode Consortium, "The Unicode Standard --Worldwide 3579 Character Encoding -- Version 1.0", Addison-Wesley, Volume 1, 1991, 3580 Volume 2, 1992. UTF-8 is described in Unicode Technical Report #4. 3582 [US-ASCII] Coded Character Set--7-bit American Standard Code for 3583 Information Interchange, ANSI X3.4-1986. 3585 19. Author's Address 3586 The following address information is provided in a vCard v3.0, the RFC 3587 2426 electronic business card format. 3589 BEGIN:VCARD 3590 VERSION:3.0 3591 N:Dawson;Frank 3592 FN:Frank Dawson 3593 ORG:Lotus Development Corporation 3594 ADR;TYPE=WORK,POSTAL,PARCEL:;;6544 Battleford Drive;Raleigh;NC; 3595 27613-3502;US 3596 TEL;TYPE=PREF,WORK,MSG:+1-617-693-8728 3597 TEL;TYPE=WORK,MSG:+1-919-676-9515 3598 TEL;TYPE=WORK,FAX:+1-919-676-9515 3599 EMAIL;TYPE=INTERNET,PREF:Frank_Dawson@Lotus.com 3600 EMAIL;TYPE=INTERNET:fdawson@earthlink.net 3601 URL;TYPE=X-HOME:http://home.earthlink.net/~fdawson 3602 END:VCARD 3604 BEGIN:VCARD 3605 VERSION:3.0 3607 Mansour/Dawson/Royer 66 Expires February 2000 3608 Taler/Hill 3609 N:Mansour;Steve 3610 FN:Steve Mansour 3611 ORG:Netscape 3612 ADR;TYPE=WORK,POSTAL,PARCEL:;;501 E Middlfield Road;Mountain 3613 View;CA;94043;US 3614 TEL;WORK;MSG:+1-650-937-2378 3615 TEL;WORK;FAX:+1-650-937-2103 3616 EMAIL;INTERNET:sman@netscape.com 3617 END:VCARD 3619 BEGIN:VCARD 3620 VERSION:3.0 3621 FN:Doug Royer 3622 N:Royer;Doug 3623 ORG:Sun Microsystems 3624 ADR;TYPE=WORK,POSTAL,PARCEL:MS MPK17-105;;901 San Antonio Road; 3625 Palo Alto;CA;94303-4900 3626 TEL;TYPE=WORK,VOICE:650-786-7599 3627 TEL;TYPE=FAX:650-786-7994 3628 EMAIL;TYPE=INTERNET:doug.royer@sun.com 3629 END:VCARD 3631 BEGIN:VCARD 3632 VERSION:3.0 3633 FN:Alexander Taler 3634 N:Taler;Alexander 3635 ORG:CS&T 3636 ADR;TYPE=WORK,POSTAL,PARCEL:;;3333 Graham Boulevard;Montreal;QC; 3637 H3R 3L5;Canada 3638 TEL;TYPE=WORK,VOICE:514-733-8500 3639 TEL;TYPE=FAX:514-733-8878 3640 EMAIL;TYPE=INTERNET:alext@cst.ca 3641 END:VCARD 3643 20. Full Copyright Statement 3644 "Copyright (C) The Internet Society (1999). All Rights Reserved. 3645 This document and translations of it may be copied and furnished to 3646 others, and derivative works that comment on or otherwise explain it or 3647 assist in its implmentation may be prepared, copied, published and 3648 distributed, in whole or in part, without restriction of any kind, 3649 provided that the above copyright notice and this paragraph are included 3650 on all such copies and derivative works. However, this document itself 3651 may not be modified in any way, such as by removing the copyright notice 3652 or references to the Internet Society or other Internet organizations, 3653 except as needed for the purpose of developing Internet standards in 3654 which case the procedures for copyrights defined in the Internet 3655 Standards process MUST be followed, or as required to translate it into 3656 languages other than English. 3658 The limited permissions granted above are perpetual and will not be 3659 revoked by the Internet Society or its successors or assigns. 3660 This document and the information contained herein is provided on an "AS 3661 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 3663 Mansour/Dawson/Royer 67 Expires February 2000 3664 Taler/Hill 3665 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 3666 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 3667 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 3668 FITNESS FOR A PARTICULAR PURPOSE. 3670 Mansour/Dawson/Royer 68 Expires February 2000 3671 Taler/Hill