idnits 2.17.1 draft-ietf-rtgwg-yang-key-chain-15.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 312 has weird spacing: '...gorithm ide...' == Line 687 has weird spacing: '...tion in hexad...' -- The document date (February 16, 2017) is 2597 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 20, 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 16, 2017 16 Routing Key Chain YANG Data Model 17 draft-ietf-rtgwg-yang-key-chain-15.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 string, send lifetime, 23 accept lifetime, and algorithm (authentication or encryption). By 24 properly overlapping the send and accept lifetimes of multiple key 25 chain elements, key strings and algorithms may be gracefully updated. 26 By 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 20, 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 . . . . . . . . . . . . . . . . . . . 17 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 string, send lifetime, 94 accept lifetime, and algorithm (authentication or encryption). By 95 properly overlapping the send and accept lifetimes of multiple key 96 chain elements, key strings and algorithms may be gracefully updated. 97 By 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 string directly, but 101 rather a key derivation function is used to derive a short-lived key 102 from the key chain element key string (e.g., the Master Keys used in 103 [TCP-AO]). 105 1.1. Requirements Notation 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 109 "OPTIONAL" in this document are to be interpreted as described in 110 [RFC-KEYWORDS]. 112 1.2. Tree Diagrams 114 A simplified graphical representation of the complete data tree is 115 presented in Section 3.3. The following tree notation is used. 117 o Brackets "[" and "]" enclose list keys. 119 o Curly braces "{" and "}" contain names of optional features that 120 make the corresponding node conditional. 122 o Abbreviations before data node names: "rw" means configuration 123 (read-write), "ro" state data (read-only), "-x" RPC operations, 124 and "-n" notifications. 126 o Symbols after data node names: "?" means an optional node, "!" a 127 container with presence, and "*" denotes a "list" or "leaf-list". 129 o Parentheses enclose choice and case nodes, and case nodes are also 130 marked with a colon (":"). 132 o Ellipsis ("...") stands for contents of subtrees that are not 133 shown. 135 2. Problem Statement 137 This document describes a YANG [YANG] data model for key chains. Key 138 chains have been implemented and deployed by a large percentage of 139 network equipment vendors. Providing a standard YANG model will 140 facilitate automated key distribution and non-disruptive key 141 rollover. This will aid in tightening the security of the core 142 routing infrastructure as recommended in [IAB-REPORT]. 144 A key chain is a list containing one or more elements containing a 145 Key ID, key string, send/accept lifetimes, and the associated 146 authentication or encryption algorithm. A key chain can be used by 147 any service or application requiring authentication or encryption. 148 In essence, the key-chain is a reusable key policy that can be 149 referenced whereever it is required. The key-chain construct has 150 been implemented by most networking vendors and deployed in many 151 networks. 153 A conceptual representation of a crypto key table is described in 154 [CRYPTO-KEYTABLE]. The crypto key table also includes keys as well 155 as their corresponding lifetimes and algorithms. Additionally, the 156 key table includes key selection criteria and envisions a deployment 157 model where the details of the applications or services requiring 158 authentication or encryption permeate into the key database. The 159 YANG key-chain model described herein doesn't include key selection 160 criteria or support this deployment model. At the same time, it does 161 not preclude it. The draft [YANG-CRYPTO-KEYTABLE] describes 162 augmentations to the key chain YANG model in support of key selection 163 criteria. 165 2.1. Applicability 167 Other YANG modules may reference ietf-key-chain YANG module key-chain 168 names for authentication and encryption applications. A YANG type 169 has been provided to facilate reference to the key-chain name without 170 having to specify the complete YANG XML Path Language (XPath) 171 selector. 173 2.2. Graceful Key Rollover using Key Chains 175 Key chains may be used to gracefully update the key string and/or 176 algorithm used by an application for authentication or encryption. 177 This MAY be accomplished by accepting all the keys that have a valid 178 accept lifetime and sending the key with the most recent send 179 lifetime. One scenario for facilitating key rollover is to: 181 1. Distribute a key chain with a new key to all the routers or other 182 network devices in the domain of that key chain. The new key's 183 accept lifetime should be such that it is accepted during the key 184 rollover period. The send lifetime should be a time in the 185 future when it can be assured that all the routers in the domain 186 of that key are upgraded. This will have no immediate impact on 187 the keys used for transmission. 189 2. Assure that all the network devices have been updated with the 190 updated key chain and that their system times are roughly 191 synchronized. The system times of devices within an 192 administrative domain are commonly synchronized (e.g., using 193 Network Time Protocol (NTP) [NTP-PROTO]). This also may be 194 automated. 196 3. When the send lifetime of the new key becomes valid, the network 197 devices within the domain of key chain will start sending the new 198 key. 200 4. At some point in the future, a new key chain with the old key 201 removed may be distributed to the network devices within the 202 domain of the key chain. However, this may be deferred until the 203 next key rollover. If this is done, the key chain will always 204 include two keys; either the current and future key (during key 205 rollovers) or the current and previous keys (between key 206 rollovers). 208 3. Design of the Key Chain Model 210 The ietf-key-chain module contains a list of one or more keys indexed 211 by a Key ID. For some applications (e.g., OSPFv3 [OSPFV3-AUTH]), the 212 Key ID is used to identify the key chain key to be used. In addition 213 to the Key ID, each key chain key includes a key-string and a 214 cryptographic algorithm. Optionally, the key chain keys include 215 send/accept lifetimes. If the send/accept lifetime is unspecified, 216 the key is always considered valid. 218 Note that asymmetric keys, i.e., a different key value used for 219 transmission versus acceptance, may be supported with multiple key 220 chain elements where the accept-lifetime or send-lifetime is not 221 valid (e.g., has an end-time equal to the start-time). 223 Due to the differences in key chain implementations across various 224 vendors, some of the data elements are optional. Finally, the crypto 225 algorithm identities are provided for reuse when configuring legacy 226 authentication and encryption not using key-chains. 228 A key-chain is identified by a unique name within the scope of the 229 network device. The "key-chain-ref" typedef SHOULD be used by other 230 YANG modules when they need to reference a configured key-chain. The 231 "key-chain-state=ref" typedef SHOULD be used by other YANG modules 232 when they need to reference operational state for a configured key- 233 chain. 235 3.1. Key Chain Operational State 237 The key chain operational state is maintained in a separate tree. 238 The key string itself is omitted from the operational state to 239 minimize visibility similar to what was done with keys in SNMP MIBs. 241 The timestamp of the last key-chain modification is also maintained 242 in the operational state. Additionally, the operational state 243 includes an indication of whether or not a key chain key is valid for 244 sending or acceptance. 246 3.2. Key Chain Model Features 248 Features are used to handle differences between vendor 249 implementations. For example, not all vendors support configuration 250 an acceptance tolerance or configuration of key strings in 251 hexadecimal. They are also used to support of security requirements 252 (e.g., TCP-AO Algorithms [TCP-AO-ALGORITHMS]) not implemented by 253 vendors or only a single vendor. 255 3.3. Key Chain Model Tree 257 +--rw key-chains 258 | +--rw key-chain* [name] 259 | | +--rw name string 260 | | +--rw description? string 261 | | +--rw accept-tolerance {accept-tolerance}? 262 | | | +--rw duration? uint32 263 | | +--rw key* [key-id] 264 | | +--rw key-id uint64 265 | | +--rw lifetime 266 | | | +--rw (lifetime)? 267 | | | +--:(send-and-accept-lifetime) 268 | | | | +--rw send-accept-lifetime 269 | | | | +--rw (lifetime)? 270 | | | | +--:(always) 271 | | | | | +--rw always? empty 272 | | | | +--:(start-end-time) 273 | | | | +--rw start-date-time? yang:date-and-time 274 | | | | +--rw (end-time)? 275 | | | | +--:(infinite) 276 | | | | | +--rw no-end-time? empty 277 | | | | +--:(duration) 278 | | | | | +--rw duration? uint32 279 | | | | +--:(end-date-time) 280 | | | | +--rw end-date-time? 281 | | | | yang:date-and-time 282 | | | +--:(independent-send-accept-lifetime) 283 | | | | {independent-send-accept-lifetime}? 284 | | | +--rw send-lifetime 285 | | | | +--rw (lifetime)? 286 | | | | +--:(always) 287 | | | | | +--rw always? empty 288 | | | | +--:(start-end-time) 289 | | | | +--rw start-date-time? yang:date-and-time 290 | | | | +--rw (end-time)? 291 | | | | +--:(infinite) 292 | | | | | +--rw no-end-time? empty 293 | | | | +--:(duration) 294 | | | | | +--rw duration? uint32 295 | | | | +--:(end-date-time) 296 | | | | +--rw end-date-time? 297 | | | | yang:date-and-time 298 | | | +--rw accept-lifetime 299 | | | +--rw (lifetime)? 300 | | | +--:(always) 301 | | | | +--rw always? empty 302 | | | +--:(start-end-time) 303 | | | +--rw start-date-time? yang:date-and-time 304 | | | +--rw (end-time)? 305 | | | +--:(infinite) 306 | | | | +--rw no-end-time? empty 307 | | | +--:(duration) 308 | | | | +--rw duration? uint32 309 | | | +--:(end-date-time) 310 | | | +--rw end-date-time? 311 | | | yang:date-and-time 312 | | +--rw crypto-algorithm identityref 313 | | +--rw key-string 314 | | +--rw (key-string-style)? 315 | | +--:(keystring) 316 | | | +--rw keystring? string 317 | | +--:(hexadecimal) {hex-key-string}? 318 | | +--rw hexadecimal-string? yang:hex-string 319 | +--rw aes-key-wrap {aes-key-wrap}? 320 | +--rw enable? boolean 321 +--ro key-chains-state 322 +--ro key-chain* [name] 323 | +--ro name string 324 | +--ro description? string 325 | +--ro accept-tolerance {accept-tolerance}? 326 | | +--ro duration? uint32 327 | +--ro last-modified-timestamp? yang:date-and-time 328 | +--ro key* [key-id] 329 | +--ro key-id uint64 330 | +--ro lifetime 331 | | +--ro (lifetime)? 332 | | +--:(send-and-accept-lifetime) 333 | | | +--ro send-accept-lifetime 334 | | | +--ro (lifetime)? 335 | | | +--:(always) 336 | | | | +--ro always? empty 337 | | | +--:(start-end-time) 338 | | | +--ro start-date-time? yang:date-and-time 339 | | | +--ro (end-time)? 340 | | | +--:(infinite) 341 | | | | +--ro no-end-time? empty 342 | | | +--:(duration) 343 | | | | +--ro duration? uint32 344 | | | +--:(end-date-time) 345 | | | +--ro end-date-time? 346 | | | yang:date-and-time 347 | | +--:(independent-send-accept-lifetime) 348 | | {independent-send-accept-lifetime}? 349 | | +--ro send-lifetime 350 | | | +--ro (lifetime)? 351 | | | +--:(always) 352 | | | | +--ro always? empty 353 | | | +--:(start-end-time) 354 | | | +--ro start-date-time? yang:date-and-time 355 | | | +--ro (end-time)? 356 | | | +--:(infinite) 357 | | | | +--ro no-end-time? empty 358 | | | +--:(duration) 359 | | | | +--ro duration? uint32 360 | | | +--:(end-date-time) 361 | | | +--ro end-date-time? 362 | | | yang:date-and-time 363 | | +--ro accept-lifetime 364 | | +--ro (lifetime)? 365 | | +--:(always) 366 | | | +--ro always? empty 367 | | +--:(start-end-time) 368 | | +--ro start-date-time? yang:date-and-time 369 | | +--ro (end-time)? 370 | | +--:(infinite) 371 | | | +--ro no-end-time? empty 372 | | +--:(duration) 373 | | | +--ro duration? uint32 374 | | +--:(end-date-time) 375 | | +--ro end-date-time? 376 | | yang:date-and-time 377 | +--ro crypto-algorithm identityref 378 | +--ro key-string 379 | | +--ro (key-string-style)? 380 | | +--:(keystring) 381 | | | +--ro keystring? string 382 | | +--:(hexadecimal) {hex-key-string}? 383 | | +--ro hexadecimal-string? yang:hex-string 384 | +--ro send-lifetime-active? boolean 385 | +--ro accept-lifetime-active? boolean 386 +--ro aes-key-wrap {aes-key-wrap}? 387 +--ro enable? boolean 389 4. Key Chain YANG Model 391 file "ietf-key-chain@2017-02-16.yang" 392 module ietf-key-chain { 393 yang-version 1.1; 394 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 395 prefix key-chain; 397 import ietf-yang-types { 398 prefix yang; 399 } 400 import ietf-netconf-acm { 401 prefix nacm; 402 } 404 organization 405 "IETF RTG (Routing) Working Group"; 406 contact 407 "Acee Lindem - acee@cisco.com"; 408 description 409 "This YANG module defines the generic configuration 410 data for key-chain. It is intended that the module 411 will be extended by vendors to define vendor-specific 412 key-chain configuration parameters. 414 Copyright (c) 2015 IETF Trust and the persons identified as 415 authors of the code. All rights reserved. 417 Redistribution and use in source and binary forms, with or 418 without modification, is permitted pursuant to, and subject 419 to the license terms contained in, the Simplified BSD License 420 set forth in Section 4.c of the IETF Trust's Legal Provisions 421 Relating to IETF Documents 422 (http://trustee.ietf.org/license-info). 423 This version of this YANG module is part of RFC XXXX; see 424 the RFC itself for full legal notices."; 426 revision 2017-02-16 { 427 description 428 "Initial RFC Revision"; 429 reference "RFC XXXX: A YANG Data Model for key-chain"; 430 } 432 feature hex-key-string { 433 description 434 "Support hexadecimal key string."; 435 } 437 feature accept-tolerance { 438 description 439 "To specify the tolerance or acceptance limit."; 440 } 442 feature independent-send-accept-lifetime { 443 description 444 "Support for independent send and accept key lifetimes."; 445 } 447 feature crypto-hmac-sha-1-12 { 448 description 449 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 450 } 452 feature clear-text { 453 description 454 "Support for clear-text algorithm. Usage is 455 NOT RECOMMENDED."; 456 } 458 feature aes-cmac-prf-128 { 459 description 460 "Support for AES Cipher based Message Authentication 461 Code Pseudo Random Function."; 462 } 464 feature aes-key-wrap { 465 description 466 "Support for Advanced Encryption Standard (AES) Key Wrap."; 467 } 469 feature replay-protection-only { 470 description 471 "Provide replay-protection without any authentication 472 as required by protocols such as Bidirectional 473 Forwarding Detection (BFD)."; 474 } 476 identity crypto-algorithm { 477 description 478 "Base identity of cryptographic algorithm options."; 479 } 480 identity hmac-sha-1-12 { 481 base crypto-algorithm; 482 if-feature "crypto-hmac-sha-1-12"; 483 description 484 "The HMAC-SHA1-12 algorithm."; 485 } 487 identity aes-cmac-prf-128 { 488 base crypto-algorithm; 489 if-feature "aes-cmac-prf-128"; 490 description 491 "The AES-CMAC-PRF-128 algorithm - required by 492 RFC 5926 for TCP-AO key derivation functions."; 493 } 495 identity md5 { 496 base crypto-algorithm; 497 description 498 "The MD5 algorithm."; 499 } 501 identity sha-1 { 502 base crypto-algorithm; 503 description 504 "The SHA-1 algorithm."; 505 } 507 identity hmac-sha-1 { 508 base crypto-algorithm; 509 description 510 "HMAC-SHA-1 authentication algorithm."; 511 } 513 identity hmac-sha-256 { 514 base crypto-algorithm; 515 description 516 "HMAC-SHA-256 authentication algorithm."; 517 } 519 identity hmac-sha-384 { 520 base crypto-algorithm; 521 description 522 "HMAC-SHA-384 authentication algorithm."; 523 } 525 identity hmac-sha-512 { 526 base crypto-algorithm; 527 description 528 "HMAC-SHA-512 authentication algorithm."; 529 } 531 identity clear-text { 532 base crypto-algorithm; 533 if-feature "clear-text"; 534 description 535 "Clear text."; 536 } 538 identity replay-protection-only { 539 base crypto-algorithm; 540 if-feature "replay-protection-only"; 541 description 542 "Provide replay-protection without any authentication as 543 required by protocols such as Bidirectional Forwarding 544 Detection (BFD)."; 545 } 547 typedef key-chain-ref { 548 type leafref { 549 path 550 "/key-chain:key-chains/key-chain:key-chain/key-chain:name"; 551 } 552 description 553 "This type is used by data models that need to reference 554 configured key-chains."; 555 } 557 typedef key-chain-state-ref { 558 type leafref { 559 path "/key-chain:key-chains-state/key-chain:key-chain/"+ 560 "key-chain:name"; 561 } 562 description 563 "This type is used by data models that need to reference 564 operational state for a configured key-chain."; 565 } 567 grouping lifetime { 568 description 569 "Key lifetime specification."; 570 choice lifetime { 571 default "always"; 572 description 573 "Options for specifying key accept or send lifetimes"; 574 case always { 575 leaf always { 576 type empty; 577 description 578 "Indicates key lifetime is always valid."; 579 } 580 } 581 case start-end-time { 582 leaf start-date-time { 583 type yang:date-and-time; 584 description 585 "Start time."; 586 } 587 choice end-time { 588 default "infinite"; 589 description 590 "End-time setting."; 591 case infinite { 592 leaf no-end-time { 593 type empty; 594 description 595 "Indicates key lifetime end-time in infinite."; 596 } 597 } 598 case duration { 599 leaf duration { 600 type uint32 { 601 range "1..2147483646"; 602 } 603 units "seconds"; 604 description 605 "Key lifetime duration, in seconds"; 606 } 607 } 608 case end-date-time { 609 leaf end-date-time { 610 type yang:date-and-time; 611 description 612 "End time."; 613 } 614 } 615 } 616 } 617 } 618 } 620 grouping key-common { 621 description 622 "Key-chain key data nodes common to 623 configuration and state."; 625 container lifetime { 626 description 627 "Specify a key's lifetime."; 628 choice lifetime { 629 description 630 "Options for specification of send and accept lifetimes."; 631 case send-and-accept-lifetime { 632 description 633 "Send and accept key have the same lifetime."; 634 container send-accept-lifetime { 635 description 636 "Single lifetime specification for both 637 send and accept lifetimes."; 638 uses lifetime; 639 } 640 } 641 case independent-send-accept-lifetime { 642 if-feature "independent-send-accept-lifetime"; 643 description 644 "Independent send and accept key lifetimes."; 645 container send-lifetime { 646 description 647 "Separate lifetime specification for send lifetime."; 648 uses lifetime; 649 } 650 container accept-lifetime { 651 description 652 "Separate lifetime specification for accept lifetime."; 653 uses lifetime; 654 } 655 } 656 } 657 } 658 leaf crypto-algorithm { 659 type identityref { 660 base crypto-algorithm; 661 } 662 mandatory true; 663 description 664 "Cryptographic algorithm associated with key."; 665 } 666 container key-string { 667 description 668 "The key string."; 669 nacm:default-deny-all; 670 choice key-string-style { 671 description 672 "Key string styles"; 674 case keystring { 675 leaf keystring { 676 type string; 677 description 678 "Key string in ASCII format."; 679 } 680 } 681 case hexadecimal { 682 if-feature "hex-key-string"; 683 leaf hexadecimal-string { 684 type yang:hex-string; 685 description 686 "Key in hexadecimal string format. When compared 687 to ASCII, specification in hexadecimal affords 688 greater key entropy with the same number of 689 octets. Additionally, it discourages usage of 690 well-known words or numbers."; 691 } 692 } 693 } 694 } 695 } 697 grouping key-chain-common { 698 description 699 "key-chain common grouping."; 700 leaf name { 701 type string; 702 description 703 "Name of the key-chain."; 704 } 705 leaf description { 706 type string; 707 description 708 "A description of the key-chain"; 709 } 710 container accept-tolerance { 711 if-feature "accept-tolerance"; 712 description 713 "Tolerance for key lifetime acceptance (seconds)."; 714 leaf duration { 715 type uint32; 716 units "seconds"; 717 default "0"; 718 description 719 "Tolerance range, in seconds."; 720 } 721 } 723 } 725 container key-chains { 726 description 727 "All configured key-chains on the device."; 728 list key-chain { 729 key "name"; 730 description 731 "List of key-chains."; 732 uses key-chain-common; 733 list key { 734 key "key-id"; 735 description 736 "Single key in key chain."; 737 leaf key-id { 738 type uint64; 739 description 740 "Numeric value uniquely identifying the key"; 741 } 742 uses key-common; 743 } 744 } 745 container aes-key-wrap { 746 if-feature "aes-key-wrap"; 747 description 748 "AES Key Wrap password encryption."; 749 leaf enable { 750 type boolean; 751 default "false"; 752 description 753 "Enable AES Key Wrap encryption."; 754 } 755 } 756 } 758 container key-chains-state { 759 config false; 760 description 761 "State for all configured key-chains on the device."; 762 list key-chain { 763 key "name"; 764 description 765 "List of key-chains and operational state."; 766 uses key-chain-common; 767 leaf last-modified-timestamp { 768 type yang:date-and-time; 769 description 770 "Timestamp of the most recent update to the key-chain"; 772 } 773 list key { 774 key "key-id"; 775 description 776 "Single key in key chain."; 777 leaf key-id { 778 type uint64; 779 description 780 "Numeric value uniquely identifying the key"; 781 } 782 uses key-common; 783 leaf send-lifetime-active { 784 type boolean; 785 config false; 786 description 787 "Indicates if the send lifetime of the 788 key-chain key is currently active."; 789 } 790 leaf accept-lifetime-active { 791 type boolean; 792 config false; 793 description 794 "Indicates if the accept lifetime of the 795 key-chain key is currently active."; 796 } 797 } 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