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