idnits 2.17.1
draft-ietf-netconf-netconf-client-server-09.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (March 9, 2019) is 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-09
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 . . . . . . . . . . . . . . . . . . . . 50
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 . . . . . . . . . . . . . . . . . . . . . . 51
108 5.5. Support both listening for connections and call home . . 51
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 . . 52
114 5.6.5. Reconnection strategy for periodic connections . . . 52
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 . . . . . . . . . . . . . 54
121 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 54
122 8.1. Normative References . . . . . . . . . . . . . . . . . . 54
123 8.2. Informative References . . . . . . . . . . . . . . . . . 55
124 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 57
125 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 57
126 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 57
127 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 57
128 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 57
129 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 57
130 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 58
131 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 58
132 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 58
133 Appendix B. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . 58
134 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 58
135 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 59
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 }
739 import ietf-tcp-server {
740 prefix tcps;
741 reference
742 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
743 }
745 import ietf-ssh-client {
746 prefix sshc;
747 revision-date 2019-03-09; // stable grouping definitions
748 reference
749 "RFC YYYY: YANG Groupings for SSH Clients and SSH Servers";
750 }
752 import ietf-tls-client {
753 prefix tlsc;
754 revision-date 2019-03-09; // stable grouping definitions
755 reference
756 "RFC ZZZZ: YANG Groupings for TLS Clients and TLS Servers";
757 }
759 organization
760 "IETF NETCONF (Network Configuration) Working Group";
762 contact
763 "WG Web:
764 WG List:
765 Author: Kent Watsen
766 Author: Gary Wu ";
768 description
769 "This module contains a collection of YANG definitions for
770 configuring NETCONF clients.
772 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
773 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
774 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
775 are to be interpreted as described in BCP 14 [RFC2119]
776 [RFC8174] when, and only when, they appear in all
777 capitals, as shown here.
779 Copyright (c) 2019 IETF Trust and the persons identified as
780 authors of the code. All rights reserved.
782 Redistribution and use in source and binary forms, with or
783 without modification, is permitted pursuant to, and subject
784 to the license terms contained in, the Simplified BSD
785 License set forth in Section 4.c of the IETF Trust's
786 Legal Provisions Relating to IETF Documents
787 (http://trustee.ietf.org/license-info).
789 This version of this YANG module is part of RFC XXXX; see
790 the RFC itself for full legal notices.";
792 revision "2019-03-09" {
793 description
794 "Initial version";
795 reference
796 "RFC XXXX: NETCONF Client and Server Models";
797 }
799 // Features
801 feature initiate {
802 description
803 "The 'initiate' feature indicates that the NETCONF client
804 supports initiating NETCONF connections to NETCONF servers
805 using at least one transport (e.g., SSH, TLS, etc.).";
806 }
808 feature ssh-initiate {
809 description
810 "The 'ssh-initiate' feature indicates that the NETCONF client
811 supports initiating SSH connections to NETCONF servers.";
812 reference
813 "RFC 6242:
814 Using the NETCONF Protocol over Secure Shell (SSH)";
815 }
817 feature tls-initiate {
818 description
819 "The 'tls-initiate' feature indicates that the NETCONF client
820 supports initiating TLS connections to NETCONF servers.";
821 reference
822 "RFC 7589: Using the NETCONF Protocol over Transport
823 Layer Security (TLS) with Mutual X.509
824 Authentication";
825 }
827 feature listen {
828 description
829 "The 'listen' feature indicates that the NETCONF client
830 supports opening a port to accept NETCONF server call
831 home connections using at least one transport (e.g.,
832 SSH, TLS, etc.).";
833 }
835 feature ssh-listen {
836 description
837 "The 'ssh-listen' feature indicates that the NETCONF client
838 supports opening a port to listen for incoming NETCONF
839 server call-home SSH connections.";
840 reference
841 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
842 }
844 feature tls-listen {
845 description
846 "The 'tls-listen' feature indicates that the NETCONF client
847 supports opening a port to listen for incoming NETCONF
848 server call-home TLS connections.";
849 reference
850 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
851 }
853 // Groupings
855 grouping netconf-client-grouping {
856 description
857 "Top-level grouping for NETCONF client configuration.";
859 container initiate {
860 if-feature initiate;
861 presence "Enables client to initiate TCP connections";
862 description
863 "Configures client initiating underlying TCP connections.";
864 list netconf-server {
865 key name;
866 min-elements 1;
867 description
868 "List of NETCONF servers the NETCONF client is to
869 initiate connections to in parallel.";
870 leaf name {
871 type string;
872 description
873 "An arbitrary name for the NETCONF server.";
874 }
875 container endpoints {
876 description
877 "Container for the list of endpoints.";
878 list endpoint {
879 key name;
880 min-elements 1;
881 ordered-by user;
882 description
883 "A user-ordered list of endpoints that the NETCONF
884 client will attempt to connect to in the specified
885 sequence. Defining more than one enables
886 high-availability.";
887 leaf name {
888 type string;
889 description
890 "An arbitrary name for the endpoint.";
891 }
892 choice transport {
893 mandatory true;
894 description
895 "Selects between available transports.";
896 case ssh {
897 if-feature ssh-initiate;
898 container ssh {
899 description
900 "Specifies IP and SSH specific configuration
901 for the connection.";
902 uses tcpc:tcp-client-grouping {
903 refine "remote-port" {
904 default 830;
905 description
906 "The NETCONF client will attempt to connect
907 to the IANA-assigned well-known port value
908 for 'netconf-ssh' (443) if no value is
909 specified.";
910 }
911 }
912 uses sshc:ssh-client-grouping;
913 } // container ssh
914 } // case ssh
916 case tls {
917 if-feature tls-initiate;
918 container tls {
919 description
920 "Specifies IP and TLS specific configuration
921 for the connection.";
922 uses tcpc:tcp-client-grouping {
923 refine "remote-port" {
924 default 6513;
925 description
926 "The NETCONF client will attempt to connect
927 to the IANA-assigned well-known port value
928 for 'netconf-tls' (6513) if no value is
929 specified.";
930 }
931 }
933 uses tlsc:tls-client-grouping {
934 refine "tls-client-identity/auth-type" {
935 mandatory true;
936 description
937 "NETCONF/TLS clients MUST pass some
938 authentication credentials.";
939 }
940 }
942 } // container tls
943 } // case tls
945 } // choice transport
946 } // list endpoint
947 } // container endpoints
949 container connection-type {
950 description
951 "Indicates the NETCONF client's preference for how the
952 NETCONF connection is maintained.";
953 choice connection-type {
954 mandatory true;
955 description
956 "Selects between available connection types.";
957 case persistent-connection {
958 container persistent {
959 presence
960 "Indicates that a persistent connection is to be
961 maintained.";
962 description
963 "Maintain a persistent connection to the NETCONF
964 server. If the connection goes down, immediately
965 start trying to reconnect to it, using the
966 reconnection strategy.
968 This connection type minimizes any NETCONF server
969 to NETCONF client data-transfer delay, albeit at
970 the expense of holding resources longer.";
971 }
972 }
973 case periodic-connection {
974 container periodic {
975 presence
976 "Indicates that a periodic connection is to be
977 maintained.";
978 description
979 "Periodically connect to the NETCONF server. The
980 NETCONF server should close the connection upon
981 completing planned activities.
983 This connection type increases resource
984 utilization, albeit with increased delay in
985 NETCONF server to NETCONF client interactions.";
986 leaf period {
987 type uint16;
988 units "minutes";
989 default 60;
990 description
991 "Duration of time between periodic connections.";
992 }
993 leaf anchor-time {
994 type yang:date-and-time {
995 // constrained to minute-level granularity
996 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}'
997 + '(Z|[\+\-]\d{2}:\d{2})';
998 }
999 description
1000 "Designates a timestamp before or after which a
1001 series of periodic connections are determined.
1002 The periodic connections occur at a whole
1003 multiple interval from the anchor time. For
1004 example, for an anchor time is 15 minutes past
1005 midnight and a period interval of 24 hours, then
1006 a periodic connection will occur 15 minutes past
1007 midnight everyday.";
1008 }
1009 leaf idle-timeout {
1010 type uint16;
1011 units "seconds";
1012 default 120; // two minutes
1013 description
1014 "Specifies the maximum number of seconds that
1015 a NETCONF session may remain idle. A NETCONF
1016 session will be dropped if it is idle for an
1017 interval longer than this number of seconds.
1018 If set to zero, then the NETCONF client will
1019 never drop a session because it is idle.";
1020 }
1021 }
1022 }
1023 }
1024 }
1025 container reconnect-strategy {
1026 description
1027 "The reconnection strategy directs how a NETCONF client
1028 reconnects to a NETCONF server, after discovering its
1029 connection to the server has dropped, even if due to a
1030 reboot. The NETCONF client starts with the specified
1031 endpoint and tries to connect to it max-attempts times
1032 before trying the next endpoint in the list (round
1033 robin).";
1034 leaf start-with {
1035 type enumeration {
1036 enum first-listed {
1037 description
1038 "Indicates that reconnections should start with
1039 the first endpoint listed.";
1040 }
1041 enum last-connected {
1042 description
1043 "Indicates that reconnections should start with
1044 the endpoint last connected to. If no previous
1045 connection has ever been established, then the
1046 first endpoint configured is used. NETCONF
1047 clients SHOULD be able to remember the last
1048 endpoint connected to across reboots.";
1049 }
1050 enum random-selection {
1051 description
1052 "Indicates that reconnections should start with
1053 a random endpoint.";
1054 }
1055 }
1056 default first-listed;
1057 description
1058 "Specifies which of the NETCONF server's endpoints
1059 the NETCONF client should start with when trying
1060 to connect to the NETCONF server.";
1061 }
1062 leaf max-attempts {
1063 type uint8 {
1064 range "1..max";
1065 }
1066 default 3;
1067 description
1068 "Specifies the number times the NETCONF client tries
1069 to connect to a specific endpoint before moving on
1070 to the next endpoint in the list (round robin).";
1071 }
1072 }
1073 } // netconf-server
1074 } // initiate
1076 container listen {
1077 if-feature listen;
1078 presence "Enables client to accept call-home connections";
1079 description
1080 "Configures client accepting call-home TCP connections.";
1082 leaf idle-timeout {
1083 type uint16;
1084 units "seconds";
1085 default 3600; // one hour
1086 description
1087 "Specifies the maximum number of seconds that a NETCONF
1088 session may remain idle. A NETCONF session will be
1089 dropped if it is idle for an interval longer than this
1090 number of seconds. If set to zero, then the server
1091 will never drop a session because it is idle. Sessions
1092 that have a notification subscription active are never
1093 dropped.";
1094 }
1096 list endpoint {
1097 key name;
1098 min-elements 1;
1099 description
1100 "List of endpoints to listen for NETCONF connections.";
1101 leaf name {
1102 type string;
1103 description
1104 "An arbitrary name for the NETCONF listen endpoint.";
1105 }
1106 choice transport {
1107 mandatory true;
1108 description
1109 "Selects between available transports.";
1110 case ssh {
1111 if-feature ssh-listen;
1112 container ssh {
1113 description
1114 "SSH-specific listening configuration for inbound
1115 connections.";
1116 uses tcps:tcp-server-grouping {
1117 refine "local-port" {
1118 default 4334;
1119 description
1120 "The NETCONF client will listen on the IANA-
1121 assigned well-known port for 'netconf-ch-ssh'
1122 (4334) if no value is specified.";
1123 }
1124 }
1125 uses sshc:ssh-client-grouping;
1126 }
1127 }
1128 case tls {
1129 if-feature tls-listen;
1130 container tls {
1131 description
1132 "TLS-specific listening configuration for inbound
1133 connections.";
1134 uses tcps:tcp-server-grouping {
1135 refine "local-port" {
1136 default 4334;
1137 description
1138 "The NETCONF client will listen on the IANA-
1139 assigned well-known port for 'netconf-ch-ssh'
1140 (4334) if no value is specified.";
1141 }
1142 }
1143 uses tlsc:tls-client-grouping {
1144 refine "tls-client-identity/auth-type" {
1145 mandatory true;
1146 description
1147 "NETCONF/TLS clients MUST pass some
1148 authentication credentials.";
1149 }
1150 }
1151 }
1152 }
1153 } // transport
1154 } // endpoint
1155 } // listen
1156 } // netconf-client
1158 // Protocol accessible node, for servers that 'implement'
1159 // this module.
1161 container netconf-client {
1162 uses netconf-client-grouping;
1163 description
1164 "Top-level container for NETCONF client configuration.";
1165 }
1166 }
1167
1169 4. The NETCONF Server Model
1171 The NETCONF server model presented in this section supports servers
1172 both listening for connections as well as initiating call-home
1173 connections.
1175 This model supports both the SSH and TLS transport protocols, using
1176 the SSH server and TLS server groupings defined in
1177 [I-D.ietf-netconf-ssh-client-server] and
1178 [I-D.ietf-netconf-tls-client-server] respectively.
1180 All private keys and trusted certificates are held in the keystore
1181 model defined in [I-D.ietf-netconf-keystore].
1183 YANG feature statements are used to enable implementations to
1184 advertise which parts of the model the NETCONF server supports.
1186 4.1. Tree Diagram
1188 The following tree diagram [RFC8340] provides an overview of the data
1189 model for the "ietf-netconf-server" module. Just the container is
1190 displayed below, but there is also a reusable grouping called
1191 "netconf-server-grouping" that the container is using.
1193 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
1194 module: ietf-netconf-server
1195 +--rw netconf-server
1196 +--rw listen! {listen}?
1197 | +--rw idle-timeout? uint16
1198 | +--rw endpoint* [name]
1199 | +--rw name string
1200 | +--rw (transport)
1201 | +--:(ssh) {ssh-listen}?
1202 | | +--rw ssh
1203 | | +--rw local-address inet:ip-address
1204 | | +--rw local-port? inet:port-number
1205 | | +--rw tcp-keepalives {tcp-server-keepalives}?
1206 | | | +--rw idle-time? uint16
1207 | | | +--rw max-probes? uint16
1208 | | | +--rw probe-interval? uint16
1209 | | +--rw ssh-server-identity
1210 | | | +--rw host-key* [name]
1211 | | | +--rw name string
1212 | | | +--rw (host-key-type)
1213 | | | +--:(public-key)
1214 | | | | +--rw public-key
1215 | | | | +--rw (local-or-keystore)
1216 | | | | +--:(local)
1217 | | | | | {local-keys-supported\
1218 \}?
1219 | | | | | +--rw local-definition
1220 | | | | | +--rw algorithm?
1221 | | | | | | asymmetric-key-a\
1222 \lgorithm-ref
1223 | | | | | +--rw public-key?
1224 | | | | | | binary
1225 | | | | | +--rw private-key?
1226 | | | | | | union
1227 | | | | | +---x generate-hidden-key
1228 | | | | | | +---w input
1229 | | | | | | +---w algorithm
1230 | | | | | | asymmetric\
1231 \-key-algorithm-ref
1232 | | | | | +---x install-hidden-key
1233 | | | | | +---w input
1234 | | | | | +---w algorithm
1235 | | | | | | asymmetric\
1236 \-key-algorithm-ref
1237 | | | | | +---w public-key?
1238 | | | | | | binary
1239 | | | | | +---w private-key?
1240 | | | | | binary
1241 | | | | +--:(keystore)
1242 | | | | {keystore-supported}?
1243 | | | | +--rw keystore-reference?
1244 | | | | ks:asymmetric-key-r\
1245 \ef
1246 | | | +--:(certificate)
1247 | | | +--rw certificate
1248 | | | {sshcmn:ssh-x509-certs}?
1249 | | | +--rw (local-or-keystore)
1250 | | | +--:(local)
1251 | | | | {local-keys-supported\
1252 \}?
1253 | | | | +--rw local-definition
1254 | | | | +--rw algorithm?
1255 | | | | | asymmetric-key-a\
1256 \lgorithm-ref
1257 | | | | +--rw public-key?
1258 | | | | | binary
1259 | | | | +--rw private-key?
1260 | | | | | union
1261 | | | | +---x generate-hidden-key
1262 | | | | | +---w input
1263 | | | | | +---w algorithm
1264 | | | | | asymmetric\
1265 \-key-algorithm-ref
1266 | | | | +---x install-hidden-key
1267 | | | | | +---w input
1268 | | | | | +---w algorithm
1269 | | | | | | asymmetric\
1270 \-key-algorithm-ref
1271 | | | | | +---w public-key?
1272 | | | | | | binary
1273 | | | | | +---w private-key?
1274 | | | | | binary
1275 | | | | +--rw cert?
1276 | | | | | end-entity-cert-\
1277 \cms
1278 | | | | +---n certificate-expira\
1279 \tion
1280 | | | | +-- expiration-date
1281 | | | | yang:date-and\
1282 \-time
1283 | | | +--:(keystore)
1284 | | | {keystore-supported}?
1285 | | | +--rw keystore-reference?
1286 | | | ks:asymmetric-key-c\
1287 \ertificate-ref
1288 | | +--rw ssh-client-cert-auth {sshcmn:ssh-x509-cert\
1289 \s}?
1290 | | | +--rw pinned-ca-certs?
1291 | | | | ta:pinned-certificates-ref
1292 | | | | {ta:x509-certificates}?
1293 | | | +--rw pinned-client-certs?
1294 | | | ta:pinned-certificates-ref
1295 | | | {ta:x509-certificates}?
1296 | | +--rw ssh-transport-params
1297 | | | {ssh-server-transport-params-config}?
1298 | | | +--rw host-key
1299 | | | | +--rw host-key-alg* identityref
1300 | | | +--rw key-exchange
1301 | | | | +--rw key-exchange-alg* identityref
1302 | | | +--rw encryption
1303 | | | | +--rw encryption-alg* identityref
1304 | | | +--rw mac
1305 | | | +--rw mac-alg* identityref
1306 | | +--rw ssh-keepalives {ssh-server-keepalives}?
1307 | | +--rw max-wait? uint16
1308 | | +--rw max-attempts? uint8
1309 | +--:(tls) {tls-listen}?
1310 | +--rw tls
1311 | +--rw local-address inet:ip-address
1312 | +--rw local-port? inet:port-number
1313 | +--rw tcp-keepalives {tcp-server-keepalives}?
1314 | | +--rw idle-time? uint16
1315 | | +--rw max-probes? uint16
1316 | | +--rw probe-interval? uint16
1317 | +--rw tls-server-identity
1318 | | +--rw (local-or-keystore)
1319 | | +--:(local) {local-keys-supported}?
1320 | | | +--rw local-definition
1321 | | | +--rw algorithm?
1322 | | | | asymmetric-key-algorithm-ref
1323 | | | +--rw public-key? bina\
1324 \ry
1325 | | | +--rw private-key? union
1326 | | | +---x generate-hidden-key
1327 | | | | +---w input
1328 | | | | +---w algorithm
1329 | | | | asymmetric-key-algorit\
1330 \hm-ref
1331 | | | +---x install-hidden-key
1332 | | | | +---w input
1333 | | | | +---w algorithm
1334 | | | | | asymmetric-key-algorit\
1335 \hm-ref
1336 | | | | +---w public-key? binary
1337 | | | | +---w private-key? binary
1338 | | | +--rw cert?
1339 | | | | end-entity-cert-cms
1340 | | | +---n certificate-expiration
1341 | | | +-- expiration-date
1342 | | | yang:date-and-time
1343 | | +--:(keystore) {keystore-supported}?
1344 | | +--rw keystore-reference?
1345 | | ks:asymmetric-key-certificate-r\
1346 \ef
1347 | +--rw tls-client-auth
1348 | | +--rw pinned-ca-certs?
1349 | | | ta:pinned-certificates-ref
1350 | | | {ta:x509-certificates}?
1351 | | +--rw pinned-client-certs?
1352 | | | ta:pinned-certificates-ref
1353 | | | {ta:x509-certificates}?
1354 | | +--rw cert-maps
1355 | | +--rw cert-to-name* [id]
1356 | | +--rw id uint32
1357 | | +--rw fingerprint
1358 | | | x509c2n:tls-fingerprint
1359 | | +--rw map-type identityref
1360 | | +--rw name string
1361 | +--rw tls-hello-params
1362 | | {tls-server-hello-params-config}?
1363 | | +--rw tls-versions
1364 | | | +--rw tls-version* identityref
1365 | | +--rw cipher-suites
1366 | | +--rw cipher-suite* identityref
1367 | +--rw tls-keepalives {tls-server-keepalives}?
1368 | +--rw max-wait? uint16
1369 | +--rw max-attempts? uint8
1370 +--rw call-home! {call-home}?
1371 +--rw netconf-client* [name]
1372 +--rw name string
1373 +--rw endpoints
1374 | +--rw endpoint* [name]
1375 | +--rw name string
1376 | +--rw (transport)
1377 | +--:(ssh) {ssh-call-home}?
1378 | | +--rw ssh
1379 | | +--rw remote-address inet:host
1380 | | +--rw remote-port?
1381 | | | inet:port-number
1382 | | +--rw local-address? inet:ip-addr\
1383 \ess
1384 | | +--rw local-port?
1385 | | | inet:port-number
1386 | | +--rw tcp-keepalives {tcp-client-keepalive\
1387 \s}?
1388 | | | +--rw idle-time? uint16
1389 | | | +--rw max-probes? uint16
1390 | | | +--rw probe-interval? uint16
1391 | | +--rw ssh-server-identity
1392 | | | +--rw host-key* [name]
1393 | | | +--rw name string
1394 | | | +--rw (host-key-type)
1395 | | | +--:(public-key)
1396 | | | | +--rw public-key
1397 | | | | +--rw (local-or-keystore)
1398 | | | | +--:(local)
1399 | | | | | {local-keys-sup\
1400 \ported}?
1401 | | | | | +--rw local-definition
1402 | | | | | +--rw algorithm?
1403 | | | | | | asymmetric\
1404 \-key-algorithm-ref
1405 | | | | | +--rw public-key?
1406 | | | | | | binary
1407 | | | | | +--rw private-key?
1408 | | | | | | union
1409 | | | | | +---x generate-hid\
1410 \den-key
1411 | | | | | | +---w input
1412 | | | | | | +---w algori\
1413 \thm
1414 | | | | | | asym\
1415 \metric-key-algorithm-ref
1416 | | | | | +---x install-hidd\
1417 \en-key
1418 | | | | | +---w input
1419 | | | | | +---w algori\
1420 \thm
1421 | | | | | | asym\
1422 \metric-key-algorithm-ref
1423 | | | | | +---w public\
1424 \-key?
1425 | | | | | | bina\
1426 \ry
1427 | | | | | +---w privat\
1428 \e-key?
1429 | | | | | bina\
1430 \ry
1431 | | | | +--:(keystore)
1432 | | | | {keystore-suppo\
1433 \rted}?
1434 | | | | +--rw keystore-refere\
1435 \nce?
1436 | | | | ks:asymmetric\
1437 \-key-ref
1438 | | | +--:(certificate)
1439 | | | +--rw certificate
1440 | | | {sshcmn:ssh-x509-certs\
1441 \}?
1442 | | | +--rw (local-or-keystore)
1443 | | | +--:(local)
1444 | | | | {local-keys-sup\
1445 \ported}?
1446 | | | | +--rw local-definition
1447 | | | | +--rw algorithm?
1448 | | | | | asymmetric\
1449 \-key-algorithm-ref
1450 | | | | +--rw public-key?
1451 | | | | | binary
1452 | | | | +--rw private-key?
1453 | | | | | union
1454 | | | | +---x generate-hid\
1455 \den-key
1456 | | | | | +---w input
1457 | | | | | +---w algori\
1458 \thm
1459 | | | | | asym\
1460 \metric-key-algorithm-ref
1461 | | | | +---x install-hidd\
1462 \en-key
1463 | | | | | +---w input
1464 | | | | | +---w algori\
1465 \thm
1466 | | | | | | asym\
1467 \metric-key-algorithm-ref
1468 | | | | | +---w public\
1469 \-key?
1470 | | | | | | bina\
1471 \ry
1472 | | | | | +---w privat\
1473 \e-key?
1474 | | | | | bina\
1475 \ry
1476 | | | | +--rw cert?
1477 | | | | | end-entity\
1478 \-cert-cms
1479 | | | | +---n certificate-\
1480 \expiration
1481 | | | | +-- expiration-\
1483 \date
1484 | | | | yang:da\
1485 \te-and-time
1486 | | | +--:(keystore)
1487 | | | {keystore-suppo\
1488 \rted}?
1489 | | | +--rw keystore-refere\
1490 \nce?
1491 | | | ks:asymmetric\
1492 \-key-certificate-ref
1493 | | +--rw ssh-client-cert-auth
1494 | | | {sshcmn:ssh-x509-certs}?
1495 | | | +--rw pinned-ca-certs?
1496 | | | | ta:pinned-certificates-ref
1497 | | | | {ta:x509-certificates}?
1498 | | | +--rw pinned-client-certs?
1499 | | | ta:pinned-certificates-ref
1500 | | | {ta:x509-certificates}?
1501 | | +--rw ssh-transport-params
1502 | | | {ssh-server-transport-params-confi\
1503 \g}?
1504 | | | +--rw host-key
1505 | | | | +--rw host-key-alg* identityref
1506 | | | +--rw key-exchange
1507 | | | | +--rw key-exchange-alg* identityref
1508 | | | +--rw encryption
1509 | | | | +--rw encryption-alg* identityref
1510 | | | +--rw mac
1511 | | | +--rw mac-alg* identityref
1512 | | +--rw ssh-keepalives {ssh-server-keepalive\
1513 \s}?
1514 | | +--rw max-wait? uint16
1515 | | +--rw max-attempts? uint8
1516 | +--:(tls) {tls-call-home}?
1517 | +--rw tls
1518 | +--rw remote-address inet:host
1519 | +--rw remote-port? inet:port-num\
1520 \ber
1521 | +--rw local-address? inet:ip-addre\
1522 \ss
1523 | +--rw local-port? inet:port-num\
1524 \ber
1525 | +--rw tcp-keepalives {tcp-client-keepalive\
1526 \s}?
1527 | | +--rw idle-time? uint16
1528 | | +--rw max-probes? uint16
1529 | | +--rw probe-interval? uint16
1530 | +--rw tls-server-identity
1531 | | +--rw (local-or-keystore)
1532 | | +--:(local) {local-keys-supported}?
1533 | | | +--rw local-definition
1534 | | | +--rw algorithm?
1535 | | | | asymmetric-key-algorit\
1536 \hm-ref
1537 | | | +--rw public-key?
1538 | | | | binary
1539 | | | +--rw private-key?
1540 | | | | union
1541 | | | +---x generate-hidden-key
1542 | | | | +---w input
1543 | | | | +---w algorithm
1544 | | | | asymmetric-key-a\
1545 \lgorithm-ref
1546 | | | +---x install-hidden-key
1547 | | | | +---w input
1548 | | | | +---w algorithm
1549 | | | | | asymmetric-key-a\
1550 \lgorithm-ref
1551 | | | | +---w public-key? bin\
1552 \ary
1553 | | | | +---w private-key? bin\
1554 \ary
1555 | | | +--rw cert?
1556 | | | | end-entity-cert-cms
1557 | | | +---n certificate-expiration
1558 | | | +-- expiration-date
1559 | | | yang:date-and-time
1560 | | +--:(keystore) {keystore-supported}?
1561 | | +--rw keystore-reference?
1562 | | ks:asymmetric-key-certifi\
1563 \cate-ref
1564 | +--rw tls-client-auth
1565 | | +--rw pinned-ca-certs?
1566 | | | ta:pinned-certificates-ref
1567 | | | {ta:x509-certificates}?
1568 | | +--rw pinned-client-certs?
1569 | | | ta:pinned-certificates-ref
1570 | | | {ta:x509-certificates}?
1571 | | +--rw cert-maps
1572 | | +--rw cert-to-name* [id]
1573 | | +--rw id uint32
1574 | | +--rw fingerprint
1575 | | | x509c2n:tls-fingerprint
1576 | | +--rw map-type identityref
1577 | | +--rw name string
1578 | +--rw tls-hello-params
1579 | | {tls-server-hello-params-config}?
1580 | | +--rw tls-versions
1581 | | | +--rw tls-version* identityref
1582 | | +--rw cipher-suites
1583 | | +--rw cipher-suite* identityref
1584 | +--rw tls-keepalives {tls-server-keepalive\
1585 \s}?
1586 | +--rw max-wait? uint16
1587 | +--rw max-attempts? uint8
1588 +--rw connection-type
1589 | +--rw (connection-type)
1590 | +--:(persistent-connection)
1591 | | +--rw persistent!
1592 | +--:(periodic-connection)
1593 | +--rw periodic!
1594 | +--rw period? uint16
1595 | +--rw anchor-time? yang:date-and-time
1596 | +--rw idle-timeout? uint16
1597 +--rw reconnect-strategy
1598 +--rw start-with? enumeration
1599 +--rw max-attempts? uint8
1601 4.2. Example Usage
1603 The following example illustrates configuring a NETCONF server to
1604 listen for NETCONF client connections using both the SSH and TLS
1605 transport protocols, as well as configuring call-home to two NETCONF
1606 clients, one using SSH and the other using TLS.
1608 This example is consistent with the examples presented in Section 3.2
1609 of [I-D.ietf-netconf-keystore].
1611 ========== NOTE: '\\' line wrapping per BCP XX (RFC XXXX) ===========
1613
1617
1618
1619
1620 netconf/ssh
1621
1622 192.0.2.7
1623
1624
1625 deployment-specific-certificate
1626
1627
1628 ct:rsa2048
1630 base64encodedvalue==
1631 base64encodedvalue==
1632
1633
1634
1635
1636
1637 explicitly-trusted-client-ca-certs
1639 explicitly-trusted-client-certs
1641
1642
1643
1644
1645 netconf/tls
1646
1647 192.0.2.7
1648
1649
1650 ct:rsa2048
1652 base64encodedvalue==
1653 base64encodedvalue==
1654 base64encodedvalue==
1655
1656
1657
1658 explicitly-trusted-client-ca-certs
1660 explicitly-trusted-client-certs
1662
1663
1664 1
1665 11:0A:05:11:00
1666 x509c2n:san-any
1667
1668
1669 2
1670 B3:4F:A1:8C:54
1671 x509c2n:specified
1672 scooby-doo
1673
1674
1676
1677
1678
1679
1681
1682
1683
1684 config-mgr
1685
1686
1687 east-data-center
1688
1689 east.config-mgr.example.com
1691
1692
1693 deployment-specific-certificate
1694
1695
1696 ct:rsa2048
1698 base64encodedvalue==
1699 base64encodedvalue==
1700
1701
1702
1703
1704
1705 explicitly-trusted-client-ca-certs
1707 explicitly-trusted-client-certs\
1708 \pinned-client-certs>
1709
1710
1711
1712
1713 west-data-center
1714
1715 west.config-mgr.example.com
1717
1718
1719 deployment-specific-certificate
1720
1721
1722 ct:rsa2048
1724 base64encodedvalue==
1725 base64encodedvalue==
1726
1727
1728
1729
1730
1731 explicitly-trusted-client-ca-certs
1733 explicitly-trusted-client-certs\
1734 \pinned-client-certs>
1735
1736
1737
1738
1739
1740
1741 300
1742 60
1743
1744
1745
1746 last-connected
1747 3
1748
1749
1750
1751 data-collector
1752
1753
1754 east-data-center
1755
1756 east.analytics.example.com
1758
1759
1760 ct:rsa2048
1762 base64encodedvalue==
1763 base64encodedvalue==
1764 base64encodedvalue==
1765
1766
1767
1768 explicitly-trusted-client-ca-certs
1770 explicitly-trusted-client-certs\
1771 \pinned-client-certs>
1772
1773
1774 1
1775 11:0A:05:11:00
1776 x509c2n:san-any
1777
1778
1779 2
1780 B3:4F:A1:8C:54
1781 x509c2n:specified
1782 scooby-doo
1783
1784
1785
1786
1787 15
1788 3
1789 30
1790
1791
1792 30
1793 3
1794
1795
1796
1797
1798 west-data-center
1799
1800 west.analytics.example.com
1802
1803
1804 ct:rsa2048
1806 base64encodedvalue==
1807 base64encodedvalue==
1808 base64encodedvalue==
1809
1810
1811
1812 explicitly-trusted-client-ca-certs
1814 explicitly-trusted-client-certs\
1815 \pinned-client-certs>
1816
1817
1818 1
1819 11:0A:05:11:00
1820 x509c2n:san-any
1821
1822
1823 2
1824 B3:4F:A1:8C:54
1825 x509c2n:specified
1826 scooby-doo
1827
1828
1829
1830
1831 15
1832 3
1833 30
1834
1835
1836 30
1837 3
1838
1839
1840
1841
1842
1843
1844
1845
1846 first-listed
1847 3
1848
1849
1850
1851
1853 4.3. YANG Module
1855 This YANG module has normative references to [RFC6242], [RFC6991],
1856 [RFC7407], [RFC7589], [RFC8071],
1857 [I-D.kwatsen-netconf-tcp-client-server],
1858 [I-D.ietf-netconf-ssh-client-server], and
1859 [I-D.ietf-netconf-tls-client-server].
1861 This YANG module imports YANG types from [RFC6991], and YANG
1862 groupings from [RFC7407], [I-D.ietf-netconf-ssh-client-server] and
1863 [I-D.ietf-netconf-ssh-client-server].
1865 file "ietf-netconf-server@2019-03-09.yang"
1866 module ietf-netconf-server {
1867 yang-version 1.1;
1868 namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-server";
1869 prefix "ncs";
1871 import ietf-yang-types {
1872 prefix yang;
1873 reference
1874 "RFC 6991: Common YANG Data Types";
1875 }
1877 import ietf-x509-cert-to-name {
1878 prefix x509c2n;
1879 reference
1880 "RFC 7407: A YANG Data Model for SNMP Configuration";
1881 }
1883 import ietf-tcp-client {
1884 prefix tcpc;
1885 reference
1886 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
1887 }
1889 import ietf-tcp-server {
1890 prefix tcps;
1891 reference
1892 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
1893 }
1895 import ietf-ssh-server {
1896 prefix sshs;
1897 revision-date 2019-03-09; // stable grouping definitions
1898 reference
1899 "RFC YYYY: YANG Groupings for SSH Clients and SSH Servers";
1900 }
1902 import ietf-tls-server {
1903 prefix tlss;
1904 revision-date 2019-03-09; // stable grouping definitions
1905 reference
1906 "RFC ZZZZ: YANG Groupings for TLS Clients and TLS Servers";
1907 }
1909 organization
1910 "IETF NETCONF (Network Configuration) Working Group";
1912 contact
1913 "WG Web:
1914 WG List:
1915 Author: Kent Watsen
1916 Author: Gary Wu
1917 Author: Juergen Schoenwaelder
1918 ";
1920 description
1921 "This module contains a collection of YANG definitions for
1922 configuring NETCONF servers.
1924 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
1925 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
1926 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
1927 are to be interpreted as described in BCP 14 [RFC2119]
1928 [RFC8174] when, and only when, they appear in all
1929 capitals, as shown here.
1931 Copyright (c) 2019 IETF Trust and the persons identified as
1932 authors of the code. All rights reserved.
1934 Redistribution and use in source and binary forms, with or
1935 without modification, is permitted pursuant to, and subject
1936 to the license terms contained in, the Simplified BSD
1937 License set forth in Section 4.c of the IETF Trust's
1938 Legal Provisions Relating to IETF Documents
1939 (http://trustee.ietf.org/license-info).
1941 This version of this YANG module is part of RFC XXXX; see
1942 the RFC itself for full legal notices.";
1944 revision "2019-03-09" {
1945 description
1946 "Initial version";
1947 reference
1948 "RFC XXXX: NETCONF Client and Server Models";
1949 }
1951 // Features
1953 feature listen {
1954 description
1955 "The 'listen' feature indicates that the NETCONF server
1956 supports opening a port to accept NETCONF client connections
1957 using at least one transport (e.g., SSH, TLS, etc.).";
1958 }
1960 feature ssh-listen {
1961 description
1962 "The 'ssh-listen' feature indicates that the NETCONF server
1963 supports opening a port to accept NETCONF over SSH
1964 client connections.";
1965 reference
1966 "RFC 6242:
1967 Using the NETCONF Protocol over Secure Shell (SSH)";
1968 }
1970 feature tls-listen {
1971 description
1972 "The 'tls-listen' feature indicates that the NETCONF server
1973 supports opening a port to accept NETCONF over TLS
1974 client connections.";
1975 reference
1976 "RFC 7589: Using the NETCONF Protocol over Transport
1977 Layer Security (TLS) with Mutual X.509
1978 Authentication";
1979 }
1981 feature call-home {
1982 description
1983 "The 'call-home' feature indicates that the NETCONF server
1984 supports initiating NETCONF call home connections to
1985 NETCONF clients using at least one transport (e.g., SSH,
1986 TLS, etc.).";
1987 reference
1988 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
1989 }
1991 feature ssh-call-home {
1992 description
1993 "The 'ssh-call-home' feature indicates that the NETCONF
1994 server supports initiating a NETCONF over SSH call
1995 home connection to NETCONF clients.";
1996 reference
1997 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
1998 }
2000 feature tls-call-home {
2001 description
2002 "The 'tls-call-home' feature indicates that the NETCONF
2003 server supports initiating a NETCONF over TLS call
2004 home connection to NETCONF clients.";
2005 reference
2006 "RFC 8071: NETCONF Call Home and RESTCONF Call Home";
2007 }
2009 // Groupings
2011 grouping netconf-server-grouping {
2012 description
2013 "Top-level grouping for NETCONF server configuration.";
2014 container listen {
2015 if-feature listen;
2016 presence "Enables server to listen for TCP connections";
2017 description "Configures listen behavior";
2018 leaf idle-timeout {
2019 type uint16;
2020 units "seconds";
2021 default 3600; // one hour
2022 description
2023 "Specifies the maximum number of seconds that a NETCONF
2024 session may remain idle. A NETCONF session will be
2025 dropped if it is idle for an interval longer than this
2026 number of seconds. If set to zero, then the server
2027 will never drop a session because it is idle. Sessions
2028 that have a notification subscription active are never
2029 dropped.";
2030 }
2031 list endpoint {
2032 key name;
2033 min-elements 1;
2034 description
2035 "List of endpoints to listen for NETCONF connections.";
2036 leaf name {
2037 type string;
2038 description
2039 "An arbitrary name for the NETCONF listen endpoint.";
2040 }
2041 choice transport {
2042 mandatory true;
2043 description
2044 "Selects between available transports.";
2045 case ssh {
2046 if-feature ssh-listen;
2047 container ssh {
2048 description
2049 "SSH-specific listening configuration for inbound
2050 connections.";
2051 uses tcps:tcp-server-grouping {
2052 refine "local-port" {
2053 default 830;
2054 description
2055 "The NETCONF server will listen on the IANA-
2056 assigned well-known port value for 'netconf-ssh'
2057 (830) if no value is specified.";
2058 }
2059 }
2060 uses sshs:ssh-server-grouping;
2061 }
2062 }
2063 case tls {
2064 if-feature tls-listen;
2065 container tls {
2066 description
2067 "TLS-specific listening configuration for inbound
2068 connections.";
2069 uses tcps:tcp-server-grouping {
2070 refine "local-port" {
2071 default 6513;
2072 description
2073 "The NETCONF server will listen on the IANA-
2074 assigned well-known port value for 'netconf-tls'
2075 (6513) if no value is specified.";
2076 }
2077 }
2078 uses tlss:tls-server-grouping {
2079 refine "tls-client-auth" {
2080 must 'pinned-ca-certs or pinned-client-certs';
2081 description
2082 "NETCONF/TLS servers MUST validate client
2083 certiticates.";
2084 }
2085 augment "tls-client-auth" {
2086 description
2087 "Augments in the cert-to-name structure.";
2088 container cert-maps {
2089 uses x509c2n:cert-to-name;
2090 description
2091 "The cert-maps container is used by a TLS-
2092 based NETCONF server to map the NETCONF
2093 client's presented X.509 certificate to a
2094 NETCONF username. If no matching and valid
2095 cert-to-name list entry can be found, then
2096 the NETCONF server MUST close the connection,
2097 and MUST NOT accept NETCONF messages over
2098 it.";
2099 reference
2100 "RFC WWWW: NETCONF over TLS, Section 7";
2101 }
2102 }
2103 }
2104 }
2105 }
2106 }
2107 }
2109 }
2111 container call-home {
2112 if-feature call-home;
2113 presence "Enables server to initiate TCP connections";
2114 description "Configures call-home behavior";
2115 list netconf-client {
2116 key name;
2117 min-elements 1;
2118 description
2119 "List of NETCONF clients the NETCONF server is to
2120 initiate call-home connections to in parallel.";
2121 leaf name {
2122 type string;
2123 description
2124 "An arbitrary name for the remote NETCONF client.";
2125 }
2126 container endpoints {
2127 description
2128 "Container for the list of endpoints.";
2129 list endpoint {
2130 key name;
2131 min-elements 1;
2132 ordered-by user;
2133 description
2134 "A non-empty user-ordered list of endpoints for this
2135 NETCONF server to try to connect to in sequence.
2136 Defining more than one enables high-availability.";
2137 leaf name {
2138 type string;
2139 description
2140 "An arbitrary name for this endpoint.";
2141 }
2142 choice transport {
2143 mandatory true;
2144 description
2145 "Selects between available transports.";
2146 case ssh {
2147 if-feature ssh-call-home;
2148 container ssh {
2149 description
2150 "Specifies SSH-specific call-home transport
2151 configuration.";
2152 uses tcpc:tcp-client-grouping {
2153 refine "remote-port" {
2154 default 4334;
2155 description
2156 "The NETCONF server will attempt to connect
2157 to the IANA-assigned well-known port for
2158 'netconf-ch-tls' (4334) if no value is
2159 specified.";
2160 }
2161 }
2162 uses sshs:ssh-server-grouping;
2163 }
2164 }
2165 case tls {
2166 if-feature tls-call-home;
2167 container tls {
2168 description
2169 "Specifies TLS-specific call-home transport
2170 configuration.";
2171 uses tcpc:tcp-client-grouping {
2172 refine "remote-port" {
2173 default 4335;
2174 description
2175 "The NETCONF server will attempt to connect
2176 to the IANA-assigned well-known port for
2177 'netconf-ch-tls' (4335) if no value is
2178 specified.";
2179 }
2180 }
2181 uses tlss:tls-server-grouping {
2182 refine "tls-client-auth" {
2183 must 'pinned-ca-certs or pinned-client-certs';
2184 description
2185 "NETCONF/TLS servers MUST validate client
2186 certiticates.";
2187 }
2188 augment "tls-client-auth" {
2189 description
2190 "Augments in the cert-to-name structure.";
2191 container cert-maps {
2192 uses x509c2n:cert-to-name;
2193 description
2194 "The cert-maps container is used by a
2195 TLS-based NETCONF server to map the
2196 NETCONF client's presented X.509
2197 certificate to a NETCONF username. If
2198 no matching and valid cert-to-name list
2199 entry can be found, then the NETCONF
2200 server MUST close the connection, and
2201 MUST NOT accept NETCONF messages over
2202 it.";
2203 reference
2204 "RFC WWWW: NETCONF over TLS, Section 7";
2206 }
2207 }
2208 }
2209 }
2210 } // tls
2211 } // choice
2212 } // endpoint
2213 } // endpoints
2214 container connection-type {
2215 description
2216 "Indicates the NETCONF server's preference for how the
2217 NETCONF connection is maintained.";
2218 choice connection-type {
2219 mandatory true;
2220 description
2221 "Selects between available connection types.";
2222 case persistent-connection {
2223 container persistent {
2224 presence
2225 "Indicates that a persistent connection is to be
2226 maintained.";
2227 description
2228 "Maintain a persistent connection to the NETCONF
2229 client. If the connection goes down, immediately
2230 start trying to reconnect to it, using the
2231 reconnection strategy.
2233 This connection type minimizes any NETCONF client
2234 to NETCONF server data-transfer delay, albeit at
2235 the expense of holding resources longer.";
2236 } // container persistent
2237 } // case persistent-connection
2239 case periodic-connection {
2240 container periodic {
2241 presence
2242 "Indicates that a periodic connection is to be
2243 maintained.";
2244 description
2245 "Periodically connect to the NETCONF client. The
2246 NETCONF client should close the underlying TLS
2247 connection upon completing planned activities.
2249 This connection type increases resource
2250 utilization, albeit with increased delay in
2251 NETCONF client to NETCONF client interactions.";
2252 leaf period {
2253 type uint16;
2254 units "minutes";
2255 default 60;
2256 description
2257 "Duration of time between periodic connections.";
2258 }
2259 leaf anchor-time {
2260 type yang:date-and-time {
2261 // constrained to minute-level granularity
2262 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}'
2263 + '(Z|[\+\-]\d{2}:\d{2})';
2264 }
2265 description
2266 "Designates a timestamp before or after which a
2267 series of periodic connections are determined.
2268 The periodic connections occur at a whole
2269 multiple interval from the anchor time. For
2270 example, for an anchor time is 15 minutes past
2271 midnight and a period interval of 24 hours, then
2272 a periodic connection will occur 15 minutes past
2273 midnight everyday.";
2274 }
2275 leaf idle-timeout {
2276 type uint16;
2277 units "seconds";
2278 default 120; // two minutes
2279 description
2280 "Specifies the maximum number of seconds that
2281 a NETCONF session may remain idle. A NETCONF
2282 session will be dropped if it is idle for an
2283 interval longer than this number of seconds.
2284 If set to zero, then the server will never
2285 drop a session because it is idle.";
2286 }
2287 } // container periodic
2288 } // case periodic-connection
2289 } // choice connection-type
2290 } // container connection-type
2291 container reconnect-strategy {
2292 description
2293 "The reconnection strategy directs how a NETCONF server
2294 reconnects to a NETCONF client, after discovering its
2295 connection to the client has dropped, even if due to a
2296 reboot. The NETCONF server starts with the specified
2297 endpoint and tries to connect to it max-attempts times
2298 before trying the next endpoint in the list (round
2299 robin).";
2300 leaf start-with {
2301 type enumeration {
2302 enum first-listed {
2303 description
2304 "Indicates that reconnections should start with
2305 the first endpoint listed.";
2306 }
2307 enum last-connected {
2308 description
2309 "Indicates that reconnections should start with
2310 the endpoint last connected to. If no previous
2311 connection has ever been established, then the
2312 first endpoint configured is used. NETCONF
2313 servers SHOULD be able to remember the last
2314 endpoint connected to across reboots.";
2315 }
2316 enum random-selection {
2317 description
2318 "Indicates that reconnections should start with
2319 a random endpoint.";
2320 }
2321 }
2322 default first-listed;
2323 description
2324 "Specifies which of the NETCONF client's endpoints
2325 the NETCONF server should start with when trying
2326 to connect to the NETCONF client.";
2327 }
2328 leaf max-attempts {
2329 type uint8 {
2330 range "1..max";
2331 }
2332 default 3;
2333 description
2334 "Specifies the number times the NETCONF server tries
2335 to connect to a specific endpoint before moving on
2336 to the next endpoint in the list (round robin).";
2337 }
2338 } // container reconnect-strategy
2339 } // list netconf-client
2340 } // container call-home
2341 } // grouping netconf-server-grouping
2343 // Protocol accessible node, for servers that *implement*
2344 // this module.
2346 container netconf-server {
2347 uses netconf-server-grouping;
2348 description
2349 "Top-level container for NETCONF server configuration.";
2351 }
2353 }
2355
2357 5. Design Considerations
2359 Editorial: this section is a hold over from before, previously called
2360 "Objectives". It was only written two support the "server" (not the
2361 "client"). The question is if it's better to add the missing
2362 "client" parts, or remove this section altogether.
2364 The primary purpose of the YANG modules defined herein is to enable
2365 the configuration of the NETCONF client and servers. This scope
2366 includes the following objectives:
2368 5.1. Support all NETCONF transports
2370 The YANG module should support all current NETCONF transports, namely
2371 NETCONF over SSH [RFC6242], NETCONF over TLS [RFC7589], and to be
2372 extensible to support future transports as necessary.
2374 Because implementations may not support all transports, the modules
2375 should use YANG "feature" statements so that implementations can
2376 accurately advertise which transports are supported.
2378 5.2. Enable each transport to select which keys to use
2380 Servers may have a multiplicity of host-keys or server-certificates
2381 from which subsets may be selected for specific uses. For instance,
2382 a NETCONF server may want to use one set of SSH host-keys when
2383 listening on port 830, and a different set of SSH host-keys when
2384 calling home. The data models provided herein should enable
2385 configuration of which keys to use on a per-use basis.
2387 5.3. Support authenticating NETCONF clients certificates
2389 When a certificate is used to authenticate a NETCONF client, there is
2390 a need to configure the server to know how to authenticate the
2391 certificates. The server should be able to authenticate the client's
2392 certificate either by using path-validation to a configured trust
2393 anchor or by matching the client-certificate to one previously
2394 configured.
2396 5.4. Support mapping authenticated NETCONF client certificates to
2397 usernames
2399 When a client certificate is used for TLS client authentication, the
2400 NETCONF server must be able to derive a username from the
2401 authenticated certificate. Thus the modules defined herein should
2402 enable this mapping to be configured.
2404 5.5. Support both listening for connections and call home
2406 The NETCONF protocols were originally defined as having the server
2407 opening a port to listen for client connections. More recently the
2408 NETCONF working group defined support for call-home ([RFC8071]),
2409 enabling the server to initiate the connection to the client. Thus
2410 the modules defined herein should enable configuration for both
2411 listening for connections and calling home. Because implementations
2412 may not support both listening for connections and calling home, YANG
2413 "feature" statements should be used so that implementation can
2414 accurately advertise the connection types it supports.
2416 5.6. For Call Home connections
2418 The following objectives only pertain to call home connections.
2420 5.6.1. Support more than one NETCONF client
2422 A NETCONF server may be managed by more than one NETCONF client. For
2423 instance, a deployment may have one client for provisioning and
2424 another for fault monitoring. Therefore, when it is desired for a
2425 server to initiate call home connections, it should be able to do so
2426 to more than one client.
2428 5.6.2. Support NETCONF clients having more than one endpoint
2430 A NETCONF client managing a NETCONF server may implement a high-
2431 availability strategy employing a multiplicity of active and/or
2432 passive endpoint. Therefore, when it is desired for a server to
2433 initiate call home connections, it should be able to connect to any
2434 of the client's endpoints.
2436 5.6.3. Support a reconnection strategy
2438 Assuming a NETCONF client has more than one endpoint, then it becomes
2439 necessary to configure how a NETCONF server should reconnect to the
2440 client should it lose its connection to one the client's endpoints.
2441 For instance, the NETCONF server may start with first endpoint
2442 defined in a user-ordered list of endpoints or with the last
2443 endpoints it was connected to.
2445 5.6.4. Support both persistent and periodic connections
2447 NETCONF clients may vary greatly on how frequently they need to
2448 interact with a NETCONF server, how responsive interactions need to
2449 be, and how many simultaneous connections they can support. Some
2450 clients may need a persistent connection to servers to optimize real-
2451 time interactions, while others prefer periodic interactions in order
2452 to minimize resource requirements. Therefore, when it is necessary
2453 for server to initiate connections, it should be configurable if the
2454 connection is persistent or periodic.
2456 5.6.5. Reconnection strategy for periodic connections
2458 The reconnection strategy should apply to both persistent and
2459 periodic connections. How it applies to periodic connections becomes
2460 clear when considering that a periodic "connection" is a logical
2461 connection to a single server. That is, the periods of
2462 unconnectedness are intentional as opposed to due to external
2463 reasons. A periodic "connection" should always reconnect to the same
2464 server until it is no longer able to, at which time the reconnection
2465 strategy guides how to connect to another server.
2467 5.6.6. Keep-alives for persistent connections
2469 If a persistent connection is desired, it is the responsibility of
2470 the connection initiator to actively test the "aliveness" of the
2471 connection. The connection initiator must immediately work to
2472 reestablish a persistent connection as soon as the connection is
2473 lost. How often the connection should be tested is driven by NETCONF
2474 client requirements, and therefore keep-alive settings should be
2475 configurable on a per-client basis.
2477 5.6.7. Customizations for periodic connections
2479 If a periodic connection is desired, it is necessary for the NETCONF
2480 server to know how often it should connect. This frequency
2481 determines the maximum amount of time a NETCONF client may have to
2482 wait to send data to a server. A server may connect to a client
2483 before this interval expires if desired (e.g., to send data to a
2484 client).
2486 6. Security Considerations
2488 The YANG module defined in this document uses groupings defined in
2489 [I-D.ietf-netconf-ssh-client-server] and
2490 [I-D.ietf-netconf-tls-client-server]. Please see the Security
2491 Considerations section in those documents for concerns related those
2492 groupings.
2494 The YANG module defined in this document is designed to be accessed
2495 via YANG based management protocols, such as NETCONF [RFC6241] and
2496 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
2497 implement secure transport layers (e.g., SSH, TLS) with mutual
2498 authentication.
2500 The NETCONF access control model (NACM) [RFC8341] provides the means
2501 to restrict access for particular users to a pre-configured subset of
2502 all available protocol operations and content.
2504 There are a number of data nodes defined in this YANG module that are
2505 writable/creatable/deletable (i.e., config true, which is the
2506 default). These data nodes may be considered sensitive or vulnerable
2507 in some network environments. Write operations (e.g., edit-config)
2508 to these data nodes without proper protection can have a negative
2509 effect on network operations. These are the subtrees and data nodes
2510 and their sensitivity/vulnerability:
2512 /: The entire data trees defined by the modules defined in this
2513 draft are sensitive to write operations. For instance, the
2514 addition or removal of references to keys, certificates,
2515 trusted anchors, etc., can dramatically alter the implemented
2516 security policy. However, no NACM annotations are applied as
2517 the data SHOULD be editable by users other than a designated
2518 'recovery session'.
2520 Some of the readable data nodes in this YANG module may be considered
2521 sensitive or vulnerable in some network environments. It is thus
2522 important to control read access (e.g., via get, get-config, or
2523 notification) to these data nodes. These are the subtrees and data
2524 nodes and their sensitivity/vulnerability:
2526 NONE
2528 Some of the RPC operations in this YANG module may be considered
2529 sensitive or vulnerable in some network environments. It is thus
2530 important to control access to these operations. These are the
2531 operations and their sensitivity/vulnerability:
2533 NONE
2535 7. IANA Considerations
2537 7.1. The IETF XML Registry
2539 This document registers two URIs in the "ns" subregistry of the IETF
2540 XML Registry [RFC3688]. Following the format in [RFC3688], the
2541 following registrations are requested:
2543 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-client
2544 Registrant Contact: The NETCONF WG of the IETF.
2545 XML: N/A, the requested URI is an XML namespace.
2547 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-server
2548 Registrant Contact: The NETCONF WG of the IETF.
2549 XML: N/A, the requested URI is an XML namespace.
2551 7.2. The YANG Module Names Registry
2553 This document registers two YANG modules in the YANG Module Names
2554 registry [RFC6020]. Following the format in [RFC6020], the the
2555 following registrations are requested:
2557 name: ietf-netconf-client
2558 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-client
2559 prefix: ncc
2560 reference: RFC XXXX
2562 name: ietf-netconf-server
2563 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-server
2564 prefix: ncs
2565 reference: RFC XXXX
2567 8. References
2569 8.1. Normative References
2571 [I-D.ietf-netconf-keystore]
2572 Watsen, K., "YANG Data Model for a Centralized Keystore
2573 Mechanism", draft-ietf-netconf-keystore-08 (work in
2574 progress), March 2019.
2576 [I-D.ietf-netconf-ssh-client-server]
2577 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for SSH
2578 Clients and SSH Servers", draft-ietf-netconf-ssh-client-
2579 server-08 (work in progress), October 2018.
2581 [I-D.ietf-netconf-tls-client-server]
2582 Watsen, K., Wu, G., and L. Xia, "YANG Groupings for TLS
2583 Clients and TLS Servers", draft-ietf-netconf-tls-client-
2584 server-08 (work in progress), October 2018.
2586 [I-D.kwatsen-netconf-tcp-client-server]
2587 Watsen, K., "YANG Groupings for TCP Clients and TCP
2588 Servers", draft-kwatsen-netconf-tcp-client-server-00 (work
2589 in progress), March 2019.
2591 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2592 Requirement Levels", BCP 14, RFC 2119,
2593 DOI 10.17487/RFC2119, March 1997,
2594 .
2596 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2597 the Network Configuration Protocol (NETCONF)", RFC 6020,
2598 DOI 10.17487/RFC6020, October 2010,
2599 .
2601 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2602 and A. Bierman, Ed., "Network Configuration Protocol
2603 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2604 .
2606 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2607 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2608 .
2610 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2611 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2612 .
2614 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
2615 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
2616 December 2014, .
2618 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the
2619 NETCONF Protocol over Transport Layer Security (TLS) with
2620 Mutual X.509 Authentication", RFC 7589,
2621 DOI 10.17487/RFC7589, June 2015,
2622 .
2624 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2625 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2626 .
2628 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2629 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
2630 May 2017, .
2632 8.2. Informative References
2634 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2635 DOI 10.17487/RFC3688, January 2004,
2636 .
2638 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2639 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2640 .
2642 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
2643 RFC 8071, DOI 10.17487/RFC8071, February 2017,
2644 .
2646 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
2647 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
2648 .
2650 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2651 Access Control Model", STD 91, RFC 8341,
2652 DOI 10.17487/RFC8341, March 2018,
2653 .
2655 Appendix A. Change Log
2657 A.1. 00 to 01
2659 o Renamed "keychain" to "keystore".
2661 A.2. 01 to 02
2663 o Added to ietf-netconf-client ability to connected to a cluster of
2664 endpoints, including a reconnection-strategy.
2666 o Added to ietf-netconf-client the ability to configure connection-
2667 type and also keep-alive strategy.
2669 o Updated both modules to accommodate new groupings in the ssh/tls
2670 drafts.
2672 A.3. 02 to 03
2674 o Refined use of tls-client-grouping to add a must statement
2675 indicating that the TLS client must specify a client-certificate.
2677 o Changed 'netconf-client' to be a grouping (not a container).
2679 A.4. 03 to 04
2681 o Added RFC 8174 to Requirements Language Section.
2683 o Replaced refine statement in ietf-netconf-client to add a
2684 mandatory true.
2686 o Added refine statement in ietf-netconf-server to add a must
2687 statement.
2689 o Now there are containers and groupings, for both the client and
2690 server models.
2692 A.5. 04 to 05
2694 o Now tree diagrams reference ietf-netmod-yang-tree-diagrams
2696 o Updated examples to inline key and certificates (no longer a
2697 leafref to keystore)
2699 A.6. 05 to 06
2701 o Fixed change log missing section issue.
2703 o Updated examples to match latest updates to the crypto-types,
2704 trust-anchors, and keystore drafts.
2706 o Reduced line length of the YANG modules to fit within 69 columns.
2708 A.7. 06 to 07
2710 o Removed "idle-timeout" from "persistent" connection config.
2712 o Added "random-selection" for reconnection-strategy's "starts-with"
2713 enum.
2715 o Replaced "connection-type" choice default (persistent) with
2716 "mandatory true".
2718 o Reduced the periodic-connection's "idle-timeout" from 5 to 2
2719 minutes.
2721 o Replaced reconnect-timeout with period/anchor-time combo.
2723 A.8. 07 to 08
2725 o Modified examples to be compatible with new crypto-types algs
2727 Appendix B. 08 to 09
2729 o Corrected use of "mandatory true" for "address" leafs.
2731 o Updated examples to reflect update to groupings defined in the
2732 keystore draft.
2734 o Updated to use groupings defined in new TCP and HTTP drafts.
2736 o Updated copyright date, boilerplate template, affiliation, and
2737 folding algorithm.
2739 Acknowledgements
2741 The authors would like to thank for following for lively discussions
2742 on list and in the halls (ordered by last name): Andy Bierman, Martin
2743 Bjorklund, Benoit Claise, Ramkumar Dhanapal, Mehmet Ersue, Balazs
2744 Kovacs, David Lamparter, Alan Luchuk, Ladislav Lhotka, Radek Krejci,
2745 Tom Petch, Juergen Schoenwaelder, Phil Shafer, Sean Turner, and Bert
2746 Wijnen.
2748 Author's Address
2750 Kent Watsen
2751 Watsen Networks
2753 EMail: kent+ietf@watsen.net