idnits 2.17.1 draft-ietf-netconf-trust-anchors-02.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 139 has weird spacing: '...on-date yan...' == Line 145 has weird spacing: '...ost-key ct:...' -- The document date (October 22, 2018) is 1984 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-01 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 Juniper Networks 4 Intended status: Standards Track October 22, 2018 5 Expires: April 25, 2019 7 YANG Data Model for Global Trust Anchors 8 draft-ietf-netconf-trust-anchors-02 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 "2018-10-22" --> 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 April 25, 2019. 59 Copyright Notice 61 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . 12 84 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 85 4.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 12 86 4.2. The YANG Module Names Registry . . . . . . . . . . . . . 13 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 94 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 96 1. Introduction 98 This document defines a YANG 1.1 [RFC7950] data model for configuring 99 global sets of X.509 certificates and SSH host-keys that can be 100 referenced by other data models for trust. While the SSH host-keys 101 are uniquely for the SSH protocol, the X.509 certificates may be used 102 for multiple uses, including authenticating protocol peers and 103 verifying signatures. 105 This document in compliant with Network Management Datastore 106 Architecture (NMDA) [RFC8342]. For instance, to support trust 107 anchors installed during manufacturing, it is expected that such data 108 may appear only in . 110 1.1. Requirements Language 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 114 "OPTIONAL" in this document are to be interpreted as described in BCP 115 14 [RFC2119] [RFC8174] when, and only when, they appear in all 116 capitals, as shown here. 118 1.2. Tree Diagram Notation 120 Tree diagrams used in this document follow the notation defined in 121 [RFC8340]. 123 2. The Trust Anchors Model 125 2.1. Tree Diagram 127 The following tree diagram provides an overview of the "ietf-trust- 128 anchors" module. 130 module: ietf-trust-anchors 131 +--rw trust-anchors 132 +--rw pinned-certificates* [name] {x509-certificates}? 133 | +--rw name string 134 | +--rw description? string 135 | +--rw pinned-certificate* [name] 136 | +--rw name string 137 | +--rw cert trust-anchor-cert-cms 138 | +---n certificate-expiration 139 | +-- expiration-date yang:date-and-time 140 +--rw pinned-host-keys* [name] {ssh-host-keys}? 141 +--rw name string 142 +--rw description? string 143 +--rw pinned-host-key* [name] 144 +--rw name string 145 +--rw host-key ct:ssh-host-key 147 2.2. Example Usage 149 The following example illustrates trust anchors in as 150 described by Section 5.3 in [RFC8342]. This datastore view 151 illustrates data set by the manufacturing process alongside 152 conventional configuration. This trust anchors instance has six sets 153 of pinned certificates and one set of pinned host keys. 155 159 160 161 manufacturers-root-ca-certs 162 163 Certificates built into the device for authenticating 164 manufacturer-signed objects, such as TLS server certificates, 165 vouchers, etc. Note, though listed here, these are not 166 configurable; any attempt to do so will be denied. 167 168 169 Manufacturer Root CA cert 1 170 base64encodedvalue== 171 172 173 Manufacturer Root CA cert 2 174 base64encodedvalue== 175 176 177 178 179 explicitly-trusted-server-certs 180 181 Specific server authentication certificates for explicitly 182 trusted servers. These are needed for server certificates 183 that are not signed by a pinned CA. 184 185 186 Fred Flintstone 187 base64encodedvalue== 188 189 191 192 193 explicitly-trusted-server-ca-certs 194 195 Trust anchors (i.e. CA certs) that are used to authenticate 196 server connections. Servers are authenticated if their 197 certificate has a chain of trust to one of these CA 198 certificates. 199 200 201 ca.example.com 202 base64encodedvalue== 203 204 206 207 208 explicitly-trusted-client-certs 209 210 Specific client authentication certificates for explicitly 211 trusted clients. These are needed for client certificates 212 that are not signed by a pinned CA. 213 214 215 George Jetson 216 base64encodedvalue== 217 218 220 221 222 explicitly-trusted-client-ca-certs 223 224 Trust anchors (i.e. CA certs) that are used to authenticate 225 client connections. Clients are authenticated if their 226 certificate has a chain of trust to one of these CA 227 certificates. 228 229 230 ca.example.com 231 base64encodedvalue== 232 233 235 236 237 common-ca-certs 238 239 Trusted certificates to authenticate common HTTPS servers. 240 These certificates are similar to those that might be 241 shipped with a web browser. 242 243 244 ex-certificate-authority 245 base64encodedvalue== 246 247 249 250 251 explicitly-trusted-ssh-host-keys 252 253 Trusted SSH host keys used to authenticate SSH servers. 254 These host keys would be analogous to those stored in 255 a known_hosts file in OpenSSH. 256 257 258 corp-fw1 259 base64encodedvalue== 260 261 263 265 The following example illustrates the "certificate-expiration" 266 notification in use with the NETCONF protocol. 268 [Note: '\' line wrapping for formatting only] 270 272 2018-05-25T00:01:00Z 273 275 276 explicitly-trusted-client-certs 277 278 George Jetson 279 280 2018-08-05T14:18:53-05:00 282 283 284 285 286 288 2.3. YANG Module 290 This YANG module imports modules from [RFC8341] and 291 [I-D.ietf-netconf-crypto-types]. 293 file "ietf-trust-anchors@2018-10-22.yang" 294 module ietf-trust-anchors { 295 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: 319 Author: Kent Watsen 320 "; 322 description 323 "This module defines a data model for configuring global 324 trust anchors used by other data models. The data model 325 enables the configuration of sets of trust anchors. 326 This data model supports configuring trust anchors for 327 both X.509 certificates and SSH host keys. 329 Copyright (c) 2018 IETF Trust and the persons identified 330 as authors of the code. All rights reserved. 332 Redistribution and use in source and binary forms, with 333 or without modification, is permitted pursuant to, and 334 subject to the license terms contained in, the Simplified 335 BSD License set forth in Section 4.c of the IETF Trust's 336 Legal Provisions Relating to IETF Documents 337 (http://trustee.ietf.org/license-info). 339 This version of this YANG module is part of RFC XXXX; see 340 the RFC itself for full legal notices."; 342 revision "2018-10-22" { 343 description 344 "Initial version"; 345 reference 346 "RFC XXXX: YANG Data Model for Global Trust Anchors"; 347 } 349 /************************************************************/ 350 /* Typedefs for leafrefs to commonly referenced objects */ 351 /************************************************************/ 353 feature x509-certificates { 354 description 355 "The 'x509-certificates' feature indicates that the server 356 implements the /trust-anchors/pinned-certificates subtree."; 357 } 359 feature ssh-host-keys { 360 description 361 "The 'ssh-host-keys' feature indicates that the server 362 implements the /trust-anchors/pinned-host-keys subtree."; 363 } 365 /************************************************************/ 366 /* Typedefs for leafrefs to commonly referenced objects */ 367 /************************************************************/ 369 typedef pinned-certificates-ref { 370 type leafref { 371 path "/ta:trust-anchors/ta:pinned-certificates/ta:name"; 372 require-instance false; 373 } 374 description 375 "This typedef enables importing modules to easily define a 376 leafref to a 'pinned-certificates' object. The require 377 instance attribute is false to enable the referencing of 378 pinned certificates that exist only in ."; 379 reference 380 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 381 } 383 typedef pinned-host-keys-ref { 384 type leafref { 385 path "/ta:trust-anchors/ta:pinned-host-keys/ta:name"; 386 require-instance false; 387 } 388 description 389 "This typedef enables importing modules to easily define a 390 leafref to a 'pinned-host-keys' object. The require 391 instance attribute is false to enable the referencing of 392 pinned host keys that exist only in ."; 393 reference 394 "RFC 8342: Network Management Datastore Architecture (NMDA)"; 395 } 397 /*********************************/ 398 /* Protocol accessible nodes */ 399 /*********************************/ 401 container trust-anchors { 402 nacm:default-deny-write; 404 description 405 "Contains sets of X.509 certificates and SSH host keys."; 407 list pinned-certificates { 408 if-feature "x509-certificates"; 409 key name; 410 description 411 "A list of pinned certificates. These certificates can be 412 used by a server to authenticate clients, or by a client 413 to authenticate servers. Each list of pinned certificates 414 SHOULD be specific to a purpose, as the list as a whole 415 may be referenced by other modules. For instance, a 416 RESTCONF server's configuration might use a specific list 417 of pinned certificates for when authenticating RESTCONF 418 client connections."; 419 leaf name { 420 type string; 421 description 422 "An arbitrary name for this list of pinned certificates."; 423 } 424 leaf description { 425 type string; 426 description 427 "An arbitrary description for this list of pinned 428 certificates."; 429 } 430 list pinned-certificate { 431 key name; 432 description 433 "A pinned certificate."; 434 leaf name { 435 type string; 436 description 437 "An arbitrary name for this pinned certificate. The 438 name must be unique across all lists of pinned 439 certificates (not just this list) so that leafrefs 440 from another module can resolve to unique values."; 441 } 442 uses ct:trust-anchor-cert-grouping { 443 refine cert { 444 mandatory true; 445 } 446 } 447 } 448 } 450 list pinned-host-keys { 451 if-feature "ssh-host-keys"; 452 key name; 453 description 454 "A list of pinned host keys. These pinned host-keys can 455 be used by clients to authenticate SSH servers. Each 456 list of pinned host keys SHOULD be specific to a purpose, 457 so the list as a whole may be referenced by other modules. 458 For instance, a NETCONF client's configuration might 459 point to a specific list of pinned host keys for when 460 authenticating specific SSH servers."; 461 leaf name { 462 type string; 463 description 464 "An arbitrary name for this list of pinned SSH 465 host keys."; 466 } 467 leaf description { 468 type string; 469 description 470 "An arbitrary description for this list of pinned SSH 471 host keys."; 472 } 473 list pinned-host-key { 474 key name; 475 description 476 "A pinned host key."; 477 leaf name { 478 type string; 479 description 480 "An arbitrary name for this pinned host-key. Must be 481 unique across all lists of pinned host-keys (not just 482 this list) so that a leafref to it from another module 483 can resolve to unique values."; 484 } 485 leaf host-key { 486 type ct:ssh-host-key; 487 mandatory true; 488 description 489 "The binary public key data for this pinned host key."; 490 reference 491 "RFC YYYY: Common YANG Data Types for Cryptography"; 492 } 493 } 494 } 495 } 497 } 498 500 3. Security Considerations 502 The YANG module defined in this document is designed to be accessed 503 via YANG based management protocols, such as NETCONF [RFC6241] and 504 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 505 implement secure transport layers (e.g., SSH, TLS) with mutual 506 authentication. 508 The NETCONF access control model (NACM) [RFC8341] provides the means 509 to restrict access for particular users to a pre-configured subset of 510 all available protocol operations and content. 512 There are a number of data nodes defined in this YANG module that are 513 writable/creatable/deletable (i.e., config true, which is the 514 default). These data nodes may be considered sensitive or vulnerable 515 in some network environments. Write operations (e.g., edit-config) 516 to these data nodes without proper protection can have a negative 517 effect on network operations. These are the subtrees and data nodes 518 and their sensitivity/vulnerability: 520 /: The entire data tree defined by this module is sensitive to 521 write operations. For instance, the addition or removal of any 522 trust anchor may dramatically alter the implemented security 523 policy. For this reason, the NACM extension "default-deny- 524 write" has been set for the entire data tree. 526 None of the readable data nodes in this YANG module are considered 527 sensitive or vulnerable in network environments. 529 This module does not define any RPCs, actions, or notifications, and 530 thus the security consideration for such is not provided here. 532 4. IANA Considerations 534 4.1. The IETF XML Registry 536 This document registers one URI in the "ns" subregistry of the IETF 537 XML Registry [RFC3688]. Following the format in [RFC3688], the 538 following registration is requested: 540 URI: urn:ietf:params:xml:ns:yang:ietf-trust-anchors 541 Registrant Contact: The NETCONF WG of the IETF. 542 XML: N/A, the requested URI is an XML namespace. 544 4.2. The YANG Module Names Registry 546 This document registers one YANG module in the YANG Module Names 547 registry [RFC6020]. Following the format in [RFC6020], the the 548 following registration is requested: 550 name: ietf-trust-anchors 551 namespace: urn:ietf:params:xml:ns:yang:ietf-trust-anchors 552 prefix: ta 553 reference: RFC XXXX 555 5. References 557 5.1. Normative References 559 [I-D.ietf-netconf-crypto-types] 560 Watsen, K., "Common YANG Data Types for Cryptography", 561 draft-ietf-netconf-crypto-types-01 (work in progress), 562 September 2018. 564 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 565 Requirement Levels", BCP 14, RFC 2119, 566 DOI 10.17487/RFC2119, March 1997, 567 . 569 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 570 RFC 7950, DOI 10.17487/RFC7950, August 2016, 571 . 573 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 574 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 575 May 2017, . 577 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 578 Access Control Model", STD 91, RFC 8341, 579 DOI 10.17487/RFC8341, March 2018, 580 . 582 5.2. Informative References 584 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 585 DOI 10.17487/RFC3688, January 2004, 586 . 588 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 589 the Network Configuration Protocol (NETCONF)", RFC 6020, 590 DOI 10.17487/RFC6020, October 2010, 591 . 593 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 594 and A. Bierman, Ed., "Network Configuration Protocol 595 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 596 . 598 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 599 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 600 . 602 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 603 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 604 . 606 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 607 and R. Wilton, "Network Management Datastore Architecture 608 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 609 . 611 Appendix A. Change Log 613 A.1. 00 to 01 615 o Added features "x509-certificates" and "ssh-host-keys". 617 o Added nacm:default-deny-write to "trust-anchors" container. 619 A.2. 01 to 02 621 o Switched "list pinned-certificate" to use the "trust-anchor-cert- 622 grouping" from crypto-types. Effectively the same definition as 623 before. 625 Acknowledgements 627 The authors would like to thank for following for lively discussions 628 on list and in the halls (ordered by last name): Martin Bjorklund, 629 Balazs Kovacs, Eric Voit, and Liang Xia. 631 Author's Address 633 Kent Watsen 634 Juniper Networks 636 EMail: kwatsen@juniper.net