idnits 2.17.1
draft-kwatsen-netconf-http-client-server-05.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 116 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 (November 1, 2019) is 1610 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 November 1, 2019
5 Expires: May 4, 2020
7 YANG Groupings for HTTP Clients and HTTP Servers
8 draft-kwatsen-netconf-http-client-server-05
10 Abstract
12 This document defines two YANG modules: the first defines a minimal
13 grouping for configuring a generic HTTP client, and the second
14 defines a minimal grouping for configuring a generic HTTP server. It
15 is intended that these groupings will be used by higher-level HTTP-
16 based protocols.
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 Artwork in this document contains placeholder values for the date of
26 publication of this draft. Please apply the following replacement:
28 o "2019-11-02" --> the publication date of this draft
30 The following Appendix section is to be removed prior to publication:
32 o Appendix A. Change Log
34 Status of This Memo
36 This Internet-Draft is submitted in full conformance with the
37 provisions of BCP 78 and BCP 79.
39 Internet-Drafts are working documents of the Internet Engineering
40 Task Force (IETF). Note that other groups may also distribute
41 working documents as Internet-Drafts. The list of current Internet-
42 Drafts is at https://datatracker.ietf.org/drafts/current/.
44 Internet-Drafts are draft documents valid for a maximum of six months
45 and may be updated, replaced, or obsoleted by other documents at any
46 time. It is inappropriate to use Internet-Drafts as reference
47 material or to cite them other than as "work in progress."
48 This Internet-Draft will expire on May 4, 2020.
50 Copyright Notice
52 Copyright (c) 2019 IETF Trust and the persons identified as the
53 document authors. All rights reserved.
55 This document is subject to BCP 78 and the IETF Trust's Legal
56 Provisions Relating to IETF Documents
57 (https://trustee.ietf.org/license-info) in effect on the date of
58 publication of this document. Please review these documents
59 carefully, as they describe your rights and restrictions with respect
60 to this document. Code Components extracted from this document must
61 include Simplified BSD License text as described in Section 4.e of
62 the Trust Legal Provisions and are provided without warranty as
63 described in the Simplified BSD License.
65 Table of Contents
67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
69 3. The HTTP Client Model . . . . . . . . . . . . . . . . . . . . 3
70 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3
71 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3
72 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4
73 4. The HTTP Server Model . . . . . . . . . . . . . . . . . . . . 7
74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7
75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8
76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8
77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 13
78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 14
80 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 15
81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
82 7.1. Normative References . . . . . . . . . . . . . . . . . . 15
83 7.2. Informative References . . . . . . . . . . . . . . . . . 16
84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
86 1. Introduction
88 This document defines two YANG 1.1 [RFC7950] modules: the first
89 defines a grouping for configuring a generic HTTP client, and the
90 second defines a grouping for configuring a generic HTTP server. It
91 is intended that these groupings will be used by higher-level HTTP-
92 based protocols.
94 2. Terminology
96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
98 "OPTIONAL" in this document are to be interpreted as described in BCP
99 14 [RFC2119] [RFC8174] when, and only when, they appear in all
100 capitals, as shown here.
102 3. The HTTP Client Model
104 3.1. Tree Diagram
106 This section provides a tree diagram [RFC8340] for the "ietf-http-
107 client" module.
109 module: ietf-http-client
111 grouping client-identity-grouping
112 +-- (auth-type)
113 +--:(basic)
114 +-- basic {basic-auth}?
115 +-- user-id string
116 +-- password string
117 grouping http-client-grouping
118 +-- client-identity
119 | +---u client-identity-grouping
120 +-- proxy-server! {proxy-connect}?
121 +-- tcp-client-parameters
122 | +---u tcpc:tcp-client-grouping
123 +-- tls-client-parameters
124 | +---u tlsc:tls-client-grouping
125 +-- proxy-client-identity
126 +---u client-identity-grouping
128 3.2. Example Usage
130 This section presents an example showing the http-client-grouping
131 populated with some data.
133
134
135
136 bob
137 secret
138
139
140
142 3.3. YANG Module
144 This YANG module has normative references to [RFC6991].
146 file "ietf-http-client@2019-11-02.yang"
148 module ietf-http-client {
149 yang-version 1.1;
150 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client";
151 prefix httpc;
153 import ietf-tcp-client {
154 prefix tcpc;
155 reference
156 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
157 }
159 import ietf-tls-client {
160 prefix tlsc;
161 reference
162 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers";
163 }
165 import ietf-netconf-acm {
166 prefix nacm;
167 reference
168 "RFC 8341: Network Configuration Access Control Model";
169 }
171 organization
172 "IETF NETCONF (Network Configuration) Working Group";
174 contact
175 "WG Web:
176 WG List:
177 Author: Kent Watsen ";
179 description
180 "This module defines reusable groupings for HTTP clients that
181 can be used as a basis for specific HTTP client instances.
183 Copyright (c) 2019 IETF Trust and the persons identified
184 as authors of the code. All rights reserved.
186 Redistribution and use in source and binary forms, with
187 or without modification, is permitted pursuant to, and
188 subject to the license terms contained in, the Simplified
189 BSD License set forth in Section 4.c of the IETF Trust's
190 Legal Provisions Relating to IETF Documents
191 (https://trustee.ietf.org/license-info).
193 This version of this YANG module is part of RFC XXXX
194 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
195 itself for full legal notices.;
197 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
198 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
199 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
200 are to be interpreted as described in BCP 14 (RFC 2119)
201 (RFC 8174) when, and only when, they appear in all
202 capitals, as shown here.";
204 revision 2019-11-02 {
205 description
206 "Initial version";
207 reference
208 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
209 }
211 // Features
213 feature proxy-connect {
214 description
215 "Proxy connection configuration is configurable for
216 HTTP clients on the server implementing this feature.";
217 }
219 feature basic-auth {
220 description
221 "The 'basic-auth' feature indicates that the client
222 may be configured to use the 'basic' HTTP authentication
223 scheme.";
224 reference
225 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
226 }
228 // Groupings
230 grouping client-identity-grouping {
231 description
232 "The credentials used by the client to authenticate to
233 the HTTP server.";
234 choice auth-type {
235 nacm:default-deny-write;
236 mandatory true;
237 description
238 "The authentication type.";
239 case basic {
240 container basic {
241 if-feature "basic-auth";
242 leaf user-id {
243 type string;
244 mandatory true;
245 description
246 "The user-id for the authenticating client.";
247 }
248 leaf password {
249 nacm:default-deny-all;
250 type string;
251 mandatory true;
252 description
253 "The password for the authenticating client.";
254 }
255 description
256 "The 'basic' HTTP scheme credentials.";
257 reference
258 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
259 }
260 }
261 }
262 } // grouping client-identity-grouping
264 grouping http-client-grouping {
265 description
266 "A reusable grouping for configuring a HTTP client,
267 including the IP address and port number it initiates
268 a connections to.
270 Note that this grouping uses fairly typical descendent
271 node names such that a stack of 'uses' statements will
272 have name conflicts. It is intended that the consuming
273 data model will resolve the issue (e.g., by wrapping
274 the 'uses' statement in a container called
275 'http-client-parameters'). This model purposely does
276 not do this itself so as to provide maximum flexibility
277 to consuming models.";
279 container client-identity {
280 description
281 "The identity the HTTP client should use when
282 authenticating itself to the HTTP server.";
283 uses client-identity-grouping;
284 }
285 container proxy-server {
286 nacm:default-deny-write;
287 if-feature "proxy-connect";
288 presence true; // only so ex-http-client can pass validation?
289 container tcp-client-parameters {
290 description
291 "A wrapper around the TCP parameters to avoid
292 name collisions.";
293 uses "tcpc:tcp-client-grouping";
294 }
295 container tls-client-parameters {
296 description
297 "A wrapper around the TLS parameters to avoid
298 name collisions.";
299 uses "tlsc:tls-client-grouping";
300 }
301 container proxy-client-identity {
302 description
303 "The identity the HTTP client should use when
304 authenticating itself to the HTTP server.";
305 uses client-identity-grouping;
306 }
307 description
308 "Proxy server settings.";
309 }
310 } // grouping http-client-grouping
312 } // module ietf-http-client
314
316 4. The HTTP Server Model
318 4.1. Tree Diagram
320 This section provides a tree diagram [RFC8340] for the "ietf-http-
321 server" module.
323 module: ietf-http-server
325 grouping http-server-grouping
326 +-- server-name? string
327 +-- protocol-versions
328 | +-- protocol-version* enumeration
329 +-- client-authentication!
330 +-- (required-or-optional)
331 | +--:(required)
332 | | +-- required? empty
333 | +--:(optional)
334 | +-- optional? empty
335 +-- (local-or-external)
336 +--:(local) {local-client-auth-supported}?
337 | +-- users
338 | +-- user* [user-id]
339 | +-- user-id? string
340 | +-- (auth-type)?
341 | +--:(basic)
342 | +-- basic {basic-auth}?
343 | +-- user-id? string
344 | +-- password? ianach:crypt-hash
345 +--:(external) {external-client-auth-supported}?
346 +-- client-auth-defined-elsewhere? empty
348 4.2. Example Usage
350 This section presents an example showing the http-server-grouping
351 populated with some data.
353
354 foo.example.com
355
356 HTTP/1.1
357 HTTP/2.0
358
359
360
361
362
363
365 4.3. YANG Module
367 This YANG module has normative references to [RFC6991].
369 file "ietf-http-server@2019-11-02.yang"
370 module ietf-http-server {
371 yang-version 1.1;
372 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server";
373 prefix https;
375 import iana-crypt-hash {
376 prefix ianach;
377 reference
378 "RFC 7317: A YANG Data Model for System Management";
379 }
381 import ietf-netconf-acm {
382 prefix nacm;
383 reference
384 "RFC 8341: Network Configuration Access Control Model";
385 }
387 organization
388 "IETF NETCONF (Network Configuration) Working Group";
390 contact
391 "WG Web:
392 WG List:
393 Author: Kent Watsen ";
395 description
396 "This module defines reusable groupings for HTTP servers that
397 can be used as a basis for specific HTTP server instances.
399 Copyright (c) 2019 IETF Trust and the persons identified
400 as authors of the code. All rights reserved.
402 Redistribution and use in source and binary forms, with
403 or without modification, is permitted pursuant to, and
404 subject to the license terms contained in, the Simplified
405 BSD License set forth in Section 4.c of the IETF Trust's
406 Legal Provisions Relating to IETF Documents
407 (https://trustee.ietf.org/license-info).
409 This version of this YANG module is part of RFC XXXX
410 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
411 itself for full legal notices.;
413 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
414 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
415 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
416 are to be interpreted as described in BCP 14 (RFC 2119)
417 (RFC 8174) when, and only when, they appear in all
418 capitals, as shown here.";
420 revision 2019-11-02 {
421 description
422 "Initial version";
423 reference
424 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
425 }
427 // Features
429 feature local-client-auth-supported {
430 description
431 "Indicates that the HTTP server supports local configuration
432 of client credentials.";
433 }
435 feature external-client-auth-supported {
436 description
437 "Indicates that the HTTP server supports external configuration
438 of client credentials.";
439 }
441 feature basic-auth {
442 description
443 "The 'basic-auth' feature indicates that the server
444 may be configured authenticate users using the 'basic'
445 HTTP authentication scheme.";
446 reference
447 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
448 }
450 // Groupings
452 grouping http-server-grouping {
453 description
454 "A reusable grouping for configuring an HTTP server.
456 Note that this grouping uses fairly typical descendent
457 node names such that a stack of 'uses' statements will
458 have name conflicts. It is intended that the consuming
459 data model will resolve the issue (e.g., by wrapping
460 the 'uses' statement in a container called
461 'http-server-parameters'). This model purposely does
462 not do this itself so as to provide maximum flexibility
463 to consuming models.";
465 leaf server-name {
466 nacm:default-deny-write;
467 type string;
468 description
469 "The value of the 'Server' header field. If not set, then
470 underlying software's default value is used. Set to the
471 empty string to disable.";
472 }
474 container protocol-versions {
475 nacm:default-deny-write;
476 description
477 "A list of HTTP protocol versions supported by this
478 server.";
479 leaf-list protocol-version {
480 type enumeration {
481 enum "HTTP/1.0" {
482 description
483 "The server supports the 'HTTP/1.0' protocol.";
484 }
485 enum "HTTP/1.1" {
486 description
487 "The server supports the 'HTTP/1.1' protocol.";
488 }
489 enum "HTTP/2.0" {
490 description
491 "The server supports the 'HTTP/2.0' protocol.";
492 }
493 }
494 description
495 "An HTTP protocol version supported by this server.";
496 }
497 }
499 container client-authentication {
500 nacm:default-deny-write;
501 presence
502 "Indicates that HTTP based client authentication is
503 supported (i.e., the server will request that the
504 HTTP client send authenticate when needed). This
505 is needed as some HTTP-based protocols may only
506 support, e.g., TLS-level client authentication.";
507 description
508 "Specifies if HTTP client authentication is required or
509 optional, and specifies if the credentials needed to
510 authenticate the HTTP client are configured locally
511 or externally.";
512 choice required-or-optional {
513 mandatory true; // or default to 'required' ?
514 description
515 "Indicates if HTTP-level client authentication is required
516 or optional. This is necessary for some protocols (e.g.,
517 RESTCONF) that may optionally authenticate a client via
518 TLS-level authentication, HTTP-level authentication, or
519 both simultaneously).";
520 leaf required {
521 type empty;
522 description
523 "Indicates that HTTP-level client authentication is
524 required to access protected resources.";
525 }
526 leaf optional {
527 type empty;
528 description
529 "Indicates that HTTP-level client authentication is
530 optional to access protected resources.";
531 }
532 }
533 choice local-or-external {
534 mandatory true;
535 description
536 "Indicates if the client credentials are configured
537 locally or externally. The need to support external
538 configuration for client authentication stems from
539 the desire to support consuming data models that
540 prefer to place client authentication with client
541 definitions, rather then in a data model principally
542 concerned with configuring the transport.";
543 case local {
544 if-feature "local-client-auth-supported";
545 description
546 "Client credentials are configured locally.";
547 container users {
548 description
549 "A list of locally configured users.";
550 list user {
551 key user-id;
552 description
553 "The list of local users configured on this device.";
554 leaf user-id {
555 type string;
556 description
557 "The user-id for the authenticating client.";
558 }
559 choice auth-type {
560 description
561 "The authentication type.";
562 container basic {
563 if-feature "basic-auth";
564 leaf user-id {
565 type string;
566 description
567 "The user-id for the authenticating client.";
568 }
569 leaf password {
570 nacm:default-deny-write;
571 type ianach:crypt-hash;
572 description
573 "The password for the authenticating client.";
574 }
575 description
576 "The 'basic' HTTP scheme credentials.";
577 reference
578 "RFC 7617:
579 The 'Basic' HTTP Authentication Scheme";
580 }
581 }
582 }
583 }
584 }
585 case external {
586 if-feature "external-client-auth-supported";
587 description
588 "Client credentials are configured externally.";
589 leaf client-auth-defined-elsewhere {
590 type empty;
591 description
592 "Indicates that credentials needed to authenticate
593 clients are configured elsewhere.";
594 }
595 }
596 } // choice local-or-external
597 } // container client-authentication
599 }
600 }
602
604 5. Security Considerations
606 The YANG modules defined in this document are designed to be accessed
607 via YANG based management protocols, such as NETCONF [RFC6241] and
608 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
609 implement secure transport layers (e.g., SSH, HTTP) with mutual
610 authentication.
612 The NETCONF access control model (NACM) [RFC8341] provides the means
613 to restrict access for particular users to a pre-configured subset of
614 all available protocol operations and content.
616 Since the modules defined in this document only define groupings,
617 these considerations are primarily for the designers of other modules
618 that use these groupings.
620 There are a number of data nodes defined in the YANG modules that are
621 writable/creatable/deletable (i.e., config true, which is the
622 default). These data nodes may be considered sensitive or vulnerable
623 in some network environments. Write operations (e.g., edit-config)
624 to these data nodes without proper protection can have a negative
625 effect on network operations. These are the subtrees and data nodes
626 and their sensitivity/vulnerability:
628 FIXME: (pending - TBD)
630 Some of the readable data nodes in the YANG modules may be considered
631 sensitive or vulnerable in some network environments. It is thus
632 important to control read access (e.g., via get, get-config, or
633 notification) to these data nodes. These are the subtrees and data
634 nodes and their sensitivity/vulnerability:
636 FIXME: (pending client auth params?)
638 Some of the RPC operations in this YANG module may be considered
639 sensitive or vulnerable in some network environments. It is thus
640 important to control access to these operations. These are the
641 operations and their sensitivity/vulnerability:
643 The modules defined in this document do not define any 'RPC' or
644 'action' statements.
646 6. IANA Considerations
648 6.1. The IETF XML Registry
650 This document registers two URIs in the "ns" subregistry of the IETF
651 XML Registry [RFC3688]. Following the format in [RFC3688], the
652 following registrations are requested:
654 URI: urn:ietf:params:xml:ns:yang:ietf-http-client
655 Registrant Contact: The NETCONF WG of the IETF.
656 XML: N/A, the requested URI is an XML namespace.
658 URI: urn:ietf:params:xml:ns:yang:ietf-http-server
659 Registrant Contact: The NETCONF WG of the IETF.
660 XML: N/A, the requested URI is an XML namespace.
662 6.2. The YANG Module Names Registry
664 This document registers two YANG modules in the YANG Module Names
665 registry [RFC6020]. Following the format in [RFC6020], the following
666 registrations are requested:
668 name: ietf-http-client
669 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client
670 prefix: httpc
671 reference: RFC XXXX
673 name: ietf-http-server
674 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server
675 prefix: https
676 reference: RFC XXXX
678 7. References
680 7.1. Normative References
682 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
683 Requirement Levels", BCP 14, RFC 2119,
684 DOI 10.17487/RFC2119, March 1997,
685 .
687 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
688 the Network Configuration Protocol (NETCONF)", RFC 6020,
689 DOI 10.17487/RFC6020, October 2010,
690 .
692 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
693 RFC 6991, DOI 10.17487/RFC6991, July 2013,
694 .
696 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
697 RFC 7950, DOI 10.17487/RFC7950, August 2016,
698 .
700 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
701 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
702 May 2017, .
704 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
705 Access Control Model", STD 91, RFC 8341,
706 DOI 10.17487/RFC8341, March 2018,
707 .
709 7.2. Informative References
711 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
712 DOI 10.17487/RFC3688, January 2004,
713 .
715 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
716 and A. Bierman, Ed., "Network Configuration Protocol
717 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
718 .
720 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
721 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
722 .
724 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
725 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
726 .
728 Author's Address
730 Kent Watsen
731 Watsen Networks
733 EMail: kent+ietf@watsen.net