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