From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc9423.txt | 359 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 doc/rfc/rfc9423.txt (limited to 'doc/rfc/rfc9423.txt') diff --git a/doc/rfc/rfc9423.txt b/doc/rfc/rfc9423.txt new file mode 100644 index 0000000..eceb210 --- /dev/null +++ b/doc/rfc/rfc9423.txt @@ -0,0 +1,359 @@ + + + + +Internet Engineering Task Force (IETF) C. Bormann +Request for Comments: 9423 Universität Bremen TZI +Category: Informational April 2024 +ISSN: 2070-1721 + + + Constrained RESTful Environments (CoRE) Target Attributes Registry + +Abstract + + The Constrained RESTful Environments (CoRE) specifications apply web + technologies to constrained environments. One such important + technology is Web Linking (RFC 8288), which CoRE specifications use + as the basis for a number of discovery protocols, such as the Link + Format (RFC 6690) in the Constrained Application Protocol's (CoAP's) + resource discovery process (Section 7.2 of RFC 7252) and the Resource + Directory (RD) (RFC 9176). + + Web Links can have target attributes, the names of which are not + generally coordinated by the Web Linking specification (Section 2.2 + of RFC 8288). This document introduces an IANA registry for + coordinating names of target attributes when used in CoRE. It + updates the "RD Parameters" IANA registry created by RFC 9176 to + coordinate with this registry. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for informational purposes. + + 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). Not all documents + approved by the IESG are candidates for any level of Internet + Standard; see 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/rfc9423. + +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. IANA Considerations + 2.1. Instructions for the Designated Expert + 2.2. Structure of Entries + 2.3. Initial Entries + 3. Security Considerations + 4. References + 4.1. Normative References + 4.2. Informative References + Acknowledgements + Contributors + Author's Address + +1. Introduction + + The Constrained RESTful Environments (CoRE) specifications apply web + technologies to constrained environments. One such important + technology is Web Linking [RFC8288], which CoRE specifications use as + the basis for a number of discovery protocols, such as the Link + Format [RFC6690] in the Constrained Application Protocol's (CoAP's) + resource discovery process (Section 7.2 of [RFC7252]) and the + Resource Directory (RD) [RFC9176]. + + Web Links can have target attributes. The original Web Linking + specification (Section 3 of [RFC5988]) did not attempt to coordinate + names of target attributes except for providing common target + attributes for use in the Link HTTP header. The current revision of + that specification (Section 2.2 of [RFC8288]) clarifies as follows: + + | This specification does not attempt to coordinate the name of + | target attributes, their cardinality, or use. Those creating and + | maintaining serialisations SHOULD coordinate their target + | attributes to avoid conflicts in semantics or syntax and MAY + | define their own registries of target attributes. + + This document introduces an IANA registry for coordinating names of + target attributes when used in CoRE, with specific instructions for + the designated expert for this registry (Section 2.1). It updates + the "RD Parameters" IANA registry created by [RFC9176] to coordinate + with this registry. + + With this registry now available, registration of target attributes + is strongly encouraged. The incentive is that an unregistered + attribute name might be registered with a different meaning at any + time. + +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. + +2. IANA Considerations + + Per this specification, IANA has created a new "Target Attributes" + registry in the "Constrained RESTful Environments (CoRE) Parameters" + registry group [IANA.core-parameters], with the policy "Expert + Review" (Section 4.5 of RFC 8126 [BCP26]). + +2.1. Instructions for the Designated Expert + + The expert is requested to guide the registrant towards reasonably + short target attribute names where the shortness will help conserve + resources in constrained systems, but to also be frugal in the + allocation of very short names, keeping them in reserve for + applications that are likely to enjoy wide use and can make good use + of their shortness. + + The expert is also instructed to direct the registrant to provide a + specification (Section 4.6 of RFC 8126 [BCP26]) but can make + exceptions -- for instance, when a specification is not available at + the time of registration but is likely forthcoming. + + Any questions or issues that might interest a wider audience might be + raised by the expert on the core-parameters@ietf.org mailing list for + a time-limited discussion. This might include security + considerations, or opportunities for orchestration, e.g., when + different names with similar intent are being or could be registered. + + If the expert becomes aware of target attributes that are deployed + and in use, they may also initiate a registration on their own if + they deem that such a registration can avert potential future + collisions. + +2.2. Structure of Entries + + Each entry in the registry must include the following: + + Attribute Name: + A lowercase ASCII string [STD80] that starts with a letter and can + contain digits and hyphen-minus characters afterward + ([a-z][-a-z0-9]*). (Note that [RFC8288] requires target attribute + names to be interpreted in a case-insensitive way; the restriction + to lowercase here ensures that they are registered in a + predictable form.) + + Brief Description: + A brief description. + + Change Controller: + See Section 2.3 of RFC 8126 [BCP26]. + + Reference: + A reference document that provides a description of the target + attribute, including the semantics for when the target attribute + appears more than once in a link. + +2.3. Initial Entries + + Initial entries in this registry are listed in Table 1. + + +===========+=========================+============+===============+ + | Attribute | Brief Description | Change | Reference | + | Name | | Controller | | + +===========+=========================+============+===============+ + | href | reserved (not useful as | IETF | [RFC6690] | + | | target attribute name) | | | + +-----------+-------------------------+------------+---------------+ + | anchor | reserved (not useful as | IETF | [RFC6690] | + | | target attribute name) | | | + +-----------+-------------------------+------------+---------------+ + | rel | reserved (not useful as | IETF | [RFC6690] | + | | target attribute name) | | | + +-----------+-------------------------+------------+---------------+ + | rev | reserved (not useful as | IETF | [RFC6690] | + | | target attribute name) | | | + +-----------+-------------------------+------------+---------------+ + | hreflang | (Web Linking) | IETF | [RFC8288] | + +-----------+-------------------------+------------+---------------+ + | media | (Web Linking) | IETF | [RFC8288] | + +-----------+-------------------------+------------+---------------+ + | title | (Web Linking) | IETF | [RFC8288] | + +-----------+-------------------------+------------+---------------+ + | type | (Web Linking) | IETF | [RFC8288] | + +-----------+-------------------------+------------+---------------+ + | rt | resource type | IETF | Section 3.1 | + | | | | of [RFC6690] | + +-----------+-------------------------+------------+---------------+ + | if | interface description | IETF | Section 3.2 | + | | | | of [RFC6690] | + +-----------+-------------------------+------------+---------------+ + | sz | maximum size estimate | IETF | Section 3.3 | + | | | | of [RFC6690] | + +-----------+-------------------------+------------+---------------+ + | ct | Content-Format hint | IETF | Section 7.2.1 | + | | | | of [RFC7252] | + +-----------+-------------------------+------------+---------------+ + | obs | observable resource | IETF | Section 6 of | + | | | | [RFC7641] | + +-----------+-------------------------+------------+---------------+ + | hct | HTTP-CoAP URI mapping | IETF | Section 5.5 | + | | template | | of [RFC8075] | + +-----------+-------------------------+------------+---------------+ + | osc | hint: resource only | IETF | Section 9 of | + | | accessible using OSCORE | | [RFC8613] | + +-----------+-------------------------+------------+---------------+ + | ep | Endpoint Name (with | IETF | Section 9.3 | + | | rt="core.rd-ep") | | of [RFC9176] | + +-----------+-------------------------+------------+---------------+ + | d | Sector (with | IETF | Section 9.3 | + | | rt="core.rd-ep") | | of [RFC9176] | + +-----------+-------------------------+------------+---------------+ + | base | Registration Base URI | IETF | Section 9.3 | + | | (with rt="core.rd-ep") | | of [RFC9176] | + +-----------+-------------------------+------------+---------------+ + | et | Endpoint Type (with | IETF | Section 9.3 | + | | rt="core.rd-ep") | | of [RFC9176] | + +-----------+-------------------------+------------+---------------+ + + Table 1: Initial Entries in the Target Attributes Registry + + A number of names are reserved, as they are used for parameters in + links other than target attributes. A further set of target + attributes is predefined in [RFC8288] and is imported into this + registry. + + Section 9.3 of [RFC9176] created the "RD Parameters" IANA registry. + Per this document, IANA has added the following note to that + registry: + + | Note: In accordance with RFC 9423, all entries with the "A" flag + | set, including new ones, MUST also be registered in the "Target + | Attributes" registry [IANA.core-parameters]. + +3. Security Considerations + + The security considerations of [RFC8288] apply, as do those of the + discovery specifications [RFC6690], [RFC7252], and [RFC9176]. + +4. References + +4.1. Normative References + + [BCP26] Best Current Practice 26, + . + 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, + . + + [IANA.core-parameters] + IANA, "Constrained RESTful Environments (CoRE) + Parameters", + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [STD80] Internet Standard 80, + . + At the time of writing, this STD comprises the following: + + Cerf, V., "ASCII format for network interchange", STD 80, + RFC 20, DOI 10.17487/RFC0020, October 1969, + . + +4.2. Informative References + + [RFC5988] Nottingham, M., "Web Linking", RFC 5988, + DOI 10.17487/RFC5988, October 2010, + . + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, + . + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + . + + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + . + + [RFC8075] Castellani, A., Loreto, S., Rahman, A., Fossati, T., and + E. Dijk, "Guidelines for Mapping Implementations: HTTP to + the Constrained Application Protocol (CoAP)", RFC 8075, + DOI 10.17487/RFC8075, February 2017, + . + + [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security for Constrained RESTful Environments + (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, + . + + [RFC9176] Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and + P. van der Stok, "Constrained RESTful Environments (CoRE) + Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April + 2022, . + +Acknowledgements + + The CoRE Working Group had been discussing setting up a registry for + target attributes since the final touches were made on [RFC6690]. + The update of the Web Linking specification to [RFC8288] provided the + formal setting, but it took until Jaime Jiménez provided the set of + initial registrations to generate a first draft version of this + specification. The current document addresses additional input and + Working Group Last Call comments by Esko Dijk, Marco Tiloca, Thomas + Fossati, and Mohamed Boucadair, as well as Area Director review + comments from Rob Wilton. + +Contributors + + Jaime Jiménez + Ericsson + Email: jaime@iki.fi + + + Jaime provided the list of initial registrations. + +Author's Address + + Carsten Bormann + Universität Bremen TZI + Postfach 330440 + D-28359 Bremen + Germany + Phone: +49-421-218-63921 + Email: cabo@tzi.org -- cgit v1.2.3