doc: Add RFC documents

1 files changed, 451 insertions, 0 deletions

diff --git a/doc/rfc/rfc8710.txt b/doc/rfc/rfc8710.txt
new file mode 100644
index 0000000..3b8359f
--- /dev/null
+++ b/doc/rfc/rfc8710.txt
@@ -0,0 +1,451 @@
+
+
+
+
+Internet Engineering Task Force (IETF)                        T. Fossati
+Request for Comments: 8710                                           ARM
+Category: Standards Track                                      K. Hartke
+ISSN: 2070-1721                                                 Ericsson
+                                                              C. Bormann
+                                                  Universität Bremen TZI
+                                                           February 2020
+
+
+Multipart Content-Format for the Constrained Application Protocol (CoAP)
+
+Abstract
+
+   This memo defines application/multipart-core, an application-
+   independent media type that can be used to combine representations of
+   zero or more different media types (each with a Constrained
+   Application Protocol (CoAP) Content-Format identifier) into a single
+   representation, with minimal framing overhead.
+
+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/rfc8710.
+
+Copyright Notice
+
+   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) 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
+     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
+
+   This memo defines application/multipart-core, an application-
+   independent media type that can be used to combine representations of
+   zero or more different media types (each with a CoAP Content-Format
+   identifier [RFC7252]) into a single representation, with minimal
+   framing overhead.
+
+   This simple and efficient binary framing mechanism can be employed to
+   create application-specific message bodies that build on multiple
+   already existing media types.
+
+   As the name of the media type suggests, application/multipart-core
+   was inspired by the multipart media types initially defined in the
+   original set of MIME specifications [RFC2046] and later.  However,
+   while those needed to focus on the syntactic aspects of integrating
+   multiple representations into one email, transfer protocols providing
+   full data transparency such as CoAP as well as readily available
+   encoding formats such as the Concise Binary Object Representation
+   (CBOR) [RFC7049] shift the focus towards the intended use of the
+   combined representations.  In this respect, the basic intent of the
+   application/multipart-core media type is like that of multipart/mixed
+   (Section 5.1.3 of [RFC2046]); however, the semantics are relaxed to
+   allow for both ordered and unordered collections of media types.
+
+      Historical Note: Experience with multipart/mixed in email has
+      shown that recipients that care about order of included body parts
+      will process them in the order they are listed inside multipart/
+      mixed, and recipients that don't care about the order will ignore
+      it anyway.  The media type multipart/parallel that was intended
+      for unordered collections didn't deploy.
+
+   The detailed semantics of the representations are refined by the
+   context established by the application in the accompanying request
+   parameters, e.g., the resource URI and any further options (header
+   fields), but three usage scenarios are envisioned:
+
+   In one case, the individual representations in an application/
+   multipart-core message body occur in a sequence, which may be
+   employed by an application where such a sequence is natural, e.g.,
+   for a number of audio snippets in various formats to be played out in
+   that sequence or search results returned in order of relevance.
+
+   In another case, an application may be more interested in a bag of
+   representations (which are distinguished by their Content-Format
+   identifiers), such as an audio snippet and a text representation
+   accompanying it.  In such a case, the sequence in which these occur
+   may not be relevant to the application.  This specification adds the
+   option of substituting a null value for the representation of an
+   optional part, which indicates that the part is not present.
+
+   A third common situation only has a single representation in the
+   sequence, and the sender selects just one of a set of formats
+   possible for this situation.  This kind of union "type" of formats
+   may also make the presence of the actual representation optional, the
+   omission of which leads to a zero-length array.
+
+   Where these rules are not sufficient, an application might still use
+   the general format defined here but register a new media type and an
+   associated Content-Format identifier to associate the representation
+   with these more specific semantics instead of using the application/
+   multipart-core media type.
+
+   Also, future specifications might want to define rough equivalents
+   for other multipart media types with specific semantics not covered
+   by the present specification, such as multipart/alternative
+   (Section 5.1.4 of [RFC2046]), where several alternative
+   representations are provided in the message body, but only one of
+   those is to be selected by the recipient for its use (this is less
+   likely to be useful in a constrained environment that has facilities
+   for pre-flight discovery).
+
+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
+
+   A representation of media type application/multipart-core contains a
+   collection of zero or more representations, each along with their
+   respective Content-Format.
+
+   The collection is 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).  The (even-numbered)
+   element preceding each of these is an unsigned integer specifying the
+   Content-Format ID of the representation following it.
+
+   For example, a collection containing two representations, one with
+   Content-Format ID 42 and one with Content-Format ID 0, looks like
+   this in CBOR diagnostic notation:
+
+   [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 intended as a strict specification: an implementation
+   MUST stop processing the representation if there is a CBOR well-
+   formedness error, a deviation from the structure defined above, or
+   any residual data left after processing the CBOR data item.  (This
+   generally means the representation is not processed at all unless
+   some streaming processing has already happened.)
+
+3.  Usage Example: Observing Resources
+
+   This section illustrates a less obvious example for using
+   application/multipart-core: combining it with observing a resource
+   [RFC7641] to handle pending results.
+
+   When a client registers to observe a resource for which no
+   representation is 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.  A diagram depicting possible resulting sequences of
+   notifications, identified by their respective response code, is shown
+   in Figure 2.
+
+         __________       __________       __________
+        |          |     |          |     |          |
+   ---->|   2.05   |---->|  2.05 /  |---->|  4.xx /  |
+        |  Pending |     |   2.03   |     |   5.xx   |
+        |__________|     |__________|     |__________|
+           ^   \ \          ^    \           ^
+            \__/  \          \___/          /
+                   \_______________________/
+
+                    Figure 2: Sequence of Notifications
+
+   The specification of the Observe option requires that all
+   notifications carry the same Content-Format.  The application/
+   multipart-core media type can be used to provide that Content-Format,
+   e.g., by carrying an empty list of representations in the case marked
+   as "Pending" in Figure 2 and carrying a single representation
+   specified as the target Content-Format in the case in the middle of
+   the figure.
+
+4.  Implementation Hints
+
+   This section describes the serialization for readers that may be new
+   to CBOR.  It does not contain any new information.
+
+   An application/multipart-core representation carrying no
+   representations is represented by an empty CBOR array, which is
+   serialized as a single byte with the value 0x80.
+
+   An application/multipart-core representation carrying a single
+   representation is represented by a two-element CBOR array, which is
+   serialized as 0x82 followed by the two elements.  The first element
+   is an unsigned integer for the Content-Format value, which is
+   represented as described in Table 1.  The second element is the
+   object as a byte string, which is represented as a length as
+   described in Table 2 followed by the bytes of the object.
+
+                      +----------------+------------+
+                      | Serialization  | Value      |
+                      +================+============+
+                      | 0x00..0x17     | 0..23      |
+                      +----------------+------------+
+                      | 0x18 0xnn      | 24..255    |
+                      +----------------+------------+
+                      | 0x19 0xnn 0xnn | 256..65535 |
+                      +----------------+------------+
+
+                         Table 1: Serialization of
+                               Content-Format
+
+            +-----------------------------+-------------------+
+            | 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) of value
+   "Hello World" (11 characters) would be serialized as follows:
+
+   0x82 0x00 0x4b H e l l o 0x20 W o r l d
+
+   In effect, the serialization for a single object is done by prefixing
+   the object with information that there is one object (here: 0x82),
+   information about its Content-Format (here: 0x00), and information
+   regarding its length (here: 0x4b).
+
+   For more than one representation included in an application/
+   multipart-core representation, the head of the CBOR array is adjusted
+   (0x84 for two representations, 0x86 for three, etc.), and the
+   sequences of Content-Format and embedded representations follow.
+
+   For instance, the example from Section 2 would be serialized as
+   follows:
+
+   0x84 (*) 0x182A 0x48 0x0123456789ABCDEF (+) 0x00 0x45 0x3031323334
+
+   where (*) marks the start of the information about 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
+
+   The security considerations of [RFC7049] apply.  In particular,
+   resource exhaustion attacks may employ large values for the byte
+   string size fields or employ 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 is 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