Internet-Draft | CBOR tag for extended time | May 2021 |
Bormann, et al. | Expires 20 November 2021 | [Page] |
The Concise Binary Object Representation (CBOR, RFC 8949) 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 8949 defines two tags for time: CBOR tag 0 (RFC3339 time as a string) and tag 1 (Posix time as 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 related CBOR tags for duration and time period. It is intended as the reference document for the IANA registration of the CBOR tags defined.¶
Version -00 of the individual submission that led to the present draft opened up the possibilities provided by extended representations of time in CBOR. Version -01 consolidated this draft to non-speculative content, the normative parts of which were believed will stay unchanged during further development of the draft. This version was provided to aid the registration of the CBOR tag immediately needed. Further versions of the individual submission made use of the IANA allocations registered and made other editorial updates. Now a WG document, future versions could re-introduce some of the material from the initial submission, but in a more concrete form.¶
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 https://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 20 November 2021.¶
Copyright (c) 2021 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 (https://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.¶
The Concise Binary Object Representation (CBOR, [RFC8949]) provides for the interchange of structured data without a requirement for a pre-agreed schema. RFC 8949 defines a basic set of data types, as 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.)¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
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.¶
For the time tag, the present specification addresses the following objectives that go beyond the original tags 0 and 1:¶
Not currently addressed, but possibly covered by the definition of additional map keys for the map inside the tag:¶
Additional tags are defined for durations and periods.¶
An extended time is indicated by CBOR tag 1001, 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 for negative integer and text string values of the key. Not understanding key/value for unsigned keys is an error.¶
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:¶
Future keys may add:¶
While this document does not define supplementary text keys, a number of unsigned and negative-integer keys are defined below.¶
Key 1 indicates a value that is exactly like the data item that would be tagged by CBOR tag 1 (Posix time [TIME_T] as int or float). The time value indicated by the value under this key can be further modified by other keys.¶
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.¶
The keys -3, -6, -9, -12, -15 and -18 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, 1e-12, 1e-15, and 1e-18, 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 |
-15 | femtoseconds | (future) |
-18 | attoseconds | (future) |
Key -1 is used to indicate a time scale. The value 0 indicates UTC, with the POSIX epoch [TIME_T]; the value 1 indicates TAI, with the PTP (Precision Time Protocol) epoch [IEEE1588-2008].¶
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 scales "GPS" or "NTP" -- instead, the time should be converted to TAI or UTC using a single addition or subtraction.)¶
A number of keys are defined to indicate the quality of clock that was used to determine the point in time.¶
The first three are analogous to clock-quality-grouping
in
[RFC8575], which is in turn based on the definitions in
[IEEE1588-2008]; two more are specific to this document.¶
ClockQuality-group = ( ? ClockClass => uint .size 1 ; PTP/RFC8575 ? ClockAccuracy => uint .size 1 ; PTP/RFC8575 ? OffsetScaledLogVariance => uint .size 2 ; PTP/RFC8575 ? Uncertainty => ~time/~duration ? Guarantee => ~time/~duration ) ClockClass = -2 ClockAccuracy = -4 OffsetScaledLogVariance = -5 Uncertainty = -7 Guarantee = -8¶
Key -2 (ClockClass) can be used to indicate the clock class as per Table 5 of [IEEE1588-2008]. It is defined as a one-byte unsigned integer as that is the range defined there.¶
Key -4 (ClockAccuracy) can be used to indicate the clock accuracy as per Table 6 of [IEEE1588-2008]. It is defined as a one-byte unsigned integer as that is the range defined there. The range between 32 and 47 is a slightly distorted logarithmic scale from 25 ns to 1 s (see Figure 2); the number 254 is the value to be used if an unknown accuracy needs to be expressed.¶
Key -5 (OffsetScaledLogVariance) can be used to represent the variance exhibited by the clock when it has lost its synchronization with an external reference clock. The details for the computation of this characteristic are defined in Section 7.6.3 of [IEEE1588-2008].¶
Key -7 (Uncertainty) can be used to represent a known measurement uncertainty for the clock, as a numeric value in seconds or as a duration (Section 4).¶
For this document, uncertainty is defined as in Section 2.2.3 of [GUM]: "parameter, associated with the result of a measurement, that characterizes the dispersion of the values that could reasonably be attributed to the measurand". More specifically, the value for this key represents the extended uncertainty for k = 2, in seconds.¶
Key -8 (Guarantee) can be used to represent a stated guarantee for the accuracy of the point in time, as a numeric value in seconds or as a duration (Section 4) representing the maximum allowed deviation from the true value.¶
While such a guarantee is unattainable in theory, existing standards such as [RFC3161] stipulate the representation of such guarantees, and therefore this format provides a way to represent them as well; the time value given is nominally guaranteed to not deviate from the actual time by more than the value of the guarantee, in seconds.¶
A duration is the length of an interval of time. Durations in this format are given in SI seconds, possibly adjusted for conventional corrections of the time scale given (e.g., leap seconds).¶
Except for using Tag 1002 instead of 1001, durations are structurally identical to time values. Semantically, they do not measure the time elapsed from a given epoch, but from the start to the end of (an otherwise unspecified) interval of time.¶
In combination with an epoch identified in the context, a duration can also be used to express an absolute time.¶
A period is a specific interval of time, specified as either two times giving the start and the end of that interval, or as one of these two plus a duration.¶
They are given as an array of unwrapped time and duration elements, tagged with Tag 1003:¶
Period = #6.1003([ start: ~Time / null end: ~Time / null ? duration: ~Duration / null ])¶
If the third array element is not given, the duration element is null. Exactly two out of the three elements must be non-null, this can be clumsily expressed in CDDL as:¶
Period = #6.1003([ (start: ~Time, ((end: ~Time, ? duration: null) // (end: null, duration: ~Duration))) // (start: null, end: ~Time, duration: ~Duration) ])¶
For the use with the CBOR Data Definition Language, CDDL [RFC8610], the type names defined in Figure 3 are recommended:¶
etime = #6.1001({* (int/tstr) => any}) duration = #6.1002({* (int/tstr) => any}) period = #6.1003([~etime/null, ~etime/null, ~duration/null])
In the registry [IANA.cbor-tags], IANA has allocated the tags in Table 2 from the FCFS space, with the present document as the specification reference.¶
Tag | Data Item | Semantics |
---|---|---|
1001 | map | [RFCthis] extended time |
1002 | map | [RFCthis] duration |
1003 | array | [RFCthis] period |
IANA is requested to change the "Data Item" column for Tag 1003 from "map" to "array".¶
The security considerations of RFC 8949 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).¶