idnits 2.17.00 (12 Aug 2021) /tmp/idnits7348/draft-ietf-rtgwg-yang-key-chain-10.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 (October 27, 2016) is 2031 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: April 30, 2017 D. Yeung 6 Arrcus, Inc 7 I. Chen 8 Ericsson 9 J. Zhang 10 Juniper Networks 11 Y. Yang 12 Individual Contributor 13 October 27, 2016 15 Routing Key Chain YANG Data Model 16 draft-ietf-rtgwg-yang-key-chain-10.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 April 30, 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 . . . . . . . . . . . . . . . . . . . 19 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 80 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 81 7.1. Normative References . . . . . . . . . . . . . . . . . . 20 82 7.2. Informative References . . . . . . . . . . . . . . . . . 21 83 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 22 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 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) {replay-protection-only}? 332 | | | +--rw replay-protection-only? empty 333 | | +--rw key-string 334 | | +--rw (key-string-style)? 335 | | +--:(keystring) 336 | | | +--rw keystring? string 337 | | +--:(hexadecimal) {hex-key-string}? 338 | | +--rw hexadecimal-string? yang:hex-string 339 | +--rw aes-key-wrap {aes-key-wrap}? 340 | +--rw enable? boolean 341 +--ro key-chain-state 342 +--ro key-chain-list* [name] 343 | +--ro name string 344 | +--ro description? string 345 | +--ro accept-tolerance {accept-tolerance}? 346 | | +--ro duration? uint32 347 | +--ro key-chain-entries* [key-id] 348 | +--ro key-id uint64 349 | +--ro lifetime 350 | | +--ro (lifetime)? 351 | | +--:(send-and-accept-lifetime) 352 | | | +--ro send-accept-lifetime 353 | | | +--ro (lifetime)? 354 | | | +--:(always) 355 | | | | +--ro always? empty 356 | | | +--:(start-end-time) 357 | | | +--ro start-date-time? 358 | | | | yang:date-and-time 359 | | | +--ro (end-time)? 360 | | | +--:(infinite) 361 | | | | +--ro no-end-time? empty 362 | | | +--:(duration) 363 | | | | +--ro duration? uint32 364 | | | +--:(end-date-time) 365 | | | +--ro end-date-time? 366 | | | yang:date-and-time 367 | | +--:(independent-send-accept-lifetime) 368 | | {independent-send-accept-lifetime}? 369 | | +--ro send-lifetime 370 | | | +--ro (lifetime)? 371 | | | +--:(always) 372 | | | | +--ro always? empty 373 | | | +--:(start-end-time) 374 | | | +--ro start-date-time? 375 | | | yang:date-and-time 376 | | | +--ro (end-time)? 377 | | | +--:(infinite) 378 | | | | +--ro no-end-time? empty 379 | | | +--:(duration) 380 | | | | +--ro duration? uint32 381 | | | +--:(end-date-time) 382 | | | +--ro end-date-time? 383 | | | yang:date-and-time 384 | | +--ro accept-lifetime 385 | | +--ro (lifetime)? 386 | | +--:(always) 387 | | | +--ro always? empty 388 | | +--:(start-end-time) 389 | | +--ro start-date-time? 390 | | | yang:date-and-time 391 | | +--ro (end-time)? 392 | | +--:(infinite) 393 | | | +--ro no-end-time? empty 394 | | +--:(duration) 395 | | | +--ro duration? uint32 396 | | +--:(end-date-time) 397 | | +--ro end-date-time? 398 | | yang:date-and-time 399 | +--ro crypto-algorithm 400 | | +--ro (algorithm)? 401 | | +--:(hmac-sha-1-12) {crypto-hmac-sha-1-12}? 402 | | | +--ro hmac-sha1-12? empty 403 | | +--:(aes-cmac-prf-128) {aes-cmac-prf-128}? 404 | | | +--ro aes-cmac-prf-128? empty 405 | | +--:(md5) 406 | | | +--ro md5? empty 407 | | +--:(sha-1) 408 | | | +--ro sha-1? empty 409 | | +--:(hmac-sha-1) 410 | | | +--ro hmac-sha-1? empty 411 | | +--:(hmac-sha-256) 412 | | | +--ro hmac-sha-256? empty 413 | | +--:(hmac-sha-384) 414 | | | +--ro hmac-sha-384? empty 415 | | +--:(hmac-sha-512) 416 | | | +--ro hmac-sha-512? empty 417 | | +--:(clear-text) {clear-text}? 418 | | | +--ro clear-text? empty 419 | | +--:(replay-protection-only) {replay-protection-only}? 420 | | +--ro replay-protection-only? empty 421 | +--ro send-lifetime-active? boolean 422 | +--ro accept-lifetime-active? boolean 423 +--ro aes-key-wrap {aes-key-wrap}? 424 +--ro enable? boolean 426 4. Key Chain YANG Model 428 file "ietf-key-chain@2016-10-27.yang" 429 module ietf-key-chain { 430 namespace "urn:ietf:params:xml:ns:yang:ietf-key-chain"; 431 // replace with IANA namespace when assigned 432 prefix "key-chain"; 434 import ietf-yang-types { 435 prefix "yang"; 436 } 438 organization 439 "IETF RTG (Routing) Working Group"; 440 contact 441 "Acee Lindem - acee@cisco.com"; 443 description 444 "This YANG module defines the generic configuration 445 data for key-chain. It is intended that the module 446 will be extended by vendors to define vendor-specific 447 key-chain configuration parameters. 449 Copyright (c) 2015 IETF Trust and the persons identified as 450 authors of the code. All rights reserved. 452 Redistribution and use in source and binary forms, with or 453 without modification, is permitted pursuant to, and subject 454 to the license terms contained in, the Simplified BSD License 455 set forth in Section 4.c of the IETF Trust's Legal Provisions 456 Relating to IETF Documents 457 (http://trustee.ietf.org/license-info). 458 This version of this YANG module is part of RFC XXXX; see 459 the RFC itself for full legal notices."; 461 revision 2016-10-27 { 462 description 463 "Restructure into separate config and state trees to 464 match YANG structure."; 465 reference 466 "RFC XXXX: A YANG Data Model for key-chain"; 467 } 468 revision 2016-08-17 { 469 description 470 "Add description and last-modified timestamp leaves."; 471 reference 472 "RFC XXXX: A YANG Data Model for key-chain"; 473 } 474 revision 2016-07-01 { 475 description 476 "Rename module back to ietf-key-chain. 477 Added replay-protection-only feature and algorithm."; 478 reference 479 "RFC XXXX: A YANG Data Model for key-chain"; 480 } 481 revision 2016-03-15 { 482 description 483 "Rename module from ietf-key-chain to 484 ietf-routing-key-chain."; 485 reference 486 "RFC XXXX: A YANG Data Model for Routing key-chain"; 487 } 488 revision 2016-02-16 { 489 description 490 "Updated version. Added clear-text algorithm as a 491 feature."; 492 reference 493 "RFC XXXX: A YANG Data Model for key-chain"; 494 } 495 revision 2015-10-15 { 496 description 497 "Updated version, organization, and copyright. 498 Added aes-cmac-prf-128 and aes-key-wrap features."; 499 reference 500 "RFC XXXX: A YANG Data Model for key-chain"; 501 } 502 revision 2015-06-29 { 503 description 504 "Updated version. Added Operation State following 505 draft-openconfig-netmod-opstate-00."; 506 reference 507 "RFC XXXX: A YANG Data Model for key-chain"; 508 } 509 revision 2015-02-24 { 510 description 511 "Initial revision."; 512 reference 513 "RFC XXXX: A YANG Data Model for key-chain"; 514 } 516 typedef key-chain-ref { 517 type leafref { 518 path "/key-chain:key-chain/key-chain:key-chain-list/" 519 + "key-chain:name"; 520 } 521 description 522 "This type is used by data models that need to reference 523 configured key-chains."; 524 } 526 /* feature list */ 527 feature hex-key-string { 528 description 529 "Support hexadecimal key string."; 531 } 533 feature accept-tolerance { 534 description 535 "To specify the tolerance or acceptance limit."; 536 } 538 feature independent-send-accept-lifetime { 539 description 540 "Support for independent send and accept key lifetimes."; 541 } 543 feature crypto-hmac-sha-1-12 { 544 description 545 "Support for TCP HMAC-SHA-1 12 byte digest hack."; 546 } 548 feature clear-text { 549 description 550 "Support for clear-text algorithm. Usage is 551 NOT RECOMMENDED."; 552 } 554 feature aes-cmac-prf-128 { 555 description 556 "Support for AES Cipher based Message Authentication 557 Code Pseudo Random Function."; 558 } 560 feature aes-key-wrap { 561 description 562 "Support for Advanced Encryption Standard (AES) 563 Key Wrap."; 564 } 566 feature replay-protection-only { 567 description 568 "Provide replay-protection without any authentication 569 as required by protocols such as Bidirectional 570 Forwarding Detection (BFD)."; 571 } 573 /* groupings */ 574 grouping lifetime { 575 description 576 "Key lifetime specification."; 577 choice lifetime { 578 default always; 579 description 580 "Options for specifying key accept or send 581 lifetimes"; 582 case always { 583 leaf always { 584 type empty; 585 description 586 "Indicates key lifetime is always valid."; 587 } 588 } 589 case start-end-time { 590 leaf start-date-time { 591 type yang:date-and-time; 592 description "Start time."; 593 } 594 choice end-time { 595 default infinite; 596 description 597 "End-time setting."; 598 case infinite { 599 leaf no-end-time { 600 type empty; 601 description 602 "Indicates key lifetime end-time in 603 infinite."; 604 } 605 } 606 case duration { 607 leaf duration { 608 type uint32 { 609 range "1..2147483646"; 610 } 611 units seconds; 612 description "Key lifetime duration, 613 in seconds"; 614 } 615 } 616 case end-date-time { 617 leaf end-date-time { 618 type yang:date-and-time; 619 description "End time."; 620 } 621 } 622 } 623 } 624 } 625 } 626 grouping crypto-algorithm-types { 627 description "Cryptographic algorithm types."; 628 choice algorithm { 629 description 630 "Options for cryptographic algorithm specification."; 631 case hmac-sha-1-12 { 632 if-feature crypto-hmac-sha-1-12; 633 leaf hmac-sha1-12 { 634 type empty; 635 description "The HMAC-SHA1-12 algorithm."; 636 } 637 } 638 case aes-cmac-prf-128 { 639 if-feature aes-cmac-prf-128; 640 leaf aes-cmac-prf-128 { 641 type empty; 642 description "The AES-CMAC-PRF-128 algorithm - 643 required by RFC 5926 for TCP-AO key 644 derivation functions."; 645 } 646 } 647 case md5 { 648 leaf md5 { 649 type empty; 650 description "The MD5 algorithm."; 651 } 652 } 653 case sha-1 { 654 leaf sha-1 { 655 type empty; 656 description "The SHA-1 algorithm."; 657 } 658 } 659 case hmac-sha-1 { 660 leaf hmac-sha-1 { 661 type empty; 662 description 663 "HMAC-SHA-1 authentication algorithm."; 664 } 665 } 666 case hmac-sha-256 { 667 leaf hmac-sha-256 { 668 type empty; 669 description 670 "HMAC-SHA-256 authentication algorithm."; 671 } 672 } 673 case hmac-sha-384 { 674 leaf hmac-sha-384 { 675 type empty; 676 description 677 "HMAC-SHA-384 authentication algorithm."; 678 } 679 } 680 case hmac-sha-512 { 681 leaf hmac-sha-512 { 682 type empty; 683 description 684 "HMAC-SHA-512 authentication algorithm."; 685 } 686 } 687 case clear-text { 688 if-feature clear-text; 689 leaf clear-text { 690 type empty; 691 description "Clear text."; 692 } 693 } 694 case replay-protection-only { 695 if-feature replay-protection-only; 696 leaf replay-protection-only { 697 type empty; 698 description 699 "Provide replay-protection without any 700 authentication as required by protocols 701 such as Bidirectional Forwarding 702 Detection (BFD)."; 703 } 704 } 705 } 706 } 708 grouping key-chain-common-entry { 709 description "Key-chain entry data nodes common to 710 configuration and state."; 711 container lifetime { 712 description "Specify a key's lifetime."; 713 choice lifetime { 714 description 715 "Options for specification of send and accept 716 lifetimes."; 717 case send-and-accept-lifetime { 718 description 719 "Send and accept key have the same 720 lifetime."; 721 container send-accept-lifetime { 722 uses lifetime; 723 description 724 "Single lifetime specification for both 725 send and accept lifetimes."; 726 } 727 } 728 case independent-send-accept-lifetime { 729 if-feature independent-send-accept-lifetime; 730 description 731 "Independent send and accept key lifetimes."; 732 container send-lifetime { 733 uses lifetime; 734 description 735 "Separate lifetime specification for send 736 lifetime."; 737 } 738 container accept-lifetime { 739 uses lifetime; 740 description 741 "Separate lifetime specification for 742 accept lifetime."; 743 } 744 } 745 } 746 } 747 container crypto-algorithm { 748 uses crypto-algorithm-types; 749 description 750 "Cryptographic algorithm associated with key."; 751 } 752 } 754 grouping key-chain-config-entry { 755 description "Key-chain configuration entry."; 756 uses key-chain-common-entry; 757 container key-string { 758 description "The key string."; 759 choice key-string-style { 760 description 761 "Key string styles"; 762 case keystring { 763 leaf keystring { 764 type string; 765 description 766 "Key string in ASCII format."; 767 } 768 } 769 case hexadecimal { 770 if-feature hex-key-string; 771 leaf hexadecimal-string { 772 type yang:hex-string; 773 description 774 "Key in hexadecimal string format."; 775 } 776 } 777 } 778 } 779 } 781 grouping key-chain-state-entry { 782 description "Key-chain state entry."; 783 uses key-chain-common-entry; 784 leaf send-lifetime-active { 785 type boolean; 786 config false; 787 description 788 "Indicates if the send lifetime of the 789 key-chain entry is currently active."; 790 } 791 leaf accept-lifetime-active { 792 type boolean; 793 config false; 794 description 795 "Indicates if the accept lifetime of the 796 key-chain entry is currently active."; 797 } 798 } 800 grouping key-chain-common { 801 description 802 "key-chain common grouping."; 803 leaf name { 804 type string; 805 description "Name of the key-chain."; 806 } 807 leaf description { 808 type string; 809 description "A description of the key-chain"; 810 } 811 container accept-tolerance { 812 if-feature accept-tolerance; 813 description 814 "Tolerance for key lifetime acceptance (seconds)."; 815 leaf duration { 816 type uint32; 817 units seconds; 818 default "0"; 819 description 820 "Tolerance range, in seconds."; 821 } 822 } 823 } 825 grouping key-chain-config { 826 description 827 "key-chain configuration grouping."; 828 uses key-chain-common; 829 list key-chain-entries { 830 key "key-id"; 831 description "One key."; 832 leaf key-id { 833 type uint64; 834 description "Key ID."; 835 } 836 uses key-chain-config-entry; 837 } 838 } 840 grouping key-chain-state { 841 description 842 "key-chain state grouping."; 843 uses key-chain-common; 844 list key-chain-entries { 845 key "key-id"; 846 description "One key."; 847 leaf key-id { 848 type uint64; 849 description "Key ID."; 850 } 851 uses key-chain-state-entry; 852 } 853 } 855 container key-chain { 856 list key-chain-list { 857 key "name"; 858 description 859 "List of key-chains."; 860 uses key-chain-config; 861 } 863 container aes-key-wrap { 864 if-feature aes-key-wrap; 865 description 866 "AES Key Wrap password encryption."; 867 leaf enable { 868 type boolean; 869 default false; 870 description 871 "Enable AES Key Wrap encryption."; 872 } 873 } 874 description "All configured key-chains 875 on the device."; 876 } 878 container key-chain-state { 879 config false; 880 list key-chain-list { 881 key "name"; 882 description 883 "List of key-chains and operational state."; 884 uses key-chain-state; 885 } 886 container aes-key-wrap { 887 if-feature aes-key-wrap; 888 description 889 "AES Key Wrap password encryption."; 890 leaf enable { 891 type boolean; 892 description 893 "Indicates whether AES Key Wrap encryption 894 is enabled."; 895 } 896 } 897 description "State for all configured key-chains 898 on the device."; 899 } 900 } 901 903 5. Security Considerations 905 This document enables the automated distribution of industry standard 906 key chains using the NETCONF [NETCONF] protocol. As such, the 907 security considerations for the NETCONF protocol are applicable. 908 Given that the key chains themselves are sensitive data, it is 909 RECOMMENDED that the NETCONF communication channel be encrypted. One 910 way to do accomplish this would be to invoke and run NETCONF over SSH 911 as described in [NETCONF-SSH]. 913 When configured, the key-strings can be encrypted using the AES Key 914 Wrap algorithm [AES-KEY-WRAP]. The AES key-encryption key (KEK) is 915 not included in the YANG model and must be set or derived independent 916 of key-chain configuration. 918 The key strings are not included in the operational state. This is a 919 practice carried over from SNMP MIB modules and is an area for 920 further discussion. 922 The clear-text algorithm is included as a YANG feature. Usage is NOT 923 RECOMMENDED except in cases where the application and device have no 924 other alternative (e.g., a legacy network device that must 925 authenticate packets at intervals of 10 milliseconds or less for many 926 peers using Bidirectional Forwarding Detection [BFD]). Keys used 927 with the clear-text algorithm are considered insecure and SHOULD NOT 928 be reused with more secure algorithms. 930 6. IANA Considerations 932 This document registers a URI in the IETF XML registry 933 [XML-REGISTRY]. Following the format in [XML-REGISTRY], the 934 following registration is requested to be made: 936 URI: urn:ietf:params:xml:ns:yang:ietf-key-chain 938 Registrant Contact: The IESG. 940 XML: N/A, the requested URI is an XML namespace. 942 This document registers a YANG module in the YANG Module Names 943 registry [YANG]. 945 name: ietf-key-chain namespace: urn:ietf:params:xml:ns:yang:ietf- 946 key-chain prefix: ietf-key-chain reference: RFC XXXX 948 7. References 950 7.1. Normative References 952 [NETCONF] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 953 Bierman, "Network Configuration Protocol (NETCONF)", RFC 954 6241, June 2011. 956 [NETCONF-SSH] 957 Wasserman, M., "Using NETCONF Protocol over Secure Shell 958 (SSH)", RFC 6242, June 2011. 960 [RFC-KEYWORDS] 961 Bradner, S., "Key words for use in RFC's to Indicate 962 Requirement Levels", BCP 14, RFC 2119, March 1997. 964 [XML-REGISTRY] 965 Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 966 January 2004. 968 [YANG] Bjorklund, M., "YANG - A Data Modeling Language for the 969 Network Configuration Protocol (NETCONF)", RFC 6020, 970 October 2010. 972 7.2. Informative References 974 [AES-KEY-WRAP] 975 Housley, R. and M. Dworkin, "Advanced Encryption Standard 976 (AES) Key Wrap with Padding Algorithm", RFC 5649, August 977 2009. 979 [BFD] Katz, D. and D. Ward, "Bidirectional Forwarding Detection 980 (BFD)", RFC 5880, June 2010. 982 [CRYPTO-KEYTABLE] 983 Housley, R., Polk, T., Hartman, S., and D. Zhang, 984 "Table of Cryptographic Keys", RFC 7210, April 2014. 986 [IAB-REPORT] 987 Andersson, L., Davies, E., and L. Zhang, "Report from the 988 IAB workshop on Unwanted Traffic March 9-10, 2006", RFC 989 4948, August 2007. 991 [NETCONF-SERVER-CONF] 992 Watsen, K. and J. Schoenwaelder, "NETCONF Server and 993 RESTCONF Server Configuration Models", draft-ietf-netconf- 994 server-model-08.txt (work in progress), October 2015. 996 [NTP-PROTO] 997 Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 998 Time Protocol Version 4: Protocol and Algorithms 999 Specification", RFC 5905, June 2010. 1001 [OSPFV3-AUTH] 1002 Bhatia, M., Manral, V., and A. Lindem, "Supporting 1003 Authentication Trailer for OSPFv3", RFC 7166, March 2014. 1005 [TCP-AO] Touch, J., Mankin, A., and R. Bonica, "The TCP 1006 Authentication Option", RFC 5925, June 2010. 1008 [TCP-AO-ALGORITHMS] 1009 Lebovitz, G. and E. Rescorla, "Cryptographic Algorithms 1010 for the TCP Authentication Option (TCP-AO)", RFC 5926, 1011 June 2010. 1013 [YANG-CRYPTO-KEYTABLE] 1014 Chen, I., "YANG Data Model for RFC 7210 Key Table", draft- 1015 chen-rtg-key-table-yang-02.txt (work in progress), 1016 November 2015. 1018 Appendix A. Acknowledgments 1020 The RFC text was produced using Marshall Rose's xml2rfc tool. 1022 Thanks to Brian Weis for fruitful discussions on security 1023 requirements. 1025 Thanks to Ines Robles for Routing Directorate QA review comments. 1027 Authors' Addresses 1029 Acee Lindem (editor) 1030 Cisco Systems 1031 301 Midenhall Way 1032 Cary, NC 27513 1033 USA 1035 Email: acee@cisco.com 1037 Yingzhen Qu 1038 Cisco Systems 1039 170 West Tasman Drive 1040 San Jose, CA 95134 1041 USA 1043 Email: yiqu@cisco.com 1045 Derek Yeung 1046 Arrcus, Inc 1048 Email: derek@arrcus.com 1049 Ing-Wher Chen 1050 Ericsson 1052 Email: ichen@kuatrotech.com 1054 Jeffrey Zhang 1055 Juniper Networks 1056 10 Technology Park Drive 1057 Westford, MA 01886 1058 USA 1060 Email: zzhang@juniper.net 1062 Yi Yang 1063 Individual Contributor 1065 Email: yiyang1998@gmail.com