idnits 2.17.1 draft-ietf-rtgwg-yang-key-chain-13.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 (January 19, 2017) is 2653 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) == 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: 1 error (**), 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 Cisco Systems 4 Intended status: Standards Track Y. Qu 5 Expires: July 23, 2017 Huawei 6 D. Yeung 7 Arrcus, Inc 8 I. Chen 9 Ericsson 10 J. Zhang 11 Juniper Networks 12 Y. Yang 13 SockRate 14 January 19, 2017 16 Routing Key Chain YANG Data Model 17 draft-ietf-rtgwg-yang-key-chain-13.txt 19 Abstract 21 This document describes the key chain YANG data model. A key chain 22 is a list of elements each containing a key, send lifetime, accept 23 lifetime, and algorithm (authentication or encryption). By properly 24 overlapping the send and accept lifetimes of multiple key chain 25 elements, keys and algorithms may be gracefully updated. By 26 representing them in a YANG data model, key distribution can be 27 automated. Key chains are commonly used for routing protocol 28 authentication and other applications. In some applications, the 29 protocols do not use the key chain element key directly, but rather a 30 key derivation function is used to derive a short-lived key from the 31 key chain element key (e.g., the Master Keys used in the TCP 32 Authentication Option. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on July 23, 2017. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 3 69 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 70 2. Problem Statement . . . . . . . . . . . . . . . . . . . . . . 3 71 2.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 4 72 2.2. Graceful Key Rollover using Key Chains . . . . . . . . . 4 73 3. Design of the Key Chain Model . . . . . . . . . . . . . . . . 5 74 3.1. Key Chain Operational State . . . . . . . . . . . . . . . 5 75 3.2. Key Chain Model Features . . . . . . . . . . . . . . . . 6 76 3.3. Key Chain Model Tree . . . . . . . . . . . . . . . . . . 6 77 4. Key Chain YANG Model . . . . . . . . . . . . . . . . . . . . 10 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 20 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 21 82 7.2. Informative References . . . . . . . . . . . . . . . . . 22 83 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 22 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 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 a separate tree. 235 The key string itself is omitted from the operational state to 236 minimize visibility similar to what was done with keys in SNMP MIBs. 237 The timestamp of the last key-chain modification is also maintained 238 in the operational state. Additionally, the operational state 239 includes an indication of whether or not a key chain entry is valid 240 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 +--rw key-chain 254 | +--rw key-chain-list* [name] 255 | | +--rw name string 256 | | +--rw description? string 257 | | +--rw accept-tolerance {accept-tolerance}? 258 | | | +--rw duration? uint32 259 | | +--rw key-chain-entries* [key-id] 260 | | +--rw key-id uint64 261 | | +--rw lifetime 262 | | | +--rw (lifetime)? 263 | | | +--:(send-and-accept-lifetime) 264 | | | | +--rw send-accept-lifetime 265 | | | | +--rw (lifetime)? 266 | | | | +--:(always) 267 | | | | | +--rw always? empty 268 | | | | +--:(start-end-time) 269 | | | | +--rw start-date-time? 270 | | | | | yang:date-and-time 271 | | | | +--rw (end-time)? 272 | | | | +--:(infinite) 273 | | | | | +--rw no-end-time? empty 274 | | | | +--:(duration) 275 | | | | | +--rw duration? uint32 276 | | | | +--:(end-date-time) 277 | | | | +--rw end-date-time? 278 | | | | yang:date-and-time 279 | | | +--:(independent-send-accept-lifetime) 280 | | | | {independent-send-accept-lifetime}? 281 | | | +--rw send-lifetime 282 | | | | +--rw (lifetime)? 283 | | | | +--:(always) 284 | | | | | +--rw always? empty 285 | | | | +--:(start-end-time) 286 | | | | +--rw start-date-time? 287 | | | | yang:date-and-time 288 | | | | +--rw (end-time)? 289 | | | | +--:(infinite) 290 | | | | | +--rw no-end-time? empty 291 | | | | +--:(duration) 292 | | | | | +--rw duration? uint32 293 | | | | +--:(end-date-time) 294 | | | | +--rw end-date-time? 295 | | | | yang:date-and-time 296 | | | +--rw accept-lifetime 297 | | | +--rw (lifetime)? 298 | | | +--:(always) 299 | | | | +--rw always? empty 300 | | | +--:(start-end-time) 301 | | | +--rw start-date-time? 302 | | | yang:date-and-time 303 | | | +--rw (end-time)? 304 | | | +--:(infinite) 305 | | | | +--rw no-end-time? empty 306 | | | +--:(duration) 307 | | | | +--rw duration? uint32 308 | | | +--:(end-date-time) 309 | | | +--rw end-date-time? 310 | | | yang:date-and-time 311 | | +--rw crypto-algorithm 312 | | | +--rw (algorithm)? 313 | | | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 314 | | | | +--rw hmac-sha1-12? empty 315 | | | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 316 | | | | +--rw aes-cmac-prf-128? empty 317 | | | +--:(md5) 318 | | | | +--rw md5? empty 319 | | | +--:(sha-1) 320 | | | | +--rw sha-1? empty 321 | | | +--:(hmac-sha-1) 322 | | | | +--rw hmac-sha-1? empty 323 | | | +--:(hmac-sha-256) 324 | | | | +--rw hmac-sha-256? empty 325 | | | +--:(hmac-sha-384) 326 | | | | +--rw hmac-sha-384? empty 327 | | | +--:(hmac-sha-512) 328 | | | | +--rw hmac-sha-512? empty 329 | | | +--:(clear-text) {clear-text}? 330 | | | | +--rw clear-text? empty 331 | | | +--:(replay-protection-only) 332 | | | {replay-protection-only}? 333 | | | +--rw replay-protection-only? empty 334 | | +--rw key-string 335 | | +--rw (key-string-style)? 336 | | +--:(keystring) 337 | | | +--rw keystring? string 338 | | +--:(hexadecimal) {hex-key-string}? 339 | | +--rw hexadecimal-string? yang:hex-string 340 | +--rw aes-key-wrap {aes-key-wrap}? 341 | +--rw enable? boolean 342 +--ro key-chain-state 343 +--ro key-chain-list* [name] 344 | +--ro name string 345 | +--ro description? string 346 | +--ro accept-tolerance {accept-tolerance}? 347 | | +--ro duration? uint32 348 | +--ro last-modified-timestamp? yang:date-and-time 349 | +--ro key-chain-entries* [key-id] 350 | +--ro key-id uint64 351 | +--ro lifetime 352 | | +--ro (lifetime)? 353 | | +--:(send-and-accept-lifetime) 354 | | | +--ro send-accept-lifetime 355 | | | +--ro (lifetime)? 356 | | | +--:(always) 357 | | | | +--ro always? empty 358 | | | +--:(start-end-time) 359 | | | +--ro start-date-time? 360 | | | yang:date-and-time 361 | | | +--ro (end-time)? 362 | | | +--:(infinite) 363 | | | | +--ro no-end-time? empty 364 | | | +--:(duration) 365 | | | | +--ro duration? uint32 366 | | | +--:(end-date-time) 367 | | | +--ro end-date-time? 368 | | | yang:date-and-time 369 | | +--:(independent-send-accept-lifetime) 370 | | | {independent-send-accept-lifetime}? 371 | | +--ro send-lifetime 372 | | | +--ro (lifetime)? 373 | | | +--:(always) 374 | | | | +--ro always? empty 375 | | | +--:(start-end-time) 376 | | | +--ro start-date-time? 377 | | | yang:date-and-time 378 | | | +--ro (end-time)? 379 | | | +--:(infinite) 380 | | | | +--ro no-end-time? empty 381 | | | +--:(duration) 382 | | | | +--ro duration? uint32 383 | | | +--:(end-date-time) 384 | | | +--ro end-date-time? 385 | | | yang:date-and-time 386 | | +--ro accept-lifetime 387 | | +--ro (lifetime)? 388 | | +--:(always) 389 | | | +--ro always? empty 390 | | +--:(start-end-time) 391 | | +--ro start-date-time? yang:date-and-time 392 | | +--ro (end-time)? 393 | | +--:(infinite) 394 | | | +--ro no-end-time? empty 395 | | +--:(duration) 396 | | | +--ro duration? uint32 397 | | +--:(end-date-time) 398 | | +--ro end-date-time? 399 | | yang:date-and-time 400 | +--ro crypto-algorithm 401 | | +--ro (algorithm)? 402 | | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 403 | | | +--ro hmac-sha1-12? empty 404 | | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 405 | | | +--ro aes-cmac-prf-128? empty 406 | | +--:(md5) 407 | | | +--ro md5? empty 408 | | +--:(sha-1) 409 | | | +--ro sha-1? empty 410 | | +--:(hmac-sha-1) 411 | | | +--ro hmac-sha-1? empty 412 | | +--:(hmac-sha-256) 413 | | | +--ro hmac-sha-256? empty 414 | | +--:(hmac-sha-384) 415 | | | +--ro hmac-sha-384? empty 416 | | +--:(hmac-sha-512) 417 | | | +--ro hmac-sha-512? empty 418 | | +--:(clear-text) {clear-text}? 419 | | | +--ro clear-text? empty 420 | | +--:(replay-protection-only) 421 | | | {replay-protection-only}? 422 | | +--ro replay-protection-only? empty 423 | +--ro key-string 424 | +--ro (key-string-style)? 425 | +--:(keystring) 426 | | +--ro keystring? string 427 | +--:(hexadecimal) {hex-key-string}? 428 | +--ro hexadecimal-string? yang:hex-string 429 | +--ro send-lifetime-active? boolean 430 | +--ro accept-lifetime-active? boolean 431 +--ro aes-key-wrap {aes-key-wrap}? 432 +--ro enable? boolean 434 4. Key Chain YANG Model 436 file "ietf-key-chain@2017-01-20.yang" 437 module ietf-key-chain { 438 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 439 // replace with IANA namespace when assigned 440 prefix "key-chain"; 441 import ietf-yang-types { 442 prefix "yang"; 443 } 445 import ietf-netconf-acm { 446 prefix "nacm"; 447 } 449 organization 450 "IETF RTG (Routing) Working Group"; 451 contact 452 "Acee Lindem - acee@cisco.com"; 454 description 455 "This YANG module defines the generic configuration 456 data for key-chain. It is intended that the module 457 will be extended by vendors to define vendor-specific 458 key-chain configuration parameters. 460 Copyright (c) 2015 IETF Trust and the persons identified as 461 authors of the code. All rights reserved. 463 Redistribution and use in source and binary forms, with or 464 without modification, is permitted pursuant to, and subject 465 to the license terms contained in, the Simplified BSD License 466 set forth in Section 4.c of the IETF Trust's Legal Provisions 467 Relating to IETF Documents 468 (http://trustee.ietf.org/license-info). 469 This version of this YANG module is part of RFC XXXX; see 470 the RFC itself for full legal notices."; 472 revision 2017-01-20 { 473 description 474 "Add support of using NETCONF Access Control for 475 key-string."; 476 reference 477 "RFC XXXX: A YANG Data Model for key-chain"; 478 } 479 revision 2016-11-14 { 480 description 481 "Restore last-modified timestamp leaf."; 482 reference 483 "RFC XXXX: A YANG Data Model for key-chain"; 484 } 485 revision 2016-10-27 { 486 description 487 "Restructure into separate config and state trees to 488 match YANG structure."; 489 reference 490 "RFC XXXX: A YANG Data Model for key-chain"; 491 } 492 revision 2016-08-17 { 493 description 494 "Add description and last-modified timestamp leaves."; 495 reference 496 "RFC XXXX: A YANG Data Model for key-chain"; 497 } 498 revision 2016-07-01 { 499 description 500 "Rename module back to ietf-key-chain. 501 Added replay-protection-only feature and algorithm."; 502 reference 503 "RFC XXXX: A YANG Data Model for key-chain"; 504 } 505 revision 2016-03-15 { 506 description 507 "Rename module from ietf-key-chain to 508 ietf-routing-key-chain."; 509 reference 510 "RFC XXXX: A YANG Data Model for Routing key-chain"; 511 } 512 revision 2016-02-16 { 513 description 514 "Updated version. Added clear-text algorithm as a 515 feature."; 516 reference 517 "RFC XXXX: A YANG Data Model for key-chain"; 518 } 519 revision 2015-10-15 { 520 description 521 "Updated version, organization, and copyright. 522 Added aes-cmac-prf-128 and aes-key-wrap features."; 523 reference 524 "RFC XXXX: A YANG Data Model for key-chain"; 525 } 526 revision 2015-06-29 { 527 description 528 "Updated version. Added Operation State following 529 draft-openconfig-netmod-opstate-00."; 530 reference 531 "RFC XXXX: A YANG Data Model for key-chain"; 532 } 533 revision 2015-02-24 { 534 description 535 "Initial revision."; 536 reference 537 "RFC XXXX: A YANG Data Model for key-chain"; 538 } 540 typedef key-chain-ref { 541 type leafref { 542 path "/key-chain:key-chain/key-chain:key-chain-list/" 543 + "key-chain:name"; 544 } 545 description 546 "This type is used by data models that need to reference 547 configured key-chains."; 548 } 550 /* feature list */ 551 feature hex-key-string { 552 description 553 "Support hexadecimal key string."; 554 } 556 feature accept-tolerance { 557 description 558 "To specify the tolerance or acceptance limit."; 559 } 561 feature independent-send-accept-lifetime { 562 description 563 "Support for independent send and accept key lifetimes."; 564 } 566 feature crypto-hmac-sha-1-12 { 567 description 568 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 569 } 571 feature clear-text { 572 description 573 "Support for clear-text algorithm. Usage is 574 NOT RECOMMENDED."; 576 } 578 feature aes-cmac-prf-128 { 579 description 580 "Support for AES Cipher based Message Authentication 581 Code Pseudo Random Function."; 582 } 584 feature aes-key-wrap { 585 description 586 "Support for Advanced Encryption Standard (AES) 587 Key Wrap."; 588 } 590 feature replay-protection-only { 591 description 592 "Provide replay-protection without any authentication 593 as required by protocols such as Bidirectional 594 Forwarding Detection (BFD)."; 595 } 597 /* groupings */ 598 grouping lifetime { 599 description 600 "Key lifetime specification."; 601 choice lifetime { 602 default always; 603 description 604 "Options for specifying key accept or send 605 lifetimes"; 606 case always { 607 leaf always { 608 type empty; 609 description 610 "Indicates key lifetime is always valid."; 611 } 612 } 613 case start-end-time { 614 leaf start-date-time { 615 type yang:date-and-time; 616 description "Start time."; 617 } 618 choice end-time { 619 default infinite; 620 description 621 "End-time setting."; 622 case infinite { 623 leaf no-end-time { 624 type empty; 625 description 626 "Indicates key lifetime end-time in 627 infinite."; 628 } 629 } 630 case duration { 631 leaf duration { 632 type uint32 { 633 range "1..2147483646"; 634 } 635 units seconds; 636 description "Key lifetime duration, 637 in seconds"; 638 } 639 } 640 case end-date-time { 641 leaf end-date-time { 642 type yang:date-and-time; 643 description "End time."; 644 } 645 } 646 } 647 } 648 } 649 } 651 grouping crypto-algorithm-types { 652 description "Cryptographic algorithm types."; 653 choice algorithm { 654 description 655 "Options for cryptographic algorithm specification."; 656 case hmac-sha-1-12 { 657 if-feature crypto-hmac-sha-1-12; 658 leaf hmac-sha1-12 { 659 type empty; 660 description "The HMAC-SHA1-12 algorithm."; 661 } 662 } 663 case aes-cmac-prf-128 { 664 if-feature aes-cmac-prf-128; 665 leaf aes-cmac-prf-128 { 666 type empty; 667 description "The AES-CMAC-PRF-128 algorithm - 668 required by RFC 5926 for TCP-AO key 669 derivation functions."; 670 } 671 } 672 case md5 { 673 leaf md5 { 674 type empty; 675 description "The MD5 algorithm."; 676 } 677 } 678 case sha-1 { 679 leaf sha-1 { 680 type empty; 681 description "The SHA-1 algorithm."; 682 } 683 } 684 case hmac-sha-1 { 685 leaf hmac-sha-1 { 686 type empty; 687 description 688 "HMAC-SHA-1 authentication algorithm."; 689 } 690 } 691 case hmac-sha-256 { 692 leaf hmac-sha-256 { 693 type empty; 694 description 695 "HMAC-SHA-256 authentication algorithm."; 696 } 697 } 698 case hmac-sha-384 { 699 leaf hmac-sha-384 { 700 type empty; 701 description 702 "HMAC-SHA-384 authentication algorithm."; 703 } 704 } 705 case hmac-sha-512 { 706 leaf hmac-sha-512 { 707 type empty; 708 description 709 "HMAC-SHA-512 authentication algorithm."; 710 } 711 } 712 case clear-text { 713 if-feature clear-text; 714 leaf clear-text { 715 type empty; 716 description "Clear text."; 717 } 718 } 719 case replay-protection-only { 720 if-feature replay-protection-only; 721 leaf replay-protection-only { 722 type empty; 723 description 724 "Provide replay-protection without any 725 authentication as required by protocols 726 such as Bidirectional Forwarding 727 Detection (BFD)."; 728 } 729 } 730 } 731 } 733 grouping key-chain-common-entry { 734 description "Key-chain entry data nodes common to 735 configuration and state."; 736 container lifetime { 737 description "Specify a key's lifetime."; 738 choice lifetime { 739 description 740 "Options for specification of send and accept 741 lifetimes."; 742 case send-and-accept-lifetime { 743 description 744 "Send and accept key have the same 745 lifetime."; 746 container send-accept-lifetime { 747 uses lifetime; 748 description 749 "Single lifetime specification for both 750 send and accept lifetimes."; 751 } 752 } 753 case independent-send-accept-lifetime { 754 if-feature independent-send-accept-lifetime; 755 description 756 "Independent send and accept key lifetimes."; 757 container send-lifetime { 758 uses lifetime; 759 description 760 "Separate lifetime specification for send 761 lifetime."; 762 } 763 container accept-lifetime { 764 uses lifetime; 765 description 766 "Separate lifetime specification for 767 accept lifetime."; 769 } 770 } 771 } 772 } 773 container crypto-algorithm { 774 uses crypto-algorithm-types; 775 description 776 "Cryptographic algorithm associated with key."; 777 } 778 container key-string { 779 description "The key string."; 780 nacm:default-deny-all; 781 choice key-string-style { 782 description 783 "Key string styles"; 784 case keystring { 785 leaf keystring { 786 type string; 787 description 788 "Key string in ASCII format."; 789 } 790 } 791 case hexadecimal { 792 if-feature hex-key-string; 793 leaf hexadecimal-string { 794 type yang:hex-string; 795 description 796 "Key in hexadecimal string format."; 797 } 798 } 799 } 800 } 801 } 803 grouping key-chain-config-entry { 804 description "Key-chain configuration entry."; 805 uses key-chain-common-entry; 806 } 807 grouping key-chain-state-entry { 808 description "Key-chain state entry."; 809 uses key-chain-common-entry; 810 leaf send-lifetime-active { 811 type boolean; 812 config false; 813 description 814 "Indicates if the send lifetime of the 815 key-chain entry is currently active."; 816 } 817 leaf accept-lifetime-active { 818 type boolean; 819 config false; 820 description 821 "Indicates if the accept lifetime of the 822 key-chain entry is currently active."; 823 } 824 } 826 grouping key-chain-common { 827 description 828 "key-chain common grouping."; 829 leaf name { 830 type string; 831 description "Name of the key-chain."; 832 } 833 leaf description { 834 type string; 835 description "A description of the key-chain"; 836 } 837 container accept-tolerance { 838 if-feature accept-tolerance; 839 description 840 "Tolerance for key lifetime acceptance (seconds)."; 841 leaf duration { 842 type uint32; 843 units seconds; 844 default "0"; 845 description 846 "Tolerance range, in seconds."; 847 } 848 } 849 } 851 grouping key-chain-config { 852 description 853 "key-chain configuration grouping."; 854 uses key-chain-common; 855 list key-chain-entries { 856 key "key-id"; 857 description "One key."; 858 leaf key-id { 859 type uint64; 860 description "Key ID."; 861 } 862 uses key-chain-config-entry; 863 } 864 } 865 grouping key-chain-state { 866 description 867 "key-chain state grouping."; 868 uses key-chain-common; 869 leaf last-modified-timestamp { 870 type yang:date-and-time; 871 description "Timestamp of the most recent update 872 to the key-chain"; 873 } 874 list key-chain-entries { 875 key "key-id"; 876 description "One key."; 877 leaf key-id { 878 type uint64; 879 description "Key ID."; 880 } 881 uses key-chain-state-entry; 882 } 883 } 885 container key-chain { 886 list key-chain-list { 887 key "name"; 888 description 889 "List of key-chains."; 890 uses key-chain-config; 891 } 893 container aes-key-wrap { 894 if-feature aes-key-wrap; 895 description 896 "AES Key Wrap password encryption."; 897 leaf enable { 898 type boolean; 899 default false; 900 description 901 "Enable AES Key Wrap encryption."; 902 } 903 } 904 description "All configured key-chains 905 on the device."; 906 } 908 container key-chain-state { 909 config false; 910 list key-chain-list { 911 key "name"; 912 description 913 "List of key-chains and operational state."; 914 uses key-chain-state; 915 } 916 container aes-key-wrap { 917 if-feature aes-key-wrap; 918 description 919 "AES Key Wrap password encryption."; 920 leaf enable { 921 type boolean; 922 description 923 "Indicates whether AES Key Wrap encryption 924 is enabled."; 925 } 926 } 927 description "State for all configured key-chains 928 on the device."; 929 } 930 } 931 933 5. Security Considerations 935 This document enables the automated distribution of industry standard 936 key chains using the NETCONF [NETCONF] protocol. As such, the 937 security considerations for the NETCONF protocol are applicable. 938 Given that the key chains themselves are sensitive data, it is 939 RECOMMENDED that the NETCONF communication channel be encrypted. One 940 way to do accomplish this would be to invoke and run NETCONF over SSH 941 as described in [NETCONF-SSH]. 943 When configured, the key-strings can be encrypted using the AES Key 944 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 945 not included in the YANG model and must be set or derived independent 946 of key-chain configuration. 948 The key strings are not accessible by default and NETCONF Access 949 Control Mode [NETCONF-ACM] rules are required to configure or 950 retrieve them. 952 The clear-text algorithm is included as a YANG feature. Usage is NOT 953 RECOMMENDED except in cases where the application and device have no 954 other alternative (e.g., a legacy network device that must 955 authenticate packets at intervals of 10 milliseconds or less for many 956 peers using Bidirectional Forwarding Detection [BFD]). Keys used 957 with the clear-text algorithm are considered insecure and SHOULD NOT 958 be reused with more secure algorithms. 960 6. IANA Considerations 962 This document registers a URI in the IETF XML registry 963 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 964 following registration is requested to be made: 966 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 968 Registrant Contact: The IESG. 970 XML: N/A, the requested URI is an XML namespace. 972 This document registers a YANG module in the YANG Module Names 973 registry [YANG]. 975 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 976 key-chain prefix: ietf-key-chain reference: RFC XXXX 978 7. References 980 7.1. Normative References 982 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 983 Bierman, "Network Configuration Protocol (NETCONF)", RFC 984 6241, June 2011. 986 [NETCONF-ACM] 987 Bierman, A. and M. Bjorklund, "Network Configuration 988 Protocol (NETCONF) Access Control Model", RFC 6536, March 989 2012. 991 [NETCONF-SSH] 992 Wasserman, M., "Using NETCONF Protocol over Secure Shell 993 (SSH)", RFC 6242, June 2011. 995 [RFC-KEYWORDS] 996 Bradner, S., "Key words for use in RFC's to Indicate 997 Requirement Levels", BCP 14, RFC 2119, March 1997. 999 [XML-REGISTRY] 1000 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1001 January 2004. 1003 [YANG] Bjorklund, M., "YANG - A Data Modeling Language for the 1004 Network Configuration Protocol (NETCONF)", RFC 6020, 1005 October 2010. 1007 7.2. Informative References 1009 [AES-KEY-WRAP] 1010 Housley, R. and M. Dworkin, "Advanced Encryption Standard 1011 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 1012 2009. 1014 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 1015 (BFD)", RFC 5880, June 2010. 1017 [CRYPTO-KEYTABLE] 1018 Housley, R., Polk, T., Hartman, S., and D. Zhang, 1019 "Table of Cryptographic Keys", RFC 7210, April 2014. 1021 [IAB-REPORT] 1022 Andersson, L., Davies, E., and L. Zhang, "Report from the 1023 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 1024 4948, August 2007. 1026 [NETCONF-SERVER-CONF] 1027 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 1028 RESTCONF Server Configuration Models", draft-ietf-netconf- 1029 server-model-08.txt (work in progress), October 2015. 1031 [NTP-PROTO] 1032 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 1033 Time Protocol Version 4: Protocol and Algorithms 1034 Specification", RFC 5905, June 2010. 1036 [OSPFV3-AUTH] 1037 Bhatia, M., Manral, V., and A. Lindem, "Supporting 1038 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 1040 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 1041 Authentication Option", RFC 5925, June 2010. 1043 [TCP-AO-ALGORITHMS] 1044 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 1045 for the TCP Authentication Option (TCP-AO)", RFC 5926, 1046 June 2010. 1048 [YANG-CRYPTO-KEYTABLE] 1049 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 1050 chen-rtg-key-table-yang-02.txt (work in progress), 1051 November 2015. 1053 Appendix A. Acknowledgments 1054 The RFC text was produced using Marshall Rose's xml2rfc tool. 1056 Thanks to Brian Weis for fruitful discussions on security 1057 requirements. 1059 Thanks to Ines Robles for Routing Directorate QA review comments. 1061 Authors' Addresses 1063 Acee Lindem (editor) 1064 Cisco Systems 1065 301 Midenhall Way 1066 Cary, NC 27513 1067 USA 1069 Email: acee@cisco.com 1071 Yingzhen Qu 1072 Huawei 1074 Email: yingzhen.qu@huawei.com 1076 Derek Yeung 1077 Arrcus, Inc 1079 Email: derek@arrcus.com 1081 Ing-Wher Chen 1082 Ericsson 1084 Email: ichen@kuatrotech.com 1086 Jeffrey Zhang 1087 Juniper Networks 1088 10 Technology Park Drive 1089 Westford, MA 01886 1090 USA 1092 Email: zzhang@juniper.net 1093 Yi Yang 1094 SockRate 1096 Email: yi.yang@sockrate.com