idnits 2.17.1 draft-bormann-cbor-time-tag-00.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 date (March 12, 2017) is 2601 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCthis' is mentioned on line 311, but not defined == Outdated reference: A later version (-11) exists of draft-greevenbosch-appsawg-cbor-cddl-09 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Informational B. Gamari 5 Expires: September 13, 2017 Well-Typed 6 H. Birkholz 7 Fraunhofer SIT 8 March 12, 2017 10 Concise Binary Object Representation (CBOR) Tags for Time, Duration, and 11 Period 12 draft-bormann-cbor-time-tag-00 14 Abstract 16 The Concise Binary Object Representation (CBOR, RFC 7049) is a data 17 format whose design goals include the possibility of extremely small 18 code size, fairly small message size, and extensibility without the 19 need for version negotiation. 21 In CBOR, one point of extensibility is the definition of CBOR tags. 22 RFC 7049 defines two tags for time: CBOR tag 0 (RFC3339 time) and tag 23 1 (Posix time [TIME_T], int or float). Since then, additional 24 requirements have become known. The present document defines a CBOR 25 tag for time that allows a more elaborate representation of time, as 26 well as CBOR tags for duration and time period. It is intended as 27 the reference document for the IANA registration of the CBOR tags 28 defined. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on September 13, 2017. 47 Copyright Notice 49 Copyright (c) 2017 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.2. Background . . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 68 3. Time Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 3.1. Keys 0 and 1 . . . . . . . . . . . . . . . . . . . . . . 4 70 3.2. Keys 4 and 5 . . . . . . . . . . . . . . . . . . . . . . 5 71 3.3. Keys -3, -6, -9, -12 . . . . . . . . . . . . . . . . . . 5 72 3.4. Key -1 . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3.5. Key -2 . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 3.6. Key -4 . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 3.7. Key -5 . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 3.8. Key -7 . . . . . . . . . . . . . . . . . . . . . . . . . 6 77 3.9. Key -8 . . . . . . . . . . . . . . . . . . . . . . . . . 6 78 3.10. Key -10 . . . . . . . . . . . . . . . . . . . . . . . . . 6 79 4. Duration Format . . . . . . . . . . . . . . . . . . . . . . . 7 80 5. Period Format . . . . . . . . . . . . . . . . . . . . . . . . 7 81 6. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 7 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 83 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 84 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 85 9.1. Normative References . . . . . . . . . . . . . . . . . . 9 86 9.2. Informative References . . . . . . . . . . . . . . . . . 10 87 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 10 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 90 1. Introduction 92 The Concise Binary Object Representation (CBOR, [RFC7049]) provides 93 for the interchange of structured data without a requirement for a 94 pre-agreed schema. RFC 7049 defines a basic set of data types, as 95 well as a tagging mechanism that enables extending the set of data 96 types supported via an IANA registry. 98 (TBD: Expand on text from abstract here.) 100 1.1. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in RFC 2119 [RFC2119]. 106 The term "byte" is used in its now customary sense as a synonym for 107 "octet". Where bit arithmetic is explained, this document uses the 108 notation familiar from the programming language C (including C++14's 109 0bnnn binary literals), except that the operator "**" stands for 110 exponentiation. 112 1.2. Background 114 Additional information about the complexities of time representation 115 can be found in [TIME]. This specification uses a number of terms 116 that should be familiar to connoisseurs of precise time; references 117 for these may need to be added. 119 2. Objectives 121 For the time tag, the present specification addresses the following 122 objectives that go beyond the original tags 0 and 1: 124 o Indication of time scale. Tags 0 and 1 are for UTC; however, some 125 interchanges are better performed on TAI. Other time scales may 126 be registered once they become relevant (e.g., one of the proposed 127 successors to UTC that might no longer use leap seconds, or a 128 scale based on smeared leap seconds). 130 o Additional resolution for epoch-based time (as in tag 1). CBOR 131 tag 1 only provides for integer and up to binary64 floating point 132 representation of times, limiting resolution to approximately 133 microseconds at the time of writing (and progressively becoming 134 worse over time). 136 o Direct representation of natural platform time formats. Some 137 platforms use epoch-based time formats that require some 138 computation to convert them into the representations allowed by 139 tag 1; these computations can also lose precision and cause 140 ambiguities. (TBD: The present specification does not take a 141 position on whether tag 1 can be "fixed" to include, e.g., Decimal 142 or BigFloat representations. It does define how to use these with 143 the extended time format.) 145 o Additional indication of intents about the interpretation of the 146 time given, in particular for future times. Intents might include 147 information about time zones, daylight savings times, etc. (TBD: 148 This is not yet a well-developed part of the spec; there needs to 149 be some effort to avoid the kitchen sink.) 151 The objectives for the duration and period tags are similar. 153 3. Time Format 155 An extended time is indicated by CBOR tag TBDET, which tags a map 156 data item (CBOR major type 5). The map may contain integer (major 157 types 0 and 1) or text string (major type 3) keys, with the value 158 type determined by each specific key. Implementations MUST ignore 159 key/value types they do not understand. (Discussion: Do we need 160 "critical" keys?) 162 The map must contain exactly one unsigned integer key, which 163 specifies the "base time", and may also contain one or more negative 164 integer or text-string keys, which may encode supplementary 165 information such as, 167 o a higher precision time offset to be added to the base time, 169 o a reference time scale, 171 o information about clock source and precision, accuracy, and 172 resolution 174 o intent information such as timezone and daylight savings time, 175 and/or possibly positioning coordinates, to express information 176 that would indicate a local time. 178 While this document does not define supplementary text keys, a number 179 of unsigned and negative-integer keys are defined below. 181 3.1. Keys 0 and 1 183 Keys 0 and 1 indicate values that are exactly like the data items 184 that would be tagged by CBOR tag 0 (RFC 3339 date/time string) or tag 185 1 (Posix time [TIME_T] as int or float), respectively. 187 3.2. Keys 4 and 5 189 Keys 4 and 5 are like key 1, except that the data item is an array as 190 defined for CBOR tag 4 or 5, respectively. This can be used to 191 include a Decimal or Bigfloat epoch-based float [TIME_T] in an 192 extended time. 194 3.3. Keys -3, -6, -9, -12 196 The keys -3, -6, -9, -12 indicate additional decimal fractions by 197 giving an unsigned integer (major type 0) and scaling this with the 198 scale factor 1e-3, 1e-6, 1e-9, and 1e-12, respectively (see Table 1). 199 More than one of these keys MUST NOT be present in one extended time 200 data item. These additional fractions are added to a base time in 201 seconds [SI-SECOND] indicated by a Key 1, which then MUST also be 202 present and MUST have an integer value. 204 +-----+--------------+-----------------+ 205 | Key | meaning | example usage | 206 +-----+--------------+-----------------+ 207 | -3 | milliseconds | Java time | 208 | -6 | microseconds | (old) UNIX time | 209 | -9 | nanoseconds | (new) UNIX time | 210 | -12 | picoseconds | Haskell time | 211 +-----+--------------+-----------------+ 213 Table 1: Key for decimally scaled Fractions 215 3.4. Key -1 217 Key -1 is used to indicate a time scale. The value 0 indicates UTC, 218 the value 1 indicates TAI. If key -1 is not present, time scale 219 value 0 is implied. Additional values can be registered in the (TBD 220 define name for time scale registry); values MUST be integers or text 221 strings. 223 (Note that there should be no time scale "GPS" - instead, the time 224 should be converted to TAI using a single subtraction.) 226 3.5. Key -2 228 Key -2 can be used to indicate the quality of the point in time: The 229 value 0 indicates a time obtained from a clock (past or "current" 230 time). The value -1 indicates a future time that has been scheduled 231 by a human. The value 1 indicates a time derived from a time 232 obtained from a clock (such as the timestamp of a record in a log 233 file). (TBD: Is this well-defined enough? What other cases should 234 be considered here?) 235 If key -2 is not present, no information is available about the 236 quality of the time. 238 3.6. Key -4 240 Key -4 can be used to indicate the resolution of the time provided 241 [RESOLUTION]: "The minimum time interval that a clock can measure or 242 whose passage a timer can detect." The value is expressed in SI 243 seconds [SI-SECOND] and can be any positive number, such as an 244 integer, a floating point value (major type 7 or Tag 5), or a decimal 245 value (Tag 4). 247 3.7. Key -5 249 Key -5 can be used to indicate the accuracy of the time 250 [IEEE1588-2008]: "The mean of the time or frequency error between the 251 clock under test and a perfect reference clock, over an ensemble of 252 measurements." The value is expressed in SI seconds [SI-SECOND] and 253 can be any positive number, such as an integer, a floating point 254 value (major type 7 or Tag 5), or a decimal value (Tag 4). 256 (This could be extended into more information about the way the clock 257 source is synchronized, e.g. manually, GPS, NTP, PTP, roughtime, ...) 259 3.8. Key -7 261 Key -7 can be used to indicate the time zone that would best fit for 262 displaying the time given to humans. (TBD: Format for the time zone 263 information; possibly including DST information. No default; 264 generally, the time can by default be presented as UTC/"Zulu time".) 266 3.9. Key -8 268 Key -8 can be used to indicate the location in which the time given 269 should be interpreted (e.g., for deriving time zone information). 270 (TBD: Format for the coordinate information; may need to contain the 271 Datum information.) 273 3.10. Key -10 275 Key -10 can be used to indicate the calendar that would best fit for 276 displaying the time given to humans. (TBD: Format for the calendar 277 information. This should probably default to Gregorian.) 279 4. Duration Format 281 (TBD; this can probably use most of the same keys as for time. 282 Clearly, ISO8601 durations are a bit different.) 284 5. Period Format 286 (TBD; this could be a pair of times, a time and a duration, a 287 duration and a time or v.v., or a RFC 3339 period.) 289 6. CDDL typenames 291 For the use with the CBOR Data Definition Language, CDDL 292 [I-D.greevenbosch-appsawg-cbor-cddl], the type names defined in 293 Figure 1 are recommended: 295 etime = #6.TBDET({* (int/tstr) => any}) 296 duration = #6.TBDED({* (int/tstr) => any}) 297 period = #6.TBDEP({* (int/tstr) => any}) ; ? 299 Figure 1: Recommended type names for CDDL 301 7. IANA Considerations 303 IANA is requested to allocate the tags in Table 2, with the present 304 document as the specification reference. 306 +-------+-----------+-------------------------+ 307 | Tag | Data Item | Semantics | 308 +-------+-----------+-------------------------+ 309 | TBDET | map | [RFCthis] extended time | 310 | TBDED | map | [RFCthis] duration | 311 | TBDEP | map (?) | [RFCthis] period | 312 +-------+-----------+-------------------------+ 314 Table 2: Values for Tags 316 (TBD: Add registry for time scales. Add registry for map keys and 317 allocation policies for additional keys.) 319 RFC editor note: Please replace TBDET, TBDED, and TBDEP by the tag 320 numbers allocated by IANA throughout the document and delete this 321 note. 323 8. Security Considerations 325 The security considerations of RFC 7049 apply; the tags introduced 326 here are not expected to raise security considerations beyond those. 328 Time, of course, has significant security considerations; these 329 include the exploitation of ambiguities where time is security 330 relevant (e.g., for freshness or in a validity span) or the 331 disclosure of characteristics of the emitting system (e.g., time 332 zone, or clock resolution and wall clock offset). 334 9. References 336 9.1. Normative References 338 [I-D.greevenbosch-appsawg-cbor-cddl] 339 Vigano, C. and H. Birkholz, "CBOR data definition language 340 (CDDL): a notational convention to express CBOR data 341 structures", draft-greevenbosch-appsawg-cbor-cddl-09 (work 342 in progress), September 2016. 344 [IEEE1588-2008] 345 IEEE, "1588-2008 - IEEE Standard for a Precision Clock 346 Synchronization Protocol for Networked Measurement and 347 Control Systems", July 2008, 348 . 351 [RESOLUTION] 352 The Open Group Base Specifications, "Vol. 1: Base 353 Definitions, Issue 7", Section 3.328 '(Time) Resolution', 354 IEEE Std 1003.1-2008, 2016 Edition, 2016, 355 . 358 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 359 Requirement Levels", BCP 14, RFC 2119, 360 DOI 10.17487/RFC2119, March 1997, 361 . 363 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 364 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 365 October 2013, . 367 [SI-SECOND] 368 International Organization for Standardization (ISO), 369 "Quantities and units -- Part 3: Space and time", 370 ISO 80000-3, March 2006. 372 [TIME_T] The Open Group Base Specifications, "Vol. 1: Base 373 Definitions, Issue 7", Section 4.15 'Seconds Since the 374 Epoch', IEEE Std 1003.1-2008, 2016 Edition, 2016, 375 . 378 9.2. Informative References 380 [TIME] Touch, J., "... time ...", unpublished manuscript, n.d.. 382 Acknowledgements 384 Authors' Addresses 386 Carsten Bormann 387 Universitaet Bremen TZI 388 Postfach 330440 389 Bremen D-28359 390 Germany 392 Phone: +49-421-218-63921 393 Email: cabo@tzi.org 395 Ben Gamari 396 Well-Typed 398 Henk Birkholz 399 Fraunhofer Institute for Secure Information Technology 400 Rheinstrasse 75 401 Darmstadt 64295 402 Germany 404 Email: henk.birkholz@sit.fraunhofer.de