idnits 2.17.1 draft-ietf-netconf-trust-anchors-09.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 158 has weird spacing: '...-format ide...' == Line 168 has weird spacing: '...-format ide...' == Line 178 has weird spacing: '...-format ide...' == Line 187 has weird spacing: '...on-date yan...' == (7 more instances...) -- The document date (March 8, 2020) is 1507 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-13 Summary: 0 errors (**), 0 flaws (~~), 8 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 8, 2020 5 Expires: September 9, 2020 7 A YANG Data Model for a Truststore 8 draft-ietf-netconf-trust-anchors-09 10 Abstract 12 This document defines a YANG 1.1 data model for configuring global 13 sets of X.509 certificates, SSH host-keys, and raw public keys that 14 can be referenced by other data models for trust. While the SSH 15 host-keys are uniquely for the SSH protocol, certificates, and raw 16 public keys may have multiple uses, including authenticating protocol 17 peers and verifying signatures. 19 Editorial Note (To be removed by RFC Editor) 21 This draft contains many placeholder values that need to be replaced 22 with finalized values at the time of publication. This note 23 summarizes all of the substitutions that are needed. No other RFC 24 Editor instructions are specified elsewhere in this document. 26 Artwork in this document contains shorthand references to drafts in 27 progress. Please apply the following replacements: 29 o "XXXX" --> the assigned RFC value for this draft 31 o "YYYY" --> the assigned RFC value for draft-ietf-netconf-crypto- 32 types 34 Artwork in this document contains placeholder values for the date of 35 publication of this draft. Please apply the following replacement: 37 o "2020-03-08" --> the publication date of this draft 39 The following Appendix section is to be removed prior to publication: 41 o Appendix A. Change Log 43 Status of This Memo 45 This Internet-Draft is submitted in full conformance with the 46 provisions of BCP 78 and BCP 79. 48 Internet-Drafts are working documents of the Internet Engineering 49 Task Force (IETF). Note that other groups may also distribute 50 working documents as Internet-Drafts. The list of current Internet- 51 Drafts is at https://datatracker.ietf.org/drafts/current/. 53 Internet-Drafts are draft documents valid for a maximum of six months 54 and may be updated, replaced, or obsoleted by other documents at any 55 time. It is inappropriate to use Internet-Drafts as reference 56 material or to cite them other than as "work in progress." 58 This Internet-Draft will expire on September 9, 2020. 60 Copyright Notice 62 Copyright (c) 2020 IETF Trust and the persons identified as the 63 document authors. All rights reserved. 65 This document is subject to BCP 78 and the IETF Trust's Legal 66 Provisions Relating to IETF Documents 67 (https://trustee.ietf.org/license-info) in effect on the date of 68 publication of this document. Please review these documents 69 carefully, as they describe your rights and restrictions with respect 70 to this document. Code Components extracted from this document must 71 include Simplified BSD License text as described in Section 4.e of 72 the Trust Legal Provisions and are provided without warranty as 73 described in the Simplified BSD License. 75 Table of Contents 77 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 78 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 79 1.2. Tree Diagram Notation . . . . . . . . . . . . . . . . . . 3 80 2. The Trust Anchors Model . . . . . . . . . . . . . . . . . . . 3 81 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 82 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 6 83 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12 84 3. Support for Built-in Trust Anchors . . . . . . . . . . . . . 24 85 4. Security Considerations . . . . . . . . . . . . . . . . . . . 24 86 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 87 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 25 88 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 25 89 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 90 6.1. Normative References . . . . . . . . . . . . . . . . . . 26 91 6.2. Informative References . . . . . . . . . . . . . . . . . 26 92 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 28 93 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 28 94 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 28 95 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 28 96 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 28 97 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 28 98 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 29 99 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 29 100 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 29 101 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 29 102 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 29 103 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 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, and raw public keys 109 that can be referenced by other data models for trust. While the SSH 110 host-keys are uniquely for the SSH protocol, certificates, and raw 111 public keys may have multiple uses, including authenticating protocol 112 peers and verifying signatures. 114 This document in compliant with Network Management Datastore 115 Architecture (NMDA) [RFC8342]. For instance, trust anchors installed 116 during manufacturing (e.g., for trusted well-known services), are 117 expected to appear in (see Section 3). 119 1.1. Requirements Language 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in BCP 124 14 [RFC2119] [RFC8174] when, and only when, they appear in all 125 capitals, as shown here. 127 1.2. Tree Diagram Notation 129 Tree diagrams used in this document follow the notation defined in 130 [RFC8340]. 132 2. The Trust Anchors Model 134 2.1. Tree Diagram 136 The following tree diagram provides an overview of the "ietf- 137 truststore" module. 139 module: ietf-truststore 140 +--rw truststore 141 +--rw certificate-bags! {x509-certificates}? 142 | +--rw certificate-bag* [name] 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 ssh-public-key-bags! {ssh-public-keys}? 151 | +--rw ssh-public-key-bag* [name] 152 | +--rw name string 153 | +--rw description? string 154 | +--rw ssh-public-key* [name] 155 | +--rw name string 156 | +--rw algorithm 157 | | iasa:asymmetric-algorithm-type 158 | +--rw public-key-format identityref 159 | +--rw public-key binary 160 +--rw raw-public-key-bags! {raw-public-keys}? 161 | +--rw raw-public-key-bag* [name] 162 | +--rw name string 163 | +--rw description? string 164 | +--rw raw-public-key* [name] 165 | +--rw name string 166 | +--rw algorithm 167 | | iasa:asymmetric-algorithm-type 168 | +--rw public-key-format identityref 169 | +--rw public-key binary 170 +--rw public-key-bags! {public-keys}? 171 +--rw public-key-bag* [name] 172 +--rw name string 173 +--rw description? string 174 +--rw public-key* [name] 175 +--rw name string 176 +--rw algorithm 177 | iasa:asymmetric-algorithm-type 178 +--rw public-key-format identityref 179 +--rw public-key binary 181 grouping local-or-truststore-certs-grouping 182 +-- (local-or-truststore) 183 +--:(local) {local-definitions-supported}? 184 | +-- local-definition 185 | +-- cert* trust-anchor-cert-cms 186 | +---n certificate-expiration 187 | +-- expiration-date yang:date-and-time 188 +--:(truststore) {truststore-supported,x509-certificates}? 189 +-- truststore-reference? ts:certificate-bag-ref 190 grouping local-or-truststore-ssh-public-keys-grouping 191 +-- (local-or-truststore) 192 +--:(local) {local-definitions-supported}? 193 | +-- local-definition 194 | +-- ssh-public-key* [name] 195 | +-- name? string 196 | +-- algorithm 197 | | iasa:asymmetric-algorithm-type 198 | +-- public-key-format identityref 199 | +-- public-key binary 200 +--:(truststore) {truststore-supported,ssh-public-keys}? 201 +-- truststore-reference? ts:ssh-public-key-bag-ref 202 grouping local-or-truststore-raw-pub-keys-grouping 203 +-- (local-or-truststore) 204 +--:(local) {local-definitions-supported}? 205 | +-- local-definition 206 | +-- raw-public-key* [name] 207 | +-- name? string 208 | +-- algorithm 209 | | iasa:asymmetric-algorithm-type 210 | +-- public-key-format identityref 211 | +-- public-key binary 212 +--:(truststore) {truststore-supported,raw-public-keys}? 213 +-- truststore-reference? ts:raw-public-key-bag-ref 214 grouping local-or-truststore-public-keys-grouping 215 +-- (local-or-truststore) 216 +--:(local) {local-definitions-supported}? 217 | +-- local-definition 218 | +-- public-key* [name] 219 | +-- name? string 220 | +-- algorithm 221 | | iasa:asymmetric-algorithm-type 222 | +-- public-key-format identityref 223 | +-- public-key binary 224 +--:(truststore) {truststore-supported,public-keys}? 225 +-- truststore-reference? ts:public-key-bag-ref 226 grouping truststore-grouping 227 +-- certificate-bags! {x509-certificates}? 228 | +-- certificate-bag* [name] 229 | +-- name? string 230 | +-- description? string 231 | +-- certificate* [name] 232 | +-- name? string 233 | +-- cert trust-anchor-cert-cms 234 | +---n certificate-expiration 235 | +-- expiration-date yang:date-and-time 236 +-- ssh-public-key-bags! {ssh-public-keys}? 237 | +-- ssh-public-key-bag* [name] 238 | +-- name? string 239 | +-- description? string 240 | +-- ssh-public-key* [name] 241 | +-- name? string 242 | +-- algorithm iasa:asymmetric-algorithm-type 243 | +-- public-key-format identityref 244 | +-- public-key binary 245 +-- raw-public-key-bags! {raw-public-keys}? 246 | +-- raw-public-key-bag* [name] 247 | +-- name? string 248 | +-- description? string 249 | +-- raw-public-key* [name] 250 | +-- name? string 251 | +-- algorithm iasa:asymmetric-algorithm-type 252 | +-- public-key-format identityref 253 | +-- public-key binary 254 +-- public-key-bags! {public-keys}? 255 +-- public-key-bag* [name] 256 +-- name? string 257 +-- description? string 258 +-- public-key* [name] 259 +-- name? string 260 +-- algorithm iasa:asymmetric-algorithm-type 261 +-- public-key-format identityref 262 +-- public-key binary 264 2.2. Example Usage 266 The following example illustrates trust anchors in . 267 Please see Section 3 for an example illustrating built-in values in 268 . 270 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 272 277 278 280 281 282 manufacturers-root-ca-certs 283 284 Certificates built into the device for authenticating 285 manufacturer-signed objects, such as TLS server certificates, 286 vouchers, etc. Note, though listed here, these are not 287 configurable; any attempt to do so will be denied. 289 290 291 Manufacturer Root CA cert 1 292 base64encodedvalue== 293 294 295 Manufacturer Root CA cert 2 296 base64encodedvalue== 297 298 300 301 302 common-ca-certs 303 304 Trust anchors (i.e. CA certs) used to authenticate server 305 certificates. A server certificate is authenticated if its 306 end-entity certificate has a chain of trust to one of these 307 certificates. 308 309 310 Go Daddy Class 2 Certification Authority 311 base64encodedvalue== 312 313 314 VeriSign Universal Root Certification Authority 315 base64encodedvalue== 316 317 319 320 321 trusted-server-ca-certs 322 323 Trust anchors (i.e. CA certs) used to authenticate server 324 certificates. A server certificate is authenticated if its 325 end-entity certificate has a chain of trust to one of these 326 certificates. 327 328 329 Server Cert Issuer #1 330 base64encodedvalue== 331 332 333 Server Cert Issuer #2 334 base64encodedvalue== 335 336 337 338 339 trusted-server-ee-certs 340 341 Specific end-entity certificates used to authenticate server 342 certificates. A server certificate is authenticated if its 343 end-entity certificate is an exact match to one of these 344 certificates. 345 346 347 My Application #1 348 base64encodedvalue== 349 350 351 My Application #2 352 base64encodedvalue== 353 354 356 357 358 trusted-client-ca-certs 359 360 Trust anchors (i.e. CA certs) used to authenticate client 361 certificates. A client certificate is authenticated if its 362 end-entity certificate has a chain of trust to one of these 363 certificates. 364 365 366 Client Identity Issuer #1 367 base64encodedvalue== 368 369 370 Client Identity Issuer #2 371 base64encodedvalue== 372 373 375 376 377 trusted-client-ee-certs 378 379 Specific end-entity certificates used to authenticate client 380 certificates. A client certificate is authenticated if its 381 end-entity certificate is an exact match to one of these 382 certificates. 383 384 385 George Jetson 386 base64encodedvalue== 387 388 389 Fred Flintstone 390 base64encodedvalue== 391 392 393 395 396 398 399 400 trusted-ssh-public-keys 401 402 Specific SSH public keys used to authenticate SSH server 403 public keys. An SSH server public key is authenticated if 404 its public key is an exact match to one of these public keys. 406 This list of SSH public keys is analogous to OpenSSH's 407 "/etc/ssh/ssh_known_hosts" file. 408 409 410 corp-fw1 411 secp256r1 412 ct:ssh-public-key-format 414 base64encodedvalue== 415 416 417 corp-fw2 418 secp256r1 419 ct:ssh-public-key-format 421 base64encodedvalue== 422 423 425 426 427 SSH Public Keys for User A 428 429 SSH public keys used to authenticate a user A's SSH public 430 keys. An SSH public key is authenticated if it is an exact 431 match to one of these public keys. 433 This list of public keys is analogous to OpenSSH's 434 "~A/.ssh/authorized_keys" file. 435 436 437 From Source #1 438 secp256r1 439 ct:ssh-public-key-format 441 base64encodedvalue== 442 443 444 From Source #2 445 secp256r1 446 ct:ssh-public-key-format 448 base64encodedvalue== 449 450 452 453 454 SSH Public Keys for User B 455 456 SSH public keys used to authenticate a user B's SSH public 457 keys. An SSH public key is authenticated if it is an exact 458 match to one of these public keys. 460 This list of public keys is analogous to OpenSSH's 461 "~B/.ssh/authorized_keys" file. 462 463 464 From Source #1 465 secp256r1 466 ct:ssh-public-key-format 468 base64encodedvalue== 469 470 471 From Source #2 472 secp256r1 473 ct:ssh-public-key-format 475 base64encodedvalue== 476 477 479 480 481 Raw Public Keys for Servers 482 483 FIXME... 484 485 486 Raw Public Key #1 487 rsa2048 488 ct:subject-public-key-info-format 490 base64encodedvalue== 491 492 493 Raw Public Key #2 494 rsa2048 495 ct:subject-public-key-info-format 497 base64encodedvalue== 498 499 501 502 503 Raw Public Keys for Clients 504 505 FIXME... 506 507 508 Raw Public Key #1 509 rsa2048 510 ct:subject-public-key-info-format 512 base64encodedvalue== 513 514 515 Raw Public Key #2 516 rsa2048 517 ct:subject-public-key-info-format 519 base64encodedvalue== 520 521 522 523 525 The following example illustrates the "certificate-expiration" 526 notification in use with the NETCONF protocol. 528 ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== 530 532 2018-05-25T00:01:00Z 533 534 535 536 explicitly-trusted-client-certs 537 538 George Jetson 539 540 2018-08-05T14:18:53-05:00 542 543 544 545 546 547 549 2.3. YANG Module 551 This YANG module imports modules from [RFC8341] and 552 [I-D.ietf-netconf-crypto-types]. 554 file "ietf-truststore@2020-03-08.yang" 556 module ietf-truststore { 557 yang-version 1.1; 558 namespace "urn:ietf:params:xml:ns:yang:ietf-truststore"; 559 prefix ts; 561 import ietf-netconf-acm { 562 prefix nacm; 563 reference 564 "RFC 8341: Network Configuration Access Control Model"; 565 } 567 import ietf-crypto-types { 568 prefix ct; 569 reference 570 "RFC YYYY: Common YANG Data Types for Cryptography"; 571 } 573 organization 574 "IETF NETCONF (Network Configuration) Working Group"; 576 contact 577 "WG Web : 578 WG List : 579 Author : Kent Watsen 580 Author : Henk Birkholz "; 582 description 583 "This module defines a truststore to centralize management 584 of trust anchors including X.509 certificates, SSH public 585 keys, raw public keys. 587 Copyright (c) 2019 IETF Trust and the persons identified 588 as authors of the code. All rights reserved. 590 Redistribution and use in source and binary forms, with 591 or without modification, is permitted pursuant to, and 592 subject to the license terms contained in, the Simplified 593 BSD License set forth in Section 4.c of the IETF Trust's 594 Legal Provisions Relating to IETF Documents 595 (https://trustee.ietf.org/license-info). 597 This version of this YANG module is part of RFC XXXX 598 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 599 itself for full legal notices. 601 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 602 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 603 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 604 are to be interpreted as described in BCP 14 (RFC 2119) 605 (RFC 8174) when, and only when, they appear in all 606 capitals, as shown here."; 608 revision 2020-03-08 { 609 description 610 "Initial version"; 611 reference 612 "RFC XXXX: A YANG Data Model for a Truststore"; 613 } 615 /****************/ 616 /* Features */ 617 /****************/ 619 feature truststore-supported { 620 description 621 "The 'truststore-supported' feature indicates that the 622 server supports the truststore (i.e., implements the 623 'ietf-truststore' module)."; 625 } 627 feature local-definitions-supported { 628 description 629 "The 'local-definitions-supported' feature indicates that 630 the server supports locally-defined trust anchors."; 631 } 633 feature x509-certificates { 634 description 635 "The 'x509-certificates' feature indicates that the server 636 implements the /truststore/certificate-bags subtree."; 637 } 639 feature ssh-public-keys { 640 description 641 "The 'ssh-public-keys' feature indicates that the server 642 implements the /truststore/ssh-public-key-bags subtree."; 643 } 645 feature raw-public-keys { 646 description 647 "The 'raw-public-keys' feature indicates that the server 648 implements the /truststore/raw-public-key-bags subtree."; 649 } 651 feature public-keys { 652 description 653 "The 'public-keys' feature indicates that the server 654 implements the /truststore/public-key-bags subtree."; 655 } 657 /****************/ 658 /* Typedefs */ 659 /****************/ 661 typedef certificate-bag-ref { 662 type leafref { 663 path "/ts:truststore/ts:certificate-bags/" 664 + "ts:certificate-bag/ts:name"; 665 } 666 description 667 "This typedef defines a reference to a certificate bag 668 defined in the truststore."; 669 } 671 typedef certificate-ref { 672 type leafref { 673 path "/ts:truststore/certificate-bags/certificate-bag" + 674 "[name = current()/../certificate-bag]/certificate/name"; 675 } 676 description 677 "This typedef define a reference to a specific certificate 678 in a certificate bag defined in the truststore. This 679 typedef requires that there exist a sibling 'leaf' node 680 called 'certificate-bag' that SHOULD have the typedef 681 'certificate-bag-ref'."; 682 } 684 typedef ssh-public-key-bag-ref { 685 type leafref { 686 path "/ts:truststore/ts:ssh-public-key-bags" 687 + "/ts:ssh-public-key-bag/ts:name"; 688 } 689 description 690 "This typedef defines a reference to an SSH public key bag 691 defined in the truststore."; 692 } 694 typedef ssh-public-key-ref { 695 type leafref { 696 path "/ts:truststore/ssh-public-key-bags/ssh-public-key-bag" + 697 "[name = current()/../ssh-public-key-bag]" + 698 "/ssh-public-key/name"; 699 } 700 description 701 "This typedef define a reference to a specific SSH public key 702 in a SSH public key bag defined in the truststore. This 703 typedef requires that there exist a sibling 'leaf' node 704 called 'ssh-public-key-bag' that SHOULD have the typedef 705 'ssh-public-key-bag-ref'."; 706 } 708 typedef raw-public-key-bag-ref { 709 type leafref { 710 path "/ts:truststore/ts:raw-public-key-bags/" 711 + "ts:raw-public-key-bag/ts:name"; 712 } 713 description 714 "This typedef define a reference to a raw public key bag 715 defined in the truststore."; 716 } 718 typedef raw-public-key-ref { 719 type leafref { 720 path "/ts:truststore/raw-public-key-bags/raw-public-key-bag" + 721 "[name = current()/../raw-public-key-bag]/" + 722 "raw-public-key/name"; 723 } 724 description 725 "This typedef define a reference to a specific raw public key 726 in a raw public key bag defined in the truststore. This 727 typedef requires that there exist a sibling 'leaf' node 728 called 'raw-public-key-bag' that SHOULD have the typedef 729 'raw-public-key-bag-ref'."; 730 } 732 typedef public-key-bag-ref { 733 type leafref { 734 path "/ts:truststore/ts:public-key-bags/" 735 + "ts:public-key-bag/ts:name"; 736 } 737 description 738 "This typedef define a reference to a public key bag 739 defined in the truststore."; 740 } 742 typedef public-key-ref { 743 type leafref { 744 path "/ts:truststore/public-key-bags/public-key-bag" + 745 "[name = current()/../public-key-bag]/" + 746 "public-key/name"; 747 } 748 description 749 "This typedef define a reference to a specific public key 750 in a public key bag defined in the truststore. This 751 typedef requires that there exist a sibling 'leaf' node 752 called 'public-key-bag' that SHOULD have the typedef 753 'public-key-bag-ref'."; 754 } 756 /*****************/ 757 /* Groupings */ 758 /*****************/ 760 grouping local-or-truststore-certs-grouping { 761 description 762 "A grouping that allows the certificates to be either 763 configured locally, within the using data model, or be a 764 reference to a certificate bag stored in the truststore."; 765 choice local-or-truststore { 766 mandatory true; 767 case local { 768 if-feature "local-definitions-supported"; 769 container local-definition { 770 description 771 "A container for locally configured trust anchor 772 certificates."; 773 uses ct:trust-anchor-certs-grouping; 774 } 775 } 776 case truststore { 777 if-feature "truststore-supported"; 778 if-feature "x509-certificates"; 779 leaf truststore-reference { 780 type ts:certificate-bag-ref; 781 description 782 "A reference to a certificate bag that exists in the 783 truststore."; 784 } 785 } 786 description 787 "A choice between an inlined definition and a definition 788 that exists in the truststore."; 789 } 790 } 792 grouping local-or-truststore-ssh-public-keys-grouping { 793 description 794 "A grouping that allows the ssh public keys to be either 795 configured locally, within the using data model, or be a 796 reference to a ssh public key bag stored in the truststore."; 797 choice local-or-truststore { 798 mandatory true; 799 case local { 800 if-feature "local-definitions-supported"; 801 container local-definition { 802 description 803 "Container to hold local ssh public key definitions."; 804 list ssh-public-key { 805 key name; 806 min-elements 1; 807 description 808 "A ssh public key."; 809 leaf name { 810 type string; 811 description 812 "An arbitrary name for this ssh public key."; 813 } 814 uses ct:public-key-grouping { 815 refine "public-key-format" { 816 must '. = "ct:ssh-public-key-format"'; 817 } 818 } 819 } 820 } 821 } 822 case truststore { 823 if-feature "truststore-supported"; 824 if-feature "ssh-public-keys"; 825 leaf truststore-reference { 826 type ts:ssh-public-key-bag-ref; 827 description 828 "A reference to a bag of SSH public keys that exist in 829 the truststore."; 830 } 831 } 832 description 833 "A choice between an inlined definition and a definition 834 that exists in the truststore."; 835 } 836 } 838 grouping local-or-truststore-raw-pub-keys-grouping { 839 description 840 "A grouping that allows the raw public keys to be either 841 configured locally, within the using data model, or be a 842 reference to a raw public key bag stored in the truststore."; 843 choice local-or-truststore { 844 mandatory true; 845 case local { 846 if-feature "local-definitions-supported"; 847 container local-definition { 848 description 849 "Container to hold local raw public key definitions."; 850 list raw-public-key { 851 key name; 852 description 853 "A raw public key definition."; 854 leaf name { 855 type string; 856 description 857 "An arbitrary name for this raw public key."; 858 } 859 uses ct:public-key-grouping; 860 } 861 } 862 } 863 case truststore { 864 if-feature "truststore-supported"; 865 if-feature "raw-public-keys"; 866 leaf truststore-reference { 867 type ts:raw-public-key-bag-ref; 868 description 869 "A reference to a bag of raw public keys that exist 870 in the truststore."; 871 } 872 } 873 description 874 "A choice between an inlined definition and a definition 875 that exists in the truststore."; 876 } 877 } 879 grouping local-or-truststore-public-keys-grouping { 880 description 881 "A grouping that allows the public keys to be either 882 configured locally, within the using data model, or be a 883 reference to a public key bag stored in the truststore."; 884 choice local-or-truststore { 885 mandatory true; 886 case local { 887 if-feature "local-definitions-supported"; 888 container local-definition { 889 description 890 "Container to hold local public key definitions."; 891 list public-key { 892 key name; 893 description 894 "A public key definition."; 895 leaf name { 896 type string; 897 description 898 "An arbitrary name for this public key."; 899 } 900 uses ct:public-key-grouping; 901 } 902 } 903 } 904 case truststore { 905 if-feature "truststore-supported"; 906 if-feature "public-keys"; 907 leaf truststore-reference { 908 type ts:public-key-bag-ref; 909 description 910 "A reference to a bag of public keys that exist 911 in the truststore."; 912 } 913 } 914 description 915 "A choice between an inlined definition and a definition 916 that exists in the truststore."; 917 } 918 } 920 grouping truststore-grouping { 921 description 922 "Grouping definition enables use in other contexts. Where 923 used, implementations SHOULD augment new 'case' statements 924 into the local-or-truststore 'choice' statements to supply 925 leafrefs to the model-specific location."; 926 container certificate-bags { 927 if-feature "x509-certificates"; 928 presence 929 "Indicates that certificate bags have been configured."; 930 description 931 "A collection of certificate bags."; 932 list certificate-bag { 933 key "name"; 934 min-elements 1; 935 description 936 "A bag of certificates. Each bag of certificates SHOULD 937 be for a specific purpose. For instance, one bag could 938 be used to authenticate a specific set of servers, while 939 another could be used to authenticate a specific set of 940 clients."; 941 leaf name { 942 type string; 943 description 944 "An arbitrary name for this bag of certificates."; 945 } 946 leaf description { 947 type string; 948 description 949 "A description for this bag of certificates. The 950 intended purpose for the bag SHOULD be described."; 951 } 952 list certificate { 953 key "name"; 954 min-elements 1; 955 description 956 "A trust anchor certificate."; 957 leaf name { 958 type string; 959 description 960 "An arbitrary name for this certificate."; 961 } 962 uses ct:trust-anchor-cert-grouping { 963 refine "cert" { 964 mandatory true; 965 } 966 } 967 } 968 } 969 } 970 container ssh-public-key-bags { 971 if-feature "ssh-public-keys"; 972 presence 973 "Indicates that SSH public keys have been configured."; 974 description 975 "A collection of SSH public key bags."; 976 list ssh-public-key-bag { 977 key "name"; 978 min-elements 1; 979 description 980 "A bag of SSH public keys. Each bag of SSH public keys 981 SHOULD be for a specific purpose. For instance, one 982 bag could be used authenticate a specific set of servers 983 (i.e., host keys), while another bag could be used to 984 authenticate a specific client or set of clients."; 985 leaf name { 986 type string; 987 description 988 "An arbitrary name for this bag of SSH public keys."; 989 } 990 leaf description { 991 type string; 992 description 993 "A description for this bag of SSH public keys. The 994 intended purpose for the bag SHOULD be described."; 995 } 996 list ssh-public-key { 997 key "name"; 998 min-elements 1; 999 description 1000 "An SSH public key."; 1001 leaf name { 1002 type string; 1003 description 1004 "An arbitrary name for this SSH public key."; 1005 } 1006 uses ct:public-key-grouping { 1007 refine "public-key-format" { 1008 must '. = "ct:ssh-public-key-format"'; 1009 } 1010 } 1011 } 1012 } 1013 } 1014 container raw-public-key-bags { 1015 if-feature "raw-public-keys"; 1016 presence 1017 "Indicates that raw public keys have been configured."; 1018 description 1019 "A collection of raw public key bags."; 1020 list raw-public-key-bag { 1021 key "name"; 1022 min-elements 1; 1023 description 1024 "A bag of raw public keys. Each bag of keys SHOULD be for 1025 a specific purpose. For instance, one bag could be used 1026 authenticate a specific set of servers, while another 1027 could be used to authenticate a specific set of clients."; 1028 leaf name { 1029 type string; 1030 description 1031 "An arbitrary name for this bag of raw public keys."; 1032 } 1033 leaf description { 1034 type string; 1035 description 1036 "A description for this bag raw public keys. The 1037 intended purpose for the bag SHOULD be described."; 1038 } 1039 list raw-public-key { 1040 key "name"; 1041 min-elements 1; 1042 description 1043 "A raw public key."; 1044 leaf name { 1045 type string; 1046 description 1047 "An arbitrary name for this raw public key."; 1048 } 1049 uses ct:public-key-grouping { 1050 refine "public-key-format" { 1051 must '. = "ct:subject-public-key-info-format"'; 1052 } 1053 } 1054 //uses ct:public-key-grouping; 1055 } 1056 } 1057 } 1058 container public-key-bags { 1059 if-feature "public-keys"; 1060 presence 1061 "Indicates that public keys have been configured."; 1062 description 1063 "A collection of public key bags."; 1064 list public-key-bag { 1065 key "name"; 1066 min-elements 1; 1067 description 1068 "A bag of public keys. Each bag of keys SHOULD be for 1069 a specific purpose. For instance, one bag could be used 1070 authenticate a specific set of servers, while another 1071 could be used to authenticate a specific set of clients."; 1072 leaf name { 1073 type string; 1074 description 1075 "An arbitrary name for this bag of public keys."; 1076 } 1077 leaf description { 1078 type string; 1079 description 1080 "A description for this bag public keys. The 1081 intended purpose for the bag SHOULD be described."; 1082 } 1083 list public-key { 1084 key "name"; 1085 min-elements 1; 1086 description 1087 "A public key."; 1088 leaf name { 1089 type string; 1090 description 1091 "An arbitrary name for this public key."; 1092 } 1093 uses ct:public-key-grouping; 1094 } 1095 } 1096 } 1097 } 1099 /*********************************/ 1100 /* Protocol accessible nodes */ 1101 /*********************************/ 1102 container truststore { 1103 nacm:default-deny-write; 1104 description 1105 "The truststore contains sets of X.509 certificates, SSH 1106 public keys, and raw public keys."; 1107 uses truststore-grouping; 1108 } 1109 } 1111 1113 3. Support for Built-in Trust Anchors 1115 In some implementations, the operating system a device is running, 1116 may define some built-in trust anchors. For instance, there may be 1117 built-in trust anchors enabling the device to securely connect to 1118 well-known services (e.g., an SZTP [RFC8572] bootstap server) or 1119 trust anchors to connect to arbitrary services using public PKI. 1121 Built-in trust anchors are expected to be set by a vendor-specific 1122 process. Any ability for operators to modify built-in trust anchors 1123 is outside the scope of this docuemnt. 1125 As built-in trust anchors are provided by the system (not 1126 configuration), they are present in . The following 1127 example illustrates bui;t-in trust anchors in . 1129 (FIXME: add illustration with origin="system" here) 1131 In order for the built-in trust anchors to be referenced by 1132 configuration, they must first be copied into as the 1133 example in Section 2.2 illustrates for the built-in trust anchors 1134 above. Note that this strategy is chosen, rather then setting 1135 "require-instance false" for the various leafrefs, as built-in trust 1136 anchors are relatively few in number and hence not worth relaxing the 1137 validation for. 1139 4. Security Considerations 1141 The YANG module defined in this document is designed to be accessed 1142 via YANG based management protocols, such as NETCONF [RFC6241] and 1143 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1144 implement secure transport layers (e.g., SSH, TLS) with mutual 1145 authentication. 1147 The NETCONF access control model (NACM) [RFC8341] provides the means 1148 to restrict access for particular users to a pre-configured subset of 1149 all available protocol operations and content. 1151 There are a number of data nodes defined in this YANG module that are 1152 writable/creatable/deletable (i.e., config true, which is the 1153 default). These data nodes may be considered sensitive or vulnerable 1154 in some network environments. Write operations (e.g., edit-config) 1155 to these data nodes without proper protection can have a negative 1156 effect on network operations. These are the subtrees and data nodes 1157 and their sensitivity/vulnerability: 1159 /: The entire data tree defined by this module is sensitive to 1160 write operations. For instance, the addition or removal of any 1161 trust anchor may dramatically alter the implemented security 1162 policy. For this reason, the NACM extension "default-deny- 1163 write" has been set for the entire data tree. 1165 None of the readable data nodes in this YANG module are considered 1166 sensitive or vulnerable in network environments. 1168 This module does not define any RPCs, actions, or notifications, and 1169 thus the security consideration for such is not provided here. 1171 5. IANA Considerations 1173 5.1. The IETF XML Registry 1175 This document registers one URI in the "ns" subregistry of the IETF 1176 XML Registry [RFC3688]. Following the format in [RFC3688], the 1177 following registration is requested: 1179 URI: urn:ietf:params:xml:ns:yang:ietf-truststore 1180 Registrant Contact: The NETCONF WG of the IETF. 1181 XML: N/A, the requested URI is an XML namespace. 1183 5.2. The YANG Module Names Registry 1185 This document registers one YANG module in the YANG Module Names 1186 registry [RFC6020]. Following the format in [RFC6020], the the 1187 following registration is requested: 1189 name: ietf-truststore 1190 namespace: urn:ietf:params:xml:ns:yang:ietf-truststore 1191 prefix: ta 1192 reference: RFC XXXX 1194 6. References 1196 6.1. Normative References 1198 [I-D.ietf-netconf-crypto-types] 1199 Watsen, K. and H. Wang, "Common YANG Data Types for 1200 Cryptography", draft-ietf-netconf-crypto-types-13 (work in 1201 progress), November 2019. 1203 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1204 Requirement Levels", BCP 14, RFC 2119, 1205 DOI 10.17487/RFC2119, March 1997, 1206 . 1208 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1209 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1210 . 1212 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1213 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1214 May 2017, . 1216 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1217 Access Control Model", STD 91, RFC 8341, 1218 DOI 10.17487/RFC8341, March 2018, 1219 . 1221 6.2. Informative References 1223 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1224 DOI 10.17487/RFC3688, January 2004, 1225 . 1227 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1228 the Network Configuration Protocol (NETCONF)", RFC 6020, 1229 DOI 10.17487/RFC6020, October 2010, 1230 . 1232 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1233 and A. Bierman, Ed., "Network Configuration Protocol 1234 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1235 . 1237 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1238 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1239 . 1241 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1242 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1243 . 1245 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1246 and R. Wilton, "Network Management Datastore Architecture 1247 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1248 . 1250 [RFC8572] Watsen, K., Farrer, I., and M. Abrahamsson, "Secure Zero 1251 Touch Provisioning (SZTP)", RFC 8572, 1252 DOI 10.17487/RFC8572, April 2019, 1253 . 1255 Appendix A. Change Log 1257 A.1. 00 to 01 1259 o Added features "x509-certificates" and "ssh-host-keys". 1261 o Added nacm:default-deny-write to "trust-anchors" container. 1263 A.2. 01 to 02 1265 o Switched "list pinned-certificate" to use the "trust-anchor-cert- 1266 grouping" from crypto-types. Effectively the same definition as 1267 before. 1269 A.3. 02 to 03 1271 o Updated copyright date, boilerplate template, affiliation, folding 1272 algorithm, and reformatted the YANG module. 1274 A.4. 03 to 04 1276 o Added groupings 'local-or-truststore-certs-grouping' and 'local- 1277 or-truststore-host-keys-grouping', matching similar definitions in 1278 the keystore draft. Note new (and incomplete) "truststore" usage! 1280 o Related to above, also added features 'truststore-supported' and 1281 'local-trust-anchors-supported'. 1283 A.5. 04 to 05 1285 o Renamed "trust-anchors" to "truststore" 1287 o Removed "pinned." prefix everywhere, to match truststore rename 1289 o Moved everything under a top-level 'grouping' to enable use in 1290 other contexts. 1292 o Renamed feature from 'local-trust-anchors-supported' to 'local- 1293 definitions-supported' (same name used in keystore) 1295 o Removed the "require-instance false" statement from the "*-ref" 1296 typedefs. 1298 o Added missing "ssh-host-keys" and "x509-certificates" if-feature 1299 statements 1301 A.6. 05 to 06 1303 o Editorial changes only. 1305 A.7. 06 to 07 1307 o Added Henk Birkholz as a co-author (thanks Henk!) 1309 o Added PSKs and raw public keys to Truststore. 1311 A.8. 07 to 08 1313 o Added new "Support for Built-in Trust Anchors" section. 1315 o Removed spurious "uses ct:trust-anchor-certs-grouping" line. 1317 o Removed PSK from model. 1319 A.9. 08 to 09 1321 o Removed remaining PSK references from text. 1323 o Wrapped each top-level list with a container. 1325 o Introduced "bag" term. 1327 o Merged "SSH Public Keys" and "Raw Public Keys" in a single "Public 1328 Keys" bag. Consuming downstream modules (i.e., "ietf-[ssh/tls]- 1329 [client/server]) refinei the "public-key-format" to be either SSH 1330 or TLS specific as needed. 1332 Acknowledgements 1334 The authors especially thank Henk Birkholz for contributing YANG to 1335 the ietf-truststore module supporting raw public keys and PSKs (pre- 1336 shared or pairwise-symmetric keys). While these contributions were 1337 eventually replaced by reusing the existing support for asymmetric 1338 and symmetric trust anchors, respectively, it was only thru Henk's 1339 initiative that the WG was able to come to that result. 1341 The authors additionally thank the following for helping give shape 1342 to this work (ordered by last name): Martin Bjorklund, Nick Hancock, 1343 Balazs Kovacs, Eric Voit, and Liang Xia. 1345 Author's Address 1347 Kent Watsen 1348 Watsen Networks 1350 EMail: kent+ietf@watsen.net