idnits 2.17.1 draft-ietf-netconf-restconf-client-server-10.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 -- The document date (March 9, 2019) is 1846 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 (-35) exists of draft-ietf-netconf-keystore-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-08 == Outdated reference: A later version (-05) exists of draft-kwatsen-netconf-http-client-server-00 == Outdated reference: A later version (-02) exists of draft-kwatsen-netconf-tcp-client-server-00 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-08 Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track March 9, 2019 5 Expires: September 10, 2019 7 RESTCONF Client and Server Models 8 draft-ietf-netconf-restconf-client-server-10 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 many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 This document contains references to other drafts in progress, both 25 in the Normative References section, as well as in body text 26 throughout. Please update the following references to reflect their 27 final RFC assignments: 29 o I-D.ietf-netconf-keystore 31 o I-D.ietf-netconf-tcp-client-server 33 o I-D.ietf-netconf-tls-client-server 35 o I-D.ietf-netconf-http-client-server 37 Artwork in this document contains shorthand references to drafts in 38 progress. Please apply the following replacements: 40 o "XXXX" --> the assigned RFC value for this draft 42 o "AAAA" --> the assigned RFC value for I-D.ietf-netconf-tcp-client- 43 server 45 o "CCCC" --> the assigned RFC value for I-D.ietf-netconf-tls-client- 46 server 48 o "BBBB" --> the assigned RFC value for I-D.ietf-netconf-http- 49 client-server 51 Artwork in this document contains placeholder values for the date of 52 publication of this draft. Please apply the following replacement: 54 o "2019-03-09" --> the publication date of this draft 56 The following Appendix section is to be removed prior to publication: 58 o Appendix A. Change Log 60 Status of This Memo 62 This Internet-Draft is submitted in full conformance with the 63 provisions of BCP 78 and BCP 79. 65 Internet-Drafts are working documents of the Internet Engineering 66 Task Force (IETF). Note that other groups may also distribute 67 working documents as Internet-Drafts. The list of current Internet- 68 Drafts is at https://datatracker.ietf.org/drafts/current/. 70 Internet-Drafts are draft documents valid for a maximum of six months 71 and may be updated, replaced, or obsoleted by other documents at any 72 time. It is inappropriate to use Internet-Drafts as reference 73 material or to cite them other than as "work in progress." 75 This Internet-Draft will expire on September 10, 2019. 77 Copyright Notice 79 Copyright (c) 2019 IETF Trust and the persons identified as the 80 document authors. All rights reserved. 82 This document is subject to BCP 78 and the IETF Trust's Legal 83 Provisions Relating to IETF Documents 84 (https://trustee.ietf.org/license-info) in effect on the date of 85 publication of this document. Please review these documents 86 carefully, as they describe your rights and restrictions with respect 87 to this document. Code Components extracted from this document must 88 include Simplified BSD License text as described in Section 4.e of 89 the Trust Legal Provisions and are provided without warranty as 90 described in the Simplified BSD License. 92 Table of Contents 94 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 95 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 96 2. The RESTCONF Client Model . . . . . . . . . . . . . . . . . . 4 97 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 98 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 99 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12 100 3. The RESTCONF Server Model . . . . . . . . . . . . . . . . . . 20 101 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 21 102 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 24 103 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 27 104 4. Security Considerations . . . . . . . . . . . . . . . . . . . 36 105 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 106 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 37 107 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 38 108 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 109 6.1. Normative References . . . . . . . . . . . . . . . . . . 38 110 6.2. Informative References . . . . . . . . . . . . . . . . . 39 111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 41 112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 41 113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 41 114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 41 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 41 116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 41 117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 42 118 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 42 119 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 42 120 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 42 121 A.10. 09 to 10 . . . . . . . . . . . . . . . . . . . . . . . . 42 122 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 43 123 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 43 125 1. Introduction 127 This document defines two YANG [RFC7950] modules, one module to 128 configure a RESTCONF client and the other module to configure a 129 RESTCONF server [RFC8040]. Both modules support the TLS [RFC8446] 130 transport protocol with both standard RESTCONF and RESTCONF Call Home 131 connections [RFC8071]. 133 1.1. Terminology 135 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 136 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 137 "OPTIONAL" in this document are to be interpreted as described in BCP 138 14 [RFC2119] [RFC8174] when, and only when, they appear in all 139 capitals, as shown here. 141 2. The RESTCONF Client Model 143 The RESTCONF client model presented in this section supports both 144 clients initiating connections to servers, as well as clients 145 listening for connections from servers calling home. 147 This model, like that presented in 148 [I-D.ietf-netconf-netconf-client-server], is designed to support any 149 number of possible transports. RESTCONF only supports the TLS 150 transport currently, thus this model only supports the TLS transport. 152 All private keys and trusted certificates are held in the keystore 153 model defined in [I-D.ietf-netconf-keystore]. 155 YANG feature statements are used to enable implementations to 156 advertise which parts of the model the RESTCONF client supports. 158 2.1. Tree Diagram 160 The following tree diagram [RFC8340] provides an overview of the data 161 model for the "ietf-restconf-client" module. Just the container is 162 displayed below, but there is also a reusable grouping called 163 "restconf-client-grouping" that the container is using. 165 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 167 module: ietf-restconf-client 168 +--rw restconf-client 169 +--rw initiate! {initiate}? 170 | +--rw restconf-server* [name] 171 | +--rw name string 172 | +--rw endpoints 173 | +--rw endpoint* [name] 174 | +--rw name string 175 | +--rw (transport) 176 | | +--:(https) {https-initiate}? 177 | | +--rw https 178 | | +--rw remote-address inet:host 179 | | +--rw remote-port? 180 | | | inet:port-number 181 | | +--rw local-address? inet:ip-addr\ 182 \ess 183 | | +--rw local-port? 184 | | | inet:port-number 185 | | +--rw tcp-keepalives {tcp-client-keepalive\ 186 \s}? 187 | | | +--rw idle-time? uint16 188 | | | +--rw max-probes? uint16 189 | | | +--rw probe-interval? uint16 190 | | +--rw tls-client-identity 191 | | | +--rw (auth-type) 192 | | | +--:(certificate) 193 | | | +--rw certificate 194 | | | +--rw (local-or-keystore) 195 | | | +--:(local) 196 | | | | {local-keys-suppor\ 197 \ted}? 198 | | | | +--rw local-definition 199 | | | | +--rw algorithm? 200 | | | | | asymmetric-ke\ 201 \y-algorithm-ref 202 | | | | +--rw public-key? 203 | | | | | binary 204 | | | | +--rw private-key? 205 | | | | | union 206 | | | | +---x generate-hidden\ 207 \-key 208 | | | | | +---w input 209 | | | | | +---w algorithm 210 | | | | | asymmet\ 211 \ric-key-algorithm-ref 212 | | | | +---x install-hidden-\ 213 \key 214 | | | | | +---w input 215 | | | | | +---w algorithm 216 | | | | | | asymmet\ 217 \ric-key-algorithm-ref 218 | | | | | +---w public-ke\ 219 \y? 220 | | | | | | binary 221 | | | | | +---w private-k\ 222 \ey? 223 | | | | | binary 224 | | | | +--rw cert? 225 | | | | | end-entity-ce\ 226 \rt-cms 227 | | | | +---n certificate-exp\ 228 \iration 229 | | | | +-- expiration-date 230 | | | | yang:date-\ 231 \and-time 232 | | | +--:(keystore) 233 | | | {keystore-supporte\ 234 \d}? 235 | | | +--rw keystore-reference? 236 | | | ks:asymmetric-ke\ 238 \y-certificate-ref 239 | | +--rw tls-server-auth 240 | | | +--rw pinned-ca-certs? 241 | | | | ta:pinned-certificates-ref 242 | | | | {ta:x509-certificates}? 243 | | | +--rw pinned-server-certs? 244 | | | ta:pinned-certificates-ref 245 | | | {ta:x509-certificates}? 246 | | +--rw tls-hello-params 247 | | | {tls-client-hello-params-config}? 248 | | | +--rw tls-versions 249 | | | | +--rw tls-version* identityref 250 | | | +--rw cipher-suites 251 | | | +--rw cipher-suite* identityref 252 | | +--rw tls-keepalives {tls-client-keepalive\ 253 \s}? 254 | | | +--rw max-wait? uint16 255 | | | +--rw max-attempts? uint8 256 | | +--rw http-client-identity 257 | | | +--rw (auth-type)? 258 | | | +--:(basic) 259 | | | | +--rw basic 260 | | | | +--rw user-id? string 261 | | | | +--rw password? string 262 | | | +--:(bearer) 263 | | | | +--rw bearer 264 | | | | +--rw token? string 265 | | | +--:(digest) 266 | | | | +--rw digest 267 | | | | +--rw username? string 268 | | | | +--rw password? string 269 | | | +--:(hoba) 270 | | | | +--rw hoba 271 | | | +--:(mutual) 272 | | | | +--rw mutual 273 | | | +--:(negotiate) 274 | | | | +--rw negotiate 275 | | | +--:(oauth) 276 | | | | +--rw oauth 277 | | | +--:(scram-sha-1) 278 | | | | +--rw scram-sha-1 279 | | | +--:(scram-sha-256) 280 | | | | +--rw scram-sha-256 281 | | | +--:(vapid) 282 | | | +--rw vapid 283 | | +--rw http-keepalives 284 | | {http-client-keepalives}? 285 | | +--rw max-wait? uint16 286 | | +--rw max-attempts? uint8 287 | +--rw connection-type 288 | | +--rw (connection-type) 289 | | +--:(persistent-connection) 290 | | | +--rw persistent! 291 | | +--:(periodic-connection) 292 | | +--rw periodic! 293 | | +--rw period? uint16 294 | | +--rw anchor-time? yang:date-and-time 295 | | +--rw idle-timeout? uint16 296 | +--rw reconnect-strategy 297 | +--rw start-with? enumeration 298 | +--rw max-attempts? uint8 299 +--rw listen! {listen}? 300 +--rw idle-timeout? uint16 301 +--rw endpoint* [name] 302 +--rw name string 303 +--rw (transport) 304 +--:(https) {https-listen}? 305 +--rw https 306 +--rw local-address inet:ip-address 307 +--rw local-port? inet:port-number 308 +--rw tcp-keepalives {tcp-server-keepalives}? 309 | +--rw idle-time? uint16 310 | +--rw max-probes? uint16 311 | +--rw probe-interval? uint16 312 +--rw tls-client-identity 313 | +--rw (auth-type) 314 | +--:(certificate) 315 | +--rw certificate 316 | +--rw (local-or-keystore) 317 | +--:(local) {local-keys-supported\ 318 \}? 319 | | +--rw local-definition 320 | | +--rw algorithm? 321 | | | asymmetric-key-algo\ 322 \rithm-ref 323 | | +--rw public-key? 324 | | | binary 325 | | +--rw private-key? 326 | | | union 327 | | +---x generate-hidden-key 328 | | | +---w input 329 | | | +---w algorithm 330 | | | asymmetric-ke\ 331 \y-algorithm-ref 332 | | +---x install-hidden-key 333 | | | +---w input 334 | | | +---w algorithm 335 | | | | asymmetric-ke\ 336 \y-algorithm-ref 337 | | | +---w public-key? 338 | | | | binary 339 | | | +---w private-key? 340 | | | binary 341 | | +--rw cert? 342 | | | end-entity-cert-cms 343 | | +---n certificate-expiration 344 | | +-- expiration-date 345 | | yang:date-and-ti\ 346 \me 347 | +--:(keystore) {keystore-supporte\ 348 \d}? 349 | +--rw keystore-reference? 350 | ks:asymmetric-key-cert\ 351 \ificate-ref 352 +--rw tls-server-auth 353 | +--rw pinned-ca-certs? 354 | | ta:pinned-certificates-ref 355 | | {ta:x509-certificates}? 356 | +--rw pinned-server-certs? 357 | ta:pinned-certificates-ref 358 | {ta:x509-certificates}? 359 +--rw tls-hello-params 360 | {tls-client-hello-params-config}? 361 | +--rw tls-versions 362 | | +--rw tls-version* identityref 363 | +--rw cipher-suites 364 | +--rw cipher-suite* identityref 365 +--rw tls-keepalives {tls-client-keepalives}? 366 | +--rw max-wait? uint16 367 | +--rw max-attempts? uint8 368 +--rw http-client-identity 369 | +--rw (auth-type)? 370 | +--:(basic) 371 | | +--rw basic 372 | | +--rw user-id? string 373 | | +--rw password? string 374 | +--:(bearer) 375 | | +--rw bearer 376 | | +--rw token? string 377 | +--:(digest) 378 | | +--rw digest 379 | | +--rw username? string 380 | | +--rw password? string 381 | +--:(hoba) 382 | | +--rw hoba 383 | +--:(mutual) 384 | | +--rw mutual 385 | +--:(negotiate) 386 | | +--rw negotiate 387 | +--:(oauth) 388 | | +--rw oauth 389 | +--:(scram-sha-1) 390 | | +--rw scram-sha-1 391 | +--:(scram-sha-256) 392 | | +--rw scram-sha-256 393 | +--:(vapid) 394 | +--rw vapid 395 +--rw http-keepalives {http-client-keepalives}? 396 +--rw max-wait? uint16 397 +--rw max-attempts? uint8 399 2.2. Example Usage 401 The following example illustrates configuring a RESTCONF client to 402 initiate connections, as well as listening for call-home connections. 404 This example is consistent with the examples presented in Section 3.2 405 of [I-D.ietf-netconf-keystore]. 407 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 409 412 413 414 415 corp-fw1 416 417 418 corp-fw1.example.com 419 420 corp-fw1.example.com 421 422 15 423 3 424 30 425 426 427 428 429 ct:rsa2048 432 base64encodedvalue== 433 base64encodedvalue== 434 base64encodedvalue== 435 436 437 438 439 explicitly-trusted-server-ca-certs 441 explicitly-trusted-server-certs 443 444 445 30 446 3 447 448 449 450 bob 451 secret 452 453 454 455 30 456 3 457 458 459 460 461 462 463 464 corp-fw2.example.com 465 466 corp-fw2.example.com 467 468 15 469 3 470 30 471 472 473 474 475 ct:rsa2048 477 base64encodedvalue== 478 base64encodedvalue== 479 base64encodedvalue== 480 481 482 483 484 explicitly-trusted-server-ca-certs 486 explicitly-trusted-server-certs 488 489 490 30 491 3 492 493 494 495 bob 496 secret 497 498 499 500 30 501 3 502 503 504 505 506 507 508 509 510 512 513 514 515 Intranet-facing listener 516 517 11.22.33.44 518 519 520 521 ct:rsa2048 523 base64encodedvalue== 524 base64encodedvalue== 525 base64encodedvalue== 526 528 529 530 531 explicitly-trusted-server-ca-certs 533 explicitly-trusted-server-certs 535 536 537 538 539 541 2.3. YANG Module 543 This YANG module has normative references to [RFC6991], [RFC8040], 544 and [RFC8071], [I-D.kwatsen-netconf-tcp-client-server], 545 [I-D.ietf-netconf-tls-client-server], and 546 [I-D.kwatsen-netconf-http-client-server]. 548 file "ietf-restconf-client@2019-03-09.yang" 549 module ietf-restconf-client { 550 yang-version 1.1; 551 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 552 prefix rcc; 554 import ietf-yang-types { 555 prefix yang; 556 reference 557 "RFC 6991: Common YANG Data Types"; 558 } 560 import ietf-tcp-client { 561 prefix tcpc; 562 reference 563 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 564 } 566 import ietf-tcp-server { 567 prefix tcps; 568 reference 569 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 570 } 572 import ietf-tls-client { 573 prefix tlsc; 574 reference 575 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 577 } 579 import ietf-http-client { 580 prefix httpc; 581 reference 582 "RFC CCCC: YANG Groupings for HTTP Clients and HTTP Servers"; 583 } 585 organization 586 "IETF NETCONF (Network Configuration) Working Group"; 588 contact 589 "WG Web: 590 WG List: 591 Author: Kent Watsen 592 Author: Gary Wu "; 594 description 595 "This module contains a collection of YANG definitions for 596 configuring RESTCONF clients. 598 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 599 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 600 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 601 are to be interpreted as described in BCP 14 [RFC2119] 602 [RFC8174] when, and only when, they appear in all 603 capitals, as shown here. 605 Copyright (c) 2019 IETF Trust and the persons identified as 606 authors of the code. All rights reserved. 608 Redistribution and use in source and binary forms, with or 609 without modification, is permitted pursuant to, and subject 610 to the license terms contained in, the Simplified BSD 611 License set forth in Section 4.c of the IETF Trust's 612 Legal Provisions Relating to IETF Documents 613 (http://trustee.ietf.org/license-info). 615 This version of this YANG module is part of RFC XXXX; see 616 the RFC itself for full legal notices."; 618 revision 2019-03-09 { 619 description 620 "Initial version"; 621 reference 622 "RFC XXXX: RESTCONF Client and Server Models"; 623 } 624 // Features 626 feature initiate { 627 description 628 "The 'initiate' feature indicates that the RESTCONF client 629 supports initiating RESTCONF connections to RESTCONF servers 630 using at least one transport (e.g., HTTPS, etc.)."; 631 } 633 feature https-initiate { 634 if-feature "initiate"; 635 description 636 "The 'https-initiate' feature indicates that the RESTCONF 637 client supports initiating HTTPS connections to RESTCONF 638 servers. This feature exists as HTTPS might not be a 639 mandatory to implement transport in the future."; 640 reference 641 "RFC 8040: RESTCONF Protocol"; 642 } 644 feature listen { 645 description 646 "The 'listen' feature indicates that the RESTCONF client 647 supports opening a port to accept RESTCONF server call 648 home connections using at least one transport (e.g., 649 HTTPS, etc.)."; 650 } 652 feature https-listen { 653 if-feature "listen"; 654 description 655 "The 'https-listen' feature indicates that the RESTCONF client 656 supports opening a port to listen for incoming RESTCONF 657 server call-home connections. This feature exists as not 658 all RESTCONF clients may support RESTCONF call home."; 659 reference 660 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 661 } 663 // Groupings 665 grouping restconf-client-grouping { 666 description 667 "Top-level grouping for RESTCONF client configuration."; 668 container initiate { 669 if-feature "initiate"; 670 presence "Enables client to initiate TCP connections"; 671 description 672 "Configures client initiating underlying TCP connections."; 673 list restconf-server { 674 key "name"; 675 min-elements 1; 676 description 677 "List of RESTCONF servers the RESTCONF client is to 678 initiate connections to in parallel."; 679 leaf name { 680 type string; 681 description 682 "An arbitrary name for the RESTCONF server."; 683 } 684 container endpoints { 685 description 686 "Container for the list of endpoints."; 687 list endpoint { 688 key "name"; 689 min-elements 1; 690 ordered-by user; 691 description 692 "A non-empty user-ordered list of endpoints for this 693 RESTCONF client to try to connect to in sequence. 694 Defining more than one enables high-availability."; 695 leaf name { 696 type string; 697 description 698 "An arbitrary name for this endpoint."; 699 } 700 choice transport { 701 mandatory true; 702 description 703 "Selects between available transports. This is a 704 'choice' statement so as to support additional 705 transport options to be augmented in."; 706 case https { 707 if-feature "https-initiate"; 708 container https { 709 description 710 "Specifies HTTPS-specific transport 711 configuration."; 712 uses tcpc:tcp-client-grouping { 713 refine "remote-port" { 714 default "443"; 715 description 716 "The RESTCONF client will attempt to 717 connect to the IANA-assigned well-known 718 port value for 'https' (443) if no value 719 is specified."; 721 } 722 } 723 uses tlsc:tls-client-grouping { 724 refine "tls-client-identity/auth-type" { 725 mandatory true; 726 description 727 "RESTCONF clients MUST pass some 728 authentication credentials."; 729 } 730 } 731 uses httpc:http-client-grouping; 732 } 733 } // https 734 } // transport 735 container connection-type { 736 description 737 "Indicates the RESTCONF client's preference for how 738 the RESTCONF connection is maintained."; 739 choice connection-type { 740 mandatory true; 741 description 742 "Selects between available connection types."; 743 case persistent-connection { 744 container persistent { 745 presence "Indicates that a persistent connection 746 is to be maintained."; 747 description 748 "Maintain a persistent connection to the 749 RESTCONF server. If the connection goes down, 750 immediately start trying to reconnect to it, 751 using the reconnection strategy. This 752 connection type minimizes any RESTCONF server 753 to RESTCONF client data-transfer delay, albeit 754 at the expense of holding resources longer."; 755 } 756 } 757 case periodic-connection { 758 container periodic { 759 presence "Indicates that a periodic connection is 760 to be maintained."; 761 description 762 "Periodically connect to the RESTCONF server. 763 The RESTCONF server should close the 764 underlying TCP connection upon completing 765 planned activities. 767 This connection type increases resource 768 utilization, albeit with increased delay in 769 RESTCONF server to RESTCONF client 770 interactions."; 771 leaf period { 772 type uint16; 773 units "minutes"; 774 default "60"; 775 description 776 "Duration of time between periodic 777 connections."; 778 } 779 leaf anchor-time { 780 type yang:date-and-time { 781 // constrained to minute-level granularity 782 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 783 + '(Z|[\+\-]\d{2}:\d{2})'; 784 } 785 description 786 "Designates a timestamp before or after which 787 a series of periodic connections are 788 determined. The periodic connections occur 789 at a whole multiple interval from the anchor 790 time. For example, for an anchor time is 15 791 minutes past midnight and a period interval 792 of 24 hours, then a periodic connection will 793 occur 15 minutes past midnight everyday."; 794 } 795 leaf idle-timeout { 796 type uint16; 797 units "seconds"; 798 default 120; // two minutes 799 description 800 "Specifies the maximum number of seconds 801 that the underlying TCP session may remain 802 idle. A TCP session will be dropped if it 803 is idle for an interval longer than this 804 number of seconds If set to zero, then the 805 RESTCONF client will never drop a session 806 because it is idle."; 807 } 808 } 809 } // periodic-connection 810 } // connection-type 811 } // connection-type 812 container reconnect-strategy { 813 description 814 "The reconnection strategy directs how a RESTCONF 815 client reconnects to a RESTCONF server, after 816 discovering its connection to the server has 817 dropped, even if due to a reboot. The RESTCONF 818 client starts with the specified endpoint and 819 tries to connect to it max-attempts times before 820 trying the next endpoint in the list (round 821 robin)."; 822 leaf start-with { 823 type enumeration { 824 enum first-listed { 825 description 826 "Indicates that reconnections should start 827 with the first endpoint listed."; 828 } 829 enum last-connected { 830 description 831 "Indicates that reconnections should start 832 with the endpoint last connected to. If 833 no previous connection has ever been 834 established, then the first endpoint 835 configured is used. RESTCONF clients 836 SHOULD be able to remember the last 837 endpoint connected to across reboots."; 838 } 839 enum random-selection { 840 description 841 "Indicates that reconnections should start with 842 a random endpoint."; 843 } 844 } 845 default "first-listed"; 846 description 847 "Specifies which of the RESTCONF server's 848 endpoints the RESTCONF client should start 849 with when trying to connect to the RESTCONF 850 server."; 851 } 852 leaf max-attempts { 853 type uint8 { 854 range "1..max"; 855 } 856 default "3"; 857 description 858 "Specifies the number times the RESTCONF client 859 tries to connect to a specific endpoint before 860 moving on to the next endpoint in the list 861 (round robin)."; 862 } 863 } // reconnect-strategy 864 } // endpoint 866 } // endpoints 867 } // restconf-server 868 } // initiate 870 container listen { 871 if-feature "listen"; 872 presence "Enables client to accept call-home connections"; 873 description 874 "Configures client accepting call-home TCP connections."; 875 leaf idle-timeout { 876 type uint16; 877 units "seconds"; 878 default 3600; // one hour 879 description 880 "Specifies the maximum number of seconds that an 881 underlying TCP session may remain idle. A TCP session 882 will be dropped if it is idle for an interval longer 883 than this number of seconds. If set to zero, then 884 the server will never drop a session because it is 885 idle. Sessions that have a notification subscription 886 active are never dropped."; 887 } 888 list endpoint { 889 key "name"; 890 min-elements 1; 891 description 892 "List of endpoints to listen for RESTCONF connections."; 893 leaf name { 894 type string; 895 description 896 "An arbitrary name for the RESTCONF listen endpoint."; 897 } 898 choice transport { 899 mandatory true; 900 description 901 "Selects between available transports. This is a 902 'choice' statement so as to support additional 903 transport options to be augmented in."; 904 case https { 905 if-feature "https-listen"; 906 container https { 907 description 908 "HTTPS-specific listening configuration for inbound 909 connections."; 910 uses tcps:tcp-server-grouping { 911 refine "local-port" { 912 default "4336"; 913 description 914 "The RESTCONF client will listen on the IANA- 915 assigned well-known port for 'restconf-ch-tls' 916 (4336) if no value is specified."; 917 } 918 } 919 uses tlsc:tls-client-grouping { 920 refine "tls-client-identity/auth-type" { 921 mandatory true; 922 description 923 "RESTCONF clients MUST pass some authentication 924 credentials."; 925 } 926 } 927 uses httpc:http-client-grouping; 928 } 929 } // case https 930 } // transport 931 } // endpoint 932 } // listen 933 } // restconf-client 935 // Protocol accessible node, for servers that implement this 936 // module. 938 container restconf-client { 939 uses restconf-client-grouping; 940 description 941 "Top-level container for RESTCONF client configuration."; 942 } 943 } 944 946 3. The RESTCONF Server Model 948 The RESTCONF server model presented in this section supports servers 949 both listening for connections as well as initiating call-home 950 connections. 952 All private keys and trusted certificates are held in the keystore 953 model defined in [I-D.ietf-netconf-keystore]. 955 YANG feature statements are used to enable implementations to 956 advertise which parts of the model the RESTCONF server supports. 958 3.1. Tree Diagram 960 The following tree diagram [RFC8340] provides an overview of the data 961 model for the "ietf-restconf-server" module. Just the container is 962 displayed below, but there is also a reusable grouping called 963 "restconf-server-grouping" that the container is using. 965 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 967 module: ietf-restconf-server 968 +--rw restconf-server 969 +--rw listen! {listen}? 970 | +--rw endpoint* [name] 971 | +--rw name string 972 | +--rw (transport) 973 | +--:(https) {https-listen}? 974 | +--rw https 975 | +--rw local-address inet:ip-address 976 | +--rw local-port? inet:port-number 977 | +--rw tcp-keepalives {tcp-server-keepalives}? 978 | | +--rw idle-time? uint16 979 | | +--rw max-probes? uint16 980 | | +--rw probe-interval? uint16 981 | +--rw tls-server-identity 982 | | +--rw (local-or-keystore) 983 | | +--:(local) {local-keys-supported}? 984 | | | +--rw local-definition 985 | | | +--rw algorithm? 986 | | | | asymmetric-key-algorithm-ref 987 | | | +--rw public-key? bina\ 988 \ry 989 | | | +--rw private-key? union 990 | | | +---x generate-hidden-key 991 | | | | +---w input 992 | | | | +---w algorithm 993 | | | | asymmetric-key-algorit\ 994 \hm-ref 995 | | | +---x install-hidden-key 996 | | | | +---w input 997 | | | | +---w algorithm 998 | | | | | asymmetric-key-algorit\ 999 \hm-ref 1000 | | | | +---w public-key? binary 1001 | | | | +---w private-key? binary 1002 | | | +--rw cert? 1003 | | | | end-entity-cert-cms 1004 | | | +---n certificate-expiration 1005 | | | +-- expiration-date 1006 | | | yang:date-and-time 1007 | | +--:(keystore) {keystore-supported}? 1008 | | +--rw keystore-reference? 1009 | | ks:asymmetric-key-certificate-r\ 1010 \ef 1011 | +--rw tls-client-auth 1012 | | +--rw pinned-ca-certs? 1013 | | | ta:pinned-certificates-ref 1014 | | | {ta:x509-certificates}? 1015 | | +--rw pinned-client-certs? 1016 | | | ta:pinned-certificates-ref 1017 | | | {ta:x509-certificates}? 1018 | | +--rw cert-maps 1019 | | +--rw cert-to-name* [id] 1020 | | +--rw id uint32 1021 | | +--rw fingerprint 1022 | | | x509c2n:tls-fingerprint 1023 | | +--rw map-type identityref 1024 | | +--rw name string 1025 | +--rw tls-hello-params 1026 | | {tls-server-hello-params-config}? 1027 | | +--rw tls-versions 1028 | | | +--rw tls-version* identityref 1029 | | +--rw cipher-suites 1030 | | +--rw cipher-suite* identityref 1031 | +--rw tls-keepalives {tls-server-keepalives}? 1032 | | +--rw max-wait? uint16 1033 | | +--rw max-attempts? uint8 1034 | +--rw http-keepalives {http-server-keepalives}? 1035 | +--rw max-wait? uint16 1036 | +--rw max-attempts? uint8 1037 +--rw call-home! {call-home}? 1038 +--rw restconf-client* [name] 1039 +--rw name string 1040 +--rw endpoints 1041 | +--rw endpoint* [name] 1042 | +--rw name string 1043 | +--rw (transport) 1044 | +--:(https) {https-call-home}? 1045 | +--rw https 1046 | +--rw remote-address inet:host 1047 | +--rw remote-port? inet:port-num\ 1048 \ber 1049 | +--rw local-address? inet:ip-addre\ 1050 \ss 1051 | +--rw local-port? inet:port-num\ 1052 \ber 1053 | +--rw tcp-keepalives {tcp-client-keepalive\ 1055 \s}? 1056 | | +--rw idle-time? uint16 1057 | | +--rw max-probes? uint16 1058 | | +--rw probe-interval? uint16 1059 | +--rw tls-server-identity 1060 | | +--rw (local-or-keystore) 1061 | | +--:(local) {local-keys-supported}? 1062 | | | +--rw local-definition 1063 | | | +--rw algorithm? 1064 | | | | asymmetric-key-algorit\ 1065 \hm-ref 1066 | | | +--rw public-key? 1067 | | | | binary 1068 | | | +--rw private-key? 1069 | | | | union 1070 | | | +---x generate-hidden-key 1071 | | | | +---w input 1072 | | | | +---w algorithm 1073 | | | | asymmetric-key-a\ 1074 \lgorithm-ref 1075 | | | +---x install-hidden-key 1076 | | | | +---w input 1077 | | | | +---w algorithm 1078 | | | | | asymmetric-key-a\ 1079 \lgorithm-ref 1080 | | | | +---w public-key? bin\ 1081 \ary 1082 | | | | +---w private-key? bin\ 1083 \ary 1084 | | | +--rw cert? 1085 | | | | end-entity-cert-cms 1086 | | | +---n certificate-expiration 1087 | | | +-- expiration-date 1088 | | | yang:date-and-time 1089 | | +--:(keystore) {keystore-supported}? 1090 | | +--rw keystore-reference? 1091 | | ks:asymmetric-key-certifi\ 1092 \cate-ref 1093 | +--rw tls-client-auth 1094 | | +--rw pinned-ca-certs? 1095 | | | ta:pinned-certificates-ref 1096 | | | {ta:x509-certificates}? 1097 | | +--rw pinned-client-certs? 1098 | | | ta:pinned-certificates-ref 1099 | | | {ta:x509-certificates}? 1100 | | +--rw cert-maps 1101 | | +--rw cert-to-name* [id] 1102 | | +--rw id uint32 1103 | | +--rw fingerprint 1104 | | | x509c2n:tls-fingerprint 1105 | | +--rw map-type identityref 1106 | | +--rw name string 1107 | +--rw tls-hello-params 1108 | | {tls-server-hello-params-config}? 1109 | | +--rw tls-versions 1110 | | | +--rw tls-version* identityref 1111 | | +--rw cipher-suites 1112 | | +--rw cipher-suite* identityref 1113 | +--rw tls-keepalives {tls-server-keepalive\ 1114 \s}? 1115 | | +--rw max-wait? uint16 1116 | | +--rw max-attempts? uint8 1117 | +--rw http-keepalives 1118 | {http-server-keepalives}? 1119 | +--rw max-wait? uint16 1120 | +--rw max-attempts? uint8 1121 +--rw connection-type 1122 | +--rw (connection-type) 1123 | +--:(persistent-connection) 1124 | | +--rw persistent! 1125 | +--:(periodic-connection) 1126 | +--rw periodic! 1127 | +--rw period? uint16 1128 | +--rw anchor-time? yang:date-and-time 1129 | +--rw idle-timeout? uint16 1130 +--rw reconnect-strategy 1131 +--rw start-with? enumeration 1132 +--rw max-attempts? uint8 1134 3.2. Example Usage 1136 The following example illustrates configuring a RESTCONF server to 1137 listen for RESTCONF client connections, as well as configuring call- 1138 home to one RESTCONF client. 1140 This example is consistent with the examples presented in Section 3.2 1141 of [I-D.ietf-netconf-keystore]. 1143 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1145 1149 1150 1151 1152 netconf/tls 1153 1154 11.22.33.44 1155 1156 1157 ct:rsa2048 1159 base64encodedvalue== 1160 base64encodedvalue== 1161 base64encodedvalue== 1162 1163 1164 1165 explicitly-trusted-client-ca-certs 1167 explicitly-trusted-client-certs 1169 1170 1171 1 1172 11:0A:05:11:00 1173 x509c2n:san-any 1174 1175 1176 2 1177 B3:4F:A1:8C:54 1178 x509c2n:specified 1179 scooby-doo 1180 1181 1182 1183 1184 1185 1187 1188 1189 1190 config-manager 1191 1192 1193 east-data-center 1194 1195 east.example.com 1196 1197 1198 ct:rsa2048 1201 base64encodedvalue== 1202 base64encodedvalue== 1203 base64encodedvalue== 1204 1205 1206 1207 explicitly-trusted-client-ca-certs 1209 explicitly-trusted-client-certs 1211 1212 1213 1 1214 11:0A:05:11:00 1215 x509c2n:san-any 1216 1217 1218 2 1219 B3:4F:A1:8C:54 1220 x509c2n:specified 1221 scooby-doo 1222 1223 1224 1225 1226 1227 1228 west-data-center 1229 1230 west.example.com 1231 1232 15 1233 3 1234 30 1235 1236 1237 1238 ct:rsa2048 1240 base64encodedvalue== 1241 base64encodedvalue== 1242 base64encodedvalue== 1243 1244 1245 1246 explicitly-trusted-client-ca-certs 1248 explicitly-trusted-client-certs 1250 1251 1252 1 1253 11:0A:05:11:00 1254 x509c2n:san-any 1255 1256 1257 2 1258 B3:4F:A1:8C:54 1259 x509c2n:specified 1260 scooby-doo 1261 1262 1263 1264 1265 30 1266 3 1267 1268 1269 1270 1271 1272 1273 300 1274 60 1275 1276 1277 1278 last-connected 1279 3 1280 1281 1282 1283 1285 3.3. YANG Module 1287 This YANG module has normative references to [RFC6991], [RFC7407], 1288 [RFC8040], [RFC8071], [I-D.kwatsen-netconf-tcp-client-server], 1289 [I-D.ietf-netconf-tls-client-server], and 1290 [I-D.kwatsen-netconf-http-client-server]. 1292 file "ietf-restconf-server@2019-03-09.yang" 1293 module ietf-restconf-server { 1294 yang-version 1.1; 1295 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 1296 prefix rcs; 1298 import ietf-yang-types { 1299 prefix yang; 1300 reference 1301 "RFC 6991: Common YANG Data Types"; 1302 } 1304 import ietf-x509-cert-to-name { 1305 prefix x509c2n; 1306 reference 1307 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1308 } 1310 import ietf-tcp-client { 1311 prefix tcpc; 1312 reference 1313 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1314 } 1316 import ietf-tcp-server { 1317 prefix tcps; 1318 reference 1319 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1320 } 1322 import ietf-tls-server { 1323 prefix tlss; 1324 reference 1325 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 1326 } 1328 import ietf-http-server { 1329 prefix https; 1330 reference 1331 "RFC CCCC: YANG Groupings for HTTP Clients and HTTP Servers"; 1332 } 1334 organization 1335 "IETF NETCONF (Network Configuration) Working Group"; 1337 contact 1338 "WG Web: 1339 WG List: 1340 Author: Kent Watsen 1341 Author: Gary Wu 1342 Author: Juergen Schoenwaelder 1343 "; 1345 description 1346 "This module contains a collection of YANG definitions for 1347 configuring RESTCONF servers. 1349 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1350 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1351 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1352 are to be interpreted as described in BCP 14 [RFC2119] 1353 [RFC8174] when, and only when, they appear in all 1354 capitals, as shown here. 1356 Copyright (c) 2019 IETF Trust and the persons identified as 1357 authors of the code. All rights reserved. 1359 Redistribution and use in source and binary forms, with or 1360 without modification, is permitted pursuant to, and subject 1361 to the license terms contained in, the Simplified BSD 1362 License set forth in Section 4.c of the IETF Trust's 1363 Legal Provisions Relating to IETF Documents 1364 (http://trustee.ietf.org/license-info). 1366 This version of this YANG module is part of RFC XXXX; see 1367 the RFC itself for full legal notices."; 1369 revision 2019-03-09 { 1370 description 1371 "Initial version"; 1372 reference 1373 "RFC XXXX: RESTCONF Client and Server Models"; 1374 } 1376 // Features 1378 feature listen { 1379 description 1380 "The 'listen' feature indicates that the RESTCONF server 1381 supports opening a port to accept RESTCONF client connections 1382 using at least one transport (e.g., HTTPS, etc.)."; 1383 } 1385 feature https-listen { 1386 if-feature "listen"; 1387 description 1388 "The 'https-listen' feature indicates that the RESTCONF server 1389 supports opening a port to listen for incoming RESTCONF 1390 client connections. This feature exists as HTTPS might not 1391 be a mandatory to implement transport in the future."; 1392 reference 1393 "RFC 8040: RESTCONF Protocol"; 1394 } 1396 feature call-home { 1397 description 1398 "The 'call-home' feature indicates that the RESTCONF 1399 server supports initiating RESTCONF call home connections 1400 to RESTCONF clients using at least one transport (e.g., 1401 HTTPS, etc.)."; 1402 reference 1403 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1404 } 1406 feature https-call-home { 1407 if-feature "call-home"; 1408 description 1409 "The 'https-call-home' feature indicates that the RESTCONF 1410 server supports initiating connections to RESTCONF clients. 1411 This feature exists as not all RESTCONF servers may 1412 support RESTCONF call home."; 1413 reference 1414 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1415 } 1417 // Groupings 1419 grouping restconf-server-grouping { 1420 description 1421 "Top-level grouping for RESTCONF server configuration."; 1422 container listen { 1423 if-feature "listen"; 1424 presence "Enables server to listen for TCP connections"; 1425 description "Configures listen behavior"; 1426 list endpoint { 1427 key "name"; 1428 min-elements 1; 1429 description 1430 "List of endpoints to listen for RESTCONF connections."; 1431 leaf name { 1432 type string; 1433 description 1434 "An arbitrary name for the RESTCONF listen endpoint."; 1435 } 1436 choice transport { 1437 mandatory true; 1438 description 1439 "Selects between available transports. This is a 1440 'choice' statement so as to support additional 1441 transport options to be augmented in."; 1442 case https { 1443 if-feature "https-listen"; 1444 container https { 1445 description 1446 "HTTPS-specific listening configuration for inbound 1447 connections."; 1448 uses tcps:tcp-server-grouping { 1449 refine "local-port" { 1450 default "443"; 1451 description 1452 "The RESTCONF server will listen on the IANA- 1453 assigned well-known port value for 'https' 1454 (443) if no value is specified."; 1455 } 1456 } 1457 uses tlss:tls-server-grouping { 1458 refine "tls-client-auth" { 1459 must 'pinned-ca-certs or pinned-client-certs'; 1460 description 1461 "RESTCONF servers MUST be able to validate 1462 clients."; 1463 } 1464 augment "tls-client-auth" { 1465 description 1466 "Augments in the cert-to-name structure, 1467 so the RESTCONF server can map TLS-layer 1468 client certificates to RESTCONF usernames."; 1469 container cert-maps { 1470 uses x509c2n:cert-to-name; 1471 description 1472 "The cert-maps container is used by a TLS- 1473 based RESTCONF server to map the RESTCONF 1474 client's presented X.509 certificate to 1475 a RESTCONF username. If no matching and 1476 valid cert-to-name list entry can be found, 1477 then the RESTCONF server MUST close the 1478 connection, and MUST NOT accept RESTCONF 1479 messages over it."; 1480 reference 1481 "RFC 7407: A YANG Data Model for SNMP 1482 Configuration."; 1483 } 1484 } 1485 } 1486 uses https:http-server-grouping; 1488 } // https container 1489 } // tls case 1490 } // transport 1491 } // endpoint 1492 } // listen 1494 container call-home { 1495 if-feature "call-home"; 1496 presence "Enables server to initiate TCP connections"; 1497 description "Configures call-home behavior"; 1498 list restconf-client { 1499 key "name"; 1500 min-elements 1; 1501 description 1502 "List of RESTCONF clients the RESTCONF server is to 1503 initiate call-home connections to in parallel."; 1504 leaf name { 1505 type string; 1506 description 1507 "An arbitrary name for the remote RESTCONF client."; 1508 } 1509 container endpoints { 1510 description 1511 "Container for the list of endpoints."; 1512 list endpoint { 1513 key "name"; 1514 min-elements 1; 1515 ordered-by user; 1516 description 1517 "User-ordered list of endpoints for this RESTCONF 1518 client. Defining more than one enables high- 1519 availability."; 1520 leaf name { 1521 type string; 1522 description 1523 "An arbitrary name for this endpoint."; 1524 } 1525 choice transport { 1526 mandatory true; 1527 description 1528 "Selects between available transports. This is a 1529 'choice' statement so as to support additional 1530 transport options to be augmented in."; 1531 case https { 1532 if-feature "https-call-home"; 1533 container https { 1534 description 1535 "Specifies HTTPS-specific call-home transport 1536 configuration."; 1537 uses tcpc:tcp-client-grouping { 1538 refine "remote-port" { 1539 default "4336"; 1540 description 1541 "The RESTCONF server will attempt to connect 1542 to the IANA-assigned well-known port for 1543 'restconf-ch-tls' (4336) if no value is 1544 specified."; 1545 } 1546 } 1547 uses tlss:tls-server-grouping { 1548 refine "tls-client-auth" { 1549 must 'pinned-ca-certs or pinned-client-certs'; 1550 description 1551 "RESTCONF servers MUST be able to validate 1552 clients."; 1553 } 1554 augment "tls-client-auth" { 1555 description 1556 "Augments in the cert-to-name structure, 1557 so the RESTCONF server can map TLS-layer 1558 client certificates to RESTCONF usernames."; 1559 container cert-maps { 1560 uses x509c2n:cert-to-name; 1561 description 1562 "The cert-maps container is used by a 1563 TLS-based RESTCONF server to map the 1564 RESTCONF client's presented X.509 1565 certificate to a RESTCONF username. If 1566 no matching and valid cert-to-name list 1567 entry can be found, then the RESTCONF 1568 server MUST close the connection, and 1569 MUST NOT accept RESTCONF messages over 1570 it."; 1571 reference 1572 "RFC 7407: A YANG Data Model for SNMP 1573 Configuration."; 1574 } 1575 } 1576 } 1577 uses https:http-server-grouping; 1578 } 1579 } 1580 } // transport 1581 } // endpoint 1582 } // endpoints 1583 container connection-type { 1584 description 1585 "Indicates the RESTCONF server's preference for how the 1586 RESTCONF connection is maintained."; 1587 choice connection-type { 1588 mandatory true; 1589 description 1590 "Selects between available connection types."; 1591 case persistent-connection { 1592 container persistent { 1593 presence "Indicates that a persistent connection is 1594 to be maintained."; 1595 description 1596 "Maintain a persistent connection to the RESTCONF 1597 client. If the connection goes down, immediately 1598 start trying to reconnect to it, using the 1599 reconnection strategy. 1601 This connection type minimizes any RESTCONF 1602 client to RESTCONF server data-transfer delay, 1603 albeit at the expense of holding resources 1604 longer."; 1605 } 1606 } 1607 case periodic-connection { 1608 container periodic { 1609 presence "Indicates that a periodic connection is 1610 to be maintained."; 1611 description 1612 "Periodically connect to the RESTCONF client. The 1613 RESTCONF client should close the underlying TCP 1614 connection upon completing planned activities. 1616 This connection type increases resource 1617 utilization, albeit with increased delay in 1618 RESTCONF client to RESTCONF client interactions."; 1619 leaf period { 1620 type uint16; 1621 units "minutes"; 1622 default "60"; 1623 description 1624 "Duration of time between periodic connections."; 1625 } 1626 leaf anchor-time { 1627 type yang:date-and-time { 1628 // constrained to minute-level granularity 1629 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 1630 + '(Z|[\+\-]\d{2}:\d{2})'; 1631 } 1632 description 1633 "Designates a timestamp before or after which a 1634 series of periodic connections are determined. 1635 The periodic connections occur at a whole 1636 multiple interval from the anchor time. For 1637 example, for an anchor time is 15 minutes past 1638 midnight and a period interval of 24 hours, then 1639 a periodic connection will occur 15 minutes past 1640 midnight everyday."; 1641 } 1642 leaf idle-timeout { 1643 type uint16; 1644 units "seconds"; 1645 default 120; // two minutes 1646 description 1647 "Specifies the maximum number of seconds that 1648 the underlying TCP session may remain idle. 1649 A TCP session will be dropped if it is idle 1650 for an interval longer than this number of 1651 seconds. If set to zero, then the server 1652 will never drop a session because it is idle."; 1653 } 1654 } 1655 } 1656 } 1657 } 1658 container reconnect-strategy { 1659 description 1660 "The reconnection strategy directs how a RESTCONF server 1661 reconnects to a RESTCONF client after discovering its 1662 connection to the client has dropped, even if due to a 1663 reboot. The RESTCONF server starts with the specified 1664 endpoint and tries to connect to it max-attempts times 1665 before trying the next endpoint in the list (round 1666 robin)."; 1667 leaf start-with { 1668 type enumeration { 1669 enum first-listed { 1670 description 1671 "Indicates that reconnections should start with 1672 the first endpoint listed."; 1673 } 1674 enum last-connected { 1675 description 1676 "Indicates that reconnections should start with 1677 the endpoint last connected to. If no previous 1678 connection has ever been established, then the 1679 first endpoint configured is used. RESTCONF 1680 servers SHOULD be able to remember the last 1681 endpoint connected to across reboots."; 1682 } 1683 enum random-selection { 1684 description 1685 "Indicates that reconnections should start with 1686 a random endpoint."; 1687 } 1688 } 1689 default "first-listed"; 1690 description 1691 "Specifies which of the RESTCONF client's endpoints 1692 the RESTCONF server should start with when trying 1693 to connect to the RESTCONF client."; 1694 } 1695 leaf max-attempts { 1696 type uint8 { 1697 range "1..max"; 1698 } 1699 default "3"; 1700 description 1701 "Specifies the number times the RESTCONF server tries 1702 to connect to a specific endpoint before moving on to 1703 the next endpoint in the list (round robin)."; 1704 } 1705 } 1706 } // restconf-client 1707 } // call-home 1708 } // restconf-server-grouping 1710 // Protocol accessible node, for servers that implement this 1711 // module. 1713 container restconf-server { 1714 uses restconf-server-grouping; 1715 description 1716 "Top-level container for RESTCONF server configuration."; 1717 } 1718 } 1719 1721 4. Security Considerations 1723 The YANG module defined in this document uses a grouping defined in 1724 [I-D.ietf-netconf-tls-client-server]. Please see the Security 1725 Considerations section in that document for concerns related that 1726 grouping. 1728 The YANG module defined in this document is designed to be accessed 1729 via YANG based management protocols, such as NETCONF [RFC6241] and 1730 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1731 implement secure transport layers (e.g., SSH, TLS) with mutual 1732 authentication. 1734 The NETCONF access control model (NACM) [RFC8341] provides the means 1735 to restrict access for particular users to a pre-configured subset of 1736 all available protocol operations and content. 1738 There are a number of data nodes defined in this YANG module that are 1739 writable/creatable/deletable (i.e., config true, which is the 1740 default). These data nodes may be considered sensitive or vulnerable 1741 in some network environments. Write operations (e.g., edit-config) 1742 to these data nodes without proper protection can have a negative 1743 effect on network operations. These are the subtrees and data nodes 1744 and their sensitivity/vulnerability: 1746 /: The entire data trees defined by the modules defined in this 1747 draft are sensitive to write operations. For instance, the 1748 addition or removal of references to keys, certificates, 1749 trusted anchors, etc., can dramatically alter the implemented 1750 security policy. However, no NACM annotations are applied as 1751 the data SHOULD be editable by users other than a designated 1752 'recovery session'. 1754 Some of the readable data nodes in this YANG module may be considered 1755 sensitive or vulnerable in some network environments. It is thus 1756 important to control read access (e.g., via get, get-config, or 1757 notification) to these data nodes. These are the subtrees and data 1758 nodes and their sensitivity/vulnerability: 1760 NONE 1762 Some of the RPC operations in this YANG module may be considered 1763 sensitive or vulnerable in some network environments. It is thus 1764 important to control access to these operations. These are the 1765 operations and their sensitivity/vulnerability: 1767 NONE 1769 5. IANA Considerations 1771 5.1. The IETF XML Registry 1773 This document registers two URIs in the "ns" subregistry of the IETF 1774 XML Registry [RFC3688]. Following the format in [RFC3688], the 1775 following registrations are requested: 1777 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1778 Registrant Contact: The NETCONF WG of the IETF. 1779 XML: N/A, the requested URI is an XML namespace. 1781 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1782 Registrant Contact: The NETCONF WG of the IETF. 1783 XML: N/A, the requested URI is an XML namespace. 1785 5.2. The YANG Module Names Registry 1787 This document registers two YANG modules in the YANG Module Names 1788 registry [RFC6020]. Following the format in [RFC6020], the the 1789 following registrations are requested: 1791 name: ietf-restconf-client 1792 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1793 prefix: ncc 1794 reference: RFC XXXX 1796 name: ietf-restconf-server 1797 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1798 prefix: ncs 1799 reference: RFC XXXX 1801 6. References 1803 6.1. Normative References 1805 [I-D.ietf-netconf-keystore] 1806 Watsen, K., "YANG Data Model for a Centralized Keystore 1807 Mechanism", draft-ietf-netconf-keystore-08 (work in 1808 progress), March 2019. 1810 [I-D.ietf-netconf-tls-client-server] 1811 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for TLS 1812 Clients and TLS Servers", draft-ietf-netconf-tls-client- 1813 server-08 (work in progress), October 2018. 1815 [I-D.kwatsen-netconf-http-client-server] 1816 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1817 Servers", draft-kwatsen-netconf-http-client-server-00 1818 (work in progress), March 2019. 1820 [I-D.kwatsen-netconf-tcp-client-server] 1821 Watsen, K., "YANG Groupings for TCP Clients and TCP 1822 Servers", draft-kwatsen-netconf-tcp-client-server-00 (work 1823 in progress), March 2019. 1825 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1826 Requirement Levels", BCP 14, RFC 2119, 1827 DOI 10.17487/RFC2119, March 1997, 1828 . 1830 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1831 the Network Configuration Protocol (NETCONF)", RFC 6020, 1832 DOI 10.17487/RFC6020, October 2010, 1833 . 1835 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1836 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1837 . 1839 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1840 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1841 December 2014, . 1843 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1844 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1845 . 1847 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1848 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1849 . 1851 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1852 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1853 . 1855 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1856 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1857 May 2017, . 1859 6.2. Informative References 1861 [I-D.ietf-netconf-netconf-client-server] 1862 Watsen, K., "NETCONF Client and Server Models", draft- 1863 ietf-netconf-netconf-client-server-08 (work in progress), 1864 October 2018. 1866 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1867 DOI 10.17487/RFC3688, January 2004, 1868 . 1870 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1871 and A. Bierman, Ed., "Network Configuration Protocol 1872 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1873 . 1875 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1876 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1877 . 1879 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1880 Access Control Model", STD 91, RFC 8341, 1881 DOI 10.17487/RFC8341, March 2018, 1882 . 1884 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1885 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1886 . 1888 Appendix A. Change Log 1890 A.1. 00 to 01 1892 o Renamed "keychain" to "keystore". 1894 A.2. 01 to 02 1896 o Filled in previously missing 'ietf-restconf-client' module. 1898 o Updated the ietf-restconf-server module to accomodate new grouping 1899 'ietf-tls-server-grouping'. 1901 A.3. 02 to 03 1903 o Refined use of tls-client-grouping to add a must statement 1904 indicating that the TLS client must specify a client-certificate. 1906 o Changed restconf-client??? to be a grouping (not a container). 1908 A.4. 03 to 04 1910 o Added RFC 8174 to Requirements Language Section. 1912 o Replaced refine statement in ietf-restconf-client to add a 1913 mandatory true. 1915 o Added refine statement in ietf-restconf-server to add a must 1916 statement. 1918 o Now there are containers and groupings, for both the client and 1919 server models. 1921 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1923 o Updated examples to inline key and certificates (no longer a 1924 leafref to keystore) 1926 A.5. 04 to 05 1928 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 1930 o Updated examples to inline key and certificates (no longer a 1931 leafref to keystore) 1933 A.6. 05 to 06 1935 o Fixed change log missing section issue. 1937 o Updated examples to match latest updates to the crypto-types, 1938 trust-anchors, and keystore drafts. 1940 o Reduced line length of the YANG modules to fit within 69 columns. 1942 A.7. 06 to 07 1944 o removed "idle-timeout" from "persistent" connection config. 1946 o Added "random-selection" for reconnection-strategy's "starts-with" 1947 enum. 1949 o Replaced "connection-type" choice default (persistent) with 1950 "mandatory true". 1952 o Reduced the periodic-connection's "idle-timeout" from 5 to 2 1953 minutes. 1955 o Replaced reconnect-timeout with period/anchor-time combo. 1957 A.8. 07 to 08 1959 o Modified examples to be compatible with new crypto-types algs 1961 A.9. 08 to 09 1963 o Corrected use of "mandatory true" for "address" leafs. 1965 o Updated examples to reflect update to groupings defined in the 1966 keystore draft. 1968 o Updated to use groupings defined in new TCP and HTTP drafts. 1970 o Updated copyright date, boilerplate template, affiliation, and 1971 folding algorithm. 1973 A.10. 09 to 10 1975 o Reformatted YANG modules. 1977 Acknowledgements 1979 The authors would like to thank for following for lively discussions 1980 on list and in the halls (ordered by last name): Andy Bierman, Martin 1981 Bjorklund, Benoit Claise, Ramkumar Dhanapal, Mehmet Ersue, Balazs 1982 Kovacs, David Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, 1983 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert 1984 Wijnen. 1986 Author's Address 1988 Kent Watsen 1989 Watsen Networks 1991 EMail: kent+ietf@watsen.net