core B. Greevenbosch
Internet-Draft Huawei Technologies
Intended status: Standards Track J. Hoebeke
Expires: April 25, 2013 I. Ishaq
iMinds-IBCN/UGent
October 22, 2012
CoAP Profile Description Format
draft-greevenbosch-core-profile-description-01
Abstract
This document provides a profile description format, that can be used
to express capabilities of a CoAP server.
Greevenbosch, et al. Expires April 25, 2013 [Page 1]
Internet-Draft CoAP Profile Description Format October 2012
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 April 25, 2013.
Copyright Notice
Copyright (c) 2012 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
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.
Greevenbosch, et al. Expires April 25, 2013 [Page 2]
Internet-Draft CoAP Profile Description Format October 2012
Table of Contents
1. Requirements notation . . . . . . . . . . . . . . . . . . . . 4
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Obtaining the profile information . . . . . . . . . . . . . . 6
4. The Profile Format . . . . . . . . . . . . . . . . . . . . . . 7
4.1. The path "path" profile field . . . . . . . . . . . . . . 7
4.2. The options "op" profile field . . . . . . . . . . . . . . 7
4.3. The Content-Formats "cf" profile field . . . . . . . . . . 7
4.4. The Block-Sizes "b1s" and "b2s" profile fields . . . . . . 8
5. Usage of URI Queries . . . . . . . . . . . . . . . . . . . . . 9
6. Forward compatibility . . . . . . . . . . . . . . . . . . . . 10
7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
8. Open topics . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Open since v00 . . . . . . . . . . . . . . . . . . . . . . 13
8.2. Open since v01 . . . . . . . . . . . . . . . . . . . . . . 13
9. Change log . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9.1. Changes in v01 . . . . . . . . . . . . . . . . . . . . . . 14
10. Security Considerations . . . . . . . . . . . . . . . . . . . 15
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
13. Normative References . . . . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19
Greevenbosch, et al. Expires April 25, 2013 [Page 3]
Internet-Draft CoAP Profile Description Format October 2012
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].
Greevenbosch, et al. Expires April 25, 2013 [Page 4]
Internet-Draft CoAP Profile Description Format October 2012
2. Introduction
The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a
RESTful protocol for constrained nodes and networks.
Often, a client first learns about a resource through the link format
[I-D.ietf-core-link-format]. The link format only provides basic
information, for example the resource URL. However, it would be good
if the client could get more extensive information on the resources
when required. This document defines a profile description format,
which can be used to signal several parameters about resources and
their servers.
One of the main features of the CoAP protocol is the ability to
include CoAP options. These options can be either elective or
critical. A message with an unsupported critical option will be
rejected, whereas unsupported elective options will be ignored.
Even though it is well defined how the server must respond to
unsupported options, it is useful for the client to know which
options are supported in advance. In this way, it can determine
which options are viable to use in a transaction, and which features
cannot be exploited. This specification allows signalling of the
supported options by the resource.
Another important feature of a CoAP server is which content formats
it supports. CoAP provides a mechanism for the client to indicate to
the server which content format the client prefers. The use of
profiles allows signalling what content formats are supported by the
server, so that the client can decide which content type it prefers.
It is anticipated that more profile descriptions will become
available in the future.
Greevenbosch, et al. Expires April 25, 2013 [Page 5]
Internet-Draft CoAP Profile Description Format October 2012
3. Obtaining the profile information
Similar to the link format from [RFC6690], the profile interface uses
a well-known resource URI as a pointer to the profile description.
The host component of the URI of the profile description should be
equal to the URI of the associated resource, whereas the path
component begins with ".well-known" as specified in [RFC5785]. The
complete path component equals ".well-known/profile".
For example, if the client wants to get the profile description of a
server with URI "www.example.org", it can send a GET request for
"coap://www.example.org/.well-known/profile". In this case the
server SHOULD respond with the profile details of all resources on
the server. The server MAY use the reserved resource name "." to
provide a default profile. This default profile applies to all
resources that are not specifically listed in the profile (e.g.
because they do not have their individual profile) and describes the
general CoAP capabilities of the server. If a resource has its own
profile, then this profile MUST be used and the default profile field
MUST be ignored.
If only the profile of a particular resource is needed, the client
SHOULD send a GET request including the "path" URI-query. If the
resource has no specific profile the server MUST respond with the
default profile.
For example, the profile of the sensor "coap://www.example.org/s" can
be acquired with a GET to:
"coap://www.example.org/.well-known/profile?path=s".
Section 5 covers this in more detail.
Greevenbosch, et al. Expires April 25, 2013 [Page 6]
Internet-Draft CoAP Profile Description Format October 2012
4. The Profile Format
The profile description is formatted as a JSON document. It consists
of several profile fields, each of which has associated parameters.
4.1. The path "path" profile field
The "path" profile field contains the Uri-Path component associated
with the resource. It can be used to filter on certain profile
properties, as described in Section 5.
4.2. The options "op" profile field
The options "op" profile field contains a list of options that are
supported by a resource. It has the format depicted in Figure 1,
where op1, op2, ... are integers representing the option numbers of
the supported options, as defined in [I-D.ietf-core-coap] and/or
through IANA. The option numbers MUST appear in numerical order,
starting with the lowest number.
"op":[op1,op2,...]
Figure 1: "op" syntax
When including the "op" profile field in the profile description of a
resource, all option numbers of the CoAP options supported by that
resource MUST be included. Options that are not supported by the
resource MUST NOT be included in the "op" profile field.
If the "op" profile field is available, the receiving party SHALL
assume a non-listed option is not supported by the associated
resource.
4.3. The Content-Formats "cf" profile field
The content formats "cf" profile field indicates which content
formats are supported. It has the format depicted in Figure 2, where
cf1, cf2, ... are integers representing the numbers of the supported
content formats, as defined in [I-D.ietf-core-coap] and/or through
IANA. The content format numbers MUST appear in numerical order,
starting with the lowest number.
"cf":[cf1,cf2,...]
Figure 2: "cf" syntax
When including the "cf" profile field in the profile description of a
resource, all content formats of the CoAP options supported by that
Greevenbosch, et al. Expires April 25, 2013 [Page 7]
Internet-Draft CoAP Profile Description Format October 2012
resource MUST be included. Content formats that are not supported by
the resource MUST NOT be included in the "cf" profile field.
If the "cf" profile field is available, the receiving party SHALL
assume a non-listed content format is not supported by the associated
resource.
4.4. The Block-Sizes "b1s" and "b2s" profile fields
The block sizes "b1s" and "b2s" profile fields indicate which block
sizes are supported for Block1 and Block2 options when block-wise
transfer is used. It has the format depicted in Figure 3, where
b1s1, b1s2, ... are three-bit unsigned integers indicating the size
of a block to the power of two. Thus block size = 2**(b1 + 4). The
allowed values of b1 are 0 to 6, i.e., the minimum block size is
2**(0+4) = 16 and the maximum is 2**(6+4) = 1024. The block-size
numbers MUST appear in numerical order, starting with the lowest
number (see [I-D.ietf-core-block]).
"b1s":[b1s1,b1s2,...]
"b2s":[b2s1,b2s2,...]
Figure 3: "b1s" and "b2s" syntax
When including the "b1s" or the "b2s" profile fields in the profile
description of a resource, all respective Block1 and Block2 sizes
that are supported in block-wise transfer by that resource MUST be
included. Block sizes that are not supported by the resource MUST
NOT be included in the "b1s" or the "b2s" profile fields.
If the "b1s" or the "b2s" profile fields are available, the receiving
party SHALL assume a non-listed block size is not supported by the
associated resource. If only one of the "b1s" and the "b2s" profile
fields is available, the receiving party SHALL assume that the other
block transfer is not supported by the associated resource.
Greevenbosch, et al. Expires April 25, 2013 [Page 8]
Internet-Draft CoAP Profile Description Format October 2012
5. Usage of URI Queries
To specify which information is needed, the client MAY include an
"Uri-Query" option in its request for the profile description. The
server SHOULD understand and process this information, although
constraint servers MAY omit the functionality. In the latter case,
they SHOULD return the same results as if the "Uri-Query" option was
not included.
The URI Queries are of the form "N=V", where N is the name of the
field to filter on, and V is the desired value.
For example, if the client wants to know all resources on the server
that support content format "application/json", which has the number
50 (see [I-D.ietf-core-coap]), then it will include a "Uri-Query"
option with the value "cf=50".
When the request contains multiple "Uri-Query" options, "AND"
semantics hold.
Greevenbosch, et al. Expires April 25, 2013 [Page 9]
Internet-Draft CoAP Profile Description Format October 2012
6. Forward compatibility
To allow addition of new profile fields in the future, unknown
profile fields SHOULD be ignored by the client.
Greevenbosch, et al. Expires April 25, 2013 [Page 10]
Internet-Draft CoAP Profile Description Format October 2012
7. Examples
The following is an example of a camera sensor at
"coap://www.example.org/cam", that supports the "Uri-Host" (3),
"ETag" (4), "Uri-Port" (7), "Uri-Path" (11), "Content-Format" (12),
"Token" (19), "Block2" (23) and "Proxy-Uri" (35) options.
The supported content formats are "text/plain" (0), "application/
link-format" (40) and "application/json" (50).
The camera can support Block2 with Block sizes of 256 or 512 bytes.
Req: GET coap://www.example.org/.well-known/profile
Res: 2.05 Content (application/json)
{
"profile":
{
"path":"cam",
"op":[3,4,7,11,12,19,23,35],
"cf":[0,40,50]
"b2s":[4,5]
}
}
If the server also supports three other resources, such as a
temperature sensor (which can do observe), a humidity and a fire
detector, the request/response pair would look as follows:
Greevenbosch, et al. Expires April 25, 2013 [Page 11]
Internet-Draft CoAP Profile Description Format October 2012
Req: GET coap://www.example.org/.well-known/profile
Res: 2.05 Content (application/json)
{
"profile":[
{
"path":".",
"op":[3,4,7,11,12,19,35],
"cf":[0]
},
{
"path":"cam",
"op":[3,4,7,11,12,19,23,35],
"cf":[0,40,50]
"b2s":[4,5]
},
{
"path":"temperature",
"op":[3,4,6,7,11,12,19,35],
"cf":[0]
},
]
}
Please note that the response did not include profiles for the "fire"
and "humidity" resources. Instead it included a default profile that
applies for these two not explicitly mentioned resources.
If the client now wants to get the resources that support content-
format "application/json" (50) it looks as follows:
Req: GET coap://www.example.org/.well-known/profile?cf=50
Res: 2.05 Content (application/json)
{
"profile":
{
"path":"cam",
"op":[3,4,7,11,12,19,23,35],
"cf":[0,40,50]
"b2s":[4,5]
}
}
Greevenbosch, et al. Expires April 25, 2013 [Page 12]
Internet-Draft CoAP Profile Description Format October 2012
8. Open topics
8.1. Open since v00
o How to signal the client profile?
o Which other profile data needs signalling?
o A natural content format for a camera would be JPEG. Therefore
the "image/jpeg" content format may need CoAP registration.
o Currently, support of observe can be signalled in the link format
as well as through the mechanism described here.
o Is it needed to signal the profile description on a resource
basis, or would it be enough to have only one, associated with the
server?
o Fix the order in which the profile fields must appear?
o Make a distinction between "critical" and "elective" profile
fields?
8.2. Open since v01
o Addition of the "path" option seems to create overlap with the
link format.
o For the time being, text about the hierarchy of profiles in
servers, batches and resources has been removed. This leads to a
requirement to provide the profile description for each separate
resource. A mechanism to re-introduce hierarchy may make
significantly reduce the profile description verboseness.
Greevenbosch, et al. Expires April 25, 2013 [Page 13]
Internet-Draft CoAP Profile Description Format October 2012
9. Change log
9.1. Changes in v01
o Changed from /p suffix to usage of ".well-known/profile"
o Added support of Uri-Query
o Updated option numbering according to [I-D.ietf-core-coap]
o Changed Media Type and "mt" to Content Format and "cf", in
accordance with [I-D.ietf-core-coap]
o Expanded examples
o Removed text about the hierarchy
o Added default profile "."
o Added "b1s" and "b2s" fields for block size
Greevenbosch, et al. Expires April 25, 2013 [Page 14]
Internet-Draft CoAP Profile Description Format October 2012
10. Security Considerations
For general CoAP security considerations see [I-D.ietf-core-coap].
In an unprotected environment, an attacker can change the profile
description. 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. However, such a threat is normal in
environments that lack secure authentication.
Greevenbosch, et al. Expires April 25, 2013 [Page 15]
Internet-Draft CoAP Profile Description Format October 2012
11. IANA Considerations
o A registry for profile fields as well as possible values needs to
be set up.
o The ".well-known/profile" path component must be registered.
Greevenbosch, et al. Expires April 25, 2013 [Page 16]
Internet-Draft CoAP Profile Description Format October 2012
12. Acknowledgements
The authors would like to thank Kepeng Li for his ideas and feedback.
Greevenbosch, et al. Expires April 25, 2013 [Page 17]
Internet-Draft CoAP Profile Description Format October 2012
13. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known
Uniform Resource Identifiers (URIs)", RFC 5785,
April 2010.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, August 2012.
[I-D.ietf-core-block]
Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP",
draft-ietf-core-block-10 (work in progress), October 2012.
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., Bormann, C., and B. Frank,
"Constrained Application Protocol (CoAP)",
draft-ietf-core-coap-12 (work in progress), October 2012.
[I-D.ietf-core-link-format]
Shelby, Z., "CoRE Link Format",
draft-ietf-core-link-format-12 (work in progress),
May 2012.
Greevenbosch, et al. Expires April 25, 2013 [Page 18]
Internet-Draft CoAP Profile Description Format October 2012
Authors' Addresses
Bert Greevenbosch
Huawei Technologies Co., Ltd.
Huawei Industrial Base
Bantian, Longgang District
Shenzhen 518129
P.R. China
Phone: +86-755-28978088
Email: bert.greevenbosch@huawei.com
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
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
Greevenbosch, et al. Expires April 25, 2013 [Page 19]