idnits 2.17.1 draft-veillette-core-yang-library-02.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 182 has weird spacing: '...evision rev...' == Line 183 has weird spacing: '...ce-type enu...' == Line 186 has weird spacing: '...evision rev...' -- The document date (January 24, 2018) is 2283 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-02 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-05 == Outdated reference: A later version (-05) exists of draft-ietf-netconf-nmda-restconf-02 == Outdated reference: A later version (-07) exists of draft-ietf-netconf-rfc7895bis-03 -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 0 errors (**), 0 flaws (~~), 9 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 24, 2018 5 Expires: July 28, 2018 7 Constrained YANG Module Library 8 draft-veillette-core-yang-library-02 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 https://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 July 28, 2018. 35 Copyright Notice 37 Copyright (c) 2018 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 (https://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/hash . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . 10 66 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 69 8.2. Informative References . . . . . . . . . . . . . . . . . 11 70 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 72 1. Introduction 74 WARNING: Both this contribution and the CoMI protocol 75 [I-D.ietf-core-comi] need to be reviewed to verify their 76 compatibility with the "Network Management Datastore Architecture" 77 (NMDA). See [I-D.dsdt-nmda-guidelines], 78 [I-D.ietf-netconf-rfc7895bis], [I-D.ietf-netmod-revised-datastores] 79 and [I-D.ietf-netconf-nmda-restconf] for more details. 81 The YANG library specified in this document is available to clients 82 of a given server to discover the YANG modules supported by this 83 constrained network management server. A CoMI server provides a link 84 to this library in the /mod.uri resource. The following YANG module 85 information is provided to client applications to fully utilize the 86 YANG data modeling language: 88 o module list: The list of YANG modules implemented by a server, 89 each module is identified by its assigned YANG Schema Item 90 iDentifier (SID) and revision. 92 o submodule list: The list of YANG submodules included by each 93 module, each submodule is identified by its assigned SID and 94 revision. 96 o feature list: The list of features supported by the server, each 97 feature is identified by its assigned SID. 99 o deviation list: The list of YANG modules used for deviation 100 statements associated with each YANG module, each module is 101 identified by its assigned SID and revision. 103 1.1. Major differences between ietf-constrained-yang-library and ietf- 104 yang-library 106 YANG module 'ietf-constrained-yang-library' targets the same 107 functionality and shares the same approach as YANG module ietf-yang- 108 library. The following changes with respect to ietf-yang-library are 109 specified to make ietf-constrained-yang-library compatible with SID 110 [I-D.ietf-core-yang-cbor] used by CoMI [I-D.ietf-core-comi] and to 111 improve its applicability to constrained devices and networks. 113 o YANG module 'ietf-constrained-yang-library' extends the caching 114 mechanism supported by 'ietf-yang-library' to multiple servers of 115 the same type. This is accomplished by replacing 'module-set-id' 116 by a hash of the library content. 118 o Modules, sub-modules, deviations and features are identified using 119 a numerical value (SID) instead of a string (yang-identifier). 121 o The "namespace" leaf, not required for SIDs, but mandatory in 122 'ietf-yang-library' is not included in 'ietf-constrained-yang- 123 library'. 125 o Schemas can be located using the already available module or sub- 126 module identifier (SID) and revision. For this reason, support of 127 module and sub-module schema URIs have been removed. 129 o To minimize their size, each revision date is encoded in binary. 131 2. Terminology and Notation 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. 137 The following terms are defined in [RFC7950]: 139 o module 141 o submodule 143 o feature 145 o deviation 146 The following terms are defined in [I-D.ietf-core-yang-cbor]: 148 o YANG Schema Item iDentifier (SID) 150 The following terms are defined in [I-D.ietf-core-comi]: 152 o client 154 o server 156 The following terms are used within this document: 158 o library: a collection of YANG modules used by a server. 160 3. Overview 162 The "ietf-constrained-yang-library" module provides information about 163 the YANG library used by a given server. This module is defined 164 using YANG version 1 as defined by [RFC7950], but it supports the 165 description of YANG modules written in any revision of YANG. 167 3.1. Tree diagram 169 The tree diagram of YANG module ietf-constrained-yang-library is 170 provided below. This graphical representation of a YANG module is 171 defined in [I-D.ietf-netmod-yang-tree-diagrams]. 173 module: ietf-constrained-yang-library 174 +--ro modules-state 175 +--ro hash binary 176 +--ro module* [sid revision] 177 +--ro sid comi:sid 178 +--ro revision revision 179 +--ro feature* comi:sid 180 +--ro deviation* [sid revision] 181 | +--ro sid comi:sid 182 | +--ro revision revision 183 +--ro conformance-type enumeration 184 +--ro submodule* [sid revision] 185 +--ro sid comi:sid 186 +--ro revision revision 188 notifications: 189 +---n yang-library-change 190 +--ro hash -> /modules-state/hash 192 3.2. Description 194 3.2.1. modules-state 196 This mandatory container specifies the module set identifier and the 197 list of modules supported by the server. 199 3.2.2. modules-state/hash 201 This mandatory leaf contains the hash of the library content. The 202 value of this leaf MUST change whenever the set of modules and 203 submodules in the library changes. This leaf allows a client to 204 fetch the module list once, cache it, and only re-fetch it if the 205 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. 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@2018-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 import ietf-comi { 230 prefix comi; 231 } 233 organization 234 "IETF CORE (Constrained RESTful Environments) Working Group"; 236 contact 237 "WG Web: 239 WG List: 240 WG Chair: Carsten Bormann 241 243 WG Chair: Jaime Jimenez 244 246 Editor: Michel Veillette 247 "; 249 description 250 "This module contains the list of YANG modules and submodules 251 implemented by a server. 253 Copyright (c) 2016 IETF Trust and the persons identified as 254 authors of the code. All rights reserved. 256 Redistribution and use in source and binary forms, with or 257 without modification, is permitted pursuant to, and subject 258 to the license terms contained in, the Simplified BSD License 259 set forth in Section 4.c of the IETF Trust's Legal Provisions 260 Relating to IETF Documents 261 (http://trustee.ietf.org/license-info). 263 This version of this YANG module is part of RFC XXXX; see 264 the RFC itself for full legal notices."; 266 // RFC Ed.: replace XXXX with actual RFC number and remove 267 // this note. 269 // RFC Ed.: update the date below with the date of the RFC 270 // publication and remove this note. 272 revision 2018-01-20 { 273 description 274 "Initial revision."; 275 reference 276 "RFC XXXX: Constrained YANG Module Library."; 277 } 279 /* 280 * Typedefs 281 */ 283 typedef revision { 284 type binary { 285 length "4"; 286 } 287 description 288 "Revision date encoded as a binary string as follow: 289 - First byte = Century 290 - Second byte = Year (0 to 99) 291 - Third byte = Month (1 = January to 12 = December) 292 - Forth byte = Day (1 to 31)"; 293 } 295 /* 296 * Groupings 297 */ 299 grouping identification-info { 300 description 301 "YANG modules and submodules identification information."; 303 leaf sid { 304 type comi:sid; 305 mandatory true; 306 description 307 "SID assigned to this module or submodule."; 308 } 310 leaf revision { 311 type revision; 312 description 313 "Revision date assigned to this module or submodule. 314 A zero-length binary string is used if no revision 315 statement is present in the YANG module or submodule."; 316 } 317 } 319 identity module-set { 320 description 321 "Base identity from which shared module-set identifiers 322 are derived."; 323 } 325 /* 326 * Operational state data nodes 327 */ 329 container modules-state { 330 config false; 331 description 332 "Contains information about the different data models 333 implemented by the server."; 335 leaf hash { 336 type binary { 337 length "8..32"; 338 } 339 mandatory true; 340 description 341 "A server-generated hash of the contents of the library. 342 The server MUST change the value of this leaf each time 343 the content of the library has changed. The hash function 344 and size are not specified, but shall be collision 345 resistant."; 346 } 348 list module { 349 key "sid revision"; 350 description 351 "Each entry represents one revision of one module 352 currently supported by the server."; 354 uses identification-info; 356 leaf-list feature { 357 type comi:sid; 358 description 359 "List of YANG features from this module that are 360 supported by the server, regardless whether 361 they are defined in the module or in any 362 included submodules."; 363 } 365 list deviation { 366 key "sid revision"; 367 description 368 "List of YANG deviation modules used by this server 369 to modify the conformance of the module associated 370 with this entry. Note that the same module can be 371 used for deviations for multiple modules, so the same 372 entry MAY appear within multiple 'module' entries. 374 Deviation modules MUST also be present in the 'module' 375 list, with the same sid and revision values and the 376 'conformance-type' set to 'implement'."; 378 uses identification-info; 379 } 381 leaf conformance-type { 382 type enumeration { 383 enum implement { 384 value 0; 385 description 386 "Indicates that the server implements one or more 387 protocol-accessible objects defined in the YANG 388 module identified in this entry. This includes 389 deviation statements defined in the module. 391 For YANG version 1.1 modules, there is at most one 392 module entry with conformance type 'implement' for 393 a particular module, since YANG 1.1 requires that 394 at most one revision of a module is implemented. 396 For YANG version 1 modules, there SHOULD NOT be more 397 than one module entry for a particular module."; 398 } 399 enum import { 400 value 1; 401 description 402 "Indicates that the server imports reusable 403 definitions from the specified revision of the 404 module, but does not implement any protocol 405 accessible objects from this revision. 407 Multiple module entries for the same module MAY 408 exist. This can occur if multiple modules import 409 the same module, but specify different revision-dates 410 in the import statements."; 411 } 412 } 413 mandatory true; 414 description 415 "Indicates the type of conformance the server is claiming 416 for the YANG module identified by this entry."; 417 } 419 list submodule { 420 key "sid revision"; 421 description 422 "Each entry represents one submodule within the 423 parent module."; 424 uses identification-info; 425 } 426 } 427 } 429 /* 430 * Notifications 431 */ 433 notification yang-library-change { 434 description 435 "Generated when the set of modules and submodules supported 436 by the server has changed."; 438 leaf hash { 439 type leafref { 440 path "/lib:modules-state/lib:hash"; 441 } 442 mandatory true; 443 description 444 "New hash value."; 445 } 446 } 447 } 448 450 5. IANA Considerations 452 5.1. YANG Module Registry 454 This document registers one YANG module in the YANG Module Names 455 registry [RFC7950]. 457 name: ietf-constrained-yang-library 459 namespace: urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library 461 prefix: lib 463 reference: RFC XXXX 465 // RFC Ed.: replace XXXX with RFC number and remove this note 467 6. Security Considerations 469 This YANG module is designed to be accessed via the CoMI protocol 470 [I-D.ietf-core-comi]. Some of the readable data nodes in this YANG 471 module may be considered sensitive or vulnerable in some network 472 environments. It is thus important to control read access to these 473 data nodes. 475 Specifically, the 'module' list may help an attacker to identify the 476 server capabilities and server implementations with known bugs. 477 Server vulnerabilities may be specific to particular modules, module 478 revisions, module features, or even module deviations. This 479 information is included in each module entry. For example, if a 480 particular operation on a particular data node is known to cause a 481 server to crash or significantly degrade device performance, then the 482 module list information will help an attacker identify server 483 implementations with such a defect, in order to launch a denial of 484 service attack on the device. 486 7. Acknowledgments 488 The YANG module defined by this memo have been derived from an 489 already existing YANG module, ietf-yang-library [RFC7895], we will 490 like to thanks to the authors of this YANG module. A special thank 491 also to Andy Bierman for his initial recommendations for the creation 492 of this YANG module. 494 8. References 496 8.1. Normative References 498 [I-D.ietf-core-comi] 499 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 500 Management Interface", draft-ietf-core-comi-02 (work in 501 progress), December 2017. 503 [I-D.ietf-core-yang-cbor] 504 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 505 Minaburo, "CBOR Encoding of Data Modeled with YANG", 506 draft-ietf-core-yang-cbor-05 (work in progress), August 507 2017. 509 [I-D.ietf-netmod-yang-tree-diagrams] 510 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 511 ietf-netmod-yang-tree-diagrams-05 (work in progress), 512 January 2018. 514 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 515 Requirement Levels", BCP 14, RFC 2119, 516 DOI 10.17487/RFC2119, March 1997, 517 . 519 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 520 RFC 7950, DOI 10.17487/RFC7950, August 2016, 521 . 523 8.2. Informative References 525 [I-D.dsdt-nmda-guidelines] 526 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 527 and R. Wilton, "Guidelines for YANG Module Authors 528 (NMDA)", draft-dsdt-nmda-guidelines-01 (work in progress), 529 May 2017. 531 [I-D.ietf-netconf-nmda-restconf] 532 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 533 and R. Wilton, "RESTCONF Extensions to Support the Network 534 Management Datastore Architecture", draft-ietf-netconf- 535 nmda-restconf-02 (work in progress), January 2018. 537 [I-D.ietf-netconf-rfc7895bis] 538 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 539 and R. Wilton, "YANG Library", draft-ietf-netconf- 540 rfc7895bis-03 (work in progress), January 2018. 542 [I-D.ietf-netmod-revised-datastores] 543 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 544 and R. Wilton, "Network Management Datastore 545 Architecture", draft-ietf-netmod-revised-datastores-10 546 (work in progress), January 2018. 548 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 549 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 550 . 552 Author's Address 554 Michel Veillette (editor) 555 Trilliant Networks Inc. 556 610 Rue du Luxembourg 557 Granby, Quebec J2J 2V2 558 Canada 560 Phone: +14503750556 561 Email: michel.veillette@trilliantinc.com