idnits 2.17.1 draft-vanderstok-core-comi-06.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: ---------------------------------------------------------------------------- == It seems as if not all pages are separated by form feeds - found 0 form feeds but 46 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 4 characters in excess of 72. == There are 3 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 3, 2015) is 3367 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7159' is defined on line 1682, but no explicit reference was found in the text == Unused Reference: 'RFC1213' is defined on line 1713, but no explicit reference was found in the text == Unused Reference: 'RFC2863' is defined on line 1721, but no explicit reference was found in the text == Unused Reference: 'RFC3411' is defined on line 1728, but no explicit reference was found in the text == Unused Reference: 'RFC3414' is defined on line 1733, but no explicit reference was found in the text == Unused Reference: 'RFC3986' is defined on line 1745, but no explicit reference was found in the text == Unused Reference: 'RFC4088' is defined on line 1749, but no explicit reference was found in the text == Unused Reference: 'RFC4113' is defined on line 1753, but no explicit reference was found in the text == Unused Reference: 'RFC4291' is defined on line 1756, but no explicit reference was found in the text == Unused Reference: 'RFC4293' is defined on line 1759, but no explicit reference was found in the text == Unused Reference: 'RFC6347' is defined on line 1770, but no explicit reference was found in the text == Unused Reference: 'RFC7388' is defined on line 1798, but no explicit reference was found in the text == Unused Reference: 'RFC7390' is defined on line 1803, but no explicit reference was found in the text == Unused Reference: 'STD0001' is defined on line 1822, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) == Outdated reference: A later version (-06) exists of draft-becker-core-coap-sms-gprs-05 == Outdated reference: A later version (-21) exists of draft-ietf-core-block-16 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-02 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-04 -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) == Outdated reference: A later version (-14) exists of draft-ietf-core-interfaces-02 == Outdated reference: A later version (-06) exists of draft-ietf-lwig-coap-01 Summary: 3 errors (**), 0 flaws (~~), 24 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 core P. van der Stok 3 Internet-Draft consultant 4 Intended status: Standards Track B. Greevenbosch 5 Expires: August 7, 2015 independent 6 A. Bierman 7 YumaWorks 8 J. Schoenwaelder 9 A. Sehgal 10 Jacobs University 11 February 3, 2015 13 CoAP Management Interface 14 draft-vanderstok-core-comi-06 16 Abstract 18 This document describes a network management interface for 19 constrained devices, called CoMI. CoMI is an adaptation of the 20 RESTCONF protocol for use in constrained devices and networks. It is 21 designed to reduce the message sizes, server code size, and 22 application development complexity. The Constrained Application 23 Protocol (CoAP) is used to access management data resources specified 24 in YANG, or SMIv2 converted to YANG. The payload of the CoMI message 25 is encoded in Concise Binary Object Representation (CBOR). 27 Note 29 Discussion and suggestions for improvement are requested, and should 30 be sent to core@ietf.org. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on August 7, 2015. 49 Copyright Notice 51 Copyright (c) 2015 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 67 1.1. Design considerations . . . . . . . . . . . . . . . . . . 4 68 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 69 1.2.1. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 5 70 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 6 71 2.1. RESTCONF/YANG Architecture . . . . . . . . . . . . . . . 9 72 3. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 10 73 4. MG Function Set . . . . . . . . . . . . . . . . . . . . . . . 11 74 4.1. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 11 75 4.1.1. GET . . . . . . . . . . . . . . . . . . . . . . . . . 12 76 4.1.2. Mapping of the 'select' Parameter . . . . . . . . . . 12 77 4.1.3. Retrieval Examples . . . . . . . . . . . . . . . . . 13 78 4.2. Data Editing . . . . . . . . . . . . . . . . . . . . . . 23 79 4.2.1. POST . . . . . . . . . . . . . . . . . . . . . . . . 23 80 4.2.2. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 23 81 4.2.3. DELETE . . . . . . . . . . . . . . . . . . . . . . . 24 82 4.3. Notify functions . . . . . . . . . . . . . . . . . . . . 24 83 4.4. Module Discovery . . . . . . . . . . . . . . . . . . . . 25 84 4.5. Error Return Codes . . . . . . . . . . . . . . . . . . . 27 85 5. Mapping YANG to CoMI payload . . . . . . . . . . . . . . . . 28 86 5.1. YANG Hash Generation . . . . . . . . . . . . . . . . . . 29 87 5.2. Re-Hash Procedure . . . . . . . . . . . . . . . . . . . . 29 88 5.3. ietf-yang-hash YANG Module . . . . . . . . . . . . . . . 30 89 5.3.1. YANG Re-Hash Example . . . . . . . . . . . . . . . . 32 90 5.4. YANG Hash in URL . . . . . . . . . . . . . . . . . . . . 33 91 6. Mapping YANG to CBOR . . . . . . . . . . . . . . . . . . . . 33 92 6.1. High level encoding . . . . . . . . . . . . . . . . . . . 33 93 6.2. Conversion from YANG datatypes to CBOR datatypes . . . . 34 94 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 35 95 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36 96 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 97 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 98 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 37 99 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 39 100 12.1. Normative References . . . . . . . . . . . . . . . . . . 39 101 12.2. Informative References . . . . . . . . . . . . . . . . . 40 102 Appendix A. Payload and Server sizes . . . . . . . . . . . . . . 43 103 Appendix B. Notational Convention for CBOR data . . . . . . . . 45 104 Appendix C. comparison with LWM2M . . . . . . . . . . . . . . . 46 105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 46 107 1. Introduction 109 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 110 Machine to Machine (M2M) applications such as smart energy and 111 building control. Constrained devices need to be managed in an 112 automatic fashion to handle the large quantities of devices that are 113 expected in future installations. The messages between devices need 114 to be as small and infrequent as possible. The implementation 115 complexity and runtime resources need to be as small as possible. 117 The draft [I-D.ietf-netconf-restconf] describes a REST-like interface 118 called RESTCONF, which uses HTTP methods to access structured data 119 defined in YANG [RFC6020]. RESTCONF allows access to data resources 120 contained in NETCONF [RFC6241] datastores. RESTCONF messages can be 121 encoded in XML [XML] or JSON. The GET method is used to retrieve 122 data resources and the POST, PUT, PATCH, and DELETE methods are used 123 to create, replace, merge, and delete data resources. 125 A large amount of Management Information Base (MIB) [RFC3418] 126 specifications already exist for monitoring purposes. This data can 127 be accessed in RESTCONF if the server converts the SMIv2 modules to 128 YANG, using the mapping rules defined in [RFC6643]. 130 The CoRE Management Interface (CoMI) is intended to work on 131 standardized data-sets in a stateless client-server fashion. The 132 RESTCONF protocol is adapted and optimized for use in constrained 133 environments, using CoAP instead of HTTP. Standardized data sets 134 promote interoperability between small devices and applications from 135 different manufacturers. Stateless communication is encouraged to 136 keep communications simple and the amount of state information small 137 in line with the design objectives of 6lowpan [RFC4944] [RFC6775], 138 RPL [RFC6650], and CoAP [RFC7252]. 140 RESTCONF uses the HTTP methods HEAD, OPTIONS, and PATCH, which are 141 not available in CoAP. HTTP uses TCP which is not recommended for 142 CoAP. The transport protocols available to CoAP are much better 143 suited for constrained networks. 145 TODO: Introduce CoAP Patch options to allow modification to subsets 146 of resource. 148 CoMI is low resource oriented, uses CoAP, and only supports the 149 methods GET, PUT, POST and DELETE. The payload of CoMI is encoded in 150 CBOR [RFC7049] which is automatically generated from JSON [JSON]. 151 CBOR has a binary format and hence has more coding efficiency than 152 JSON. To promote small packets, CoMI uses an additional data 153 identifier string to number conversion to minimise CBOR payloads and 154 URI length. It is assumed that the managed device is the most 155 constrained entity. The client might be more capable, however this 156 is not necessarily the case. 158 Currently, small managed devices need to support at least two 159 protocols: CoAP and SNMP. When the MIB can be accessed with the CoAP 160 protocol, the SNMP protocol can be replaced with the CoAP protocol. 161 Although the SNMP server size is not huge (see Appendix A), the code 162 for the security aspects of SMIv3 is not negligible. Using CoAP to 163 access secured management objects reduces the code complexity of the 164 stack in the constrained device, and harmonizes applications 165 development. 167 The objective of CoMI is to provide a CoAP based Function Set that 168 reads and sets values of managed objects in devices to (1) initialize 169 parameter values at start-up, (2) acquire statistics during 170 operation, and (3) maintain nodes by adjusting parameter values 171 during operation. 173 The end goal of CoMI is to provide information exchange over the CoAP 174 transport protocol in a uniform manner as a first step to the full 175 management functionality as specified in 176 [I-D.ersue-constrained-mgmt]. 178 1.1. Design considerations 180 CoMI supports discovery of resources, accompanied by reading, writing 181 and notification of resource values. As such it is close to the 182 device management of the Open Mobile Alliance described in [OMA]. A 183 detailed comparison between CoMI and LWM2M management can be found in 184 Appendix C. CoMI supports MIB modules which have been translated 185 from SMIv2 to YANG, using [RFC6643]. This mapping is read-only so 186 writable SMIv2 objects need to be converted to YANG using an 187 implementation-specific mapping. 189 CoMI uses a simple URI to access the management object resources. 190 Complexity introduced by instance selection, or multiple object 191 specification is expressed with uri-query attributes. The choice for 192 uri-query attributes makes the URI structure less context dependent. 194 TODO: Use of YANG data model reduces message size. 196 1.2. Terminology 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",and "OPTIONAL" in this 200 document are to be interpreted as described in [RFC2119]. 202 Readers of this specification should be familiar with all the terms 203 and concepts discussed in [RFC3410], [RFC3416], and [RFC2578]. 205 The following terms are defined in the NETCONF protocol [RFC6241]: 206 client, configuration data, datastore, and server. 208 The following terms are defined in the YANG data modelling language 209 [RFC6020]: container, data node, key, key leaf, leaf, leaf-list, and 210 list. 212 The following terms are defined in RESTCONF protocol 213 [I-D.ietf-netconf-restconf]: data resource, datastore resource, edit 214 operation, query parameter, target resource, and unified datastore. 216 The following terms are defined in this document: 218 YANG hash: CoMI object identifier, which is a 30-bit numeric hash of 219 the YANG object identifier string for the object. When a YANG 220 hash value is printed in a request target URI, error-path or other 221 string, then the lowercase hexadecimal representation is used. 222 Leading zeros are used so the value uses 8 hex characters. 224 The following list contains the abbreviations used in this document. 226 XXXX: TODO, and others to follow. 228 1.2.1. Tree Diagrams 230 A simplified graphical representation of the data model is used in 231 this document. The meaning of the symbols in these diagrams is as 232 follows: 234 Brackets "[" and "]" enclose list keys. 236 Abbreviations before data node names: "rw" means configuration 237 data (read-write) and "ro" state data (read-only). 239 Symbols after data node names: "?" means an optional node, "!" 240 means a presence container, and "*" denotes a list and leaf-list. 242 Parentheses enclose choice and case nodes, and case nodes are also 243 marked with a colon (":"). 245 Ellipsis ("...") stands for contents of subtrees that are not 246 shown. 248 2. CoMI Architecture 250 This section describes the CoMI architecture to use CoAP for the 251 reading and modifying of instrumentation variables used for the 252 management of the instrumented node. 254 Client 255 +--------------------------------------------------------------+ 256 | +----------------+ +----------------+ | 257 | | SMIv2 | > | YANG | > COAP | 258 | |specification(2)| |specification(1)| Request(3) | 259 | +----------------+ +----------------+[ * | 260 +-----------------------------*-----------[---------*----------+ 261 * [ * 262 * [ +-----------+ 263 mapping * security[ | Network | 264 * (8) [ | packet(4) | 265 * [ +-----------+ 266 Server * [ * 267 +-----------------------------*-----------[---------*----------+ 268 | * [ * | 269 | * Retrieval, | 270 | * Modification(5) | 271 | \*/ * | 272 | +-------------------------------------------------*--------+ | 273 | | +--------------+ +------------+ | | 274 | | |configuration | |Operational | | | 275 | | | (6b) | | state(6a) | | | 276 | | +--------------+ +------------+ | | 277 | | variable store (6) * | | 278 | +-------------------------------------------------*--------+ | 279 | * | 280 | Variable | 281 | Instrumentation(7)| 282 +--------------------------------------------------------------+ 284 Figure 1: Abstract CoMI architecture 286 Figure 1 is a high level representation of the main elements of the 287 CoAP management architecture. A client sends requests as payload in 288 packets over the network to a managed constrained node. 290 Objectives are: 292 o Equip a constrained node with a management server that provides 293 information about the operational characteristics of the code 294 running in the constrained node. 296 o The server provides this information in a variable store that 297 contains values describing the performance characteristics and the 298 code parameter values. 300 o The client receives the performance characteristics on a regular 301 basis or on request. 303 o The client sets the parameter values in the server at bootstrap 304 and intermittently when operational conditions change. 306 o The constrained network requires the payload to be as small as 307 possible, and the constrained server memory requirements should be 308 as small as possible. 310 For interoperability it is required that in addition to using the 311 Internet Protocol for data transport: 313 o The names, type, and semantics of the instrumentation variables 314 are standardized. 316 o The instrumentation variables are described in a standard 317 language. 319 o The signature of the CoAP request in the server is standardized. 321 o The format of the packet payload is standardized. 323 o The notification from server to client is standardized. 325 The different numbered components of Figure 1 are discussed according 326 to component number. 328 (1) YANG specification: contains a set of named and versioned 329 modules. A module specifies a hierarchy of named and typed 330 resources. A resource is uniquely identified by a sequence of its 331 name and the names of the enveloping resources following the 332 hierarchy order. The YANG specification serves as input to the 333 writers of application and instrumentation code and the humans 334 analysing the returned values (arrow from YANG specification to 335 Variable store). The specification can be used to check the 336 correctness of the CoAP request and do the CBOR encoding. 338 (2) SMIv2 specification: A named module specifies a set of variables 339 and "conceptual tables". Named variables have simple types. 340 Conceptual tables are composed of typed named columns. The 341 variable name and module name identify the variable uniquely. 342 There is an algorithm to translate SMIv2 specifications to YANG 343 specifications. 345 (3) CoAP request: The CoAP request needs a Universal Resource 346 Identifier (URI) and the payload of the packet to send a request. 347 The URI is composed of the schema, server, path and query and 348 looks like coap://entry.example.com/?. Fragments are 349 not supported. Allowed operations are PUT, GET, DELETE, and POST. 350 New variables can be created with POST when they exist in the YANG 351 specification. The Observe option can be used to return variable 352 values regularly or on event occurrence (notification). 354 (3.1) CoAP : The path identifies the variable in the form 355 "/mg/". 357 (3.2) CoAP : The query parameter is used to specify 358 additional (optional) aspects like the module name, the smi 359 context, and others. The idea is to keep the path simple and put 360 variations on variable specification in the query. 362 (3.3) CoAP discovery: Discovery of the variables is done with 363 standard CoAP resource discovery using /.well-known/core with 364 ?rt=/core.mg. 366 (4) Network packet: The payload contains the CBOR encoding of JSON 367 objects. This object corresponds to the converted RESTCONF 368 message payload. 370 (5) Retrieval, modification: The server needs to parse the CBOR 371 encoded message and identify the corresponding instances in the 372 Variable store. In addition, this component includes the code for 373 CoAP Observe and block options. 375 (6) Variable store: The store is composed of two parts: Operational 376 state and Configuration datastore (see Section 2.1). CoMI does 377 not see the different variable store types. The Variable store 378 contains instances of the YANG specification. Values are stored 379 in the appropriate instances, and or values are returned from the 380 instances into the payload of the packet. 382 (7) Variable instrumentation: This code depends on implementation of 383 drivers and other node specific aspects. The Variable 384 instrumentation code stores the values of the parameters into the 385 appropriate places in the operational code. The variable 386 instrumentation code reads current execution values from the 387 operational code and stores them in the appropriate instances. 389 (8) Security: The server MUST prevent unauthorized users from 390 reading or writing any data resources. CoMI relies on DTLS which 391 is specified to secure CoAP communication. 393 2.1. RESTCONF/YANG Architecture 395 CoMI adapts the RESTCONF architecture so data exchange and 396 implementation requirements are optimized for constrained devices. 398 The RESTCONF protocol uses a unified datastore to edit conceptual 399 data structures supported by the server. The details of transaction 400 preparation and non-volatile storage of the data are hidden from the 401 RESTCONF client. CoMI also uses a unified datastore, to allow 402 stateless editing of configuration variables and the notification of 403 operational variables. 405 The child schema nodes of the unified datastore include all the top- 406 level YANG data nodes in all the YANG modules supported by the 407 server. The YANG data structures represent a hierarchy of data 408 resources. The client discovers the list of YANG modules, and 409 important conformance information such as the module revision dates, 410 YANG features supported, and YANG deviations required. The 411 individual data nodes are discovered indirectly by parsing the YANG 412 modules supported by the server. 414 The YANG data definition statements contain a lot of information that 415 can help automation tools, developers, and operators use the data 416 model correctly and efficiently. The YANG definitions and server 417 YANG module capability advertisements provide an "API contract" that 418 allow a client to determine the detailed server management 419 capabilities very quickly. CoMI allows access to the same data 420 resources as a RESTCONF server, except the messages are optimized to 421 reduce identifier and payload size. 423 RESTCONF uses a simple algorithmic mapping from YANG to URI syntax to 424 identify the target resource of a retrieval or edit operation. A 425 client can construct operations or scripts using a predictable 426 syntax, based on the YANG data definitions. The target resource URI 427 can reference a data resource instance, or the datastore itself (to 428 retrieve the entire datastore or create a top-level data resource 429 instance). CoMI uses a 30-bit YANG hash value (based on the YANG 430 data node path identifier strings) to identify schema nodes in the 431 target resource URI and in the payload. 433 Any message payload data is relative to the node specified in the 434 target resource URI in a request message. CoMI message payloads are 435 based on the JSON encoding of a RESTCONF message payload. The JSON 436 identifier names are first converted to their 30-bit YANG hash values 437 and then the payload is converted to CBOR. 439 3. CoAP Interface 441 In CoAP a group of links can constitute a Function Set. The format of 442 the links is specified in [I-D.ietf-core-interfaces]. This note 443 specifies a Management Function Set. CoMI end-points that implement 444 the CoMI management protocol support at least one discoverable 445 management resource of resource type (rt): core.mg, with path: /mg, 446 where mg is short-hand for management. The name /mg is recommended 447 but not compulsory (see Section 4.4). 449 The mg resource has three sub-resources accessible with the paths: 451 /mg: YANG-based data with path "/mg" and using CBOR content encoding 452 format. This path represents a datastore resource which contains 453 YANG data resources as its descendant nodes. All identifiers 454 referring to YANG data nodes within this path are encoded as YANG 455 hash values (see Section 5.4. 457 /mg/mod.uri: URI indicating the location of the server module 458 information, with path "/mg/mod.uri" and CBOR content format. 459 This YANG data is encoded with plain identifier strings, not YANG 460 hash values. 462 /mg/yang.hash: URI indicating the location of the server YANG hash 463 information if any objects needed to be re-hashed by the server. 464 It has path "/mg/yang.hash" and is encoded in CBOR format. The 465 "ietf-yang-hash" module of Section 5.3 is used to define the 466 syntax and semantics of this data structure. This YANG data is 467 encoded with plain identifier strings, not YANG hash values. The 468 server will only have this resource if there are any objects that 469 needed to be re-hashed due to a hash collision. 471 The mapping of YANG data nodes to CoMI resources is as follows: A 472 YANG module describes a set of data trees composed of YANG data 473 nodes. Every root of a data tree in a YANG module loaded in the CoMI 474 server represents a resource of the server. All data root 475 descendants represent sub-resources. 477 The resource identifiers of the instances of the YANG specifications 478 are YANG hash values, as described in Section 5.1. When multiple 479 instances of a list node exist, the instance selection is described 480 in Section 4.1.3.4 482 The profile of the management function set, with IF=core.mg, is shown 483 in the table below, following the guidelines of 484 [I-D.ietf-core-interfaces]: 486 +------------+---------------+-------------------+------------------+ 487 | name | path | rt | Data Type | 488 +------------+---------------+-------------------+------------------+ 489 | Management | /mg | core.mg | n/a | 490 | | | | | 491 | Data | /mg | core.mg.data | application/cbor | 492 | | | | | 493 | Module Set | /mg/mod.uri | core.mg.moduri | application/cbor | 494 | URI | | | | 495 | | | | | 496 | YANG Hash | /mg/yang.hash | core.mg.yang-hash | application/cbor | 497 | Info | | | | 498 +------------+---------------+-------------------+------------------+ 500 4. MG Function Set 502 The MG Function Set provides a CoAP interface to perform a subset of 503 the functions provided by RESTCONF. 505 A subset of the operations defined in RESTCONF are used in CoMI: 507 +-----------+-----------------------------------------------------+ 508 | Operation | Description | 509 +-----------+-----------------------------------------------------+ 510 | GET | Retrieve the datastore resource or a data resource | 511 | | | 512 | POST | Create a data resource | 513 | | | 514 | PUT | Create or replace a data resource | 515 | | | 516 | DELETE | Delete a data resource | 517 +-----------+-----------------------------------------------------+ 519 4.1. Data Retrieval 520 4.1.1. GET 522 One or more instances of data resources are retrieved by the client 523 with the GET method. The RESTCONF GET operation is supported in 524 CoMI. The same constraints apply as defined in section 3.3 of 525 [I-D.ietf-netconf-restconf]. The operation is mapped to the GET 526 method defined in section 5.8.1 of [RFC7252]. 528 It is possible that the size of the payload is too large to fit in a 529 single message. In the case that management data is bigger than the 530 maximum supported payload size, the Block mechanism from 531 [I-D.ietf-core-block] is used. Notice that the Block mechanism 532 splits the data at fixed positions, such that individual data fields 533 may become fragmented. Therefore, assembly of multiple blocks may be 534 required to process the complete data field. 536 There are two query parameters for the GET method. A CoMI server 537 MUST implement the keys parameter and MAY implement the select 538 parameter to allow common data retrieval filtering functionality. 540 +----------------+--------------------------------------------------+ 541 | Query | Description | 542 | Parameter | | 543 +----------------+--------------------------------------------------+ 544 | keys | Request to select instances of a YANG definition | 545 | | | 546 | select | Request selected sub-trees from the target | 547 | | resource | 548 +----------------+--------------------------------------------------+ 550 The "keys" parameter is used to specify a specific instance of the 551 resource. When keys is not specified, all instances are returned. 552 When no or one instance of the resource exists, the keys parameter is 553 not needed. 555 4.1.2. Mapping of the 'select' Parameter 557 ANUJ TODO: Add more details based on the RESTCONF 'select' parameter. 558 We need to add information about how this parameter is encoded. 559 There should there be an error notification when filtering fails. 561 RESTCONF uses the 'select' parameter to specify an expression which 562 can represent a subset of all data nodes within the target resource 563 [I-D.ietf-netconf-restconf]. This parameter is useful for filtering 564 sub-trees and retrieving only a subset that a managing application is 565 interested in. 567 However, filtering is a resource intensive task and not all 568 constrained devices can be expected to have enough computing 569 resources such that they will be able to successfully filter and 570 return a subset of a sub-tree. This is especially likely to be true 571 with Class 0 devices that have significantly lesser RAM than 10 KiB 572 [RFC7228]. Since CoMI is targeted at constrained devices and 573 networks, only a limited subset of the 'select' parameter is used 574 here. 576 Unlike the RESTCONF 'select' parameter, CoMI does not use object 577 names in "XPath" or "path-expr" format to identify the subset that 578 needs to be filtered. Parsing XML is resource intensive for 579 constrained devices [management] and using object names can lead to 580 large message sizes. Instead, CoMI utilizes the YANG hashes 581 described in Section 5 to identify the sub-trees that should be 582 filtered from a target resource. Using these hashes ensures that a 583 constrained node can identify the target sub-tree without expending 584 many resources and that the messages generated are also efficiently 585 encoded. 587 The implementation of the 'select' parameter is already optional for 588 constrained devices, however, even when implemented it is expected to 589 be a best effort feature, rather than a service that nodes must 590 provide. This implies that if a node receives the 'select' parameter 591 specifying a set of sub-trees that should be returned, it will only 592 return those that it is able to. 594 4.1.3. Retrieval Examples 596 The examples in this section use a JSON payload with one or more 597 entries describing the pair (identifier, value). CoMI transports the 598 CBOR format to transport the equivalent contents. The CBOR syntax of 599 the payloads is specified in Section 5. 601 4.1.3.1. Single instance retrieval 603 A request to read the values of instances of a management object or 604 the leaf of an object is sent with a confirmable CoAP GET message. A 605 single object is specified in the URI path prefixed with /mg. 607 Using for example the clock container from [RFC7317], a request is 608 sent to retrieve the value of clock/current-datetime specified in 609 module system-state. The answer to the request returns a 610 (identifier, value) pair. 612 In all examples: (1) the payload is expressed in JSON, although the 613 operational payload is specified to be in CBOR, (2) the path is 614 expressed in readable names although the transported path is 615 expressed a hash value of the name (where the hash value in the 616 payload is expressed as a hexadecimal number, and the hash value in 617 the URL as a baseb 64 number), and (3) only one instance is 618 associated with the resource. 620 REQ: GET example.com/mg/system-state/clock/current-datetime 622 RES: 2.05 Content (Content-Format: application/cbor) 623 { 624 "current-datetime" : "2014-10-26T12:16:31Z" 625 } 627 The YANG hash value for 'current-datetime' is calculated by 628 constructing the schema node identifier for the object: 630 /sys:system-state/sys:clock/sys:current-datetime 632 The 30 bit murmur3 hash value is calculated on this string 633 (0x15370408 and VNwQI). The request using this hash value is shown 634 below: 636 REQ: GET example.com/mg/VNwQI 638 RES: 2.05 Content (Content-Format: application/cbor) 639 { 640 0x15370408 : "2014-10-26T12:16:31Z" 641 } 643 The specified object can be an entire object. Accordingly, the 644 returned payload is composed of all the leaves associated with the 645 object. Each leaf is returned as a (YANG hash, value) pair. For 646 example, the GET of the clock object, sent by the client, results in 647 the following returned payload sent by the managed entity: 649 REQ: GET example.com/mg/system-state/clock 650 (Content-Format: application/cbor) 652 RES: 2.05 Content (Content-Format: application/cbor) 653 { 654 "clock" : { 655 "current-datetime" : "2014-10-26T12:16:51Z", 656 "boot-datetime" : "2014-10-21T03:00:00Z" 657 } 658 } 659 The YANG hash values for 'clock', 'current-datetime', and 'boot- 660 datetime' are calculated by constructing the schema node identifier 661 for the objects, and then calculating the 30 bit murmur3 hash values 662 (shown in parenthesis): 664 /sys:system-state/sys:clock (0x2eb2fa3b and usvo7) 665 /sys:system-state/sys:clock/sys:current-datetime (0x15370408) 666 /sys:system-state/sys:clock/sys:boot-datetime (0x1fa25361) 668 The request using the hash values is shown below: 670 REQ: GET example.com/mg/usvo7 671 (Content-Format: application/cbor) 673 RES: 2.05 Content (Content-Format: application/cbor) 674 { 675 0x2eb2fa3b : { 676 0x15370408 : "2014-10-26T12:16:51Z", 677 0x1fa25361 : "2014-10-21T03:00:00Z" 678 } 679 } 681 4.1.3.2. Multiple instance retrieval 683 The specified list node can have multiple instances. Accordingly, 684 the returned payload is composed of all the instances associated with 685 the list node. Each instance is returned as a (identifier, value) 686 pair. For example, the GET of the /interfaces/interface/ipv6/ 687 neighbor instance identified with interface index "eth0" [RFC7223], 688 sent by the client, results in the following returned payload sent by 689 the managed entity: 691 REQ: GET example.com/mg/interfaces/interface/ipv6/neighbor?keys=eth0 692 (Content-Format: application/cbor) 694 RES: 2.05 Content (Content-Format: application/cbor) 695 { 696 "neighbor" : [ 697 { 698 "ip" : "fe80::200:f8ff:fe21:67cf", 699 "link-layer-address" : "00:00::10:01:23:45" 700 }, 701 { 702 "ip" : "fe80::200:f8ff:fe21:6708", 703 "link-layer-address" : "00:00::10:54:32:10" 704 }, 705 { 706 "ip" : "fe80::200:f8ff:fe21:88ee", 707 "link-layer-address" : "00:00::10:98:76:54" 708 } 709 ] 710 } 712 The YANG hash values for 'neighbor', 'ip', and 'link-layer-address' 713 are calculated by constructing the schema node identifier for the 714 objects, and then calculating the 30 bit murmur3 hash values (shown 715 in parenthesis): 717 /if:interfaces/if:interface/ip:ipv6/ip:neighbor (0x2354bc49 and jVLxJ) 718 /if:interfaces/if:interface/ip:ipv6/ip:neighbor/ip:ip (0x20b8907e and guJB_) 719 /if:interfaces/if:interface/ip:ipv6/ip:neighbor/ip:link-layer-address 720 (0x16f47fd8) 722 The request using the hash values is shown below: 724 REQ: GET example.com/mg/jVLxJ?keys=eth0 725 (Content-Format: application/cbor) 727 RES: 2.05 Content (Content-Format: application/cbor) 728 { 729 0x2354bc49 : [ 730 { 731 0x20b8907e : "fe80::200:f8ff:fe21:67cf", 732 0x16f47fd8 : "00:00::10:01:23:45" 733 }, 734 { 735 0x20b8907e : "fe80::200:f8ff:fe21:6708", 736 0x16f47fd8 : "00:00::10:54:32:10" 737 }, 738 { 739 0x20b8907e : "fe80::200:f8ff:fe21:88ee", 740 0x16f47fd8 : "00:00::10:98:76:54" 741 } 742 ] 743 } 745 4.1.3.3. Access to MIB Data 747 The YANG translation of the SMI specifying the 748 ipNetToMediaTable yields: 750 container IP-MIB { 751 container ipNetToPhysicalTable { 752 list ipNetToPhysicalEntry { 753 key "ipNetToPhysicalIfIndex ipNetToPhysicalNetAddressType 754 ipNetToPhysicalNetAddress"; 755 leaf ipNetToMediaIfIndex { 756 type: int32; 757 } 758 leaf ipNetToPhysicalIfIndex { 759 type if-mib:InterfaceIndex; 760 } 761 leaf ipNetToPhysicalNetAddressType { 762 type inet-address:InetAddressType; 763 } 764 leaf ipNetToPhysicalNetAddress { 765 type inet-address:InetAddress; 766 } 767 leaf ipNetToPhysicalPhysAddress { 768 type yang:phys-address { 769 length "0..65535"; 770 } 771 } 772 leaf ipNetToPhysicalLastUpdated { 773 type yang:timestamp; 774 } 775 leaf ipNetToPhysicalType { 776 type enumeration { ... } 777 } 778 leaf ipNetToPhysicalState { 779 type enumeration { ... } 780 } 781 leaf ipNetToPhysicalRowStatus { 782 type snmpv2-tc:RowStatus; 783 } 784 } 785 } 787 The following example shows an "ipNetToPhysicalTable" with 2 788 instances, using JSON encoding: 790 { 791 "IP-MIB" { 792 "ipNetToPhysicalTable" : { 793 "ipNetToPhysicalEntry" : [ 794 { 795 "ipNetToPhysicalIfIndex" : 1, 796 "ipNetToPhysicalNetAddressType" : "ipv4", 797 "ipNetToPhysicalNetAddress" : "10.0.0.51", 798 "ipNetToPhysicalPhysAddress" : "00:00:10:01:23:45", 799 "ipNetToPhysicalLastUpdated" : "2333943", 800 "ipNetToPhysicalType" : "static", 801 "ipNetToPhysicalState" : "reachable", 802 "ipNetToPhysicalRowStatus" : "active" 803 }, 804 { 805 "ipNetToPhysicalIfIndex" : 1, 806 "ipNetToPhysicalNetAddressType" : "ipv4", 807 "ipNetToPhysicalNetAddress" : "9.2.3.4", 808 "ipNetToPhysicalPhysAddress" : "00:00:10:54:32:10", 809 "ipNetToPhysicalLastUpdated" : "2329836", 810 "ipNetToPhysicalType" : "dynamic", 811 "ipNetToPhysicalState" : "unknown", 812 "ipNetToPhysicalRowStatus" : "active" 813 } 814 ] 815 } 816 } 817 } 819 The YANG hash values for 'ipNetToPhysicalEntry' and its child nodes 820 are calculated by constructing the schema node identifier for the 821 objects, and then calculating the 30 bit murmur3 hash values (shown 822 in parenthesis): 824 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable (0x30b7bc3f and wt7w_) 825 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry 826 (0x1067f289 and QZ/KJ) 827 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 828 ip-mib:ipNetToPhysicalIfIndex (0x00d38564) 829 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 830 ip-mib:ipNetToPhysicalNetAddressType (0x2745e222) 831 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 832 ip-mib:ipNetToPhysicalNetAddress (0x387804eb) 833 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 834 ip-mib:ipNetToPhysicalPhysAddress (0x1a51514a) 835 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 836 ip-mib:ipNetToPhysicalLastUpdated (0x03f95578) 837 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 838 ip-mib:ipNetToPhysicalType (0x24ade115) 839 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 840 ip-mib:ipNetToPhysicalState (0x09e640ef) 841 /ip-mib:IP-MIB/ip-mib:ipNetToPhysicalTable/ip-mib:ipNetToPhysicalEntry/ 842 ip-mib:ipNetToPhysicalRowStatus (0x3b5c1ab6) 844 The following example shows a request for the entire 845 ipNetToPhysicalTable. Since all the instances are requested, no 846 "keys" query parameter is needed. 848 REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable 850 REQ: GET example.com/mg/wt7w_ 852 RES: 2.05 Content (Content-Format: application/cbor) 853 { 854 0x30b7bc3f : { 855 0x1067f289 : [ 856 { 857 0x00d38564 : 1, 858 0x2745e222 : "ipv4", 859 0x387804eb : "10.0.0.51", 860 0x1a51514a : "00:00:10:01:23:45", 861 0x03f95578 : "2333943", 862 0x24ade115 : "static", 863 0x09e640ef : "reachable", 864 0x3b5c1ab6 : "active" 865 }, 866 { 867 0x00d38564 : 1, 868 0x2745e222 : "ipv4", 869 0x387804eb : "9.2.3.4", 870 0x1a51514a : "00:00:10:54:32:10", 871 0x03f95578 : "2329836", 872 0x24ade115 : "dynamic", 873 0x09e640ef : "unknown", 874 0x3b5c1ab6 : "active" 875 } 876 ] 877 } 878 } 880 4.1.3.4. The 'keys' Query Parameter 882 There is a mandatory query parameter that MUST be supported by 883 servers called "keys". This parameter is used to specify the key 884 values for an instance of an object identified by a YANG hash value. 885 Any key leaf values of the instance are passed in order. The first 886 key leaf in the top-most list is the first key encoded in the 'keys' 887 parameter. 889 The key leafs from top to bottom and left to right are encoded as a 890 comma-delimited list. If a key leaf value is missing then all values 891 for that key leaf are returned. 893 Example: In this example exactly 1 instance is requested from the 894 ipNetToPhysicalEntry (from a previous example). 896 REQ: GET example.com/mg/IP-MIB/ipNetToPhysicalTable/ 897 ipNetToPhysicalEntry?keys=1,ipv4,10.0.0.51 899 REQ: GET example.com/mg/QZ/KJ?keys=1,ipv4,10.0.0.51 901 RES: 2.05 Content (Content-Format: application/cbor) 902 { 903 0x1067f289 : [ 904 { 905 0x00d38564 : 1, 906 0x2745e222 : "ipv4", 907 0x387804eb : "10.0.0.51", 908 0x1a51514a : "00:00:10:01:23:45", 909 0x03f95578 : "2333943", 910 0x24ade115 : "static", 911 0x09e640ef : "reachable", 912 0x3b5c1ab6 : "active" 913 } 914 ] 915 } 917 An example illustrates the syntax of keys query parameter. In this 918 example the following YANG module is used: 920 module foo-mod { 921 namespace foo-mod-ns; 922 prefix foo; 924 list A { 925 key "key1 key2"; 926 leaf key1 { type string; } 927 leaf key2 { type int32; } 928 list B { 929 key "key3"; 930 leaf key3 { type string; } 931 leaf col1 { type uint32; } 932 } 933 } 934 } 936 The path identifier for the leaf "col1" is the following string: 938 /foo:A/foo:B/foo:col1 940 The YANG has value for this identifier string 0xa9abdcca and pq9zK). 942 The following string represents the RESTCONF target resource URI 943 expression for the "col1" leaf for the key values "top", 17, and 944 "group1": 946 /restconf/data/foo-mod:A=top,17/B=group1/col1 948 The following string represents the CoMI target resource identifier 949 for the same instance of the "col1" leaf: 951 /mg/pq9zK?keys=top,17,group1 953 4.2. Data Editing 955 CoMI allows datastore contents to be created, modified and deleted 956 using CoAP methods. 958 TODO: Data-editing is an optional feature. A server can choose to 959 only support YANG modules with read-only objects. 961 4.2.1. POST 963 Data resource instances are created with the POST method. The 964 RESTCONF POST operation is supported in CoMI, however it is only 965 allowed for creation of data resources. The same constraints apply 966 as defined in section 3.4.1 of [I-D.ietf-netconf-restconf]. The 967 operation is mapped to the POST method defined in section 5.8.2 of 968 [RFC7252]. 970 There are no query parameters for the POST method. 972 TODO: CoMI does not support user-ordered lists in YANG. 974 4.2.2. PUT 976 Data resource instances are created or replaced with the PUT method. 977 The PUT operation is supported in CoMI. A request to set the values 978 of instances of an object/leaf is sent with a confirmable CoAP PUT 979 message. The Response is piggybacked to the CoAP ACK message 980 corresponding with the Request. The same constraints apply as 981 defined in section 3.5 of [I-D.ietf-netconf-restconf]. The operation 982 is mapped to the PUT method defined in section 5.8.3 of [RFC7252]. 984 There are no query parameters for the PUT method. 986 TODO: Define where PATCH is needed. 988 4.2.3. DELETE 990 Data resource instances are deleted with the DELETE method. The 991 RESTCONF DELETE operation is supported in CoMI. The same constraints 992 apply as defined in section 3.7 of [I-D.ietf-netconf-restconf]. The 993 operation is mapped to the DELETE method defined in section 5.8.4 of 994 [RFC7252]. 996 There are no optional query parameters for the PUT method. 998 4.3. Notify functions 1000 Notification by the server to a selection of clients when the value 1001 of a management object changes is an essential function for the 1002 management of servers. CoMI allows to do a notifications on all 1003 variables in the datastore. 1005 Notification of object changes is supported with the CoAP Observe 1006 [I-D.ietf-core-observe] function. The client subscribes to the 1007 object by sending a GET request with an "Observe" option. 1009 REQ: GET example.com/mg/ietf-ip/ipv6/neighbor/ip 1010 (observe option register) 1012 RES: 2.05 Content (Content-Format: application/cbor) 1013 { 1014 "ip" : "fe80::200:f8ff:fe21:67cf" 1015 } 1017 The same example with the hash values instead of the string 1018 identifiers looks like: 1020 REQ: GET example.com/mg/guJB_ 1021 (observe option register) 1023 RES: 2.05 Content (Content-Format: application/cbor) 1024 { 1025 0x20b8907e : "fe80::200:f8ff:fe21:67cf" 1026 } 1027 In the example, the request returns a success response with the 1028 contents of the ip field. Consecutively the server will regularly 1029 notify the client when ip changes value. 1031 To check that the client is still alive, the server MUST send 1032 confirmable notifications once in a while. When the client does not 1033 confirm the notification from the server, the server will remove the 1034 client from the list of observers[I-D.ietf-core-observe]. 1036 In the registration request, the client MAY include a "Response-To- 1037 Uri-Host" and optionally "Response-To-Uri-Port" option as defined in 1038 [I-D.becker-core-coap-sms-gprs]. In this case, the observations 1039 SHOULD be sent to the address and port indicated in these options. 1040 This can be useful when the client wants the managed device to send 1041 the trap information to a multicast address. 1043 4.4. Module Discovery 1045 The presence and location of (path to) the management data are 1046 discovered by sending a GET request to "/.well-known/core" including 1047 a resource type (RT) parameter with the value "core.mg" [RFC6690]. 1048 Upon success, the return payload will contain the root resource of 1049 the management data. It is up to the implementation to choose its 1050 root resource, but it is recommended that the value "/mg" is used, 1051 where possible. The example below shows the discovery of the 1052 presence and location of management data. 1054 REQ: GET /.well-known/core?rt=core.mg 1056 RES: 2.05 Content ; rt="core.mg" 1058 Management objects MAY be discovered with the standard CoAP resource 1059 discovery. The implementation can add the hash values of the object 1060 identifiers to /.well-known/core with rt="core.mg.data". The 1061 available objects identified by the hash values can be discovered by 1062 sending a GET request to "/.well-known/core" including a resource 1063 type (RT) parameter with the value "core.mg.data". Upon success, the 1064 return payload will contain the registered hash values and their 1065 location. The example below shows the discovery of the presence and 1066 location of management data. 1068 REQ: GET /.well-known/core?rt=core.mg.data 1070 RES: 2.05 Content ; rt="core.mg.data", 1071 ; rt="core.mg.data"; obs 1073 In the example the "obs" attribute indicates that the object /mg/ 1074 CF_fA is observed. 1076 Lists of hash values may become prohibitively long. It is 1077 discouraged to provide long lists of objects on discovery. 1078 Therefore, it is recommended that details about management objects 1079 are discovered following the RESTCONF protocol. The YANG module 1080 information is stored in the "ietf-yang-library" module 1081 [I-D.ietf-netconf-restconf]. The resource "/mg/mod.uri" is used to 1082 retrieve the location of the YANG module library. 1084 Since many constrained servers within a deployment are likely to be 1085 similar, the module list can be stored locally on each server, or 1086 remotely on a different server. 1088 Local in example.com server: 1090 REQ: GET example.com/mg/mod.uri 1092 RES: 2.05 Content (Content-Format: application/cbor) 1093 { 1094 "mod.uri" : "example.com/mg/modules" 1095 } 1097 Remote in example-remote-server: 1099 REQ: GET example.com/mg/mod.uri 1101 RES: 2.05 Content (Content-Format: application/cbor) 1102 { 1103 "moduri" : "example-remote-server.com/mg/group17/modules" 1104 } 1106 Within the YANG module library all information about the module is 1107 stored such as: module identifier, identifier hierarchy, grouping, 1108 features and revision numbers. 1110 The hash identifier is obtained as specified in Section 5.1. When a 1111 collision occurred in the name space of the target server, a rehash 1112 is executed. 1114 4.5. Error Return Codes 1116 The RESTCONF return status codes defined in section 6 of the RESTCONF 1117 draft are used in CoMI error responses, except they are converted to 1118 CoAP error codes. 1120 TODO: complete RESTCONF to CoAP error code mappings 1121 +-------------------------------+------------------+ 1122 | RESTCONF Status Line | CoAP Status Code | 1123 +-------------------------------+------------------+ 1124 | 100 Continue | none? | 1125 | | | 1126 | 200 OK | 2.05 | 1127 | | | 1128 | 201 Created | 2.01 | 1129 | | | 1130 | 202 Accepted | none? | 1131 | | | 1132 | 204 No Content | ? | 1133 | | | 1134 | 304 Not Modified | 2.03 | 1135 | | | 1136 | 400 Bad Request | 4.00 | 1137 | | | 1138 | 403 Forbidden | 4.03 | 1139 | | | 1140 | 404 Not Found | 4.04 | 1141 | | | 1142 | 405 Method Not Allowed | 4.05 | 1143 | | | 1144 | 409 Conflict | none? | 1145 | | | 1146 | 412 Precondition Failed | 4.12 | 1147 | | | 1148 | 413 Request Entity Too Large | 4.13 | 1149 | | | 1150 | 414 Request-URI Too Large | 4.00 | 1151 | | | 1152 | 415 Unsupported Media Type | 4.15 | 1153 | | | 1154 | 500 Internal Server Error | 5.00 | 1155 | | | 1156 | 501 Not Implemented | 5.01 | 1157 | | | 1158 | 503 Service Unavailable | 5.03 | 1159 +-------------------------------+------------------+ 1161 5. Mapping YANG to CoMI payload 1163 A mapping for the encoding of YANG data in CBOR is necessary for the 1164 efficient transport of management data in the CoAP payload. Since 1165 object names may be rather long and may occur repeatedly, CoMI allows 1166 for association of a given object path identifier string value with 1167 an integer, called a "YANG hash". 1169 5.1. YANG Hash Generation 1171 The association between string value and string number is done 1172 through a hash algorithm. The 30 least significant bits of the 1173 "murmur3" 32-bit hash algorithm are used. This hash algorithm is 1174 described online at http://en.wikipedia.org/wiki/MurmurHash. 1175 Implementation are available online, including at 1176 https://code.google.com/p/smhasher/wiki/MurmurHash. When converting 1177 4 input bytes to a 32-bit integer in the hash algorithm, the Little- 1178 Endian convention MUST be used. 1180 The hash is generated for the string representing the object path 1181 identifier. A canonical representation of the path identifier is 1182 used. 1184 Prefix values are used on every node. 1186 The prefix values defined in the YANG module containing the data 1187 object are used for the path expression. For external modules, 1188 this is the value of the 'prefix' sub-statement in the 'import' 1189 statement for each external module. 1191 Path expressions for objects which augment data nodes in external 1192 modules are calculated in the augmenting module, using the prefix 1193 values in the augmenting module. 1195 Choice and case node names are not included in the path 1196 expression. Only 'container', 'list', 'leaf', 'leaf-list', and 1197 'anyxml' nodes are listed in the path expression. 1199 The "murmur3_32" hash function is executed for the entire path 1200 string. The value '42' is used as the seed for the hash function. 1201 The YANG hash is subsequently calculated by taking the 30 least 1202 significant bits. 1204 The resulting 30-bit number is used by the server, unless the value 1205 is already being used for a different object by the server. In this 1206 case, the re-hash procedure in the following section is executed. 1208 5.2. Re-Hash Procedure 1210 A hash collision occurs if two different path identifier strings have 1211 the same hash value. If the server has over 38,000 objects in its 1212 YANG modules, then the probability of a collision is fairly high. If 1213 a hash collision occurs on the server, then the object that is 1214 causing the conflict has to be altered, such that the new hash value 1215 does not conflict with any value already in use by the server. 1217 In most cases, the hash function is expected to produce unique values 1218 for all the objects supported by a constrained device. Given a known 1219 set of YANG modules, both server and client can calculate the YANG 1220 hashes independently, and offline. 1222 Even though collisions are expected to happen rather rarely, they 1223 needs to be considered. Collisions can be detected before 1224 deployment, if the vendor knows which modules are supported by the 1225 server, and hence all YANG hashes can be calculated. Collisions are 1226 only an issue when they occur at the same server. The client needs 1227 to discover any re-hash mappings on a per server basis. 1229 If the server needs to re-hash any object identifiers, then it MUST 1230 create a "rehash-map" entry for the altered identifier, as described 1231 in the following YANG module. 1233 5.3. ietf-yang-hash YANG Module 1235 The "ietf-yang-hash" YANG module is used by the server to report any 1236 objects that have been mapped to produce a new hash value that does 1237 not conflict with any other YANG hash values used by the server. 1239 YANG tree diagram for "ietf-yang-hash" module: 1241 +--ro yang-hash 1242 +--ro rehash* [hash] 1243 +--ro hash uint32 1244 +--ro path? string 1245 +--ro append? string 1247 module ietf-yang-hash { 1248 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-hash"; 1249 prefix "yh"; 1251 organization 1252 "IETF CORE (Constrained RESTful Environments) Working Group"; 1254 contact 1255 "WG Web: 1256 WG List: 1258 WG Chair: Carsten Bormann 1259 1261 WG Chair: Andrew McGregor 1262 1264 Editor: Peter van der Stok 1265 1267 Editor: Bert Greevenbosch 1268 1270 Editor: Andy Bierman 1271 1273 Editor: Juergen Schoenwaelder 1274 1276 Editor: Anuj Sehgal 1277 "; 1279 description 1280 "This module contains re-hash information for the CoMI protocol. 1282 Copyright (c) 2014 IETF Trust and the persons identified as 1283 authors of the code. All rights reserved. 1285 Redistribution and use in source and binary forms, with or 1286 without modification, is permitted pursuant to, and subject 1287 to the license terms contained in, the Simplified BSD License 1288 set forth in Section 4.c of the IETF Trust's Legal Provisions 1289 Relating to IETF Documents 1290 (http://trustee.ietf.org/license-info). 1292 This version of this YANG module is part of RFC XXXX; see 1293 the RFC itself for full legal notices."; 1295 // RFC Ed.: replace XXXX with actual RFC number and remove this 1296 // note. 1298 // RFC Ed.: remove this note 1299 // Note: extracted from draft-vanderstok-core-comi-05.txt 1301 // RFC Ed.: update the date below with the date of RFC publication 1302 // and remove this note. 1303 revision 2014-10-27 { 1304 description 1305 "Initial revision."; 1306 reference 1307 "RFC XXXX: CoMI Protocol."; 1308 } 1309 container yang-hash { 1310 config false; 1311 description 1312 "Contains information on the YANG Hash values used by 1313 the server."; 1315 list rehash { 1316 key hash; 1317 description 1318 "Each entry describes an re-hash mapping in use by 1319 the server."; 1321 leaf hash { 1322 type uint32; 1323 description "The hash value that has a collision"; 1324 } 1325 leaf path { 1326 type string; 1327 description 1328 "The YANG identifier path expression that caused the 1329 collision and is being remapped"; 1330 } 1331 leaf append { 1332 type string; 1333 description 1334 "The string that the server appended to the path 1335 expression contained in the 'path' leaf to produce 1336 a new path expression and therefore new hash value. 1337 The YANG hash value for the new string (identified 1338 by 'path' + 'append') is used to identify the 1339 'path' object."; 1340 } 1341 } 1342 } 1344 } 1346 5.3.1. YANG Re-Hash Example 1348 In this example the server has an object that is already registered 1349 when the "/foo:A/foo:B/foo:col1" object is processed. This object 1350 path string hashes to value 0x29abdcca. The server has appended the 1351 string "_" to the path to produce a new hash (0x2a7a2044) which does 1352 not collide with any other objects. 1354 The server would return the following information if the client 1355 retrieved the "/mg/yang-hash" resource. 1357 REQ: GET example.com/mg/yang-hash 1359 RES: 2.05 Content (Content-Format: application/cbor) 1360 { 1361 "ietf-yang-hash:yang-hash" : { 1362 "rehash" : [ 1363 { 1364 "hash" : 712646724, 1365 "path" :"/foo:A/foo:B/foo:col1", 1366 "append" : "_" 1367 } 1368 ] 1369 } 1370 } 1372 5.4. YANG Hash in URL 1374 When a URL contains a YANG hash, it is encoded using base64url "URL 1375 and Filename safe" encoding as specified in [RFC4648]. 1377 The hash H is represented as a 30-bit integer, divided into five 1378 6-bit integers as follows: 1380 B1 = (H & 0x3f000000) >> 24 1381 B2 = (H & 0xfc0000) >> 18 1382 B3 = (H & 0x03f000) >> 12 1383 B4 = (H & 0x000fc0) >> 6 1384 B5 = H & 0x00003f 1386 Subsequently, each 6-bit integer Bx is translated into a character Cx 1387 using Table 2 from [RFC4648], and a string is formed by concatenating 1388 the characters in the order C1, C2, C3, C4, C5. 1390 For example, the YANG hash 0x29abdcca is encoded as "pq9zK". 1392 6. Mapping YANG to CBOR 1394 6.1. High level encoding 1396 When encoding YANG variables in CBOR, the CBOR encodings entry is a 1397 map. The key is the YANG hash of entry variable, whereas the value 1398 contains its value. 1400 For encoding of the variable values, a CBOR datatype is used. 1401 Section 6.2 provides the mapping between YANG datatypes and CBOR 1402 datatypes. 1404 6.2. Conversion from YANG datatypes to CBOR datatypes 1406 Table 1 defines the mapping between YANG datatypes and CBOR 1407 datatypes. 1409 Elements of types not in this table, and of which the type cannot be 1410 inferred from a type in this table, are ignored in the CBOR encoding 1411 by default. Examples include the "description" and "key" elements. 1412 However, conversion rules for some elements to CBOR MAY be defined 1413 elsewhere. 1415 +--------------+------------------+---------------------------------+ 1416 | YANG type | CBOR type | Specification | 1417 +--------------+------------------+---------------------------------+ 1418 | int8, int16, | unsigned int | The CBOR integer type depends | 1419 | int32, | (major type 0) | on the sign of the actual | 1420 | int64, | or negative int | value. | 1421 | uint16, | (mayor type 1) | | 1422 | uint32, | | | 1423 | uint64, | | | 1424 | decimal64 | | | 1425 | | | | 1426 | boolean | either "true" | | 1427 | | (major type 7, | | 1428 | | simple value 21) | | 1429 | | or "false" | | 1430 | | (major type 7, | | 1431 | | simple value 20) | | 1432 | | | | 1433 | string | text string | | 1434 | | (major type 3) | | 1435 | | | | 1436 | enumeration | unsigned int | | 1437 | | (major type 0) | | 1438 | | | | 1439 | bits | array of text | Each text string contains the | 1440 | | strings | name of a bit value that is | 1441 | | | set. | 1442 | | | | 1443 | binary | byte string | | 1444 | | (major type 2) | | 1445 | | | | 1446 | empty | null (major type | TBD: This MAY not be applicable | 1447 | | 7, simple value | to true MIBs, as SNMP may not | 1448 | | 22) | support empty variables... | 1449 | | | | 1450 | union | | Similar ot the JSON | 1451 | | | transcription from | 1452 | | | [I-D.ietf-netmod-yang-json], | 1453 | | | the elements in a union MUST be | 1454 | | | determined using the procedure | 1455 | | | specified in section 9.12 of | 1456 | | | [RFC6020]. | 1457 | | | | 1458 | leaf-list | array (major | The array is encapsulated in | 1459 | | type 4) | the map associated with the | 1460 | | | YANG variable. | 1461 | | | | 1462 | list | array (major | Each array element contains a | 1463 | | type 4) of maps | map of associated YANG hash - | 1464 | | (major type 5) | value pairs. | 1465 | | | | 1466 | container | map (major type | The map contains YANG hash - | 1467 | | 5) | value pairs corresponding to | 1468 | | | the elements in the container. | 1469 | | | | 1470 | smiv2:oid | array of | Each integer contains an | 1471 | | integers | element of the OID, the first | 1472 | | | integer in the array | 1473 | | | corresponds to the most left | 1474 | | | element in the OID. | 1475 +--------------+------------------+---------------------------------+ 1477 Table 1: Conversion of YANG datatypes to CBOR 1479 7. Error Handling 1481 In case a request is received which cannot be processed properly, the 1482 managed entity MUST return an error message. This error message MUST 1483 contain a CoAP 4.xx or 5.xx response code, and SHOULD include 1484 additional information in the payload. 1486 Such an error message payload is encoded in CBOR, using the following 1487 structure: 1489 TODO: Adapt RESTCONF data structure for use in CoMI. Need 1490 to select the most important fields like . 1492 errorMsg : ErrorMsg; 1494 *ErrorMsg { 1495 errorCode : uint; 1496 ?errorText : tstr; 1497 } 1498 The variable "errorCode" has one of the values from the table below, 1499 and the OPTIONAL "errorText" field contains a human readable 1500 explanation of the error. 1502 +----------------+----------------+---------------------------------+ 1503 | CoMI Error | CoAP Error | Description | 1504 | Code | Code | | 1505 +----------------+----------------+---------------------------------+ 1506 | 0 | 4.00 | General error | 1507 | | | | 1508 | 1 | 4.00 | Malformed CBOR data | 1509 | | | | 1510 | 2 | 4.00 | Incorrect CBOR datatype | 1511 | | | | 1512 | 3 | 4.00 | Unknown MIB variable | 1513 | | | | 1514 | 4 | 4.00 | Unknown conversion table | 1515 | | | | 1516 | 5 | 4.05 | Attempt to write read-only | 1517 | | | variable | 1518 | | | | 1519 | 0..2 | 5.01 | Access exceptions | 1520 | | | | 1521 | 0..18 | 5.00 | SMI error status | 1522 +----------------+----------------+---------------------------------+ 1524 The CoAP error code 5.01 is associated with the exceptions defined in 1525 [RFC3416] and CoAP error code 5.00 is associated with the error- 1526 status defined in [RFC3416]. 1528 8. Security Considerations 1530 For secure network management, it is important to restrict access to 1531 MIB variables only to authorised parties. This requires integrity 1532 protection of both requests and responses, and depending on the 1533 application encryption. 1535 CoMI re-uses the security mechanisms already available to CoAP as 1536 much as possible. This includes DTLS for protected access to 1537 resources, as well suitable authentication and authorisation 1538 mechanisms. 1540 Among the security decisions that need to be made are selecting 1541 security modes and encryption mechanisms (see [RFC7252]). This 1542 requires a trade-off, as the NoKey mode gives no protection at all, 1543 but is easy to implement, whereas the X.509 mode is quite secure, but 1544 may be too complex for constrained devices. 1546 In addition, mechanisms for authentication and authorisation may need 1547 to be selected. 1549 CoMI avoids defining new security mechanisms as much as possible. 1550 However some adaptations may still be required, to cater for CoMI's 1551 specific requirements. 1553 9. IANA Considerations 1555 'rt="core.mg.data"' needs registration with IANA. 1557 'rt="core.mg.moduri"' needs registration with IANA. 1559 'rt="core.mg.yang-hash"' needs registration with IANA. 1561 Content types to be registered: 1563 o application/comi+cbor 1565 10. Acknowledgements 1567 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1568 transported under SNMP. Carsten Bormann has given feedback on the 1569 use of CBOR. The draft has benefited from comments (alphabetical 1570 order) by Dee Denteneer, Esko Dijk, Michael van Hartskamp, Zach 1571 Shelby, Michel Veillette, Michael Verschoor, and Thomas Watteyne. 1572 The CBOR encoding borrows extensively from Ladislav Lhotka's 1573 description on conversion from YANG to JSON. 1575 11. Changelog 1577 Changes from version 00 to version 01 1579 o Focus on MIB only 1581 o Introduced CBOR, JSON, removed BER 1583 o defined mappings from SMI to xx 1585 o Introduced the concept of addressable table rows 1587 Changes from version 01 to version 02 1589 o Focus on CBOR, used JSON for examples, removed XML and EXI 1591 o added uri-query attributes mod and con to specify modules and 1592 contexts 1594 o Definition of CBOR string conversion tables for data reduction 1596 o use of Block for multiple fragments 1598 o Error returns generalized 1600 o SMI - YANG - CBOR conversion 1602 Changes from version 02 to version 03 1604 o Added security considerations 1606 Changes from version 03 to version 04 1608 o Added design considerations section 1610 o Extended comparison of management protocols in introduction 1612 o Added automatic generation of CBOR tables 1614 o Moved lowpan table to Appendix 1616 Changes from version 04 to version 05 1618 o Merged SNMP access with RESTCONF access to management objects in 1619 small devices 1621 o Added CoMI architecture section 1623 o Added RESTCONf NETMOD description 1625 o Rewrote section 5 with YANG examples 1627 o Added server and payload size appendix 1629 o Removed Appendix C for now. It will be replaced with a YANG 1630 example. 1632 Changes from version 04 to version 05 1634 o Extended examples with hash representation 1636 o Added keys query parameter text 1638 o Added select query parameter text 1640 o Better separation between specification and instance 1641 o Section on discovery updated 1643 o Text on rehashing introduced 1645 o Elaborated SMI MIB example 1647 o Yang libary use described 1649 o use of BigEndian/LittleEndian in Hash generation specified 1651 Changes from version 05 to version 06 1653 o Hash values in payload as hexadecimal and in URL in base64 numbers 1655 o Streamlined CoMI architecture text 1657 o Added select query parameter text 1659 o Data editing optional 1661 o Text on Notify added 1663 o Text on rehashing improved with example 1665 12. References 1667 12.1. Normative References 1669 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1670 Requirement Levels", BCP 14, RFC 2119, March 1997. 1672 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1673 Encodings", RFC 4648, October 2006. 1675 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1676 Network Configuration Protocol (NETCONF)", RFC 6020, 1677 October 2010. 1679 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1680 Representation (CBOR)", RFC 7049, October 2013. 1682 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1683 Interchange Format", RFC 7159, March 2014. 1685 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1686 Application Protocol (CoAP)", RFC 7252, June 2014. 1688 [I-D.becker-core-coap-sms-gprs] 1689 Becker, M., Li, K., Kuladinithi, K., and T. Poetsch, 1690 "Transport of CoAP over SMS", draft-becker-core-coap-sms- 1691 gprs-05 (work in progress), August 2014. 1693 [I-D.ietf-core-block] 1694 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 1695 draft-ietf-core-block-16 (work in progress), October 2014. 1697 [I-D.ietf-core-observe] 1698 Hartke, K., "Observing Resources in CoAP", draft-ietf- 1699 core-observe-16 (work in progress), December 2014. 1701 [I-D.ietf-netmod-yang-json] 1702 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1703 draft-ietf-netmod-yang-json-02 (work in progress), 1704 November 2014. 1706 [I-D.ietf-netconf-restconf] 1707 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1708 Protocol", draft-ietf-netconf-restconf-04 (work in 1709 progress), January 2015. 1711 12.2. Informative References 1713 [RFC1213] McCloghrie, K. and M. Rose, "Management Information Base 1714 for Network Management of TCP/IP-based internets:MIB-II", 1715 STD 17, RFC 1213, March 1991. 1717 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1718 Schoenwaelder, Ed., "Structure of Management Information 1719 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1721 [RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group 1722 MIB", RFC 2863, June 2000. 1724 [RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart, 1725 "Introduction and Applicability Statements for Internet- 1726 Standard Management Framework", RFC 3410, December 2002. 1728 [RFC3411] Harrington, D., Presuhn, R., and B. Wijnen, "An 1729 Architecture for Describing Simple Network Management 1730 Protocol (SNMP) Management Frameworks", STD 62, RFC 3411, 1731 December 2002. 1733 [RFC3414] Blumenthal, U. and B. Wijnen, "User-based Security Model 1734 (USM) for version 3 of the Simple Network Management 1735 Protocol (SNMPv3)", STD 62, RFC 3414, December 2002. 1737 [RFC3416] Presuhn, R., "Version 2 of the Protocol Operations for the 1738 Simple Network Management Protocol (SNMP)", STD 62, RFC 1739 3416, December 2002. 1741 [RFC3418] Presuhn, R., "Management Information Base (MIB) for the 1742 Simple Network Management Protocol (SNMP)", STD 62, RFC 1743 3418, December 2002. 1745 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1746 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1747 3986, January 2005. 1749 [RFC4088] Black, D., McCloghrie, K., and J. Schoenwaelder, "Uniform 1750 Resource Identifier (URI) Scheme for the Simple Network 1751 Management Protocol (SNMP)", RFC 4088, June 2005. 1753 [RFC4113] Fenner, B. and J. Flick, "Management Information Base for 1754 the User Datagram Protocol (UDP)", RFC 4113, June 2005. 1756 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1757 Architecture", RFC 4291, February 2006. 1759 [RFC4293] Routhier, S., "Management Information Base for the 1760 Internet Protocol (IP)", RFC 4293, April 2006. 1762 [RFC4944] Montenegro, G., Kushalnagar, N., Hui, J., and D. Culler, 1763 "Transmission of IPv6 Packets over IEEE 802.15.4 1764 Networks", RFC 4944, September 2007. 1766 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1767 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1768 6241, June 2011. 1770 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1771 Security Version 1.2", RFC 6347, January 2012. 1773 [RFC6643] Schoenwaelder, J., "Translation of Structure of Management 1774 Information Version 2 (SMIv2) MIB Modules to YANG 1775 Modules", RFC 6643, July 2012. 1777 [RFC6650] Falk, J. and M. Kucherawy, "Creation and Use of Email 1778 Feedback Reports: An Applicability Statement for the Abuse 1779 Reporting Format (ARF)", RFC 6650, June 2012. 1781 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1782 Format", RFC 6690, August 2012. 1784 [RFC6775] Shelby, Z., Chakrabarti, S., Nordmark, E., and C. Bormann, 1785 "Neighbor Discovery Optimization for IPv6 over Low-Power 1786 Wireless Personal Area Networks (6LoWPANs)", RFC 6775, 1787 November 2012. 1789 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1790 Management", RFC 7223, May 2014. 1792 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1793 Constrained-Node Networks", RFC 7228, May 2014. 1795 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1796 System Management", RFC 7317, August 2014. 1798 [RFC7388] Schoenwaelder, J., Sehgal, A., Tsou, T., and C. Zhou, 1799 "Definition of Managed Objects for IPv6 over Low-Power 1800 Wireless Personal Area Networks (6LoWPANs)", RFC 7388, 1801 October 2014. 1803 [RFC7390] Rahman, A. and E. Dijk, "Group Communication for the 1804 Constrained Application Protocol (CoAP)", RFC 7390, 1805 October 2014. 1807 [I-D.ietf-core-interfaces] 1808 Shelby, Z. and M. Vial, "CoRE Interfaces", draft-ietf- 1809 core-interfaces-02 (work in progress), November 2014. 1811 [I-D.ersue-constrained-mgmt] 1812 Ersue, M., Romascanu, D., and J. Schoenwaelder, 1813 "Management of Networks with Constrained Devices: Problem 1814 Statement, Use Cases and Requirements", draft-ersue- 1815 constrained-mgmt-03 (work in progress), February 2013. 1817 [I-D.ietf-lwig-coap] 1818 Kovatsch, M., Bergmann, O., Dijk, E., He, X., and C. 1819 Bormann, "CoAP Implementation Guidance", draft-ietf-lwig- 1820 coap-01 (work in progress), July 2014. 1822 [STD0001] "Official Internet Protocols Standard", Web 1823 http://www.rfc-editor.org/rfcxx00.html, . 1825 [XML] "Extensible Markup Language (XML)", Web 1826 http://www.w3.org/xml, . 1828 [JSON] "JavaScript Object Notation (JSON)", Web 1829 http://www.json.org, . 1831 [OMA] "OMA-TS-LightweightM2M-V1_0-20131210-C", Web 1832 http://technical.openmobilealliance.org/Technical/ 1833 current_releases.aspx, . 1835 [DTLS-size] 1836 Hummen, R., Shafagh, H., Raza, S., Voigt, T., and K. 1837 Wehrle, "Delegation-based Authentication and Authorization 1838 for the IP-based Internet of Things", Web 1839 http://www.vs.inf.ethz.ch/publ/papers/ 1840 mshafagh_secon14.pdf, . 1842 [dcaf] Bormann, C., Bergmann, O., and S. Gerdes, "Delegated 1843 Authenticated Authorization for Constrained Environments", 1844 Private Information , . 1846 [openwsn] Watteijne, T., "Coap size in Openwsn", Web 1847 http://builder.openwsn.org/, . 1849 [Erbium] Kovatsch, M., "Erbium Memory footprint for coap-18", 1850 Private Communication , . 1852 [management] 1853 Schoenwalder, J. and A. Sehgal, "Management of the 1854 Internet of Things", Web http://cnds.eecs.jacobs- 1855 university.de/slides/2013-im-iot-management.pdf, 2013. 1857 Appendix A. Payload and Server sizes 1859 This section provides information on code sizes and payload sizes for 1860 a set of management servers. Approximate code sizes are: 1862 +---------------+------------+-------+-------+----------------------+ 1863 | Code | processor | Text | Data | reference | 1864 +---------------+------------+-------+-------+----------------------+ 1865 | Observe agent | erbium | 800 | n/a | [Erbium] | 1866 | | | | | | 1867 | CoAP server | MSP430 | 1K | 6 | [openwsn] | 1868 | | | | | | 1869 | SNMP server | ATmega128 | 9K | 700 | [management] | 1870 | | | | | | 1871 | Secure SNMP | ATmega128 | 30K | 1.5K | [management] | 1872 | | | | | | 1873 | DTLS server | ATmega128 | 37K | 2K | [management] | 1874 | | | | | | 1875 | NETCONF | ATmega128 | 23K | 627 | [management] | 1876 | | | | | | 1877 | JSON parser | CC2538 | 4.6K | 8 | [dcaf] | 1878 | | | | | | 1879 | CBOR parser | CC2538 | 1.5K | 2.6K | [dcaf] | 1880 | | | | | | 1881 | DTLS server | ARM7 | 15K | 4 | [I-D.ietf-lwig-coap] | 1882 | | | | | | 1883 | DTLS server | MSP430 | 15K | 4 | [DTLS-size] | 1884 | | | | | | 1885 | Certificate | MSP430 | 23K | | [DTLS-size] | 1886 | | | | | | 1887 | Crypto | MSP430 | 2-8K | | [DTLS-size] | 1888 +---------------+------------+-------+-------+----------------------+ 1890 Thomas says that the size of the CoAP server is rather arbitrary, as 1891 its size depends mostly on the implementation of the underlying 1892 library modules and interfaces. 1894 Payload sizes are compared for the following request payloads, where 1895 each attribute value is null (N.B. these sizes are educated guesses, 1896 will be replaced with generated data). The identifier are assumed to 1897 be a string representation of the OID. Sizes for SysUpTime differ 1898 due to preambles of payload. "CBOR opt" stands for CBOR payload 1899 where the strings are replaced by table numbers. 1901 +-------------------------+-----------+------+------+----------+ 1902 | Request | BERR SNMP | JSON | CBOR | CBOR opt | 1903 +-------------------------+-----------+------+------+----------+ 1904 | IPnetTOMediaTable | 205 | 327 | ~327 | ~51 | 1905 | | | | | | 1906 | lowpanIfStatsTable | | 710 | 614 | 121 | 1907 | | | | | | 1908 | sysUpTime | 29 | 13 | ~13 | 20 | 1909 | | | | | | 1910 | RESTconf example | | | | | 1911 +-------------------------+-----------+------+------+----------+ 1913 Appendix B. Notational Convention for CBOR data 1915 To express CBOR structures [RFC7049], this document uses the 1916 following conventions: 1918 A declaration of a CBOR variable has the form: 1920 name : datatype; 1922 where "name" is the name of the variable, and "datatype" its CBOR 1923 datatype. 1925 The name of the variable has no encoding in the CBOR data. 1927 "datatype" can be a CBOR primitive such as: 1929 tstr: A text string (major type 3) 1931 uint: An unsigned integer (major type 0) 1933 map(x,y): A map (major type 5), where each first element of a pair 1934 is of datatype x, and each second element of datatype y. A '.' 1935 character for either x or y means that all datatypes for that 1936 element are valid. 1938 A datatype can also be a CBOR structure, in which case the variable's 1939 "datatype" field contains the name of the CBOR structure. Such CBOR 1940 structure is defined by a character sequence consisting of first its 1941 name, then a '{' character, then its subfields and finally a '}' 1942 character. 1944 A CBOR structure can be encapsulated in an array, in which case its 1945 name in its definition is preceded by a '*' character. Otherwise the 1946 structure is just a grouping of fields, but without actual encoding 1947 of such grouping. 1949 The name of an optional field is preceded by a '?' character. This 1950 means, that the field may be omitted if not required. 1952 Appendix C. comparison with LWM2M 1954 TODO: Anuj promised text 1956 Authors' Addresses 1958 Peter van der Stok 1959 consultant 1961 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 1962 Email: consultancy@vanderstok.org 1963 URI: www.vanderstok.org 1965 Bert Greevenbosch 1966 independent 1968 Email: ietf@bertgreevenbosch.nl 1970 Andy Bierman 1971 YumaWorks 1973 Email: andy@yumaworks.com 1975 Juergen Schoenwaelder 1976 Jacobs University 1977 Campus Ring 1 1978 Bremen 28759 1979 Germany 1981 Email: j.schoenwaelder@jacobs-university.de 1983 Anuj Sehgal 1984 Jacobs University 1985 Campus Ring 1 1986 Bremen 28759 1987 Germany 1989 Email: s.anuj@jacobs-university.de