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
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\
1698 \pinned-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\
1724 \pinned-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\
1761 \pinned-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\
1806 \pinned-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