idnits 2.17.1 draft-ietf-rtgwg-yang-key-chain-18.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 -- The document date (April 11, 2017) is 2569 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) -- Obsolete informational reference (is this intentional?): RFC 5246 (ref. 'TLS') (Obsoleted by RFC 8446) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). 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: October 13, 2017 Huawei 6 D. Yeung 7 Arrcus, Inc 8 I. Chen 9 Jabil 10 J. Zhang 11 Juniper Networks 12 April 11, 2017 14 Routing Key Chain YANG Data Model 15 draft-ietf-rtgwg-yang-key-chain-18.txt 17 Abstract 19 This document describes the key chain YANG data model. Key chains 20 are commonly used for routing protocol authentication and other 21 applications requiring symmetric keys. A key chain is a list of 22 elements each containing a key string, 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, key strings and algorithms may be gracefully updated. By 26 representing them in a YANG data model, key distribution can be 27 automated. 29 In some applications, the protocols do not use the key chain element 30 key directly, but rather a key derivation function is used to derive 31 a short-lived key from the key chain element key (e.g., the Master 32 Keys used in the TCP Authentication Option(TCP-AO)). 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 October 13, 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 . . . . . . . . . . . . . . . 6 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. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 19 81 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 82 8.1. Normative References . . . . . . . . . . . . . . . . . . 19 83 8.2. Informative References . . . . . . . . . . . . . . . . . 20 84 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 85 A.1. Simple Key Chain with Always Valid Single Key . . . . . . 21 86 A.2. Key Chain with Keys having Different Lifetimes . . . . . 22 87 A.3. Key Chain with Independent Send and Accept Lifetimes . . 23 88 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 24 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 91 1. Introduction 93 This document describes the key chain YANG [YANG] data model. Key 94 chains are commonly used for routing protocol authentication and 95 other applications requiring symmetric keys. A key chain is a list 96 of elements each containing a key string, send lifetime, accept 97 lifetime, and algorithm (authentication or encryption). By properly 98 overlapping the send and accept lifetimes of multiple key chain 99 elements, key strings and algorithms may be gracefully updated. By 100 representing them in a YANG data model, key distribution can be 101 automated. 103 In some applications, the protocols do not use the key chain element 104 key directly, but rather a key derivation function is used to derive 105 a short-lived key from the key chain element key (e.g., the Master 106 Keys used in [TCP-AO]). 108 1.1. Requirements Notation 110 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 111 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 112 "OPTIONAL" in this document are to be interpreted as described in 113 [RFC-KEYWORDS]. 115 1.2. Tree Diagrams 117 A simplified graphical representation of the complete data tree is 118 presented in Section 3.3. The following tree notation is used. 120 o Brackets "[" and "]" enclose YANG list keys. These YANG list keys 121 should not be confused with the key-chain keys. 123 o Curly braces "{" and "}" contain names of optional features that 124 make the corresponding node conditional. 126 o Abbreviations before data node names: "rw" means configuration 127 (read-write), "ro" state data (read-only), "-x" RPC operations, 128 and "-n" notifications. 130 o Symbols after data node names: "?" means an optional node, "!" a 131 container with presence, and "*" denotes a "list" or "leaf-list". 133 o Parentheses enclose choice and case nodes, and case nodes are also 134 marked with a colon (":"). 136 o Ellipsis ("...") stands for contents of subtrees that are not 137 shown. 139 2. Problem Statement 141 This document describes a YANG [YANG] data model for key chains. Key 142 chains have been implemented and deployed by a large percentage of 143 network equipment vendors. Providing a standard YANG model will 144 facilitate automated key distribution and non-disruptive key 145 rollover. This will aid in tightening the security of the core 146 routing infrastructure as recommended in [IAB-REPORT]. 148 A key chain is a list containing one or more elements containing a 149 Key ID, key string, send/accept lifetimes, and the associated 150 authentication or encryption algorithm. A key chain can be used by 151 any service or application requiring authentication or encryption. 152 In essence, the key-chain is a reusable key policy that can be 153 referenced wherever it is required. The key-chain construct has been 154 implemented by most networking vendors and deployed in many networks. 156 A conceptual representation of a crypto key table is described in 157 [CRYPTO-KEYTABLE]. The crypto key table also includes keys as well 158 as their corresponding lifetimes and algorithms. Additionally, the 159 key table includes key selection criteria and envisions a deployment 160 model where the details of the applications or services requiring 161 authentication or encryption permeate into the key database. The 162 YANG key-chain model described herein doesn't include key selection 163 criteria or support this deployment model. At the same time, it does 164 not preclude it. The draft [YANG-CRYPTO-KEYTABLE] describes 165 augmentations to the key chain YANG model in support of key selection 166 criteria. 168 2.1. Applicability 170 Other YANG modules may reference ietf-key-chain YANG module key-chain 171 names for authentication and encryption applications. A YANG type 172 has been provided to facilitate reference to the key-chain name 173 without having to specify the complete YANG XML Path Language (XPath) 174 selector. 176 2.2. Graceful Key Rollover using Key Chains 178 Key chains may be used to gracefully update the key string and/or 179 algorithm used by an application for authentication or encryption. 180 This MAY be accomplished by accepting all the keys that have a valid 181 accept lifetime and sending the key with the most recent send 182 lifetime. One scenario for facilitating key rollover is to: 184 1. Distribute a key chain with a new key to all the routers or other 185 network devices in the domain of that key chain. The new key's 186 accept lifetime should be such that it is accepted during the key 187 rollover period. The send lifetime should be a time in the 188 future when it can be assured that all the routers in the domain 189 of that key are upgraded. This will have no immediate impact on 190 the keys used for transmission. 192 2. Assure that all the network devices have been updated with the 193 updated key chain and that their system times are roughly 194 synchronized. The system times of devices within an 195 administrative domain are commonly synchronized (e.g., using 196 Network Time Protocol (NTP) [NTP-PROTO]). This also may be 197 automated. 199 3. When the send lifetime of the new key becomes valid, the network 200 devices within the domain of key chain will using the new key for 201 transmissions. 203 4. At some point in the future, a new key chain with the old key 204 removed may be distributed to the network devices within the 205 domain of the key chain. However, this may be deferred until the 206 next key rollover. If this is done, the key chain will always 207 include two keys; either the current and future key (during key 208 rollovers) or the current and previous keys (between key 209 rollovers). 211 3. Design of the Key Chain Model 213 The ietf-key-chain module contains a list of one or more keys indexed 214 by a Key ID. For some applications (e.g., OSPFv3 [OSPFV3-AUTH]), the 215 Key ID is used to identify the key chain key to be used. In addition 216 to the Key ID, each key chain key includes a key-string and a 217 cryptographic algorithm. Optionally, the key chain keys include 218 send/accept lifetimes. If the send/accept lifetime is unspecified, 219 the key is always considered valid. 221 Note that different key values for transmission versus acceptance may 222 be supported with multiple key chain elements where the accept- 223 lifetime or send-lifetime is not valid (e.g., has an end-time equal 224 to the start-time). 226 Due to the differences in key chain implementations across various 227 vendors, some of the data elements are optional. Finally, the crypto 228 algorithm identities are provided for reuse when configuring legacy 229 authentication and encryption not using key-chains. 231 A key-chain is identified by a unique name within the scope of the 232 network device. The "key-chain-ref" typedef SHOULD be used by other 233 YANG modules when they need to reference a configured key-chain. The 234 "key-chain-state=ref" typedef SHOULD be used by other YANG modules 235 when they need to reference operational state for a configured key- 236 chain. 238 3.1. Key Chain Operational State 240 The key chain operational state is maintained in a separate tree. 241 The key string itself is omitted from the operational state to 242 minimize visibility similar to what was done with keys in SNMP MIBs. 243 The timestamp of the last key-chain modification is also maintained 244 in the operational state. Additionally, the operational state 245 includes an indication of whether or not a key chain key is valid for 246 sending or acceptance. 248 3.2. Key Chain Model Features 250 Features are used to handle differences between vendor 251 implementations. For example, not all vendors support configuration 252 of an acceptance tolerance or configuration of key strings in 253 hexadecimal. They are also used to support of security requirements 254 (e.g., TCP-AO Algorithms [TCP-AO-ALGORITHMS]) not implemented by 255 vendors or only a single vendor. 257 3.3. Key Chain Model Tree 259 +--rw key-chains 260 | +--rw key-chain* [name] 261 | | +--rw name string 262 | | +--rw description? string 263 | | +--rw accept-tolerance {accept-tolerance}? 264 | | | +--rw duration? uint32 265 | | +--rw key* [key-id] 266 | | +--rw key-id uint64 267 | | +--rw lifetime 268 | | | +--rw (lifetime)? 269 | | | +--:(send-and-accept-lifetime) 270 | | | | +--rw send-accept-lifetime 271 | | | | +--rw (lifetime)? 272 | | | | +--:(always) 273 | | | | | +--rw always? empty 274 | | | | +--:(start-end-time) 275 | | | | +--rw start-date-time? yang:date-and-time 276 | | | | +--rw (end-time)? 277 | | | | +--:(infinite) 278 | | | | | +--rw no-end-time? empty 279 | | | | +--:(duration) 280 | | | | | +--rw duration? uint32 281 | | | | +--:(end-date-time) 282 | | | | +--rw end-date-time? 283 | | | | yang:date-and-time 284 | | | +--:(independent-send-accept-lifetime) 285 | | | | {independent-send-accept-lifetime}? 286 | | | +--rw send-lifetime 287 | | | | +--rw (lifetime)? 288 | | | | +--:(always) 289 | | | | | +--rw always? empty 290 | | | | +--:(start-end-time) 291 | | | | +--rw start-date-time? yang:date-and-time 292 | | | | +--rw (end-time)? 293 | | | | +--:(infinite) 294 | | | | | +--rw no-end-time? empty 295 | | | | +--:(duration) 296 | | | | | +--rw duration? uint32 297 | | | | +--:(end-date-time) 298 | | | | +--rw end-date-time? 299 | | | | yang:date-and-time 300 | | | +--rw accept-lifetime 301 | | | +--rw (lifetime)? 302 | | | +--:(always) 303 | | | | +--rw always? empty 304 | | | +--:(start-end-time) 305 | | | +--rw start-date-time? yang:date-and-time 306 | | | +--rw (end-time)? 307 | | | +--:(infinite) 308 | | | | +--rw no-end-time? empty 309 | | | +--:(duration) 310 | | | | +--rw duration? uint32 311 | | | +--:(end-date-time) 312 | | | +--rw end-date-time? 313 | | | yang:date-and-time 314 | | +--rw crypto-algorithm identityref 315 | | +--rw key-string 316 | | +--rw (key-string-style)? 317 | | +--:(keystring) 318 | | | +--rw keystring? string 319 | | +--:(hexadecimal) {hex-key-string}? 320 | | +--rw hexadecimal-string? yang:hex-string 321 | +--rw aes-key-wrap {aes-key-wrap}? 322 | +--rw enable? boolean 323 +--ro key-chains-state 324 +--ro key-chain* [name] 325 | +--ro name string 326 | +--ro description? string 327 | +--ro accept-tolerance {accept-tolerance}? 328 | | +--ro duration? uint32 329 | +--ro last-modified-timestamp? yang:date-and-time 330 | +--ro key* [key-id] 331 | +--ro key-id uint64 332 | +--ro lifetime 333 | | +--ro (lifetime)? 334 | | +--:(send-and-accept-lifetime) 335 | | | +--ro send-accept-lifetime 336 | | | +--ro (lifetime)? 337 | | | +--:(always) 338 | | | | +--ro always? empty 339 | | | +--:(start-end-time) 340 | | | +--ro start-date-time? yang:date-and-time 341 | | | +--ro (end-time)? 342 | | | +--:(infinite) 343 | | | | +--ro no-end-time? empty 344 | | | +--:(duration) 345 | | | | +--ro duration? uint32 346 | | | +--:(end-date-time) 347 | | | +--ro end-date-time? 348 | | | yang:date-and-time 349 | | +--:(independent-send-accept-lifetime) 350 | | {independent-send-accept-lifetime}? 351 | | +--ro send-lifetime 352 | | | +--ro (lifetime)? 353 | | | +--:(always) 354 | | | | +--ro always? empty 355 | | | +--:(start-end-time) 356 | | | +--ro start-date-time? yang:date-and-time 357 | | | +--ro (end-time)? 358 | | | +--:(infinite) 359 | | | | +--ro no-end-time? empty 360 | | | +--:(duration) 361 | | | | +--ro duration? uint32 362 | | | +--:(end-date-time) 363 | | | +--ro end-date-time? 364 | | | yang:date-and-time 365 | | +--ro accept-lifetime 366 | | +--ro (lifetime)? 367 | | +--:(always) 368 | | | +--ro always? empty 369 | | +--:(start-end-time) 370 | | +--ro start-date-time? yang:date-and-time 371 | | +--ro (end-time)? 372 | | +--:(infinite) 373 | | | +--ro no-end-time? empty 374 | | +--:(duration) 375 | | | +--ro duration? uint32 376 | | +--:(end-date-time) 377 | | +--ro end-date-time? 378 | | yang:date-and-time 379 | +--ro crypto-algorithm identityref 380 | +--ro key-string 381 | | +--ro (key-string-style)? 382 | | +--:(keystring) 383 | | | +--ro keystring? string 384 | | +--:(hexadecimal) {hex-key-string}? 385 | | +--ro hexadecimal-string? yang:hex-string 386 | +--ro send-lifetime-active? boolean 387 | +--ro accept-lifetime-active? boolean 388 +--ro aes-key-wrap {aes-key-wrap}? 389 +--ro enable? boolean 391 4. Key Chain YANG Model 393 file "ietf-key-chain@2017-02-16.yang" 394 module ietf-key-chain { 395 yang-version 1.1; 396 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 397 prefix key-chain; 399 import ietf-yang-types { 400 prefix yang; 401 } 402 import ietf-netconf-acm { 403 prefix nacm; 404 } 406 organization 407 "IETF RTG (Routing) Working Group"; 408 contact 409 "Acee Lindem - acee@cisco.com"; 410 description 411 "This YANG module defines the generic configuration 412 data for key-chain. It is intended that the module 413 will be extended by vendors to define vendor-specific 414 key-chain configuration parameters. 416 Copyright (c) 2015 IETF Trust and the persons identified as 417 authors of the code. All rights reserved. 419 Redistribution and use in source and binary forms, with or 420 without modification, is permitted pursuant to, and subject 421 to the license terms contained in, the Simplified BSD License 422 set forth in Section 4.c of the IETF Trust's Legal Provisions 423 Relating to IETF Documents 424 (http://trustee.ietf.org/license-info). 425 This version of this YANG module is part of RFC XXXX; see 426 the RFC itself for full legal notices."; 428 revision 2017-02-16 { 429 description 430 "Initial RFC Revision"; 431 reference "RFC XXXX: A YANG Data Model for key-chain"; 432 } 434 feature hex-key-string { 435 description 436 "Support hexadecimal key string."; 437 } 439 feature accept-tolerance { 440 description 441 "To specify the tolerance or acceptance limit."; 442 } 444 feature independent-send-accept-lifetime { 445 description 446 "Support for independent send and accept key lifetimes."; 447 } 449 feature crypto-hmac-sha-1-12 { 450 description 451 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 452 } 454 feature clear-text { 455 description 456 "Support for clear-text algorithm. Usage is 457 NOT RECOMMENDED."; 458 } 460 feature aes-cmac-prf-128 { 461 description 462 "Support for AES Cipher based Message Authentication 463 Code Pseudo Random Function."; 464 } 466 feature aes-key-wrap { 467 description 468 "Support for Advanced Encryption Standard (AES) Key Wrap."; 469 } 471 feature replay-protection-only { 472 description 473 "Provide replay-protection without any authentication 474 as required by protocols such as Bidirectional 475 Forwarding Detection (BFD)."; 476 } 477 identity crypto-algorithm { 478 description 479 "Base identity of cryptographic algorithm options."; 480 } 482 identity hmac-sha-1-12 { 483 base crypto-algorithm; 484 if-feature "crypto-hmac-sha-1-12"; 485 description 486 "The HMAC-SHA1-12 algorithm."; 487 } 489 identity aes-cmac-prf-128 { 490 base crypto-algorithm; 491 if-feature "aes-cmac-prf-128"; 492 description 493 "The AES-CMAC-PRF-128 algorithm - required by 494 RFC 5926 for TCP-AO key derivation functions."; 495 } 497 identity md5 { 498 base crypto-algorithm; 499 description 500 "The MD5 algorithm."; 501 } 503 identity sha-1 { 504 base crypto-algorithm; 505 description 506 "The SHA-1 algorithm."; 507 } 509 identity hmac-sha-1 { 510 base crypto-algorithm; 511 description 512 "HMAC-SHA-1 authentication algorithm."; 513 } 515 identity hmac-sha-256 { 516 base crypto-algorithm; 517 description 518 "HMAC-SHA-256 authentication algorithm."; 519 } 521 identity hmac-sha-384 { 522 base crypto-algorithm; 523 description 524 "HMAC-SHA-384 authentication algorithm."; 526 } 528 identity hmac-sha-512 { 529 base crypto-algorithm; 530 description 531 "HMAC-SHA-512 authentication algorithm."; 532 } 534 identity clear-text { 535 base crypto-algorithm; 536 if-feature "clear-text"; 537 description 538 "Clear text."; 539 } 541 identity replay-protection-only { 542 base crypto-algorithm; 543 if-feature "replay-protection-only"; 544 description 545 "Provide replay-protection without any authentication as 546 required by protocols such as Bidirectional Forwarding 547 Detection (BFD)."; 548 } 550 typedef key-chain-ref { 551 type leafref { 552 path 553 "/key-chain:key-chains/key-chain:key-chain/key-chain:name"; 554 } 555 description 556 "This type is used by data models that need to reference 557 configured key-chains."; 558 } 560 typedef key-chain-state-ref { 561 type leafref { 562 path "/key-chain:key-chains-state/key-chain:key-chain/"+ 563 "key-chain:name"; 564 } 565 description 566 "This type is used by data models that need to reference 567 operational state for a configured key-chain."; 568 } 570 grouping lifetime { 571 description 572 "Key lifetime specification."; 573 choice lifetime { 574 default "always"; 575 description 576 "Options for specifying key accept or send lifetimes"; 577 case always { 578 leaf always { 579 type empty; 580 description 581 "Indicates key lifetime is always valid."; 582 } 583 } 584 case start-end-time { 585 leaf start-date-time { 586 type yang:date-and-time; 587 description 588 "Start time."; 589 } 590 choice end-time { 591 default "infinite"; 592 description 593 "End-time setting."; 594 case infinite { 595 leaf no-end-time { 596 type empty; 597 description 598 "Indicates key lifetime end-time in infinite."; 599 } 600 } 601 case duration { 602 leaf duration { 603 type uint32 { 604 range "1..2147483646"; 605 } 606 units "seconds"; 607 description 608 "Key lifetime duration, in seconds"; 609 } 610 } 611 case end-date-time { 612 leaf end-date-time { 613 type yang:date-and-time; 614 description 615 "End time."; 616 } 617 } 618 } 619 } 620 } 621 } 622 grouping key-common { 623 description 624 "Key-chain key data nodes common to 625 configuration and state."; 626 container lifetime { 627 description 628 "Specify a key's lifetime."; 629 choice lifetime { 630 description 631 "Options for specification of send and accept lifetimes."; 632 case send-and-accept-lifetime { 633 description 634 "Send and accept key have the same lifetime."; 635 container send-accept-lifetime { 636 description 637 "Single lifetime specification for both 638 send and accept lifetimes."; 639 uses lifetime; 640 } 641 } 642 case independent-send-accept-lifetime { 643 if-feature "independent-send-accept-lifetime"; 644 description 645 "Independent send and accept key lifetimes."; 646 container send-lifetime { 647 description 648 "Separate lifetime specification for send lifetime."; 649 uses lifetime; 650 } 651 container accept-lifetime { 652 description 653 "Separate lifetime specification for accept lifetime."; 654 uses lifetime; 655 } 656 } 657 } 658 } 659 leaf crypto-algorithm { 660 type identityref { 661 base crypto-algorithm; 662 } 663 mandatory true; 664 description 665 "Cryptographic algorithm associated with key."; 666 } 667 container key-string { 668 description 669 "The key string."; 671 nacm:default-deny-all; 672 choice key-string-style { 673 description 674 "Key string styles"; 675 case keystring { 676 leaf keystring { 677 type string; 678 description 679 "Key string in ASCII format."; 680 } 681 } 682 case hexadecimal { 683 if-feature "hex-key-string"; 684 leaf hexadecimal-string { 685 type yang:hex-string; 686 description 687 "Key in hexadecimal string format. When compared 688 to ASCII, specification in hexadecimal affords 689 greater key entropy with the same number of 690 octets. Additionally, it discourages usage of 691 well-known words or numbers."; 692 } 693 } 694 } 695 } 696 } 698 grouping key-chain-common { 699 description 700 "key-chain common grouping."; 701 leaf name { 702 type string; 703 description 704 "Name of the key-chain."; 705 } 706 leaf description { 707 type string; 708 description 709 "A description of the key-chain"; 710 } 711 container accept-tolerance { 712 if-feature "accept-tolerance"; 713 description 714 "Tolerance for key lifetime acceptance (seconds)."; 715 leaf duration { 716 type uint32; 717 units "seconds"; 718 default "0"; 719 description 720 "Tolerance range, in seconds."; 721 } 722 } 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"; 771 } 772 list key { 773 key "key-id"; 774 description 775 "Single key in key chain."; 776 leaf key-id { 777 type uint64; 778 description 779 "Numeric value uniquely identifying the key"; 780 } 781 uses key-common; 782 leaf send-lifetime-active { 783 type boolean; 784 config false; 785 description 786 "Indicates if the send lifetime of the 787 key-chain key is currently active."; 788 } 789 leaf accept-lifetime-active { 790 type boolean; 791 config false; 792 description 793 "Indicates if the accept lifetime of the 794 key-chain key is currently active."; 795 } 796 } 797 } 798 container aes-key-wrap { 799 if-feature "aes-key-wrap"; 800 description 801 "AES Key Wrap password encryption."; 802 leaf enable { 803 type boolean; 804 description 805 "Indicates whether AES Key Wrap encryption is enabled."; 806 } 807 } 808 } 809 } 810 812 5. Security Considerations 814 The YANG module defined in this document is designed to be accessed 815 via network management protocols such as NETCONF [NETCONF] or 816 RESTCONF [RESTCONF]. The lowest NETCONF layer is the secure 817 transport layer, and the mandatory-to-implement secure transport is 818 Secure Shell (SSH) [NETCONF-SSH]. The lowest RESTCONF layer is 819 HTTPS, and the mandatory-to-implement secure transport is TLS [TLS]. 821 The NETCONF access control model [NETCONF-ACM] provides the means to 822 restrict access for particular NETCONF or RESTCONF users to a pre- 823 configured subset of all available NETCONF or RESTCONF protocol 824 operations and content. The key strings are not accessible by 825 default and NETCONF Access Control Mode [NETCONF-ACM] rules are 826 required to configure or retrieve them. 828 When configured, the key-strings can be encrypted using the AES Key 829 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 830 not included in the YANG model and must be set or derived independent 831 of key-chain configuration. When AES key-encryption is used, the 832 hex-key-string feature is also required since the encrypted keys will 833 contain characters that are not representable in the YANG string 834 built-in type [YANG]. AES key-encryption MAY be used for added key 835 security in situations where the NETCONF Access Control Mode is not 836 available. 838 The clear-text algorithm is included as a YANG feature. Usage is NOT 839 RECOMMENDED except in cases where the application and device have no 840 other alternative (e.g., a legacy network device that must 841 authenticate packets at intervals of 10 milliseconds or less for many 842 peers using Bidirectional Forwarding Detection [BFD]). Keys used 843 with the clear-text algorithm are considered insecure and SHOULD NOT 844 be reused with more secure algorithms. 846 Similarly, the MD5 and SHA-1 algorithms have been proven to be 847 insecure ([Dobb96a], [Dobb96b], and [SHA-SEC-CON]) and usage is NOT 848 RECOMMENDED. Usage should be confined to deployments where it is 849 required for backward compatibility. 851 It is RECOMMENDED that keys be encrypted or otherwise obfuscated when 852 stored internally on a network device supporting this specification. 854 6. IANA Considerations 856 This document registers a URI in the IETF XML registry 857 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 858 following registration is requested to be made: 860 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 862 Registrant Contact: The IESG. 864 XML: N/A, the requested URI is an XML namespace. 866 This document registers a YANG module in the YANG Module Names 867 registry [YANG]. 869 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 870 key-chain prefix: ietf-key-chain reference: RFC XXXX 872 7. Contributors 874 Contributors' Addresses 876 Yi Yang 877 SockRate 879 Email: yi.yang@sockrate.com 881 8. References 883 8.1. Normative References 885 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 886 Bierman, "Network Configuration Protocol (NETCONF)", RFC 887 6241, June 2011. 889 [NETCONF-ACM] 890 Bierman, A. and M. Bjorklund, "Network Configuration 891 Protocol (NETCONF) Access Control Model", RFC 6536, March 892 2012. 894 [RFC-KEYWORDS] 895 Bradner, S., "Key words for use in RFC's to Indicate 896 Requirement Levels", BCP 14, RFC 2119, March 1997. 898 [XML-REGISTRY] 899 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 900 January 2004. 902 [YANG] Bjorklund, M., "The YANG 1.1 Data Modeling Language", RFC 903 7950, August 2016. 905 8.2. Informative References 907 [AES-KEY-WRAP] 908 Housley, R. and M. Dworkin, "Advanced Encryption Standard 909 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 910 2009. 912 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 913 (BFD)", RFC 5880, June 2010. 915 [CRYPTO-KEYTABLE] 916 Housley, R., Polk, T., Hartman, S., and D. Zhang, 917 "Table of Cryptographic Keys", RFC 7210, April 2014. 919 [Dobb96a] Dobbertin, H., "Cryptanalysis of MD5 Compress", Technical 920 Report (Presented at the RUMP Session of EuroCrypt 1996), 921 2 May 1996. 923 [Dobb96b] Dobbertin, H., "The Status of MD5 After a Recent Attack", 924 CryptoBytes Vol. 2, No. 2, Summer 1996. 926 [IAB-REPORT] 927 Andersson, L., Davies, E., and L. Zhang, "Report from the 928 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 929 4948, August 2007. 931 [NETCONF-SSH] 932 Wasserman, M., "NETCONF over SSH", RFC 6242, June 2011. 934 [NTP-PROTO] 935 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 936 Time Protocol Version 4: Protocol and Algorithms 937 Specification", RFC 5905, June 2010. 939 [OSPFV3-AUTH] 940 Bhatia, M., Manral, V., and A. Lindem, "Supporting 941 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 943 [RESTCONF] 944 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 945 Protocol", RFC 8040, January 2017. 947 [SHA-SEC-CON] 948 Polk, T., Chen, L., Turner, S., and P. Hoffman, "Security 949 Considerations for the SHA-0 and SHA-1 Message-Digest 950 Algorithms", RFC 6194, February 2011. 952 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 953 Authentication Option", RFC 5925, June 2010. 955 [TCP-AO-ALGORITHMS] 956 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 957 for the TCP Authentication Option (TCP-AO)", RFC 5926, 958 June 2010. 960 [TLS] Dierks, T. and E. Rescorla, "The Transport Layer Security 961 (TLS) Protocol", RFC 5246, August 2008. 963 [YANG-CRYPTO-KEYTABLE] 964 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 965 chen-rtg-key-table-yang-00.txt (work in progress), 966 November 2015. 968 Appendix A. Examples 970 A.1. Simple Key Chain with Always Valid Single Key 972 973 974 975 976 keychain-no-end-time 977 978 A key chain with a single key that is always valid for tx/rx 979 980 981 100 982 983 984 985 986 987 md5 988 989 keystring_in_ascii_100 990 991 992 993 994 996 A.2. Key Chain with Keys having Different Lifetimes 998 999 1000 1001 1002 keychain2 1003 1004 A key chain where each key contains different send time 1005 and accept time 1006 1007 1008 35 1009 1010 1011 2017-01-01T00:00:00Z 1012 2017-02-01T00:00:00Z 1013 1014 1015 2016-12-31T23:59:55Z 1016 2017-02-01T00:00:05Z 1017 1018 1019 hmac-sha-1 1020 1021 keystring_in_ascii_35 1022 1023 1024 1025 36 1026 1027 1028 2017-02-01T00:00:00Z 1029 2017-03-01T00:00:00Z 1030 1031 1032 2017-01-31T23:59:55Z 1033 2017-03-01T00:00:05Z 1034 1035 1036 hmac-sha-1 1037 1038 fe:ed:be:af:36 1039 1040 1041 1042 1043 1045 A.3. Key Chain with Independent Send and Accept Lifetimes 1047 1048 1049 1050 1051 keychain2 1052 1053 A key chain where each key contains different send time 1054 and accept time 1055 1056 1057 35 1058 1059 1060 2017-01-01T00:00:00Z 1061 2017-02-01T00:00:00Z 1062 1063 1064 2016-12-31T23:59:55Z 1065 2017-02-01T00:00:05Z 1066 1067 1068 hmac-sha-1 1069 1070 keystring_in_ascii_35 1071 1072 1073 1074 36 1075 1076 1077 2017-02-01T00:00:00Z 1078 2017-03-01T00:00:00Z 1079 1080 1081 2017-01-31T23:59:55Z 1082 2017-03-01T00:00:05Z 1083 1084 1085 hmac-sha-1 1086 1087 fe:ed:be:af:36 1088 1089 1090 1091 1092 1094 Appendix B. Acknowledgments 1096 The RFC text was produced using Marshall Rose's xml2rfc tool. 1098 Thanks to Brian Weis for fruitful discussions on security 1099 requirements. 1101 Thanks to Ines Robles for Routing Directorate QA review comments. 1103 Thanks to Ladislav Lhotka for YANG Doctor comments. 1105 Thanks to Martin Bjorklund for additional YANG Doctor comments. 1107 Thanks to Tom Petch for comments during IETF last call. 1109 Thanks to Matthew Miller for comments made during the Gen-ART review. 1111 Thanks to Vincent Roca for comments made during the Security 1112 Directorate review. 1114 Authors' Addresses 1116 Acee Lindem (editor) 1117 Cisco Systems 1118 301 Midenhall Way 1119 Cary, NC 27513 1120 USA 1122 Email: acee@cisco.com 1124 Yingzhen Qu 1125 Huawei 1127 Email: yingzhen.qu@huawei.com 1129 Derek Yeung 1130 Arrcus, Inc 1132 Email: derek@arrcus.com 1134 Ing-Wher Chen 1135 Jabil 1137 Email: ing-wher_chen@jabil.com 1138 Jeffrey Zhang 1139 Juniper Networks 1140 10 Technology Park Drive 1141 Westford, MA 01886 1142 USA 1144 Email: zzhang@juniper.net