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]