core A. Bierman Internet-Draft YumaWorks, Inc. Intended status: Standards Track P. van der Stok Expires: February 17, 2017 consultant August 16, 2016 Numeric YANG Identifiers draft-bierman-core-yid-00 Abstract This document describes an encoding of YANG object identifiers using numeric values instead of string values. It combines several techniques to provide optimized serialization in protocol messages. 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 February 17, 2017. Copyright Notice Copyright (c) 2016 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 Bierman & van der Stok Expires February 17, 2017 [Page 1] Internet-Draft YANG IDs August 2016 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.1.1. Examples . . . . . . . . . . . . . . . . . . . . . . 4 1.1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 4 1.2. Design Objectives . . . . . . . . . . . . . . . . . . . . 5 1.3. Solution Approach . . . . . . . . . . . . . . . . . . . . 5 2. YANG Identifier Registry . . . . . . . . . . . . . . . . . . 6 2.1. YANG Identifier Registry Example . . . . . . . . . . . . 8 3. YANG Identifier . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. module-id . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2. local-id . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.1. YANG Hash Numbered local-id . . . . . . . . . . . . . 11 3.2.2. Manually Numbered local-id . . . . . . . . . . . . . 11 4. YANG Identifier Registry Format . . . . . . . . . . . . . . . 12 4.1. ietf-yid Module . . . . . . . . . . . . . . . . . . . . . 12 5. YANG Hash Generation . . . . . . . . . . . . . . . . . . . . 19 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 7.1. YANG Module Library Entry: ietf-yid . . . . . . . . . . . 21 7.2. YANG Module Names Parameter Addition: module-id . . . . . 21 7.3. YANG Identifier Registry . . . . . . . . . . . . . . . . 22 7.3.1. Registry Maintenance . . . . . . . . . . . . . . . . 22 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 23 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 9.1. Normative References . . . . . . . . . . . . . . . . . . 23 9.2. Informative References . . . . . . . . . . . . . . . . . 23 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 24 Appendix B. YANG Identifier Examples . . . . . . . . . . . . . . 25 B.1. Hash Collision Repair Example . . . . . . . . . . . . . . 25 B.2. Manual Numbering Example . . . . . . . . . . . . . . . . 26 B.3. Augment Numbering Example . . . . . . . . . . . . . . . . 28 Appendix C. YANG Hash Examples . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 1. Introduction This document describes mechanisms for mapping YANG schema nodes to numeric values. Existing YANG-based protocol use path expression strings or element hierarchies that use element names to identify a particular YANG data node. These object identifiers can represent a significant percentage of protocol message payload content. Bierman & van der Stok Expires February 17, 2017 [Page 2] Internet-Draft YANG IDs August 2016 Constrained environments require efficient protocols and a numeric (binary) representation of YANG object identifiers can help reduce payload overhead in protocol messages. The effective use of YANG Identifiers requires three components: YANG Identifier Registry: A collection of numeric encoding rules for a specific set of YANG modules. Implementations need to use the contents of the registry to encode and decode object identifiers for data nodes in the associated modules. YANG Identifier: A hierarchical numeric YANG object identifier. This is intended to be a permanent object identifier, like the path expression or element names it is meant to replace. Message Serialization: A set of encoding rules within a particular serialization format. It is expected that CBOR will be used in constrained environments. This document does not define any message serialization techniques, or assume any specific protocols will be used. [TBD: add ref. to YANG to CBOR draft] This document replaces the YANG Hash draft [I-D.bierman-core-yang-hash]. The core concepts from that draft have been incorporated into this document. 1.1. 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 [RFC2578]. The following terms are defined in the NETCONF protocol [RFC6241]: client, configuration data, datastore, and server. The following terms are defined in the YANG data modelling language [RFC6020]: container, data node, key, key leaf, leaf, leaf-list, and list. The following terms are defined in RESTCONF protocol [I-D.ietf-netconf-restconf]: data resource, data-store resource, edit operation, query parameter, target resource, and unified data-store. The following terms are defined in this document: Bierman & van der Stok Expires February 17, 2017 [Page 3] Internet-Draft YANG IDs August 2016 YANG module schema tree: The conceptual tree of YANG objects comprised of all "rpc", "data-def" and "notification" statements within a particular revision of a module and all submodules included by this module. YANG Identifier: Numeric object identifier, which is a fixed-length numeric value that represents a particular schema node within a YANG module schema tree. The length and format of a YANG identifier are defined in the YANG Identifier Registry. Also called a "YID". YANG Identifier File: Also called a YID File. Contains a representation of the manual numeric path assignments for a YANG module. 1.1.1. Examples Some text within examples throughout the document are split into multiple lines for display purposes only. When a line ends with backslash ('\') as the last character, the line is wrapped for display purposes. It is to be considered to be joined to the next line by deleting the backslash, the following line break, and the leading whitespace of the next line. 1.1.2. Tree Diagrams A simplified graphical representation of the data model is used in the YANG modules specified 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. Bierman & van der Stok Expires February 17, 2017 [Page 4] Internet-Draft YANG IDs August 2016 1.2. Design Objectives This work is motivated by the need to minimize the size of object identifiers within protocol messages representing YANG data, encoded using binary format. The string encoding size of YANG identifier names can be very significant since designers are encouraged to provide long descriptive names to help human readability of the YANG module. It is therefore desirable to produce an object numbering algorithm that can be serialized efficiently in protocol messages with binary encoding formats such as CBOR. There are several design objectives for this work: Persistent Identifiers: It is important that once an identifier is assigned, that is it never changed in any future revisions in the module. Unique Identifiers: It is important that it is easy to ensure that all identifiers are unique within a server, and all servers that share the same set of YANG Identifier information. Low Complexity: The algorithms need to be simple to understand. Module updates need be simple, and only require the latest module and registry information. Dependency on YANG statement order or statement refactoring (e.g., move to groupings or submodules) must be avoided. Flexibility: The algorithms need be tuned for specific YANG modules. Manual (packed) numbering or hash-based numbering should be supported. No Inter-Module Dependencies: The algorithms must not allow identifiers from different YANG modules to conflict in any way. An identifier that is always scoped by an administratively assigned module identifier is required. No Hash Collisions: The algorithms must allow hash collisions to be avoided without modifying the associated YANG module. The numeric assignments for all objects within a module must be permanently unique (within that module scope). 1.3. Solution Approach This document describes a solution with four components: Bierman & van der Stok Expires February 17, 2017 [Page 5] Internet-Draft YANG IDs August 2016 YANG Identifier Registry: A YANG Identifier registry contains manually administered information for each YANG module. A minimal amount of information is needed for each module. A numeric module identifier needs to be assigned for each module in the registry. Most registry information is permanent. New entries can be added but naming information for old entries cannot be changed. Each module can be either be numbered automatically using YANG Hash, or manually using registry assignment. YANG Identifier Format: A YANG Identifier format is a structured binary identifier that allows a hierarchical YANG schema node to be represented as a single integer. The mapping is based on a murmur32 hash of the YANG object identifier string for each data definition node. The YANG path identifier is not allowed to change value after it is first assigned, so it can be safely and easily used as a permanent identifier. The value does not depend on module statement order or any field that is allowed to change in YANG in new module revisions. YANG Hash: The YANG Hash automatic numbering algorithm, defined in Section 5, is used to automatically assign the numeric identifiers to YANG data definition schema nodes. Hash values are scoped by the module identifier, so clashes between modules are not possible. If a hash collision does occur within the same module, then a registry entry is used to map the clashing data nodes to manually assigned identifiers. Hash collisions are not allowed in the registry. They are manually avoided without any need to modify the YANG module. Manual Numbering: A manual numbering mechanism and a YANG Identifier template to specify manually assigned local identifiers is needed. This allows compact numbering of objects and therefore the most efficient use of identifier numbering space. 2. YANG Identifier Registry A YANG Identifier registry is a data structure representing the numeric mapping information for a set of YANG modules. This is a global registry, meaning that all servers that use the same registry use the same numeric assignments. Ideally, all servers will use the same registry and there will be only one registry. It is expected that a server will use the official registry maintained by IANA, but other registries including locally administered registries are possible. Each registry is self- contained. Registries cannot be mixed or reference other registries. (This is a subject for future work). All YANG identifier values are Bierman & van der Stok Expires February 17, 2017 [Page 6] Internet-Draft YANG IDs August 2016 hierarchical, and scoped by the numeric identifier assigned in the registry for the module. The YANG Identifier registry supports automatically numbered objects within a module using YANG Hash. It also supports manually numbered objects within a module using object path to number mappings. If YANG Hash is used, then some of the numbering space for the module is reserved for manual assignments in case there are any hash collisions within the module. The size of the YANG identifiers, and the size of each field within the YANG identifier, are configured in the registry. The type of local identifier numbering is also configured, on a per-module basis. A server can only support one registry at a time, and it is expected to advertise which registry it is using via the management protocol in use. Each registry entry represents the numeric mapping information for one YANG module. Only one entry per module is maintained, for the latest revision. Registry information is never allowed to change. Information for new schema nodes can be added but information for existing schema nodes can never be altered. A YANG Identifier registry provides the following global parameters that apply to all modules: name: The administrative name for the registry revision: The current revision ID for the registry module-bits: The number of bits assigned to a module-id in a YID for the registry local-bits: The number of bits assigned to a local-id in a YID for the registry The registry also has a list of modules that support numeric YANG identifiers. Each module entry has the following parameters that apply to all revisions of the module: module-id: The numeric identifier assigned to the module in the registry name: The name of the YANG module. revision: The revision ID of the registry entry for the module Bierman & van der Stok Expires February 17, 2017 [Page 7] Internet-Draft YANG IDs August 2016 local-type: The type of local-id values used in a YANG Identifier for a schema node in the module. The values 'hash' and 'manual' are supported. If the 'local-type' is equal to 'manual' for a module entry, then the manually assigned numbers are provided in the module registry entry. This information can either be in-line in the registry entry or accessible via an external URI. The following information is provided for every YANG identifier in the module if the mapping parameters are local: local-id: The local identifier assigned to the schema node path: The YANG object identifier for the schema node The following information is provided for the entire module if the mapping parameters are remote: mapping-url: The URL for retrieval of a representation of the mapping information mapping-type: The media type for the 'mapping-url' 2.1. YANG Identifier Registry Example The following example shows a JSON representation of a "yid-registry" container. There are 3 modules (ietf-system, ietf-yang-library, and example-address). The registry uses 32 bit identifiers. 16 bits are used for local identifiers in each module. Bierman & van der Stok Expires February 17, 2017 [Page 8] Internet-Draft YANG IDs August 2016 { "yid-registry" : { "name" : "example-reg", "revision" : 0x7e00701, "module-bits" : 16, "local-bits" : 16, "module" : [ { "module-id" : 1, "name" : "ietf-system", "revision" : 0x7de0806, "local-type" : "hash" }, { "module-id" : 2, "name" : "ietf-yang-library", "revision" : 0x7e00615, "local-type" : "hash" }, { "module-id" : 3, "name" : "example-address", "revision" : 0x7de0508, "local-type" : "manual", "mapping-url" : "http://example.com/yang-ids-47.json", "mapping-type" : "application/json" } ] } } 3. YANG Identifier A YANG Identifier is constructed of 2 fields: a module identifier called "module-id" and a local identifier within the scope of the module, called "local-id". Bierman & van der Stok Expires February 17, 2017 [Page 9] Internet-Draft YANG IDs August 2016 YANG Identifier Formats: Form 1: YANG Hash Used +-------------+ +-------------+ | module-id | |R| local-id | +-------------+ +-------------+ Form 2: Manual Identifiers used +-------------+ +-------------+ | module-id | | local-id | +-------------+ +-------------+ The local identifier can either be a YANG Hash if the 'local-type' for the module registry entry is 'hash', or manual numbering if the 'local-type' is 'manual'. If YANG Hash is used, then one bit is reserved within the local-id as the "rehash bit". A YANG Identifier is derived from the 'module-id', 'local-bits', and 'local-id' fields, using the following formula: YID = (module-id * (2 ^^ local-bits)) + local-id 3.1. module-id The module-id field is a mandatory fixed-width number that must be unique within the registry. This number is manually assigned for each YANG module and is specified in the registry entry information for the YANG module. All other YANG identifier sub-fields are scoped by this module-id. It is not possible for YANG identifier values from different modules within a YANG Identifier registry to collide. Module identifiers are expected to be assigned by the registry maintainer, not by YANG module authors. It is critical that assignments are unique and stable. Registry maintenance procedures are discussed in the IANA Considerations section . Section 7. 3.2. local-id The local-id is a fixed width number defined in the YANG Identifier registry. Local identifiers can be one of two formats: YANG Hash or Manually Assigned. Bierman & van der Stok Expires February 17, 2017 [Page 10] Internet-Draft YANG IDs August 2016 3.2.1. YANG Hash Numbered local-id The automatic numbering of local identifier values is based on the YANG Hash for the path identifier for the schema node. An absolute path expression is used to identify the schema node. The YANG registry value of 'local-bits' determines the size of the YANG hash value. One bit is reserved as the "rehash" bit and "local- bits - 1" number of bits are used for the YANG hash value. A YANG Hash is calculated for the path expression for each schema node according to the procedure defined in Section 5. The lowest order bits are used. If any hash collisions occur, then a manual registry entry is needed for all but one of the colliding nodes. Since the value zero is reserved, a hash value of zero is considered a clash, and must be fixed using a manually assigned entry for the node. For example, if 8 bits were used for the 'local-bits' value, then the low order 7 bits are for hash values. The local-id values 1 - 127 would be allowed for hash values. The values 128 - 255 would be allowed for manually assigned rehash values. 3.2.2. Manually Numbered local-id A YANG Identifier data structure is used to represent the manually assigned schema node assignments for a YANG module. Each data node is explicitly assigned a numeric value that is unique within the YANG module where it is defined. Data nodes that augment external modules are defined in the augmenting module. Once an assignment is made it can never be changed. Only new assignments can be made in new revisions of a module registry entry. If local identifiers are used then the mapping between the YANG object identifier and numeric value MUST be provided via the registry. The format for 'local' entries is defined in the YANG module in Section 4.1. The format of registry entry files that use the 'remote' form of local-id identification is outside the scope of this document. The only requirements are that the fields "local-id" and "path" MUST be used in each entry to represent the YANG identifier to numeric mapping. The 'mapping-type' field is used to determine the syntax and semantics of the data represented by the 'mapping-url' resource. Bierman & van der Stok Expires February 17, 2017 [Page 11] Internet-Draft YANG IDs August 2016 4. YANG Identifier Registry Format A YANG Identifier Registry is a data structure that represents the module identifier encoding details for all modules in the registry. It is expected that the protocol using YANG Identifiers will indicate which YANG Identifier Registry it is using. The YANG Identifier Registry syntax and semantics are defined using a YANG module called "ietf-yid". This allows instances that conform to the registry structure to be serialized in different encoding formats, such as XML, JSON, or CBOR. The following YANG tree diagram represents the contents of the ietf- yid module: +--rw yid-registry! +--rw name string +--rw revision yid-revision-id +--rw module-bits uint8 +--rw local-bits uint8 +--rw module* [module-id] +--rw module-id yid-module-id +--rw name string +--rw revision yid-revision-id +--rw local-type enumeration +--rw (local-type-parms)? +--:(local) | +--rw mapping* [local-id] | +--rw local-id yid-local-id | +--rw path string +--:(remote) +--rw mapping-url? inet:uri +--rw mapping-type? string 4.1. ietf-yid Module module ietf-yid { namespace "urn:ietf:params:xml:ns:yang:ietf-yid"; prefix "yid"; import ietf-inet-types { prefix inet; } organization "IETF CORE (Constrained RESTfull Environments) Working Group"; contact "WG Web: Bierman & van der Stok Expires February 17, 2017 [Page 12] Internet-Draft YANG IDs August 2016 WG List: Author: Andy Bierman Author: Peter Van der Stock "; description "This module contains a conceptual YANG specification for a YANG Identifier Registry. Copyright (c) 2016 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-bierman-core-yid-00.txt // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2016-08-16 { description "Initial revision."; reference "RFC XXXX: Numeric YANG Identifiers."; } extension permanent-data { description "This extension can be used as a sub-statement in any data definition statement. It indicates that an instance of the associated data node is considered permanent. The value of an instance of a data node that contains this Bierman & van der Stok Expires February 17, 2017 [Page 13] Internet-Draft YANG IDs August 2016 extension MUST NOT change after it is assigned in a published version of an instance document. Note that a work-in-progress is not a published document. An RFC or IANA registry entry are examples of published document. There is no parameter value for this extension."; } typedef yid-revision-id { type uint32; description "Contains a numeric representation of the YANG Identifier registry version. This value SHOULD be constructed from a revision date string, using the following unsigned integer format: YYYYMMDD where: YYYY is a 16-bit integer representation of the year MM is a 8-bit integer representation of the month (1 - 12) DD is a 8-bit integer representation of the day in the month "; } typedef yid-module-id { type uint32 { range "1 .. max"; } description "Represents a YANG Identifier module-id field."; } typedef yid-local-id { type uint32 { range "1 .. max"; } description "Represents a YANG Identifier local-id field."; } grouping yid-registry { description "A grouping that representing the syntax and semantics of a YANG Identifier Registry."; container yid-registry { Bierman & van der Stok Expires February 17, 2017 [Page 14] Internet-Draft YANG IDs August 2016 presence "Instantiation of the YID registry is required."; description "Represents an YANG Identifier Registry"; leaf name { type string; mandatory true; description "An administrative name for the YANG identifier registry. This value SHOULD NOT change once assigned."; } leaf revision { type yid-revision-id; mandatory true; description "A revision identifier that is unique within all revisions of a YANG Identifier registry. This value MUST NOT change once assigned in the first revision of the YANG Identifier registry."; } leaf module-bits { yid:permanent-data; type uint8 { range "4 .. 32"; } mandatory true; description "The number of bits reserved for all module identifier values used within the registry. This value MUST NOT be changed after initial publication of the registry."; } leaf local-bits { yid:permanent-data; type uint8 { range "4 .. 32"; } mandatory true; description "The number of bits reserved for all local identifier values used within each module. The value 'module-bits + local-bits' represents Bierman & van der Stok Expires February 17, 2017 [Page 15] Internet-Draft YANG IDs August 2016 the total number of bits contained in all full-form YANG Identifier values used within the registry. This value MUST NOT be changed after initial publication of the registry."; } list module { key module-id; unique name; description "Represents one module entry in the registry. Only complete YANG module schema trees are represented in a YID registry entry. Sub-module or incomplete representations are not allowed."; uses yid-module-entry; } // list module } // container yid-registry } // grouping yid-registry grouping yid-module-entry { description "Represents one module entry in the registry. Only complete YANG module schema trees are represented in a YID registry entry. Sub-module or incomplete representations are not allowed."; leaf module-id { yid:permanent-data; type yid-module-id; description "The numeric identifier assigned to this module. This value MUST NOT be changed once the the module entry is created."; } leaf name { yid:permanent-data; type string; mandatory true; description Bierman & van der Stok Expires February 17, 2017 [Page 16] Internet-Draft YANG IDs August 2016 "The module name string. This exactly matches the value used in the associated YANG module. This value MUST NOT be changed once the the module entry is created."; } leaf revision { type yid-revision-id; mandatory true; description "A revision identifier that is unique within all revisions of the specified YANG module. This value MUST be updated to the new publication identifier value each time the YANG module is updated in the registry. Only one entry per module is maintained."; } leaf local-type { yid:permanent-data; type enumeration { enum hash { value 0; description "All local-id values where the most significant bit is set are YANG hash values. All local-id values where the most significant bit is not set are manually assigned YANG rehash values."; } enum manual { value 1; description "All local-id values are manually assigned identifiers."; } } mandatory true; description "The type of numbering used in local identifiers."; } choice local-type-parms { description "The manual local-id assignments can be done inline or contained in a remote YID file representation. This choice MUST be provided if any local identifier Bierman & van der Stok Expires February 17, 2017 [Page 17] Internet-Draft YANG IDs August 2016 mappings are used in the module. This includes all manually assigned values, and and rehash entries, if the associated 'local-type' value is 'hash'."; case local { description "Case arm for inline local-id manual assignments. The YID node list MAY be updated in the registry for each new revision of the associated YANG module."; list mapping { key "local-id"; unique path; description "Represents one manual schema node assignment."; leaf local-id { yid:permanent-data; type yid-local-id; description "The manually assigned local-id value for this entry. The actual allowed range for this list is controlled by the value of 'local-bits'. The number of entries allowed is (2 ^^ local-bits) - 2. The 'local-id' value zero is reserved and cannot be used."; } leaf path { yid:permanent-data; type string; mandatory true; description "The path expression representing this schema node. This value MUST NOT be changed in new revisions of an instance of a YID file."; } } } case remote { leaf mapping-url { type inet:uri; description "Case arm for remote specification of the manual assignments. The value is a URI for a representation of the YID File associated with the manually assigned numbers for a set of YANG schema nodes with a YANG module. This value MAY be updated in the registry for Bierman & van der Stok Expires February 17, 2017 [Page 18] Internet-Draft YANG IDs August 2016 each new revision of the associated YANG module."; } leaf mapping-type { type string; description "The value is a string identifying the media-type for the representation of mapping information identified by the associated 'mapping-url' value. This value MAY be updated in the registry for each new revision of the associated YANG module."; } } // case remote } // choice local-parm-types } // grouping yid-module-entry uses yid-registry; } 5. YANG Hash Generation Hash based local identifiers are defined in this section. The association between a path string value and numeric value is done through a hash algorithm. The 'N' least significant bits of the "murmur3" 32-bit hash algorithm are used. The value of 'N' is defined by the "local-bits" value in the YANG Identifier registry. This hash algorithm is described online at [murmur3]. Implementations are available online [murmur-imp]. When converting 4 input bytes to a 32-bit integer in the hash algorithm, the Little- Endian convention MUST be used. 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 YANG hash is subsequently calculated by taking the 'N - 1' least significant bits, where the value of N is defined by the "local-bits' value for the YANG Identifier registry. The resulting number is used by the server. If the value is already being used for a different object within the same YANG module, then the assignment is considered invalid, and MUST be resolved in the Bierman & van der Stok Expires February 17, 2017 [Page 19] Internet-Draft YANG IDs August 2016 registry entry. This is done by separating the clashing objects by manually assigning identifiers. The hash is generated for the string representing the object path identifier. A canonical representation of the path identifier is used. The module name is used to identify the namespace of the object node. The prefix cannot be used because it is allowed to change over time. The module name is never allowed to change. The module name MUST be present in the identifier for the first node in the object path identifier. If a child node in the object path identifier is from the same module namespace as its parent, then the module-name MUST NOT be used in the identifier. If a child node in the object path identifier is not from the same module namespace as its parent, then the module-name MUST be used in the identifier. 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 YANG Hash value is calculated for all data nodes in the module. The hash values are calculated, even if the server only implements a subset of these objects. This includes all "data-def" statements. Example: the following identifier is for the 'mtu' leaf in the ietf- interfaces module: /ietf-interfaces:interfaces/interface/mtu Example: the following identifier is for the 'ipv4' container in the ietf-ip module, which augments the 'interface' list in the ietf- interfaces module: /ietf-interfaces:interfaces/interface/ietf-ip:ipv4 Bierman & van der Stok Expires February 17, 2017 [Page 20] Internet-Draft YANG IDs August 2016 6. Security Considerations The exchange of names by numbers does not affect the security of the transmitted requests. 7. IANA Considerations This document requests the following actions be taken by IANA 1) add the "ietf-yid" YANG module to the YANG Module Names Registry 2) add a new "module-id" parameter to the YANG Module Names Registry 3) create a new YANG Identifiers Registry 7.1. YANG Module Library Entry: ietf-yid This document registers one URI as a namespace in the IETF XML registry [RFC3688]. Following the format in RFC 3688, the following registration is requested: URI: urn:ietf:params:xml:ns:yang:ietf-yid Registrant Contact: The CORE WG of the IETF. XML: N/A, the requested URI is an XML namespace. This document registers one YANG module in the YANG Module Names registry [RFC6020]: name: ietf-yid namespace: urn:ietf:params:xml:ns:yang:ietf-yid prefix: yid // RFC Ed.: replace XXXX with RFC number and remove this note reference: RFCXXXX 7.2. YANG Module Names Parameter Addition: module-id This document requests that a new parameter named "module-id" be added to the YANG Module Names Registry. This value is a 20 bit number, greater than zero, that represents an arbitrary integer assignment (by IANA) for the YANG module. This is only required for registry entries that represent YANG modules, not YANG sub-modules. The YANG typedef "yid-module-id" in the "ietf-yid" YANG module defines the syntax and semantics of a module-id value. Bierman & van der Stok Expires February 17, 2017 [Page 21] Internet-Draft YANG IDs August 2016 7.3. YANG Identifier Registry This document requests that a new YANG Identifier Registry be created and maintained by IANA. This registry is used to archive numeric numbering information for YANG modules found in the YANG Module Names registry. This is only required for registry entries that represent YANG modules, not YANG sub-modules. The YANG data node "yid-registry" in the "ietf-yid" YANG module defines the syntax and semantics of a YANG Identifier registry. The syntax and semantics of the registry structure is described by the "yid-registry" grouping definition in the "ietf-yid" YANG module defined in Section 4.1. A "module" entry needs to be maintained for each YANG module maintained by IANA. The "yid-module-entry" grouping in the "ietf- yid" YANG module defines the syntax and semantics of each module entry. The "module-id" field in the entry must match the "module-id" assigned to the YANG module in the YANG Module Names registry. TBD: List the tools available to generate YANG hash and manual assignment entries The following initial parameter values are suggested for the registry: { "yid-registry" : { "name" : "ietf-yid", "revision" : TBD, "module-bits" : 20, "local-bits" : 16 } } 7.3.1. Registry Maintenance When a YANG module is added to the YANG Module Names Registry, IANA will assign a unique module-id value for the module. At this time an initial YANG Identifier registry entry for the module is created. When a YANG module update is being published, and IANA actions are being processed for the pending RFC, an update to the YANG Identifier registry for the existing module is created. The registry entry "revision" field is updated to a new value that is greater than the previous value. Bierman & van der Stok Expires February 17, 2017 [Page 22] Internet-Draft YANG IDs August 2016 No existing entry information is allowed to change. Only new manually numbered local-id values can be added. For local mappings, new "mapping" list entries can be added. For remote mappings, the "mapping-url" and "mapping-type" fields can be updated to identify the new mapping information. For YANG modules that use YANG hash based local-id values, there is no need to update the registry entry for the module unless any hash collisions would be introduced by the new module revision. For YANG modules that use manually numbered local-id values, there is no need to update the registry unless new data nodes have been added to the YANG module. 8. Acknowledgements We are very grateful to Bert Greevenbosch who suggested the use of hashes and specified the use of murmur3. 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [murmur3] "murmurhash family", Web http://en.wikipedia.org/wiki/MurmurHash. [murmur-imp] "murmurhash implementation", Web https://code.google.com/p/smhasher/. 9.2. Informative References [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, DOI 10.17487/RFC2578, April 1999, . Bierman & van der Stok Expires February 17, 2017 [Page 23] Internet-Draft YANG IDs August 2016 [RFC4293] Routhier, S., Ed., "Management Information Base for the Internet Protocol (IP)", RFC 4293, DOI 10.17487/RFC4293, April 2006, . [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [I-D.ietf-netconf-restconf] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", draft-ietf-netconf-restconf-16 (work in progress), August 2016. [I-D.bierman-core-yang-hash] Bierman, A. and P. Stok, "YANG Hash", draft-bierman-core- yang-hash-00 (work in progress), February 2016. Appendix A. Open Issues There are some advanced features not specified in this document. These can be left as future work. When to assign a module-id: There may be significant delay between the time a module is used in development and when it is published and added to a registry. Once a module-id has been assigned, it cannot be undone or changed. When should a module-id be assigned in a YANG Identifier registry? Should it be early in development, late in development, or after the module approval process? How to support private numbering: Should it be possible for a registry used by a server to contain module-id values that have not been globally assigned in the registry? Should a numeric range be reserved for this purpose? If so, is this range globally reserved or configured into each registry? How to combine registries: What if a server vendor wants to support modules not listed in a single registry? How can this be supported? E.g., increase the size of the identifier and allocate some bits for a registry identifier? Should more YANG statements be numbered: Should "rpc" and "notification" statements be numbered? Should YANG 1.1 "action" statements be numbered? How to support anyxml and anydata subtrees: A YANG data node that is defined with the "anyxml" ar "anydata" statement has an identifier for the top of the specified subtree in instance documents. XML Bierman & van der Stok Expires February 17, 2017 [Page 24] Internet-Draft YANG IDs August 2016 and JSON representations of these YANG statements uses a QName to identify each descendant node within the anyxml or anydata subtree. These descendant nodes do not exist in the YANG module schema tree. They only exist in instance documents conforming to the YANG module. Therefore it is not possible to give these nodes numeric assignments. Use of string (QName) identifiers within anyxml or anydata subtrees may be required. Appendix B. YANG Identifier Examples The following simple YANG module is used throughout these examples: module example-address { namespace "http://example.com/ns/example-address"; prefix "exaddr"; revision 2016-08-05; container addresses { list address { key "last first"; leaf last { type string; } leaf first { type string; } leaf street { type string; } leaf city { type string; } leaf zipcode { type string; } } } } B.1. Hash Collision Repair Example The following example shows how a hash collision can be avoided using the YANG Hash "rehash" bit. The following path identifiers and conceptual hash values are assigned for the "example-address" module: H1 /example-address:addresses H2 /example-address:addresses/address H3 /example-address:addresses/address/last H4 /example-address:addresses/address/first H5 /example-address:addresses/address/street H6 /example-address:addresses/address/city H7 /example-address:addresses/address/zipcode The following YANG Identifier values could be assigned using if there are no hash collisions. Bierman & van der Stok Expires February 17, 2017 [Page 25] Internet-Draft YANG IDs August 2016 module-id = M local-id = Hn However, if 2 nodes have the same hash value (say H2 and H5) then one of the nodes needs to be renumbered using an manual assignment in the YANG registry. If 16 bit local identifiers are used then values 1 - 32767 are reserved for hash values, and values 32768 - 65535 are reserved for manually assigned rehash mappings. { "module" : [ { "module-id" : 17, "name" : "example-address", "revision" : 0x7e00801, "local-type" : "hash", "mapping" : [ { "local-id" : 32768, "path" : "/example-address:addresses/address/street" } ] } ] } B.2. Manual Numbering Example In this example, manually assigned local-id values are given to the example-address module. Instead of hash values, simple ascending integer values are given. 1 /example-address:addresses 2 /example-address:addresses/address 3 /example-address:addresses/address/last 4 /example-address:addresses/address/first 5 /example-address:addresses/address/street 6 /example-address:addresses/address/city 7 /example-address:addresses/address/zipcode If the 'module-id' value '17' is assigned, and the 'local-bits' value is '16', then the following YANG Identifier values would be assigned for these local-id values: Bierman & van der Stok Expires February 17, 2017 [Page 26] Internet-Draft YANG IDs August 2016 0x110001 /example-address:addresses 0x110002 /example-address:addresses/address 0x110003 /example-address:addresses/address/last 0x110004 /example-address:addresses/address/first 0x110005 /example-address:addresses/address/street 0x110006 /example-address:addresses/address/city 0x110007 /example-address:addresses/address/zipcode The example YANG Identifier (YID) file contents: Bierman & van der Stok Expires February 17, 2017 [Page 27] Internet-Draft YANG IDs August 2016 { "module" : [ { "module-id" : 17, "name" : "example-address", "revision" : 0x7e00801, "local-type" : "manual", "mapping" : [ { "local-id" : 1, "path" : "/example-address:addresses" }, { "local-id" : 2, "path" : "/example-address:addresses/address" }, { "local-id" : 3, "path" : "/example-address:addresses/address/last" }, { "local-id" : 4, "path" : "/example-address:addresses/address/first" }, { "local-id" : 5, "path" : "/example-address:addresses/address/street" }, { "local-id" : 6, "path" : "/example-address:addresses/address/city" }, { "local-id" : 7, "path" : "/example-address:addresses/address/zipcode" } ] } } } B.3. Augment Numbering Example In this example, manually assigned local-id values are given to the following "example-phone" module: Bierman & van der Stok Expires February 17, 2017 [Page 28] Internet-Draft YANG IDs August 2016 module example-phone { namespace "http://example.com/ns/example-phone"; prefix "exphone"; import example-address { prefix addr; } revision 2016-08-05; augment "/addr:addresses/addr:address" { container phones { list phone { key "prefix number"; leaf prefix { type string; } leaf number { type string; } leaf type { type phone-type; } } } } } The following local-id mappings are defined in this example. 1 /example-address:addresses/address/example-phone:phones 2 /example-address:addresses/address/example-phone:phones\ /phone 3 /example-address:addresses/address/example-phone:phones\ /phone/prefix 4 /example-address:addresses/address/example-phone:phones\ /phone/number 5 /example-address:addresses/address/example-phone:phones\ /phone/type If the 'module-id' value '24' is assigned, and the 'local-bits' value is '16', then the following YANG Identifier values would be assigned for these local-id values: 0x180001 /example-address:addresses/address/example-phone:phones 0x180002 /example-address:addresses/address/example-phone:phones\ /phone 0x180003 /example-address:addresses/address/example-phone:phones\ /phone/prefix 0x180004 /example-address:addresses/address/example-phone:phones\ /phone/number 0x180005 /example-address:addresses/address/example-phone:phones\ /phone/type The example YANG Identifier (YID) file contents are shown below. Bierman & van der Stok Expires February 17, 2017 [Page 29] Internet-Draft YANG IDs August 2016 { "module" : [ { "module-id" : 24, "name" : "example-phone", "revision" : 0x7e00801, "local-type" : "manual", "mapping" : [ { "local-id" : 1, "path" : "/example-address:addresses/address\ /example-phone:phones" }, { "local-id" : 2, "path" : "/example-address:addresses/address\ /example-phone:phones/phone" }, { "local-id" : 3, "path" : "/example-address:addresses/address\ /example-phone:phones/phone/prefix" }, { "local-id" : 4, "path" : "/example-address:addresses/address\ /example-phone:phones/phone/number" }, { "local-id" : 5, "path" : "/example-address:addresses/address\ /example-phone:phones/phone/type" } ] } } } Appendix C. YANG Hash Examples The YANG translation of the SMIv2 module specifying the ipNetToMediaTable [RFC4293] yields: Bierman & van der Stok Expires February 17, 2017 [Page 30] Internet-Draft YANG IDs August 2016 container IP-MIB { container ipNetToPhysicalTable { list ipNetToPhysicalEntry { key "ipNetToPhysicalIfIndex ipNetToPhysicalNetAddressType ipNetToPhysicalNetAddress"; leaf ipNetToMediaIfIndex { type: int32; } leaf ipNetToPhysicalIfIndex { type if-mib:InterfaceIndex; } leaf ipNetToPhysicalNetAddressType { type inet-address:InetAddressType; } leaf ipNetToPhysicalNetAddress { type inet-address:InetAddress; } leaf ipNetToPhysicalPhysAddress { type yang:phys-address { length "0..65535"; } } leaf ipNetToPhysicalLastUpdated { type yang:timestamp; } leaf ipNetToPhysicalType { type enumeration { ... } } leaf ipNetToPhysicalState { type enumeration { ... } } leaf ipNetToPhysicalRowStatus { type snmpv2-tc:RowStatus; } } } The YANG hash values for 'ipNetToPhysicalEntry' and its child nodes are calculated by constructing the schema node identifier for the objects, and then calculating the 30 bit murmur3 hash values (shown in parenthesis): Bierman & van der Stok Expires February 17, 2017 [Page 31] Internet-Draft YANG IDs August 2016 /IP-MIB:IP-MIB/ipNetToPhysicalTable (0x0aba15cc) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry (0xo6aaddbc) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalIfIndex (0x346b3071) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalNetAddressType (0x3650bb64) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalNetAddress (0x06fd4d91) /IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalPhysAddress (0x26180bcb) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalLastUpdated (0x3d6bbe90) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalType (0x35ecbb3d) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalState (0x13038bb5) /IP-MIB:IP-MIB/ipNetToPhysicalTable/ipNetToPhysicalEntry\ /ipNetToPhysicalRowStatus (0x09e1fa37) The example YANG Identifier (YID) file contents are shown below. Note that there are no hash collisions so there are no local identifiers assigned. This is expected to be the typical case. { "module" : [ { "module-id" : 25, "name" : "IP-MIB", "revision" : 0x7d60202, "local-type" : "hash" } ] } If the 'module-id' value '25' is assigned, and the 'local-bits' value is '16', then the following YANG Identifier values would be assigned for these local-id values (only the terminal node is shown since they are unique in SMIv2). Note that only 15 bits of the 30 bit hash value are used. The 16th bit is reserved to identify manually assigned rehash entries. Bierman & van der Stok Expires February 17, 2017 [Page 32] Internet-Draft YANG IDs August 2016 0x1915cc ipNetToPhysicalTable 0x195dbc ipNetToPhysicalEntry 0x193071 ipNetToPhysicalIfIndex 0x193b64 ipNetToPhysicalNetAddressType 0x194d91 ipNetToPhysicalNetAddress 0x190bcb ipNetToPhysicalPhysAddress 0x193e90 ipNetToPhysicalLastUpdated 0x193b3d ipNetToPhysicalType 0x190bb5 ipNetToPhysicalState 0x197a37 ipNetToPhysicalRowStatus Authors' Addresses Andy Bierman YumaWorks, Inc. 685 Cochran St. Suite #160 Simi Valley, CA 93065 USA Email: andy@yumaworks.com Peter van der Stok consultant Phone: +31-492474673 (Netherlands), +33-966015248 (France) Email: consultancy@vanderstok.org URI: www.vanderstok.org Bierman & van der Stok Expires February 17, 2017 [Page 33]