CoAP Management Interface
draft-vanderstok-core-comi-05

Abstract

This document describes a network management interface for constrained devices, called CoMI. CoMI is an adaptation of the RESTCONF protocol for use in constrained devices and networks. It is designed to reduce the message sizes, server code size, and application development complexity. The Constrained Application Protocol (CoAP) is used to access management data resources specified in YANG, or SMIv2 converted to YANG. The payload of the CoMI message is encoded in Concise Binary Object Representation (CBOR).

Note

Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on April 30, 2015.

Copyright Notice

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Design considerations
• 1.2. Terminology
• 1.2.1. Tree Diagrams
• 2. CoMI Architecture
• 2.1. RESTCONF/YANG Architecture
• 3. CoAP Interface
• 4. MG Function Set
• 4.1. Data Retrieval
• 4.1.1. GET
• 4.1.2. Mapping of the 'select' Parameter
• 4.1.3. Retrieval Examples
• 4.2. Data Editing
• 4.2.1. POST
• 4.2.2. PUT
• 4.2.3. DELETE
• 4.3. Module Discovery
• 4.4. Error Return Codes
• 5. Mapping YANG to CoMI payload
• 5.1. YANG Hash Generation
• 5.2. Re-Hash Procedure
• 5.3. ietf-yang-hash YANG Module
• 5.3.1. YANG Re-Hash Example
• 5.4. The 'keys' Query Parameter
• 6. Mapping YANG to CBOR
• 6.1. Conversion from YANG datatypes to CBOR datatypes
• 7. Examples
• 8. Trap functions
• 9. Object access management
• 9.1. Notify destinations
• 10. Error Handling
• 11. Security Considerations
• 12. IANA Considerations
• 13. Acknowledgements
• 14. Changelog
• 15. References
• 15.1. Normative References
• 15.2. Informative References
• Appendix A. Payload and Server sizes
• Appendix B. Notational Convention for CBOR data
• Authors' Addresses

1. Introduction

The Constrained Application Protocol (CoAP) [RFC7252] is designed for Machine to Machine (M2M) applications such as smart energy and building control. Constrained devices need to be managed in an automatic fashion to handle the large quantities of devices that are expected in future installations. The messages between devices need to be as small and infrequent as possible. The implementation complexity and runtime resources need to be as small as possible.

The draft [I-D.ietf-netconf-restconf] describes a REST-like interface called RESTCONF, which uses HTTP methods to access structured data defined in YANG [RFC6020]. RESTCONF allows access to data resources contained in NETCONF [RFC6241] datastores. RESTCONF messages can be encoded in XML [XML] or JSON. The GET method is used to retrieve data resources and the POST, PUT, PATCH, and DELETE methods are used to create, replace, merge, and delete data resources.

A large amount of Management Information Base (MIB) [RFC3418] specifications already exist for monitoring purposes. This data can be accessed in RESTCONF if the server converts the SMIv2 modules to YANG, using the mapping rules defined in [RFC6643].

The CoRE Management Interface (CoMI) is intended to work on standardized data-sets in a stateless client-server fashion. The RESTCONF protocol is adapted and optimized for use in constrained environments, using CoAP instead of HTTP. Standardized data sets promote interoperability between small devices and applications from different manufacturers. Stateless communication is encouraged to keep communications simple and the amount of state information small in line with the design objectives of 6lowpan [RFC4944] [RFC6775], RPL [RFC6650], and CoAP [RFC7252].

RESTCONF uses the HTTP methods HEAD, OPTIONS, and PATCH, which are not available in CoAP. The use of TCP is also a problem in HTTP. The transport protocols available fo CoAP are much better suited to constrained networks.

CoMI is low resource oriented, uses CoAP, and only supports the methods GET, PUT, POST and DELETE. CoMI uses CBOR as the data format. To support small payloads, CoMI use an additional data identifier string to number conversion to minimise CBOR payloads. It is assumed that the managed device is the most constrained entity. The client might be more capable, however this is not necessarily the case.

Currently, small managed devices need to support at least two protocols: CoAP and SNMP. When the MIB can be accessed with the CoAP protocol, the SNMP protocol can be replaced with the CoAP protocol. Although the SNMP server size is not huge (see Appendix A), the code for the security aspects of SMIv3 is not negligible. Using CoAP to access secured management objects reduces the code complexity of the stack in the constrained device, and harmonizes applications development.

