idnits 2.17.1 draft-greevenbosch-core-profile-description-00.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 12, 2012) is 4335 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-09 == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-12 == Outdated reference: A later version (-05) exists of draft-shelby-core-interfaces-02 Summary: 0 errors (**), 0 flaws (~~), 4 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: Informational June 12, 2012 5 Expires: December 14, 2012 7 CoAP Profile Description Format 8 draft-greevenbosch-core-profile-description-00 10 Abstract 12 This document provides a profile description format, that can be used 13 to express capabilities of a CoAP server. 15 Note 17 Discussion and suggestions for improvement are requested, and should 18 be sent to core@ietf.org. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on December 14, 2012. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 4 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3. The Profile Interface . . . . . . . . . . . . . . . . . . . . 6 57 4. The Profile Format . . . . . . . . . . . . . . . . . . . . . . 7 58 4.1. The Options "op" profile field . . . . . . . . . . . . . . 7 59 4.2. The Media-Types "mt" profile field . . . . . . . . . . . . 7 60 5. Usage with servers, resources and batches . . . . . . . . . . 8 61 6. Forward compatibility . . . . . . . . . . . . . . . . . . . . 9 62 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 63 8. Open topics . . . . . . . . . . . . . . . . . . . . . . . . . 11 64 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 65 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 66 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 14 67 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 68 12.1. Normative References . . . . . . . . . . . . . . . . . . . 15 69 12.2. Informative References . . . . . . . . . . . . . . . . . . 15 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 72 1. Requirements notation 74 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 75 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 76 document are to be interpreted as described in [RFC2119]. 78 2. Introduction 80 The Constrained Application Protocol (CoAP) [I-D.ietf-core-coap] is a 81 RESTful protocol for constrained nodes and networks. 83 Often, a client first learns about a resource through the link format 84 [I-D.ietf-core-link-format]. The link format only provides basic 85 information, for example the resource URL. However, it would be good 86 if the client could get more extensive information on the resources 87 when required. This document defines a profile description format, 88 which can be used to signal several parameters about resources and 89 their servers. 91 One of the main features of the CoAP protocol is the ability to 92 include CoAP options. These options can be either elective or 93 critical. A message with an unsupported critical option will be 94 rejected, whereas unsupported elective options will be ignored. 96 Even though it is well defined how the server must respond to 97 unsupported options, it is useful for the client to know which 98 options are supported in advance. In this way, it can determine 99 which options are viable to use in a transaction, and which features 100 cannot be exploited. This specification allows signalling of the 101 supported options by the resource. 103 Another important feature of a server is which media types it 104 supports. This document allows signalling of that information too. 106 It is anticipated that more profile descriptions will become 107 available in the future. 109 3. The Profile Interface 111 The profile description can be obtained through a link with interface 112 type "core#p" (see also [I-D.shelby-core-interfaces]). The URI of 113 the profile description should be equal to the URI of the associated 114 resource, but with a "/p" suffix. For example, if the client wants 115 to get profile description on a server witn URI "www.example.org", it 116 can send a GET request for "coap://www.example.org/p". 118 If the profile of a particular resource is available, it should use 119 the same naming convention. For example, the profile of the sensor 120 "coap://www.example.org/s/tmp" (on the same server) can be acquired 121 with a GET to: "coap://www.example.org/s/tmp/p". 123 4. The Profile Format 125 The profile description is formatted as a JSON document. It consists 126 of several profile fields, each of which has associated parameters. 128 4.1. The Options "op" profile field 130 The Options "op" profile field contains a list of options that are 131 supported by a resource. It has the format depicted in Figure 1, 132 where op1, op2, ... are integers representing the option numbers of 133 the supported options, as defined in [I-D.ietf-core-coap] and/or 134 through IANA. The option numbers MUST appear in numerical order, 135 starting with the lowest number. 137 "op":[op1,op2,...] 139 Figure 1: "op" syntax 141 When including the "op" profile field in the profile description of a 142 resource, all option numbers of the CoAP options supported by that 143 resource MUST be included. Options that are not supported by the 144 resource MUST NOT be included in the "op" profile field. 146 If the "op" profile field is available, the receiving party SHALL 147 assume a non-listed option is not supported by the associated 148 resource. 150 4.2. The Media-Types "mt" profile field 152 The Media-Types "mt" profile field indicates which media-types are 153 supported. It has the format depicted in Figure 2, where mt1, mt2, 154 ... are integers representing the media-type numbers of the supported 155 media-types, as defined in [I-D.ietf-core-coap] and/or through IANA. 156 The media-type numbers MUST appear in numerical order, starting with 157 the lowest number. 159 "mt":[mt1,mt2,...] 161 Figure 2: "mt" syntax 163 When including the "mt" profile field in the profile description of a 164 resource, all media-types of the CoAP options supported by that 165 resource MUST be included. Media-types that are not supported by the 166 resource MUST NOT be included in the "mt" profile field. 168 If the "mt" profile field is available, the receiving party SHALL 169 assume a non-listed media-type is not supported by the associated 170 resource. 172 5. Usage with servers, resources and batches 174 A CoAP server may cater for multiple resources. In addition, the 175 document [I-D.shelby-core-interfaces] provides a batch mechanism that 176 allows querying/manipulating multiple resources at once. 178 The "/p" URI suffix allows obtaining profile description on each of 179 these three levels. For example, a GET to "http://www.example.org/p" 180 would return profile description about the complete server, whereas a 181 GET to "http://www.example.org/s/tmp/p" only returns profile 182 description about the temperature sensor "tmp". Lastly, a GET to 183 "http://www.example.org/s/p", where "/s" is a batch of sensors, would 184 return common profile description for all these sensors. 186 The hierarchical nature of these three entities implies that profiles 187 can only become more restrictive when going to a lower level. For 188 example, a server may support the block option, whereas one of its 189 resources does not. In that case, the profile of the server would 190 indicate block option support, whereas the profile of the resource 191 would not do so. 193 6. Forward compatibility 195 To allow addition of new profile fields in the future, unknown 196 profile fields SHOULD be ignored by the client. 198 7. Examples 200 The following is an example of a camera sensor at 201 "coap://www.example.org/s/cam", that supports the "Content-Type" (1), 202 "Proxy-Uri" (3), "ETag" (4), "Uri-Host" (5), "Uri-Port" (7), "Uri- 203 Path" (9), "Token" (11) and "Block2" (17) options. 205 The supported media types are "text/plan" (0), "application/ 206 link-format" (40) and "application/json" (50). 208 Req: GET /s/cam/p 210 Res: 2.05 Content (application/json) 211 { 212 "op":[1,3,4,5,7,9,11,17], 213 "mt":[0,40,50] 214 } 216 8. Open topics 218 o How to signal the client profile? 220 o Which other profile data needs signalling? 222 o A natural media type for a camera would be JPEG. Therefore the 223 "image/jpeg" media type may need CoAP registration. 225 o Currently, support of observe can be signalled in the link format 226 as well as through the mechanism described here. 228 o Section 5 describes the hierchical nature of servers, batches and 229 sensors, and how the profiles fit in this hierarchy. It is the 230 question how to handle sensors that do not provide profile data. 231 One option could be to assume profile description is inherited, 232 unless separately specified. This may be reasonable as often the 233 server provides most functionality to all of its resources. 234 However, if we don't allow inheritance of the profile description, 235 it would be needed to specify the profile description for all 236 resources separately. 238 o Is it needed to signal the profile description on a resource 239 basis, or would it be enough to have only one, associated with the 240 server? 242 o Fix the order in which the profile fields must appear? 244 o Make a distinction between "critical" and "elective" profile 245 fields? 247 9. Security Considerations 249 For general CoAP security considerations see [I-D.ietf-core-coap]. 251 In an unprotected environment, an attacker can change the profile 252 description. For example, the list of supported options may be 253 changed. This could cause the client to make a wrong decision on 254 which mechanisms to use. However, such a threat is normal in 255 environments that lack secure authentication. 257 10. IANA Considerations 259 o A registry for profile fields as well as possible values needs to 260 be set up. 262 o The "core#p" interface must be registered in due time. 264 11. Acknowledgements 266 The author would like to thank Kepeng Li for his ideas and feedback. 268 12. References 270 12.1. Normative References 272 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 273 Requirement Levels", BCP 14, RFC 2119, March 1997. 275 12.2. Informative References 277 [I-D.ietf-core-coap] 278 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 279 "Constrained Application Protocol (CoAP)", 280 draft-ietf-core-coap-09 (work in progress), March 2012. 282 [I-D.ietf-core-link-format] 283 Shelby, Z., "CoRE Link Format", 284 draft-ietf-core-link-format-12 (work in progress), 285 May 2012. 287 [I-D.shelby-core-interfaces] 288 Shelby, Z., "CoRE Link Format", 289 draft-shelby-core-interfaces-02 (work in progress), 290 March 2012. 292 Author's Address 294 Bert Greevenbosch 295 Huawei Technologies Co., Ltd. 296 Huawei Industrial Base 297 Bantian, Longgang District 298 Shenzhen 518129 299 P.R. China 301 Phone: +86-755-28978088 302 Email: bert.greevenbosch@huawei.com