From c43d4620cbb87a4afae84733e221c74404c62c66 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 22 Nov 2023 13:24:06 +0100 Subject: [PATCH 1/6] Add discussion of and CoAP Options for CRI use in CoAP --- draft-ietf-core-href.md | 87 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index f6419ab..3521240 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -65,6 +65,7 @@ normative: BCP26: -: ianacons =: RFC8126 + IANA.core-parameters: I-D.carpenter-6man-rfc6874bis: zonebis RFC8610: cddl Unicode: @@ -953,8 +954,79 @@ properties of UTF-8 make this a simple linear process.) > text-pet-sequence elements for their representation typically need > to process them byte by byte. +# CoAP Integration + +This section discusses ways in which CRIs can be used in the context +of the CoAP protocol {{-coap}}. + +## Converting Between CoAP CRIs and Sets of CoAP Options + +... Analogue to {{Sections 6.4 and 6.5 of -coap}}... + +## CoAP Options for Forward-Proxies {#coap-options} + +Apart from the above procedures to convert CoAP CRIs to and from sets +of CoAP Options, two additional CoAP Options are defined in {{Section +5.10.2 of -coap}} that support requests to forward-proxies: + +* Proxy-Uri, and +* its more lightweight variant, Proxy-Scheme + +This section defines analogues of these that employ CRIs and the URI +Scheme numering provided by the present specification. + +### Proxy-CRI + + | No. | C | U | N | R | Name | Format | Length | Default | + | TBD235 | x | x | - | | Proxy-Cri | opaque | 1-1023 | (none) | +{: #tab-proxy-cri title="Proxy-Cri CoAP Option"} + +The Proxy-CRI Option carries an encoded CBOR data item that represents +an absolute CRI reference. +It is used analogously to Proxy-Uri as defined in {{Section 5.10.2 +of -coap}}. +The Proxy-Cri Option MUST take precedence over any of the Uri-Host, +Uri-Port, Uri-Path or Uri-Query options, as well as over any +Proxy-Uri Option (each of which MUST NOT be +included in a request containing the Proxy-Cri Option). + + +### Proxy-Scheme-Number + + + | No. | C | U | N | R | Name | Format | Length | Default | + | TBD239 | x | x | - | | Proxy-Scheme-Number | uint | 1-255 | (none) | +{: #tab-proxy-scheme-number title="Proxy-Scheme-Number CoAP Option"} + +The Proxy-Scheme-Number Option carries a URI Scheme Number represented as a +CoAP unsigned integer. +It is used analogously to Proxy-Scheme as defined in {{Section 5.10.2 +of -coap}}. + +Since CoAP Options are only defined as empty, (text) string, opaque +(byte string), or unsigned integer, the Option carries an unsigned +integer that gives the 1's complement of the URI Scheme Number, i.e.: + +~~~ math +option value = -1 - scheme number +~~~ + +[^scheme-negative] + +[^scheme-negative]: DISCUSS: Should the scheme registry simply use + unsigned numbers so it can be used here right away and the 1's + complement form is only used specifically for the nint that + `scheme-id` at the start of CRIs is? + +[^location-scheme] + +[^location-scheme]: TO DO: Discuss the need for a + location-scheme-numeric option? + # Implementation Status {#impl} +{::boilerplate rfc7942info} + With the exception of the authority=true fix, host-names split into labels, and {{pet}}, CRIs are implemented in `https://gitlab.com/chrysn/micrurus`. A golang implementation of version -10 of this document is found at: @@ -981,7 +1053,7 @@ The security considerations discussed in {{Section 7 of RFC3986}} and ## CRI Scheme Numbers Registry {#cri-reg} This specification defines a new "CRI Scheme Numbers" sub-registry in -the "CoRE Parameters" registry {{!IANA.core-parameters}}, with the +the "CoRE Parameters" registry {{IANA.core-parameters}}, with the policy "Expert Review" ({{Section 4.5 of -ianacons}}). The objective is to have CRI scheme number values registered for all registered URI schemes (Uniform Resource Identifier (URI) Schemes @@ -1073,6 +1145,19 @@ IANA is requested to register the application-extension identifier [^replace-xxxx] +## CoAP Option Numbers Registry + +In the "CoAP Option Numbers" registry in the "CoRE Parameters" registry group [IANA.core-parameters], +IANA is requested to register the CoAP Option Numbers +as described in {{tab-iana-options}} and defined in {{coap-options}}. + + | No. | Name | Reference | + | TBD235 | Proxy-Cri | RFC-XXXX | + | TBD239 | Proxy-Scheme-Number | RFC-XXXX | +{: #tab-iana-options title="New CoAP Option Numbers"} + +[^replace-xxxx] + --- back # Mapping Scheme Numbers to Scheme Names {#sec-numbers} From 575e9057f63149454775d22a7e2ebb5f9a618995 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 22 Nov 2023 13:30:59 +0100 Subject: [PATCH 2/6] More realistic size limits for Proxy-Scheme-Number --- draft-ietf-core-href.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index 3521240..d7d4dd0 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -995,7 +995,7 @@ included in a request containing the Proxy-Cri Option). | No. | C | U | N | R | Name | Format | Length | Default | - | TBD239 | x | x | - | | Proxy-Scheme-Number | uint | 1-255 | (none) | + | TBD239 | x | x | - | | Proxy-Scheme-Number | uint | 0-3 | (none) | {: #tab-proxy-scheme-number title="Proxy-Scheme-Number CoAP Option"} The Proxy-Scheme-Number Option carries a URI Scheme Number represented as a From 35856e06a74f3fcb7eae2142b63744e923f2aabd Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Fri, 8 Dec 2023 15:56:50 +0100 Subject: [PATCH 3/6] Add a Section 8.1 --- draft-ietf-core-href.md | 103 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index d7d4dd0..abeb67f 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -961,7 +961,108 @@ of the CoAP protocol {{-coap}}. ## Converting Between CoAP CRIs and Sets of CoAP Options -... Analogue to {{Sections 6.4 and 6.5 of -coap}}... +This section provides an analogue to {{Sections 6.4 and 6.5 of -coap}}: +Computing a set of CoAP options from a request CRI {{decompose-coap}} and computing a +request CRI from a set of COAP options {{compose-coap}}. + +This section makes use of the mapping between CRI scheme ids +and URI scheme names shown in {{scheme-map}}: + +| CRI scheme id | URI scheme | +|---------------|------------| +| -1 | coap | +| -2 | coaps | +| -7 | coap+tcp | +| -8 | coaps+tcp | +| -9 | coap+ws | +| -10 | coaps+ws | +{: #scheme-map title="Mapping CRI scheme ids and URI scheme names"} + + +### Decomposing a Request CRI into a set of CoAP Options {#decompose-coap} + + The steps to parse a request's options from a CRI »cri« are as + follows. These steps either result in zero or more of the Uri-Host, + Uri-Port, Uri-Path, and Uri-Query Options being included in the + request or they fail. + +Where the following speaks of deriving a text-string for a CoAP Option +value from a data item in the CRI, the presence of any +`text-pet-sequence` subitem ({{pet}}) in this item fails this algorithm. + + 1. If »cri« is not an absolute CRI reference, then fail this + algorithm. + + 2. Translate the scheme id into a URI scheme name as per + {{scheme-map}}; if a scheme id not in this list is being used, + fail this algorithm. + Remember the specific variant of CoAP to be used based on this + URI scheme name. + + 3. If »cri« has a `fragment` component, then fail this algorithm. + + 4. If the `host` component of »cri« is a `host-name`, include a + Uri-Host Option and let that option's value be the text string + value of the `host-name`. + + 5. If »cri« has a `port` component, then let »port« be that + component's unsigned integer value; otherwise, let »port« be + the default port number for the scheme. + + 6. If »port« does not equal the request's destination UDP port, + include a Uri-Port Option and let that option's value be »port«. + + 7. If the value of the `path` component of »cri« is empty or + consists of a single empty string, then move to the next step. + + Otherwise, for each element in the »path« component, include a + Uri-Path Option and let that option's value be the text string + value of that element. + + 8. If »cri« has a `query` component, then, for each element in the + `query` component, include a Uri-Query Option and let that + option's value be the be the text string + value of that element. + +### Composing a Request URI from a Set of CoAP Options {#compose-coap} + + The steps to construct a CRI from a request's options are as follows. + These steps either result in a CRI or they fail. + + +[^clarify-host]: Hmm, this is asymmetric. Is this OK? + + + 1. Based on the variant of CoAP used in the request, choose a + `scheme-id` as per table {{scheme-map}}. Use that as the first + value in the resulting CRI array. + + 2. If the request includes a Uri-Host Option, insert an + `authority` with its value as the `host-name`. + If that value is not a valid + reg-name or IP-literal or IPv4address, fail the algorithm. + [^clarify-host] + + If the request does not include a Uri-Host Option, inser an + `authority` with `host-ip` being the byte string that + represents the request's destination IP address. + + 3. If the request includes a Uri-Port Option, let »port« be that + option's value. Otherwise, let »port« be the request's + destination UDP port. + If »port« is not the default port for the scheme, then insert + the integer value of »port« as the value of `port` in the + authority. + Otherwise, elide the `port`. + + 4. Insert a `path` component that contains an array built from + the text string values of the Uri-Path Options in the request, + or an empty array if no such options are present. + + 5. Insert a `query` component that contains an array built from + the text string values of the Uri-Query Options in the request, + or an empty array if no such options are present. + ## CoAP Options for Forward-Proxies {#coap-options} From 32d7ee35a6fb3b5bf3722ad03cc18b839a535913 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Mon, 11 Dec 2023 15:27:52 +0100 Subject: [PATCH 4/6] Clarify uri-host processing --- draft-ietf-core-href.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index abeb67f..23bad84 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -733,6 +733,7 @@ authority normalization would turn the percent-encoding back to the unreserved character that a dot is.) + {: #host-ip-to-uri} The value of a `host-ip` item MUST be represented as a string that matches the "IPv4address" or "IP-literal" rule ({{Section 3.2.2 of RFC3986}}). @@ -1005,6 +1006,13 @@ value from a data item in the CRI, the presence of any Uri-Host Option and let that option's value be the text string value of the `host-name`. + If the `host` component of »cri« is a `host-ip`, check whether + the IP address given represents the request's + destination IP address (and, if present, zone-id). + Only if it does not, include a Uri-Host Option, and let that + option's value be the text value of the URI representation of + the IP address, as derived in {{host-ip-to-uri}}. + 5. If »cri« has a `port` component, then let »port« be that component's unsigned integer value; otherwise, let »port« be the default port number for the scheme. @@ -1024,28 +1032,30 @@ value from a data item in the CRI, the presence of any option's value be the be the text string value of that element. -### Composing a Request URI from a Set of CoAP Options {#compose-coap} +### Composing a Request CRI from a Set of CoAP Options {#compose-coap} The steps to construct a CRI from a request's options are as follows. These steps either result in a CRI or they fail. -[^clarify-host]: Hmm, this is asymmetric. Is this OK? - - 1. Based on the variant of CoAP used in the request, choose a `scheme-id` as per table {{scheme-map}}. Use that as the first value in the resulting CRI array. 2. If the request includes a Uri-Host Option, insert an - `authority` with its value as the `host-name`. - If that value is not a valid - reg-name or IP-literal or IPv4address, fail the algorithm. - [^clarify-host] - - If the request does not include a Uri-Host Option, inser an + `authority` with its value determined as follows: + If the value of the Uri-Host Option is a `reg-name`, include + this as the `host-name`. + If the value is an IP-literal or IPv4address, extract any + `zone-id`, and represent the IP address as a byte string of + the correct length in `host-ip`, followed by any `zone-id` + extracted if present. + If the value is none of the three, fail this algorithm. + + If the request does not include a Uri-Host Option, insert an `authority` with `host-ip` being the byte string that - represents the request's destination IP address. + represents the request's destination IP address and, + if one is present in the request's destination, add a `zone-id`. 3. If the request includes a Uri-Port Option, let »port« be that option's value. Otherwise, let »port« be the request's From 6c2b0dd2944b9c64f4a8869e350677265d568a41 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 10 Jan 2024 05:02:20 +0100 Subject: [PATCH 5/6] Use conventional BCP reference for BCP26 (Could do other BCPs as well.) --- draft-ietf-core-href.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index 23bad84..2ce8985 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -64,7 +64,7 @@ normative: IANA.uri-schemes: BCP26: -: ianacons - =: RFC8126 +# =: RFC8126 IANA.core-parameters: I-D.carpenter-6man-rfc6874bis: zonebis RFC8610: cddl @@ -1165,7 +1165,7 @@ The security considerations discussed in {{Section 7 of RFC3986}} and This specification defines a new "CRI Scheme Numbers" sub-registry in the "CoRE Parameters" registry {{IANA.core-parameters}}, with the -policy "Expert Review" ({{Section 4.5 of -ianacons}}). +policy "Expert Review" ({{Section 4.5 of RFC8126@-ianacons}}). The objective is to have CRI scheme number values registered for all registered URI schemes (Uniform Resource Identifier (URI) Schemes registry), as well as exceptionally for certain text strings that the From aa3a87ab48dce0244e2bb3d3ff79622f816ff21a Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 10 Jan 2024 05:13:20 +0100 Subject: [PATCH 6/6] -14: Publish snapshot from CoAP integration branch (PR #81) --- draft-ietf-core-href.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/draft-ietf-core-href.md b/draft-ietf-core-href.md index 2ce8985..c4be513 100644 --- a/draft-ietf-core-href.md +++ b/draft-ietf-core-href.md @@ -92,7 +92,13 @@ memory size. [^status] [^status]: (This "cref" paragraph will be removed by the RFC editor:)\\ - The present revision –14 of this draft picks up comments from the shepherd review. + The present revision –14 of this draft picks up comments from the + shepherd review and adds sections on CoAP integration and on `cri` + application-oriented literals for the Extended Diagnostic + Notation.\\ + This revision still contains open issues and is intended to serve + as a snapshot while the processing of the shepherd review is being + completed. --- middle @@ -1528,7 +1534,11 @@ Changes from -09 to -14 * Add Christian Amsüss as contributor -* Add CBOR EDN application-extension "`cri`" (see {{edn-cri}} and {{cri-iana}}). +* Add CBOR EDN application-extension "`cri`" (see {{edn-cri}} and + {{cri-iana}}). + +* Add Section on CoAP integration (and new CoAP Options Proxy-Cri and + Proxy-Scheme-Number). Changes from -08 to -09