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