idnits 2.17.1 draft-ietf-netconf-trust-anchors-03.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 == Line 140 has weird spacing: '...on-date yan...' == Line 146 has weird spacing: '...ost-key ct:...' -- The document date (March 9, 2019) is 1847 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 (-34) exists of draft-ietf-netconf-crypto-types-02 Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track March 9, 2019 5 Expires: September 10, 2019 7 YANG Data Model for Global Trust Anchors 8 draft-ietf-netconf-trust-anchors-03 10 Abstract 12 This document defines a YANG 1.1 data model for configuring global 13 sets of X.509 certificates and SSH host-keys that can be referenced 14 by other data models for trust. While the SSH host-keys are uniquely 15 for the SSH protocol, the X.509 certificates may have multiple uses, 16 including authenticating protocol peers and verifying signatures. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains many placeholder values that need to be replaced 21 with finalized values at the time of publication. This note 22 summarizes all of the substitutions that are needed. No other RFC 23 Editor instructions are specified elsewhere in this document. 25 Artwork in this document contains shorthand references to drafts in 26 progress. Please apply the following replacements: 28 o "XXXX" --> the assigned RFC value for this draft 30 o "YYYY" --> the assigned RFC value for draft-ietf-netconf-crypto- 31 types 33 Artwork in this document contains placeholder values for the date of 34 publication of this draft. Please apply the following replacement: 36 o "2019-03-09" --> the publication date of this draft 38 The following Appendix section is to be removed prior to publication: 40 o Appendix A. Change Log 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at https://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on September 10, 2019. 59 Copyright Notice 61 Copyright (c) 2019 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (https://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 77 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 78 1.2. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 3 79 2. The Trust Anchors Model . . . . . . . . . . . . . . . . . . . 3 80 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 81 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 4 82 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 7 83 3. Security Considerations . . . . . . . . . . . . . . . . . . . 11 84 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 85 4.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 12 86 4.2. The YANG Module Names Registry . . . . . . . . . . . . . 12 87 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 88 5.1. Normative References . . . . . . . . . . . . . . . . . . 13 89 5.2. Informative References . . . . . . . . . . . . . . . . . 13 90 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 15 91 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 15 92 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 15 93 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 15 94 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 95 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 97 1. Introduction 99 This document defines a YANG 1.1 [RFC7950] data model for configuring 100 global sets of X.509 certificates and SSH host-keys that can be 101 referenced by other data models for trust. While the SSH host-keys 102 are uniquely for the SSH protocol, the X.509 certificates may be used 103 for multiple uses, including authenticating protocol peers and 104 verifying signatures. 106 This document in compliant with Network Management Datastore 107 Architecture (NMDA) [RFC8342]. For instance, to support trust 108 anchors installed during manufacturing, it is expected that such data 109 may appear only in . 111 1.1. Requirements Language 113 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 114 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 115 "OPTIONAL" in this document are to be interpreted as described in BCP 116 14 [RFC2119] [RFC8174] when, and only when, they appear in all 117 capitals, as shown here. 119 1.2. Tree Diagram Notation 121 Tree diagrams used in this document follow the notation defined in 122 [RFC8340]. 124 2. The Trust Anchors Model 126 2.1. Tree Diagram 128 The following tree diagram provides an overview of the "ietf-trust- 129 anchors" module. 131 module: ietf-trust-anchors 132 +--rw trust-anchors 133 +--rw pinned-certificates* [name] {x509-certificates}? 134 | +--rw name string 135 | +--rw description? string 136 | +--rw pinned-certificate* [name] 137 | +--rw name string 138 | +--rw cert trust-anchor-cert-cms 139 | +---n certificate-expiration 140 | +-- expiration-date yang:date-and-time 141 +--rw pinned-host-keys* [name] {ssh-host-keys}? 142 +--rw name string 143 +--rw description? string 144 +--rw pinned-host-key* [name] 145 +--rw name string 146 +--rw host-key ct:ssh-host-key 148 2.2. Example Usage 150 The following example illustrates trust anchors in as 151 described by Section 5.3 in [RFC8342]. This datastore view 152 illustrates data set by the manufacturing process alongside 153 conventional configuration. This trust anchors instance has six sets 154 of pinned certificates and one set of pinned host keys. 156 160 161 162 manufacturers-root-ca-certs 163 164 Certificates built into the device for authenticating 165 manufacturer-signed objects, such as TLS server certificates, 166 vouchers, etc. Note, though listed here, these are not 167 configurable; any attempt to do so will be denied. 168 169 170 Manufacturer Root CA cert 1 171 base64encodedvalue== 172 173 174 Manufacturer Root CA cert 2 175 base64encodedvalue== 176 177 178 179 180 explicitly-trusted-server-certs 181 182 Specific server authentication certificates for explicitly 183 trusted servers. These are needed for server certificates 184 that are not signed by a pinned CA. 185 186 187 Fred Flintstone 188 base64encodedvalue== 189 190 192 193 194 explicitly-trusted-server-ca-certs 195 196 Trust anchors (i.e. CA certs) that are used to authenticate 197 server connections. Servers are authenticated if their 198 certificate has a chain of trust to one of these CA 199 certificates. 200 201 202 ca.example.com 203 base64encodedvalue== 204 205 207 208 209 explicitly-trusted-client-certs 210 211 Specific client authentication certificates for explicitly 212 trusted clients. These are needed for client certificates 213 that are not signed by a pinned CA. 214 215 216 George Jetson 217 base64encodedvalue== 218 219 221 222 223 explicitly-trusted-client-ca-certs 224 225 Trust anchors (i.e. CA certs) that are used to authenticate 226 client connections. Clients are authenticated if their 227 certificate has a chain of trust to one of these CA 228 certificates. 229 230 231 ca.example.com 232 base64encodedvalue== 233 234 236 237 238 common-ca-certs 239 240 Trusted certificates to authenticate common HTTPS servers. 241 These certificates are similar to those that might be 242 shipped with a web browser. 243 244 245 ex-certificate-authority 246 base64encodedvalue== 247 248 250 251 252 explicitly-trusted-ssh-host-keys 253 254 Trusted SSH host keys used to authenticate SSH servers. 255 These host keys would be analogous to those stored in 256 a known_hosts file in OpenSSH. 257 258 259 corp-fw1 260 base64encodedvalue== 261 262 264 266 The following example illustrates the "certificate-expiration" 267 notification in use with the NETCONF protocol. 269 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 271 273 2018-05-25T00:01:00Z 274 276 277 explicitly-trusted-client-certs 278 279 George Jetson 280 281 2018-08-05T14:18:53-05:00 283 284 285 286 287 289 2.3. YANG Module 291 This YANG module imports modules from [RFC8341] and 292 [I-D.ietf-netconf-crypto-types]. 294 file "ietf-trust-anchors@2019-03-09.yang" 295 module ietf-trust-anchors { 296 yang-version 1.1; 297 namespace "urn:ietf:params:xml:ns:yang:ietf-trust-anchors"; 298 prefix ta; 300 import ietf-netconf-acm { 301 prefix nacm; 302 reference 303 "RFC 8341: Network Configuration Access Control Model"; 304 } 306 import ietf-crypto-types { 307 prefix ct; 308 reference 309 "RFC YYYY: Common YANG Data Types for Cryptography"; 310 } 312 organization 313 "IETF NETCONF (Network Configuration) Working Group"; 315 contact 316 "WG Web: 317 WG List: 318 Author: Kent Watsen "; 320 description 321 "This module defines a data model for configuring global 322 trust anchors used by other data models. The data model 323 enables the configuration of sets of trust anchors. 324 This data model supports configuring trust anchors for 325 both X.509 certificates and SSH host keys. 327 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 328 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 329 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 330 are to be interpreted as described in BCP 14 [RFC2119] 331 [RFC8174] when, and only when, they appear in all 332 capitals, as shown here. 334 Copyright (c) 2019 IETF Trust and the persons identified 335 as authors of the code. All rights reserved. 337 Redistribution and use in source and binary forms, with 338 or without modification, is permitted pursuant to, and 339 subject to the license terms contained in, the Simplified 340 BSD License set forth in Section 4.c of the IETF Trust's 341 Legal Provisions Relating to IETF Documents 342 (http://trustee.ietf.org/license-info). 344 This version of this YANG module is part of RFC XXXX; see 345 the RFC itself for full legal notices."; 347 revision 2019-03-09 { 348 description 349 "Initial version"; 350 reference 351 "RFC XXXX: YANG Data Model for Global Trust Anchors"; 352 } 354 /************************************************************/ 355 /* Typedefs for leafrefs to commonly referenced objects */ 356 /************************************************************/ 358 feature x509-certificates { 359 description 360 "The 'x509-certificates' feature indicates that the server 361 implements the /trust-anchors/pinned-certificates subtree."; 362 } 363 feature ssh-host-keys { 364 description 365 "The 'ssh-host-keys' feature indicates that the server 366 implements the /trust-anchors/pinned-host-keys subtree."; 367 } 369 /************************************************************/ 370 /* Typedefs for leafrefs to commonly referenced objects */ 371 /************************************************************/ 373 typedef pinned-certificates-ref { 374 type leafref { 375 path "/ta:trust-anchors/ta:pinned-certificates/ta:name"; 376 require-instance false; 377 } 378 description 379 "This typedef enables importing modules to easily define a 380 leafref to a 'pinned-certificates' object. The require 381 instance attribute is false to enable the referencing of 382 pinned certificates that exist only in ."; 383 reference 384 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 385 } 387 typedef pinned-host-keys-ref { 388 type leafref { 389 path "/ta:trust-anchors/ta:pinned-host-keys/ta:name"; 390 require-instance false; 391 } 392 description 393 "This typedef enables importing modules to easily define a 394 leafref to a 'pinned-host-keys' object. The require 395 instance attribute is false to enable the referencing of 396 pinned host keys that exist only in ."; 397 reference 398 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 399 } 401 /*********************************/ 402 /* Protocol accessible nodes */ 403 /*********************************/ 405 container trust-anchors { 406 nacm:default-deny-write; 407 description 408 "Contains sets of X.509 certificates and SSH host keys."; 409 list pinned-certificates { 410 if-feature "x509-certificates"; 411 key "name"; 412 description 413 "A list of pinned certificates. These certificates can be 414 used by a server to authenticate clients, or by a client 415 to authenticate servers. Each list of pinned certificates 416 SHOULD be specific to a purpose, as the list as a whole 417 may be referenced by other modules. For instance, a 418 RESTCONF server's configuration might use a specific list 419 of pinned certificates for when authenticating RESTCONF 420 client connections."; 421 leaf name { 422 type string; 423 description 424 "An arbitrary name for this list of pinned certificates."; 425 } 426 leaf description { 427 type string; 428 description 429 "An arbitrary description for this list of pinned 430 certificates."; 431 } 432 list pinned-certificate { 433 key "name"; 434 description 435 "A pinned certificate."; 436 leaf name { 437 type string; 438 description 439 "An arbitrary name for this pinned certificate. The 440 name must be unique across all lists of pinned 441 certificates (not just this list) so that leafrefs 442 from another module can resolve to unique values."; 443 } 444 uses ct:trust-anchor-cert-grouping { 445 refine "cert" { 446 mandatory true; 447 } 448 } 449 } 450 } 451 list pinned-host-keys { 452 if-feature "ssh-host-keys"; 453 key "name"; 454 description 455 "A list of pinned host keys. These pinned host-keys can 456 be used by clients to authenticate SSH servers. Each 457 list of pinned host keys SHOULD be specific to a purpose, 458 so the list as a whole may be referenced by other modules. 460 For instance, a NETCONF client's configuration might 461 point to a specific list of pinned host keys for when 462 authenticating specific SSH servers."; 463 leaf name { 464 type string; 465 description 466 "An arbitrary name for this list of pinned SSH 467 host keys."; 468 } 469 leaf description { 470 type string; 471 description 472 "An arbitrary description for this list of pinned SSH 473 host keys."; 474 } 475 list pinned-host-key { 476 key "name"; 477 description 478 "A pinned host key."; 479 leaf name { 480 type string; 481 description 482 "An arbitrary name for this pinned host-key. Must be 483 unique across all lists of pinned host-keys (not just 484 this list) so that a leafref to it from another module 485 can resolve to unique values."; 486 } 487 leaf host-key { 488 type ct:ssh-host-key; 489 mandatory true; 490 description 491 "The binary public key data for this pinned host key."; 492 reference 493 "RFC YYYY: Common YANG Data Types for Cryptography"; 494 } 495 } 496 } 497 } 498 } 499 501 3. Security Considerations 503 The YANG module defined in this document is designed to be accessed 504 via YANG based management protocols, such as NETCONF [RFC6241] and 505 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 506 implement secure transport layers (e.g., SSH, TLS) with mutual 507 authentication. 509 The NETCONF access control model (NACM) [RFC8341] provides the means 510 to restrict access for particular users to a pre-configured subset of 511 all available protocol operations and content. 513 There are a number of data nodes defined in this YANG module that are 514 writable/creatable/deletable (i.e., config true, which is the 515 default). These data nodes may be considered sensitive or vulnerable 516 in some network environments. Write operations (e.g., edit-config) 517 to these data nodes without proper protection can have a negative 518 effect on network operations. These are the subtrees and data nodes 519 and their sensitivity/vulnerability: 521 /: The entire data tree defined by this module is sensitive to 522 write operations. For instance, the addition or removal of any 523 trust anchor may dramatically alter the implemented security 524 policy. For this reason, the NACM extension "default-deny- 525 write" has been set for the entire data tree. 527 None of the readable data nodes in this YANG module are considered 528 sensitive or vulnerable in network environments. 530 This module does not define any RPCs, actions, or notifications, and 531 thus the security consideration for such is not provided here. 533 4. IANA Considerations 535 4.1. The IETF XML Registry 537 This document registers one URI in the "ns" subregistry of the IETF 538 XML Registry [RFC3688]. Following the format in [RFC3688], the 539 following registration is requested: 541 URI: urn:ietf:params:xml:ns:yang:ietf-trust-anchors 542 Registrant Contact: The NETCONF WG of the IETF. 543 XML: N/A, the requested URI is an XML namespace. 545 4.2. The YANG Module Names Registry 547 This document registers one YANG module in the YANG Module Names 548 registry [RFC6020]. Following the format in [RFC6020], the the 549 following registration is requested: 551 name: ietf-trust-anchors 552 namespace: urn:ietf:params:xml:ns:yang:ietf-trust-anchors 553 prefix: ta 554 reference: RFC XXXX 556 5. References 558 5.1. Normative References 560 [I-D.ietf-netconf-crypto-types] 561 Watsen, K. and H. Wang, "Common YANG Data Types for 562 Cryptography", draft-ietf-netconf-crypto-types-02 (work in 563 progress), October 2018. 565 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 566 Requirement Levels", BCP 14, RFC 2119, 567 DOI 10.17487/RFC2119, March 1997, 568 . 570 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 571 RFC 7950, DOI 10.17487/RFC7950, August 2016, 572 . 574 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 575 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 576 May 2017, . 578 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 579 Access Control Model", STD 91, RFC 8341, 580 DOI 10.17487/RFC8341, March 2018, 581 . 583 5.2. Informative References 585 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 586 DOI 10.17487/RFC3688, January 2004, 587 . 589 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 590 the Network Configuration Protocol (NETCONF)", RFC 6020, 591 DOI 10.17487/RFC6020, October 2010, 592 . 594 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 595 and A. Bierman, Ed., "Network Configuration Protocol 596 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 597 . 599 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 600 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 601 . 603 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 604 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 605 . 607 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 608 and R. Wilton, "Network Management Datastore Architecture 609 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 610 . 612 Appendix A. Change Log 614 A.1. 00 to 01 616 o Added features "x509-certificates" and "ssh-host-keys". 618 o Added nacm:default-deny-write to "trust-anchors" container. 620 A.2. 01 to 02 622 o Switched "list pinned-certificate" to use the "trust-anchor-cert- 623 grouping" from crypto-types. Effectively the same definition as 624 before. 626 A.3. 02 to 03 628 o Updated copyright date, boilerplate template, affiliation, folding 629 algorithm, and reformatted the YANG module. 631 Acknowledgements 633 The authors would like to thank for following for lively discussions 634 on list and in the halls (ordered by last name): Martin Bjorklund, 635 Balazs Kovacs, Eric Voit, and Liang Xia. 637 Author's Address 639 Kent Watsen 640 Watsen Networks 642 EMail: kent+ietf@watsen.net