idnits 2.17.1 draft-ietf-core-sid-09.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 : ---------------------------------------------------------------------------- ** There are 11 instances of too long lines in the document, the longest one being 9 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 23, 2020) is 1548 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) == Missing Reference: 'DONE' is mentioned on line 1413, but not defined == Unused Reference: 'I-D.ietf-anima-constrained-voucher' is defined on line 788, but no explicit reference was found in the text == Outdated reference: A later version (-24) exists of draft-ietf-anima-constrained-voucher-07 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-08 Summary: 1 error (**), 0 flaws (~~), 5 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 A. Pelov, Ed. 5 Expires: July 26, 2020 I. Petrov, Ed. 6 Acklio 7 January 23, 2020 9 YANG Schema Item iDentifier (SID) 10 draft-ietf-core-sid-09 12 Abstract 14 YANG Schema Item iDentifiers (SID) are globally unique 63-bit 15 unsigned integers used to identify YANG items. This document defines 16 the semantics, the registration, and assignment processes of SIDs. 17 To enable the implementation of these processes, this document also 18 defines a file format used to persist and publish assigned SIDs. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on July 26, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 56 3. ".sid" file lifecycle . . . . . . . . . . . . . . . . . . . . 4 57 4. ".sid" file format . . . . . . . . . . . . . . . . . . . . . 5 58 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 59 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 60 6.1. Register SID File Format Module . . . . . . . . . . . . . 9 61 6.2. Create new IANA Registry: "SID Mega-Range" registry . . . 9 62 6.2.1. Structure . . . . . . . . . . . . . . . . . . . . . . 9 63 6.2.2. Allocation policy . . . . . . . . . . . . . . . . . . 10 64 6.2.2.1. First allocation . . . . . . . . . . . . . . . . 11 65 6.2.2.2. Consecutive allocations . . . . . . . . . . . . . 11 66 6.2.3. Initial contents of the Registry . . . . . . . . . . 11 67 6.3. Create a new IANA Registry: IETF SID Range Registry 68 (managed by IANA) . . . . . . . . . . . . . . . . . . . . 11 69 6.3.1. Structure . . . . . . . . . . . . . . . . . . . . . . 11 70 6.3.2. Allocation policy . . . . . . . . . . . . . . . . . . 11 71 6.3.3. Initial contents of the registry . . . . . . . . . . 13 72 6.4. Create new IANA Registry: "IETF SID Registry" . . . . . . 14 73 6.4.1. Structure . . . . . . . . . . . . . . . . . . . . . . 14 74 6.4.2. Allocation policy . . . . . . . . . . . . . . . . . . 14 75 6.4.3. Recursive Allocation of SID Range at Document 76 Adoption . . . . . . . . . . . . . . . . . . . . . . 15 77 6.4.4. Initial contents of the registry . . . . . . . . . . 16 78 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 79 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 80 8.1. Normative References . . . . . . . . . . . . . . . . . . 17 81 8.2. Informative References . . . . . . . . . . . . . . . . . 17 82 Appendix A. ".sid" file example . . . . . . . . . . . . . . . . 18 83 Appendix B. SID auto generation . . . . . . . . . . . . . . . . 27 84 Appendix C. ".sid" file lifecycle . . . . . . . . . . . . . . . 28 85 C.1. SID File Creation . . . . . . . . . . . . . . . . . . . . 28 86 C.2. SID File Update . . . . . . . . . . . . . . . . . . . . . 29 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 89 1. Introduction 91 Some of the items defined in YANG [RFC7950] require the use of a 92 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 93 these identifiers are implemented using names. To allow the 94 implementation of data models defined in YANG in constrained devices 95 and constrained networks, a more compact method to identify YANG 96 items is required. This compact identifier, called SID, is encoded 97 using a 63-bit unsigned integer. The limitation to 63-bit unsigned 98 integers allows SIDs to be manipulated more easily on platforms that 99 might otherwise lack native 64-bit unsigned arithmetic. The loss of 100 a single bit of range is not significant given the size of the 101 remaining space. 103 The following items are identified using SIDs: 105 o identities 107 o data nodes (Note: including those parts of a YANG template as 108 defined by the 'yang-data' extension.) 110 o RPCs and associated input(s) and output(s) 112 o actions and associated input(s) and output(s) 114 o notifications and associated information 116 o YANG modules, submodules and features 118 SIDs are globally unique integers, a registration system is used in 119 order to guarantee their uniqueness. SIDs are registered in blocks 120 called "SID ranges". 122 Assignment of SIDs to YANG items can be automated. For more details 123 how this could be achieved, please consult Appendix B. 125 SIDs are assigned permanently, items introduced by a new revision of 126 a YANG module are added to the list of SIDs already assigned. 128 Section 3 provides more details about the registration process of 129 YANG modules and associated SIDs. To enable the implementation of 130 this registry, Section 4 defines a standard file format used to store 131 and publish SIDs. 133 2. Terminology and Notation 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 137 "OPTIONAL" in this document are to be interpreted as described in BCP 138 14 [RFC2119] [RFC8174] when, and only when, they appear in all 139 capitals, as shown here. 141 The following terms are defined in [RFC7950]: 143 o action 144 o feature 146 o module 148 o notification 150 o RPC 152 o schema node 154 o schema tree 156 o submodule 158 The following term is defined in [RFC8040]: 160 o yang-data extension 162 This specification also makes use of the following terminology: 164 o item: A schema node, an identity, a module, a submodule or a 165 feature defined using the YANG modeling language. 167 o path: A path is a string that identifies a schema node within the 168 schema tree. A path consists of the list of schema node 169 identifier(s) separated by slashes ("/"). Schema node 170 identifier(s) are always listed from the top-level schema node up 171 to the targeted schema node. (e.g. "/ietf-system:system- 172 state/clock/current-datetime") 174 o YANG Schema Item iDentifier (SID): Unsigned integer used to 175 identify different YANG items. 177 3. ".sid" file lifecycle 179 YANG is a language designed to model data accessed using one of the 180 compatible protocols (e.g. NETCONF [RFC6241], RESCONF [RFC8040] and 181 CoRECONF [I-D.ietf-core-comi]). A YANG module defines hierarchies of 182 data, including configuration, state data, RPCs, actions and 183 notifications. 185 Many YANG modules are not created in the context of constrained 186 applications. YANG modules can be implemented using NETCONF 187 [RFC6241] or RESTCONF [RFC8040] without the need to assign SIDs. 189 As needed, authors of YANG modules can assign SIDs to their YANG 190 modules. In order to do that, they should first obtain a SID range 191 from a registry and use that range to assign or generate SIDs to 192 items of their YANG module. For example how this could be achieved, 193 please refer to Appendix C. 195 Registration of the .sid file associated to a YANG module is optional 196 but recommended to promote interoperability between devices and to 197 avoid duplicate allocation of SIDs to a single YANG module. 198 Different registries might have different requirements for the 199 registration and publication of the ".sid" files. For diagram of one 200 of the possibilities, please refer to the activity diagram on 201 Figure 1 in Appendix C. 203 Each time a YANG module or one of its imported module(s) or included 204 sub-module(s) is updated, the ".sid" file MAY need to be updated. 205 This update SHOULD be performed using an automated tool. 207 If a new revision requires more SIDs than initially allocated, a new 208 SID range MUST be added to the 'assignment-ranges' as defined in 209 Section 4. These extra SIDs are used for subsequent assignments. 211 For an example of this update process, see activity diagram Figure 2 212 in Appendix C. 214 4. ".sid" file format 216 ".sid" files are used to persist and publish SIDs assigned to the 217 different YANG items of a specific YANG module. The following YANG 218 module defined the structure of this file, encoding is performed 219 using the rules defined in [RFC7951]. 221 file "ietf-sid-file@2017-11-26.yang" 222 module ietf-sid-file { 223 namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file"; 224 prefix sid; 226 import ietf-yang-types { 227 prefix yang; 228 } 230 organization 231 "IETF Core Working Group"; 233 contact 234 "Michel Veillette 235 237 Andy Bierman 238 239 Alexander Pelov 240 "; 242 description 243 "This module defines the structure of the .sid files. 245 Each .sid file contains the mapping between the different 246 string identifiers defined by a YANG module and a 247 corresponding numeric value called SID."; 249 revision 2017-11-26 { 250 description 251 "Initial revision."; 252 reference 253 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 254 } 256 typedef revision-identifier { 257 type string { 258 pattern '\d{4}-\d{2}-\d{2}'; 259 } 260 description 261 "Represents a date in YYYY-MM-DD format."; 262 } 264 typedef sid { 265 type uint64; 266 description 267 "YANG Schema Item iDentifier"; 268 reference 269 "[I-D.ietf-core-sid] YANG Schema Item iDentifier (SID)"; 270 } 272 typedef schema-node-path { 273 type string { 274 pattern 275 '/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' + 276 '(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*'; 277 } 278 description 279 "Identifies a schema-node path string for use in the 280 SID registry. This string format follows the rules 281 for an instance-identifier, as defined in RFC 7959, 282 except that no predicates are allowed. 284 This format is intended to support the YANG 1.1 ABNF 285 for a schema node identifier, except module names 286 are used instead of prefixes, as specified in RFC 7951."; 288 reference 289 "RFC 7950, The YANG 1.1 Data Modeling Language; 290 Section 6.5: Schema Node Identifier; 291 RFC 7951, JSON Encoding of YANG Data; 292 Section 6.11: The instance-identifier type"; 293 } 295 leaf module-name { 296 type yang:yang-identifier; 297 description 298 "Name of the YANG module associated with this .sid file."; 299 } 301 leaf module-revision { 302 type revision-identifier; 303 description 304 "Revision of the YANG module associated with this .sid file. 305 This leaf is not present if no revision statement is 306 defined in the YANG module."; 307 } 309 list assigment-ranges { 310 key "entry-point"; 311 description 312 "SID range(s) allocated to the YANG module identified by 313 'module-name' and 'module-revision'."; 315 leaf entry-point { 316 type sid; 317 mandatory true; 318 description 319 "Lowest SID available for assignment."; 320 } 322 leaf size { 323 type uint64; 324 mandatory true; 325 description 326 "Number of SIDs available for assignment."; 327 } 328 } 330 list items { 331 key "namespace identifier"; 332 description 333 "Each entry within this list defined the mapping between 334 a YANG item string identifier and a SID. This list MUST 335 include a mapping entry for each YANG item defined by 336 the YANG module identified by 'module-name' and 337 'module-revision'."; 339 leaf namespace { 340 type enumeration { 341 enum module { 342 value 0; 343 description 344 "All module and submodule names share the same 345 global module identifier namespace."; 346 } 347 enum identity { 348 value 1; 349 description 350 "All identity names defined in a module and its 351 submodules share the same identity identifier 352 namespace."; 353 } 354 enum feature { 355 value 2; 356 description 357 "All feature names defined in a module and its 358 submodules share the same feature identifier 359 namespace."; 360 } 361 enum data { 362 value 3; 363 description 364 "The namespace for all data nodes, as defined in YANG."; 365 } 366 } 367 description 368 "Namespace of the YANG item for this mapping entry."; 369 } 371 leaf identifier { 372 type union { 373 type yang:yang-identifier; 374 type schema-node-path; 375 } 376 description 377 "String identifier of the YANG item for this mapping entry. 379 If the corresponding 'namespace' field is 'module', 380 'feature', or 'identity', then this field MUST 381 contain a valid YANG identifier string. 383 If the corresponding 'namespace' field is 'data', 384 then this field MUST contain a valid schema node 385 path."; 386 } 388 leaf sid { 389 type sid; 390 mandatory true; 391 description 392 "SID assigned to the YANG item for this mapping entry."; 393 } 394 } 395 } 396 398 5. Security Considerations 400 This document defines a new type of identifier used to encode data 401 models defined in YANG [RFC7950]. As such, this identifier does not 402 contribute to any new security issues in addition of those identified 403 for the specific protocols or contexts for which it is used. 405 6. IANA Considerations 407 6.1. Register SID File Format Module 409 This document registers one YANG module in the "YANG Module Names" 410 registry [RFC6020]: 412 o name: ietf-sid-file 414 o namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file 416 o prefix: sid 418 o reference: [[THISRFC]] 420 6.2. Create new IANA Registry: "SID Mega-Range" registry 422 The name of this registry is "SID Mega-Range". This registry is used 423 to record the delegation of the management of a block of SIDs to 424 third parties (such as SDOs or registrars). 426 6.2.1. Structure 428 Each entry in this registry must include: 430 o The entry point (first SID) of the registered SID block. 432 o The size of the registered SID block. The size MUST be one 433 million (1 000 000) SIDs. 435 o The contact information of the requesting organization including: 437 * The policy of SID range allocations: Public, Private or Both. 439 * Organization name 441 * URL 443 The information associated to the Organization name should not be 444 publicly visible in the registry, but should be available. This 445 information includes contact email and phone number and change 446 controller email and phone number. 448 6.2.2. Allocation policy 450 The IANA policy for future additions to this registry is "Expert 451 Review" [RFC8126]. 453 An organization requesting to manage a SID Range (and thus have an 454 entry in the SID Mega-Range Registry), must ensure the following 455 capacities: 457 o The capacity to manage and operate a SID Range Registry. A SID 458 Range Registry MUST provide the following information for all SID 459 Ranges allocated by the Registry: 461 * Entry Point of allocated SID Range 463 * Size of allocated SID Range 465 * Type: Public or Private 467 + Public Ranges MUST include at least a reference to the YANG 468 module and ".sid" files for that SID Range. 470 + Private Ranges MUST be marked as "Private" 472 o A Policy of allocation, which clearly identifies if the SID Range 473 allocations would be Private, Public or Both. 475 o Technical capacity to ensure the sustained operation of the 476 registry for a period of at least 5 years. If Private 477 Registrations are allowed, the period must be of at least 10 478 years. 480 6.2.2.1. First allocation 482 For a first allocation to be provided, the requesting organization 483 must demonstrate a functional registry infrastructure. 485 6.2.2.2. Consecutive allocations 487 On subsequent allocation request(s), the organization must 488 demonstrate the exhaustion of the prior range. These conditions need 489 to be asserted by the assigned expert(s). 491 If that extra-allocation is done within 3 years from the last 492 allocation, the experts need to discuss this request on the CORE 493 working group mailing list and consensus needs to be obtained before 494 allocating a new Mega-Range. 496 6.2.3. Initial contents of the Registry 498 The initial entry in this registry is allocated to IANA: 500 +-------------+---------+------------+-------------------+----------+ 501 | Entry Point | Size | Allocation | Organization name | URL | 502 +-------------+---------+------------+-------------------+----------+ 503 | 0 | 1000000 | Public | IANA | iana.org | 504 +-------------+---------+------------+-------------------+----------+ 506 6.3. Create a new IANA Registry: IETF SID Range Registry (managed by 507 IANA) 509 6.3.1. Structure 511 Each entry in this registry must include: 513 o The SID range entry point. 515 o The SID range size. 517 o The YANG module name. 519 o Document reference. 521 6.3.2. Allocation policy 523 The first million SIDs assigned to IANA is sub-divided as follows: 525 o The range of 0 to 999 (size 1000) is "Reserved" as defined in 526 [RFC8126]. 528 o The range of 1000 to 59,999 (size 59,000) is reserved for YANG 529 modules defined in RFCs. The IANA policy for additions to this 530 registry is "Expert Review" [RFC8126]. 532 * The Expert MUST verify that the YANG module for which this 533 allocation is made has an RFC (existing RFC) OR is on track to 534 become RFC (early allocation with a request from the WG chairs 535 as defined by [RFC7120]). 537 o The SID range allocated for a YANG module can follow in one of the 538 four categories: 540 * SMALL (50 SIDs) 542 * MEDIUM (100 SIDs) 544 * LARGE (250 SIDs) 546 * CUSTOM (requested by the YANG module author, with a maximum of 547 1000 SIDs). In all cases, the size of a SID range assigned to 548 a YANG module should be at least 33% above the current number 549 of YANG items. This headroom allows assignment within the same 550 range of new YANG items introduced by subsequent revisions. A 551 larger SID range size may be requested by the authors if this 552 recommendation is considered insufficient. It is important to 553 note that an additional SID range can be allocated to an 554 existing YANG module if the initial range is exhausted. 556 o The range of 60,000 to 99,999 (size 40,000)is reserved for 557 experimental YANG modules. This range MUST NOT be used in 558 operational deployments since these SIDs are not globally unique 559 which limit their interoperability. The IANA policy for this 560 range is "Experimental use" [RFC8126]. 562 o The range of 100,000 to 999,999 (size 900,000) is "Reserved" as 563 defined in [RFC8126]. 565 +-------------+---------+------------------+ 566 | Entry Point | Size | IANA policy | 567 +-------------+---------+------------------+ 568 | 0 | 1,000 | Reserved | 569 | 1,000 | 59,000 | Expert Review | 570 | 60,000 | 40,000 | Experimental use | 571 | 100,000 | 900,000 | Reserved | 572 +-------------+---------+------------------+ 574 6.3.3. Initial contents of the registry 576 Initial entries in this registry are as follows: 578 +-----+-----+--------------------------+----------------------------+ 579 | Ent | Siz | Module name | Document reference | 580 | ry | e | | | 581 | Poi | | | | 582 | nt | | | | 583 +-----+-----+--------------------------+----------------------------+ 584 | 100 | 100 | ietf-comi | [I-D.ietf-core-comi] | 585 | 0 | | | | 586 | 110 | 50 | ietf-yang-types | [RFC6991] | 587 | 0 | | | | 588 | 115 | 50 | ietf-inet-types | [RFC6991] | 589 | 0 | | | | 590 | 120 | 50 | iana-crypt-hash | [RFC7317] | 591 | 0 | | | | 592 | 125 | 50 | ietf-netconf-acm | [RFC8341] | 593 | 0 | | | | 594 | 130 | 50 | ietf-sid-file | RFCXXXX | 595 | 0 | | | | 596 | 150 | 100 | ietf-interfaces | [RFC8343] | 597 | 0 | | | | 598 | 160 | 100 | ietf-ip | [RFC8344] | 599 | 0 | | | | 600 | 170 | 100 | ietf-system | [RFC7317] | 601 | 0 | | | | 602 | 180 | 400 | iana-if-type | [RFC7224] | 603 | 0 | | | | 604 | 240 | 50 | ietf-voucher | [RFC8366] | 605 | 0 | | | | 606 | 245 | 50 | ietf-constrained-voucher | [I-D.ietf-anima-constraine | 607 | 0 | | | d-voucher] | 608 | 250 | 50 | ietf-constrained- | [I-D.ietf-anima-constraine | 609 | 0 | | voucher-request | d-voucher] | 610 +-----+-----+--------------------------+----------------------------+ 612 // RFC Ed.: replace XXXX with RFC number assigned to this draft. 614 For allocation, RFC publication of the YANG module is required as per 615 [RFC8126]. The YANG module must be registered in the "YANG module 616 Name" registry according to the rules specified in section 14 of 617 [RFC6020]. 619 6.4. Create new IANA Registry: "IETF SID Registry" 621 The name of this registry is "IETF SID Registry". This registry is 622 used to record the allocation of SIDs for individual YANG module 623 items. 625 6.4.1. Structure 627 Each entry in this registry must include: 629 o The YANG module name. This module name must be present in the 630 "Name" column of the "YANG Module Names" registry. 632 o A link to the associated ".yang" file. This file link must be 633 present in the "File" column of the "YANG Module Names" registry. 635 o The link to the ".sid" file which defines the allocation. The 636 ".sid" file is stored by IANA. 638 o The number of actually allocated SIDs in the ".sid" file. 640 6.4.2. Allocation policy 642 The allocation policy is Expert review. The Expert MUST ensure that 643 the following conditions are met: 645 o The ".sid" file has a valid structure: 647 * The ".sid" file MUST be a valid JSON file following the 648 structure of the module defined in RFCXXXX (RFC Ed: replace XXX 649 with RFC number assigned to this draft). 651 o The ".sid" file allocates individual SIDs ONLY in the SID Ranges 652 for this YANG module (as allocated in the IETF SID Range 653 Registry): 655 * All SIDs in this ".sid" file MUST be within the ranges 656 allocated to this YANG module in the "IETF SID Range Registry". 658 o If another ".sid" file has already allocated SIDs for this YANG 659 module (e.g. for older or newer versions of the YANG module), the 660 YANG items are assigned the same SIDs as in the the other ".sid" 661 file. 663 o SIDs never change. 665 6.4.3. Recursive Allocation of SID Range at Document Adoption 667 Due to the difficulty in changing SID values during IETF document 668 processing, it is expected that most documents will ask for SID 669 allocations using Early Allocations [RFC7120]. The details of the 670 Early Allocation should be included in any Working Group Adoption 671 call. Prior to Working Group Adoption, an internet draft authors can 672 use the experimental SID range (as per Section 6.3.2) for their SIDs 673 allocations or other values that do not create ambiguity with other 674 SID uses (for example they can use a range that comes from a non-IANA 675 managed "SID Mega-Range" registry). 677 After Working Group Adoption, any modification of a .sid file is 678 expected to be discussed on the mailing list of the appropriate 679 Working Groups. Specific attention should be paid to implementers' 680 opinion after Working Group Last Call if a SID value is to change its 681 meaning. In all cases, a .sid file and the SIDs associated with it 682 are subject to change before the publication of an internet draft as 683 an RFC. 685 During the early use of SIDs, many existing, previously published 686 YANG modules will not have SID allocations. For an allocation to be 687 useful the included YANG modules may also need to have SID 688 allocations made. 690 The Expert Reviewer who performs the (Early) Allocation analysis will 691 need to go through the list of included YANG modules and perform SID 692 allocations for those modules as well. 694 o If the document is a published RFC, then the allocation of SIDs 695 for its referenced YANG modules is permanent. The Expert Reviewer 696 provides the generated SID file to IANA for registration. This 697 process may be time consuming during a bootstrap period (there are 698 over 100 YANG modules to date, none of which have SID 699 allocations), but should quiet down once needed entries are 700 allocated. 702 o If the document is an unprocessed Internet-Draft adopted in a WG, 703 then an Early Allocation is performed for this document as well. 704 Early Allocations require approval by an IESG Area Director. An 705 early allocation which requires additional allocations will list 706 the other allocations in it's description, and will be cross- 707 posted to the any other working group mailing lists. 709 o A YANG module which references a module in an document which has 710 not yet been adopted by any working group will be unable to 711 perform an Early Allocation for that other document until it is 712 adopted by a working group. As described in [RFC7120], an AD 713 Sponsored document acts as if it had a working group. The 714 approving AD may also exempt a document from this policy by 715 agreeing to AD Sponsor the document. 717 Critically, the original document should never get through the IETF 718 process and then be surprised to be referencing a document whose 719 progress is not certain. 721 A previously SID-allocated YANG module which changes its references 722 to include a YANG module for which there is no SID allocation needs 723 to repeat the Early Allocation process. 725 Early Allocations are made with a one-year period, after which they 726 are expired. [RFC7120] indicates that at most one renewal may be 727 made. For the SID allocation a far more lenient stance is desired. 729 1. An extension of a referencing documents Early Allocation should 730 update any referenced Early Allocations to expire no sooner than 731 the referencing document. 733 2. The [RFC7120] mechanism allows the IESG to provide a second 734 renewal, and such an event may prompt some thought about how the 735 collection of documents are being processed. 737 This is driven by the very generous size of the SID space and the 738 often complex and deep dependencies of YANG modules. Often a core 739 module with many dependencies will undergo extensive review, delaying 740 the publication of other documents. 742 [RFC7120] also says 744 Note that if a document is submitted for review to the IESG and at 745 the time of submission some early allocations are valid (not 746 expired), these allocations should not be expired while the document 747 is under IESG consideration or waiting in the RFC Editor's queue 748 after approval by the IESG. 750 6.4.4. Initial contents of the registry 752 None. 754 7. Acknowledgments 756 The authors would like to thank Andy Bierman, Carsten Bormann, 757 Michael Richardson, Abhinav Somaraju, Peter van der Stok, Laurent 758 Toutain and Randy Turner for their help during the development of 759 this document and their useful comments during the review process. 761 8. References 763 8.1. Normative References 765 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 766 Requirement Levels", BCP 14, RFC 2119, 767 DOI 10.17487/RFC2119, March 1997, 768 . 770 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 771 Points", BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 772 2014, . 774 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 775 RFC 7950, DOI 10.17487/RFC7950, August 2016, 776 . 778 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 779 RFC 7951, DOI 10.17487/RFC7951, August 2016, 780 . 782 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 783 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 784 May 2017, . 786 8.2. Informative References 788 [I-D.ietf-anima-constrained-voucher] 789 Richardson, M., Stok, P., and P. Kampanakis, "Constrained 790 Voucher Artifacts for Bootstrapping Protocols", draft- 791 ietf-anima-constrained-voucher-07 (work in progress), 792 January 2020. 794 [I-D.ietf-core-comi] 795 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 796 Petrov, "CoAP Management Interface", draft-ietf-core- 797 comi-08 (work in progress), September 2019. 799 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 800 the Network Configuration Protocol (NETCONF)", RFC 6020, 801 DOI 10.17487/RFC6020, October 2010, 802 . 804 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 805 and A. Bierman, Ed., "Network Configuration Protocol 806 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 807 . 809 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 810 RFC 6991, DOI 10.17487/RFC6991, July 2013, 811 . 813 [RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", 814 RFC 7224, DOI 10.17487/RFC7224, May 2014, 815 . 817 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 818 System Management", RFC 7317, DOI 10.17487/RFC7317, August 819 2014, . 821 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 822 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 823 . 825 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 826 Writing an IANA Considerations Section in RFCs", BCP 26, 827 RFC 8126, DOI 10.17487/RFC8126, June 2017, 828 . 830 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 831 Access Control Model", STD 91, RFC 8341, 832 DOI 10.17487/RFC8341, March 2018, 833 . 835 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 836 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 837 . 839 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 840 RFC 8344, DOI 10.17487/RFC8344, March 2018, 841 . 843 [RFC8366] Watsen, K., Richardson, M., Pritikin, M., and T. Eckert, 844 "A Voucher Artifact for Bootstrapping Protocols", 845 RFC 8366, DOI 10.17487/RFC8366, May 2018, 846 . 848 Appendix A. ".sid" file example 850 The following .sid file (ietf-system@2014-08-06.sid) have been 851 generated using the following yang modules: 853 o ietf-system@2014-08-06.yang 855 o ietf-yang-types@2013-07-15.yang 856 o ietf-inet-types@2013-07-15.yang 858 o ietf-netconf-acm@2012-02-22.yang 860 o iana-crypt-hash@2014-04-04.yang 862 { 863 "assignment-ranges": [ 864 { 865 "entry-point": 1700, 866 "size": 100 867 } 868 ], 869 "module-name": "ietf-system", 870 "module-revision": "2014-08-06", 871 "items": [ 872 { 873 "namespace": "module", 874 "identifier": "ietf-system", 875 "sid": 1700 876 }, 877 { 878 "namespace": "identity", 879 "identifier": "authentication-method", 880 "sid": 1701 881 }, 882 { 883 "namespace": "identity", 884 "identifier": "local-users", 885 "sid": 1702 886 }, 887 { 888 "namespace": "identity", 889 "identifier": "radius", 890 "sid": 1703 891 }, 892 { 893 "namespace": "identity", 894 "identifier": "radius-authentication-type", 895 "sid": 1704 896 }, 897 { 898 "namespace": "identity", 899 "identifier": "radius-chap", 900 "sid": 1705 901 }, 902 { 903 "namespace": "identity", 904 "identifier": "radius-pap", 905 "sid": 1706 906 }, 907 { 908 "namespace": "feature", 909 "identifier": "authentication", 910 "sid": 1707 911 }, 912 { 913 "namespace": "feature", 914 "identifier": "dns-udp-tcp-port", 915 "sid": 1708 916 }, 917 { 918 "namespace": "feature", 919 "identifier": "local-users", 920 "sid": 1709 921 }, 922 { 923 "namespace": "feature", 924 "identifier": "ntp", 925 "sid": 1710 926 }, 927 { 928 "namespace": "feature", 929 "identifier": "ntp-udp-port", 930 "sid": 1711 931 }, 932 { 933 "namespace": "feature", 934 "identifier": "radius", 935 "sid": 1712 936 }, 937 { 938 "namespace": "feature", 939 "identifier": "radius-authentication", 940 "sid": 1713 941 }, 942 { 943 "namespace": "feature", 944 "identifier": "timezone-name", 945 "sid": 1714 946 }, 947 { 948 "namespace": "data", 949 "identifier": "/ietf-system:set-current-datetime", 950 "sid": 1715 951 }, 952 { 953 "namespace": "data", 954 "identifier": "/ietf-system:set-current-datetime/ 955 current-datetime", 956 "sid": 1716 957 }, 958 { 959 "namespace": "data", 960 "identifier": "/ietf-system:system", 961 "sid": 1717 962 }, 963 { 964 "namespace": "data", 965 "identifier": "/ietf-system:system-restart", 966 "sid": 1718 967 }, 968 { 969 "namespace": "data", 970 "identifier": "/ietf-system:system-shutdown", 971 "sid": 1719 972 }, 973 { 974 "namespace": "data", 975 "identifier": "/ietf-system:system-state", 976 "sid": 1720 977 }, 978 { 979 "namespace": "data", 980 "identifier": "/ietf-system:system-state/clock", 981 "sid": 1721 982 }, 983 { 984 "namespace": "data", 985 "identifier": "/ietf-system:system-state/clock/boot-datetime", 986 "sid": 1722 987 }, 988 { 989 "namespace": "data", 990 "identifier": "/ietf-system:system-state/clock/ 991 current-datetime", 992 "sid": 1723 993 }, 994 { 995 "namespace": "data", 996 "identifier": "/ietf-system:system-state/platform", 997 "sid": 1724 998 }, 999 { 1000 "namespace": "data", 1001 "identifier": "/ietf-system:system-state/platform/machine", 1002 "sid": 1725 1003 }, 1004 { 1005 "namespace": "data", 1006 "identifier": "/ietf-system:system-state/platform/os-name", 1007 "sid": 1726 1008 }, 1009 { 1010 "namespace": "data", 1011 "identifier": "/ietf-system:system-state/platform/os-release", 1012 "sid": 1727 1013 }, 1014 { 1015 "namespace": "data", 1016 "identifier": "/ietf-system:system-state/platform/os-version", 1017 "sid": 1728 1018 }, 1019 { 1020 "namespace": "data", 1021 "identifier": "/ietf-system:system/authentication", 1022 "sid": 1729 1023 }, 1024 { 1025 "namespace": "data", 1026 "identifier": "/ietf-system:system/authentication/user", 1027 "sid": 1730 1028 }, 1029 { 1030 "namespace": "data", 1031 "identifier": "/ietf-system:system/authentication/ 1032 user-authentication-order", 1033 "sid": 1731 1034 }, 1035 { 1036 "namespace": "data", 1037 "identifier": "/ietf-system:system/authentication/user/ 1038 authorized-key", 1039 "sid": 1732 1040 }, 1041 { 1042 "namespace": "data", 1043 "identifier": "/ietf-system:system/authentication/user/ 1044 authorized-key/algorithm", 1045 "sid": 1733 1046 }, 1047 { 1048 "namespace": "data", 1049 "identifier": "/ietf-system:system/authentication/user/ 1050 authorized-key/key-data", 1051 "sid": 1734 1052 }, 1053 { 1054 "namespace": "data", 1055 "identifier": "/ietf-system:system/authentication/user/ 1056 authorized-key/name", 1057 "sid": 1735 1058 }, 1059 { 1060 "namespace": "data", 1061 "identifier": "/ietf-system:system/authentication/user/ 1062 name", 1063 "sid": 1736 1064 }, 1065 { 1066 "namespace": "data", 1067 "identifier": "/ietf-system:system/authentication/user/ 1068 password", 1069 "sid": 1737 1070 }, 1071 { 1072 "namespace": "data", 1073 "identifier": "/ietf-system:system/clock", 1074 "sid": 1738 1075 }, 1076 { 1077 "namespace": "data", 1078 "identifier": "/ietf-system:system/clock/timezone-name", 1079 "sid": 1739 1080 }, 1081 { 1082 "namespace": "data", 1083 "identifier": "/ietf-system:system/clock/timezone-utc-offset", 1084 "sid": 1740 1085 }, 1086 { 1087 "namespace": "data", 1088 "identifier": "/ietf-system:system/contact", 1089 "sid": 1741 1090 }, 1091 { 1092 "namespace": "data", 1093 "identifier": "/ietf-system:system/dns-resolver", 1094 "sid": 1742 1095 }, 1096 { 1097 "namespace": "data", 1098 "identifier": "/ietf-system:system/dns-resolver/options", 1099 "sid": 1743 1100 }, 1101 { 1102 "namespace": "data", 1103 "identifier": "/ietf-system:system/dns-resolver/options/ 1104 attempts", 1105 "sid": 1744 1106 }, 1107 { 1108 "namespace": "data", 1109 "identifier": "/ietf-system:system/dns-resolver/options/ 1110 timeout", 1111 "sid": 1745 1112 }, 1113 { 1114 "namespace": "data", 1115 "identifier": "/ietf-system:system/dns-resolver/search", 1116 "sid": 1746 1117 }, 1118 { 1119 "namespace": "data", 1120 "identifier": "/ietf-system:system/dns-resolver/server", 1121 "sid": 1747 1122 }, 1123 { 1124 "namespace": "data", 1125 "identifier": "/ietf-system:system/dns-resolver/server/name", 1126 "sid": 1748 1127 }, 1128 { 1129 "namespace": "data", 1130 "identifier": "/ietf-system:system/dns-resolver/server/ 1131 udp-and-tcp", 1132 "sid": 1749 1133 }, 1134 { 1135 "namespace": "data", 1136 "identifier": "/ietf-system:system/dns-resolver/server/ 1137 udp-and-tcp/address", 1138 "sid": 1750 1139 }, 1140 { 1141 "namespace": "data", 1142 "identifier": "/ietf-system:system/dns-resolver/server/ 1143 udp-and-tcp/port", 1145 "sid": 1751 1146 }, 1147 { 1148 "namespace": "data", 1149 "identifier": "/ietf-system:system/hostname", 1150 "sid": 1752 1151 }, 1152 { 1153 "namespace": "data", 1154 "identifier": "/ietf-system:system/location", 1155 "sid": 1753 1156 }, 1157 { 1158 "namespace": "data", 1159 "identifier": "/ietf-system:system/ntp", 1160 "sid": 1754 1161 }, 1162 { 1163 "namespace": "data", 1164 "identifier": "/ietf-system:system/ntp/enabled", 1165 "sid": 1755 1166 }, 1167 { 1168 "namespace": "data", 1169 "identifier": "/ietf-system:system/ntp/server", 1170 "sid": 1756 1171 }, 1172 { 1173 "namespace": "data", 1174 "identifier": "/ietf-system:system/ntp/server/ 1175 association-type", 1176 "sid": 1757 1177 }, 1178 { 1179 "namespace": "data", 1180 "identifier": "/ietf-system:system/ntp/server/iburst", 1181 "sid": 1758 1182 }, 1183 { 1184 "namespace": "data", 1185 "identifier": "/ietf-system:system/ntp/server/name", 1186 "sid": 1759 1187 }, 1188 { 1189 "namespace": "data", 1190 "identifier": "/ietf-system:system/ntp/server/prefer", 1191 "sid": 1760 1192 }, 1193 { 1194 "namespace": "data", 1195 "identifier": "/ietf-system:system/ntp/server/udp", 1196 "sid": 1761 1197 }, 1198 { 1199 "namespace": "data", 1200 "identifier": "/ietf-system:system/ntp/server/udp/address", 1201 "sid": 1762 1202 }, 1203 { 1204 "namespace": "data", 1205 "identifier": "/ietf-system:system/ntp/server/udp/port", 1206 "sid": 1763 1207 }, 1208 { 1209 "namespace": "data", 1210 "identifier": "/ietf-system:system/radius", 1211 "sid": 1764 1212 }, 1213 { 1214 "namespace": "data", 1215 "identifier": "/ietf-system:system/radius/options", 1216 "sid": 1765 1217 }, 1218 { 1219 "namespace": "data", 1220 "identifier": "/ietf-system:system/radius/options/attempts", 1221 "sid": 1766 1222 }, 1223 { 1224 "namespace": "data", 1225 "identifier": "/ietf-system:system/radius/options/timeout", 1226 "sid": 1767 1227 }, 1228 { 1229 "namespace": "data", 1230 "identifier": "/ietf-system:system/radius/server", 1231 "sid": 1768 1232 }, 1233 { 1234 "namespace": "data", 1235 "identifier": "/ietf-system:system/radius/server/ 1236 authentication-type", 1237 "sid": 1769 1238 }, 1239 { 1240 "namespace": "data", 1241 "identifier": "/ietf-system:system/radius/server/name", 1242 "sid": 1770 1243 }, 1244 { 1245 "namespace": "data", 1246 "identifier": "/ietf-system:system/radius/server/udp", 1247 "sid": 1771 1248 }, 1249 { 1250 "namespace": "data", 1251 "identifier": "/ietf-system:system/radius/server/udp/ 1252 address", 1253 "sid": 1772 1254 }, 1255 { 1256 "namespace": "data", 1257 "identifier": "/ietf-system:system/radius/server/udp/ 1258 authentication-port", 1259 "sid": 1773 1260 }, 1261 { 1262 "namespace": "data", 1263 "identifier": "/ietf-system:system/radius/server/udp/ 1264 shared-secret", 1265 "sid": 1774 1266 } 1267 ] 1268 } 1270 Appendix B. SID auto generation 1272 Assignment of SIDs to YANG items can be automated, the recommended 1273 process to assign SIDs is as follows: 1275 1. A tool extracts the different items defined for a specific YANG 1276 module. 1278 2. The list of items is sorted in alphabetical order, 'namespace' in 1279 descending order, 'identifier' in ascending order. The 1280 'namespace' and 'identifier' formats are described in the YANG 1281 module 'ietf-sid-file' defined in Section 4. 1283 3. SIDs are assigned sequentially from the entry point up to the 1284 size of the registered SID range. This approach is recommended 1285 to minimize the serialization overhead, especially when delta 1286 between a reference SID and the current SID is used by protocols 1287 aiming to reduce message size. 1289 4. If the number of items exceeds the SID range(s) allocated to a 1290 YANG module, an extra range is added for subsequent assignments. 1292 Changes of SID files can also be automated using the same method 1293 described above, only unassigned YANG items are processed at step #3. 1294 Already existing items in the SID file should not be given new SIDs. 1296 Appendix C. ".sid" file lifecycle 1298 Before assigning SIDs to their YANG modules, YANG module authors must 1299 acquire a SID range from a "SID Range Registry". If the YANG module 1300 is part of an IETF draft or RFC, the SID range need to be acquired 1301 from the "IETF SID Range Registry" as defined in Section 6.3. For 1302 the other YANG modules, the authors can acquire a SID range from any 1303 "SID Range Registry" of their choice. 1305 Once the SID range is acquired, the owner can use it to generate 1306 ".sid" file/s for his YANG module/s. It is recommended to leave some 1307 unallocated SIDs following the allocated range in each ".sid" file in 1308 order to allow better evolution of the YANG module in the future. 1309 Generation of ".sid" files should be performed using an automated 1310 tool. Note that ".sid" files can only be generated for YANG modules 1311 and not for submodules. 1313 C.1. SID File Creation 1315 The following activity diagram summarizes the creation of a YANG 1316 module and its associated .sid file. 1318 +---------------+ 1319 O | Creation of a | 1320 -|- ->| YANG module | 1321 / \ +---------------+ 1322 | 1323 V 1324 /-------------\ 1325 / Standardized \ yes 1326 \ YANG module ? /-------------+ 1327 \-------------/ | 1328 | no | 1329 V V 1330 /-------------\ +---------------+ 1331 / Constrained \ yes | SID range | 1332 +-->\ application ? /---->| registration |<----------+ 1333 | \-------------/ +---------------+ | 1334 | | no | | 1335 | V V | 1336 | +---------------+ +---------------+ | 1337 +---| YANG module | | SID sub-range | | 1338 | update | | assignment |<----------+ 1339 +---------------+ +---------------+ | 1340 | | 1341 V | 1342 +---------------+ +-------------+ 1343 | .sid file | | Rework YANG | 1344 | generation | | model | 1345 +---------------+ +-------------+ 1346 | ^ 1347 V | 1348 /----------\ yes | 1349 / Work in \ -----------+ 1350 \ progress / 1351 \----------/ 1352 | no 1353 V 1354 /-------------\ /-------------\ 1355 / RFC \ no / Open \ no 1356 \ publication? /---->\ specification?/---+ 1357 \-------------/ \-------------/ | 1358 | yes | yes | 1359 | +---------------+ | 1360 V V V 1361 +---------------+ +---------------+ 1362 | IANA | | Third party | 1363 | registration | | registration | 1364 +-------+-------+ +-------+-------+ 1365 | | 1366 +---------------------------------+ 1367 V 1368 [DONE] 1370 Figure 1: SID Lifecycle 1372 C.2. SID File Update 1374 The following Activity diagram summarizes the update of a YANG module 1375 and its associated .sid file. 1377 +---------------+ 1378 O | Update of the | 1379 -|- ->| YANG module | 1380 / \ | or include(s) | 1381 | or import(s) | 1382 +---------------+ 1383 | 1384 V 1385 /-------------\ 1386 / New items \ yes 1387 \ created ? /------+ 1388 \-------------/ | 1389 | no V 1390 | /-------------\ +----------------+ 1391 | / SID range \ yes | Extra sub-range| 1392 | \ exhausted ? /---->| assignment | 1393 | \-------------/ +----------------+ 1394 | | no | 1395 | +---------------------+ 1396 | | 1397 | V 1398 | +---------------+ 1399 | | .sid file | 1400 | | update based | 1401 | | on previous | 1402 | | .sid file | 1403 | +---------------+ 1404 | | 1405 | V 1406 | /-------------\ +---------------+ 1407 | / Publicly \ yes | YANG module | 1408 | \ available ? /---->| registration | 1409 | \-------------/ +---------------+ 1410 | | no | 1411 +--------------+---------------------+ 1412 | 1413 [DONE] 1415 Figure 2: YANG and SID file update 1417 Authors' Addresses 1418 Michel Veillette (editor) 1419 Trilliant Networks Inc. 1420 610 Rue du Luxembourg 1421 Granby, Quebec J2J 2V2 1422 Canada 1424 Phone: +14503750556 1425 Email: michel.veillette@trilliant.com 1427 Alexander Pelov (editor) 1428 Acklio 1429 1137A avenue des Champs Blancs 1430 Cesson-Sevigne, Bretagne 35510 1431 France 1433 Email: a@ackl.io 1435 Ivaylo Petrov (editor) 1436 Acklio 1437 1137A avenue des Champs Blancs 1438 Cesson-Sevigne, Bretagne 35510 1439 France 1441 Email: ivaylo@ackl.io