idnits 2.17.1 draft-ietf-netconf-restconf-client-server-22.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 1205 has weird spacing: '...address ine...' -- The document date (10 February 2021) is 1169 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 (-20) exists of draft-ietf-netconf-http-client-server-05 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-20 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-22 == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-18 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-21 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-22 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-13 Summary: 0 errors (**), 0 flaws (~~), 11 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 10 February 2021 5 Expires: 14 August 2021 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-22 10 Abstract 12 This document defines two YANG modules, one module to configure a 13 RESTCONF client and the other module to configure a RESTCONF server. 14 Both modules support the TLS transport protocol with both standard 15 RESTCONF and RESTCONF Call Home connections. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains placeholder values that need to be replaced with 20 finalized values at the time of publication. This note summarizes 21 all of the substitutions that are needed. No other RFC Editor 22 instructions are specified elsewhere in this document. 24 Artwork in this document contains shorthand references to drafts in 25 progress. Please apply the following replacements (note: not all may 26 be present): 28 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 29 types 31 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 32 anchors 34 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 36 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 37 client-server 39 * "EEEE" --> the assigned RFC value for draft-ietf-netconf-ssh- 40 client-server 42 * "FFFF" --> the assigned RFC value for draft-ietf-netconf-tls- 43 client-server 45 * "GGGG" --> the assigned RFC value for draft-ietf-netconf-http- 46 client-server 48 * "HHHH" --> the assigned RFC value for draft-ietf-netconf-netconf- 49 client-server 51 * "IIII" --> the assigned RFC value for this draft 53 Artwork in this document contains placeholder values for the date of 54 publication of this draft. Please apply the following replacement: 56 * "2021-02-10" --> the publication date of this draft 58 The following Appendix section is to be removed prior to publication: 60 * Appendix B. Change Log 62 Status of This Memo 64 This Internet-Draft is submitted in full conformance with the 65 provisions of BCP 78 and BCP 79. 67 Internet-Drafts are working documents of the Internet Engineering 68 Task Force (IETF). Note that other groups may also distribute 69 working documents as Internet-Drafts. The list of current Internet- 70 Drafts is at https://datatracker.ietf.org/drafts/current/. 72 Internet-Drafts are draft documents valid for a maximum of six months 73 and may be updated, replaced, or obsoleted by other documents at any 74 time. It is inappropriate to use Internet-Drafts as reference 75 material or to cite them other than as "work in progress." 77 This Internet-Draft will expire on 14 August 2021. 79 Copyright Notice 81 Copyright (c) 2021 IETF Trust and the persons identified as the 82 document authors. All rights reserved. 84 This document is subject to BCP 78 and the IETF Trust's Legal 85 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 86 license-info) in effect on the date of publication of this document. 87 Please review these documents carefully, as they describe your rights 88 and restrictions with respect to this document. Code Components 89 extracted from this document must include Simplified BSD License text 90 as described in Section 4.e of the Trust Legal Provisions and are 91 provided without warranty as described in the Simplified BSD License. 93 Table of Contents 95 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 96 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 4 97 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 98 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 99 2. The "ietf-restconf-client" Module . . . . . . . . . . . . . . 5 100 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 101 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 10 102 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 14 103 3. The "ietf-restconf-server" Module . . . . . . . . . . . . . . 24 104 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 24 105 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 29 106 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 33 107 4. Security Considerations . . . . . . . . . . . . . . . . . . . 45 108 4.1. The "ietf-restconf-client" YANG Module . . . . . . . . . 45 109 4.2. The "ietf-restconf-server" YANG Module . . . . . . . . . 46 110 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 111 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 46 112 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 47 113 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 114 6.1. Normative References . . . . . . . . . . . . . . . . . . 47 115 6.2. Informative References . . . . . . . . . . . . . . . . . 48 116 Appendix A. Expanded Tree Diagrams . . . . . . . . . . . . . . . 50 117 A.1. Expanded Tree Diagram for 'ietf-restconf-client' . . . . 50 118 A.2. Expanded Tree Diagram for 'ietf-restconf-server' . . . . 50 119 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 50 120 B.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 50 121 B.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 51 122 B.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 51 123 B.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 51 124 B.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 51 125 B.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 51 126 B.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 52 127 B.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 52 128 B.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 52 129 B.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 52 130 B.11. 10 to 11 . . . . . . . . . . . . . . . . . . . . . . . . 52 131 B.12. 11 to 12 . . . . . . . . . . . . . . . . . . . . . . . . 53 132 B.13. 12 to 13 . . . . . . . . . . . . . . . . . . . . . . . . 53 133 B.14. 13 to 14 . . . . . . . . . . . . . . . . . . . . . . . . 53 134 B.15. 14 to 15 . . . . . . . . . . . . . . . . . . . . . . . . 54 135 B.16. 15 to 16 . . . . . . . . . . . . . . . . . . . . . . . . 54 136 B.17. 16 to 17 . . . . . . . . . . . . . . . . . . . . . . . . 54 137 B.18. 17 to 18 . . . . . . . . . . . . . . . . . . . . . . . . 54 138 B.19. 18 to 19 . . . . . . . . . . . . . . . . . . . . . . . . 54 139 B.20. 19 to 20 . . . . . . . . . . . . . . . . . . . . . . . . 54 140 B.21. 20 to 21 . . . . . . . . . . . . . . . . . . . . . . . . 55 141 B.22. 21 to 22 . . . . . . . . . . . . . . . . . . . . . . . . 55 142 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 55 143 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 55 145 1. Introduction 147 This document defines two YANG [RFC7950] modules, one module to 148 configure a RESTCONF client and the other module to configure a 149 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446] 150 transport protocol with both standard RESTCONF and RESTCONF Call Home 151 connections [RFC8071]. 153 1.1. Relation to other RFCs 155 This document presents one or more YANG modules [RFC7950] that are 156 part of a collection of RFCs that work together to, ultimately, 157 enable the configuration of the clients and servers of both the 158 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 160 The modules have been defined in a modular fashion to enable their 161 use by other efforts, some of which are known to be in progress at 162 the time of this writing, with many more expected to be defined in 163 time. 165 The normative dependency relationship between the various RFCs in the 166 collection is presented in the below diagram. The labels in the 167 diagram represent the primary purpose provided by each RFC. 168 Hyperlinks to each RFC are provided below the diagram. 170 crypto-types 171 ^ ^ 172 / \ 173 / \ 174 truststore keystore 175 ^ ^ ^ ^ 176 | +---------+ | | 177 | | | | 178 | +------------+ | 179 tcp-client-server | / | | 180 ^ ^ ssh-client-server | | 181 | | ^ tls-client-server 182 | | | ^ ^ http-client-server 183 | | | | | ^ 184 | | | +-----+ +---------+ | 185 | | | | | | 186 | +-----------|--------|--------------+ | | 187 | | | | | | 188 +-----------+ | | | | | 189 | | | | | | 190 | | | | | | 191 netconf-client-server restconf-client-server 193 +=======================+===========================================+ 194 |Label in Diagram | Originating RFC | 195 +=======================+===========================================+ 196 |crypto-types | [I-D.ietf-netconf-crypto-types] | 197 +-----------------------+-------------------------------------------+ 198 |truststore | [I-D.ietf-netconf-trust-anchors] | 199 +-----------------------+-------------------------------------------+ 200 |keystore | [I-D.ietf-netconf-keystore] | 201 +-----------------------+-------------------------------------------+ 202 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 203 +-----------------------+-------------------------------------------+ 204 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 205 +-----------------------+-------------------------------------------+ 206 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 207 +-----------------------+-------------------------------------------+ 208 |http-client-server | [I-D.ietf-netconf-http-client-server] | 209 +-----------------------+-------------------------------------------+ 210 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 211 +-----------------------+-------------------------------------------+ 212 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 213 +-----------------------+-------------------------------------------+ 215 Table 1: Label to RFC Mapping 217 1.2. Specification Language 219 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 220 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 221 "OPTIONAL" in this document are to be interpreted as described in BCP 222 14 [RFC2119] [RFC8174] when, and only when, they appear in all 223 capitals, as shown here. 225 1.3. Adherence to the NMDA 227 This document in compliant with the Network Management Datastore 228 Architecture (NMDA) [RFC8342]. For instance, as described in 229 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 230 trust anchors and keys installed during manufacturing are expected to 231 appear in . 233 2. The "ietf-restconf-client" Module 235 The RESTCONF client model presented in this section supports both 236 clients initiating connections to servers, as well as clients 237 listening for connections from servers calling home. 239 YANG feature statements are used to enable implementations to 240 advertise which potentially uncommon parts of the model the RESTCONF 241 client supports. 243 2.1. Data Model Overview 245 This section provides an overview of the "ietf-restconf-client" 246 module in terms of its features and groupings. 248 2.1.1. Features 250 The following diagram lists all the "feature" statements defined in 251 the "ietf-restconf-client" module: 253 Features: 254 +-- https-initiate 255 +-- http-listen 256 +-- https-listen 258 | The diagram above uses syntax that is similar to but not 259 | defined in [RFC8340]. 261 2.1.2. Groupings 263 The "ietf-restconf-client" module defines the following "grouping" 264 statements: 266 * restconf-client-grouping 267 * restconf-client-initiate-stack-grouping 268 * restconf-client-listen-stack-grouping 269 * restconf-client-app-grouping 271 Each of these groupings are presented in the following subsections. 273 2.1.2.1. The "restconf-client-grouping" Grouping 275 The following tree diagram [RFC8340] illustrates the "restconf- 276 client-grouping" grouping: 278 grouping restconf-client-grouping ---> 280 Comments: 282 * This grouping does not define any nodes, but is maintained so that 283 downstream modules can augment nodes into it if needed. 285 * The "restconf-client-grouping" defines, if it can be called that, 286 the configuration for just "RESTCONF" part of a protocol stack. 287 It does not, for instance, define any configuration for the "TCP", 288 "TLS", or "HTTP" protocol layers (for that, see Section 2.1.2.2 289 and Section 2.1.2.3). 291 2.1.2.2. The "restconf-client-initiate-stack-grouping" Grouping 293 The following tree diagram [RFC8340] illustrates the "restconf- 294 client-initiate-stack-grouping" grouping: 296 grouping restconf-client-initiate-stack-grouping 297 +-- (transport) 298 +--:(https) {https-initiate}? 299 +-- https 300 +-- tcp-client-parameters 301 | +---u tcpc:tcp-client-grouping 302 +-- tls-client-parameters 303 | +---u tlsc:tls-client-grouping 304 +-- http-client-parameters 305 | +---u httpc:http-client-grouping 306 +-- restconf-client-parameters 307 +---u rcc:restconf-client-grouping 309 Comments: 311 * The "restconf-client-initiate-stack-grouping" defines the 312 configuration for a full RESTCONF protocol stack, for RESTCONF 313 clients that initiate connections to RESTCONF servers, as opposed 314 to receiving call-home [RFC8071] connections. 316 * The "transport" choice node enables transport options to be 317 configured. This document only defines an "https" option, but 318 other options MAY be augmented in. 320 * For the referenced grouping statement(s): 322 - The "tcp-client-grouping" grouping is discussed in 323 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 324 - The "tls-client-grouping" grouping is discussed in 325 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 326 - The "http-client-grouping" grouping is discussed in 327 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 328 - The "restconf-client-grouping" grouping is discussed in 329 Section 2.1.2.1 in this document. 331 2.1.2.3. The "restconf-client-listen-stack-grouping" Grouping 333 The following tree diagram [RFC8340] illustrates the "restconf- 334 client-listen-stack-grouping" grouping: 336 grouping restconf-client-listen-stack-grouping 337 +-- (transport) 338 +--:(http) {http-listen}? 339 | +-- http 340 | +-- tcp-server-parameters 341 | | +---u tcps:tcp-server-grouping 342 | +-- http-client-parameters 343 | | +---u httpc:http-client-grouping 344 | +-- restconf-client-parameters 345 | +---u rcc:restconf-client-grouping 346 +--:(https) {https-listen}? 347 +-- https 348 +-- tcp-server-parameters 349 | +---u tcps:tcp-server-grouping 350 +-- tls-client-parameters 351 | +---u tlsc:tls-client-grouping 352 +-- http-client-parameters 353 | +---u httpc:http-client-grouping 354 +-- restconf-client-parameters 355 +---u rcc:restconf-client-grouping 357 Comments: 359 * The "restconf-client-listen-stack-grouping" defines the 360 configuration for a full RESTCONF protocol stack, for RESTCONF 361 clients that receive call-home [RFC8071] connections from RESTCONF 362 servers. 364 * The "transport" choice node enables both the HTTP and HTTPS 365 transports to be configured, with each option enabled by a 366 "feature" statement. Note that RESTCONF requires HTTPS, the HTTP 367 option is provided to support cases where a TLS-terminator is 368 deployed in front of the RESTCONF-client. 370 * For the referenced grouping statement(s): 372 - The "tcp-server-grouping" grouping is discussed in 373 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 374 - The "tls-client-grouping" grouping is discussed in 375 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 376 - The "http-client-grouping" grouping is discussed in 377 Section 2.1.2.2 of [I-D.ietf-netconf-http-client-server]. 379 - The "restconf-client-grouping" grouping is discussed in 380 Section 2.1.2.1 in this document. 382 2.1.2.4. The "restconf-client-app-grouping" Grouping 384 The following tree diagram [RFC8340] illustrates the "restconf- 385 client-app-grouping" grouping: 387 grouping restconf-client-app-grouping 388 +-- initiate! {https-initiate}? 389 | +-- restconf-server* [name] 390 | +-- name? string 391 | +-- endpoints 392 | | +-- endpoint* [name] 393 | | +-- name? string 394 | | +---u restconf-client-initiate-stack-grouping 395 | +-- connection-type 396 | | +-- (connection-type) 397 | | +--:(persistent-connection) 398 | | | +-- persistent! 399 | | +--:(periodic-connection) 400 | | +-- periodic! 401 | | +-- period? uint16 402 | | +-- anchor-time? yang:date-and-time 403 | | +-- idle-timeout? uint16 404 | +-- reconnect-strategy 405 | +-- start-with? enumeration 406 | +-- max-attempts? uint8 407 +-- listen! {http-listen or https-listen}? 408 +-- idle-timeout? uint16 409 +-- endpoint* [name] 410 +-- name? string 411 +---u restconf-client-listen-stack-grouping 413 Comments: 415 * The "restconf-client-app-grouping" defines the configuration for a 416 RESTCONF client that supports both initiating connections to 417 RESTCONF servers as well as receiving call-home connections from 418 RESTCONF servers. 420 * Both the "initiate" and "listen" subtrees must be enabled by 421 "feature" statements. 423 * For the referenced grouping statement(s): 425 - The "restconf-client-initiate-stack-grouping" grouping is 426 discussed in Section 2.1.2.2 in this document. 428 - The "restconf-client-listen-stack-grouping" grouping is 429 discussed in Section 2.1.2.3 in this document. 431 2.1.3. Protocol-accessible Nodes 433 The following tree diagram [RFC8340] lists all the protocol- 434 accessible nodes defined in the "ietf-restconf-client" module: 436 module: ietf-restconf-client 437 +--rw restconf-client 438 +---u restconf-client-app-grouping 440 Comments: 442 * Protocol-accessible nodes are those nodes that are accessible when 443 the module is "implemented", as described in Section 5.6.5 of 444 [RFC7950]. 446 * For the "ietf-restconf-client" module, the protocol-accessible 447 nodes are an instance of the "restconf-client-app-grouping" 448 discussed in Section 2.1.2.4 grouping. 450 * The reason for why "restconf-client-app-grouping" exists separate 451 from the protocol-accessible nodes definition is so as to enable 452 instances of restconf-client-app-grouping to be instantiated in 453 other locations, as may be needed or desired by some modules. 455 2.2. Example Usage 457 The following example illustrates configuring a RESTCONF client to 458 initiate connections, as well as to listen for call-home connections. 460 This example is consistent with the examples presented in Section 2.2 461 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 462 [I-D.ietf-netconf-keystore]. 464 =============== NOTE: '\' line wrapping per RFC 8792 ================ 466 470 471 472 473 corp-fw1 474 475 476 corp-fw1.example.com 477 478 479 corp-fw1.example.com 480 481 15 482 3 483 30 484 485 486 487 488 489 490 rsa-asymmetric-key 492 ex-rsa-cert 493 494 495 496 497 498 trusted-server-ca-certs 500 501 502 trusted-server-ee-certs 504 505 506 507 508 30 509 3 510 511 512 513 514 515 516 bob 517 secret 518 519 520 521 522 523 524 corp-fw2.example.com 525 526 527 corp-fw2.example.com 528 529 15 530 3 531 30 532 533 534 535 536 537 538 rsa-asymmetric-key 540 ex-rsa-cert 541 542 543 544 545 546 trusted-server-ca-certs 548 549 550 trusted-server-ee-certs 552 553 554 555 556 30 557 3 558 559 560 561 562 563 564 bob 565 secret 566 567 568 569 570 571 572 573 574 575 576 578 579 580 581 Intranet-facing listener 582 583 584 11.22.33.44 585 586 587 588 589 590 rsa-asymmetric-key 591 ex-rsa-cert 592 593 594 595 596 597 trusted-server-ca-certs 599 600 601 trusted-server-ee-certs 603 604 605 606 607 608 609 610 611 612 bob 613 secret 614 615 616 617 618 619 621 623 2.3. YANG Module 625 This YANG module has normative references to [RFC6991], [RFC8040], 626 and [RFC8071], [I-D.ietf-netconf-tcp-client-server], 627 [I-D.ietf-netconf-tls-client-server], and 628 [I-D.ietf-netconf-http-client-server]. 630 file "ietf-restconf-client@2021-02-10.yang" 632 module ietf-restconf-client { 633 yang-version 1.1; 634 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 635 prefix rcc; 637 import ietf-yang-types { 638 prefix yang; 639 reference 640 "RFC 6991: Common YANG Data Types"; 641 } 643 import ietf-tcp-client { 644 prefix tcpc; 645 reference 646 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 647 } 649 import ietf-tcp-server { 650 prefix tcps; 651 reference 652 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 653 } 655 import ietf-tls-client { 656 prefix tlsc; 657 reference 658 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 659 } 661 import ietf-http-client { 662 prefix httpc; 663 reference 664 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 665 } 667 organization 668 "IETF NETCONF (Network Configuration) Working Group"; 670 contact 671 "WG Web: 672 WG List: 673 Author: Kent Watsen 674 Author: Gary Wu "; 676 description 677 "This module contains a collection of YANG definitions 678 for configuring RESTCONF clients. 680 Copyright (c) 2020 IETF Trust and the persons identified 681 as authors of the code. All rights reserved. 683 Redistribution and use in source and binary forms, with 684 or without modification, is permitted pursuant to, and 685 subject to the license terms contained in, the Simplified 686 BSD License set forth in Section 4.c of the IETF Trust's 687 Legal Provisions Relating to IETF Documents 688 (https://trustee.ietf.org/license-info). 690 This version of this YANG module is part of RFC IIII 691 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 692 itself for full legal notices. 694 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 695 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 696 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 697 are to be interpreted as described in BCP 14 (RFC 2119) 698 (RFC 8174) when, and only when, they appear in all 699 capitals, as shown here."; 701 revision 2021-02-10 { 702 description 703 "Initial version"; 704 reference 705 "RFC IIII: RESTCONF Client and Server Models"; 706 } 708 // Features 710 feature https-initiate { 711 description 712 "The 'https-initiate' feature indicates that the RESTCONF 713 client supports initiating HTTPS connections to RESTCONF 714 servers. This feature exists as HTTPS might not be a 715 mandatory to implement transport in the future."; 716 reference 717 "RFC 8040: RESTCONF Protocol"; 719 } 721 feature http-listen { 722 description 723 "The 'https-listen' feature indicates that the RESTCONF client 724 supports opening a port to listen for incoming RESTCONF 725 server call-home connections. This feature exists as not 726 all RESTCONF clients may support RESTCONF call home."; 727 reference 728 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 729 } 731 feature https-listen { 732 description 733 "The 'https-listen' feature indicates that the RESTCONF client 734 supports opening a port to listen for incoming RESTCONF 735 server call-home connections. This feature exists as not 736 all RESTCONF clients may support RESTCONF call home."; 737 reference 738 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 739 } 741 // Groupings 743 grouping restconf-client-grouping { 744 description 745 "A reusable grouping for configuring a RESTCONF client 746 without any consideration for how underlying transport 747 sessions are established. 749 This grouping currently doesn't define any nodes."; 750 } 752 grouping restconf-client-initiate-stack-grouping { 753 description 754 "A reusable grouping for configuring a RESTCONF client 755 'initiate' protocol stack for a single connection."; 757 choice transport { 758 mandatory true; 759 description 760 "Selects between available transports. This is a 761 'choice' statement so as to support additional 762 transport options to be augmented in."; 763 case https { 764 if-feature "https-initiate"; 765 container https { 766 must 'tls-client-parameters/client-identity 767 or http-client-parameters/client-identity'; 768 description 769 "Specifies HTTPS-specific transport 770 configuration."; 771 container tcp-client-parameters { 772 description 773 "A wrapper around the TCP client parameters 774 to avoid name collisions."; 775 uses tcpc:tcp-client-grouping { 776 refine "remote-port" { 777 default "443"; 778 description 779 "The RESTCONF client will attempt to 780 connect to the IANA-assigned well-known 781 port value for 'https' (443) if no value 782 is specified."; 783 } 784 } 785 } 786 container tls-client-parameters { 787 description 788 "A wrapper around the TLS client parameters 789 to avoid name collisions."; 790 uses tlsc:tls-client-grouping; 791 } 792 container http-client-parameters { 793 description 794 "A wrapper around the HTTP client parameters 795 to avoid name collisions."; 796 uses httpc:http-client-grouping; 797 } 798 container restconf-client-parameters { 799 description 800 "A wrapper around the HTTP client parameters 801 to avoid name collisions."; 802 uses rcc:restconf-client-grouping; 803 } 804 } 805 } 806 } 807 } // restconf-client-initiate-stack-grouping 809 grouping restconf-client-listen-stack-grouping { 810 description 811 "A reusable grouping for configuring a RESTCONF client 812 'listen' protocol stack for a single connection. The 813 'listen' stack supports call home connections, as 814 described in RFC 8071"; 816 reference 817 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 818 choice transport { 819 mandatory true; 820 description 821 "Selects between available transports. This is a 822 'choice' statement so as to support additional 823 transport options to be augmented in."; 824 case http { 825 if-feature "http-listen"; 826 container http { 827 description 828 "HTTP-specific listening configuration for inbound 829 connections. 831 This transport option is made available to support 832 deployments where the TLS connections are terminated 833 by another system (e.g., a load balanacer) fronting 834 the client."; 835 container tcp-server-parameters { 836 description 837 "A wrapper around the TCP client parameters 838 to avoid name collisions."; 839 uses tcps:tcp-server-grouping { 840 refine "local-port" { 841 default "4336"; 842 description 843 "The RESTCONF client will listen on the IANA- 844 assigned well-known port for 'restconf-ch-tls' 845 (4336) if no value is specified."; 846 } 847 } 848 } 849 container http-client-parameters { 850 description 851 "A wrapper around the HTTP client parameters 852 to avoid name collisions."; 853 uses httpc:http-client-grouping; 854 } 855 container restconf-client-parameters { 856 description 857 "A wrapper around the RESTCONF client parameters 858 to avoid name collisions."; 859 uses rcc:restconf-client-grouping; 860 } 861 } 862 } 863 case https { 864 if-feature "https-listen"; 865 container https { 866 must 'tls-client-parameters/client-identity 867 or http-client-parameters/client-identity'; 868 description 869 "HTTPS-specific listening configuration for inbound 870 connections."; 871 container tcp-server-parameters { 872 description 873 "A wrapper around the TCP client parameters 874 to avoid name collisions."; 875 uses tcps:tcp-server-grouping { 876 refine "local-port" { 877 default "4336"; 878 description 879 "The RESTCONF client will listen on the IANA- 880 assigned well-known port for 'restconf-ch-tls' 881 (4336) if no value is specified."; 882 } 883 } 884 } 885 container tls-client-parameters { 886 description 887 "A wrapper around the TLS client parameters 888 to avoid name collisions."; 889 uses tlsc:tls-client-grouping; 890 } 891 container http-client-parameters { 892 description 893 "A wrapper around the HTTP client parameters 894 to avoid name collisions."; 895 uses httpc:http-client-grouping; 896 } 897 container restconf-client-parameters { 898 description 899 "A wrapper around the RESTCONF client parameters 900 to avoid name collisions."; 901 uses rcc:restconf-client-grouping; 902 } 903 } 904 } 905 } 906 } // restconf-client-listen-stack-grouping 908 grouping restconf-client-app-grouping { 909 description 910 "A reusable grouping for configuring a RESTCONF client 911 application that supports both 'initiate' and 'listen' 912 protocol stacks for a multiplicity of connections."; 913 container initiate { 914 if-feature "https-initiate"; 915 presence "Enables client to initiate TCP connections"; 916 description 917 "Configures client initiating underlying TCP connections."; 918 list restconf-server { 919 key "name"; 920 min-elements 1; 921 description 922 "List of RESTCONF servers the RESTCONF client is to 923 maintain simultaneous connections with."; 924 leaf name { 925 type string; 926 description 927 "An arbitrary name for the RESTCONF server."; 928 } 929 container endpoints { 930 description 931 "Container for the list of endpoints."; 932 list endpoint { 933 key "name"; 934 min-elements 1; 935 ordered-by user; 936 description 937 "A non-empty user-ordered list of endpoints for this 938 RESTCONF client to try to connect to in sequence. 939 Defining more than one enables high-availability."; 940 leaf name { 941 type string; 942 description 943 "An arbitrary name for this endpoint."; 944 } 945 uses restconf-client-initiate-stack-grouping; 946 } 947 } 948 container connection-type { 949 description 950 "Indicates the RESTCONF client's preference for how 951 the RESTCONF connection is maintained."; 952 choice connection-type { 953 mandatory true; 954 description 955 "Selects between available connection types."; 956 case persistent-connection { 957 container persistent { 958 presence "Indicates that a persistent connection 959 is to be maintained."; 961 description 962 "Maintain a persistent connection to the 963 RESTCONF server. If the connection goes down, 964 immediately start trying to reconnect to the 965 RESTCONF server, using the reconnection strategy. 967 This connection type minimizes any RESTCONF server 968 to RESTCONF client data-transfer delay, albeit 969 at the expense of holding resources longer."; 970 } 971 } 972 case periodic-connection { 973 container periodic { 974 presence "Indicates that a periodic connection is 975 to be maintained."; 976 description 977 "Periodically connect to the RESTCONF server. 979 This connection type increases resource 980 utilization, albeit with increased delay 981 in RESTCONF server to RESTCONF client 982 interactions. 984 The RESTCONF client SHOULD gracefully close 985 the underlying TLS connection upon completing 986 planned activities. 988 In the case that the previous connection is 989 still active, establishing a new connection 990 is NOT RECOMMENDED."; 991 leaf period { 992 type uint16; 993 units "minutes"; 994 default "60"; 995 description 996 "Duration of time between periodic 997 connections."; 998 } 999 leaf anchor-time { 1000 type yang:date-and-time { 1001 // constrained to minute-level granularity 1002 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1003 + '(Z|[\+\-]\d{2}:\d{2})'; 1004 } 1005 description 1006 "Designates a timestamp before or after which 1007 a series of periodic connections are 1008 determined. The periodic connections occur 1009 at a whole multiple interval from the anchor 1010 time. For example, for an anchor time is 15 1011 minutes past midnight and a period interval 1012 of 24 hours, then a periodic connection will 1013 occur 15 minutes past midnight everyday."; 1014 } 1015 leaf idle-timeout { 1016 type uint16; 1017 units "seconds"; 1018 default 120; // two minutes 1019 description 1020 "Specifies the maximum number of seconds 1021 that the underlying TCP session may remain 1022 idle. A TCP session will be dropped if it 1023 is idle for an interval longer than this 1024 number of seconds If set to zero, then the 1025 RESTCONF client will never drop a session 1026 because it is idle."; 1027 } 1028 } 1029 } // periodic-connection 1030 } // connection-type 1031 } // connection-type 1032 container reconnect-strategy { 1033 description 1034 "The reconnection strategy directs how a RESTCONF 1035 client reconnects to a RESTCONF server, after 1036 discovering its connection to the server has 1037 dropped, even if due to a reboot. The RESTCONF 1038 client starts with the specified endpoint and 1039 tries to connect to it max-attempts times before 1040 trying the next endpoint in the list (round 1041 robin)."; 1042 leaf start-with { 1043 type enumeration { 1044 enum first-listed { 1045 description 1046 "Indicates that reconnections should start 1047 with the first endpoint listed."; 1048 } 1049 enum last-connected { 1050 description 1051 "Indicates that reconnections should start 1052 with the endpoint last connected to. If 1053 no previous connection has ever been 1054 established, then the first endpoint 1055 configured is used. RESTCONF clients 1056 SHOULD be able to remember the last 1057 endpoint connected to across reboots."; 1058 } 1059 enum random-selection { 1060 description 1061 "Indicates that reconnections should start with 1062 a random endpoint."; 1063 } 1064 } 1065 default "first-listed"; 1066 description 1067 "Specifies which of the RESTCONF server's 1068 endpoints the RESTCONF client should start 1069 with when trying to connect to the RESTCONF 1070 server."; 1071 } 1072 leaf max-attempts { 1073 type uint8 { 1074 range "1..max"; 1075 } 1076 default "3"; 1077 description 1078 "Specifies the number times the RESTCONF client 1079 tries to connect to a specific endpoint before 1080 moving on to the next endpoint in the list 1081 (round robin)."; 1082 } 1083 } 1084 } 1085 } // initiate 1086 container listen { 1087 if-feature "http-listen or https-listen"; 1088 presence "Enables client to accept call-home connections"; 1089 description 1090 "Configures the client to accept call-home TCP connections."; 1091 leaf idle-timeout { 1092 type uint16; 1093 units "seconds"; 1094 default 3600; // one hour 1095 description 1096 "Specifies the maximum number of seconds that an 1097 underlying TCP session may remain idle. A TCP session 1098 will be dropped if it is idle for an interval longer 1099 then this number of seconds. If set to zero, then 1100 the server will never drop a session because it is 1101 idle. Sessions that have a notification subscription 1102 active are never dropped."; 1103 } 1104 list endpoint { 1105 key "name"; 1106 min-elements 1; 1107 description 1108 "List of endpoints to listen for RESTCONF connections."; 1109 leaf name { 1110 type string; 1111 description 1112 "An arbitrary name for the RESTCONF listen endpoint."; 1113 } 1114 uses restconf-client-listen-stack-grouping; 1115 } 1116 } 1117 } // restconf-client-app-grouping 1119 // Protocol accessible node, for servers that implement 1120 // this module. 1121 container restconf-client { 1122 uses restconf-client-app-grouping; 1123 description 1124 "Top-level container for RESTCONF client configuration."; 1125 } 1126 } 1128 1130 3. The "ietf-restconf-server" Module 1132 The RESTCONF server model presented in this section supports both 1133 listening for connections as well as initiating call-home 1134 connections. 1136 YANG feature statements are used to enable implementations to 1137 advertise which potentially uncommon parts of the model the RESTCONF 1138 server supports. 1140 3.1. Data Model Overview 1142 This section provides an overview of the "ietf-restconf-server" 1143 module in terms of its features and groupings. 1145 3.1.1. Features 1147 The following diagram lists all the "feature" statements defined in 1148 the "ietf-restconf-server" module: 1150 Features: 1151 +-- http-listen 1152 +-- https-listen 1153 +-- https-call-home 1155 | The diagram above uses syntax that is similar to but not 1156 | defined in [RFC8340]. 1158 3.1.2. Groupings 1160 The "ietf-restconf-server" module defines the following "grouping" 1161 statements: 1163 * restconf-server-grouping 1164 * restconf-server-listen-stack-grouping 1165 * restconf-server-callhome-stack-grouping 1166 * restconf-server-app-grouping 1168 Each of these groupings are presented in the following subsections. 1170 3.1.2.1. The "restconf-server-grouping" Grouping 1172 The following tree diagram [RFC8340] illustrates the "restconf- 1173 server-grouping" grouping: 1175 grouping restconf-server-grouping 1176 +-- client-identity-mappings 1177 +---u x509c2n:cert-to-name 1179 Comments: 1181 * The "restconf-server-grouping" defines the configuration for just 1182 "RESTCONF" part of a protocol stack. It does not, for instance, 1183 define any configuration for the "TCP", "TLS", or "HTTP" protocol 1184 layers (for that, see Section 3.1.2.2 and Section 3.1.2.3). 1186 * The "client-identity-mappings" node, which must be enabled by 1187 "feature" statements, defines a mapping from certificate fields to 1188 RESTCONF user names. 1190 * For the referenced grouping statement(s): 1192 - The "cert-to-name" grouping is discussed in Section 4.1 of 1193 [RFC7407]. 1195 3.1.2.2. The "restconf-server-listen-stack-grouping" Grouping 1197 The following tree diagram [RFC8340] illustrates the "restconf- 1198 server-listen-stack-grouping" grouping: 1200 grouping restconf-server-listen-stack-grouping 1201 +-- (transport) 1202 +--:(http) {http-listen}? 1203 | +-- http 1204 | +-- external-endpoint! 1205 | | +-- address inet:ip-address 1206 | | +-- port? inet:port-number 1207 | +-- tcp-server-parameters 1208 | | +---u tcps:tcp-server-grouping 1209 | +-- http-server-parameters 1210 | | +---u https:http-server-grouping 1211 | +-- restconf-server-parameters 1212 | +---u rcs:restconf-server-grouping 1213 +--:(https) {https-listen}? 1214 +-- https 1215 +-- tcp-server-parameters 1216 | +---u tcps:tcp-server-grouping 1217 +-- tls-server-parameters 1218 | +---u tlss:tls-server-grouping 1219 +-- http-server-parameters 1220 | +---u https:http-server-grouping 1221 +-- restconf-server-parameters 1222 +---u rcs:restconf-server-grouping 1224 Comments: 1226 * The "restconf-server-listen-stack-grouping" defines the 1227 configuration for a full RESTCONF protocol stack for RESTCONF 1228 servers that listen for standard connections from RESTCONF 1229 clients, as opposed to initiating call-home [RFC8071] connections. 1231 * The "transport" choice node enables both the HTTP and HTTPS 1232 transports to be configured, with each option enabled by a 1233 "feature" statement. The HTTP option is provided to support cases 1234 where a TLS-terminator is deployed in front of the RESTCONF- 1235 server. 1237 * For the referenced grouping statement(s): 1239 - The "tcp-server-grouping" grouping is discussed in 1240 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1241 - The "tls-server-grouping" grouping is discussed in 1242 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1244 - The "http-server-grouping" grouping is discussed in 1245 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1246 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1247 of this document. 1249 3.1.2.3. The "restconf-server-callhome-stack-grouping" Grouping 1251 The following tree diagram [RFC8340] illustrates the "restconf- 1252 server-callhome-stack-grouping" grouping: 1254 grouping restconf-server-callhome-stack-grouping 1255 +-- (transport) 1256 +--:(https) {https-listen}? 1257 +-- https 1258 +-- tcp-client-parameters 1259 | +---u tcpc:tcp-client-grouping 1260 +-- tls-server-parameters 1261 | +---u tlss:tls-server-grouping 1262 +-- http-server-parameters 1263 | +---u https:http-server-grouping 1264 +-- restconf-server-parameters 1265 +---u rcs:restconf-server-grouping 1267 Comments: 1269 * The "restconf-server-callhome-stack-grouping" defines the 1270 configuration for a full RESTCONF protocol stack, for RESTCONF 1271 servers that initiate call-home [RFC8071] connections to RESTCONF 1272 clients. 1274 * The "transport" choice node enables transport options to be 1275 configured. This document only defines an "https" option, but 1276 other options MAY be augmented in. 1278 * For the referenced grouping statement(s): 1280 - The "tcp-client-grouping" grouping is discussed in 1281 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 1282 - The "tls-server-grouping" grouping is discussed in 1283 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 1284 - The "http-server-grouping" grouping is discussed in 1285 Section 3.1.2.1 of [I-D.ietf-netconf-http-client-server]. 1286 - The "restconf-server-grouping" is discussed in Section 3.1.2.1 1287 of this document. 1289 3.1.2.4. The "restconf-server-app-grouping" Grouping 1291 The following tree diagram [RFC8340] illustrates the "restconf- 1292 server-app-grouping" grouping: 1294 grouping restconf-server-app-grouping 1295 +-- listen! {http-listen or https-listen}? 1296 | +-- endpoint* [name] 1297 | +-- name? string 1298 | +---u restconf-server-listen-stack-grouping 1299 +-- call-home! {https-call-home}? 1300 +-- restconf-client* [name] 1301 +-- name? string 1302 +-- endpoints 1303 | +-- endpoint* [name] 1304 | +-- name? string 1305 | +---u restconf-server-callhome-stack-grouping 1306 +-- connection-type 1307 | +-- (connection-type) 1308 | +--:(persistent-connection) 1309 | | +-- persistent! 1310 | +--:(periodic-connection) 1311 | +-- periodic! 1312 | +-- period? uint16 1313 | +-- anchor-time? yang:date-and-time 1314 | +-- idle-timeout? uint16 1315 +-- reconnect-strategy 1316 +-- start-with? enumeration 1317 +-- max-attempts? uint8 1319 Comments: 1321 * The "restconf-server-app-grouping" defines the configuration for a 1322 RESTCONF server that supports both listening for connections from 1323 RESTCONF clients as well as initiatiating call-home connections to 1324 RESTCONF clients. 1326 * Both the "listen" and "call-home" subtrees must be enabled by 1327 "feature" statements. 1329 * For the referenced grouping statement(s): 1331 - The "restconf-server-listen-stack-grouping" grouping is 1332 discussed in Section 3.1.2.2 in this document. 1333 - The "restconf-server-callhome-stack-grouping" grouping is 1334 discussed in Section 3.1.2.3 in this document. 1336 3.1.3. Protocol-accessible Nodes 1338 The following tree diagram [RFC8340] lists all the protocol- 1339 accessible nodes defined in the "ietf-restconf-server" module: 1341 module: ietf-restconf-server 1342 +--rw restconf-server 1343 +---u restconf-server-app-grouping 1345 Comments: 1347 * Protocol-accessible nodes are those nodes that are accessible when 1348 the module is "implemented", as described in Section 5.6.5 of 1349 [RFC7950]. 1351 * For the "ietf-restconf-server" module, the protocol-accessible 1352 nodes are an instance of the "restconf-server-app-grouping" 1353 discussed in Section 3.1.2.4 grouping. 1355 * The reason for why "restconf-server-app-grouping" exists separate 1356 from the protocol-accessible nodes definition is so as to enable 1357 instances of restconf-server-app-grouping to be instantiated in 1358 other locations, as may be needed or desired by some modules. 1360 3.2. Example Usage 1362 The following example illustrates configuring a RESTCONF server to 1363 listen for RESTCONF client connections, as well as configuring call- 1364 home to one RESTCONF client. 1366 This example is consistent with the examples presented in Section 2.2 1367 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 1368 [I-D.ietf-netconf-keystore]. 1370 =============== NOTE: '\' line wrapping per RFC 8792 ================ 1372 1377 1378 1379 1380 restconf/https 1381 1382 1383 11.22.33.44 1385 1386 1387 1388 1389 1390 rsa-asymmetric-key 1391 ex-rsa-cert 1392 1393 1394 1395 1396 1397 trusted-client-ca-certs 1399 1400 1401 trusted-client-ee-certs 1403 1404 1405 1406 1407 1408 1409 1410 foo.example.com 1411 1412 1413 1414 1415 1 1416 11:0A:05:11:00 1417 x509c2n:specified 1418 scooby-doo 1419 1420 1421 2 1422 x509c2n:san-any 1423 1424 1425 1426 1427 1428 1430 1431 1432 1433 config-manager 1434 1435 1436 east-data-center 1437 1438 1439 east.example.com 1440 1441 15 1442 3 1443 30 1444 1445 1446 1447 1448 1449 1450 rsa-asymmetric-key 1452 ex-rsa-cert 1453 1454 1455 1456 1457 1458 trusted-client-ca-certs 1460 1461 1462 trusted-client-ee-certs 1464 1465 1466 1467 1468 30 1469 3 1470 1471 1472 1473 1474 foo.example.com 1475 1476 1477 1478 1479 1 1480 11:0A:05:11:00 1481 x509c2n:specified 1482 scooby-doo 1483 1484 1485 2 1486 x509c2n:san-any 1487 1488 1489 1490 1491 1492 1493 west-data-center 1494 1495 1496 west.example.com 1497 1498 15 1499 3 1500 30 1501 1502 1503 1504 1505 1506 1507 rsa-asymmetric-key 1509 ex-rsa-cert 1510 1511 1512 1513 1514 1515 trusted-client-ca-certs 1517 1518 1519 trusted-client-ee-certs 1521 1522 1523 1524 1525 30 1526 3 1527 1528 1530 1531 1532 foo.example.com 1533 1534 1535 1536 1537 1 1538 11:0A:05:11:00 1539 x509c2n:specified 1540 scooby-doo 1541 1542 1543 2 1544 x509c2n:san-any 1545 1546 1547 1548 1549 1550 1551 1552 1553 300 1554 60 1555 1556 1557 1558 last-connected 1559 3 1560 1561 1562 1563 1565 3.3. YANG Module 1567 This YANG module has normative references to [RFC6991], [RFC7407], 1568 [RFC8040], [RFC8071], [I-D.ietf-netconf-tcp-client-server], 1569 [I-D.ietf-netconf-tls-client-server], and 1570 [I-D.ietf-netconf-http-client-server]. 1572 file "ietf-restconf-server@2021-02-10.yang" 1573 module ietf-restconf-server { 1574 yang-version 1.1; 1575 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1576 prefix rcs; 1578 import ietf-yang-types { 1579 prefix yang; 1580 reference 1581 "RFC 6991: Common YANG Data Types"; 1582 } 1584 import ietf-inet-types { 1585 prefix inet; 1586 reference 1587 "RFC 6991: Common YANG Data Types"; 1588 } 1590 import ietf-x509-cert-to-name { 1591 prefix x509c2n; 1592 reference 1593 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1594 } 1596 import ietf-tcp-client { 1597 prefix tcpc; 1598 reference 1599 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1600 } 1602 import ietf-tcp-server { 1603 prefix tcps; 1604 reference 1605 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 1606 } 1608 import ietf-tls-server { 1609 prefix tlss; 1610 reference 1611 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 1612 } 1614 import ietf-http-server { 1615 prefix https; 1616 reference 1617 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 1618 } 1620 organization 1621 "IETF NETCONF (Network Configuration) Working Group"; 1623 contact 1624 "WG Web: 1625 WG List: 1626 Author: Kent Watsen 1627 Author: Gary Wu 1628 Author: Juergen Schoenwaelder 1629 "; 1631 description 1632 "This module contains a collection of YANG definitions 1633 for configuring RESTCONF servers. 1635 Copyright (c) 2020 IETF Trust and the persons identified 1636 as authors of the code. All rights reserved. 1638 Redistribution and use in source and binary forms, with 1639 or without modification, is permitted pursuant to, and 1640 subject to the license terms contained in, the Simplified 1641 BSD License set forth in Section 4.c of the IETF Trust's 1642 Legal Provisions Relating to IETF Documents 1643 (https://trustee.ietf.org/license-info). 1645 This version of this YANG module is part of RFC IIII 1646 (https://www.rfc-editor.org/info/rfcIIII); see the RFC 1647 itself for full legal notices. 1649 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1650 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1651 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1652 are to be interpreted as described in BCP 14 (RFC 2119) 1653 (RFC 8174) when, and only when, they appear in all 1654 capitals, as shown here."; 1656 revision 2021-02-10 { 1657 description 1658 "Initial version"; 1659 reference 1660 "RFC IIII: RESTCONF Client and Server Models"; 1661 } 1663 // Features 1665 feature http-listen { 1666 description 1667 "The 'http-listen' feature indicates that the RESTCONF server 1668 supports opening a port to listen for incoming RESTCONF over 1669 TPC client connections, whereby the TLS connections are 1670 terminated by an external system."; 1671 reference 1672 "RFC 8040: RESTCONF Protocol"; 1673 } 1675 feature https-listen { 1676 description 1677 "The 'https-listen' feature indicates that the RESTCONF server 1678 supports opening a port to listen for incoming RESTCONF over 1679 TLS client connections, whereby the TLS connections are 1680 terminated by the server itself."; 1681 reference 1682 "RFC 8040: RESTCONF Protocol"; 1683 } 1685 feature https-call-home { 1686 description 1687 "The 'https-call-home' feature indicates that the RESTCONF 1688 server supports initiating connections to RESTCONF clients."; 1689 reference 1690 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1691 } 1693 // Groupings 1695 grouping restconf-server-grouping { 1696 description 1697 "A reusable grouping for configuring a RESTCONF server 1698 without any consideration for how underlying transport 1699 sessions are established. 1701 Note that this grouping uses a fairly typical descendent 1702 node name such that a stack of 'uses' statements will 1703 have name conflicts. It is intended that the consuming 1704 data model will resolve the issue by wrapping the 'uses' 1705 statement in a container called, e.g., 1706 'restconf-server-parameters'. This model purposely does 1707 not do this itself so as to provide maximum flexibility 1708 to consuming models."; 1710 container client-identity-mappings { 1711 description 1712 "Specifies mappings through which RESTCONF client X.509 1713 certificates are used to determine a RESTCONF username. 1714 If no matching and valid cert-to-name list entry can be 1715 found, then the RESTCONF server MUST close the connection, 1716 and MUST NOT accept RESTCONF messages over it."; 1717 reference 1718 "RFC 7407: A YANG Data Model for SNMP Configuration."; 1719 uses x509c2n:cert-to-name { 1720 refine "cert-to-name/fingerprint" { 1721 mandatory false; 1722 description 1723 "A 'fingerprint' value does not need to be specified 1724 when the 'cert-to-name' mapping is independent of 1725 fingerprint matching. A 'cert-to-name' having no 1726 fingerprint value will match any client certificate 1727 and therefore should only be present at the end of 1728 the user-ordered 'cert-to-name' list."; 1729 } 1730 } 1731 } 1732 } 1734 grouping restconf-server-listen-stack-grouping { 1735 description 1736 "A reusable grouping for configuring a RESTCONF server 1737 'listen' protocol stack for a single connection."; 1738 choice transport { 1739 mandatory true; 1740 description 1741 "Selects between available transports. This is a 1742 'choice' statement so as to support additional 1743 transport options to be augmented in."; 1744 case http { 1745 if-feature "http-listen"; 1746 container http { 1747 description 1748 "Configures RESTCONF server stack assuming that 1749 TLS-termination is handled externally."; 1750 container external-endpoint { 1751 presence 1752 "Specifies configuration for an external endpoint."; 1753 description 1754 "Identifies contact information for the external 1755 system that terminates connections before passing 1756 them thru to this server (e.g., a network address 1757 translator or a load balancer). These values have 1758 no effect on the local operation of this server, but 1759 may be used by the application when needing to 1760 inform other systems how to contact this server."; 1761 leaf address { 1762 type inet:ip-address; 1763 mandatory true; 1764 description 1765 "The IP address or hostname of the external system 1766 that terminates incoming RESTCONF client 1767 connections before forwarding them to this 1768 server."; 1769 } 1770 leaf port { 1771 type inet:port-number; 1772 default "443"; 1773 description 1774 "The port number that the external system listens 1775 on for incoming RESTCONF client connections that 1776 are forwarded to this server. The default HTTPS 1777 port (443) is used, as expected for a RESTCONF 1778 connection."; 1779 } 1780 } 1781 container tcp-server-parameters { 1782 description 1783 "A wrapper around the TCP server parameters 1784 to avoid name collisions."; 1785 uses tcps:tcp-server-grouping { 1786 refine "local-port" { 1787 default "80"; 1788 description 1789 "The RESTCONF server will listen on the IANA- 1790 assigned well-known port value for 'http' 1791 (80) if no value is specified."; 1792 } 1793 } 1794 } 1795 container http-server-parameters { 1796 description 1797 "A wrapper around the HTTP server parameters 1798 to avoid name collisions."; 1799 uses https:http-server-grouping; 1800 } 1801 container restconf-server-parameters { 1802 description 1803 "A wrapper around the RESTCONF server parameters 1804 to avoid name collisions."; 1805 uses rcs:restconf-server-grouping; 1806 } 1807 } 1808 } 1809 case https { 1810 if-feature "https-listen"; 1811 container https { 1812 description 1813 "Configures RESTCONF server stack assuming that 1814 TLS-termination is handled internally."; 1815 container tcp-server-parameters { 1816 description 1817 "A wrapper around the TCP server parameters 1818 to avoid name collisions."; 1819 uses tcps:tcp-server-grouping { 1820 refine "local-port" { 1821 default "443"; 1822 description 1823 "The RESTCONF server will listen on the IANA- 1824 assigned well-known port value for 'https' 1825 (443) if no value is specified."; 1826 } 1827 } 1828 } 1829 container tls-server-parameters { 1830 description 1831 "A wrapper around the TLS server parameters 1832 to avoid name collisions."; 1833 uses tlss:tls-server-grouping; 1834 } 1835 container http-server-parameters { 1836 description 1837 "A wrapper around the HTTP server parameters 1838 to avoid name collisions."; 1839 uses https:http-server-grouping; 1840 } 1841 container restconf-server-parameters { 1842 description 1843 "A wrapper around the RESTCONF server parameters 1844 to avoid name collisions."; 1845 uses rcs:restconf-server-grouping; 1846 } 1847 } 1848 } 1849 } 1850 } 1852 grouping restconf-server-callhome-stack-grouping { 1853 description 1854 "A reusable grouping for configuring a RESTCONF server 1855 'call-home' protocol stack, for a single connection."; 1856 choice transport { 1857 mandatory true; 1858 description 1859 "Selects between available transports. This is a 1860 'choice' statement so as to support additional 1861 transport options to be augmented in."; 1862 case https { 1863 if-feature "https-listen"; 1864 container https { 1865 description 1866 "Configures RESTCONF server stack assuming that 1867 TLS-termination is handled internally."; 1868 container tcp-client-parameters { 1869 description 1870 "A wrapper around the TCP client parameters 1871 to avoid name collisions."; 1872 uses tcpc:tcp-client-grouping { 1873 refine "remote-port" { 1874 default "4336"; 1875 description 1876 "The RESTCONF server will attempt to 1877 connect to the IANA-assigned well-known 1878 port for 'restconf-ch-tls' (4336) if no 1879 value is specified."; 1880 } 1881 } 1882 } 1883 container tls-server-parameters { 1884 description 1885 "A wrapper around the TLS server parameters 1886 to avoid name collisions."; 1887 uses tlss:tls-server-grouping; 1888 } 1889 container http-server-parameters { 1890 description 1891 "A wrapper around the HTTP server parameters 1892 to avoid name collisions."; 1893 uses https:http-server-grouping; 1894 } 1895 container restconf-server-parameters { 1896 description 1897 "A wrapper around the RESTCONF server parameters 1898 to avoid name collisions."; 1899 uses rcs:restconf-server-grouping; 1900 } 1901 } 1902 } 1903 } 1904 } 1906 grouping restconf-server-app-grouping { 1907 description 1908 "A reusable grouping for configuring a RESTCONF server 1909 application that supports both 'listen' and 'call-home' 1910 protocol stacks for a multiplicity of connections."; 1911 container listen { 1912 if-feature "http-listen or https-listen"; 1913 presence 1914 "Enables the RESTCONF server to listen for RESTCONF 1915 client connections."; 1916 description "Configures listen behavior"; 1917 list endpoint { 1918 key "name"; 1919 min-elements 1; 1920 description 1921 "List of endpoints to listen for RESTCONF connections."; 1922 leaf name { 1923 type string; 1924 description 1925 "An arbitrary name for the RESTCONF listen endpoint."; 1926 } 1927 uses restconf-server-listen-stack-grouping; 1928 } 1929 } 1930 container call-home { 1931 if-feature "https-call-home"; 1932 presence 1933 "Enables the RESTCONF server to initiate the underlying 1934 transport connection to RESTCONF clients."; 1935 description "Configures call-home behavior"; 1936 list restconf-client { 1937 key "name"; 1938 min-elements 1; 1939 description 1940 "List of RESTCONF clients the RESTCONF server is to 1941 maintain simultaneous call-home connections with."; 1942 leaf name { 1943 type string; 1944 description 1945 "An arbitrary name for the remote RESTCONF client."; 1946 } 1947 container endpoints { 1948 description 1949 "Container for the list of endpoints."; 1950 list endpoint { 1951 key "name"; 1952 min-elements 1; 1953 ordered-by user; 1954 description 1955 "User-ordered list of endpoints for this RESTCONF 1956 client. Defining more than one enables high- 1957 availability."; 1958 leaf name { 1959 type string; 1960 description 1961 "An arbitrary name for this endpoint."; 1962 } 1963 uses restconf-server-callhome-stack-grouping; 1964 } 1965 } 1966 container connection-type { 1967 description 1968 "Indicates the RESTCONF server's preference for how the 1969 RESTCONF connection is maintained."; 1970 choice connection-type { 1971 mandatory true; 1972 description 1973 "Selects between available connection types."; 1974 case persistent-connection { 1975 container persistent { 1976 presence "Indicates that a persistent connection is 1977 to be maintained."; 1978 description 1979 "Maintain a persistent connection to the RESTCONF 1980 client. If the connection goes down, immediately 1981 start trying to reconnect to the RESTCONF server, 1982 using the reconnection strategy. 1984 This connection type minimizes any RESTCONF 1985 client to RESTCONF server data-transfer delay, 1986 albeit at the expense of holding resources 1987 longer."; 1988 } 1989 } 1990 case periodic-connection { 1991 container periodic { 1992 presence "Indicates that a periodic connection is 1993 to be maintained."; 1994 description 1995 "Periodically connect to the RESTCONF client. 1997 This connection type increases resource 1998 utilization, albeit with increased delay in 1999 RESTCONF client to RESTCONF client interactions. 2001 The RESTCONF client SHOULD gracefully close 2002 the underlying TLS connection upon completing 2003 planned activities. If the underlying TLS 2004 connection is not closed gracefully, the 2005 RESTCONF server MUST immediately attempt 2006 to reestablish the connection. 2008 In the case that the previous connection is 2009 still active (i.e., the RESTCONF client has not 2010 closed it yet), establishing a new connection 2011 is NOT RECOMMENDED."; 2013 leaf period { 2014 type uint16; 2015 units "minutes"; 2016 default "60"; 2017 description 2018 "Duration of time between periodic connections."; 2019 } 2020 leaf anchor-time { 2021 type yang:date-and-time { 2022 // constrained to minute-level granularity 2023 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2024 + '(Z|[\+\-]\d{2}:\d{2})'; 2025 } 2026 description 2027 "Designates a timestamp before or after which a 2028 series of periodic connections are determined. 2029 The periodic connections occur at a whole 2030 multiple interval from the anchor time. For 2031 example, for an anchor time is 15 minutes past 2032 midnight and a period interval of 24 hours, then 2033 a periodic connection will occur 15 minutes past 2034 midnight everyday."; 2035 } 2036 leaf idle-timeout { 2037 type uint16; 2038 units "seconds"; 2039 default 120; // two minutes 2040 description 2041 "Specifies the maximum number of seconds that 2042 the underlying TCP session may remain idle. 2043 A TCP session will be dropped if it is idle 2044 for an interval longer than this number of 2045 seconds. If set to zero, then the server 2046 will never drop a session because it is idle."; 2047 } 2048 } 2049 } 2050 } 2052 } 2053 container reconnect-strategy { 2054 description 2055 "The reconnection strategy directs how a RESTCONF server 2056 reconnects to a RESTCONF client after discovering its 2057 connection to the client has dropped, even if due to a 2058 reboot. The RESTCONF server starts with the specified 2059 endpoint and tries to connect to it max-attempts times 2060 before trying the next endpoint in the list (round 2061 robin)."; 2062 leaf start-with { 2063 type enumeration { 2064 enum first-listed { 2065 description 2066 "Indicates that reconnections should start with 2067 the first endpoint listed."; 2068 } 2069 enum last-connected { 2070 description 2071 "Indicates that reconnections should start with 2072 the endpoint last connected to. If no previous 2073 connection has ever been established, then the 2074 first endpoint configured is used. RESTCONF 2075 servers SHOULD be able to remember the last 2076 endpoint connected to across reboots."; 2077 } 2078 enum random-selection { 2079 description 2080 "Indicates that reconnections should start with 2081 a random endpoint."; 2082 } 2083 } 2084 default "first-listed"; 2085 description 2086 "Specifies which of the RESTCONF client's endpoints 2087 the RESTCONF server should start with when trying 2088 to connect to the RESTCONF client."; 2089 } 2090 leaf max-attempts { 2091 type uint8 { 2092 range "1..max"; 2093 } 2094 default "3"; 2095 description 2096 "Specifies the number times the RESTCONF server tries 2097 to connect to a specific endpoint before moving on to 2098 the next endpoint in the list (round robin)."; 2099 } 2101 } 2102 } // restconf-client 2103 } // call-home 2104 } // restconf-server-app-grouping 2106 // Protocol accessible node, for servers that implement 2107 // this module. 2108 container restconf-server { 2109 uses restconf-server-app-grouping; 2110 description 2111 "Top-level container for RESTCONF server configuration."; 2112 } 2114 } 2116 2118 4. Security Considerations 2120 4.1. The "ietf-restconf-client" YANG Module 2122 The "ietf-restconf-client" YANG module defines data nodes that are 2123 designed to be accessed via YANG based management protocols, such as 2124 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2125 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2126 with mutual authentication. 2128 The NETCONF access control model (NACM) [RFC8341] provides the means 2129 to restrict access for particular users to a pre-configured subset of 2130 all available protocol operations and content. 2132 None of the readable data nodes in this YANG module are considered 2133 sensitive or vulnerable in network environments. The NACM "default- 2134 deny-all" extension has not been set for any data nodes defined in 2135 this module. 2137 None of the writable data nodes in this YANG module are considered 2138 sensitive or vulnerable in network environments. The NACM "default- 2139 deny-write" extension has not been set for any data nodes defined in 2140 this module. 2142 This module does not define any RPCs, actions, or notifications, and 2143 thus the security consideration for such is not provided here. 2145 Please be aware that this module uses groupings defined in other RFCs 2146 that define data nodes that do set the NACM "default-deny-all" and 2147 "default-deny-write" extensions. 2149 4.2. The "ietf-restconf-server" YANG Module 2151 The "ietf-restconf-server" YANG module defines data nodes that are 2152 designed to be accessed via YANG based management protocols, such as 2153 NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 2154 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 2155 with mutual authentication. 2157 The NETCONF access control model (NACM) [RFC8341] provides the means 2158 to restrict access for particular users to a pre-configured subset of 2159 all available protocol operations and content. 2161 None of the readable data nodes in this YANG module are considered 2162 sensitive or vulnerable in network environments. The NACM "default- 2163 deny-all" extension has not been set for any data nodes defined in 2164 this module. 2166 None of the writable data nodes in this YANG module are considered 2167 sensitive or vulnerable in network environments. The NACM "default- 2168 deny-write" extension has not been set for any data nodes defined in 2169 this module. 2171 This module does not define any RPCs, actions, or notifications, and 2172 thus the security consideration for such is not provided here. 2174 Please be aware that this module uses groupings defined in other RFCs 2175 that define data nodes that do set the NACM "default-deny-all" and 2176 "default-deny-write" extensions. 2178 5. IANA Considerations 2180 5.1. The "IETF XML" Registry 2182 This document registers two URIs in the "ns" subregistry of the IETF 2183 XML Registry [RFC3688]. Following the format in [RFC3688], the 2184 following registrations are requested: 2186 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2187 Registrant Contact: The IESG 2188 XML: N/A, the requested URI is an XML namespace. 2190 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2191 Registrant Contact: The IESG 2192 XML: N/A, the requested URI is an XML namespace. 2194 5.2. The "YANG Module Names" Registry 2196 This document registers two YANG modules in the YANG Module Names 2197 registry [RFC6020]. Following the format in [RFC6020], the following 2198 registrations are requested: 2200 name: ietf-restconf-client 2201 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 2202 prefix: ncc 2203 reference: RFC IIII 2205 name: ietf-restconf-server 2206 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 2207 prefix: ncs 2208 reference: RFC IIII 2210 6. References 2212 6.1. Normative References 2214 [I-D.ietf-netconf-http-client-server] 2215 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 2216 Servers", Work in Progress, Internet-Draft, draft-ietf- 2217 netconf-http-client-server-05, 20 August 2020, 2218 . 2221 [I-D.ietf-netconf-keystore] 2222 Watsen, K., "A YANG Data Model for a Keystore", Work in 2223 Progress, Internet-Draft, draft-ietf-netconf-keystore-20, 2224 20 August 2020, . 2227 [I-D.ietf-netconf-tcp-client-server] 2228 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 2229 and TCP Servers", Work in Progress, Internet-Draft, draft- 2230 ietf-netconf-tcp-client-server-08, 20 August 2020, 2231 . 2234 [I-D.ietf-netconf-tls-client-server] 2235 Watsen, K., "YANG Groupings for TLS Clients and TLS 2236 Servers", Work in Progress, Internet-Draft, draft-ietf- 2237 netconf-tls-client-server-22, 20 August 2020, 2238 . 2241 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2242 Requirement Levels", BCP 14, RFC 2119, 2243 DOI 10.17487/RFC2119, March 1997, 2244 . 2246 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2247 the Network Configuration Protocol (NETCONF)", RFC 6020, 2248 DOI 10.17487/RFC6020, October 2010, 2249 . 2251 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2252 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2253 . 2255 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2256 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2257 December 2014, . 2259 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2260 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2261 . 2263 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2264 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2265 . 2267 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2268 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2269 . 2271 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2272 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2273 May 2017, . 2275 6.2. Informative References 2277 [I-D.ietf-netconf-crypto-types] 2278 Watsen, K., "YANG Data Types and Groupings for 2279 Cryptography", Work in Progress, Internet-Draft, draft- 2280 ietf-netconf-crypto-types-18, 20 August 2020, 2281 . 2284 [I-D.ietf-netconf-netconf-client-server] 2285 Watsen, K., "NETCONF Client and Server Models", Work in 2286 Progress, Internet-Draft, draft-ietf-netconf-netconf- 2287 client-server-21, 20 August 2020, 2288 . 2291 [I-D.ietf-netconf-restconf-client-server] 2292 Watsen, K., "RESTCONF Client and Server Models", Work in 2293 Progress, Internet-Draft, draft-ietf-netconf-restconf- 2294 client-server-21, 20 August 2020, 2295 . 2298 [I-D.ietf-netconf-ssh-client-server] 2299 Watsen, K., "YANG Groupings for SSH Clients and SSH 2300 Servers", Work in Progress, Internet-Draft, draft-ietf- 2301 netconf-ssh-client-server-22, 20 August 2020, 2302 . 2305 [I-D.ietf-netconf-trust-anchors] 2306 Watsen, K., "A YANG Data Model for a Truststore", Work in 2307 Progress, Internet-Draft, draft-ietf-netconf-trust- 2308 anchors-13, 20 August 2020, . 2311 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2312 DOI 10.17487/RFC3688, January 2004, 2313 . 2315 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2316 and A. Bierman, Ed., "Network Configuration Protocol 2317 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2318 . 2320 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2321 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2322 . 2324 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2325 Access Control Model", STD 91, RFC 8341, 2326 DOI 10.17487/RFC8341, March 2018, 2327 . 2329 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 2330 and R. Wilton, "Network Management Datastore Architecture 2331 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 2332 . 2334 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 2335 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 2336 . 2338 Appendix A. Expanded Tree Diagrams 2340 A.1. Expanded Tree Diagram for 'ietf-restconf-client' 2342 The following tree diagram [RFC8340] provides an overview of the data 2343 model for the "ietf-restconf-client" module. 2345 This tree diagram shows all the nodes defined in this module, 2346 including those defined by "grouping" statements used by this module. 2348 Please see Section 2.1 for a tree diagram that illustrates what the 2349 module looks like without all the "grouping" statements expanded. 2351 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-client-tree.txt) 2353 A.2. Expanded Tree Diagram for 'ietf-restconf-server' 2355 The following tree diagram [RFC8340] provides an overview of the data 2356 model for the "ietf-restconf-server" module. 2358 This tree diagram shows all the nodes defined in this module, 2359 including those defined by "grouping" statements used by this module. 2361 Please see Section 3.1 for a tree diagram that illustrates what the 2362 module looks like without all the "grouping" statements expanded. 2364 XNSERT_TEXT_FROM_FILE(refs/ietf-restconf-server-tree.txt) 2366 Appendix B. Change Log 2368 This section is to be removed before publishing as an RFC. 2370 B.1. 00 to 01 2372 * Renamed "keychain" to "keystore". 2374 B.2. 01 to 02 2376 * Filled in previously missing 'ietf-restconf-client' module. 2378 * Updated the ietf-restconf-server module to accommodate new 2379 grouping 'ietf-tls-server-grouping'. 2381 B.3. 02 to 03 2383 * Refined use of tls-client-grouping to add a must statement 2384 indicating that the TLS client must specify a client-certificate. 2386 * Changed restconf-client??? to be a grouping (not a container). 2388 B.4. 03 to 04 2390 * Added RFC 8174 to Requirements Language Section. 2392 * Replaced refine statement in ietf-restconf-client to add a 2393 mandatory true. 2395 * Added refine statement in ietf-restconf-server to add a must 2396 statement. 2398 * Now there are containers and groupings, for both the client and 2399 server models. 2401 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2403 * Updated examples to inline key and certificates (no longer a 2404 leafref to keystore) 2406 B.5. 04 to 05 2408 * Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2410 * Updated examples to inline key and certificates (no longer a 2411 leafref to keystore) 2413 B.6. 05 to 06 2415 * Fixed change log missing section issue. 2417 * Updated examples to match latest updates to the crypto-types, 2418 trust-anchors, and keystore drafts. 2420 * Reduced line length of the YANG modules to fit within 69 columns. 2422 B.7. 06 to 07 2424 * removed "idle-timeout" from "persistent" connection config. 2426 * Added "random-selection" for reconnection-strategy's "starts-with" 2427 enum. 2429 * Replaced "connection-type" choice default (persistent) with 2430 "mandatory true". 2432 * Reduced the periodic-connection's "idle-timeout" from 5 to 2 2433 minutes. 2435 * Replaced reconnect-timeout with period/anchor-time combo. 2437 B.8. 07 to 08 2439 * Modified examples to be compatible with new crypto-types algs 2441 B.9. 08 to 09 2443 * Corrected use of "mandatory true" for "address" leafs. 2445 * Updated examples to reflect update to groupings defined in the 2446 keystore draft. 2448 * Updated to use groupings defined in new TCP and HTTP drafts. 2450 * Updated copyright date, boilerplate template, affiliation, and 2451 folding algorithm. 2453 B.10. 09 to 10 2455 * Reformatted YANG modules. 2457 B.11. 10 to 11 2459 * Adjusted for the top-level "demux container" added to groupings 2460 imported from other modules. 2462 * Added "must" expressions to ensure that keepalives are not 2463 configured for "periodic" connections. 2465 * Updated the boilerplate text in module-level "description" 2466 statement to match copyeditor convention. 2468 * Moved "expanded" tree diagrams to the Appendix. 2470 B.12. 11 to 12 2472 * Removed the 'must' statement limiting keepalives in periodic 2473 connections. 2475 * Updated models and examples to reflect removal of the "demux" 2476 containers in the imported models. 2478 * Updated the "periodic-connnection" description statements to 2479 better describe behavior when connections are not closed 2480 gracefully. 2482 * Updated text to better reference where certain examples come from 2483 (e.g., which Section in which draft). 2485 * In the server model, commented out the "must 'pinned-ca-certs or 2486 pinned-client-certs'" statement to reflect change made in the TLS 2487 draft whereby the trust anchors MAY be defined externally. 2489 * Replaced the 'listen', 'initiate', and 'call-home' features with 2490 boolean expressions. 2492 B.13. 12 to 13 2494 * Updated to reflect changes in trust-anchors drafts (e.g., s/trust- 2495 anchors/truststore/g + s/pinned.//) 2497 * In ietf-restconf-server, Added 'http-listen' (not https-listen) 2498 choice, to support case when server is behind a TLS-terminator. 2500 * Refactored server module to be more like other 'server' models. 2501 If folks like it, will also apply to the client model, as well as 2502 to both the netconf client/server models. Now the 'restconf- 2503 server-grouping' is just the RC-specific bits (i.e., the "demux" 2504 container minus the container), 'restconf-server- 2505 [listen|callhome]-stack-grouping' is the protocol stack for a 2506 single connection, and 'restconf-server-app-grouping' is 2507 effectively what was before (both listen+callhome for many 2508 inbound/outbound endpoints). 2510 B.14. 13 to 14 2512 * Updated examples to reflect ietf-crypto-types change (e.g., 2513 identities --> enumerations) 2515 * Adjusting from change in TLS client model (removing the top-level 2516 'certificate' container). 2518 * Added "external-endpoint" to the "http-listen" choice in ietf- 2519 restconf-server. 2521 B.15. 14 to 15 2523 * Added missing "or https-listen" clause in a "must" expression. 2525 * Refactored the client module similar to how the server module was 2526 refactored in -13. Now the 'restconf-client-grouping' is just the 2527 RC-specific bits, the 'restconf-client-[initiate|listen]-stack- 2528 grouping' is the protocol stack for a single connection, and 2529 'restconf-client-app-grouping' is effectively what was before 2530 (both listen+callhome for many inbound/outbound endpoints). 2532 B.16. 15 to 16 2534 * Added refinement to make "cert-to-name/fingerprint" be mandatory 2535 false. 2537 * Commented out refinement to "tls-server-grouping/client- 2538 authentication" until a better "must" expression is defined. 2540 * Updated restconf-client example to reflect that http-client- 2541 grouping no longer has a "protocol-version" leaf. 2543 B.17. 16 to 17 2545 * Updated examples to include the "*-key-format" nodes. 2547 * Updated examples to remove the "required" nodes. 2549 B.18. 17 to 18 2551 * Updated examples to reflect new "bag" addition to truststore. 2553 B.19. 18 to 19 2555 * Updated examples to remove the 'algorithm' nodes. 2557 * Updated examples to reflect the new TLS keepalives structure. 2559 * Removed the 'protocol-versions' node from the restconf-server 2560 examples. 2562 * Added a "Note to Reviewers" note to first page. 2564 B.20. 19 to 20 2565 * Moved and changed "must" statement so that either TLS *or* HTTP 2566 auth must be configured. 2568 * Expanded "Data Model Overview section(s) [remove "wall" of tree 2569 diagrams]. 2571 * Updated the Security Considerations section. 2573 B.21. 20 to 21 2575 * Cleaned up titles in the IANA Consideratons section 2577 * Fixed issues found by the SecDir review of the "keystore" draft. 2579 B.22. 21 to 22 2581 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 2583 Acknowledgements 2585 The authors would like to thank for following for lively discussions 2586 on list and in the halls (ordered by last name): Andy Bierman, Martin 2587 Bjorklund, Benoit Claise, Mehmet Ersue, Ramkumar Dhanapal, Balazs 2588 Kovacs, Radek Krejci, David Lamparter, Ladislav Lhotka, Alan Luchuk, 2589 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, Bert 2590 Wijnen. 2592 Author's Address 2594 Kent Watsen 2595 Watsen Networks 2597 Email: kent+ietf@watsen.net