The objective of CoMI is to provide a CoAP based Function Set that reads and sets values of managed objects in devices to (1) initialize parameter values at start-up, (2) acquire statistics during operation, and (3) maintain nodes by adjusting parameter values during operation.

The payload of CoMI is encoded in CBOR [RFC7049] which is automatically generated from JSON [JSON]. CBOR has a binary format and hence has more coding efficiency than JSON.

The end goal of CoMI is to provide information exchange over the CoAP transport protocol in a uniform manner as a first step to the full management functionality as specified in [I-D.ersue-constrained-mgmt].

1.1. Design considerations

CoMI supports discovery of resources, accompanied by reading, writing and notification of resource values. CoMI supports MIB modules which have been translated from SMIv2 to YANG, using [RFC6643]. This mapping is read-only so writable SMIv2 objects need to be converted to YANG using an implementation-specific mapping.

CoMI uses a simple URI to access the management object resources. Complexity introduced by module name, context specification, or row selection, is expressed with uri-query attributes. The choice for uri-query attributes makes the URI structure less context dependent.

1.2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

Readers of this specification should be familiar with all the terms and concepts discussed in [RFC3410], [RFC3416], and [RFC2578].

The following terms are defined in the NETCONF protocol [RFC6241]:

• client
• configuration data
• datastore
• server

The following terms are defined in the YANG data modeling language [RFC6020]:

• container
• data node
• key
• key leaf
• leaf
• leaf-list
• list

The following terms are defined in RESTCONF protocol [I-D.ietf-netconf-restconf]:

• data resource
• datastore resource
• edit operation
• query parameter
• target resource
• unified datastore

The following terms are defined in this document:

YANG hash:

CoMI object identifier, which is a 32-bit numeric hash of the YANG object identifier string for the object. When a YANG hash value is printed in a request target URI, error-path or other string, then the lowercase hexadecimal representation is used. Leading zeros are used so the value uses 8 hex characters.

The following list contains the abbreviations used in this document.

XXXX:

TODO, and others to follow.

1.2.1. Tree Diagrams

A simplified graphical representation of the data model is used in this document. The meaning of the symbols in these diagrams is as follows:

• Brackets "[" and "]" enclose list keys.
• Abbreviations before data node names: "rw" means configuration data (read-write) and "ro" state data (read-only).
• Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list.
• Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":").
• Ellipsis ("...") stands for contents of subtrees that are not shown.

2. CoMI Architecture

This section describes the CoMI architecture to use CoAP for the reading and modifying of instrumentation variables used for the management of the instrumented node.

