idnits 2.17.1 draft-ietf-netconf-http-client-server-09.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 (7 March 2022) is 781 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-21 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-08 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-23 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-24 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-24 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-26 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-11 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-26 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-16 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 7 March 2022 5 Expires: 8 September 2022 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-09 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-client- 34 server 36 * FFFF --> the assigned RFC value for draft-ietf-netconf-tls-client- 37 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 * 2022-03-07 --> 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 8 September 2022. 67 Copyright Notice 69 Copyright (c) 2022 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 Revised BSD License text as 78 described in Section 4.e of the Trust Legal Provisions and are 79 provided without warranty as described in the Revised 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 1.4. Conventions . . . . . . . . . . . . . . . . . . . . . . . 5 88 2. The "ietf-http-client" Module . . . . . . . . . . . . . . . . 5 89 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 5 90 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 91 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 92 3. The "ietf-http-server" Module . . . . . . . . . . . . . . . . 16 93 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 16 94 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18 95 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 96 4. Security Considerations . . . . . . . . . . . . . . . . . . . 24 97 4.1. The "ietf-http-client" YANG Module . . . . . . . . . . . 24 98 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 A.8. 07 to 08 . . . . . . . . . . . . . . . . . . . . . . . . 31 114 A.9. 08 to 09 . . . . . . . . . . . . . . . . . . . . . . . . 31 115 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 116 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31 118 1. Introduction 120 This document defines two YANG 1.1 [RFC7950] modules: the first 121 defines a minimal grouping for configuring an HTTP client, and the 122 second defines a minimal grouping for configuring an HTTP server. It 123 is intended that these groupings will be used to help define the 124 configuration for simple HTTP-based protocols (not for complete web 125 servers or browsers). 127 1.1. Relation to other RFCs 129 This document presents one or more YANG modules [RFC7950] that are 130 part of a collection of RFCs that work together to, ultimately, 131 enable the configuration of the clients and servers of both the 132 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 134 The modules have been defined in a modular fashion to enable their 135 use by other efforts, some of which are known to be in progress at 136 the time of this writing, with many more expected to be defined in 137 time. 139 The normative dependency relationship between the various RFCs in the 140 collection is presented in the below diagram. The labels in the 141 diagram represent the primary purpose provided by each RFC. 142 Hyperlinks to each RFC are provided below the diagram. 144 crypto-types 145 ^ ^ 146 / \ 147 / \ 148 truststore keystore 149 ^ ^ ^ ^ 150 | +---------+ | | 151 | | | | 152 | +------------+ | 153 tcp-client-server | / | | 154 ^ ^ ssh-client-server | | 155 | | ^ tls-client-server 156 | | | ^ ^ http-client-server 157 | | | | | ^ 158 | | | +-----+ +---------+ | 159 | | | | | | 160 | +-----------|--------|--------------+ | | 161 | | | | | | 162 +-----------+ | | | | | 163 | | | | | | 164 | | | | | | 165 netconf-client-server restconf-client-server 167 +=======================+===========================================+ 168 |Label in Diagram | Originating RFC | 169 +=======================+===========================================+ 170 |crypto-types | [I-D.ietf-netconf-crypto-types] | 171 +-----------------------+-------------------------------------------+ 172 |truststore | [I-D.ietf-netconf-trust-anchors] | 173 +-----------------------+-------------------------------------------+ 174 |keystore | [I-D.ietf-netconf-keystore] | 175 +-----------------------+-------------------------------------------+ 176 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 177 +-----------------------+-------------------------------------------+ 178 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 179 +-----------------------+-------------------------------------------+ 180 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 181 +-----------------------+-------------------------------------------+ 182 |http-client-server | [I-D.ietf-netconf-http-client-server] | 183 +-----------------------+-------------------------------------------+ 184 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 185 +-----------------------+-------------------------------------------+ 186 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 187 +-----------------------+-------------------------------------------+ 189 Table 1: Label to RFC Mapping 191 1.2. Specification Language 193 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 195 "OPTIONAL" in this document are to be interpreted as described in BCP 196 14 [RFC2119] [RFC8174] when, and only when, they appear in all 197 capitals, as shown here. 199 1.3. Adherence to the NMDA 201 This document is compliant with the Network Management Datastore 202 Architecture (NMDA) [RFC8342]. For instance, as described in 203 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 204 trust anchors and keys installed during manufacturing are expected to 205 appear in . 207 1.4. Conventions 209 Various examples used in this document use a placeholder value for 210 binary data that has been base64 encoded (e.g., "BASE64VALUE="). 211 This placeholder value is used as real base64 encoded structures are 212 often many lines long and hence distracting to the example being 213 presented. 215 2. The "ietf-http-client" Module 217 This section defines a YANG 1.1 module called "ietf-http-client". A 218 high-level overview of the module is provided in Section 2.1. 219 Examples illustrating the module's use are provided in Examples 220 (Section 2.2). The YANG module itself is defined in Section 2.3. 222 2.1. Data Model Overview 224 This section provides an overview of the "ietf-http-client" module in 225 terms of its features and groupings. 227 2.1.1. Features 229 The following diagram lists all the "feature" statements defined in 230 the "ietf-http-client" module: 232 Features: 233 +-- proxy-connect 234 +-- basic-auth 235 +-- tcp-supported 236 +-- tls-supported 237 | The diagram above uses syntax that is similar to but not 238 | defined in [RFC8340]. 240 2.1.2. Groupings 242 The "ietf-http-client" module defines the following "grouping" 243 statements: 245 * http-client-identity-grouping 246 * http-client-grouping 247 * http-client-stack-grouping 249 Each of these groupings are presented in the following subsections. 251 2.1.2.1. The "http-client-identity-grouping" Grouping 253 The following tree diagram [RFC8340] illustrates the "http-client- 254 identity-grouping" grouping: 256 grouping http-client-identity-grouping 257 +-- client-identity! 258 +-- (auth-type) 259 +--:(basic) 260 +-- basic {basic-auth}? 261 +-- user-id string 262 +---u ct:password-grouping 264 Comments: 266 * This grouping exists because it is used three times by the "http- 267 client-grouping" discussed in Section 2.1.2.2. 269 * The "client-identity" node is a "presence" container so the 270 mandatory descendant nodes do not imply that this node must be 271 configured, as a client identity may be configured at protocol 272 layers. 274 * The "basic" authentication scheme is the only scheme defined by 275 this module, albeit it must be enabled via the "basic-auth" 276 feature (see Section 2.1.1). 278 * Other authentication schemes MAY be augmented in as needed by the 279 application. 281 2.1.2.2. The "http-client-grouping" Grouping 283 The following tree diagram [RFC8340] illustrates the "http-client- 284 grouping" grouping: 286 grouping http-client-grouping 287 +---u http-client-identity-grouping 288 +-- proxy-connect! {proxy-connect}? 289 +-- (proxy-type) 290 +--:(http) 291 | +-- http-proxy 292 | +-- tcp-client-parameters 293 | | +---u tcpc:tcp-client-grouping 294 | +-- http-client-parameters 295 | +---u http-client-identity-grouping 296 +--:(https) 297 +-- https-proxy 298 +-- tcp-client-parameters 299 | +---u tcpc:tcp-client-grouping 300 +-- tls-client-parameters 301 | +---u tlsc:tls-client-grouping 302 +-- http-client-parameters 303 +---u http-client-identity-grouping 305 Comments: 307 * The "http-client-grouping" defines the configuration for just 308 "HTTP" part of a protocol stack. It does not, for instance, 309 define any configuration for the "TCP" or "TLS" protocol layers 310 (for that, see Section 2.1.2.3). 312 * Beyond configuring the client's identity, via the "http-client- 313 identity-grouping" grouping discussed in Section 2.1.2.1, this 314 grouping defines support for HTTP-proxies, albeit it must be 315 enabled via a "feature" statement. 317 * The "proxy-connect" node is a "presence" container so the 318 mandatory descendant nodes do not imply that this node must be 319 configured, assuming the server supports the "proxy-connect" 320 feature. 322 * For the referenced grouping statement(s): 324 - The "http-client-identity-grouping" grouping is discussed in 325 Section 2.1.2.1. 326 - The "tcp-client-grouping" grouping is discussed in 327 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 328 - The "tls-client-grouping" grouping is discussed in 329 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 331 2.1.2.3. The "http-client-stack-grouping" Grouping 333 The following tree diagram [RFC8340] illustrates the "http-client- 334 stack-grouping" grouping: 336 grouping http-client-stack-grouping 337 +-- (transport) 338 +--:(tcp) {tcp-supported}? 339 | +-- tcp 340 | +-- tcp-client-parameters 341 | | +---u tcpc:tcp-client-grouping 342 | +-- http-client-parameters 343 | +---u http-client-grouping 344 +--:(tls) {tls-supported}? 345 +-- tls 346 +-- tcp-client-parameters 347 | +---u tcpc:tcp-client-grouping 348 +-- tls-client-parameters 349 | +---u tlsc:tls-client-grouping 350 +-- http-client-parameters 351 +---u http-client-grouping 353 Comments: 355 * The "http-client-stack-grouping" is a convenience grouping for 356 downstream modules. It defines both the "HTTP" and "HTTPS" 357 protocol stacks, with each option enabled by a "feature" statement 358 for application control. 360 * For the referenced grouping statement(s): 362 - The "tcp-client-grouping" grouping is discussed in 363 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 364 - The "tls-client-grouping" grouping is discussed in 365 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 366 - The "http-client-grouping" grouping is discussed in 367 Section 2.1.2.2 in this document. 369 2.1.3. Protocol-accessible Nodes 371 The "ietf-http-client" module defines only "grouping" statements that 372 are used by other modules to instantiate protocol-accessible nodes. 374 2.2. Example Usage 376 This section presents two examples showing the http-client-grouping 377 populated with some data. 379 The following example illustrates an HTTP client connecting directly 380 to an HTTP server. 382 383 385 386 387 388 bob 389 secret 390 391 392 394 The following example illustrates the same client connecting through 395 an HTTP proxy. This example is consistent with examples presented in 396 Section 2.2 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 397 [I-D.ietf-netconf-keystore]. 399 =============== NOTE: '\' line wrapping per RFC 8792 ================ 401 402 404 405 406 407 bob 408 secret 409 410 411 412 413 414 corp-fw2.example.com 415 416 15 417 3 418 30 419 420 421 422 423 424 425 rsa-asymmetric-key 426 ex-rsa-cert 428 429 430 431 432 433 trusted-server-ca-certs 435 436 437 trusted-server-ee-certs 439 440 441 442 443 444 445 local-app-1 446 secret 447 448 449 450 451 452 454 2.3. YANG Module 456 This YANG module has normative references to [RFC6991]. 458 file "ietf-http-client@2022-03-07.yang" 460 module ietf-http-client { 461 yang-version 1.1; 462 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 463 prefix httpc; 465 import ietf-netconf-acm { 466 prefix nacm; 467 reference 468 "RFC 8341: Network Configuration Access Control Model"; 469 } 471 import ietf-crypto-types { 472 prefix ct; 473 reference 474 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 475 } 476 import ietf-tcp-client { 477 prefix tcpc; 478 reference 479 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 480 } 482 import ietf-tls-client { 483 prefix tlsc; 484 reference 485 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 486 } 488 organization 489 "IETF NETCONF (Network Configuration) Working Group"; 491 contact 492 "WG Web: https://datatracker.ietf.org/wg/netconf 493 WG List: NETCONF WG list 494 Author: Kent Watsen "; 496 description 497 "This module defines reusable groupings for HTTP clients that 498 can be used as a basis for specific HTTP client instances. 500 Copyright (c) 2021 IETF Trust and the persons identified 501 as authors of the code. All rights reserved. 503 Redistribution and use in source and binary forms, with 504 or without modification, is permitted pursuant to, and 505 subject to the license terms contained in, the Revised 506 BSD License set forth in Section 4.c of the IETF Trust's 507 Legal Provisions Relating to IETF Documents 508 (https://trustee.ietf.org/license-info). 510 This version of this YANG module is part of RFC GGGG 511 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 512 itself for full legal notices. 514 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 515 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 516 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 517 are to be interpreted as described in BCP 14 (RFC 2119) 518 (RFC 8174) when, and only when, they appear in all 519 capitals, as shown here."; 521 revision 2022-03-07 { 522 description 523 "Initial version"; 525 reference 526 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 527 } 529 // Features 531 feature proxy-connect { 532 description 533 "Proxy connection configuration is configurable for 534 HTTP clients on the server implementing this feature."; 535 } 537 feature basic-auth { 538 description 539 "The 'basic-auth' feature indicates that the client 540 may be configured to use the 'basic' HTTP authentication 541 scheme."; 542 reference 543 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 544 } 546 feature tcp-supported { 547 description 548 "Indicates that the server supports HTTP/TCP."; 549 } 551 feature tls-supported { 552 description 553 "Indicates that the server supports HTTP/TLS."; 554 } 556 // Groupings 558 grouping http-client-identity-grouping { 559 description 560 "A grouping to provide HTTP credentials used by the 561 client to authenticate itself to the HTTP server."; 562 container client-identity { 563 nacm:default-deny-write; 564 presence 565 "Indicates that a client identity has been configured. 566 This statement is present so the mandatory descendant 567 nodes do not imply that this node must be configured."; 568 description 569 "The identity the HTTP client should use when 570 authenticating itself to the HTTP server."; 571 choice auth-type { 572 mandatory true; 573 description 574 "A choice amongst available authentication types."; 575 case basic { 576 container basic { 577 if-feature "basic-auth"; 578 leaf user-id { 579 type string; 580 mandatory true; 581 description 582 "The user-id for the authenticating client."; 583 } 584 uses ct:password-grouping { 585 description 586 "The password for the authenticating client."; 587 } 588 description 589 "The 'basic' HTTP scheme credentials."; 590 reference 591 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 592 } 593 } 594 } 595 } 596 } // grouping http-client-identity-grouping 598 grouping http-client-grouping { 599 description 600 "A reusable grouping for configuring a HTTP client. 602 This grouping is expected to be used in conjunction with 603 other configurations providing, e.g., the hostname or IP 604 address and port number the client initiates connections 605 to. 607 Note that this grouping uses fairly typical descendant 608 node names such that a stack of 'uses' statements will 609 have name conflicts. It is intended that the consuming 610 data model will resolve the issue (e.g., by wrapping 611 the 'uses' statement in a container called 612 'http-client-parameters'). This model purposely does 613 not do this itself so as to provide maximum flexibility 614 to consuming models."; 616 uses http-client-identity-grouping; 618 container proxy-connect { 619 nacm:default-deny-write; 620 if-feature "proxy-connect"; 621 presence 622 "Indicates that a proxy server connections have been 623 configured. This statement is present so the mandatory 624 descendant nodes do not imply that this node must be 625 configured."; 626 description 627 "Configures the proxy server the HTTP-client is to 628 connect thru."; 629 choice proxy-type { 630 mandatory true; 631 description 632 "Choice amongst proxy server types."; 633 case http { 634 container http-proxy { 635 description 636 "Container for HTTP Proxy (Web Proxy) server 637 configuration parameters."; 638 container tcp-client-parameters { 639 description 640 "A wrapper around the TCP parameters to avoid 641 name collisions."; 642 uses tcpc:tcp-client-grouping; 643 } 644 container http-client-parameters { 645 description 646 "A wrapper around the HTTP parameters to avoid 647 name collisions."; 648 uses http-client-identity-grouping; 649 } 650 } 651 } 652 case https { 653 container https-proxy { 654 description 655 "Container for HTTPS Proxy (Secure Web Proxy) server 656 configuration parameters."; 657 container tcp-client-parameters { 658 description 659 "A wrapper around the TCP parameters to avoid 660 name collisions."; 661 uses tcpc:tcp-client-grouping; 662 } 663 container tls-client-parameters { 664 description 665 "A wrapper around the TLS parameters to avoid 666 name collisions."; 667 uses tlsc:tls-client-grouping; 668 } 669 container http-client-parameters { 670 description 671 "A wrapper around the HTTP parameters to avoid 672 name collisions."; 673 uses http-client-identity-grouping; 674 } 675 } 676 } 677 } 678 } 679 } // grouping http-client-grouping 681 grouping http-client-stack-grouping { 682 description 683 "A grouping that defines common HTTP-based protocol stacks."; 684 choice transport { 685 mandatory true; 686 description 687 "Choice amongst various transports type. TCP, with and 688 without TLS are defined here, with 'feature' statements 689 so that they may be disabled. Other transports MAY be 690 augmented in as 'case' statements by future efforts."; 691 case tcp { 692 if-feature "tcp-supported"; 693 container tcp { 694 description 695 "Container for TCP-based HTTP protocols."; 696 container tcp-client-parameters { 697 description 698 "A wrapper around the TCP parameters to avoid 699 name collisions."; 700 uses tcpc:tcp-client-grouping; 701 } 702 container http-client-parameters { 703 description 704 "A wrapper around the HTTP parameters to avoid 705 name collisions."; 706 uses http-client-grouping; 707 } 708 } 709 } 710 case tls { 711 if-feature "tls-supported"; 712 container tls { 713 description 714 "Container for TLS-based HTTP protocols."; 715 container tcp-client-parameters { 716 description 717 "A wrapper around the TCP parameters to avoid 718 name collisions."; 719 uses tcpc:tcp-client-grouping; 720 } 721 container tls-client-parameters { 722 description 723 "A wrapper around the TLS parameters to avoid 724 name collisions."; 725 uses tlsc:tls-client-grouping; 726 } 727 container http-client-parameters { 728 description 729 "A wrapper around the HTTP parameters to avoid 730 name collisions."; 731 uses http-client-grouping; 732 } 733 } 734 } 735 } 736 } // http-client-stack-grouping 738 } 740 742 3. The "ietf-http-server" Module 744 This section defines a YANG 1.1 module called "ietf-http-server". A 745 high-level overview of the module is provided in Section 3.1. 746 Examples illustrating the module's use are provided in Examples 747 (Section 3.2). The YANG module itself is defined in Section 3.3. 749 3.1. Data Model Overview 751 This section provides an overview of the "ietf-http-server" module in 752 terms of its features and groupings. 754 3.1.1. Features 756 The following diagram lists all the "feature" statements defined in 757 the "ietf-http-server" module: 759 Features: 760 +-- client-auth-supported 761 +-- local-users-supported 762 +-- basic-auth 763 +-- tcp-supported 764 +-- tls-supported 765 | The diagram above uses syntax that is similar to but not 766 | defined in [RFC8340]. 768 3.1.2. Groupings 770 The "ietf-http-server" module defines the following "grouping" 771 statements: 773 * http-server-grouping 774 * http-server-stack-grouping 776 Each of these groupings are presented in the following subsections. 778 3.1.2.1. The "http-server-grouping" Grouping 780 The following tree diagram [RFC8340] illustrates the "http-server- 781 grouping" grouping: 783 grouping http-server-grouping 784 +-- server-name? string 785 +-- client-authentication! {client-auth-supported}? 786 +-- users {local-users-supported}? 787 +-- user* [user-id] 788 +-- user-id? string 789 +-- (auth-type) 790 +--:(basic) 791 +-- basic {basic-auth}? 792 +-- user-id? string 793 +-- password? ianach:crypt-hash 795 Comments: 797 * The "http-server-grouping" defines the configuration for just 798 "HTTP" part of a protocol stack. It does not, for instance, 799 define any configuration for the "TCP" or "TLS" protocol layers 800 (for that, see Section 3.1.2.2). 802 * The "server-name" node defines the HTTP server's name, as 803 presented to HTTP clients. 805 * The "client-authentication" node, which must by enabled by a 806 feature, defines a very simple user-database. Only the "basic" 807 authentication scheme is supported, albeit it must be enabled by a 808 "feature". Other authentication schemes MAY be augmented in. 810 3.1.2.2. The "http-server-stack-grouping" Grouping 812 The following tree diagram [RFC8340] illustrates the "http-server- 813 stack-grouping" grouping: 815 grouping http-server-stack-grouping 816 +-- (transport) 817 +--:(tcp) {tcp-supported}? 818 | +-- tcp 819 | +-- tcp-server-parameters 820 | | +---u tcps:tcp-server-grouping 821 | +-- http-server-parameters 822 | +---u http-server-grouping 823 +--:(tls) {tls-supported}? 824 +-- tls 825 +-- tcp-server-parameters 826 | +---u tcps:tcp-server-grouping 827 +-- tls-server-parameters 828 | +---u tlss:tls-server-grouping 829 +-- http-server-parameters 830 +---u http-server-grouping 832 Comments: 834 * The "http-server-stack-grouping" is a convenience grouping for 835 downstream modules. It defines both the "HTTP" and "HTTPS" 836 protocol stacks, with each option enabled by a "feature" statement 837 for application control. 839 * For the referenced grouping statement(s): 841 - The "tcp-server-grouping" grouping is discussed in 842 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 843 - The "tls-server-grouping" grouping is discussed in 844 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 845 - The "http-server-grouping" grouping is discussed in 846 Section 3.1.2.1 in this document. 848 3.1.3. Protocol-accessible Nodes 850 The "ietf-http-server" module defines only "grouping" statements that 851 are used by other modules to instantiate protocol-accessible nodes. 853 3.2. Example Usage 855 This section presents an example showing the http-server-grouping 856 populated with some data. 858 859 861 862 foo.example.com 863 865 3.3. YANG Module 867 This YANG module has normative references to [RFC6991]. 869 file "ietf-http-server@2022-03-07.yang" 871 module ietf-http-server { 872 yang-version 1.1; 873 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 874 prefix https; 876 import iana-crypt-hash { 877 prefix ianach; 878 reference 879 "RFC 7317: A YANG Data Model for System Management"; 880 } 882 import ietf-netconf-acm { 883 prefix nacm; 884 reference 885 "RFC 8341: Network Configuration Access Control Model"; 886 } 888 import ietf-tcp-server { 889 prefix tcps; 890 reference 891 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 892 } 894 import ietf-tls-server { 895 prefix tlss; 896 reference 897 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 898 } 900 organization 901 "IETF NETCONF (Network Configuration) Working Group"; 903 contact 904 "WG Web: https://datatracker.ietf.org/wg/netconf 905 WG List: NETCONF WG list 906 Author: Kent Watsen "; 908 description 909 "This module defines reusable groupings for HTTP servers that 910 can be used as a basis for specific HTTP server instances. 912 Copyright (c) 2021 IETF Trust and the persons identified 913 as authors of the code. All rights reserved. 915 Redistribution and use in source and binary forms, with 916 or without modification, is permitted pursuant to, and 917 subject to the license terms contained in, the Revised 918 BSD License set forth in Section 4.c of the IETF Trust's 919 Legal Provisions Relating to IETF Documents 920 (https://trustee.ietf.org/license-info). 922 This version of this YANG module is part of RFC GGGG 923 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 924 itself for full legal notices. 926 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 927 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 928 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 929 are to be interpreted as described in BCP 14 (RFC 2119) 930 (RFC 8174) when, and only when, they appear in all 931 capitals, as shown here."; 933 revision 2022-03-07 { 934 description 935 "Initial version"; 936 reference 937 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 938 } 940 // Features 942 feature client-auth-supported { 943 description 944 "Indicates that the configuration for how to authenticate 945 clients can be configured herein. HTTP-level client 946 authentication may not be needed when client authentication 947 is expected to occur only at another protocol layer."; 948 } 950 feature local-users-supported { 951 description 952 "Indicates that the configuration for users can be 953 configured herein, as opposed to in an application 954 specific location."; 955 } 957 feature basic-auth { 958 description 959 "The 'basic-auth' feature indicates that the server 960 may be configured authenticate users using the 'basic' 961 HTTP authentication scheme."; 962 reference 963 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 964 } 966 feature tcp-supported { 967 description 968 "Indicates that the server supports HTTP/TCP."; 969 } 971 feature tls-supported { 972 description 973 "Indicates that the server supports HTTP/TLS."; 974 } 976 // Groupings 978 grouping http-server-grouping { 979 description 980 "A reusable grouping for configuring an HTTP server. 982 Note that this grouping uses fairly typical descendant 983 node names such that a stack of 'uses' statements will 984 have name conflicts. It is intended that the consuming 985 data model will resolve the issue (e.g., by wrapping 986 the 'uses' statement in a container called 987 'http-server-parameters'). This model purposely does 988 not do this itself so as to provide maximum flexibility 989 to consuming models."; 991 leaf server-name { 992 nacm:default-deny-write; 993 type string; 994 description 995 "The value of the 'Server' header field. If not set, then 996 underlying software's default value is used. Set to the 997 empty string to disable."; 998 } 1000 container client-authentication { 1001 if-feature "client-auth-supported"; 1002 nacm:default-deny-write; 1003 presence 1004 "Indicates that HTTP based client authentication is 1005 configured. This statement is present so the mandatory 1006 descendant nodes do not imply that this node must be 1007 configured."; 1008 description 1009 "Configures how the HTTP server can authenticate HTTP 1010 clients. The HTTP server will request that the HTTP 1011 client send authentication when needed."; 1012 container users { 1013 if-feature "local-users-supported"; 1014 description 1015 "A list of locally configured users."; 1016 list user { 1017 key "user-id"; 1018 description 1019 "The list of local users configured on this device."; 1020 leaf user-id { 1021 type string; 1022 description 1023 "The user-id for the authenticating client."; 1024 } 1025 choice auth-type { 1026 mandatory true; 1027 description 1028 "The authentication type."; 1029 case basic { 1030 container basic { 1031 if-feature "basic-auth"; 1032 leaf user-id { 1033 type string; 1034 description 1035 "The user-id for the authenticating client."; 1036 } 1037 leaf password { 1038 nacm:default-deny-write; 1039 type ianach:crypt-hash; 1040 description 1041 "The password for the authenticating client."; 1042 } 1043 description 1044 "The 'basic' HTTP scheme credentials."; 1045 reference 1046 "RFC 7617: 1047 The 'Basic' HTTP Authentication Scheme"; 1048 } 1049 } 1051 } 1052 } 1053 } 1054 } // container client-authentication 1055 } // grouping http-server-grouping 1057 grouping http-server-stack-grouping { 1058 description 1059 "A grouping that defines common HTTP-based protocol stacks."; 1060 choice transport { 1061 mandatory true; 1062 description 1063 "Choice amongst various transports type. TCP, with and 1064 without TLS are defined here, with 'feature' statements 1065 so that they may be disabled. Other transports MAY be 1066 augmented in as 'case' statements by future efforts."; 1067 case tcp { 1068 if-feature "tcp-supported"; 1069 container tcp { 1070 description 1071 "Container for TCP-based HTTP protocols."; 1072 container tcp-server-parameters { 1073 description 1074 "A wrapper around the TCP parameters to avoid 1075 name collisions."; 1076 uses tcps:tcp-server-grouping; 1077 } 1078 container http-server-parameters { 1079 description 1080 "A wrapper around the HTTP parameters to avoid 1081 name collisions."; 1082 uses http-server-grouping; 1083 } 1084 } 1085 } 1086 case tls { 1087 if-feature "tls-supported"; 1088 container tls { 1089 description 1090 "Container for TLS-based HTTP protocols."; 1091 container tcp-server-parameters { 1092 description 1093 "A wrapper around the TCP parameters to avoid 1094 name collisions."; 1095 uses tcps:tcp-server-grouping; 1096 } 1097 container tls-server-parameters { 1098 description 1099 "A wrapper around the TLS parameters to avoid 1100 name collisions."; 1101 uses tlss:tls-server-grouping; 1102 } 1103 container http-server-parameters { 1104 description 1105 "A wrapper around the HTTP parameters to avoid 1106 name collisions."; 1107 uses http-server-grouping; 1108 } 1109 } 1110 } 1111 } 1112 } // http-server-stack-grouping 1114 } 1116 1118 4. Security Considerations 1120 4.1. The "ietf-http-client" YANG Module 1122 The "ietf-http-client" YANG module defines "grouping" statements that 1123 are designed to be accessed via YANG based management protocols, such 1124 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1125 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1126 with mutual authentication. 1128 The NETCONF access control model (NACM) [RFC8341] provides the means 1129 to restrict access for particular users to a pre-configured subset of 1130 all available protocol operations and content. 1132 Since the module in this document only define groupings, these 1133 considerations are primarily for the designers of other modules that 1134 use these groupings. 1136 One readable data node defined in this YANG module may be considered 1137 sensitive or vulnerable in some network environments. This node is 1138 as follows: 1140 * The "client-identity/basic/password" node: 1142 The cleartext "password" node defined in the "http-client- 1143 identity-grouping" grouping is additionally sensitive to read 1144 operations such that, in normal use cases, it should never be 1145 returned to a client. For this reason, the NACM extension 1146 "default-deny-all" has been applied to it. 1148 | Please be aware that this module uses the "key" and "private- 1149 | key" nodes from the "ietf-crypto-types" module 1150 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 1151 | extension "default-deny-all" set, thus preventing unrestricted 1152 | read-access to the cleartext key values. 1154 None of the writable data nodes defined in this YANG module are 1155 considered sensitive or vulnerable in network environments. The NACM 1156 "default-deny-write" extension has not been set for any data nodes 1157 defined in this module. 1159 | Please be aware that this module uses groupings from the "ietf- 1160 | tls-client" and "ietf-tls-server" modules defined in 1161 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1162 | defined in these groupings have the NACM extension "default- 1163 | deny-write" set, thus preventing unrestricted write-access to 1164 | the data nodes defined in those groupings. 1166 This module does not define any RPCs, actions, or notifications, and 1167 thus the security consideration for such is not provided here. 1169 4.2. The "ietf-http-server" YANG Module 1171 The "ietf-http-server" YANG module defines "grouping" statements that 1172 are designed to be accessed via YANG based management protocols, such 1173 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1174 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1175 with mutual authentication. 1177 The NETCONF access control model (NACM) [RFC8341] provides the means 1178 to restrict access for particular users to a pre-configured subset of 1179 all available protocol operations and content. 1181 Since the module in this document only define groupings, these 1182 considerations are primarily for the designers of other modules that 1183 use these groupings. 1185 None of the readable data nodes defined in this YANG module are 1186 considered sensitive or vulnerable in network environments. The NACM 1187 "default-deny-all" extension has not been set for any data nodes 1188 defined in this module. 1190 None of the writable data nodes defined in this YANG module are 1191 considered sensitive or vulnerable in network environments. The NACM 1192 "default-deny-write" extension has not been set for any data nodes 1193 defined in this module. 1195 | Please be aware that this module uses groupings from the "ietf- 1196 | tls-client" and "ietf-tls-server" modules defined in 1197 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1198 | defined in these groupings have the NACM extension "default- 1199 | deny-write" set, thus preventing unrestricted write-access to 1200 | the data nodes defined in those groupings. 1202 This module does not define any RPCs, actions, or notifications, and 1203 thus the security consideration for such is not provided here. 1205 5. IANA Considerations 1207 5.1. The "IETF XML" Registry 1209 This document registers two URIs in the "ns" subregistry of the IETF 1210 XML Registry [RFC3688]. Following the format in [RFC3688], the 1211 following registrations are requested: 1213 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 1214 Registrant Contact: The IESG 1215 XML: N/A, the requested URI is an XML namespace. 1217 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 1218 Registrant Contact: The IESG 1219 XML: N/A, the requested URI is an XML namespace. 1221 5.2. The "YANG Module Names" Registry 1223 This document registers two YANG modules in the YANG Module Names 1224 registry [RFC6020]. Following the format in [RFC6020], the following 1225 registrations are requested: 1227 name: ietf-http-client 1228 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 1229 prefix: httpc 1230 reference: RFC GGGG 1232 name: ietf-http-server 1233 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 1234 prefix: https 1235 reference: RFC GGGG 1237 6. References 1239 6.1. Normative References 1241 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1242 Requirement Levels", BCP 14, RFC 2119, 1243 DOI 10.17487/RFC2119, March 1997, 1244 . 1246 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1247 the Network Configuration Protocol (NETCONF)", RFC 6020, 1248 DOI 10.17487/RFC6020, October 2010, 1249 . 1251 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1252 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1253 . 1255 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1256 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1257 . 1259 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1260 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1261 May 2017, . 1263 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1264 Access Control Model", STD 91, RFC 8341, 1265 DOI 10.17487/RFC8341, March 2018, 1266 . 1268 6.2. Informative References 1270 [I-D.ietf-netconf-crypto-types] 1271 Watsen, K., "YANG Data Types and Groupings for 1272 Cryptography", Work in Progress, Internet-Draft, draft- 1273 ietf-netconf-crypto-types-21, 14 September 2021, 1274 . 1277 [I-D.ietf-netconf-http-client-server] 1278 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1279 Servers", Work in Progress, Internet-Draft, draft-ietf- 1280 netconf-http-client-server-08, 14 December 2021, 1281 . 1284 [I-D.ietf-netconf-keystore] 1285 Watsen, K., "A YANG Data Model for a Keystore", Work in 1286 Progress, Internet-Draft, draft-ietf-netconf-keystore-23, 1287 14 December 2021, . 1290 [I-D.ietf-netconf-netconf-client-server] 1291 Watsen, K., "NETCONF Client and Server Models", Work in 1292 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1293 client-server-24, 14 December 2021, 1294 . 1297 [I-D.ietf-netconf-restconf-client-server] 1298 Watsen, K., "RESTCONF Client and Server Models", Work in 1299 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1300 client-server-24, 14 December 2021, 1301 . 1304 [I-D.ietf-netconf-ssh-client-server] 1305 Watsen, K., "YANG Groupings for SSH Clients and SSH 1306 Servers", Work in Progress, Internet-Draft, draft-ietf- 1307 netconf-ssh-client-server-26, 14 December 2021, 1308 . 1311 [I-D.ietf-netconf-tcp-client-server] 1312 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1313 and TCP Servers", Work in Progress, Internet-Draft, draft- 1314 ietf-netconf-tcp-client-server-11, 14 December 2021, 1315 . 1318 [I-D.ietf-netconf-tls-client-server] 1319 Watsen, K., "YANG Groupings for TLS Clients and TLS 1320 Servers", Work in Progress, Internet-Draft, draft-ietf- 1321 netconf-tls-client-server-26, 14 December 2021, 1322 . 1325 [I-D.ietf-netconf-trust-anchors] 1326 Watsen, K., "A YANG Data Model for a Truststore", Work in 1327 Progress, Internet-Draft, draft-ietf-netconf-trust- 1328 anchors-16, 14 December 2021, 1329 . 1332 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1333 DOI 10.17487/RFC3688, January 2004, 1334 . 1336 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1337 and A. Bierman, Ed., "Network Configuration Protocol 1338 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1339 . 1341 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1342 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1343 . 1345 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1346 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1347 . 1349 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1350 and R. Wilton, "Network Management Datastore Architecture 1351 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1352 . 1354 Appendix A. Change Log 1356 This section is to be removed before publishing as an RFC. 1358 A.1. 00 to 01 1360 * Modified Abstract and Intro to be more accurate wrt intended 1361 applicability. 1363 * In ietf-http-client, removed "protocol-version" and all auth 1364 schemes except "basic". 1366 * In ietf-http-client, factored out "client-identity-grouping" for 1367 proxy connections. 1369 * In ietf-http-server, removed "choice required-or-optional" and 1370 "choice local-or-external". 1372 * In ietf-http-server, moved the basic auth under a "choice auth- 1373 type" limited by new "feature basic-auth". 1375 A.2. 01 to 02 1377 * Removed the unused "external-client-auth-supported" feature from 1378 ietf-http-server. 1380 A.3. 02 to 03 1382 * Removed "protocol-versions" from ietf-http-server based on HTTP WG 1383 feedback. 1385 * Slightly restructured the "proxy-server" definition in ietf-http- 1386 client. 1388 * Added http-client example show proxy server use. 1390 * Added a "Note to Reviewers" note to first page. 1392 A.4. 03 to 04 1394 * Added a parent "container" to "client-identity-grouping" so that 1395 it could be better used by the proxy model. 1397 * Added a "choice" to the proxy model enabling selection of proxy 1398 types. 1400 * Added 'http-client-stack-grouping' and 'http-server-stack- 1401 grouping' convenience groupings. 1403 * Expanded "Data Model Overview section(s) [remove "wall" of tree 1404 diagrams]. 1406 * Updated the Security Considerations section. 1408 A.5. 04 to 05 1410 * Fixed titles and a ref in the IANA Considerations section 1412 * Cleaned up examples (e.g., removed FIXMEs) 1414 * Fixed issues found by the SecDir review of the "keystore" draft. 1416 * Updated the "ietf-http-client" module to use the new "password- 1417 grouping" grouping from the "crypto-types" module. 1419 A.6. 05 to 06 1421 * Removed note questioning if okay for app to augment-in a 'path' 1422 node when needed, discussed during the 108 session. 1424 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 1426 A.7. 06 to 07 1428 * Added XML-comment above examples explaining the reason for the 1429 unusual top-most element's presence. 1431 * Renamed 'client-auth-config-supported' to 'client-auth-supported' 1432 consistent with other drafts. 1434 * Wrapped 'container basic' choice inside a 'case basic' per best 1435 practice. 1437 * Aligned modules with `pyang -f` formatting. 1439 * Fixed nits found by YANG Doctor reviews. 1441 A.8. 07 to 08 1443 * Replaced "base64encodedvalue==" with "BASE64VALUE=" in examples. 1445 * Minor editorial nits 1447 A.9. 08 to 09 1449 * Fixed up the 'WG Web' and 'WG List' lines in YANG module(s) 1451 * Fixed up copyright (i.e., s/Simplified/Revised/) in YANG module(s) 1453 Acknowledgements 1455 The authors would like to thank for following for lively discussions 1456 on list and in the halls (ordered by first name): Ben Schwartz, Mark 1457 Nottingham, Rob Wilton (contributor), and Willy Tarreau. 1459 Author's Address 1461 Kent Watsen 1462 Watsen Networks 1463 Email: kent+ietf@watsen.net