idnits 2.17.1
draft-ietf-netconf-http-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 :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 122 has weird spacing: '...assword str...'
== The document doesn't use any RFC 2119 keywords, yet seems to have RFC
2119 boilerplate text.
-- The document date (March 8, 2020) is 1510 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)
No issues found here.
Summary: 0 errors (**), 0 flaws (~~), 3 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 8, 2020
5 Expires: September 9, 2020
7 YANG Groupings for HTTP Clients and HTTP Servers
8 draft-ietf-netconf-http-client-server-02
10 Abstract
12 This document defines two YANG modules: the first defines a minimal
13 grouping for configuring an HTTP client, and the second defines a
14 minimal grouping for configuring an HTTP server. It is intended that
15 these groupings will be used to help define the configuration for
16 simple HTTP-based protocols (not for complete webservers or
17 browsers).
19 Editorial Note (To be removed by RFC Editor)
21 This draft contains many placeholder values that need to be replaced
22 with finalized values at the time of publication. This note
23 summarizes all of the substitutions that are needed. No other RFC
24 Editor instructions are specified elsewhere in this document.
26 Artwork in this document contains placeholder values for the date of
27 publication of this draft. Please apply the following replacement:
29 o "2020-03-08" --> the publication date of this draft
31 The following Appendix section is to be removed prior to publication:
33 o Appendix A. Change Log
35 Status of This Memo
37 This Internet-Draft is submitted in full conformance with the
38 provisions of BCP 78 and BCP 79.
40 Internet-Drafts are working documents of the Internet Engineering
41 Task Force (IETF). Note that other groups may also distribute
42 working documents as Internet-Drafts. The list of current Internet-
43 Drafts is at https://datatracker.ietf.org/drafts/current/.
45 Internet-Drafts are draft documents valid for a maximum of six months
46 and may be updated, replaced, or obsoleted by other documents at any
47 time. It is inappropriate to use Internet-Drafts as reference
48 material or to cite them other than as "work in progress."
49 This Internet-Draft will expire on September 9, 2020.
51 Copyright Notice
53 Copyright (c) 2020 IETF Trust and the persons identified as the
54 document authors. All rights reserved.
56 This document is subject to BCP 78 and the IETF Trust's Legal
57 Provisions Relating to IETF Documents
58 (https://trustee.ietf.org/license-info) in effect on the date of
59 publication of this document. Please review these documents
60 carefully, as they describe your rights and restrictions with respect
61 to this document. Code Components extracted from this document must
62 include Simplified BSD License text as described in Section 4.e of
63 the Trust Legal Provisions and are provided without warranty as
64 described in the Simplified BSD License.
66 Table of Contents
68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
70 3. The HTTP Client Model . . . . . . . . . . . . . . . . . . . . 3
71 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3
72 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3
73 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4
74 4. The HTTP Server Model . . . . . . . . . . . . . . . . . . . . 7
75 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7
76 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8
77 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8
78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
80 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 13
81 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 13
82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
83 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
84 7.2. Informative References . . . . . . . . . . . . . . . . . 14
85 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 16
86 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 16
87 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 16
88 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16
89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
91 1. Introduction
93 This document defines two YANG 1.1 [RFC7950] modules: the first
94 defines a minimal grouping for configuring an HTTP client, and the
95 second defines a minimal grouping for configuring an HTTP server. It
96 is intended that these groupings will be used to help define the
97 configuration for simple HTTP-based protocols (not for complete
98 webservers or browsers).
100 2. Terminology
102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
104 "OPTIONAL" in this document are to be interpreted as described in BCP
105 14 [RFC2119] [RFC8174] when, and only when, they appear in all
106 capitals, as shown here.
108 3. The HTTP Client Model
110 3.1. Tree Diagram
112 This section provides a tree diagram [RFC8340] for the "ietf-http-
113 client" module.
115 module: ietf-http-client
117 grouping client-identity-grouping
118 +-- (auth-type)
119 +--:(basic)
120 +-- basic {basic-auth}?
121 +-- user-id string
122 +-- password string
123 grouping http-client-grouping
124 +-- client-identity
125 | +---u client-identity-grouping
126 +-- proxy-server! {proxy-connect}?
127 +-- tcp-client-parameters
128 | +---u tcpc:tcp-client-grouping
129 +-- tls-client-parameters
130 | +---u tlsc:tls-client-grouping
131 +-- proxy-client-identity
132 +---u client-identity-grouping
134 3.2. Example Usage
136 This section presents an example showing the http-client-grouping
137 populated with some data.
139
140
141
142 bob
143 secret
144
145
146
148 3.3. YANG Module
150 This YANG module has normative references to [RFC6991].
152 file "ietf-http-client@2020-03-08.yang"
154 module ietf-http-client {
155 yang-version 1.1;
156 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client";
157 prefix httpc;
159 import ietf-tcp-client {
160 prefix tcpc;
161 reference
162 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
163 }
165 import ietf-tls-client {
166 prefix tlsc;
167 reference
168 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers";
169 }
171 import ietf-netconf-acm {
172 prefix nacm;
173 reference
174 "RFC 8341: Network Configuration Access Control Model";
175 }
177 organization
178 "IETF NETCONF (Network Configuration) Working Group";
180 contact
181 "WG Web:
182 WG List:
183 Author: Kent Watsen ";
185 description
186 "This module defines reusable groupings for HTTP clients that
187 can be used as a basis for specific HTTP client instances.
189 Copyright (c) 2019 IETF Trust and the persons identified
190 as authors of the code. All rights reserved.
192 Redistribution and use in source and binary forms, with
193 or without modification, is permitted pursuant to, and
194 subject to the license terms contained in, the Simplified
195 BSD License set forth in Section 4.c of the IETF Trust's
196 Legal Provisions Relating to IETF Documents
197 (https://trustee.ietf.org/license-info).
199 This version of this YANG module is part of RFC XXXX
200 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
201 itself for full legal notices.
203 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
204 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
205 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
206 are to be interpreted as described in BCP 14 (RFC 2119)
207 (RFC 8174) when, and only when, they appear in all
208 capitals, as shown here.";
210 revision 2020-03-08 {
211 description
212 "Initial version";
213 reference
214 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
215 }
217 // Features
219 feature proxy-connect {
220 description
221 "Proxy connection configuration is configurable for
222 HTTP clients on the server implementing this feature.";
223 }
225 feature basic-auth {
226 description
227 "The 'basic-auth' feature indicates that the client
228 may be configured to use the 'basic' HTTP authentication
229 scheme.";
230 reference
231 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
232 }
234 // Groupings
235 grouping client-identity-grouping {
236 description
237 "The credentials used by the client to authenticate to
238 the HTTP server.";
239 choice auth-type {
240 nacm:default-deny-write;
241 mandatory true;
242 description
243 "The authentication type.";
244 case basic {
245 container basic {
246 if-feature "basic-auth";
247 leaf user-id {
248 type string;
249 mandatory true;
250 description
251 "The user-id for the authenticating client.";
252 }
253 leaf password {
254 nacm:default-deny-all;
255 type string;
256 mandatory true;
257 description
258 "The password for the authenticating client.";
259 }
260 description
261 "The 'basic' HTTP scheme credentials.";
262 reference
263 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
264 }
265 }
266 }
267 } // grouping client-identity-grouping
269 grouping http-client-grouping {
270 description
271 "A reusable grouping for configuring a HTTP client,
272 including the IP address and port number it initiates
273 a connections to.
275 Note that this grouping uses fairly typical descendent
276 node names such that a stack of 'uses' statements will
277 have name conflicts. It is intended that the consuming
278 data model will resolve the issue (e.g., by wrapping
279 the 'uses' statement in a container called
280 'http-client-parameters'). This model purposely does
281 not do this itself so as to provide maximum flexibility
282 to consuming models.";
284 container client-identity {
285 description
286 "The identity the HTTP client should use when
287 authenticating itself to the HTTP server.";
288 uses client-identity-grouping;
289 }
291 container proxy-server {
292 nacm:default-deny-write;
293 if-feature "proxy-connect";
294 presence true; // only so ex-http-client can pass validation?
295 container tcp-client-parameters {
296 description
297 "A wrapper around the TCP parameters to avoid
298 name collisions.";
299 uses "tcpc:tcp-client-grouping";
300 }
301 container tls-client-parameters {
302 description
303 "A wrapper around the TLS parameters to avoid
304 name collisions.";
305 uses "tlsc:tls-client-grouping";
306 }
307 container proxy-client-identity {
308 description
309 "The identity the HTTP client should use when
310 authenticating itself to the HTTP server.";
311 uses client-identity-grouping;
312 }
313 description
314 "Proxy server settings.";
315 }
316 } // grouping http-client-grouping
318 } // module ietf-http-client
320
322 4. The HTTP Server Model
324 4.1. Tree Diagram
326 This section provides a tree diagram [RFC8340] for the "ietf-http-
327 server" module.
329 module: ietf-http-server
331 grouping http-server-grouping
332 +-- server-name? string
333 +-- protocol-versions
334 | +-- protocol-version* enumeration
335 +-- client-authentication! {client-auth-config-supported}?
336 +-- users
337 +-- user* [user-id]
338 +-- user-id? string
339 +-- (auth-type)?
340 +--:(basic)
341 +-- basic {basic-auth}?
342 +-- user-id? string
343 +-- password? ianach:crypt-hash
345 4.2. Example Usage
347 This section presents an example showing the http-server-grouping
348 populated with some data.
350
351 foo.example.com
352
353 HTTP/1.1
354 HTTP/2.0
355
356
358 4.3. YANG Module
360 This YANG module has normative references to [RFC6991].
362 file "ietf-http-server@2020-03-08.yang"
364 module ietf-http-server {
365 yang-version 1.1;
366 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server";
367 prefix https;
369 import iana-crypt-hash {
370 prefix ianach;
371 reference
372 "RFC 7317: A YANG Data Model for System Management";
373 }
375 import ietf-netconf-acm {
376 prefix nacm;
377 reference
378 "RFC 8341: Network Configuration Access Control Model";
379 }
381 organization
382 "IETF NETCONF (Network Configuration) Working Group";
384 contact
385 "WG Web:
386 WG List:
387 Author: Kent Watsen ";
389 description
390 "This module defines reusable groupings for HTTP servers that
391 can be used as a basis for specific HTTP server instances.
393 Copyright (c) 2019 IETF Trust and the persons identified
394 as authors of the code. All rights reserved.
396 Redistribution and use in source and binary forms, with
397 or without modification, is permitted pursuant to, and
398 subject to the license terms contained in, the Simplified
399 BSD License set forth in Section 4.c of the IETF Trust's
400 Legal Provisions Relating to IETF Documents
401 (https://trustee.ietf.org/license-info).
403 This version of this YANG module is part of RFC XXXX
404 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
405 itself for full legal notices.
407 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
408 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
409 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
410 are to be interpreted as described in BCP 14 (RFC 2119)
411 (RFC 8174) when, and only when, they appear in all
412 capitals, as shown here.";
414 revision 2020-03-08 {
415 description
416 "Initial version";
417 reference
418 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
419 }
421 // Features
423 feature client-auth-config-supported {
424 description
425 "Indicates that the configuration for how to authenticate
426 clients can be configured herein, as opposed to in an
427 application specific location. That is, to support the
428 consuming data models that prefer to place client
429 authentication with client definitions, rather then
430 in a data model principally concerned with configuring
431 the transport.";
432 }
434 feature basic-auth {
435 description
436 "The 'basic-auth' feature indicates that the server
437 may be configured authenticate users using the 'basic'
438 HTTP authentication scheme.";
439 reference
440 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
441 }
443 // Groupings
445 grouping http-server-grouping {
446 description
447 "A reusable grouping for configuring an HTTP server.
449 Note that this grouping uses fairly typical descendent
450 node names such that a stack of 'uses' statements will
451 have name conflicts. It is intended that the consuming
452 data model will resolve the issue (e.g., by wrapping
453 the 'uses' statement in a container called
454 'http-server-parameters'). This model purposely does
455 not do this itself so as to provide maximum flexibility
456 to consuming models.";
458 leaf server-name {
459 nacm:default-deny-write;
460 type string;
461 description
462 "The value of the 'Server' header field. If not set, then
463 underlying software's default value is used. Set to the
464 empty string to disable.";
465 }
467 container protocol-versions {
468 nacm:default-deny-write;
469 description
470 "A list of HTTP protocol versions supported by this
471 server.";
473 leaf-list protocol-version {
474 type enumeration {
475 enum "HTTP/1.0" {
476 description
477 "The server supports the 'HTTP/1.0' protocol.";
478 }
479 enum "HTTP/1.1" {
480 description
481 "The server supports the 'HTTP/1.1' protocol.";
482 }
483 enum "HTTP/2.0" {
484 description
485 "The server supports the 'HTTP/2.0' protocol.";
486 }
487 }
488 description
489 "An HTTP protocol version supported by this server.";
490 }
491 }
493 container client-authentication {
494 if-feature "client-auth-config-supported";
495 nacm:default-deny-write;
496 presence
497 "Indicates that HTTP based client authentication is
498 supported (i.e., the server will request that the
499 HTTP client send authenticate when needed). This
500 is needed as some HTTP-based protocols may only
501 support, e.g., TLS-level client authentication.";
502 description
503 "Specifies how the HTTP server can authenticate HTTP
504 clients.";
505 container users {
506 description
507 "A list of locally configured users.";
508 list user {
509 key user-id;
510 description
511 "The list of local users configured on this device.";
512 leaf user-id {
513 type string;
514 description
515 "The user-id for the authenticating client.";
516 }
517 choice auth-type {
518 description
519 "The authentication type.";
520 container basic {
521 if-feature "basic-auth";
522 leaf user-id {
523 type string;
524 description
525 "The user-id for the authenticating client.";
526 }
527 leaf password {
528 nacm:default-deny-write;
529 type ianach:crypt-hash;
530 description
531 "The password for the authenticating client.";
532 }
533 description
534 "The 'basic' HTTP scheme credentials.";
535 reference
536 "RFC 7617:
537 The 'Basic' HTTP Authentication Scheme";
538 }
539 }
540 }
541 }
542 } // container client-authentication
543 } // grouping http-server-grouping
544 }
546
548 5. Security Considerations
550 The YANG modules defined in this document are designed to be accessed
551 via YANG based management protocols, such as NETCONF [RFC6241] and
552 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
553 implement secure transport layers (e.g., SSH, HTTP) with mutual
554 authentication.
556 The NETCONF access control model (NACM) [RFC8341] provides the means
557 to restrict access for particular users to a pre-configured subset of
558 all available protocol operations and content.
560 Since the modules defined in this document only define groupings,
561 these considerations are primarily for the designers of other modules
562 that use these groupings.
564 There are a number of data nodes defined in the YANG modules that are
565 writable/creatable/deletable (i.e., config true, which is the
566 default). These data nodes may be considered sensitive or vulnerable
567 in some network environments. Write operations (e.g., edit-config)
568 to these data nodes without proper protection can have a negative
569 effect on network operations. These are the subtrees and data nodes
570 and their sensitivity/vulnerability:
572 FIXME: (pending - TBD)
574 Some of the readable data nodes in the YANG modules may be considered
575 sensitive or vulnerable in some network environments. It is thus
576 important to control read access (e.g., via get, get-config, or
577 notification) to these data nodes. These are the subtrees and data
578 nodes and their sensitivity/vulnerability:
580 FIXME: (pending client auth params?)
582 Some of the RPC operations in this YANG module may be considered
583 sensitive or vulnerable in some network environments. It is thus
584 important to control access to these operations. These are the
585 operations and their sensitivity/vulnerability:
587 The modules defined in this document do not define any 'RPC' or
588 'action' statements.
590 6. IANA Considerations
592 6.1. The IETF XML Registry
594 This document registers two URIs in the "ns" subregistry of the IETF
595 XML Registry [RFC3688]. Following the format in [RFC3688], the
596 following registrations are requested:
598 URI: urn:ietf:params:xml:ns:yang:ietf-http-client
599 Registrant Contact: The NETCONF WG of the IETF.
600 XML: N/A, the requested URI is an XML namespace.
602 URI: urn:ietf:params:xml:ns:yang:ietf-http-server
603 Registrant Contact: The NETCONF WG of the IETF.
604 XML: N/A, the requested URI is an XML namespace.
606 6.2. The YANG Module Names Registry
608 This document registers two YANG modules in the YANG Module Names
609 registry [RFC6020]. Following the format in [RFC6020], the following
610 registrations are requested:
612 name: ietf-http-client
613 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client
614 prefix: httpc
615 reference: RFC XXXX
617 name: ietf-http-server
618 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server
619 prefix: https
620 reference: RFC XXXX
622 7. References
624 7.1. Normative References
626 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
627 Requirement Levels", BCP 14, RFC 2119,
628 DOI 10.17487/RFC2119, March 1997,
629 .
631 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
632 the Network Configuration Protocol (NETCONF)", RFC 6020,
633 DOI 10.17487/RFC6020, October 2010,
634 .
636 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
637 RFC 6991, DOI 10.17487/RFC6991, July 2013,
638 .
640 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
641 RFC 7950, DOI 10.17487/RFC7950, August 2016,
642 .
644 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
645 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
646 May 2017, .
648 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
649 Access Control Model", STD 91, RFC 8341,
650 DOI 10.17487/RFC8341, March 2018,
651 .
653 7.2. Informative References
655 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
656 DOI 10.17487/RFC3688, January 2004,
657 .
659 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
660 and A. Bierman, Ed., "Network Configuration Protocol
661 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
662 .
664 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
665 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
666 .
668 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
669 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
670 .
672 Appendix A. Change Log
674 A.1. 00 to 01
676 o Modified Abstract and Intro to be more accurate wrt intended
677 applicability.
679 o In ietf-http-client, removed "protocol-version" and all auth
680 schemes except "basic".
682 o In ietf-http-client, factored out "client-identity-grouping" for
683 proxy connections.
685 o In ietf-http-server, removed "choice required-or-optional" and
686 "choice local-or-external".
688 o In ietf-http-server, moved the basic auth under a "choice auth-
689 type" limited by new "feature basic-auth".
691 A.2. 01 to 02
693 o Removed the unused "external-client-auth-supported" feature from
694 ietf-http-server.
696 Acknowledgements
698 The authors would like to thank for following for lively discussions
699 on list and in the halls (ordered by last name): TBD
701 Author's Address
703 Kent Watsen
704 Watsen Networks
706 EMail: kent+ietf@watsen.net