idnits 2.17.1 draft-ietf-rtgwg-yang-key-chain-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (September 19, 2016) is 2774 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-09) exists of draft-ietf-netconf-server-model-08 -- Unexpected draft version: The latest known version of draft-chen-rtg-key-table-yang is -00, but you're referring to -02. Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 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 Y. Qu 4 Intended status: Standards Track Cisco Systems 5 Expires: March 23, 2017 D. Yeung 6 Arrcus, Inc 7 I. Chen 8 Ericsson 9 J. Zhang 10 Juniper Networks 11 Y. Yang 12 Cisco Systems 13 September 19, 2016 15 Routing Key Chain YANG Data Model 16 draft-ietf-rtgwg-yang-key-chain-09.txt 18 Abstract 20 This document describes the key chain YANG data model. A key chain 21 is a list of elements each containing a key, send lifetime, accept 22 lifetime, and algorithm (authentication or encryption). By properly 23 overlapping the send and accept lifetimes of multiple key chain 24 elements, keys and algorithms may be gracefully updated. By 25 representing them in a YANG data model, key distribution can be 26 automated. Key chains are commonly used for routing protocol 27 authentication and other applications. In some applications, the 28 protocols do not use the key chain element key directly, but rather a 29 key derivation function is used to derive a short-lived key from the 30 key chain element key (e.g., the Master Keys used in the TCP 31 Authentication Option. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on March 23, 2017. 50 Copyright Notice 52 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . . . 19 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 82 7.2. Informative References . . . . . . . . . . . . . . . . . 20 83 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 21 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 86 1. Introduction 88 This document describes the key chain YANG data model. A key chain 89 is a list of elements each containing a key, send lifetime, accept 90 lifetime, and algorithm (authentication or encryption). By properly 91 overlapping the send and accept lifetimes of multiple key chain 92 elements, keys and algorithms may be gracefully updated. By 93 representing them in a YANG data model, key distribution can be 94 automated. Key chains are commonly used for routing protocol 95 authentication and other applications. In some applications, the 96 protocols do not use the key chain element key directly, but rather a 97 key derivation function is used to derive a short-lived key from the 98 key chain element key (e.g., the Master Keys used in [TCP-AO]). 100 1.1. Requirements Notation 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in [RFC-KEYWORDS]. 106 1.2. Tree Diagrams 108 A simplified graphical representation of the complete data tree is 109 presented in Section 3.3. The following tree notation is used. 111 o Brackets "[" and "]" enclose list keys. 113 o Curly braces "{" and "}" contain names of optional features that 114 make the corresponding node conditional. 116 o Abbreviations before data node names: "rw" means configuration 117 (read-write), "ro" state data (read-only), "-x" RPC operations, 118 and "-n" notifications. 120 o Symbols after data node names: "?" means an optional node, "!" a 121 container with presence, and "*" denotes a "list" or "leaf-list". 123 o Parentheses enclose choice and case nodes, and case nodes are also 124 marked with a colon (":"). 126 o Ellipsis ("...") stands for contents of subtrees that are not 127 shown. 129 2. Problem Statement 131 This document describes a YANG [YANG] data model for key chains. Key 132 chains have been implemented and deployed by a large percentage of 133 network equipment vendors. Providing a standard YANG model will 134 facilitate automated key distribution and non-disruptive key 135 rollover. This will aid in tightening the security of the core 136 routing infrastructure as recommended in [IAB-REPORT]. 138 A key chain is a list containing one or more elements containing a 139 Key ID, key, send/accept lifetimes, and the associated authentication 140 or encryption algorithm. A key chain can be used by any service or 141 application requiring authentication or encryption. In essence, the 142 key-chain is a reusable key policy that can be referenced where ever 143 it is required. The key-chain construct has been implemented by most 144 networking vendors and deployed in many networks. 146 The module name was change from ietf-key-chain to ietf-routing-key- 147 chain to avoid disambiguate it from the ietf-system-keychain module 148 defined in [NETCONF-SERVER-CONF]. However, due to popular demand, 149 the module name has been restored to simply ietf-key-chain. 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. Additionally, the 223 key-chain is made a grouping so that an implementation could support 224 scoping other than at the global level. Finally, the crypto- 225 algorithm-types grouping is provided for reuse when configuring 226 legacy 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. 232 3.1. Key Chain Operational State 234 The key chain operational state is maintained in the key-chain 235 entries along with the configuration state. The key string itself is 236 omitted from the operational state to minimize visibility similar to 237 what was done with keys in SNMP MIBs. The timestamp of the last key- 238 chain modification is also maintained in the operational state. 239 Additionally, the operational state includes an indication of whether 240 or not a key chain entry is valid for sending or acceptance. 242 3.2. Key Chain Model Features 244 Features are used to handle differences between vendor 245 implementations. For example, not all vendors support configuration 246 an acceptance tolerance or configuration of key strings in 247 hexadecimal. They are also used to support of security requirements 248 (e.g., TCP-AO Algorithms [TCP-AO-ALGORITHMS]) not implemented by 249 vendors or only a single vendor. 251 3.3. Key Chain Model Tree 253 module: ietf-key-chain 254 +--rw key-chains 255 +--rw key-chain-list* [name] 256 | +--rw name string 257 | +--ro name-state? string 258 | +--rw description? string 259 | +--rw accept-tolerance {accept-tolerance}? 260 | | +--rw duration? uint32 261 | +--ro accept-tolerance-state 262 | | +--ro duration? uint32 263 | +--ro last-modified-timestamp? yang:date-and-time 264 | +--rw key-chain-entry* [key-id] 265 | +--rw key-id uint64 266 | +--ro key-id-state? uint64 267 | +--rw key-string 268 | | +--rw (key-string-style)? 269 | | +--:(keystring) 270 | | | +--rw keystring? string 271 | | +--:(hexadecimal) {hex-key-string}? 272 | | +--rw hexadecimal-string? yang:hex-string 273 | +--rw lifetime 274 | | +--rw (lifetime)? 275 | | +--:(send-and-accept-lifetime) 276 | | | +--rw send-accept-lifetime 277 | | | +--rw (lifetime)? 278 | | | +--:(always) 279 | | | | +--rw always? empty 280 | | | +--:(start-end-time) 281 | | | +--rw start-date-time? yang:date-and-time 282 | | | +--rw (end-time)? 283 | | | +--:(infinite) 284 | | | | +--rw no-end-time? empty 285 | | | +--:(duration) 286 | | | | +--rw duration? uint32 287 | | | +--:(end-date-time) 288 | | | +--rw end-date-time? 289 | | | yang:date-and-time 290 | | +--:(independent-send-accept-lifetime) 291 | | {independent-send-accept-lifetime}? 292 | | +--rw send-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 accept-lifetime 307 | | +--rw (lifetime)? 308 | | +--:(always) 309 | | | +--rw always? empty 310 | | +--:(start-end-time) 311 | | +--rw start-date-time? yang:date-and-time 312 | | +--rw (end-time)? 313 | | +--:(infinite) 314 | | | +--rw no-end-time? empty 315 | | +--:(duration) 316 | | | +--rw duration? uint32 317 | | +--:(end-date-time) 318 | | +--rw end-date-time? 319 | | yang:date-and-time 320 | +--ro lifetime-state 321 | | +--ro send-lifetime 322 | | | +--ro (lifetime)? 323 | | | +--:(always) 324 | | | | +--ro always? empty 325 | | | +--:(start-end-time) 326 | | | +--ro start-date-time? yang:date-and-time 327 | | | +--ro (end-time)? 328 | | | +--:(infinite) 329 | | | | +--ro no-end-time? empty 330 | | | +--:(duration) 331 | | | | +--ro duration? uint32 332 | | | +--:(end-date-time) 333 | | | +--ro end-date-time? yang:date-and-time 334 | | +--ro send-valid? boolean 335 | | +--ro 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? yang:date-and-time 348 | | +--ro accept-valid? boolean 349 | +--rw crypto-algorithm 350 | | +--rw (algorithm)? 351 | | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 352 | | | +--rw hmac-sha1-12? empty 353 | | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 354 | | | +--rw aes-cmac-prf-128? empty 355 | | +--:(md5) 356 | | | +--rw md5? empty 357 | | +--:(sha-1) 358 | | | +--rw sha-1? empty 359 | | +--:(hmac-sha-1) 360 | | | +--rw hmac-sha-1? empty 361 | | +--:(hmac-sha-256) 362 | | | +--rw hmac-sha-256? empty 363 | | +--:(hmac-sha-384) 364 | | | +--rw hmac-sha-384? empty 365 | | +--:(hmac-sha-512) 366 | | | +--rw hmac-sha-512? empty 367 | | +--:(clear-text) {clear-text}? 368 | | | +--rw clear-text? empty 369 | | +--:(replay-protection-only) {replay-protection-only}? 370 | | +--rw replay-protection-only? empty 371 | +--ro crypto-algorithm-state 372 | +--ro (algorithm)? 373 | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 374 | | +--ro hmac-sha1-12? empty 375 | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 376 | | +--ro aes-cmac-prf-128? empty 377 | +--:(md5) 378 | | +--ro md5? empty 379 | +--:(sha-1) 380 | | +--ro sha-1? empty 381 | +--:(hmac-sha-1) 382 | | +--ro hmac-sha-1? empty 383 | +--:(hmac-sha-256) 384 | | +--ro hmac-sha-256? empty 385 | +--:(hmac-sha-384) 386 | | +--ro hmac-sha-384? empty 387 | +--:(hmac-sha-512) 388 | | +--ro hmac-sha-512? empty 389 | +--:(clear-text) {clear-text}? 390 | | +--ro clear-text? empty 391 | +--:(replay-protection-only) {replay-protection-only}? 392 | +--ro replay-protection-only? empty 393 +--rw aes-key-wrap {aes-key-wrap}? 394 | +--rw enable? boolean 395 +--ro aes-key-wrap-state {aes-key-wrap}? 396 +--ro enable? boolean 398 4. Key Chain YANG Model 400 file "ietf-key-chain@2016-08-17.yang" 401 module ietf-key-chain { 402 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 403 // replace with IANA namespace when assigned 404 prefix "key-chain"; 406 import ietf-yang-types { 407 prefix "yang"; 408 } 410 organization 411 "IETF RTG (Routing) Working Group"; 412 contact 413 "Acee Lindem - acee@cisco.com"; 415 description 416 "This YANG module defines the generic configuration 417 data for key-chain. It is intended that the module 418 will be extended by vendors to define vendor-specific 419 key-chain configuration parameters. 421 Copyright (c) 2015 IETF Trust and the persons identified as 422 authors of the code. All rights reserved. 424 Redistribution and use in source and binary forms, with or 425 without modification, is permitted pursuant to, and subject 426 to the license terms contained in, the Simplified BSD License 427 set forth in Section 4.c of the IETF Trust's Legal Provisions 428 Relating to IETF Documents 429 (http://trustee.ietf.org/license-info). 430 This version of this YANG module is part of RFC XXXX; see 431 the RFC itself for full legal notices."; 433 revision 2016-08-17 { 434 description 435 "Add description and last-modified timestamp leaves."; 436 reference 437 "RFC XXXX: A YANG Data Model for key-chain"; 438 } 439 revision 2016-07-01 { 440 description 441 "Rename module back to ietf-key-chain. 442 Added replay-protection-only feature and algorithm."; 443 reference 444 "RFC XXXX: A YANG Data Model for key-chain"; 445 } 446 revision 2016-03-15 { 447 description 448 "Rename module from ietf-key-chain to 449 ietf-routing-key-chain."; 450 reference 451 "RFC XXXX: A YANG Data Model for Routing key-chain"; 452 } 453 revision 2016-02-16 { 454 description 455 "Updated version. Added clear-text algorithm as a 456 feature."; 457 reference 458 "RFC XXXX: A YANG Data Model for key-chain"; 459 } 460 revision 2015-10-15 { 461 description 462 "Updated version, organization, and copyright. 463 Added aes-cmac-prf-128 and aes-key-wrap features."; 464 reference 465 "RFC XXXX: A YANG Data Model for key-chain"; 466 } 467 revision 2015-06-29 { 468 description 469 "Updated version. Added Operation State following 470 draft-openconfig-netmod-opstate-00."; 471 reference 472 "RFC XXXX: A YANG Data Model for key-chain"; 473 } 474 revision 2015-02-24 { 475 description 476 "Initial revision."; 477 reference 478 "RFC XXXX: A YANG Data Model for key-chain"; 479 } 481 typedef key-chain-ref { 482 type leafref { 483 path "/key-chain:key-chains/key-chain:key-chain-list/" 484 + "key-chain:name"; 485 } 486 description 487 "This type is used by data models that need to reference 488 configured key-chains."; 489 } 491 /* feature list */ 492 feature hex-key-string { 493 description 494 "Support hexadecimal key string."; 495 } 497 feature accept-tolerance { 498 description 499 "To specify the tolerance or acceptance limit."; 500 } 502 feature independent-send-accept-lifetime { 503 description 504 "Support for independent send and accept key lifetimes."; 505 } 507 feature crypto-hmac-sha-1-12 { 508 description 509 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 510 } 512 feature clear-text { 513 description 514 "Support for clear-text algorithm. Usage is NOT RECOMMENDED."; 515 } 517 feature aes-cmac-prf-128 { 518 description 519 "Support for AES Cipher based Message Authentication Code 520 Pseudo Random Function."; 521 } 523 feature aes-key-wrap { 524 description 525 "Support for Advanced Encryption Standard (AES) Key Wrap."; 526 } 528 feature replay-protection-only { 529 description 530 "Provide replay-protection without any authentication 531 as required by protocols such as Bidirectional 532 Forwarding Detection (BFD)."; 533 } 535 /* groupings */ 536 grouping lifetime { 537 description 538 "Key lifetime specification."; 539 choice lifetime { 540 default always; 541 description 542 "Options for specifying key accept or send lifetimes"; 543 case always { 544 leaf always { 545 type empty; 546 description 547 "Indicates key lifetime is always valid."; 548 } 549 } 550 case start-end-time { 551 leaf start-date-time { 552 type yang:date-and-time; 553 description "Start time."; 554 } 555 choice end-time { 556 default infinite; 557 description 558 "End-time setting."; 559 case infinite { 560 leaf no-end-time { 561 type empty; 562 description 563 "Indicates key lifetime end-time in infinite."; 564 } 565 } 566 case duration { 567 leaf duration { 568 type uint32 { 569 range "1..2147483646"; 570 } 571 units seconds; 572 description "Key lifetime duration, in seconds"; 573 } 574 } 575 case end-date-time { 576 leaf end-date-time { 577 type yang:date-and-time; 578 description "End time."; 579 } 580 } 581 } 582 } 583 } 584 } 586 grouping crypto-algorithm-types { 587 description "Cryptographic algorithm types."; 588 choice algorithm { 589 description 590 "Options for cryptographic algorithm specification."; 591 case hmac-sha-1-12 { 592 if-feature crypto-hmac-sha-1-12; 593 leaf hmac-sha1-12 { 594 type empty; 595 description "The HMAC-SHA1-12 algorithm."; 596 } 597 } 598 case aes-cmac-prf-128 { 599 if-feature aes-cmac-prf-128; 600 leaf aes-cmac-prf-128 { 601 type empty; 602 description "The AES-CMAC-PRF-128 algorithm - required 603 by RFC 5926 for TCP-AO key derivation 604 functions."; 605 } 606 } 607 case md5 { 608 leaf md5 { 609 type empty; 610 description "The MD5 algorithm."; 611 } 612 } 613 case sha-1 { 614 leaf sha-1 { 615 type empty; 616 description "The SHA-1 algorithm."; 617 } 618 } 619 case hmac-sha-1 { 620 leaf hmac-sha-1 { 621 type empty; 622 description "HMAC-SHA-1 authentication algorithm."; 623 } 624 } 625 case hmac-sha-256 { 626 leaf hmac-sha-256 { 627 type empty; 628 description "HMAC-SHA-256 authentication algorithm."; 629 } 630 } 631 case hmac-sha-384 { 632 leaf hmac-sha-384 { 633 type empty; 634 description "HMAC-SHA-384 authentication algorithm."; 635 } 636 } 637 case hmac-sha-512 { 638 leaf hmac-sha-512 { 639 type empty; 640 description "HMAC-SHA-512 authentication algorithm."; 641 } 642 } 643 case clear-text { 644 if-feature clear-text; 645 leaf clear-text { 646 type empty; 647 description "Clear text."; 648 } 649 } 650 case replay-protection-only { 651 if-feature replay-protection-only; 652 leaf replay-protection-only { 653 type empty; 654 description 655 "Provide replay-protection without any authentication 656 as required by protocols such as Bidirectional 657 Forwarding Detection (BFD)."; 658 } 659 } 660 } 661 } 663 grouping key-chain { 664 description 665 "key-chain specification grouping."; 666 leaf name { 667 type string; 668 description "Name of the key-chain."; 669 } 671 leaf name-state { 672 type string; 673 config false; 674 description "Configured name of the key-chain."; 675 } 677 leaf description { 678 type string; 679 description "A description of the key-chain"; 680 } 682 container accept-tolerance { 683 if-feature accept-tolerance; 684 description 685 "Tolerance for key lifetime acceptance (seconds)."; 686 leaf duration { 687 type uint32; 688 units seconds; 689 default "0"; 690 description 691 "Tolerance range, in seconds."; 692 } 693 } 695 container accept-tolerance-state { 696 config false; 697 description 698 "Configured tolerance for key lifetime 699 acceptance (seconds)."; 700 leaf duration { 701 type uint32; 702 description 703 "Configured tolerance range, in seconds."; 704 } 705 } 707 leaf last-modified-timestamp { 708 type yang:date-and-time; 709 config false; 710 description "Timestamp of the most recent update 711 to the key-chain"; 712 } 714 list key-chain-entry { 715 key "key-id"; 716 description "One key."; 717 leaf key-id { 718 type uint64; 719 description "Key ID."; 720 } 721 leaf key-id-state { 722 type uint64; 723 config false; 724 description "Configured Key ID."; 725 } 726 container key-string { 727 description "The key string."; 728 choice key-string-style { 729 description 730 "Key string styles"; 731 case keystring { 732 leaf keystring { 733 type string; 734 description "Key string in ASCII format."; 735 } 736 } 737 case hexadecimal { 738 if-feature hex-key-string; 739 leaf hexadecimal-string { 740 type yang:hex-string; 741 description 742 "Key in hexadecimal string format."; 743 } 744 } 745 } 746 } 747 container lifetime { 748 description "Specify a key's lifetime."; 749 choice lifetime { 750 description 751 "Options for specification of send and accept 752 lifetimes."; 753 case send-and-accept-lifetime { 754 description 755 "Send and accept key have the same lifetime."; 756 container send-accept-lifetime { 757 uses lifetime; 758 description 759 "Single lifetime specification for both send and 760 accept lifetimes."; 761 } 762 } 763 case independent-send-accept-lifetime { 764 if-feature independent-send-accept-lifetime; 765 description 766 "Independent send and accept key lifetimes."; 767 container send-lifetime { 768 uses lifetime; 769 description 770 "Separate lifetime specification for send 771 lifetime."; 772 } 773 container accept-lifetime { 774 uses lifetime; 775 description 776 "Separate lifetime specification for accept 777 lifetime."; 778 } 779 } 780 } 781 } 782 container lifetime-state { 783 config false; 784 description "Configured key's lifetime."; 785 container send-lifetime { 786 uses lifetime; 787 description 788 "Configured send-lifetime."; 789 } 790 leaf send-valid { 791 type boolean; 792 description 793 "Status of send-lifetime."; 794 } 795 container accept-lifetime { 796 uses lifetime; 797 description 798 "Configured accept-lifetime."; 799 } 800 leaf accept-valid { 801 type boolean; 802 description 803 "Status of accept-lifetime."; 804 } 805 } 806 container crypto-algorithm { 807 uses crypto-algorithm-types; 808 description "Cryptographic algorithm associated with key."; 809 } 810 container crypto-algorithm-state { 811 config false; 812 uses crypto-algorithm-types; 813 description "Configured cryptographic algorithm."; 814 } 815 } 816 } 817 container key-chains { 818 list key-chain-list { 819 key "name"; 820 description 821 "List of key-chains."; 822 uses key-chain; 823 } 824 container aes-key-wrap { 825 if-feature aes-key-wrap; 826 leaf enable { 827 type boolean; 828 default false; 829 description 830 "Enable AES Key Wrap encryption."; 831 } 832 description 833 "AES Key Wrap password encryption."; 834 } 835 container aes-key-wrap-state { 836 if-feature aes-key-wrap; 837 config false; 838 leaf enable { 839 type boolean; 840 description "AES Key Wrap state."; 841 } 842 description "Status of AES Key Wrap."; 843 } 844 description "All configured key-chains for the device."; 845 } 846 } 847 849 5. Security Considerations 851 This document enables the automated distribution of industry standard 852 key chains using the NETCONF [NETCONF] protocol. As such, the 853 security considerations for the NETCONF protocol are applicable. 854 Given that the key chains themselves are sensitive data, it is 855 RECOMMENDED that the NETCONF communication channel be encrypted. One 856 way to do accomplish this would be to invoke and run NETCONF over SSH 857 as described in [NETCONF-SSH]. 859 When configured, the key-strings can be encrypted using the AES Key 860 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 861 not included in the YANG model and must be set or derived independent 862 of key-chain configuration. 864 The key strings are not included in the operational state. This is a 865 practice carried over from SNMP MIB modules and is an area for 866 further discussion. 868 The clear-text algorithm is included as a YANG feature. Usage is NOT 869 RECOMMENDED except in cases where the application and device have no 870 other alternative (e.g., a legacy network device that must 871 authenticate packets at intervals of 10 milliseconds or less for many 872 peers using Bidirectional Forwarding Detection [BFD]). Keys used 873 with the clear-text algorithm are considered insecure and SHOULD NOT 874 be reused with more secure algorithms. 876 6. IANA Considerations 878 This document registers a URI in the IETF XML registry 879 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 880 following registration is requested to be made: 882 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 884 Registrant Contact: The IESG. 886 XML: N/A, the requested URI is an XML namespace. 888 This document registers a YANG module in the YANG Module Names 889 registry [YANG]. 891 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 892 key-chain prefix: ietf-key-chain reference: RFC XXXX 894 7. References 896 7.1. Normative References 898 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 899 Bierman, "Network Configuration Protocol (NETCONF)", RFC 900 6241, June 2011. 902 [NETCONF-SSH] 903 Wasserman, M., "Using NETCONF Protocol over Secure Shell 904 (SSH)", RFC 6242, June 2011. 906 [RFC-KEYWORDS] 907 Bradner, S., "Key words for use in RFC's to Indicate 908 Requirement Levels", BCP 14, RFC 2119, March 1997. 910 [XML-REGISTRY] 911 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 912 January 2004. 914 [YANG] Bjorklund, M., "YANG - A Data Modeling Language for the 915 Network Configuration Protocol (NETCONF)", RFC 6020, 916 October 2010. 918 7.2. Informative References 920 [AES-KEY-WRAP] 921 Housley, R. and M. Dworkin, "Advanced Encryption Standard 922 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 923 2009. 925 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 926 (BFD)", RFC 5880, June 2010. 928 [CRYPTO-KEYTABLE] 929 Housley, R., Polk, T., Hartman, S., and D. Zhang, 930 "Table of Cryptographic Keys", RFC 7210, April 2014. 932 [IAB-REPORT] 933 Andersson, L., Davies, E., and L. Zhang, "Report from the 934 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 935 4948, August 2007. 937 [NETCONF-SERVER-CONF] 938 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 939 RESTCONF Server Configuration Models", draft-ietf-netconf- 940 server-model-08.txt (work in progress), October 2015. 942 [NTP-PROTO] 943 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 944 Time Protocol Version 4: Protocol and Algorithms 945 Specification", RFC 5905, June 2010. 947 [OSPFV3-AUTH] 948 Bhatia, M., Manral, V., and A. Lindem, "Supporting 949 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 951 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 952 Authentication Option", RFC 5925, June 2010. 954 [TCP-AO-ALGORITHMS] 955 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 956 for the TCP Authentication Option (TCP-AO)", RFC 5926, 957 June 2010. 959 [YANG-CRYPTO-KEYTABLE] 960 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 961 chen-rtg-key-table-yang-02.txt (work in progress), 962 November 2015. 964 Appendix A. Acknowledgments 966 The RFC text was produced using Marshall Rose's xml2rfc tool. 968 Thanks to Brian Weis for fruitful discussions on security 969 requirements. 971 Thanks to Ines Robles for Routing Directorate QA review comments. 973 Authors' Addresses 975 Acee Lindem (editor) 976 Cisco Systems 977 301 Midenhall Way 978 Cary, NC 27513 979 USA 981 Email: acee@cisco.com 983 Yingzhen Qu 984 Cisco Systems 985 170 West Tasman Drive 986 San Jose, CA 95134 987 USA 989 Email: yiqu@cisco.com 991 Derek Yeung 992 Arrcus, Inc 994 Email: derek@arrcus.com 996 Ing-Wher Chen 997 Ericsson 999 Email: ichen@kuatrotech.com 1000 Jeffrey Zhang 1001 Juniper Networks 1002 10 Technology Park Drive 1003 Westford, MA 01886 1004 USA 1006 Email: zzhang@juniper.net 1008 Yi Yang 1009 Cisco Systems 1010 7025 Kit Creek Road 1011 Research Triangle Park, NC 27709 1012 USA 1014 Email: yiya@cisco.com