idnits 2.17.1 draft-ietf-netconf-trust-anchors-07.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 149 has weird spacing: '...on-date yan...' == Line 155 has weird spacing: '...ost-key ct:...' == Line 160 has weird spacing: '...rw name str...' == Line 167 has weird spacing: '...lic-key ct:...' == Line 175 has weird spacing: '...on-date yan...' == (3 more instances...) == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (November 1, 2019) is 1631 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-11 Summary: 0 errors (**), 0 flaws (~~), 9 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 H. Birkholz 5 Expires: May 4, 2020 Fraunhofer SIT 6 November 1, 2019 8 A YANG Data Model for a Truststore 9 draft-ietf-netconf-trust-anchors-07 11 Abstract 13 This document defines a YANG 1.1 data model for configuring global 14 sets of X.509 certificates, SSH host-keys, raw public keys, and PSKs 15 (pairwise-symmetric or pre-shared keys) that can be referenced by 16 other data models for trust. While the SSH host-keys are uniquely 17 for the SSH protocol, certificates, raw public keys, and PSKs may 18 have multiple uses, including authenticating protocol peers and 19 verifying signatures. 21 Editorial Note (To be removed by RFC Editor) 23 This draft contains many placeholder values that need to be replaced 24 with finalized values at the time of publication. This note 25 summarizes all of the substitutions that are needed. No other RFC 26 Editor instructions are specified elsewhere in this document. 28 Artwork in this document contains shorthand references to drafts in 29 progress. Please apply the following replacements: 31 o "XXXX" --> the assigned RFC value for this draft 33 o "YYYY" --> the assigned RFC value for draft-ietf-netconf-crypto- 34 types 36 Artwork in this document contains placeholder values for the date of 37 publication of this draft. Please apply the following replacement: 39 o "2019-11-02" --> the publication date of this draft 41 The following Appendix section is to be removed prior to publication: 43 o Appendix A. Change Log 45 Status of This Memo 47 This Internet-Draft is submitted in full conformance with the 48 provisions of BCP 78 and BCP 79. 50 Internet-Drafts are working documents of the Internet Engineering 51 Task Force (IETF). Note that other groups may also distribute 52 working documents as Internet-Drafts. The list of current Internet- 53 Drafts is at https://datatracker.ietf.org/drafts/current/. 55 Internet-Drafts are draft documents valid for a maximum of six months 56 and may be updated, replaced, or obsoleted by other documents at any 57 time. It is inappropriate to use Internet-Drafts as reference 58 material or to cite them other than as "work in progress." 60 This Internet-Draft will expire on May 4, 2020. 62 Copyright Notice 64 Copyright (c) 2019 IETF Trust and the persons identified as the 65 document authors. All rights reserved. 67 This document is subject to BCP 78 and the IETF Trust's Legal 68 Provisions Relating to IETF Documents 69 (https://trustee.ietf.org/license-info) in effect on the date of 70 publication of this document. Please review these documents 71 carefully, as they describe your rights and restrictions with respect 72 to this document. Code Components extracted from this document must 73 include Simplified BSD License text as described in Section 4.e of 74 the Trust Legal Provisions and are provided without warranty as 75 described in the Simplified BSD License. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 80 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 81 1.2. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 3 82 2. The Trust Anchors Model . . . . . . . . . . . . . . . . . . . 3 83 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 84 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 5 85 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 86 3. Security Considerations . . . . . . . . . . . . . . . . . . . 9 87 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 88 4.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 9 89 4.2. The YANG Module Names Registry . . . . . . . . . . . . . 10 90 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 91 5.1. Normative References . . . . . . . . . . . . . . . . . . 10 92 5.2. Informative References . . . . . . . . . . . . . . . . . 10 94 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 12 95 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 12 96 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 12 97 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 12 98 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 12 99 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 12 100 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 13 101 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 13 102 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 105 1. Introduction 107 This document defines a YANG 1.1 [RFC7950] data model for configuring 108 global sets of X.509 certificates, SSH host-keys, raw public keys, 109 and PSKs (pairwise-symmetric or pre-shared keys) that can be 110 referenced by other data models for trust. While the SSH host-keys 111 are uniquely for the SSH protocol, certificates, raw public keys, and 112 PSKs may have multiple uses, including authenticating protocol peers 113 and verifying signatures. 115 This document in compliant with Network Management Datastore 116 Architecture (NMDA) [RFC8342]. For instance, to support trust 117 anchors installed during manufacturing, it is expected that such data 118 would appear only in . 120 1.1. Requirements Language 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 124 "OPTIONAL" in this document are to be interpreted as described in BCP 125 14 [RFC2119] [RFC8174] when, and only when, they appear in all 126 capitals, as shown here. 128 1.2. Tree Diagram Notation 130 Tree diagrams used in this document follow the notation defined in 131 [RFC8340]. 133 2. The Trust Anchors Model 135 2.1. Tree Diagram 137 The following tree diagram provides an overview of the "ietf- 138 truststore" module. 140 module: ietf-truststore 141 +--rw truststore 142 +--rw certificates* [name] {x509-certificates}? 143 | +--rw name string 144 | +--rw description? string 145 | +--rw certificate* [name] 146 | +--rw name string 147 | +--rw cert trust-anchor-cert-cms 148 | +---n certificate-expiration 149 | +-- expiration-date yang:date-and-time 150 +--rw host-keys* [name] {ssh-host-keys}? 151 | +--rw name string 152 | +--rw description? string 153 | +--rw host-key* [name] 154 | +--rw name string 155 | +--rw host-key ct:ssh-host-key 156 +--rw psks* [name] {psks}? 157 | +--rw name string 158 | +--rw description? string 159 | +--rw psk* [name] 160 | +--rw name string 161 | +--rw psk ct:psk 162 +--rw raw-public-keys* [name] {raw-public-keys}? 163 +--rw name string 164 +--rw description? string 165 +--rw raw-public-key* [name] 166 +--rw name string 167 +--rw raw-public-key ct:raw-public-key 169 grouping local-or-truststore-certs-grouping 170 +-- (local-or-truststore) 171 +--:(local) {local-definitions-supported}? 172 | +-- local-definition 173 | +-- cert* trust-anchor-cert-cms 174 | +---n certificate-expiration 175 | +-- expiration-date yang:date-and-time 176 +--:(truststore) {truststore-supported,x509-certificates}? 177 +-- truststore-reference? ts:certificates-ref 178 grouping local-or-truststore-host-keys-grouping 179 +-- (local-or-truststore) 180 +--:(local) {local-definitions-supported}? 181 | +-- local-definition 182 | +-- host-key* ct:ssh-host-key 183 +--:(truststore) {truststore-supported,ssh-host-keys}? 184 +-- truststore-reference? ts:host-keys-ref 185 grouping local-or-truststore-psks-grouping 186 +-- (local-or-truststore) 187 +--:(local) {local-definitions-supported}? 188 | +-- local-definition 189 | +-- psk* ct:psk 190 +--:(truststore) {truststore-supported,psks}? 191 +-- truststore-reference? ts:psks-ref 192 grouping local-or-truststore-raw-pub-keys-grouping 193 +-- (local-or-truststore) 194 +--:(local) {local-definitions-supported}? 195 | +-- local-definition 196 | +-- raw-public-key* ct:raw-public-key 197 +--:(truststore) {truststore-supported,raw-public-keys}? 198 +-- truststore-reference? ts:raw-public-keys-ref 199 grouping truststore-grouping 200 +-- certificates* [name] {x509-certificates}? 201 | +-- name? string 202 | +-- description? string 203 | +-- certificate* [name] 204 | +-- name? string 205 | +-- cert trust-anchor-cert-cms 206 | +---n certificate-expiration 207 | +-- expiration-date yang:date-and-time 208 +-- host-keys* [name] {ssh-host-keys}? 209 | +-- name? string 210 | +-- description? string 211 | +-- host-key* [name] 212 | +-- name? string 213 | +-- host-key ct:ssh-host-key 214 +-- psks* [name] {psks}? 215 | +-- name? string 216 | +-- description? string 217 | +-- psk* [name] 218 | +-- name? string 219 | +-- psk ct:psk 220 +-- raw-public-keys* [name] {raw-public-keys}? 221 +-- name? string 222 +-- description? string 223 +-- raw-public-key* [name] 224 +-- name? string 225 +-- raw-public-key ct:raw-public-key 227 2.2. Example Usage 229 The following example illustrates trust anchors in as 230 described by Section 5.3 in [RFC8342]. This datastore view 231 illustrates data set by the manufacturing process alongside 232 conventional configuration. This trust anchors instance has six sets 233 of pinned certificates and one set of pinned host keys. 235 239 240 241 manufacturers-root-ca-certs 242 243 Certificates built into the device for authenticating 244 manufacturer-signed objects, such as TLS server certificates, 245 vouchers, etc. Note, though listed here, these are not 246 configurable; any attempt to do so will be denied. 247 248 249 Manufacturer Root CA cert 1 250 base64encodedvalue== 251 252 253 Manufacturer Root CA cert 2 254 base64encodedvalue== 255 256 258 259 260 explicitly-trusted-server-certs 261 262 Specific server authentication certificates for explicitly 263 trusted servers. These are needed for server certificates 264 that are not signed by a CA. 265 266 267 Fred Flintstone 268 base64encodedvalue== 269 270 272 273 274 explicitly-trusted-server-ca-certs 275 276 Trust anchors (i.e. CA certs) that are used to authenticate 277 server connections. Servers are authenticated if their 278 certificate has a chain of trust to one of these CA 279 certificates. 280 281 282 ca.example.com 283 base64encodedvalue== 284 285 286 287 288 explicitly-trusted-client-certs 289 290 Specific client authentication certificates for explicitly 291 trusted clients. These are needed for client certificates 292 that are not signed by a CA. 293 294 295 George Jetson 296 base64encodedvalue== 297 298 300 301 302 explicitly-trusted-client-ca-certs 303 304 Trust anchors (i.e. CA certs) that are used to authenticate 305 client connections. Clients are authenticated if their 306 certificate has a chain of trust to one of these CA 307 certificates. 308 309 310 ca.example.com 311 base64encodedvalue== 312 313 315 316 317 common-ca-certs 318 319 Trusted certificates to authenticate common HTTPS servers. 320 These certificates are similar to those that might be 321 shipped with a web browser. 322 323 324 ex-certificate-authority 325 base64encodedvalue== 326 327 329 330 331 explicitly-trusted-ssh-host-keys 332 333 Trusted SSH host keys used to authenticate SSH servers. 335 These host keys would be analogous to those stored in 336 a known_hosts file in OpenSSH. 337 338 339 corp-fw1 340 base64encodedvalue== 341 342 344 346 The following example illustrates the "certificate-expiration" 347 notification in use with the NETCONF protocol. 349 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 351 353 2018-05-25T00:01:00Z 354 355 356 explicitly-trusted-client-certs 357 358 George Jetson 359 360 2018-08-05T14:18:53-05:00 362 363 364 365 366 368 2.3. YANG Module 370 This YANG module imports modules from [RFC8341] and 371 [I-D.ietf-netconf-crypto-types]. 373 file "ietf-truststore@2019-11-02.yang" 375 377 3. Security Considerations 379 The YANG module defined in this document is designed to be accessed 380 via YANG based management protocols, such as NETCONF [RFC6241] and 381 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 382 implement secure transport layers (e.g., SSH, TLS) with mutual 383 authentication. 385 The NETCONF access control model (NACM) [RFC8341] provides the means 386 to restrict access for particular users to a pre-configured subset of 387 all available protocol operations and content. 389 There are a number of data nodes defined in this YANG module that are 390 writable/creatable/deletable (i.e., config true, which is the 391 default). These data nodes may be considered sensitive or vulnerable 392 in some network environments. Write operations (e.g., edit-config) 393 to these data nodes without proper protection can have a negative 394 effect on network operations. These are the subtrees and data nodes 395 and their sensitivity/vulnerability: 397 /: The entire data tree defined by this module is sensitive to 398 write operations. For instance, the addition or removal of any 399 trust anchor may dramatically alter the implemented security 400 policy. For this reason, the NACM extension "default-deny- 401 write" has been set for the entire data tree. 403 None of the readable data nodes in this YANG module are considered 404 sensitive or vulnerable in network environments. 406 This module does not define any RPCs, actions, or notifications, and 407 thus the security consideration for such is not provided here. 409 4. IANA Considerations 411 4.1. The IETF XML Registry 413 This document registers one URI in the "ns" subregistry of the IETF 414 XML Registry [RFC3688]. Following the format in [RFC3688], the 415 following registration is requested: 417 URI: urn:ietf:params:xml:ns:yang:ietf-truststore 418 Registrant Contact: The NETCONF WG of the IETF. 419 XML: N/A, the requested URI is an XML namespace. 421 4.2. The YANG Module Names Registry 423 This document registers one YANG module in the YANG Module Names 424 registry [RFC6020]. Following the format in [RFC6020], the the 425 following registration is requested: 427 name: ietf-truststore 428 namespace: urn:ietf:params:xml:ns:yang:ietf-truststore 429 prefix: ta 430 reference: RFC XXXX 432 5. References 434 5.1. Normative References 436 [I-D.ietf-netconf-crypto-types] 437 Watsen, K. and H. Wang, "Common YANG Data Types for 438 Cryptography", draft-ietf-netconf-crypto-types-11 (work in 439 progress), October 2019. 441 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 442 Requirement Levels", BCP 14, RFC 2119, 443 DOI 10.17487/RFC2119, March 1997, 444 . 446 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 447 RFC 7950, DOI 10.17487/RFC7950, August 2016, 448 . 450 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 451 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 452 May 2017, . 454 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 455 Access Control Model", STD 91, RFC 8341, 456 DOI 10.17487/RFC8341, March 2018, 457 . 459 5.2. Informative References 461 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 462 DOI 10.17487/RFC3688, January 2004, 463 . 465 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 466 the Network Configuration Protocol (NETCONF)", RFC 6020, 467 DOI 10.17487/RFC6020, October 2010, 468 . 470 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 471 and A. Bierman, Ed., "Network Configuration Protocol 472 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 473 . 475 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 476 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 477 . 479 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 480 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 481 . 483 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 484 and R. Wilton, "Network Management Datastore Architecture 485 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 486 . 488 Appendix A. Change Log 490 A.1. 00 to 01 492 o Added features "x509-certificates" and "ssh-host-keys". 494 o Added nacm:default-deny-write to "trust-anchors" container. 496 A.2. 01 to 02 498 o Switched "list pinned-certificate" to use the "trust-anchor-cert- 499 grouping" from crypto-types. Effectively the same definition as 500 before. 502 A.3. 02 to 03 504 o Updated copyright date, boilerplate template, affiliation, folding 505 algorithm, and reformatted the YANG module. 507 A.4. 03 to 04 509 o Added groupings 'local-or-truststore-certs-grouping' and 'local- 510 or-truststore-host-keys-grouping', matching similar definitions in 511 the keystore draft. Note new (and incomplete) "truststore" usage! 513 o Related to above, also added features 'truststore-supported' and 514 'local-trust-anchors-supported'. 516 A.5. 04 to 05 518 o Renamed "trust-anchors" to "truststore" 520 o Removed "pinned." prefix everywhere, to match truststore rename 522 o Moved everything under a top-level 'grouping' to enable use in 523 other contexts. 525 o Renamed feature from 'local-trust-anchors-supported' to 'local- 526 definitions-supported' (same name used in keystore) 528 o Removed the "require-instance false" statement from the "*-ref" 529 typedefs. 531 o Added missing "ssh-host-keys" and "x509-certificates" if-feature 532 statements 534 A.6. 05 to 06 536 o Editorial changes only. 538 A.7. 06 to 07 540 o Added Henk Birkholz as a co-author (thanks Henk!) 542 o Added PSKs and raw public keys to Truststore. 544 Acknowledgements 546 The authors would like to thank for following for lively discussions 547 on list and in the halls (ordered by last name): Martin Bjorklund, 548 Nick Hancock, Balazs Kovacs, Eric Voit, and Liang Xia. 550 Authors' Addresses 552 Kent Watsen 553 Watsen Networks 555 EMail: kent+ietf@watsen.net 557 Henk Birkholz 558 Fraunhofer SIT 560 EMail: henk.birkholz@sit.fraunhofer.de