summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc9193.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc9193.txt')
-rw-r--r--doc/rfc/rfc9193.txt498
1 files changed, 498 insertions, 0 deletions
diff --git a/doc/rfc/rfc9193.txt b/doc/rfc/rfc9193.txt
new file mode 100644
index 0000000..dbfcb0a
--- /dev/null
+++ b/doc/rfc/rfc9193.txt
@@ -0,0 +1,498 @@
+
+
+
+
+Internet Engineering Task Force (IETF) A. Keränen
+Request for Comments: 9193 Ericsson
+Category: Standards Track C. Bormann
+ISSN: 2070-1721 Universität Bremen TZI
+ June 2022
+
+
+ Sensor Measurement Lists (SenML) Fields for Indicating Data Value
+ Content-Format
+
+Abstract
+
+ The Sensor Measurement Lists (SenML) media types support multiple
+ types of values, from numbers to text strings and arbitrary binary
+ Data Values. In order to facilitate processing of binary Data
+ Values, this document specifies a pair of new SenML fields for
+ indicating the content format of those binary Data Values, i.e.,
+ their Internet media type, including parameters as well as any
+ content codings applied.
+
+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/rfc9193.
+
+Copyright Notice
+
+ Copyright (c) 2022 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. Evolution
+ 2. Terminology
+ 3. SenML Content-Format ("ct") Field
+ 4. SenML Base Content-Format ("bct") Field
+ 5. Examples
+ 6. ABNF
+ 7. Security Considerations
+ 8. IANA Considerations
+ 9. References
+ 9.1. Normative References
+ 9.2. Informative References
+ Acknowledgments
+ Authors' Addresses
+
+1. Introduction
+
+ The Sensor Measurement Lists (SenML) media types [RFC8428] can be
+ used to send various kinds of data. In the example given in
+ Figure 1, a temperature value, an indication whether a lock is open,
+ and a Data Value (with SenML field "vd") read from a Near Field
+ Communication (NFC) reader is sent in a single SenML Pack. The
+ example is given in SenML JSON representation, so the "vd" (Data
+ Value) field is encoded as a base64url string (without padding), as
+ per Section 5 of [RFC8428].
+
+ [
+ {"bn":"urn:dev:ow:10e2073a01080063:","n":"temp","u":"Cel","v":7.1},
+ {"n":"open","vb":false},
+ {"n":"nfc-reader","vd":"aGkgCg"}
+ ]
+
+ Figure 1: SenML Pack with Unidentified Binary Data
+
+ The receiver is expected to know how to interpret the data in the
+ "vd" field based on the context, e.g., the name of the data source
+ and out-of-band knowledge of the application. However, this context
+ may not always be easily available to entities processing the SenML
+ Pack, especially if the Pack is propagated over time and via multiple
+ entities. To facilitate automatic interpretation, it is useful to be
+ able to indicate an Internet media type and, optionally, content
+ codings right in the SenML Record.
+
+ The Constrained Application Protocol (CoAP) Content-Format
+ (Section 12.3 of [RFC7252]) provides this information in the form of
+ a single unsigned integer. For instance, [RFC8949] defines the
+ Content-Format number 60 for Content-Type application/cbor.
+ Enclosing this Content-Format number in the Record is illustrated in
+ Figure 2. All registered CoAP Content-Format numbers are listed in
+ the "CoAP Content-Formats" registry [IANA.core-parameters], as
+ specified by Section 12.3 of [RFC7252]. Note that, at the time of
+ writing, the structure of this registry only provides for zero or one
+ content coding; nothing in the present document needs to change if
+ the registry is extended to allow sequences of content codings.
+
+ {"n":"nfc-reader", "vd":"gmNmb28YKg", "ct":"60"}
+
+ Figure 2: SenML Record with Binary Data Identified as CBOR
+
+ In this example SenML Record, the Data Value contains a string "foo"
+ and a number 42 encoded in a Concise Binary Object Representation
+ (CBOR) [RFC8949] array. Since the example above uses the JSON format
+ of SenML, the Data Value containing the binary CBOR value is base64
+ encoded (Section 5 of [RFC4648]). The Data Value after base64
+ decoding is shown with CBOR diagnostic notation in Figure 3.
+
+ 82 # array(2)
+ 63 # text(3)
+ 666F6F # "foo"
+ 18 2A # unsigned(42)
+
+ Figure 3: Example Data Value in CBOR Diagnostic Notation
+
+1.1. Evolution
+
+ As with SenML in general, there is no expectation that the creator of
+ a SenML Pack knows (or has negotiated with) each consumer of that
+ Pack, which may be very remote in space and particularly in time.
+ This means that the SenML creator in general has no way to know
+ whether the consumer knows:
+
+ * each specific Media-Type-Name used,
+
+ * each parameter and each parameter value used,
+
+ * each content coding in use, and
+
+ * each Content-Format number in use for a combination of these.
+
+ What SenML, as well as the new fields defined here, guarantees is
+ that a recipient implementation _knows_ when it needs to be updated
+ to understand these field values and the values controlled by them;
+ registries are used to evolve these name spaces in a controlled way.
+ SenML Packs can be processed by a consumer while not understanding
+ all the information in them, and information can generally be
+ preserved in this processing such that it is useful for further
+ consumers.
+
+2. 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.
+
+ Media type: A registered label for representations (byte strings)
+ prepared for interchange [RFC1590] [RFC6838], identified by a
+ Media-Type-Name.
+
+ Media-Type-Name: A combination of a type-name and a subtype-name
+ registered in [IANA.media-types], as per [RFC6838], conventionally
+ identified by the two names separated by a slash.
+
+ Content-Type: A Media-Type-Name, optionally associated with
+ parameters (Section 5 of [RFC2045], separated from the Media-Type-
+ Name and from each other by a semicolon). In HTTP and many other
+ protocols, it is used in a Content-Type header field.
+
+ Content coding: A name registered in the "HTTP Content Coding
+ Registry" [IANA.http-parameters], as specified by Sections 16.6.1
+ and 18.6 of [RFC9110], indicating an encoding transformation with
+ semantics further specified in Section 8.4.1 of [RFC9110].
+ Confusingly, in HTTP, content coding values are found in a header
+ field called "Content-Encoding"; however, "content coding" is the
+ correct term for the process and the registered values.
+
+ Content format: The combination of a Content-Type and zero or more
+ content codings, identified by (1) a numeric identifier defined in
+ the "CoAP Content-Formats" registry [IANA.core-parameters], as per
+ Section 12.3 of [RFC7252] (referred to as Content-Format number),
+ or (2) a Content-Format-String.
+
+ Content-Format-String: The string representation of the combination
+ of a Content-Type and zero or more content codings.
+
+ Content-Format-Spec: The string representation of a content format;
+ either a Content-Format-String or the (decimal) string
+ representation of a Content-Format number.
+
+ Readers should also be familiar with the terms and concepts discussed
+ in [RFC8428].
+
+3. SenML Content-Format ("ct") Field
+
+ When a SenML Record contains a Data Value field ("vd"), the Record
+ MAY also include a Content-Format indication field, using label "ct".
+ The value of this field is a Content-Format-Spec, i.e., one of the
+ following:
+
+ * a CoAP Content-Format number in decimal form with no leading zeros
+ (except for the value "0" itself). This value represents an
+ unsigned integer in the range of 0-65535, similar to the "ct"
+ attribute defined in Section 7.2.1 of [RFC7252] for CoRE Link
+ Format [RFC6690].
+
+ * a Content-Format-String containing a Content-Type and zero or more
+ content codings (see below).
+
+ The syntax of this field is formally defined in Section 6.
+
+ The CoAP Content-Format number provides a simple and efficient way to
+ indicate the type of the data. Since some Internet media types and
+ their content coding and parameter alternatives do not have assigned
+ CoAP Content-Format numbers, using Content-Type and zero or more
+ content codings is also allowed. Both methods use a string value in
+ the "ct" field to keep its data type consistent across uses. When
+ the "ct" field contains only digits, it is interpreted as a CoAP
+ Content-Format number.
+
+ To indicate that one or more content codings are used with a Content-
+ Type, each of the content coding values is appended to the Content-
+ Type value (media type and parameters, if any), separated by an "@"
+ sign, in the order of when the content codings were applied (the same
+ order as in Section 8.4 of [RFC9110]). For example (using a content
+ coding value of "deflate", as defined in Section 8.4.1.2 of
+ [RFC9110]):
+
+ text/plain; charset=utf-8@deflate
+
+ If no "@" sign is present after the media type and parameters, then
+ no content coding has been specified, and the "identity" content
+ coding is used -- no encoding transformation is employed.
+
+4. SenML Base Content-Format ("bct") Field
+
+ The Base Content-Format field, label "bct", provides a default value
+ for the Content-Format field (label "ct") within its range. The
+ range of the base field includes the Record containing it, up to (but
+ not including) the next Record containing a "bct" field, if any, or
+ up to the end of the Pack otherwise. The process of resolving
+ (Section 4.6 of [RFC8428]) this base field is performed by adding its
+ value with the label "ct" to all Records in this range that carry a
+ "vd" field but do not already contain a Content-Format ("ct") field.
+
+ Figure 4 shows a variation of Figure 2 with multiple records, with
+ the "nfc-reader" records resolving to the base field value "60" and
+ the "iris-photo" record overriding this with the "image/png" media
+ type (actual data left out for brevity).
+
+ [
+ {"n":"nfc-reader", "vd":"gmNmb28YKg",
+ "bct":"60", "bt":1627430700},
+ {"n":"nfc-reader", "vd":"gmNiYXIYKw", "t":10},
+ {"n":"iris-photo", "vd":".....", "ct":"image/png", "t":10},
+ {"n":"nfc-reader", "vd":"gmNiYXoYLA", "t":20}
+ ]
+
+ Figure 4: SenML Pack with the bct Field
+
+5. Examples
+
+ The following examples are valid values for the "ct" and "bct" fields
+ (explanation/comments in parentheses):
+
+ * "60" (CoAP Content-Format number for "application/cbor")
+
+ * "0" (CoAP Content-Format number for "text/plain" with parameter
+ "charset=utf-8")
+
+ * "application/json" (JSON Content-Type -- equivalent to "50" CoAP
+ Content-Format number)
+
+ * "application/json@deflate" (JSON Content-Type with "deflate" as
+ content coding -- equivalent to "11050" CoAP Content-Format
+ number)
+
+ * "application/json@deflate@aes128gcm" (JSON Content-Type with
+ "deflate" followed by "aes128gcm" as content codings)
+
+ * "text/csv" (Comma-Separated Values (CSV) [RFC4180] Content-Type)
+
+ * "text/csv;header=present@gzip" (CSV with header row, using "gzip"
+ as content coding)
+
+6. ABNF
+
+ This specification provides a formal definition of the syntax of
+ Content-Format-Spec strings using ABNF notation [RFC5234], which
+ contains three new rules and a number of rules collected and adapted
+ from various RFCs [RFC9110] [RFC6838] [RFC5234] [RFC8866].
+
+ ; New in this document
+
+ Content-Format-Spec = Content-Format-Number / Content-Format-String
+
+ Content-Format-Number = "0" / (POS-DIGIT *DIGIT)
+ Content-Format-String = Content-Type *("@" Content-Coding)
+
+ ; Cleaned up from RFC 9110,
+ ; leaving only SP as blank space,
+ ; removing legacy 8-bit characters, and
+ ; leaving the parameter as mandatory with each semicolon:
+
+ Content-Type = Media-Type-Name *( *SP ";" *SP parameter )
+ parameter = token "=" ( token / quoted-string )
+
+ token = 1*tchar
+ tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
+ / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
+ / DIGIT / ALPHA
+ quoted-string = %x22 *( qdtext / quoted-pair ) %x22
+ qdtext = SP / %x21 / %x23-5B / %x5D-7E
+ quoted-pair = "\" ( SP / VCHAR )
+
+ ; Adapted from Section 8.4.1 of RFC 9110
+
+ Content-Coding = token
+
+ ; Adapted from various specs
+
+ Media-Type-Name = type-name "/" subtype-name
+
+ ; From RFC 6838
+
+ type-name = restricted-name
+ subtype-name = restricted-name
+
+ restricted-name = restricted-name-first *126restricted-name-chars
+ restricted-name-first = ALPHA / DIGIT
+ restricted-name-chars = ALPHA / DIGIT / "!" / "#" /
+ "$" / "&" / "-" / "^" / "_"
+ restricted-name-chars =/ "." ; Characters before first dot always
+ ; specify a facet name
+ restricted-name-chars =/ "+" ; Characters after last plus always
+ ; specify a structured syntax suffix
+
+
+ ; Boilerplate from RFC 5234 and RFC 8866
+
+ DIGIT = %x30-39 ; 0 - 9
+ POS-DIGIT = %x31-39 ; 1 - 9
+ ALPHA = %x41-5A / %x61-7A ; A - Z / a - z
+ SP = %x20
+ VCHAR = %x21-7E ; printable ASCII (no SP)
+
+ Figure 5: ABNF Syntax of Content-Format-Spec
+
+7. Security Considerations
+
+ The indication of a media type in the data does not exempt a
+ consuming application from properly checking its inputs. Also, the
+ ability for an attacker to supply crafted SenML data that specifies
+ media types chosen by the attacker may expose vulnerabilities of
+ handlers for these media types to the attacker. This includes
+ "decompression bombs", compressed data that is crafted to decompress
+ to extremely large data items.
+
+8. IANA Considerations
+
+ IANA has assigned the following new labels in the "SenML Labels"
+ subregistry of the "Sensor Measurement Lists (SenML)" registry
+ [IANA.senml] (as defined in Section 12.2 of [RFC8428]) for the
+ Content-Format indication, as per Table 1:
+
+ +=====================+=======+===========+==========+===========+
+ | Name | Label | JSON Type | XML Type | Reference |
+ +=====================+=======+===========+==========+===========+
+ | Base Content-Format | bct | String | string | RFC 9193 |
+ +---------------------+-------+-----------+----------+-----------+
+ | Content-Format | ct | String | string | RFC 9193 |
+ +---------------------+-------+-----------+----------+-----------+
+
+ Table 1: IANA Registration for New SenML Labels
+
+ Note that, per Section 12.2 of [RFC8428], no CBOR labels nor
+ Efficient XML Interchange (EXI) schemaId values (EXI ID column) are
+ supplied.
+
+9. References
+
+9.1. Normative References
+
+ [IANA.core-parameters]
+ IANA, "Constrained RESTful Environments (CoRE)
+ Parameters",
+ <https://www.iana.org/assignments/core-parameters>.
+
+ [IANA.http-parameters]
+ IANA, "Hypertext Transfer Protocol (HTTP) Parameters",
+ <https://www.iana.org/assignments/http-parameters>.
+
+ [IANA.media-types]
+ IANA, "Media Types",
+ <https://www.iana.org/assignments/media-types>.
+
+ [IANA.senml]
+ IANA, "Sensor Measurement Lists (SenML)",
+ <https://www.iana.org/assignments/senml>.
+
+ [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
+ Extensions (MIME) Part One: Format of Internet Message
+ Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
+ <https://www.rfc-editor.org/info/rfc2045>.
+
+ [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>.
+
+ [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
+ Specifications: ABNF", STD 68, RFC 5234,
+ DOI 10.17487/RFC5234, January 2008,
+ <https://www.rfc-editor.org/info/rfc5234>.
+
+ [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
+ Application Protocol (CoAP)", RFC 7252,
+ DOI 10.17487/RFC7252, June 2014,
+ <https://www.rfc-editor.org/info/rfc7252>.
+
+ [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>.
+
+ [RFC8428] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C.
+ Bormann, "Sensor Measurement Lists (SenML)", RFC 8428,
+ DOI 10.17487/RFC8428, August 2018,
+ <https://www.rfc-editor.org/info/rfc8428>.
+
+ [RFC9110] Fielding, R., Nottingham, M., and J. Reschke, "HTTP
+ Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110,
+ February 2022, <https://www.rfc-editor.org/rfc/rfc9110>.
+
+9.2. Informative References
+
+ [RFC1590] Postel, J., "Media Type Registration Procedure", RFC 1590,
+ DOI 10.17487/RFC1590, March 1994,
+ <https://www.rfc-editor.org/info/rfc1590>.
+
+ [RFC4180] Shafranovich, Y., "Common Format and MIME Type for Comma-
+ Separated Values (CSV) Files", RFC 4180,
+ DOI 10.17487/RFC4180, October 2005,
+ <https://www.rfc-editor.org/info/rfc4180>.
+
+ [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
+ Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
+ <https://www.rfc-editor.org/info/rfc4648>.
+
+ [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
+ Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
+ <https://www.rfc-editor.org/info/rfc6690>.
+
+ [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
+ Specifications and Registration Procedures", BCP 13,
+ RFC 6838, DOI 10.17487/RFC6838, January 2013,
+ <https://www.rfc-editor.org/info/rfc6838>.
+
+ [RFC8866] Begen, A., Kyzivat, P., Perkins, C., and M. Handley, "SDP:
+ Session Description Protocol", RFC 8866,
+ DOI 10.17487/RFC8866, January 2021,
+ <https://www.rfc-editor.org/info/rfc8866>.
+
+ [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>.
+
+Acknowledgments
+
+ The authors would like to thank Sérgio Abreu for the discussions
+ leading to the design of this extension and Isaac Rivera for reviews
+ and feedback. Klaus Hartke suggested not burdening this document
+ with a separate mandatory-to-implement version of the fields. Alexey
+ Melnikov, Jim Schaad, and Thomas Fossati provided helpful comments at
+ Working Group Last Call. Marco Tiloca asked for clarifying and using
+ the term Content-Format-Spec.
+
+Authors' Addresses
+
+ Ari Keränen
+ Ericsson
+ FI-02420 Jorvas
+ Finland
+ Email: ari.keranen@ericsson.com
+
+
+ Carsten Bormann
+ Universität Bremen TZI
+ Postfach 330440
+ D-28359 Bremen
+ Germany
+ Phone: +49-421-218-63921
+ Email: cabo@tzi.org