idnits 2.17.00 (12 Aug 2021) /tmp/idnits60750/draft-ietf-cbor-time-tag-00.txt: -(3): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding -(433): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 4 instances of lines with non-ascii characters in the document. 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 == Line 251 has weird spacing: '... utc ntp...' == Line 254 has weird spacing: '... tai gps...' == Line 295 has weird spacing: '... enum appr...' -- The document date (19 May 2021) is 360 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCthis' is mentioned on line 406, but not defined Summary: 0 errors (**), 0 flaws (~~), 6 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 Universität Bremen TZI 4 Intended status: Informational B. Gamari 5 Expires: 20 November 2021 Well-Typed 6 H. Birkholz 7 Fraunhofer SIT 8 19 May 2021 10 Concise Binary Object Representation (CBOR) Tags for Time, Duration, and 11 Period 12 draft-ietf-cbor-time-tag-00 14 Abstract 16 The Concise Binary Object Representation (CBOR, RFC 8949) 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 8949 defines two tags for time: CBOR tag 0 (RFC3339 time as a 23 string) and tag 1 (Posix time as int or float). Since then, 24 additional requirements have become known. The present document 25 defines a CBOR tag for time that allows a more elaborate 26 representation of time, as well as related CBOR tags for duration and 27 time period. It is intended as the reference document for the IANA 28 registration of the CBOR tags defined. 30 Note to Readers 32 Version -00 of the individual submission that led to the present 33 draft opened up the possibilities provided by extended 34 representations of time in CBOR. Version -01 consolidated this draft 35 to non-speculative content, the normative parts of which were 36 believed will stay unchanged during further development of the draft. 37 This version was provided to aid the registration of the CBOR tag 38 immediately needed. Further versions of the individual submission 39 made use of the IANA allocations registered and made other editorial 40 updates. Now a WG document, future versions could re-introduce some 41 of the material from the initial submission, but in a more concrete 42 form. 44 Status of This Memo 46 This Internet-Draft is submitted in full conformance with the 47 provisions of BCP 78 and BCP 79. 49 Internet-Drafts are working documents of the Internet Engineering 50 Task Force (IETF). Note that other groups may also distribute 51 working documents as Internet-Drafts. The list of current Internet- 52 Drafts is at https://datatracker.ietf.org/drafts/current/. 54 Internet-Drafts are draft documents valid for a maximum of six months 55 and may be updated, replaced, or obsoleted by other documents at any 56 time. It is inappropriate to use Internet-Drafts as reference 57 material or to cite them other than as "work in progress." 59 This Internet-Draft will expire on 20 November 2021. 61 Copyright Notice 63 Copyright (c) 2021 IETF Trust and the persons identified as the 64 document authors. All rights reserved. 66 This document is subject to BCP 78 and the IETF Trust's Legal 67 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 68 license-info) in effect on the date of publication of this document. 69 Please review these documents carefully, as they describe your rights 70 and restrictions with respect to this document. Code Components 71 extracted from this document must include Simplified BSD License text 72 as described in Section 4.e of the Trust Legal Provisions and are 73 provided without warranty as described in the Simplified BSD License. 75 Table of Contents 77 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 78 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 79 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3 80 3. Time Format . . . . . . . . . . . . . . . . . . . . . . . . . 4 81 3.1. Key 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 5 82 3.2. Keys 4 and 5 . . . . . . . . . . . . . . . . . . . . . . 5 83 3.3. Keys -3, -6, -9, -12, -15, -18 . . . . . . . . . . . . . 5 84 3.4. Key -1: Time Scale . . . . . . . . . . . . . . . . . . . 5 85 3.5. Clock Quality . . . . . . . . . . . . . . . . . . . . . . 6 86 3.5.1. ClockClass (Key -2) . . . . . . . . . . . . . . . . . 6 87 3.5.2. ClockAccuracy (Key -4) . . . . . . . . . . . . . . . 7 88 3.5.3. OffsetScaledLogVariance (Key -5) . . . . . . . . . . 7 89 3.5.4. Uncertainty (Key -7) . . . . . . . . . . . . . . . . 7 90 3.5.5. Guarantee (Key -8) . . . . . . . . . . . . . . . . . 7 91 4. Duration Format . . . . . . . . . . . . . . . . . . . . . . . 8 92 5. Period Format . . . . . . . . . . . . . . . . . . . . . . . . 8 93 6. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 9 94 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 10 98 9.2. Informative References . . . . . . . . . . . . . . . . . 11 99 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 11 100 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 102 1. Introduction 104 The Concise Binary Object Representation (CBOR, [RFC8949]) provides 105 for the interchange of structured data without a requirement for a 106 pre-agreed schema. RFC 8949 defines a basic set of data types, as 107 well as a tagging mechanism that enables extending the set of data 108 types supported via an IANA registry. 110 (TBD: Expand on text from abstract here.) 112 1.1. Terminology 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 116 "OPTIONAL" in this document are to be interpreted as described in 117 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 118 capitals, as shown here. 120 The term "byte" is used in its now customary sense as a synonym for 121 "octet". Where bit arithmetic is explained, this document uses the 122 notation familiar from the programming language C (including C++14's 123 0bnnn binary literals), except that the operator "**" stands for 124 exponentiation. 126 2. Objectives 128 For the time tag, the present specification addresses the following 129 objectives that go beyond the original tags 0 and 1: 131 * Additional resolution for epoch-based time (as in tag 1). CBOR 132 tag 1 only provides for integer and up to binary64 floating point 133 representation of times, limiting resolution to approximately 134 microseconds at the time of writing (and progressively becoming 135 worse over time). 137 * Indication of time scale. Tags 0 and 1 are for UTC; however, some 138 interchanges are better performed on TAI. Other time scales may 139 be registered once they become relevant (e.g., one of the proposed 140 successors to UTC that might no longer use leap seconds, or a 141 scale based on smeared leap seconds). 143 Not currently addressed, but possibly covered by the definition of 144 additional map keys for the map inside the tag: 146 * Direct representation of natural platform time formats. Some 147 platforms use epoch-based time formats that require some 148 computation to convert them into the representations allowed by 149 tag 1; these computations can also lose precision and cause 150 ambiguities. (TBD: The present specification does not take a 151 position on whether tag 1 can be "fixed" to include, e.g., Decimal 152 or BigFloat representations. It does define how to use these with 153 the extended time format.) 155 * Additional indication of intents about the interpretation of the 156 time given, in particular for future times. Intents might include 157 information about time zones, daylight savings times, etc. 159 Additional tags are defined for durations and periods. 161 3. Time Format 163 An extended time is indicated by CBOR tag 1001, which tags a map data 164 item (CBOR major type 5). The map may contain integer (major types 0 165 and 1) or text string (major type 3) keys, with the value type 166 determined by each specific key. Implementations MUST ignore key/ 167 value types they do not understand for negative integer and text 168 string values of the key. Not understanding key/value for unsigned 169 keys is an error. 171 The map must contain exactly one unsigned integer key, which 172 specifies the "base time", and may also contain one or more negative 173 integer or text-string keys, which may encode supplementary 174 information such as: 176 * a higher precision time offset to be added to the base time, 178 * a reference time scale and epoch different from the default UTC 179 and 1970-01-01 181 * information about clock quality parameters, such as source, 182 accuracy, and uncertainty 184 Future keys may add: 186 * intent information such as timezone and daylight savings time, 187 and/or possibly positioning coordinates, to express information 188 that would indicate a local time. 190 While this document does not define supplementary text keys, a number 191 of unsigned and negative-integer keys are defined below. 193 3.1. Key 1 195 Key 1 indicates a value that is exactly like the data item that would 196 be tagged by CBOR tag 1 (Posix time [TIME_T] as int or float). The 197 time value indicated by the value under this key can be further 198 modified by other keys. 200 3.2. Keys 4 and 5 202 Keys 4 and 5 are like key 1, except that the data item is an array as 203 defined for CBOR tag 4 or 5, respectively. This can be used to 204 include a Decimal or Bigfloat epoch-based float [TIME_T] in an 205 extended time. 207 3.3. Keys -3, -6, -9, -12, -15, -18 209 The keys -3, -6, -9, -12, -15 and -18 indicate additional decimal 210 fractions by giving an unsigned integer (major type 0) and scaling 211 this with the scale factor 1e-3, 1e-6, 1e-9, 1e-12, 1e-15, and 1e-18, 212 respectively (see Table 1). More than one of these keys MUST NOT be 213 present in one extended time data item. These additional fractions 214 are added to a base time in seconds [SI-SECOND] indicated by a Key 1, 215 which then MUST also be present and MUST have an integer value. 217 +=====+==============+=================+ 218 | Key | meaning | example usage | 219 +=====+==============+=================+ 220 | -3 | milliseconds | Java time | 221 +-----+--------------+-----------------+ 222 | -6 | microseconds | (old) UNIX time | 223 +-----+--------------+-----------------+ 224 | -9 | nanoseconds | (new) UNIX time | 225 +-----+--------------+-----------------+ 226 | -12 | picoseconds | Haskell time | 227 +-----+--------------+-----------------+ 228 | -15 | femtoseconds | (future) | 229 +-----+--------------+-----------------+ 230 | -18 | attoseconds | (future) | 231 +-----+--------------+-----------------+ 233 Table 1: Key for decimally scaled 234 Fractions 236 3.4. Key -1: Time Scale 238 Key -1 is used to indicate a time scale. The value 0 indicates UTC, 239 with the POSIX epoch [TIME_T]; the value 1 indicates TAI, with the 240 PTP (Precision Time Protocol) epoch [IEEE1588-2008]. 242 If key -1 is not present, time scale value 0 is implied. Additional 243 values can be registered in the (TBD define name for time scale 244 registry); values MUST be integers or text strings. 246 (Note that there should be no time scales "GPS" or "NTP" -- instead, 247 the time should be converted to TAI or UTC using a single addition or 248 subtraction.) 250 t = t - 2208988800 251 utc ntp 253 t = t + 315964819 254 tai gps 256 Figure 1: Converting Common Offset Time Scales 258 3.5. Clock Quality 260 A number of keys are defined to indicate the quality of clock that 261 was used to determine the point in time. 263 The first three are analogous to "clock-quality-grouping" in 264 [RFC8575], which is in turn based on the definitions in 265 [IEEE1588-2008]; two more are specific to this document. 267 ClockQuality-group = ( 268 ? ClockClass => uint .size 1 ; PTP/RFC8575 269 ? ClockAccuracy => uint .size 1 ; PTP/RFC8575 270 ? OffsetScaledLogVariance => uint .size 2 ; PTP/RFC8575 271 ? Uncertainty => ~time/~duration 272 ? Guarantee => ~time/~duration 273 ) 274 ClockClass = -2 275 ClockAccuracy = -4 276 OffsetScaledLogVariance = -5 277 Uncertainty = -7 278 Guarantee = -8 280 3.5.1. ClockClass (Key -2) 282 Key -2 (ClockClass) can be used to indicate the clock class as per 283 Table 5 of [IEEE1588-2008]. It is defined as a one-byte unsigned 284 integer as that is the range defined there. 286 3.5.2. ClockAccuracy (Key -4) 288 Key -4 (ClockAccuracy) can be used to indicate the clock accuracy as 289 per Table 6 of [IEEE1588-2008]. It is defined as a one-byte unsigned 290 integer as that is the range defined there. The range between 32 and 291 47 is a slightly distorted logarithmic scale from 25 ns to 1 s (see 292 Figure 2); the number 254 is the value to be used if an unknown 293 accuracy needs to be expressed. 295 enum approx48 + |_2cdotlog {accovers} - epsilon_| 296 acc 10 298 Figure 2: Approximate conversion from accuracy to accuracy 299 enumeration value 301 3.5.3. OffsetScaledLogVariance (Key -5) 303 Key -5 (OffsetScaledLogVariance) can be used to represent the 304 variance exhibited by the clock when it has lost its synchronization 305 with an external reference clock. The details for the computation of 306 this characteristic are defined in Section 7.6.3 of [IEEE1588-2008]. 308 3.5.4. Uncertainty (Key -7) 310 Key -7 (Uncertainty) can be used to represent a known measurement 311 uncertainty for the clock, as a numeric value in seconds or as a 312 duration (Section 4). 314 For this document, uncertainty is defined as in Section 2.2.3 of 315 [GUM]: "parameter, associated with the result of a measurement, that 316 characterizes the dispersion of the values that could reasonably be 317 attributed to the measurand". More specifically, the value for this 318 key represents the extended uncertainty for k = 2, in seconds. 320 3.5.5. Guarantee (Key -8) 322 Key -8 (Guarantee) can be used to represent a stated guarantee for 323 the accuracy of the point in time, as a numeric value in seconds or 324 as a duration (Section 4) representing the maximum allowed deviation 325 from the true value. 327 While such a guarantee is unattainable in theory, existing standards 328 such as [RFC3161] stipulate the representation of such guarantees, 329 and therefore this format provides a way to represent them as well; 330 the time value given is nominally guaranteed to not deviate from the 331 actual time by more than the value of the guarantee, in seconds. 333 4. Duration Format 335 A duration is the length of an interval of time. Durations in this 336 format are given in SI seconds, possibly adjusted for conventional 337 corrections of the time scale given (e.g., leap seconds). 339 Except for using Tag 1002 instead of 1001, durations are structurally 340 identical to time values. Semantically, they do not measure the time 341 elapsed from a given epoch, but from the start to the end of (an 342 otherwise unspecified) interval of time. 344 In combination with an epoch identified in the context, a duration 345 can also be used to express an absolute time. 347 | (TBD: Clearly, ISO8601 durations are rather different; we do 348 | not want to use these.) 350 5. Period Format 352 A period is a specific interval of time, specified as either two 353 times giving the start and the end of that interval, or as one of 354 these two plus a duration. 356 They are given as an array of unwrapped time and duration elements, 357 tagged with Tag 1003: 359 Period = #6.1003([ 360 start: ~Time / null 361 end: ~Time / null 362 ? duration: ~Duration / null 363 ]) 365 If the third array element is not given, the duration element is 366 null. Exactly two out of the three elements must be non-null, this 367 can be clumsily expressed in CDDL as: 369 Period = #6.1003([ 370 (start: ~Time, 371 ((end: ~Time, 372 ? duration: null) // 373 (end: null, 374 duration: ~Duration))) // 375 (start: null, 376 end: ~Time, 377 duration: ~Duration) 378 ]) 379 | (Issue: should start/end be given the two-element treatment, or 380 | start/duration?) 382 6. CDDL typenames 384 For the use with the CBOR Data Definition Language, CDDL [RFC8610], 385 the type names defined in Figure 3 are recommended: 387 etime = #6.1001({* (int/tstr) => any}) 388 duration = #6.1002({* (int/tstr) => any}) 389 period = #6.1003([~etime/null, ~etime/null, ~duration/null]) 391 Figure 3: Recommended type names for CDDL 393 7. IANA Considerations 395 In the registry [IANA.cbor-tags], IANA has allocated the tags in 396 Table 2 from the FCFS space, with the present document as the 397 specification reference. 399 +======+===========+=========================+ 400 | Tag | Data Item | Semantics | 401 +======+===========+=========================+ 402 | 1001 | map | [RFCthis] extended time | 403 +------+-----------+-------------------------+ 404 | 1002 | map | [RFCthis] duration | 405 +------+-----------+-------------------------+ 406 | 1003 | array | [RFCthis] period | 407 +------+-----------+-------------------------+ 409 Table 2: Values for Tags 411 IANA is requested to change the "Data Item" column for Tag 1003 from 412 "map" to "array". 414 | (TBD: Add registry for time scales. Add registry for map keys 415 | and allocation policies for additional keys.) 417 8. Security Considerations 419 The security considerations of RFC 8949 apply; the tags introduced 420 here are not expected to raise security considerations beyond those. 422 Time, of course, has significant security considerations; these 423 include the exploitation of ambiguities where time is security 424 relevant (e.g., for freshness or in a validity span) or the 425 disclosure of characteristics of the emitting system (e.g., time 426 zone, or clock resolution and wall clock offset). 428 9. References 430 9.1. Normative References 432 [GUM] Joint Committee for Guides in Metrology, "Evaluation of 433 measurement data — Guide to the expression of uncertainty 434 in measurement", JCGM 100:2008, September 2008, 435 . 437 [IANA.cbor-tags] 438 IANA, "Concise Binary Object Representation (CBOR) Tags", 439 . 441 [IEEE1588-2008] 442 IEEE, "1588-2008 - IEEE Standard for a Precision Clock 443 Synchronization Protocol for Networked Measurement and 444 Control Systems", July 2008, 445 . 448 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 449 Requirement Levels", BCP 14, RFC 2119, 450 DOI 10.17487/RFC2119, March 1997, 451 . 453 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 454 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 455 May 2017, . 457 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 458 Definition Language (CDDL): A Notational Convention to 459 Express Concise Binary Object Representation (CBOR) and 460 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 461 June 2019, . 463 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 464 Representation (CBOR)", STD 94, RFC 8949, 465 DOI 10.17487/RFC8949, December 2020, 466 . 468 [SI-SECOND] 469 International Organization for Standardization (ISO), 470 "Quantities and units — Part 3: Space and time", 471 ISO 80000-3, 1 March 2006. 473 [TIME_T] The Open Group Base Specifications, "Vol. 1: Base 474 Definitions, Issue 7", Section 4.15 'Seconds Since the 475 Epoch', IEEE Std 1003.1-2008, 2016 Edition, 2016, 476 . 479 9.2. Informative References 481 [RFC3161] Adams, C., Cain, P., Pinkas, D., and R. Zuccherato, 482 "Internet X.509 Public Key Infrastructure Time-Stamp 483 Protocol (TSP)", RFC 3161, DOI 10.17487/RFC3161, August 484 2001, . 486 [RFC8575] Jiang, Y., Ed., Liu, X., Xu, J., and R. Cummings, Ed., 487 "YANG Data Model for the Precision Time Protocol (PTP)", 488 RFC 8575, DOI 10.17487/RFC8575, May 2019, 489 . 491 Acknowledgements 493 Authors' Addresses 495 Carsten Bormann 496 Universität Bremen TZI 497 Postfach 330440 498 D-28359 Bremen 499 Germany 501 Phone: +49-421-218-63921 502 Email: cabo@tzi.org 504 Ben Gamari 505 Well-Typed 506 117 Middle Rd. 507 Portsmouth, NH 03801 508 United States 510 Email: ben@well-typed.com 512 Henk Birkholz 513 Fraunhofer Institute for Secure Information Technology 514 Rheinstrasse 75 515 64295 Darmstadt 516 Germany 518 Email: henk.birkholz@sit.fraunhofer.de