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