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