idnits 2.17.00 (12 Aug 2021) /tmp/idnits13298/draft-ietf-rtgwg-yang-key-chain-14.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 306 has weird spacing: '...gorithm ide...' == Line 673 has weird spacing: '...tion in hexad...' -- The document date (February 15, 2017) is 1921 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) ** Obsolete normative reference: RFC 6536 (ref. 'NETCONF-ACM') (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Lindem, Ed. 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track Y. Qu 5 Expires: August 19, 2017 Huawei 6 D. Yeung 7 Arrcus, Inc 8 I. Chen 9 Jabil 10 J. Zhang 11 Juniper Networks 12 Y. Yang 13 SockRate 14 February 15, 2017 16 Routing Key Chain YANG Data Model 17 draft-ietf-rtgwg-yang-key-chain-14.txt 19 Abstract 21 This document describes the key chain YANG data model. A key chain 22 is a list of elements each containing a key, send lifetime, accept 23 lifetime, and algorithm (authentication or encryption). By properly 24 overlapping the send and accept lifetimes of multiple key chain 25 elements, keys and algorithms may be gracefully updated. By 26 representing them in a YANG data model, key distribution can be 27 automated. Key chains are commonly used for routing protocol 28 authentication and other applications. In some applications, the 29 protocols do not use the key chain element key directly, but rather a 30 key derivation function is used to derive a short-lived key from the 31 key chain element key (e.g., the Master Keys used in the TCP 32 Authentication Option. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on August 19, 2017. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 69 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 70 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 71 2.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 72 2.2. Graceful Key Rollover using Key Chains . . . . . . . . . 4 73 3. Design of the Key Chain Model . . . . . . . . . . . . . . . . 5 74 3.1. Key Chain Operational State . . . . . . . . . . . . . . . 5 75 3.2. Key Chain Model Features . . . . . . . . . . . . . . . . 6 76 3.3. Key Chain Model Tree . . . . . . . . . . . . . . . . . . 6 77 4. Key Chain YANG Model . . . . . . . . . . . . . . . . . . . . 9 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 82 7.2. Informative References . . . . . . . . . . . . . . . . . 19 83 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 20 84 A.1. Simple Key Chain with Always Valid Single Key . . . . . . 20 85 A.2. Key Chain with Keys having Different Lifetimes . . . . . 21 86 A.3. Key Chain with Independent Send and Accept Lifetimes . . 22 87 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 23 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 90 1. Introduction 92 This document describes the key chain YANG data model. A key chain 93 is a list of elements each containing a key, send lifetime, accept 94 lifetime, and algorithm (authentication or encryption). By properly 95 overlapping the send and accept lifetimes of multiple key chain 96 elements, keys and algorithms may be gracefully updated. By 97 representing them in a YANG data model, key distribution can be 98 automated. Key chains are commonly used for routing protocol 99 authentication and other applications. In some applications, the 100 protocols do not use the key chain element key directly, but rather a 101 key derivation function is used to derive a short-lived key from the 102 key chain element key (e.g., the Master Keys used in [TCP-AO]). 104 1.1. Requirements Notation 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in 109 [RFC-KEYWORDS]. 111 1.2. Tree Diagrams 113 A simplified graphical representation of the complete data tree is 114 presented in Section 3.3. The following tree notation is used. 116 o Brackets "[" and "]" enclose list keys. 118 o Curly braces "{" and "}" contain names of optional features that 119 make the corresponding node conditional. 121 o Abbreviations before data node names: "rw" means configuration 122 (read-write), "ro" state data (read-only), "-x" RPC operations, 123 and "-n" notifications. 125 o Symbols after data node names: "?" means an optional node, "!" a 126 container with presence, and "*" denotes a "list" or "leaf-list". 128 o Parentheses enclose choice and case nodes, and case nodes are also 129 marked with a colon (":"). 131 o Ellipsis ("...") stands for contents of subtrees that are not 132 shown. 134 2. Problem Statement 136 This document describes a YANG [YANG] data model for key chains. Key 137 chains have been implemented and deployed by a large percentage of 138 network equipment vendors. Providing a standard YANG model will 139 facilitate automated key distribution and non-disruptive key 140 rollover. This will aid in tightening the security of the core 141 routing infrastructure as recommended in [IAB-REPORT]. 143 A key chain is a list containing one or more elements containing a 144 Key ID, key, send/accept lifetimes, and the associated authentication 145 or encryption algorithm. A key chain can be used by any service or 146 application requiring authentication or encryption. In essence, the 147 key-chain is a reusable key policy that can be referenced whereever 148 it is required. The key-chain construct has been implemented by most 149 networking vendors and deployed in many networks. 151 A conceptual representation of a crypto key table is described in 152 [CRYPTO-KEYTABLE]. The crypto key table also includes keys as well 153 as their corresponding lifetimes and algorithms. Additionally, the 154 key table includes key selection criteria and envisions a deployment 155 model where the details of the applications or services requiring 156 authentication or encryption permeate into the key database. The 157 YANG key-chain model described herein doesn't include key selection 158 criteria or support this deployment model. At the same time, it does 159 not preclude it. The draft [YANG-CRYPTO-KEYTABLE] describes 160 augmentations to the key chain YANG model in support of key selection 161 criteria. 163 2.1. Applicability 165 Other YANG modules may reference ietf-key-chain YANG module key-chain 166 names for authentication and encryption applications. A YANG type 167 has been provided to facilate reference to the key-chain name without 168 having to specify the complete YANG XML Path Language (XPath) 169 selector. 171 2.2. Graceful Key Rollover using Key Chains 173 Key chains may be used to gracefully update the key and/or algorithm 174 used by an application for authentication or encryption. This MAY be 175 accomplished by accepting all the keys that have a valid accept 176 lifetime and sending the key with the most recent send lifetime. One 177 scenario for facilitating key rollover is to: 179 1. Distribute a key chain with a new key to all the routers or other 180 network devices in the domain of that key chain. The new key's 181 accept lifetime should be such that it is accepted during the key 182 rollover period. The send lifetime should be a time in the 183 future when it can be assured that all the routers in the domain 184 of that key are upgraded. This will have no immediate impact on 185 the keys used for transmission. 187 2. Assure that all the network devices have been updated with the 188 updated key chain and that their system times are roughly 189 synchronized. The system times of devices within an 190 administrative domain are commonly synchronized (e.g., using 191 Network Time Protocol (NTP) [NTP-PROTO]). This also may be 192 automated. 194 3. When the send lifetime of the new key becomes valid, the network 195 devices within the domain of key chain will start sending the new 196 key. 198 4. At some point in the future, a new key chain with the old key 199 removed may be distributed to the network devices within the 200 domain of the key chain. However, this may be deferred until the 201 next key rollover. If this is done, the key chain will always 202 include two keys; either the current and future key (during key 203 rollovers) or the current and previous keys (between key 204 rollovers). 206 3. Design of the Key Chain Model 208 The ietf-key-chain module contains a list of one or more keys indexed 209 by a Key ID. For some applications (e.g., OSPFv3 [OSPFV3-AUTH]), the 210 Key ID is used to identify the key chain entry to be used. In 211 addition to the Key ID, each key chain entry includes a key-string 212 and a cryptographic algorithm. Optionally, the key chain entries 213 include send/accept lifetimes. If the send/accept lifetime is 214 unspecified, the key is always considered valid. 216 Note that asymmetric keys, i.e., a different key value used for 217 transmission versus acceptance, may be supported with multiple key 218 chain elements where the accept-lifetime or send-lifetime is not 219 valid (e.g., has an end-time equal to the start-time). 221 Due to the differences in key chain implementations across various 222 vendors, some of the data elements are optional. Finally, the crypto 223 algorithm identities are provided for reuse when configuring legacy 224 authentication and encryption not using key-chains. 226 A key-chain is identified by a unique name within the scope of the 227 network device. The "key-chain-ref" typedef SHOULD be used by other 228 YANG modules when they need to reference a configured key-chain. 230 3.1. Key Chain Operational State 232 The key chain operational state is maintained in a separate tree. 233 The key string itself is omitted from the operational state to 234 minimize visibility similar to what was done with keys in SNMP MIBs. 235 The timestamp of the last key-chain modification is also maintained 236 in the operational state. Additionally, the operational state 237 includes an indication of whether or not a key chain entry is valid 238 for sending or acceptance. 240 3.2. Key Chain Model Features 242 Features are used to handle differences between vendor 243 implementations. For example, not all vendors support configuration 244 an acceptance tolerance or configuration of key strings in 245 hexadecimal. They are also used to support of security requirements 246 (e.g., TCP-AO Algorithms [TCP-AO-ALGORITHMS]) not implemented by 247 vendors or only a single vendor. 249 3.3. Key Chain Model Tree 251 +--rw key-chains 252 | +--rw key-chain* [name] 253 | | +--rw name string 254 | | +--rw description? string 255 | | +--rw accept-tolerance {accept-tolerance}? 256 | | | +--rw duration? uint32 257 | | +--rw key-entry* [key-id] 258 | | +--rw key-id uint64 259 | | +--rw lifetime 260 | | | +--rw (lifetime)? 261 | | | +--:(send-and-accept-lifetime) 262 | | | | +--rw send-accept-lifetime 263 | | | | +--rw (lifetime)? 264 | | | | +--:(always) 265 | | | | | +--rw always? empty 266 | | | | +--:(start-end-time) 267 | | | | +--rw start-date-time? yang:date-and-time 268 | | | | +--rw (end-time)? 269 | | | | +--:(infinite) 270 | | | | | +--rw no-end-time? empty 271 | | | | +--:(duration) 272 | | | | | +--rw duration? uint32 273 | | | | +--:(end-date-time) 274 | | | | +--rw end-date-time? 275 | | | | yang:date-and-time 276 | | | +--:(independent-send-accept-lifetime) 277 | | | | {independent-send-accept-lifetime}? 278 | | | +--rw send-lifetime 279 | | | | +--rw (lifetime)? 280 | | | | +--:(always) 281 | | | | | +--rw always? empty 282 | | | | +--:(start-end-time) 283 | | | | +--rw start-date-time? yang:date-and-time 284 | | | | +--rw (end-time)? 285 | | | | +--:(infinite) 286 | | | | | +--rw no-end-time? empty 287 | | | | +--:(duration) 288 | | | | | +--rw duration? uint32 289 | | | | +--:(end-date-time) 290 | | | | +--rw end-date-time? 291 | | | | yang:date-and-time 292 | | | +--rw accept-lifetime 293 | | | +--rw (lifetime)? 294 | | | +--:(always) 295 | | | | +--rw always? empty 296 | | | +--:(start-end-time) 297 | | | +--rw start-date-time? yang:date-and-time 298 | | | +--rw (end-time)? 299 | | | +--:(infinite) 300 | | | | +--rw no-end-time? empty 301 | | | +--:(duration) 302 | | | | +--rw duration? uint32 303 | | | +--:(end-date-time) 304 | | | +--rw end-date-time? 305 | | | yang:date-and-time 306 | | +--rw crypto-algorithm identityref 307 | | +--rw key-string 308 | | +--rw (key-string-style)? 309 | | +--:(keystring) 310 | | | +--rw keystring? string 311 | | +--:(hexadecimal) {hex-key-string}? 312 | | +--rw hexadecimal-string? yang:hex-string 313 | +--rw aes-key-wrap {aes-key-wrap}? 314 | +--rw enable? boolean 315 +--ro key-chains-state 316 +--ro key-chain-state* [name] 317 | +--ro name string 318 | +--ro description? string 319 | +--ro accept-tolerance {accept-tolerance}? 320 | | +--ro duration? uint32 321 | +--ro last-modified-timestamp? yang:date-and-time 322 | +--ro key-entry-state* [key-id] 323 | +--ro key-id uint64 324 | +--ro lifetime 325 | | +--ro (lifetime)? 326 | | +--:(send-and-accept-lifetime) 327 | | | +--ro send-accept-lifetime 328 | | | +--ro (lifetime)? 329 | | | +--:(always) 330 | | | | +--ro always? empty 331 | | | +--:(start-end-time) 332 | | | +--ro start-date-time? yang:date-and-time 333 | | | +--ro (end-time)? 334 | | | +--:(infinite) 335 | | | | +--ro no-end-time? empty 336 | | | +--:(duration) 337 | | | | +--ro duration? uint32 338 | | | +--:(end-date-time) 339 | | | +--ro end-date-time? 340 | | | yang:date-and-time 341 | | +--:(independent-send-accept-lifetime) 342 | | | {independent-send-accept-lifetime}? 343 | | +--ro send-lifetime 344 | | | +--ro (lifetime)? 345 | | | +--:(always) 346 | | | | +--ro always? empty 347 | | | +--:(start-end-time) 348 | | | +--ro start-date-time? yang:date-and-time 349 | | | +--ro (end-time)? 350 | | | +--:(infinite) 351 | | | | +--ro no-end-time? empty 352 | | | +--:(duration) 353 | | | | +--ro duration? uint32 354 | | | +--:(end-date-time) 355 | | | +--ro end-date-time? 356 | | | yang:date-and-time 357 | | +--ro accept-lifetime 358 | | +--ro (lifetime)? 359 | | +--:(always) 360 | | | +--ro always? empty 361 | | +--:(start-end-time) 362 | | +--ro start-date-time? yang:date-and-time 363 | | +--ro (end-time)? 364 | | +--:(infinite) 365 | | | +--ro no-end-time? empty 366 | | +--:(duration) 367 | | | +--ro duration? uint32 368 | | +--:(end-date-time) 369 | | +--ro end-date-time? 370 | | yang:date-and-time 371 | +--ro crypto-algorithm identityref 372 | +--ro key-string 373 | | +--ro (key-string-style)? 374 | | +--:(keystring) 375 | | | +--ro keystring? string 376 | | +--:(hexadecimal) {hex-key-string}? 377 | | +--ro hexadecimal-string? yang:hex-string 378 | +--ro send-lifetime-active? boolean 379 | +--ro accept-lifetime-active? boolean 380 +--ro aes-key-wrap {aes-key-wrap}? 381 +--ro enable? boolean 383 4. Key Chain YANG Model 385 file "ietf-key-chain@2017-02-15.yang" 386 module ietf-key-chain { 387 yang-version 1.1; 388 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 389 prefix key-chain; 391 import ietf-yang-types { 392 prefix yang; 393 } 394 import ietf-netconf-acm { 395 prefix nacm; 396 } 398 organization 399 "IETF RTG (Routing) Working Group"; 400 contact 401 "Acee Lindem - acee@cisco.com"; 402 description 403 "This YANG module defines the generic configuration 404 data for key-chain. It is intended that the module 405 will be extended by vendors to define vendor-specific 406 key-chain configuration parameters. 408 Copyright (c) 2015 IETF Trust and the persons identified as 409 authors of the code. All rights reserved. 411 Redistribution and use in source and binary forms, with or 412 without modification, is permitted pursuant to, and subject 413 to the license terms contained in, the Simplified BSD License 414 set forth in Section 4.c of the IETF Trust's Legal Provisions 415 Relating to IETF Documents 416 (http://trustee.ietf.org/license-info). 417 This version of this YANG module is part of RFC XXXX; see 418 the RFC itself for full legal notices."; 420 revision 2017-02-15 { 421 description 422 "Replace choice statement with identity for crypto-algorithm. 423 Removed unneeded groupings. 424 Fixed indenations."; 425 reference "RFC XXXX: A YANG Data Model for key-chain"; 426 } 428 feature hex-key-string { 429 description 430 "Support hexadecimal key string."; 432 } 434 feature accept-tolerance { 435 description 436 "To specify the tolerance or acceptance limit."; 437 } 439 feature independent-send-accept-lifetime { 440 description 441 "Support for independent send and accept key lifetimes."; 442 } 444 feature crypto-hmac-sha-1-12 { 445 description 446 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 447 } 449 feature clear-text { 450 description 451 "Support for clear-text algorithm. Usage is 452 NOT RECOMMENDED."; 453 } 455 feature aes-cmac-prf-128 { 456 description 457 "Support for AES Cipher based Message Authentication 458 Code Pseudo Random Function."; 459 } 461 feature aes-key-wrap { 462 description 463 "Support for Advanced Encryption Standard (AES) Key Wrap."; 464 } 466 feature replay-protection-only { 467 description 468 "Provide replay-protection without any authentication 469 as required by protocols such as Bidirectional 470 Forwarding Detection (BFD)."; 471 } 473 identity crypto-algorithm { 474 description 475 "Base identity of cryptographic algorithm options."; 476 } 478 identity hmac-sha-1-12 { 479 base crypto-algorithm; 480 if-feature "crypto-hmac-sha-1-12"; 481 description 482 "The HMAC-SHA1-12 algorithm."; 483 } 485 identity aes-cmac-prf-128 { 486 base crypto-algorithm; 487 if-feature "aes-cmac-prf-128"; 488 description 489 "The AES-CMAC-PRF-128 algorithm - required by 490 RFC 5926 for TCP-AO key derivation functions."; 491 } 493 identity md5 { 494 base crypto-algorithm; 495 description 496 "The MD5 algorithm."; 497 } 499 identity sha-1 { 500 base crypto-algorithm; 501 description 502 "The SHA-1 algorithm."; 503 } 505 identity hmac-sha-1 { 506 base crypto-algorithm; 507 description 508 "HMAC-SHA-1 authentication algorithm."; 509 } 511 identity hmac-sha-256 { 512 base crypto-algorithm; 513 description 514 "HMAC-SHA-256 authentication algorithm."; 515 } 517 identity hmac-sha-384 { 518 base crypto-algorithm; 519 description 520 "HMAC-SHA-384 authentication algorithm."; 521 } 523 identity hmac-sha-512 { 524 base crypto-algorithm; 525 description 526 "HMAC-SHA-512 authentication algorithm."; 527 } 528 identity clear-text { 529 base crypto-algorithm; 530 if-feature "clear-text"; 531 description 532 "Clear text."; 533 } 535 identity replay-protection-only { 536 base crypto-algorithm; 537 if-feature "replay-protection-only"; 538 description 539 "Provide replay-protection without any authentication as 540 required by protocols such as Bidirectional Forwarding 541 Detection (BFD)."; 542 } 544 typedef key-chain-ref { 545 type leafref { 546 path 547 "/key-chain:key-chains/key-chain:key-chain/key-chain:name"; 548 } 549 description 550 "This type is used by data models that need to reference 551 configured key-chains."; 552 } 554 grouping lifetime { 555 description 556 "Key lifetime specification."; 557 choice lifetime { 558 default "always"; 559 description 560 "Options for specifying key accept or send lifetimes"; 561 case always { 562 leaf always { 563 type empty; 564 description 565 "Indicates key lifetime is always valid."; 566 } 567 } 568 case start-end-time { 569 leaf start-date-time { 570 type yang:date-and-time; 571 description 572 "Start time."; 573 } 574 choice end-time { 575 default "infinite"; 576 description 577 "End-time setting."; 578 case infinite { 579 leaf no-end-time { 580 type empty; 581 description 582 "Indicates key lifetime end-time in infinite."; 583 } 584 } 585 case duration { 586 leaf duration { 587 type uint32 { 588 range "1..2147483646"; 589 } 590 units "seconds"; 591 description 592 "Key lifetime duration, in seconds"; 593 } 594 } 595 case end-date-time { 596 leaf end-date-time { 597 type yang:date-and-time; 598 description 599 "End time."; 600 } 601 } 602 } 603 } 604 } 605 } 607 grouping key-common-entry { 608 description 609 "Key-chain entry data nodes common to 610 configuration and state."; 611 container lifetime { 612 description 613 "Specify a key's lifetime."; 614 choice lifetime { 615 description 616 "Options for specification of send and accept lifetimes."; 617 case send-and-accept-lifetime { 618 description 619 "Send and accept key have the same lifetime."; 620 container send-accept-lifetime { 621 description 622 "Single lifetime specification for both 623 send and accept lifetimes."; 625 uses lifetime; 626 } 627 } 628 case independent-send-accept-lifetime { 629 if-feature "independent-send-accept-lifetime"; 630 description 631 "Independent send and accept key lifetimes."; 632 container send-lifetime { 633 description 634 "Separate lifetime specification for send lifetime."; 635 uses lifetime; 636 } 637 container accept-lifetime { 638 description 639 "Separate lifetime specification for accept lifetime."; 640 uses lifetime; 641 } 642 } 643 } 644 } 645 leaf crypto-algorithm { 646 type identityref { 647 base crypto-algorithm; 648 } 649 mandatory true; 650 description 651 "Cryptographic algorithm associated with key."; 652 } 653 container key-string { 654 description 655 "The key string."; 656 nacm:default-deny-all; 657 choice key-string-style { 658 description 659 "Key string styles"; 660 case keystring { 661 leaf keystring { 662 type string; 663 description 664 "Key string in ASCII format."; 665 } 666 } 667 case hexadecimal { 668 if-feature "hex-key-string"; 669 leaf hexadecimal-string { 670 type yang:hex-string; 671 description 672 "Key in hexadecimal string format. When compared 673 to ASCII, specification in hexadecimal affords 674 greater key entropy with the same number of 675 octets. Additionally, it discourages usage of 676 well-known words or numbers."; 677 } 678 } 679 } 680 } 681 } 683 grouping key-state-entry { 684 description 685 "Key state entry."; 686 uses key-common-entry; 687 leaf send-lifetime-active { 688 type boolean; 689 config false; 690 description 691 "Indicates if the send lifetime of the 692 key-chain entry is currently active."; 693 } 694 leaf accept-lifetime-active { 695 type boolean; 696 config false; 697 description 698 "Indicates if the accept lifetime of the 699 key-chain entry is currently active."; 700 } 701 } 703 grouping key-chain-common { 704 description 705 "key-chain common grouping."; 706 leaf name { 707 type string; 708 description 709 "Name of the key-chain."; 710 } 711 leaf description { 712 type string; 713 description 714 "A description of the key-chain"; 715 } 716 container accept-tolerance { 717 if-feature "accept-tolerance"; 718 description 719 "Tolerance for key lifetime acceptance (seconds)."; 720 leaf duration { 721 type uint32; 722 units "seconds"; 723 default "0"; 724 description 725 "Tolerance range, in seconds."; 726 } 727 } 728 } 730 grouping key-chain-config { 731 description 732 "key-chain configuration grouping."; 733 uses key-chain-common; 734 list key-entry { 735 key "key-id"; 736 description 737 "One key."; 738 leaf key-id { 739 type uint64; 740 description 741 "Key ID."; 742 } 743 uses key-common-entry; 744 } 745 } 747 grouping key-chain-state { 748 description 749 "key-chain state grouping."; 750 uses key-chain-common; 751 leaf last-modified-timestamp { 752 type yang:date-and-time; 753 description 754 "Timestamp of the most recent update to the key-chain"; 755 } 756 list key-entry-state { 757 key "key-id"; 758 description 759 "One key."; 760 leaf key-id { 761 type uint64; 762 description 763 "Key ID."; 764 } 765 uses key-state-entry; 766 } 767 } 768 container key-chains { 769 description 770 "All configured key-chains on the device."; 771 list key-chain { 772 key "name"; 773 description 774 "List of key-chains."; 775 uses key-chain-config; 776 } 777 container aes-key-wrap { 778 if-feature "aes-key-wrap"; 779 description 780 "AES Key Wrap password encryption."; 781 leaf enable { 782 type boolean; 783 default "false"; 784 description 785 "Enable AES Key Wrap encryption."; 786 } 787 } 788 } 789 container key-chains-state { 790 config false; 791 description 792 "State for all configured key-chains on the device."; 793 list key-chain-state { 794 key "name"; 795 description 796 "List of key-chains and operational state."; 797 uses key-chain-state; 798 } 799 container aes-key-wrap { 800 if-feature "aes-key-wrap"; 801 description 802 "AES Key Wrap password encryption."; 803 leaf enable { 804 type boolean; 805 description 806 "Indicates whether AES Key Wrap encryption is enabled."; 807 } 808 } 809 } 810 } 811 813 5. Security Considerations 815 This document enables the automated distribution of industry standard 816 key chains using the NETCONF [NETCONF] protocol. As such, the 817 security considerations for the NETCONF protocol are applicable. The 818 NETCONF protocol mandates confidentiality (section 2.2 of [NETCONF]. 819 Similarily, the RESTCONF protocol also mandates confidentiality 820 (section 1.1 of [RESTCONF]). If a transport not mandating 821 confidentiality is used, it is RECOMMENDED that the transport 822 communication channel be encrypted. 824 When configured, the key-strings can be encrypted using the AES Key 825 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 826 not included in the YANG model and must be set or derived independent 827 of key-chain configuration. 829 The key strings are not accessible by default and NETCONF Access 830 Control Mode [NETCONF-ACM] rules are required to configure or 831 retrieve them. 833 The clear-text algorithm is included as a YANG feature. Usage is NOT 834 RECOMMENDED except in cases where the application and device have no 835 other alternative (e.g., a legacy network device that must 836 authenticate packets at intervals of 10 milliseconds or less for many 837 peers using Bidirectional Forwarding Detection [BFD]). Keys used 838 with the clear-text algorithm are considered insecure and SHOULD NOT 839 be reused with more secure algorithms. 841 It is RECOMMENDED that keys be encrypted or otherwise obfuscated when 842 stored internally on a network device supporting this specification. 844 6. IANA Considerations 846 This document registers a URI in the IETF XML registry 847 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 848 following registration is requested to be made: 850 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 852 Registrant Contact: The IESG. 854 XML: N/A, the requested URI is an XML namespace. 856 This document registers a YANG module in the YANG Module Names 857 registry [YANG]. 859 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 860 key-chain prefix: ietf-key-chain reference: RFC XXXX 862 7. References 864 7.1. Normative References 866 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 867 Bierman, "Network Configuration Protocol (NETCONF)", RFC 868 6241, June 2011. 870 [NETCONF-ACM] 871 Bierman, A. and M. Bjorklund, "Network Configuration 872 Protocol (NETCONF) Access Control Model", RFC 6536, March 873 2012. 875 [RFC-KEYWORDS] 876 Bradner, S., "Key words for use in RFC's to Indicate 877 Requirement Levels", BCP 14, RFC 2119, March 1997. 879 [XML-REGISTRY] 880 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 881 January 2004. 883 [YANG] Bjorklund, M., "YANG - A Data Modeling Language for the 884 Network Configuration Protocol (NETCONF)", RFC 6020, 885 October 2010. 887 7.2. Informative References 889 [AES-KEY-WRAP] 890 Housley, R. and M. Dworkin, "Advanced Encryption Standard 891 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 892 2009. 894 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 895 (BFD)", RFC 5880, June 2010. 897 [CRYPTO-KEYTABLE] 898 Housley, R., Polk, T., Hartman, S., and D. Zhang, 899 "Table of Cryptographic Keys", RFC 7210, April 2014. 901 [IAB-REPORT] 902 Andersson, L., Davies, E., and L. Zhang, "Report from the 903 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 904 4948, August 2007. 906 [NTP-PROTO] 907 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 908 Time Protocol Version 4: Protocol and Algorithms 909 Specification", RFC 5905, June 2010. 911 [OSPFV3-AUTH] 912 Bhatia, M., Manral, V., and A. Lindem, "Supporting 913 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 915 [RESTCONF] 916 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 917 Protocol", RFC 8040, January 2017. 919 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 920 Authentication Option", RFC 5925, June 2010. 922 [TCP-AO-ALGORITHMS] 923 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 924 for the TCP Authentication Option (TCP-AO)", RFC 5926, 925 June 2010. 927 [YANG-CRYPTO-KEYTABLE] 928 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 929 chen-rtg-key-table-yang-00.txt (work in progress), 930 November 2015. 932 Appendix A. Examples 934 A.1. Simple Key Chain with Always Valid Single Key 936 937 938 939 940 keychain-no-end-time 941 942 A key chain with a single key that is always valid for tx/rx 943 944 945 100 946 947 948 949 950 951 md5 952 953 keystring_in_ascii_100 954 955 956 957 958 960 A.2. Key Chain with Keys having Different Lifetimes 962 963 964 965 966 keychain2 967 968 A key chain where each key contains different send time 969 and accept time 970 971 972 35 973 974 975 2017-01-01T00:00:00Z 976 2017-02-01T00:00:00Z 977 978 979 2016-12-31T23:59:55Z 980 2017-02-01T00:00:05Z 981 982 983 hmac-sha-1 984 985 keystring_in_ascii_35 986 987 988 989 36 990 991 992 2017-02-01T00:00:00Z 993 2017-03-01T00:00:00Z 994 995 996 2017-01-31T23:59:55Z 997 2017-03-01T00:00:05Z 998 999 1000 hmac-sha-1 1001 1002 fe:ed:be:af:36 1003 1004 1005 1006 1007 1009 A.3. Key Chain with Independent Send and Accept Lifetimes 1011 1012 1013 1014 1015 keychain2 1016 1017 A key chain where each key contains different send time 1018 and accept time 1019 1020 1021 35 1022 1023 1024 2017-01-01T00:00:00Z 1025 2017-02-01T00:00:00Z 1026 1027 1028 2016-12-31T23:59:55Z 1029 2017-02-01T00:00:05Z 1030 1031 1032 hmac-sha-1 1033 1034 keystring_in_ascii_35 1035 1036 1037 1038 36 1039 1040 1041 2017-02-01T00:00:00Z 1042 2017-03-01T00:00:00Z 1043 1044 1045 2017-01-31T23:59:55Z 1046 2017-03-01T00:00:05Z 1047 1048 1049 hmac-sha-1 1050 1051 fe:ed:be:af:36 1052 1053 1054 1055 1056 1058 Appendix B. Acknowledgments 1060 The RFC text was produced using Marshall Rose's xml2rfc tool. 1062 Thanks to Brian Weis for fruitful discussions on security 1063 requirements. 1065 Thanks to Ines Robles for Routing Directorate QA review comments. 1067 Thanks to Ladislav Lhotka for YANG Doctor comments. 1069 Thanks to Martin Bjorklund for additional YANG Doctor comments. 1071 Authors' Addresses 1073 Acee Lindem (editor) 1074 Cisco Systems 1075 301 Midenhall Way 1076 Cary, NC 27513 1077 USA 1079 Email: acee@cisco.com 1081 Yingzhen Qu 1082 Huawei 1084 Email: yingzhen.qu@huawei.com 1086 Derek Yeung 1087 Arrcus, Inc 1089 Email: derek@arrcus.com 1091 Ing-Wher Chen 1092 Jabil 1094 Email: ing-wher_chen@jabil.com 1095 Jeffrey Zhang 1096 Juniper Networks 1097 10 Technology Park Drive 1098 Westford, MA 01886 1099 USA 1101 Email: zzhang@juniper.net 1103 Yi Yang 1104 SockRate 1106 Email: yi.yang@sockrate.com