The Time Zone Information Format (TZif)
draft-murchison-tzdist-tzif-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 8536.
|
|
|---|---|---|---|
| Authors | Arthur David Olson , Paul Eggert , Kenneth Murchison | ||
| Last updated | 2017-11-27 | ||
| RFC stream | (None) | ||
| Formats | |||
| Reviews |
GENART Telechat review
(of
-15)
by Dale Worley
Ready w/nits
GENART Last Call review
(of
-14)
by Dale Worley
Ready w/issues
|
||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | Became RFC 8536 (Proposed Standard) | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-murchison-tzdist-tzif-00
Independent Submission A. Olson
Internet-Draft
Updates: 7808 (if approved) P. Eggert
Intended status: Standards Track UCLA
Expires: May 30, 2018 K. Murchison
FastMail
November 26, 2017
The Time Zone Information Format (TZif)
draft-murchison-tzdist-tzif-00
Abstract
This document defines the Time Zone Information File Format for
representing and exchanging time zone information, independent of any
particular service or protocol. A MIME media type for this format is
also defined.
Open Issues
o Need to review definitions of terms.
o Should we require TZDIST servers to always return a particular
format (2 or 3) with/without leap seconds? Or should we allow the
client to choose what they want (via parameters on the MIME type)?
o Are we referencing the correct and most current versions of the
relevant POSIX specs?
o Is the MIME registration complete and correct (e.g. any security
or privacy considerations)?
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
Olson, et al. Expires May 30, 2018 [Page 1]
Internet-Draft TZif November 2017
This Internet-Draft will expire on May 30, 2018.
Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. The Time Zone Information Format (TZif) . . . . . . . . . . . 3
4. Use with the Time Zone Data Distribution Service . . . . . . 8
4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 10
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
8.1. Normative References . . . . . . . . . . . . . . . . . . 11
8.2. Informative References . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12
1. Introduction
Time zone data typically consists of an offset from Universal
Coordinated Time (UTC), daylight saving transition rules, one or more
local time designations (acronyms or abbreviations), and optional
leap second adjustments. One such format for conveying this
information is iCalendar [RFC5545]. It is a text-based format used
by calendaring and scheduling systems.
This document defines the Time Zone Information Format. It is a
binary format used by most UNIX systems to calculate local time.
There is a wide variety of interoperable software [tz-link] capable
of generating and reading files in this format.
This specification does not define the source of the time zone data
or leap second information. It is assumed that a reliable and
accurate source is available. One such source is the IANA-hosted
time zone database [RFC6557].
Olson, et al. Expires May 30, 2018 [Page 2]
Internet-Draft TZif November 2017
2. Conventions Used in This Document
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC2119].
The following terms are used in this document:
Coordinated Universal Time (UTC): The time at the prime meridian (0
degrees longitude) as determined by atomic clocks and the Earth's
rotational time.
Daylight Saving Time (DST): The time according to a location's law
or practice, adjusted forward from standard time during summer
months to gain more evening daylight.
International Atomic Time (TAI): The time at the prime meridian (0
degrees longitude) based on a continuous counting of atomic clock
seconds.
Local Time: The time according to a locations's current time zone
offset from Coordinated Universal Time.
POSIX Time: The time as returned by the C time() function (see
Section 3 of [POSIX-time]).
Standard Time: The time according to a location's law or practice,
unadjusted for changes such as Daylight Saving Time.
Wall Time: The time as shown on a clock set according to a
location's law or practice.
3. The Time Zone Information Format (TZif)
The time zone information format begins with a fixed 44-octet header
followed by a variable-length body using four-octet (32-bit)
transition times and leap second occurrences. These 32-bit values
are limited to representing times no later than 19 January, 2038
03:14:07 UTC. The 32-bit header and body is structured as follows
(the number of octets occupied by a field is shown in parenthesis):
Olson, et al. Expires May 30, 2018 [Page 3]
Internet-Draft TZif November 2017
+---------------+---+
| magic (4) | <-+-- version (1)
+---------------+---+---------------------------------------+
| [unused - reserved for future use] (15) |
+---------------+---------------+---------------+-----------+
| isutccnt (4) | isstdcnt (4) | leapcnt (4) |
+---------------+---------------+---------------+
| timecnt (4) | typecnt (4) | charcnt (4) |
+===============+===============+===============+
| transition times (timecnt x 4) ...
+-----------------------------------------------+
| transition time index (timecnt) ...
+-----------------------------------------------+
| local time type records (typecnt x 6) ...
+-----------------------------------------------+
| time zone designations (charcnt) ...
+-----------------------------------------------+
| leap second records (leapcnt x 8) ...
+-----------------------------------------------+
| standard/wall indicators (isstdcnt) ...
+-----------------------------------------------+
| UTC/local indicators (isutccnt) ...
+-----------------------------------------------+
Figure 1: 32-bit Header and Body
Depending on the file version, the 32-bit header and body MAY be
followed by a second 44-octet header and variable-length body using
eight-octet (64-bit) transition times and leap second occurrences.
These 64-bit values can represent times approximately 292 billion
years into the future. The 64-bit header and body is structured as
follows:
Olson, et al. Expires May 30, 2018 [Page 4]
Internet-Draft TZif November 2017
+---------------+---+
| magic (4) | <-+-- version (1)
+---------------+---+---------------------------------------+
| [unused - reserved for future use] (15) |
+---------------+---------------+---------------+-----------+
| isutccnt (4) | isstdcnt (4) | leapcnt (4) |
+---------------+---------------+---------------+
| timecnt (4) | typecnt (4) | charcnt (4) |
+===============+===============+===============+
| transition times (timecnt x 8) ...
+-----------------------------------------------+
| transition time index (timecnt) ...
+-----------------------------------------------+
| local time type records (typecnt x 6) ...
+-----------------------------------------------+
| time zone designations (charcnt) ...
+-----------------------------------------------+
| leap second records (leapcnt x 12) ...
+-----------------------------------------------+
| standard/wall indicators (isstdcnt) ...
+-----------------------------------------------+
| UTC/local indicators (isutccnt) ...
+---+---------------------------------------+---+
| NL| POSIX TZ string (0...) |NL |
+---+---------------------------------------+---+
Figure 2: 64-bit Header and Body
NOTE: All multi-octet integer values MUST be stored in big-endian
format (high-order octet first).
The fields of the headers are defined as follows:
magic: The four-octet ASCII sequence "TZif" (0x54 0x5A 0x69 0x66)
which identifies the file as utilizing the Time Zone Information
Format.
version: An octet identifying the version of the file's format. The
value MUST be one of the following:
NUL (0x00) Version 1 - The file contains only the 32-bit header
and body. Version 1 files MUST NOT contain a 64-bit header or
body.
'2' (0x32) Version 2 - The file MUST contain both the 32-bit
header and body and a 64-bit header and body. The POSIX TZ
string MUST strictly adhere to the expanded format specified in
Section 8 of [POSIX-TZ].
Olson, et al. Expires May 30, 2018 [Page 5]
Internet-Draft TZif November 2017
'3' (0x33) Version 3 - The file MUST contain both the 32-bit
header and body and a 64-bit header and body. The POSIX TZ
string MAY use the following extensions:
+ The hours part of the transition times may be signed and
range from -167 through 167 instead of the POSIX-required
unsigned values from 0 through 24.
+ DST is considered to be in effect all year if it starts
January 1 at 00:00 and ends December 31 at 24:00 plus the
difference between daylight saving and standard time,
leaving no room for standard time in the calendar.
isutccnt: A four-octet unsigned integer specifying the number of
UTC/local indicators contained in the body.
isstdcnt: A four-octet unsigned integer specifying the number of
standard/wall indicators contained in the body.
leapcnt: A four-octet unsigned integer specifying the number of leap
second records contained in the body.
timecnt: A four-octet unsigned integer specifying the number of
transition times contained in the body.
typecnt: A four-octet unsigned integer specifying the number of
local time type Records contained in the body - MUST NOT be zero.
charcnt: A four-octet unsigned integer specifying the total number
of octets used by the set of time zone designations contained in
the body.
The data elements of the bodies are defined as follows:
transition times: A series of four- or eight-octet POSIX time values
sorted in ascending order. Each value is used as a transition
time at which the rules for computing local time change. The
number of time values is specified by the 'timecnt' field in the
header.
transition time index: A series of one-octet unsigned integers
specifying the type of local time of the same-indexed transition
time. These values serve as indices into the array of local time
type records. The number of time indices is specified by the
'timecnt' field in the header.
local time type records: A series of six-octet records specifying a
local time type. The number of records is specified by the
Olson, et al. Expires May 30, 2018 [Page 6]
Internet-Draft TZif November 2017
'typecnt' field in the header. Each record has the following
format:
+-------- isdst (1)
|
+---------------+-+-+---+
| utcoff (4) | v | <-+-- desigidx (1)
+---------------+---+---+
utcoff: A four-octet signed integer specifying the number of
seconds to be added to UTC in order to determine local time.
isdst: A one-octet value indicating whether local time should be
considered Daylight Savings Time (DST). A value of one (1)
indicates that DST is in effect. A value of zero (0) indicates
that standard time in effect.
desigidx: A one-octet unsigned integer specifying an index into
the series of time zone designation characters, thereby
selecting a particular designation string.
time zone designations: A series of ASCII characters constituting
array of NUL-terminated (0x00) time zone designation strings. The
total number of characters is specified by the 'charcnt' field in
the header. Note that two designations MAY overlap if one is a
suffix of the other.
leap second records: A series of eight- or twelve-octet records
specifying the corrections that need to be applied to UTC in order
to determine TAI. The records are sorted by the occurrence time
in ascending order. The number of records is specified by the
'leapcnt; field in the header. Each record has one of the
following structures:
32-bit Body:
+---------------+---------------+
| epoch (4) | corr (4) |
+---------------+---------------+
64-bit Body:
+---------------+---------------+---------------+
| epoch (8) | corr (4) |
+---------------+---------------+---------------+
epoch: A four- or eight-octet POSIX time value specifying the
time at which a leap second occurs.
Olson, et al. Expires May 30, 2018 [Page 7]
Internet-Draft TZif November 2017
corr: A four-octet signed integer specifying the total number of
leap seconds to be applied to UTC on or after the epoch.
standard/wall indicators: A series of one-octet values indicating
whether the transition times associated with local time types were
specified as standard time or wall clock time. A value of one (1)
indicates standard time. A value of zero (0) indicates wall time.
The number of values is specified by the 'isstdcnt' field in the
header.
UTC/local indicators: A series of one-octet values indicating
whether the transition times associated with local time types were
specified as UTC or local time. A value of one (1) indicates UTC.
A value of zero (0) indicates local time. The number of values is
specified by the 'isutccnt' field in the header.
POSIX TZ string: A rule for computing local time changes after the
last transition time stored in the body. The string uses the
expanded format as defined in Section 8 of [POSIX-TZ]. Note that
the string MUST NOT be NUL-terminated, and MAY be empty.
NL: An ASCII new line character (0x0A).
4. Use with the Time Zone Data Distribution Service
The Time Zone Data Distribution Service (TZDIST) [RFC7808] is a
service that allows reliable, secure, and fast delivery of time zone
data and leap second rules to client systems such as calendaring and
scheduling applications or operating systems.
A TZDIST service MAY supply time zone data to clients in the Time
Zone Information Format. Such a service MUST indicate that it
supports this format by including the MIME media type "application/
tzif" (Section 7) in its "capabilities" response (see Section 5.1 of
[RFC7808].
TZDIST clients MUST use the HTTP "Accept" [RFC7231] header field to
indicate their preference to receive data in the "application/tzif"
format.
4.1. Example
In this example, the client checks the server for the available
formats and then requests that the time zone with a specific time
zone identifer be returned in Time Zone Information Format.
Olson, et al. Expires May 30, 2018 [Page 8]
Internet-Draft TZif November 2017
Note that this example presumes that the time zone context path has
been discovered (see [RFC7808] Section 4.2.1) to be "/tzdist").
>> Request <<
GET /tzdist/capabilities HTTP/1.1
Host: tz.example.com
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 22 Nov 2017 09:32:12 GMT
Content-Type: application/json; charset="utf-8"
Content-Length: xxxx
{
"version": 1,
"info": {
"primary-source": "IANA:2017c",
"formats": [
"text/calendar",
"application/tzfile",
],
...
},
...
}
>> Request <<
GET /tzdist/zones/America%2FNew_York HTTP/1.1
Host: tz.example.com
Accept: application/tzif
>> Response <<
HTTP/1.1 200 OK
Date: Wed, 22 Nov 2017 09:32:12 GMT
Content-Type: application/tzif
Content-Length: xxxx
ETag: "123456789-000-111"
TZif2...[binary data]...
EST5EDT,M3.2.0,M11.1.0
Olson, et al. Expires May 30, 2018 [Page 9]
Internet-Draft TZif November 2017
5. Security Considerations
None.
6. Privacy Considerations
None.
7. IANA Considerations
This document defines a MIME [RFC6838] media type for the exchange of
data utilizing the Time Zone Information Format.
Type name: application
Subtype name: tzif
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: Binary
Security considerations: N/A
Interoperability considerations: N/A
Published specification: This specification.
Applications that use this media type: This media type is designed
for widespread use by applications that need to exchange time zone
information. The Time Zone Distribution Service [RFC7808] can
directly use this media type.
Fragment identifier considerations: N/A
Additional information:
Magic number(s): The first 4 bytes are 0x54, 0x5A, 0x69, 0x66
File extensions(s): N/A
Macintosh file type code(s): N/A
Person & email address to contact for further
information:
Time Zone Database mailing list <tz@iana.org>
Olson, et al. Expires May 30, 2018 [Page 10]
Internet-Draft TZif November 2017
Intended usage: COMMON
Restrictions on usage: N/A
Author: See the "Author's Address" section of this document.
Change controller: IETF
8. References
8.1. Normative References
[POSIX-time]
Institute of Electrical and Electronics Engineers, "IEEE
P1003.1-2008, Information Technology Portable Operating
System Interface (POSIX) Part 1: System Application
Program Interface (API) [C Language]", 2016,
<http://pubs.opengroup.org/onlinepubs/9699919799/>.
[POSIX-TZ]
Institute of Electrical and Electronics Engineers, "IEEE
P1003.1-2008, Information Technology Portable Operating
System Interface (POSIX) - Base Definitions", 2016,
<http://pubs.opengroup.org/onlinepubs/9699919799/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution
Service", RFC 7808, DOI 10.17487/RFC7808, March 2016,
<https://www.rfc-editor.org/info/rfc7808>.
Olson, et al. Expires May 30, 2018 [Page 11]
Internet-Draft TZif November 2017
8.2. Informative References
[RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and
Scheduling Core Object Specification (iCalendar)",
RFC 5545, DOI 10.17487/RFC5545, September 2009,
<https://www.rfc-editor.org/info/rfc5545>.
[RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the
Time Zone Database", BCP 175, RFC 6557,
DOI 10.17487/RFC6557, February 2012,
<https://www.rfc-editor.org/info/rfc6557>.
[tz-link] Eggert, P. and A. Olson, "Sources for Time Zone and
Daylight Saving Time Data", 2017,
<https://www.iana.org/time-zones/repository/tz-link.html>.
Authors' Addresses
Arthur David Olson
Email: arthurdavidolson@gmail.com
Paul Eggert
University of California, Los Angeles
Email: eggert@cs.ucla.edu
Kenneth Murchison
FastMail Pty Ltd.
Email: murch@fastmailteam.com
Olson, et al. Expires May 30, 2018 [Page 12]