One document matched: draft-fossati-core-publish-option-02.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!-- vim: set ts=2 expandtab: -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.RFC.5988.xml">
<!ENTITY RFC6690 SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.RFC.6690.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-ietf-core-coap-18.xml">
<!ENTITY I-D.rahman-core-sleepy-problem-statement SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.draft-rahman-core-sleepy-problem-statement-01.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<?rfc comments="yes" ?>
<?rfc inline="yes" ?>
<rfc category="std" docName="draft-fossati-core-publish-option-02" ipr="trust200902">
<front>
<title>
Publish Option for CoAP
</title>
<author fullname="Thomas Fossati" initials="T.F." surname="Fossati">
<organization>KoanLogic</organization>
<address>
<email>tho@koanlogic.com</email>
</address>
</author>
<author fullname="Pierpaolo Giacomin" initials="P.G." surname="Giacomin">
<organization>Freelance</organization>
<address>
<email>yrz@anche.no</email>
</address>
</author>
<author fullname="Salvatore Loreto" initials="S.L." surname="Loreto">
<organization>Ericsson</organization>
<address>
<postal>
<street>Hirsalantie 11</street>
<city>Jorvas</city>
<code>02420</code>
<country>Finland</country>
</postal>
<email>salvatore.loreto@ericsson.com</email>
</address>
</author>
<date year="2013" month="October"/>
<area>General</area>
<workgroup>Internet Engineering Task Force</workgroup>
<keyword>CoAP, Monitor Option, sleepy sensor</keyword>
<abstract>
<t>This memo defines the Publish Option for the Constrained Application Protocol (CoAP). This Option is used by a CoAP Endpoint to control the authority delegation of one of its resources to another Endpoint. All the phases of the authority delegation process (setup, renewal, cancellation) are controlled by a simple RESTful protocol.</t>
<t>This memo also introduces the 'proxies' Web Linking relation type, to be used by a CoAP Proxy to explicitly advertise the resources that it can serve from its cache, or by forwarding the Client request upstream (either to the origin, or to another Proxy).</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>This memo defines the Publish Option for the Constrained Application Protocol <xref target="I-D.ietf-core-coap" />.</t>
<t>The Publish Option is used by a sleepy Endpoint (SEP) to temporarily delegate the authority of one of its resources to another, always on, Endpoint. The delegated Endpoint is typically a Proxy, though it could be an Endpoint with no other special network role.</t>
<t>The SEP is given a simple RESTful messaging protocol that enables the setup, renewal and cancellation of the authority transfer. The whole process is driven by the SEP, which may actually never need to listen or to keep any state.</t>
<t>This memo also introduces the 'proxies' Web Linking <xref target="RFC5988" /> relation type.</t>
<t>This new relation, which complements the default 'hosts' relation defined in <xref target="RFC6690" />, can be used by a CoAP Proxy to explicitly advertise the resources that it can serve either from cache or by forwarding the Client request upstream.</t>
<t>The 'proxies' relation works in concert with the Publish Option to enable SEP discovery even while SEP is off-line.</t>
<section title="Requirements Language and Motivation">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in <xref target="RFC2119"/>.</t>
<t>The terms Client, Proxy, Server, and Endpoint are to be interpreted as described in <xref target="I-D.ietf-core-coap" />.</t>
<t>This memo reuses the terminology introduced in <xref target="I-D.rahman-core-sleepy-problem-statement"/>, and aims at meeting the objectives stated in its Section 4 via an entirely in-protocol solution.</t>
</section>
</section>
<section title="Publish Option">
<t>The Publish Option enables a SEP to temporarily (i.e. for a specified "lease" time) delegate the authority of one of its hosted resources to another Endpoint.</t>
<!-- <t>This allows a SEP to use the delegated Endpoint as the rendezvous point for one-way SEP to SEP signaling.</t> -->
<figure align="center">
<artwork align="left"><![CDATA[
+------+---+---+---+---+---------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+---------+--------+--------+---------+
| 2n+1 | x | x | x | - | Publish | uint | 1 | (none) |
+------+---+---+---+---+---------+--------+--------+---------+
]]></artwork>
</figure>
<section title="Publishing a Resource">
<t>The SEP publishes one of its hosted resources, specified by the enclosed Proxy-URI, by making a PUT to the Proxy with a Publish Option attached. The Publish Option value specifies the CoAP methods that Clients are allowed to use on the resource (see <xref target="publish_format"/>).</t>
<t>The example in <xref target="publish_creation"/> shows a delegation where the GET and PUT methods are allowed, while POST and DELETE are explicitly prohibited, meaning that the resource can only be read and updated by Clients.</t>
<figure align="left" anchor="publish_creation">
<artwork align="left"><![CDATA[
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| r | Content-Format: text/plain
| | ETag: 0xabcd
| | Max-Age: 1200
| 2.01 |
+-------->|
| |
]]></artwork>
</figure>
<t>The Proxy, which is voluntarily entrusted by the resource owner to act as the delegated origin for the "lease" time specified by Max-Age, replies with a 2.01 if the authority transfer succeeds. An exact duplicate of the submitted representation is created, and from now on it can be accessed using the original URI provided that Clients request it through the delegated Proxy. If the Publish operation isn't successful (e.g. because the Proxy does not support Publish), then the origin transfer fails, and an appropriate response code is returned (e.g. 4.02 Bad Option).</t>
<t>An ETag MAY be supplied as a further metadatum to be included in responses involving the published representation. If no Max-Age is given, a default of 3600 seconds MUST be assumed. The Max-Age value, either implicit or explicit, determines the lifetime of the origin delegation. When Max-Age is elapsed, the Proxy MUST delete the published resource value and fall back to its usual proxying function.</t>
<t>The Publish Option is critical, and MUST NOT be present in a response. If the Proxy does not recognize it, a 4.02 (Bad Option) MUST be returned to the Client. If the Option value is not correctly formatted (see <xref target="publish_format"/>), a 4.00 (Bad Request) MUST be returned to the Client. The Publish Option is not Safe-to-Forward, and neither is a Cache-Key.</t>
<t>Since the 2.01 is emitted, and for the duration of the delegation, any Client wishing to access the resource can do so by making a Proxy-URI request to the Proxy, which shall then serve the resource off from its own storage.</t>
<t>An interesting outcome of this communication strategy is that the SEP may really never need to listen on its radio interface. However, ignoring the response status code from Proxy is not a safe practice and is not encouraged.</t>
<t>Upon publishing, the Proxy MUST save the identity of the publishing SEP, and MUST use it to correctly authorise "maintenance" operations such as renewal or cancellation of the published resource. The SEP identity MUST be kept for the whole duration of the delegation (including any associated renewal) and can be forgotten as soon as the delegation vanishes either implicitly or explicitly.</t>
</section>
<section title="Updating a Resource">
<t>In order to update the delegated resource state or to just extend the lease period, the SEP shall send basically the same request (except possibly for the representation value and the associated ETag) to the Proxy, which in turn replies with a 2.04 Changed status code in case the update operation succeeds. If the operation fails, e.g. because the request comes from an Endpoint different from the publishing SEP, a suitable status code is returned (e.g. 4.01 Unauthorized).</t>
<figure align="left" anchor="publish_update">
<artwork align="left"><![CDATA[
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| r | Content-Format: text/plain
| | ETag: 0xdcba
| | Max-Age: 1200
| 2.04 |
+-------->|
| |
]]></artwork>
</figure>
</section>
<section title="Unpublishing a Resource" anchor="publish_removal">
<t>The delegation of a given resource can be explicitly revoked by the SEP at any time before the lease time expires, by issuing a DELETE request to the Proxy hosting the resource duplicate with a Publish Option with value 0x00.</t>
<figure align="left">
<artwork align="left"><![CDATA[
P S
| DELETE | Proxy-URI: coap://sleepy.example.org/res
|<---------+ Publish: 0x00
| |
| 2.02 |
+--------->|
| |
]]></artwork>
</figure>
<t>On successful deletion of the delegation, a 2.02 Deleted response code is returned by the Proxy. On error a suitable status code is returned.</t>
</section>
<section title="Value Format" anchor="publish_format">
<t>The Publish Option consists of a single byte having the following layout:</t>
<figure align="left">
<artwork align="left"><![CDATA[
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|C R U D 0 0 0 0|
+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>Each of the higher 4 bits is a flag field indicating whether the associated CoAP method (respectively: POST, GET, PUT and DELETE) is allowed on the published resource. The lower 4 bits are reserved and MUST be set to 0.</t>
<!--
<t>If the (optional) value is missing, then:
<list>
<t>on PUT, a default of 0x40 SHALL be assumed, indicating a read-only resource;</t>
<t>on DELETE, a default value of 0x00 is assumed.</t>
</list>
</t>
-->
<t>The 0x00 value is used to explicitly revoke the delegation (see <xref target="publish_removal"/>.) and MUST NOT be used for any other purpose of the Option.</t>
<t>If the delegated Proxy receives a request for the published resource with a method that is not compatible with the mask supplied by the SEP, it MUST respond with a 4.05 (Method Not Allowed) response code.</t>
</section>
</section>
<section title="Discovery">
<section title="The 'proxies' Relation Type">
<t>The new 'proxies' Web Linking <xref target="RFC5988"/> relation type is meant to signify that the target resource carried by the link, which MUST be identified by an absolute URI, is reachable through a Proxy-URI request made to the anchored Origin (i.e. the Proxy).</t>
<t>(Note that we need to specify the Proxy through an explicit anchor, thus increasing the verbosity of the link value, because of the way the context URI override rules are defined in Section 2.1 of <xref target="RFC6690"/>. In fact, absent an explicit anchor, rule (b) would set the context to the SEP origin, which is definitely not what we want.)</t>
<section title="Examples">
<t>
<list style="symbols">
<t>C discovers resources that P "proxies":</t>
</list>
</t>
<figure align="left">
<artwork align="left"><![CDATA[
P C
| GET | Uri-Path: .well-known
|<--------+ Uri-Path: core
| | Uri-Query: rel="proxies"
| 2.05 |
+-------->| <coap://sleepy.example.org/res>;
| | anchor="coap://proxy.example.org/";
| | rel="proxies",
| | <...
]]></artwork>
</figure>
<t>
<list style="symbols">
<t>C GET's a "proxied" resource from P:</t>
</list>
</t>
<figure align="left">
<artwork align="left"><![CDATA[
P C
| GET |
|<--------+ Proxy-URI: coap://sleepy.example.org/res
| |
| 2.05 |
+-------->| "res" data...
| |
]]></artwork>
</figure>
<t>The 'proxies' relation is orthogonal to the Publish Option, so it's up to P to decide whether to serve coap://sleepy.example.org/res from its store/cache, or to forward the request to the origin at coap://sleepy.example.org.</t>
</section>
</section>
<section title="Adjusting Link-Format Attributes">
<section title="Implicitly">
<t>The resource metadata are implicitly extracted from the published representation. Basically, the Proxy works out the ct and sz attributes by inspecting Content-Format and the request payload size.</t>
</section>
<section title="Explicitly">
<t>The resource metadata are explicitly published to the same Proxy-URI used for the sibling resource, either in a separate request/response cycle (see <xref target="non_atomic_publish"/>),</t>
<figure align="left" anchor="non_atomic_publish">
<artwork align="left"><![CDATA[
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| <meta> | Content-Format: application/link-format
| |
| 2.01 |
+-------->|
| |
]]></artwork>
</figure>
<t>or atomically, within the same Publish operation, e.g. by using the Multipart Content-Format to aggregate one (or even more than one) representation(s) together with the application/link-format entry (see <xref target="atomic_publish"/>).</t>
<figure align="left" anchor="atomic_publish">
<artwork align="left"><![CDATA[
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| [mp] | Content-Format: application/multipart+publish
| | ETag: 0xabcd
| | Max-Age: 1200
| 2.01 |
+-------->|
| |
]]></artwork>
</figure>
<t>Note that the former (<xref target="non_atomic_publish"/>) is non-atomic, and limited to only one representation of the resource; the latter (<xref target="atomic_publish"/>) is atomic and supports multiple Content-Format's for the published resource.</t>
</section>
</section>
<!--
<section title="Publishing the /.well-known/core Resource" anchor="wkc">
<t>The Link-Format specification <xref target="RFC6690" /> has no explicit text about discovery of "well-known" devices through a Proxy, or about the cacheability rules for such resource. Even if it seems reasonable to assume that the /.well-known/core URI is both query-able and cacheable through a Proxy, on the contrary the situation is not very much so.</t>
<t>In fact, since the "well-known" interface relies on the resource origin being implicitly defined by the source address of the UDP packet carrying the response, quering the "well-known" interface (either unicast or multicast) through a Proxy-URI has little hope to be fully functional. The (ab)use of a an implicit L3 locator as the identifier of the resource authority makes "well-known" discovery generally incompatible with Proxy mediated communication, unless each target URI in a link is given as a URI and not as a relative-ref (section 4.1 of <xref target="RFC3986" />).</t>
<t>Consequently, in this proposal we assume that the /.well-known/core of a SEP can be published if and only if the target URI in the each link is not a relative-ref.</t>
<t>Its registration is the same as in <xref target="publish_creation" />, but the Proxy MAY need to treat it in a way that is slightly different from other "normal" delegated resources. In fact, while delegation is in place (i.e. the lease period is not elapsed, and neither explicit revocation has happened) the Proxy MAY be able to respond to filtered queries (section 4.1 of <xref target="RFC6690" />) regarding the published /.well-known/core.</t>
</section>
<section title="Resource Directory">
<t>Given the strong requirement on the link formatting given in <xref target="wkc" />, it could be preferable (or even necessary) to use the Resource Directory <xref target="I-D.ietf-core-resource-directory" /> as a means of delegating the discovery of the resources hosted at a SEP.</t>
<t>This can be done either by the SEP, or automatically by the delegated Proxy when a Publish request is received.</t>
<t><cref anchor="Automatic push to RD">check it out</cref></t>
</section>
-->
</section>
<!-- This PI places the pagebreak correctly (before the section title) in the text output. -->
<?rfc needLines="8" ?>
<section title="Acknowledgements">
<t>Thanks to Bruce Nordman and Matthieu Vial.</t>
</section>
<section anchor="IANA" title="IANA Considerations">
<t>The following entries are added to the CoAP Option Numbers registry:</t>
<figure align="center">
<artwork align="left"><![CDATA[
.------------------------------.
| Number | Name | Reference |
:--------:---------:-----------:
| 2n+1 | Publish | RFC XXXX |
`------------------------------'
]]></artwork>
</figure>
<t>This memo registers the new "proxies" Web Linking relation type as per <xref target="RFC5988"/>.</t>
<t>
<list>
<t>Relation Name: proxies</t>
<t>Description: the target is the absolute URI of a resource proxied by the Origin stated in the anchor.</t>
<t>Reference: this memo</t>
<t>Notes: This relation is used in CoRE where links are retrieved as a "/.well-known/core" resource representation.</t>
<t>Application Data: None</t>
</list>
</t>
</section>
<section anchor="Security" title="Security Considerations">
<t>This section identifies Threats (T) and related countermeasures (C).</t>
<?rfc subcompact="yes"?>
<t>
<list style="symbols">
<t>T: cache poisoning.</t>
<t>C: use strong auth to identify SEP.</t>
</list>
</t>
<t>
<list style="symbols">
<t>T: unauthorized update or de-registration</t>
<t>C: strong auth to identify SEP.</t>
</list>
</t>
<t>
<list style="symbols">
<t>T: Proxy resources' exhaustion.</t>
<t>C: use strong auth to identify SEP + quota limit.</t>
</list>
</t>
<t>
<list style="symbols">
<t>T: lobal state loss.</t>
<t>C: cache redundancy.</t>
</list>
</t>
<t>
<list style="symbols">
<t>T: Inject fake copies of the resource by a 3rd party.</t>
<t>C: use delegation scheme that bundles the identities of the SEP and the Proxy, together with the resource being delegated. A third party must be able to verify SEP and Proxy identities, maybe offline, and check the resource fingerprint.</t>
</list>
</t>
<?rfc subcompact="no"?>
<section title="Securing the Delegation">
<t>(Sketch) SEP signs the identity of the delegated Proxy and a fingerprint of the resource (both data and meta), and bundles it up with the resource itself, maybe in a MultiPart envelope (TBD define signed Content-Format). Client verifies the resource is indeed from the SEP by checking the signature, and it has been served by the intended origin, within the validity frame of the delegation. There seems to be an issue with hierarchical caching: the resource can't be served from a downstream Proxy which is different from the one that was originally delegated unless each Proxy in the delivery chain wraps the received message with its own credentials?</t>
<!--
each proxy should wrap the received message with its own credentials).</t>
-->
</section>
</section>
</middle>
<back>
<references title="Normative References">
&RFC2119;
&I-D.ietf-core-coap;
&RFC5988;
&RFC6690;
</references>
<references title="Informative References">
&I-D.rahman-core-sleepy-problem-statement;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:39:00 |