]> Internet Calendar Scheduling Protocol (iSchedule) Apple Inc.
1 Infinite Loop Cupertino CA 95014 USA cyrus@daboo.name http://www.apple.com/
Oracle Corporation
600 Blvd. de Maisonneuve West Suite 1900 Montreal QC H3A 3J2 CANADA bernard.desruisseaux@oracle.com http://www.oracle.com/
Applications calsched calsch caldav calendar calendaring calsify HTTP iCal iCalendar iMIP iTIP iRIP iSchedule scheduling text/calendar DKIM DomainKeys Identified Mail This document defines the Internet Calendar Scheduling Protocol (iSchedule), which is a binding from the iCalendar Transport-independent Interoperability Protocol (iTIP) to the Hypertext Transfer Protocol (HTTP) to enable interoperability between calendaring and scheduling systems over the Internet.
This binding document provides the transport specific information necessary to convey iCalendar Transport-independent Interoperability Protocol (iTIP) messages over the Hypertext Transfer Protocol (HTTP). The Internet Calendar Scheduling Protocol (iSchedule) enables interoperability between different calendaring and scheduling systems. Calendaring and scheduling systems that provide support for iSchedule allow their users to perform scheduling transactions such as schedule, reschedule, respond to scheduling request or cancel scheduled calendar components, as well as search for busy time information with users of other calendaring and scheduling systems on the Internet. iSchedule leverages the DomainKeys Identified Mail (DKIM) service to provide end-to-end domain-level authentication based on message content that is transparent to end users. Discussion of this Internet-Draft is taking place on the mailing list <https://www.ietf.org/mailman/listinfo/ischedule>.
The iCalendar Message-Based Interoperability Protocol (iMIP), has proven to be insufficient to allow users to seamlessly perform the same scheduling operations with users of other calendaring and scheduling systems on the Internet as with users of their own system. This section clarifies the motivations for a binding from the iCalendar Transport-independent Interoperability Protocol (iTIP) to a transport that allows synchronous end-to-end connectivity. A binding to an email-based transport is clearly inadequate to search for busy time information since users need and expect to get an immediate response. As such, some calendaring and scheduling systems allow users to publish their free busy information in a resource accessible to others on the Internet. In the absence of a standardized mechanism to locate the resource that provides the free busy information of a user, one thus needs to know the location of this resource in addition to the calendar user address of the users one wishes to schedule with. With an email-based transport, the transparent processing of incoming scheduling messages on the server is only possible when the calendaring and scheduling system is integrated with the email system. Commonly, the processing of incoming scheduling messages occurs on the client and requires user intervention, which yields the following consequences: The processing of incoming scheduling messages and the corresponding updates to the calendar only occur when the client is active. As a result, free busy information may be inaccurate (e.g., user still appears busy when the organizer actually rescheduled or canceled the meeting). Calendaring and scheduling systems generally restrain the number of updates sent to users to reduce the number of messages that will clutter their email inbox. As a result, attendees rarely obtain up to date participation status of other attendees. The client becomes responsible for verification of the authenticity and integrity of the scheduling message.
Implementers will need to be familiar with other documents that, along with this document, form a framework for Internet calendaring and scheduling standards. This document specifies a binding from iTIP to HTTP. iCalendar specifies a core specification of objects, data types, properties and property parameters; iTIP specifies an interoperability protocol for scheduling between different implementations. Furthermore, implementers will need to be familiar with the DomainKeys Identified Mail (DKIM) service defined in . An overview of DKIM can be found in . This document does not attempt to repeat the specification of concepts or definitions from these other documents. Where possible, references are made to the document that provides the specification of these concepts or definitions.
This specification reuses much of the same terminology as iCalendar, iTIP, HTTP, and DKIM. Additional terms used by this specification are: An iCalendar object conforming to the requirements of iTIP. The calendar user who is sending a scheduling message to one or more other calendar users. A calendar user to whom a scheduling message is being sent. The iSchedule service responsible for sending scheduling messages. The iSchedule service responsible for receiving scheduling messages.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in . The Augmented BNF (ABNF) syntax used by this document to describe protocol elements is defined in . Definitions of XML elements in this document use XML element type declarations (as found in XML Document Type Declarations), described in Section 3.2 of . The namespace "urn:ietf:params:xml:ns:ischedule" is reserved for the XML elements defined in this specification, or in other Standards Track IETF RFCs written to extend iSchedule. It MUST NOT be used for proprietary extensions. When XML element types in this namespace are referenced in this document outside of the context of an XML fragment, the string "IS:" will be prefixed to the element type names. Note that the XML declarations used in this document are incomplete, in that they do not include namespace information. Thus, the reader MUST NOT use these declarations as the only way to validate iSchedule XML element types.
The iSchedule design can be pictured as:
|===========|----------->|===========|-->| or | | User | | iSchedule | | iSchedule | | User | | Agent | | Sender | | Receiver | | Agent | +----------+ +-----------+ +-----------+ +----------+ | | <--------------------------> DKIM Signature/Verification ]]>
When an iSchedule Sender has a scheduling message to transmit, it determines the iSchedule Receivers to which to deliver the message and sends the appropriate iSchedule message. The iSchedule Receiver verifies the authenticity and content of the iSchedule message and delivers it to the Calendar Service. The means by which a Calendar Store or User Agent instructs a Calendar Service, acting as an iSchedule Sender, to transmit scheduling messages is outside the scope of this document. A Calendar Service could provide support for a standard calendar access protocol, such as CalDAV , or any other protocol, to allow a Calendar User Agent to perform scheduling operations with users of other Calendar Services. Likewise, the actual processing of scheduling messages received by a Calendar Service, acting as an iSchedule Receiver, is also outside the scope of this document. Some Calendar Service implementations may decide to process some or all received scheduling messages, while other implementations may decide to leave that work to Calendar User Agent implementations.
This section provides an overview of the various steps involved for iSchedule Senders and Receivers to transmit scheduling messages between Calendar Services. It references later sections describing the precise details of each step.
A Calendar Service will generate an iTIP scheduling message for transmission. It will additionally provide details of the Originator and Recipients. The Calendar Service will "submit" the scheduling message and details to the iSchedule Sender, through a process that is outside the scope of this document. The iSchedule Sender MUST verify the authenticity of the Originator and the Originator's authorization to send the scheduling message. In particular the "ORGANIZER" iCalendar property value MUST match the Originator calendar user address. The process by which this authentication and authorization is done is outside the scope of this document. For each Recipient, the iSchedule Sender will attempt to lookup a matching iSchedule Receiver to which the iSchedule message can be sent, following the rules in . After determining the iSchedule Receiver to use, the iSchedule Sender MUST check the capabilities of the iSchedule Receiver to ensure it will be able to accept the scheduling message that needs to be sent, as per . The iSchedule Sender MUST group together Recipients for whom the iSchedule Receiver is the same, so that a single scheduling message is sent for multiple Recipients, within the limits of the IS:max-recipients value specified in the iSchedule Receiver's capabilities. For each group of Recipients handled by the same iSchedule Receiver, the iSchedule Sender will construct an HTTP request, as per , with the body of the HTTP request containing the iSchedule message. Note, in the case of a "VFREEBUSY" iSchedule message, the iSchedule Sender MUST ensure that iCalendar "ATTENDEE" properties in the iSchedule message match one-for-one with the Recipients listed in the HTTP request header. After constructing the HTTP request, the iSchedule Sender MUST generate a DKIM signature for the request and include a "DKIM-Signature" request header, as per . The iSchedule Sender then sends the HTTP request to the iSchedule Receiver handling the Recipient group, and receives the HTTP response, which will be an XML document with either an IS:schedule-response or IS:error element as the root element. The iSchedule Sender aggregates the results for each Recipient group receiving an iSchedule message, and returns the resulting status information for each Recipient to the Calendar Service that generated the schedule message. The process by which this is done is outside the scope of this document.
iSchedule Receivers MUST provide a capabilities document to Senders, as per . Upon receipt of an iSchedule HTTP request, the iSchedule Receiver verifies the message as per . Once the authenticity of the message is confirmed, the iSchedule Receiver delivers the scheduling message to the indicated recipients, collects and aggregates the delivery status for each recipient, and returns the result in the HTTP response body. In the event of a processing error related to the overall request, iSchedule Receivers MUST return an error response as per .
This section describes how an iSchedule Sender can discover the host name, port, and the path to use to submit an HTTP request to an iSchedule Receiver. For each Recipient to whom a scheduling message is being sent, the iSchedule Sender will "resolve" the associated calendar user address into a domain name, as per . The iSchedule Sender then uses the extracted domain name to issue a DNS SRV query for the iSchedule service expected to be hosted at the domain. The result of an SRV record lookup will be a target host name and a port, as per . An iSchedule Sender uses these to contact the iSchedule Receiver. iSchedule Senders MUST honor the full behavior of SRV records, in particular the TTL, Priority and Weight options in the record, as well as handling multiple records being returned, as per . Since an iSchedule Receiver is an HTTP server, an iSchedule Sender needs to supply a Request-URI in the HTTP request it makes to the iSchedule Receiver, in addition to the host name and port information. iSchedule Senders MUST use the path specified in any TXT records accompanying the SRV record (as per ), or in the absence of a matching TXT record, MUST use the .well-known URI (as per ).
To deliver a scheduling message via the iSchedule protocol, an iSchedule Sender needs to determine which iSchedule Receiver to use for a particular recipient. Each recipient's calendar user address is specified in one or more Recipient request headers. A calendar user address as defined by iCalendar is simply a URI. This is typically a mailto URI, but could potentially be any URI type. However, only URIs containing a "host" element can be used to extract the necessary information to locate an iSchedule Receiver. To get the SRV record name to query for a given mailto URI, the "domain" portion of the mailto URI is extracted and appended to the service label "_ischedules._tcp.". Example:
In cases where the "domain" portion of the mailto URI contains one or more levels of sub-domain, iSchedule Senders MAY choose to remove successive levels of "sub-domain" if queries for that sub-domain fail to return any SRV records. For example, a mailto URI with the full domain "host.calendar.example.com" would first trigger a query using the domain "host.calendar.example.com", then if that failed, the domain "calendar.example.com" would be tried, then if that failed the domain "example.com" would be tried.
This specification adds an SRV service label for use with iSchedule: Identifies an iSchedule Receiver that uses HTTP with transport layer security (). Example: service record for iSchedule Receiver with transport layer security
_ischedules._tcp.example.com. IN SRV 0 1 443 ischedule.example.com.
When SRV RRs are used to advertise iSchedule services, it is also convenient to be able to specify a "context path" in the DNS to be retrieved at the same time. To enable that, this specification uses a TXT RR that follows the syntax defined in Section 6 of and defines a "path" key for use in that record. The value of the key MUST be the actual "context path" to the corresponding service on the iSchedule Receiver. A site might provide TXT records in addition to SRV records for the service. When present, iSchedule Senders MUST use the "path" value as the "context path" for the service in HTTP requests. When not present, iSchedule Senders use the ".well-known" URI approach described next.
Example: text record for service with TLS _ischedules._tcp TXT path=/ischedule
This specification registers a well-known URI for the iSchedule service, namely, "ischedule" (see ). iSchedule Receivers MUST support requests targeted at this well-known URI. iSchedule Senders MUST handle HTTP redirects on this well-known URI.
iSchedule Receivers supporting the features described in this document MUST allow iSchedule Senders to query their capabilities by accepting GET requests targeted at the Request-URI found during discovery (). The response body for a successful GET request targeted at this URI MUST be an XML document with IS:query-result as its root element. Informative rationale: The GET method was favored over the POST method to allow iSchedule Senders to query capabilities with "conditional GET" requests (see Section 9.3 of ). iSchedule Receivers SHOULD use normal HTTP expiration mechanisms (as per Section 13.1.3 of ) to ensure caches do not cache the capabilities response for too long. iSchedule Senders SHOULD use normal HTTP conditional GET requests when re-checking capabilities to avoid re-transferring already cached data. iSchedule Senders SHOULD use the information in the capabilities to determine whether the iSchedule Receiver supports a version of the protocol that the iSchedule Sender can use, and if not, not issue any iSchedule requests with scheduling messages to the iSchedule Receiver. iSchedule Senders SHOULD verify that the scheduling message to be sent to the iSchedule Receiver is in line with the restrictions on scheduling messages indicated by the capabilities before sending the scheduling message.
>> Request <<
>> Response << 123 1.0 102400 19910101T000000Z 20381231T000000Z 150 250 mailto:ischedule-admin@example.com< /administrator> ]]>
This section defines how an iSchedule Sender can use the HTTP POST method to submit a scheduling message to an iSchedule Receiver. Note, this describes the HTTP request prior to generating a DKIM signature as per .
The POST method submits a scheduling message to one or more Recipients by targeting the request at the Request-URI of an iSchedule Receiver. The request body of a POST method MUST contain a scheduling message (i.e., an iCalendar object that follows the iTIP semantic). The submitted scheduling message will be delivered to the Recipients, with status information about per-recipient delivery returned in the HTTP response. However, when the scheduling message is a request for free-busy time, the iSchedule Receiver will immediately execute the free-busy request for the Recipients and return per-recipient iCalendar data in the response for successful free-busy queries. Every POST request MUST include the "iSchedule-Version" general header. Every POST request SHOULD include the "iSchedule-Message-ID" request header. Every POST request MUST include the "Cache-Control" HTTP general header containing the cache-directives "no-cache" and "no-transform" to prevent intermediary caches from caching or transforming responses. Every POST request MUST include a single "Originator" request header that specifies the calendar user address of the Originator of the scheduling message. The value of the "Originator" request header MUST match the value of the "ORGANIZER" iCalendar property or one of the specified "ATTENDEE" iCalendar properties in the scheduling message, depending on the specified "METHOD" iCalendar property value as summarized in the following table: Method Originator Requirement PUBLISH MUST match ORGANIZER REQUEST MUST match ORGANIZER (see Note 1) REPLY MUST match ATTENDEE ADD MUST match ORGANIZER CANCEL MUST match ORGANIZER REFRESH MUST match ATTENDEE COUNTER MUST match ATTENDEE DECLINECOUNTER MUST match ORGANIZER Note 1: iTIP does allow an Attendee to forward a "METHOD:REQUEST" scheduling message to another attendee. However, due to complexity of managing the authorization of such requests, this specification does not allow scheduling message forwarding. Every POST request MUST include one or more "Recipient" request headers. The value of this header is a list of one or more calendar user addresses and corresponds to the set of calendar users who will have the scheduling message delivered to them. The value of the "Recipient" request header MUST match the value of the "ORGANIZER" iCalendar property or one of the specified "ATTENDEE" iCalendar properties in the scheduling message, depending on the specified "METHOD" iCalendar property value as summarized in the following table: Method Recipient Requirement PUBLISH None (see Note 1) REQUEST MUST match ATTENDEE (see Note 1) REPLY MUST match ORGANIZER ADD MUST match ATTENDEE (see Note 1) CANCEL MUST match ATTENDEE (see Note 1) REFRESH MUST match ORGANIZER COUNTER MUST match ORGANIZER DECLINECOUNTER MUST match ATTENDEE Note 1: iTIP does allow an Organizer to send scheduling message to calendar users who are not listed as Attendees, e.g., to inform other calendar users of an event taking place. However, due to complexity of managing the authorization of such requests, this specification does not allow such scheduling messages. The Content-Type general header MUST include the type parameters "component" and "method" defined in . The value of the "component" MUST correspond to the iCalendar component type (e.g., "VEVENT") specified in the scheduling message. The value of the "method" parameter MUST be the same as the value of the "METHOD" iCalendar property in the scheduling message.
A POST request may deliver a scheduling message to one or more calendar users specified in the Recipient request header. Since the behavior of each recipient may vary, it is useful to get response status information for each recipient in the overall POST response. This specification defines a new XML response to convey multiple recipient status. A response to a POST method that indicates status for one or more recipients MUST be an XML document with IS:schedule-response as its root element. This MUST contain one or more response elements for each recipient, with each of those containing elements that indicate which recipient they correspond to, the scheduling status of the request for that recipient, any error codes and an optional description. In the case of a free-busy request, the response elements can also contain calendar-data elements which contain free busy information (e.g., an iCalendar VFREEBUSY component) indicating the busy state of the corresponding recipient, assuming that the free-busy request for that recipient succeeded. Every POST response MUST include the "Cache-Control" HTTP general header containing the cache-directives "no-cache" and "no-transform" to prevent intermediary caches from caching or transforming responses.
When there is an overall, as opposed to per-recipient, failure of the POST request, the iSchedule Receiver SHOULD return an XML document with IS:error as its root element. The child elements of the IS:error element are used to indicate an error code and description, primarily meant for service administrators. The following XML elements are error codes which can be used within an IS:error element to represent errors: IS:version-not-supported: The POST request was either missing an "iSchedule-Version" header, or had an "iSchedule-Version" header value for a version not supported by the iSchedule Receiver, as advertised in the IS:versions capability. IS:invalid-calendar-data-type: The resource submitted in the POST request was not a supported media type (i.e. text/calendar) for scheduling or free-busy messages; IS:invalid-calendar-data: The resource submitted in the POST request was not valid data for the media type being specified; IS:invalid-scheduling-message: The resource submitted in the POST request did not obey all restrictions specified for the POST request, violating the IS:scheduling-message capability element, or the requirements of iTIP; IS:verification-failed: The POST request failed DKIM verification; IS:originator-missing: The POST request did not include an "Originator" request header specifying the calendar user address of the Originator of the scheduling message. IS:too-many-originators: The POST request contained more than one "Originator" request header. IS:originator-invalid: The "Originator" header in the POST request did not include a valid calendar user address for the Originator of the scheduling message. IS:originator-denied: The calendar user identified by the "Originator" header in the POST request is not allowed to use this service. IS:recipient-missing: The POST request did not include one or more valid "Recipient" request headers specifying the calendar user address of users to whom the scheduling message will be delivered. IS:recipient-mismatch: The POST request did not include "Recipient" request header values which exactly match the list of "ATTENDEE" property values in a "VFREEBUSY" request. IS:max-recipients: The POST request had too many calendar user addresses specified in "Recipient" request headers, violating the IS:max-recipients capability. IS:attachment-type-not-supported: The scheduling message submitted in the POST request had iCalendar data with "ATTACH" properties whose value type is not supported, violating the IS:attachments capability. IS:max-content-length: The scheduling message submitted in the POST request had iCalendar data violating the IS:max-content-length capability. IS:min-date-time: The scheduling message submitted in the POST request had iCalendar data violating the IS:min-date-time capability. IS:max-date-time: The scheduling message submitted in the POST request had iCalendar data violating the IS:max-date-time capability. IS:max-instances: The scheduling message submitted in the POST request had iCalendar data violating the IS:max-instances capability. The following are examples of response codes one would expect to be used for this method. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a response. Typically a 403 response code would be used when an XML document with an IS:error element as its root is also returned. 200 (OK) - The command succeeded. 400 (Bad Request) - The Sender has provided an invalid scheduling message, or invalid iSchedule request headers. 403 (Forbidden) - The Sender cannot submit a scheduling message to the specified Request-URI. 404 (Not Found) - The URL in the Request-URI was not present. 507 (Insufficient Storage) - The server did not have sufficient space to record the scheduling message.
iSchedule uses and extends the mechanism defined by DomainKeys Identified Mail (DKIM) . DKIM defines a domain-level digital signature authentication framework for email, using public-key cryptography, with the domain name service (DNS) as one possible key server technology. This specification extends the applicability of DKIM to the HTTP protocol, with a specific "profile" for use with iSchedule messages. Additionally, DKIM support is REQUIRED for all iSchedule requests, and iSchedule Receivers MUST reject any messages which cannot be verified according to the requirements of DKIM. This is a much stronger requirement than the email use of DKIM, which has to deal with legacy systems. iSchedule Senders MUST only send iSchedule messages for Originators whose authenticity they have verified. iSchedule Receivers that verify a DKIM signature on an iSchedule request can assume that the iSchedule Sender is not only taking responsibility for sending the message, but has also verified the authenticity of the Originator. As such, iSchedule Receivers can reliably use the Originator information to perform their own authorization based on that value. e.g., the Calendar Service to which an iSchedule Receiver delivers a scheduling message, can apply "filtering" rules to such messages based on the guarantee that the Originator calendar user address has been verified at both the iSchedule Sender and Receiver ends. This specification uses the syntactic elements of DKIM, but modified for use with HTTP. Where definitions of syntactic elements of DKIM are applicable to HTTP, they will be used by reference. In cases where the HTTP definition is different, the same ABNF rule name will be used, but the value modified as appropriate. The following sections describe how the DomainKeys Identified Mail (DKIM) service can fit into a scheduling service.
The following HTTP headers MUST be included in the signature of a message: Content-Type iSchedule-Version Originator Recipient The iSchedule Receiver MUST verify that the above HTTP headers are included in the signature. iSchedule Senders and Receivers might use HTTP authentication in requests, though the process through which credentials are managed are out of scope for this document. If HTTP authentication is used, then the "Authorization" HTTP request header MUST be included in the signature of the message. The following HTTP headers, if present, SHOULD be included in the signature of a message: iSchedule-Message-ID User-Agent To allow iSchedule messages to transit via HTTP intermediaries, hop-by-hop headers, such as the following HTTP/1.1 headers MUST NOT be included in the signature of a message: Cache-Control Connection Host Keep-Alive Proxy-Authenticate Proxy-Authorization TE Trailer Transfer-Encoding Upgrade The "Content-Length" header MUST NOT be signed, since the DKIM signature is generated prior to transfer encoding, and the header value represents the length after any transfer encodings have been applied. iSchedule Senders MAY include an "x=" DKIM signature tag in the "DKIM-Signature" header to indicate an expiration time for the signature. When doing so, the "x=" value SHOULD be set to at least 1 minute ahead of the "t=" DKIM signature tag value, to account for processing time between the iSchedule Sender and Receiver.
iSchedule Senders and Receivers MUST use the "simple" body canonicalization algorithm defined in Section 3.4.3 of DKIM to canonicalize the HTTP request message body used for the body hash computation. The iSchedule Sender MUST calculate the body hash prior to any HTTP transfer encodings being applied to the request message body. The iSchedule Receiver MUST calculate the body hash after any HTTP transfer encoding have been removed from the request message body. iSchedule Senders and Receivers MUST use the new "ischedule-relaxed" header canonicalization algorithm defined below to canonicalize the HTTP request headers used for the signature computation.
The "ischedule-relaxed" header canonicalization algorithm is used to canonicalize HTTP header fields where multiple headers fields with the same name might be combined by an HTTP intermediary. The following steps MUST be applied in order: Convert all header field names (not the header field values) to lowercase. For example, convert "SUBJect: AbC" to "subject: AbC". Unfold all header field continuation lines; in particular, lines with terminators embedded in continued header field values (that is, CRLF sequences followed by LWS) MUST be interpreted without the CRLF. Implementations MUST NOT remove the CRLF at the end of the header field value. Combine multiple header fields with the same field name into one one header field value; specifically, append each subsequent field value to the combined field value in order, separated by a comma. For example, combine "recipient:mailto:cyrus@example.com,mailto:mike@example.com" and "recipient:mailto:ken@example.org" into "recipient:mailto:cyrus@example.com,mailto:mike@example.com,mailto:ken@example.org" Convert all sequences of one or more LWS characters to a single SP character. LWS characters here include those before and after a line folding boundary. Delete all WS characters at the end of each unfolded header field value. Delete any LWS characters remaining before and after the colon separating the header field name from the header field value. The colon separator MUST be retained. Delete any LWS characters remaining before and after any commas in the header field value. Since this canonicalization algorithm "collapses" multiple HTTP header fields into a single header field, the h= tag used in the "DKIM-Signature" request header MUST contain only a single value for each different header field name being signed.
Section 3.6.2 of DKIM defines a DNS-based key-binding for public key retrieval. iSchedule Senders and Receivers MUST support this method of public key retrieval. To allow public keys to be restricted to just an iSchedule service, this specification defines a new service type "ischedule" to constrain the use of a key to iSchedule: ABNF:
This specification defines a new HTTP-based public key management method for use with DKIM. The "DKIM-Signature" header "q" tag value associated with this method is "http/well-known": ABNF:
Key lookup first involves retrieving an SRV record that will provide the HTTP server host name and port to use for actual key retrieval. Then the key retrieval is done via an HTTP GET request on a .well-known resource. This new key management approach off-loads the key handling from DNS to an HTTP server, only requiring the DNS administrator to provide the SRV records for authorized HTTP key management servers.
This specification adds one SRV service label for use with HTTP key management: Identifies an HTTP server from which public keys for DKIM signatures can be retrieved. The HTTP server MUST support transport layer security (). The iSchedule Receiver determines the appropriate SRV name using the "d=" DKIM signature tag value in the "DKIM-signature" header being verified:
This specification registers a well-known URI for the DKIM HTTP-based public key management information, "domainkey" (see ). To retrieve information about the public key used to sign an iSchedule message, the iSchedule Sender constructs a URI of the form:
Documents retrieved from the well-known URI MUST be text documents with a media-type of "text/plain". The format of the text document is:
]]>
where tag-list is the unstructured textual form defined in Section 3.6.1. of - i.e., the same data that would be placed in a DNS TXT record for DNS-based public key management. Note that this allows information for multiple keys to be returned for each {domain-name}, {selector} pair. iSchedule Receivers must use HTTP+TLS (https:) to retrieve the public key information document, and follow the certificate-verification process specified in .
Given the following (partial) DKIM-Signature header, the steps below describe how a public key is retrieved from the HTTP pubic key management system.
The iSchedule Receiver first does an SRV record lookup for "_domainkey_lookup._tcp.cal.example.com", and gets back the following example record:
the iSchedule Receiver then makes an HTTP request:
It parses the returned document to determine the appropriate public key to use to verify the DKIM signature.
This specification defines a new public key management method for use with DKIM. This method is used to indicate that the associated public key has been transferred to the recipient through some (unspecified, secure) private exchange. The "DKIM-Signature" header "q" tag value associated with this method is "private-exchange": ABNF:
This method is useful, for example, in situations where an "internal" deployment of iSchedule is being used to connect different calendar systems within an organization. It avoids the need to setup other public key discovery mechanisms when a simple, secure public key exchange can be accomplished between the system administrators.
iSchedule Receivers MUST verify the follow details: The HTTP request contains an "iSchedule-Version" header that matches a version of the iSchedule protocol that the iSchedule Receiver supports. Only one Originator HTTP request header is present in the request and it matches the appropriate iCalendar property as per . One or more Recipient HTTP request headers are present in the request and they match the appropriate iCalendar properties as per . The "DKIM-Signature" header contains valid information and the signature and body hash values can be verified correctly. Note, for the t= value in the "DKIM-Signature", iSchedule Receivers SHOULD accept values that are no more than 5 minutes in the future, to account for possible clock skew between iSchedule Sender and Receiver. If the signature cannot be verified, the iSchedule Receiver MUST reject the iSchedule message outright. If the signature is valid, then iSchedule Receivers have a guarantee that the iSchedule Sender has verified the authenticity of the Originator and determined they are authorized to send the enclosed iTIP message. This allows iSchedule Receivers to use the Originator calendar user address value for access control purposes.
The third-party signature authorization protocol defined in MAY be used by iSchedule Senders and Receivers.
This section defines the syntax and semantics of additional HTTP/1.1 header fields. The header's syntax uses the optional whitespace (OWS) rule defined as follows:
The "DKIM-Signature" request header MUST be specified by the iSchedule Sender on all scheduling requests to specify all of the signature and key-fetching data.
]]>
The "iSchedule-Version" general header field MUST be specified by the iSchedule Sender on requests, and by the iSchedule Receiver on responses. It SHOULD be included in a response to any "OPTIONS *" HTTP request targeting the iSchedule Receiver, or any "OPTIONS" request on a resource supporting the iSchedule behaviors described in this specification (e.g., the .well-known resource or any resource that .well-known redirects to).
The "iSchedule-Capabilities" response header field MUST be specified by the iSchedule Receiver on all responses. iSchedule Senders SHOULD cache this value and use it to detect a change in the iSchedule Receiver capabilities that cause the iSchedule Sender to reload capabilities. The value of this header is maintained by the iSchedule Receiver as described in .
The "iSchedule-Message-ID" request header field SHOULD be specified by the iSchedule Sender on requests. This header provides a unique identifier that refers to the specific iSchedule request in which it is included. The uniqueness of this identifier is guaranteed by the iSchedule Sender that generates it. This identifier is intended to be machine readable and not necessarily meaningful to humans.
The "Originator" request header value is a URI which specifies the calendar user address of the originator of the scheduling message. Note that the absoluteURI rule is defined in .
The "Recipient" request header value is a URI which specifies the calendar user address of the recipients to which the POST method should deliver the submitted scheduling message. Note that the absoluteURI rule is defined in .
schedule-response urn:ietf:params:xml:ns:ischedule Contains the set of responses for a POST method request. See .
]]>
response urn:ietf:params:xml:ns:ischedule Contains a single response for a POST method request. See .
]]>
recipient urn:ietf:params:xml:ns:ischedule The calendar user address (recipient header value) that the enclosing response for a POST method request is for. See .
]]>
request-status urn:ietf:params:xml:ns:ischedule The iTIP REQUEST-STATUS property value for this response. See .
]]>
calendar-data urn:ietf:params:xml:ns:ischedule An iCalendar object in a response to a search for busy time information. See .
]]>
error urn:ietf:params:xml:ns:ischedule Error responses sometimes need more information to indicate what went wrong. See .
]]>
response-description urn:ietf:params:xml:ns:ischedule Contains information about a status response See .
]]>
query-result urn:ietf:params:xml:ns:ischedule Contains result of a query request. A generic container for the result of a query request, such as a query of the capabilities of an iSchedule Receiver.
]]>
capabilities urn:ietf:params:xml:ns:ischedule Contains iSchedule Receiver capabilities. The capabilities element contains capabilities of the iSchedule Receiver.
]]>
serial-number urn:ietf:params:xml:ns:ischedule Identifies the version of the capabilities information. This is a numeric value maintained by the iSchedule Receiver. The value is incremented by the iSchedule Receiver each time there has been a substantive change to the capabilities that would require an iSchedule Sender to reload the capabilities to adjust its behavior. The value of this element MUST be returned by the iSchedule Receiver in all HTTP requests via the "iSchedule-Capabilities" response header. This allows iSchedule Senders to detect changes to the iSchedule Receiver's capabilities during the normal course of making requests, without the need to poll the iSchedule Receiver for such changes.
]]>
versions urn:ietf:params:xml:ns:ischedule Identifies the iSchedule versions supported by the iSchedule Receiver. An iSchedule Receiver MAY advertise support for multiple versions of the iSchedule protocol. iSchedule Senders check this value to ensure they can send iSchedule messages with a matching version.
]]>
version urn:ietf:params:xml:ns:ischedule Identifies an iSchedule protocol version.
]]>
scheduling-messages urn:ietf:params:xml:ns:ischedule Identifies the type of supported scheduling messages. An iSchedule Receiver advertises which iCalendar component types it will accept for iTIP messages sent to it. In addition, for each component, it can specify the allowed iTIP "METHOD" property values.
]]>
component urn:ietf:params:xml:ns:ischedule Identifies a calendar component type. Used to specify a supported iCalendar component type for scheduling messages. If a IS:method child element is not present, then any iTIP "METHOD" property value can be used in iTIP messages sent to the iSchedule Receiver. If one or more IS:method elements are present, then those indicate the allowed set of iTIP "METHOD" property values.
]]>
method urn:ietf:params:xml:ns:ischedule Identifies an iCalendar method type. See IS:component.
]]>
calendar-data-types urn:ietf:params:xml:ns:ischedule Identifies what formats of iCalendar data are acceptable.
]]>
calendar-data-type urn:ietf:params:xml:ns:ischedule Identifies a supported media type and version for iTIP messages.
]]>
attachments urn:ietf:params:xml:ns:ischedule Identifies the attachment values supported. iSchedule Receivers might restrict what form of attachments are allowed in iTIP messages that are sent to it, for performance, or security reasons. In iCalendar data, attachments can either be specified using "inline" data in the form of a base64 encoded property value, or "external" data in the form of a URI property value. With this capability, an iSchedule Receiver can specify which of "inline" or "external" values it will accept in iTIP messages. See for additional details.
]]>
inline urn:ietf:params:xml:ns:ischedule Identifies "inline" attachments as a supported attachment value.
]]>
external urn:ietf:params:xml:ns:ischedule Identifies "external" attachments as a supported attachment value.
]]>
max-content-length urn:ietf:params:xml:ns:ischedule Identifies the maximum size allowed for a scheduling message in octets.
]]>
min-date-time urn:ietf:params:xml:ns:ischedule A DATE-TIME value indicating the earliest date and time in UTC that the iSchedule Receiver is willing to accept for any DATE or DATE-TIME value in a scheduling message.
]]>
max-date-time urn:ietf:params:xml:ns:ischedule A DATE-TIME value indicating the latest date and time in UTC that the iSchedule Receiver is willing to accept for any DATE or DATE-TIME value in a scheduling message.
]]>
max-instances urn:ietf:params:xml:ns:ischedule The maximum number of recurrence instances allowed in a scheduling message.
]]>
max-recipients urn:ietf:params:xml:ns:ischedule The maximum number of recipients allowed for a scheduling message.
]]>
administrator urn:ietf:params:xml:ns:ischedule Provides contact information for the administrator of the iSchedule Receiver.
]]>
The process of scheduling involves the sending and receiving of scheduling messages. As a result, the security problems related to messaging in general are relevant here. In particular the authenticity of the scheduling messages needs to be verified. Potential attacks described in the security considerations of DKIM are also applicable to iSchedule.
iSchedule Senders and iSchedule Receivers MUST use an HTTP connection protected with TLS as defined in for all transactions.
iSchedule uses and extends the mechanism defined by DomainKeys Identified Mail (DKIM) . DKIM defines a domain-level digital signature authentication framework for email, using public-key cryptography, with the domain name service as its key server technology.
DNS security issues are addressed by DNSSEC .
iCalendar data can include "inline" attachment data in the form of a base64-encoded "ATTACH" property value. iSchedule Receivers MUST take care when allowing "inline" attachments in scheduling messages as such data might contain malicious content, and SHOULD use some form of content scanner on the attachment data to verify its safety (e.g., a content scanner used for email messages). In addition, "inline" attachment data is likely to be much larger than the actual calendar-related data in a scheduling message, and thus could adversely affect the performance of an iSchedule Receiver processing it. If an iSchedule Receiver allows "inline" attachment data, it MUST apply a limit on the size of acceptable scheduling messages to prevent possible denial-of-service attacks using large "inline" attachment data. In general, it is best for iSchedule Receivers to simply disable the ability for scheduling messages to contain "inline" attachment data, and instead rely solely on "external" attachments in the form of URI attachment values.
This specification registers a new URN to identify a new XML namespace as per .
Registration request for the iSchedule namespace: URI: urn:ietf:params:xml:ns:ischedule Registrant Contact: See the "Authors' Addresses" section of this document. XML: None. Namespace URIs do not represent an XML specification.
This specification registers new headers for use with HTTP as per .
Header field name: DKIM-Signature Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
Header field name: iSchedule-Version Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
Header field name: iSchedule-Capabilities Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
Header field name: iSchedule-Message-ID Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
Header field name: Originator Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
Header field name: Recipient Applicable protocol: http Status: standard Author/Change controller: IETF Specification document(s): this specification Related information: none
This specification registers a new well-known URI as per .
URI suffix: ischedule Change controller: IETF. Specification document(s): this specification Related information: none
URI suffix: domainkey Change controller: IETF. Specification document(s): this specification Related information: none
This specification registers two new query mechanisms that can be used in DKIM-Signature fields. The following values should be added to the DKIM-Signature Query Method Registry established in Section 7.3 of : Type Option Reference Status http well-known (this document ) active private-exchange (this document ) active
This specification registers a new DKIM service type to specify that a given public key MUST only be used to verify messages of iSchedule services. The following value should be added to the DKIM Service Type Registry established in Section 7.8 of : Type Reference Status ischedule (this document ) active
The authors would like to thank the following individuals for contributing their ideas and support for writing this specification: Mattias Amnefelt, Mike Douglass, Tomas Hnetila, Ciny Joy, Barry Leiba, Ken Murchison, Simon Pilette, Arnaud Quillaud, Simon Vaillancourt, and Wilfredo Sanchez Vega. The authors would also like to thank CalConnect, The Calendaring and Scheduling Consortium, for advice with this specification, and for organizing interoperability testing events to help refine it.
&rfc2119; &rfc2616; &rfc2617; &rfc2782; &rfc2818; &rfc3688; &rfc3986; &rfc4033; &rfc5234; &rfc5246; &rfc5545; &rfc5546; &rfc5785; &rfc6125; &rfc6376; &rfc6763; &W3C.REC-xml-20081126; &rfc3864; &rfc4791; &rfc5585; &rfc6047; &rfc6638; &rfc6541;
This section describes some example scheduling transactions that give a general idea of how scheduling is carried out between an iSchedule Sender and an iSchedule Receiver.
In the following example, the iSchedule Sender requests the iSchedule Receiver to deliver a meeting invitation (scheduling REQUEST) to the calendar user mailto:cyrus@example.org. The response indicates that delivery of the scheduling message was successful.
>> Request <<
>> Response << mailto:cyrus@example.org 2.0;Success Delivered to recipient< /response-description> ]]>
In the following example, the iSchedule Sender requests the iSchedule Receiver to determine the busy information of the calendar users mailto:cyrus@example.org and mailto:mike@example.org, over the time range specified by the scheduling message sent in the request. The response includes VFREEBUSY components with the busy time for one calendar user, and an error for the other calendar user.
>> Request <<
>> Response << mailto:cyrus@example.org 2.0;Success BEGIN:VCALENDAR VERSION:2.0 PRODID:-//Example Corp.//EN METHOD:REPLY BEGIN:VFREEBUSY DTSTAMP:20040901T200200Z ORGANIZER:mailto:bernard@example.com DTSTART:20040902T000000Z DTEND:20040903T000000Z UID:34222-232@example.com ATTENDEE;CN=Cyrus Daboo:mailto:cyrus@example.org FREEBUSY;FBTYPE=BUSY-UNAVAILABLE:20040902T000000Z/ 20040902T090000Z,20040902T170000Z/20040903T000000Z FREEBUSY;FBTYPE=BUSY:20040902T120000Z/20040902T130000Z END:VFREEBUSY END:VCALENDAR mailto:mike@example.org 5.3;No scheduling support for user< /request-status> Unknown calendar user< /response-description> ]]>
In the following example, the iSchedule Sender requests the iSchedule Sender to deliver a task assignment (scheduling REQUEST) to the calendar user mailto:cyrus@example.org. For some reason the verification of the request fails as is indicated by the error response.
>> Request <<
>> Response << Unable to verify request< /response-description> ]]>
Fixed missing Recipient header in example. Added statements about what happens when a signature is or is not valid. Removed _ischedule SRV record type as we only support HTTPS. Removed text about adding an extra Recipient header as we no longer need that.
Added some addition error codes to match MUST requirements. Free busy example now shows a failed calendar user response. Fixed capabilities response example to add method elements for VTODO and VFREEBUSY. More details added to XML element definitions.
Removed http= tag from DKIM header. Updated lists of must and must not sign headers. Stated that Recipient list must match ATTENDEE list for VFREEBUSY requests. Recommend 5 minute skew for t=. Added serial-number to capabilities and iSchedule-Capabilities response header. Added "ischedule-relaxed" header canonicalization. Fixed examples.
Major structural changes as well as addition of new sections, including an Overview. Changed capabilities XML schema. XML error elements are now named for the actual error as opposed to WebDAV style pre-conditions. Removed intermediary support and iSchedule-Via header. Added TXT path= lookup to accompany SRV lookup. Added http/well-known public key lookup mechanism. Added iSchedule-Message-ID header. Provided suggested values for t= and x= to cope with clock skew and processing time issues. Indicated that iSchedule-Version header can be returned in OPTIONS responses. Clarified that Attendee list for VFREEBUSY has to be the same as the Recipient list.
Introduced use of DKIM for calendaring and scheduling services. The XML elements "supported-calendar-data" and "calendar-data" were renamed to "supported-calendar-data-type" and "calendar-data-type" respectively to avoid confusion with the "calendar-data" XML element being used in the "response" XML element. The "recipient" XML element was redefined to accept (#PCDATA) instead of an "href" XML element. The grammar of new HTTP headers is now using the ABNF syntax defined in . Fixed various typos.