idnits 2.17.1
draft-kwatsen-netconf-http-client-server-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== The document doesn't use any RFC 2119 keywords, yet seems to have RFC
2119 boilerplate text.
-- The document date (April 7, 2019) is 1846 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 (~~), 2 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 April 7, 2019
5 Expires: October 9, 2019
7 YANG Groupings for HTTP Clients and HTTP Servers
8 draft-kwatsen-netconf-http-client-server-01
10 Abstract
12 This document defines two YANG modules: the first defines a grouping
13 for configuring a generic HTTP client, and the second defines a
14 grouping for configuring a generic HTTP server. It is intended that
15 these groupings will be used by applications using the HTTP protocol.
17 Editorial Note (To be removed by RFC Editor)
19 This draft contains many placeholder values that need to be replaced
20 with finalized values at the time of publication. This note
21 summarizes all of the substitutions that are needed. No other RFC
22 Editor instructions are specified elsewhere in this document.
24 Artwork in this document contains placeholder values for the date of
25 publication of this draft. Please apply the following replacement:
27 o "2019-04-07" --> the publication date of this draft
29 The following Appendix section is to be removed prior to publication:
31 o Appendix A. Change Log
33 Status of This Memo
35 This Internet-Draft is submitted in full conformance with the
36 provisions of BCP 78 and BCP 79.
38 Internet-Drafts are working documents of the Internet Engineering
39 Task Force (IETF). Note that other groups may also distribute
40 working documents as Internet-Drafts. The list of current Internet-
41 Drafts is at https://datatracker.ietf.org/drafts/current/.
43 Internet-Drafts are draft documents valid for a maximum of six months
44 and may be updated, replaced, or obsoleted by other documents at any
45 time. It is inappropriate to use Internet-Drafts as reference
46 material or to cite them other than as "work in progress."
48 This Internet-Draft will expire on October 9, 2019.
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 . . . . . . . . . . . . . . . . . . . . . . 4
72 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 5
73 4. The HTTP Server Model . . . . . . . . . . . . . . . . . . . . 11
74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 11
75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 11
76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 12
77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14
78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 15
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 applications using
92 the HTTP protocol.
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 http-client-grouping
112 +-- http-client-parameters
113 +-- protocol-version? enumeration
114 +-- client-identity
115 | +-- (auth-type)?
116 | +--:(basic)
117 | | +-- basic {basic-auth}?
118 | | +-- user-id? string
119 | | +-- password? string
120 | +--:(bearer)
121 | | +-- bearer {bearer-auth}?
122 | | +-- token? string
123 | +--:(digest)
124 | | +-- digest {digest-auth}?
125 | | +-- username? string
126 | | +-- password? string
127 | +--:(hoba)
128 | | +-- hoba {hoba-auth}?
129 | +--:(mutual)
130 | | +-- mutual {mutual-auth}?
131 | +--:(negotiate)
132 | | +-- negotiate {negotiate-auth}?
133 | +--:(oauth)
134 | | +-- oauth {oauth-auth}?
135 | +--:(scram-sha-1)
136 | | +-- scram-sha-1 {scram-sha-1-auth}?
137 | +--:(scram-sha-256)
138 | | +-- scram-sha-256 {scram-sha-256-auth}?
139 | +--:(vapid)
140 | +-- vapid {vapid-auth}?
141 +-- proxy-server! {proxy-connect}?
142 +---u tcpc:tcp-client-grouping
143 +---u tlsc:tls-client-grouping
144 +-- proxy-client-identity
145 +-- user-id? string
146 +-- password? string
148 3.2. Example Usage
150 This section presents an example showing the http-client-grouping
151 populated with some data.
153
154
155 HTTP/1.1
156
157
158 bob
159 secret
160
161
162
163
165 3.3. YANG Module
167 This YANG module has normative references to [RFC6991].
169 file "ietf-http-client@2019-04-07.yang"
170 module ietf-http-client {
171 yang-version 1.1;
172 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client";
173 prefix httpc;
175 import ietf-tcp-client {
176 prefix tcpc;
177 reference
178 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers";
179 }
181 import ietf-tls-client {
182 prefix tlsc;
183 reference
184 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers";
185 }
187 organization
188 "IETF NETCONF (Network Configuration) Working Group";
190 contact
191 "WG Web:
192 WG List:
193 Author: Kent Watsen ";
195 description
196 "This module defines reusable groupings for HTTP clients that
197 can be used as a basis for specific HTTP client instances.
199 Copyright (c) 2019 IETF Trust and the persons identified
200 as authors of the code. All rights reserved.
202 Redistribution and use in source and binary forms, with
203 or without modification, is permitted pursuant to, and
204 subject to the license terms contained in, the Simplified
205 BSD License set forth in Section 4.c of the IETF Trust's
206 Legal Provisions Relating to IETF Documents
207 (https://trustee.ietf.org/license-info).
209 This version of this YANG module is part of RFC XXXX
210 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
211 itself for full legal notices.;
213 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
214 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
215 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
216 are to be interpreted as described in BCP 14 (RFC 2119)
217 (RFC 8174) when, and only when, they appear in all
218 capitals, as shown here.";
220 revision 2019-04-07 {
221 description
222 "Initial version";
223 reference
224 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
225 }
227 // Features
229 feature proxy-connect {
230 description
231 "Proxy connection configuration is configurable for
232 HTTP clients on the server implementing this feature.";
233 }
235 feature basic-auth {
236 description
237 "fixme";
238 }
240 feature bearer-auth {
241 description
242 "fixme";
243 }
245 feature digest-auth {
246 description
247 "fixme";
248 }
249 feature hoba-auth {
250 description
251 "fixme";
252 }
254 feature mutual-auth {
255 description
256 "fixme";
257 }
259 feature negotiate-auth {
260 description
261 "fixme";
262 }
264 feature oauth-auth {
265 description
266 "fixme";
267 }
269 feature scram-sha-1-auth {
270 description
271 "fixme";
272 }
274 feature scram-sha-256-auth {
275 description
276 "fixme";
277 }
279 feature vapid-auth {
280 description
281 "fixme";
282 }
284 // Groupings
286 grouping http-client-grouping {
287 description
288 "A reusable grouping for configuring a HTTP client,
289 including the IP address and port number it initiates
290 a connections to.";
292 container http-client-parameters {
293 description
294 "A container to hold HTTP client configuration. As HTTP
295 clients vary wildly, it is expected that this container
296 will be augmented by application-level modules as needed.";
298 leaf protocol-version {
299 type enumeration {
300 enum HTTP/1.0 {
301 description
302 "The client should use the 'HTTP/1.0' protocol.";
303 }
304 enum HTTP/1.1 {
305 description
306 "The client should use the 'HTTP/1.1' protocol.";
307 }
308 enum HTTP/2.0 {
309 description
310 "The client should use the 'HTTP/2.0' protocol.";
311 }
312 }
313 description
314 "The HTTP protocol version the client should use.";
315 } // leaf protocol-version
317 container client-identity {
318 description
319 "The credentials used by the client to authenticate to
320 the HTTP server.";
321 choice auth-type {
322 description
323 "The authentication type.";
324 container basic {
325 if-feature "basic-auth";
326 leaf user-id {
327 type string;
328 description
329 "The user-id for the authenticating client.";
330 }
331 leaf password {
332 type string;
333 description
334 "The password for the authenticating client.";
335 }
336 description
337 "The 'basic' HTTP scheme credentials.";
338 reference
339 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
340 }
341 container bearer {
342 if-feature "bearer-auth";
343 leaf token {
344 type string;
345 description
346 "The bearer token for the authenticating client,
347 encoded in base64, as described in RFC 6750,
348 Section 2.1.";
349 }
350 description
351 "The 'bearer' HTTP scheme credentials.";
352 reference
353 "RFC 6750: The OAuth 2.0 Authorization Framework:
354 Bearer Token Usage";
355 }
356 container digest {
357 if-feature "digest-auth";
358 leaf username {
359 type string;
360 description
361 "The username for the authenticating client.";
362 }
363 leaf password {
364 type string;
365 description
366 "The password for the authenticating client.";
367 }
368 description
369 "The 'digest' HTTP scheme credentials.";
370 reference
371 "RFC 7616: HTTP Digest Access Authentication";
372 }
373 container hoba {
374 if-feature "hoba-auth";
375 // FIXME
376 description
377 "The 'hoba' HTTP scheme credentials.";
378 reference
379 "RFC 7486: HTTP Origin-Bound Authentication (HOBA)";
380 }
381 container mutual {
382 if-feature "mutual-auth";
383 // FIXME
384 description
385 "The 'mutual' HTTP scheme credentials.";
386 reference
387 "RFC 8120: Mutual Authentication Protocol for HTTP";
388 }
389 container negotiate {
390 if-feature "negotiate-auth";
391 // FIXME
392 description
393 "The 'negotiate' HTTP scheme credentials.";
395 reference
396 "RFC 4559: SPNEGO-based Kerberos and NTLM HTTP
397 Authentication in Microsoft Windows";
398 }
399 container oauth {
400 if-feature "oauth-auth";
401 // FIXME
402 description
403 "The 'oauth' HTTP scheme credentials.";
404 reference
405 "RFC 6749: The OAuth 2.0 Authorization Framework";
406 }
407 container scram-sha-1 {
408 if-feature "scram-sha-1-auth";
409 // FIXME
410 description
411 "The 'scram-sha-1' HTTP scheme credentials.";
412 reference
413 "RFC 7804: Salted Challenge Response HTTP
414 Authentication Mechanism";
415 }
416 container scram-sha-256 {
417 if-feature "scram-sha-256-auth";
418 // FIXME
419 description
420 "The 'scram-sha-256' HTTP scheme credentials.";
421 reference
422 "RFC 7804: Salted Challenge Response HTTP
423 Authentication Mechanism";
424 }
425 container vapid {
426 if-feature "vapid-auth";
427 // FIXME
428 description
429 "The 'vapid' HTTP scheme credentials.";
430 reference
431 "RFC 8292: Voluntary Application Server
432 Identification (VAPID) for Web Push";
433 }
434 }
435 } // container client-identity
437 container proxy-server {
438 if-feature "proxy-connect";
439 presence true; // only so ex-http-client can pass validation?
440 uses "tcpc:tcp-client-grouping";
441 uses "tlsc:tls-client-grouping";
442 container proxy-client-identity {
443 leaf user-id {
444 type string;
445 description
446 "The user-id for the authenticating client.";
447 }
448 leaf password {
449 type string;
450 description
451 "The password for the authenticating client.";
452 }
453 description
454 "The 'basic' HTTP scheme credentials.";
455 reference
456 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
457 }
458 description
459 "Proxy server settings.";
460 } // container proxy-server
461 } // container http-client-parameters
462 } //grouping http-client-grouping
463 }
464
466 4. The HTTP Server Model
468 4.1. Tree Diagram
470 This section provides a tree diagram [RFC8340] for the "ietf-http-
471 server" module.
473 module: ietf-http-server
475 grouping http-server-grouping
476 +-- http-server-parameters
477 +-- server-name? string
478 +-- protocol-versions
479 +-- protocol-version* enumeration
481 4.2. Example Usage
483 This section presents an example showing the http-server-grouping
484 populated with some data.
486
487
488 foo.example.com
489
490 HTTP/1.1
491 HTTP/2.0
492
493
494
496 4.3. YANG Module
498 This YANG module has normative references to [RFC6991].
500 file "ietf-http-server@2019-04-07.yang"
501 module ietf-http-server {
502 yang-version 1.1;
503 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server";
504 prefix https;
506 organization
507 "IETF NETCONF (Network Configuration) Working Group";
509 contact
510 "WG Web:
511 WG List:
512 Author: Kent Watsen ";
514 description
515 "This module defines reusable groupings for HTTP servers that
516 can be used as a basis for specific HTTP server instances.
518 Copyright (c) 2019 IETF Trust and the persons identified
519 as authors of the code. All rights reserved.
521 Redistribution and use in source and binary forms, with
522 or without modification, is permitted pursuant to, and
523 subject to the license terms contained in, the Simplified
524 BSD License set forth in Section 4.c of the IETF Trust's
525 Legal Provisions Relating to IETF Documents
526 (https://trustee.ietf.org/license-info).
528 This version of this YANG module is part of RFC XXXX
529 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC
530 itself for full legal notices.;
532 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
533 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
534 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
535 are to be interpreted as described in BCP 14 (RFC 2119)
536 (RFC 8174) when, and only when, they appear in all
537 capitals, as shown here.";
539 revision 2019-04-07 {
540 description
541 "Initial version";
542 reference
543 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
544 }
546 // Groupings
548 grouping http-server-grouping {
549 description
550 "A reusable grouping for configuring an HTTP server.";
552 container http-server-parameters {
553 description
554 "A container that holds HTTP server configuration. As HTTP
555 servers vary wildly, it is expected that this container will
556 be augmented by application-level modules as needed.";
558 leaf server-name {
559 type string;
560 description
561 "The value of the 'Server' header field. If not set, then
562 underlying software's default value is used. Set to the
563 empty string to disable.";
564 }
566 container protocol-versions {
567 description
568 "A list of HTTP protocol versions supported by this
569 server.";
570 leaf-list protocol-version {
571 type enumeration {
572 enum "HTTP/1.0" {
573 description
574 "The server supports the 'HTTP/1.0' protocol.";
575 }
576 enum "HTTP/1.1" {
577 description
578 "The server supports the 'HTTP/1.1' protocol.";
579 }
580 enum "HTTP/2.0" {
581 description
582 "The server supports the 'HTTP/2.0' protocol.";
583 }
584 }
585 description
586 "An HTTP protocol version supported by this server.";
587 }
588 }
589 }
590 }
591 }
592
594 5. Security Considerations
596 The YANG modules defined in this document are designed to be accessed
597 via YANG based management protocols, such as NETCONF [RFC6241] and
598 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
599 implement secure transport layers (e.g., SSH, HTTP) with mutual
600 authentication.
602 The NETCONF access control model (NACM) [RFC8341] provides the means
603 to restrict access for particular users to a pre-configured subset of
604 all available protocol operations and content.
606 Since the modules defined in this document only define groupings,
607 these considerations are primarily for the designers of other modules
608 that use these groupings.
610 There are a number of data nodes defined in the YANG modules that are
611 writable/creatable/deletable (i.e., config true, which is the
612 default). These data nodes may be considered sensitive or vulnerable
613 in some network environments. Write operations (e.g., edit-config)
614 to these data nodes without proper protection can have a negative
615 effect on network operations. These are the subtrees and data nodes
616 and their sensitivity/vulnerability:
618 FIXME: (pending - TBD)
620 Some of the readable data nodes in the YANG modules may be considered
621 sensitive or vulnerable in some network environments. It is thus
622 important to control read access (e.g., via get, get-config, or
623 notification) to these data nodes. These are the subtrees and data
624 nodes and their sensitivity/vulnerability:
626 FIXME: (pending client auth params?)
628 Some of the RPC operations in this YANG module may be considered
629 sensitive or vulnerable in some network environments. It is thus
630 important to control access to these operations. These are the
631 operations and their sensitivity/vulnerability:
633 The modules defined in this document do not define any 'RPC' or
634 'action' statements.
636 6. IANA Considerations
638 6.1. The IETF XML Registry
640 This document registers two URIs in the "ns" subregistry of the IETF
641 XML Registry [RFC3688]. Following the format in [RFC3688], the
642 following registrations are requested:
644 URI: urn:ietf:params:xml:ns:yang:ietf-http-client
645 Registrant Contact: The NETCONF WG of the IETF.
646 XML: N/A, the requested URI is an XML namespace.
648 URI: urn:ietf:params:xml:ns:yang:ietf-http-server
649 Registrant Contact: The NETCONF WG of the IETF.
650 XML: N/A, the requested URI is an XML namespace.
652 6.2. The YANG Module Names Registry
654 This document registers two YANG modules in the YANG Module Names
655 registry [RFC6020]. Following the format in [RFC6020], the following
656 registrations are requested:
658 name: ietf-http-client
659 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client
660 prefix: httpc
661 reference: RFC XXXX
663 name: ietf-http-server
664 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server
665 prefix: https
666 reference: RFC XXXX
668 7. References
670 7.1. Normative References
672 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
673 Requirement Levels", BCP 14, RFC 2119,
674 DOI 10.17487/RFC2119, March 1997,
675 .
677 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
678 the Network Configuration Protocol (NETCONF)", RFC 6020,
679 DOI 10.17487/RFC6020, October 2010,
680 .
682 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
683 RFC 6991, DOI 10.17487/RFC6991, July 2013,
684 .
686 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
687 RFC 7950, DOI 10.17487/RFC7950, August 2016,
688 .
690 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
691 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
692 May 2017, .
694 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
695 Access Control Model", STD 91, RFC 8341,
696 DOI 10.17487/RFC8341, March 2018,
697 .
699 7.2. Informative References
701 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
702 DOI 10.17487/RFC3688, January 2004,
703 .
705 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
706 and A. Bierman, Ed., "Network Configuration Protocol
707 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
708 .
710 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
711 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
712 .
714 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
715 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
716 .
718 Author's Address
720 Kent Watsen
721 Watsen Networks
723 EMail: kent+ietf@watsen.net