idnits 2.17.1 draft-veillette-core-cool-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 145 has weird spacing: '...-set-id uni...' == Line 152 has weird spacing: '...evision rev...' == Line 153 has weird spacing: '...ce-type enu...' == Line 156 has weird spacing: '...evision rev...' -- The document date (August 23, 2016) is 2796 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 (-18) exists of draft-ietf-netconf-restconf-16 Summary: 0 errors (**), 0 flaws (~~), 6 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 August 23, 2016 5 Expires: February 24, 2017 7 Constrained YANG Module Library 8 draft-veillette-core-cool-library-00 10 Abstract 12 This document describes a library, which provides information about 13 all YANG modules implemented by a CoOL server endpoint. A simple 14 caching mechanism is provided to minimize retrieval of this 15 information by CoOL clients. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on February 24, 2017. 34 Copyright Notice 36 Copyright (c) 2016 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 52 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 2 53 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3.1. Tree diagram . . . . . . . . . . . . . . . . . . . . . . 3 55 3.2. Description . . . . . . . . . . . . . . . . . . . . . . . 4 56 3.2.1. modules-state . . . . . . . . . . . . . . . . . . . . 4 57 3.2.2. modules-state/module-set-id . . . . . . . . . . . . . 4 58 3.2.3. modules-state/module . . . . . . . . . . . . . . . . 4 59 4. YANG Module "ietf-cool-library" . . . . . . . . . . . . . . . 5 60 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 61 5.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 10 62 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 63 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 64 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 65 8.1. Normative References . . . . . . . . . . . . . . . . . . 11 66 8.2. Informative References . . . . . . . . . . . . . . . . . 11 67 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 69 1. Introduction 71 The YANG module defined in this meno is available to CoOL clients to 72 discover the different YANG data models supported by a CoOL server 73 endpoint. The following YANG module information is needed by client 74 applications to fully utilize the YANG data modeling language: 76 o module list: The list of YANG modules implemented by the CoOL 77 server endpoint, each module is identified by its SID and 78 revision. 80 o submodule list: The list of YANG submodules included by each 81 module, each submodule is identified by its SID and revision. 83 o feature list: The list of features supported by each YANG module, 84 each feature is identified by its SID. 86 o deviation list: The list of YANG modules used for deviation 87 statements associated with each YANG module, each module is 88 identified by its SID and revision. 90 2. Terminology and Notation 92 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 93 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 94 document are to be interpreted as described in [RFC2119]. 96 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 98 o module 100 o submodule 102 o feature 104 o deviation 106 The following terms are defined in [I-D.somaraju-core-sid]: 108 o Structured IDentifier (SID) 110 The following terms are defined in [I-D.veillette-core-cool]: 112 o CoOL client 114 o CoOL server 116 o endpoint 118 The following terms are used within this document: 120 o library: a collection of YANG modules used by a server endpoint 122 3. Overview 124 The "ietf-cool-library" module provides information about the YANG 125 library used by a server endpoint. This module is defined using YANG 126 version 1, but it supports the description of YANG modules written in 127 any revision of YANG. 129 3.1. Tree diagram 131 A simplified graphical representation of the YANG module specified in 132 this document (ietf-cool-library) is provided below. The meaning of 133 the symbols in this diagram is as follows: 135 o Brackets "[" and "]" enclose list keys. 137 o Abbreviations before data node names: "rw" means configuration 138 data (read-write) and "ro" state data (read-only). 140 o Symbols after data node names: "?" means an optional node, "!" 141 means a presence container, and "*" denotes a list and leaf-list. 143 module: ietf-cool-library 144 +--ro modules-state 145 +--ro module-set-id union 146 +--ro module* [sid revision] 147 +--ro sid sid 148 +--ro revision revision 149 +--ro feature* sid 150 +--ro deviation* [sid revision] 151 | +--ro sid sid 152 | +--ro revision revision 153 +--ro conformance-type enumeration 154 +--ro submodule* [sid revision] 155 +--ro sid sid 156 +--ro revision revision 157 notifications: 158 +---n cool-library-change 159 +--ro module-set-id -> /modules-state/module-set-id 161 3.2. Description 163 3.2.1. modules-state 165 This mandatory container holds the module set identifier and the list 166 of modules supported by the server endpoint. 168 3.2.2. modules-state/module-set-id 170 This mandatory leaf contains an identifier representing the current 171 set of modules and submodules used by a server endpoint. This 172 identifier is endpoint-specific when implemented as unit32 or shared 173 between multiple endpoints on one or multiple servers when 174 implemented as identityref. The value of this leaf MUST change 175 whenever the set of modules and submodules in the library changes. 176 There is no requirement that the same set always results in the same 177 module-set-id value. 179 This leaf allows a client to fetch the module list once, cache it, 180 and only re-fetch it if the value of this leaf has been changed. 182 If the value of this leaf changes, the server also generates a "cool- 183 library-change" notification, with the new value of "module-set-id". 185 3.2.3. modules-state/module 187 This mandatory list contains one entry for each YANG module supported 188 by the server endpoint. There MUST be an entry in this list for each 189 revision of each YANG module that is used by the server. 191 4. YANG Module "ietf-cool-library" 193 RFC Ed.: update the date below with the date of RFC publication and 194 remove this note. 196 file "ietf-cool-library@2016-06-01.yang" 197 module ietf-cool-library { 198 namespace "urn:ietf:params:xml:ns:yang:ietf-cool-library"; 199 prefix "coollib"; 201 organization 202 "IETF CORE (Constrained RESTful Environments) Working Group"; 204 contact 205 "WG Web: 207 WG List: 209 WG Chair: Carsten Bormann 210 212 WG Chair: Jaime Jimenez 213 215 Editor: Michel Veillette 216 "; 218 description 219 "This module contains the list of YANG modules and submodules 220 implemented by a CoOL server endpoint. 222 Copyright (c) 2016 IETF Trust and the persons identified as 223 authors of the code. All rights reserved. 225 Redistribution and use in source and binary forms, with or 226 without modification, is permitted pursuant to, and subject 227 to the license terms contained in, the Simplified BSD License 228 set forth in Section 4.c of the IETF Trust's Legal Provisions 229 Relating to IETF Documents 230 (http://trustee.ietf.org/license-info). 232 This version of this YANG module is part of RFC XXXX; see 233 the RFC itself for full legal notices."; 235 // RFC Ed.: replace XXXX with actual RFC number and remove 236 // this note. 238 // RFC Ed.: update the date below with the date of the RFC 239 // publication and remove this note. 241 // RFC Ed.: update [I-D.somaraju-core-sid] with actual RFC 242 // number and remove this note. 244 revision 2016-06-01 { 245 description 246 "Initial revision."; 247 reference 248 "RFC XXXX: Contrained YANG Module Library."; 249 } 251 /* 252 * Typedefs 253 */ 255 typedef revision { 256 type binary { 257 length "4"; 258 } 259 description 260 "Revision date encoded as a binary string as follow: 261 - First byte = Century 262 - Second byte = Year (0 to 99) 263 - Third byte = Month (1 = January to 12 = december) 264 - Forth byte = Day (1 to 31)"; 265 } 267 typedef sid { 268 type uint32; 269 description 270 "Unique identifier assigned to different YANG items 271 such as data nodes, RPCs and actions, notifications, 272 modules, sub-modules, features and deviations. The SID 273 registration process is defined in 274 [I-D.somaraju-core-sid]."; 275 } 277 /* 278 * Groupings 279 */ 281 grouping identification-info { 282 description 283 "YANG modules and submodules identification information."; 285 leaf sid { 286 type sid; 287 mandatory true; 288 description 289 "SID assigned to this module or submodule."; 290 } 292 leaf revision { 293 type revision; 294 description 295 "Revision date assigned to this module or submodule. 296 A zero-length binary string is used if no revision statement 297 is present in the YANG module or submodule."; 298 } 299 } 301 identity module-set { 302 description 303 "Base identity from which shared module-set identifiers 304 are derived."; 305 } 307 /* 308 * Operational state data nodes 309 */ 311 container modules-state { 312 config false; 313 description 314 "Contain information about the different data models 315 implement by a CoOL endpoint."; 317 leaf module-set-id { 318 type union { 319 type uint32; 320 type identityref { 321 base "coollib:module-set"; 322 } 323 } 324 mandatory true; 325 description 326 "Identifier representing the current set of modules 327 and submodules listed in the 'module' list. This 328 identifier is endpoint-specific when implemented as 329 unit32 or shared between multiple endpoints on one 330 or multiple servers when implemented as identityref. 331 The server MUST change the value of this leaf each 332 time the information represented by the 'module' 333 list instance changes."; 334 } 335 list module { 336 key "sid revision"; 337 description 338 "Each entry represents one revision of one module 339 currently supported by the server endpoint."; 341 uses identification-info; 343 leaf-list feature { 344 type sid; 345 description 346 "List of YANG features from this module that are 347 supported by the server endpoint, regardless whether 348 they are defined in the module or any included 349 submodule."; 350 } 352 list deviation { 353 key "sid revision"; 354 description 355 "List of YANG deviation modules used by this server 356 endpoint to modify the conformance of the module 357 associated with this entry. Note that the same module 358 can be used for deviations for multiple modules, so the 359 same entry MAY appear within multiple 'module' entries. 361 The deviation module MUST be present in the 'module' 362 list, with the same sid and revision values. 363 The 'conformance-type' value will be 'implement' for 364 the deviation module."; 366 uses identification-info; 367 } 369 leaf conformance-type { 370 type enumeration { 371 enum implement { 372 value 0; 373 description 374 "Indicates that the server endpoint implements one or 375 more protocol-accessible objects defined in the YANG 376 module identified in this entry. This includes 377 deviation statements defined in the module. 379 For YANG version 1.1 modules, there is at most one 380 module entry with conformance type 'implement' for a 381 particular module, since YANG 1.1 requires that 382 at most one revision of a module is implemented. 384 For YANG version 1 modules, there SHOULD NOT be more 385 than one module entry for a particular module."; 386 } 387 enum import { 388 value 1; 389 description 390 "Indicates that the server endpoint imports reusable 391 definitions from the specified revision of the module, 392 but does not implement any protocol accessible objects 393 from this revision. 395 Multiple module entries for the same module MAY 396 exist. This can occur if multiple modules import the 397 same module, but specify different revision-dates in 398 the import statements."; 399 } 400 } 401 mandatory true; 402 description 403 "Indicates the type of conformance the server endpoint is 404 claiming for the YANG module identified by this entry."; 405 } 407 list submodule { 408 key "sid revision"; 409 description 410 "Each entry represents one submodule within the 411 parent module."; 412 uses identification-info; 413 } 414 } 415 } 417 /* 418 * Notifications 419 */ 421 notification cool-library-change { 422 description 423 "Generated when the set of modules and submodules supported 424 by the server endpoint has changed."; 426 leaf module-set-id { 427 type leafref { 428 path "/coollib:modules-state/coollib:module-set-id"; 429 } 430 mandatory true; 431 description 432 "Contains the module-set-id value representing the 433 set of modules and submodules supported at the server 434 endpoint at the time the notification is generated."; 435 } 436 } 437 } 438 440 5. IANA Considerations 442 5.1. YANG Module Registry 444 This document registers one YANG module in the YANG Module Names 445 registry [I-D.ietf-netmod-rfc6020bis]. 447 name: ietf-cool-library 449 namespace: urn:ietf:params:xml:ns:yang:ietf-cool-library 451 prefix: coollib 453 reference: RFC XXXX 455 // RFC Ed.: replace XXXX with RFC number and remove this note 457 6. Security Considerations 459 This YANG module is designed to be accessed via the CoOL protocol 460 [I-D.veillette-core-cool]. Some of the readable data nodes in this 461 YANG module may be considered sensitive or vulnerable in some network 462 environments. It is thus important to control read access to these 463 data nodes. 465 Specifically, the 'module' list may help an attacker identify the 466 server capabilities and server implementations with known bugs. 467 Server vulnerabilities may be specific to particular modules, module 468 revisions, module features, or even module deviations. This 469 information is included in each module entry. For example, if a 470 particular operation on a particular data node is known to cause a 471 server to crash or significantly degrade device performance, then the 472 module list information will help an attacker identify server 473 implementations with such a defect, in order to launch a denial of 474 service attack on the device. 476 7. Acknowledgments 478 The YANG module defined by this memo have been derived from an 479 already existing YANG module targeting the RESTconf protocol 480 [I-D.ietf-netconf-restconf]. We will like to thank the authors of 481 this prior work [I-D.ietf-netconf-yang-library] which have been 482 essential for the development of "ietf-cool-library" targeting the 483 Constrained Objects Language [I-D.veillette-core-cool] protocol. The 484 authors would also like to thank Andy Bierman for his recommendations 485 and his review of the resulting YANG module. 487 8. References 489 8.1. Normative References 491 [I-D.ietf-netmod-rfc6020bis] 492 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 493 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 494 2016. 496 [I-D.somaraju-core-sid] 497 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 498 Minaburo, "Structure Identifier (SID)", draft-somaraju- 499 core-sid-01 (work in progress), July 2016. 501 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 502 Requirement Levels", BCP 14, RFC 2119, 503 DOI 10.17487/RFC2119, March 1997, 504 . 506 8.2. Informative References 508 [I-D.ietf-netconf-restconf] 509 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 510 Protocol", draft-ietf-netconf-restconf-16 (work in 511 progress), August 2016. 513 [I-D.ietf-netconf-yang-library] 514 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 515 Library", draft-ietf-netconf-yang-library-06 (work in 516 progress), April 2016. 518 [I-D.veillette-core-cool] 519 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 520 Minaburo, "Constrained Objects Language", draft-veillette- 521 core-cool-02 (work in progress), July 2016. 523 Author's Address 525 Michel Veillette (editor) 526 Trilliant Networks Inc. 527 610 Rue du Luxembourg 528 Granby, Quebec J2J 2V2 529 Canada 531 Phone: +14503750556 532 Email: michel.veillette@trilliantinc.com