[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 RFC 8536

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]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/