idnits 2.17.1 draft-ietf-netconf-restconf-client-server-03.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 9 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 181 has weird spacing: '...address ine...' == Line 239 has weird spacing: '...address ine...' == Line 731 has weird spacing: '...rw name str...' == Line 739 has weird spacing: '...rw name lea...' == Line 746 has weird spacing: '...erprint x50...' == (3 more instances...) == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (June 13, 2017) is 2507 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-01 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-02 ** 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 (~~), 10 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: December 15, 2017 Jacobs University Bremen 6 June 13, 2017 8 RESTCONF Client and Server Models 9 draft-ietf-netconf-restconf-client-server-03 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-06-13" --> 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 December 15, 2017. 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 . . . . . . . . . . . . . 30 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 . . . . . . . . . . . . . . . . . . . . . 33 105 A.1. server-model-09 to 00 . . . . . . . . . . . . . . . . . . 33 106 A.2. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 33 107 A.3. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 33 108 A.4. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 33 109 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 111 1. Introduction 113 This document defines two YANG [RFC7950] modules, one module to 114 configure a RESTCONF client and the other module to configure a 115 RESTCONF server [RFC8040]. Both modules support the TLS [RFC5246] 116 transport protocol with both standard RESTCONF and RESTCONF Call Home 117 connections [RFC8071]. 119 1.1. Terminology 121 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in RFC 2119 [RFC2119]. 125 1.2. Tree Diagrams 127 A simplified graphical representation of the data models is used in 128 this document. The meaning of the symbols in these diagrams is as 129 follows: 131 o Brackets "[" and "]" enclose list keys. 133 o Braces "{" and "}" enclose feature names, and indicate that the 134 named feature must be present for the subtree to be present. 136 o Abbreviations before data node names: "rw" means configuration 137 (read-write) and "ro" state data (read-only). 139 o Symbols after data node names: "?" means an optional node, "!" 140 means a presence container, and "*" denotes a list and leaf-list. 142 o Parentheses enclose choice and case nodes, and case nodes are also 143 marked with a colon (":"). 145 o Ellipsis ("...") stands for contents of subtrees that are not 146 shown. 148 2. The RESTCONF Client Model 150 EDITOR NOTE: Please ignore this section, it is incomplete. 152 The RESTCONF client model presented in this section supports both 153 clients initiating connections to servers, as well as clients 154 listening for connections from servers calling home. 156 This model supports the TLS transport protocol using the TLS client 157 groupings defined in [I-D.ietf-netconf-tls-client-server]. 159 All private keys and trusted certificates are held in the keystore 160 model defined in [I-D.ietf-netconf-keystore]. 162 YANG feature statements are used to enable implementations to 163 advertise which parts of the model the RESTCONF client supports. 165 2.1. Tree Diagram 167 Note: all lines are folded at column 71 with no '\' character. 169 module: ietf-restconf-client 170 groupings: 171 restconf-client 172 +---- initiate {initiate}? 173 | +---- restconf-server* [name] 174 | +---- name? string 175 | +---- (transport) 176 | | +--:(tls) {tls-initiate}? 177 | | +---- tls 178 | | +---- endpoints 179 | | | +---- endpoint* [name] 180 | | | +---- name? string 181 | | | +---- address inet:host 182 | | | +---- port? inet:port-number 183 | | +---- server-auth 184 | | | +---- trusted-ca-certs? leafref 185 | | | +---- trusted-server-certs? leafref 186 | | +---- client-auth 187 | | | +---- (auth-type)? 188 | | | +--:(certificate) 189 | | | +---- certificate? leafref 190 | | +---- hello-params 191 | | {tls-client-hello-params-config}? 192 | | +---- tls-versions 193 | | | +---- tls-version* identityref 194 | | +---- cipher-suites 195 | | +---- cipher-suite* identityref 196 | +---- connection-type 197 | | +---- (connection-type)? 198 | | +--:(persistent-connection) 199 | | | +---- persistent! 200 | | | +---- idle-timeout? uint32 201 | | | +---- keep-alives 202 | | | +---- max-wait? uint16 203 | | | +---- max-attempts? uint8 204 | | +--:(periodic-connection) 205 | | +---- periodic! 206 | | +---- idle-timeout? uint16 207 | | +---- reconnect-timeout? uint16 208 | +---- reconnect-strategy 209 | +---- start-with? enumeration 210 | +---- max-attempts? uint8 211 +---- listen {listen}? 212 +---- max-sessions? uint16 213 +---- idle-timeout? uint16 214 +---- endpoint* [name] 215 +---- name? string 216 +---- (transport) 217 +--:(tls) {tls-listen}? 218 +---- tls 219 +---- address? inet:ip-address 220 +---- port? inet:port-number 221 +---- server-auth 222 | +---- trusted-ca-certs? leafref 223 | +---- trusted-server-certs? leafref 224 +---- client-auth 225 | +---- (auth-type)? 226 | +--:(certificate) 227 | +---- certificate? leafref 228 +---- hello-params 229 {tls-client-hello-params-config}? 230 +---- tls-versions 231 | +---- tls-version* identityref 232 +---- cipher-suites 233 +---- cipher-suite* identityref 235 endpoints-container 236 +---- endpoints 237 +---- endpoint* [name] 238 +---- name? string 239 +---- address inet:host 240 +---- port? inet:port-number 242 2.2. Example Usage 244 The following example illustrates configuring a RESTCONF client to 245 initiate connections, as well as listening for call-home connections. 247 This example is consistent with the examples presented in Section 2.2 248 of [I-D.ietf-netconf-keystore]. 250 253 254 255 256 corp-fw1 257 258 259 260 corp-fw1.example.com 261
corp-fw1.example.com
262 263 264 corp-fw2.example.com 265
corp-fw2.example.com
266 267 268 269 deployment-specific-ca-certs 270 271 272 tls-ec-cert 273 274 275 276 278 279 280 281 Intranet-facing listener 282 283
11.22.33.44
284 285 deployment-specific-ca-certs 286 explicitly-trusted-server-certs 287 288 289 tls-ec-cert 290 291 292 293 294 295 2.3. YANG Model 297 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 299 file "ietf-restconf-client@2017-06-13.yang" 301 module ietf-restconf-client { 302 yang-version 1.1; 304 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-client"; 305 prefix "rcc"; 307 import ietf-inet-types { 308 prefix inet; 309 reference 310 "RFC 6991: Common YANG Data Types"; 311 } 313 import ietf-tls-client { 314 prefix ts; 315 revision-date 2017-06-13; // stable grouping definitions 316 reference 317 "RFC ZZZZ: TLS Client and Server Models"; 318 } 320 organization 321 "IETF NETCONF (Network Configuration) Working Group"; 323 contact 324 "WG Web: 325 WG List: 327 Author: Kent Watsen 328 330 Author: Gary Wu 331 "; 333 description 334 "This module contains a collection of YANG definitions for 335 configuring RESTCONF clients. 337 Copyright (c) 2014 IETF Trust and the persons identified as 338 authors of the code. All rights reserved. 340 Redistribution and use in source and binary forms, with or 341 without modification, is permitted pursuant to, and subject 342 to the license terms contained in, the Simplified BSD 343 License set forth in Section 4.c of the IETF Trust's 344 Legal Provisions Relating to IETF Documents 345 (http://trustee.ietf.org/license-info). 347 This version of this YANG module is part of RFC XXXX; see 348 the RFC itself for full legal notices."; 350 revision "2017-06-13" { 351 description 352 "Initial version"; 353 reference 354 "RFC XXXX: RESTCONF Client and Server Models"; 355 } 357 // Features 359 feature initiate { 360 description 361 "The 'initiate' feature indicates that the RESTCONF client 362 supports initiating RESTCONF connections to RESTCONF servers 363 using at least one transport (e.g., TLS, etc.)."; 364 } 366 feature tls-initiate { 367 description 368 "The 'tls-initiate' feature indicates that the RESTCONF client 369 supports initiating TLS connections to RESTCONF servers."; 370 reference 371 "RFC 8040: RESTCONF Protocol"; 372 } 374 feature listen { 375 description 376 "The 'listen' feature indicates that the RESTCONF client 377 supports opening a port to accept RESTCONF server call 378 home connections using at least one transport (e.g., 379 TLS, etc.)."; 380 } 382 feature tls-listen { 383 description 384 "The 'tls-listen' feature indicates that the RESTCONF client 385 supports opening a port to listen for incoming RESTCONF 386 server call-home TLS connections."; 387 reference 388 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 390 } 392 grouping restconf-client { 393 description 394 "Top-level grouping for RESTCONF client configuration."; 396 container initiate { 397 if-feature initiate; 398 description 399 "Configures client initiating underlying TCP connections."; 400 list restconf-server { 401 key name; 402 description 403 "List of RESTCONF servers the RESTCONF client is to initiate 404 connections to."; 405 leaf name { 406 type string; 407 description 408 "An arbitrary name for the RESTCONF server."; 409 } 410 choice transport { 411 mandatory true; 412 description 413 "Selects between available transports."; 415 case tls { 416 if-feature tls-initiate; 417 container tls { 418 description 419 "Specifies TLS-specific transport configuration."; 420 uses endpoints-container { 421 refine endpoints/endpoint/port { 422 default 443; 423 } 424 } 425 uses ts:tls-client-grouping { 426 refine "client-auth" { 427 must 'certificate'; 428 description 429 "RESTCONF clients MUST pass a client certiticate."; 430 } 431 } 432 } 433 } // end tls 435 } // end transport 437 container connection-type { 438 description 439 "Indicates the kind of connection to use."; 440 choice connection-type { 441 description 442 "Selects between available connection types."; 443 case persistent-connection { 444 container persistent { 445 presence true; 446 description 447 "Maintain a persistent connection to the RESTCONF 448 server. If the connection goes down, immediately 449 start trying to reconnect to it, using the 450 reconnection strategy. 452 This connection type minimizes any RESTCONF server 453 to RESTCONF client data-transfer delay, albeit at 454 the expense of holding resources longer."; 455 leaf idle-timeout { 456 type uint32; 457 units "seconds"; 458 default 86400; // one day; 459 description 460 "Specifies the maximum number of seconds that a 461 a RESTCONF session may remain idle. A RESTCONF 462 session will be dropped if it is idle for an 463 interval longer than this number of seconds. 464 If set to zero, then the client will never drop 465 a session because it is idle. Sessions that 466 have a notification subscription active are 467 never dropped."; 468 } 469 container keep-alives { 470 description 471 "Configures the keep-alive policy, to proactively 472 test the aliveness of the SSH/TLS server. An 473 unresponsive SSH/TLS server will be dropped after 474 approximately max-attempts * max-wait seconds."; 475 reference 476 "RFC 8071: NETCONF Call Home and RESTCONF Call 477 Home, Section 3.1, item S6"; 478 leaf max-wait { 479 type uint16 { 480 range "1..max"; 481 } 482 units seconds; 483 default 30; 484 description 485 "Sets the amount of time in seconds after which 486 if no data has been received from the SSH/TLS 487 server, a SSH/TLS-level message will be sent 488 to test the aliveness of the SSH/TLS server."; 489 } 490 leaf max-attempts { 491 type uint8; 492 default 3; 493 description 494 "Sets the maximum number of sequential keep-alive 495 messages that can fail to obtain a response from 496 the SSH/TLS server before assuming the SSH/TLS 497 server is no longer alive."; 498 } 499 } 500 } 501 } 502 case periodic-connection { 503 container periodic { 504 presence true; 505 description 506 "Periodically connect to the RESTCONF server, so that 507 the RESTCONF server may deliver messages pending for 508 the RESTCONF client. The RESTCONF server must close 509 the connection when it is ready to release it. Once 510 the connection has been closed, the RESTCONF client 511 will restart its timer until the next connection."; 512 leaf idle-timeout { 513 type uint16; 514 units "seconds"; 515 default 300; // five minutes 516 description 517 "Specifies the maximum number of seconds that a 518 a RESTCONF session may remain idle. A RESTCONF 519 session will be dropped if it is idle for an 520 interval longer than this number of seconds. 521 If set to zero, then the server will never drop 522 a session because it is idle. Sessions that 523 have a notification subscription active are 524 never dropped."; 525 } 526 leaf reconnect-timeout { 527 type uint16 { 528 range "1..max"; 529 } 530 units minutes; 531 default 60; 532 description 533 "Sets the maximum amount of unconnected time the 534 RESTCONF client will wait before re-establishing 535 a connection to the RESTCONF server. The RESTCONF 536 client may initiate a connection before this 537 time if desired (e.g., to set configuration)."; 538 } 539 } 540 } 541 } 542 } 543 container reconnect-strategy { 544 description 545 "The reconnection strategy directs how a RESTCONF client 546 reconnects to a RESTCONF server, after discovering its 547 connection to the server has dropped, even if due to a 548 reboot. The RESTCONF client starts with the specified 549 endpoint and tries to connect to it max-attempts times 550 before trying the next endpoint in the list (round 551 robin)."; 552 leaf start-with { 553 type enumeration { 554 enum first-listed { 555 description 556 "Indicates that reconnections should start with 557 the first endpoint listed."; 558 } 559 enum last-connected { 560 description 561 "Indicates that reconnections should start with 562 the endpoint last connected to. If no previous 563 connection has ever been established, then the 564 first endpoint configured is used. RESTCONF 565 clients SHOULD be able to remember the last 566 endpoint connected to across reboots."; 567 } 568 } 569 default first-listed; 570 description 571 "Specifies which of the RESTCONF server's endpoints the 572 RESTCONF client should start with when trying to connect 573 to the RESTCONF server."; 574 } 575 leaf max-attempts { 576 type uint8 { 577 range "1..max"; 578 } 579 default 3; 580 description 581 "Specifies the number times the RESTCONF client tries to 582 connect to a specific endpoint before moving on to the 583 next endpoint in the list (round robin)."; 584 } 585 } 586 } // end restconf-server 587 } // end initiate 589 container listen { 590 if-feature listen; 591 description 592 "Configures client accepting call-home TCP connections."; 594 leaf max-sessions { 595 type uint16; 596 default 0; 597 description 598 "Specifies the maximum number of concurrent sessions 599 that can be active at one time. The value 0 indicates 600 that no artificial session limit should be used."; 601 } 603 leaf idle-timeout { 604 type uint16; 605 units "seconds"; 606 default 3600; // one hour 607 description 608 "Specifies the maximum number of seconds that a RESTCONF 609 session may remain idle. A RESTCONF session will be dropped 610 if it is idle for an interval longer than this number of 611 seconds. If set to zero, then the server will never drop 612 a session because it is idle. Sessions that have a 613 notification subscription active are never dropped."; 614 } 616 list endpoint { 617 key name; 618 description 619 "List of endpoints to listen for RESTCONF connections."; 620 leaf name { 621 type string; 622 description 623 "An arbitrary name for the RESTCONF listen endpoint."; 624 } 625 choice transport { 626 mandatory true; 627 description 628 "Selects between available transports."; 629 case tls { 630 if-feature tls-listen; 631 container tls { 632 description 633 "TLS-specific listening configuration for inbound 634 connections."; 635 leaf address { 636 type inet:ip-address; 637 description 638 "The IP address to listen for call-home connections."; 639 } 640 leaf port { 641 type inet:port-number; 642 default 4336; 643 description 644 "The port number to listen for call-home connections."; 645 } 646 uses ts:tls-client-grouping { 647 refine "client-auth" { 648 must 'certificate'; 649 description 650 "RESTCONF clients MUST pass a client certiticate."; 651 } 652 } 653 } 654 } 655 } // end transport 656 } // end endpoint 657 } // end listen 659 } // end restconf-client 661 grouping endpoints-container { 662 description 663 "This grouping is used to configure a set of RESTCONF servers 664 a RESTCONF client may initiate connections to."; 665 container endpoints { 666 description 667 "Container for the list of endpoints."; 668 list endpoint { 669 key name; 670 unique "address port"; 671 min-elements 1; 672 ordered-by user; 673 description 674 "A non-empty user-ordered list of endpoints for this RESTCONF 675 client to try to connect to. Defining more than one enables 676 high-availability."; 678 leaf name { 679 type string; 680 description 681 "An arbitrary name for this endpoint."; 682 } 683 leaf address { 684 type inet:host; 685 mandatory true; 686 description 687 "The IP address or hostname of the endpoint. If a 688 hostname is configured and the DNS resolution results 689 in more than one IP address, the RESTCONF client 690 will process the IP addresses as if they had been 691 explicitly configured in place of the hostname."; 692 } 693 leaf port { 694 type inet:port-number; 695 description 696 "The IP port for this endpoint. The RESTCONF client will 697 use the IANA-assigned well-known port (set via a refine 698 statement when uses) if no value is specified."; 699 } 700 } 701 } 702 } 703 } 705 707 3. The RESTCONF Server Model 709 The RESTCONF Server model presented in this section supports servers 710 both listening for connections as well as initiating call-home 711 connections. 713 This model supports the TLS transport protocol using the TLS server 714 groupings defined in [I-D.ietf-netconf-tls-client-server]. 716 All private keys and trusted certificates are held in the keystore 717 model defined in [I-D.ietf-netconf-keystore]. 719 YANG feature statements are used to enable implementations to 720 advertise which parts of the model the RESTCONF server supports. 722 3.1. Tree Diagram 724 Note: all lines are folded at column 71 with no '\' character. 726 module: ietf-restconf-server 727 +--rw restconf-server 728 +--rw listen {listen}? 729 | +--rw max-sessions? uint16 730 | +--rw endpoint* [name] 731 | +--rw name string 732 | +--rw (transport) 733 | +--:(tls) {tls-listen}? 734 | +--rw tls 735 | +--rw address? inet:ip-address 736 | +--rw port? inet:port-number 737 | +--rw certificates 738 | | +--rw certificate* [name] 739 | | +--rw name leafref 740 | +--rw client-auth 741 | | +--rw trusted-ca-certs? leafref 742 | | +--rw trusted-client-certs? leafref 743 | | +--rw cert-maps 744 | | +--rw cert-to-name* [id] 745 | | +--rw id uint32 746 | | +--rw fingerprint x509c2n:tls-fingerprint 747 | | +--rw map-type identityref 748 | | +--rw name string 749 | +--rw hello-params 750 | {tls-server-hello-params-config}? 751 | +--rw tls-versions 752 | | +--rw tls-version* identityref 753 | +--rw cipher-suites 754 | +--rw cipher-suite* identityref 755 +--rw call-home {call-home}? 756 +--rw restconf-client* [name] 757 +--rw name string 758 +--rw (transport) 759 | +--:(tls) {tls-call-home}? 760 | +--rw tls 761 | +--rw endpoints 762 | | +--rw endpoint* [name] 763 | | +--rw name string 764 | | +--rw address inet:host 765 | | +--rw port? inet:port-number 766 | +--rw certificates 767 | | +--rw certificate* [name] 768 | | +--rw name leafref 769 | +--rw client-auth 770 | | +--rw trusted-ca-certs? leafref 771 | | +--rw trusted-client-certs? leafref 772 | | +--rw cert-maps 773 | | +--rw cert-to-name* [id] 774 | | +--rw id uint32 775 | | +--rw fingerprint x509c2n:tls-fingerprint 776 | | +--rw map-type identityref 777 | | +--rw name string 778 | +--rw hello-params 779 | {tls-server-hello-params-config}? 780 | +--rw tls-versions 781 | | +--rw tls-version* identityref 782 | +--rw cipher-suites 783 | +--rw cipher-suite* identityref 784 +--rw connection-type 785 | +--rw (connection-type)? 786 | +--:(persistent-connection) 787 | | +--rw persistent! 788 | | +--rw keep-alives 789 | | +--rw max-wait? uint16 790 | | +--rw max-attempts? uint8 791 | +--:(periodic-connection) 792 | +--rw periodic! 793 | +--rw reconnect-timeout? uint16 794 +--rw reconnect-strategy 795 +--rw start-with? enumeration 796 +--rw max-attempts? uint8 798 3.2. Example Usage 800 The following example illustrates configuring a RESTCONF server to 801 listen for RESTCONF client connections, as well as configuring call- 802 home to one RESTCONF client. 804 This example is consistent with the examples presented in Section 2.2 805 of [I-D.ietf-netconf-keystore]. 807 811 812 813 814 netconf/tls 815 816
11.22.33.44
817 818 819 tls-ec-cert 820 821 822 823 deployment-specific-ca-certs 824 explicitly-trusted-client-certs 825 826 827 1 828 11:0A:05:11:00 829 x509c2n:san-any 830 831 832 2 833 B3:4F:A1:8C:54 834 x509c2n:specified 835 scooby-doo 836 837 838 839 840 841 843 844 845 846 config-manager 847 848 849 850 east-data-center 851
22.33.44.55
852 853 854 west-data-center 855
33.44.55.66
856 857 858 859 860 tls-ec-cert 861 862 863 864 deployment-specific-ca-certs 865 explicitly-trusted-client-certs 866 867 868 1 869 11:0A:05:11:00 870 x509c2n:san-any 871 872 873 2 874 B3:4F:A1:8C:54 875 x509c2n:specified 876 scooby-doo 877 878 879 880 881 882 883 300 884 60 885 886 887 888 last-connected 889 3 890 891 892 894 896 3.3. YANG Model 898 This YANG module imports YANG types from [RFC6991] and [RFC7407]. 900 file "ietf-restconf-server@2017-06-13.yang" 902 module ietf-restconf-server { 903 yang-version 1.1; 905 namespace "urn:ietf:params:xml:ns:yang:ietf-restconf-server"; 906 prefix "rcs"; 908 //import ietf-netconf-acm { 909 // prefix nacm; 910 // reference 911 // "RFC 6536: Network Configuration Protocol (NETCONF) 912 // Access Control Model"; 913 //} 915 import ietf-inet-types { 916 prefix inet; 917 reference 918 "RFC 6991: Common YANG Data Types"; 919 } 921 import ietf-x509-cert-to-name { 922 prefix x509c2n; 923 reference 924 "RFC 7407: A YANG Data Model for SNMP Configuration"; 925 } 927 import ietf-tls-server { 928 prefix ts; 929 revision-date 2017-06-13; // stable grouping definitions 930 reference 931 "RFC ZZZZ: TLS Client and Server Models"; 932 } 934 organization 935 "IETF NETCONF (Network Configuration) Working Group"; 937 contact 938 "WG Web: 939 WG List: 941 WG Chair: Mehmet Ersue 942 944 WG Chair: Mahesh Jethanandani 945 947 Editor: Kent Watsen 948 "; 950 description 951 "This module contains a collection of YANG definitions for 952 configuring RESTCONF servers. 954 Copyright (c) 2014 IETF Trust and the persons identified as 955 authors of the code. All rights reserved. 957 Redistribution and use in source and binary forms, with or 958 without modification, is permitted pursuant to, and subject 959 to the license terms contained in, the Simplified BSD 960 License set forth in Section 4.c of the IETF Trust's 961 Legal Provisions Relating to IETF Documents 962 (http://trustee.ietf.org/license-info). 964 This version of this YANG module is part of RFC XXXX; see 965 the RFC itself for full legal notices."; 967 revision "2017-06-13" { 968 description 969 "Initial version"; 970 reference 971 "RFC XXXX: RESTCONF Client and Server Models"; 972 } 974 // Features 976 feature listen { 977 description 978 "The 'listen' feature indicates that the RESTCONF server 979 supports opening a port to accept RESTCONF client connections 980 using at least one transport (e.g., TLS, etc.)."; 981 } 983 feature tls-listen { 984 description 985 "The 'tls-listen' feature indicates that the RESTCONF server 986 supports opening a port to listen for incoming RESTCONF 987 client connections."; 988 reference 989 "RFC XXXX: RESTCONF Protocol"; 990 } 992 feature call-home { 993 description 994 "The 'call-home' feature indicates that the RESTCONF server 995 supports initiating RESTCONF call home connections to REETCONF 996 clients using at least one transport (e.g., TLS, etc.)."; 997 reference 998 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 999 } 1001 feature tls-call-home { 1002 description 1003 "The 'tls-call-home' feature indicates that the RESTCONF server 1004 supports initiating connections to RESTCONF clients."; 1005 reference 1006 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1008 } 1010 feature client-cert-auth { 1011 description 1012 "The client-cert-auth feature indicates that the RESTCONF 1013 server supports the ClientCertificate authentication scheme."; 1014 reference 1015 "RFC ZZZZ: Client Authentication over New TLS Connection"; 1016 } 1018 // top-level container 1019 container restconf-server { 1020 description 1021 "Top-level container for RESTCONF server configuration."; 1023 container listen { 1024 if-feature listen; 1025 description 1026 "Configures listen behavior"; 1027 leaf max-sessions { 1028 type uint16; 1029 default 0; // should this be 'max'? 1030 description 1031 "Specifies the maximum number of concurrent sessions 1032 that can be active at one time. The value 0 indicates 1033 that no artificial session limit should be used."; 1034 } 1035 list endpoint { 1036 key name; 1037 description 1038 "List of endpoints to listen for RESTCONF connections."; 1039 leaf name { 1040 type string; 1041 description 1042 "An arbitrary name for the RESTCONF listen endpoint."; 1043 } 1044 choice transport { 1045 mandatory true; 1046 description 1047 "Selects between available transports."; 1048 case tls { 1049 if-feature tls-listen; 1050 container tls { 1051 description 1052 "TLS-specific listening configuration for inbound 1053 connections."; 1054 leaf address { 1055 type inet:ip-address; 1056 description 1057 "The IP address of the interface to listen on. The 1058 TLS server will listen on all interfaces if no value 1059 is specified. Please note that some addresses have 1060 special meanings (e.g., '0.0.0.0' and '::')."; 1061 } 1062 leaf port { 1063 type inet:port-number; 1064 default 443; 1065 description 1066 "The local port number on this interface the TLS server 1067 listens on."; 1068 } 1069 uses ts:tls-server-grouping { 1070 augment "client-auth" { 1071 description 1072 "Augments in the cert-to-name structure."; 1073 uses cert-maps-grouping; 1074 } 1075 } 1076 } 1077 } 1078 } 1079 } 1080 } 1082 container call-home { 1083 if-feature call-home; 1084 description 1085 "Configures call-home behavior"; 1086 list restconf-client { 1087 key name; 1088 description 1089 "List of RESTCONF clients the RESTCONF server is to 1090 initiate call-home connections to."; 1091 leaf name { 1092 type string; 1093 description 1094 "An arbitrary name for the remote RESTCONF client."; 1095 } 1096 choice transport { 1097 mandatory true; 1098 description 1099 "Selects between TLS and any transports augmented in."; 1100 case tls { 1101 if-feature tls-call-home; 1102 container tls { 1103 description 1104 "Specifies TLS-specific call-home transport 1105 configuration."; 1106 uses endpoints-container { 1107 refine endpoints/endpoint/port { 1108 default 4336; 1109 } 1110 } 1111 uses ts:tls-server-grouping { 1112 augment "client-auth" { 1113 description 1114 "Augments in the cert-to-name structure."; 1115 uses cert-maps-grouping; 1116 } 1117 } 1118 } 1119 } 1120 } 1121 container connection-type { 1122 description 1123 "Indicates the RESTCONF client's preference for how the 1124 RESTCONF server's connection is maintained."; 1125 choice connection-type { 1126 description 1127 "Selects between available connection types."; 1128 case persistent-connection { 1129 container persistent { 1130 presence true; 1131 description 1132 "Maintain a persistent connection to the RESTCONF 1133 client. If the connection goes down, immediately 1134 start trying to reconnect to it, using the 1135 reconnection strategy. 1137 This connection type minimizes any RESTCONF client 1138 to RESTCONF server data-transfer delay, albeit at 1139 the expense of holding resources longer."; 1141 container keep-alives { 1142 description 1143 "Configures the keep-alive policy, to proactively 1144 test the aliveness of the TLS client. An 1145 unresponsive TLS client will be dropped after 1146 approximately (max-attempts * max-wait) 1147 seconds."; 1148 reference 1149 "RFC 8071: NETCONF Call Home and RESTCONF Call 1150 Home, Section 3.1, item S6"; 1152 leaf max-wait { 1153 type uint16 { 1154 range "1..max"; 1155 } 1156 units seconds; 1157 default 30; 1158 description 1159 "Sets the amount of time in seconds after which 1160 if no data has been received from the TLS 1161 client, a TLS-level message will be sent to 1162 test the aliveness of the TLS client."; 1163 } 1164 leaf max-attempts { 1165 type uint8; 1166 default 3; 1167 description 1168 "Sets the maximum number of sequential keep-alive 1169 messages that can fail to obtain a response from 1170 the TLS client before assuming the TLS client is 1171 no longer alive."; 1172 } 1173 } 1174 } 1175 } 1176 case periodic-connection { 1177 container periodic { 1178 presence true; 1179 description 1180 "Periodically connect to the RESTCONF client, so that 1181 the RESTCONF client may deliver messages pending for 1182 the RESTCONF server. The client must close the 1183 connection when it's ready to release it. Once the 1184 connection has been closed, the server will restart 1185 its timer until the next connection."; 1186 leaf reconnect-timeout { 1187 type uint16 { 1188 range "1..max"; 1189 } 1190 units minutes; 1191 default 60; 1192 description 1193 "The maximum amount of unconnected time the 1194 RESTCONF server will wait before re-establishing 1195 a connection to the RESTCONF client. The 1196 RESTCONF server may initiate a connection to 1197 the RESTCONF client before this time if desired 1198 (e.g., to deliver a notification)."; 1199 } 1201 } 1202 } 1203 } 1204 } 1205 container reconnect-strategy { 1206 description 1207 "The reconnection strategy directs how a RESTCONF server 1208 reconnects to a RESTCONF client after after discovering 1209 its connection to the client has dropped, even if due to 1210 a reboot. The RESTCONF server starts with the specified 1211 endpoint and tries to connect to it max-attempts times 1212 before trying the next endpoint in the list (round 1213 robin)."; 1214 leaf start-with { 1215 type enumeration { 1216 enum first-listed { 1217 description 1218 "Indicates that reconnections should start with 1219 the first endpoint listed."; 1220 } 1221 enum last-connected { 1222 description 1223 "Indicates that reconnections should start with 1224 the endpoint last connected to. If no previous 1225 connection has ever been established, then the 1226 first endpoint configured is used. RESTCONF 1227 servers SHOULD be able to remember the last 1228 endpoint connected to across reboots."; 1229 } 1230 } 1231 default first-listed; 1232 description 1233 "Specifies which of the RESTCONF client's endpoints the 1234 RESTCONF server should start with when trying to connect 1235 to the RESTCONF client."; 1236 } 1237 leaf max-attempts { 1238 type uint8 { 1239 range "1..max"; 1240 } 1241 default 3; 1242 description 1243 "Specifies the number times the RESTCONF server tries to 1244 connect to a specific endpoint before moving on to the 1245 next endpoint in the list (round robin)."; 1246 } 1247 } 1248 } 1250 } 1251 } 1253 grouping cert-maps-grouping { 1254 description 1255 "A grouping that defines a container around the 1256 cert-to-name structure defined in RFC 7407."; 1257 container cert-maps { 1258 uses x509c2n:cert-to-name; 1259 description 1260 "The cert-maps container is used by a TLS-based RESTCONF 1261 server to map the RESTCONF client's presented X.509 1262 certificate to a RESTCONF username. If no matching and 1263 valid cert-to-name list entry can be found, then the 1264 RESTCONF server MUST close the connection, and MUST NOT 1265 accept RESTCONF messages over it."; 1266 reference 1267 "RFC XXXX: The RESTCONF Protocol"; 1268 } 1269 } 1271 grouping endpoints-container { 1272 description 1273 "This grouping is used by tls container for call-home 1274 configurations."; 1275 container endpoints { 1276 description 1277 "Container for the list of endpoints."; 1278 list endpoint { 1279 key name; 1280 unique "address port"; 1281 min-elements 1; 1282 ordered-by user; 1283 description 1284 "User-ordered list of endpoints for this RESTCONF client. 1285 Defining more than one enables high-availability."; 1286 leaf name { 1287 type string; 1288 description 1289 "An arbitrary name for this endpoint."; 1290 } 1291 leaf address { 1292 type inet:host; 1293 mandatory true; 1294 description 1295 "The IP address or hostname of the endpoint. If a 1296 hostname is configured and the DNS resolution results 1297 in more than one IP address, the RESTCONF server 1298 will process the IP addresses as if they had been 1299 explicitly configured in place of the hostname."; 1300 } 1301 leaf port { 1302 type inet:port-number; 1303 description 1304 "The IP port for this endpoint. The RESTCONF server will 1305 use the IANA-assigned well-known port if no value is 1306 specified."; 1307 } 1308 } 1309 } 1310 } 1312 } 1314 1316 4. Security Considerations 1318 The YANG module defined in this document uses a grouping defined in 1319 [I-D.ietf-netconf-tls-client-server]. Please see the Security 1320 Considerations section in that document for concerns related that 1321 grouping. 1323 The YANG module defined in this document is designed to be accessed 1324 via YANG based management protocols, such as NETCONF [RFC6241] and 1325 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 1326 implement secure transport layers (e.g., SSH, TLS) with mutual 1327 authentication. 1329 The NETCONF access control model (NACM) [RFC6536] provides the means 1330 to restrict access for particular users to a pre-configured subset of 1331 all available protocol operations and content. 1333 There are a number of data nodes defined in this YANG module that are 1334 writable/creatable/deletable (i.e., config true, which is the 1335 default). These data nodes may be considered sensitive or vulnerable 1336 in some network environments. Write operations (e.g., edit-config) 1337 to these data nodes without proper protection can have a negative 1338 effect on network operations. These are the subtrees and data nodes 1339 and their sensitivity/vulnerability: 1341 NONE 1343 Some of the readable data nodes in this YANG module may be considered 1344 sensitive or vulnerable in some network environments. It is thus 1345 important to control read access (e.g., via get, get-config, or 1346 notification) to these data nodes. These are the subtrees and data 1347 nodes and their sensitivity/vulnerability: 1349 NONE 1351 Some of the RPC operations in this YANG module may be considered 1352 sensitive or vulnerable in some network environments. It is thus 1353 important to control access to these operations. These are the 1354 operations and their sensitivity/vulnerability: 1356 NONE 1358 5. IANA Considerations 1360 5.1. The IETF XML Registry 1362 This document registers two URIs in the IETF XML registry [RFC3688]. 1363 Following the format in [RFC3688], the following registrations are 1364 requested: 1366 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1367 Registrant Contact: The NETCONF WG of the IETF. 1368 XML: N/A, the requested URI is an XML namespace. 1370 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1371 Registrant Contact: The NETCONF WG of the IETF. 1372 XML: N/A, the requested URI is an XML namespace. 1374 5.2. The YANG Module Names Registry 1376 This document registers two YANG modules in the YANG Module Names 1377 registry [RFC7950]. Following the format in [RFC7950], the the 1378 following registrations are requested: 1380 name: ietf-restconf-client 1381 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-client 1382 prefix: ncc 1383 reference: RFC XXXX 1385 name: ietf-restconf-server 1386 namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-server 1387 prefix: ncs 1388 reference: RFC XXXX 1390 6. Acknowledgements 1392 The authors would like to thank for following for lively discussions 1393 on list and in the halls (ordered by last name): Andy Bierman, Martin 1394 Bjorklund, Benoit Claise, Mehmet Ersue, Balazs Kovacs, David 1395 Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, Tom Petch, 1396 Phil Shafer, Sean Turner, and Bert Wijnen. 1398 Juergen Schoenwaelder and was partly funded by Flamingo, a Network of 1399 Excellence project (ICT-318488) supported by the European Commission 1400 under its Seventh Framework Programme. 1402 7. References 1404 7.1. Normative References 1406 [I-D.ietf-netconf-keystore] 1407 Watsen, K., "Keystore Model", draft-ietf-netconf- 1408 keystore-01 (work in progress), March 2017. 1410 [I-D.ietf-netconf-tls-client-server] 1411 Watsen, K. and G. Wu, "TLS Client and Server Models", 1412 draft-ietf-netconf-tls-client-server-02 (work in 1413 progress), March 2017. 1415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1416 Requirement Levels", BCP 14, RFC 2119, 1417 DOI 10.17487/RFC2119, March 1997, 1418 . 1420 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1421 Protocol (NETCONF) Access Control Model", RFC 6536, 1422 DOI 10.17487/RFC6536, March 2012, 1423 . 1425 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1426 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1427 . 1429 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1430 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1431 December 2014, . 1433 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1434 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1435 . 1437 7.2. Informative References 1439 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1440 DOI 10.17487/RFC3688, January 2004, 1441 . 1443 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1444 (TLS) Protocol Version 1.2", RFC 5246, 1445 DOI 10.17487/RFC5246, August 2008, 1446 . 1448 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1449 and A. Bierman, Ed., "Network Configuration Protocol 1450 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1451 . 1453 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1454 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1455 . 1457 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1458 RFC 8071, DOI 10.17487/RFC8071, February 2017, 1459 . 1461 Appendix A. Change Log 1463 A.1. server-model-09 to 00 1465 o This draft was split out from draft-ietf-netconf-server-model-09. 1467 o Added in new features 'listen' and 'call-home' so future 1468 transports can be augmented in. 1470 A.2. 00 to 01 1472 o Renamed "keychain" to "keystore". 1474 A.3. 01 to 02 1476 o Filled in previously missing 'ietf-restconf-client' module. 1478 o Updated the ietf-restconf-server module to accomodate new grouping 1479 'ietf-tls-server-grouping'. 1481 A.4. 02 to 03 1483 o Refined use of tls-client-grouping to add a must statement 1484 indicating that the TLS client must specify a client-certificate. 1486 o Changed restconf-client??? to be a grouping (not a container). 1488 Authors' Addresses 1490 Kent Watsen 1491 Juniper Networks 1493 EMail: kwatsen@juniper.net 1495 Juergen Schoenwaelder 1496 Jacobs University Bremen 1498 EMail: j.schoenwaelder@jacobs-university.de