idnits 2.17.1 draft-ietf-netconf-netconf-client-server-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 9, 2019) is 1868 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-08 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-08 == Outdated reference: A later version (-02) exists of draft-kwatsen-netconf-tcp-client-server-00 Summary: 0 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF Working Group K. Watsen 3 Internet-Draft Watsen Networks 4 Intended status: Standards Track March 9, 2019 5 Expires: September 10, 2019 7 NETCONF Client and Server Models 8 draft-ietf-netconf-netconf-client-server-10 10 Abstract 12 This document defines two YANG modules, one module to configure a 13 NETCONF client and the other module to configure a NETCONF server. 14 Both modules support both the SSH and TLS transport protocols, and 15 support both standard NETCONF and NETCONF Call Home connections. 17 Editorial Note (To be removed by RFC Editor) 19 This draft contains many placeholder values that need to be replaced 20 with finalized values at the time of publication. This note 21 summarizes all of the substitutions that are needed. No other RFC 22 Editor instructions are specified elsewhere in this document. 24 This document contains references to other drafts in progress, both 25 in the Normative References section, as well as in body text 26 throughout. Please update the following references to reflect their 27 final RFC assignments: 29 o I-D.ietf-netconf-keystore 31 o I-D.ietf-netconf-ssh-client-server 33 o I-D.ietf-netconf-tls-client-server 35 Artwork in this document contains shorthand references to drafts in 36 progress. Please apply the following replacements: 38 o "XXXX" --> the assigned RFC value for this draft 40 o "YYYY" --> the assigned RFC value for I-D.ietf-netconf-ssh-client- 41 server 43 o "ZZZZ" --> the assigned RFC value for I-D.ietf-netconf-tls-client- 44 server 46 o "AAAA" --> the assigned RFC value for I-D.ietf-netconf-tcp-client- 47 server 49 Artwork in this document contains placeholder values for the date of 50 publication of this draft. Please apply the following replacement: 52 o "2019-03-09" --> the publication date of this draft 54 The following Appendix section is to be removed prior to publication: 56 o Appendix A. Change Log 58 Status of This Memo 60 This Internet-Draft is submitted in full conformance with the 61 provisions of BCP 78 and BCP 79. 63 Internet-Drafts are working documents of the Internet Engineering 64 Task Force (IETF). Note that other groups may also distribute 65 working documents as Internet-Drafts. The list of current Internet- 66 Drafts is at https://datatracker.ietf.org/drafts/current/. 68 Internet-Drafts are draft documents valid for a maximum of six months 69 and may be updated, replaced, or obsoleted by other documents at any 70 time. It is inappropriate to use Internet-Drafts as reference 71 material or to cite them other than as "work in progress." 73 This Internet-Draft will expire on September 10, 2019. 75 Copyright Notice 77 Copyright (c) 2019 IETF Trust and the persons identified as the 78 document authors. All rights reserved. 80 This document is subject to BCP 78 and the IETF Trust's Legal 81 Provisions Relating to IETF Documents 82 (https://trustee.ietf.org/license-info) in effect on the date of 83 publication of this document. Please review these documents 84 carefully, as they describe your rights and restrictions with respect 85 to this document. Code Components extracted from this document must 86 include Simplified BSD License text as described in Section 4.e of 87 the Trust Legal Provisions and are provided without warranty as 88 described in the Simplified BSD License. 90 Table of Contents 92 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 93 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 94 3. The NETCONF Client Model . . . . . . . . . . . . . . . . . . 4 95 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 96 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 13 97 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 16 98 4. The NETCONF Server Model . . . . . . . . . . . . . . . . . . 25 99 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 25 100 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 34 101 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 39 102 5. Design Considerations . . . . . . . . . . . . . . . . . . . . 49 103 5.1. Support all NETCONF transports . . . . . . . . . . . . . 50 104 5.2. Enable each transport to select which keys to use . . . . 50 105 5.3. Support authenticating NETCONF clients certificates . . . 50 106 5.4. Support mapping authenticated NETCONF client certificates 107 to usernames . . . . . . . . . . . . . . . . . . . . . . 50 108 5.5. Support both listening for connections and call home . . 50 109 5.6. For Call Home connections . . . . . . . . . . . . . . . . 51 110 5.6.1. Support more than one NETCONF client . . . . . . . . 51 111 5.6.2. Support NETCONF clients having more than one endpoint 51 112 5.6.3. Support a reconnection strategy . . . . . . . . . . . 51 113 5.6.4. Support both persistent and periodic connections . . 51 114 5.6.5. Reconnection strategy for periodic connections . . . 51 115 5.6.6. Keep-alives for persistent connections . . . . . . . 52 116 5.6.7. Customizations for periodic connections . . . . . . . 52 117 6. Security Considerations . . . . . . . . . . . . . . . . . . . 52 118 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 119 7.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 53 120 7.2. The YANG Module Names Registry . . . . . . . . . . . . . 53 121 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 122 8.1. Normative References . . . . . . . . . . . . . . . . . . 54 123 8.2. Informative References . . . . . . . . . . . . . . . . . 55 124 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 56 125 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 56 126 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 56 127 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 56 128 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 56 129 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 56 130 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 57 131 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 57 132 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 57 133 Appendix B. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . 57 134 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 57 135 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 58 137 1. Introduction 139 This document defines two YANG [RFC7950] modules, one module to 140 configure a NETCONF [RFC6241] client and the other module to 141 configure a NETCONF server. Both modules support both NETCONF over 142 SSH [RFC6242] and NETCONF over TLS [RFC7589] and NETCONF Call Home 143 connections [RFC8071]. 145 2. Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 149 "OPTIONAL" in this document are to be interpreted as described in BCP 150 14 [RFC2119] [RFC8174] when, and only when, they appear in all 151 capitals, as shown here. 153 3. The NETCONF Client Model 155 The NETCONF 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 both the SSH and TLS transport protocols, using 160 the SSH client and TLS client groupings defined in 161 [I-D.ietf-netconf-ssh-client-server] and 162 [I-D.ietf-netconf-tls-client-server] respectively. 164 All private keys and trusted certificates are held in the keystore 165 model defined in [I-D.ietf-netconf-keystore]. 167 YANG feature statements are used to enable implementations to 168 advertise which parts of the model the NETCONF client supports. 170 3.1. Tree Diagram 172 The following tree diagram [RFC8340] provides an overview of the data 173 model for the "ietf-netconf-client" module. Just the container is 174 displayed below, but there is also a reusable grouping called 175 "netconf-client-grouping" that the container is using. 177 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 179 module: ietf-netconf-client 180 +--rw netconf-client 181 +--rw initiate! {initiate}? 182 | +--rw netconf-server* [name] 183 | +--rw name string 184 | +--rw endpoints 185 | | +--rw endpoint* [name] 186 | | +--rw name string 187 | | +--rw (transport) 188 | | +--:(ssh) {ssh-initiate}? 189 | | | +--rw ssh 190 | | | +--rw remote-address inet:host 191 | | | +--rw remote-port? 192 | | | | inet:port-number 193 | | | +--rw local-address? inet:ip-addr\ 194 \ess 195 | | | +--rw local-port? 196 | | | | inet:port-number 197 | | | +--rw tcp-keepalives {tcp-client-keepalive\ 198 \s}? 199 | | | | +--rw idle-time? uint16 200 | | | | +--rw max-probes? uint16 201 | | | | +--rw probe-interval? uint16 202 | | | +--rw ssh-client-identity 203 | | | | +--rw username? string 204 | | | | +--rw (auth-type) 205 | | | | +--:(password) 206 | | | | | +--rw password? string 207 | | | | +--:(public-key) 208 | | | | | +--rw public-key 209 | | | | | +--rw (local-or-keystore) 210 | | | | | +--:(local) 211 | | | | | | {local-keys-suppor\ 212 \ted}? 213 | | | | | | +--rw local-definition 214 | | | | | | +--rw algorithm? 215 | | | | | | | asymmetric-ke\ 216 \y-algorithm-ref 217 | | | | | | +--rw public-key? 218 | | | | | | | binary 219 | | | | | | +--rw private-key? 220 | | | | | | | union 221 | | | | | | +---x generate-hidden\ 222 \-key 223 | | | | | | | +---w input 224 | | | | | | | +---w algorithm 225 | | | | | | | asymmet\ 226 \ric-key-algorithm-ref 227 | | | | | | +---x install-hidden-\ 228 \key 229 | | | | | | +---w input 230 | | | | | | +---w algorithm 231 | | | | | | | asymmet\ 232 \ric-key-algorithm-ref 233 | | | | | | +---w public-ke\ 234 \y? 235 | | | | | | | binary 236 | | | | | | +---w private-k\ 237 \ey? 238 | | | | | | binary 239 | | | | | +--:(keystore) 240 | | | | | {keystore-supporte\ 241 \d}? 242 | | | | | +--rw keystore-reference? 243 | | | | | ks:asymmetric-ke\ 244 \y-ref 245 | | | | +--:(certificate) 246 | | | | +--rw certificate 247 | | | | {sshcmn:ssh-x509-certs}? 248 | | | | +--rw (local-or-keystore) 249 | | | | +--:(local) 250 | | | | | {local-keys-suppor\ 251 \ted}? 252 | | | | | +--rw local-definition 253 | | | | | +--rw algorithm? 254 | | | | | | asymmetric-ke\ 255 \y-algorithm-ref 256 | | | | | +--rw public-key? 257 | | | | | | binary 258 | | | | | +--rw private-key? 259 | | | | | | union 260 | | | | | +---x generate-hidden\ 261 \-key 262 | | | | | | +---w input 263 | | | | | | +---w algorithm 264 | | | | | | asymmet\ 265 \ric-key-algorithm-ref 266 | | | | | +---x install-hidden-\ 267 \key 268 | | | | | | +---w input 269 | | | | | | +---w algorithm 270 | | | | | | | asymmet\ 271 \ric-key-algorithm-ref 272 | | | | | | +---w public-ke\ 273 \y? 274 | | | | | | | binary 275 | | | | | | +---w private-k\ 276 \ey? 277 | | | | | | binary 278 | | | | | +--rw cert? 279 | | | | | | end-entity-ce\ 280 \rt-cms 281 | | | | | +---n certificate-exp\ 282 \iration 283 | | | | | +-- expiration-date 284 | | | | | yang:date-\ 285 \and-time 286 | | | | +--:(keystore) 287 | | | | {keystore-supporte\ 288 \d}? 289 | | | | +--rw keystore-reference? 290 | | | | ks:asymmetric-ke\ 291 \y-certificate-ref 292 | | | +--rw ssh-server-auth 293 | | | | +--rw pinned-ssh-host-keys? 294 | | | | | ta:pinned-host-keys-ref 295 | | | | | {ta:ssh-host-keys}? 296 | | | | +--rw pinned-ca-certs? 297 | | | | | ta:pinned-certificates-ref 298 | | | | | {sshcmn:ssh-x509-certs,ta:x509-\ 299 \certificates}? 300 | | | | +--rw pinned-server-certs? 301 | | | | ta:pinned-certificates-ref 302 | | | | {sshcmn:ssh-x509-certs,ta:x509-\ 303 \certificates}? 304 | | | +--rw ssh-transport-params 305 | | | | {ssh-client-transport-params-confi\ 306 \g}? 307 | | | | +--rw host-key 308 | | | | | +--rw host-key-alg* identityref 309 | | | | +--rw key-exchange 310 | | | | | +--rw key-exchange-alg* identityref 311 | | | | +--rw encryption 312 | | | | | +--rw encryption-alg* identityref 313 | | | | +--rw mac 314 | | | | +--rw mac-alg* identityref 315 | | | +--rw ssh-keepalives {ssh-client-keepalive\ 316 \s}? 317 | | | +--rw max-wait? uint16 318 | | | +--rw max-attempts? uint8 319 | | +--:(tls) {tls-initiate}? 320 | | +--rw tls 321 | | +--rw remote-address inet:host 322 | | +--rw remote-port? inet:port-num\ 323 \ber 324 | | +--rw local-address? inet:ip-addre\ 325 \ss 326 | | +--rw local-port? inet:port-num\ 327 \ber 328 | | +--rw tcp-keepalives {tcp-client-keepalive\ 330 \s}? 331 | | | +--rw idle-time? uint16 332 | | | +--rw max-probes? uint16 333 | | | +--rw probe-interval? uint16 334 | | +--rw tls-client-identity 335 | | | +--rw (auth-type) 336 | | | +--:(certificate) 337 | | | +--rw certificate 338 | | | +--rw (local-or-keystore) 339 | | | +--:(local) 340 | | | | {local-keys-suppor\ 341 \ted}? 342 | | | | +--rw local-definition 343 | | | | +--rw algorithm? 344 | | | | | asymmetric-ke\ 345 \y-algorithm-ref 346 | | | | +--rw public-key? 347 | | | | | binary 348 | | | | +--rw private-key? 349 | | | | | union 350 | | | | +---x generate-hidden\ 351 \-key 352 | | | | | +---w input 353 | | | | | +---w algorithm 354 | | | | | asymmet\ 355 \ric-key-algorithm-ref 356 | | | | +---x install-hidden-\ 357 \key 358 | | | | | +---w input 359 | | | | | +---w algorithm 360 | | | | | | asymmet\ 361 \ric-key-algorithm-ref 362 | | | | | +---w public-ke\ 363 \y? 364 | | | | | | binary 365 | | | | | +---w private-k\ 366 \ey? 367 | | | | | binary 368 | | | | +--rw cert? 369 | | | | | end-entity-ce\ 370 \rt-cms 371 | | | | +---n certificate-exp\ 372 \iration 373 | | | | +-- expiration-date 374 | | | | yang:date-\ 375 \and-time 376 | | | +--:(keystore) 377 | | | {keystore-supporte\ 379 \d}? 380 | | | +--rw keystore-reference? 381 | | | ks:asymmetric-ke\ 382 \y-certificate-ref 383 | | +--rw tls-server-auth 384 | | | +--rw pinned-ca-certs? 385 | | | | ta:pinned-certificates-ref 386 | | | | {ta:x509-certificates}? 387 | | | +--rw pinned-server-certs? 388 | | | ta:pinned-certificates-ref 389 | | | {ta:x509-certificates}? 390 | | +--rw tls-hello-params 391 | | | {tls-client-hello-params-config}? 392 | | | +--rw tls-versions 393 | | | | +--rw tls-version* identityref 394 | | | +--rw cipher-suites 395 | | | +--rw cipher-suite* identityref 396 | | +--rw tls-keepalives {tls-client-keepalive\ 397 \s}? 398 | | +--rw max-wait? uint16 399 | | +--rw max-attempts? uint8 400 | +--rw connection-type 401 | | +--rw (connection-type) 402 | | +--:(persistent-connection) 403 | | | +--rw persistent! 404 | | +--:(periodic-connection) 405 | | +--rw periodic! 406 | | +--rw period? uint16 407 | | +--rw anchor-time? yang:date-and-time 408 | | +--rw idle-timeout? uint16 409 | +--rw reconnect-strategy 410 | +--rw start-with? enumeration 411 | +--rw max-attempts? uint8 412 +--rw listen! {listen}? 413 +--rw idle-timeout? uint16 414 +--rw endpoint* [name] 415 +--rw name string 416 +--rw (transport) 417 +--:(ssh) {ssh-listen}? 418 | +--rw ssh 419 | +--rw local-address inet:ip-address 420 | +--rw local-port? inet:port-number 421 | +--rw tcp-keepalives {tcp-server-keepalives}? 422 | | +--rw idle-time? uint16 423 | | +--rw max-probes? uint16 424 | | +--rw probe-interval? uint16 425 | +--rw ssh-client-identity 426 | | +--rw username? string 427 | | +--rw (auth-type) 428 | | +--:(password) 429 | | | +--rw password? string 430 | | +--:(public-key) 431 | | | +--rw public-key 432 | | | +--rw (local-or-keystore) 433 | | | +--:(local) {local-keys-supported\ 434 \}? 435 | | | | +--rw local-definition 436 | | | | +--rw algorithm? 437 | | | | | asymmetric-key-algo\ 438 \rithm-ref 439 | | | | +--rw public-key? 440 | | | | | binary 441 | | | | +--rw private-key? 442 | | | | | union 443 | | | | +---x generate-hidden-key 444 | | | | | +---w input 445 | | | | | +---w algorithm 446 | | | | | asymmetric-ke\ 447 \y-algorithm-ref 448 | | | | +---x install-hidden-key 449 | | | | +---w input 450 | | | | +---w algorithm 451 | | | | | asymmetric-ke\ 452 \y-algorithm-ref 453 | | | | +---w public-key? 454 | | | | | binary 455 | | | | +---w private-key? 456 | | | | binary 457 | | | +--:(keystore) {keystore-supporte\ 458 \d}? 459 | | | +--rw keystore-reference? 460 | | | ks:asymmetric-key-ref 461 | | +--:(certificate) 462 | | +--rw certificate {sshcmn:ssh-x509-cert\ 463 \s}? 464 | | +--rw (local-or-keystore) 465 | | +--:(local) {local-keys-supported\ 466 \}? 467 | | | +--rw local-definition 468 | | | +--rw algorithm? 469 | | | | asymmetric-key-algo\ 470 \rithm-ref 471 | | | +--rw public-key? 472 | | | | binary 473 | | | +--rw private-key? 474 | | | | union 475 | | | +---x generate-hidden-key 476 | | | | +---w input 477 | | | | +---w algorithm 478 | | | | asymmetric-ke\ 479 \y-algorithm-ref 480 | | | +---x install-hidden-key 481 | | | | +---w input 482 | | | | +---w algorithm 483 | | | | | asymmetric-ke\ 484 \y-algorithm-ref 485 | | | | +---w public-key? 486 | | | | | binary 487 | | | | +---w private-key? 488 | | | | binary 489 | | | +--rw cert? 490 | | | | end-entity-cert-cms 491 | | | +---n certificate-expiration 492 | | | +-- expiration-date 493 | | | yang:date-and-ti\ 494 \me 495 | | +--:(keystore) {keystore-supporte\ 496 \d}? 497 | | +--rw keystore-reference? 498 | | ks:asymmetric-key-cert\ 499 \ificate-ref 500 | +--rw ssh-server-auth 501 | | +--rw pinned-ssh-host-keys? 502 | | | ta:pinned-host-keys-ref 503 | | | {ta:ssh-host-keys}? 504 | | +--rw pinned-ca-certs? 505 | | | ta:pinned-certificates-ref 506 | | | {sshcmn:ssh-x509-certs,ta:x509-certif\ 507 \icates}? 508 | | +--rw pinned-server-certs? 509 | | ta:pinned-certificates-ref 510 | | {sshcmn:ssh-x509-certs,ta:x509-certif\ 511 \icates}? 512 | +--rw ssh-transport-params 513 | | {ssh-client-transport-params-config}? 514 | | +--rw host-key 515 | | | +--rw host-key-alg* identityref 516 | | +--rw key-exchange 517 | | | +--rw key-exchange-alg* identityref 518 | | +--rw encryption 519 | | | +--rw encryption-alg* identityref 520 | | +--rw mac 521 | | +--rw mac-alg* identityref 522 | +--rw ssh-keepalives {ssh-client-keepalives}? 523 | +--rw max-wait? uint16 524 | +--rw max-attempts? uint8 525 +--:(tls) {tls-listen}? 526 +--rw tls 527 +--rw local-address inet:ip-address 528 +--rw local-port? inet:port-number 529 +--rw tcp-keepalives {tcp-server-keepalives}? 530 | +--rw idle-time? uint16 531 | +--rw max-probes? uint16 532 | +--rw probe-interval? uint16 533 +--rw tls-client-identity 534 | +--rw (auth-type) 535 | +--:(certificate) 536 | +--rw certificate 537 | +--rw (local-or-keystore) 538 | +--:(local) {local-keys-supported\ 539 \}? 540 | | +--rw local-definition 541 | | +--rw algorithm? 542 | | | asymmetric-key-algo\ 543 \rithm-ref 544 | | +--rw public-key? 545 | | | binary 546 | | +--rw private-key? 547 | | | union 548 | | +---x generate-hidden-key 549 | | | +---w input 550 | | | +---w algorithm 551 | | | asymmetric-ke\ 552 \y-algorithm-ref 553 | | +---x install-hidden-key 554 | | | +---w input 555 | | | +---w algorithm 556 | | | | asymmetric-ke\ 557 \y-algorithm-ref 558 | | | +---w public-key? 559 | | | | binary 560 | | | +---w private-key? 561 | | | binary 562 | | +--rw cert? 563 | | | end-entity-cert-cms 564 | | +---n certificate-expiration 565 | | +-- expiration-date 566 | | yang:date-and-ti\ 567 \me 568 | +--:(keystore) {keystore-supporte\ 569 \d}? 570 | +--rw keystore-reference? 571 | ks:asymmetric-key-cert\ 572 \ificate-ref 573 +--rw tls-server-auth 574 | +--rw pinned-ca-certs? 575 | | ta:pinned-certificates-ref 576 | | {ta:x509-certificates}? 577 | +--rw pinned-server-certs? 578 | ta:pinned-certificates-ref 579 | {ta:x509-certificates}? 580 +--rw tls-hello-params 581 | {tls-client-hello-params-config}? 582 | +--rw tls-versions 583 | | +--rw tls-version* identityref 584 | +--rw cipher-suites 585 | +--rw cipher-suite* identityref 586 +--rw tls-keepalives {tls-client-keepalives}? 587 +--rw max-wait? uint16 588 +--rw max-attempts? uint8 590 3.2. Example Usage 592 The following example illustrates configuring a NETCONF client to 593 initiate connections, using both the SSH and TLS transport protocols, 594 as well as listening for call-home connections, again using both the 595 SSH and TLS transport protocols. 597 This example is consistent with the examples presented in Section 3.2 598 of [I-D.ietf-netconf-keystore]. 600 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 602 605 606 607 608 corp-fw1 609 610 611 corp-fw1.example.com 612 613 corp-fw1.example.com 614 615 15 616 3 617 30 618 619 620 foobar 621 622 623 ct:rsa2048 625 base64encodedvalue== 626 base64encodedvalue== 627 628 629 630 631 explicitly-trusted-server-ca-certs 633 explicitly-trusted-server-certs 635 636 637 30 638 3 639 640 641 642 643 corp-fw2.example.com 644 645 corp-fw2.example.com 646 647 15 648 3 649 30 650 651 652 foobar 653 654 655 ct:rsa2048 657 base64encodedvalue== 658 base64encodedvalue== 659 660 661 662 663 explicitly-trusted-server-ca-certs 665 explicitly-trusted-server-certs 667 668 669 30 670 3 671 672 673 674 675 676 677 678 679 last-connected 680 681 682 684 685 686 687 Intranet-facing listener 688 689 192.0.2.7 690 691 foobar 692 693 694 ct:rsa2048 696 base64encodedvalue== 697 base64encodedvalue== 698 699 700 701 702 explicitly-trusted-server-ca-certs 704 explicitly-trusted-server-certs 706 explicitly-trusted-ssh-host-keys 708 709 710 711 712 714 3.3. YANG Module 716 This YANG module has normative references to [RFC6242], [RFC6991], 717 [RFC7589], [RFC8071], [I-D.kwatsen-netconf-tcp-client-server], 718 [I-D.ietf-netconf-ssh-client-server], and 719 [I-D.ietf-netconf-tls-client-server]. 721 file "ietf-netconf-client@2019-03-09.yang" 722 module ietf-netconf-client { 723 yang-version 1.1; 724 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-client"; 725 prefix ncc; 727 import ietf-yang-types { 728 prefix yang; 729 reference 730 "RFC 6991: Common YANG Data Types"; 731 } 733 import ietf-tcp-client { 734 prefix tcpc; 735 reference 736 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 737 } 738 import ietf-tcp-server { 739 prefix tcps; 740 reference 741 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 742 } 744 import ietf-ssh-client { 745 prefix sshc; 746 revision-date 2019-03-09; // stable grouping definitions 747 reference 748 "RFC YYYY: YANG Groupings for SSH Clients and SSH Servers"; 749 } 751 import ietf-tls-client { 752 prefix tlsc; 753 revision-date 2019-03-09; // stable grouping definitions 754 reference 755 "RFC ZZZZ: YANG Groupings for TLS Clients and TLS Servers"; 756 } 758 organization 759 "IETF NETCONF (Network Configuration) Working Group"; 761 contact 762 "WG Web: 763 WG List: 764 Author: Kent Watsen 765 Author: Gary Wu "; 767 description 768 "This module contains a collection of YANG definitions for 769 configuring NETCONF clients. 771 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 772 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 773 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 774 are to be interpreted as described in BCP 14 [RFC2119] 775 [RFC8174] when, and only when, they appear in all 776 capitals, as shown here. 778 Copyright (c) 2019 IETF Trust and the persons identified as 779 authors of the code. All rights reserved. 781 Redistribution and use in source and binary forms, with or 782 without modification, is permitted pursuant to, and subject 783 to the license terms contained in, the Simplified BSD 784 License set forth in Section 4.c of the IETF Trust's 785 Legal Provisions Relating to IETF Documents 786 (http://trustee.ietf.org/license-info). 788 This version of this YANG module is part of RFC XXXX; see 789 the RFC itself for full legal notices."; 791 revision 2019-03-09 { 792 description 793 "Initial version"; 794 reference 795 "RFC XXXX: NETCONF Client and Server Models"; 796 } 798 // Features 800 feature initiate { 801 description 802 "The 'initiate' feature indicates that the NETCONF client 803 supports initiating NETCONF connections to NETCONF servers 804 using at least one transport (e.g., SSH, TLS, etc.)."; 805 } 807 feature ssh-initiate { 808 description 809 "The 'ssh-initiate' feature indicates that the NETCONF client 810 supports initiating SSH connections to NETCONF servers."; 811 reference 812 "RFC 6242: 813 Using the NETCONF Protocol over Secure Shell (SSH)"; 814 } 816 feature tls-initiate { 817 description 818 "The 'tls-initiate' feature indicates that the NETCONF client 819 supports initiating TLS connections to NETCONF servers."; 820 reference 821 "RFC 7589: Using the NETCONF Protocol over Transport 822 Layer Security (TLS) with Mutual X.509 Authentication"; 823 } 825 feature listen { 826 description 827 "The 'listen' feature indicates that the NETCONF client 828 supports opening a port to accept NETCONF server call 829 home connections using at least one transport (e.g., 830 SSH, TLS, etc.)."; 831 } 833 feature ssh-listen { 834 description 835 "The 'ssh-listen' feature indicates that the NETCONF client 836 supports opening a port to listen for incoming NETCONF 837 server call-home SSH connections."; 838 reference 839 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 840 } 842 feature tls-listen { 843 description 844 "The 'tls-listen' feature indicates that the NETCONF client 845 supports opening a port to listen for incoming NETCONF 846 server call-home TLS connections."; 847 reference 848 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 849 } 851 // Groupings 853 grouping netconf-client-grouping { 854 description 855 "Top-level grouping for NETCONF client configuration."; 856 container initiate { 857 if-feature "initiate"; 858 presence "Enables client to initiate TCP connections"; 859 description 860 "Configures client initiating underlying TCP connections."; 861 list netconf-server { 862 key "name"; 863 min-elements 1; 864 description 865 "List of NETCONF servers the NETCONF client is to 866 initiate connections to in parallel."; 867 leaf name { 868 type string; 869 description 870 "An arbitrary name for the NETCONF server."; 871 } 872 container endpoints { 873 description 874 "Container for the list of endpoints."; 875 list endpoint { 876 key "name"; 877 min-elements 1; 878 ordered-by user; 879 description 880 "A user-ordered list of endpoints that the NETCONF 881 client will attempt to connect to in the specified 882 sequence. Defining more than one enables 883 high-availability."; 884 leaf name { 885 type string; 886 description 887 "An arbitrary name for the endpoint."; 888 } 889 choice transport { 890 mandatory true; 891 description 892 "Selects between available transports."; 893 case ssh { 894 if-feature "ssh-initiate"; 895 container ssh { 896 description 897 "Specifies IP and SSH specific configuration 898 for the connection."; 899 uses tcpc:tcp-client-grouping { 900 refine "remote-port" { 901 default "830"; 902 description 903 "The NETCONF client will attempt to connect 904 to the IANA-assigned well-known port value 905 for 'netconf-ssh' (443) if no value is 906 specified."; 907 } 908 } 909 uses sshc:ssh-client-grouping; 910 } 911 } 912 case tls { 913 if-feature "tls-initiate"; 914 container tls { 915 description 916 "Specifies IP and TLS specific configuration 917 for the connection."; 918 uses tcpc:tcp-client-grouping { 919 refine "remote-port" { 920 default "6513"; 921 description 922 "The NETCONF client will attempt to connect 923 to the IANA-assigned well-known port value 924 for 'netconf-tls' (6513) if no value is 925 specified."; 926 } 927 } 928 uses tlsc:tls-client-grouping { 929 refine "tls-client-identity/auth-type" { 930 mandatory true; 931 description 932 "NETCONF/TLS clients MUST pass some 933 authentication credentials."; 934 } 935 } 936 } 937 } 938 } // choice transport 939 } // list endpoint 940 } // container endpoints 942 container connection-type { 943 description 944 "Indicates the NETCONF client's preference for how the 945 NETCONF connection is maintained."; 946 choice connection-type { 947 mandatory true; 948 description 949 "Selects between available connection types."; 950 case persistent-connection { 951 container persistent { 952 presence "Indicates that a persistent connection is 953 to be maintained."; 955 description 956 "Maintain a persistent connection to the NETCONF 957 server. If the connection goes down, immediately 958 start trying to reconnect to it, using the 959 reconnection strategy. 961 This connection type minimizes any NETCONF server 962 to NETCONF client data-transfer delay, albeit at 963 the expense of holding resources longer."; 964 } 965 } 966 case periodic-connection { 967 container periodic { 968 presence "Indicates that a periodic connection is 969 to be maintained."; 970 description 971 "Periodically connect to the NETCONF server. The 972 NETCONF server should close the connection upon 973 completing planned activities. 975 This connection type increases resource 976 utilization, albeit with increased delay in 977 NETCONF server to NETCONF client interactions."; 978 leaf period { 979 type uint16; 980 units "minutes"; 981 default "60"; 982 description 983 "Duration of time between periodic connections."; 984 } 985 leaf anchor-time { 986 type yang:date-and-time { 987 // constrained to minute-level granularity 988 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 989 + '(Z|[\+\-]\d{2}:\d{2})'; 990 } 991 description 992 "Designates a timestamp before or after which a 993 series of periodic connections are determined. 994 The periodic connections occur at a whole 995 multiple interval from the anchor time. For 996 example, for an anchor time is 15 minutes past 997 midnight and a period interval of 24 hours, then 998 a periodic connection will occur 15 minutes past 999 midnight everyday."; 1000 } 1001 leaf idle-timeout { 1002 type uint16; 1003 units "seconds"; 1004 default 120; // two minutes 1005 description 1006 "Specifies the maximum number of seconds that 1007 a NETCONF session may remain idle. A NETCONF 1008 session will be dropped if it is idle for an 1009 interval longer than this number of seconds. 1010 If set to zero, then the NETCONF client will 1011 never drop a session because it is idle."; 1012 } 1013 } 1014 } 1015 } 1016 } 1017 container reconnect-strategy { 1018 description 1019 "The reconnection strategy directs how a NETCONF client 1020 reconnects to a NETCONF server, after discovering its 1021 connection to the server has dropped, even if due to a 1022 reboot. The NETCONF client starts with the specified 1023 endpoint and tries to connect to it max-attempts times 1024 before trying the next endpoint in the list (round 1025 robin)."; 1026 leaf start-with { 1027 type enumeration { 1028 enum first-listed { 1029 description 1030 "Indicates that reconnections should start with 1031 the first endpoint listed."; 1032 } 1033 enum last-connected { 1034 description 1035 "Indicates that reconnections should start with 1036 the endpoint last connected to. If no previous 1037 connection has ever been established, then the 1038 first endpoint configured is used. NETCONF 1039 clients SHOULD be able to remember the last 1040 endpoint connected to across reboots."; 1041 } 1042 enum random-selection { 1043 description 1044 "Indicates that reconnections should start with 1045 a random endpoint."; 1046 } 1047 } 1048 default "first-listed"; 1049 description 1050 "Specifies which of the NETCONF server's endpoints 1051 the NETCONF client should start with when trying 1052 to connect to the NETCONF server."; 1053 } 1054 leaf max-attempts { 1055 type uint8 { 1056 range "1..max"; 1057 } 1058 default "3"; 1059 description 1060 "Specifies the number times the NETCONF client tries 1061 to connect to a specific endpoint before moving on 1062 to the next endpoint in the list (round robin)."; 1063 } 1064 } 1065 } // netconf-server 1066 } // initiate 1068 container listen { 1069 if-feature "listen"; 1070 presence "Enables client to accept call-home connections"; 1071 description 1072 "Configures client accepting call-home TCP connections."; 1073 leaf idle-timeout { 1074 type uint16; 1075 units "seconds"; 1076 default "3600"; // one hour 1077 description 1078 "Specifies the maximum number of seconds that a NETCONF 1079 session may remain idle. A NETCONF session will be 1080 dropped if it is idle for an interval longer than this 1081 number of seconds. If set to zero, then the server 1082 will never drop a session because it is idle. Sessions 1083 that have a notification subscription active are never 1084 dropped."; 1085 } 1086 list endpoint { 1087 key "name"; 1088 min-elements 1; 1089 description 1090 "List of endpoints to listen for NETCONF connections."; 1091 leaf name { 1092 type string; 1093 description 1094 "An arbitrary name for the NETCONF listen endpoint."; 1095 } 1096 choice transport { 1097 mandatory true; 1098 description 1099 "Selects between available transports."; 1100 case ssh { 1101 if-feature "ssh-listen"; 1102 container ssh { 1103 description 1104 "SSH-specific listening configuration for inbound 1105 connections."; 1106 uses tcps:tcp-server-grouping { 1107 refine "local-port" { 1108 default "4334"; 1109 description 1110 "The NETCONF client will listen on the IANA- 1111 assigned well-known port for 'netconf-ch-ssh' 1112 (4334) if no value is specified."; 1113 } 1114 } 1115 uses sshc:ssh-client-grouping; 1116 } 1117 } 1118 case tls { 1119 if-feature "tls-listen"; 1120 container tls { 1121 description 1122 "TLS-specific listening configuration for inbound 1123 connections."; 1124 uses tcps:tcp-server-grouping { 1125 refine "local-port" { 1126 default "4334"; 1127 description 1128 "The NETCONF client will listen on the IANA- 1129 assigned well-known port for 'netconf-ch-ssh' 1130 (4334) if no value is specified."; 1131 } 1132 } 1133 uses tlsc:tls-client-grouping { 1134 refine "tls-client-identity/auth-type" { 1135 mandatory true; 1136 description 1137 "NETCONF/TLS clients MUST pass some 1138 authentication credentials."; 1139 } 1140 } 1141 } 1142 } 1143 } // transport 1144 } // endpoint 1145 } // listen 1146 } // netconf-client 1147 // Protocol accessible node, for servers that implement this 1148 // module. 1150 container netconf-client { 1151 uses netconf-client-grouping; 1152 description 1153 "Top-level container for NETCONF client configuration."; 1154 } 1155 } 1156 1158 4. The NETCONF Server Model 1160 The NETCONF server model presented in this section supports servers 1161 both listening for connections as well as initiating call-home 1162 connections. 1164 This model supports both the SSH and TLS transport protocols, using 1165 the SSH server and TLS server groupings defined in 1166 [I-D.ietf-netconf-ssh-client-server] and 1167 [I-D.ietf-netconf-tls-client-server] respectively. 1169 All private keys and trusted certificates are held in the keystore 1170 model defined in [I-D.ietf-netconf-keystore]. 1172 YANG feature statements are used to enable implementations to 1173 advertise which parts of the model the NETCONF server supports. 1175 4.1. Tree Diagram 1177 The following tree diagram [RFC8340] provides an overview of the data 1178 model for the "ietf-netconf-server" module. Just the container is 1179 displayed below, but there is also a reusable grouping called 1180 "netconf-server-grouping" that the container is using. 1182 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1184 module: ietf-netconf-server 1185 +--rw netconf-server 1186 +--rw listen! {listen}? 1187 | +--rw idle-timeout? uint16 1188 | +--rw endpoint* [name] 1189 | +--rw name string 1190 | +--rw (transport) 1191 | +--:(ssh) {ssh-listen}? 1192 | | +--rw ssh 1193 | | +--rw local-address inet:ip-address 1194 | | +--rw local-port? inet:port-number 1195 | | +--rw tcp-keepalives {tcp-server-keepalives}? 1196 | | | +--rw idle-time? uint16 1197 | | | +--rw max-probes? uint16 1198 | | | +--rw probe-interval? uint16 1199 | | +--rw ssh-server-identity 1200 | | | +--rw host-key* [name] 1201 | | | +--rw name string 1202 | | | +--rw (host-key-type) 1203 | | | +--:(public-key) 1204 | | | | +--rw public-key 1205 | | | | +--rw (local-or-keystore) 1206 | | | | +--:(local) 1207 | | | | | {local-keys-supported\ 1208 \}? 1209 | | | | | +--rw local-definition 1210 | | | | | +--rw algorithm? 1211 | | | | | | asymmetric-key-a\ 1212 \lgorithm-ref 1213 | | | | | +--rw public-key? 1214 | | | | | | binary 1215 | | | | | +--rw private-key? 1216 | | | | | | union 1217 | | | | | +---x generate-hidden-key 1218 | | | | | | +---w input 1219 | | | | | | +---w algorithm 1220 | | | | | | asymmetric\ 1221 \-key-algorithm-ref 1222 | | | | | +---x install-hidden-key 1223 | | | | | +---w input 1224 | | | | | +---w algorithm 1225 | | | | | | asymmetric\ 1226 \-key-algorithm-ref 1227 | | | | | +---w public-key? 1228 | | | | | | binary 1229 | | | | | +---w private-key? 1230 | | | | | binary 1231 | | | | +--:(keystore) 1232 | | | | {keystore-supported}? 1233 | | | | +--rw keystore-reference? 1234 | | | | ks:asymmetric-key-r\ 1235 \ef 1236 | | | +--:(certificate) 1237 | | | +--rw certificate 1238 | | | {sshcmn:ssh-x509-certs}? 1239 | | | +--rw (local-or-keystore) 1240 | | | +--:(local) 1241 | | | | {local-keys-supported\ 1242 \}? 1243 | | | | +--rw local-definition 1244 | | | | +--rw algorithm? 1245 | | | | | asymmetric-key-a\ 1246 \lgorithm-ref 1247 | | | | +--rw public-key? 1248 | | | | | binary 1249 | | | | +--rw private-key? 1250 | | | | | union 1251 | | | | +---x generate-hidden-key 1252 | | | | | +---w input 1253 | | | | | +---w algorithm 1254 | | | | | asymmetric\ 1255 \-key-algorithm-ref 1256 | | | | +---x install-hidden-key 1257 | | | | | +---w input 1258 | | | | | +---w algorithm 1259 | | | | | | asymmetric\ 1260 \-key-algorithm-ref 1261 | | | | | +---w public-key? 1262 | | | | | | binary 1263 | | | | | +---w private-key? 1264 | | | | | binary 1265 | | | | +--rw cert? 1266 | | | | | end-entity-cert-\ 1267 \cms 1268 | | | | +---n certificate-expira\ 1269 \tion 1270 | | | | +-- expiration-date 1271 | | | | yang:date-and\ 1272 \-time 1273 | | | +--:(keystore) 1274 | | | {keystore-supported}? 1275 | | | +--rw keystore-reference? 1276 | | | ks:asymmetric-key-c\ 1277 \ertificate-ref 1278 | | +--rw ssh-client-cert-auth {sshcmn:ssh-x509-cert\ 1279 \s}? 1280 | | | +--rw pinned-ca-certs? 1281 | | | | ta:pinned-certificates-ref 1282 | | | | {ta:x509-certificates}? 1283 | | | +--rw pinned-client-certs? 1284 | | | ta:pinned-certificates-ref 1285 | | | {ta:x509-certificates}? 1286 | | +--rw ssh-transport-params 1287 | | | {ssh-server-transport-params-config}? 1288 | | | +--rw host-key 1289 | | | | +--rw host-key-alg* identityref 1290 | | | +--rw key-exchange 1291 | | | | +--rw key-exchange-alg* identityref 1292 | | | +--rw encryption 1293 | | | | +--rw encryption-alg* identityref 1294 | | | +--rw mac 1295 | | | +--rw mac-alg* identityref 1296 | | +--rw ssh-keepalives {ssh-server-keepalives}? 1297 | | +--rw max-wait? uint16 1298 | | +--rw max-attempts? uint8 1299 | +--:(tls) {tls-listen}? 1300 | +--rw tls 1301 | +--rw local-address inet:ip-address 1302 | +--rw local-port? inet:port-number 1303 | +--rw tcp-keepalives {tcp-server-keepalives}? 1304 | | +--rw idle-time? uint16 1305 | | +--rw max-probes? uint16 1306 | | +--rw probe-interval? uint16 1307 | +--rw tls-server-identity 1308 | | +--rw (local-or-keystore) 1309 | | +--:(local) {local-keys-supported}? 1310 | | | +--rw local-definition 1311 | | | +--rw algorithm? 1312 | | | | asymmetric-key-algorithm-ref 1313 | | | +--rw public-key? bina\ 1314 \ry 1315 | | | +--rw private-key? union 1316 | | | +---x generate-hidden-key 1317 | | | | +---w input 1318 | | | | +---w algorithm 1319 | | | | asymmetric-key-algorit\ 1320 \hm-ref 1321 | | | +---x install-hidden-key 1322 | | | | +---w input 1323 | | | | +---w algorithm 1324 | | | | | asymmetric-key-algorit\ 1325 \hm-ref 1326 | | | | +---w public-key? binary 1327 | | | | +---w private-key? binary 1328 | | | +--rw cert? 1329 | | | | end-entity-cert-cms 1330 | | | +---n certificate-expiration 1331 | | | +-- expiration-date 1332 | | | yang:date-and-time 1333 | | +--:(keystore) {keystore-supported}? 1334 | | +--rw keystore-reference? 1335 | | ks:asymmetric-key-certificate-r\ 1336 \ef 1337 | +--rw tls-client-auth 1338 | | +--rw pinned-ca-certs? 1339 | | | ta:pinned-certificates-ref 1340 | | | {ta:x509-certificates}? 1341 | | +--rw pinned-client-certs? 1342 | | | ta:pinned-certificates-ref 1343 | | | {ta:x509-certificates}? 1344 | | +--rw cert-maps 1345 | | +--rw cert-to-name* [id] 1346 | | +--rw id uint32 1347 | | +--rw fingerprint 1348 | | | x509c2n:tls-fingerprint 1349 | | +--rw map-type identityref 1350 | | +--rw name string 1351 | +--rw tls-hello-params 1352 | | {tls-server-hello-params-config}? 1353 | | +--rw tls-versions 1354 | | | +--rw tls-version* identityref 1355 | | +--rw cipher-suites 1356 | | +--rw cipher-suite* identityref 1357 | +--rw tls-keepalives {tls-server-keepalives}? 1358 | +--rw max-wait? uint16 1359 | +--rw max-attempts? uint8 1360 +--rw call-home! {call-home}? 1361 +--rw netconf-client* [name] 1362 +--rw name string 1363 +--rw endpoints 1364 | +--rw endpoint* [name] 1365 | +--rw name string 1366 | +--rw (transport) 1367 | +--:(ssh) {ssh-call-home}? 1368 | | +--rw ssh 1369 | | +--rw remote-address inet:host 1370 | | +--rw remote-port? 1371 | | | inet:port-number 1372 | | +--rw local-address? inet:ip-addr\ 1373 \ess 1374 | | +--rw local-port? 1375 | | | inet:port-number 1376 | | +--rw tcp-keepalives {tcp-client-keepalive\ 1377 \s}? 1378 | | | +--rw idle-time? uint16 1379 | | | +--rw max-probes? uint16 1380 | | | +--rw probe-interval? uint16 1381 | | +--rw ssh-server-identity 1382 | | | +--rw host-key* [name] 1383 | | | +--rw name string 1384 | | | +--rw (host-key-type) 1385 | | | +--:(public-key) 1386 | | | | +--rw public-key 1387 | | | | +--rw (local-or-keystore) 1388 | | | | +--:(local) 1389 | | | | | {local-keys-sup\ 1390 \ported}? 1391 | | | | | +--rw local-definition 1392 | | | | | +--rw algorithm? 1393 | | | | | | asymmetric\ 1394 \-key-algorithm-ref 1395 | | | | | +--rw public-key? 1396 | | | | | | binary 1397 | | | | | +--rw private-key? 1398 | | | | | | union 1399 | | | | | +---x generate-hid\ 1400 \den-key 1401 | | | | | | +---w input 1402 | | | | | | +---w algori\ 1403 \thm 1404 | | | | | | asym\ 1405 \metric-key-algorithm-ref 1406 | | | | | +---x install-hidd\ 1407 \en-key 1408 | | | | | +---w input 1409 | | | | | +---w algori\ 1410 \thm 1411 | | | | | | asym\ 1412 \metric-key-algorithm-ref 1413 | | | | | +---w public\ 1414 \-key? 1415 | | | | | | bina\ 1416 \ry 1417 | | | | | +---w privat\ 1418 \e-key? 1419 | | | | | bina\ 1420 \ry 1421 | | | | +--:(keystore) 1422 | | | | {keystore-suppo\ 1423 \rted}? 1424 | | | | +--rw keystore-refere\ 1425 \nce? 1426 | | | | ks:asymmetric\ 1427 \-key-ref 1428 | | | +--:(certificate) 1429 | | | +--rw certificate 1430 | | | {sshcmn:ssh-x509-certs\ 1431 \}? 1432 | | | +--rw (local-or-keystore) 1433 | | | +--:(local) 1434 | | | | {local-keys-sup\ 1436 \ported}? 1437 | | | | +--rw local-definition 1438 | | | | +--rw algorithm? 1439 | | | | | asymmetric\ 1440 \-key-algorithm-ref 1441 | | | | +--rw public-key? 1442 | | | | | binary 1443 | | | | +--rw private-key? 1444 | | | | | union 1445 | | | | +---x generate-hid\ 1446 \den-key 1447 | | | | | +---w input 1448 | | | | | +---w algori\ 1449 \thm 1450 | | | | | asym\ 1451 \metric-key-algorithm-ref 1452 | | | | +---x install-hidd\ 1453 \en-key 1454 | | | | | +---w input 1455 | | | | | +---w algori\ 1456 \thm 1457 | | | | | | asym\ 1458 \metric-key-algorithm-ref 1459 | | | | | +---w public\ 1460 \-key? 1461 | | | | | | bina\ 1462 \ry 1463 | | | | | +---w privat\ 1464 \e-key? 1465 | | | | | bina\ 1466 \ry 1467 | | | | +--rw cert? 1468 | | | | | end-entity\ 1469 \-cert-cms 1470 | | | | +---n certificate-\ 1471 \expiration 1472 | | | | +-- expiration-\ 1473 \date 1474 | | | | yang:da\ 1475 \te-and-time 1476 | | | +--:(keystore) 1477 | | | {keystore-suppo\ 1478 \rted}? 1479 | | | +--rw keystore-refere\ 1480 \nce? 1481 | | | ks:asymmetric\ 1482 \-key-certificate-ref 1483 | | +--rw ssh-client-cert-auth 1484 | | | {sshcmn:ssh-x509-certs}? 1485 | | | +--rw pinned-ca-certs? 1486 | | | | ta:pinned-certificates-ref 1487 | | | | {ta:x509-certificates}? 1488 | | | +--rw pinned-client-certs? 1489 | | | ta:pinned-certificates-ref 1490 | | | {ta:x509-certificates}? 1491 | | +--rw ssh-transport-params 1492 | | | {ssh-server-transport-params-confi\ 1493 \g}? 1494 | | | +--rw host-key 1495 | | | | +--rw host-key-alg* identityref 1496 | | | +--rw key-exchange 1497 | | | | +--rw key-exchange-alg* identityref 1498 | | | +--rw encryption 1499 | | | | +--rw encryption-alg* identityref 1500 | | | +--rw mac 1501 | | | +--rw mac-alg* identityref 1502 | | +--rw ssh-keepalives {ssh-server-keepalive\ 1503 \s}? 1504 | | +--rw max-wait? uint16 1505 | | +--rw max-attempts? uint8 1506 | +--:(tls) {tls-call-home}? 1507 | +--rw tls 1508 | +--rw remote-address inet:host 1509 | +--rw remote-port? inet:port-num\ 1510 \ber 1511 | +--rw local-address? inet:ip-addre\ 1512 \ss 1513 | +--rw local-port? inet:port-num\ 1514 \ber 1515 | +--rw tcp-keepalives {tcp-client-keepalive\ 1516 \s}? 1517 | | +--rw idle-time? uint16 1518 | | +--rw max-probes? uint16 1519 | | +--rw probe-interval? uint16 1520 | +--rw tls-server-identity 1521 | | +--rw (local-or-keystore) 1522 | | +--:(local) {local-keys-supported}? 1523 | | | +--rw local-definition 1524 | | | +--rw algorithm? 1525 | | | | asymmetric-key-algorit\ 1526 \hm-ref 1527 | | | +--rw public-key? 1528 | | | | binary 1529 | | | +--rw private-key? 1530 | | | | union 1531 | | | +---x generate-hidden-key 1532 | | | | +---w input 1533 | | | | +---w algorithm 1534 | | | | asymmetric-key-a\ 1535 \lgorithm-ref 1536 | | | +---x install-hidden-key 1537 | | | | +---w input 1538 | | | | +---w algorithm 1539 | | | | | asymmetric-key-a\ 1540 \lgorithm-ref 1541 | | | | +---w public-key? bin\ 1542 \ary 1543 | | | | +---w private-key? bin\ 1544 \ary 1545 | | | +--rw cert? 1546 | | | | end-entity-cert-cms 1547 | | | +---n certificate-expiration 1548 | | | +-- expiration-date 1549 | | | yang:date-and-time 1550 | | +--:(keystore) {keystore-supported}? 1551 | | +--rw keystore-reference? 1552 | | ks:asymmetric-key-certifi\ 1553 \cate-ref 1554 | +--rw tls-client-auth 1555 | | +--rw pinned-ca-certs? 1556 | | | ta:pinned-certificates-ref 1557 | | | {ta:x509-certificates}? 1558 | | +--rw pinned-client-certs? 1559 | | | ta:pinned-certificates-ref 1560 | | | {ta:x509-certificates}? 1561 | | +--rw cert-maps 1562 | | +--rw cert-to-name* [id] 1563 | | +--rw id uint32 1564 | | +--rw fingerprint 1565 | | | x509c2n:tls-fingerprint 1566 | | +--rw map-type identityref 1567 | | +--rw name string 1568 | +--rw tls-hello-params 1569 | | {tls-server-hello-params-config}? 1570 | | +--rw tls-versions 1571 | | | +--rw tls-version* identityref 1572 | | +--rw cipher-suites 1573 | | +--rw cipher-suite* identityref 1574 | +--rw tls-keepalives {tls-server-keepalive\ 1575 \s}? 1576 | +--rw max-wait? uint16 1577 | +--rw max-attempts? uint8 1578 +--rw connection-type 1579 | +--rw (connection-type) 1580 | +--:(persistent-connection) 1581 | | +--rw persistent! 1582 | +--:(periodic-connection) 1583 | +--rw periodic! 1584 | +--rw period? uint16 1585 | +--rw anchor-time? yang:date-and-time 1586 | +--rw idle-timeout? uint16 1587 +--rw reconnect-strategy 1588 +--rw start-with? enumeration 1589 +--rw max-attempts? uint8 1591 4.2. Example Usage 1593 The following example illustrates configuring a NETCONF server to 1594 listen for NETCONF client connections using both the SSH and TLS 1595 transport protocols, as well as configuring call-home to two NETCONF 1596 clients, one using SSH and the other using TLS. 1598 This example is consistent with the examples presented in Section 3.2 1599 of [I-D.ietf-netconf-keystore]. 1601 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) =========== 1603 1607 1608 1609 1610 netconf/ssh 1611 1612 192.0.2.7 1613 1614 1615 deployment-specific-certificate 1616 1617 1618 ct:rsa2048 1620 base64encodedvalue== 1621 base64encodedvalue== 1622 1623 1624 1625 1626 1627 explicitly-trusted-client-ca-certs 1630 explicitly-trusted-client-certs 1632 1633 1634 1635 1636 netconf/tls 1637 1638 192.0.2.7 1639 1640 1641 ct:rsa2048 1643 base64encodedvalue== 1644 base64encodedvalue== 1645 base64encodedvalue== 1646 1647 1648 1649 explicitly-trusted-client-ca-certs 1651 explicitly-trusted-client-certs 1653 1654 1655 1 1656 11:0A:05:11:00 1657 x509c2n:san-any 1658 1659 1660 2 1661 B3:4F:A1:8C:54 1662 x509c2n:specified 1663 scooby-doo 1664 1665 1666 1667 1668 1669 1671 1672 1673 1674 config-mgr 1675 1676 1677 east-data-center 1678 1679 east.config-mgr.example.com 1681 1682 1683 deployment-specific-certificate 1684 1685 1686 ct:rsa2048 1688 base64encodedvalue== 1689 base64encodedvalue== 1690 1691 1692 1693 1694 1695 explicitly-trusted-client-ca-certs 1697 explicitly-trusted-client-certs 1699 1700 1701 1702 1703 west-data-center 1704 1705 west.config-mgr.example.com 1707 1708 1709 deployment-specific-certificate 1710 1711 1712 ct:rsa2048 1714 base64encodedvalue== 1715 base64encodedvalue== 1716 1717 1718 1719 1720 1721 explicitly-trusted-client-ca-certs 1723 explicitly-trusted-client-certs 1725 1726 1727 1728 1729 1730 1731 300 1732 60 1733 1734 1735 1736 last-connected 1737 3 1738 1739 1740 1741 data-collector 1742 1743 1744 east-data-center 1745 1746 east.analytics.example.com 1748 1749 1750 ct:rsa2048 1752 base64encodedvalue== 1753 base64encodedvalue== 1754 base64encodedvalue== 1755 1756 1757 1758 explicitly-trusted-client-ca-certs 1760 explicitly-trusted-client-certs 1762 1763 1764 1 1765 11:0A:05:11:00 1766 x509c2n:san-any 1767 1768 1769 2 1770 B3:4F:A1:8C:54 1771 x509c2n:specified 1772 scooby-doo 1774 1775 1776 1777 1778 15 1779 3 1780 30 1781 1782 1783 30 1784 3 1785 1786 1787 1788 1789 west-data-center 1790 1791 west.analytics.example.com 1793 1794 1795 ct:rsa2048 1797 base64encodedvalue== 1798 base64encodedvalue== 1799 base64encodedvalue== 1800 1801 1802 1803 explicitly-trusted-client-ca-certs 1805 explicitly-trusted-client-certs 1807 1808 1809 1 1810 11:0A:05:11:00 1811 x509c2n:san-any 1812 1813 1814 2 1815 B3:4F:A1:8C:54 1816 x509c2n:specified 1817 scooby-doo 1818 1819 1820 1821 1822 15 1823 3 1824 30 1825 1826 1827 30 1828 3 1829 1830 1831 1832 1833 1834 1835 1836 1837 first-listed 1838 3 1839 1840 1841 1842 1844 4.3. YANG Module 1846 This YANG module has normative references to [RFC6242], [RFC6991], 1847 [RFC7407], [RFC7589], [RFC8071], 1848 [I-D.kwatsen-netconf-tcp-client-server], 1849 [I-D.ietf-netconf-ssh-client-server], and 1850 [I-D.ietf-netconf-tls-client-server]. 1852 This YANG module imports YANG types from [RFC6991], and YANG 1853 groupings from [RFC7407], [I-D.ietf-netconf-ssh-client-server] and 1854 [I-D.ietf-netconf-ssh-client-server]. 1856 file "ietf-netconf-server@2019-03-09.yang" 1857 module ietf-netconf-server { 1858 yang-version 1.1; 1859 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server"; 1860 prefix ncs; 1862 import ietf-yang-types { 1863 prefix yang; 1864 reference 1865 "RFC 6991: Common YANG Data Types"; 1866 } 1868 import ietf-x509-cert-to-name { 1869 prefix x509c2n; 1870 reference 1871 "RFC 7407: A YANG Data Model for SNMP Configuration"; 1872 } 1874 import ietf-tcp-client { 1875 prefix tcpc; 1876 reference 1877 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1878 } 1880 import ietf-tcp-server { 1881 prefix tcps; 1882 reference 1883 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 1884 } 1886 import ietf-ssh-server { 1887 prefix sshs; 1888 revision-date 2019-03-09; // stable grouping definitions 1889 reference 1890 "RFC YYYY: YANG Groupings for SSH Clients and SSH Servers"; 1891 } 1893 import ietf-tls-server { 1894 prefix tlss; 1895 revision-date 2019-03-09; // stable grouping definitions 1896 reference 1897 "RFC ZZZZ: YANG Groupings for TLS Clients and TLS Servers"; 1898 } 1900 organization 1901 "IETF NETCONF (Network Configuration) Working Group"; 1902 contact 1903 "WG Web: 1904 WG List: 1905 Author: Kent Watsen 1906 Author: Gary Wu 1907 Author: Juergen Schoenwaelder 1908 "; 1909 description 1910 "This module contains a collection of YANG definitions for 1911 configuring NETCONF servers. 1913 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 1914 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 1915 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 1916 are to be interpreted as described in BCP 14 [RFC2119] 1917 [RFC8174] when, and only when, they appear in all 1918 capitals, as shown here. 1920 Copyright (c) 2019 IETF Trust and the persons identified as 1921 authors of the code. All rights reserved. 1923 Redistribution and use in source and binary forms, with or 1924 without modification, is permitted pursuant to, and subject 1925 to the license terms contained in, the Simplified BSD 1926 License set forth in Section 4.c of the IETF Trust's 1927 Legal Provisions Relating to IETF Documents 1928 (http://trustee.ietf.org/license-info). 1930 This version of this YANG module is part of RFC XXXX; see 1931 the RFC itself for full legal notices."; 1933 revision 2019-03-09 { 1934 description 1935 "Initial version"; 1936 reference 1937 "RFC XXXX: NETCONF Client and Server Models"; 1938 } 1940 // Features 1942 feature listen { 1943 description 1944 "The 'listen' feature indicates that the NETCONF server 1945 supports opening a port to accept NETCONF client connections 1946 using at least one transport (e.g., SSH, TLS, etc.)."; 1947 } 1949 feature ssh-listen { 1950 description 1951 "The 'ssh-listen' feature indicates that the NETCONF server 1952 supports opening a port to accept NETCONF over SSH 1953 client connections."; 1954 reference 1955 "RFC 6242: 1956 Using the NETCONF Protocol over Secure Shell (SSH)"; 1957 } 1959 feature tls-listen { 1960 description 1961 "The 'tls-listen' feature indicates that the NETCONF server 1962 supports opening a port to accept NETCONF over TLS 1963 client connections."; 1964 reference 1965 "RFC 7589: Using the NETCONF Protocol over Transport 1966 Layer Security (TLS) with Mutual X.509 1967 Authentication"; 1968 } 1970 feature call-home { 1971 description 1972 "The 'call-home' feature indicates that the NETCONF server 1973 supports initiating NETCONF call home connections to 1974 NETCONF clients using at least one transport (e.g., SSH, 1975 TLS, etc.)."; 1976 reference 1977 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1978 } 1980 feature ssh-call-home { 1981 description 1982 "The 'ssh-call-home' feature indicates that the NETCONF 1983 server supports initiating a NETCONF over SSH call 1984 home connection to NETCONF clients."; 1985 reference 1986 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1987 } 1989 feature tls-call-home { 1990 description 1991 "The 'tls-call-home' feature indicates that the NETCONF 1992 server supports initiating a NETCONF over TLS call 1993 home connection to NETCONF clients."; 1994 reference 1995 "RFC 8071: NETCONF Call Home and RESTCONF Call Home"; 1996 } 1998 // Groupings 2000 grouping netconf-server-grouping { 2001 description 2002 "Top-level grouping for NETCONF server configuration."; 2003 container listen { 2004 if-feature "listen"; 2005 presence "Enables server to listen for TCP connections"; 2006 description 2007 "Configures listen behavior"; 2008 leaf idle-timeout { 2009 type uint16; 2010 units "seconds"; 2011 default 3600; // one hour 2012 description 2013 "Specifies the maximum number of seconds that a NETCONF 2014 session may remain idle. A NETCONF session will be 2015 dropped if it is idle for an interval longer than this 2016 number of seconds. If set to zero, then the server 2017 will never drop a session because it is idle. Sessions 2018 that have a notification subscription active are never 2019 dropped."; 2020 } 2021 list endpoint { 2022 key "name"; 2023 min-elements 1; 2024 description 2025 "List of endpoints to listen for NETCONF connections."; 2026 leaf name { 2027 type string; 2028 description 2029 "An arbitrary name for the NETCONF listen endpoint."; 2030 } 2031 choice transport { 2032 mandatory true; 2033 description 2034 "Selects between available transports."; 2035 case ssh { 2036 if-feature "ssh-listen"; 2037 container ssh { 2038 description 2039 "SSH-specific listening configuration for inbound 2040 connections."; 2041 uses tcps:tcp-server-grouping { 2042 refine "local-port" { 2043 default "830"; 2044 description 2045 "The NETCONF server will listen on the IANA- 2046 assigned well-known port value for 'netconf-ssh' 2047 (830) if no value is specified."; 2048 } 2049 } 2050 uses sshs:ssh-server-grouping; 2051 } 2052 } 2053 case tls { 2054 if-feature "tls-listen"; 2055 container tls { 2056 description 2057 "TLS-specific listening configuration for inbound 2058 connections."; 2059 uses tcps:tcp-server-grouping { 2060 refine "local-port" { 2061 default "6513"; 2062 description 2063 "The NETCONF server will listen on the IANA- 2064 assigned well-known port value for 'netconf-tls' 2065 (6513) if no value is specified."; 2066 } 2067 } 2068 uses tlss:tls-server-grouping { 2069 refine "tls-client-auth" { 2070 must 'pinned-ca-certs or pinned-client-certs'; 2071 description 2072 "NETCONF/TLS servers MUST validate client 2073 certiticates."; 2074 } 2075 augment "tls-client-auth" { 2076 description 2077 "Augments in the cert-to-name structure."; 2078 container cert-maps { 2079 uses x509c2n:cert-to-name; 2080 description 2081 "The cert-maps container is used by a TLS- 2082 based NETCONF server to map the NETCONF 2083 client's presented X.509 certificate to a 2084 NETCONF username. If no matching and valid 2085 cert-to-name list entry can be found, then 2086 the NETCONF server MUST close the connection, 2087 and MUST NOT accept NETCONF messages over 2088 it."; 2089 reference 2090 "RFC WWWW: NETCONF over TLS, Section 7"; 2091 } 2092 } 2093 } 2094 } 2095 } 2096 } 2097 } 2098 } 2099 container call-home { 2100 if-feature "call-home"; 2101 presence "Enables server to initiate TCP connections"; 2102 description "Configures call-home behavior"; 2103 list netconf-client { 2104 key "name"; 2105 min-elements 1; 2106 description 2107 "List of NETCONF clients the NETCONF server is to 2108 initiate call-home connections to in parallel."; 2109 leaf name { 2110 type string; 2111 description 2112 "An arbitrary name for the remote NETCONF client."; 2113 } 2114 container endpoints { 2115 description 2116 "Container for the list of endpoints."; 2117 list endpoint { 2118 key "name"; 2119 min-elements 1; 2120 ordered-by user; 2121 description 2122 "A non-empty user-ordered list of endpoints for this 2123 NETCONF server to try to connect to in sequence. 2124 Defining more than one enables high-availability."; 2125 leaf name { 2126 type string; 2127 description 2128 "An arbitrary name for this endpoint."; 2129 } 2130 choice transport { 2131 mandatory true; 2132 description 2133 "Selects between available transports."; 2134 case ssh { 2135 if-feature "ssh-call-home"; 2136 container ssh { 2137 description 2138 "Specifies SSH-specific call-home transport 2139 configuration."; 2140 uses tcpc:tcp-client-grouping { 2141 refine "remote-port" { 2142 default "4334"; 2143 description 2144 "The NETCONF server will attempt to connect 2145 to the IANA-assigned well-known port for 2146 'netconf-ch-tls' (4334) if no value is 2147 specified."; 2148 } 2149 } 2150 uses sshs:ssh-server-grouping; 2151 } 2152 } 2153 case tls { 2154 if-feature "tls-call-home"; 2155 container tls { 2156 description 2157 "Specifies TLS-specific call-home transport 2158 configuration."; 2159 uses tcpc:tcp-client-grouping { 2160 refine "remote-port" { 2161 default "4335"; 2162 description 2163 "The NETCONF server will attempt to connect 2164 to the IANA-assigned well-known port for 2165 'netconf-ch-tls' (4335) if no value is 2166 specified."; 2167 } 2168 } 2169 uses tlss:tls-server-grouping { 2170 refine "tls-client-auth" { 2171 must 'pinned-ca-certs or pinned-client-certs'; 2172 description 2173 "NETCONF/TLS servers MUST validate client 2174 certiticates."; 2175 } 2176 augment "tls-client-auth" { 2177 description 2178 "Augments in the cert-to-name structure."; 2179 container cert-maps { 2180 uses x509c2n:cert-to-name; 2181 description 2182 "The cert-maps container is used by a 2183 TLS-based NETCONF server to map the 2184 NETCONF client's presented X.509 2185 certificate to a NETCONF username. If 2186 no matching and valid cert-to-name list 2187 entry can be found, then the NETCONF 2188 server MUST close the connection, and 2189 MUST NOT accept NETCONF messages over 2190 it."; 2191 reference 2192 "RFC WWWW: NETCONF over TLS, Section 7"; 2193 } 2194 } 2195 } 2196 } 2197 } // tls 2198 } // choice 2199 } // endpoint 2200 } // endpoints 2201 container connection-type { 2202 description 2203 "Indicates the NETCONF server's preference for how the 2204 NETCONF connection is maintained."; 2205 choice connection-type { 2206 mandatory true; 2207 description 2208 "Selects between available connection types."; 2209 case persistent-connection { 2210 container persistent { 2211 presence "Indicates that a persistent connection is 2212 to be maintained."; 2213 description 2214 "Maintain a persistent connection to the NETCONF 2215 client. If the connection goes down, immediately 2216 start trying to reconnect to it, using the 2217 reconnection strategy. 2219 This connection type minimizes any NETCONF client 2220 to NETCONF server data-transfer delay, albeit at 2221 the expense of holding resources longer."; 2222 } // container persistent 2223 } // case persistent-connection 2224 case periodic-connection { 2225 container periodic { 2226 presence "Indicates that a periodic connection is 2227 to be maintained."; 2228 description 2229 "Periodically connect to the NETCONF client. The 2230 NETCONF client should close the underlying TLS 2231 connection upon completing planned activities. 2233 This connection type increases resource 2234 utilization, albeit with increased delay in 2235 NETCONF client to NETCONF client interactions."; 2236 leaf period { 2237 type uint16; 2238 units "minutes"; 2239 default "60"; 2240 description 2241 "Duration of time between periodic connections."; 2242 } 2243 leaf anchor-time { 2244 type yang:date-and-time { 2245 // constrained to minute-level granularity 2246 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}' 2247 + '(Z|[\+\-]\d{2}:\d{2})'; 2248 } 2249 description 2250 "Designates a timestamp before or after which a 2251 series of periodic connections are determined. 2252 The periodic connections occur at a whole 2253 multiple interval from the anchor time. For 2254 example, for an anchor time is 15 minutes past 2255 midnight and a period interval of 24 hours, then 2256 a periodic connection will occur 15 minutes past 2257 midnight everyday."; 2258 } 2259 leaf idle-timeout { 2260 type uint16; 2261 units "seconds"; 2262 default 120; // two minutes 2263 description 2264 "Specifies the maximum number of seconds that 2265 a NETCONF session may remain idle. A NETCONF 2266 session will be dropped if it is idle for an 2267 interval longer than this number of seconds. 2268 If set to zero, then the server will never 2269 drop a session because it is idle."; 2270 } 2271 } // container periodic 2272 } // case periodic-connection 2273 } // choice connection-type 2274 } // container connection-type 2275 container reconnect-strategy { 2276 description 2277 "The reconnection strategy directs how a NETCONF server 2278 reconnects to a NETCONF client, after discovering its 2279 connection to the client has dropped, even if due to a 2280 reboot. The NETCONF server starts with the specified 2281 endpoint and tries to connect to it max-attempts times 2282 before trying the next endpoint in the list (round 2283 robin)."; 2284 leaf start-with { 2285 type enumeration { 2286 enum first-listed { 2287 description 2288 "Indicates that reconnections should start with 2289 the first endpoint listed."; 2290 } 2291 enum last-connected { 2292 description 2293 "Indicates that reconnections should start with 2294 the endpoint last connected to. If no previous 2295 connection has ever been established, then the 2296 first endpoint configured is used. NETCONF 2297 servers SHOULD be able to remember the last 2298 endpoint connected to across reboots."; 2299 } 2300 enum random-selection { 2301 description 2302 "Indicates that reconnections should start with 2303 a random endpoint."; 2304 } 2305 } 2306 default "first-listed"; 2307 description 2308 "Specifies which of the NETCONF client's endpoints 2309 the NETCONF server should start with when trying 2310 to connect to the NETCONF client."; 2311 } 2312 leaf max-attempts { 2313 type uint8 { 2314 range "1..max"; 2315 } 2316 default "3"; 2317 description 2318 "Specifies the number times the NETCONF server tries 2319 to connect to a specific endpoint before moving on 2320 to the next endpoint in the list (round robin)."; 2321 } 2322 } // container reconnect-strategy 2323 } // list netconf-client 2324 } // container call-home 2325 } // grouping netconf-server-grouping 2327 // Protocol accessible node, for servers that implement this 2328 // module. 2330 container netconf-server { 2331 uses netconf-server-grouping; 2332 description 2333 "Top-level container for NETCONF server configuration."; 2334 } 2335 } 2336 2338 5. Design Considerations 2340 Editorial: this section is a hold over from before, previously called 2341 "Objectives". It was only written two support the "server" (not the 2342 "client"). The question is if it's better to add the missing 2343 "client" parts, or remove this section altogether. 2345 The primary purpose of the YANG modules defined herein is to enable 2346 the configuration of the NETCONF client and servers. This scope 2347 includes the following objectives: 2349 5.1. Support all NETCONF transports 2351 The YANG module should support all current NETCONF transports, namely 2352 NETCONF over SSH [RFC6242], NETCONF over TLS [RFC7589], and to be 2353 extensible to support future transports as necessary. 2355 Because implementations may not support all transports, the modules 2356 should use YANG "feature" statements so that implementations can 2357 accurately advertise which transports are supported. 2359 5.2. Enable each transport to select which keys to use 2361 Servers may have a multiplicity of host-keys or server-certificates 2362 from which subsets may be selected for specific uses. For instance, 2363 a NETCONF server may want to use one set of SSH host-keys when 2364 listening on port 830, and a different set of SSH host-keys when 2365 calling home. The data models provided herein should enable 2366 configuration of which keys to use on a per-use basis. 2368 5.3. Support authenticating NETCONF clients certificates 2370 When a certificate is used to authenticate a NETCONF client, there is 2371 a need to configure the server to know how to authenticate the 2372 certificates. The server should be able to authenticate the client's 2373 certificate either by using path-validation to a configured trust 2374 anchor or by matching the client-certificate to one previously 2375 configured. 2377 5.4. Support mapping authenticated NETCONF client certificates to 2378 usernames 2380 When a client certificate is used for TLS client authentication, the 2381 NETCONF server must be able to derive a username from the 2382 authenticated certificate. Thus the modules defined herein should 2383 enable this mapping to be configured. 2385 5.5. Support both listening for connections and call home 2387 The NETCONF protocols were originally defined as having the server 2388 opening a port to listen for client connections. More recently the 2389 NETCONF working group defined support for call-home ([RFC8071]), 2390 enabling the server to initiate the connection to the client. Thus 2391 the modules defined herein should enable configuration for both 2392 listening for connections and calling home. Because implementations 2393 may not support both listening for connections and calling home, YANG 2394 "feature" statements should be used so that implementation can 2395 accurately advertise the connection types it supports. 2397 5.6. For Call Home connections 2399 The following objectives only pertain to call home connections. 2401 5.6.1. Support more than one NETCONF client 2403 A NETCONF server may be managed by more than one NETCONF client. For 2404 instance, a deployment may have one client for provisioning and 2405 another for fault monitoring. Therefore, when it is desired for a 2406 server to initiate call home connections, it should be able to do so 2407 to more than one client. 2409 5.6.2. Support NETCONF clients having more than one endpoint 2411 A NETCONF client managing a NETCONF server may implement a high- 2412 availability strategy employing a multiplicity of active and/or 2413 passive endpoint. Therefore, when it is desired for a server to 2414 initiate call home connections, it should be able to connect to any 2415 of the client's endpoints. 2417 5.6.3. Support a reconnection strategy 2419 Assuming a NETCONF client has more than one endpoint, then it becomes 2420 necessary to configure how a NETCONF server should reconnect to the 2421 client should it lose its connection to one the client's endpoints. 2422 For instance, the NETCONF server may start with first endpoint 2423 defined in a user-ordered list of endpoints or with the last 2424 endpoints it was connected to. 2426 5.6.4. Support both persistent and periodic connections 2428 NETCONF clients may vary greatly on how frequently they need to 2429 interact with a NETCONF server, how responsive interactions need to 2430 be, and how many simultaneous connections they can support. Some 2431 clients may need a persistent connection to servers to optimize real- 2432 time interactions, while others prefer periodic interactions in order 2433 to minimize resource requirements. Therefore, when it is necessary 2434 for server to initiate connections, it should be configurable if the 2435 connection is persistent or periodic. 2437 5.6.5. Reconnection strategy for periodic connections 2439 The reconnection strategy should apply to both persistent and 2440 periodic connections. How it applies to periodic connections becomes 2441 clear when considering that a periodic "connection" is a logical 2442 connection to a single server. That is, the periods of 2443 unconnectedness are intentional as opposed to due to external 2444 reasons. A periodic "connection" should always reconnect to the same 2445 server until it is no longer able to, at which time the reconnection 2446 strategy guides how to connect to another server. 2448 5.6.6. Keep-alives for persistent connections 2450 If a persistent connection is desired, it is the responsibility of 2451 the connection initiator to actively test the "aliveness" of the 2452 connection. The connection initiator must immediately work to 2453 reestablish a persistent connection as soon as the connection is 2454 lost. How often the connection should be tested is driven by NETCONF 2455 client requirements, and therefore keep-alive settings should be 2456 configurable on a per-client basis. 2458 5.6.7. Customizations for periodic connections 2460 If a periodic connection is desired, it is necessary for the NETCONF 2461 server to know how often it should connect. This frequency 2462 determines the maximum amount of time a NETCONF client may have to 2463 wait to send data to a server. A server may connect to a client 2464 before this interval expires if desired (e.g., to send data to a 2465 client). 2467 6. Security Considerations 2469 The YANG module defined in this document uses groupings defined in 2470 [I-D.ietf-netconf-ssh-client-server] and 2471 [I-D.ietf-netconf-tls-client-server]. Please see the Security 2472 Considerations section in those documents for concerns related those 2473 groupings. 2475 The YANG module defined in this document is designed to be accessed 2476 via YANG based management protocols, such as NETCONF [RFC6241] and 2477 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 2478 implement secure transport layers (e.g., SSH, TLS) with mutual 2479 authentication. 2481 The NETCONF access control model (NACM) [RFC8341] provides the means 2482 to restrict access for particular users to a pre-configured subset of 2483 all available protocol operations and content. 2485 There are a number of data nodes defined in this YANG module that are 2486 writable/creatable/deletable (i.e., config true, which is the 2487 default). These data nodes may be considered sensitive or vulnerable 2488 in some network environments. Write operations (e.g., edit-config) 2489 to these data nodes without proper protection can have a negative 2490 effect on network operations. These are the subtrees and data nodes 2491 and their sensitivity/vulnerability: 2493 /: The entire data trees defined by the modules defined in this 2494 draft are sensitive to write operations. For instance, the 2495 addition or removal of references to keys, certificates, 2496 trusted anchors, etc., can dramatically alter the implemented 2497 security policy. However, no NACM annotations are applied as 2498 the data SHOULD be editable by users other than a designated 2499 'recovery session'. 2501 Some of the readable data nodes in this YANG module may be considered 2502 sensitive or vulnerable in some network environments. It is thus 2503 important to control read access (e.g., via get, get-config, or 2504 notification) to these data nodes. These are the subtrees and data 2505 nodes and their sensitivity/vulnerability: 2507 NONE 2509 Some of the RPC operations in this YANG module may be considered 2510 sensitive or vulnerable in some network environments. It is thus 2511 important to control access to these operations. These are the 2512 operations and their sensitivity/vulnerability: 2514 NONE 2516 7. IANA Considerations 2518 7.1. The IETF XML Registry 2520 This document registers two URIs in the "ns" subregistry of the IETF 2521 XML Registry [RFC3688]. Following the format in [RFC3688], the 2522 following registrations are requested: 2524 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-client 2525 Registrant Contact: The NETCONF WG of the IETF. 2526 XML: N/A, the requested URI is an XML namespace. 2528 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server 2529 Registrant Contact: The NETCONF WG of the IETF. 2530 XML: N/A, the requested URI is an XML namespace. 2532 7.2. The YANG Module Names Registry 2534 This document registers two YANG modules in the YANG Module Names 2535 registry [RFC6020]. Following the format in [RFC6020], the the 2536 following registrations are requested: 2538 name: ietf-netconf-client 2539 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-client 2540 prefix: ncc 2541 reference: RFC XXXX 2543 name: ietf-netconf-server 2544 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server 2545 prefix: ncs 2546 reference: RFC XXXX 2548 8. References 2550 8.1. Normative References 2552 [I-D.ietf-netconf-keystore] 2553 Watsen, K., "YANG Data Model for a Centralized Keystore 2554 Mechanism", draft-ietf-netconf-keystore-08 (work in 2555 progress), March 2019. 2557 [I-D.ietf-netconf-ssh-client-server] 2558 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for SSH 2559 Clients and SSH Servers", draft-ietf-netconf-ssh-client- 2560 server-08 (work in progress), October 2018. 2562 [I-D.ietf-netconf-tls-client-server] 2563 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for TLS 2564 Clients and TLS Servers", draft-ietf-netconf-tls-client- 2565 server-08 (work in progress), October 2018. 2567 [I-D.kwatsen-netconf-tcp-client-server] 2568 Watsen, K., "YANG Groupings for TCP Clients and TCP 2569 Servers", draft-kwatsen-netconf-tcp-client-server-00 (work 2570 in progress), March 2019. 2572 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2573 Requirement Levels", BCP 14, RFC 2119, 2574 DOI 10.17487/RFC2119, March 1997, 2575 . 2577 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 2578 the Network Configuration Protocol (NETCONF)", RFC 6020, 2579 DOI 10.17487/RFC6020, October 2010, 2580 . 2582 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 2583 and A. Bierman, Ed., "Network Configuration Protocol 2584 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 2585 . 2587 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 2588 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 2589 . 2591 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2592 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2593 . 2595 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 2596 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 2597 December 2014, . 2599 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2600 NETCONF Protocol over Transport Layer Security (TLS) with 2601 Mutual X.509 Authentication", RFC 7589, 2602 DOI 10.17487/RFC7589, June 2015, 2603 . 2605 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2606 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2607 . 2609 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2610 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2611 May 2017, . 2613 8.2. Informative References 2615 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2616 DOI 10.17487/RFC3688, January 2004, 2617 . 2619 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2620 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2621 . 2623 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 2624 RFC 8071, DOI 10.17487/RFC8071, February 2017, 2625 . 2627 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2628 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2629 . 2631 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 2632 Access Control Model", STD 91, RFC 8341, 2633 DOI 10.17487/RFC8341, March 2018, 2634 . 2636 Appendix A. Change Log 2638 A.1. 00 to 01 2640 o Renamed "keychain" to "keystore". 2642 A.2. 01 to 02 2644 o Added to ietf-netconf-client ability to connected to a cluster of 2645 endpoints, including a reconnection-strategy. 2647 o Added to ietf-netconf-client the ability to configure connection- 2648 type and also keep-alive strategy. 2650 o Updated both modules to accommodate new groupings in the ssh/tls 2651 drafts. 2653 A.3. 02 to 03 2655 o Refined use of tls-client-grouping to add a must statement 2656 indicating that the TLS client must specify a client-certificate. 2658 o Changed 'netconf-client' to be a grouping (not a container). 2660 A.4. 03 to 04 2662 o Added RFC 8174 to Requirements Language Section. 2664 o Replaced refine statement in ietf-netconf-client to add a 2665 mandatory true. 2667 o Added refine statement in ietf-netconf-server to add a must 2668 statement. 2670 o Now there are containers and groupings, for both the client and 2671 server models. 2673 A.5. 04 to 05 2675 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams 2677 o Updated examples to inline key and certificates (no longer a 2678 leafref to keystore) 2680 A.6. 05 to 06 2682 o Fixed change log missing section issue. 2684 o Updated examples to match latest updates to the crypto-types, 2685 trust-anchors, and keystore drafts. 2687 o Reduced line length of the YANG modules to fit within 69 columns. 2689 A.7. 06 to 07 2691 o Removed "idle-timeout" from "persistent" connection config. 2693 o Added "random-selection" for reconnection-strategy's "starts-with" 2694 enum. 2696 o Replaced "connection-type" choice default (persistent) with 2697 "mandatory true". 2699 o Reduced the periodic-connection's "idle-timeout" from 5 to 2 2700 minutes. 2702 o Replaced reconnect-timeout with period/anchor-time combo. 2704 A.8. 07 to 08 2706 o Modified examples to be compatible with new crypto-types algs 2708 Appendix B. 08 to 09 2710 o Corrected use of "mandatory true" for "address" leafs. 2712 o Updated examples to reflect update to groupings defined in the 2713 keystore draft. 2715 o Updated to use groupings defined in new TCP and HTTP drafts. 2717 o Updated copyright date, boilerplate template, affiliation, and 2718 folding algorithm. 2720 Acknowledgements 2722 The authors would like to thank for following for lively discussions 2723 on list and in the halls (ordered by last name): Andy Bierman, Martin 2724 Bjorklund, Benoit Claise, Ramkumar Dhanapal, Mehmet Ersue, Balazs 2725 Kovacs, David Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci, 2726 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert 2727 Wijnen. 2729 Author's Address 2731 Kent Watsen 2732 Watsen Networks 2734 EMail: kent+ietf@watsen.net