idnits 2.17.1 draft-veillette-core-yang-library-01.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 172 has weird spacing: '...-set-id uni...' == Line 179 has weird spacing: '...evision rev...' == Line 180 has weird spacing: '...ce-type enu...' == Line 183 has weird spacing: '...evision rev...' -- The document date (July 24, 2017) is 2440 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) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-01 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-04 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-01 -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 0 errors (**), 0 flaws (~~), 8 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 July 24, 2017 5 Expires: January 25, 2018 7 Constrained YANG Module Library 8 draft-veillette-core-yang-library-01 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 January 25, 2018. 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 . . . . . . . . . . . . . . . . . . . . . . . 4 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" . . . . . . . . . 5 63 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 64 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 10 65 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 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 /mod.uri resource. The following YANG module 78 information is provided to client applications to fully utilize the 79 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.ietf-core-comi] and to 104 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.ietf-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 The tree diagram of YANG module ietf-constrained-yang-library is 167 provided below. This graphical representation of a YANG module is 168 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 170 module: ietf-constrained-yang-library 171 +--ro modules-state 172 +--ro module-set-id union 173 +--ro module* [sid revision] 174 +--ro sid sid 175 +--ro revision revision 176 +--ro feature* sid 177 +--ro deviation* [sid revision] 178 | +--ro sid sid 179 | +--ro revision revision 180 +--ro conformance-type enumeration 181 +--ro submodule* [sid revision] 182 +--ro sid sid 183 +--ro revision revision 184 notifications: 185 +---n yang-library-change 186 +--ro module-set-id -> /modules-state/module-set-id 188 3.2. Description 189 3.2.1. modules-state 191 This mandatory container specifies the module set identifier and the 192 list of modules supported by the server. 194 3.2.2. modules-state/module-set-id 196 This mandatory leaf contains an identifier representing the current 197 set of modules and submodules used by a server. This identifier is 198 server-specific when implemented as unit32 or can be used by multiple 199 servers when implemented as identityref. The value of this leaf MUST 200 change whenever the set of modules and submodules in the library 201 changes. There is no requirement that the same set always results in 202 the same 'module-set-id' value. 204 This leaf allows a client to fetch the module list once, cache it, 205 and only re-fetch it if the value of this leaf has been changed. 207 If the value of this leaf changes, the server also generates a 'yang- 208 library-change' notification, with the new value of 'module-set-id'. 210 3.2.3. modules-state/module 212 This mandatory list contains one entry for each YANG module supported 213 by the server. There MUST be an entry in this list for each revision 214 of each YANG module that is used by the server. It is possible for 215 multiple revisions of the same module to be imported, in addition to 216 an entry for the revision that is implemented by the server. 218 4. YANG Module "ietf-constrained-yang-library" 220 RFC Ed.: update the date below with the date of RFC publication and 221 remove this note. 223 file "ietf-constrained-yang-library@2017-01-20.yang" 224 module ietf-constrained-yang-library { 225 namespace 226 "urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library"; 227 prefix "lib"; 229 organization 230 "IETF CORE (Constrained RESTful Environments) Working Group"; 232 contact 233 "WG Web: 235 WG List: 236 WG Chair: Carsten Bormann 237 239 WG Chair: Jaime Jimenez 240 242 Editor: Michel Veillette 243 "; 245 description 246 "This module contains the list of YANG modules and submodules 247 implemented by a server. 249 Copyright (c) 2016 IETF Trust and the persons identified as 250 authors of the code. All rights reserved. 252 Redistribution and use in source and binary forms, with or 253 without modification, is permitted pursuant to, and subject 254 to the license terms contained in, the Simplified BSD License 255 set forth in Section 4.c of the IETF Trust's Legal Provisions 256 Relating to IETF Documents 257 (http://trustee.ietf.org/license-info). 259 This version of this YANG module is part of RFC XXXX; see 260 the RFC itself for full legal notices."; 262 // RFC Ed.: replace XXXX with actual RFC number and remove 263 // this note. 265 // RFC Ed.: update the date below with the date of the RFC 266 // publication and remove this note. 268 revision 2017-01-20 { 269 description 270 "Initial revision."; 271 reference 272 "RFC XXXX: Constrained YANG Module Library."; 273 } 275 /* 276 * Typedefs 277 */ 279 typedef revision { 280 type binary { 281 length "4"; 282 } 283 description 284 "Revision date encoded as a binary string as follow: 285 - First byte = Year divided by 100 286 - Second byte = Year modulo 100 (0 to 99) 287 - Third byte = Month (1 = January to 12 = december) 288 - Forth byte = Day (1 to 31)"; 289 } 291 typedef sid { 292 type uint64; 293 description 294 "Identifier assigned to different YANG items such as 295 data nodes, RPCs and actions, notifications, modules, 296 sub-modules, features and deviations."; 297 } 299 /* 300 * Groupings 301 */ 303 grouping identification-info { 304 description 305 "YANG modules and submodules identification information."; 307 leaf sid { 308 type sid; 309 mandatory true; 310 description 311 "SID assigned to this module or submodule."; 312 } 314 leaf revision { 315 type revision; 316 description 317 "Revision date assigned to this module or submodule. 318 A zero-length binary string is used if no revision statement 319 is present in the YANG module or submodule."; 320 } 321 } 323 identity module-set { 324 description 325 "Base identity from which shared module-set identifiers 326 are derived."; 327 } 329 /* 330 * Operational state data nodes 331 */ 333 container modules-state { 334 config false; 335 description 336 "Contains information about the different data models 337 implemented by the server."; 339 leaf module-set-id { 340 type union { 341 type uint32; 342 type identityref { 343 base "lib:module-set"; 344 } 345 } 346 mandatory true; 347 description 348 "Identifier representing the current set of modules 349 and submodules listed in the 'module' list. This 350 identifier is server-specific when implemented as 351 unit32 or shared between multiple servers when 352 implemented as identityref. The server MUST change 353 the value of this leaf each time the content of the 354 'module' list instance change."; 355 } 357 list module { 358 key "sid revision"; 359 description 360 "Each entry represents one revision of one module 361 currently supported by the server."; 363 uses identification-info; 365 leaf-list feature { 366 type sid; 367 description 368 "List of YANG features from this module that are 369 supported by the server, regardless whether 370 they are defined in the module or in any included 371 submodules."; 372 } 374 list deviation { 375 key "sid revision"; 376 description 377 "List of YANG deviation modules used by this server 378 to modify the conformance of the module associated 379 with this entry. Note that the same module can be 380 used for deviations for multiple modules, so the 381 same entry MAY appear within multiple 'module' entries. 383 The deviation module MUST be present in the 'module' 384 list, with the same sid and revision values. 385 The 'conformance-type' value will be 'implement' for 386 the deviation module."; 388 uses identification-info; 389 } 391 leaf conformance-type { 392 type enumeration { 393 enum implement { 394 value 0; 395 description 396 "Indicates that the server implements one or more 397 protocol-accessible objects defined in the YANG 398 module identified in this entry. This includes 399 deviation statements defined in the module. 401 For YANG version 1.1 modules, there is at most one 402 module entry with conformance type 'implement' for a 403 particular module, since YANG 1.1 requires that 404 at most one revision of a module is implemented. 406 For YANG version 1 modules, there SHOULD NOT be more 407 than one module entry for a particular module."; 408 } 409 enum import { 410 value 1; 411 description 412 "Indicates that the server imports reusable definitions 413 from the specified revision of the module, but does 414 not implement any protocol accessible objects from 415 this revision. 417 Multiple module entries for the same module MAY 418 exist. This can occur if multiple modules import the 419 same module, but specify different revision-dates in 420 the import statements."; 421 } 422 } 423 mandatory true; 424 description 425 "Indicates the type of conformance the server is claiming 426 for the YANG module identified by this entry."; 427 } 428 list submodule { 429 key "sid revision"; 430 description 431 "Each entry represents one submodule within the 432 parent module."; 433 uses identification-info; 434 } 435 } 436 } 438 /* 439 * Notifications 440 */ 442 notification yang-library-change { 443 description 444 "Generated when the set of modules and submodules supported 445 by the server has changed."; 447 leaf module-set-id { 448 type leafref { 449 path "/lib:modules-state/lib:module-set-id"; 450 } 451 mandatory true; 452 description 453 "Contains the module-set-id value representing the 454 set of modules and submodules supported by the server 455 at the time the notification is generated."; 456 } 457 } 458 } 459 461 5. IANA Considerations 463 5.1. YANG Module Registry 465 This document registers one YANG module in the YANG Module Names 466 registry [RFC7950]. 468 name: ietf-constrained-yang-library 470 namespace: urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library 472 prefix: lib 474 reference: RFC XXXX 475 // RFC Ed.: replace XXXX with RFC number and remove this note 477 6. Security Considerations 479 This YANG module is designed to be accessed via the CoMI protocol 480 [I-D.ietf-core-comi]. Some of the readable data nodes in this YANG 481 module may be considered sensitive or vulnerable in some network 482 environments. It is thus important to control read access to these 483 data nodes. 485 Specifically, the 'module' list may help an attacker to identify the 486 server capabilities and server implementations with known bugs. 487 Server vulnerabilities may be specific to particular modules, module 488 revisions, module features, or even module deviations. This 489 information is included in each module entry. For example, if a 490 particular operation on a particular data node is known to cause a 491 server to crash or significantly degrade device performance, then the 492 module list information will help an attacker identify server 493 implementations with such a defect, in order to launch a denial of 494 service attack on the device. 496 7. Acknowledgments 498 The YANG module defined by this memo have been derived from an 499 already existing YANG module, ietf-yang-library [RFC7895], we will 500 like to thanks to the authors of this YANG module. A special thank 501 also to Andy Bierman for his initial recommendations for the creation 502 of this YANG module. 504 8. References 506 8.1. Normative References 508 [I-D.ietf-core-comi] 509 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 510 Management Interface", draft-ietf-core-comi-01 (work in 511 progress), July 2017. 513 [I-D.ietf-core-yang-cbor] 514 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 515 Minaburo, "CBOR Encoding of Data Modeled with YANG", 516 draft-ietf-core-yang-cbor-04 (work in progress), February 517 2017. 519 [I-D.ietf-netmod-yang-tree-diagrams] 520 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 521 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 522 2017. 524 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 525 Requirement Levels", BCP 14, RFC 2119, 526 DOI 10.17487/RFC2119, March 1997, 527 . 529 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 530 RFC 7950, DOI 10.17487/RFC7950, August 2016, 531 . 533 8.2. Informative References 535 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 536 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 537 . 539 Author's Address 541 Michel Veillette (editor) 542 Trilliant Networks Inc. 543 610 Rue du Luxembourg 544 Granby, Quebec J2J 2V2 545 Canada 547 Phone: +14503750556 548 Email: michel.veillette@trilliantinc.com