idnits 2.17.1 draft-daboo-valarm-extensions-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC5545, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack 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? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (Using the creation date from RFC5545, updated by this document, for RFC5378 checks: 2005-10-26) -- 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 (March 5, 2019) is 1872 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 545 == Unused Reference: 'BTcore' is defined on line 533, but no explicit reference was found in the text == Outdated reference: A later version (-19) exists of draft-ietf-calext-eventpub-extensions-11 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple 4 Updates: 5545 (if approved) K. Murchison, Ed. 5 Intended status: Standards Track FastMail 6 Expires: September 6, 2019 March 5, 2019 8 VALARM Extensions for iCalendar 9 draft-daboo-valarm-extensions-05 11 Abstract 13 This document defines a set of extensions to the iCalendar VALARM 14 component to enhance use of alarms and improve interoperability 15 between clients and servers. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on September 6, 2019. 34 Copyright Notice 36 Copyright (c) 2019 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 53 3. Extensible syntax for VALARM . . . . . . . . . . . . . . . . 3 54 4. Alarm Unique Identifier . . . . . . . . . . . . . . . . . . . 5 55 5. Alarm Acknowledgement . . . . . . . . . . . . . . . . . . . . 5 56 5.1. Acknowledged Property . . . . . . . . . . . . . . . . . . 6 57 6. Snoozing Alarms . . . . . . . . . . . . . . . . . . . . . . . 7 58 7. Alarm Proximity Trigger . . . . . . . . . . . . . . . . . . . 8 59 7.1. Proximity Property . . . . . . . . . . . . . . . . . . . 9 60 7.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 62 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 63 9.1. Property Registrations . . . . . . . . . . . . . . . . . 10 64 9.2. Proximity Value Registry . . . . . . . . . . . . . . . . 11 65 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 66 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 68 11.2. Informative References . . . . . . . . . . . . . . . . . 12 69 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 Appendix A. Change History (To be removed by RFC Editor before 71 publication) . . . . . . . . . . . . . . . . . . . . 12 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 74 1. Introduction 76 The iCalendar [RFC5545] specification defines a set of components 77 used to describe calendar data. One of those is the "VALARM" 78 component which appears as a sub-component of "VEVENT" and "VTODO" 79 components. The "VALARM" component is used to specify a reminder for 80 an event or task. Different alarm actions are possible, as are 81 different ways to specify how the alarm is triggered. 83 As iCalendar has become more widely used and as client-server 84 protocols such as CalDAV [RFC4791] have become more popular, several 85 issues with "VALARM" components have arisen. Most of these relate to 86 the need to extend the existing "VALARM" component with new 87 properties and behaviors to allow clients and servers to accomplish 88 specific tasks in an interoperable manner. For example, clients 89 typically need a way to specify that an alarm has been dismissed by a 90 calendar user, or has been "snoozed" by a set amount of time. To 91 date, this has been done through the use of custom "X-" properties 92 specific to each client implementation, leading to poor 93 interoperability. 95 This specification defines a set of extensions to "VALARM" components 96 to cover common requirements for alarms not currently addressed in 97 iCalendar. Each extension is defined in a separate section below. 98 For the most part, each extension can be supported independently of 99 the others, though in some cases one extension will require another. 100 In addition, this specification describes mechanisms by which clients 101 can interoperably implement common features such as "snoozing". 103 2. Conventions Used in This Document 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 When XML element types in the namespaces "DAV:" and 112 "urn:ietf:params:xml:ns:caldav" are referenced in this document 113 outside of the context of an XML fragment, the string "DAV:" and 114 "CALDAV:" will be prefixed to the element type names respectively. 116 3. Extensible syntax for VALARM 118 Section 3.6.6 of [RFC5545] defines the syntax for "VALARM" components 119 and properties within them. However, as written, it is hard to 120 extend this by adding, e.g., a new property common to all types of 121 alarm. Since many of the extensions defined in this document need to 122 extend the base syntax, an alternative form for the base syntax is 123 defined here, with the goal of simplifying specification of the 124 extensions. 126 A "VALARM" calendar component is re-defined by the following 127 notation: 129 alarmcext = "BEGIN" ":" "VALARM" CRLF 130 alarmprop 131 "END" ":" "VALARM" CRLF 133 alarmprop = *( 135 ; the following are REQUIRED, 136 ; but MUST NOT occur more than once 138 action / trigger / 140 ; one set of action properties MUST be 141 ; present and MUST match the action specified 142 ; in the ACTION property 144 actionprops / 145 ; the following is OPTIONAL, 146 ; and MAY occur more than once 148 x-prop / iana-prop 150 ) 152 actionprops = audiopropext / disppropext / emailpropext 154 audiopropext = *( 156 ; 'duration' and 'repeat' are both OPTIONAL, 157 ; and MUST NOT occur more than once each, 158 ; but if one occurs, so MUST the other 160 duration / repeat / 162 ; the following is OPTIONAL, 163 ; but MUST NOT occur more than once 165 attach 167 ) 169 disppropext = *( 171 ; the following are REQUIRED, 172 ; but MUST NOT occur more than once 174 description / 176 ; 'duration' and 'repeat' are both OPTIONAL, 177 ; and MUST NOT occur more than once each, 178 ; but if one occurs, so MUST the other 180 duration / repeat 182 ) 184 emailpropext = *( 186 ; the following are all REQUIRED, 187 ; but MUST NOT occur more than once 189 description / summary / 191 ; the following is REQUIRED, 192 ; and MAY occur more than once 193 attendee / 195 ; 'duration' and 'repeat' are both OPTIONAL, 196 ; and MUST NOT occur more than once each, 197 ; but if one occurs, so MUST the other 199 duration / repeat 201 ) 203 4. Alarm Unique Identifier 205 This extension adds a "UID" property to "VALARM" components to allow 206 a unique identifier to specified. The value of this property can 207 then be used to refer uniquely to the "VALARM" component. 209 The "UID" property defined here follows the definition in 210 Section 3.8.4.7 of [RFC5545] with the security and privacy updates in 211 Section 5.3 of [RFC7986]. In particular it MUST be a globally unique 212 identifier that does not contain any security- or privacy-sensitive 213 information. 215 The "VALARM" component defined in Section 3 is extended here as: 217 alarmprop /= *( 219 ; the following is OPTIONAL, 220 ; but MUST NOT occur more than once 222 uid 224 ) 226 5. Alarm Acknowledgement 228 There is currently no way for a "VALARM" component to indicate 229 whether it has been triggered and acknowledged. With the advent of a 230 standard client/server protocol for calendaring and scheduling data 231 ([RFC4791]) it is quite possible for an event with an alarm to exist 232 on multiple clients in addition to the server. If each of those is 233 responsible for performing the action when an alarm triggers, then 234 multiple "alerts" are generated by different devices. In such a 235 situation, a calendar user would like to be able to "dismiss" the 236 alarm on one device and have it automatically dismissed on the others 237 too. 239 Also, with recurring events that have alarms, it is important to know 240 when the last alarm in the recurring set was acknowledged, so that 241 the client can determine whether past alarms have been missed. 243 To address these needs, this specification adds an "ACKNOWLEDGED" 244 property to "VALARM" components to indicate when the alarm was last 245 sent or acknowledged. This is defined by the syntax below. 247 alarmprop /= *( 249 ; the following is OPTIONAL, 250 ; but MUST NOT occur more than once 252 acknowledged 254 ) 256 5.1. Acknowledged Property 258 Property Name: ACKNOWLEDGED 260 Purpose: This property specifies the UTC date and time at which the 261 corresponding alarm was last sent or acknowledged. 263 Value Type: DATE-TIME 265 Property Parameters: IANA and non-standard property parameters can 266 be specified on this property. 268 Conformance: This property can be specified within "VALARM" calendar 269 components. 271 Description: This property is used to specify when an alarm was last 272 sent or acknowledged. This allows clients to determine when a 273 pending alarm has been acknowledged by a calendar user so that any 274 alerts can be dismissed across multiple devices. It also allows 275 clients to track repeating alarms or alarms on recurring events or 276 to-dos to ensure that the right number of missed alarms can be 277 tracked. 279 Clients SHOULD set this property to the current date-time value in 280 UTC when a calendar user acknowledges a pending alarm. Certain 281 kinds of alarm may not provide feedback as to when the calendar 282 user sees them, for example email based alerts. For those kinds 283 of alarms, the client SHOULD set this property when the alarm is 284 triggered and the action successfully carried out. 286 When an alarm is triggered on a client, clients can check to see 287 if an "ACKNOWLEDGED" property is present. If it is, and the value 288 of that property is greater than or equal to the computed trigger 289 time for the alarm, then the client SHOULD NOT trigger the alarm. 290 Similarly, if an alarm has been triggered and an "alert" presented 291 to a calendar user, clients can monitor the iCalendar data to 292 determine whether an "ACKNOWLEDGED" property is added or changed 293 in the alarm component. If the value of any "ACKNOWLEDGED" 294 property in the alarm changes and is greater than or equal to the 295 trigger time of the alarm, then clients SHOULD dismiss or cancel 296 any "alert" presented to the calendar user. 298 Format Definition: This property is defined by the following 299 notation: 301 acknowledged = "ACKNOWLEDGED" acknowledgedparam ":" datetime CRLF 303 acknowledgedparam = *( 305 ; the following is OPTIONAL, 306 ; and MAY occur more than once 308 (";" other-param) 310 ) 312 Example: The following is an example of this property: 314 ACKNOWLEDGED:20090604T084500Z 316 6. Snoozing Alarms 318 Users often want to "snooze" an alarm, and this specification defines 319 a standard approach to accomplish that. 321 To "snooze" an alarm, clients create a new "VALARM" component within 322 the parent component of the "VALARM" that was triggered and is being 323 "snoozed" (i.e., as a "sibling" component of the "VALARM" being 324 snoozed). The new "VALARM" MUST be set to trigger at the user's 325 chosen "snooze" interval after the original alarm triggered. Clients 326 SHOULD use an absolute "TRIGGER" property with a "DATE-TIME" value 327 specified in UTC. 329 When the "snooze" alarm is triggered and dismissed the client SHOULD 330 remove the corresponding "VALARM" component, or set the 331 "ACKNOWLEDGED" property (see Section 5.1). Alternatively, if the 332 "snooze" alarm is itself "snoozed", the client SHOULD remove the 333 original "snooze" alarm and create a new one, with the appropriate 334 trigger time and relationship set. 336 7. Alarm Proximity Trigger 338 VALARMs are currently triggered when a specific date-time is reached. 339 It is also desirable to be able to trigger alarms based on location, 340 e.g. when arriving at or departing from a particular location. 342 This specification adds the following properties to "VALARM" 343 components to indicate when an alarm can be triggered based on 344 location. 346 "PROXIMITY" - indicates that a location based trigger is to be 347 used and which direction of motion is used for the trigger 349 "STRUCTURED-LOCATION" [I-D.ietf-calext-eventpub-extensions] - used 350 to indicate the actual location to trigger off, specified using a 351 geo: URI [RFC5870] which allows for two or three coordinate values 352 with an optional uncertainty 354 alarmprop /= *( 356 ; the following is OPTIONAL, 357 ; but MUST NOT occur more than once 359 proximity / 361 ; the following is OPTIONAL, 362 ; and MAY occur more than once, but only 363 ; when a PROXIMITY property is also present 365 structured-location 367 ) 369 Typically, when a "PROXIMITY" property is used there is no need to 370 specify a time-based trigger using the "TRIGGER" property. However, 371 since "TRIGGER" is defined as a required property for a "VALARM" 372 component, for backwards compatibility it has to be present, but 373 ignored. To indicate a "TRIGGER" that is to be ignored, clients 374 SHOULD use a value a long time in the past. A value of 375 "19760401T005545Z" has been commonly used for this purpose. 377 7.1. Proximity Property 379 Property Name: PROXIMITY 381 Purpose: This property indicates that a location based trigger is 382 applied to an alarm. 384 Value Type: TEXT 386 Property Parameters: IANA and non-standard property parameters can 387 be specified on this property. 389 Conformance: This property can be specified within "VALARM" calendar 390 components. 392 Description: This property is used to indicate that an alarm has a 393 location-based trigger. Its value identifies the direction of 394 motion used to trigger the alarm. One or more location values are 395 set using "STRUCTURED-LOCATION" properties. 397 When the property value is set to "ARRIVE", the alarm is triggered 398 when the calendar user agent arrives in the vicinity of any of the 399 specified locations. When set to "DEPART", the alarm is triggered 400 when the calendar user agent departs from the vicinity of any 401 specified locations. 403 When the property value is set to "CONNECT", the alarm is 404 triggered when the calendar user agent connects to a Bluetooth(R) 405 [BTcore]-enabled automobile. When set to "DISCONNECT", the alarm 406 is triggered when the calendar user agent disconnects from a 407 Bluetooth(R)-enabled automobile. 409 Format Definition: This property is defined by the following 410 notation: 412 proximity = "PROXIMITY" proximityparam ":" proximityvalue CRLF 414 proximityparam = *( 416 ; the following is OPTIONAL, 417 ; and MAY occur more than once 419 (";" other-param) 421 ) 423 proximityvalue = "ARRIVE" / "DEPART" / 424 "CONNECT" / "DISCONNECT" / iana-token / x-name 426 Example: The following is an example of this property: 428 PROXIMITY:ARRIVE 430 7.2. Example 432 The following example shows a "VALARM" component with a proximity 433 trigger set to trigger when the device running the calendar user 434 agent leaves the vicinity defined by the structured location 435 property. Note use of the "u=" parameter with the "geo" URI to 436 define the precision of the location determination. 438 BEGIN:VALARM 439 UID:77D80D14-906B-4257-963F-85B1E734DBB6 440 TRIGGER;VALUE=DATE-TIME:19760401T005545Z 441 ACTION:DISPLAY 442 DESCRIPTION:Remember to buy milk 443 TRIGGER;VALUE=DATE-TIME:19760401T005545Z 444 PROXIMITY:DEPART 445 STRUCTURED-LOCATION;VALUE=URI:geo:40.443,-79.945;u=10 446 END:VALARM 448 8. Security Considerations 450 VALARMs, if not monitored properly, can be used to "spam" users and/ 451 or leak personal information. For instance, an unwanted audio or 452 display alert could be considered spam. Or an email alert could be 453 used to leak a user's location to a third party or to send 454 unsolicited email to multiple users. Therefore, CalDAV clients and 455 servers that accept iCalendar data from a third party (e.g. via iTIP 456 [RFC5546], a subscription feed, or a shared calendar) SHOULD remove 457 all VALARMs from the data prior to storing in their calendar system. 459 9. IANA Considerations 461 9.1. Property Registrations 463 This document defines the following new iCalendar properties to be 464 added to the registry defined in Section 8.2.3 of [RFC5545]: 466 +--------------+---------+----------------------+ 467 | Property | Status | Reference | 468 +--------------+---------+----------------------+ 469 | ACKNOWLEDGED | Current | RFCXXXX, Section 5.1 | 470 | PROXIMITY | Current | RFCXXXX, Section 7.1 | 471 +--------------+---------+----------------------+ 473 9.2. Proximity Value Registry 475 This document creates a new iCalendar registry for values of the 476 "PROXIMITY" property: 478 +------------+---------+----------------------+ 479 | Value | Status | Reference | 480 +------------+---------+----------------------+ 481 | ARRIVE | Current | RFCXXXX, Section 7.1 | 482 | DEPART | Current | RFCXXXX, Section 7.1 | 483 | CONNECT | Current | RFCXXXX, Section 7.1 | 484 | DISCONNECT | Current | RFCXXXX, Section 7.1 | 485 +------------+---------+----------------------+ 487 10. Acknowledgments 489 This specification came about via discussions at the Calendaring and 490 Scheduling Consortium. Also, thanks to the following for providing 491 feedback: Bernard Desruisseaux, Mike Douglass, Jacob Farkas, Jeffrey 492 Harris, and Ciny Joy. 494 11. References 496 11.1. Normative References 498 [I-D.ietf-calext-eventpub-extensions] 499 Douglass, M., "Event Publishing Extensions to iCalendar", 500 draft-ietf-calext-eventpub-extensions-11 (work in 501 progress), February 2019. 503 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 504 Requirement Levels", BCP 14, RFC 2119, 505 DOI 10.17487/RFC2119, March 1997, 506 . 508 [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault, 509 "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791, 510 DOI 10.17487/RFC4791, March 2007, 511 . 513 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 514 Scheduling Core Object Specification (iCalendar)", 515 RFC 5545, DOI 10.17487/RFC5545, September 2009, 516 . 518 [RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource 519 Identifier for Geographic Locations ('geo' URI)", 520 RFC 5870, DOI 10.17487/RFC5870, June 2010, 521 . 523 [RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986, 524 DOI 10.17487/RFC7986, October 2016, 525 . 527 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 528 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 529 May 2017, . 531 11.2. Informative References 533 [BTcore] Bluetooth Special Interest Group, "Bluetooth Core 534 Specification Version 5.0", December 2016, 535 . 538 [RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent 539 Interoperability Protocol (iTIP)", RFC 5546, 540 DOI 10.17487/RFC5546, December 2009, 541 . 543 11.3. URIs 545 [1] https://tools.ietf.org/html/bcp14 547 Appendix A. Change History (To be removed by RFC Editor before 548 publication) 550 Changes in -05: 552 1. Added Murchison as editor. 554 2. Updated keywords boilerplate. 556 3. Added reference to UID security/privacy recommendations. 558 4. Removed default alarms. 560 5. Removed ALARM-AGENT property. 562 6. Added text about using TRIGGER value in the past in addition to 563 ACTION:NONE to have a default alarm be ignored. 565 7. Removed text about related alarms. 567 8. Removed URL alarm action. 569 9. Added reference to draft-ietf-calext-eventpub-extensions for 570 STRUCTURED-LOCATION. 572 10. Added CONNECT and DISCONNECT PROXIMITY property values. 574 11. Added Security Considerations. 576 12. Editorial fixes. 578 Changes in -04: 580 1. Changed "ID" to "AGENT-ID". 582 2. Add more text on using "ACKNOWLEDGED" property. 584 3. Add "RELATED-TO" as a valid property for VALARMs. 586 4. Add "SNOOZE" relationship type for use with VALARMs. 588 5. State that "TRIGGER" is typically ignored in proximity alarms. 590 6. Added "PROXIMITY" value registry. 592 7. Added a lot more detail on default alarms including new action 593 and property. 595 Changes in -03: none - resubmission of -02 597 Changes in -02: 599 1. Updated to 5545 reference. 601 2. Clarified use of absolute trigger in UTC in snooze alarms 603 3. Snooze alarms should be removed when completed 605 4. Removed status and replaced last-triggered by acknowledged 606 property 608 5. Added location-based trigger 610 6. IANA registry tables added 612 Changes in -01: 614 1. Removed DESCRIPTION as an allowed property in the URI alarm. 616 2. Added statement about what to do when ALARM-AGENT is not present. 618 3. Allow multiple ALARM-AGENT properties to be present. 620 4. Removed SNOOZE-UNTIL - snoozing now accomplished by creating a 621 new VALARM. 623 5. Remove VALARM by reference section. 625 6. Added more detail to CalDAV default alarms. 627 Authors' Addresses 629 Cyrus Daboo 630 Apple Inc. 631 1 Infinite Loop 632 Cupertino, CA 95014 633 USA 635 Email: cyrus@daboo.name 636 URI: http://www.apple.com/ 638 Kenneth Murchison (editor) 639 FastMail US LLC 640 1429 Walnut St, Suite 1201 641 Philadephia, PA 19102 642 USA 644 Email: murch@fastmailteam.com 645 URI: http://www.fastmail.com/