< draft-ietf-core-observe-13.txt   draft-ietf-core-observe-14.txt >
CoRE Working Group K. Hartke CoRE Working Group K. Hartke
Internet-Draft Universitaet Bremen TZI Internet-Draft Universitaet Bremen TZI
Intended status: Standards Track April 10, 2014 Intended status: Standards Track June 30, 2014
Expires: October 12, 2014 Expires: January 1, 2015
Observing Resources in CoAP Observing Resources in CoAP
draft-ietf-core-observe-13 draft-ietf-core-observe-14
Abstract Abstract
CoAP is a RESTful application protocol for constrained nodes and CoAP is a RESTful application protocol for constrained nodes and
networks. The state of a resource on a CoAP server can change over networks. The state of a resource on a CoAP server can change over
time. This document specifies a simple protocol extension for CoAP time. This document specifies a simple protocol extension for CoAP
that enables CoAP clients to "observe" resources, i.e., to retrieve that enables CoAP clients to "observe" resources, i.e., to retrieve
a representation of a resource and keep this representation updated a representation of a resource and keep this representation updated
by the server over a period of time. The protocol follows a best- by the server over a period of time. The protocol follows a best-
effort approach for sending new representations to clients and effort approach for sending new representations to clients and
skipping to change at page 1, line 38 skipping to change at page 1, line 38
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 http://datatracker.ietf.org/drafts/current/. Drafts is at http://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 October 12, 2014. This Internet-Draft will expire on January 1, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 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 Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 9 skipping to change at page 3, line 9
10.2. Informative References . . . . . . . . . . . . . . . . . . 20 10.2. Informative References . . . . . . . . . . . . . . . . . . 20
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21
A.1. Client/Server Examples . . . . . . . . . . . . . . . . . . 21 A.1. Client/Server Examples . . . . . . . . . . . . . . . . . . 21
A.2. Proxy Examples . . . . . . . . . . . . . . . . . . . . . . 25 A.2. Proxy Examples . . . . . . . . . . . . . . . . . . . . . . 25
Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 27 Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction 1. Introduction
1.1. Background 1.1. Background
CoAP [RFCXXXX] is an application protocol for constrained nodes and CoAP [RFC7252] is an application protocol for constrained nodes and
networks. It is intended to provide RESTful services [REST] not networks. It is intended to provide RESTful services [REST] not
unlike HTTP [RFC2616] while reducing the complexity of implementation unlike HTTP [RFC7230] while reducing the complexity of implementation
as well as the size of packets exchanged in order to make these as well as the size of packets exchanged in order to make these
services useful in a highly constrained network of themselves highly services useful in a highly constrained network of themselves highly
constrained nodes. constrained nodes [RFC7228].
The model of REST is that of a client exchanging representations of The model of REST is that of a client exchanging representations of
resources with a server, where a representation captures the current resources with a server, where a representation captures the current
or intended state of a resource and the server is the authority for or intended state of a resource and the server is the authority for
representations of the resources in its namespace. A client representations of the resources in its namespace. A client
interested in the state of a resource initiates a request to the interested in the state of a resource initiates a request to the
server; the server then returns a response with a representation of server; the server then returns a response with a representation of
the resource that is current at the time of the request. the resource that is current at the time of the request.
This model does not work well when a client is interested in having a This model does not work well when a client is interested in having a
skipping to change at page 8, line 14 skipping to change at page 8, line 14
In a response, the Observe Option identifies the message as a In a response, the Observe Option identifies the message as a
notification. This implies that the server has added an entry with notification. This implies that the server has added an entry with
the client endpoint and request token to the list of observers and the client endpoint and request token to the list of observers and
that it will notify the client of changes to the resource state. The that it will notify the client of changes to the resource state. The
option value is a 24-bit sequence number for reordering detection option value is a 24-bit sequence number for reordering detection
(see Section 3.4 and Section 4.4). (see Section 3.4 and Section 4.4).
The value of the Observe Option is encoded as an unsigned integer in The value of the Observe Option is encoded as an unsigned integer in
network byte order using a variable number of bytes ('uint' option network byte order using a variable number of bytes ('uint' option
format); see Section 3.2 of RFC XXXX [RFCXXXX]. format); see Section 3.2 of RFC 7252 [RFC7252].
The Observe Option is not part of the cache-key: a cacheable response The Observe Option is not part of the cache-key: a cacheable response
obtained with an Observe Option in the request can be used to satisfy obtained with an Observe Option in the request can be used to satisfy
a request without an Observe Option, and vice versa. When a stored a request without an Observe Option, and vice versa. When a stored
response with an Observe Option is used to satisfy a normal GET response with an Observe Option is used to satisfy a normal GET
request, the option MUST be removed before the response is returned. request, the option MUST be removed before the response is returned.
3. Client-side Requirements 3. Client-side Requirements
3.1. Request 3.1. Request
skipping to change at page 9, line 18 skipping to change at page 9, line 18
normal GET request at that time to return a non-2.xx response (for normal GET request at that time to return a non-2.xx response (for
example, when the resource is deleted), the server sends a example, when the resource is deleted), the server sends a
notification with an appropriate response code (such as 4.04 Not notification with an appropriate response code (such as 4.04 Not
Found) and removes all clients from the list of observers of the Found) and removes all clients from the list of observers of the
resource. Non-2.xx responses do not include an Observe Option. resource. Non-2.xx responses do not include an Observe Option.
3.3. Caching 3.3. Caching
As notifications are just additional responses to a GET request, As notifications are just additional responses to a GET request,
notifications partake in caching as defined in Section 5.6 of RFC notifications partake in caching as defined in Section 5.6 of RFC
XXXX [RFCXXXX]. Both the freshness model and the validation model 7252 [RFC7252]. Both the freshness model and the validation model
are supported. are supported.
3.3.1. Freshness 3.3.1. Freshness
A client MAY store a notification like a response in its cache and A client MAY store a notification like a response in its cache and
use a stored notification that is fresh without contacting the use a stored notification that is fresh without contacting the
server. Like a response, a notification is considered fresh while server. Like a response, a notification is considered fresh while
its age is not greater than the value indicated by the Max-Age Option its age is not greater than the value indicated by the Max-Age Option
(and no newer notification/response has been received). (and no newer notification/response has been received).
skipping to change at page 11, line 6 skipping to change at page 11, line 6
Design Note: The first two conditions verify that V1 is less than V2 Design Note: The first two conditions verify that V1 is less than V2
in 24-bit serial number arithmetic [RFC1982]. The third condition in 24-bit serial number arithmetic [RFC1982]. The third condition
ensures that the time elapsed between the two incoming messages is ensures that the time elapsed between the two incoming messages is
not so large that the difference between V1 and V2 has become not so large that the difference between V1 and V2 has become
larger than the largest integer that it is meaningful to add to a larger than the largest integer that it is meaningful to add to a
24-bit serial number; in other words, after 128 seconds have 24-bit serial number; in other words, after 128 seconds have
elapsed without any notification, a client does not need to check elapsed without any notification, a client does not need to check
the sequence numbers to assume an incoming notification is new. the sequence numbers to assume an incoming notification is new.
The duration of 128 seconds was chosen as a nice round number The duration of 128 seconds was chosen as a nice round number
greater than MAX_LATENCY (Section 4.8.2 of RFC XXXX [RFCXXXX]). greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]).
3.5. Transmission 3.5. Transmission
A notification can be confirmable or non-confirmable, i.e., it can be A notification can be confirmable or non-confirmable, i.e., it can be
sent in a confirmable or a non-confirmable message. The message type sent in a confirmable or a non-confirmable message. The message type
used for a notification is independent from the type used for the used for a notification is independent from the type used for the
request or for any previous notification. request or for any previous notification.
If a client does not recognize the token in a confirmable If a client does not recognize the token in a confirmable
notification, it MUST NOT acknowledge the message and SHOULD reject notification, it MUST NOT acknowledge the message and SHOULD reject
skipping to change at page 13, line 20 skipping to change at page 13, line 20
the resource. the resource.
A 2.xx notification MUST include an Observe Option with a sequence A 2.xx notification MUST include an Observe Option with a sequence
number as specified in Section 4.4 below; a non-2.xx notification number as specified in Section 4.4 below; a non-2.xx notification
MUST NOT include an Observe Option. MUST NOT include an Observe Option.
4.3. Caching 4.3. Caching
As notifications are just additional responses sent by the server in As notifications are just additional responses sent by the server in
reply to a GET request, they are subject to caching as defined in reply to a GET request, they are subject to caching as defined in
Section 5.6 of RFC XXXX [RFCXXXX]. Section 5.6 of RFC 7252 [RFC7252].
4.3.1. Freshness 4.3.1. Freshness
After returning the initial response, the server MUST try to keep the After returning the initial response, the server MUST try to keep the
returned representation current, i.e., it MUST keep the resource returned representation current, i.e., it MUST keep the resource
state observed by the client as closely in sync with the actual state observed by the client as closely in sync with the actual
resource state as possible. resource state as possible.
Since becoming out of sync at times cannot be avoided, the server Since becoming out of sync at times cannot be avoided, the server
MUST indicate for each representation an age up to which it is MUST indicate for each representation an age up to which it is
skipping to change at page 16, line 8 skipping to change at page 16, line 8
A server that transmits notifications mostly in non-confirmable A server that transmits notifications mostly in non-confirmable
messages MUST send a notification in a confirmable message instead of messages MUST send a notification in a confirmable message instead of
a non-confirmable message at least every 24 hours. This prevents a a non-confirmable message at least every 24 hours. This prevents a
client that went away or is no longer interested from remaining in client that went away or is no longer interested from remaining in
the list of observers indefinitely. the list of observers indefinitely.
4.5.1. Congestion Control 4.5.1. Congestion Control
Basic congestion control for CoAP is provided by the exponential Basic congestion control for CoAP is provided by the exponential
back-off mechanism in Section 4.2 of RFC XXXX [RFCXXXX] and the back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the
limitations in Section 4.7 of RFC XXXX [RFCXXXX]. However, CoAP limitations in Section 4.7 of RFC 7252 [RFC7252]. However, CoAP
places the responsibility of congestion control for simple request/ places the responsibility of congestion control for simple request/
response interactions only on the clients: rate limiting request response interactions only on the clients: rate limiting request
transmission implicitly controls the transmission of the responses. transmission implicitly controls the transmission of the responses.
When a single request yields a potentially infinite number of When a single request yields a potentially infinite number of
notifications, additional responsibility needs to be placed on the notifications, additional responsibility needs to be placed on the
server. server.
In order not to cause congestion, servers MUST strictly limit the In order not to cause congestion, servers MUST strictly limit the
number of simultaneous outstanding notifications/responses that they number of simultaneous outstanding notifications/responses that they
transmit to a given client to NSTART (1 by default; see Section 4.7 transmit to a given client to NSTART (1 by default; see Section 4.7
of RFC XXXX [RFCXXXX]). An outstanding notification/response is of RFC 7252 [RFC7252]). An outstanding notification/response is
either a confirmable message for which an acknowledgement has not yet either a confirmable message for which an acknowledgement has not yet
been received and whose last retransmission attempt has not yet timed been received and whose last retransmission attempt has not yet timed
out, or a non-confirmable message for which the waiting time that out, or a non-confirmable message for which the waiting time that
results from the following rate limiting rules has not yet elapsed. results from the following rate limiting rules has not yet elapsed.
The server SHOULD NOT send more than one non-confirmable notification The server SHOULD NOT send more than one non-confirmable notification
per round-trip time (RTT) to a client on average. If the server per round-trip time (RTT) to a client on average. If the server
cannot maintain an RTT estimate for a client, it SHOULD NOT send more cannot maintain an RTT estimate for a client, it SHOULD NOT send more
than one non-confirmable notification every 3 seconds, and SHOULD use than one non-confirmable notification every 3 seconds, and SHOULD use
an even less aggressive rate when possible (see also Section 3.1.2 of an even less aggressive rate when possible (see also Section 3.1.2 of
skipping to change at page 17, line 34 skipping to change at page 17, line 34
a new notification with a representation of the current resource a new notification with a representation of the current resource
state. Should the resource have changed its state more than once state. Should the resource have changed its state more than once
in the meantime, the notifications for the intermediate states in the meantime, the notifications for the intermediate states
are silently skipped. are silently skipped.
4. The new notification is transmitted with a new Message ID and the 4. The new notification is transmitted with a new Message ID and the
following transmission parameters: If the previous following transmission parameters: If the previous
(re-)transmission attempt timed out, retain its transmission (re-)transmission attempt timed out, retain its transmission
parameters, increment the retransmission counter and double the parameters, increment the retransmission counter and double the
timeout; otherwise, initialize the transmission parameters as timeout; otherwise, initialize the transmission parameters as
usual (see Section 4.2 of RFC XXXX [RFCXXXX]). usual (see Section 4.2 of RFC 7252 [RFC7252]).
It is possible that the server later receives an acknowledgement for It is possible that the server later receives an acknowledgement for
a confirmable notification that it superseded this way. Even though a confirmable notification that it superseded this way. Even though
this does not signal consistency, it is valuable in that it signals this does not signal consistency, it is valuable in that it signals
the client's further interest in the resource. The server therefore the client's further interest in the resource. The server therefore
should avoid inadvertently removing the associated entry from the should avoid inadvertently removing the associated entry from the
list of observers. list of observers.
5. Intermediaries 5. Intermediaries
skipping to change at page 19, line 7 skipping to change at page 19, line 7
A client may need to resort to polling the resource if the Observe A client may need to resort to polling the resource if the Observe
Option is not returned in the response to the GET request. Option is not returned in the response to the GET request.
A value MUST NOT be given for the "obs" attribute; any present value A value MUST NOT be given for the "obs" attribute; any present value
MUST be ignored by parsers. The "obs" attribute MUST NOT appear more MUST be ignored by parsers. The "obs" attribute MUST NOT appear more
than once in a given link-value; occurrences after the first MUST be than once in a given link-value; occurrences after the first MUST be
ignored by parsers. ignored by parsers.
7. Security Considerations 7. Security Considerations
The security considerations in Section 11 of RFC XXXX [RFCXXXX] The security considerations in Section 11 of RFC 7252 [RFC7252]
apply. apply.
Observing resources can dramatically increase the negative effects of Observing resources can dramatically increase the negative effects of
amplification attacks. That is, not only can notifications messages amplification attacks. That is, not only can notifications messages
be much larger than the request message, but the nature of the be much larger than the request message, but the nature of the
protocol can cause a significant number of notifications to be protocol can cause a significant number of notifications to be
generated. Without client authentication, a server therefore MUST generated. Without client authentication, a server therefore MUST
strictly limit the number of notifications that it sends between strictly limit the number of notifications that it sends between
receiving acknowledgements that confirm the actual interest of the receiving acknowledgements that confirm the actual interest of the
client in the data; i.e., any notifications sent in non-confirmable client in the data; i.e., any notifications sent in non-confirmable
skipping to change at page 19, line 42 skipping to change at page 19, line 42
employed to create a loop. A simple way to break any loops is to employed to create a loop. A simple way to break any loops is to
employ caches for forwarding notifications in intermediaries. employ caches for forwarding notifications in intermediaries.
8. IANA Considerations 8. IANA Considerations
The following entry is added to the CoAP Option Numbers registry: The following entry is added to the CoAP Option Numbers registry:
+--------+---------+-----------+ +--------+---------+-----------+
| Number | Name | Reference | | Number | Name | Reference |
+--------+---------+-----------+ +--------+---------+-----------+
| 6 | Observe | [RFCYYYY] | | 6 | Observe | [RFCXXXX] |
+--------+---------+-----------+ +--------+---------+-----------+
[Note to RFC Editor: Please replace YYYY with the RFC number of this [Note to RFC Editor: Please replace XXXX with the RFC number of this
specification.] specification.]
9. Acknowledgements 9. Acknowledgements
Carsten Bormann was an original author of this draft and is Carsten Bormann was an original author of this draft and is
acknowledged for significant contribution to this document. acknowledged for significant contribution to this document.
Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo
P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank,
Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias
skipping to change at page 20, line 31 skipping to change at page 20, line 31
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines
for Application Designers", BCP 145, RFC 5405, for Application Designers", BCP 145, RFC 5405,
November 2008. November 2008.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFCXXXX] Shelby, Z., Hartke, K., and C. Bormann, "Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18 Application Protocol (CoAP)", RFC 7252, June 2014.
(work in progress), June 2013.
10.2. Informative References 10.2. Informative References
[GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides,
"Design Patterns: Elements of Reusable Object-Oriented "Design Patterns: Elements of Reusable Object-Oriented
Software", Addison-Wesley, Reading, MA, USA, Software", Addison-Wesley, Reading, MA, USA,
November 1994. November 1994.
[REST] Fielding, R., "Architectural Styles and the Design of [REST] Fielding, R., "Architectural Styles and the Design of
Network-based Software Architectures", Ph.D. Dissertation, Network-based Software Architectures", Ph.D. Dissertation,
University of California, Irvine, 2000, <http:// University of California, Irvine, 2000, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/ www.ics.uci.edu/~fielding/pubs/dissertation/
fielding_dissertation.pdf>. fielding_dissertation.pdf>.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes
to an HTTP Resource", RFC 5989, October 2010. to an HTTP Resource", RFC 5989, October 2010.
[RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins,
"Known Issues and Best Practices for the Use of Long "Known Issues and Best Practices for the Use of Long
Polling and Streaming in Bidirectional HTTP", RFC 6202, Polling and Streaming in Bidirectional HTTP", RFC 6202,
April 2011. April 2011.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012. Format", RFC 6690, August 2012.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for
Constrained-Node Networks", RFC 7228, May 2014.
[RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Message Syntax and Routing", RFC 7230,
June 2014.
Appendix A. Examples Appendix A. Examples
A.1. Client/Server Examples A.1. Client/Server Examples
Observed CLIENT SERVER Actual Observed CLIENT SERVER Actual
t State | | State t State | | State
____________ | | ____________ ____________ | | ____________
1 | | 1 | |
2 unknown | | 18.5 Cel 2 unknown | | 18.5 Cel
3 +----->| Header: GET 0x41011633 3 +----->| Header: GET 0x41011633
skipping to change at page 27, line 9 skipping to change at page 27, line 9
| | | Max-Age: 60 | | | Max-Age: 60
| | | Payload: "busy" | | | Payload: "busy"
| | | | | |
Figure 8: A client observes a resource through a proxy Figure 8: A client observes a resource through a proxy
Appendix B. Changelog Appendix B. Changelog
[Note to RFC Editor: Please remove this section before publication.] [Note to RFC Editor: Please remove this section before publication.]
Changes from ietf-13 to ietf-14:
o Updated references.
Changes from ietf-12 to ietf-13: Changes from ietf-12 to ietf-13:
o Extended the Observe Option in requests to not only add but also o Extended the Observe Option in requests to not only add but also
remove an entry in the list of observers, depending on the option remove an entry in the list of observers, depending on the option
value. value.
Note: The value of the Observe Option in a registration request Note: The value of the Observe Option in a registration request
may now be any sequence of bytes that encodes the unsigned may now be any sequence of bytes that encodes the unsigned
integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'. integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'.
 End of changes. 20 change blocks. 
25 lines changed or deleted 31 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/