idnits 2.17.1
draft-kwatsen-netconf-http-client-server-00.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 (March 9, 2019) is 1874 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 March 9, 2019
5 Expires: September 10, 2019
7 YANG Groupings for HTTP Clients and HTTP Servers
8 draft-kwatsen-netconf-http-client-server-00
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-03-09" --> 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 September 10, 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 . . . . . . . . . . . . . . . . . . . . 9
74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 9
75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 10
76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10
77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 13
80 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 13
81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
82 7.1. Normative References . . . . . . . . . . . . . . . . . . 14
83 7.2. Informative References . . . . . . . . . . . . . . . . . 14
84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15
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. For instance, these groupings could help define
93 the configuration module for an SSH, TLS, or HTTP based application.
95 2. Terminology
97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
99 "OPTIONAL" in this document are to be interpreted as described in BCP
100 14 [RFC2119] [RFC8174] when, and only when, they appear in all
101 capitals, as shown here.
103 3. The HTTP Client Model
105 3.1. Tree Diagram
107 This section provides a tree diagram [RFC8340] for the "ietf-http-
108 client" module.
110 module: ietf-http-client
112 grouping http-client-grouping
113 +-- http-client-identity
114 | +-- (auth-type)?
115 | +--:(basic)
116 | | +-- basic
117 | | +-- user-id? string
118 | | +-- password? string
119 | +--:(bearer)
120 | | +-- bearer
121 | | +-- token? string
122 | +--:(digest)
123 | | +-- digest
124 | | +-- username? string
125 | | +-- password? string
126 | +--:(hoba)
127 | | +-- hoba
128 | +--:(mutual)
129 | | +-- mutual
130 | +--:(negotiate)
131 | | +-- negotiate
132 | +--:(oauth)
133 | | +-- oauth
134 | +--:(scram-sha-1)
135 | | +-- scram-sha-1
136 | +--:(scram-sha-256)
137 | | +-- scram-sha-256
138 | +--:(vapid)
139 | +-- vapid
140 +-- http-keepalives {http-client-keepalives}?
141 +-- max-wait? uint16
142 +-- max-attempts? uint8
144 grouping http-client-identity-grouping
145 +-- http-client-identity
146 +-- (auth-type)?
147 +--:(basic)
148 | +-- basic
149 | +-- user-id? string
150 | +-- password? string
151 +--:(bearer)
152 | +-- bearer
153 | +-- token? string
154 +--:(digest)
155 | +-- digest
156 | +-- username? string
157 | +-- password? string
158 +--:(hoba)
159 | +-- hoba
160 +--:(mutual)
161 | +-- mutual
162 +--:(negotiate)
163 | +-- negotiate
164 +--:(oauth)
165 | +-- oauth
166 +--:(scram-sha-1)
167 | +-- scram-sha-1
168 +--:(scram-sha-256)
169 | +-- scram-sha-256
170 +--:(vapid)
171 +-- vapid
172 grouping http-keepalives-grouping
173 +-- http-keepalives {http-client-keepalives}?
174 +-- max-wait? uint16
175 +-- max-attempts? uint8
177 3.2. Example Usage
179 This section presents an example showing the http-client-grouping
180 populated with some data.
182
183
184
185 bob
186 secret
187
188
189
190 30
191 3
192
193
195 3.3. YANG Module
197 This YANG module has normative references to [RFC6991].
199 file "ietf-http-client@2019-03-09.yang"
200 module ietf-http-client {
201 yang-version 1.1;
202 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client";
203 prefix httpc;
205 organization
206 "IETF NETCONF (Network Configuration) Working Group";
207 contact
208 "WG Web:
209 WG List:
210 Author: Kent Watsen ";
211 description
212 "This module defines reusable groupings for HTTP clients that
213 can be used as a basis for specific HTTP client instances.
215 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
216 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
217 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
218 are to be interpreted as described in BCP 14 [RFC2119]
219 [RFC8174] when, and only when, they appear in all
220 capitals, as shown here.
222 Copyright (c) 2019 IETF Trust and the persons identified as
223 authors of the code. All rights reserved.
225 Redistribution and use in source and binary forms, with or
226 without modification, is permitted pursuant to, and subject
227 to the license terms contained in, the Simplified BSD
228 License set forth in Section 4.c of the IETF Trust's
229 Legal Provisions Relating to IETF Documents
230 (http://trustee.ietf.org/license-info).
232 This version of this YANG module is part of RFC XXXX; see
233 the RFC itself for full legal notices.";
235 revision 2019-03-09 {
236 description
237 "Initial version";
238 reference
239 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
240 }
242 // Features
244 feature http-client-keepalives {
245 description
246 "Per socket HTTP keepalive parameters are configurable for
247 HTTP clients on the server implementing this feature.";
248 }
250 // Groupings
252 grouping http-client-grouping {
253 description
254 "A reusable grouping for configuring a HTTP client,
255 including the IP address and port number it initiates
256 a connections to.";
257 uses http-client-identity-grouping;
258 uses http-keepalives-grouping;
259 // uses http-proxy-grouping;
260 }
262 grouping http-client-identity-grouping {
263 description
264 "A reusable grouping for configuring a HTTP client identity.";
265 container http-client-identity {
266 description
267 "The credentials used by the client to authenticate to
268 the HTTP server.";
269 choice auth-type {
270 description
271 "The authentication type.";
272 container basic {
273 leaf user-id {
274 type string;
275 description
276 "The user-id for the authenticating client.";
277 }
278 leaf password {
279 type string;
280 description
281 "The password for the authenticating client.";
282 }
283 description
284 "The 'basic' HTTP scheme credentials.";
285 reference
286 "RFC 7617: The 'Basic' HTTP Authentication Scheme";
287 }
288 container bearer {
289 leaf token {
290 type string;
291 description
292 "The bearer token for the authenticating client,
293 encoded in base64, as described in RFC 6750,
294 Section 2.1.";
295 }
296 description
297 "The 'bearer' HTTP scheme credentials.";
298 reference
299 "RFC 6750: The OAuth 2.0 Authorization Framework:
300 Bearer Token Usage";
301 }
302 container digest {
303 leaf username {
304 type string;
305 description
306 "The username for the authenticating client.";
307 }
308 leaf password {
309 type string;
310 description
311 "The password for the authenticating client.";
312 }
313 description
314 "The 'digest' HTTP scheme credentials.";
315 reference
316 "RFC 7616: HTTP Digest Access Authentication";
317 }
318 container hoba {
319 // FIXME
320 description
321 "The 'hoba' HTTP scheme credentials.";
322 reference
323 "RFC 7486: HTTP Origin-Bound Authentication (HOBA)";
324 }
325 container mutual {
326 // FIXME
327 description
328 "The 'mutual' HTTP scheme credentials.";
329 reference
330 "RFC 8120: Mutual Authentication Protocol for HTTP";
331 }
332 container negotiate {
333 // FIXME
334 description
335 "The 'negotiate' HTTP scheme credentials.";
336 reference
337 "RFC 4559: SPNEGO-based Kerberos and NTLM HTTP
338 Authentication in Microsoft Windows";
339 }
340 container oauth {
341 // FIXME
342 description
343 "The 'oauth' HTTP scheme credentials.";
344 reference
345 "RFC 6749: The OAuth 2.0 Authorization Framework";
346 }
347 container scram-sha-1 {
348 // FIXME
349 description
350 "The 'scram-sha-1' HTTP scheme credentials.";
351 reference
352 "RFC 7804: Salted Challenge Response HTTP
353 Authentication Mechanism";
354 }
355 container scram-sha-256 {
356 // FIXME
357 description
358 "The 'scram-sha-256' HTTP scheme credentials.";
359 reference
360 "RFC 7804: Salted Challenge Response HTTP
361 Authentication Mechanism";
362 }
363 container vapid {
364 // FIXME
365 description
366 "The 'vapid' HTTP scheme credentials.";
367 reference
368 "RFC 8292: Voluntary Application Server
369 Identification (VAPID) for Web Push";
370 }
371 }
372 }
373 }
374 grouping http-keepalives-grouping {
375 description
376 "A reusable grouping for configuring HTTP client keepalive
377 parameters.";
378 container http-keepalives {
379 if-feature "http-client-keepalives";
380 description
381 "Configures the keep-alive policy, to proactively test
382 the aliveness of the HTTP server. An unresponsive
383 HTTP server is dropped after approximately max-wait
384 * max-attempts seconds.";
385 leaf max-wait {
386 type uint16 {
387 range "1..max";
388 }
389 units "seconds";
390 default "30";
391 description
392 "Sets the amount of time in seconds after which if no
393 data has been received from the HTTP server, a HTTP
394 level message will be sent to test the aliveness of
395 the HTTP server.";
396 }
397 leaf max-attempts {
398 type uint8;
399 default "3";
400 description
401 "Sets the maximum number of sequential keep-alive messages
402 that can fail to obtain a response from the HTTP server
403 before assuming the HTTP server is no longer alive.";
404 }
405 }
406 }
407 }
408
410 4. The HTTP Server Model
412 4.1. Tree Diagram
414 This section provides a tree diagram [RFC8340] for the "ietf-http-
415 server" module.
417 module: ietf-http-server
419 grouping http-server-grouping
420 +-- http-keepalives {http-server-keepalives}?
421 +-- max-wait? uint16
422 +-- max-attempts? uint8
423 grouping keepalives-grouping
424 +-- http-keepalives {http-server-keepalives}?
425 +-- max-wait? uint16
426 +-- max-attempts? uint8
428 4.2. Example Usage
430 This section presents an example showing the http-server-grouping
431 populated with some data.
433
434
435 30
436 3
437
438
440 4.3. YANG Module
442 This YANG module has normative references to [RFC6991].
444 file "ietf-http-server@2019-03-09.yang"
445 module ietf-http-server {
446 yang-version 1.1;
447 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server";
448 prefix https;
450 organization
451 "IETF NETCONF (Network Configuration) Working Group";
452 contact
453 "WG Web:
454 WG List:
455 Author: Kent Watsen ";
456 description
457 "This module defines reusable groupings for HTTP servers that
458 can be used as a basis for specific HTTP server instances.
460 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
461 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
462 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
463 are to be interpreted as described in BCP 14 [RFC2119]
464 [RFC8174] when, and only when, they appear in all
465 capitals, as shown here.
467 Copyright (c) 2019 IETF Trust and the persons identified as
468 authors of the code. All rights reserved.
470 Redistribution and use in source and binary forms, with or
471 without modification, is permitted pursuant to, and subject
472 to the license terms contained in, the Simplified BSD
473 License set forth in Section 4.c of the IETF Trust's
474 Legal Provisions Relating to IETF Documents
475 (http://trustee.ietf.org/license-info).
477 This version of this YANG module is part of RFC XXXX; see
478 the RFC itself for full legal notices.";
480 revision 2019-03-09 {
481 description
482 "Initial version";
483 reference
484 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers";
485 }
487 // Features
489 feature http-server-keepalives {
490 description
491 "Per socket HTTP keepalive parameters are configurable for
492 HTTP servers on the server implementing this feature.";
493 }
495 // Groupings
497 grouping http-server-grouping {
498 description
499 "A reusable grouping for configuring a HTTP server,
500 including the IP address and port number it listens
501 for connections on.";
502 uses keepalives-grouping;
503 }
505 grouping keepalives-grouping {
506 description
507 "A reusable grouping for configuring HTTP server keepalive
508 parameters.";
509 container http-keepalives {
510 if-feature "http-server-keepalives";
511 description
512 "Configures the keep-alive policy, to proactively test
513 the aliveness of the HTTP client. An unresponsive
514 HTTP client is dropped after approximately max-wait
515 * max-attempts seconds.";
516 leaf max-wait {
517 type uint16 {
518 range "1..max";
519 }
520 units "seconds";
521 default "30";
522 description
523 "Sets the amount of time in seconds after which if no
524 data has been received from the HTTP client, a HTTP
525 level message will be sent to test the aliveness of
526 the HTTP client.";
527 }
528 leaf max-attempts {
529 type uint8;
530 default "3";
531 description
532 "Sets the maximum number of sequential keep-alive messages
533 that can fail to obtain a response from the HTTP client
534 before assuming the HTTP client is no longer alive.";
535 }
536 }
537 }
538 }
539
541 5. Security Considerations
543 The YANG modules defined in this document are designed to be accessed
544 via YANG based management protocols, such as NETCONF [RFC6241] and
545 RESTCONF [RFC8040]. Both of these protocols have mandatory-to-
546 implement secure transport layers (e.g., SSH, HTTP) with mutual
547 authentication.
549 The NETCONF access control model (NACM) [RFC8341] provides the means
550 to restrict access for particular users to a pre-configured subset of
551 all available protocol operations and content.
553 Since the modules defined in this document only define groupings,
554 these considerations are primarily for the designers of other modules
555 that use these groupings.
557 There are a number of data nodes defined in the YANG modules that are
558 writable/creatable/deletable (i.e., config true, which is the
559 default). These data nodes may be considered sensitive or vulnerable
560 in some network environments. Write operations (e.g., edit-config)
561 to these data nodes without proper protection can have a negative
562 effect on network operations. These are the subtrees and data nodes
563 and their sensitivity/vulnerability:
565 NONE
567 Some of the readable data nodes in the YANG modules may be considered
568 sensitive or vulnerable in some network environments. It is thus
569 important to control read access (e.g., via get, get-config, or
570 notification) to these data nodes. These are the subtrees and data
571 nodes and their sensitivity/vulnerability:
573 NONE
575 Some of the RPC operations in this YANG module may be considered
576 sensitive or vulnerable in some network environments. It is thus
577 important to control access to these operations. These are the
578 operations and their sensitivity/vulnerability:
580 NONE
582 6. IANA Considerations
584 6.1. The IETF XML Registry
586 This document registers two URIs in the "ns" subregistry of the IETF
587 XML Registry [RFC3688]. Following the format in [RFC3688], the
588 following registrations are requested:
590 URI: urn:ietf:params:xml:ns:yang:ietf-http-client
591 Registrant Contact: The NETCONF WG of the IETF.
592 XML: N/A, the requested URI is an XML namespace.
594 URI: urn:ietf:params:xml:ns:yang:ietf-http-server
595 Registrant Contact: The NETCONF WG of the IETF.
596 XML: N/A, the requested URI is an XML namespace.
598 6.2. The YANG Module Names Registry
600 This document registers two YANG modules in the YANG Module Names
601 registry [RFC6020]. Following the format in [RFC6020], the following
602 registrations are requested:
604 name: ietf-http-client
605 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client
606 prefix: httpc
607 reference: RFC XXXX
609 name: ietf-http-server
610 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server
611 prefix: https
612 reference: RFC XXXX
614 7. References
616 7.1. Normative References
618 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
619 Requirement Levels", BCP 14, RFC 2119,
620 DOI 10.17487/RFC2119, March 1997,
621 .
623 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
624 the Network Configuration Protocol (NETCONF)", RFC 6020,
625 DOI 10.17487/RFC6020, October 2010,
626 .
628 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
629 RFC 6991, DOI 10.17487/RFC6991, July 2013,
630 .
632 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
633 RFC 7950, DOI 10.17487/RFC7950, August 2016,
634 .
636 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
637 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
638 May 2017, .
640 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
641 Access Control Model", STD 91, RFC 8341,
642 DOI 10.17487/RFC8341, March 2018,
643 .
645 7.2. Informative References
647 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
648 DOI 10.17487/RFC3688, January 2004,
649 .
651 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
652 and A. Bierman, Ed., "Network Configuration Protocol
653 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
654 .
656 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
657 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
658 .
660 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
661 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
662 .
664 Author's Address
666 Kent Watsen
667 Watsen Networks
669 EMail: kent+ietf@watsen.net