RFC 8710

Multipart Content-Format for the Constrained Application Protocol (CoAP)

📅 published February 2020, from ietf

RFC 8710: Multipart Content-Format for the Constrained Application Protocol (CoAP) 🎀

(part 1 of 2 💖)

  • RFC number: 8710
  • Stream: Internet Engineering Task Force (IETF) 🌸
  • Authors: T. Fossati (ARM), K. Hartke (Ericsson), C. Bormann (Universität Bremen TZI) 💅
  • Category: Standards Track ✨
  • ISSN: 2070-1721
  • Date: February 2020 📅
  • Obsoletes / Updates: the title block doesn't list anything this RFC obsoletes or updates 🙈

Abstract

okay so bestie, this memo defines application/multipart-core 🦋 It's an application-independent media type, which means it isn't tied to one specific app. Its whole job is to bundle representations of zero or more different media types into a single representation, and each one keeps its own CoAP Content-Format identifier. The best part is that it does this with minimal framing overhead 🧚

Status of This Memo

This is an Internet Standards Track document 🌈

This document is a product of the IETF. It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 🫶 If you want more info on Internet Standards, check out Section 2 of RFC 7841.

Want the current status of this document, any errata, or a way to send feedback? Head to https://www.rfc-editor.org/info/rfc8710 💜

Copyright (c) 2020 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), as they stand on the publication date. Please read these carefully, because they spell out your rights and restrictions for this document 📜 One important bit: any Code Components pulled out of this document must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 🔥

Table of Contents

   1.  Introduction
     1.1.  Requirements Language
   2.  Multipart Content-Format Encoding
   3.  Usage Example: Observing Resources
   4.  Implementation Hints
   5.  IANA Considerations
     5.1.  Registration of Media Type application/multipart-core
     5.2.  Registration of a Content-Format Identifier for
           application/multipart-core
   6.  Security Considerations
   7.  References
     7.1.  Normative References
     7.2.  Informative References
   Acknowledgements
   Authors' Addresses

1. Introduction 🌸

Okay so this memo introduces application/multipart-core, an application-independent media type. It lets you combine representations of zero or more different media types (each with a CoAP Content-Format identifier [RFC7252]) into one single representation, with minimal framing overhead 💖

This is a simple and efficient binary framing mechanism 🦋 You can use it to build application-specific message bodies that sit on top of several media types that already exist, which is so clever ✨

Here's where the name comes from. As the name says, application/multipart-core was inspired by the multipart media types first defined in the original set of MIME specifications [RFC2046] and later. The difference is that email multipart types had to focus on the syntax of squishing multiple representations into one email 📧 Transfer protocols with full data transparency, like CoAP, plus easy-to-get encoding formats like the Concise Binary Object Representation (CBOR) [RFC7049], shift the focus over to what the combined representations are actually for 👑 So the basic intent of application/multipart-core is like that of multipart/mixed (Section 5.1.3 of [RFC2046]). The big upgrade is that its semantics are relaxed, so it can handle both ordered and unordered collections of media types 🎀

Historical Note: Experience with multipart/mixed in email has shown that recipients who care about the order of body parts go through them in the order they're listed inside multipart/mixed 🙈 Recipients who don't care about order just ignore it anyway. The multipart/parallel type, which was meant for unordered collections, never actually got deployed 💀

The detailed meaning of the representations gets refined by the context the application sets up in the accompanying request parameters, like the resource URI and any further options (header fields) 🧚 Three usage scenarios are envisioned:

Scenario one: the individual representations in an application/multipart-core message body show up in a sequence. This is great when a sequence is natural for the app, like a bunch of audio snippets in different formats that get played out in order, or search results returned in order of relevance 🎶

Scenario two: the app cares more about a bag of representations (distinguished by their Content-Format identifiers), like an audio snippet plus a text representation that goes with it 🛍️ Here the order probably doesn't matter to the app. This spec adds the option of substituting a null value for the representation of an optional part, and a null value tells you that the part isn't present 🍓

Scenario three is the single-representation case. The sequence only has one representation, and the sender picks just one out of a set of formats that are possible for this situation. This kind of union "type" of formats can also make the actual representation optional, and leaving it out gives you a zero-length array 🌈

Where these rules aren't enough, an application can still use the general format defined here, but it can register a new media type and an associated Content-Format identifier for those more specific semantics. That way it doesn't have to use application/multipart-core directly ✨

