idnits 2.17.1 draft-ietf-netconf-restconf-client-server-04.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 : ---------------------------------------------------------------------------- ** There are 11 instances of too long lines in the document, the longest one being 14 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 186 has weird spacing: '...address ine...' == Line 220 has weird spacing: '...rw name str...' == Line 740 has weird spacing: '...rw name str...' == Line 748 has weird spacing: '...rw name lea...' == Line 755 has weird spacing: '...erprint x50...' == (3 more instances...) -- The document date (July 3, 2017) is 2489 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-02 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-03 ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) -- Obsolete informational reference (is this intentional?): RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Juniper Networks 4 Intended status: Standards Track J. Schoenwaelder 5 Expires: January 4, 2018 Jacobs University Bremen 6 July 3, 2017 8 RESTCONF Client and Server Models 9 draft-ietf-netconf-restconf-client-server-04 11 Abstract 13 This document defines two YANG modules, one module to configure a 14 RESTCONF client and the other module to configure a RESTCONF server. 15 Both modules support the TLS transport protocol with both standard 16 RESTCONF and RESTCONF Call Home connections. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains many placeholder values that need to be replaced 21 with finalized values at the time of publication. This note 22 summarizes all of the substitutions that are needed. No other RFC 23 Editor instructions are specified elsewhere in this document. 25 This document contains references to other drafts in progress, both 26 in the Normative References section, as well as in body text 27 throughout. Please update the following references to reflect their 28 final RFC assignments: 30 o I-D.ietf-netconf-keystore 32 o I-D.ietf-netconf-tls-client-server 34 Artwork in this document contains shorthand references to drafts in 35 progress. Please apply the following replacements: 37 o "XXXX" --> the assigned RFC value for this draft 39 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-tls-client- 40 server 42 Artwork in this document contains placeholder values for the date of 43 publication of this draft. Please apply the following replacement: 45 o "2017-07-03" --> the publication date of this draft 47 The following Appendix section is to be removed prior to publication: 49 o Appendix A. Change Log 51 Status of This Memo 53 This Internet-Draft is submitted in full conformance with the 54 provisions of BCP 78 and BCP 79. 56 Internet-Drafts are working documents of the Internet Engineering 57 Task Force (IETF). Note that other groups may also distribute 58 working documents as Internet-Drafts. The list of current Internet- 59 Drafts is at http://datatracker.ietf.org/drafts/current/. 61 Internet-Drafts are draft documents valid for a maximum of six months 62 and may be updated, replaced, or obsoleted by other documents at any 63 time. It is inappropriate to use Internet-Drafts as reference 64 material or to cite them other than as "work in progress." 66 This Internet-Draft will expire on January 4, 2018. 68 Copyright Notice 70 Copyright (c) 2017 IETF Trust and the persons identified as the 71 document authors. All rights reserved. 73 This document is subject to BCP 78 and the IETF Trust's Legal 74 Provisions Relating to IETF Documents 75 (http://trustee.ietf.org/license-info) in effect on the date of 76 publication of this document. Please review these documents 77 carefully, as they describe your rights and restrictions with respect 78 to this document. Code Components extracted from this document must 79 include Simplified BSD License text as described in Section 4.e of 80 the Trust Legal Provisions and are provided without warranty as 81 described in the Simplified BSD License. 83 Table of Contents 85 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 86 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 87 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 88 2. The RESTCONF Client Model . . . . . . . . . . . . . . . . . . 4 89 2.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 90 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 6 91 2.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 8 92 3. The RESTCONF Server Model . . . . . . . . . . . . . . . . . . 16 93 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 17 94 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18 95 3.3. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 20 96 4. Security Considerations . . . . . . . . . . . . . . . . . . . 29 97 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 98 5.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 30 99 5.2. The YANG Module Names Registry . . . . . . . . . . . . . 31 100 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 31 101 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 102 7.1. Normative References . . . . . . . . . . . . . . . . . . 31 103 7.2. Informative References . . . . . . . . . . . . . . . . . 32 104 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 34 105 A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 34 106 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 34 107 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 34 108 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 34 109 A.5. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 34 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 112 1. Introduction 114 This document defines two YANG [RFC7950] modules, one module to 115 configure a RESTCONF client and the other module to configure a 116 RESTCONF server [RFC8040]. Both modules support the TLS [RFC5246] 117 transport protocol with both standard RESTCONF and RESTCONF Call Home 118 connections [RFC8071]. 120 1.1. Terminology 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 124 "OPTIONAL" in this document are to be interpreted as described in BCP 125 14 [RFC2119] [RFC8174] when, and only when, they appear in all 126 capitals, as shown here. 128 1.2. Tree Diagrams 130 A simplified graphical representation of the data models is used in 131 this document. The meaning of the symbols in these diagrams is as 132 follows: 134 o Brackets "[" and "]" enclose list keys. 136 o Braces "{" and "}" enclose feature names, and indicate that the 137 named feature must be present for the subtree to be present. 139 o Abbreviations before data node names: "rw" means configuration 140 (read-write) and "ro" state data (read-only). 142 o Symbols after data node names: "?" means an optional node, "!" 143 means a presence container, and "*" denotes a list and leaf-list. 145 o Parentheses enclose choice and case nodes, and case nodes are also 146 marked with a colon (":"). 148 o Ellipsis ("...") stands for contents of subtrees that are not 149 shown. 151 2. The RESTCONF Client Model 153 EDITOR NOTE: Please ignore this section, it is incomplete. 155 The RESTCONF client model presented in this section supports both 156 clients initiating connections to servers, as well as clients 157 listening for connections from servers calling home. 159 This model supports the TLS transport protocol using the TLS client 160 groupings defined in [I-D.ietf-netconf-tls-client-server]. 162 All private keys and trusted certificates are held in the keystore 163 model defined in [I-D.ietf-netconf-keystore]. 165 YANG feature statements are used to enable implementations to 166 advertise which parts of the model the RESTCONF client supports. 168 2.1. Tree Diagram 170 Just the container is displayed below, but there is also a grouping 171 that the container is using. 173 Note: all lines are folded at column 71 with no '\' character. 175 module: ietf-restconf-client 176 +--rw restconf-client 177 +--rw initiate {initiate}? 178 | +--rw restconf-server* [name] 179 | +--rw name string 180 | +--rw (transport) 181 | | +--:(tls) {tls-initiate}? 182 | | +--rw tls 183 | | +--rw endpoints 184 | | | +--rw endpoint* [name] 185 | | | +--rw name string 186 | | | +--rw address inet:host 187 | | | +--rw port? inet:port-number 188 | | +--rw server-auth 189 | | | +--rw trusted-ca-certs? leafref 190 | | | +--rw trusted-server-certs? leafref 191 | | +--rw client-auth 192 | | | +--rw (auth-type) 193 | | | +--:(certificate) 194 | | | +--rw certificate? leafref 195 | | +--rw hello-params 196 | | {tls-client-hello-params-config}? 197 | | +--rw tls-versions 198 | | | +--rw tls-version* identityref 199 | | +--rw cipher-suites 200 | | +--rw cipher-suite* identityref 201 | +--rw connection-type 202 | | +--rw (connection-type)? 203 | | +--:(persistent-connection) 204 | | | +--rw persistent! 205 | | | +--rw idle-timeout? uint32 206 | | | +--rw keep-alives 207 | | | +--rw max-wait? uint16 208 | | | +--rw max-attempts? uint8 209 | | +--:(periodic-connection) 210 | | +--rw periodic! 211 | | +--rw idle-timeout? uint16 212 | | +--rw reconnect-timeout? uint16 213 | +--rw reconnect-strategy 214 | +--rw start-with? enumeration 215 | +--rw max-attempts? uint8 216 +--rw listen {listen}? 217 +--rw max-sessions? uint16 218 +--rw idle-timeout? uint16 219 +--rw endpoint* [name] 220 +--rw name string 221 +--rw (transport) 222 +--:(tls) {tls-listen}? 223 +--rw tls 224 +--rw address? inet:ip-address 225 +--rw port? inet:port-number 226 +--rw server-auth 227 | +--rw trusted-ca-certs? leafref 228 | +--rw trusted-server-certs? leafref 229 +--rw client-auth 230 | +--rw (auth-type) 231 | +--:(certificate) 232 | +--rw certificate? leafref 233 +--rw hello-params 234 {tls-client-hello-params-config}? 235 +--rw tls-versions 236 | +--rw tls-version* identityref 237 +--rw cipher-suites 238 +--rw cipher-suite* identityref 240 2.2. Example Usage 242 The following example illustrates configuring a RESTCONF client to 243 initiate connections, as well as listening for call-home connections. 245 This example is consistent with the examples presented in Section 2.2 246 of [I-D.ietf-netconf-keystore]. 248 251 252 253 254 corp-fw1 255 256 257 258 corp-fw1.example.com 259
corp-fw1.example.com
260 261 262 corp-fw2.example.com 263
corp-fw2.example.com
264 265 266 267 deployment-specific-ca-certs 268 269 270 tls-ec-cert 271 272 273 274 276 277 278 279 Intranet-facing listener 280 281
11.22.33.44
282 283 deployment-specific-ca-certs 284 explicitly-trusted-server-certs 285 286 287 tls-ec-cert 288 289 290 291 292 293 2.3. YANG Model 295 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 297 file "ietf-restconf-client@2017-07-03.yang" 299 module ietf-restconf-client { 300 yang-version 1.1; 302 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 303 prefix "rcc"; 305 import ietf-inet-types { 306 prefix inet; 307 reference 308 "RFC 6991: Common YANG Data Types"; 309 } 311 import ietf-tls-client { 312 prefix ts; 313 revision-date 2017-06-13; // stable grouping definitions 314 reference 315 "RFC ZZZZ: TLS Client and Server Models"; 316 } 318 organization 319 "IETF NETCONF (Network Configuration) Working Group"; 321 contact 322 "WG Web: 323 WG List: 325 Author: Kent Watsen 326 328 Author: Gary Wu 329 "; 331 description 332 "This module contains a collection of YANG definitions for 333 configuring RESTCONF clients. 335 Copyright (c) 2014 IETF Trust and the persons identified as 336 authors of the code. All rights reserved. 338 Redistribution and use in source and binary forms, with or 339 without modification, is permitted pursuant to, and subject 340 to the license terms contained in, the Simplified BSD 341 License set forth in Section 4.c of the IETF Trust's 342 Legal Provisions Relating to IETF Documents 343 (http://trustee.ietf.org/license-info). 345 This version of this YANG module is part of RFC XXXX; see 346 the RFC itself for full legal notices."; 348 revision "2017-07-03" { 349 description 350 "Initial version"; 351 reference 352 "RFC XXXX: RESTCONF Client and Server Models"; 353 } 355 // Features 357 feature initiate { 358 description 359 "The 'initiate' feature indicates that the RESTCONF client 360 supports initiating RESTCONF connections to RESTCONF servers 361 using at least one transport (e.g., TLS, etc.)."; 362 } 364 feature tls-initiate { 365 description 366 "The 'tls-initiate' feature indicates that the RESTCONF client 367 supports initiating TLS connections to RESTCONF servers."; 368 reference 369 "RFC 8040: RESTCONF Protocol"; 370 } 372 feature listen { 373 description 374 "The 'listen' feature indicates that the RESTCONF client 375 supports opening a port to accept RESTCONF server call 376 home connections using at least one transport (e.g., 377 TLS, etc.)."; 378 } 380 feature tls-listen { 381 description 382 "The 'tls-listen' feature indicates that the RESTCONF client 383 supports opening a port to listen for incoming RESTCONF 384 server call-home TLS connections."; 385 reference 386 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 388 } 390 container restconf-client { 391 uses restconf-client; 392 description 393 "Top-level container for RESTCONF client configuration."; 394 } 396 grouping restconf-client { 397 description 398 "Top-level grouping for RESTCONF client configuration."; 400 container initiate { 401 if-feature initiate; 402 description 403 "Configures client initiating underlying TCP connections."; 404 list restconf-server { 405 key name; 406 description 407 "List of RESTCONF servers the RESTCONF client is to initiate 408 connections to."; 409 leaf name { 410 type string; 411 description 412 "An arbitrary name for the RESTCONF server."; 413 } 414 choice transport { 415 mandatory true; 416 description 417 "Selects between available transports."; 419 case tls { 420 if-feature tls-initiate; 421 container tls { 422 description 423 "Specifies TLS-specific transport configuration."; 424 uses endpoints-container { 425 refine endpoints/endpoint/port { 426 default 443; 427 } 428 } 429 uses ts:tls-client-grouping { 430 refine "client-auth/auth-type" { 431 mandatory true; 432 description 433 "RESTCONF clients MUST pass some authentication 434 credentials."; 435 } 437 } 438 } 439 } // end tls 441 } // end transport 443 container connection-type { 444 description 445 "Indicates the kind of connection to use."; 446 choice connection-type { 447 description 448 "Selects between available connection types."; 449 case persistent-connection { 450 container persistent { 451 presence true; 452 description 453 "Maintain a persistent connection to the RESTCONF 454 server. If the connection goes down, immediately 455 start trying to reconnect to it, using the 456 reconnection strategy. 458 This connection type minimizes any RESTCONF server 459 to RESTCONF client data-transfer delay, albeit at 460 the expense of holding resources longer."; 461 leaf idle-timeout { 462 type uint32; 463 units "seconds"; 464 default 86400; // one day; 465 description 466 "Specifies the maximum number of seconds that a 467 a RESTCONF session may remain idle. A RESTCONF 468 session will be dropped if it is idle for an 469 interval longer than this number of seconds. 470 If set to zero, then the client will never drop 471 a session because it is idle. Sessions that 472 have a notification subscription active are 473 never dropped."; 474 } 475 container keep-alives { 476 description 477 "Configures the keep-alive policy, to proactively 478 test the aliveness of the SSH/TLS server. An 479 unresponsive SSH/TLS server will be dropped after 480 approximately max-attempts * max-wait seconds."; 481 reference 482 "RFC 8071: NETCONF Call Home and RESTCONF Call 483 Home, Section 3.1, item S6"; 484 leaf max-wait { 485 type uint16 { 486 range "1..max"; 487 } 488 units seconds; 489 default 30; 490 description 491 "Sets the amount of time in seconds after which 492 if no data has been received from the SSH/TLS 493 server, a SSH/TLS-level message will be sent 494 to test the aliveness of the SSH/TLS server."; 495 } 496 leaf max-attempts { 497 type uint8; 498 default 3; 499 description 500 "Sets the maximum number of sequential keep-alive 501 messages that can fail to obtain a response from 502 the SSH/TLS server before assuming the SSH/TLS 503 server is no longer alive."; 504 } 505 } 506 } 507 } 508 case periodic-connection { 509 container periodic { 510 presence true; 511 description 512 "Periodically connect to the RESTCONF server, so that 513 the RESTCONF server may deliver messages pending for 514 the RESTCONF client. The RESTCONF server must close 515 the connection when it is ready to release it. Once 516 the connection has been closed, the RESTCONF client 517 will restart its timer until the next connection."; 518 leaf idle-timeout { 519 type uint16; 520 units "seconds"; 521 default 300; // five minutes 522 description 523 "Specifies the maximum number of seconds that a 524 a RESTCONF session may remain idle. A RESTCONF 525 session will be dropped if it is idle for an 526 interval longer than this number of seconds. 527 If set to zero, then the server will never drop 528 a session because it is idle. Sessions that 529 have a notification subscription active are 530 never dropped."; 531 } 532 leaf reconnect-timeout { 533 type uint16 { 534 range "1..max"; 535 } 536 units minutes; 537 default 60; 538 description 539 "Sets the maximum amount of unconnected time the 540 RESTCONF client will wait before re-establishing 541 a connection to the RESTCONF server. The RESTCONF 542 client may initiate a connection before this 543 time if desired (e.g., to set configuration)."; 544 } 545 } 546 } 547 } 548 } 549 container reconnect-strategy { 550 description 551 "The reconnection strategy directs how a RESTCONF client 552 reconnects to a RESTCONF server, after discovering its 553 connection to the server has dropped, even if due to a 554 reboot. The RESTCONF client starts with the specified 555 endpoint and tries to connect to it max-attempts times 556 before trying the next endpoint in the list (round 557 robin)."; 558 leaf start-with { 559 type enumeration { 560 enum first-listed { 561 description 562 "Indicates that reconnections should start with 563 the first endpoint listed."; 564 } 565 enum last-connected { 566 description 567 "Indicates that reconnections should start with 568 the endpoint last connected to. If no previous 569 connection has ever been established, then the 570 first endpoint configured is used. RESTCONF 571 clients SHOULD be able to remember the last 572 endpoint connected to across reboots."; 573 } 574 } 575 default first-listed; 576 description 577 "Specifies which of the RESTCONF server's endpoints the 578 RESTCONF client should start with when trying to connect 579 to the RESTCONF server."; 580 } 581 leaf max-attempts { 582 type uint8 { 583 range "1..max"; 584 } 585 default 3; 586 description 587 "Specifies the number times the RESTCONF client tries to 588 connect to a specific endpoint before moving on to the 589 next endpoint in the list (round robin)."; 590 } 591 } 592 } // end restconf-server 593 } // end initiate 595 container listen { 596 if-feature listen; 597 description 598 "Configures client accepting call-home TCP connections."; 600 leaf max-sessions { 601 type uint16; 602 default 0; 603 description 604 "Specifies the maximum number of concurrent sessions 605 that can be active at one time. The value 0 indicates 606 that no artificial session limit should be used."; 607 } 609 leaf idle-timeout { 610 type uint16; 611 units "seconds"; 612 default 3600; // one hour 613 description 614 "Specifies the maximum number of seconds that a RESTCONF 615 session may remain idle. A RESTCONF session will be dropped 616 if it is idle for an interval longer than this number of 617 seconds. If set to zero, then the server will never drop 618 a session because it is idle. Sessions that have a 619 notification subscription active are never dropped."; 620 } 622 list endpoint { 623 key name; 624 description 625 "List of endpoints to listen for RESTCONF connections."; 626 leaf name { 627 type string; 628 description 629 "An arbitrary name for the RESTCONF listen endpoint."; 630 } 631 choice transport { 632 mandatory true; 633 description 634 "Selects between available transports."; 635 case tls { 636 if-feature tls-listen; 637 container tls { 638 description 639 "TLS-specific listening configuration for inbound 640 connections."; 641 leaf address { 642 type inet:ip-address; 643 description 644 "The IP address to listen for call-home connections."; 645 } 646 leaf port { 647 type inet:port-number; 648 default 4336; 649 description 650 "The port number to listen for call-home connections."; 651 } 652 uses ts:tls-client-grouping { 653 refine "client-auth/auth-type" { 654 mandatory true; 655 description 656 "RESTCONF clients MUST pass some authentication 657 credentials."; 658 } 659 } 660 } 661 } 662 } // end transport 663 } // end endpoint 664 } // end listen 666 } // end restconf-client 668 grouping endpoints-container { 669 description 670 "This grouping is used to configure a set of RESTCONF servers 671 a RESTCONF client may initiate connections to."; 672 container endpoints { 673 description 674 "Container for the list of endpoints."; 675 list endpoint { 676 key name; 677 unique "address port"; 678 min-elements 1; 679 ordered-by user; 680 description 681 "A non-empty user-ordered list of endpoints for this RESTCONF 682 client to try to connect to. Defining more than one enables 683 high-availability."; 684 leaf name { 685 type string; 686 description 687 "An arbitrary name for this endpoint."; 688 } 689 leaf address { 690 type inet:host; 691 mandatory true; 692 description 693 "The IP address or hostname of the endpoint. If a 694 hostname is configured and the DNS resolution results 695 in more than one IP address, the RESTCONF client 696 will process the IP addresses as if they had been 697 explicitly configured in place of the hostname."; 698 } 699 leaf port { 700 type inet:port-number; 701 description 702 "The IP port for this endpoint. The RESTCONF client will 703 use the IANA-assigned well-known port (set via a refine 704 statement when uses) if no value is specified."; 705 } 706 } 707 } 708 } 709 } 711 713 3. The RESTCONF Server Model 715 The RESTCONF Server model presented in this section supports servers 716 both listening for connections as well as initiating call-home 717 connections. 719 This model supports the TLS transport protocol using the TLS server 720 groupings defined in [I-D.ietf-netconf-tls-client-server]. 722 All private keys and trusted certificates are held in the keystore 723 model defined in [I-D.ietf-netconf-keystore]. 725 YANG feature statements are used to enable implementations to 726 advertise which parts of the model the RESTCONF server supports. 728 3.1. Tree Diagram 730 Just the container is displayed below, but there is also a grouping 731 that the container is using. 733 Note: all lines are folded at column 71 with no '\' character. 735 module: ietf-restconf-server 736 +--rw restconf-server 737 +--rw listen {listen}? 738 | +--rw max-sessions? uint16 739 | +--rw endpoint* [name] 740 | +--rw name string 741 | +--rw (transport) 742 | +--:(tls) {tls-listen}? 743 | +--rw tls 744 | +--rw address? inet:ip-address 745 | +--rw port? inet:port-number 746 | +--rw certificates 747 | | +--rw certificate* [name] 748 | | +--rw name leafref 749 | +--rw client-auth 750 | | +--rw trusted-ca-certs? leafref 751 | | +--rw trusted-client-certs? leafref 752 | | +--rw cert-maps 753 | | +--rw cert-to-name* [id] 754 | | +--rw id uint32 755 | | +--rw fingerprint x509c2n:tls-fingerprint 756 | | +--rw map-type identityref 757 | | +--rw name string 758 | +--rw hello-params 759 | {tls-server-hello-params-config}? 760 | +--rw tls-versions 761 | | +--rw tls-version* identityref 762 | +--rw cipher-suites 763 | +--rw cipher-suite* identityref 764 +--rw call-home {call-home}? 765 +--rw restconf-client* [name] 766 +--rw name string 767 +--rw (transport) 768 | +--:(tls) {tls-call-home}? 769 | +--rw tls 770 | +--rw endpoints 771 | | +--rw endpoint* [name] 772 | | +--rw name string 773 | | +--rw address inet:host 774 | | +--rw port? inet:port-number 775 | +--rw certificates 776 | | +--rw certificate* [name] 777 | | +--rw name leafref 778 | +--rw client-auth 779 | | +--rw trusted-ca-certs? leafref 780 | | +--rw trusted-client-certs? leafref 781 | | +--rw cert-maps 782 | | +--rw cert-to-name* [id] 783 | | +--rw id uint32 784 | | +--rw fingerprint x509c2n:tls-fingerprint 785 | | +--rw map-type identityref 786 | | +--rw name string 787 | +--rw hello-params 788 | {tls-server-hello-params-config}? 789 | +--rw tls-versions 790 | | +--rw tls-version* identityref 791 | +--rw cipher-suites 792 | +--rw cipher-suite* identityref 793 +--rw connection-type 794 | +--rw (connection-type)? 795 | +--:(persistent-connection) 796 | | +--rw persistent! 797 | | +--rw keep-alives 798 | | +--rw max-wait? uint16 799 | | +--rw max-attempts? uint8 800 | +--:(periodic-connection) 801 | +--rw periodic! 802 | +--rw reconnect-timeout? uint16 803 +--rw reconnect-strategy 804 +--rw start-with? enumeration 805 +--rw max-attempts? uint8 807 3.2. Example Usage 809 The following example illustrates configuring a RESTCONF server to 810 listen for RESTCONF client connections, as well as configuring call- 811 home to one RESTCONF client. 813 This example is consistent with the examples presented in Section 2.2 814 of [I-D.ietf-netconf-keystore]. 816 820 821 822 823 netconf/tls 824 825
11.22.33.44
826 827 828 tls-ec-cert 829 830 831 832 deployment-specific-ca-certs 833 explicitly-trusted-client-certs 834 835 836 1 837 11:0A:05:11:00 838 x509c2n:san-any 839 840 841 2 842 B3:4F:A1:8C:54 843 x509c2n:specified 844 scooby-doo 845 846 847 848 849 850 852 853 854 855 config-manager 856 857 858 859 east-data-center 860
22.33.44.55
861 862 863 west-data-center 864
33.44.55.66
865 866 867 868 869 tls-ec-cert 870 871 872 873 deployment-specific-ca-certs 874 explicitly-trusted-client-certs 875 876 877 1 878 11:0A:05:11:00 879 x509c2n:san-any 880 881 882 2 883 B3:4F:A1:8C:54 884 x509c2n:specified 885 scooby-doo 886 887 888 889 890 891 892 300 893 60 894 895 896 897 last-connected 898 3 899 900 901 903 905 3.3. YANG Model 907 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 909 file "ietf-restconf-server@2017-07-03.yang" 911 module ietf-restconf-server { 912 yang-version 1.1; 914 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 915 prefix "rcs"; 916 //import ietf-netconf-acm { 917 // prefix nacm; 918 // reference 919 // "RFC 6536: Network Configuration Protocol (NETCONF) 920 // Access Control Model"; 921 //} 923 import ietf-inet-types { 924 prefix inet; 925 reference 926 "RFC 6991: Common YANG Data Types"; 927 } 929 import ietf-x509-cert-to-name { 930 prefix x509c2n; 931 reference 932 "RFC 7407: A YANG Data Model for SNMP Configuration"; 933 } 935 import ietf-tls-server { 936 prefix ts; 937 revision-date 2017-06-13; // stable grouping definitions 938 reference 939 "RFC ZZZZ: TLS Client and Server Models"; 940 } 942 organization 943 "IETF NETCONF (Network Configuration) Working Group"; 945 contact 946 "WG Web: 947 WG List: 949 WG Chair: Mehmet Ersue 950 952 WG Chair: Mahesh Jethanandani 953 955 Editor: Kent Watsen 956 "; 958 description 959 "This module contains a collection of YANG definitions for 960 configuring RESTCONF servers. 962 Copyright (c) 2014 IETF Trust and the persons identified as 963 authors of the code. All rights reserved. 965 Redistribution and use in source and binary forms, with or 966 without modification, is permitted pursuant to, and subject 967 to the license terms contained in, the Simplified BSD 968 License set forth in Section 4.c of the IETF Trust's 969 Legal Provisions Relating to IETF Documents 970 (http://trustee.ietf.org/license-info). 972 This version of this YANG module is part of RFC XXXX; see 973 the RFC itself for full legal notices."; 975 revision "2017-07-03" { 976 description 977 "Initial version"; 978 reference 979 "RFC XXXX: RESTCONF Client and Server Models"; 980 } 982 // Features 984 feature listen { 985 description 986 "The 'listen' feature indicates that the RESTCONF server 987 supports opening a port to accept RESTCONF client connections 988 using at least one transport (e.g., TLS, etc.)."; 989 } 991 feature tls-listen { 992 description 993 "The 'tls-listen' feature indicates that the RESTCONF server 994 supports opening a port to listen for incoming RESTCONF 995 client connections."; 996 reference 997 "RFC XXXX: RESTCONF Protocol"; 998 } 1000 feature call-home { 1001 description 1002 "The 'call-home' feature indicates that the RESTCONF server 1003 supports initiating RESTCONF call home connections to REETCONF 1004 clients using at least one transport (e.g., TLS, etc.)."; 1005 reference 1006 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1007 } 1009 feature tls-call-home { 1010 description 1011 "The 'tls-call-home' feature indicates that the RESTCONF server 1012 supports initiating connections to RESTCONF clients."; 1013 reference 1014 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1015 } 1017 feature client-cert-auth { 1018 description 1019 "The client-cert-auth feature indicates that the RESTCONF 1020 server supports the ClientCertificate authentication scheme."; 1021 reference 1022 "RFC ZZZZ: Client Authentication over New TLS Connection"; 1023 } 1025 // top-level container 1026 container restconf-server { 1027 uses restconf-server; 1028 description 1029 "Top-level container for RESTCONF server configuration."; 1030 } 1032 grouping restconf-server { 1033 description 1034 "Top-level grouping for RESTCONF server configuration."; 1036 container listen { 1037 if-feature listen; 1038 description 1039 "Configures listen behavior"; 1040 leaf max-sessions { 1041 type uint16; 1042 default 0; // should this be 'max'? 1043 description 1044 "Specifies the maximum number of concurrent sessions 1045 that can be active at one time. The value 0 indicates 1046 that no artificial session limit should be used."; 1047 } 1048 list endpoint { 1049 key name; 1050 description 1051 "List of endpoints to listen for RESTCONF connections."; 1052 leaf name { 1053 type string; 1054 description 1055 "An arbitrary name for the RESTCONF listen endpoint."; 1056 } 1057 choice transport { 1058 mandatory true; 1059 description 1060 "Selects between available transports."; 1061 case tls { 1062 if-feature tls-listen; 1063 container tls { 1064 description 1065 "TLS-specific listening configuration for inbound 1066 connections."; 1067 leaf address { 1068 type inet:ip-address; 1069 description 1070 "The IP address of the interface to listen on. The 1071 TLS server will listen on all interfaces if no value 1072 is specified. Please note that some addresses have 1073 special meanings (e.g., '0.0.0.0' and '::')."; 1074 } 1075 leaf port { 1076 type inet:port-number; 1077 default 443; 1078 description 1079 "The local port number on this interface the TLS server 1080 listens on."; 1081 } 1082 uses ts:tls-server-grouping { 1083 refine "client-auth" { 1084 must 'trusted-ca-certs or trusted-client-certs'; 1085 description 1086 "RESTCONF servers MUST be able to validate clients."; 1087 } 1088 augment "client-auth" { 1089 description 1090 "Augments in the cert-to-name structure."; 1091 uses cert-maps-grouping; 1092 } 1093 } 1094 } // end tls container 1095 } // end tls case 1096 } // end transport 1097 } // end endpoint 1098 } // end listen 1100 container call-home { 1101 if-feature call-home; 1102 description 1103 "Configures call-home behavior"; 1104 list restconf-client { 1105 key name; 1106 description 1107 "List of RESTCONF clients the RESTCONF server is to 1108 initiate call-home connections to."; 1109 leaf name { 1110 type string; 1111 description 1112 "An arbitrary name for the remote RESTCONF client."; 1113 } 1114 choice transport { 1115 mandatory true; 1116 description 1117 "Selects between TLS and any transports augmented in."; 1118 case tls { 1119 if-feature tls-call-home; 1120 container tls { 1121 description 1122 "Specifies TLS-specific call-home transport 1123 configuration."; 1124 uses endpoints-container { 1125 refine endpoints/endpoint/port { 1126 default 4336; 1127 } 1128 } 1129 uses ts:tls-server-grouping { 1130 refine "client-auth" { 1131 must 'trusted-ca-certs or trusted-client-certs'; 1132 description 1133 "RESTCONF servers MUST be able to validate clients."; 1134 } 1135 augment "client-auth" { 1136 description 1137 "Augments in the cert-to-name structure."; 1138 uses cert-maps-grouping; 1139 } 1140 } 1141 } 1142 } 1143 } 1144 container connection-type { 1145 description 1146 "Indicates the RESTCONF client's preference for how the 1147 RESTCONF server's connection is maintained."; 1148 choice connection-type { 1149 description 1150 "Selects between available connection types."; 1151 case persistent-connection { 1152 container persistent { 1153 presence true; 1154 description 1155 "Maintain a persistent connection to the RESTCONF 1156 client. If the connection goes down, immediately 1157 start trying to reconnect to it, using the 1158 reconnection strategy. 1160 This connection type minimizes any RESTCONF client 1161 to RESTCONF server data-transfer delay, albeit at 1162 the expense of holding resources longer."; 1164 container keep-alives { 1165 description 1166 "Configures the keep-alive policy, to proactively 1167 test the aliveness of the TLS client. An 1168 unresponsive TLS client will be dropped after 1169 approximately (max-attempts * max-wait) 1170 seconds."; 1171 reference 1172 "RFC 8071: NETCONF Call Home and RESTCONF Call 1173 Home, Section 3.1, item S6"; 1174 leaf max-wait { 1175 type uint16 { 1176 range "1..max"; 1177 } 1178 units seconds; 1179 default 30; 1180 description 1181 "Sets the amount of time in seconds after which 1182 if no data has been received from the TLS 1183 client, a TLS-level message will be sent to 1184 test the aliveness of the TLS client."; 1185 } 1186 leaf max-attempts { 1187 type uint8; 1188 default 3; 1189 description 1190 "Sets the maximum number of sequential keep-alive 1191 messages that can fail to obtain a response from 1192 the TLS client before assuming the TLS client is 1193 no longer alive."; 1194 } 1195 } 1196 } 1197 } 1198 case periodic-connection { 1199 container periodic { 1200 presence true; 1201 description 1202 "Periodically connect to the RESTCONF client, so that 1203 the RESTCONF client may deliver messages pending for 1204 the RESTCONF server. The client must close the 1205 connection when it's ready to release it. Once the 1206 connection has been closed, the server will restart 1207 its timer until the next connection."; 1208 leaf reconnect-timeout { 1209 type uint16 { 1210 range "1..max"; 1211 } 1212 units minutes; 1213 default 60; 1214 description 1215 "The maximum amount of unconnected time the 1216 RESTCONF server will wait before re-establishing 1217 a connection to the RESTCONF client. The 1218 RESTCONF server may initiate a connection to 1219 the RESTCONF client before this time if desired 1220 (e.g., to deliver a notification)."; 1221 } 1222 } 1223 } 1224 } 1225 } 1226 container reconnect-strategy { 1227 description 1228 "The reconnection strategy directs how a RESTCONF server 1229 reconnects to a RESTCONF client after after discovering 1230 its connection to the client has dropped, even if due to 1231 a reboot. The RESTCONF server starts with the specified 1232 endpoint and tries to connect to it max-attempts times 1233 before trying the next endpoint in the list (round 1234 robin)."; 1235 leaf start-with { 1236 type enumeration { 1237 enum first-listed { 1238 description 1239 "Indicates that reconnections should start with 1240 the first endpoint listed."; 1241 } 1242 enum last-connected { 1243 description 1244 "Indicates that reconnections should start with 1245 the endpoint last connected to. If no previous 1246 connection has ever been established, then the 1247 first endpoint configured is used. RESTCONF 1248 servers SHOULD be able to remember the last 1249 endpoint connected to across reboots."; 1250 } 1251 } 1252 default first-listed; 1253 description 1254 "Specifies which of the RESTCONF client's endpoints the 1255 RESTCONF server should start with when trying to connect 1256 to the RESTCONF client."; 1257 } 1258 leaf max-attempts { 1259 type uint8 { 1260 range "1..max"; 1261 } 1262 default 3; 1263 description 1264 "Specifies the number times the RESTCONF server tries to 1265 connect to a specific endpoint before moving on to the 1266 next endpoint in the list (round robin)."; 1267 } 1268 } 1269 } 1270 } 1271 } 1273 grouping cert-maps-grouping { 1274 description 1275 "A grouping that defines a container around the 1276 cert-to-name structure defined in RFC 7407."; 1277 container cert-maps { 1278 uses x509c2n:cert-to-name; 1279 description 1280 "The cert-maps container is used by a TLS-based RESTCONF 1281 server to map the RESTCONF client's presented X.509 1282 certificate to a RESTCONF username. If no matching and 1283 valid cert-to-name list entry can be found, then the 1284 RESTCONF server MUST close the connection, and MUST NOT 1285 accept RESTCONF messages over it."; 1286 reference 1287 "RFC XXXX: The RESTCONF Protocol"; 1288 } 1289 } 1291 grouping endpoints-container { 1292 description 1293 "This grouping is used by tls container for call-home 1294 configurations."; 1296 container endpoints { 1297 description 1298 "Container for the list of endpoints."; 1299 list endpoint { 1300 key name; 1301 unique "address port"; 1302 min-elements 1; 1303 ordered-by user; 1304 description 1305 "User-ordered list of endpoints for this RESTCONF client. 1306 Defining more than one enables high-availability."; 1307 leaf name { 1308 type string; 1309 description 1310 "An arbitrary name for this endpoint."; 1311 } 1312 leaf address { 1313 type inet:host; 1314 mandatory true; 1315 description 1316 "The IP address or hostname of the endpoint. If a 1317 hostname is configured and the DNS resolution results 1318 in more than one IP address, the RESTCONF server 1319 will process the IP addresses as if they had been 1320 explicitly configured in place of the hostname."; 1321 } 1322 leaf port { 1323 type inet:port-number; 1324 description 1325 "The IP port for this endpoint. The RESTCONF server will 1326 use the IANA-assigned well-known port if no value is 1327 specified."; 1328 } 1329 } 1330 } 1331 } 1333 } 1335 1337 4. Security Considerations 1339 The YANG module defined in this document uses a grouping defined in 1340 [I-D.ietf-netconf-tls-client-server]. Please see the Security 1341 Considerations section in that document for concerns related that 1342 grouping. 1344 The YANG module defined in this document is designed to be accessed 1345 via YANG based management protocols, such as NETCONF [RFC6241] and 1346 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1347 implement secure transport layers (e.g., SSH, TLS) with mutual 1348 authentication. 1350 The NETCONF access control model (NACM) [RFC6536] provides the means 1351 to restrict access for particular users to a pre-configured subset of 1352 all available protocol operations and content. 1354 There are a number of data nodes defined in this YANG module that are 1355 writable/creatable/deletable (i.e., config true, which is the 1356 default). These data nodes may be considered sensitive or vulnerable 1357 in some network environments. Write operations (e.g., edit-config) 1358 to these data nodes without proper protection can have a negative 1359 effect on network operations. These are the subtrees and data nodes 1360 and their sensitivity/vulnerability: 1362 NONE 1364 Some of the readable data nodes in this YANG module may be considered 1365 sensitive or vulnerable in some network environments. It is thus 1366 important to control read access (e.g., via get, get-config, or 1367 notification) to these data nodes. These are the subtrees and data 1368 nodes and their sensitivity/vulnerability: 1370 NONE 1372 Some of the RPC operations in this YANG module may be considered 1373 sensitive or vulnerable in some network environments. It is thus 1374 important to control access to these operations. These are the 1375 operations and their sensitivity/vulnerability: 1377 NONE 1379 5. IANA Considerations 1381 5.1. The IETF XML Registry 1383 This document registers two URIs in the IETF XML registry [RFC3688]. 1384 Following the format in [RFC3688], the following registrations are 1385 requested: 1387 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1388 Registrant Contact: The NETCONF WG of the IETF. 1389 XML: N/A, the requested URI is an XML namespace. 1391 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1392 Registrant Contact: The NETCONF WG of the IETF. 1393 XML: N/A, the requested URI is an XML namespace. 1395 5.2. The YANG Module Names Registry 1397 This document registers two YANG modules in the YANG Module Names 1398 registry [RFC7950]. Following the format in [RFC7950], the the 1399 following registrations are requested: 1401 name: ietf-restconf-client 1402 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1403 prefix: ncc 1404 reference: RFC XXXX 1406 name: ietf-restconf-server 1407 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1408 prefix: ncs 1409 reference: RFC XXXX 1411 6. Acknowledgements 1413 The authors would like to thank for following for lively discussions 1414 on list and in the halls (ordered by last name): Andy Bierman, Martin 1415 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1416 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1417 Phil Shafer, Sean Turner, and Bert Wijnen. 1419 Juergen Schoenwaelder and was partly funded by Flamingo, a Network of 1420 Excellence project (ICT-318488) supported by the European Commission 1421 under its Seventh Framework Programme. 1423 7. References 1425 7.1. Normative References 1427 [I-D.ietf-netconf-keystore] 1428 Watsen, K., "Keystore Model", draft-ietf-netconf- 1429 keystore-02 (work in progress), June 2017. 1431 [I-D.ietf-netconf-tls-client-server] 1432 Watsen, K. and G. Wu, "TLS Client and Server Models", 1433 draft-ietf-netconf-tls-client-server-03 (work in 1434 progress), June 2017. 1436 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1437 Requirement Levels", BCP 14, RFC 2119, 1438 DOI 10.17487/RFC2119, March 1997, 1439 . 1441 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1442 Protocol (NETCONF) Access Control Model", RFC 6536, 1443 DOI 10.17487/RFC6536, March 2012, 1444 . 1446 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1447 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1448 . 1450 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1451 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1452 December 2014, . 1454 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1455 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1456 . 1458 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1459 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1460 May 2017, . 1462 7.2. Informative References 1464 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1465 DOI 10.17487/RFC3688, January 2004, 1466 . 1468 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1469 (TLS) Protocol Version 1.2", RFC 5246, 1470 DOI 10.17487/RFC5246, August 2008, 1471 . 1473 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1474 and A. Bierman, Ed., "Network Configuration Protocol 1475 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1476 . 1478 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1479 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1480 . 1482 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1483 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1484 . 1486 Appendix A. Change Log 1488 A.1. server-model-09 to 00 1490 o This draft was split out from draft-ietf-netconf-server-model-09. 1492 o Added in new features 'listen' and 'call-home' so future 1493 transports can be augmented in. 1495 A.2. 00 to 01 1497 o Renamed "keychain" to "keystore". 1499 A.3. 01 to 02 1501 o Filled in previously missing 'ietf-restconf-client' module. 1503 o Updated the ietf-restconf-server module to accomodate new grouping 1504 'ietf-tls-server-grouping'. 1506 A.4. 02 to 03 1508 o Refined use of tls-client-grouping to add a must statement 1509 indicating that the TLS client must specify a client-certificate. 1511 o Changed restconf-client??? to be a grouping (not a container). 1513 A.5. 03 to 04 1515 o Added RFC 8174 to Requirements Language Section. 1517 o Replaced refine statement in ietf-restconf-client to add a 1518 mandatory true. 1520 o Added refine statement in ietf-restconf-server to add a must 1521 statement. 1523 o Now there are containers and groupings, for both the client and 1524 server models. 1526 Authors' Addresses 1528 Kent Watsen 1529 Juniper Networks 1531 EMail: kwatsen@juniper.net 1532 Juergen Schoenwaelder 1533 Jacobs University Bremen 1535 EMail: j.schoenwaelder@jacobs-university.de