idnits 2.17.1 draft-bormann-cbor-time-tag-02.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 (October 22, 2018) is 2014 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFCthis' is mentioned on line 246, but not defined == Unused Reference: 'IEEE1588-2008' is defined on line 281, but no explicit reference was found in the text == Unused Reference: 'RESOLUTION' is defined on line 288, but no explicit reference was found in the text == Outdated reference: A later version (-08) exists of draft-ietf-cbor-cddl-05 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-06) exists of draft-touch-time-04 Summary: 1 error (**), 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 Universitaet Bremen TZI 4 Intended status: Informational B. Gamari 5 Expires: April 25, 2019 Well-Typed 6 H. Birkholz 7 Fraunhofer SIT 8 October 22, 2018 10 Concise Binary Object Representation (CBOR) Tags for Time, Duration, and 11 Period 12 draft-bormann-cbor-time-tag-02 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, and 26 anticipates the definition of related CBOR tags for duration and time 27 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. The present version 38 -02 makes use of the IANA allocations registered. Further versions 39 will re-introduce some of the material from -00, but in a more 40 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 April 25, 2019. 59 Copyright Notice 61 Copyright (c) 2018 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 66 (https://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 77 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 78 1.2. Background . . . . . . . . . . . . . . . . . . . . . . . 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 4. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 5 85 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 86 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6 87 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 88 7.1. Normative References . . . . . . . . . . . . . . . . . . 7 89 7.2. Informative References . . . . . . . . . . . . . . . . . 8 90 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 8 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 93 1. Introduction 95 The Concise Binary Object Representation (CBOR, [RFC7049]) provides 96 for the interchange of structured data without a requirement for a 97 pre-agreed schema. RFC 7049 defines a basic set of data types, as 98 well as a tagging mechanism that enables extending the set of data 99 types supported via an IANA registry. 101 (TBD: Expand on text from abstract here.) 103 1.1. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in RFC 2119 [RFC2119]. 109 The term "byte" is used in its now customary sense as a synonym for 110 "octet". Where bit arithmetic is explained, this document uses the 111 notation familiar from the programming language C (including C++14's 112 0bnnn binary literals), except that the operator "**" stands for 113 exponentiation. 115 1.2. Background 117 Additional information about the complexities of time representation 118 can be found in [TIME]. This specification uses a number of terms 119 that should be familiar to connoisseurs of precise time; references 120 for these may need to be added. 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 o 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 Not currently addressed, but possibly covered by the definition of 134 additional map keys for the map inside the tag: 136 o Indication of time scale. Tags 0 and 1 are for UTC; however, some 137 interchanges are better performed on TAI. Other time scales may 138 be registered once they become relevant (e.g., one of the proposed 139 successors to UTC that might no longer use leap seconds, or a 140 scale based on smeared leap seconds). 142 o 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 o 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 might later be defined for duration and period. The 156 objectives for such duration and period tags are likely similar. 158 3. Time Format 160 An extended time is indicated by CBOR tag 1001, which tags a map data 161 item (CBOR major type 5). The map may contain integer (major types 0 162 and 1) or text string (major type 3) keys, with the value type 163 determined by each specific key. Implementations MUST ignore key/ 164 value types they do not understand for negative integer and text 165 string values of the key. Not understanding key/value for unsigned 166 keys is an error. 168 The map must contain exactly one unsigned integer key, which 169 specifies the "base time", and may also contain one or more negative 170 integer or text-string keys, which may encode supplementary 171 information such as: 173 o a higher precision time offset to be added to the base time, 175 Future keys may add: 177 o a reference time scale and epoch different from the default UTC 178 and 1970-01-01 180 o information about clock source and precision, accuracy, and 181 resolution 183 o intent information such as timezone and daylight savings time, 184 and/or possibly positioning coordinates, to express information 185 that would indicate a local time. 187 While this document does not define supplementary text keys, a number 188 of unsigned and negative-integer keys are defined below. 190 3.1. Key 1 192 Key 1 indicates a value that is exactly like the data item that would 193 be tagged by CBOR tag 1 (Posix time [TIME_T] as int or float). 195 3.2. Keys 4 and 5 197 Keys 4 and 5 are like key 1, except that the data item is an array as 198 defined for CBOR tag 4 or 5, respectively. This can be used to 199 include a Decimal or Bigfloat epoch-based float [TIME_T] in an 200 extended time. 202 3.3. Keys -3, -6, -9, -12, -15, -18 204 The keys -3, -6, -9, -12, -15 and -18 indicate additional decimal 205 fractions by giving an unsigned integer (major type 0) and scaling 206 this with the scale factor 1e-3, 1e-6, 1e-9, 1e-12, 1e-15, and 1e-18, 207 respectively (see Table 1). More than one of these keys MUST NOT be 208 present in one extended time data item. These additional fractions 209 are added to a base time in seconds [SI-SECOND] indicated by a Key 1, 210 which then MUST also be present and MUST have an integer value. 212 +-----+--------------+-----------------+ 213 | Key | meaning | example usage | 214 +-----+--------------+-----------------+ 215 | -3 | milliseconds | Java time | 216 | -6 | microseconds | (old) UNIX time | 217 | -9 | nanoseconds | (new) UNIX time | 218 | -12 | picoseconds | Haskell time | 219 | -15 | femtoseconds | (future) | 220 | -18 | attoseconds | (future) | 221 +-----+--------------+-----------------+ 223 Table 1: Key for decimally scaled Fractions 225 4. CDDL typenames 227 For the use with the CBOR Data Definition Language, CDDL 228 [I-D.ietf-cbor-cddl], the type names defined in Figure 1 are 229 recommended: 231 etime = #6.1001({* (int/tstr) => any}) 233 Figure 1: Recommended type names for CDDL 235 5. IANA Considerations 237 In the registry [IANA.cbor-tags], IANA has allocated the tags in 238 Table 2 from the FCFS space, with the present document as the 239 specification reference. 241 +------+-----------+-------------------------+ 242 | Tag | Data Item | Semantics | 243 +------+-----------+-------------------------+ 244 | 1001 | map | [RFCthis] extended time | 245 | 1002 | map | [RFCthis] duration | 246 | 1003 | map | [RFCthis] period | 247 +------+-----------+-------------------------+ 249 Table 2: Values for Tags 251 Although duration and period are not yet defined in the present 252 version of this document, the tag values for duration and period have 253 been requested at the same time as the value for extended time in 254 order to achieve allocation of all three values as a contiguous set. 256 6. Security Considerations 258 The security considerations of RFC 7049 apply; the tags introduced 259 here are not expected to raise security considerations beyond those. 261 Time, of course, has significant security considerations; these 262 include the exploitation of ambiguities where time is security 263 relevant (e.g., for freshness or in a validity span) or the 264 disclosure of characteristics of the emitting system (e.g., time 265 zone, or clock resolution and wall clock offset). 267 7. References 269 7.1. Normative References 271 [I-D.ietf-cbor-cddl] 272 Birkholz, H., Vigano, C., and C. Bormann, "Concise data 273 definition language (CDDL): a notational convention to 274 express CBOR and JSON data structures", draft-ietf-cbor- 275 cddl-05 (work in progress), August 2018. 277 [IANA.cbor-tags] 278 IANA, "Concise Binary Object Representation (CBOR) Tags", 279 . 281 [IEEE1588-2008] 282 IEEE, "1588-2008 - IEEE Standard for a Precision Clock 283 Synchronization Protocol for Networked Measurement and 284 Control Systems", July 2008, 285 . 288 [RESOLUTION] 289 The Open Group Base Specifications, "Vol. 1: Base 290 Definitions, Issue 7", Section 3.328 '(Time) Resolution', 291 IEEE Std 1003.1-2008, 2016 Edition, 2016, 292 . 295 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 296 Requirement Levels", BCP 14, RFC 2119, 297 DOI 10.17487/RFC2119, March 1997, 298 . 300 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 301 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 302 October 2013, . 304 [SI-SECOND] 305 International Organization for Standardization (ISO), 306 "Quantities and units -- Part 3: Space and time", 307 ISO 80000-3, March 2006. 309 [TIME_T] The Open Group Base Specifications, "Vol. 1: Base 310 Definitions, Issue 7", Section 4.15 'Seconds Since the 311 Epoch', IEEE Std 1003.1-2008, 2016 Edition, 2016, 312 . 315 7.2. Informative References 317 [TIME] Touch, J., "Resolving Multiple Time Scales in the 318 Internet", draft-touch-time-04 (work in progress), July 319 2018. 321 Acknowledgements 323 Authors' Addresses 325 Carsten Bormann 326 Universitaet Bremen TZI 327 Postfach 330440 328 Bremen D-28359 329 Germany 331 Phone: +49-421-218-63921 332 Email: cabo@tzi.org 334 Ben Gamari 335 Well-Typed 336 117 Middle Rd. 337 Portsmouth, NH 03801 338 United States 340 Email: ben@well-typed.com 342 Henk Birkholz 343 Fraunhofer Institute for Secure Information Technology 344 Rheinstrasse 75 345 Darmstadt 64295 346 Germany 348 Email: henk.birkholz@sit.fraunhofer.de