Also, future specifications might want rough equivalents for other multipart media types with specific semantics that this spec doesn't cover. One example is multipart/alternative (Section 5.1.4 of [RFC2046]), where several alternative representations come in the message body, but the recipient only selects one of them to use 🦋 This is less likely to be useful in a constrained environment that has facilities for pre-flight discovery, so keep that in mind 🙈

1.1. Requirements Language 💅

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 🎀

2. Multipart Content-Format Encoding 🧚

Here's the core idea: a representation of media type application/multipart-core holds a collection of zero or more representations, and each one comes along with its own Content-Format 💖

The collection gets encoded as a CBOR [RFC7049] array with an even number of elements. Counting from zero, the odd-numbered elements are a byte string containing a representation, or the value "null" (if an optional part is indicated as not given). Each of those odd-numbered elements is preceded by an even-numbered element, which is an unsigned integer that specifies the Content-Format ID of the representation right after it 🔥

Here's a quick example. Say a collection has two representations, one with Content-Format ID 42 and one with Content-Format ID 0. In CBOR diagnostic notation, it looks like this:

[42, h'0123456789abcdef', 0, h'3031323334']

For illustration, the structure of an application/multipart-core representation can be described by the Concise Data Definition Language (CDDL) [RFC8610] specification in Figure 1:

   multipart-core = [* multipart-part]
   multipart-part = (type: uint .size 2, part: bytes / null)

               Figure 1: CDDL for application/multipart-core

This format is meant to be a strict specification 🙅‍♀️ An implementation MUST stop processing the representation if there's a CBOR well-formedness error, a deviation from the structure defined above, or any residual data left over after processing the CBOR data item. (In general, this means the representation doesn't get processed at all, unless some streaming processing has already happened.) 😭

3. Usage Example: Observing Resources 👑

This section shows a less obvious way to use application/multipart-core: pairing it with observing a resource [RFC7641] to handle pending results 🦋

Here's the situation. When a client registers to observe a resource that doesn't have a representation available yet, the server may send one or more 2.05 (Content) notifications that indicate the lack of an actual representation. Later on, when one becomes available, the server will send the first actual 2.05 (Content) or 2.03 (Valid) notification 💫 Figure 2 is a diagram of the possible resulting sequences of notifications, each identified by its response code 🌸

         __________       __________       __________
        |          |     |          |     |          |
   ---->|   2.05   |---->|  2.05 /  |---->|  4.xx /  |
        |  Pending |     |   2.03   |     |   5.xx   |
        |__________|     |__________|     |__________|
           ^   \ \          ^    \           ^
            \__/  \          \___/          /
                   \_______________________/

                    Figure 2: Sequence of Notifications

And here's the payoff 🎀 The Observe option specification requires that all notifications carry the same Content-Format. application/multipart-core can be used to provide that Content-Format. For example, you can carry an empty list of representations in the "Pending" case shown in Figure 2, and carry a single representation specified as the target Content-Format in the middle case of the figure. Iconic, honestly 💅✨

4. Implementation Hints ✨

okay so this section is the serialization walkthrough for anyone who's new to CBOR 🧚 it doesn't add any new rules, it just shows you how the bytes actually look 💅

an application/multipart-core representation with no representations at all is an empty CBOR array, which is just one byte: 0x80 🫶

with exactly one representation, you get a two-element CBOR array. that's 0x82, then the two elements. element one is the Content-Format value as an unsigned integer (see Table 1 🎀). element two is the object as a byte string, which is a length (see Table 2) followed by the actual bytes 🍓

Table 1: Serialization of Content-Format 💖

                  +----------------+------------+
                  | Serialization  | Value      |
                  +================+============+
                  | 0x00..0x17     | 0..23      |
                  +----------------+------------+
                  | 0x18 0xnn      | 24..255    |
                  +----------------+------------+
                  | 0x19 0xnn 0xnn | 256..65535 |
                  +----------------+------------+

                     Table 1: Serialization of
                           Content-Format

Table 2: Serialization of Object Length 🦋

        +-----------------------------+-------------------+
        | Serialization               | Length            |
        +=============================+===================+
        | 0x40..0x57                  | 0..23             |
        +-----------------------------+-------------------+
        | 0x58 0xnn                   | 24..255           |
        +-----------------------------+-------------------+
        | 0x59 0xnn 0xnn              | 256..65535        |
        +-----------------------------+-------------------+
        | 0x5a 0xnn 0xnn 0xnn 0xnn    | 65536..4294967295 |
        +-----------------------------+-------------------+
        | 0x5b 0xnn .. 0xnn (8 bytes) | 4294967296..      |
        +-----------------------------+-------------------+

              Table 2: Serialization of Object Length

