idnits 2.17.1 draft-ietf-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 152 has weird spacing: '...ntifier sid...' == Line 157 has weird spacing: '...ntifier sid...' == Line 163 has weird spacing: '...ntifier sid...' == Line 168 has weird spacing: '...ntifier sid...' == Line 175 has weird spacing: '...ntifier ds:...' -- The document date (July 24, 2019) is 1731 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 (-24) exists of draft-ietf-core-sid-07 Summary: 0 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). 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 I. Petrov, Ed. 5 Expires: January 25, 2020 Acklio 6 July 24, 2019 8 Constrained YANG Module Library 9 draft-ietf-core-yang-library-00 11 Abstract 13 This document describes a constrained version of the YANG library 14 that provides information about the YANG modules, datastores, and 15 datastore schemas used by a constrained network management server 16 (e.g., a CORECONF server). 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 January 25, 2020. 35 Copyright Notice 37 Copyright (c) 2019 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 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 2 54 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 3 56 3.2. Major differences between ietf-constrained-yang-library 57 and ietf-yang-library . . . . . . . . . . . . . . . . . . 4 58 4. YANG Module "ietf-constrained-yang-library" . . . . . . . . . 5 59 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 60 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 13 61 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 62 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 63 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 64 8.1. Normative References . . . . . . . . . . . . . . . . . . 14 65 8.2. Informative References . . . . . . . . . . . . . . . . . 14 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 68 1. Introduction 70 There is a need for a standard mechanism to expose which YANG 71 modules, datastores and datastore schemas are in use by a constrained 72 network management server. This document defines the YANG module 73 'ietf-constrained-yang-library' that provides this information. 75 YANG module 'ietf-constrained-yang-library' shares the same data 76 model and objectives as 'ietf-yang-library', only datatypes and 77 mandatory requirements have been updated to minimize its size to 78 allow its implementation by Constrained Nodes and/or Constrained 79 Networks as defined by [RFC7228]. To review the list of objectives 80 and proposed data model, please refer to [RFC8525] section 2 and 3. 82 2. Terminology and Notation 84 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 85 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 86 "OPTIONAL" in this document are to be interpreted as described in BCP 87 14 [RFC2119] [RFC8174] when, and only when, they appear in all 88 capitals, as shown here. 90 The following terms are defined in [RFC7950]: client, deviation, 91 feature, module, submodule and server. 93 The following term is defined in [I-D.ietf-core-sid]: YANG Schema 94 Item iDentifier (SID). 96 The following terms are defined in [RFC8525]: YANG library and YANG 97 library checksum. 99 3. Overview 101 The conceptual model of the YANG library is depicted in Figure 1. 103 +-----------+ 104 | datastore | 105 +-----------+ 106 | 107 | has a 108 V 109 +-----------+ +--------+ +------------+ 110 | datastore | union of | module | consists of | modules + | 111 | schema |----------->| set |--------------->| submodules | 112 +-----------+ +--------+ +------------+ 114 Figure 1: Conceptual model of the YANG library 116 It's expected that most constrained network management servers have 117 one datastore (e.g. a unified datastore). However, some servers may 118 have multiples datastore as described by NMDA [RFC8342]. The YANG 119 library data model supports both cases. 121 In this model, every datastore has an associated datastore schema, 122 which is the union of module sets, which is a collection of modules. 123 Multiple datastores may refer to the same datastore schema and 124 individual datastore schemas may share module sets. 126 For each module, the YANG library provides: 128 o the YANG module identifier (i.e. SID) 130 o its revision 132 o its list of submodules 134 o its list of imported modules 136 o its set of features and deviations 138 YANG module namespace and location are also supported, but their 139 implementation is not recommended for constrained servers. 141 3.1. Tree diagram 143 The tree diagram of YANG module ietf-constrained-yang-library is 144 provided below. This graphical representation of a YANG module is 145 defined in [RFC8340]. 147 module: ietf-constrained-yang-library 148 +--ro yang-library 149 +--ro module-set* [index] 150 | +--ro index uint8 151 | +--ro module* [identifier] 152 | | +--ro identifier sid:sid 153 | | +--ro revision? revision-identifier 154 | | +--ro namespace? inet:uri 155 | | +--ro location* inet:uri 156 | | +--ro submodule* [identifier] 157 | | | +--ro identifier sid:sid 158 | | | +--ro revision? revision-identifier 159 | | | +--ro location* inet:uri 160 | | +--ro feature* sid:sid 161 | | +--ro deviation* -> ../../module/identifier 162 | +--ro import-only-module* [identifier revision] 163 | +--ro identifier sid:sid 164 | +--ro revision union 165 | +--ro namespace? inet:uri 166 | +--ro location* inet:uri 167 | +--ro submodule* [identifier] 168 | +--ro identifier sid:sid 169 | +--ro revision? revision-identifier 170 | +--ro location* inet:uri 171 +--ro schema* [index] 172 | +--ro index uint8 173 | +--ro module-set* -> ../../module-set/index 174 +--ro datastore* [identifier] 175 | +--ro identifier ds:datastore-ref 176 | +--ro schema -> ../../schema/index 177 +--ro checksum binary 179 notifications: 180 +---n yang-library-update 181 +--ro checksum -> /yang-library/checksum 183 3.2. Major differences between ietf-constrained-yang-library and ietf- 184 yang-library 186 The changes between the reference data model 'ietf-yang-library' and 187 its constrained version 'ietf-constrained-yang-library' are listed 188 below: 190 o module-set 'name' and schema 'name' are implemented using an 8 191 bits unsigned integer and renamed 'index'. 193 o module 'name', submodule 'name' and datastore 'name' are 194 implemented using a SID (i.e. an unsigned integer) and renamed 195 'identifier'. 197 o 'feature' and 'deviation' are implemented using a SID (i.e. an 198 unsigned integer). 200 o 'revision' fields are implemented using a 4 bytes binary string. 202 o the mandatory requirement of the 'namespace' fields is removed, 203 and implementation is not recommended. SIDs used by constrained 204 devices and protocols don't require namespaces. 206 o the implementation of the 'location' fields are not recommended, 207 the use of the module SID as the handle to retrieve the associated 208 YANG module is proposed instead. 210 4. YANG Module "ietf-constrained-yang-library" 212 RFC Ed.: update the date below with the date of RFC publication and 213 remove this note. 215 file "ietf-constrained-yang-library@2019-03-28.yang" 216 module ietf-constrained-yang-library { 217 yang-version 1.1; 218 namespace 219 "urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library"; 220 prefix "yanglib"; 222 // RFC Ed.: update ietf-core-sid reference. 224 import ietf-sid-file { 225 prefix sid; 226 reference "I-D.ietf-core-sid"; 227 } 228 import ietf-inet-types { 229 prefix inet; 230 reference "RFC 6991: Common YANG Data Types."; 231 } 232 import ietf-datastores { 233 prefix ds; 234 reference 235 "RFC 8342: Network Management Datastore Architecture (NMDA)."; 236 } 238 organization 239 "IETF NETCONF (Network Configuration) Working Group"; 241 contact 242 "WG Web: 244 WG List: 246 WG Chair: Carsten Bormann 247 249 WG Chair: Jaime Jimenez 250 252 Editor: Michel Veillette 253 "; 255 description 256 "This module provides information about the YANG modules, 257 datastores, and datastore schemas implemented by a 258 constrained network management server. 260 Copyright (c) 2018 IETF Trust and the persons identified as 261 authors of the code. All rights reserved. 263 Redistribution and use in source and binary forms, with or 264 without modification, is permitted pursuant to, and subject 265 to the license terms contained in, the Simplified BSD License 266 set forth in Section 4.c of the IETF Trust's Legal Provisions 267 Relating to IETF Documents 268 (http://trustee.ietf.org/license-info). 270 This version of this YANG module is part of RFC XXXX; see 271 the RFC itself for full legal notices."; 273 // RFC Ed.: update reference. 275 revision 2019-03-28 { 276 description 277 "Second revision."; 278 reference 279 "[I-D.veillette-core-yang-library]"; 280 } 282 revision 2018-09-21 { 283 description 284 "Initial revision."; 285 reference 286 "[I-D.veillette-core-yang-library]"; 287 } 288 /* 289 * Typedefs 290 */ 292 typedef revision-identifier { 293 type binary { 294 length "4"; 295 } 296 description 297 "Revision date encoded as a binary string, each nibble 298 representing a digit of the of revision date. For example, 299 revision 2018-09-21 is encoded as 0x20 0x18 0x09 0x21."; 300 } 302 /* 303 * Groupings 304 */ 306 grouping module-identification-leafs { 307 description 308 "Parameters for identifying YANG modules and submodules."; 310 leaf identifier { 311 type sid:sid; 312 mandatory true; 313 description 314 "SID assigned to this module or submodule."; 315 } 316 leaf revision { 317 type revision-identifier; 318 description 319 "The YANG module or submodule revision date. If no 320 revision statement is present in the YANG module 321 or submodule, this leaf is not instantiated."; 322 } 323 } 325 grouping location-leaf-list { 326 description 327 "Common location leaf list parameter for modules and 328 submodules."; 330 leaf-list location { 331 type inet:uri; 332 description 333 "Contains a URL that represents the YANG schema resource 334 for this module or submodule. 336 This leaf is present in the model to keep the alignment 337 with 'ietf-yang-library'. Support of this leaf in 338 constrained devices is not necessarily required, nor 339 expected. It is recommended that clients used the module 340 or sub-module SID as the handle used to retrieve the 341 corresponding YANG module"; 342 } 343 } 345 grouping implementation-parameters { 346 description 347 "Parameters for describing the implementation of a module."; 349 leaf-list feature { 350 type sid:sid; 351 description 352 "List of all YANG feature names from this module that are 353 supported by the server, regardless whether they are 354 defined in the module or any included submodule."; 355 } 356 leaf-list deviation { 357 type leafref { 358 path "../../module/identifier"; 359 } 360 description 361 "List of all YANG deviation modules used by this server to 362 modify the conformance of the module associated with this 363 entry. Note that the same module can be used for 364 deviations for multiple modules, so the same entry MAY 365 appear within multiple 'module' entries. 367 This reference MUST NOT (directly or indirectly) 368 refer to the module being deviated. 370 Robust clients may want to make sure that they handle a 371 situation where a module deviates itself (directly or 372 indirectly) gracefully."; 373 } 374 } 376 grouping module-set-parameters { 377 description 378 "A set of parameters that describe a module set."; 380 leaf index { 381 type uint8; 382 description 383 "An arbitrary number assigned of the module set."; 385 } 386 list module { 387 key "identifier"; 388 description 389 "An entry in this list represents a module implemented 390 by the server, as per RFC 7950 section 5.6.5, with a 391 particular set of supported features and deviations."; 392 reference 393 "RFC 7950: The YANG 1.1 Data Modeling Language."; 395 uses module-identification-leafs; 397 leaf namespace { 398 type inet:uri; 399 description 400 "The XML namespace identifier for this module. 401 This leaf is present in the model to keep the alignment 402 with 'ietf-yang-library'. Support of this leaf in 403 constrained devices is not required, nor expected."; 404 } 406 uses location-leaf-list; 408 list submodule { 409 key "identifier"; 410 description 411 "Each entry represents one submodule within the parent 412 module."; 413 uses module-identification-leafs; 414 uses location-leaf-list; 415 } 417 uses implementation-parameters; 418 } 419 list import-only-module { 420 key "identifier revision"; 421 description 422 "An entry in this list indicates that the server imports 423 reusable definitions from the specified revision of the 424 module, but does not implement any protocol accessible 425 objects from this revision. 427 Multiple entries for the same module name MAY exist. 428 This can occur if multiple modules import the same 429 module, but specify different revision-dates in the 430 import statements."; 432 leaf identifier { 433 type sid:sid; 434 description 435 "The YANG module name."; 436 } 437 leaf revision { 438 type union { 439 type revision-identifier; 440 type string { 441 length 0; 442 } 443 } 444 description 445 "The YANG module revision date."; 446 } 447 leaf namespace { 448 type inet:uri; 449 description 450 "The XML namespace identifier for this module. 451 This leaf is present in the model to keep the alignment 452 with 'ietf-yang-library'. Support of this leaf in 453 constrained devices is not required, nor expected."; 454 } 456 uses location-leaf-list; 458 list submodule { 459 key "identifier"; 460 description 461 "Each entry represents one submodule within the 462 parent module."; 464 uses module-identification-leafs; 465 uses location-leaf-list; 466 } 467 } 468 } 470 grouping yang-library-parameters { 471 description 472 "The YANG library data structure is represented as a grouping 473 so it can be reused in configuration or another monitoring 474 data structure."; 476 list module-set { 477 key index; 478 description 479 "A set of modules that may be used by one or more schemas. 481 A module set does not have to be referentially complete, 482 i.e., it may define modules that contain import statements 483 for other modules not included in the module set."; 485 uses module-set-parameters; 486 } 488 list schema { 489 key "index"; 490 description 491 "A datastore schema that may be used by one or more 492 datastores. 494 The schema must be valid and referentially complete, 495 i.e., it must contain modules to satisfy all used import 496 statements for all modules specified in the schema."; 498 leaf index { 499 type uint8; 500 description 501 "An arbitrary reference number assigned to the schema."; 502 } 503 leaf-list module-set { 504 type leafref { 505 path "../../module-set/index"; 506 } 507 description 508 "A set of module-sets that are included in this schema. 509 If a non import-only module appears in multiple module 510 sets, then the module revision and the associated 511 features and deviations must be identical."; 512 } 513 } 515 list datastore { 516 key "identifier"; 517 description 518 "A datastore supported by this server. 520 Each datastore indicates which schema it supports. 522 The server MUST instantiate one entry in this list 523 per specific datastore it supports. 525 Each datstore entry with the same datastore schema 526 SHOULD reference the same schema."; 528 leaf identifier { 529 type ds:datastore-ref; 530 description 531 "The identity of the datastore."; 532 } 533 leaf schema { 534 type leafref { 535 path "../../schema/index"; 536 } 537 mandatory true; 538 description 539 "A reference to the schema supported by this datastore. 540 All non import-only modules of the schema are 541 implementedwith their associated features and 542 deviations."; 543 } 544 } 545 } 547 /* 548 * Top-level container 549 */ 551 container yang-library { 552 config false; 553 description 554 "Container holding the entire YANG library of this server."; 556 uses yang-library-parameters; 558 leaf checksum { 559 type binary; 560 mandatory true; 561 description 562 "A server-generated checksum or digest of the contents of 563 the 'yang-library' tree. The server MUST change the 564 value of this leaf if the information represented by 565 the 'yang-library' tree, except 'yang-library/checksum', 566 has changed."; 567 } 568 } 570 /* 571 * Notifications 572 */ 574 notification yang-library-update { 575 description 576 "Generated when any YANG library information on the 577 server has changed."; 579 leaf checksum { 580 type leafref { 581 path "/yanglib:yang-library/yanglib:checksum"; 582 } 583 mandatory true; 584 description 585 "Contains the YANG library checksum or digest for the 586 updated YANG library at the time the notification is 587 generated."; 588 } 589 } 590 } 591 593 5. IANA Considerations 595 5.1. YANG Module Registry 597 This document registers one YANG module in the YANG Module Names 598 registry [RFC7950]. 600 name: ietf-constrained-yang-library 602 namespace: urn:ietf:params:xml:ns:yang:ietf-constrained-yang-library 604 prefix: lib 606 reference: RFC XXXX 608 // RFC Ed.: replace XXXX with RFC number and remove this note 610 6. Security Considerations 612 Some of the readable data nodes in this YANG module may be considered 613 sensitive or vulnerable in some network environments. It is thus 614 important to control read access to these data nodes. 616 Specifically, the 'module' list may help an attacker to identify the 617 server capabilities and server implementations with known bugs. 618 Server vulnerabilities may be specific to particular modules, module 619 revisions, module features, or even module deviations. This 620 information is included in each module entry. For example, if a 621 particular operation on a particular data node is known to cause a 622 server to crash or significantly degrade device performance, then the 623 module list information will help an attacker to identify server 624 implementations with such a defect, in order to launch a denial of 625 service attack on these devices. 627 7. Acknowledgments 629 The YANG module defined by this memo have been derived from an 630 already existing YANG module, ietf-yang-library [RFC8525], we will 631 like to thanks to the authors of this YANG module. A special thank 632 also to Andy Bierman for his initial recommendations for the creation 633 of this YANG module. 635 8. References 637 8.1. Normative References 639 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 640 Requirement Levels", BCP 14, RFC 2119, 641 DOI 10.17487/RFC2119, March 1997, 642 . 644 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 645 RFC 7950, DOI 10.17487/RFC7950, August 2016, 646 . 648 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 649 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 650 May 2017, . 652 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 653 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 654 . 656 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 657 and R. Wilton, "Network Management Datastore Architecture 658 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 659 . 661 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 662 and R. Wilton, "YANG Library", RFC 8525, 663 DOI 10.17487/RFC8525, March 2019, 664 . 666 8.2. Informative References 668 [I-D.ietf-core-sid] 669 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 670 iDentifier (SID)", draft-ietf-core-sid-07 (work in 671 progress), July 2019. 673 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 674 Constrained-Node Networks", RFC 7228, 675 DOI 10.17487/RFC7228, May 2014, 676 . 678 Authors' Addresses 680 Michel Veillette (editor) 681 Trilliant Networks Inc. 682 610 Rue du Luxembourg 683 Granby, Quebec J2J 2V2 684 Canada 686 Email: michel.veillette@trilliantinc.com 688 Ivaylo Petrov (editor) 689 Acklio 690 1137A avenue des Champs Blancs 691 Cesson-Sevigne, Bretagne 35510 692 France 694 Email: ivaylo@ackl.io