Internet Engineering Task Force T. Fossati
Internet-Draft KoanLogic
Intended status: Standards Track P. Giacomin
Expires: April 24, 2014 Freelance
S. Loreto
Ericsson
October 21, 2013
Publish Option for CoAP
draft-fossati-core-publish-option-01
Abstract
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.
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).
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 24, 2014.
Copyright Notice
Copyright (c) 2013 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
Fossati, et al. Expires April 24, 2014 [Page 1]
Internet-Draft Publish Option for CoAP October 2013
Provisions Relating to IETF Documents
(http://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 Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language and Motivation . . . . . . . . . . . 3
2. Publish Option . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Publishing a Resource . . . . . . . . . . . . . . . . . . 4
2.2. Updating a Resource . . . . . . . . . . . . . . . . . . . 5
2.3. Unpublishing a Resource . . . . . . . . . . . . . . . . . 6
2.4. Value Format . . . . . . . . . . . . . . . . . . . . . . . 6
3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1. The 'proxies' Relation Type . . . . . . . . . . . . . . . 7
3.1.1. Examples . . . . . . . . . . . . . . . . . . . . . . . 7
3.2. Adjusting Link-Format Attributes . . . . . . . . . . . . . 7
3.2.1. Implicitly . . . . . . . . . . . . . . . . . . . . . . 8
3.2.2. Explicitly . . . . . . . . . . . . . . . . . . . . . . 8
4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
6. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6.1. Securing the Delegation . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . . 10
7.2. Informative References . . . . . . . . . . . . . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10
Fossati, et al. Expires April 24, 2014 [Page 2]
Internet-Draft Publish Option for CoAP October 2013
1. Introduction
This memo defines the Publish Option for the Constrained Application
Protocol [I-D.ietf-core-coap].
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.
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.
This memo also introduces the 'proxies' Web Linking [RFC5988]
relation type.
This new relation, which complements the default 'hosts' relation
defined in [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.
The 'proxies' relation works in concert with the Publish Option to
enable SEP discovery even while SEP is off-line.
1.1. Requirements Language and Motivation
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 [RFC2119].
The terms Client, Proxy, Server, and Endpoint are to be interpreted
as described in [I-D.ietf-core-coap].
This memo reuses the terminology introduced in
[I-D.rahman-core-sleepy-problem-statement], and aims at meeting the
objectives stated in its Section 4 via an entirely in-protocol
solution.
2. Publish Option
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.
Fossati, et al. Expires April 24, 2014 [Page 3]
Internet-Draft Publish Option for CoAP October 2013
+------+---+---+---+---+---------+--------+--------+---------+
| No. | C | U | N | R | Name | Format | Length | Default |
+------+---+---+---+---+---------+--------+--------+---------+
| 2n+1 | x | x | x | - | Publish | uint | 1 | (none) |
+------+---+---+---+---+---------+--------+--------+---------+
2.1. Publishing a Resource
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 Section 2.4).
The example in Figure 1 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.
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| r | Content-Format: text/plain
| | ETag: 0xabcd
| | Max-Age: 1200
| 2.01 |
+-------->|
| |
Figure 1
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).
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.
The Publish Option is critical, and MUST NOT be present in a
Fossati, et al. Expires April 24, 2014 [Page 4]
Internet-Draft Publish Option for CoAP October 2013
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 Section 2.4), 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.
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.
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.
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.
2.2. Updating a Resource
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).
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| r | Content-Format: text/plain
| | ETag: 0xdcba
| | Max-Age: 1200
| 2.04 |
+-------->|
| |
Figure 2
Fossati, et al. Expires April 24, 2014 [Page 5]
Internet-Draft Publish Option for CoAP October 2013
2.3. Unpublishing a Resource
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.
P S
| DELETE | Proxy-URI: coap://sleepy.example.org/res
|<---------+ Publish: 0x00
| |
| 2.02 |
+--------->|
| |
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.
2.4. Value Format
The Publish Option consists of a single byte having the following
layout:
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
|C R U D 0 0 0 0|
+-+-+-+-+-+-+-+-+
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.
The 0x00 value is used to explicitly revoke the delegation (see
Section 2.3.) and MUST NOT be used for any other purpose of the
Option.
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.
3. Discovery
Fossati, et al. Expires April 24, 2014 [Page 6]
Internet-Draft Publish Option for CoAP October 2013
3.1. The 'proxies' Relation Type
The new 'proxies' Web Linking [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).
(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
[RFC6690]. In fact, absent an explicit anchor, rule (b) would set
the context to the SEP origin, which is definitely not what we want.)
3.1.1. Examples
o C discovers resources that P "proxies":
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",
| | <...
o C GET's a "proxied" resource from P:
P C
| GET |
|<--------+ Proxy-URI: coap://sleepy.example.org/res
| |
| 2.05 |
+-------->| "res" data...
| |
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.
3.2. Adjusting Link-Format Attributes
Fossati, et al. Expires April 24, 2014 [Page 7]
Internet-Draft Publish Option for CoAP October 2013
3.2.1. Implicitly
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.
3.2.2. Explicitly
The resource metadata are explicitly published to the same Proxy-URI
used for the sibling resource, either in a separate request/response
cycle (see Figure 3),
P S
| PUT | Proxy-URI: coap://sleepy.example.org/res
|<--------+ Publish: 0x60
| <meta> | Content-Format: application/link-format
| |
| 2.01 |
+-------->|
| |
Figure 3
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 Figure 4).
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 |
+-------->|
| |
Figure 4
Note that the former (Figure 3) is non-atomic, and limited to only
one representation of the resource; the latter (Figure 4) is atomic
and supports multiple Content-Format's for the published resource.
Fossati, et al. Expires April 24, 2014 [Page 8]
Internet-Draft Publish Option for CoAP October 2013
4. Acknowledgements
Thanks to Bruce Nordman and Matthieu Vial.
5. IANA Considerations
The following entries are added to the CoAP Option Numbers registry:
.------------------------------.
| Number | Name | Reference |
:--------:---------:-----------:
| 2n+1 | Publish | RFC XXXX |
`------------------------------'
This memo registers the new "proxies" Web Linking relation type as
per [RFC5988].
Relation Name: proxies
Description: the target is the absolute URI of a resource proxied
by the Origin stated in the anchor.
Reference: this memo
Notes: This relation is used in CoRE where links are retrieved as
a "/.well-known/core" resource representation.
Application Data: None
6. Security Considerations
This section identifies Threats (T) and related countermeasures (C).
o T: cache poisoning.
o C: use strong auth to identify SEP.
o T: unauthorized update or de-registration
o C: strong auth to identify SEP.
o T: Proxy resources' exhaustion.
o C: use strong auth to identify SEP + quota limit.
o T: lobal state loss.
o C: cache redundancy.
Fossati, et al. Expires April 24, 2014 [Page 9]
Internet-Draft Publish Option for CoAP October 2013
o T: Inject fake copies of the resource by a 3rd party.
o 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.
6.1. Securing the Delegation
(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?
7. References
7.1. Normative References
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
7.2. Informative References
[I-D.rahman-core-sleepy-problem-statement]
Rahman, A., Fossati, T., Loreto, S., and M. Vial, "Sleepy
Devices in CoAP - Problem Statement",
draft-rahman-core-sleepy-problem-statement-01 (work in
progress), October 2012.
Fossati, et al. Expires April 24, 2014 [Page 10]
Internet-Draft Publish Option for CoAP October 2013
Authors' Addresses
Thomas Fossati
KoanLogic
Email: tho@koanlogic.com
Pierpaolo Giacomin
Freelance
Email: yrz@anche.no
Salvatore Loreto
Ericsson
Hirsalantie 11
Jorvas 02420
Finland
Email: salvatore.loreto@ericsson.com
Fossati, et al. Expires April 24, 2014 [Page 11]