Internet DRAFT - draft-ishaq-core-entities
draft-ishaq-core-entities
core I. Ishaq
Internet-Draft J. Hoebeke
Intended status: Standards Track F. Van den Abeele
Expires: December 19, 2013 iMinds-IBCN/UGent
June 17, 2013
CoAP Entities
draft-ishaq-core-entities-00
Abstract
This document describes a format to create entities that can be used
for group communication using CoAP unicast messages.
Note
Discussion and suggestions for improvement are requested, and should
be sent to core@ietf.org.
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 December 19, 2013.
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
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
Ishaq, et al. Expires December 19, 2013 [Page 1]
Internet-Draft CoAP Entities June 2013
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. Requirements notation . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 4
4. Entity Creation . . . . . . . . . . . . . . . . . . . . . . . 5
5. Validation Process . . . . . . . . . . . . . . . . . . . . . 6
6. Entity Profile . . . . . . . . . . . . . . . . . . . . . . . 7
6.1. The resources "r" entity field . . . . . . . . . . . . . 7
7. Entity Usage . . . . . . . . . . . . . . . . . . . . . . . . 8
8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1. Entity Creation . . . . . . . . . . . . . . . . . . . . . 8
8.2. Entity Profile . . . . . . . . . . . . . . . . . . . . . 8
8.3. Entity Usage . . . . . . . . . . . . . . . . . . . . . . 10
9. Open topics . . . . . . . . . . . . . . . . . . . . . . . . . 11
9.1. Open since v00 . . . . . . . . . . . . . . . . . . . . . 11
10. Security Considerations . . . . . . . . . . . . . . . . . . . 11
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
12.1. Normative References . . . . . . . . . . . . . . . . . . 12
12.2. Informative reference . . . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
1. Requirements notation
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 above key words are used to establish a set of guidelines for
CoAP entities. An implementation of CoAP entities MAY implement
these guidelines; an implementation claiming compliance to this
document MUST implement the set of guidelines.
This document assumes readers are familiar with the terms and
concepts that are used in [I-D.ietf-core-coap] and
[I-D.greevenbosch-core-profile-description]. In addition, this
document defines the following terminology:
Entity
A group of resources on CoAP servers that can be created, used or
manipulated through a single CoAP request.
Entity Manager (EM)
Ishaq, et al. Expires December 19, 2013 [Page 2]
Internet-Draft CoAP Entities June 2013
The component that manages the entities. This component, which
can reside e.g. on the Border Gateway of the LLN, is responsible
for maintaining entities. Clients on the Internet can interact
with an EM to create new entities and/or customize how these
entities should behave.
2. Introduction
The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a
RESTful protocol for constrained nodes. The networks that connect
these nodes together are often referred to as low power and lossy
networks (LLNs).
Typically, each of the constrained servers has at least one CoAP
resource that may be queried by clients to obtain information about
the nodes themselves (e.g. battery level), about the environment that
they monitor (e.g. temperature of the room), or to trigger the nodes
to perform real-world actions (switch the light on).
Depending on the application, information from individual nodes might
not be sufficient, reliable, or useful. An application may need to
aggregate and/or compare data from several nodes in order to obtain
accurate results. In the same way, a single user request might need
to trigger a series of actions on multiple actuators to perform a
single user request.
Although multicast may be used to transmit the same request to
several nodes [I-D.ietf-core-groupcomm], multicast communication in
LLNs has some disadvantages. For instance, it is difficult to avoid
duplication of messages, and duplication is undesirable in an LLN
where bandwidth is limited for these constrained nodes. Furthermore,
basic multicast is not reliable in an LLN, which is problematic for
requests that require guaranteed delivery. Security of multicast is
another issue. Currently CoAP relies on Datagram Transport Layer
Security (DTLS) [RFC6347] for secure unicast communication. At the
moment, DTLS requires non-standard extensions like
[I-D.keoh-tls-multicast-security] to secure multicast. As
demonstrated by the formation of the upcoming DTLS-IoT WG (pending a
BoF at IETF 87) that aims to introduce multicast record layer support
for DTLS, work is very much ongoing in this field but no standard
solution is available as of today. Also, the creation of multicast
groups, defining which nodes should be addressed when using a
particular multicast address, is hard to realize inside LLNs. For
instance, the approach in [I-D.ietf-core-groupcomm] suggests that
every CoAP endpoint should implement the "core.gp" interface.
Additionally, the use of multicast increases the footprint of the
code that needs to fit on the constrained nodes, and it is to be
expected that this functionality will not be available in many LLNs.
Ishaq, et al. Expires December 19, 2013 [Page 3]
Internet-Draft CoAP Entities June 2013
Consequently, in some cases the use of multicast might be not
feasible or provide a suboptimal solution.
As an alternative, unicast-based solutions should be considered.
Simple unicast solutions are defined in the CoRE Interfaces draft
[I-D.ietf-core-interfaces]. Among other interface types, this draft
defines the Batch interface type and its extension, the Linked Batch
interface type. Batch interfaces are used to manipulate a collection
of sub-resources at the same time. Contrary to the basic Batch,
which is a collection statically defined by the web server, a Linked
Batch is dynamically controlled by a web client. A Linked Batch
resource has no sub-resources. Instead the resources forming the
batch are referenced using Web Linking [RFC5988] and the CoRE Link
Format [RFC6690]. The draft does not foresee any way to manipulate
resources that are located on multiple smart objects with a single
client request.
The current CoRE drafts do not foresee any unicast-based way to
manipulate resources that are located on multiple nodes with a single
client request. To overcome this shortcoming and be able to perform
such composite requests, intelligence is typically added to the
client application to make it communicate with the nodes
individually. This leads to more complex user applications, and the
added intelligence and programming cannot be shared with other
applications easily. Furthermore, complex use applications may be
unmanageable. Any modifications to those complex user applications
may require significant testing time, thus limiting the flexibility
of the user applications. Additionally a large overhead of
communication between the client machine and the nodes is generated,
especially when many nodes are involved in these actions. When the
communication between the client and the nodes is done across the
Internet, delays are unpredictable and a sequence of actuator
commands might arrive out of order and possibly have unwanted
results. Furthermore, if the communication occurs over costly links,
communication between the client and the nodes might get
unnecessarily expensive.
The discussed approaches are able to realize communication with a
group of resources, but each exhibit some limitations. Therefore, in
this Internet Draft we propose an alternative unicast-based approach
for communication with a group of resources across multiple nodes.
3. System Overview
We call the component that manages the entities, the Entity Manager
(EM). This component, which can reside e.g. on the Border Gateway of
the LLN, is responsible for maintaining entities that are created
from groups of CoAP servers (i.e. sensors and actuators) and/or
Ishaq, et al. Expires December 19, 2013 [Page 4]
Internet-Draft CoAP Entities June 2013
resources inside the LLN. Clients on the Internet can interact with
an EM to create new entities and/or customize how these entities
should behave. Optionally the client can elect to contact a resource
directory [I-D.ietf-core-resource-directory] in order to discover
which resources are available in the network.
The EM functionality does not have to be put on a dedicated device.
Theoretically any CoAP server can be extended to become an EM. The
choice of the most appropriate location to put the EM functionality
depends on the size and topology of the network. For example, it can
reside on a smart object in the constrained network with enough
resources, in the Cloud, on the client device itself, or on a gateway
at the edge of the LLN. The latter case has the added benefit that
security can be centrally managed besides offloading the processing
from constrained devices.
Regardless of the location of the EM, it will serve as a proxy
between the client and the constrained devices. Client requests will
be sent to the EM, which will analyze and verify the requests and
then issue the appropriate requests to the constrained devices using
CoAP. Once the EM receives responses from the constrained devices,
it will combine them according to the client needs and will send back
an aggregated response to the client.
When a client tries to create a new entity consisting of a group of
resources inside LLNs, the EM performs a sanity check on the request
in order to make sure that the resulting entity would make sense.
For example it verifies that the resources inside the entity are
valid, if they support a certain content format or if their data can
be aggregated. Customization of the entity behavior is accomplished
by creating profiles for the entities. A profile of an entity can
specify for example whether to return the values of all resources in
the entity, only the computed average of all values or a subset of
all values.
4. Entity Creation
To facilitate the creation and manipulation of entities, an Entity
Manager MUST implement the RESTful interface defined in this draft.
A CoAP resource implementing this interface can be identified by
using the resource type (rt) "core.em". We call this interface the
Entity Management Interface and the corresponding resource the Entity
Management Resource (available at e.g. "/e"). This interface
supports only the CoAP POST request method. As payload of the
request, it expects a collection of resources in CoRE link format
[RFC6690], which together should form the entity. In the response,
the Location-Path CoAP option MUST be used to specify the name of the
newly created resource. The payload of the response is in plain text
Ishaq, et al. Expires December 19, 2013 [Page 5]
Internet-Draft CoAP Entities June 2013
and describes the results of the validation tests performed by the EM
on the collection of resources.
When a client wants to create an entity consisting of several sub-
resources, it MUST compose a CoAP POST request and send it to the
Entity Management resource on the EM. The EM creates the entity,
assigns it a unique URI, and stores the entity in the entity database
for future usage. Then the EM starts the entity validation process
(explained in the next subsection). The EM MUST inform the client
about the URI to use in order to access or further customize the
newly created entity and about the results of the validation of the
entity. If the entity did not pass the validation process the client
SHOULD fix any errors and resubmit the entity for validation again
before the client can use the entity.
5. Validation Process
Whenever a client requests to create a new entity or to modify an
existing entity, the EM SHOULD perform a validation process. The
purpose of this validation process is twofold: 1) Make sure that the
sub-resources in the entity exist and can be used. 2) Derive the
properties of the entity based on the properties of the sub-resources
it contains. If the entity passes validation the EM marks the entity
as a valid entity and stores the entity along with its calculated
properties in the entity database for future usage. If the entity
fails validation it is still created, but marked as invalid. The
entity validation is based on EM knowledge of the individual sub-
resources through .well-known/core and their profiles and possibly
based on additional functionality implemented by the EM (e.g. vendor-
specific functionality).
If the Entity Manager does not know any of the subresources in an
entity (e.g. based on knowledge in a resource directory) or does not
know the sub-resource capabilities, it tries to obtain this
information according to a fallback mechanism as follows.
o The EM tries to contact the object containing the resource in
order to obtain the resource profile, since this would provide the
most complete information about the resource.
o If the resource profile does not exist, the EM tries to obtain any
information about this resource from .well-known/core of the
respective object.
o If this fails as well, the EM tries to query the resource directly
to discover, at a minimum, if the resource exists or not.
Ishaq, et al. Expires December 19, 2013 [Page 6]
Internet-Draft CoAP Entities June 2013
The validation process that the entity manger performs on entities
MUST ensure the following:
o The individual sub-resources contained in the entity are valid
(e.g. the resources exist on the respective nodes).
o The requested operations can be performed on the individual sub-
resources (e.g. which CoAP options are supported, which RESTful
methods are allowed?).
o The individual sub-resources do not conflict. A sample conflict
can occur when an entity creation request contains two sub-
resources on the same actuator asking it to do contradictory
actions, e.g. open and close at the same time.
o The responses sent by the individual sub-resources can be combined
together by using a common denominator or by executing custom
algorithms that reside at the EM.
6. Entity Profile
Once the EM knows all information about the subresources that should
become part of the entity and once all necessary checks have passed,
the EM SHOULD create a profile for the entity based on this
information and its custom algorithms. This profile contains
information related to the resource itself, as described in
[I-D.greevenbosch-core-profile-description]. In addition, the
profile is extended with an entity specific part, providing more
information about the entity itself. The entity specific part is a
JSON object with the name "entity". The value of this object is an
array of entity specific fields.
6.1. The resources "r" entity field
The resources "r" entity field contains a list of the resources in
the entity. It has the format depicted in Figure 1, where r1, r2,
... are strings containing the absolute URIs of the individual
resources.
"r":[r1,r2,...]
Figure 1: resources "r" entity field syntax
When including the "r" entity field in the entity profile
description, all individual resources of the CoAP entity MUST be
included.
Ishaq, et al. Expires December 19, 2013 [Page 7]
Internet-Draft CoAP Entities June 2013
If the "r" entity profile field is available, the receiving party
SHALL assume a non-listed URI is not a resource of the entity.
7. Entity Usage
Once an entity is created the response contains the URI of the
dynamically created resource name. The client CAN now interact with
the entity by issuing a single CoAP request to the resource
representing the entity. When a request for an entity arrives, the
following process flow SHOULD be executed.
o The EM breaks down the request into its components and sends the
individual requests to the respective objects using unicast CoAP
messages. It can either do that in parallel or sequentially.
o Once all needed answers are received, the EM creates a response
for the client based on the individual responses and sends it to
the client. Note that the amount of sub-resources that should
respond, the way in which a response is formed and how it should
look like can be configured by customizing the entity profile as
will be explained later on.
8. Examples
8.1. Entity Creation
In the following simple example the client requests the creation of
an entity consisting of two sub-resources: coap://sen5.example.com/
tmp and coap://sen8.example.com/tmp. The EM creates the new entity,
assigns it the URI "/1" and informs the client about the newly
created entity. From now on, any client can access the newly created
entity by accessing the "/1" resource on the EM.
Req: POST coap://em.example.com/e (application/link-format)
Body: <coap://sen5.example.com/tmp>,
<coap://sen8.example.com/tmp>
Res: 2.05 Content (text/plain)
Body: /1 created
8.2. Entity Profile
Assume that the temperature sensor at "coap://sen5.example.com/tmp"
from the previous example supports the "Uri-Host" (3), "ETag" (4),
"Observe" (6), "Uri-Port" (7), "Uri-Path" (11) and "Content-Format"
(12) CoAP options (op). This sensor further supports the
Ishaq, et al. Expires December 19, 2013 [Page 8]
Internet-Draft CoAP Entities June 2013
"application/senml+json" (55) content format (cf) and the allowed
method is GET (1). This will result in Sen5 having the following
profile [I-D.greevenbosch-core-profile-description]:
Req: GET coap://sen5.example.com/.well-known/profile?path=/tmp
Res: 2.05 Content (application/json)
Body:
{
"profile":[
{
"path":"tmp",
"op":[3,4,6,7,11,12],
"cf":[55],
"m":[1]
}
]
}
Let us further assume that the second temperature sensor "coap://
sen8.example.com/tmp" supports the same options as sen5 except for
the observe option. Only the GET method is allowed and the supported
content formats on this sensor are "text/plain" (0) and "application/
senml+json" (55). Thus Sen8 will have the following profile:
Req: GET coap://sen8.example.com/.well-known/profile?path=/tmp
Res: 2.05 Content (application/json)
Body:
{
"profile":[
{
"path":"tmp",
"op":[3,4,7,11,12],
"cf":[0,55],
"m":[1]
}
]
}
Ishaq, et al. Expires December 19, 2013 [Page 9]
Internet-Draft CoAP Entities June 2013
Based on these two profiles the EM constructs a profile for the newly
created entity. This profile contains information related to the
resource itself. In this example, this includes the options that are
supported, the supported methods (only GET) and the content format
"application/senml+json" (55). In addition, the profile is extended
with an entity specific part, providing more information about the
entity itself. The resulting profile of the entity looks as follows:
Res: 2.05 Content (application/json)
{
"profile":[
{
"path":"1",
"op":[3,4,7,11,12],
"cf":[55],
"m":[1]
}
],
"entity":[
{
"r":["coap://sen5.example.com/tmp",
"coap://sen8.example.com/tmp"]
}
]
}
8.3. Entity Usage
The following Figure shows an example of using the entity that was
created previous example. The client issues a GET request on the
entity's resource "/1". This results in the EM issuing two GET
requests to the individual sub-resources, waiting for replies from
both of them and then sending back both results in one combined
response back to the client.
Client EM Sen5 Sen8
| | | |
| GET | | |
| coap://em.example.com/1 | | |
|------------------------>| GET | |
| | coap://sen5.example.com/tmp |
| |-------------------->| |
| | | |
| | GET coap://sen8.example.com/tmp |
| |---------------------------------------->|
| | | |
| |<----------------------------------------|
Ishaq, et al. Expires December 19, 2013 [Page 10]
Internet-Draft CoAP Entities June 2013
| | 2.05 Content (text/plain) Body: 23.5 |
| | | |
| |<--------------------| |
| | 2.05 Content (text/plain) Body: 26.6 |
| | | |
|<------------------------| | |
| 2.05 Content (application/senml+json) | |
| Payload: {"e":[ | | |
| {"n": "Sen5/tmp", "v": "26.6", u="degC"}, | |
| {"n": "Sen8/tmp", "v": "23.5", u="degC"}]} | |
| | | |
9. Open topics
9.1. Open since v00
o Use key words consistently.
10. Security Considerations
For general CoAP security considerations see [I-D.ietf-core-coap].
A client might request the creation of a large number of entities or
entities that contain a large number of resources. This might lead
to buffer overflow on the EM.
In an unprotected environment, an attacker can change the profile
description of Entities. For example, the list of supported options
may be changed. This could cause the client to make a wrong decision
on which mechanisms to use. As the Entity Manager amplifies a single
requests into multiple requests per user, special care should be
taken to avoid congestion and to avoid abuse of this mechanism by a
malicious user that might want to flood the LLN. However, such
threats are normal in environments that lack authentication.
11. IANA Considerations
o A registry for entity profile fields as well as possible values
needs to be set up.
12. References
Ishaq, et al. Expires December 19, 2013 [Page 11]
Internet-Draft CoAP Entities June 2013
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-17
(work in progress), May 2013.
[I-D.greevenbosch-core-profile-description]
Greevenbosch, B., Hoebeke, J., and I. Ishaq, "CoAP Profile
Description Format", draft-greevenbosch-core-profile-
description-01 (work in progress), October 2012.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785, April
2010.
12.2. Informative reference
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, January 2012.
[I-D.ietf-core-groupcomm]
Rahman, A. and E. Dijk, "Group Communication for CoAP",
draft-ietf-core-groupcomm-09 (work in progress), May 2013.
[I-D.ietf-core-interfaces]
Shelby, Z. and M. Vial, "CoRE Interfaces", draft-ietf-
core-interfaces-00 (work in progress), June 2013.
[I-D.ietf-core-resource-directory]
Shelby, Z., Krco, S., and C. Bormann, "CoRE Resource
Directory", draft-ietf-core-resource-directory-00 (work in
progress), June 2013.
[I-D.keoh-tls-multicast-security]
Keoh, S., Kumar, S., and E. Dijk, "DTLS-based Multicast
Security for Low-Power and Lossy Networks (LLNs)", draft-
keoh-tls-multicast-security-00 (work in progress), October
2012.
Ishaq, et al. Expires December 19, 2013 [Page 12]
Internet-Draft CoAP Entities June 2013
Authors' Addresses
Isam Ishaq
iMinds-IBCN/UGent
Department of Information Technology
Internet Based Communication Networks and Services (IBCN)
Ghent University - iMinds
Gaston Crommenlaan 8 bus 201
Ghent B-9050
Belgium
Phone: +32-9-3314946
Email: isam.ishaq@intec.ugent.be
Jeroen Hoebeke
iMinds-IBCN/UGent
Department of Information Technology
Internet Based Communication Networks and Services (IBCN)
Ghent University - iMinds
Gaston Crommenlaan 8 bus 201
Ghent B-9050
Belgium
Phone: +32-9-3314954
Email: jeroen.hoebeke@intec.ugent.be
Floris Van den Abeele
iMinds-IBCN/UGent
Department of Information Technology
Internet Based Communication Networks and Services (IBCN)
Ghent University - iMinds
Gaston Crommenlaan 8 bus 201
Ghent B-9050
Belgium
Phone: +32-9-3314946
Email: floris.vandenabeele@intec.ugent.be
Ishaq, et al. Expires December 19, 2013 [Page 13]