Client
+--------------------------------------------------------------+
| +--------------+    +--------------+                         |
| |    SMIv2     | >  |      YANG    |    >       COAP         |
| |description(2)|    |description(1)|          Request(3)     |
| ----------------    +--------------+    [         *          |
+-----------------------------*-----------[---------*----------+
                              *           [         *
                              *           [    +-----------+
                      mapping *   security[    |  Network  |
                              *      (8)  [    | packet(4) |
                              *           [    +-----------+
Server                        *           [         *
+-----------------------------*-----------[---------*----------+
|                             *           [         *          |
|                             *                 Retrieval,     |
|                             *               Modification(5)  |
|                            \*/                    *          |
| +-------------------------------------------------*--------+ |
| | +--------------+   +--------------+       +------------+ | |
| | | statistics   |   |configuration |       |Operational | | |
| | |    (6c)      |   |     (6b)     |       |  state(6a) | | |
| | +--------------+   +--------------+       +------------+ | |
| |                    variable store (6)           *        | |
| +-------------------------------------------------*--------+ |
|                                                   *          |
|                                                Variable      |
|                                            Instrumentation(7)|
+--------------------------------------------------------------+

Figure 1 is a high level representation of the main elements of the CoAP management architecture. A client sends requests as payload in packets over the network to a managed constrained node.

Objectives are:

• Equip a constrained node with a management server that provides information about the operational characteristics of the code running in the constrained node.
• The server provides this information in a variable store that contains values describing the performance characteristics and the code parameter values.
• The client receives the performance characteristics on a regular basis or on request.
• The client sets the parameter values in the server at bootstrap and intermittently when operational conditions change.
• The constrained network requires the payload to be as small as possible, and the constrained server memory requirements should be as small as possible.

The components in Figure 1 have the following high-level functionality.

• The instrumentation variables and parameters are described in the YANG or SMIv2 language.
• Descriptions in the SMIv2 language are translated into the YANG language.
• The YANG description serves as input to the writers of application and instrumentation code and the humans analysing the returned values (arrow from YANG description to Variable store). The description is used to check the correctness of the CoAP request and do the CBOR encoding.
• The CoAP request packs the request to read or set variables in the packet payload, which is transmitted over the network using IP. The CoAP request also receives values returned by the server in the payload of a packet. On arrival of the packet in the server, the payload is retrieved and decoded.
• Values are stored in the appropriate variables in the Variable store, and or values are returned from the Variable store into the payload of the packet. The Variable instrumentation code stores the values of the parameters into the appropriate places in the operational code. The variable instrumentation code reads current execution values from the operational code and stores them in the Variable store.
• The network communication must be secured.

For interoperability it is required that in addition to using the Internet Protocol for data transport:

• The names, type, and semantics of the instrumentation variables are standardized.
• The instrumentation variables are described in a standard language.
• The signature of the CoAP request in the server is standardized.
• The format of the packet payload is standardized.
• The notification from server to client is standardized.

The different numbered components of Figure 1 are discussed according to component number.

(1) YANG description:

A description contains a set of named and versioned modules. A module contains a hierarchy of named and typed resources. A resource is uniquely identified by a sequence of its name and the names of the enveloping resources following the hierarchy order.

(2) SMIv2 description:

A named module contains a set of variables and "conceptual tables". Named variables have simple types. Conceptual tables are composed of typed named columns. The variable name and module name identify the variable uniquely. There is an algorithm to translate SMIv2 specifications to YANG specifications.

(3) CoAP request:

The CoAP request needs a Universal Resource Identifier (URI) and the payload of the packet to send a request. The URI is composed of the schema, server, path and query and looks like coap://entry.example.com/<path>?<query>. Fragments are not supported. Allowed operations are PUT, GET, DELETE, and POST. New variables can be created with POST when they exist in the YANG specification. The Observe option can be used to return variable values regularly or on event occurrence (notification).

(3.1) CoAP <path>:

The path identifies the variable in the form "/mg/data/<identifier>.

(3.2) CoAP <query>:

The query parameter is used to specify additional (optional) aspects like the module name, the smi context, and others. The idea is to keep the path simple and put variations on variable specification in the query.

(3.3) CoAP discovery:

Discovery of the variables is done with standard CoAP resource discovery using /.well-known/core with ?rt=/core/mg.

(4) Network packet:

The payload contains the CBOR encoding of a single JSON object. This object corresponds to the converted RESTCONF message payload.

(5) Retrieval, modification:

The server needs to parse the CBOR encoded message and identify the corresponding entries in the Variable store. In addition, this component includes the code for CoAP Observe and block options.

(6) Variable store:

The store is composed of three parts: Operational state, Configuration datastore, and Statistics (see Section 2.1.

(7) Variable instrumentation:

This code depends on implementation of drivers and other node specific aspects.

(8) Security:

The server MUST prevent unauthorized users from reading or writing any data resources, however a standard access control model for CoMI should be specified in a separate document. DTLS is specified to secure CoAP communication.

2.1. RESTCONF/YANG Architecture

CoMI adapts the RESTCONF architecture so data exchange and implementation requirements are optimized for constrained devices.

The RESTCONF protocol uses a unified datastore to edit conceptual data structures supported by the server. The details of transaction preparation and non-volatile storage of the data are hidden from the RESTCONF client. CoMI also uses a unified datastore, to allow stateless editing of any configuration variables.

The child schema nodes of the unified datastore include all the top-level YANG data nodes in all the YANG modules supported by the server. The YANG data structures represent a hierarchy of data resources. The client discovers the list of YANG modules, and important conformance information such as the module revision dates, YANG features supported, and YANG deviations required. The individual data nodes are discovered indirectly by parsing the YANG modules supported by the server.

The YANG data definition statements contain a lot of information that can help automation tools, developers, and operators use the data model correctly and efficiently. The YANG definitions and server YANG module capability advertisements provide an "API contract" that allow a client to determine the detailed server management capabilities very quickly. CoMI allows access to the same data resources as a RESTCONF server, except the messages are optimized to reduce identifier and payload size.

RESTCONF uses a simple algorithmic mapping from YANG to URI syntax to identify the target resource of a retrieval or edit operation. A client can construct operations or scripts using a predictable syntax, based on the YANG data definitions. The target resource URI can reference a data resource instance, or the datastore itself (to retrieve the entire datastore or create a top-level data resource instance). CoMI uses a 32-bit YANG hash value (based on the YANG data node path identifier strings) to identify schema nodes in the target resource URI.

Any message payload data is relative to the node specified in the target resource URI in a request message. Each message is a well-formed XML instance document or JSON object, corresponding to the YANG schema definition specified by the target resource node. CoMI uses the hash value for the data node identifier in the message payloads, instead of the module-name prefixed identifier name like RESTCONF. CoMI message payloads are based on the JSON encoding of a RESTCONF message payload. The JSON identifier names are first converted to their 32-bit YANG hash values and then the payload is converted to CBOR.

3. CoAP Interface

In CoRE a group of links can constitute a Function Set. The format of the links is specified in [I-D.ietf-core-interfaces]. This note specifies a Management Function Set. CoMI end-points that implement the CoMI management protocol support at least one discoverable management resource of resource type (rt): core.mg, with path: /mg, where mg is short-hand for management.

The mg resource has three sub-resources accessible with the paths:

/mg/data:

YANG-based data with path "/mg/data" and using CBOR content encoding format. This path represents a datastore resource which contains YANG data resources as its descendant nodes. All identifiers referring to YANG data nodes within this path are encoded as YANG hash values.

/mg/moduri:

URI indicating the location of the server module information, with path "/mg/moduri" and CBOR content format. This YANG data is encoded with plain identifier strings, not YANG hash values.

/mg/yang-hash:

URI indicating the location of the server YANG hash information if any objects needed to be re-hashed by the server. It has path "/mg/yang-hash" and is encoded in CBOR format. The "ietf-yang-hash" module in Section 5.3 is used to define the syntax and semantics of this data structure. This YANG data is encoded with plain identifier strings, not YANG hash values. The server will only have this resource if there are any objects that needed to be re-hashed due to a hash collision.

The "/mg/data" resource provides access to the YANG data resources as described in Section 4. The "/mg/moduri" resource provides access to a URI that can be used to retrieve an instance of the "ietf-yang-library" module, defined in the RESTCONF draft. This module lists the name, revision, and conformance information for each YANG module, which a client needs to determine the YANG data model objects that are supported by a server. This URI can be reference a local data resource within the server, or reference a remote data resource, such as a shared file server. The data resource identifiers are YANG hash values, as described in Section 5.1.

The profile of the management function set, with IF=core.mg, is shown in the table below, following the guidelines of [I-D.ietf-core-interfaces]:

4. MG Function Set

The MG Function Set provides a CoAP interface to perform a subset of the functions provided by RESTCONF.

A subset of the operations defined in RESTCONF are used in CoMI:

4.1. Data Retrieval

4.1.1. GET

Data resources are retrieved by the client with the GET method. The RESTCONF GET operation is supported in CoMI. The same constraints apply as defined in section 3.3 of [I-D.ietf-netconf-restconf]. The operation is mapped to the GET method defined in section 5.8.1 of [RFC7252].

It is possible that the size of the payload is too large to fit in a single message. In the case that management data is bigger than the maximum supported payload size, the Block mechanism from [I-D.ietf-core-block] is used. Notice that the Block mechanism splits the data at fixed positions, such that individual data fields may become fragmented. Therefore, assembly of multiple blocks may be required to process the complete data field.

There are optional query parameters for the GET method. A CoMI server MAY implement these query parameters in order to allow common data retrieval filtering functionality.

4.1.2. Mapping of the 'select' Parameter

TODO: discuss how only a limited subset of the select parameter is used, and how the node names are changed to YANG hashes.

4.1.3. Retrieval Examples

The examples in this section use a JSON payload with one or more entries describing the pair (objectID, value). CoMI transports the CBOR format to transport the equivalent contents. The CBOR syntax of the payloads is specified in Section 5.

4.1.3.1. Single object values

A request to read the value of a management object or the leaf of an object is sent with a confirmable CoAP GET message. A single object is specified in the URI path prefixed with /mg/data.

A request to set the value of an object/leaf is sent with a confirmable CoAP PUT message. The Response is piggybacked to the CoAP ACK message corresponding with the Request.

Using for example the clock container from [RFC7317], a request is sent to retrieve the value of clock/current-datetime specified in module system-state. The answer to the request returns a (ObjectID, value) pair.

In all examples: (1) the payload is expressed in JSON, although the operational payload is specified to be in CBOR, and (2) the path is expressed in readable names although the transported path is expressed in numbers.

REQ: GET example.com/mg/data/system-state/clock/current-datetime

RES: 2.05 Content (Content-Format: application/cbor)
{
    "current-datetime" : "2014-10-26T12:16:31Z"
}

TODO: convert the example above so it uses YANG hash values instead of the string "current-datetime". Convert the target resource URI string "system-state/clock/current-datetime" to a YANG hash value.

The specified object can be an entire object. Accordingly, the returned payload is composed of all the leaves associated with the object. Each leaf is returned as a (YANG hash, value) pair. For example, the GET of the clock object, sent by the client, results in the following returned payload sent by the managed entity:

REQ: GET example.com/mg/data/system-state/clock
   (Content-Format: application/cbor)

RES: 2.05 Content (Content-Format: application/cbor)
{
   "clock" : {
      "current-datetime" : "2014-10-26T12:16:51Z",
      "boot-datetime" : "2014-10-21T03:00:00Z"
      "timezone" : {
         "timezone-location" : "Europe/Stockholm",
         "timezone-utc-offset" : -60
      }
   }
}

TODO: convert the example above so it uses YANG hash values instead of the strings "clock", "current-datetime", "boot-datetime", "timezone", and "timezone-utc-offset". Convert the target resource URI string "system-state/clock" to a YANG hash value.

The specified object can be a list. Accordingly, the returned payload is composed of all the entries associated with the list. Each entry is returned as a (entry name, value) pair. For example, the GET of the ietf-ip/ipv6/neighbor list, sent by the client, results in the following returned payload sent by the managed entity:

REQ: GET example.com/mg/data/ietf-ip/ipv6/neighbor
   (Content-Format: application/cbor)


RES: 2.05 Content (Content-Format: application/cbor)
{
   "neighbor" : [
     {
	"ip" : "fe80::200:f8ff:fe21:67cf",
	"link-layer-address" : "00:00::10:01:23:45"
	},
     {
	"ip" : "fe80::200:f8ff:fe21:6708",
	"link-layer-address" : "00:00::10:54:32:10"
	},
     {
	"ip" : "fe80::200:f8ff:fe21:88ee",
	"link-layer-address" : "00:00::10:98:76:54"
	}
    ]
}

TODO: convert the example above so it uses YANG hash values instead of the strings "neighbor", "ip", and "link-layer-address". Convert the target resource URI string "ietf-ip/ipv6/neighbor" to a YANG hash value.

TODO: show examples using the "keys" parameter to select a specific instance of a list entry.

4.2. Data Editing

CoMI allows datastore contents to be created, modified and deleted using CoAP methods.

TODO: Should this be an optional feature? A server can choose to only support YANG modules with read-only objects. MIN-ACCESS conformance does not exist in YANG.

4.2.1. POST

Data resource instances are created with the POST method. The RESTCONF POST operation is supported in CoMI, however it is only allowed for creation of data resources. The same constraints apply as defined in section 3.4.1 of [I-D.ietf-netconf-restconf]. The operation is mapped to the POST method defined in section 5.8.2 of [RFC7252].

There are no query parameters for the POST method.

TODO: how to support user-ordered lists in YANG? This is done with the 'insert' and 'point' parameters in RESTCONF. In CoMI, a client will have to replace the all list or leaf-list entries (e.g. PUT parent container) to change the order or insert anywhere but last.

4.2.2. PUT

Data resource instances are created or replaced with the PUT method. The PUT operation is supported in CoMI. The same constraints apply as defined in section 3.5 of [I-D.ietf-netconf-restconf]. The operation is mapped to the PUT method defined in section 5.8.3 of [RFC7252].

There are no query parameters for the PUT method.

TODO: how to support user-ordered lists in YANG? Same issue as for POST.

4.2.3. DELETE

Data resource instances are deleted with the DELETE method. The RESTCONF DELETE operation is supported in CoMI. The same constraints apply as defined in section 3.7 of [I-D.ietf-netconf-restconf]. The operation is mapped to the DELETE method defined in section 5.8.4 of [RFC7252].

There are no optional query parameters for the PUT method.

4.3. Module Discovery

Management objects are discovered in a manner similar to the RESTCONF protocol, not with the standard CoAP resource discovery. Only the YANG module information needs to be retrieved by the client. The YANG modules contain all the data resource schema and naming information.

The "rt" attribute is used to filter resource queries as specified in [RFC6690].

The resource "/mg/moduri" is used to retrieve the location of the YANG module library information for the server. This data structure is defined in the "ietf-yang-library" module in the RESTCONF draft.

Since many constrained servers within a deployment are likely to be similar, the module list can be stored locally on each server, or remotely on a different server.

  Local:

  REQ: GET example.com/mg/moduri

  RES: 2.05 Content (Content-Format: application/cbor)
  {
    "moduri" : "example.com/mg/data/modules"
  }


  Remote:

  REQ: GET example.com/mg/moduri

  RES: 2.05 Content (Content-Format: application/cbor)
  {
    "moduri" : "example-remote-server.com/mg/data/group17/modules"
  }

TODO: Example:

4.4. Error Return Codes

The RESTCONF return status codes defined in section 6 of the RESTCONF draft are used in CoMI error responses, except they are converted to CoAP error codes.

TODO: complete RESTCONF to CoAP error code mappings

5. Mapping YANG to CoMI payload

A mapping for the encoding of YANG data in CBOR is necessary for the efficient transport of management data in the CoAP payload. Since object names may be rather long and may occur repeatedly, CoMI allows for association of a given object path identifier string value with an integer, called a "YANG hash".

5.1. YANG Hash Generation

The association between string value and string number is done through a hash algorithm. The "murmur3" 32-bit hash algorithm is used. This hash algorithm is described online at http://en.wikipedia.org/wiki/MurmurHash. Implementation are available online, including at https://code.google.com/p/smhasher/wiki/MurmurHash.

The hash is generated for the string representing the object path identifier. A canonical representation of the path identifier is used.

• Prefix values are used on every node.
• The prefix values defined in the YANG module containing the data object are used for the path expression. For external modules, this is the value of the 'prefix' sub-statement in the 'import' statement for each external module.
• Path expressions for objects which augment data nodes in external modules are calculated in the augmenting module, using the prefix values in the augmenting module.
• Choice and case node names are not included in the path expression. Only 'container', 'list', 'leaf', 'leaf-list', and 'anyxml' nodes are listed in the path expression.

The "murmur3_32" hash function is executed for the entire path string. The value '42' is used as the seed for the hash function.

The resulting 32-bit number is used by the server, unless the value is already being used for a different object by the server. In this case, the re-hash procedure in the following section is executed.

5.2. Re-Hash Procedure

A hash collision occurs if two different path identifier strings have the same hash value. If the server has over 77,000 objects in its YANG modules, then the probability of a collision is fairly high. If a hash collision occurs on the server, then the object that is causing the conflict has to be altered, such that the new hash value does not conflict with any value already in use by the server.

In most cases, the hash function is expected to produce unique values for all the objects supported by a constrained device. Given a known set of YANG modules, both server and client can calculate the YANG hashes independently, and offline.

Even though collisions are expected to happen rather rarely, they needs to be considered. Collisions can be detected before deployment, if the vendor knows which modules are supported by the server, and hence all YANG hashes can be calculated. Collisions are only an issue when they occur at the same server. The client needs to discover any re-hash mappings on a per server basis.

If the server needs to re-hash any object identifiers, then it MUST create a "rehash-map" entry for the altered identifier, as described in the following YANG module.

5.3. ietf-yang-hash YANG Module

The "ietf-yang-hash" YANG module is used by the server to report any objects that have been mapped to produce a new hash value that does not conflict with any other YANG hash values used by the server.

YANG tree diagram for "ietf-yang-hash" module:

   +--ro yang-hash
      +--ro rehash* [hash]
         +--ro hash      uint32
         +--ro path?     string
         +--ro append?   string

module ietf-yang-hash {
  namespace "urn:ietf:params:xml:ns:yang:ietf-yang-hash";
  prefix "yh";

  organization
    "IETF CORE (Constrained RESTful Environments) Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/core/>
     WG List:  <mailto:core@ietf.org>

     WG Chair: Carsten Bormann
               <mailto:cabo@tzi.org>

     WG Chair: Andrew McGregor
               <mailto:andrewmcgr@google.com>

     Editor:   Peter van der Stok
               <mailto:consultancy@vanderstok.org>

     Editor:   Bert Greevenbosch
               <mailto:andy@bert.greevenbosch@huawei.com>

     Editor:   Andy Bierman
               <mailto:andy@yumaworks.com>

     Editor:   Juergen Schoenwaelder
               <mailto:j.schoenwaelder@jacobs-university.de>

     Editor:   Anuj Sehgal
               <mailto:s.anuj@jacobs-university.de>";

  description
    "This module contains re-hash information for the CoMI protocol.

     Copyright (c) 2014 IETF Trust and the persons identified as
     authors of the code.  All rights reserved.

     Redistribution and use in source and binary forms, with or
     without modification, is permitted pursuant to, and subject
     to the license terms contained in, the Simplified BSD License
     set forth in Section 4.c of the IETF Trust's Legal Provisions
     Relating to IETF Documents
     (http://trustee.ietf.org/license-info).

     This version of this YANG module is part of RFC XXXX; see
     the RFC itself for full legal notices.";

  // RFC Ed.: replace XXXX with actual RFC number and remove this
  // note.

  // RFC Ed.: remove this note
  // Note: extracted from draft-vanderstok-core-comi-05.txt

  // RFC Ed.: update the date below with the date of RFC publication
  // and remove this note.
  revision 2014-10-27 {
    description
      "Initial revision.";
    reference
      "RFC XXXX: CoMI Protocol.";
  }

  container yang-hash {
    config false;
    description
      "Contains information on the YANG Hash values used by
       the server.";

    list rehash {
      key hash;
      description
        "Each entry describes an re-hash mapping in use by
         the server.";

      leaf hash {
        type uint32;
        description "The hash value that has a collision";
      }
      leaf path {
        type string;
        description
          "The YANG identifier path expression that caused the
           collision and is being remapped";
      }
      leaf append {
        type string;
        description
          "The string that the server appended to the path
           expression contained in the 'path' leaf to produce
           a new path expression and therefore new hash value.
           The YANG hash value for the new string (identified
           by 'path' + 'append') is used to identify the
           'path' object.";
      }
    }
  }

}

5.3.1. YANG Re-Hash Example

In this example the server has an object that is already registered when the "/foo:A/foo:B/foo:col1" object is processed. This object path string hashes to value "a9abdcca". The server has appended the string "_" to the path to produce a new hash ("ea7a2044") which does not collide with any other objects.

The server would return the following information if the client retrieved the "/mg/yang-hash" resource.

REQ: GET example.com/mg/yang-hash

RES: 2.05 Content (Content-Format: application/cbor)
{
   "ietf-yang-hash:yang-hash" : {
      "rehash" : [
         {
            "hash" : 3933872196,
            "path" :"/foo:A/foo:B/foo:col1",
            "append" : "_"
         }
      ]
   }
}

5.4. The 'keys' Query Parameter

There is a mandatory query parameter that MUST be supported by servers called "keys". This parameter is used to specify the key values for an instance of an object identified by a YANG hash value. Any key leaf values for the object are passed in order. The first key leaf in the top-most list is the first key encoded in the 'keys' parameter.

Example: In this example the following YANG module is used:

  module foo-mod {
    namespace foo-mod-ns;
    prefix foo;

    list A {
      key "key1 key2";
      leaf key1 { type string; }
      leaf key2 { type int32; }
      list B {
        key "key3";
        leaf key3 { type string; }
        leaf col1 { type uint32; }
      }
    }
  }

The path identifier for the leaf "col1" is the following string:

   /foo:A/foo:B/foo:col1

The YANG has value for this identifier string "2846612682" (hex "a9abdcca").

The following string represents the RESTCONF target resource URI expression for the "col1" leaf for the key values "top", 17, and "group1":

   /restconf/data/foo-mod:A=top,17/B=group1/col1

The following string represents the CoMI target resource identifier for the same instance of the "col1" leaf:

   /mg/data/a9abdcca?keys=top,17,group1

6. Mapping YANG to CBOR

6.1. Conversion from YANG datatypes to CBOR datatypes

Table 1 defines the mapping between YANG datatypes and CBOR datatypes.

Elements of types not in this table, and of which the type cannot be inferred from a type in this table, are ignored in the CBOR encoding by default. Examples include the "description" and "key" elements. However, conversion rules for some elements to CBOR MAY be defined elsewhere.

errorMsg     : ErrorMsg;

*ErrorMsg {
  errorCode  : uint;
  ?errorText : tstr;
}

   name : datatype;