for example, a single text/plain object (Content-Format 0) with the value "Hello World" (11 characters) gets serialized like this 👑

0x82 0x00 0x4b H e l l o 0x20 W o r l d

so basically, one object gets wrapped up by: the 0x82 (there's one object), then its Content-Format (here 0x00), then its length (here 0x4b) 🌸

for more than one representation, the head of the CBOR array changes (0x84 for two, 0x86 for three, and so on), and then you get the Content-Format and embedded representation pairs one after another ✨

for instance, the example from Section 2 serializes like this 🧚

0x84 (*) 0x182A 0x48 0x0123456789ABCDEF (+) 0x00 0x45 0x3031323334

where (*) marks the start of the first representation (Content-Format 42, byte string length 8), and (+) marks the start of the second representation (Content-Format 0, byte string length 5) 💜

5. IANA Considerations 🌈

5.1. Registration of Media Type application/multipart-core 📝

IANA has registered the following media type [RFC6838]:

Type name:  application

Subtype name:  multipart-core

Required parameters:  N/A

Optional parameters:  N/A

Encoding considerations:  binary

Security considerations:  See the Security Considerations section of
   RFC 8710.

Interoperability considerations:  N/A

Published specification:  RFC 8710

Applications that use this media type:  Applications that need to
   combine representations of zero or more different media types into
   one, e.g., EST over secure CoAP (EST-CoAP) [EST-COAPS]

Fragment identifier considerations:  The syntax and semantics of
   fragment identifiers specified for application/multipart-core are
   as specified for application/cbor.  (At publication of this
   document, there is no fragment identification syntax defined for
   application/cbor.)

Additional information:  Deprecated alias names for this type:  N/A

                         Magic number(s):  N/A

                         File extension(s):  N/A

                         Macintosh file type code(s):  N/A

Person & email address to contact for further information:
   iesg@ietf.org

Intended usage:  COMMON

Restrictions on usage:  N/A

Author:  CoRE WG

Change controller:  IESG

Provisional registration? (standards tree only):  no

5.2. Registration of a Content-Format Identifier for application/multipart-core 🎀

IANA has registered the following Content-Format in the "CoAP Content-Formats" subregistry within the "Constrained RESTful Environments (CoRE) Parameters" registry 🫶

     +----------------------------+----------+----+-----------+
     | Media Type                 | Encoding | ID | Reference |
     +============================+==========+====+===========+
     | application/multipart-core | -        | 62 | RFC 8710  |
     +----------------------------+----------+----+-----------+

        Table 3: Addition to "CoAP Content-Formats" Registry

6. Security Considerations 🔥

bestie, this one is serious 😭 the security considerations of [RFC7049] apply. in particular, resource exhaustion attacks may use huge values in the byte string size fields, or use deeply nested structures of recursively embedded application/multipart-core representations 💀

7. References 📚

7.1. Normative References 🌸

[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>.

[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>.

7.2. Informative References 🦋

[EST-COAPS]
           Stok, P., Kampanakis, P., Richardson, M., and S. Raza,
           "EST over secure CoAP (EST-coaps)", Work in Progress,
           Internet-Draft, draft-ietf-ace-coap-est-18, 6 January
           2020,
           <https://tools.ietf.org/html/draft-ietf-ace-coap-est-18>.

[RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
           Extensions (MIME) Part Two: Media Types", RFC 2046,
           DOI 10.17487/RFC2046, November 1996,
           <https://www.rfc-editor.org/info/rfc2046>.

[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>.

[RFC7641]  Hartke, K., "Observing Resources in the Constrained
           Application Protocol (CoAP)", RFC 7641,
           DOI 10.17487/RFC7641, September 2015,
           <https://www.rfc-editor.org/info/rfc7641>.

[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>.

Acknowledgements 🫶

most of the text in this document comes from earlier contributions by two of the authors, Thomas Fossati and Klaus Hartke 💖 this earlier work was reorganized in this document based on the requirements in [EST-COAPS] and discussions with Michael Richardson, Panos Kampanis, and Peter van der Stok 🙌

Authors' Addresses 💌

Thomas Fossati
ARM

Email: thomas.fossati@arm.com


Klaus Hartke
Ericsson
Torshamnsgatan 23
SE-16483 Stockholm
Sweden

Email: klaus.hartke@ericsson.com


Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany

Phone: +49-421-218-63921
Email: cabo@tzi.org
📦 where this page comes from