idnits 2.17.1 draft-ietf-netconf-http-client-server-07.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 date (18 May 2021) is 1074 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) == Outdated reference: A later version (-34) exists of draft-ietf-netconf-crypto-types-19 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-06 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-22 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-22 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-23 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-09 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-23 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-14 Summary: 0 errors (**), 0 flaws (~~), 10 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 18 May 2021 5 Expires: 19 November 2021 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-07 10 Abstract 12 This document defines two YANG modules: the first defines a minimal 13 grouping for configuring an HTTP client, and the second defines a 14 minimal grouping for configuring an HTTP server. It is intended that 15 these groupings will be used to help define the configuration for 16 simple HTTP-based protocols (not for complete web servers or 17 browsers). 19 Editorial Note (To be removed by RFC Editor) 21 This draft contains placeholder values that need to be replaced with 22 finalized values at the time of publication. This note summarizes 23 all of the substitutions that are needed. No other RFC Editor 24 instructions are specified elsewhere in this document. 26 Artwork in this document contains shorthand references to drafts in 27 progress. Please apply the following replacements (note: not all may 28 be present): 30 * "AAAA" --> the assigned RFC value for draft-ietf-netconf-crypto- 31 types 33 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 34 client-server 36 * "FFFF" --> the assigned RFC value for draft-ietf-netconf-tls- 37 client-server 39 * "GGGG" --> the assigned RFC value for this draft 41 Artwork in this document contains placeholder values for the date of 42 publication of this draft. Please apply the following replacement: 44 * "2021-05-18" --> the publication date of this draft 46 The following Appendix section is to be removed prior to publication: 48 * Appendix A. Change Log 50 Status of This Memo 52 This Internet-Draft is submitted in full conformance with the 53 provisions of BCP 78 and BCP 79. 55 Internet-Drafts are working documents of the Internet Engineering 56 Task Force (IETF). Note that other groups may also distribute 57 working documents as Internet-Drafts. The list of current Internet- 58 Drafts is at https://datatracker.ietf.org/drafts/current/. 60 Internet-Drafts are draft documents valid for a maximum of six months 61 and may be updated, replaced, or obsoleted by other documents at any 62 time. It is inappropriate to use Internet-Drafts as reference 63 material or to cite them other than as "work in progress." 65 This Internet-Draft will expire on 19 November 2021. 67 Copyright Notice 69 Copyright (c) 2021 IETF Trust and the persons identified as the 70 document authors. All rights reserved. 72 This document is subject to BCP 78 and the IETF Trust's Legal 73 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 74 license-info) in effect on the date of publication of this document. 75 Please review these documents carefully, as they describe your rights 76 and restrictions with respect to this document. Code Components 77 extracted from this document must include Simplified BSD License text 78 as described in Section 4.e of the Trust Legal Provisions and are 79 provided without warranty as described in the Simplified BSD License. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 84 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 3 85 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 86 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 87 2. The "ietf-http-client" Module . . . . . . . . . . . . . . . . 5 88 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 5 89 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 90 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 91 3. The "ietf-http-server" Module . . . . . . . . . . . . . . . . 16 92 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 16 93 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18 94 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 95 4. Security Considerations . . . . . . . . . . . . . . . . . . . 24 96 4.1. The "ietf-http-client" YANG Module . . . . . . . . . . . 24 97 4.2. The "ietf-http-server" YANG Module . . . . . . . . . . . 25 99 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 100 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 26 101 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 26 102 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 103 6.1. Normative References . . . . . . . . . . . . . . . . . . 26 104 6.2. Informative References . . . . . . . . . . . . . . . . . 27 105 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 29 106 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 29 107 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 29 108 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 29 109 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 30 110 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 30 111 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 30 112 A.7. 06 to 07 . . . . . . . . . . . . . . . . . . . . . . . . 30 113 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 114 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31 116 1. Introduction 118 This document defines two YANG 1.1 [RFC7950] modules: the first 119 defines a minimal grouping for configuring an HTTP client, and the 120 second defines a minimal grouping for configuring an HTTP server. It 121 is intended that these groupings will be used to help define the 122 configuration for simple HTTP-based protocols (not for complete web 123 servers or browsers). 125 1.1. Relation to other RFCs 127 This document presents one or more YANG modules [RFC7950] that are 128 part of a collection of RFCs that work together to, ultimately, 129 enable the configuration of the clients and servers of both the 130 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 132 The modules have been defined in a modular fashion to enable their 133 use by other efforts, some of which are known to be in progress at 134 the time of this writing, with many more expected to be defined in 135 time. 137 The normative dependency relationship between the various RFCs in the 138 collection is presented in the below diagram. The labels in the 139 diagram represent the primary purpose provided by each RFC. 140 Hyperlinks to each RFC are provided below the diagram. 142 crypto-types 143 ^ ^ 144 / \ 145 / \ 146 truststore keystore 147 ^ ^ ^ ^ 148 | +---------+ | | 149 | | | | 150 | +------------+ | 151 tcp-client-server | / | | 152 ^ ^ ssh-client-server | | 153 | | ^ tls-client-server 154 | | | ^ ^ http-client-server 155 | | | | | ^ 156 | | | +-----+ +---------+ | 157 | | | | | | 158 | +-----------|--------|--------------+ | | 159 | | | | | | 160 +-----------+ | | | | | 161 | | | | | | 162 | | | | | | 163 netconf-client-server restconf-client-server 165 +=======================+===========================================+ 166 |Label in Diagram | Originating RFC | 167 +=======================+===========================================+ 168 |crypto-types | [I-D.ietf-netconf-crypto-types] | 169 +-----------------------+-------------------------------------------+ 170 |truststore | [I-D.ietf-netconf-trust-anchors] | 171 +-----------------------+-------------------------------------------+ 172 |keystore | [I-D.ietf-netconf-keystore] | 173 +-----------------------+-------------------------------------------+ 174 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 175 +-----------------------+-------------------------------------------+ 176 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 177 +-----------------------+-------------------------------------------+ 178 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 179 +-----------------------+-------------------------------------------+ 180 |http-client-server | [I-D.ietf-netconf-http-client-server] | 181 +-----------------------+-------------------------------------------+ 182 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 183 +-----------------------+-------------------------------------------+ 184 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 185 +-----------------------+-------------------------------------------+ 187 Table 1: Label to RFC Mapping 189 1.2. Specification Language 191 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 192 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 193 "OPTIONAL" in this document are to be interpreted as described in BCP 194 14 [RFC2119] [RFC8174] when, and only when, they appear in all 195 capitals, as shown here. 197 1.3. Adherence to the NMDA 199 This document is compliant with the Network Management Datastore 200 Architecture (NMDA) [RFC8342]. For instance, as described in 201 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 202 trust anchors and keys installed during manufacturing are expected to 203 appear in . 205 2. The "ietf-http-client" Module 207 This section defines a YANG 1.1 module called "ietf-http-client". A 208 high-level overview of the module is provided in Section 2.1. 209 Examples illustrating the module's use are provided in Examples 210 (Section 2.2). The YANG module itself is defined in Section 2.3. 212 2.1. Data Model Overview 214 This section provides an overview of the "ietf-http-client" module in 215 terms of its features and groupings. 217 2.1.1. Features 219 The following diagram lists all the "feature" statements defined in 220 the "ietf-http-client" module: 222 Features: 223 +-- proxy-connect 224 +-- basic-auth 225 +-- tcp-supported 226 +-- tls-supported 228 | The diagram above uses syntax that is similar to but not 229 | defined in [RFC8340]. 231 2.1.2. Groupings 233 The "ietf-http-client" module defines the following "grouping" 234 statements: 236 * http-client-identity-grouping 237 * http-client-grouping 238 * http-client-stack-grouping 240 Each of these groupings are presented in the following subsections. 242 2.1.2.1. The "http-client-identity-grouping" Grouping 244 The following tree diagram [RFC8340] illustrates the "http-client- 245 identity-grouping" grouping: 247 grouping http-client-identity-grouping 248 +-- client-identity! 249 +-- (auth-type) 250 +--:(basic) 251 +-- basic {basic-auth}? 252 +-- user-id string 253 +---u ct:password-grouping 255 Comments: 257 * This grouping exists because it is used three times by the "http- 258 client-grouping" discussed in Section 2.1.2.2. 260 * The "client-identity" node is a "presence" container so that its 261 descendent "choice" node's "mandatory true" doesn't imply that a 262 client identity must be configured, as a client identity may be 263 configured at protocol layers. 265 * The "basic" authentication scheme is the only scheme defined by 266 this module, albeit it must be enabled via the "basic-auth" 267 feature (see Section 2.1.1). 269 * Other authentication schemes MAY be augmented in as needed by the 270 application. 272 2.1.2.2. The "http-client-grouping" Grouping 274 The following tree diagram [RFC8340] illustrates the "http-client- 275 grouping" grouping: 277 grouping http-client-grouping 278 +---u http-client-identity-grouping 279 +-- proxy-connect! {proxy-connect}? 280 +-- (proxy-type) 281 +--:(http) 282 | +-- http-proxy 283 | +-- tcp-client-parameters 284 | | +---u tcpc:tcp-client-grouping 285 | +-- http-client-parameters 286 | +---u http-client-identity-grouping 287 +--:(https) 288 +-- https-proxy 289 +-- tcp-client-parameters 290 | +---u tcpc:tcp-client-grouping 291 +-- tls-client-parameters 292 | +---u tlsc:tls-client-grouping 293 +-- http-client-parameters 294 +---u http-client-identity-grouping 296 Comments: 298 * The "http-client-grouping" defines the configuration for just 299 "HTTP" part of a protocol stack. It does not, for instance, 300 define any configuration for the "TCP" or "TLS" protocol layers 301 (for that, see Section 2.1.2.3). 303 * Beyond configuring the client's identity, via the "http-client- 304 identity-grouping" grouping discussed in Section 2.1.2.1, this 305 grouping defines support for HTTP-proxies, albeit it must be 306 enabled via a "feature" statement. 308 * The "proxy-connect" node is a "presence" container so that its 309 descendent "choice" node's "mandatory true" doesn't imply that a 310 proxy connection must be configured, assuming the server supports 311 the "proxy-connect" feature. 313 * For the referenced grouping statement(s): 315 - The "http-client-identity-grouping" grouping is discussed in 316 Section 2.1.2.1. 317 - The "tcp-client-grouping" grouping is discussed in 318 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 319 - The "tls-client-grouping" grouping is discussed in 320 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 322 2.1.2.3. The "http-client-stack-grouping" Grouping 324 The following tree diagram [RFC8340] illustrates the "http-client- 325 stack-grouping" grouping: 327 grouping http-client-stack-grouping 328 +-- (transport) 329 +--:(tcp) {tcp-supported}? 330 | +-- tcp 331 | +-- tcp-client-parameters 332 | | +---u tcpc:tcp-client-grouping 333 | +-- http-client-parameters 334 | +---u http-client-grouping 335 +--:(tls) {tls-supported}? 336 +-- tls 337 +-- tcp-client-parameters 338 | +---u tcpc:tcp-client-grouping 339 +-- tls-client-parameters 340 | +---u tlsc:tls-client-grouping 341 +-- http-client-parameters 342 +---u http-client-grouping 344 Comments: 346 * The "http-client-stack-grouping" is a convenience grouping for 347 downstream modules. It defines both the "HTTP" and "HTTPS" 348 protocol stacks, with each option enabled by a "feature" statement 349 for application control. 351 * For the referenced grouping statement(s): 353 - The "tcp-client-grouping" grouping is discussed in 354 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 355 - The "tls-client-grouping" grouping is discussed in 356 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 357 - The "http-client-grouping" grouping is discussed in 358 Section 2.1.2.2 in this document. 360 2.1.3. Protocol-accessible Nodes 362 The "ietf-http-client" module defines only "grouping" statements that 363 are used by other modules to instantiate protocol-accessible nodes. 365 2.2. Example Usage 367 This section presents two examples showing the http-client-grouping 368 populated with some data. 370 The following example illustrates an HTTP client connecting directly 371 to an HTTP server. 373 374 375 376 377 378 bob 379 secret 380 381 382 384 The following example illustrates the same client connecting through 385 an HTTP proxy. This example is consistent with examples presented in 386 Section 2.2 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 387 [I-D.ietf-netconf-keystore]. 389 =============== NOTE: '\' line wrapping per RFC 8792 ================ 391 392 393 394 395 396 bob 397 secret 398 399 400 401 402 403 corp-fw2.example.com 404 405 15 406 3 407 30 408 409 410 411 412 413 414 rsa-asymmetric-key 415 ex-rsa-cert 416 417 419 420 421 422 trusted-server-ca-certs 424 425 426 trusted-server-ee-certs 428 429 430 431 432 433 434 local-app-1 435 secret 436 437 438 439 440 441 443 2.3. YANG Module 445 This YANG module has normative references to [RFC6991]. 447 file "ietf-http-client@2021-05-18.yang" 449 module ietf-http-client { 450 yang-version 1.1; 451 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 452 prefix httpc; 454 import ietf-netconf-acm { 455 prefix nacm; 456 reference 457 "RFC 8341: Network Configuration Access Control Model"; 458 } 460 import ietf-crypto-types { 461 prefix ct; 462 reference 463 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 464 } 466 import ietf-tcp-client { 467 prefix tcpc; 468 reference 469 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 470 } 472 import ietf-tls-client { 473 prefix tlsc; 474 reference 475 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 476 } 478 organization 479 "IETF NETCONF (Network Configuration) Working Group"; 481 contact 482 "WG Web: 483 WG List: 484 Author: Kent Watsen "; 486 description 487 "This module defines reusable groupings for HTTP clients that 488 can be used as a basis for specific HTTP client instances. 490 Copyright (c) 2021 IETF Trust and the persons identified 491 as authors of the code. All rights reserved. 493 Redistribution and use in source and binary forms, with 494 or without modification, is permitted pursuant to, and 495 subject to the license terms contained in, the Simplified 496 BSD License set forth in Section 4.c of the IETF Trust's 497 Legal Provisions Relating to IETF Documents 498 (https://trustee.ietf.org/license-info). 500 This version of this YANG module is part of RFC GGGG 501 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 502 itself for full legal notices. 504 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 505 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 506 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 507 are to be interpreted as described in BCP 14 (RFC 2119) 508 (RFC 8174) when, and only when, they appear in all 509 capitals, as shown here."; 511 revision 2021-05-18 { 512 description 513 "Initial version"; 514 reference 515 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 516 } 518 // Features 520 feature proxy-connect { 521 description 522 "Proxy connection configuration is configurable for 523 HTTP clients on the server implementing this feature."; 524 } 526 feature basic-auth { 527 description 528 "The 'basic-auth' feature indicates that the client 529 may be configured to use the 'basic' HTTP authentication 530 scheme."; 531 reference 532 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 533 } 535 feature tcp-supported { 536 description 537 "Indicates that the server supports HTTP/TCP."; 538 } 540 feature tls-supported { 541 description 542 "Indicates that the server supports HTTP/TLS."; 543 } 545 // Groupings 547 grouping http-client-identity-grouping { 548 description 549 "A grouping to provide HTTP credentials used by the 550 client to authenticate itself to the HTTP server."; 551 container client-identity { 552 nacm:default-deny-write; 553 presence 554 "Indicates that a client identity has been configured. 555 This statement is present so the mandatory descendent 556 nodes do not imply that this node must be configured."; 557 description 558 "The identity the HTTP client should use when 559 authenticating itself to the HTTP server."; 560 choice auth-type { 561 mandatory true; 562 description 563 "A choice amongst available authentication types."; 564 case basic { 565 container basic { 566 if-feature "basic-auth"; 567 leaf user-id { 568 type string; 569 mandatory true; 570 description 571 "The user-id for the authenticating client."; 572 } 573 uses ct:password-grouping { 574 description 575 "The password for the authenticating client."; 576 } 577 description 578 "The 'basic' HTTP scheme credentials."; 579 reference 580 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 581 } 582 } 583 } 584 } 585 } // grouping http-client-identity-grouping 587 grouping http-client-grouping { 588 description 589 "A reusable grouping for configuring a HTTP client. 591 This grouping is expected to be used in conjunction with 592 other configurations providing, e.g., the hostname or IP 593 address and port number the client initiates connections 594 to. 596 Note that this grouping uses fairly typical descendant 597 node names such that a stack of 'uses' statements will 598 have name conflicts. It is intended that the consuming 599 data model will resolve the issue (e.g., by wrapping 600 the 'uses' statement in a container called 601 'http-client-parameters'). This model purposely does 602 not do this itself so as to provide maximum flexibility 603 to consuming models."; 605 uses http-client-identity-grouping; 607 container proxy-connect { 608 nacm:default-deny-write; 609 if-feature "proxy-connect"; 610 presence 611 "Indicates that a proxy server connections have been 612 configured. This statement is present so the mandatory 613 descendant nodes do not imply that this node must be 614 configured."; 615 description 616 "Configures the proxy server the HTTP-client is to 617 connect thru."; 618 choice proxy-type { 619 mandatory true; 620 description 621 "Choice amongst proxy server types."; 622 case http { 623 container http-proxy { 624 description 625 "Container for HTTP Proxy (Web Proxy) server 626 configuration parameters."; 627 container tcp-client-parameters { 628 description 629 "A wrapper around the TCP parameters to avoid 630 name collisions."; 631 uses tcpc:tcp-client-grouping; 632 } 633 container http-client-parameters { 634 description 635 "A wrapper around the HTTP parameters to avoid 636 name collisions."; 637 uses http-client-identity-grouping; 638 } 639 } 640 } 641 case https { 642 container https-proxy { 643 description 644 "Container for HTTPS Proxy (Secure Web Proxy) server 645 configuration parameters."; 646 container tcp-client-parameters { 647 description 648 "A wrapper around the TCP parameters to avoid 649 name collisions."; 650 uses tcpc:tcp-client-grouping; 651 } 652 container tls-client-parameters { 653 description 654 "A wrapper around the TLS parameters to avoid 655 name collisions."; 656 uses tlsc:tls-client-grouping; 657 } 658 container http-client-parameters { 659 description 660 "A wrapper around the HTTP parameters to avoid 661 name collisions."; 662 uses http-client-identity-grouping; 663 } 664 } 665 } 666 } 667 } 668 } // grouping http-client-grouping 670 grouping http-client-stack-grouping { 671 description 672 "A grouping that defines common HTTP-based protocol stacks."; 673 choice transport { 674 mandatory true; 675 description 676 "Choice amongst various transports type. TCP, with and 677 without TLS are defined here, with 'feature' statements 678 so that they may be disabled. Other transports MAY be 679 augmented in as 'case' statements by future efforts."; 680 case tcp { 681 if-feature "tcp-supported"; 682 container tcp { 683 description 684 "Container for TCP-based HTTP protocols."; 685 container tcp-client-parameters { 686 description 687 "A wrapper around the TCP parameters to avoid 688 name collisions."; 689 uses tcpc:tcp-client-grouping; 690 } 691 container http-client-parameters { 692 description 693 "A wrapper around the HTTP parameters to avoid 694 name collisions."; 695 uses http-client-grouping; 696 } 697 } 698 } 699 case tls { 700 if-feature "tls-supported"; 701 container tls { 702 description 703 "Container for TLS-based HTTP protocols."; 704 container tcp-client-parameters { 705 description 706 "A wrapper around the TCP parameters to avoid 707 name collisions."; 708 uses tcpc:tcp-client-grouping; 709 } 710 container tls-client-parameters { 711 description 712 "A wrapper around the TLS parameters to avoid 713 name collisions."; 714 uses tlsc:tls-client-grouping; 715 } 716 container http-client-parameters { 717 description 718 "A wrapper around the HTTP parameters to avoid 719 name collisions."; 720 uses http-client-grouping; 721 } 722 } 723 } 724 } 725 } // http-client-stack-grouping 727 } 729 731 3. The "ietf-http-server" Module 733 This section defines a YANG 1.1 module called "ietf-http-server". A 734 high-level overview of the module is provided in Section 3.1. 735 Examples illustrating the module's use are provided in Examples 736 (Section 3.2). The YANG module itself is defined in Section 3.3. 738 3.1. Data Model Overview 740 This section provides an overview of the "ietf-http-server" module in 741 terms of its features and groupings. 743 3.1.1. Features 745 The following diagram lists all the "feature" statements defined in 746 the "ietf-http-server" module: 748 Features: 749 +-- client-auth-supported 750 +-- local-users-supported 751 +-- basic-auth 752 +-- tcp-supported 753 +-- tls-supported 754 | The diagram above uses syntax that is similar to but not 755 | defined in [RFC8340]. 757 3.1.2. Groupings 759 The "ietf-http-server" module defines the following "grouping" 760 statements: 762 * http-server-grouping 763 * http-server-stack-grouping 765 Each of these groupings are presented in the following subsections. 767 3.1.2.1. The "http-server-grouping" Grouping 769 The following tree diagram [RFC8340] illustrates the "http-server- 770 grouping" grouping: 772 grouping http-server-grouping 773 +-- server-name? string 774 +-- client-authentication! {client-auth-supported}? 775 +-- users {local-users-supported}? 776 +-- user* [user-id] 777 +-- user-id? string 778 +-- (auth-type) 779 +--:(basic) 780 +-- basic {basic-auth}? 781 +-- user-id? string 782 +-- password? ianach:crypt-hash 784 Comments: 786 * The "http-server-grouping" defines the configuration for just 787 "HTTP" part of a protocol stack. It does not, for instance, 788 define any configuration for the "TCP" or "TLS" protocol layers 789 (for that, see Section 3.1.2.2). 791 * The "server-name" node defines the HTTP server's name, as 792 presented to HTTP clients. 794 * The "client-authentication" node, which must by enabled by a 795 feature, defines a very simple user-database. Only the "basic" 796 authentication scheme is supported, albeit it must be enabled by a 797 "feature". Other authentication schemes MAY be augmented in. 799 3.1.2.2. The "http-server-stack-grouping" Grouping 801 The following tree diagram [RFC8340] illustrates the "http-server- 802 stack-grouping" grouping: 804 grouping http-server-stack-grouping 805 +-- (transport) 806 +--:(tcp) {tcp-supported}? 807 | +-- tcp 808 | +-- tcp-server-parameters 809 | | +---u tcps:tcp-server-grouping 810 | +-- http-server-parameters 811 | +---u http-server-grouping 812 +--:(tls) {tls-supported}? 813 +-- tls 814 +-- tcp-server-parameters 815 | +---u tcps:tcp-server-grouping 816 +-- tls-server-parameters 817 | +---u tlss:tls-server-grouping 818 +-- http-server-parameters 819 +---u http-server-grouping 821 Comments: 823 * The "http-server-stack-grouping" is a convenience grouping for 824 downstream modules. It defines both the "HTTP" and "HTTPS" 825 protocol stacks, with each option enabled by a "feature" statement 826 for application control. 828 * For the referenced grouping statement(s): 830 - The "tcp-server-grouping" grouping is discussed in 831 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 832 - The "tls-server-grouping" grouping is discussed in 833 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 834 - The "http-server-grouping" grouping is discussed in 835 Section 3.1.2.1 in this document. 837 3.1.3. Protocol-accessible Nodes 839 The "ietf-http-server" module defines only "grouping" statements that 840 are used by other modules to instantiate protocol-accessible nodes. 842 3.2. Example Usage 844 This section presents an example showing the http-server-grouping 845 populated with some data. 847 848 849 850 foo.example.com 851 853 3.3. YANG Module 855 This YANG module has normative references to [RFC6991]. 857 file "ietf-http-server@2021-05-18.yang" 859 module ietf-http-server { 860 yang-version 1.1; 861 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 862 prefix https; 864 import iana-crypt-hash { 865 prefix ianach; 866 reference 867 "RFC 7317: A YANG Data Model for System Management"; 868 } 870 import ietf-netconf-acm { 871 prefix nacm; 872 reference 873 "RFC 8341: Network Configuration Access Control Model"; 874 } 876 import ietf-tcp-server { 877 prefix tcps; 878 reference 879 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 880 } 882 import ietf-tls-server { 883 prefix tlss; 884 reference 885 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 886 } 888 organization 889 "IETF NETCONF (Network Configuration) Working Group"; 891 contact 892 "WG Web: 893 WG List: 894 Author: Kent Watsen "; 896 description 897 "This module defines reusable groupings for HTTP servers that 898 can be used as a basis for specific HTTP server instances. 900 Copyright (c) 2021 IETF Trust and the persons identified 901 as authors of the code. All rights reserved. 903 Redistribution and use in source and binary forms, with 904 or without modification, is permitted pursuant to, and 905 subject to the license terms contained in, the Simplified 906 BSD License set forth in Section 4.c of the IETF Trust's 907 Legal Provisions Relating to IETF Documents 908 (https://trustee.ietf.org/license-info). 910 This version of this YANG module is part of RFC GGGG 911 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 912 itself for full legal notices. 914 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 915 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 916 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 917 are to be interpreted as described in BCP 14 (RFC 2119) 918 (RFC 8174) when, and only when, they appear in all 919 capitals, as shown here."; 921 revision 2021-05-18 { 922 description 923 "Initial version"; 924 reference 925 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 926 } 928 // Features 930 feature client-auth-supported { 931 description 932 "Indicates that the configuration for how to authenticate 933 clients can be configured herein. HTTP-level client 934 authentication may not be needed when client authentication 935 is expected to occur only at another protocol layer."; 936 } 938 feature local-users-supported { 939 description 940 "Indicates that the configuration for users can be 941 configured herein, as opposed to in an application 942 specific location."; 943 } 944 feature basic-auth { 945 description 946 "The 'basic-auth' feature indicates that the server 947 may be configured authenticate users using the 'basic' 948 HTTP authentication scheme."; 949 reference 950 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 951 } 953 feature tcp-supported { 954 description 955 "Indicates that the server supports HTTP/TCP."; 956 } 958 feature tls-supported { 959 description 960 "Indicates that the server supports HTTP/TLS."; 961 } 963 // Groupings 965 grouping http-server-grouping { 966 description 967 "A reusable grouping for configuring an HTTP server. 969 Note that this grouping uses fairly typical descendant 970 node names such that a stack of 'uses' statements will 971 have name conflicts. It is intended that the consuming 972 data model will resolve the issue (e.g., by wrapping 973 the 'uses' statement in a container called 974 'http-server-parameters'). This model purposely does 975 not do this itself so as to provide maximum flexibility 976 to consuming models."; 978 leaf server-name { 979 nacm:default-deny-write; 980 type string; 981 description 982 "The value of the 'Server' header field. If not set, then 983 underlying software's default value is used. Set to the 984 empty string to disable."; 985 } 987 container client-authentication { 988 if-feature "client-auth-supported"; 989 nacm:default-deny-write; 990 presence 991 "Indicates that HTTP based client authentication is 992 configured. This statement is present so the mandatory 993 descendant nodes do not imply that this node must be 994 configured."; 995 description 996 "Configures how the HTTP server can authenticate HTTP 997 clients. The HTTP server will request that the HTTP 998 client send authentication when needed."; 999 container users { 1000 if-feature "local-users-supported"; 1001 description 1002 "A list of locally configured users."; 1003 list user { 1004 key "user-id"; 1005 description 1006 "The list of local users configured on this device."; 1007 leaf user-id { 1008 type string; 1009 description 1010 "The user-id for the authenticating client."; 1011 } 1012 choice auth-type { 1013 mandatory true; 1014 description 1015 "The authentication type."; 1016 case basic { 1017 container basic { 1018 if-feature "basic-auth"; 1019 leaf user-id { 1020 type string; 1021 description 1022 "The user-id for the authenticating client."; 1023 } 1024 leaf password { 1025 nacm:default-deny-write; 1026 type ianach:crypt-hash; 1027 description 1028 "The password for the authenticating client."; 1029 } 1030 description 1031 "The 'basic' HTTP scheme credentials."; 1032 reference 1033 "RFC 7617: 1034 The 'Basic' HTTP Authentication Scheme"; 1035 } 1036 } 1037 } 1038 } 1039 } 1041 } // container client-authentication 1042 } // grouping http-server-grouping 1044 grouping http-server-stack-grouping { 1045 description 1046 "A grouping that defines common HTTP-based protocol stacks."; 1047 choice transport { 1048 mandatory true; 1049 description 1050 "Choice amongst various transports type. TCP, with and 1051 without TLS are defined here, with 'feature' statements 1052 so that they may be disabled. Other transports MAY be 1053 augmented in as 'case' statements by future efforts."; 1054 case tcp { 1055 if-feature "tcp-supported"; 1056 container tcp { 1057 description 1058 "Container for TCP-based HTTP protocols."; 1059 container tcp-server-parameters { 1060 description 1061 "A wrapper around the TCP parameters to avoid 1062 name collisions."; 1063 uses tcps:tcp-server-grouping; 1064 } 1065 container http-server-parameters { 1066 description 1067 "A wrapper around the HTTP parameters to avoid 1068 name collisions."; 1069 uses http-server-grouping; 1070 } 1071 } 1072 } 1073 case tls { 1074 if-feature "tls-supported"; 1075 container tls { 1076 description 1077 "Container for TLS-based HTTP protocols."; 1078 container tcp-server-parameters { 1079 description 1080 "A wrapper around the TCP parameters to avoid 1081 name collisions."; 1082 uses tcps:tcp-server-grouping; 1083 } 1084 container tls-server-parameters { 1085 description 1086 "A wrapper around the TLS parameters to avoid 1087 name collisions."; 1088 uses tlss:tls-server-grouping; 1090 } 1091 container http-server-parameters { 1092 description 1093 "A wrapper around the HTTP parameters to avoid 1094 name collisions."; 1095 uses http-server-grouping; 1096 } 1097 } 1098 } 1099 } 1100 } // http-server-stack-grouping 1102 } 1104 1106 4. Security Considerations 1108 4.1. The "ietf-http-client" YANG Module 1110 The "ietf-http-client" YANG module defines "grouping" statements that 1111 are designed to be accessed via YANG based management protocols, such 1112 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1113 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1114 with mutual authentication. 1116 The NETCONF access control model (NACM) [RFC8341] provides the means 1117 to restrict access for particular users to a pre-configured subset of 1118 all available protocol operations and content. 1120 Since the module in this document only define groupings, these 1121 considerations are primarily for the designers of other modules that 1122 use these groupings. 1124 One readable data node defined in this YANG module may be considered 1125 sensitive or vulnerable in some network environments. This node is 1126 as follows: 1128 * The "client-identity/basic/password" node: 1130 The cleartext "password" node defined in the "http-client- 1131 identity-grouping" grouping is additionally sensitive to read 1132 operations such that, in normal use cases, it should never be 1133 returned to a client. For this reason, the NACM extension 1134 "default-deny-all" has been applied to it. 1136 | Please be aware that this module uses the "key" and "private- 1137 | key" nodes from the "ietf-crypto-types" module 1138 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 1139 | extension "default-deny-all" set, thus preventing unrestricted 1140 | read-access to the cleartext key values. 1142 None of the writable data nodes defined in this YANG module are 1143 considered sensitive or vulnerable in network environments. The NACM 1144 "default-deny-write" extension has not been set for any data nodes 1145 defined in this module. 1147 | Please be aware that this module uses groupings from the "ietf- 1148 | tls-client" and "ietf-tls-server" modules defined in 1149 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1150 | defined in these groupings have the NACM extension "default- 1151 | deny-write" set, thus preventing unrestricted write-access to 1152 | the data nodes defined in those groupings. 1154 This module does not define any RPCs, actions, or notifications, and 1155 thus the security consideration for such is not provided here. 1157 4.2. The "ietf-http-server" YANG Module 1159 The "ietf-http-server" YANG module defines "grouping" statements that 1160 are designed to be accessed via YANG based management protocols, such 1161 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1162 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1163 with mutual authentication. 1165 The NETCONF access control model (NACM) [RFC8341] provides the means 1166 to restrict access for particular users to a pre-configured subset of 1167 all available protocol operations and content. 1169 Since the module in this document only define groupings, these 1170 considerations are primarily for the designers of other modules that 1171 use these groupings. 1173 None of the readable data nodes defined in this YANG module are 1174 considered sensitive or vulnerable in network environments. The NACM 1175 "default-deny-all" extension has not been set for any data nodes 1176 defined in this module. 1178 None of the writable data nodes defined in this YANG module are 1179 considered sensitive or vulnerable in network environments. The NACM 1180 "default-deny-write" extension has not been set for any data nodes 1181 defined in this module. 1183 | Please be aware that this module uses groupings from the "ietf- 1184 | tls-client" and "ietf-tls-server" modules defined in 1185 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1186 | defined in these groupings have the NACM extension "default- 1187 | deny-write" set, thus preventing unrestricted write-access to 1188 | the data nodes defined in those groupings. 1190 This module does not define any RPCs, actions, or notifications, and 1191 thus the security consideration for such is not provided here. 1193 5. IANA Considerations 1195 5.1. The "IETF XML" Registry 1197 This document registers two URIs in the "ns" subregistry of the IETF 1198 XML Registry [RFC3688]. Following the format in [RFC3688], the 1199 following registrations are requested: 1201 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 1202 Registrant Contact: The IESG 1203 XML: N/A, the requested URI is an XML namespace. 1205 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 1206 Registrant Contact: The IESG 1207 XML: N/A, the requested URI is an XML namespace. 1209 5.2. The "YANG Module Names" Registry 1211 This document registers two YANG modules in the YANG Module Names 1212 registry [RFC6020]. Following the format in [RFC6020], the following 1213 registrations are requested: 1215 name: ietf-http-client 1216 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 1217 prefix: httpc 1218 reference: RFC GGGG 1220 name: ietf-http-server 1221 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 1222 prefix: https 1223 reference: RFC GGGG 1225 6. References 1227 6.1. Normative References 1229 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1230 Requirement Levels", BCP 14, RFC 2119, 1231 DOI 10.17487/RFC2119, March 1997, 1232 . 1234 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1235 the Network Configuration Protocol (NETCONF)", RFC 6020, 1236 DOI 10.17487/RFC6020, October 2010, 1237 . 1239 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1240 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1241 . 1243 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1244 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1245 . 1247 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1248 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1249 May 2017, . 1251 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1252 Access Control Model", STD 91, RFC 8341, 1253 DOI 10.17487/RFC8341, March 2018, 1254 . 1256 6.2. Informative References 1258 [I-D.ietf-netconf-crypto-types] 1259 Watsen, K., "YANG Data Types and Groupings for 1260 Cryptography", Work in Progress, Internet-Draft, draft- 1261 ietf-netconf-crypto-types-19, 10 February 2021, 1262 . 1265 [I-D.ietf-netconf-http-client-server] 1266 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1267 Servers", Work in Progress, Internet-Draft, draft-ietf- 1268 netconf-http-client-server-06, 10 February 2021, 1269 . 1272 [I-D.ietf-netconf-keystore] 1273 Watsen, K., "A YANG Data Model for a Keystore", Work in 1274 Progress, Internet-Draft, draft-ietf-netconf-keystore-21, 1275 10 February 2021, . 1278 [I-D.ietf-netconf-netconf-client-server] 1279 Watsen, K., "NETCONF Client and Server Models", Work in 1280 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1281 client-server-22, 10 February 2021, 1282 . 1285 [I-D.ietf-netconf-restconf-client-server] 1286 Watsen, K., "RESTCONF Client and Server Models", Work in 1287 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1288 client-server-22, 10 February 2021, 1289 . 1292 [I-D.ietf-netconf-ssh-client-server] 1293 Watsen, K., "YANG Groupings for SSH Clients and SSH 1294 Servers", Work in Progress, Internet-Draft, draft-ietf- 1295 netconf-ssh-client-server-23, 10 February 2021, 1296 . 1299 [I-D.ietf-netconf-tcp-client-server] 1300 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1301 and TCP Servers", Work in Progress, Internet-Draft, draft- 1302 ietf-netconf-tcp-client-server-09, 10 February 2021, 1303 . 1306 [I-D.ietf-netconf-tls-client-server] 1307 Watsen, K., "YANG Groupings for TLS Clients and TLS 1308 Servers", Work in Progress, Internet-Draft, draft-ietf- 1309 netconf-tls-client-server-23, 10 February 2021, 1310 . 1313 [I-D.ietf-netconf-trust-anchors] 1314 Watsen, K., "A YANG Data Model for a Truststore", Work in 1315 Progress, Internet-Draft, draft-ietf-netconf-trust- 1316 anchors-14, 10 February 2021, 1317 . 1320 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1321 DOI 10.17487/RFC3688, January 2004, 1322 . 1324 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1325 and A. Bierman, Ed., "Network Configuration Protocol 1326 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1327 . 1329 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1330 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1331 . 1333 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1334 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1335 . 1337 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1338 and R. Wilton, "Network Management Datastore Architecture 1339 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1340 . 1342 Appendix A. Change Log 1344 This section is to be removed before publishing as an RFC. 1346 A.1. 00 to 01 1348 * Modified Abstract and Intro to be more accurate wrt intended 1349 applicability. 1351 * In ietf-http-client, removed "protocol-version" and all auth 1352 schemes except "basic". 1354 * In ietf-http-client, factored out "client-identity-grouping" for 1355 proxy connections. 1357 * In ietf-http-server, removed "choice required-or-optional" and 1358 "choice local-or-external". 1360 * In ietf-http-server, moved the basic auth under a "choice auth- 1361 type" limited by new "feature basic-auth". 1363 A.2. 01 to 02 1365 * Removed the unused "external-client-auth-supported" feature from 1366 ietf-http-server. 1368 A.3. 02 to 03 1370 * Removed "protocol-versions" from ietf-http-server based on HTTP WG 1371 feedback. 1373 * Slightly restructured the "proxy-server" definition in ietf-http- 1374 client. 1376 * Added http-client example show proxy server use. 1378 * Added a "Note to Reviewers" note to first page. 1380 A.4. 03 to 04 1382 * Added a parent "container" to "client-identity-grouping" so that 1383 it could be better used by the proxy model. 1385 * Added a "choice" to the proxy model enabling selection of proxy 1386 types. 1388 * Added 'http-client-stack-grouping' and 'http-server-stack- 1389 grouping' convenience groupings. 1391 * Expanded "Data Model Overview section(s) [remove "wall" of tree 1392 diagrams]. 1394 * Updated the Security Considerations section. 1396 A.5. 04 to 05 1398 * Fixed titles and a ref in the IANA Considerations section 1400 * Cleaned up examples (e.g., removed FIXMEs) 1402 * Fixed issues found by the SecDir review of the "keystore" draft. 1404 * Updated the "ietf-http-client" module to use the new "password- 1405 grouping" grouping from the "crypto-types" module. 1407 A.6. 05 to 06 1409 * Removed note questioning if okay for app to augment-in a 'path' 1410 node when needed, discussed during the 108 session. 1412 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 1414 A.7. 06 to 07 1416 * Added XML-comment above examples explaining the reason for the 1417 unusual top-most element's presence. 1419 * Renamed 'client-auth-config-supported' to 'client-auth-supported' 1420 consistent with other drafts. 1422 * Wrapped 'container basic' choice inside a 'case basic' per best 1423 practice. 1425 * Aligned modules with `pyang -f` formatting. 1427 * Fixed nits found by YANG Doctor reviews. 1429 Acknowledgements 1431 The authors would like to thank for following for lively discussions 1432 on list and in the halls (ordered by first name): Ben Schwartz, Mark 1433 Nottingham, Rob Wilton (contributor), and Willy Tarreau. 1435 Author's Address 1437 Kent Watsen 1438 Watsen Networks 1440 Email: kent+ietf@watsen.net