idnits 2.17.1 draft-greevenbosch-core-profile-description-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 21, 2013) is 3954 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-21) exists of draft-ietf-core-block-11 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-17 Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core B. Greevenbosch 3 Internet-Draft Huawei Technologies 4 Intended status: Standards Track J. Hoebeke 5 Expires: December 23, 2013 I. Ishaq 6 F. Van den Abeele 7 iMinds-IBCN/UGent 8 June 21, 2013 10 CoAP Profile Description Format 11 draft-greevenbosch-core-profile-description-02 13 Abstract 15 This document provides a profile description format, that can be used 16 to express capabilities of a CoAP server. 18 Note 20 Discussion and suggestions for improvement are requested, and should 21 be sent to core@ietf.org. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 23, 2013. 40 Copyright Notice 42 Copyright (c) 2013 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 2 58 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 3. Obtaining the profile information . . . . . . . . . . . . . . 3 60 4. The Profile Format . . . . . . . . . . . . . . . . . . . . . 4 61 4.1. The Path "path" profile field . . . . . . . . . . . . . . 4 62 4.2. The Methods "m" profile field . . . . . . . . . . . . . . 4 63 4.3. The Options "op" profile field . . . . . . . . . . . . . 4 64 4.4. The Block-Sizes "b1s" and "b2s" profile fields . . . . . 5 65 4.5. The Content-Formats "cf" profile field . . . . . . . . . 5 66 5. Usage of URI Queries . . . . . . . . . . . . . . . . . . . . 6 67 6. Forward compatibility . . . . . . . . . . . . . . . . . . . . 6 68 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 8. Open topics . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 8.1. Open since v00 . . . . . . . . . . . . . . . . . . . . . 8 71 8.2. Open since v01 . . . . . . . . . . . . . . . . . . . . . 8 72 8.3. Open since v02 . . . . . . . . . . . . . . . . . . . . . 9 73 9. Change log . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 9.1. Changes in v01 . . . . . . . . . . . . . . . . . . . . . 9 75 9.2. Changes in v02 . . . . . . . . . . . . . . . . . . . . . 9 76 10. Security Considerations . . . . . . . . . . . . . . . . . . . 9 77 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 79 13. Normative References . . . . . . . . . . . . . . . . . . . . 10 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 10 82 1. Requirements notation 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 86 document are to be interpreted as described in [RFC2119]. 88 2. Introduction 90 The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a 91 RESTful protocol for constrained nodes and networks. 93 Often, a client first learns about a resource through the link format 94 [I-D.ietf-core-link-format]. The link format only provides basic 95 information, for example the resource URL. However, it would be good 96 if the client could get more extensive information on the resources 97 when required. This document defines a profile description format, 98 which can be used to signal several parameters about resources and 99 their servers. 101 One of the main features of the CoAP protocol is the ability to 102 include CoAP options. These options can be either elective or 103 critical. A message with an unsupported critical option will be 104 rejected, whereas unsupported elective options will be ignored. 106 Even though it is well defined how the server must respond to 107 unsupported options, it is useful for the client to know which 108 options are supported in advance. In this way, it can determine 109 which options are viable to use in a transaction, and which features 110 cannot be exploited. This specification allows signalling of the 111 supported options by the resource. 113 Another important feature of a CoAP server is which content formats 114 it supports. CoAP provides a mechanism for the client to indicate to 115 the server which content format the client prefers. The use of 116 profiles allows signalling what content formats are supported by the 117 server, so that the client can decide which content type it prefers. 119 Signalling of the supported CoAP methods (e.g. GET, POST) and maximum 120 block size is also provided. It is anticipated that more profile 121 fields will be defined in the future. 123 3. Obtaining the profile information 125 Similar to the link format from [RFC6690], the profile interface uses 126 a well-known resource URI as a pointer to the profile description. 128 The host component of the URI of the profile description should be 129 equal to the URI of the associated resource, whereas the path 130 component begins with ".well-known" as specified in [RFC5785]. The 131 complete path component equals ".well-known/profile". 133 For example, if the client wants to get the profile description of a 134 server with URI "www.example.org", it can send a GET request for 135 "coap://www.example.org/.well-known/profile". In this case the 136 server SHOULD respond with the profile details of all resources on 137 the server. The server MAY use the reserved resource name "." to 138 provide a default profile. This default profile applies to all 139 resources that are not specifically listed in the profile (e.g. 140 because they do not have their individual profile) and describes the 141 general CoAP capabilities of the server. If a resource has its own 142 profile, then this profile MUST be used and the default profile field 143 MUST be ignored. 145 If only the profile of a particular resource is needed, the client 146 SHOULD send a GET request including the "path" URI-query. If the 147 resource has no specific profile the server MUST respond with the 148 default profile. 150 For example, the profile of the sensor "coap://www.example.org/s" can 151 be acquired with a GET to: "coap://www.example.org/.well-known/ 152 profile?path=s". 154 Section 5 covers this in more detail. 156 4. The Profile Format 158 The profile description is formatted as a JSON document. It consists 159 of several profile fields, each of which has associated parameters. 161 4.1. The Path "path" profile field 163 The "path" profile field contains the Uri-Path component associated 164 with the resource. It can be used to filter on certain profile 165 properties, as described in Section 5. 167 4.2. The Methods "m" profile field 169 The methods "m" profile field describes the CoAP methods that the 170 resource supports. 172 "m":[m1,m2,...] 174 Figure 1: "m" syntax 176 The methods are defined by integer values containing the method codes 177 as defined in [I-D.ietf-core-coap], Table 5 [TBD update this when 178 CoAP has become RFC.], or registered with IANA. 180 For simplicity, the "0." prefix is omitted. So in the "m" profile 181 field, GET is indicated by the value 1, POST by 2, PUT by 3 and 182 DELETE by 4. 184 4.3. The Options "op" profile field 186 The options "op" profile field contains a list of options that are 187 supported by a resource. It has the format depicted in Figure 2, 188 where op1, op2, ... are integers representing the option numbers of 189 the supported options, as defined in [I-D.ietf-core-coap] or 190 registered with IANA. The option numbers MUST appear in numerical 191 order, starting with the lowest number. 193 "op":[op1,op2,...] 195 Figure 2: "op" syntax 197 When including the "op" profile field in the profile description of a 198 resource, all option numbers of the CoAP options supported by that 199 resource MUST be included. Options that are not supported by the 200 resource MUST NOT be included in the "op" profile field. 202 If the "op" profile field is available, the receiving party SHALL 203 assume a non-listed option is not supported by the associated 204 resource. 206 4.4. The Block-Sizes "b1s" and "b2s" profile fields 208 The block sizes "b1s" and "b2s" profile fields indicate which block 209 sizes are supported for Block1 and Block2 options when block-wise 210 transfer is used. It has the format depicted in Figure 3, where 211 b1s1, b1s2, ... are three-bit unsigned integers indicating the size 212 of a block to the power of two. Thus block size = 2**(b1 + 4). The 213 allowed values of b1 are 0 to 6, i.e., the minimum block size is 214 2**(0+4) = 16 and the maximum is 2**(6+4) = 1024. The block-size 215 numbers MUST appear in numerical order, starting with the lowest 216 number (see [I-D.ietf-core-block]). 218 "b1s":[b1s1,b1s2,...] 219 "b2s":[b2s1,b2s2,...] 221 Figure 3: "b1s" and "b2s" syntax 223 When including the "b1s" or the "b2s" profile fields in the profile 224 description of a resource, all respective Block1 and Block2 sizes 225 that are supported in block-wise transfer by that resource MUST be 226 included. Block sizes that are not supported by the resource MUST 227 NOT be included in the "b1s" or the "b2s" profile fields. 229 If the "b1s" or the "b2s" profile fields are available, the receiving 230 party SHALL assume a non-listed block size is not supported by the 231 associated resource. If only one of the "b1s" and the "b2s" profile 232 fields is available, the receiving party SHALL assume that the other 233 block transfer is not supported by the associated resource. 235 4.5. The Content-Formats "cf" profile field 237 The content formats "cf" profile field indicates which content 238 formats are supported. It has the format depicted in Figure 4, where 239 cf1, cf2, ... are integers representing the numbers of the supported 240 content formats, as defined in [I-D.ietf-core-coap] or registered 241 with IANA. The content format numbers MUST appear in numerical 242 order, starting with the lowest number. 244 "cf":[cf1,cf2,...] 246 Figure 4: "cf" syntax 248 When including the "cf" profile field in the profile description of a 249 resource, all content formats of the CoAP options supported by that 250 resource MUST be included. Content formats that are not supported by 251 the resource MUST NOT be included in the "cf" profile field. 253 If the "cf" profile field is available, the receiving party SHALL 254 assume a non-listed content format is not supported by the associated 255 resource. 257 5. Usage of URI Queries 259 To specify which information is needed, the client MAY include an 260 "Uri-Query" option in its request for the profile description. The 261 server SHOULD understand and process this information, although 262 constraint servers MAY omit the functionality. In the latter case, 263 they SHOULD return the same results as if the "Uri-Query" option was 264 not included. 266 The URI Queries are of the form "N=V", where N is the name of the 267 field to filter on, and V is the desired value. 269 For example, if the client wants to know all resources on the server 270 that support content format "application/json", which has the number 271 50 (see [I-D.ietf-core-coap]), then it will include a "Uri-Query" 272 option with the value "cf=50". 274 When the request contains multiple "Uri-Query" options, "AND" 275 semantics hold. 277 6. Forward compatibility 279 To allow addition of new profile fields in the future, unknown 280 profile fields SHOULD be ignored by the client. 282 7. Examples 284 The following is an example of a camera sensor at "coap:// 285 www.example.org/cam", that supports the "Uri-Host" (3), "ETag" (4), 286 "Uri-Port" (7), "Uri-Path" (11), "Content-Format" (12), "Token" (19), 287 "Block2" (23) and "Proxy-Uri" (35) options. 289 The supported content formats are "text/plain" (0), "application/ 290 link-format" (40) and "application/json" (50). 292 The camera only supports the GET method (1). 294 The camera can support Block2 with Block sizes of 256 or 512 bytes. 296 Req: GET coap://www.example.org/.well-known/profile 298 Res: 2.05 Content (application/json) 299 { 300 "profile": 301 { 302 "path":"cam", 303 "m":[1], 304 "op":[3,4,7,11,12,19,23,35], 305 "b2s":[4,5], 306 "cf":[0,40,50] 307 } 308 } 310 If the server also supports three other resources, such as a 311 temperature sensor (which can do observe), a humidity and a fire 312 detector, the request/response pair would look as follows: 314 Req: GET coap://www.example.org/.well-known/profile 316 Res: 2.05 Content (application/json) 317 { 318 "profile":[ 319 { 320 "path":".", 321 "m":[1], 322 "op":[3,4,7,11,12,19,35], 323 "cf":[0] 324 }, 325 { 326 "path":"cam", 327 "m":[1], 328 "op":[3,4,7,11,12,19,23,35], 329 "b2s":[4,5], 330 "cf":[0,40,50] 331 }, 332 { 333 "path":"temperature", 334 "m":[1], 335 "op":[3,4,6,7,11,12,19,35], 336 "cf":[0] 337 } 338 ] 339 } 341 Please note that the response did not include profiles for the "fire" 342 and "humidity" resources. Instead it included a default profile that 343 applies for these two not explicitly mentioned resources. 345 If the client now wants to get the resources that support content- 346 format "application/json" (50) it looks as follows: 348 Req: GET coap://www.example.org/.well-known/profile?cf=50 350 Res: 2.05 Content (application/json) 351 { 352 "profile": 353 { 354 "path":"cam", 355 "m":[1], 356 "op":[3,4,7,11,12,19,23,35], 357 "b2s":[4,5], 358 "cf":[0,40,50] 359 } 360 } 362 8. Open topics 364 8.1. Open since v00 366 o How to signal the client profile? 368 o Which other profile data needs signalling? 370 o A natural content format for a camera would be JPEG. Therefore 371 the "image/jpeg" content format may need CoAP registration. 373 o Fix the order in which the profile fields must appear? 375 8.2. Open since v01 377 o For the time being, text about the hierarchy of profiles in 378 servers, batches and resources has been removed. This leads to a 379 requirement to provide the profile description for each separate 380 resource. A mechanism to re-introduce hierarchy may make 381 significantly reduce the profile description verboseness. 383 8.3. Open since v02 385 o The "cf" field contains redundant information, as supported 386 content types can also be signalled through the link format "ct" 387 attribute. However, it could be useful to insert this information 388 in ".well-known/profile" too, such that a receiving entity does 389 not need to gather the information from two sources. 391 9. Change log 393 9.1. Changes in v01 395 o Changed from /p suffix to usage of ".well-known/profile" 397 o Added support of Uri-Query 399 o Updated option numbering according to [I-D.ietf-core-coap] 401 o Changed Media Type and "mt" to Content Format and "cf", in 402 accordance with [I-D.ietf-core-coap] 404 o Expanded examples 406 o Removed text about the hierarchy 408 o Added default profile "." 410 o Added "b1s" and "b2s" fields for block size 412 9.2. Changes in v02 414 o Added methods "m" profile field. 416 o The order of the fields has been changed in both the description 417 and the examples. This order is not mandated though. 419 10. Security Considerations 421 For general CoAP security considerations see [I-D.ietf-core-coap]. 423 In an unprotected environment, an attacker can change the profile 424 description. For example, the list of supported options may be 425 changed. This could cause the client to make a wrong decision on 426 which mechanisms to use. However, such a threat is normal in 427 environments that lack secure authentication. 429 11. IANA Considerations 430 o A registry for profile fields as well as possible values needs to 431 be set up. 433 o The ".well-known/profile" path component must be registered. 435 12. Acknowledgements 437 The authors would like to thank Kepeng Li for his ideas and feedback. 439 13. Normative References 441 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 442 Requirement Levels", BCP 14, RFC 2119, March 1997. 444 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 445 Uniform Resource Identifiers (URIs)", RFC 5785, April 446 2010. 448 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 449 Format", RFC 6690, August 2012. 451 [I-D.ietf-core-block] 452 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 453 draft-ietf-core-block-11 (work in progress), March 2013. 455 [I-D.ietf-core-coap] 456 Shelby, Z., Hartke, K., and C. Bormann, "Constrained 457 Application Protocol (CoAP)", draft-ietf-core-coap-17 458 (work in progress), May 2013. 460 [I-D.ietf-core-link-format] 461 Shelby, Z., "CoRE Link Format", draft-ietf-core-link- 462 format-14 (work in progress), June 2012. 464 Authors' Addresses 466 Bert Greevenbosch 467 Huawei Technologies Co., Ltd. 468 Huawei Industrial Base 469 Bantian, Longgang District 470 Shenzhen 518129 471 P.R. China 473 Phone: +86-755-28978088 474 Email: bert.greevenbosch@huawei.com 475 Jeroen Hoebeke 476 iMinds-IBCN/UGent 477 Department of Information Technology 478 Internet Based Communication Networks and Services (IBCN) 479 Ghent University - iMinds 480 Gaston Crommenlaan 8 bus 201 481 Ghent B-9050 482 Belgium 484 Phone: +32-9-3314954 485 Email: jeroen.hoebeke@intec.ugent.be 487 Isam Ishaq 488 iMinds-IBCN/UGent 489 Department of Information Technology 490 Internet Based Communication Networks and Services (IBCN) 491 Ghent University - iMinds 492 Gaston Crommenlaan 8 bus 201 493 Ghent B-9050 494 Belgium 496 Phone: +32-9-3314946 497 Email: isam.ishaq@intec.ugent.be 499 Floris Van den Abeele 500 iMinds-IBCN/UGent 501 Department of Information Technology 502 Internet Based Communication Networks and Services (IBCN) 503 Ghent University - iMinds 504 Gaston Crommenlaan 8 bus 201 505 Ghent B-9050 506 Belgium 508 Phone: +32-9-3314946 509 Email: floris.vandenabeele@intec.ugent.be