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