| Network Working Group | M. Douglass |
| Internet-Draft | RPI |
| Intended status: Standards Track | C. Daboo |
| Expires: June 03, 2013 | Apple |
| November 30, 2012 |
Timezone Service Protocol
draft-douglass-timezone-service-07
This document defines a timezone service protocol that allows reliable, secure and fast delivery of timezone information to client systems such as calendaring and scheduling applications or operating systems.
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 http:/⁠/⁠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 June 03, 2013.
Copyright (c) 2012 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.
Timezone information typically combines a coordinated universal time (UTC) offset with daylight saving time (DST) rules. Timezones are typically tied to specific geographic and geopolitical regions. Whilst the UTC offset for particular regions changes infrequently, DST rules can change frequently and sometimes with very little notice (sometimes hours before a change comes into effect).
Calendaring and scheduling systems, such as those that use iCalendar [RFC5545], as well as operating systems, critically rely on timezone information to determine the correct local time. As such they need to be kept up to date with changes to timezone information. To date there has been no fast and easy way to do that. Timezone data is often supplied in the form of a set of data files that have to be "compiled" into a suitable database format for use by the client application or operating system. In the case of operating systems, those changes often only get propagated out to client machines when there is an operating system update and those can be infrequent, resulting in inaccurate timezone data being present for significant amounts of time.
This specification defines a timezone service protocol that allows for fast, reliable and accurate delivery of timezone information to client systems. This protocol is based on HTTP [RFC2616] using a REST style API, with JSON [RFC4627] responses.
This specification does not define the source of the timezone information. It is assumed that a reliable and accurate source is available. One such source is the IANA hosted timezone database [RFC6557].
This specification does not address the need for global timezone identifiers for timezone data.
Discussion of this document should take place on the calsify mailing list calsify@ietf.org
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 [RFC2119].
The following terms with the given meanings are used throughout this document.
==================== ====================
(a) | Contributors | | Contributors |
==================== ====================
| |
==================== ====================
(b) | Publisher A | | Publisher B |
==================== ====================
|
====================
(c) | Provider |
====================
/ | \
/ | \
==================== | ====================
(d) | Provider | | | Provider |
==================== | ====================
| | | |
| | | |
========== ========== ========== ==========
(e) | Client | | Client | | Client | | Client |
========== ========== ========== ==========
Figure 1: Timezone Service Architecture
The overall process for the delivery of timezone data can be visualized via the diagram shown below.
The overall service is made up of several layers:
Some of those layers may be coalesced by implementors. For example, a vendor may choose to implement the entire service as a single monolithic virtual server with the address embedded in distributed systems. Others may choose to provide a service consisting of multiple layers of providers, many local servers and a small number of root servers.
This specification is only concerned with the protocol used to exchange data between providers and from provider to client. This specification does not define how contributors pass their information to publishers, nor how those publishers vet that information to obtain trustworthy data, nor the format of the data produced by the publishers.
This is the label by which a time zone calendar component is
referenced by any iCalendar properties whose value type is
either "DATE-TIME" or "TIME" and not intended to specify a UTC
or a "floating" time. The presence of the SOLIDUS character
as a prefix, indicates that this "TZID" represents an unique
identifier in a globally defined time zone registry (when such
registry is defined).
Timezone identifiers are the canonical names for identifiers. There MUST be one and only one identifier per specification. iCalendar Section 3.8.3.1 [RFC5545] has this text on the identifier:
This specification does not define what identifiers should be used. While the above specifies that names must start with "/" to be globally unique, it is assumed that a set of timezone identifiers will be considered the default set with an implied "/" preceding the identifier.
Timezone identifier aliases map a timezone identifier onto a canonical timezone identifier. For example US/Eastern is usually mapped on to America/New_York.
A timezone service needs to maintain timezone identifier alias information, and return that data as well as allow queries using aliases.
Localized names are names for timezones which can be presented to a user in their own language. Each timezone may have one or more localized names associated with it. Names would typically be unique in their own locale as they might be presented to the user in a list.
A timezone service needs to return localized name information, for one or more chosen languages, as well as provide a way for clients to query for timezone data based on a localized name.
Over time, timezones can be replaced by others, but need to be maintained for historical purposes. Usually, clients are only concerned with timezones valid for current and future dates and times. A timezone service needs to return inactive timezones, but only needs to do that at the specific request of a client. i.e., current timezones would be returned by default, but inactive timezones could also be requested.
The timezone service protocol uses HTTP [RFC2616] for query and delivery of data. Queries are made on a single HTTP resource using the GET method is used, with specific client request attributes passed in request-URI parameters.
The "action" request-URI parameter defines the overall function being requested, with other request parameters acting as arguments to that function.
Most security considerations are already handled adequately by HTTP. However, given the nature of the data being transferred and the requirement it be correct all interactions between client and server SHOULD use an HTTP connection protected with TLS [RFC5246] as defined in [RFC2818].
Timezone identifiers, aliases or names can be used to query for timezone data. This will be more explicitly defined below for each action. In general however, if a "tzid" request parameter is used then the value may be an identifier or an alias. When the "name" parameter is used it may be an identifier, an alias or a localized name.
The default format for returning timezone definitions is the iCalendar [RFC5545] data format. In addition, the iCalendar-in-XML [RFC6321], and iCalendar-in-JSON [I-D.kewisch-et-al-icalendar-in-json] representations are also available. The "format" request-URI parameter can be used to select which data format is returned.
Timezone information is generally slow moving, with the set of timezones that change from even year-to-year being relatively small. However, any changes that do occur, need to be distributed in a timely manner. Typically it is more efficient to just provide the set of changes to timezone data, so a client can do updates to any locally cached data.
When listing timezones, a timestamp is returned by the server, and that can be used later by clients to determine if any "substantive" change has occurred in the timezone data. Clients can use a conditional "list" action (see Section 6.2), supplying a previous timestamp value, to limit the results to timezones which have changed in a "substantive" manner since that previous timestamp. This allows clients to cache the last timestamp and to periodically poll the server for possible changes.
A "substantive" change is one which affects the calculated onsets for a timezone. Changes to properties such as a description are not treated as a "substantive" change.
Clients SHOULD NOT poll for such changes too frequently. See Section 8 on expected client and server behavior regarding high request rates.
Determining timezone offsets at a particular point in time is often a complicated process, as the rules for daylight saving time can be complex. To help with this, the timezone service provides an action that allows clients to request the server to expand a timezone definition into a set of "observances" over a fixed period of time (see Section 6.4). Each of these observances describes a local onset time and UTC offsets for the prior time and the observance time. Together, these provide a quick way for "thin" clients to determine an appropriate UTC offset for an arbitrary date without having to do full timezone expansion themselves.
All servers MUST deliver timezone information for all timezones. This means that any client API implementation can go to a single server to get all timezone information. In turn, any server can refresh any of the data from any other server - though the root servers may provide the most up-to-date copy of the data.
All service providers MUST deliver functionally equivalent data for all timezones. This ensures that all parties in a contract agree on the UTC time. Service providers (or publishers) may choose to map a particular region on to a different timezone identifier to correct a deficiency in the original timezone specification.
The following are examples of response codes one would expect to be used by the server. Note, however, that unless explicitly prohibited any 2/3/4/5xx series response code may be used in a response.
When an error status is set the server SHOULD respond with some descriptive text in an error element Section 7.4
This protocol is designed to be extensible through a standards based registration mechanism (see Section 9). It is anticipated that other useful timezone actions will be added in the future (e.g., mapping a geographical location to timezone identifiers, getting change history for timezones), and so, servers MUST return a description of their capabilities. This will allow clients to determine if new features have been installed and, if not, fall back on earlier features or disable some client capabilities.
Client implementations need to either know where the timezone service is located or discover it through some mechanism. To use a timezone service, a client needs an FQDN, port and HTTP request-URI path.
[RFC2782] defines a DNS-based service discovery protocol that has been widely adopted as a means of locating particular services within a local area network and beyond, using SRV RR records. This can be used to discover a service's FQDN and port.
This specification adds two service types for use with SRV records:
Clients MUST honor "TTL", "Priority" and "Weight" values in the SRV records, as described by [RFC2782].
Example: service record for server without transport layer security
_timezone._tcp SRV 0 1 80 tz.example.com.
Example: service record for server with transport layer security
_timezones._tcp SRV 0 1 443 tz.example.com.
When SRV RRs are used to advertise a timezone service, 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 [I-D.cheshire-dnsext-dns-sd] 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 server.
A site might provide TXT records in addition to SRV records for each service. When present, clients MUST use the "path" value as the "context path" for the service in HTTP requests. When not present, clients use the ".well-known" URI approach described next.
Example: text record for service with transport layer security
_timezones._tcp TXT path=/timezones
A "well-known" URI [RFC5785] is registered by this specification for the Timezone service, "timezone" (see Section 9). This URI points to a resource that the client can use as the initial "context path" for the service they are trying to connect to. The server MUST redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP (e.g., using a 301, 303, 307 response). Clients MUST handle HTTP redirects on the ".well-known" URI. Servers MUST NOT locate the actual timezone service endpoint at the ".well-known" URI as per Section 1.1 of [RFC5785].
Servers SHOULD set an appropriate Cache-Control header value (as per Section 14.9 of [RFC2616]) in the redirect response to ensure caching occurs or does not occur as needed, or as required by the type of response generated. For example, if it is anticipated that the location of the redirect might change over time, then a "no-cache" value would be used.
To facilitate "context path's" that might differ from user to user, the server MAY require authentication when a client tries to access the ".well-known" URI (i.e., the server would return a 401 status response to the unauthenticated request from the client, then return the redirect response only after a successful authentication by the client).
A Timezone server has a "context path" that is "/servlet/timezone". The client will use "/.well-known/timezone" as the path for the service process after it has first found the FQDN and port number via an SRV lookup or via manual entry of information by the user from which the client can parse suitable information. When the client makes its initial HTTP request against "/.well-known/timezone", the server would issue an HTTP 301 redirect response with a Location response header using the path "/servlet/timezone". The client would then "follow" this redirect to the new resource and continue making HTTP requests there.
When a secondary service or a client wishing to cache all timezone data first starts or wishes to do a full refresh it synchronizes with another server by first issuing a list action with returnall="true". The client should preserve the returned datestamp for subsequent use. Each timezone in the returned list can then be fetched and stored locally. In addition a mapping of aliases to timezones can be built.
Periodically a secondary service or a client caching all timezone data needs to synchronize with another server. To do so it should issue a list action with the changedsince parameter set to the value of the datestamp returned at the last synchronization. The client should again preserve the returned datestamp for subsequent use. Each timezone in the returned list can then be fetched and stored locally.
Note, this process makes no provision for handling deleted timezones. In general it is bad practice to delete timezones as they may now be in use by consumers of timezone data.
All requests require the "action" request-URI parameter to define what action is required of the server.
Servers MUST support the following request-URI parameters.
Servers MUST support the following actions.
In this example the client requests the server capabilities.
>> Request <<
GET /?action=capabilities HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"info": {
"primary-source": "Olson:2011m",
"contact": "mailto:tzs@example.org",
},
"actions": [
{
"name": "list",
"parameters": [
{
"name": "lang",
"required": false,
"multi": true
},
{
"name": "changedsince",
"required": false,
"multi": false
},
{
"name": "returnall",
"required": false,
"multi": false
}
]
},
{
"name": "get",
"parameters": [
{
"name": "format",
"required": false,
"multi": false,
"values": [
"text/calendar",
"application/calendar+xml",
"application/calendar+json"
]
},
{
"name": "lang",
"required": false,
"multi": true
},
{
"name": "tzid",
"required": true,
"multi": true,
},
{
"name": "returnall",
"required": false,
"multi": false,
}
]
},
{
"name": "expand",
"parameters": [
{
"name": "tzid",
"required": true,
"multi": true,
},
{
"name": "start",
"required": false,
"multi": false
},
{
"name": "end",
"required": false,
"multi": false,
}
]
},
{
"name":"capabilities",
"parameters": []
},
]
}
In this example the client requests the timezone identifiers and in addition requests that the US-English local names be returned.
>> Request <<
GET /?action=list&lang=en_US HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"dtstamp": "2009-10-11T09:32:11Z",
"timezones": [
{
"tzid": "America/New_York",
"last-modified": "2009-09-17T01:39:34Z",
"aliases":["US/Eastern"],
"local-names": [
{
"name": "America/New_York",
"lang": "en_US"
}
]
},
...
]
}
In this example the client requests the timezone with a specific timezone identifier to be returned
>> Request <<
GET /?action=get&tzid=America/New_York
&format=text/calendar HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: text/calendar; charset="utf-8"
Content-Length: xxxx
ETag: "123456789-000-111"
BEGIN:VCALENDAR
...
BEGIN:VTIMEZONE
...
END:VTIMEZONE
END:VCALENDAR
In this example the client requests a timezone in the expanded form.
>> Request <<
GET /?action=expand&tzid=America/New_York HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 4 Jun 2008 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
ETag: "123456789-000-111"
{
"dtstamp": "2009-10-11T09:32:11Z",
"observances": [
{
"name": "Daylight",
"onset": "2008-03-09T07:00:00Z",
"utc-offset-from": -18000,
"utc-offset-to": -14400
},
{
"name": "Standard",
"onset": "2008-11-02T07:00:00Z",
"utc-offset-from": -14400,
"utc-offset-to": -18000
},
{
"name": "Daylight",
"onset": "2009-03-08T07:00:00Z",
"utc-offset-from": -18000,
"utc-offset-to": -14400
},
...
]
}
In this example the client asks for information about "America/New_York".
>> Request << GET /?action=find&name=America/New_York HTTP/1.1 Host: tz.example.com >> Response << HTTP/1.1 200 OK Date: Wed, 4 Jun 2008 09:32:12 GMT Content-Type: application/json; charset="utf-8" Content-Length: xxxx TBD
JSON members used by this specification are defined here using the syntax in [I-D.newton-json-content-rules].
JSON Content Rules for the JSON document returned for a "capabilities" action request.
; root object
root = {
info,
actions
}
; object containing service information
info "info" : {
primary_source / secondary_source,
contacts
}
; The source of the timezone data provided by a "primary" server
primary_source "primary-source" : string
; The timezone server from which data is provided by a "secondary"
; server
secondary_source "secondary-source" : uri
; Array of URIs providing contact details for the server
; administrator
contacts "contacts" : [ * :uri ]
; Array of actions supported by the server
actions "actions" : [ * action ]
; An action supported by the server
action : {
action_name,
action_params
}
; Name of the action
action_name "name" : string
; Array of request-URI query parameters supported by the action
action_params = "parameters" : [ * parameter ]
; Object defining an action parameter
parameter = {
param_name,
?param_required,
?param_multi,
?param_values
}
; Name of the parameter
param_name "name" : string
; If true the parameter has to be present in the request-URI
; default is false
param_required "required" : boolean
; If true the parameter can occur more than once in the request-URI
; default is false
param_multi "multi" : boolean,
; An array that defines the allowed set of values for the parameter
; In the absence of this member, any string value is acceptable
param_values "values" : [ * : string ]
JSON Content Rules for the JSON document returned for a "list" action request.
; root object
root = {
dtstamp,
timezones
}
; Server generated timestamp used for synchronizing changes,
; [RFC3339] UTC value
dtstamp "dtstamp" : date-time
; Array of timezone objects
timezones "timezones" : [ * timezone ]
; Information about a timezone available on the server
timezone : {
tzid,
last_modified,
?inactive,
?aliases,
?local_names,
}
; Timezone identifier
tzid "tzid" : string
; Date/time when the timezone data was last modified
; [RFC3339] UTC value
last_modified "last-modified" : date-time
; Indicates whether the timerzone is an inactive timezone
inactive "inactive" : boolean
; An array that lists the set of timezone identifier aliases
; available for the corresponding timezone
aliases "aliases" : [ * : string ]
; An array that lists the set of timezone identifier aliases
; available for the corresponding timezone
local_names "local-names" : [ * local_name ]
local_name = [lang, lname, ?pref]
; Language tag for the language of the associated name
lang : string
; Localized name
lname : string
; Indicates whether this is the preferred name for the associated
; language default: false
pref : boolean
JSON Content Rules for the JSON document returned for a "expand" action request.
; root object
root = {
dtstamp,
observances
}
; Server generated timestamp used for synchronizing changes
; [RFC3339] UTC value
dtstamp "dtstamp" : date-time
; Array of timezone objects
observances "observances" : [ * observances ]
; Information about a timezone available on the server
observance : {
oname,
?olocal_names,
onset,
utc_offset_from,
utc_offset_to
}
; Observance name
oname "name" : string
; Array of localized observance names
olocal_names "local-names" : [ * :string]
; The local time at which the observance takes effect
; [RFC3339] value modified to exclude "time-offset" part
onset "onset" : date-time
; The UTC offset in seconds before the start of this observance
utc_offset_from "utc-offset-from" : integer
; The UTC offset in seconds at and after the start of this observance
utc_offset_to "utc-offset-to" : integer
JSON Content Rules for the JSON document returned when an error occurs.
; root object
root = {
error,
?description
}
; Error code
error "error" : integer
; Description of the error
description "description" : string
Timezone data is critical in determining local or UTC time for devices and in calendaring and scheduling operations. As such, it is vital that a reliable source of timezone data is used. Servers providing a timezone service MUST support HTTP over Transport Layer Security (TLS) (as defined by [RFC2818]) with a valid certificate. Clients and servers making use of a timezone service SHOULD use HTTP over TLS and verify the authenticity of the service being used before accepting and using any timezone data from that source.
Clients that support transport layer security as defined by [RFC2818] SHOULD try the "_timezones" service first before trying the "_timezone" service. Clients MUST follow the certificate verification process specified in [RFC6125].
A malicious attacker with access to the DNS server data, or able to get spoofed answers cached in a recursive resolver, can potentially cause clients to connect to any server chosen by the attacker. In the absence of a secure DNS option, clients SHOULD check that the target FQDN returned in the SRV record matches the original service domain that was queried. If the target FQDN is not in the queried domain, clients SHOULD verify with the user that the SRV target FQDN is suitable for use before executing any connections to the host.
Timezone servers SHOULD protect themselves against errant or malicious clients by throttling high request rates or frequent requests for large amounts of data. Clients can avoid being throttled by using the polling capabilities outlined in Section 4.1.3
This defines a new registry of "actions" for the timezone service protocol, and defines a "well-known" URI using the registration procedure and template from Section 5.1 of [RFC5785], and creates two new SRV service label aliases.
This section defines the process to register new or modified timezone service actions with IANA.
The IETF will create a mailing list, timezone-service@ietf.org, which can be used for public discussion of timezone service actions proposals prior to registration. Use of the mailing list is strongly encouraged. The IESG will appoint a designated expert who will monitor the timezone-service@ietf.org mailing list and review registrations.
Registration of new timezone service actions MUST be reviewed by the designated expert and published in an RFC. A Standard Tracks RFC is REQUIRED for the registration of new timezone service actions. A Standard Tracks RFC is also REQUIRED for changes to actions previously documented in a Standard Tracks RFC.
The registration procedure begins when a completed registration template, defined in the sections below, is sent to timezone-service@ietf.org and iana@iana.org. The designated expert is expected to tell IANA and the submitter of the registration within two weeks whether the registration is approved, approved with minor changes, or rejected with cause. When a registration is rejected with cause, it can be re-submitted if the concerns listed in the cause are addressed. Decisions made by the designated expert can be appealed to the IESG Applications Area Director, then to the IESG. They follow the normal appeals procedure for IESG decisions.
An action is defined by completing the following template.
An action parameter is defined by completing the following template.
The IANA is requested to create and maintain the following registries for timezone service actions with pointers to appropriate reference documents.
The following table is to be used to initialize the actions registry.
| Action Name | Status | Reference |
|---|---|---|
| capabilities | Current | RFCXXXX, Section 6.1 |
| list | Current | RFCXXXX, Section 6.2 |
| get | Current | RFCXXXX, Section 6.3 |
| expand | Current | RFCXXXX, Section 6.4 |
| find | Current | RFCXXXX, Section 6.5 |
The following table is to be used to initialize the parameters registry.
| Parameter | Status | Reference |
|---|---|---|
| action | Current | RFCXXXX, Section 5.1 |
| changedsince | Current | RFCXXXX, Section 5.3 |
| end | Current | RFCXXXX, Section 5.5 |
| format | Current | RFCXXXX, Section 5.2 |
| lang | Current | RFCXXXX, Section 5.6 |
| returnall | Current | RFCXXXX, Section 5.7 |
| start | Current | RFCXXXX, Section 5.4 |
| tzid | Current | RFCXXXX, Section 5.8 |
This document registers two new service names as per [RFC6335]. Both are defined within this document.
The authors would like to thank the members of the Calendaring and Scheduling Consortium's Timezone Technical Committee and the following individuals for contributing their ideas and support: Steve Allen, John Haug, Ciny Joy, Bryan Keller, Andrew McMillan, Arnaud Quillaud, Jose Edvaldo Saraiva.
The authors would also like to thank the Calendaring and Scheduling Consortium for advice with this specification.