Internet DRAFT - draft-daboo-valarm-extensions
draft-daboo-valarm-extensions
Network Working Group C. Daboo
Internet-Draft Apple
Updates: 5545 (if approved) K. Murchison, Ed.
Intended status: Standards Track FastMail
Expires: September 6, 2019 March 5, 2019
VALARM Extensions for iCalendar
draft-daboo-valarm-extensions-05
Abstract
This document defines a set of extensions to the iCalendar VALARM
component to enhance use of alarms and improve interoperability
between clients and servers.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 6, 2019.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Daboo & Murchison Expires September 6, 2019 [Page 1]
Internet-Draft VALARM Extensions March 2019
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Extensible syntax for VALARM . . . . . . . . . . . . . . . . 3
4. Alarm Unique Identifier . . . . . . . . . . . . . . . . . . . 5
5. Alarm Acknowledgement . . . . . . . . . . . . . . . . . . . . 5
5.1. Acknowledged Property . . . . . . . . . . . . . . . . . . 6
6. Snoozing Alarms . . . . . . . . . . . . . . . . . . . . . . . 7
7. Alarm Proximity Trigger . . . . . . . . . . . . . . . . . . . 8
7.1. Proximity Property . . . . . . . . . . . . . . . . . . . 9
7.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. Security Considerations . . . . . . . . . . . . . . . . . . . 10
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
9.1. Property Registrations . . . . . . . . . . . . . . . . . 10
9.2. Proximity Value Registry . . . . . . . . . . . . . . . . 11
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
11.1. Normative References . . . . . . . . . . . . . . . . . . 11
11.2. Informative References . . . . . . . . . . . . . . . . . 12
11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Appendix A. Change History (To be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Introduction
The iCalendar [RFC5545] specification defines a set of components
used to describe calendar data. One of those is the "VALARM"
component which appears as a sub-component of "VEVENT" and "VTODO"
components. The "VALARM" component is used to specify a reminder for
an event or task. Different alarm actions are possible, as are
different ways to specify how the alarm is triggered.
As iCalendar has become more widely used and as client-server
protocols such as CalDAV [RFC4791] have become more popular, several
issues with "VALARM" components have arisen. Most of these relate to
the need to extend the existing "VALARM" component with new
properties and behaviors to allow clients and servers to accomplish
specific tasks in an interoperable manner. For example, clients
typically need a way to specify that an alarm has been dismissed by a
calendar user, or has been "snoozed" by a set amount of time. To
date, this has been done through the use of custom "X-" properties
specific to each client implementation, leading to poor
interoperability.
This specification defines a set of extensions to "VALARM" components
to cover common requirements for alarms not currently addressed in
Daboo & Murchison Expires September 6, 2019 [Page 2]
Internet-Draft VALARM Extensions March 2019
iCalendar. Each extension is defined in a separate section below.
For the most part, each extension can be supported independently of
the others, though in some cases one extension will require another.
In addition, this specification describes mechanisms by which clients
can interoperably implement common features such as "snoozing".
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
When XML element types in the namespaces "DAV:" and
"urn:ietf:params:xml:ns:caldav" are referenced in this document
outside of the context of an XML fragment, the string "DAV:" and
"CALDAV:" will be prefixed to the element type names respectively.
3. Extensible syntax for VALARM
Section 3.6.6 of [RFC5545] defines the syntax for "VALARM" components
and properties within them. However, as written, it is hard to
extend this by adding, e.g., a new property common to all types of
alarm. Since many of the extensions defined in this document need to
extend the base syntax, an alternative form for the base syntax is
defined here, with the goal of simplifying specification of the
extensions.
A "VALARM" calendar component is re-defined by the following
notation:
alarmcext = "BEGIN" ":" "VALARM" CRLF
alarmprop
"END" ":" "VALARM" CRLF
alarmprop = *(
; the following are REQUIRED,
; but MUST NOT occur more than once
action / trigger /
; one set of action properties MUST be
; present and MUST match the action specified
; in the ACTION property
actionprops /
Daboo & Murchison Expires September 6, 2019 [Page 3]
Internet-Draft VALARM Extensions March 2019
; the following is OPTIONAL,
; and MAY occur more than once
x-prop / iana-prop
)
actionprops = audiopropext / disppropext / emailpropext
audiopropext = *(
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat /
; the following is OPTIONAL,
; but MUST NOT occur more than once
attach
)
disppropext = *(
; the following are REQUIRED,
; but MUST NOT occur more than once
description /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
emailpropext = *(
; the following are all REQUIRED,
; but MUST NOT occur more than once
description / summary /
; the following is REQUIRED,
; and MAY occur more than once
Daboo & Murchison Expires September 6, 2019 [Page 4]
Internet-Draft VALARM Extensions March 2019
attendee /
; 'duration' and 'repeat' are both OPTIONAL,
; and MUST NOT occur more than once each,
; but if one occurs, so MUST the other
duration / repeat
)
4. Alarm Unique Identifier
This extension adds a "UID" property to "VALARM" components to allow
a unique identifier to specified. The value of this property can
then be used to refer uniquely to the "VALARM" component.
The "UID" property defined here follows the definition in
Section 3.8.4.7 of [RFC5545] with the security and privacy updates in
Section 5.3 of [RFC7986]. In particular it MUST be a globally unique
identifier that does not contain any security- or privacy-sensitive
information.
The "VALARM" component defined in Section 3 is extended here as:
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
uid
)
5. Alarm Acknowledgement
There is currently no way for a "VALARM" component to indicate
whether it has been triggered and acknowledged. With the advent of a
standard client/server protocol for calendaring and scheduling data
([RFC4791]) it is quite possible for an event with an alarm to exist
on multiple clients in addition to the server. If each of those is
responsible for performing the action when an alarm triggers, then
multiple "alerts" are generated by different devices. In such a
situation, a calendar user would like to be able to "dismiss" the
alarm on one device and have it automatically dismissed on the others
too.
Daboo & Murchison Expires September 6, 2019 [Page 5]
Internet-Draft VALARM Extensions March 2019
Also, with recurring events that have alarms, it is important to know
when the last alarm in the recurring set was acknowledged, so that
the client can determine whether past alarms have been missed.
To address these needs, this specification adds an "ACKNOWLEDGED"
property to "VALARM" components to indicate when the alarm was last
sent or acknowledged. This is defined by the syntax below.
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
acknowledged
)
5.1. Acknowledged Property
Property Name: ACKNOWLEDGED
Purpose: This property specifies the UTC date and time at which the
corresponding alarm was last sent or acknowledged.
Value Type: DATE-TIME
Property Parameters: IANA and non-standard property parameters can
be specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Description: This property is used to specify when an alarm was last
sent or acknowledged. This allows clients to determine when a
pending alarm has been acknowledged by a calendar user so that any
alerts can be dismissed across multiple devices. It also allows
clients to track repeating alarms or alarms on recurring events or
to-dos to ensure that the right number of missed alarms can be
tracked.
Clients SHOULD set this property to the current date-time value in
UTC when a calendar user acknowledges a pending alarm. Certain
kinds of alarm may not provide feedback as to when the calendar
user sees them, for example email based alerts. For those kinds
of alarms, the client SHOULD set this property when the alarm is
triggered and the action successfully carried out.
Daboo & Murchison Expires September 6, 2019 [Page 6]
Internet-Draft VALARM Extensions March 2019
When an alarm is triggered on a client, clients can check to see
if an "ACKNOWLEDGED" property is present. If it is, and the value
of that property is greater than or equal to the computed trigger
time for the alarm, then the client SHOULD NOT trigger the alarm.
Similarly, if an alarm has been triggered and an "alert" presented
to a calendar user, clients can monitor the iCalendar data to
determine whether an "ACKNOWLEDGED" property is added or changed
in the alarm component. If the value of any "ACKNOWLEDGED"
property in the alarm changes and is greater than or equal to the
trigger time of the alarm, then clients SHOULD dismiss or cancel
any "alert" presented to the calendar user.
Format Definition: This property is defined by the following
notation:
acknowledged = "ACKNOWLEDGED" acknowledgedparam ":" datetime CRLF
acknowledgedparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
Example: The following is an example of this property:
ACKNOWLEDGED:20090604T084500Z
6. Snoozing Alarms
Users often want to "snooze" an alarm, and this specification defines
a standard approach to accomplish that.
To "snooze" an alarm, clients create a new "VALARM" component within
the parent component of the "VALARM" that was triggered and is being
"snoozed" (i.e., as a "sibling" component of the "VALARM" being
snoozed). The new "VALARM" MUST be set to trigger at the user's
chosen "snooze" interval after the original alarm triggered. Clients
SHOULD use an absolute "TRIGGER" property with a "DATE-TIME" value
specified in UTC.
When the "snooze" alarm is triggered and dismissed the client SHOULD
remove the corresponding "VALARM" component, or set the
"ACKNOWLEDGED" property (see Section 5.1). Alternatively, if the
"snooze" alarm is itself "snoozed", the client SHOULD remove the
Daboo & Murchison Expires September 6, 2019 [Page 7]
Internet-Draft VALARM Extensions March 2019
original "snooze" alarm and create a new one, with the appropriate
trigger time and relationship set.
7. Alarm Proximity Trigger
VALARMs are currently triggered when a specific date-time is reached.
It is also desirable to be able to trigger alarms based on location,
e.g. when arriving at or departing from a particular location.
This specification adds the following properties to "VALARM"
components to indicate when an alarm can be triggered based on
location.
"PROXIMITY" - indicates that a location based trigger is to be
used and which direction of motion is used for the trigger
"STRUCTURED-LOCATION" [I-D.ietf-calext-eventpub-extensions] - used
to indicate the actual location to trigger off, specified using a
geo: URI [RFC5870] which allows for two or three coordinate values
with an optional uncertainty
alarmprop /= *(
; the following is OPTIONAL,
; but MUST NOT occur more than once
proximity /
; the following is OPTIONAL,
; and MAY occur more than once, but only
; when a PROXIMITY property is also present
structured-location
)
Typically, when a "PROXIMITY" property is used there is no need to
specify a time-based trigger using the "TRIGGER" property. However,
since "TRIGGER" is defined as a required property for a "VALARM"
component, for backwards compatibility it has to be present, but
ignored. To indicate a "TRIGGER" that is to be ignored, clients
SHOULD use a value a long time in the past. A value of
"19760401T005545Z" has been commonly used for this purpose.
Daboo & Murchison Expires September 6, 2019 [Page 8]
Internet-Draft VALARM Extensions March 2019
7.1. Proximity Property
Property Name: PROXIMITY
Purpose: This property indicates that a location based trigger is
applied to an alarm.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can
be specified on this property.
Conformance: This property can be specified within "VALARM" calendar
components.
Description: This property is used to indicate that an alarm has a
location-based trigger. Its value identifies the direction of
motion used to trigger the alarm. One or more location values are
set using "STRUCTURED-LOCATION" properties.
When the property value is set to "ARRIVE", the alarm is triggered
when the calendar user agent arrives in the vicinity of any of the
specified locations. When set to "DEPART", the alarm is triggered
when the calendar user agent departs from the vicinity of any
specified locations.
When the property value is set to "CONNECT", the alarm is
triggered when the calendar user agent connects to a Bluetooth(R)
[BTcore]-enabled automobile. When set to "DISCONNECT", the alarm
is triggered when the calendar user agent disconnects from a
Bluetooth(R)-enabled automobile.
Format Definition: This property is defined by the following
notation:
proximity = "PROXIMITY" proximityparam ":" proximityvalue CRLF
proximityparam = *(
; the following is OPTIONAL,
; and MAY occur more than once
(";" other-param)
)
proximityvalue = "ARRIVE" / "DEPART" /
"CONNECT" / "DISCONNECT" / iana-token / x-name
Daboo & Murchison Expires September 6, 2019 [Page 9]
Internet-Draft VALARM Extensions March 2019
Example: The following is an example of this property:
PROXIMITY:ARRIVE
7.2. Example
The following example shows a "VALARM" component with a proximity
trigger set to trigger when the device running the calendar user
agent leaves the vicinity defined by the structured location
property. Note use of the "u=" parameter with the "geo" URI to
define the precision of the location determination.
BEGIN:VALARM
UID:77D80D14-906B-4257-963F-85B1E734DBB6
TRIGGER;VALUE=DATE-TIME:19760401T005545Z
ACTION:DISPLAY
DESCRIPTION:Remember to buy milk
TRIGGER;VALUE=DATE-TIME:19760401T005545Z
PROXIMITY:DEPART
STRUCTURED-LOCATION;VALUE=URI:geo:40.443,-79.945;u=10
END:VALARM
8. Security Considerations
VALARMs, if not monitored properly, can be used to "spam" users and/
or leak personal information. For instance, an unwanted audio or
display alert could be considered spam. Or an email alert could be
used to leak a user's location to a third party or to send
unsolicited email to multiple users. Therefore, CalDAV clients and
servers that accept iCalendar data from a third party (e.g. via iTIP
[RFC5546], a subscription feed, or a shared calendar) SHOULD remove
all VALARMs from the data prior to storing in their calendar system.
9. IANA Considerations
9.1. Property Registrations
This document defines the following new iCalendar properties to be
added to the registry defined in Section 8.2.3 of [RFC5545]:
+--------------+---------+----------------------+
| Property | Status | Reference |
+--------------+---------+----------------------+
| ACKNOWLEDGED | Current | RFCXXXX, Section 5.1 |
| PROXIMITY | Current | RFCXXXX, Section 7.1 |
+--------------+---------+----------------------+
Daboo & Murchison Expires September 6, 2019 [Page 10]
Internet-Draft VALARM Extensions March 2019
9.2. Proximity Value Registry
This document creates a new iCalendar registry for values of the
"PROXIMITY" property:
+------------+---------+----------------------+
| Value | Status | Reference |
+------------+---------+----------------------+
| ARRIVE | Current | RFCXXXX, Section 7.1 |
| DEPART | Current | RFCXXXX, Section 7.1 |
| CONNECT | Current | RFCXXXX, Section 7.1 |
| DISCONNECT | Current | RFCXXXX, Section 7.1 |
+------------+---------+----------------------+
10. Acknowledgments
This specification came about via discussions at the Calendaring and
Scheduling Consortium. Also, thanks to the following for providing
feedback: Bernard Desruisseaux, Mike Douglass, Jacob Farkas, Jeffrey
Harris, and Ciny Joy.
11. References
11.1. Normative References
[I-D.ietf-calext-eventpub-extensions]
Douglass, M., "Event Publishing Extensions to iCalendar",
draft-ietf-calext-eventpub-extensions-11 (work in
progress), February 2019.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
"Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
DOI 10.17487/RFC4791, March 2007,
<https://www.rfc-editor.org/info/rfc4791>.
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
Daboo & Murchison Expires September 6, 2019 [Page 11]
Internet-Draft VALARM Extensions March 2019
[RFC5870] Mayrhofer, A. and C. Spanring, "A Uniform Resource
Identifier for Geographic Locations ('geo' URI)",
RFC 5870, DOI 10.17487/RFC5870, June 2010,
<https://www.rfc-editor.org/info/rfc5870>.
[RFC7986] Daboo, C., "New Properties for iCalendar", RFC 7986,
DOI 10.17487/RFC7986, October 2016,
<https://www.rfc-editor.org/info/rfc7986>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
11.2. Informative References
[BTcore] Bluetooth Special Interest Group, "Bluetooth Core
Specification Version 5.0", December 2016,
<https://www.bluetooth.com/specifications/
bluetooth-core-specification>.
[RFC5546] Daboo, C., Ed., "iCalendar Transport-Independent
Interoperability Protocol (iTIP)", RFC 5546,
DOI 10.17487/RFC5546, December 2009,
<https://www.rfc-editor.org/info/rfc5546>.
11.3. URIs
[1] https://tools.ietf.org/html/bcp14
Appendix A. Change History (To be removed by RFC Editor before
publication)
Changes in -05:
1. Added Murchison as editor.
2. Updated keywords boilerplate.
3. Added reference to UID security/privacy recommendations.
4. Removed default alarms.
5. Removed ALARM-AGENT property.
6. Added text about using TRIGGER value in the past in addition to
ACTION:NONE to have a default alarm be ignored.
7. Removed text about related alarms.
Daboo & Murchison Expires September 6, 2019 [Page 12]
Internet-Draft VALARM Extensions March 2019
8. Removed URL alarm action.
9. Added reference to draft-ietf-calext-eventpub-extensions for
STRUCTURED-LOCATION.
10. Added CONNECT and DISCONNECT PROXIMITY property values.
11. Added Security Considerations.
12. Editorial fixes.
Changes in -04:
1. Changed "ID" to "AGENT-ID".
2. Add more text on using "ACKNOWLEDGED" property.
3. Add "RELATED-TO" as a valid property for VALARMs.
4. Add "SNOOZE" relationship type for use with VALARMs.
5. State that "TRIGGER" is typically ignored in proximity alarms.
6. Added "PROXIMITY" value registry.
7. Added a lot more detail on default alarms including new action
and property.
Changes in -03: none - resubmission of -02
Changes in -02:
1. Updated to 5545 reference.
2. Clarified use of absolute trigger in UTC in snooze alarms
3. Snooze alarms should be removed when completed
4. Removed status and replaced last-triggered by acknowledged
property
5. Added location-based trigger
6. IANA registry tables added
Changes in -01:
1. Removed DESCRIPTION as an allowed property in the URI alarm.
Daboo & Murchison Expires September 6, 2019 [Page 13]
Internet-Draft VALARM Extensions March 2019
2. Added statement about what to do when ALARM-AGENT is not present.
3. Allow multiple ALARM-AGENT properties to be present.
4. Removed SNOOZE-UNTIL - snoozing now accomplished by creating a
new VALARM.
5. Remove VALARM by reference section.
6. Added more detail to CalDAV default alarms.
Authors' Addresses
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
Email: cyrus@daboo.name
URI: http://www.apple.com/
Kenneth Murchison (editor)
FastMail US LLC
1429 Walnut St, Suite 1201
Philadephia, PA 19102
USA
Email: murch@fastmailteam.com
URI: http://www.fastmail.com/
Daboo & Murchison Expires September 6, 2019 [Page 14]