Internet Engineering Task Force (IETF) C. Daboo Request for Comments: 7986 Apple Inc. Updates: 5545 October 2016 Category: Standards Track ISSN: 2070-1721
New Properties for iCalendar
Abstract
This document defines a set of new properties for iCalendar data and extends the use of some existing properties to the entire iCalendar object.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7986.
Copyright Notice
Copyright (c) 2016 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 (http://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 Standards Track [Page 1]
RFC 7986 iCalendar Property Extensions October 2016
The iCalendar [RFC5545] data format is used to represent calendar data and is used with the iCalendar Transport-Independent Interoperability Protocol (iTIP) [RFC5546] to handle scheduling operations between calendar users. iCalendar is in widespread use, and in accordance with provisions in that specification, extension elements have been added by various vendors to the data format in order to support and enhance capabilities. This specification collects a number of these ad hoc extensions and uses the new IANA registry capability defined in [RFC5545] to register standard variants with clearly defined definitions and semantics. In addition, some new elements are introduced for features that vendors have recently been requesting.
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 [RFC2119].
The notation used in this memo is the ABNF notation of [RFC5234] as used by iCalendar [RFC5545]. Any syntax elements shown below that are not explicitly defined in this specification come from iCalendar [RFC5545].
iCalendar defines properties that can have different value types indicated by a "VALUE" parameter. The definition of a property specifies a "default" value type that is assumed to be used when no "VALUE" parameter is present. However, this poses a problem to the iCalendar parser/generator software that does not know about the default values for new properties. For example, if a new property "FOO" were defined with a default value type of URI and a URI value with a comma was used, an iCalendar generator not aware of this fact would likely treat the property value as "TEXT" and apply backslash escaping to the comma in the value, effectively making it an invalid URI value.
To avoid this problem, this specification recommends that all properties not defined in [RFC5545] always include a "VALUE" parameter if the type is other than "TEXT". That is, in the example above, the "FOO" property would have a "VALUE=URI" parameter. This allows iCalendar parser/generator software to track the correct types of unknown properties.
Daboo Standards Track [Page 3]
RFC 7986 iCalendar Property Extensions October 2016
New properties defined in this specification use the term "no default" in the "Value Type" definition to indicate that the "VALUE" parameter has to be included.
This section details changes to the syntax defined in iCalendar [RFC5545]. New elements are defined in subsequent sections.
calprops =/ *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; uid / last-mod / url / refresh / source / color ; ; The following are OPTIONAL, ; and MAY occur more than once. ; name / description / categories / image ; )
eventprop =/ *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; color / ; ; The following are OPTIONAL, ; and MAY occur more than once. ; conference / image ; )
todoprop =/ *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; color / ; ; The following are OPTIONAL, ; and MAY occur more than once.
Daboo Standards Track [Page 4]
RFC 7986 iCalendar Property Extensions October 2016
; conference / image ; )
jourprop =/ *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; color / ; ; The following are OPTIONAL, ; and MAY occur more than once. ; image ; )
Purpose: This property specifies the name of the calendar.
Value Type: TEXT
Property Parameters: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance: This property can be specified multiple times in an iCalendar object. However, each property MUST represent the name of the calendar in a different language.
Description: This property is used to specify a name of the iCalendar object that can be used by calendar user agents when presenting the calendar data to a user. Whilst a calendar only has a single name, multiple language variants can be specified by including this property multiple times with different "LANGUAGE" parameter values on each.
Daboo Standards Track [Page 5]
RFC 7986 iCalendar Property Extensions October 2016
Format Definition: This property is defined by the following notation:
name = "NAME" nameparam ":" text CRLF
nameparam = *( ; ; The following are OPTIONAL, ; but MUST NOT occur more than once. ; (";" altrepparam) / (";" languageparam) / ; ; The following is OPTIONAL, ; and MAY occur more than once. ; (";" other-param) ; )
Example: The following is an example of this property:
This specification modifies the definition of the "DESCRIPTION" property to allow it to be defined in an iCalendar object. The following additions are made to the definition of this property, originally specified in Section 3.8.1.5 of [RFC5545].
Purpose: This property specifies the description of the calendar.
Conformance: This property can be specified multiple times in an iCalendar object. However, each property MUST represent the description of the calendar in a different language.
Description: This property is used to specify a lengthy textual description of the iCalendar object that can be used by calendar user agents when describing the nature of the calendar data to a user. Whilst a calendar only has a single description, multiple language variants can be specified by including this property multiple times with different "LANGUAGE" parameter values on each.
Daboo Standards Track [Page 6]
RFC 7986 iCalendar Property Extensions October 2016
This specification modifies the definition of the "UID" property to allow it to be defined in an iCalendar object. The following additions are made to the definition of this property, originally specified in Section 3.8.4.7 of [RFC5545].
Purpose: This property specifies the persistent, globally unique identifier for the iCalendar object. This can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the "LAST-MODIFIED" property also specified on the "VCALENDAR" object to identify the most recent version of a calendar.
Conformance: This property can be specified once in an iCalendar object.
The description of the "UID" property in [RFC5545] contains some recommendations on how the value can be constructed. In particular, it suggests use of host names, IP addresses, and domain names to construct the value. However, this is no longer considered good practice, particularly from a security and privacy standpoint, since use of such values can leak key information about a calendar user or their client and network environment. This specification updates [RFC5545] by stating that "UID" values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate "UID" values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of [RFC4122].
The following is an example of such a property value:
UID:5FC53010-1267-4F8E-BC28-1D7AE55A7C99
Additionally, if calendar user agents choose to use other forms of opaque identifiers for the "UID" value, they MUST have a length less than 255 octets and MUST conform to the "iana-token" ABNF syntax defined in Section 3.1 of [RFC5545].
Daboo Standards Track [Page 7]
RFC 7986 iCalendar Property Extensions October 2016
This specification modifies the definition of the "LAST-MODIFIED" property to allow it to be defined in an iCalendar object. The following additions are made to the definition of this property, originally specified in Section 3.8.7.3 of [RFC5545].
Purpose: This property specifies the date and time that the information associated with the calendar was last revised.
Conformance: This property can be specified once in an iCalendar object.
This specification modifies the definition of the "URL" property to allow it to be defined in an iCalendar object. The following additions are made to the definition of this property, originally specified in Section 3.8.4.6 of [RFC5545].
Purpose: This property may be used to convey a location where a more dynamic rendition of the calendar information can be found.
Conformance: This property can be specified once in an iCalendar object.
This specification modifies the definition of the "CATEGORIES" property to allow it to be defined in an iCalendar object. The following additions are made to the definition of this property, originally specified in Section 3.8.1.2 of [RFC5545].
Purpose: This property defines the categories for an entire calendar.
Conformance: This property can be specified multiple times in an iCalendar object.
Description: When multiple properties are present, the set of categories that apply to the iCalendar object are the union of all the categories listed in each property value.
Daboo Standards Track [Page 8]
RFC 7986 iCalendar Property Extensions October 2016
Purpose: This property specifies a suggested minimum interval for polling for changes of the calendar data from the original source of that data.
Value Type: DURATION -- no default
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property can be specified once in an iCalendar object.
Description: This property specifies a positive duration that gives a suggested minimum polling interval for checking for updates to the calendar data. The value of this property SHOULD be used by calendar user agents to limit the polling interval for calendar data updates to the minimum interval specified.
Format Definition: This property is defined by the following notation:
refresh = "REFRESH-INTERVAL" refreshparam ":" dur-value CRLF ;consisting of a positive duration of time.
refreshparam = *( ; ; The following is REQUIRED, ; but MUST NOT occur more than once. ; (";" "VALUE" "=" "DURATION") / ; ; The following is OPTIONAL, ; and MAY occur more than once. ; (";" other-param) ; )
Example: The following is an example of this property:
REFRESH-INTERVAL;VALUE=DURATION:P1W
Daboo Standards Track [Page 9]
RFC 7986 iCalendar Property Extensions October 2016
Purpose: This property identifies a URI where calendar data can be refreshed from.
Value Type: URI -- no default
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property can be specified once in an iCalendar object.
Description: This property identifies a location where a client can retrieve updated data for the calendar. Clients SHOULD honor any specified "REFRESH-INTERVAL" value when periodically retrieving data. Note that this property differs from the "URL" property in that "URL" is meant to provide an alternative representation of the calendar data rather than the original location of the data.
Format Definition: This property is defined by the following notation:
source = "SOURCE" sourceparam ":" uri CRLF
sourceparam = *(";" other-param)
Example: The following is an example of this property:
Purpose: This property specifies a color used for displaying the calendar, event, todo, or journal data.
Value Type: TEXT
Property Parameters: IANA and non-standard property parameters can be specified on this property.
Conformance: This property can be specified once in an iCalendar object or in "VEVENT", "VTODO", or "VJOURNAL" calendar components.
Daboo Standards Track [Page 10]
RFC 7986 iCalendar Property Extensions October 2016
Description: This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the "background" color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of [W3C.REC-css3-color-20110607].
Format Definition: This property is defined by the following notation:
color = "COLOR" colorparam ":" text CRLF ; Value is CSS3 color name
colorparam = *(";" other-param)
Example: The following is an example of this property:
Purpose: This property specifies an image associated with the calendar or a calendar component.
Value Type: URI or BINARY -- no default. The value MUST be data with a media type of "image" or refer to such data.
Property Parameters: IANA, non-standard, display, inline encoding, and value data type property parameters can be specified on this property. The format type parameter can be specified on this property and is RECOMMENDED for inline binary-encoded content information.
Conformance: This property can be specified multiple times in an iCalendar object or in "VEVENT", "VTODO", or "VJOURNAL" calendar components.
Description: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The "DISPLAY" parameter is used to indicate the intended display mode for the image. The "ALTREP" parameter,
Daboo Standards Track [Page 11]
RFC 7986 iCalendar Property Extensions October 2016
defined in [RFC5545], can be used to provide a "clickable" image where the URI in the parameter value can be "launched" by a click on the image in the calendar user agent.
Format Definition: This property is defined by the following notation:
imageparam = *( ; ; The following is OPTIONAL for a URI value, ; RECOMMENDED for a BINARY value, ; and MUST NOT occur more than once. ; (";" fmttypeparam) / ; ; The following are OPTIONAL, ; and MUST NOT occur more than once. ; (";" altrepparam) / (";" displayparam) / ; ; The following is OPTIONAL, ; and MAY occur more than once. ; (";" other-param) ; )
Example: The following is an example of this property:
Purpose: This property specifies information for accessing a conferencing system.
Value Type: URI -- no default.
Property Parameters: IANA, non-standard, feature, and label property parameters can be specified on this property.
Conformance: This property can be specified multiple times in a "VEVENT" or "VTODO" calendar component.
Description: This property specifies information for accessing a conferencing system for attendees of a meeting or task. This might be for a telephone-based conference number dial-in with access codes included (such as a tel: URI [RFC3966] or a sip: or sips: URI [RFC3261]), for a web-based video chat (such as an http: or https: URI [RFC7230]), or for an instant messaging group chat room (such as an xmpp: URI [RFC5122]). If a specific URI for a conferencing system is not available, a data: URI [RFC2397] containing a text description can be used.
A conference system can be a bidirectional communication channel or a uni-directional "broadcast feed".
The "FEATURE" property parameter is used to describe the key capabilities of the conference system to allow a client to choose the ones that give the required level of interaction from a set of multiple properties.
The "LABEL" property parameter is used to convey additional details on the use of the URI. For example, the URIs or access codes for the moderator and attendee of a teleconference system could be different, and the "LABEL" property parameter could be used to "tag" each "CONFERENCE" property to indicate which is which.
The "LANGUAGE" property parameter can be used to specify the language used for text values used with this property (as per Section 3.2.10 of [RFC5545]).
Daboo Standards Track [Page 13]
RFC 7986 iCalendar Property Extensions October 2016
Format Definition: This property is defined by the following notation:
conference = "CONFERENCE" confparam ":" uri CRLF
confparam = *( ; ; The following is REQUIRED, ; but MUST NOT occur more than once. ; (";" "VALUE" "=" "URI") / ; ; The following are OPTIONAL, ; and MUST NOT occur more than once. ; (";" featureparam) / (";" labelparam) / (";" languageparam ) / ; ; The following is OPTIONAL, ; and MAY occur more than once. ; (";" other-param) ; )
Example: The following are examples of this property:
displayval = ("BADGE" / ; image inline with the title of the ; event "GRAPHIC" / ; a full image replacement for the event ; itself "FULLSIZE" / ; an image that is used to enhance the ; event "THUMBNAIL" / ; a smaller variant of "FULLSIZE" to be ; used when space for the image is ; constrained x-name / ; Experimental type iana-token) ; Other IANA-registered type ; ; Default is BADGE
Description: This property parameter MAY be specified on "IMAGE" properties. In the absence of this parameter, the default value "BADGE" MUST be used. The value determines how a client ought to present an image supplied in iCalendar data to the user.
Values for this parameter are registered with IANA as per Section 9.3.1. New values can be added to this registry following the procedure outlined in Section 8.2.1 of [RFC5545].
Servers and clients MUST handle x-name and iana-token values they don't recognize by not displaying any image at all.
Purpose: To specify an email address that is used to identify or contact an organizer or attendee.
Format Definition: This property parameter is defined by the following notation:
emailparam = "EMAIL" "=" param-value
Daboo Standards Track [Page 15]
RFC 7986 iCalendar Property Extensions October 2016
Description: This property parameter MAY be specified on "ORGANIZER" or "ATTENDEE" properties. This property can be used in situations where the calendar user address value of the "ORGANIZER" and "ATTENDEE" properties is not likely to be an identifier that recipients of scheduling messages could use to match the calendar user with, for example, an address book entry. The value of this property is an email address that can easily be matched by recipients. Recipients can also use this value as an alternative means of contacting the calendar user via email. If a recipient's calendar user agent allows the recipient to save contact information based on the "ORGANIZER" or "ATTENDEE" properties, those calendar user agents SHOULD use any "EMAIL" property parameter value for the email address of the contact over any mailto: calendar user address specified as the value of the property. Calendar user agents SHOULD NOT include an "EMAIL" property parameter when its value matches the calendar user address specified as the value of the property.
Purpose: To specify a feature or features of a conference or broadcast system.
Format Definition: This property parameter is defined by the following notation:
featureparam = "FEATURE" "=" featuretext *("," featuretext) featuretext = ("AUDIO" / ; Audio capability "CHAT" / ; Chat or instant messaging "FEED" / ; Blog or Atom feed "MODERATOR" / ; Moderator dial-in code "PHONE" / ; Phone conference "SCREEN" / ; Screen sharing "VIDEO" / ; Video capability x-name / ; Experimental type iana-token) ; Other IANA-registered type
Daboo Standards Track [Page 16]
RFC 7986 iCalendar Property Extensions October 2016
Description: This property parameter MAY be specified on the "CONFERENCE" property. Multiple values can be specified. The "MODERATOR" value is used to indicate that the property value is specific to the owner/initiator of the conference and contains a URI that "activates" the system (e.g., a "moderator" access code for a phone conference system that is different from the "regular" access code).
Format Definition: This property parameter is defined by the following notation:
labelparam = "LABEL" "=" param-value
Description: This property parameter MAY be specified on the "CONFERENCE" property. It is anticipated that other extensions to iCalendar will reuse this property parameter on new properties that they define. As a result, clients MUST expect to find this property parameter present on many different properties. It provides a human-readable label that can be presented to calendar users to allow them to discriminate between properties that might be similar or provide additional information for properties that are not self-describing. The "LANGUAGE" property parameter can be used to specify the language of the text in the parameter value (as per Section 3.2.10 of [RFC5545]).
Several of the new properties or parameters defined by this specification allow reference to "external" URIs. Care MUST be taken when accessing data at external URIs as malicious content could be present. Clients SHOULD ensure that suitable permission is granted by calendar users before such URIs are dereferenced.
The "REFRESH-INTERVAL" property could be used by an attacker to make a client carry out rapid requests to the server hosting the calendar by specifying a very short duration (e.g., one second). This could lead to resource consumption on the client or server and to denial- of-service attacks against the server. Clients MUST ensure that they throttle requests to the server to a reasonable rate. In most cases, updating a public calendar once per day would suffice. If the "REFRESH-INTERVAL" is any less than that, clients SHOULD warn the calendar user and allow them to override it with a longer value.
The "CONFERENCE" property can include a "FEATURE" property parameter with a "MODERATOR" value. In some cases, the access code used by the owner/initiator of a conference might be private to an individual, and clients and servers MUST ensure that such properties are not sent to attendees of a scheduled component.
Both the "COLOR" and "IMAGE" properties are likely to be used by calendar users to express their own personal view of the calendar data. In addition, these properties could be used by attackers to produce a confusing display in a calendar user agent. When such properties are encountered in calendar data that has come from other calendar users (e.g., via a scheduling message, "public" calendar subscription, etc.), it is advisable for the client to give the receiving calendar user the option to remove (or adjust) these properties as the data is imported into their calendar system.
This specification changes the recommendations on how "UID" property values are constructed to minimize leaking any information that might be security sensitive.
Security considerations in [RFC5545] and [RFC5546] MUST also be adhered to.
Several of the new properties or parameters defined by this specification allow reference to "external" URIs. Access to those URIs could be tracked, leading to loss of privacy. Clients SHOULD ensure that suitable permission is granted by calendar users before such URIs are dereferenced. In particular, calendar publishers
Daboo Standards Track [Page 18]
RFC 7986 iCalendar Property Extensions October 2016
wishing to help protect the privacy of their subscribers MUST use HTTP with Transport Layer Security [RFC7230] ("https:" URIs instead of "http:" URIs) for access to calendar data or ancillary data such as images.
In general, for their own privacy protection, users have to rely on the privacy policies of any conferencing system being accessed via the "CONFERENCE" property. It is entirely possible for such systems to uniquely identify and log the activity and participation (or lack thereof) of calendar users in the conference. Calendar user agents SHOULD track which conferencing systems are used and warn users the first time a new one is about to be used. This is particularly important if the client automatically "dials in" to the conference when the event start time occurs.
By giving different calendar users different values for the "REFRESH- INTERVAL" property, it is possible for a publisher of calendar data to uniquely identify each refresh from each calendar users' clients and thereby track user activity and IP address over time. To address this, clients SHOULD add or subtract some random amount of time from the published "REFRESH-INTERVAL" value when doing actual refreshes.
This specification changes the recommendations on how "UID" property values are constructed to minimize leaking any information that might be privacy sensitive.
Privacy considerations in [RFC5545] and [RFC5546] MUST also be adhered to.
This document defines the following new iCalendar properties. IANA has registered the new properties in the "Properties" registry defined in Section 8.3.2 of [RFC5545]. IANA has also added a reference to this document where the properties originally defined in RFC 5545 have been updated by this document.
Daboo Standards Track [Page 19]
RFC 7986 iCalendar Property Extensions October 2016
This document defines the following new iCalendar property parameters. IANA has registered these in the "Parameters" registry defined in Section 8.3.3 of [RFC5545].
IANA has created two new registries for iCalendar elements: the "Display Types" registry and the "Feature Types" registry. Additional codes MAY be used, provided the process and template described in Sections 8.2.1 and 8.2.6 of [RFC5545] are used to register them.
Daboo Standards Track [Page 20]
RFC 7986 iCalendar Property Extensions October 2016
[W3C.REC-css3-color-20110607] Celik, T., Lilley, C., and D. Baron, "CSS Color Module Level 3", World Wide Web Consortium Recommendation REC-css3-color-20110607, June 2011, <https://www.w3.org/TR/2011/REC-css3-color-20110607>.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, DOI 10.17487/RFC3261, June 2002, <http://www.rfc-editor.org/info/rfc3261>.
[RFC5122] Saint-Andre, P., "Internationalized Resource Identifiers (IRIs) and Uniform Resource Identifiers (URIs) for the Extensible Messaging and Presence Protocol (XMPP)", RFC 5122, DOI 10.17487/RFC5122, February 2008, <http://www.rfc-editor.org/info/rfc5122>.
RFC 7986 iCalendar Property Extensions October 2016
Acknowledgments
Thanks to the following individuals for feedback: Bernard Desruisseaux, Mike Douglass, Lucia Fedorova, Ken Murchison, Arnaud Quillaud, and Dave Thewlis.
This specification came about via discussions at the Calendaring and Scheduling Consortium.
Author's Address
Cyrus Daboo Apple Inc. 1 Infinite Loop Cupertino, CA 95014 United States of America