Network Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Informational B. Gamari Expires: September 13, 2017 Well-Typed H. Birkholz Fraunhofer SIT March 12, 2017 Concise Binary Object Representation (CBOR) Tags for Time, Duration, and Period draft-bormann-cbor-time-tag-00 Abstract The Concise Binary Object Representation (CBOR, RFC 7049) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. In CBOR, one point of extensibility is the definition of CBOR tags. RFC 7049 defines two tags for time: CBOR tag 0 (RFC3339 time) and tag 1 (Posix time [TIME_T], int or float). Since then, additional requirements have become known. The present document defines a CBOR tag for time that allows a more elaborate representation of time, as well as CBOR tags for duration and time period. It is intended as the reference document for the IANA registration of the CBOR tags defined. 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 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 September 13, 2017. Bormann, et al. Expires September 13, 2017 [Page 1] Internet-Draft CBOR tag for extended time March 2017 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 (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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Background . . . . . . . . . . . . . . . . . . . . . . . 3 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Time Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Keys 0 and 1 . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Keys 4 and 5 . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Keys -3, -6, -9, -12 . . . . . . . . . . . . . . . . . . 5 3.4. Key -1 . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.5. Key -2 . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.6. Key -4 . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.7. Key -5 . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.8. Key -7 . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.9. Key -8 . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.10. Key -10 . . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Duration Format . . . . . . . . . . . . . . . . . . . . . . . 7 5. Period Format . . . . . . . . . . . . . . . . . . . . . . . . 7 6. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 7 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 9.2. Informative References . . . . . . . . . . . . . . . . . 10 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 1. Introduction The Concise Binary Object Representation (CBOR, [RFC7049]) provides for the interchange of structured data without a requirement for a pre-agreed schema. RFC 7049 defines a basic set of data types, as Bormann, et al. Expires September 13, 2017 [Page 2] Internet-Draft CBOR tag for extended time March 2017 well as a tagging mechanism that enables extending the set of data types supported via an IANA registry. (TBD: Expand on text from abstract here.) 1.1. Terminology 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 RFC 2119 [RFC2119]. The term "byte" is used in its now customary sense as a synonym for "octet". Where bit arithmetic is explained, this document uses the notation familiar from the programming language C (including C++14's 0bnnn binary literals), except that the operator "**" stands for exponentiation. 1.2. Background Additional information about the complexities of time representation can be found in [TIME]. This specification uses a number of terms that should be familiar to connoisseurs of precise time; references for these may need to be added. 2. Objectives For the time tag, the present specification addresses the following objectives that go beyond the original tags 0 and 1: o Indication of time scale. Tags 0 and 1 are for UTC; however, some interchanges are better performed on TAI. Other time scales may be registered once they become relevant (e.g., one of the proposed successors to UTC that might no longer use leap seconds, or a scale based on smeared leap seconds). o Additional resolution for epoch-based time (as in tag 1). CBOR tag 1 only provides for integer and up to binary64 floating point representation of times, limiting resolution to approximately microseconds at the time of writing (and progressively becoming worse over time). o Direct representation of natural platform time formats. Some platforms use epoch-based time formats that require some computation to convert them into the representations allowed by tag 1; these computations can also lose precision and cause ambiguities. (TBD: The present specification does not take a position on whether tag 1 can be "fixed" to include, e.g., Decimal Bormann, et al. Expires September 13, 2017 [Page 3] Internet-Draft CBOR tag for extended time March 2017 or BigFloat representations. It does define how to use these with the extended time format.) o Additional indication of intents about the interpretation of the time given, in particular for future times. Intents might include information about time zones, daylight savings times, etc. (TBD: This is not yet a well-developed part of the spec; there needs to be some effort to avoid the kitchen sink.) The objectives for the duration and period tags are similar. 3. Time Format An extended time is indicated by CBOR tag TBDET, which tags a map data item (CBOR major type 5). The map may contain integer (major types 0 and 1) or text string (major type 3) keys, with the value type determined by each specific key. Implementations MUST ignore key/value types they do not understand. (Discussion: Do we need "critical" keys?) The map must contain exactly one unsigned integer key, which specifies the "base time", and may also contain one or more negative integer or text-string keys, which may encode supplementary information such as, o a higher precision time offset to be added to the base time, o a reference time scale, o information about clock source and precision, accuracy, and resolution o intent information such as timezone and daylight savings time, and/or possibly positioning coordinates, to express information that would indicate a local time. While this document does not define supplementary text keys, a number of unsigned and negative-integer keys are defined below. 3.1. Keys 0 and 1 Keys 0 and 1 indicate values that are exactly like the data items that would be tagged by CBOR tag 0 (RFC 3339 date/time string) or tag 1 (Posix time [TIME_T] as int or float), respectively. Bormann, et al. Expires September 13, 2017 [Page 4] Internet-Draft CBOR tag for extended time March 2017 3.2. Keys 4 and 5 Keys 4 and 5 are like key 1, except that the data item is an array as defined for CBOR tag 4 or 5, respectively. This can be used to include a Decimal or Bigfloat epoch-based float [TIME_T] in an extended time. 3.3. Keys -3, -6, -9, -12 The keys -3, -6, -9, -12 indicate additional decimal fractions by giving an unsigned integer (major type 0) and scaling this with the scale factor 1e-3, 1e-6, 1e-9, and 1e-12, respectively (see Table 1). More than one of these keys MUST NOT be present in one extended time data item. These additional fractions are added to a base time in seconds [SI-SECOND] indicated by a Key 1, which then MUST also be present and MUST have an integer value. +-----+--------------+-----------------+ | Key | meaning | example usage | +-----+--------------+-----------------+ | -3 | milliseconds | Java time | | -6 | microseconds | (old) UNIX time | | -9 | nanoseconds | (new) UNIX time | | -12 | picoseconds | Haskell time | +-----+--------------+-----------------+ Table 1: Key for decimally scaled Fractions 3.4. Key -1 Key -1 is used to indicate a time scale. The value 0 indicates UTC, the value 1 indicates TAI. If key -1 is not present, time scale value 0 is implied. Additional values can be registered in the (TBD define name for time scale registry); values MUST be integers or text strings. (Note that there should be no time scale "GPS" - instead, the time should be converted to TAI using a single subtraction.) 3.5. Key -2 Key -2 can be used to indicate the quality of the point in time: The value 0 indicates a time obtained from a clock (past or "current" time). The value -1 indicates a future time that has been scheduled by a human. The value 1 indicates a time derived from a time obtained from a clock (such as the timestamp of a record in a log file). (TBD: Is this well-defined enough? What other cases should be considered here?) Bormann, et al. Expires September 13, 2017 [Page 5] Internet-Draft CBOR tag for extended time March 2017 If key -2 is not present, no information is available about the quality of the time. 3.6. Key -4 Key -4 can be used to indicate the resolution of the time provided [RESOLUTION]: "The minimum time interval that a clock can measure or whose passage a timer can detect." The value is expressed in SI seconds [SI-SECOND] and can be any positive number, such as an integer, a floating point value (major type 7 or Tag 5), or a decimal value (Tag 4). 3.7. Key -5 Key -5 can be used to indicate the accuracy of the time [IEEE1588-2008]: "The mean of the time or frequency error between the clock under test and a perfect reference clock, over an ensemble of measurements." The value is expressed in SI seconds [SI-SECOND] and can be any positive number, such as an integer, a floating point value (major type 7 or Tag 5), or a decimal value (Tag 4). (This could be extended into more information about the way the clock source is synchronized, e.g. manually, GPS, NTP, PTP, roughtime, ...) 3.8. Key -7 Key -7 can be used to indicate the time zone that would best fit for displaying the time given to humans. (TBD: Format for the time zone information; possibly including DST information. No default; generally, the time can by default be presented as UTC/"Zulu time".) 3.9. Key -8 Key -8 can be used to indicate the location in which the time given should be interpreted (e.g., for deriving time zone information). (TBD: Format for the coordinate information; may need to contain the Datum information.) 3.10. Key -10 Key -10 can be used to indicate the calendar that would best fit for displaying the time given to humans. (TBD: Format for the calendar information. This should probably default to Gregorian.) Bormann, et al. Expires September 13, 2017 [Page 6] Internet-Draft CBOR tag for extended time March 2017 4. Duration Format (TBD; this can probably use most of the same keys as for time. Clearly, ISO8601 durations are a bit different.) 5. Period Format (TBD; this could be a pair of times, a time and a duration, a duration and a time or v.v., or a RFC 3339 period.) 6. CDDL typenames For the use with the CBOR Data Definition Language, CDDL [I-D.greevenbosch-appsawg-cbor-cddl], the type names defined in Figure 1 are recommended: etime = #6.TBDET({* (int/tstr) => any}) duration = #6.TBDED({* (int/tstr) => any}) period = #6.TBDEP({* (int/tstr) => any}) ; ? Figure 1: Recommended type names for CDDL 7. IANA Considerations IANA is requested to allocate the tags in Table 2, with the present document as the specification reference. +-------+-----------+-------------------------+ | Tag | Data Item | Semantics | +-------+-----------+-------------------------+ | TBDET | map | [RFCthis] extended time | | TBDED | map | [RFCthis] duration | | TBDEP | map (?) | [RFCthis] period | +-------+-----------+-------------------------+ Table 2: Values for Tags (TBD: Add registry for time scales. Add registry for map keys and allocation policies for additional keys.) RFC editor note: Please replace TBDET, TBDED, and TBDEP by the tag numbers allocated by IANA throughout the document and delete this note. Bormann, et al. Expires September 13, 2017 [Page 7] Internet-Draft CBOR tag for extended time March 2017 8. Security Considerations The security considerations of RFC 7049 apply; the tags introduced here are not expected to raise security considerations beyond those. Time, of course, has significant security considerations; these include the exploitation of ambiguities where time is security relevant (e.g., for freshness or in a validity span) or the disclosure of characteristics of the emitting system (e.g., time zone, or clock resolution and wall clock offset). Bormann, et al. Expires September 13, 2017 [Page 8] Internet-Draft CBOR tag for extended time March 2017 9. References 9.1. Normative References [I-D.greevenbosch-appsawg-cbor-cddl] Vigano, C. and H. Birkholz, "CBOR data definition language (CDDL): a notational convention to express CBOR data structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work in progress), September 2016. [IEEE1588-2008] IEEE, "1588-2008 - IEEE Standard for a Precision Clock Synchronization Protocol for Networked Measurement and Control Systems", July 2008, . [RESOLUTION] The Open Group Base Specifications, "Vol. 1: Base Definitions, Issue 7", Section 3.328 '(Time) Resolution', IEEE Std 1003.1-2008, 2016 Edition, 2016, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, . [SI-SECOND] International Organization for Standardization (ISO), "Quantities and units -- Part 3: Space and time", ISO 80000-3, March 2006. [TIME_T] The Open Group Base Specifications, "Vol. 1: Base Definitions, Issue 7", Section 4.15 'Seconds Since the Epoch', IEEE Std 1003.1-2008, 2016 Edition, 2016, . Bormann, et al. Expires September 13, 2017 [Page 9] Internet-Draft CBOR tag for extended time March 2017 9.2. Informative References [TIME] Touch, J., "... time ...", unpublished manuscript, n.d.. Acknowledgements Authors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Ben Gamari Well-Typed Henk Birkholz Fraunhofer Institute for Secure Information Technology Rheinstrasse 75 Darmstadt 64295 Germany Email: henk.birkholz@sit.fraunhofer.de Bormann, et al. Expires September 13, 2017 [Page 10]