Network Working Group C. Bormann
Internet-Draft Universitaet Bremen TZI
Intended status: Informational B. Gamari
Expires: April 25, 2019 Well-Typed
H. Birkholz
Fraunhofer SIT
October 22, 2018
Concise Binary Object Representation (CBOR) Tags for Time, Duration, and
Period
draft-bormann-cbor-time-tag-02
Abstract
The Concise Binary Object Representation (CBOR, RFC 7049) 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 7049 defines two tags for time: CBOR tag 0 (RFC3339 time) and tag
1 (Posix time [TIME_T], 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, and
anticipates the definition of related CBOR tags for duration and time
period. It is intended as the reference document for the IANA
registration of the CBOR tags defined.
Note to Readers
Version -00 of 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 are believed will stay unchanged during further
development of the draft. This version is provided to aid the
registration of the CBOR tag immediately needed. The present version
-02 makes use of the IANA allocations registered. Further versions
will re-introduce some of the material from -00, but in a more
concrete form.
Status of This Memo
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
Bormann, et al. Expires April 25, 2019 [Page 1]
Internet-Draft CBOR tag for extended time October 2018
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 April 25, 2019.
Copyright Notice
Copyright (c) 2018 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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Background . . . . . . . . . . . . . . . . . . . . . . . 3
2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Time Format . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Key 1 . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Keys 4 and 5 . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Keys -3, -6, -9, -12, -15, -18 . . . . . . . . . . . . . 5
4. CDDL typenames . . . . . . . . . . . . . . . . . . . . . . . 5
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
7.1. Normative References . . . . . . . . . . . . . . . . . . 7
7.2. Informative References . . . . . . . . . . . . . . . . . 8
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
Bormann, et al. Expires April 25, 2019 [Page 2]
Internet-Draft CBOR tag for extended time October 2018
1. Introduction
The Concise Binary Object Representation (CBOR, [RFC7049]) provides
for the interchange of structured data without a requirement for a
pre-agreed schema. RFC 7049 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.)
1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
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.
1.2. Background
Additional information about the complexities of time representation
can be found in [TIME]. This specification uses a number of terms
that should be familiar to connoisseurs of precise time; references
for these may need to be added.
2. Objectives
For the time tag, the present specification addresses the following
objectives that go beyond the original tags 0 and 1:
o Additional resolution for epoch-based time (as in tag 1). CBOR
tag 1 only provides for integer and up to binary64 floating point
representation of times, limiting resolution to approximately
microseconds at the time of writing (and progressively becoming
worse over time).
Not currently addressed, but possibly covered by the definition of
additional map keys for the map inside the tag:
o Indication of time scale. Tags 0 and 1 are for UTC; however, some
interchanges are better performed on TAI. Other time scales 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).
Bormann, et al. Expires April 25, 2019 [Page 3]
Internet-Draft CBOR tag for extended time October 2018
o Direct representation 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. (TBD: 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 with
the extended time format.)
o Additional indication of intents about the interpretation of the
time given, in particular for future times. Intents might include
information about time zones, daylight savings times, etc.
Additional tags might later be defined for duration and period. The
objectives for such duration and period tags are likely similar.
3. Time Format
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:
o a higher precision time offset to be added to the base time,
Future keys may add:
o a reference time scale and epoch different from the default UTC
and 1970-01-01
o information about clock source and precision, accuracy, and
resolution
o intent information such as timezone and daylight savings time,
and/or possibly positioning coordinates, to express information
that would indicate a local time.
While this document does not define supplementary text keys, a number
of unsigned and negative-integer keys are defined below.
Bormann, et al. Expires April 25, 2019 [Page 4]
Internet-Draft CBOR tag for extended time October 2018
3.1. Key 1
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).
3.2. Keys 4 and 5
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.
3.3. Keys -3, -6, -9, -12, -15, -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). 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) |
+-----+--------------+-----------------+
Table 1: Key for decimally scaled Fractions
4. CDDL typenames
For the use with the CBOR Data Definition Language, CDDL
[I-D.ietf-cbor-cddl], the type names defined in Figure 1 are
recommended:
etime = #6.1001({* (int/tstr) => any})
Figure 1: Recommended type names for CDDL
Bormann, et al. Expires April 25, 2019 [Page 5]
Internet-Draft CBOR tag for extended time October 2018
5. IANA Considerations
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 | map | [RFCthis] period |
+------+-----------+-------------------------+
Table 2: Values for Tags
Although duration and period are not yet defined in the present
version of this document, the tag values for duration and period have
been requested at the same time as the value for extended time in
order to achieve allocation of all three values as a contiguous set.
6. Security Considerations
The security considerations of RFC 7049 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).
Bormann, et al. Expires April 25, 2019 [Page 6]
Internet-Draft CBOR tag for extended time October 2018
7. References
7.1. Normative References
[I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR and JSON data structures", draft-ietf-cbor-
cddl-05 (work in progress), August 2018.
[IANA.cbor-tags]
IANA, "Concise Binary Object Representation (CBOR) Tags",
<http://www.iana.org/assignments/cbor-tags>.
[IEEE1588-2008]
IEEE, "1588-2008 - IEEE Standard for a Precision Clock
Synchronization Protocol for Networked Measurement and
Control Systems", July 2008,
<http://standards.ieee.org/findstds/
standard/1588-2008.html>.
[RESOLUTION]
The Open Group Base Specifications, "Vol. 1: Base
Definitions, Issue 7", Section 3.328 '(Time) Resolution',
IEEE Std 1003.1-2008, 2016 Edition, 2016,
<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/
V1_chap03.html#tag_03_328>.
[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>.
[RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049,
October 2013, <https://www.rfc-editor.org/info/rfc7049>.
[SI-SECOND]
International Organization for Standardization (ISO),
"Quantities and units -- Part 3: Space and time",
ISO 80000-3, March 2006.
[TIME_T] The Open Group Base Specifications, "Vol. 1: Base
Definitions, Issue 7", Section 4.15 'Seconds Since the
Epoch', IEEE Std 1003.1-2008, 2016 Edition, 2016,
<http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/
V1_chap04.html#tag_04_16>.
Bormann, et al. Expires April 25, 2019 [Page 7]
Internet-Draft CBOR tag for extended time October 2018
7.2. Informative References
[TIME] Touch, J., "Resolving Multiple Time Scales in the
Internet", draft-touch-time-04 (work in progress), July
2018.
Acknowledgements
Authors' Addresses
Carsten Bormann
Universitaet Bremen TZI
Postfach 330440
Bremen D-28359
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
Ben Gamari
Well-Typed
117 Middle Rd.
Portsmouth, NH 03801
United States
Email: ben@well-typed.com
Henk Birkholz
Fraunhofer Institute for Secure Information Technology
Rheinstrasse 75
Darmstadt 64295
Germany
Email: henk.birkholz@sit.fraunhofer.de
Bormann, et al. Expires April 25, 2019 [Page 8]