idnits 2.17.00 (12 Aug 2021) /tmp/idnits21356/draft-ietf-rtgwg-yang-key-chain-08.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 (August 30, 2016) is 2090 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 D. Yeung 5 Expires: March 3, 2017 Cisco Systems 6 I. Chen 7 Ericsson 8 J. Zhang 9 Juniper Networks 10 Y. Yang 11 Cisco Systems 12 August 30, 2016 14 Routing Key Chain YANG Data Model 15 draft-ietf-rtgwg-yang-key-chain-08.txt 17 Abstract 19 This document describes the key chain YANG data model. A key chain 20 is a list of elements each containing a key, send lifetime, accept 21 lifetime, and algorithm (authentication or encryption). By properly 22 overlapping the send and accept lifetimes of multiple key chain 23 elements, keys and algorithms may be gracefully updated. By 24 representing them in a YANG data model, key distribution can be 25 automated. Key chains are commonly used for routing protocol 26 authentication and other applications. In some applications, the 27 protocols do not use the key chain element key directly, but rather a 28 key derivation function is used to derive a short-lived key from the 29 key chain element key (e.g., the Master Keys used in the TCP 30 Authentication Option. 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at http://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on March 3, 2017. 49 Copyright Notice 51 Copyright (c) 2016 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents 56 (http://trustee.ietf.org/license-info) in effect on the date of 57 publication of this document. Please review these documents 58 carefully, as they describe your rights and restrictions with respect 59 to this document. Code Components extracted from this document must 60 include Simplified BSD License text as described in Section 4.e of 61 the Trust Legal Provisions and are provided without warranty as 62 described in the Simplified BSD License. 64 Table of Contents 66 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 67 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 68 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 69 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 70 2.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 71 2.2. Graceful Key Rollover using Key Chains . . . . . . . . . 4 72 3. Design of the Key Chain Model . . . . . . . . . . . . . . . . 5 73 3.1. Key Chain Operational State . . . . . . . . . . . . . . . 5 74 3.2. Key Chain Model Features . . . . . . . . . . . . . . . . 6 75 3.3. Key Chain Model Tree . . . . . . . . . . . . . . . . . . 6 76 4. Key Chain YANG Model . . . . . . . . . . . . . . . . . . . . 9 77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 79 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 81 7.2. Informative References . . . . . . . . . . . . . . . . . 20 82 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 21 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 85 1. Introduction 87 This document describes the key chain YANG data model. A key chain 88 is a list of elements each containing a key, send lifetime, accept 89 lifetime, and algorithm (authentication or encryption). By properly 90 overlapping the send and accept lifetimes of multiple key chain 91 elements, keys and algorithms may be gracefully updated. By 92 representing them in a YANG data model, key distribution can be 93 automated. Key chains are commonly used for routing protocol 94 authentication and other applications. In some applications, the 95 protocols do not use the key chain element key directly, but rather a 96 key derivation function is used to derive a short-lived key from the 97 key chain element key (e.g., the Master Keys used in [TCP-AO]). 99 1.1. Requirements Notation 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in [RFC-KEYWORDS]. 105 1.2. Tree Diagrams 107 A simplified graphical representation of the complete data tree is 108 presented in Section 3.3. The following tree notation is used. 110 o Brackets "[" and "]" enclose list keys. 112 o Curly braces "{" and "}" contain names of optional features that 113 make the corresponding node conditional. 115 o Abbreviations before data node names: "rw" means configuration 116 (read-write), "ro" state data (read-only), "-x" RPC operations, 117 and "-n" notifications. 119 o Symbols after data node names: "?" means an optional node, "!" a 120 container with presence, and "*" denotes a "list" or "leaf-list". 122 o Parentheses enclose choice and case nodes, and case nodes are also 123 marked with a colon (":"). 125 o Ellipsis ("...") stands for contents of subtrees that are not 126 shown. 128 2. Problem Statement 130 This document describes a YANG [YANG] data model for key chains. Key 131 chains have been implemented and deployed by a large percentage of 132 network equipment vendors. Providing a standard YANG model will 133 facilitate automated key distribution and non-disruptive key 134 rollover. This will aid in tightening the security of the core 135 routing infrastructure as recommended in [IAB-REPORT]. 137 A key chain is a list containing one or more elements containing a 138 Key ID, key, send/accept lifetimes, and the associated authentication 139 or encryption algorithm. A key chain can be used by any service or 140 application requiring authentication or encryption. In essence, the 141 key-chain is a reusable key policy that can be referenced where ever 142 it is required. The key-chain construct has been implemented by most 143 networking vendors and deployed in many networks. 145 The module name was change from ietf-key-chain to ietf-routing-key- 146 chain to avoid disambiguate it from the ietf-system-keychain module 147 defined in [NETCONF-SERVER-CONF]. However, due to popular demand, 148 the module name has been restored to simply ietf-key-chain. 150 A conceptual representation of a crypto key table is described in 151 [CRYPTO-KEYTABLE]. The crypto key table also includes keys as well 152 as their corresponding lifetimes and algorithms. Additionally, the 153 key table includes key selection criteria and envisions a deployment 154 model where the details of the applications or services requiring 155 authentication or encryption permeate into the key database. The 156 YANG key-chain model described herein doesn't include key selection 157 criteria or support this deployment model. At the same time, it does 158 not preclude it. The draft [YANG-CRYPTO-KEYTABLE] describes 159 augmentations to the key chain YANG model in support of key selection 160 criteria. 162 2.1. Applicability 164 Other YANG modules may reference ietf-key-chain YANG module key-chain 165 names for authentication and encryption applications. A YANG type 166 has been provided to facilate reference to the key-chain name without 167 having to specify the complete YANG XML Path Language (XPath) 168 selector. 170 2.2. Graceful Key Rollover using Key Chains 172 Key chains may be used to gracefully update the key and/or algorithm 173 used by an application for authentication or encryption. This MAY be 174 accomplished by accepting all the keys that have a valid accept 175 lifetime and sending the key with the most recent send lifetime. One 176 scenario for facilitating key rollover is to: 178 1. Distribute a key chain with a new key to all the routers or other 179 network devices in the domain of that key chain. The new key's 180 accept lifetime should be such that it is accepted during the key 181 rollover period. The send lifetime should be a time in the 182 future when it can be assured that all the routers in the domain 183 of that key are upgraded. This will have no immediate impact on 184 the keys used for transmission. 186 2. Assure that all the network devices have been updated with the 187 updated key chain and that their system times are roughly 188 synchronized. The system times of devices within an 189 administrative domain are commonly synchronized (e.g., using 190 Network Time Protocol (NTP) [NTP-PROTO]). This also may be 191 automated. 193 3. When the send lifetime of the new key becomes valid, the network 194 devices within the domain of key chain will start sending the new 195 key. 197 4. At some point in the future, a new key chain with the old key 198 removed may be distributed to the network devices within the 199 domain of the key chain. However, this may be deferred until the 200 next key rollover. If this is done, the key chain will always 201 include two keys; either the current and future key (during key 202 rollovers) or the current and previous keys (between key 203 rollovers). 205 3. Design of the Key Chain Model 207 The ietf-key-chain module contains a list of one or more keys indexed 208 by a Key ID. For some applications (e.g., OSPFv3 [OSPFV3-AUTH]), the 209 Key-Id is used to identify the key chain entry to be used. In 210 addition to the Key-ID, each key chain entry includes a key-string 211 and a cryptographic algorithm. Optionally, the key chain entries 212 include send/accept lifetimes. If the send/accept lifetime is 213 unspecified, the key is always considered valid. 215 Note that asymmetric keys, i.e., a different key value used for 216 transmission versus acceptance, may be supported with multiple key 217 chain elements where the accept-lifetime or send-lifetime is not 218 valid (e.g., has an end-time equal to the start-time). 220 Due to the differences in key chain implementations across various 221 vendors, some of the data elements are optional. Additionally, the 222 key-chain is made a grouping so that an implementation could support 223 scoping other than at the global level. Finally, the crypto- 224 algorithm-types grouping is provided for reuse when configuring 225 legacy authentication and encryption not using key-chains. 227 A key-chain is identified by a unique name within the scope of the 228 network device. The "key-chain-ref" typedef SHOULD be used by other 229 YANG modules when they need to reference a configured key-chain. 231 3.1. Key Chain Operational State 233 The key chain operational state is maintained in the key-chain 234 entries along with the configuration state. The key string itself is 235 omitted from the operational state to minimize visibility similar to 236 what was done with keys in SNMP MIBs. The timestamp of the last key- 237 chain modification is also maintained in the operational state. 238 Additionally, the operational state includes an indication of whether 239 or not a key chain entry is valid for sending or acceptance. 241 3.2. Key Chain Model Features 243 Features are used to handle differences between vendor 244 implementations. For example, not all vendors support configuration 245 an acceptance tolerance or configuration of key strings in 246 hexadecimal. They are also used to support of security requirements 247 (e.g., TCP-AO Algorithms [TCP-AO-ALGORITHMS]) not implemented by 248 vendors or only a single vendor. 250 3.3. Key Chain Model Tree 252 module: ietf-key-chain 253 +--rw key-chains 254 +--rw key-chain-list* [name] 255 | +--rw name string 256 | +--ro name-state? string 257 | +--rw description? string 258 | +--rw accept-tolerance {accept-tolerance}? 259 | | +--rw duration? uint32 260 | +--ro accept-tolerance-state 261 | | +--ro duration? uint32 262 | +--ro last-modified-timestamp? yang:date-and-time 263 | +--rw key-chain-entry* [key-id] 264 | +--rw key-id uint64 265 | +--ro key-id-state? uint64 266 | +--rw key-string 267 | | +--rw (key-string-style)? 268 | | +--:(keystring) 269 | | | +--rw keystring? string 270 | | +--:(hexadecimal) {hex-key-string}? 271 | | +--rw hexadecimal-string? yang:hex-string 272 | +--rw lifetime 273 | | +--rw (lifetime)? 274 | | +--:(send-and-accept-lifetime) 275 | | | +--rw send-accept-lifetime 276 | | | +--rw (lifetime)? 277 | | | +--:(always) 278 | | | | +--rw always? empty 279 | | | +--:(start-end-time) 280 | | | +--rw start-date-time? yang:date-and-time 281 | | | +--rw (end-time)? 282 | | | +--:(infinite) 283 | | | | +--rw no-end-time? empty 284 | | | +--:(duration) 285 | | | | +--rw duration? uint32 286 | | | +--:(end-date-time) 287 | | | +--rw end-date-time? 288 | | | yang:date-and-time 289 | | +--:(independent-send-accept-lifetime) 290 | | {independent-send-accept-lifetime}? 291 | | +--rw send-lifetime 292 | | | +--rw (lifetime)? 293 | | | +--:(always) 294 | | | | +--rw always? empty 295 | | | +--:(start-end-time) 296 | | | +--rw start-date-time? yang:date-and-time 297 | | | +--rw (end-time)? 298 | | | +--:(infinite) 299 | | | | +--rw no-end-time? empty 300 | | | +--:(duration) 301 | | | | +--rw duration? uint32 302 | | | +--:(end-date-time) 303 | | | +--rw end-date-time? 304 | | | yang:date-and-time 305 | | +--rw accept-lifetime 306 | | +--rw (lifetime)? 307 | | +--:(always) 308 | | | +--rw always? empty 309 | | +--:(start-end-time) 310 | | +--rw start-date-time? yang:date-and-time 311 | | +--rw (end-time)? 312 | | +--:(infinite) 313 | | | +--rw no-end-time? empty 314 | | +--:(duration) 315 | | | +--rw duration? uint32 316 | | +--:(end-date-time) 317 | | +--rw end-date-time? 318 | | yang:date-and-time 319 | +--ro lifetime-state 320 | | +--ro send-lifetime 321 | | | +--ro (lifetime)? 322 | | | +--:(always) 323 | | | | +--ro always? empty 324 | | | +--:(start-end-time) 325 | | | +--ro start-date-time? yang:date-and-time 326 | | | +--ro (end-time)? 327 | | | +--:(infinite) 328 | | | | +--ro no-end-time? empty 329 | | | +--:(duration) 330 | | | | +--ro duration? uint32 331 | | | +--:(end-date-time) 332 | | | +--ro end-date-time? yang:date-and-time 333 | | +--ro send-valid? boolean 334 | | +--ro accept-lifetime 335 | | | +--ro (lifetime)? 336 | | | +--:(always) 337 | | | | +--ro always? empty 338 | | | +--:(start-end-time) 339 | | | +--ro start-date-time? yang:date-and-time 340 | | | +--ro (end-time)? 341 | | | +--:(infinite) 342 | | | | +--ro no-end-time? empty 343 | | | +--:(duration) 344 | | | | +--ro duration? uint32 345 | | | +--:(end-date-time) 346 | | | +--ro end-date-time? yang:date-and-time 347 | | +--ro accept-valid? boolean 348 | +--rw crypto-algorithm 349 | | +--rw (algorithm)? 350 | | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 351 | | | +--rw hmac-sha1-12? empty 352 | | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 353 | | | +--rw aes-cmac-prf-128? empty 354 | | +--:(md5) 355 | | | +--rw md5? empty 356 | | +--:(sha-1) 357 | | | +--rw sha-1? empty 358 | | +--:(hmac-sha-1) 359 | | | +--rw hmac-sha-1? empty 360 | | +--:(hmac-sha-256) 361 | | | +--rw hmac-sha-256? empty 362 | | +--:(hmac-sha-384) 363 | | | +--rw hmac-sha-384? empty 364 | | +--:(hmac-sha-512) 365 | | | +--rw hmac-sha-512? empty 366 | | +--:(clear-text) {clear-text}? 367 | | | +--rw clear-text? empty 368 | | +--:(replay-protection-only) {replay-protection-only}? 369 | | +--rw replay-protection-only? empty 370 | +--ro crypto-algorithm-state 371 | +--ro (algorithm)? 372 | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 373 | | +--ro hmac-sha1-12? empty 374 | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 375 | | +--ro aes-cmac-prf-128? empty 376 | +--:(md5) 377 | | +--ro md5? empty 378 | +--:(sha-1) 379 | | +--ro sha-1? empty 380 | +--:(hmac-sha-1) 381 | | +--ro hmac-sha-1? empty 382 | +--:(hmac-sha-256) 383 | | +--ro hmac-sha-256? empty 384 | +--:(hmac-sha-384) 385 | | +--ro hmac-sha-384? empty 386 | +--:(hmac-sha-512) 387 | | +--ro hmac-sha-512? empty 388 | +--:(clear-text) {clear-text}? 389 | | +--ro clear-text? empty 390 | +--:(replay-protection-only) {replay-protection-only}? 391 | +--ro replay-protection-only? empty 392 +--rw aes-key-wrap {aes-key-wrap}? 393 | +--rw enable? boolean 394 +--ro aes-key-wrap-state {aes-key-wrap}? 395 +--ro enable? boolean 397 4. Key Chain YANG Model 399 file "ietf-key-chain@2016-08-17.yang" 400 module ietf-key-chain { 401 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 402 // replace with IANA namespace when assigned 403 prefix "key-chain"; 405 import ietf-yang-types { 406 prefix "yang"; 407 } 409 organization 410 "IETF RTG (Routing) Working Group"; 411 contact 412 "Acee Lindem - acee@cisco.com"; 414 description 415 "This YANG module defines the generic configuration 416 data for key-chain. It is intended that the module 417 will be extended by vendors to define vendor-specific 418 key-chain configuration parameters. 420 Copyright (c) 2015 IETF Trust and the persons identified as 421 authors of the code. All rights reserved. 423 Redistribution and use in source and binary forms, with or 424 without modification, is permitted pursuant to, and subject 425 to the license terms contained in, the Simplified BSD License 426 set forth in Section 4.c of the IETF Trust's Legal Provisions 427 Relating to IETF Documents 428 (http://trustee.ietf.org/license-info). 429 This version of this YANG module is part of RFC XXXX; see 430 the RFC itself for full legal notices."; 432 revision 2016-08-17 { 433 description 434 "Add description and last-modified timestamp leaves."; 435 reference 436 "RFC XXXX: A YANG Data Model for key-chain"; 437 } 438 revision 2016-07-01 { 439 description 440 "Rename module back to ietf-key-chain. 441 Added replay-protection-only feature and algorithm."; 442 reference 443 "RFC XXXX: A YANG Data Model for key-chain"; 444 } 445 revision 2016-03-15 { 446 description 447 "Rename module from ietf-key-chain to 448 ietf-routing-key-chain."; 449 reference 450 "RFC XXXX: A YANG Data Model for Routing key-chain"; 451 } 452 revision 2016-02-16 { 453 description 454 "Updated version. Added clear-text algorithm as a 455 feature."; 456 reference 457 "RFC XXXX: A YANG Data Model for key-chain"; 458 } 459 revision 2015-10-15 { 460 description 461 "Updated version, organization, and copyright. 462 Added aes-cmac-prf-128 and aes-key-wrap features."; 463 reference 464 "RFC XXXX: A YANG Data Model for key-chain"; 465 } 466 revision 2015-06-29 { 467 description 468 "Updated version. Added Operation State following 469 draft-openconfig-netmod-opstate-00."; 470 reference 471 "RFC XXXX: A YANG Data Model for key-chain"; 472 } 473 revision 2015-02-24 { 474 description 475 "Initial revision."; 476 reference 477 "RFC XXXX: A YANG Data Model for key-chain"; 478 } 480 typedef key-chain-ref { 481 type leafref { 482 path "/key-chain:key-chains/key-chain:key-chain-list/" 483 + "key-chain:name"; 484 } 485 description 486 "This type is used by data models that need to reference 487 configured key-chains."; 488 } 490 /* feature list */ 491 feature hex-key-string { 492 description 493 "Support hexadecimal key string."; 494 } 496 feature accept-tolerance { 497 description 498 "To specify the tolerance or acceptance limit."; 499 } 501 feature independent-send-accept-lifetime { 502 description 503 "Support for independent send and accept key lifetimes."; 504 } 506 feature crypto-hmac-sha-1-12 { 507 description 508 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 509 } 511 feature clear-text { 512 description 513 "Support for clear-text algorithm. Usage is NOT RECOMMENDED."; 514 } 516 feature aes-cmac-prf-128 { 517 description 518 "Support for AES Cipher based Message Authentication Code 519 Pseudo Random Function."; 520 } 522 feature aes-key-wrap { 523 description 524 "Support for Advanced Encryption Standard (AES) Key Wrap."; 525 } 527 feature replay-protection-only { 528 description 529 "Provide replay-protection without any authentication 530 as required by protocols such as Bidirectional 531 Forwarding Detection (BFD)."; 532 } 534 /* groupings */ 535 grouping lifetime { 536 description 537 "Key lifetime specification."; 538 choice lifetime { 539 default always; 540 description 541 "Options for specifying key accept or send lifetimes"; 542 case always { 543 leaf always { 544 type empty; 545 description 546 "Indicates key lifetime is always valid."; 547 } 548 } 549 case start-end-time { 550 leaf start-date-time { 551 type yang:date-and-time; 552 description "Start time."; 553 } 554 choice end-time { 555 default infinite; 556 description 557 "End-time setting."; 558 case infinite { 559 leaf no-end-time { 560 type empty; 561 description 562 "Indicates key lifetime end-time in infinite."; 563 } 564 } 565 case duration { 566 leaf duration { 567 type uint32 { 568 range "1..2147483646"; 569 } 570 units seconds; 571 description "Key lifetime duration, in seconds"; 572 } 573 } 574 case end-date-time { 575 leaf end-date-time { 576 type yang:date-and-time; 577 description "End time."; 578 } 579 } 580 } 581 } 582 } 583 } 585 grouping crypto-algorithm-types { 586 description "Cryptographic algorithm types."; 587 choice algorithm { 588 description 589 "Options for cryptographic algorithm specification."; 590 case hmac-sha-1-12 { 591 if-feature crypto-hmac-sha-1-12; 592 leaf hmac-sha1-12 { 593 type empty; 594 description "The HMAC-SHA1-12 algorithm."; 595 } 596 } 597 case aes-cmac-prf-128 { 598 if-feature aes-cmac-prf-128; 599 leaf aes-cmac-prf-128 { 600 type empty; 601 description "The AES-CMAC-PRF-128 algorithm - required 602 by RFC 5926 for TCP-AO key derivation 603 functions."; 604 } 605 } 606 case md5 { 607 leaf md5 { 608 type empty; 609 description "The MD5 algorithm."; 610 } 611 } 612 case sha-1 { 613 leaf sha-1 { 614 type empty; 615 description "The SHA-1 algorithm."; 616 } 617 } 618 case hmac-sha-1 { 619 leaf hmac-sha-1 { 620 type empty; 621 description "HMAC-SHA-1 authentication algorithm."; 622 } 623 } 624 case hmac-sha-256 { 625 leaf hmac-sha-256 { 626 type empty; 627 description "HMAC-SHA-256 authentication algorithm."; 628 } 629 } 630 case hmac-sha-384 { 631 leaf hmac-sha-384 { 632 type empty; 633 description "HMAC-SHA-384 authentication algorithm."; 634 } 635 } 636 case hmac-sha-512 { 637 leaf hmac-sha-512 { 638 type empty; 639 description "HMAC-SHA-512 authentication algorithm."; 640 } 641 } 642 case clear-text { 643 if-feature clear-text; 644 leaf clear-text { 645 type empty; 646 description "Clear text."; 647 } 648 } 649 case replay-protection-only { 650 if-feature replay-protection-only; 651 leaf replay-protection-only { 652 type empty; 653 description 654 "Provide replay-protection without any authentication 655 as required by protocols such as Bidirectional 656 Forwarding Detection (BFD)."; 657 } 658 } 659 } 660 } 662 grouping key-chain { 663 description 664 "key-chain specification grouping."; 665 leaf name { 666 type string; 667 description "Name of the key-chain."; 668 } 670 leaf name-state { 671 type string; 672 config false; 673 description "Configured name of the key-chain."; 674 } 676 leaf description { 677 type string; 678 description "A description of the key-chain"; 679 } 681 container accept-tolerance { 682 if-feature accept-tolerance; 683 description 684 "Tolerance for key lifetime acceptance (seconds)."; 685 leaf duration { 686 type uint32; 687 units seconds; 688 default "0"; 689 description 690 "Tolerance range, in seconds."; 691 } 692 } 694 container accept-tolerance-state { 695 config false; 696 description 697 "Configured tolerance for key lifetime 698 acceptance (seconds)."; 699 leaf duration { 700 type uint32; 701 description 702 "Configured tolerance range, in seconds."; 703 } 704 } 706 leaf last-modified-timestamp { 707 type yang:date-and-time; 708 config false; 709 description "Timestamp of the most recent update 710 to the key-chain"; 711 } 713 list key-chain-entry { 714 key "key-id"; 715 description "One key."; 716 leaf key-id { 717 type uint64; 718 description "Key ID."; 719 } 720 leaf key-id-state { 721 type uint64; 722 config false; 723 description "Configured Key ID."; 724 } 725 container key-string { 726 description "The key string."; 727 choice key-string-style { 728 description 729 "Key string styles"; 730 case keystring { 731 leaf keystring { 732 type string; 733 description "Key string in ASCII format."; 734 } 735 } 736 case hexadecimal { 737 if-feature hex-key-string; 738 leaf hexadecimal-string { 739 type yang:hex-string; 740 description 741 "Key in hexadecimal string format."; 742 } 743 } 744 } 745 } 746 container lifetime { 747 description "Specify a key's lifetime."; 748 choice lifetime { 749 description 750 "Options for specification of send and accept 751 lifetimes."; 752 case send-and-accept-lifetime { 753 description 754 "Send and accept key have the same lifetime."; 755 container send-accept-lifetime { 756 uses lifetime; 757 description 758 "Single lifetime specification for both send and 759 accept lifetimes."; 760 } 761 } 762 case independent-send-accept-lifetime { 763 if-feature independent-send-accept-lifetime; 764 description 765 "Independent send and accept key lifetimes."; 766 container send-lifetime { 767 uses lifetime; 768 description 769 "Separate lifetime specification for send 770 lifetime."; 771 } 772 container accept-lifetime { 773 uses lifetime; 774 description 775 "Separate lifetime specification for accept 776 lifetime."; 777 } 778 } 779 } 780 } 781 container lifetime-state { 782 config false; 783 description "Configured key's lifetime."; 784 container send-lifetime { 785 uses lifetime; 786 description 787 "Configured send-lifetime."; 788 } 789 leaf send-valid { 790 type boolean; 791 description 792 "Status of send-lifetime."; 793 } 794 container accept-lifetime { 795 uses lifetime; 796 description 797 "Configured accept-lifetime."; 798 } 799 leaf accept-valid { 800 type boolean; 801 description 802 "Status of accept-lifetime."; 803 } 804 } 805 container crypto-algorithm { 806 uses crypto-algorithm-types; 807 description "Cryptographic algorithm associated with key."; 808 } 809 container crypto-algorithm-state { 810 config false; 811 uses crypto-algorithm-types; 812 description "Configured cryptographic algorithm."; 813 } 814 } 815 } 816 container key-chains { 817 list key-chain-list { 818 key "name"; 819 description 820 "List of key-chains."; 821 uses key-chain; 822 } 823 container aes-key-wrap { 824 if-feature aes-key-wrap; 825 leaf enable { 826 type boolean; 827 default false; 828 description 829 "Enable AES Key Wrap encryption."; 830 } 831 description 832 "AES Key Wrap password encryption."; 833 } 834 container aes-key-wrap-state { 835 if-feature aes-key-wrap; 836 config false; 837 leaf enable { 838 type boolean; 839 description "AES Key Wrap state."; 840 } 841 description "Status of AES Key Wrap."; 842 } 843 description "All configured key-chains for the device."; 844 } 845 } 846 848 5. Security Considerations 850 This document enables the automated distribution of industry standard 851 key chains using the NETCONF [NETCONF] protocol. As such, the 852 security considerations for the NETCONF protocol are applicable. 853 Given that the key chains themselves are sensitive data, it is 854 RECOMMENDED that the NETCONF communication channel be encrypted. One 855 way to do accomplish this would be to invoke and run NETCONF over SSH 856 as described in [NETCONF-SSH]. 858 When configured, the key-strings can be encrypted using the AES Key 859 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 860 not included in the YANG model and must be set or derived independent 861 of key-chain configuration. 863 The key strings are not included in the operational state. This is a 864 practice carried over from SNMP MIB modules and is an area for 865 further discussion. 867 The clear-text algorithm is included as a YANG feature. Usage is NOT 868 RECOMMENDED except in cases where the application and device have no 869 other alternative (e.g., a legacy network device that must 870 authenticate packets at intervals of 10 milliseconds or less for many 871 peers using Bidirectional Forwarding Detection [BFD]). Keys used 872 with the clear-text algorithm are considered insecure and SHOULD NOT 873 be reused with more secure algorithms. 875 6. IANA Considerations 877 This document registers a URI in the IETF XML registry 878 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 879 following registration is requested to be made: 881 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 883 Registrant Contact: The IESG. 885 XML: N/A, the requested URI is an XML namespace. 887 This document registers a YANG module in the YANG Module Names 888 registry [YANG]. 890 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 891 key-chain prefix: ietf-key-chain reference: RFC XXXX 893 7. References 895 7.1. Normative References 897 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 898 Bierman, "Network Configuration Protocol (NETCONF)", RFC 899 6241, June 2011. 901 [NETCONF-SSH] 902 Wasserman, M., "Using NETCONF Protocol over Secure Shell 903 (SSH)", RFC 6242, June 2011. 905 [RFC-KEYWORDS] 906 Bradner, S., "Key words for use in RFC's to Indicate 907 Requirement Levels", BCP 14, RFC 2119, March 1997. 909 [XML-REGISTRY] 910 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 911 January 2004. 913 [YANG] Bjorklund, M., "YANG - A Data Modeling Language for the 914 Network Configuration Protocol (NETCONF)", RFC 6020, 915 October 2010. 917 7.2. Informative References 919 [AES-KEY-WRAP] 920 Housley, R. and M. Dworkin, "Advanced Encryption Standard 921 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 922 2009. 924 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 925 (BFD)", RFC 5880, June 2010. 927 [CRYPTO-KEYTABLE] 928 Housley, R., Polk, T., Hartman, S., and D. Zhang, 929 "Table of Cryptographic Keys", RFC 7210, April 2014. 931 [IAB-REPORT] 932 Andersson, L., Davies, E., and L. Zhang, "Report from the 933 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 934 4948, August 2007. 936 [NETCONF-SERVER-CONF] 937 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 938 RESTCONF Server Configuration Models", draft-ietf-netconf- 939 server-model-08.txt (work in progress), October 2015. 941 [NTP-PROTO] 942 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 943 Time Protocol Version 4: Protocol and Algorithms 944 Specification", RFC 5905, June 2010. 946 [OSPFV3-AUTH] 947 Bhatia, M., Manral, V., and A. Lindem, "Supporting 948 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 950 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 951 Authentication Option", RFC 5925, June 2010. 953 [TCP-AO-ALGORITHMS] 954 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 955 for the TCP Authentication Option (TCP-AO)", RFC 5926, 956 June 2010. 958 [YANG-CRYPTO-KEYTABLE] 959 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 960 chen-rtg-key-table-yang-02.txt (work in progress), 961 November 2015. 963 Appendix A. Acknowledgments 965 The RFC text was produced using Marshall Rose's xml2rfc tool. 967 Thanks to Brian Weis for fruitful discussions on security 968 requirements. 970 Thanks to Ines Robles for Routing Directorate QA review comments. 972 Authors' Addresses 974 Acee Lindem (editor) 975 Cisco Systems 976 301 Midenhall Way 977 Cary, NC 27513 978 USA 980 Email: acee@cisco.com 982 Yingzhen Qu 983 Cisco Systems 984 170 West Tasman Drive 985 San Jose, CA 95134 986 USA 988 Email: yiqu@cisco.com 990 Derek Yeung 991 Cisco Systems 992 170 West Tasman Drive 993 San Jose, CA 95134 994 USA 996 Email: myeung@cisco.com 998 Ing-Wher Chen 999 Ericsson 1001 Email: ichen@kuatrotech.com 1002 Jeffrey Zhang 1003 Juniper Networks 1004 10 Technology Park Drive 1005 Westford, MA 01886 1006 USA 1008 Email: zzhang@juniper.net 1010 Yi Yang 1011 Cisco Systems 1012 7025 Kit Creek Road 1013 Research Triangle Park, NC 27709 1014 USA 1016 Email: yiya@cisco.com