[Docs] [txt|pdf] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02

core                                                     B. Greevenbosch
Internet-Draft                                       Huawei Technologies
Intended status: Standards Track                              J. Hoebeke
Expires: December 23, 2013                                      I. Ishaq
                                                       F. Van den Abeele
                                                       iMinds-IBCN/UGent
                                                           June 21, 2013


                    CoAP Profile Description Format
             draft-greevenbosch-core-profile-description-02

Abstract

   This document provides a profile description format, that can be used
   to express capabilities of a CoAP server.

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 23, 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



Greevenbosch, et al.    Expires December 23, 2013               [Page 1]


Internet-Draft       CoAP Profile Description Format           June 2013


   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.  Requirements notation . . . . . . . . . . . . . . . . . . . .   2
   2.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Obtaining the profile information . . . . . . . . . . . . . .   3
   4.  The Profile Format  . . . . . . . . . . . . . . . . . . . . .   4
     4.1.  The Path "path" profile field . . . . . . . . . . . . . .   4
     4.2.  The Methods "m" profile field . . . . . . . . . . . . . .   4
     4.3.  The Options "op" profile field  . . . . . . . . . . . . .   4
     4.4.  The Block-Sizes "b1s" and "b2s" profile fields  . . . . .   5
     4.5.  The Content-Formats "cf" profile field  . . . . . . . . .   5
   5.  Usage of URI Queries  . . . . . . . . . . . . . . . . . . . .   6
   6.  Forward compatibility . . . . . . . . . . . . . . . . . . . .   6
   7.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .   6
   8.  Open topics . . . . . . . . . . . . . . . . . . . . . . . . .   8
     8.1.  Open since v00  . . . . . . . . . . . . . . . . . . . . .   8
     8.2.  Open since v01  . . . . . . . . . . . . . . . . . . . . .   8
     8.3.  Open since v02  . . . . . . . . . . . . . . . . . . . . .   9
   9.  Change log  . . . . . . . . . . . . . . . . . . . . . . . . .   9
     9.1.  Changes in v01  . . . . . . . . . . . . . . . . . . . . .   9
     9.2.  Changes in v02  . . . . . . . . . . . . . . . . . . . . .   9
   10. Security Considerations . . . . . . . . . . . . . . . . . . .   9
   11. IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
   12. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .  10
   13. Normative References  . . . . . . . . . . . . . . . . . . . .  10
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  10

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].

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



Greevenbosch, et al.    Expires December 23, 2013               [Page 2]


Internet-Draft       CoAP Profile Description Format           June 2013


   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.

   Signalling of the supported CoAP methods (e.g. GET, POST) and maximum
   block size is also provided.  It is anticipated that more profile
   fields will be defined in the future.

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.




Greevenbosch, et al.    Expires December 23, 2013               [Page 3]


Internet-Draft       CoAP Profile Description Format           June 2013


   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.

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 Methods "m" profile field

   The methods "m" profile field describes the CoAP methods that the
   resource supports.

   "m":[m1,m2,...]

                           Figure 1: "m" syntax

   The methods are defined by integer values containing the method codes
   as defined in [I-D.ietf-core-coap], Table 5 [TBD update this when
   CoAP has become RFC.], or registered with IANA.

   For simplicity, the "0." prefix is omitted.  So in the "m" profile
   field, GET is indicated by the value 1, POST by 2, PUT by 3 and
   DELETE by 4.

4.3.  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 2,
   where op1, op2, ... are integers representing the option numbers of
   the supported options, as defined in [I-D.ietf-core-coap] or
   registered with IANA.  The option numbers MUST appear in numerical
   order, starting with the lowest number.




Greevenbosch, et al.    Expires December 23, 2013               [Page 4]


Internet-Draft       CoAP Profile Description Format           June 2013


   "op":[op1,op2,...]

                           Figure 2: "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.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.

4.5.  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 4, where
   cf1, cf2, ... are integers representing the numbers of the supported
   content formats, as defined in [I-D.ietf-core-coap] or registered



Greevenbosch, et al.    Expires December 23, 2013               [Page 5]


Internet-Draft       CoAP Profile Description Format           June 2013


   with IANA.  The content format numbers MUST appear in numerical
   order, starting with the lowest number.

   "cf":[cf1,cf2,...]

                           Figure 4: "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
   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.

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.

6.  Forward compatibility

   To allow addition of new profile fields in the future, unknown
   profile fields SHOULD be ignored by the client.

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.




Greevenbosch, et al.    Expires December 23, 2013               [Page 6]


Internet-Draft       CoAP Profile Description Format           June 2013


   The supported content formats are "text/plain" (0), "application/
   link-format" (40) and "application/json" (50).

   The camera only supports the GET method (1).

   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",
       "m":[1],
       "op":[3,4,7,11,12,19,23,35],
       "b2s":[4,5],
       "cf":[0,40,50]
     }
   }


   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:

   Req: GET coap://www.example.org/.well-known/profile

   Res: 2.05 Content (application/json)
   {
     "profile":[
       {
         "path":".",
         "m":[1],
         "op":[3,4,7,11,12,19,35],
         "cf":[0]
      },
      {
         "path":"cam",
         "m":[1],
         "op":[3,4,7,11,12,19,23,35],
         "b2s":[4,5],
         "cf":[0,40,50]
       },
       {
         "path":"temperature",
         "m":[1],
         "op":[3,4,6,7,11,12,19,35],



Greevenbosch, et al.    Expires December 23, 2013               [Page 7]


Internet-Draft       CoAP Profile Description Format           June 2013


         "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",
       "m":[1],
       "op":[3,4,7,11,12,19,23,35],
       "b2s":[4,5],
       "cf":[0,40,50]
     }
   }


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  Fix the order in which the profile fields must appear?

8.2.  Open since v01

   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 December 23, 2013               [Page 8]


Internet-Draft       CoAP Profile Description Format           June 2013


8.3.  Open since v02

   o  The "cf" field contains redundant information, as supported
      content types can also be signalled through the link format "ct"
      attribute.  However, it could be useful to insert this information
      in ".well-known/profile" too, such that a receiving entity does
      not need to gather the information from two sources.

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

9.2.  Changes in v02

   o  Added methods "m" profile field.

   o  The order of the fields has been changed in both the description
      and the examples.  This order is not mandated though.

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.

11.  IANA Considerations




Greevenbosch, et al.    Expires December 23, 2013               [Page 9]


Internet-Draft       CoAP Profile Description Format           June 2013


   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.

12.  Acknowledgements

   The authors would like to thank Kepeng Li for his ideas and feedback.

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-11 (work in progress), March 2013.

   [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.ietf-core-link-format]
              Shelby, Z., "CoRE Link Format", draft-ietf-core-link-
              format-14 (work in progress), June 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






Greevenbosch, et al.    Expires December 23, 2013              [Page 10]


Internet-Draft       CoAP Profile Description Format           June 2013


   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


   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














Greevenbosch, et al.    Expires December 23, 2013              [Page 11]


Html markup produced by rfcmarkup 1.127, available from https://tools.ietf.org/tools/rfcmarkup/