summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc9423.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc9423.txt')
-rw-r--r--doc/rfc/rfc9423.txt359
1 files changed, 359 insertions, 0 deletions
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,
+ <https://www.rfc-editor.org/info/bcp26>.
+ 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,
+ <https://www.rfc-editor.org/info/rfc8126>.
+
+ [IANA.core-parameters]
+ IANA, "Constrained RESTful Environments (CoRE)
+ Parameters",
+ <https://www.iana.org/assignments/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,
+ <https://www.rfc-editor.org/info/rfc2119>.
+
+ [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>.
+
+ [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
+ DOI 10.17487/RFC8288, October 2017,
+ <https://www.rfc-editor.org/info/rfc8288>.
+
+ [STD80] Internet Standard 80,
+ <https://www.rfc-editor.org/info/std80>.
+ 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,
+ <https://www.rfc-editor.org/info/rfc20>.
+
+4.2. Informative References
+
+ [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
+ DOI 10.17487/RFC5988, October 2010,
+ <https://www.rfc-editor.org/info/rfc5988>.
+
+ [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
+ Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
+ <https://www.rfc-editor.org/info/rfc6690>.
+
+ [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>.
+
+ [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>.
+
+ [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,
+ <https://www.rfc-editor.org/info/rfc8075>.
+
+ [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,
+ <https://www.rfc-editor.org/info/rfc8613>.
+
+ [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, <https://www.rfc-editor.org/info/rfc9176>.
+
+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