idnits 2.17.1 draft-murchison-tzdist-tzif-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (September 12, 2018) is 2046 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 856 -- Looks like a reference, but probably isn't: '2' on line 858 -- Looks like a reference, but probably isn't: '3' on line 861 == Missing Reference: '-89999' is mentioned on line 365, but not defined -- Looks like a reference, but probably isn't: '93599' on line 365 -- Looks like a reference, but probably isn't: '4' on line 864 -- Looks like a reference, but probably isn't: '5' on line 867 -- Looks like a reference, but probably isn't: '6' on line 870 -- Looks like a reference, but probably isn't: '7' on line 872 -- Looks like a reference, but probably isn't: '8' on line 874 -- Looks like a reference, but probably isn't: '9' on line 876 == Missing Reference: '-3599' is mentioned on line 989, but not defined == Missing Reference: '-1' is mentioned on line 989, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Independent Submission A. Olson 3 Internet-Draft 4 Intended status: Standards Track P. Eggert 5 Expires: March 16, 2019 UCLA 6 K. Murchison 7 FastMail 8 September 12, 2018 10 The Time Zone Information Format (TZif) 11 draft-murchison-tzdist-tzif-14 13 Abstract 15 This document defines the Time Zone Information Format (TZif) for 16 representing and exchanging time zone information, independent of any 17 particular service or protocol. Two MIME media types for this format 18 are also defined. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on March 16, 2019. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 53 3. The Time Zone Information Format (TZif) . . . . . . . . . . . 4 54 3.1. TZif Header . . . . . . . . . . . . . . . . . . . . . . . 5 55 3.2. TZif Data Block . . . . . . . . . . . . . . . . . . . . . 7 56 3.3. TZif Footer . . . . . . . . . . . . . . . . . . . . . . . 11 57 3.3.1. TZ String Extensions . . . . . . . . . . . . . . . . 11 58 4. Interoperability Considerations . . . . . . . . . . . . . . . 12 59 5. Use with the Time Zone Data Distribution Service . . . . . . 13 60 5.1. Truncating TZif Files . . . . . . . . . . . . . . . . . . 13 61 5.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 14 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 16 63 7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 16 64 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 65 8.1. application/tzif . . . . . . . . . . . . . . . . . . . . 16 66 8.2. application/tzif-leap . . . . . . . . . . . . . . . . . . 17 67 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18 68 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 69 10.1. Normative References . . . . . . . . . . . . . . . . . . 18 70 10.2. Informative References . . . . . . . . . . . . . . . . . 19 71 10.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 19 72 Appendix A. Common Interoperability Issues . . . . . . . . . . . 20 73 Appendix B. Change History (To be removed by RFC Editor before 74 publication) . . . . . . . . . . . . . . . . . . . . 22 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 77 1. Introduction 79 Time zone data typically consists of offsets from Universal Time 80 (UT), daylight saving transition rules, one or more local time 81 designations (acronyms or abbreviations), and optional leap second 82 adjustments. One such format for conveying this information is 83 iCalendar [RFC5545]. It is a text-based format used by calendaring 84 and scheduling systems. 86 This document defines the Time Zone Information Format (TZif). It is 87 a binary format used by most UNIX systems to calculate local time. 88 There is a wide variety of interoperable software [tz-link] capable 89 of generating and reading files in this format. 91 This specification does not define the source of leap second 92 information, nor does it define the source the time zone data, 93 metadata, identifiers, aliases, localized names, or versions as 94 defined in Section 3 of [RFC7808]. One such source is the IANA- 95 hosted time zone database [RFC6557]. 97 2. Conventions Used in This Document 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 101 "OPTIONAL" in this document are to be interpreted as described in BCP 102 14 [1] [RFC2119] [RFC8174] when, and only when, they appear in all 103 capitals, as shown here. 105 The following terms are used in this document: 107 Coordinated Universal Time (UTC): The basis for civil time since 108 1960. It is approximately equal to mean solar time at the prime 109 meridian (0 degrees longitude). 111 Daylight Saving Time (DST): The time according to a location's law 112 or practice, adjusted as necessary from standard time. The 113 adjustment may be positive, negative, or zero. 115 International Atomic Time (TAI): The time standard based on atomic 116 clocks since 1972. It is equal to UTC except without leap second 117 adjustments. 119 Leap Second Correction (LEAPCORR): The value of TAI - UTC - 10 for 120 timestamps after the first leap second, and zero for timestamps 121 before that. The expression "TAI - UTC - 10" comes from the fact 122 that TAI - UTC was defined to be 10 just prior to the first leap 123 second in 1972, so clocks with leap seconds have a zero LEAPCORR 124 before the first leap second. 126 Local Time: The time according to a location's current time zone 127 offset from Universal Time. 129 Standard Time: The time according to a location's law or practice, 130 unadjusted for Daylight Saving Time. 132 Time Change: A change to civil timekeeping practice. It occurs when 133 one or more of the following happen simultaneously: 135 1. a change in UT offset 137 2. a change in whether standard or daylight saving time is in use 139 3. a change in time zone abbreviation 141 4. a leap second (i.e., a change in LEAPCORR) 143 Time Zone Data: The Time Zone Data Distribution Service (TZDIST) 144 [RFC7808] defines "Time zone data" as "data that defines a single 145 time zone, including an identifier, UTC offset values, DST rules, 146 and other information such as time zone abbreviations." The 147 interchange format defined in this document is one such form of 148 time zone data. 150 Universal Time (UT): The basis of civil time. This is the principal 151 form of the mean solar time at the prime meridian (0 degrees 152 longitude) for timestamps before UTC was introduced in 1960, and 153 is UTC for timestamps thereafter. Although UT is sometimes called 154 "UTC" or "GMT" in other sources, this specification uses the term 155 "UT" to avoid confusion with UTC or with GMT. 157 UNIX Time: The time as returned by the C time() function (see 158 Section 3 of the "System Interfaces" Volume [2] of [POSIX]). This 159 is an integer number of seconds since the POSIX Epoch (1970-01-01 160 00:00:00 UTC) not counting leap seconds. As an extension to 161 POSIX, negative values represent times before the POSIX Epoch, 162 using UT. 164 UNIX Leap Time: UNIX time plus all preceding leap second 165 corrections. For example, if the first leap second record in a 166 TZif file occurs at 1972-06-30 23:59:60 UTC, the UNIX leap time 167 for the timestamp 1972-07-01 00:00:00 UTC would be 78796801, one 168 greater than the UNIX time for the same timestamp. Similarly, if 169 the second leap second record occurs at 1972-12-31 23:59:60 UTC, 170 its UNIX leap time would be 94694401; the second occurrence 171 accounts for the first leap second. If a TZif file specifies no 172 leap second records, UNIX leap time is equivalent to UNIX time. 174 Wall Time: The time as shown on a clock set according to a 175 location's law or practice. 177 3. The Time Zone Information Format (TZif) 179 The time zone information format begins with a fixed 44-octet header 180 (Section 3.1) followed by a variable-length data block (Section 3.2) 181 using four-octet (32-bit) transition times and leap second 182 occurrences. These 32-bit values are limited to representing times 183 from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 UT. 185 The TZif header contains a field which specifies the version of the 186 file's format. Version 1 files terminate after the 32-bit data 187 block. 189 Version 2 and 3 files extend the format by appending a second 190 44-octet header, another variable-length data block using eight-octet 191 (64-bit) transition times and leap second occurrences, and a variable 192 length footer (Section 3.3). These 64-bit values can represent times 193 approximately 292 billion years into the past or future. 195 A TZif file is structured as follows: 197 Version 1 Versions 2 & 3 198 +-------------+ +-------------+ 199 | Header for | | Header for | 200 | 32-bit | | 32-bit | 201 | Transitions | | Transitions | 202 +-------------+ +-------------+ 203 | Data with | | Data with | 204 | 32-bit | | 32-bit | 205 | Transitions | | Transitions | 206 +-------------+ +-------------+ 207 | Header for | 208 | 64-bit | 209 | Transitions | 210 +-------------+ 211 | Data with | 212 | 64-bit | 213 | Transitions | 214 +-------------+ 215 | Footer | 216 +-------------+ 218 General Format of TZif Files 220 NOTE: All multi-octet integer values MUST be stored in network octet 221 order format (high-order octet first, otherwise known as big-endian), 222 with all bits significant. Signed integer values MUST be represented 223 using two's complement. 225 3.1. TZif Header 227 The TZif header is structured as follows (the number of octets 228 occupied by a field is shown in parenthesis): 230 +---------------+---+ 231 | magic (4) |ver| 232 +---------------+---+---------------------------------------+ 233 | [unused - reserved for future use] (15) | 234 +---------------+---------------+---------------+-----------+ 235 | isutcnt (4) | isstdcnt (4) | leapcnt (4) | 236 +---------------+---------------+---------------+ 237 | timecnt (4) | typecnt (4) | charcnt (4) | 238 +---------------+---------------+---------------+ 240 TZif Header 242 The fields of the header are defined as follows: 244 magic: The four-octet ASCII [RFC0020] sequence "TZif" (0x54 0x5A 245 0x69 0x66) which identifies the file as utilizing the Time Zone 246 Information Format. 248 ver(sion): An octet identifying the version of the file's format. 249 The value MUST be one of the following: 251 NUL (0x00) Version 1 - The file contains only the 32-bit header 252 and data block. Version 1 files MUST NOT contain a 64-bit 253 header, data block, or footer. 255 '2' (0x32) Version 2 - The file MUST contain the 32-bit header 256 and data block, a 64-bit header and data block, and a footer. 257 The TZ string in the footer (Section 3.3), if nonempty, MUST 258 strictly adhere to the requirements for the TZ environment 259 variable as defined in Section 8.3 of the "Base Definitions" 260 Volume [3] of [POSIX], and MUST encode the POSIX portable 261 character set as ASCII. 263 '3' (0x33) Version 3 - The file MUST contain the 32-bit header 264 and data block, a 64-bit header and data block, and a footer. 265 The TZ string in the footer (Section 3.3), if nonempty, MUST 266 conform to POSIX requirements with ASCII encoding, except that 267 it MAY use the TZ string extensions described below 268 (Section 3.3.1). 270 isutcnt: A four-octet unsigned integer specifying the number of UT/ 271 local indicators contained in the data block - MUST either be zero 272 or equal to 'typecnt'. 274 isstdcnt: A four-octet unsigned integer specifying the number of 275 standard/wall indicators contained in the data block - MUST either 276 be zero or equal to 'typecnt'. 278 leapcnt: A four-octet unsigned integer specifying the number of leap 279 second records contained in the data block. 281 timecnt: A four-octet unsigned integer specifying the number of 282 transition times contained in the data block. 284 typecnt: A four-octet unsigned integer specifying the number of 285 local time type records contained in the data block - MUST NOT be 286 zero. (Although time type 0 is not used in files that have 287 nonempty TZ strings but no transitions, it is nevertheless 288 required because many TZif readers reject files that lack time 289 types.) 291 charcnt: A four-octet unsigned integer specifying the total number 292 of octets used by the set of time zone designations contained in 293 the data block. 295 3.2. TZif Data Block 297 The TZif data block consists of seven variable-length elements, each 298 of which is series of zero or more items. The number of items in 299 each series is determined by the corresponding count field in the 300 header. The total length of each element is calculated by 301 multiplying the number of items by the size of each item. Therefore, 302 implementations that do not wish to parse or use the 32-bit data 303 block can calculate its total length and skip directly to the header 304 of the 64-bit data block. 306 In the initial data block, time values are 32-bit (TIME_SIZE = 4 307 octets). In the second data block, present only in version 2 and 3 308 files, time values are 64-bit (TIME_SIZE = 8 octets). 310 The data block is structured as follows (the number of octets 311 occupied by a field is shown in parenthesis): 313 +---------------------------------------------------------+ 314 | transition times (timecnt x TIME_SIZE) | 315 +---------------------------------------------------------+ 316 | transition types (timecnt) | 317 +---------------------------------------------------------+ 318 | local time type records (typecnt x 6) | 319 +---------------------------------------------------------+ 320 | time zone designations (charcnt) | 321 +---------------------------------------------------------+ 322 | leap second records (leapcnt x (TIME_SIZE + 4)) | 323 +---------------------------------------------------------+ 324 | standard/wall indicators (isstdcnt) | 325 +---------------------------------------------------------+ 326 | UT/local indicators (isutcnt) | 327 +---------------------------------------------------------+ 329 TZif Data Block 331 The elements of the data block are defined as follows: 333 transition times: A series of four- or eight-octet UNIX leap time 334 values sorted in strictly ascending order. Each value is used as 335 a transition time at which the rules for computing local time may 336 change. The number of time values is specified by the 'timecnt' 337 field in the header. Each time value SHOULD be at least -2**59. 338 (-2**59 is the greatest negated power of 2 that predates the Big 339 Bang, and avoiding earlier timestamps works around known TZif 340 reader bugs relating to outlandlishly negative timestamps.) 342 transition types: A series of one-octet unsigned integers specifying 343 the type of local time of the corresponding transition time. 344 These values serve as indices into the array of local time type 345 records. The number of type indices is specified by the 'timecnt' 346 field in the header. Each type index MUST be in the range [0, 347 'typecnt'). 349 local time type records: A series of six-octet records specifying a 350 local time type. The number of records is specified by the 351 'typecnt' field in the header. Each record has the following 352 format: 354 +---------------+-+-+---+ 355 | utoff (4) |dst|idx| 356 +---------------+---+---+ 358 utoff: A four-octet signed integer specifying the number of 359 seconds to be added to UT in order to determine local time. 360 The value MUST NOT be -2**31, and SHOULD be in the range 362 [-89999, 93599] (i.e., its value SHOULD be more than -25 hours 363 and less than 26 hours). (Avoiding -2**31 allows 32-bit 364 clients to negate the value without overflow. Restricting it 365 to [-89999, 93599] allows easy support by implementations that 366 already support the the POSIX-required range [-24:59:59, 367 25:59:59].) 369 (is)dst: A one-octet value indicating whether local time should 370 be considered Daylight Savings Time (DST). The value MUST be 0 371 or 1. A value of one (1) indicates that DST is in effect. A 372 value of zero (0) indicates that standard time in effect. 374 (desig)idx: A one-octet unsigned integer specifying an index into 375 the series of time zone designation octets, thereby selecting a 376 particular designation string. Each index MUST be in the range 377 [0, 'charcnt'), and MUST index a NUL-terminated (0x00) sequence 378 of octets. 380 time zone designations: A series of octets constituting an array of 381 NUL-terminated (0x00) time zone designation strings. The total 382 number of octets is specified by the 'charcnt' field in the 383 header. Note that two designations MAY overlap if one is a suffix 384 of the other. 386 leap second records: A series of eight- or twelve-octet records 387 specifying the corrections that need to be applied to UTC in order 388 to determine TAI. The records are sorted by the occurrence time 389 in strictly ascending order. The number of records is specified 390 by the 'leapcnt' field in the header. Each record has one of the 391 following structures: 393 32-bit Data Block: 395 +---------------+---------------+ 396 | occur (4) | corr (4) | 397 +---------------+---------------+ 399 64-bit Data Block: 401 +---------------+---------------+---------------+ 402 | occur (8) | corr (4) | 403 +---------------+---------------+---------------+ 405 occur(rence): A four- or eight-octet UNIX leap time value 406 specifying the time at which a leap second correction occurs. 407 The first value, if present, MUST be nonnegative, and each 408 later value MUST be at least 2419199 greater than the previous 409 value. (This is 28 days' worth of seconds, minus a potential 410 negative leap second.) 412 corr(ection): A four-octet signed integer specifying the value of 413 LEAPCORR on or after the occurrence. The correction value in 414 the first leap second record, if present, MUST be either one 415 (1) or minus one (-1). The correction values in adjacent leap 416 second records MUST differ by exactly one (1). The value of 417 LEAPCORR is zero for timestamps that occur before the 418 occurrence time in the first leap second record (or for all 419 timestamps if there are no leap second records). 421 standard/wall indicators: A series of one-octet values indicating 422 whether the transition times associated with local time types were 423 specified as standard time or wall clock time. Each value MUST be 424 0 or 1. A value of one (1) indicates standard time, and MUST be 425 set to one (1) if the corresponding UT/local indicator is set to 426 one (1). A value of zero (0) indicates wall time. The number of 427 values is specified by the 'isstdcnt' field in the header. If 428 'isstdcnt' is zero (0), all transition times associated with local 429 time types are assumed to be specified as wall time. 431 UT/local indicators: A series of one-octet values indicating whether 432 the transition times associated with local time types were 433 specified as UT or local time. Each value MUST be 0 or 1. A 434 value of one (1) indicates UT, and the corresponding standard/wall 435 indicator MUST also be set to one (1). A value of zero (0) 436 indicates local time. The number of values is specified by the 437 'isutcnt' field in the header. If 'isutcnt' is zero (0), all 438 transition times associated with local time types are assumed to 439 be specified as local time. 441 The type corresponding to a transition time specifies local time for 442 timestamps starting at the given transition time and continuing up 443 to, but not including, the next transition time. Local time for 444 timestamps before the first transition is specified by the first time 445 type (time type 0). Local time for timestamps on or after the last 446 transition is specified by the TZ string in the footer (Section 3.3) 447 if present and nonempty, and is unspecified otherwise. If there are 448 no transitions, local time for all timestamps is specified by the TZ 449 string in the footer if present and nonempty, and is specified by 450 time type 0 otherwise. 452 A given pair of standard/wall and UT/local indicators is used to 453 designate whether the corresponding transition time was specified as 454 UT, standard time, or wall clock time. Note that there are only 455 three combinations of the two indicators given that the standard/wall 456 value MUST be one (1) if the UT/local value is one (1). This 457 information can be useful if the transition times in a TZif file need 458 to be transformed into transitions appropriate for another time zone 459 (e.g. when calculating transition times for a simple POSIX TZ string 460 such as "AKST9AKDT"). 462 In order to eliminate unused space in a TZif file, every nonzero 463 local time type index SHOULD appear at least once in the transition 464 type array. Likewise, every octet in the time zone designations 465 array SHOULD be used by at least one time type record. 467 3.3. TZif Footer 469 The TZif footer is structured as follows (the number of octets 470 occupied by a field is shown in parenthesis): 472 +---+--------------------+---+ 473 | NL| TZ string (0...) |NL | 474 +---+--------------------+---+ 476 TZif Footer 478 The elements of the footer are defined as follows: 480 NL: An ASCII new line character (0x0A). 482 TZ string: A rule for computing local time changes after the last 483 transition time stored in the 64-bit data block. The string is 484 either empty or uses the expanded format of the "TZ" environment 485 variable as defined in Section 8.3 of the "Base Definitions" 486 Volume [4] of [POSIX] with ASCII encoding, possibly utilizing 487 extensions described below (Section 3.3.1) in version 3 files. If 488 the string is empty, the corresponding information is not 489 available. If the string is nonempty and one or more transitions 490 appear in the 64-bit data, the string MUST be consistent with the 491 last 64-bit transition - i.e., evaluating the TZ string at the 492 time of the last transition should yield the same time type as the 493 time type specified in the last transition. The string MUST NOT 494 contain NUL octets or be NUL-terminated, and SHOULD NOT begin with 495 the ':' (colon) character. 497 3.3.1. TZ String Extensions 499 The TZ string in a Version 3 TZif file MAY use the following 500 extensions to POSIX TZ strings. These extensions are described using 501 the terminology of Section 8.3 of the "Base Definitions" Volume [5] 502 of [POSIX]. 504 o The hours part of the transition times may be signed and range 505 from -167 through 167 (-167 <= hh <= 167) instead of the POSIX- 506 required unsigned values from 0 through 24. 508 Example: <-03>3<-02>,M3.5.0/-2,M10.5.0/-1 509 This represents a time zone that observes daylight saving time 510 from 22:00 on the day before March's last Sunday until 23:00 on 511 the day before October's last Sunday. Standard time is 3 hours 512 west of UT and is abbreviated "-03"; daylight saving time is 2 513 hours west of UT and is abbreviated "-02". 515 o DST is considered to be in effect all year if it starts January 1 516 at 00:00 and ends December 31 at 24:00 plus the difference between 517 daylight saving and standard time, leaving no room for standard 518 time in the calendar. 520 Example: EST5EDT,0/0,J365/25 521 This represents a time zone that observes daylight saving time 522 all year. It is 4 hours west of UT and is abbreviated "EDT". 524 4. Interoperability Considerations 526 These recommended practices should be followed in order to assure 527 interoperability of TZif applications. 529 o Version 1 files are considered a legacy format and SHOULD NOT be 530 generated, as they do not support transition times after the year 531 2038. 533 o Implementations SHOULD generate a version 3 file if TZ string 534 extensions are necessary to accurately model transition times. 535 Otherwise, version 2 files SHOULD be generated. 537 o The sequence of time changes defined by the 32-bit header and data 538 block SHOULD be a contiguous subsequence of the time changes 539 defined by the 64-bit header and data block, and by the footer. 540 This guideline helps obsolescent version 1 readers agree with 541 current readers about timestamps within the contiguous 542 subsequence. It also lets writers not catering to obsolescent 543 readers use a 'timecnt' of zero in the 32-bit data to save space. 545 o Time zone designations SHOULD consist of at least three (3) and no 546 more than six (6) ASCII characters from the set of alphanumerics, 547 '-', and '+'. This is for compatibility with POSIX requirements 548 for time zone abbreviations. 550 o When reading a version 2 or 3 file, implementations SHOULD ignore 551 the 32-bit header and data block except for the purpose of 552 skipping over them. 554 o Implementations SHOULD calculate the total lengths of the 32- and 555 64-bit headers and data blocks and compare them against the actual 556 file size, as part of a validity check for the file. 558 o When a TZif file is used in a MIME message entity it SHOULD be 559 indicated by one of the following media types: 561 * "application/tzif-leap" (Section 8.2) to indicate that leap 562 second records are included in the TZif data. 564 * "application/tzif" (Section 8.1) to indicate that leap second 565 records are not included in the TZif data; 'leapcnt' in the 566 header(s) MUST be zero (0). 568 o Common interoperability issues and possible workarounds are 569 described in Appendix A. 571 5. Use with the Time Zone Data Distribution Service 573 The Time Zone Data Distribution Service (TZDIST) [RFC7808] is a 574 service that allows reliable, secure, and fast delivery of time zone 575 data and leap second rules to client systems such as calendaring and 576 scheduling applications or operating systems. 578 A TZDIST service MAY supply time zone data to clients in the Time 579 Zone Information Format. Such a service MUST indicate that it 580 supports this format by including the MIME media type "application/ 581 tzif" (Section 8.1) in its "capabilities" response (see Section 5.1 582 of [RFC7808]). A TZDIST service MAY also include the MIME media type 583 "application/tzif-leap" (Section 8.2) in its "capabilities" response 584 if it is able to generate TZif files containing leap second records. 585 A TZDIST service MUST NOT advertise the "application/tzif-leap" MIME 586 media type without also advertising "application/tzif". 588 TZDIST clients MUST use the HTTP "Accept" [RFC7231] header field to 589 indicate their preference to receive data in the "application/tzif" 590 and/or "application/tzif-leap" formats. 592 5.1. Truncating TZif Files 594 As described in Section 3.9 of [RFC7808], a TZDIST service MAY 595 truncate time zone transition data. A truncated TZif file is valid 596 from its first and up to, but not including, its last 64-bit 597 transition time, if present. 599 When truncating the start of a TZif file, the service MUST supply in 600 the 64-bit data a first transition time that is the start point of 601 the truncation range. As with untruncated TZif files, time type 0 602 indicates local time immediately before the start point, and the time 603 type of the first transition indicates local time thereafter. 605 When truncating the end of a TZif file, the service MUST supply in 606 the 64-bit data a last transition time that is the end point of the 607 truncation range, and MUST supply an empty TZ string. As with 608 untruncated TZif files with empty TZ strings, a truncated TZif file 609 does not indicate local time after the last transition. 611 All represented information that falls inside the truncation range 612 MUST be the same as that represented by a corresponding untruncated 613 TZif file. 615 TZDIST clients SHOULD NOT use a truncated TZif file (as described 616 above) to interpret timestamps outside the truncation time range. 618 5.2. Example 620 In this example, the client checks the server for the available 621 formats and then requests that the time zone with a specific time 622 zone identifier be returned in Time Zone Information Format. 624 Note that this example presumes that the time zone context path has 625 been discovered (see [RFC7808] Section 4.2.1) to be "/tzdist". 627 >> Request << 629 GET /tzdist/capabilities HTTP/1.1 630 Host: tz.example.com 632 >> Response << 634 HTTP/1.1 200 OK 635 Date: Fri, 01 Jun 2018 14:52:23 GMT 636 Content-Type: application/json; charset="utf-8" 637 Content-Length: xxxx 639 { 640 "version": 1, 642 "info": { 643 "primary-source": "IANA:2018e", 644 "formats": [ 645 "text/calendar", 646 "application/tzif", 647 "application/tzif-leap" 648 ], 649 ... 650 }, 651 ... 652 } 654 >> Request << 656 GET /tzdist/zones/America%2FNew_York HTTP/1.1 657 Host: tz.example.com 658 Accept: application/tzif 660 >> Response << 662 HTTP/1.1 200 OK 663 Date: Fri, 01 Jun 2018 14:52:24 GMT 664 Content-Type: application/tzif 665 Content-Length: xxxx 666 ETag: "123456789-000-111" 668 TZif2...[binary data without leap second records]... 669 EST5EDT,M3.2.0,M11.1.0 671 6. Security Considerations 673 The Time Zone Information Format contains no executable code and the 674 format does not define any extensible areas that could be used to 675 store such code. 677 TZif contains counted arrays of data elements. All counts should be 678 checked when processing TZif objects to guard against references past 679 the end of the object. 681 TZif provides no confidentiality or integrity protection. Time zone 682 information is normally public and does not call for confidentiality 683 protection. Since time zone information is used in many critical 684 applications, integrity protection may be required, and must be 685 provided externally. 687 7. Privacy Considerations 689 The Time Zone Information Format contains publicly available data and 690 the format does not define any extensible areas that could be used to 691 store private data. 693 8. IANA Considerations 695 This document defines two MIME [RFC6838] media types for the exchange 696 of data utilizing the Time Zone Information Format. 698 8.1. application/tzif 700 Type name: application 702 Subtype name: tzif 704 Required parameters: none 706 Optional parameters: none 708 Encoding considerations: binary 710 Security considerations: See Section 6 of this document. 712 Interoperability considerations: See Section 4 of this document. 714 Published specification: This specification. 716 Applications that use this media type: This media type is designed 717 for widespread use by applications that need to use or exchange 718 time zone information, such as the Time Zone Information Compiler 719 (zic) [6] and the GNU C Library [7]. The Time Zone Distribution 720 Service [RFC7808] can directly use this media type. 722 Fragment identifier considerations: N/A 724 Additional information: 726 Magic number(s): The first 4 octets are 0x54, 0x5A, 0x69, 0x66 728 File extensions(s): N/A 730 Macintosh file type code(s): N/A 732 Person & email address to contact for further 733 information: 734 Time Zone Database mailing list 736 Intended usage: COMMON 738 Restrictions on usage: N/A 740 Author: See the "Author's Address" section of this document. 742 Change controller: IETF 744 8.2. application/tzif-leap 746 Type name: application 748 Subtype name: tzif-leap 750 Required parameters: none 752 Optional parameters: none 754 Encoding considerations: binary 756 Security considerations: See Section 6 of this document. 758 Interoperability considerations: See Section 4 of this document. 760 Published specification: This specification. 762 Applications that use this media type: This media type is designed 763 for widespread use by applications that need to use or exchange 764 time zone information, such as the Time Zone Information Compiler 765 (zic) [8] and the GNU C Library [9]. The Time Zone Distribution 766 Service [RFC7808] can directly use this media type. 768 Fragment identifier considerations: N/A 770 Additional information: 772 Magic number(s): The first 4 octets are 0x54, 0x5A, 0x69, 0x66 774 File extensions(s): N/A 776 Macintosh file type code(s): N/A 778 Person & email address to contact for further 779 information: 780 Time Zone Database mailing list 782 Intended usage: COMMON 784 Restrictions on usage: N/A 786 Author: See the "Author's Address" section of this document. 788 Change controller: IETF 790 9. Acknowledgments 792 The authors would like to thank the following individuals for 793 contributing their ideas and support for writing this specification: 794 Michael Douglass, Ned Freed, Guy Harris, Eliot Lear, and Alexey 795 Melnikov. 797 10. References 799 10.1. Normative References 801 [POSIX] IEEE, "Standard for Information Technology--Portable 802 Operating System Interface (POSIX(R)) Base Specifications, 803 Issue 7", IEEE 1003.1-2017, 804 DOI 10.1109/IEEESTD.2018.8277153, January 2018, 805 . 807 This standard is also 808 published by ieeexplore.ieee.org. 811 [RFC0020] Cerf, V., "ASCII format for network interchange", STD 80, 812 RFC 20, DOI 10.17487/RFC0020, October 1969, 813 . 815 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 816 Requirement Levels", BCP 14, RFC 2119, 817 DOI 10.17487/RFC2119, March 1997, 818 . 820 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 821 Specifications and Registration Procedures", BCP 13, 822 RFC 6838, DOI 10.17487/RFC6838, January 2013, 823 . 825 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 826 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 827 DOI 10.17487/RFC7231, June 2014, 828 . 830 [RFC7808] Douglass, M. and C. Daboo, "Time Zone Data Distribution 831 Service", RFC 7808, DOI 10.17487/RFC7808, March 2016, 832 . 834 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 835 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 836 May 2017, . 838 10.2. Informative References 840 [RFC5545] Desruisseaux, B., Ed., "Internet Calendaring and 841 Scheduling Core Object Specification (iCalendar)", 842 RFC 5545, DOI 10.17487/RFC5545, September 2009, 843 . 845 [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the 846 Time Zone Database", BCP 175, RFC 6557, 847 DOI 10.17487/RFC6557, February 2012, 848 . 850 [tz-link] Eggert, P. and A. Olson, "Sources for Time Zone and 851 Daylight Saving Time Data", 2018, 852 . 854 10.3. URIs 856 [1] https://tools.ietf.org/html/bcp14 858 [2] http://pubs.opengroup.org/onlinepubs/9699919799/functions/ 859 time.html 861 [3] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 862 V1_chap08.html#tag_08_03 864 [4] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 865 V1_chap08.html#tag_08_03 867 [5] http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ 868 V1_chap08.html#tag_08_03 870 [6] http://man7.org/linux/man-pages/man8/zic.8.html 872 [7] https://www.gnu.org/software/libc/ 874 [8] http://man7.org/linux/man-pages/man8/zic.8.html 876 [9] https://www.gnu.org/software/libc/ 878 Appendix A. Common Interoperability Issues 880 This section documents common problems in implementing this 881 specification. Most of these are problems in generating TZif files 882 for use by readers conforming to predecessors of this specification. 883 The goals of this section are: 885 1. to help TZif writers output files that avoid common pitfalls in 886 older or buggy TZif readers, 888 2. to help TZif readers avoid common pitfalls when reading files 889 generated by future TZif writers, and 891 3. to help any future specification authors see what sort of 892 problems arise when the TZif format is changed. 894 When new versions of the TZif format have been defined, a design goal 895 has been that a reader can successfully use a TZif file even if the 896 file is of a later TZif version than what the reader was designed 897 for. When complete compatibility was not achieved, an attempt was 898 made to limit glitches to rarely-used timestamps, and to allow simple 899 partial workarounds in writers designed to generate new-version data 900 useful even for older-version readers. This section attempts to 901 document these compatibility issues and workarounds, as well as to 902 document other common bugs in readers. 904 Interoperability problems with TZif include the following: 906 o Some readers examine only 32-bit data. As a partial workaround, a 907 writer can output as much 32-bit data as possible. However, a 908 reader should ignore 32-bit data, and should use 64-bit data even 909 if the reader's native timestamps have only 32 bits. 911 o Some readers designed for version 2 might mishandle timestamps 912 after a version 3 file's last transition, because they cannot 913 parse extensions to POSIX in the TZ-like string. As a partial 914 workaround, a writer can output more transitions than necessary, 915 so that only far-future timestamps are mishandled by version 2 916 readers. 918 o Some readers designed for version 2 do not support permanent 919 daylight saving time, e.g., a TZ string "EST5EDT,0/0,J365/25" 920 denoting permanent Eastern Daylight Time (-04). As a partial 921 workaround, a writer can substitute standard time for the next 922 time zone east, e.g., "AST4" for permanent Atlantic Standard Time 923 (-04). 925 o Some readers ignore the footer, and instead predict future 926 timestamps from the time type of the last transition. As a 927 partial workaround, a writer can output more transitions than 928 necessary. 930 o Some readers do not use time type 0 for timestamps before the 931 first transition, in that they infer a time type using a heuristic 932 that does not always select time type 0. As a partial workaround, 933 a writer can output a dummy (no-op) first transition at an early 934 time. 936 o Some readers mishandle timestamps before the first transition that 937 has a timestamp not less than -2**31. Readers that support only 938 32-bit timestamps are likely to be more prone to this problem, for 939 example, when they process 64-bit transitions only some of which 940 are representable in 32 bits. As a partial workaround, a writer 941 can output a dummy transition at timestamp -2**31. 943 o Some readers mishandle a transition if its timestamp has the 944 minimum possible signed 64-bit value. Timestamps less than -2**59 945 are not recommended. 947 o Some readers mishandle POSIX-style TZ strings that contain '<' or 948 '>'. As a partial workaround, a writer can avoid using '<' or '>' 949 for time zone abbreviations containing only alphabetic characters. 951 o Many readers mishandle time zone abbreviations that contain non- 952 ASCII characters. These characters are not recommended. 954 o Some readers may mishandle time zone abbreviations that contain 955 fewer than 3 or more than 6 characters, or that contain ASCII 956 characters other than alphanumerics, '-', and '+'. These 957 abbreviations are not recommended. 959 o Some readers mishandle TZif files that specify daylight-saving 960 time UT offsets that are less than the UT offsets for the 961 corresponding standard time. These readers do not support 962 locations like Ireland, which uses the equivalent of the POSIX TZ 963 string "IST-1GMT0,M10.5.0,M3.5.0/1", observing standard time (IST, 964 +01) in summer and daylight saving time (GMT, +00) in winter. As 965 a partial workaround, a writer can output data for the equivalent 966 of the POSIX TZ string "GMT0IST,M3.5.0/1,M10.5.0", thus swapping 967 standard and daylight saving time. Although this workaround 968 misidentifies which part of the year uses daylight saving time, it 969 records UT offsets and time zone abbreviations correctly. 971 Some interoperability problems are reader bugs that are listed here 972 mostly as warnings to developers of readers. 974 o Some readers do not support negative timestamps. Developers of 975 distributed applications should keep this in mind if they need to 976 deal with pre-1970 data. 978 o Some readers mishandle timestamps before the first transition that 979 has a nonnegative timestamp. Readers that do not support negative 980 timestamps are likely to be more prone to this problem. 982 o Some readers mishandle time zone abbreviations like "-08" that 983 contain '+', '-', or digits. 985 o Some readers mishandle UT offsets that are out of the traditional 986 range of -12 through +12 hours, and so do not support locations 987 like Kiritimati that are outside this range. 989 o Some readers mishandle UT offsets in the range [-3599, -1] seconds 990 from UT, because they integer-divide the offset by 3600 to get 0 991 and then display the hour part as "+00". 993 o Some readers mishandle UT offsets that are not a multiple of one 994 hour, or of 15 minutes, or of 1 minute. 996 Appendix B. Change History (To be removed by RFC Editor before 997 publication) 999 Changes since -13: 1001 o Added text to Privacy Considerations. 1003 Changes since -12: 1005 o Added reference to RFC0020. 1007 o Fully fleshed out application/tzif-leap declaration rather than 1008 referencing application/tzif. 1010 o Added definition for "Leap Second Correction". 1012 o Added external references directly to the relevant sections of 1013 POSIX. 1015 Changes since -11: 1017 o Removed text requiring leapcnt by non-zero for application/tzif- 1018 leap files. 1020 Changes since -10: 1022 o Removed text mandating all TZDIST features be supported. 1024 o Minor editorial changes. 1026 Changes since -09: 1028 o Removed "Update 7808" from header as this spec doesn't introduce 1029 new TZDIST functionality. 1031 o Added text regarding truncation of TZif via TZDIST. 1033 o Expanded what this spec DOESN'T define. 1035 o Added reasons for some of the recommended practices. 1037 o Added common interoperability issues appendix. 1039 o Minor editorial changes. 1041 Changes since -08: 1043 o Clarifying text regarding MIME types. 1045 o Consolidated/referenced duplicate security and interoperability 1046 text. 1048 o Switched to 'octets' instead of 'characters' when describing time 1049 zone designations. 1051 o Minor editorial changes. 1053 Changes since -07: 1055 o Clarifying text regarding TZ string. 1057 o Added "application/tzif-leap" MIME media type. 1059 o New reference for zic(8) man page. 1061 o Minor editorial changes. 1063 Changes since -06: 1065 o Added definition of UNIX Leap Time and used it to describe 1066 transition times and leap second occurrences. 1068 o Moved TZif generation recommendations into discussion of version 1069 field. 1071 o Repeated TZif generation recommendations in TZDIST section. 1073 o Rewrote part of the TZ string text. 1075 o Minor editorial changes. 1077 Changes since -05: 1079 o Clarify TAI, leap seconds, some descriptions, and some field 1080 values/ranges with text from Paul Eggert. 1082 o Refined MIME declaration based on feedback from Ned Freed. 1084 Changes since -04: 1086 o Edited text discussing timestamps before first and after last 1087 transition. 1089 o Specified legal range of time type indices and time zone 1090 designation indices. 1092 o Notes that corrections in adjacent leap second records must differ 1093 by one. 1095 o Added recommendations to eliminate unused space. 1097 o Minor editorial changes. 1099 Changes since -03: 1101 o Removed definition of GMT. 1103 o Updated definitions of UTC, TAI, and UT 1105 o Switched to using UT rather than UTC. 1107 o Added more text about the use of standard/wall and UT/local 1108 indicators. 1110 o Added Acknowledgments. 1112 o Minor editorial changes. 1114 Changes since -02: 1116 o Updated definitions of Standard Time and DST. 1118 o Added definitions of GMT and UT. 1120 o Added a definition of Time Zone Data from RFC7808. 1122 o Removed sentence stating that TZDB is accurate. 1124 o Added more text for standard/wall and UTC/local indicators and 1125 counts. 1127 o Added text discussing timestamps before first and after last 1128 transition. 1130 o Added more guidance text regarding 32-bit and 64-bit data 1131 consistency. 1133 o Minor editorial changes. 1135 Changes since -01: 1137 o Renamed "POSIX Time" to "UNIX Time" and noted that values can be 1138 negative. 1140 o Noted that signed values MUST be represented using two's 1141 complement. 1143 o Renamed "POSIX TZ string" to "TZ string" and noted that it can be 1144 empty. 1146 o Moved TZ string extensions into its own subsection with examples. 1148 o Renamed leap second "epoch" to "occurrence". 1150 o Editorial changes from Paul Eggert. 1152 Changes since -00: 1154 o Split TZif format description into a general overview and 3 1155 subsections. 1157 o Updated Keywords boilerplate. 1159 o Updated POSIX reference. 1161 o Editorial changes from Eliot Lear. 1163 Authors' Addresses 1165 Arthur David Olson 1167 Email: arthurdavidolson@gmail.com 1169 Paul Eggert 1170 University of California, Los Angeles 1172 Email: eggert@cs.ucla.edu 1174 Kenneth Murchison 1175 FastMail US LLC 1177 Email: murch@fastmailteam.com