idnits 2.17.1 draft-veillette-core-yang-library-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 180 has weird spacing: '...-set-id uni...' == Line 187 has weird spacing: '...evision rev...' == Line 188 has weird spacing: '...ce-type enu...' == Line 191 has weird spacing: '...evision rev...' -- The document date (January 31, 2017) is 2642 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-netconf-restconf' is defined on line 541, but no explicit reference was found in the text == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-03 -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track January 31, 2017 5 Expires: August 4, 2017 7 Constrained YANG Module Library 8 draft-veillette-core-yang-library-00 10 Abstract 12 This document describes a YANG library that provides information 13 about all the YANG modules used by a constrained network management 14 server (e.g., a CoAP Management Interface (CoMI) server). Simple 15 caching mechanisms are provided to allow clients to minimize 16 retrieval of this information. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on August 4, 2017. 35 Copyright Notice 37 Copyright (c) 2017 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Major differences between ietf-constrained-yang-library 54 and ietf-yang-library . . . . . . . . . . . . . . . . . . 3 55 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 56 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 4 58 3.2. Description . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.2.1. modules-state . . . . . . . . . . . . . . . . . . . . 5 60 3.2.2. modules-state/module-set-id . . . . . . . . . . . . . 5 61 3.2.3. modules-state/module . . . . . . . . . . . . . . . . 5 62 4. YANG Module "ietf-constrained-yang-library" . . . . . . . . . 6 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 64 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 11 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 12 69 8.2. Informative References . . . . . . . . . . . . . . . . . 12 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 72 1. Introduction 74 The YANG library specified in this document is available to clients 75 of a given server to discover the YANG modules supported by this 76 constrained network management server. A CoMI server provides a link 77 to this library in the /c/mod.uri resource. The following YANG 78 module information is provided to client applications to fully 79 utilize the YANG data modeling language: 81 o module list: The list of YANG modules implemented by a server, 82 each module is identified by its assigned YANG Schema Item 83 iDentifier (SID) and revision. 85 o submodule list: The list of YANG submodules included by each 86 module, each submodule is identified by its assigned SID and 87 revision. 89 o feature list: The list of features supported by the server, each 90 feature is identified by its assigned SID. 92 o deviation list: The list of YANG modules used for deviation 93 statements associated with each YANG module, each module is 94 identified by its assigned SID and revision. 96 1.1. Major differences between ietf-constrained-yang-library and ietf- 97 yang-library 99 YANG module ietf-constrained-yang-library targets the same 100 functionality and shares the same approach as YANG module ietf-yang- 101 library. The following changes with respect to ietf-yang-library are 102 specified to make ietf-constrained-yang-library compatible with SID 103 [I-D.ietf-core-yang-cbor] used by CoMI [I-D.vanderstok-core-comi] and 104 to improve its applicability to constrained devices and networks. 106 o YANG module ietf-constrained-yang-library extends the caching 107 mechanism supported by ietf-yang-library to multiple servers. 108 This is accomplished by supporting the identityref datatype for 109 "module-set-id". This enables the use of a managed identifier 110 (i.e. a SID) to identify a specific assembly of YANG modules, 111 deviations and features implemented by a group of constrained 112 servers. 114 o Modules, sub-modules, deviations and features are identified using 115 a numerical value (SID) instead of a string (yang-identifier). 117 o The "namespace" leaf, not required for SIDs, but mandatory in 118 ietf-yang-library is not included in ietf-constrained-yang- 119 library. 121 o Schemas can be located using the already available module or sub- 122 module identifier (SID) and revision. For this reason, support of 123 module and sub-module schema URIs have been removed. 125 o To minimize their size, each revision date is encoded in binary. 127 2. Terminology and Notation 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 The following terms are defined in [RFC7950]: 135 o module 137 o submodule 139 o feature 141 o deviation 143 The following terms are defined in [I-D.ietf-core-yang-cbor]: 145 o YANG Schema Item iDentifier (SID) 147 The following terms are defined in [I-D.vanderstok-core-comi]: 149 o client 151 o server 153 The following terms are used within this document: 155 o library: a collection of YANG modules used by a server. 157 3. Overview 159 The "ietf-constrained-yang-library" module provides information about 160 the YANG library used by a given server. This module is defined 161 using YANG version 1 as defined by [RFC7950], but it supports the 162 description of YANG modules written in any revision of YANG. 164 3.1. Tree diagram 166 A simplified graphical representation of the YANG module specified in 167 this document (ietf-constrained-yang-library) is provided below. The 168 meaning of the symbols in this diagram is as follows: 170 o Brackets "[" and "]" enclose list keys. 172 o Abbreviations before data node names: "rw" means configuration 173 data (read-write) and "ro" state data (read-only). 175 o Symbols after data node names: "?" means an optional node, "!" 176 means a presence container, and "*" denotes a list and leaf-list. 178 module: ietf-constrained-yang-library 179 +--ro modules-state 180 +--ro module-set-id union 181 +--ro module* [sid revision] 182 +--ro sid sid 183 +--ro revision revision 184 +--ro feature* sid 185 +--ro deviation* [sid revision] 186 | +--ro sid sid 187 | +--ro revision revision 188 +--ro conformance-type enumeration 189 +--ro submodule* [sid revision] 190 +--ro sid sid 191 +--ro revision revision 192 notifications: 193 +---n yang-library-change 194 +--ro module-set-id -> /modules-state/module-set-id 196 3.2. Description 198 3.2.1. modules-state 200 This mandatory container specifies the module set identifier and the 201 list of modules supported by the server. 203 3.2.2. modules-state/module-set-id 205 This mandatory leaf contains an identifier representing the current 206 set of modules and submodules used by a server. This identifier is 207 server-specific when implemented as unit32 or can be used by multiple 208 servers when implemented as identityref. The value of this leaf MUST 209 change whenever the set of modules and submodules in the library 210 changes. There is no requirement that the same set always results in 211 the same module-set-id value. 213 This leaf allows a client to fetch the module list once, cache it, 214 and only re-fetch it if the value of this leaf has been changed. 216 If the value of this leaf changes, the server also generates a "yang- 217 library-change" notification, with the new value of "module-set-id". 219 3.2.3. modules-state/module 221 This mandatory list contains one entry for each YANG module supported 222 by the server. There MUST be an entry in this list for each revision 223 of each YANG module that is used by the server. It is possible for 224 multiple revisions of the same module to be imported, in addition to 225 an entry for the revision that is implemented by the server. 227 4. YANG Module "ietf-constrained-yang-library" 229 RFC Ed.: update the date below with the date of RFC publication and 230 remove this note. 232 file "ietf-constrained-yang-library@2017-01-20.yang" 233 module ietf-constrained-yang-library { 234 namespace "urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library"; 235 prefix "lib"; 237 organization 238 "IETF CORE (Constrained RESTful Environments) Working Group"; 240 contact 241 "WG Web: 243 WG List: 245 WG Chair: Carsten Bormann 246 248 WG Chair: Jaime Jimenez 249 251 Editor: Michel Veillette 252 "; 254 description 255 "This module contains the list of YANG modules and submodules 256 implemented by a server. 258 Copyright (c) 2016 IETF Trust and the persons identified as 259 authors of the code. All rights reserved. 261 Redistribution and use in source and binary forms, with or 262 without modification, is permitted pursuant to, and subject 263 to the license terms contained in, the Simplified BSD License 264 set forth in Section 4.c of the IETF Trust's Legal Provisions 265 Relating to IETF Documents 266 (http://trustee.ietf.org/license-info). 268 This version of this YANG module is part of RFC XXXX; see 269 the RFC itself for full legal notices."; 271 // RFC Ed.: replace XXXX with actual RFC number and remove 272 // this note. 274 // RFC Ed.: update the date below with the date of the RFC 275 // publication and remove this note. 277 revision 2017-01-20 { 278 description 279 "Initial revision."; 280 reference 281 "RFC XXXX: Constrained YANG Module Library."; 282 } 284 /* 285 * Typedefs 286 */ 288 typedef revision { 289 type binary { 290 length "4"; 291 } 292 description 293 "Revision date encoded as a binary string as follow: 294 - First byte = Year divided by 100 295 - Second byte = Year modulo 100 (0 to 99) 296 - Third byte = Month (1 = January to 12 = december) 297 - Forth byte = Day (1 to 31)"; 298 } 300 typedef sid { 301 type uint64; 302 description 303 "Identifier assigned to different YANG items such as 304 data nodes, RPCs and actions, notifications, modules, 305 sub-modules, features and deviations."; 306 } 308 /* 309 * Groupings 310 */ 312 grouping identification-info { 313 description 314 "YANG modules and submodules identification information."; 316 leaf sid { 317 type sid; 318 mandatory true; 319 description 320 "SID assigned to this module or submodule."; 321 } 322 leaf revision { 323 type revision; 324 description 325 "Revision date assigned to this module or submodule. 326 A zero-length binary string is used if no revision statement 327 is present in the YANG module or submodule."; 328 } 329 } 331 identity module-set { 332 description 333 "Base identity from which shared module-set identifiers 334 are derived."; 335 } 337 /* 338 * Operational state data nodes 339 */ 341 container modules-state { 342 config false; 343 description 344 "Contains information about the different data models 345 implemented by the server."; 347 leaf module-set-id { 348 type union { 349 type uint32; 350 type identityref { 351 base "lib:module-set"; 352 } 353 } 354 mandatory true; 355 description 356 "Identifier representing the current set of modules 357 and submodules listed in the 'module' list. This 358 identifier is server-specific when implemented as 359 unit32 or shared between multiple servers when 360 implemented as identityref. The server MUST change 361 the value of this leaf each time the content of the 362 'module' list instance change."; 363 } 365 list module { 366 key "sid revision"; 367 description 368 "Each entry represents one revision of one module 369 currently supported by the server."; 371 uses identification-info; 373 leaf-list feature { 374 type sid; 375 description 376 "List of YANG features from this module that are 377 supported by the server, regardless whether 378 they are defined in the module or in any included 379 submodule."; 380 } 382 list deviation { 383 key "sid revision"; 384 description 385 "List of YANG deviation modules used by this server 386 to modify the conformance of the module associated 387 with this entry. Note that the same module can be 388 used for deviations for multiple modules, so the 389 same entry MAY appear within multiple 'module' entries. 391 The deviation module MUST be present in the 'module' 392 list, with the same sid and revision values. 393 The 'conformance-type' value will be 'implement' for 394 the deviation module."; 396 uses identification-info; 397 } 399 leaf conformance-type { 400 type enumeration { 401 enum implement { 402 value 0; 403 description 404 "Indicates that the server implements one or more 405 protocol-accessible objects defined in the YANG 406 module identified in this entry. This includes 407 deviation statements defined in the module. 409 For YANG version 1.1 modules, there is at most one 410 module entry with conformance type 'implement' for a 411 particular module, since YANG 1.1 requires that 412 at most one revision of a module is implemented. 414 For YANG version 1 modules, there SHOULD NOT be more 415 than one module entry for a particular module."; 416 } 417 enum import { 418 value 1; 419 description 420 "Indicates that the server imports reusable definitions 421 from the specified revision of the module, but does 422 not implement any protocol accessible objects from 423 this revision. 425 Multiple module entries for the same module MAY 426 exist. This can occur if multiple modules import the 427 same module, but specify different revision-dates in 428 the import statements."; 429 } 430 } 431 mandatory true; 432 description 433 "Indicates the type of conformance the server is claiming 434 for the YANG module identified by this entry."; 435 } 437 list submodule { 438 key "sid revision"; 439 description 440 "Each entry represents one submodule within the 441 parent module."; 442 uses identification-info; 443 } 444 } 445 } 447 /* 448 * Notifications 449 */ 451 notification yang-library-change { 452 description 453 "Generated when the set of modules and submodules supported 454 by the server has changed."; 456 leaf module-set-id { 457 type leafref { 458 path "/lib:modules-state/lib:module-set-id"; 459 } 460 mandatory true; 461 description 462 "Contains the module-set-id value representing the 463 set of modules and submodules supported by the server 464 at the time the notification is generated."; 465 } 466 } 468 } 469 471 5. IANA Considerations 473 5.1. YANG Module Registry 475 This document registers one YANG module in the YANG Module Names 476 registry [RFC7950]. 478 name: ietf-constrained-yang-library 480 namespace: urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library 482 prefix: lib 484 reference: RFC XXXX 486 // RFC Ed.: replace XXXX with RFC number and remove this note 488 6. Security Considerations 490 This YANG module is designed to be accessed via the CoMI protocol 491 [I-D.vanderstok-core-comi]. Some of the readable data nodes in this 492 YANG module may be considered sensitive or vulnerable in some network 493 environments. It is thus important to control read access to these 494 data nodes. 496 Specifically, the 'module' list may help an attacker to identify the 497 server capabilities and server implementations with known bugs. 498 Server vulnerabilities may be specific to particular modules, module 499 revisions, module features, or even module deviations. This 500 information is included in each module entry. For example, if a 501 particular operation on a particular data node is known to cause a 502 server to crash or significantly degrade device performance, then the 503 module list information will help an attacker identify server 504 implementations with such a defect, in order to launch a denial of 505 service attack on the device. 507 7. Acknowledgments 509 The YANG module defined by this memo have been derived from an 510 already existing YANG module, ietf-yang-library [RFC7895], we will 511 like to thanks to the authors of this YANG module. A special thank 512 Andy Bierman for his initial recommendations for the creation of this 513 YANG module. 515 8. References 517 8.1. Normative References 519 [I-D.ietf-core-yang-cbor] 520 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 521 Minaburo, "CBOR Encoding of Data Modeled with YANG", 522 draft-ietf-core-yang-cbor-03 (work in progress), October 523 2016. 525 [I-D.vanderstok-core-comi] 526 Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP 527 Management Interface", draft-vanderstok-core-comi-11 (work 528 in progress), January 2017. 530 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 531 Requirement Levels", BCP 14, RFC 2119, 532 DOI 10.17487/RFC2119, March 1997, 533 . 535 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 536 RFC 7950, DOI 10.17487/RFC7950, August 2016, 537 . 539 8.2. Informative References 541 [I-D.ietf-netconf-restconf] 542 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 543 Protocol", draft-ietf-netconf-restconf-18 (work in 544 progress), October 2016. 546 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 547 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 548 . 550 Author's Address 552 Michel Veillette (editor) 553 Trilliant Networks Inc. 554 610 Rue du Luxembourg 555 Granby, Quebec J2J 2V2 556 Canada 558 Phone: +14503750556 559 Email: michel.veillette@trilliantinc.com