draft-ietf-core-href-03.txt   draft-ietf-core-href-04.txt 
CoRE Working Group K. Hartke CoRE Working Group K. Hartke
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Standards Track 9 March 2020 Intended status: Standards Track C. Bormann, Ed.
Expires: 10 September 2020 Expires: 8 November 2021 Universitaet Bremen TZI
7 May 2021
Constrained Resource Identifiers Constrained Resource Identifiers
draft-ietf-core-href-03 draft-ietf-core-href-04
Abstract Abstract
The Constrained Resource Identifier (CRI) is a complement to the The Constrained Resource Identifier (CRI) is a complement to the
Uniform Resource Identifier (URI) that serializes the URI components Uniform Resource Identifier (URI) that serializes the URI components
in Concise Binary Object Representation (CBOR) instead of a sequence in Concise Binary Object Representation (CBOR) instead of a sequence
of characters. This simplifies parsing, comparison and reference of characters. This simplifies parsing, comparison and reference
resolution in environments with severe limitations on processing resolution in environments with severe limitations on processing
power, code size, and memory size. power, code size, and memory size.
skipping to change at line 44 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on 10 September 2020. This Internet-Draft will expire on 8 November 2021.
Copyright Notice Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the Copyright (c) 2021 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components and restrictions with respect to this document. Code Components
extracted from this document must include Simplified BSD License text extracted from this document must include Simplified BSD License text
as described in Section 4.e of the Trust Legal Provisions and are as described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Simplified BSD License. provided without warranty as described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Constraints 2. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Creation and Normalization 3. Creation and Normalization . . . . . . . . . . . . . . . . . 5
4. Comparison 4. Comparison . . . . . . . . . . . . . . . . . . . . . . . . . 6
5. CRI References 5. CRI References . . . . . . . . . . . . . . . . . . . . . . . 6
5.1. CBOR Serialization 5.1. CBOR Serialization . . . . . . . . . . . . . . . . . . . 7
5.2. Reference Resolution 5.2. Reference Resolution . . . . . . . . . . . . . . . . . . 8
6. Relationship between CRIs, URIs and IRIs 6. Relationship between CRIs, URIs and IRIs . . . . . . . . . . 10
6.1. Converting CRIs to URIs 6.1. Converting CRIs to URIs . . . . . . . . . . . . . . . . . 10
7. Security Considerations 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12
8. IANA Considerations 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
9. References 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
9.1. Normative References 9.1. Normative References . . . . . . . . . . . . . . . . . . 12
9.2. Informative References 9.2. Informative References . . . . . . . . . . . . . . . . . 13
Appendix A. Change Log Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 14
Acknowledgements Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15
Author's Address Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
The Uniform Resource Identifier (URI) [RFC3986] and its most common The Uniform Resource Identifier (URI) [RFC3986] and its most common
usage, the URI reference, are the Internet standard for linking to usage, the URI reference, are the Internet standard for linking to
resources in hypertext formats such as HTML [W3C.REC-html52-20171214] resources in hypertext formats such as HTML [W3C.REC-html52-20171214]
and the HTTP "Link" header field [RFC8288]. or the HTTP "Link" header field [RFC8288].
A URI reference is a sequence of characters chosen from the A URI reference is a sequence of characters chosen from the
repertoire of US-ASCII characters. The individual components of a repertoire of US-ASCII characters. The individual components of a
URI reference are delimited by a number of reserved characters, which URI reference are delimited by a number of reserved characters, which
necessitates the use of an escape mechanism ("percent-encoding") when necessitates the use of a character escape mechanism called "percent-
these reserved characters are used in a non-delimiting function. The encoding" when these reserved characters are used in a non-delimiting
resolution of URI references involves parsing a character sequence function. The resolution of URI references involves parsing a
into its components, combining those components with the components character sequence into its components, combining those components
of a base URI, merging path components, removing dot-segments, and with the components of a base URI, merging path components, removing
recomposing the result back into a character sequence. dot-segments, and recomposing the result back into a character
sequence.
Overall, the proper handling of URI references is relatively Overall, the proper handling of URI references is quite intricate.
intricate. This can be a problem, especially in constrained This can be a problem especially in constrained environments
environments [RFC7228] where nodes often have severe code size and [RFC7228], where nodes often have severe code size and memory size
memory size limitations. As a result, many implementations in such limitations. As a result, many implementations in such environments
environments support only an ad-hoc, informally-specified, bug- support only an ad-hoc, informally-specified, bug-ridden, non-
ridden, non-interoperable subset of half of RFC 3986. interoperable subset of half of RFC 3986.
This document defines the Constrained Resource Identifier (CRI) by This document defines the Constrained Resource Identifier (CRI) by
constraining URIs to a simplified subset and serializing their constraining URIs to a simplified subset and serializing their
components in Concise Binary Object Representation (CBOR) components in Concise Binary Object Representation (CBOR) [RFC8949]
[RFC7049bis] instead of a sequence of characters. This allows instead of a sequence of characters. This allows typical operations
typical operations on URI references such as parsing, comparison and on URI references such as parsing, comparison and reference
reference resolution to be implemented (including all corner cases) resolution (including all corner cases) to be implemented in a
in a comparatively small amount of code. comparatively small amount of code.
As a result of simplification, however, CRIs are not capable of As a result of simplification, however, CRIs are not capable of
expressing all URIs permitted by the generic syntax of RFC 3986 expressing all URIs permitted by the generic syntax of RFC 3986
(hence the "constrained" in "Constrained Resource Identifier"). The (hence the "constrained" in "Constrained Resource Identifier"). The
supported subset includes all URIs of the Constrained Application supported subset includes all URIs of the Constrained Application
Protocol (CoAP) [RFC7252], most URIs of the Hypertext Transfer Protocol (CoAP) [RFC7252], most URIs of the Hypertext Transfer
Protocol (HTTP) [RFC7230], and other URIs that are similar. The Protocol (HTTP) [RFC7230], Uniform Resource Names (URNs) [RFC8141],
exact constraints are defined in Section 2. and other similar URIs. The exact constraints are defined in
Section 2.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
In this specification, the term "byte" is used in its now customary
sense as a synonym for "octet".
Terms defined in this document appear in _cursive_ where they are Terms defined in this document appear in _cursive_ where they are
introduced (rendered in plain text as the new term surrounded by introduced (rendered in plain text as the new term surrounded by
underscores). underscores).
2. Constraints 2. Constraints
A Constrained Resource Identifier consists of the same five A Constrained Resource Identifier consists of the same five
components as a URI: scheme, authority, path, query, and fragment. components as a URI: scheme, authority, path, query, and fragment.
The components are subject to the following constraints: The components are subject to the following constraints:
C1. The scheme name can be any Unicode string (see Definition D80 C1. The scheme name can be any Unicode string (see Definition D80
in [Unicode]) that matches the syntax defined in Section 3.1 of in [Unicode]) that matches the syntax of a URI scheme (see
[RFC3986] and is lowercase (see Definition D139 in [Unicode]). Section 3.1 of [RFC3986]) and is lowercase (see Definition D139
in [Unicode]).
C2. An authority is always a host identified by an IP address or C2. An authority is always a host identified by an IP address or
registered name, along with optional port information. User registered name, along with optional port information. User
information is not supported. information is not supported.
C3. An IP address can be either an IPv4 address or an IPv6 address. C3. An IP address can be either an IPv4 address or an IPv6 address.
IPv6 scoped addressing zone identifiers and future versions of IPv6 scoped addressing zone identifiers and future versions of
IP are not supported. IP are not supported.
C4. A registered name can be any Unicode string that is lowercase C4. A registered name can be any Unicode string that is lowercase
skipping to change at line 167 skipping to change at page 4, line 40
Empty ports or ports outside this range are not supported. Empty ports or ports outside this range are not supported.
C6. The port is omitted if and only if the port would be the same C6. The port is omitted if and only if the port would be the same
as the scheme's default port (provided the scheme is defining as the scheme's default port (provided the scheme is defining
such a default port) or the scheme is not using ports. such a default port) or the scheme is not using ports.
C7. A path consists of zero or more path segments. A path must not C7. A path consists of zero or more path segments. A path must not
consist of a single zero-length path segment, which is consist of a single zero-length path segment, which is
considered equivalent to a path of zero path segments. considered equivalent to a path of zero path segments.
C8. A path segment can be any Unicode string that is in NFC C8. A path segment can be any Unicode string that is in NFC, with
(including the zero-length string) with the exception of the the exception of the special "." and ".." complete path
special "." and ".." complete path segments. No special segments. It can be the zero-length string. No special
constraints are placed on the first path segment. constraints are placed on the first path segment.
C9. A query always consists of one or more query parameters. A C9. A query always consists of one or more query parameters. A
query parameter can be any Unicode string that is in NFC. It query parameter can be any Unicode string that is in NFC. It
is often in the form of a "key=value" pair. When converting a is often in the form of a "key=value" pair. When converting a
CRI to a URI, query parameters are separated by an ampersand CRI to a URI, query parameters are separated by an ampersand
("&") character. (This matches the structure and encoding of ("&") character. (This matches the structure and encoding of
the query in CoAP URIs.) the target URI in CoAP requests.) Queries are optional; there
is a difference between an absent query and a single query
parameter that is the empty string.
C10. A fragment identifier can be any Unicode string that is in NFC. C10. A fragment identifier can be any Unicode string that is in NFC.
Fragment identifiers are optional; there is a difference
between an absent fragment identifier and a fragment identifier
that is the empty string.
C11. The syntax of registered names, path segments, query C11. The syntax of registered names, path segments, query
parameters, and fragment identifiers may be further restricted parameters, and fragment identifiers may be further restricted
and sub-structured by the scheme. There is no support, and sub-structured by the scheme. There is no support,
however, for escaping sub-delimiters that are not intended to however, for escaping sub-delimiters that are not intended to
be used in a delimiting function. be used in a delimiting function.
C12. When converting a CRI to a URI, any character that is outside C12. When converting a CRI to a URI, any character that is outside
the allowed character range or a delimiter in the URI syntax is the allowed character range or is a delimiter in the URI syntax
percent-encoded. Percent-encoding always uses the UTF-8 is percent-encoded. For CRIs, percent-encoding always uses the
encoding form (see Definition D92 in [Unicode]) to convert the UTF-8 encoding form (see Definition D92 in [Unicode]) to
character to a sequence of one or more octets. convert the character to a sequence of bytes (that is then
converted to a sequence of %HH triplets).
3. Creation and Normalization 3. Creation and Normalization
Resource identifiers are generally created on the initial creation of In general, resource identifiers are created on the initial creation
a resource with a certain resource identifier, or the initial of a resource with a certain resource identifier, or the initial
exposition of a resource under a particular resource identifier. exposition of a resource under a particular resource identifier.
A Constrained Resource Identifier SHOULD be created by the naming A Constrained Resource Identifier SHOULD be created by the naming
authority that governs the namespace of the resource identifier. For authority that governs the namespace of the resource identifier (see
example, for the resources of an HTTP origin server, that server is also [RFC8820]). For example, for the resources of an HTTP origin
responsible for creating the CRIs for those resources. server, that server is responsible for creating the CRIs for those
resources.
The creator MUST ensure that any CRI created satisfies the The naming authority MUST ensure that any CRI created satisfies the
constraints defined in Section 2. The creation of a CRI fails if the constraints defined in Section 2. The creation of a CRI fails if the
CRI cannot be validated to satisfy all of the constraints. CRI cannot be validated to satisfy all of the constraints.
If a creator creates a CRI from user input, it MAY apply the If a naming authority creates a CRI from user input, it MAY apply the
following (and only the following) normalizations to get the CRI more following (and only the following) normalizations to get the CRI more
likely to validate: map the scheme name to lowercase (C1.); map the likely to validate:
registered name to NFC (C4.); elide the port if it's the default port
for the scheme (C6.); elide a single zero-length path segment (C7.); * map the scheme name to lowercase (C1);
map path segments, query parameters and the fragment identifier to
NFC (C8., C9., C10.). * map the registered name to NFC (C4);
* elide the port if it is the default port for the scheme (C6);
* elide a single zero-length path segment (C7);
* map path segments, query parameters and the fragment identifier to
NFC (C8, C9, C10).
Once a CRI has been created, it can be used and transferred without Once a CRI has been created, it can be used and transferred without
further normalization. All operations that operate on a CRI SHOULD further normalization. All operations that operate on a CRI SHOULD
rely on the assumption that the CRI is appropriately pre-normalized. rely on the assumption that the CRI is appropriately pre-normalized.
(This does not contradict the requirement that when CRIs are (This does not contradict the requirement that when CRIs are
transferred, recipients must operate on as-good-as untrusted input transferred, recipients must operate on as-good-as untrusted input
and fail gracefully in the face of malicious inputs.) and fail gracefully in the face of malicious inputs.)
4. Comparison 4. Comparison
One of the most common operations on CRIs is comparison: determining One of the most common operations on CRIs is comparison: determining
whether two CRIs are equivalent, without using the CRIs to access whether two CRIs are equivalent, without dereferencing the CRIs
their respective resource(s). (using them to access their respective resource(s)).
Determination of equivalence or difference of CRIs is based on simple Determination of equivalence or difference of CRIs is based on simple
component-wise comparison. If two CRIs are identical component-by- component-wise comparison. If two CRIs are identical component-by-
component (using code-point-by-code-point comparison for components component (using code-point-by-code-point comparison for components
that are Unicode strings) then it is safe to conclude that they are that are Unicode strings) then it is safe to conclude that they are
equivalent. equivalent.
This comparison mechanism is designed to minimize false negatives This comparison mechanism is designed to minimize false negatives
while strictly avoiding false positives. The constraints defined in while strictly avoiding false positives. The constraints defined in
Section 2 imply the most common forms of syntax- and scheme-based Section 2 imply the most common forms of syntax- and scheme-based
normalizations in URIs, but do not comprise protocol-based normalizations in URIs, but do not comprise protocol-based
normalizations that require accessing the resources or detailed normalizations that require accessing the resources or detailed
knowledge of the scheme's dereference algorithm. False negatives can knowledge of the scheme's dereference algorithm. False negatives can
be caused by resource aliases and CRIs that do not fully satisfy the be caused, for example, by CRIs that are not appropriately pre-
constraints. normalized and by resource aliases.
When CRIs are compared to select (or avoid) a network action, such as When CRIs are compared to select (or avoid) a network action, such as
retrieval of a representation, fragment components (if any) should be retrieval of a representation, fragment components (if any) should be
excluded from the comparison. excluded from the comparison.
5. CRI References 5. CRI References
The most common usage of a Constrained Resource Identifier is to The most common usage of a Constrained Resource Identifier is to
embed it in resource representations, e.g., to express a hyperlink embed it in resource representations, e.g., to express a hyperlink
between the represented resource and the resource identified by the between the represented resource and the resource identified by the
CRI. CRI.
This section defines the serialization of CRIs in Concise Binary This section defines the serialization of CRIs in Concise Binary
Object Representation (CBOR) [RFC7049bis]. To reduce representation Object Representation (CBOR) [RFC8949]. To reduce representation
size, CRIs are not serialized directly. Instead, CRIs are indirectly size, CRIs are not serialized directly. Instead, CRIs are indirectly
referenced through _CRI references_ that take advantage of referenced through _CRI references_. These take advantage of
hierarchical locality. The CBOR serialization of CRI references is hierarchical locality and provide a very compact encoding. The CBOR
specified in Section 5.1. serialization of CRI references is specified in Section 5.1.
The only operation defined on a CRI reference is _reference The only operation defined on a CRI reference is _reference
resolution_: the act of transforming a CRI reference into a CRI. An resolution_: the act of transforming a CRI reference into a CRI. An
application MUST implement this operation by applying the algorithm application MUST implement this operation by applying the algorithm
specified in Section 5.2 or any algorithm that is functionally specified in Section 5.2 (or any algorithm that is functionally
equivalent to it. equivalent to it).
The method of transforming a CRI into a CRI reference is unspecified; The reverse operation of transforming a CRI into a CRI reference is
implementations are free to use any algorithm as long as reference unspecified; implementations are free to use any algorithm as long as
resolution of the resulting CRI reference yields the original CRI. reference resolution of the resulting CRI reference yields the
original CRI. Notably, a CRI reference is not required to satisfy
all of the constraints of a CRI; the only requirement on a CRI
reference is that reference resolution MUST yield the original CRI.
When testing for equivalence or difference, applications SHOULD NOT When testing for equivalence or difference, applications SHOULD NOT
directly compare CRI references; the references should be resolved to directly compare CRI references; the references should be resolved to
their respective CRI before comparison. their respective CRI before comparison.
5.1. CBOR Serialization 5.1. CBOR Serialization
A CRI reference is encoded as a CBOR array [RFC7049bis] that contains A CRI reference is encoded as a CBOR array [RFC8949], with the
a sequence of zero or more options. Each option consists of an structure as described in the Concise Data Definition Language (CDDL)
option number followed by an option value, holding one component or [RFC8610] as follows:
sub-component of the CRI reference. To reduce size, both option
numbers and option values are immediate elements of the CBOR array
and appear in alternating order.
Not all possible sequences of options denote a well-formed CRI
reference. The structure can be described in the Concise Data
Definition Language (CDDL) [RFC8610] as follows:
CRI-Reference = [ CRI-Reference = [
(?scheme, ?((host.name // host.ip), ?port) // path.type), (authority // discard),
*path, *path,
*query, ? (([], fragment) ; include array only if
?fragment //([+query], ?fragment)) ; at least one query and/or fragment
] ]
scheme = (0, text .regexp "[a-z][a-z0-9+.-]*") authority = (?scheme, ?(host, ?port))
host.name = (1, text) scheme = (scheme-name
host.ip = (2, bytes .size 4 / bytes .size 16) // COAP // COAPS // HTTP // HTTPS)
port = (3, 0..65535) scheme-name = (false, text .regexp "[a-z][a-z0-9+.-]*")
path.type = (4, 0..127) COAP = -1 COAPS = -2 HTTP = -3 HTTPS = -4
path = (5, text) host = (host-name // host-ip)
query = (6, text) host-name = (true, text)
fragment = (7, text) host-ip = bytes .size 4 / bytes .size 16
port = 0..65535
discard = 0..127
path = text
query = text
fragment = text
The options correspond to the (sub-)components of a CRI, as described The rules "scheme", "host", "port", "path", "query", "fragment"
in Section 2, with the addition of the "path.type" option. The correspond to the (sub-)components of a CRI, as described in
"path.type" option can be used to express path prefixes like "/", Section 2, with the addition of the "discard" element. While
"./", "../", "../../", etc. The exact semantics of the option values "scheme" and "host" can comprise two array elements, we will treat
are defined by Section 5.2. A sequence of options that is empty or such a combination as a single "element" in the following exposition.
starts with a "path" option is equivalent the same sequence prefixed (The combination is needed to disambiguate what would otherwise be a
by a "path.type" option with value 2. leading text string as a scheme, host, or path element.) The
"discard" element or its absence can be used to express path prefixes
such as "/", "./", "../", "../../", etc. The exact semantics of the
element values are defined by Section 5.2.
Examples: Examples:
[0, "coap", [-1, / scheme -- equivalent to ...false, "coap",... /
2, h'C6336401', h'C6336401', / host /
3, 61616, 61616, / port /
5, ".well-known", ".well-known", / path /
5, "core"] "core"] / path /
[4, 0, [".well-known", / path /
5, ".well-known", "core", / path /
5, "core", ["rt=temperature-c"]] / query /
6, "rt=temperature-c"]
A CRI reference is considered _absolute_ if the sequence of options A CRI reference is considered _well-formed_ if it matches the CDDL
starts with a "scheme" option. structure.
A CRI reference is considered _relative_ if the sequence of options A CRI reference is considered _absolute_ if it is well-formed and the
is empty or starts with an option other than a "scheme" option. sequence of elements starts with a "scheme".
A CRI reference is considered _relative_ if it is well-formed and the
sequence of elements is empty or starts with an element other than
those that would constitute a "scheme".
5.2. Reference Resolution 5.2. Reference Resolution
The term "relative" implies that a "base CRI" exists against which The term "relative" implies that a "base CRI" exists against which
the relative reference is applied. Aside from fragment-only the relative reference is applied. Aside from fragment-only
references, relative references are only usable when a base CRI is references, relative references are only usable when a base CRI is
known. known.
The following steps define the process of resolving any CRI reference The following steps define the process of resolving any well-formed
against a base CRI so that the result is a CRI in the form of an CRI reference against a base CRI so that the result is a CRI in the
absolute CRI reference: form of an absolute CRI reference:
1. Establish the base CRI of the CRI reference and express it in the 1. Establish the base CRI of the CRI reference and express it in the
form of an absolute CRI reference. The base CRI can be form of an absolute CRI reference. (The base CRI can be
established in a number of ways; see Section 5.1 of [RFC3986]. established in a number of ways; see Section 5.1 of [RFC3986].)
Assign each element an element number according to the number E
for that element in Table 1.
2. Determine the values of two variables, T and E, depending on the 2. Determine the values of two variables, T and E, based on the
first option of the CRI reference to be resolved, according to first element in the sequence of elements of the CRI reference to
Table 1. be resolved, according to Table 1.
+---------------------+------------------+------------------------+ 3. Initialize a buffer with all the elements from the base CRI where
| First Option Number | T | E | the element number is less than the value of E.
+=====================+==================+========================+
| 0 (scheme) | 0 | 0 |
+---------------------+------------------+------------------------+
| 1 (host.name) | 0 | 1 |
+---------------------+------------------+------------------------+
| 2 (host.ip) | 0 | 1 |
+---------------------+------------------+------------------------+
| 3 (port) | (invalid sequence of options) |
+---------------------+------------------+------------------------+
| 4 (path.type) | option value - 1 | if T < 0 then 5 else 6 |
+---------------------+------------------+------------------------+
| 5 (path) | 1 | 6 |
+---------------------+------------------+------------------------+
| 6 (query) | 0 | 6 |
+---------------------+------------------+------------------------+
| 7 (fragment) | 0 | 7 |
+---------------------+------------------+------------------------+
| none/empty sequence | 0 | 7 |
+---------------------+------------------+------------------------+
Table 1: Values of the Variables T and E 4. If the value of T is greater than 0, remove the last T-many
"path" elements from the end of the buffer (up to the number of
"path" elements in the buffer).
3. Initialize a buffer with all the options from the base CRI where 5. Append all the elements from the CRI reference to the buffer,
the option number is less than the value of E. except for any "discard" element.
4. If the value of T is greater than 0, remove the last T-many 6. If the number of "path" elements in the buffer is one and the
"path" options from the end of the buffer (up to the number of value of that element is the zero-length string, remove that
"path" options in the buffer). element from the buffer.
5. Append all the options from the CRI reference to the buffer, 7. Return the sequence of elements in the buffer as the resolved
except for any "path.type" option. CRI.
6. If the buffer contains a single "path" option and the value of +=====================+===============+===+
that option is the zero-length string, remove that option from | First Element | T | E |
the buffer. +=====================+===============+===+
| (scheme) | 0 | 0 |
+---------------------+---------------+---+
| (host) | 0 | 1 |
+---------------------+---------------+---+
| (discard) | element value | 3 |
+---------------------+---------------+---+
| (path) | 0 | 2 |
+---------------------+---------------+---+
| (query) | 0 | 3 |
+---------------------+---------------+---+
| (fragment) | 0 | 4 |
+---------------------+---------------+---+
| none/empty sequence | 0 | 4 |
+---------------------+---------------+---+
7. Return the sequence of options in the buffer. Table 1: Values of the Variables T and E
6. Relationship between CRIs, URIs and IRIs 6. Relationship between CRIs, URIs and IRIs
CRIs are meant to replace both Uniform Resource Identifiers (URIs) CRIs are meant to replace both Uniform Resource Identifiers (URIs)
[RFC3986] and Internationalized Resource Identifiers (IRIs) [RFC3987] [RFC3986] and Internationalized Resource Identifiers (IRIs) [RFC3987]
in constrained environments [RFC7228]. Applications in these in constrained environments [RFC7228]. Applications in these
environments may never need to use URIs and IRIs directly, especially environments may never need to use URIs and IRIs directly, especially
when the resource identifier is used simply for identification when the resource identifier is used simply for identification
purposes or when the CRI can be directly converted into a CoAP purposes or when the CRI can be directly converted into a CoAP
request. request.
skipping to change at line 415 skipping to change at page 10, line 29
CRI to URI CRI to URI
A CRI is converted to a URI as specified in Section 6.1. A CRI is converted to a URI as specified in Section 6.1.
URI to CRI URI to CRI
The method of converting a URI to a CRI is unspecified; The method of converting a URI to a CRI is unspecified;
implementations are free to use any algorithm as long as implementations are free to use any algorithm as long as
converting the resulting CRI back to a URI yields an equivalent converting the resulting CRI back to a URI yields an equivalent
URI. URI.
CRI to IRI CRI to IRI
A CRI can be converted to an IRI by first converting it to a URI, A CRI can be converted to an IRI by first converting it to a URI
and then converting the URI to an IRI as described in Section 3.2 as specified in Section 6.1, and then converting the URI to an IRI
of [RFC3987]. as described in Section 3.2 of [RFC3987].
IRI to CRI IRI to CRI
An IRI can be converted to a CRI by first converting it to a URI An IRI can be converted to a CRI by first converting it to a URI
as described in Section 3.1 of [RFC3987], and then converting the as described in Section 3.1 of [RFC3987], and then converting the
URI to a CRI. URI to a CRI as described above.
Everything in this section also applies to CRI references, URI Everything in this section also applies to CRI references, URI
references and IRI references. references and IRI references.
6.1. Converting CRIs to URIs 6.1. Converting CRIs to URIs
Applications MUST convert a CRI reference to a URI reference by Applications MUST convert a CRI reference to a URI reference by
determining the components of the URI reference according to the determining the components of the URI reference according to the
following steps and then recomposing the components to a URI following steps and then recomposing the components to a URI
reference string as specified in Section 5.3 of [RFC3986]. reference string as specified in Section 5.3 of [RFC3986].
scheme scheme
If the CRI reference contains a "scheme" option, the scheme If the CRI reference contains a "scheme" element, the scheme
component of the URI reference consists of the value of that component of the URI reference consists of the value of that
option. Otherwise, the scheme component is undefined. element. Otherwise, the scheme component is unset.
authority authority
If the CRI reference contains a "host.name" or "host.ip" option, If the CRI reference contains a "host-name" or "host-ip" element,
the authority component consists of the host subcomponent, the authority component of the URI reference consists of a host
optionally followed by a colon (":") character and the port subcomponent, optionally followed by a colon (":") character and a
subcomponent. Otherwise, the authority component is undefined. port subcomponent. Otherwise, the authority component is unset.
The host subcomponent consists of the value of the "host.name" or The host subcomponent consists of the value of the "host-name" or
"host.ip" option. "host-ip" element.
Any character in the value of a "host.name" option that is not in Any character in the value of a "host-name" element that is not in
the set of unreserved characters (Section 2.3 of [RFC3986]) or the set of unreserved characters (Section 2.3 of [RFC3986]) or
"sub-delims" (Section 2.2 of [RFC3986]) MUST be percent-encoded. "sub-delims" (Section 2.2 of [RFC3986]) MUST be percent-encoded.
The value of a "host.ip" option MUST be represented as a string The value of a "host-ip" element MUST be represented as a string
that matches the "IPv4address" or "IP-literal" rule (Section 3.2.2 that matches the "IPv4address" or "IP-literal" rule (Section 3.2.2
of [RFC3986]). of [RFC3986]).
If the CRI reference contains a "port" option, the port If the CRI reference contains a "port" element, the port
subcomponent consists of the value of that option in decimal subcomponent consists of the value of that element in decimal
notation. Otherwise, the colon (":") character and the port notation. Otherwise, the colon (":") character and the port
subcomponent are both omitted. subcomponent are both omitted.
path path
If the CRI reference is an empty sequence of options or starts If the CRI reference is an empty sequence of elements or starts
with a "port" option, a "path" option, or a "path.type" option with a "port" element, a "path" element, or a "discard" element
where the value is not 0, the conversion fails. where the value is not 0, the conversion fails.
If the CRI reference contains a "host.name" option, a "host.ip" If the CRI reference contains a "host-name" element, a "host-ip"
option or a "path.type" option where the value is not 0, the path element or a "discard" element, the path component of the URI
component of the URI reference is prefixed by a slash ("/") reference is prefixed by a slash ("/") character. Otherwise, the
character. Otherwise, the path component is prefixed by the empty path component is prefixed by the zero-length string.
string.
If the CRI reference contains one or more "path" options, the If the CRI reference contains one or more "path" elements, the
prefix is followed by the value of each option, separated by a prefix is followed by the value of each element, separated by a
slash ("/") character. slash ("/") character.
Any character in the value of a "path" option that is not in the Any character in the value of a "path" element that is not in the
set of unreserved characters or "sub-delims" or a colon (":") or set of unreserved characters or "sub-delims" or a colon (":") or
commercial at ("@") character MUST be percent-encoded. commercial at ("@") character MUST be percent-encoded.
If the authority component is defined and the path component does If the authority component is defined and the path component does
not match the "path-abempty" rule (Section 3.3 of [RFC3986]), the not match the "path-abempty" rule (Section 3.3 of [RFC3986]), the
conversion fails. conversion fails.
If the authority component is undefined and the scheme component If the authority component is unset and the scheme component is
is defined and the path component does not match the "path- defined and the path component does not match the "path-absolute",
absolute", "path-rootless" or "path-empty" rule (Section 3.3 of "path-rootless" or "path-empty" rule (Section 3.3 of [RFC3986]),
[RFC3986]), the conversion fails. the conversion fails.
If the authority component is undefined and the scheme component If the authority component is unset and the scheme component is
is undefined and the path component does not match the "path- unset and the path component does not match the "path-absolute",
absolute", "path-noscheme" or "path-empty" rule (Section 3.3 of "path-noscheme" or "path-empty" rule (Section 3.3 of [RFC3986]),
[RFC3986]), the conversion fails. the conversion fails.
query query
If the CRI reference contains one or more "query" options, the If the CRI reference contains one or more "query" elements, the
query component of the URI reference consists of the value of each query component of the URI reference consists of the value of each
option, separated by an ampersand ("&") character. Otherwise, the element, separated by an ampersand ("&") character. Otherwise,
query component is undefined. the query component is unset.
Any character in the value of a "query" option that is not in the Any character in the value of a "query" element that is not in the
set of unreserved characters or "sub-delims" or a colon (":"), set of unreserved characters or "sub-delims" or a colon (":"),
commercial at ("@"), slash ("/") or question mark ("?") character commercial at ("@"), slash ("/") or question mark ("?") character
MUST be percent-encoded. Additionally, any ampersand character MUST be percent-encoded. Additionally, any ampersand character
("&") in the option value MUST be percent-encoded. ("&") in the element value MUST be percent-encoded.
fragment fragment
If the CRI reference contains a fragment option, the fragment If the CRI reference contains a fragment element, the fragment
component of the URI reference consists of the value of that component of the URI reference consists of the value of that
option. Otherwise, the fragment component is undefined. element. Otherwise, the fragment component is unset.
Any character in the value of a "fragment" option that is not in Any character in the value of a "fragment" element that is not in
the set of unreserved characters or "sub-delims" or a colon (":"), the set of unreserved characters or "sub-delims" or a colon (":"),
commercial at ("@"), slash ("/") or question mark ("?") character commercial at ("@"), slash ("/") or question mark ("?") character
MUST be percent-encoded. MUST be percent-encoded.
7. Security Considerations 7. Security Considerations
Parsers of CRI references must operate on input that is assumed to be Parsers of CRI references must operate on input that is assumed to be
untrusted. This means that parsers MUST fail gracefully in the face untrusted. This means that parsers MUST fail gracefully in the face
of malicious inputs. Additionally, parsers MUST be prepared to deal of malicious inputs. Additionally, parsers MUST be prepared to deal
with resource exhaustion (e.g., resulting from the allocation of big with resource exhaustion (e.g., resulting from the allocation of big
data items) or exhaustion of the call stack (stack overflow). See data items) or exhaustion of the call stack (stack overflow). See
Section 10 of [RFC7049bis] for additional security considerations Section 10 of [RFC8949] for additional security considerations
relating to CBOR. relating to CBOR.
The security considerations discussed in Section 7 of [RFC3986] and The security considerations discussed in Section 7 of [RFC3986] and
Section 8 of [RFC3987] for URIs and IRIs also apply to CRIs. Section 8 of [RFC3987] for URIs and IRIs also apply to CRIs.
8. IANA Considerations 8. IANA Considerations
This document has no IANA actions. This document has no IANA actions.
9. References 9. References
skipping to change at line 551 skipping to change at page 13, line 19
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource
Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987,
January 2005, <https://www.rfc-editor.org/info/rfc3987>. January 2005, <https://www.rfc-editor.org/info/rfc3987>.
[RFC7049bis]
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", Work in Progress, Internet-Draft,
draft-ietf-cbor-7049bis-13, 8 March 2020,
<https://tools.ietf.org/html/draft-ietf-cbor-7049bis-13>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
Definition Language (CDDL): A Notational Convention to Definition Language (CDDL): A Notational Convention to
Express Concise Binary Object Representation (CBOR) and Express Concise Binary Object Representation (CBOR) and
JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
June 2019, <https://www.rfc-editor.org/info/rfc8610>. June 2019, <https://www.rfc-editor.org/info/rfc8610>.
[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>.
[Unicode] The Unicode Consortium, "The Unicode Standard, Version [Unicode] The Unicode Consortium, "The Unicode Standard, Version
12.1.0", ISBN 978-1-936213-25-2, May 2019, 13.0.0", ISBN 978-1-936213-26-9, March 2020,
<http://www.unicode.org/versions/Unicode12.1.0/>. <https://www.unicode.org/versions/Unicode13.0.0/>.
9.2. Informative References 9.2. Informative References
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, Constrained-Node Networks", RFC 7228,
DOI 10.17487/RFC7228, May 2014, DOI 10.17487/RFC7228, May 2014,
<https://www.rfc-editor.org/info/rfc7228>. <https://www.rfc-editor.org/info/rfc7228>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing", Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014, RFC 7230, DOI 10.17487/RFC7230, June 2014,
<https://www.rfc-editor.org/info/rfc7230>. <https://www.rfc-editor.org/info/rfc7230>.
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, DOI 10.17487/RFC7252, June 2014,
<https://www.rfc-editor.org/info/rfc7252>. <https://www.rfc-editor.org/info/rfc7252>.
[RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names
(URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
<https://www.rfc-editor.org/info/rfc8141>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
[RFC8820] Nottingham, M., "URI Design and Ownership", BCP 190,
RFC 8820, DOI 10.17487/RFC8820, June 2020,
<https://www.rfc-editor.org/info/rfc8820>.
[W3C.REC-html52-20171214] [W3C.REC-html52-20171214]
Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and Faulkner, S., Eicholz, A., Leithead, T., Danilo, A., and
S. Moon, "HTML 5.2", World Wide Web Consortium S. Moon, "HTML 5.2", World Wide Web Consortium
Recommendation REC-html52-20171214, 14 December 2017, Recommendation REC-html52-20171214, 14 December 2017,
<https://www.w3.org/TR/2017/REC-html52-20171214>. <https://www.w3.org/TR/2017/REC-html52-20171214>.
Appendix A. Change Log Appendix A. Change Log
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
Changes from -03 to -04:
* Minor editorial improvements.
* Renamed path.type/path-type to discard.
* Renamed option to element.
* Simplied Table 1.
* Use the CBOR structure inspired by Jim Schaad's proposals.
Changes from -02 to -03: Changes from -02 to -03:
* Expanded the set of supported schemes (#3). * Expanded the set of supported schemes (#3).
* Specified creation, normalization and comparison (#9). * Specified creation, normalization and comparison (#9).
* Clarified the default value of the "path.type" option (#33). * Clarified the default value of the "discard" option (#33).
* Removed the "append-relation" path type (#41). * Removed the "append-relation" discard option (#41).
* Renumbered the remaining path types. * Renumbered the remaining discards.
* Renumbered the option numbers. * Renumbered the option numbers.
* Restructured the document. * Restructured the document.
* Minor editorial improvements. * Minor editorial improvements.
Changes from -01 to -02: Changes from -01 to -02:
* Changed the syntax of schemes to exclude upper case characters * Changed the syntax of schemes to exclude upper case characters
(#13). (#13).
* Minor editorial improvements (#34 #37). * Minor editorial improvements (#34 #37).
Changes from -00 to -01: Changes from -00 to -01:
* None. * None.
Acknowledgements Acknowledgements
Thanks to Christian Amsuess, Carsten Bormann, Ari Keranen, Jim Schaad Thanks to Christian Amsüss, Ari Keränen, Jim Schaad and Dave Thaler
and Dave Thaler for helpful comments and discussions that have shaped for helpful comments and discussions that have shaped the document.
the document.
Author's Address Authors' Addresses
Klaus Hartke Klaus Hartke
Ericsson Ericsson
Torshamnsgatan 23 Torshamnsgatan 23
SE-16483 Stockholm SE-16483 Stockholm
Sweden Sweden
Email: klaus.hartke@ericsson.com Email: klaus.hartke@ericsson.com
Carsten Bormann (editor)
Universitaet Bremen TZI
Postfach 330440
D-28359 Bremen
Germany
Phone: +49-421-218-63921
Email: cabo@tzi.org
 End of changes. 81 change blocks. 
223 lines changed or deleted 267 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/