diff options
Diffstat (limited to 'doc/rfc/rfc9581.txt')
| -rw-r--r-- | doc/rfc/rfc9581.txt | 1063 |
1 files changed, 1063 insertions, 0 deletions
diff --git a/doc/rfc/rfc9581.txt b/doc/rfc/rfc9581.txt new file mode 100644 index 0000000..bf9aa1c --- /dev/null +++ b/doc/rfc/rfc9581.txt @@ -0,0 +1,1063 @@ + + + + +Internet Engineering Task Force (IETF) C. Bormann +Request for Comments: 9581 Universität Bremen TZI +Category: Standards Track B. Gamari +ISSN: 2070-1721 Well-Typed + H. Birkholz + Fraunhofer SIT + August 2024 + + +Concise Binary Object Representation (CBOR) Tags for Time, Duration, and + Period + +Abstract + + 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 (RFC 3339 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. This document is intended as the reference document for + the IANA registration of the CBOR tags defined. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9581. + +Copyright Notice + + Copyright (c) 2024 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 Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 2. Objectives + 3. Time Format + 3.1. Key 1 + 3.2. Keys 4 and 5 + 3.3. Keys -3, -6, -9, -12, -15, and -18 + 3.4. Keys -1, -13, and 13: Timescale + 3.5. Clock Quality + 3.5.1. ClockClass (Key -2) + 3.5.2. ClockAccuracy (Key -4) + 3.5.3. OffsetScaledLogVariance (Key -5) + 3.5.4. Uncertainty (Key -7) + 3.5.5. Guarantee (Key -8) + 3.6. Keys -10, 10: Time Zone Hint + 3.7. Keys -11, 11: IXDTF Suffix Information + 4. Duration Format + 5. Period Format + 6. CDDL Type Names + 7. IANA Considerations + 7.1. CBOR Tags + 7.2. Timescales Registry + 7.3. Time Tag Map Keys Registry + 8. Security Considerations + 9. References + 9.1. Normative References + 9.2. Informative References + Appendix A. Collected CDDL + Acknowledgements + Authors' Addresses + +1. Introduction + + 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 for CBOR tags (see + [IANA.cbor-tags] and Section 9.2 of [RFC8949]). + + 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 durations + and time periods. This document is intended as the reference + document for the IANA registration of the CBOR tags defined. + +1.1. Terminology + + 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". + + Superscript notation denotes exponentiation. For example, 2 to the + power of 64 is notated: 2^64. In the plain-text rendition of this + specification, superscript notation is not available and + exponentiation is therefore rendered by the surrogate notation seen + here in the plain-text rendition. + + CBOR diagnostic notation is defined in Section 8 of [RFC8949] and + Appendix G of [RFC8610]. A machine-processable model of the data + structures defined in this specification is provided throughout the + text using the Concise Data Definition Language (CDDL) [RFC8610]; + Appendix A provides the collected model information. + + Several time-related terms, such as UTC and International Atomic Time + (TAI), are discussed in [RFC9557], which may be a useful companion + document beyond its direct use in Sections 3.6 and 3.7. + +2. Objectives + + For the time tag, the present specification addresses the following + objectives that go beyond the original tags 0 and 1 (defined in + Sections 3.4.1 and 3.4.2 of [RFC8949]): + + * Additional resolution for epoch-based time (as in tag 1). CBOR + tag 1 only provides for representation of time as an integer and + as up to a binary64 floating-point value [IEEE754], which limits + the resolution to approximately microseconds at the time of + writing (progressively becoming worse over time). + + * Indication of timescale. Tags 0 and 1 are defined for UTC; + however, some interchanges are better performed on TAI. Other + timescales may be registered once they become relevant (e.g., one + of the proposed successors to UTC that might no longer use leap + seconds or a scale based on smeared leap seconds). + + By incorporating a way to transport [RFC9557] suffix information (see + Sections 3.6 and 3.7), additional indications of intents about the + interpretation of the time given can be provided; in particular, for + instances of time that, at the time they are being described, are in + the future. Intents might include information about time zones, + daylight saving times, preferred calendar representations, etc. + + Semantics not covered by this document can be added by registering + additional map keys for the map that is the content of the tag (see + etime-detailed in Figure 1), the specification for which is + referenced by the registry entry (see Section 3). + + For example, map keys could be registered for direct representations + of natural platform time formats. Some platforms use epoch-based + time formats that require some computation to convert them into the + representations allowed by tag 1; these computations can also lose + precision and cause ambiguities. (The present specification does not + take a position on whether tag 1 can be "fixed" to include, e.g., + Decimal or Bigfloat representations. It does define how to use these + representations with the extended time format.) + + Additional tags are defined for durations and periods. + +3. Time Format + + An extended time is indicated by CBOR tag 1001, the content of which + is 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. For negative integer + keys and text string values of the key, implementations MUST ignore + key/value pairs they do not understand; these keys are "elective", as + the extended time as a whole is still usable without the information + they carry if an implementation elects not to implement them. + Conversely, implementations MUST signal an error when encountering + key/value pairs that use unsigned integer keys they do not understand + or implement (these are either "base time" or "critical", see below). + + The map MUST contain exactly one unsigned integer key that specifies + the "base time" and MAY also contain one or more negative integer or + text-string keys, which may encode supplementary information. + + Supplementary information MAY also be provided by additional unsigned + integer keys that are explicitly defined to provide supplementary + information (we say these keys are defined to be "critical"); as + these are required to be understood, there can be no confusion with + base time keys. + + Negative integer and text string keys always supply supplementary + information (they are "elective", and this will not be explicitly + stated below). + + Supplementary information may include: + + * a higher precision time offset to be added to the base time, + + * a reference timescale and epoch different from the default UTC and + 1970-01-01, and + + * information about clock quality parameters, such as source, + accuracy, and uncertainty. + + Additional keys can be defined by registering them in the "Time Tag + Map Keys" registry (Section 7.3). Registered keys may, for instance, + add intent information such as time zone, daylight saving time, and/ + or possibly positioning coordinates to express information that would + indicate a local time. + + This document does not define supplementary text keys. A number of + both unsigned and negative-integer keys are defined in the following + subsections. + + Figure 1 provides a formal definition of tag 1001 in CDDL. + + Etime = #6.1001(etime-detailed) + + etime-framework = { + uint => any ; at least one base time + * (nint/text) => any ; elective supplementary information + * uint => any ; critical supplementary information + } + + etime-detailed = ({ + $$ETIME-BASETIME + ClockQuality-group + * $$ETIME-ELECTIVE + * $$ETIME-CRITICAL + * ((nint/text) .feature "etime-elective-extension") => any + * (uint .feature "etime-critical-extension") => any + }) .within etime-framework + + Figure 1: CDDL Definition of Tag 1001 + +3.1. Key 1 + + Key 1 indicates a base time value that is exactly like the data item + that would be tagged by CBOR tag 1 (POSIX time [TIME_T] as int or + float). As described above, the time value indicated by the value + under this key can be further modified by other keys. + + $$ETIME-BASETIME //= (1: ~time) + +3.2. Keys 4 and 5 + + Keys 4 and 5 indicate a base time value and 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, e.g., to achieve + higher resolution or to avoid rounding errors. + + $$ETIME-BASETIME //= (4: ~decfrac) + $$ETIME-BASETIME //= (5: ~bigfloat) + +3.3. Keys -3, -6, -9, -12, -15, and -18 + + 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). Each extended time data item MUST NOT + contain more than one of these keys. These additional fractions are + added to a base time in seconds [SI-SECOND] indicated by 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) | + +-----+--------------+-----------------+ + + Table 1: Keys for Decimally Scaled + Fractions + + $$ETIME-ELECTIVE //= (-3: uint) + $$ETIME-ELECTIVE //= (-6: uint) + $$ETIME-ELECTIVE //= (-9: uint) + $$ETIME-ELECTIVE //= (-12: uint) + $$ETIME-ELECTIVE //= (-15: uint) + $$ETIME-ELECTIVE //= (-18: uint) + + Note that these keys have been provided to facilitate representing + pairs of the form second/decimal fraction of a second, as found for + instance in C timespec (Section 7.27.1 of [C]). When ingesting a + timestamp with one of these keys into a type provided by the target + platform, care has to be taken to meet its invariants. For example, + for C timespec, the fractional part tv_nsec needs to be between 0 + inclusive and 10^9 exclusive, which can be achieved by also adjusting + the base time appropriately. + +3.4. Keys -1, -13, and 13: Timescale + + Keys -1, -13, and 13 are used to indicate a timescale, where key 13 + is critical. Keys -1 and -13 have identical semantics (both are + assigned because key -1 was chosen first and then, when key 13 was + added, it appeared desirable to have a negative equivalent). Each + extended time data item MUST NOT contain more than one of these keys. + + The value 0 indicates UTC, with the POSIX epoch [TIME_T]; the value 1 + indicates TAI, with the Precision Time Protocol (PTP) epoch (1 + January 1970 00:00:00 TAI, see [IEEE1588-2019] or [IEEE1588-2008]). + + $$ETIME-ELECTIVE //= (-1 => $ETIME-TIMESCALE) + $$ETIME-ELECTIVE //= (-13 => $ETIME-TIMESCALE) + $$ETIME-CRITICAL //= (13 => $ETIME-TIMESCALE) + + $ETIME-TIMESCALE /= &(etime-utc: 0) + $ETIME-TIMESCALE /= &(etime-tai: 1) + + If none of the keys are present, the default timescale value 0 is + implied. + + Timescale values MUST be unsigned integers or text strings; text + strings are provided for experimentation and MUST NOT be used between + parties that are not both part of the experiment. Additional + unsigned integer values can be registered in the "Timescales" + registry (Section 7.2). (Note that there should be no timescales + "GPS" or "NTP" [RFC5905] -- instead, the time should be converted to + TAI or UTC using a single addition or subtraction.) + + t = t - 2208988800 + utc ntp + + t = t + 315964819 + tai gps + + Figure 2: Converting Common Offset Timescales + + | Editor's note: This initial set of timescales was deliberately + | chosen to be frugal, as the specification of the tag provides + | an extension point where additional timescales can be + | registered at any time. Registrations are clearly needed for + | earth-referenced timescales (such as UT1 and TT), as well as + | possibly for specific realizations of abstract timescales (such + | as TAI(USNO), the specific realization obtained at the United + | States Naval Observatory, which is more accurate as a constant + | offset basis for GPS times). While the registration process + | itself is trivial, these registrations need to be made based on + | a solid specification of their actual definition. + +3.5. Clock Quality + + A number of keys are defined to indicate the quality of the 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]; the + last two are specific to this document. + + ClockQuality-group = ( + ? &(ClockClass: -2) => uint .size 1 ; PTP/RFC8575 + ? &(ClockAccuracy: -4) => uint .size 1 ; PTP/RFC8575 + ? &(OffsetScaledLogVariance: -5) => uint .size 2 ; PTP/RFC8575 + ? &(Uncertainty: -7) => ~time/~duration + ? &(Guarantee: -8) => ~time/~duration + ) + +3.5.1. ClockClass (Key -2) + + Key -2 (ClockClass) can be used to indicate the clock class as per + [RFC8575] (which is based on Table 5 in Section 7.6.2.4 of + [IEEE1588-2008]; Table 4 in Section 7.6.2.5 of [IEEE1588-2019] has + updated language). It is defined as a one-byte unsigned integer as + that is the range defined in IEEE 1588. + +3.5.2. ClockAccuracy (Key -4) + + Key -4 (ClockAccuracy) can be used to indicate the clock accuracy as + per [RFC8575] (which is based on Table 6 in Section 7.6.2.5 of + [IEEE1588-2008]; additional values have been defined in Table 5 in + Section 7.6.2.6 of [IEEE1588-2019]). It is defined as a one-byte + unsigned integer as that is the range defined there. The range + between 23 and 47 is a slightly distorted logarithmic scale from 1 ps + to 1 s in [IEEE1588-2019] (in [IEEE1588-2008], the range was a subset + of that, 32 to 47 for 25 ns to 1 s) -- see Figure 3; the number 254 + is the value to be used if an unknown accuracy needs to be expressed. + + acc + enum ≈ 48 + ⌊2 ⋅log ──── - ε⌋ + acc 10 s + + Figure 3: Approximate Conversion from Accuracy to Accuracy + Enumeration Value + +3.5.3. OffsetScaledLogVariance (Key -5) + + 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-2019] + and the same section in [IEEE1588-2008]. + +3.5.4. Uncertainty (Key -7) + + Key -7 (Uncertainty) can be used to represent a known uncertainty of + measurement 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 expanded uncertainty for k = 2 (Section 6.2.1 of + [GUM]) in seconds. + + Note that the additional information that can be meaningfully + provided with the duration that represents an uncertainty is limited, + e.g., it is not customary to provide an uncertainty for a duration + representing an uncertainty. Implementations are free to reduce the + information contained in an uncertainty (which is already elective) + to the information they can process. + + For example, a timestamp that is given to a resolution of 10^-6 + seconds (microseconds) but only has an uncertainty of 10^-3 seconds + (milliseconds) could be expressed by one of the extended time tags in + Figure 4 (note the slight rounding error in the third case, which is + probably inconsequential for an uncertainty value): + + 1001({1: 1697724754, -6: 873294, -7: {1: 0, -6: 1000}}), + 1001({1: 1697724754, -6: 873294, -7: {1: 0, -3: 1}}), + 1001({1: 1697724754, -6: 873294, -7: {1: 0.001}}) + + Figure 4: Examples Using Uncertainty + +3.5.5. Guarantee (Key -8) + + 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. + + Note that the additional information that can be meaningfully + provided with the duration that represents a guarantee is limited, + e.g., it is not meaningful to provide a guarantee of accuracy for the + duration representing a guarantee of accuracy. Implementations are + free to reduce a guarantee (which is already elective) to the + information they can process. + +3.6. Keys -10, 10: Time Zone Hint + + Keys -10 and 10 supply supplementary information, where key 10 is + critical. + + They can be used to provide a hint about the time zone that would + best fit for displaying the time given to humans, using a text string + in the format defined for time-zone-name or time-numoffset in + [RFC9557]. Key -10 is equivalent to providing this information as an + elective hint, while key 10 provides this information as critical + (i.e., it MUST be used when interpreting the entry with this key). + + Keys -10 and 10 MUST NOT both be present. + + $$ETIME-ELECTIVE //= (-10: time-zone-info) + $$ETIME-CRITICAL //= (10: time-zone-info) + + time-zone-info = tstr .abnf + ("time-zone-name / time-numoffset" .det IXDTFtz) + IXDTFtz = ' + time-hour = 2DIGIT ; 00-23 + time-minute = 2DIGIT ; 00-59 + time-numoffset = ("+" / "-") time-hour ":" time-minute + + time-zone-initial = ALPHA / "." / "_" + time-zone-char = time-zone-initial / DIGIT / "-" / "+" + time-zone-part = time-zone-initial *time-zone-char + ; but not "." or ".." + time-zone-name = time-zone-part *("/" time-zone-part) + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + DIGIT = %x30-39 ; 0-9 + ' ; extracted from [RFC9557] and [RFC3339] + +3.7. Keys -11, 11: IXDTF Suffix Information + + Keys -11 and 11 supply supplementary information, where key 11 is + critical. + + Similar to keys -10 and 10, keys -11 (elective) and 11 (critical) can + be used to provide additional information in the style of Internet + Extended Date/Time Format (IXDTF) suffixes, such as the calendar that + would best fit for displaying the time given to humans. The key's + value is a map that has IXDTF suffix-key names as keys and + corresponding suffix values as values, specifically: + + $$ETIME-ELECTIVE //= (-11: suffix-info-map) + $$ETIME-CRITICAL //= (11: suffix-info-map) + + suffix-info-map = { * suffix-key => suffix-values } + suffix-key = tstr .abnf ("suffix-key" .det IXDTF) + suffix-values = one-or-more<suffix-value> + one-or-more<T> = T / [ 2* T ] + suffix-value = tstr .abnf ("suffix-value" .det IXDTF) + + IXDTF = ' + key-initial = lcalpha / "_" + key-char = key-initial / DIGIT / "-" + suffix-key = key-initial *key-char + + suffix-value = 1*alphanum + alphanum = ALPHA / DIGIT + lcalpha = %x61-7A + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + DIGIT = %x30-39 ; 0-9 + ' ; extracted from [RFC9557] + + When keys -11 and 11 are both present, the two maps MUST NOT have + entries with the same map keys. + + Figure 4 of [RFC9557] gives an example for an extended date-time with + both time zone and suffix information: + + 1996-12-19T16:39:57-08:00[America/Los_Angeles][u-ca=hebrew] + + A time tag that is approximating this example, in CBOR diagnostic + notation, would be: + + / 1996-12-19T16:39:57-08:00[America//Los_Angeles][u-ca=hebrew] / + 1001({ 1: 851042397, + -10: "America/Los_Angeles", + -11: { "u-ca": "hebrew" } + }) + + Note that both -10 and -11 are using negative keys and therefore + provide elective information, as in the IXDTF form given in the + comment. Also note that, in this example, the time numeric offset + (-08:00) is lost in translating from the [RFC3339] information in the + IXDTF into a POSIX time that can be included under key 1 in a time + tag. + +4. Duration Format + + A duration is the length of an interval of time. Durations in this + format are given in International System of Units (SI) seconds, + possibly adjusted for conventional corrections of the timescale given + (e.g., leap seconds). + + Except for using tag 1002 instead of 1001, durations are structurally + identical to time values. + + Duration = #6.1002(etime-detailed) + + 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. + + Without such context, durations are subject to some uncertainties + underlying the timescale used. For example, for durations intended + as a determinant of future time periods, there is some uncertainty of + what irregularities (such as leap seconds and timescale corrections) + will be exhibited by the timescale in that period. For durations as + measurements of past periods, abstracting the period to a duration + loses some detail about timescale irregularities. For many + applications, these uncertainties are acceptable and thus the use of + durations is appropriate. + + | Note that the durations defined in [ISO8601:1988] and + | [ISO8601-1:2019] are rather different from the ones defined in + | the present specification; there is no intention to support ISO + | 8601 durations here. + +5. Period Format + + A period is a specific interval of time, specified as either two + extended times giving the start and the end of that interval or as + one of these two plus a duration. + + This is represented as an array of unwrapped time and duration + elements, tagged with tag 1003, one of: + + * a start and end time, in which case the tag content is an array of + two unwrapped extended time elements, or + + * a start time with duration or an end time with duration. The tag + content is an array of 3 elements: the first two as above but + either the start or end time MUST be set to null and the third one + then is an unwrapped duration. + + A simple CDDL definition that does not capture all the constraints + is: + + simple-Period = #6.1003([ + start: ~Etime / null + end: ~Etime / null + ? duration: ~Duration + ]) + + Exactly two out of the three elements must be present and non-null; + this can be somewhat more verbosely expressed in CDDL as: + + Period = #6.1003([ + (start: ~Etime, + ((end: ~Etime) // + (end: null, + duration: ~Duration))) // + (start: null, + end: ~Etime, + duration: ~Duration) + ]) + +6. CDDL Type Names + + When detailed validation is not needed, the type names defined in + Figure 5 are recommended: + + etime = #6.1001({* (int/tstr) => any}) + duration = #6.1002({* (int/tstr) => any}) + period = #6.1003([~etime/null, ~etime/null, ?~duration]) + + Figure 5: Recommended Type Names for CDDL + +7. IANA Considerations + +7.1. CBOR Tags + + In the "CBOR Tags" registry [IANA.cbor-tags], IANA has allocated the + tags in Table 2. + + +======+===========+===============+======================+ + | Tag | Data Item | Semantics | Reference | + +======+===========+===============+======================+ + | 1001 | map | extended time | [RFC9581, Section 3] | + +------+-----------+---------------+----------------------+ + | 1002 | map | duration | [RFC9581, Section 4] | + +------+-----------+---------------+----------------------+ + | 1003 | array | period | [RFC9581, Section 5] | + +------+-----------+---------------+----------------------+ + + Table 2: Values for Tags + + IANA has updated the "Data Item" column for tag 1003 from "map" to + "array". + +7.2. Timescales Registry + + Per this specification, IANA has created a new "Timescales" registry + within the "Concise Binary Object Representation (CBOR) Tags" + registry group [IANA.cbor-tags]. The registration procedure requires + both "Expert Review" and "RFC Required" (Sections 4.5 and 4.7 of RFC + 8126 [BCP26], respectively). + + Each entry needs to provide a timescale name (a sequence of uppercase + ASCII characters and digits, where a digit may not occur at the + start: [A-Z][A-Z0-9]*), a value (CBOR unsigned integer, uint, + 0..18446744073709551615), a brief description of the semantics, and a + specification reference (RFC). The initial contents are shown in + Table 3. + + +===========+=======+======================+===========+ + | Timescale | Value | Semantics | Reference | + +===========+=======+======================+===========+ + | UTC | 0 | UTC with POSIX Epoch | [RFC9581] | + +-----------+-------+----------------------+-----------+ + | TAI | 1 | TAI with PTP Epoch | [RFC9581] | + +-----------+-------+----------------------+-----------+ + + Table 3: Initial Content of Timescale Registry + +7.3. Time Tag Map Keys Registry + + Per this specification, IANA has created a new "Time Tag Map Keys" + registry within the "Concise Binary Object Representation (CBOR) + Tags" registry group [IANA.cbor-tags]. The registration procedure is + "Specification Required" (Section 4.6 of RFC 8126 [BCP26]). + + The designated expert is requested to assign the key values with the + shortest encodings (1+0 and 1+1 encoding) to registrations that are + likely to enjoy wide use and can benefit from short encodings. + + Each entry needs to provide a map key value (CBOR integer, int, + -18446744073709551616..18446744073709551615), a brief description of + the semantics, and a specification reference. Note that negative + integers indicate an elective key, while unsigned integers indicate a + key that either provides a base time or is critical. The designated + expert is requested to discuss with the registrant whether or not it + is desirable to register a pair of an elective and a critical key for + the same information, where the elective key value is the negative of + the critical key (similar to how for example -11 and 11 have been + assigned in Table 4). For the unsigned integers as keys, the choice + of base time or critical needs to be indicated in the brief semantics + description. (Elective map keys may be explicitly marked as such in + the description, e.g., to distinguish them from critical keys.) + + The initial contents are shown in Table 4. + + +=======+=====================================+============+ + | Value | Semantics | Reference | + +=======+=====================================+============+ + | -18 | attoseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -15 | femtoseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -13 | timescale (elective) | [RFC9581] | + +-------+-------------------------------------+------------+ + | -12 | picoseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -11 | IXDTF Suffix Information (elective) | [RFC9581], | + | | | [RFC9557] | + +-------+-------------------------------------+------------+ + | -10 | IXDTF Time Zone Hint (elective) | [RFC9581], | + | | | [RFC9557] | + +-------+-------------------------------------+------------+ + | -9 | nanoseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -8 | Guarantee | [RFC9581] | + +-------+-------------------------------------+------------+ + | -7 | Uncertainty | [RFC9581] | + +-------+-------------------------------------+------------+ + | -6 | microseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -5 | Offset-Scaled Log Variance | [RFC9581] | + +-------+-------------------------------------+------------+ + | -4 | Clock Accuracy | [RFC9581] | + +-------+-------------------------------------+------------+ + | -3 | milliseconds | [RFC9581] | + +-------+-------------------------------------+------------+ + | -2 | Clock Class | [RFC9581] | + +-------+-------------------------------------+------------+ + | -1 | timescale (elective) legacy | [RFC9581] | + +-------+-------------------------------------+------------+ + | 1 | base time value as in CBOR tag 1 | [RFC8949], | + | | | [RFC9581] | + +-------+-------------------------------------+------------+ + | 4 | base time value as in CBOR tag 4 | [RFC8949], | + | | | [RFC9581] | + +-------+-------------------------------------+------------+ + | 5 | base time value as in CBOR tag 5 | [RFC8949], | + | | | [RFC9581] | + +-------+-------------------------------------+------------+ + | 10 | IXDTF Time Zone Hint (critical) | [RFC9557], | + | | | [RFC9581] | + +-------+-------------------------------------+------------+ + | 11 | IXDTF Suffix Information (critical) | [RFC9557], | + | | | [RFC9581] | + +-------+-------------------------------------+------------+ + | 13 | timescale (critical) | [RFC9581] | + +-------+-------------------------------------+------------+ + + Table 4: Initial Content of Time Tag Map Keys Registry + +8. Security Considerations + + The security considerations of [RFC8949] 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). + + A more detailed discussion of security considerations emanating from + using a representation of time that allows the inclusion of complex + and possibly inconsistent information is available in "Security + Considerations" (Section 7 of [RFC9557]). + +9. References + +9.1. Normative References + + [BCP26] Best Current Practice 26, + <https://www.rfc-editor.org/info/bcp26>. + At the time of writing, this BCP comprises the following: + + Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + <https://www.rfc-editor.org/info/rfc8126>. + + [GUM] Joint Committee for Guides in Metrology, "Evaluation of + measurement data -- Guide to the expression of uncertainty + in measurement", JCGM 100:2008, September 2008, + <https://www.bipm.org/en/publications/guides/gum.html>. + + [IANA.cbor-tags] + IANA, "Concise Binary Object Representation (CBOR) Tags", + <https://www.iana.org/assignments/cbor-tags>. + + [IEEE1588-2008] + IEEE, "IEEE Standard for a Precision Clock Synchronization + Protocol for Networked Measurement and Control Systems", + IEEE 1588-2008, July 2008, + <https://standards.ieee.org/ieee/1588/4355/>. Often + called PTP v2, as it replaced the earlier 2002 version of + this standard by a non-backwards compatible protocol. + + [IEEE1588-2019] + IEEE, "IEEE Standard for a Precision Clock Synchronization + Protocol for Networked Measurement and Control Systems", + IEEE 1588-2019, June 2020, + <https://standards.ieee.org/ieee/1588/6825/>. Often + called PTP v2.1, as it has been designed so it can be used + in a way that is fully backwards compatible to + IEEE1588-2008. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8575] Jiang, Y., Ed., Liu, X., Xu, J., and R. Cummings, Ed., + "YANG Data Model for the Precision Time Protocol (PTP)", + RFC 8575, DOI 10.17487/RFC8575, May 2019, + <https://www.rfc-editor.org/info/rfc8575>. + + [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data + Definition Language (CDDL): A Notational Convention to + Express Concise Binary Object Representation (CBOR) and + JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, + June 2019, <https://www.rfc-editor.org/info/rfc8610>. + + [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object + Representation (CBOR)", STD 94, RFC 8949, + DOI 10.17487/RFC8949, December 2020, + <https://www.rfc-editor.org/info/rfc8949>. + + [RFC9557] Sharma, U. and C. Bormann, "Date and Time on the Internet: + Timestamps with Additional Information", RFC 9557, + DOI 10.17487/RFC9557, April 2024, + <https://www.rfc-editor.org/info/rfc9557>. + + [SI-SECOND] + ISO, "Quantities and units -- Part 3: Space and time", + ISO 80000-3:2019, October 2019, + <https://www.iso.org/standard/64974.html>. + + [TIME_T] IEEE, "The Open Group Base Specifications Issue 7", + Section 4.16 Seconds Since the Epoch, IEEE + Std 1003.1-2017, 2018, + <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/ + V1_chap04.html#tag_04_16>. + +9.2. Informative References + + [C] ISO, "Information technology -- Programming languages -- + C", Fourth Edition, ISO/IEC 9899:2018, June 2018, + <https://www.iso.org/standard/74528.html>. Contents + available via <https://www.open- + std.org/jtc1/sc22/wg14/www/docs/n2310.pdf> + + [IEEE754] IEEE, "IEEE Standard for Floating-Point Arithmetic", + IEEE 754-2019, DOI 10.1109/IEEESTD.2019.8766229, July + 2019, <https://ieeexplore.ieee.org/document/8766229>. + + [ISO8601-1:2019] + ISO, "Date and time -- Representations for information + interchange -- Part 1: Basic rules", ISO 8601-1:2019, + February 2019, <https://www.iso.org/standard/70907.html>. + + [ISO8601:1988] + ISO, "Data elements and interchange formats -- Information + interchange -- Representation of dates and times", + ISO 8601:1988, June 1988, + <https://www.iso.org/standard/15903.html>. Also available + from <https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/ + fipspub4-1-1991.pdf + (https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/ + fipspub4-1-1991.pdf)>. + + [RFC3161] Adams, C., Cain, P., Pinkas, D., and R. Zuccherato, + "Internet X.509 Public Key Infrastructure Time-Stamp + Protocol (TSP)", RFC 3161, DOI 10.17487/RFC3161, August + 2001, <https://www.rfc-editor.org/info/rfc3161>. + + [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, + <https://www.rfc-editor.org/info/rfc3339>. + + [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, + "Network Time Protocol Version 4: Protocol and Algorithms + Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, + <https://www.rfc-editor.org/info/rfc5905>. + +Appendix A. Collected CDDL + + This appendix collects the CDDL rules spread over the document into + one convenient place. + + Etime = #6.1001(etime-detailed) + + etime-framework = { + uint => any ; at least one base time + * (nint/text) => any ; elective supplementary information + * uint => any ; critical supplementary information + } + + etime-detailed = ({ + $$ETIME-BASETIME + ClockQuality-group + * $$ETIME-ELECTIVE + * $$ETIME-CRITICAL + * ((nint/text) .feature "etime-elective-extension") => any + * (uint .feature "etime-critical-extension") => any + }) .within etime-framework + + + $$ETIME-BASETIME //= (1: ~time) + + + $$ETIME-BASETIME //= (4: ~decfrac) + $$ETIME-BASETIME //= (5: ~bigfloat) + + + $$ETIME-ELECTIVE //= (-3: uint) + $$ETIME-ELECTIVE //= (-6: uint) + $$ETIME-ELECTIVE //= (-9: uint) + $$ETIME-ELECTIVE //= (-12: uint) + $$ETIME-ELECTIVE //= (-15: uint) + $$ETIME-ELECTIVE //= (-18: uint) + + + $$ETIME-ELECTIVE //= (-1 => $ETIME-TIMESCALE) + $$ETIME-ELECTIVE //= (-13 => $ETIME-TIMESCALE) + $$ETIME-CRITICAL //= (13 => $ETIME-TIMESCALE) + + $ETIME-TIMESCALE /= &(etime-utc: 0) + $ETIME-TIMESCALE /= &(etime-tai: 1) + + + ClockQuality-group = ( + ? &(ClockClass: -2) => uint .size 1 ; PTP/RFC8575 + ? &(ClockAccuracy: -4) => uint .size 1 ; PTP/RFC8575 + ? &(OffsetScaledLogVariance: -5) => uint .size 2 ; PTP/RFC8575 + ? &(Uncertainty: -7) => ~time/~duration + ? &(Guarantee: -8) => ~time/~duration + ) + + + $$ETIME-ELECTIVE //= (-10: time-zone-info) + $$ETIME-CRITICAL //= (10: time-zone-info) + + time-zone-info = tstr .abnf + ("time-zone-name / time-numoffset" .det IXDTFtz) + IXDTFtz = ' + time-hour = 2DIGIT ; 00-23 + time-minute = 2DIGIT ; 00-59 + time-numoffset = ("+" / "-") time-hour ":" time-minute + + time-zone-initial = ALPHA / "." / "_" + time-zone-char = time-zone-initial / DIGIT / "-" / "+" + time-zone-part = time-zone-initial *time-zone-char + ; but not "." or ".." + time-zone-name = time-zone-part *("/" time-zone-part) + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + DIGIT = %x30-39 ; 0-9 + ' ; extracted from [RFC9557] and [RFC3339] + + + $$ETIME-ELECTIVE //= (-11: suffix-info-map) + $$ETIME-CRITICAL //= (11: suffix-info-map) + + suffix-info-map = { * suffix-key => suffix-values } + suffix-key = tstr .abnf ("suffix-key" .det IXDTF) + suffix-values = one-or-more<suffix-value> + one-or-more<T> = T / [ 2* T ] + suffix-value = tstr .abnf ("suffix-value" .det IXDTF) + + IXDTF = ' + key-initial = lcalpha / "_" + key-char = key-initial / DIGIT / "-" + suffix-key = key-initial *key-char + + suffix-value = 1*alphanum + alphanum = ALPHA / DIGIT + lcalpha = %x61-7A + ALPHA = %x41-5A / %x61-7A ; A-Z / a-z + DIGIT = %x30-39 ; 0-9 + ' ; extracted from [RFC9557] + + + Duration = #6.1002(etime-detailed) + + + simple-Period = #6.1003([ + start: ~Etime / null + end: ~Etime / null + ? duration: ~Duration + ]) + + + Period = #6.1003([ + (start: ~Etime, + ((end: ~Etime) // + (end: null, + duration: ~Duration))) // + (start: null, + end: ~Etime, + duration: ~Duration) + ]) + + + etime = #6.1001({* (int/tstr) => any}) + duration = #6.1002({* (int/tstr) => any}) + period = #6.1003([~etime/null, ~etime/null, ?~duration]) + + Figure 6: Collected CDDL Rules from This Specification + +Acknowledgements + + The authors would like to acknowledge the many comments from members + of the CBOR WG, Francesca Palombini for her AD review, Thomas Fossati + and Qin Wu for their directorate reviews, and Rohan Mahy for one more + review late in the process. + +Authors' Addresses + + Carsten Bormann + Universität Bremen TZI + Postfach 330440 + D-28359 Bremen + Germany + Phone: +49-421-218-63921 + Email: cabo@tzi.org + + + Ben Gamari + Well-Typed + 117 Middle Rd. + Portsmouth, NH 03801 + United States of America + Email: ben@well-typed.com + + + Henk Birkholz + Fraunhofer Institute for Secure Information Technology + Rheinstrasse 75 + 64295 Darmstadt + Germany + Email: henk.birkholz@ietf.contact |