idnits 2.17.1 draft-ietf-netconf-http-client-server-06.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 (10 February 2021) is 1142 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-18 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-05 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-20 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-21 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-21 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-22 == Outdated reference: A later version (-24) exists of draft-ietf-netconf-tcp-client-server-08 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-22 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-13 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 10 February 2021 5 Expires: 14 August 2021 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-06 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 * "BBBB" --> the assigned RFC value for draft-ietf-netconf-trust- 34 anchors 36 * "CCCC" --> the assigned RFC value for draft-ietf-netconf-keystore 38 * "DDDD" --> the assigned RFC value for draft-ietf-netconf-tcp- 39 client-server 41 * "EEEE" --> the assigned RFC value for draft-ietf-netconf-ssh- 42 client-server 44 * "FFFF" --> the assigned RFC value for draft-ietf-netconf-tls- 45 client-server 47 * "GGGG" --> the assigned RFC value for this draft 48 Artwork in this document contains placeholder values for the date of 49 publication of this draft. Please apply the following replacement: 51 * "2021-02-10" --> the publication date of this draft 53 The following Appendix section is to be removed prior to publication: 55 * Appendix A. Change Log 57 Status of This Memo 59 This Internet-Draft is submitted in full conformance with the 60 provisions of BCP 78 and BCP 79. 62 Internet-Drafts are working documents of the Internet Engineering 63 Task Force (IETF). Note that other groups may also distribute 64 working documents as Internet-Drafts. The list of current Internet- 65 Drafts is at https://datatracker.ietf.org/drafts/current/. 67 Internet-Drafts are draft documents valid for a maximum of six months 68 and may be updated, replaced, or obsoleted by other documents at any 69 time. It is inappropriate to use Internet-Drafts as reference 70 material or to cite them other than as "work in progress." 72 This Internet-Draft will expire on 14 August 2021. 74 Copyright Notice 76 Copyright (c) 2021 IETF Trust and the persons identified as the 77 document authors. All rights reserved. 79 This document is subject to BCP 78 and the IETF Trust's Legal 80 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 81 license-info) in effect on the date of publication of this document. 82 Please review these documents carefully, as they describe your rights 83 and restrictions with respect to this document. Code Components 84 extracted from this document must include Simplified BSD License text 85 as described in Section 4.e of the Trust Legal Provisions and are 86 provided without warranty as described in the Simplified BSD License. 88 Table of Contents 90 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 91 1.1. Relation to other RFCs . . . . . . . . . . . . . . . . . 3 92 1.2. Specification Language . . . . . . . . . . . . . . . . . 5 93 1.3. Adherence to the NMDA . . . . . . . . . . . . . . . . . . 5 94 2. The "ietf-http-client" Module . . . . . . . . . . . . . . . . 5 95 2.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 6 96 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 9 97 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 98 3. The "ietf-http-server" Module . . . . . . . . . . . . . . . . 16 99 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 17 100 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 19 101 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 19 102 4. Security Considerations . . . . . . . . . . . . . . . . . . . 24 103 4.1. The "ietf-http-client" YANG Module . . . . . . . . . . . 24 104 4.2. The "ietf-http-server" YANG Module . . . . . . . . . . . 25 105 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 106 5.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 26 107 5.2. The "YANG Module Names" Registry . . . . . . . . . . . . 26 108 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 109 6.1. Normative References . . . . . . . . . . . . . . . . . . 27 110 6.2. Informative References . . . . . . . . . . . . . . . . . 27 111 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 29 112 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 29 113 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 29 114 A.3. 02 to 03 . . . . . . . . . . . . . . . . . . . . . . . . 30 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 30 116 A.5. 04 to 05 . . . . . . . . . . . . . . . . . . . . . . . . 30 117 A.6. 05 to 06 . . . . . . . . . . . . . . . . . . . . . . . . 30 118 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 31 119 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31 121 1. Introduction 123 This document defines two YANG 1.1 [RFC7950] modules: the first 124 defines a minimal grouping for configuring an HTTP client, and the 125 second defines a minimal grouping for configuring an HTTP server. It 126 is intended that these groupings will be used to help define the 127 configuration for simple HTTP-based protocols (not for complete web 128 servers or browsers). 130 1.1. Relation to other RFCs 132 This document presents one or more YANG modules [RFC7950] that are 133 part of a collection of RFCs that work together to, ultimately, 134 enable the configuration of the clients and servers of both the 135 NETCONF [RFC6241] and RESTCONF [RFC8040] protocols. 137 The modules have been defined in a modular fashion to enable their 138 use by other efforts, some of which are known to be in progress at 139 the time of this writing, with many more expected to be defined in 140 time. 142 The normative dependency relationship between the various RFCs in the 143 collection is presented in the below diagram. The labels in the 144 diagram represent the primary purpose provided by each RFC. 145 Hyperlinks to each RFC are provided below the diagram. 147 crypto-types 148 ^ ^ 149 / \ 150 / \ 151 truststore keystore 152 ^ ^ ^ ^ 153 | +---------+ | | 154 | | | | 155 | +------------+ | 156 tcp-client-server | / | | 157 ^ ^ ssh-client-server | | 158 | | ^ tls-client-server 159 | | | ^ ^ http-client-server 160 | | | | | ^ 161 | | | +-----+ +---------+ | 162 | | | | | | 163 | +-----------|--------|--------------+ | | 164 | | | | | | 165 +-----------+ | | | | | 166 | | | | | | 167 | | | | | | 168 netconf-client-server restconf-client-server 170 +=======================+===========================================+ 171 |Label in Diagram | Originating RFC | 172 +=======================+===========================================+ 173 |crypto-types | [I-D.ietf-netconf-crypto-types] | 174 +-----------------------+-------------------------------------------+ 175 |truststore | [I-D.ietf-netconf-trust-anchors] | 176 +-----------------------+-------------------------------------------+ 177 |keystore | [I-D.ietf-netconf-keystore] | 178 +-----------------------+-------------------------------------------+ 179 |tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 180 +-----------------------+-------------------------------------------+ 181 |ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 182 +-----------------------+-------------------------------------------+ 183 |tls-client-server | [I-D.ietf-netconf-tls-client-server] | 184 +-----------------------+-------------------------------------------+ 185 |http-client-server | [I-D.ietf-netconf-http-client-server] | 186 +-----------------------+-------------------------------------------+ 187 |netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 188 +-----------------------+-------------------------------------------+ 189 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 190 +-----------------------+-------------------------------------------+ 192 Table 1: Label to RFC Mapping 194 1.2. Specification Language 196 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 197 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 198 "OPTIONAL" in this document are to be interpreted as described in BCP 199 14 [RFC2119] [RFC8174] when, and only when, they appear in all 200 capitals, as shown here. 202 1.3. Adherence to the NMDA 204 This document in compliant with the Network Management Datastore 205 Architecture (NMDA) [RFC8342]. For instance, as described in 206 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 207 trust anchors and keys installed during manufacturing are expected to 208 appear in . 210 2. The "ietf-http-client" Module 212 This section defines a YANG 1.1 [RFC7950] module called "ietf-http- 213 client". A high-level overview of the module is provided in 214 Section 2.1. Examples illustatrating the module's use are provided 215 in Examples (Section 2.2). The YANG module itself is defined in 216 Section 2.3. 218 2.1. Data Model Overview 220 This section provides an overview of the "ietf-http-client" module in 221 terms of its features and groupings. 223 2.1.1. Features 225 The following diagram lists all the "feature" statements defined in 226 the "ietf-http-client" module: 228 Features: 229 +-- proxy-connect 230 +-- basic-auth 231 +-- tcp-supported 232 +-- tls-supported 234 | The diagram above uses syntax that is similar to but not 235 | defined in [RFC8340]. 237 2.1.2. Groupings 239 The "ietf-http-client" module defines the following "grouping" 240 statements: 242 * http-client-identity-grouping 243 * http-client-grouping 244 * http-client-stack-grouping 246 Each of these groupings are presented in the following subsections. 248 2.1.2.1. The "http-client-identity-grouping" Grouping 250 The following tree diagram [RFC8340] illustrates the "http-client- 251 identity-grouping" grouping: 253 grouping http-client-identity-grouping 254 +-- client-identity! 255 +-- (auth-type) 256 +--:(basic) 257 +-- basic {basic-auth}? 258 +-- user-id string 259 +---u ct:password-grouping 261 Comments: 263 * This grouping exists because it is used three times by the "http- 264 client-grouping" discussed in Section 2.1.2.2. 266 * The "client-identity" node is a "presence" container so that its 267 descendent "choice" node's "mandatory true" doesn't imply that a 268 client identity must be configured, as a client identity may be 269 configured at protocol layers. 271 * The "basic" authentication scheme is the only scheme defined by 272 this module, albeit it must be enabled via the "basic-auth" 273 feature (see Section 2.1.1). 275 * Other authentication schemes MAY be augmented in as needed by the 276 application. 278 2.1.2.2. The "http-client-grouping" Grouping 280 The following tree diagram [RFC8340] illustrates the "http-client- 281 grouping" grouping: 283 grouping http-client-grouping 284 +---u http-client-identity-grouping 285 +-- proxy-connect! {proxy-connect}? 286 +-- (proxy-type) 287 +--:(http) 288 | +-- http-proxy 289 | +-- tcp-client-parameters 290 | | +---u tcpc:tcp-client-grouping 291 | +-- http-client-parameters 292 | +---u http-client-identity-grouping 293 +--:(https) 294 +-- https-proxy 295 +-- tcp-client-parameters 296 | +---u tcpc:tcp-client-grouping 297 +-- tls-client-parameters 298 | +---u tlsc:tls-client-grouping 299 +-- http-client-parameters 300 +---u http-client-identity-grouping 302 Comments: 304 * The "http-client-grouping" defines the configuration for just 305 "HTTP" part of a protocol stack. It does not, for instance, 306 define any configuration for the "TCP" or "TLS" protocol layers 307 (for that, see Section 2.1.2.3). 309 * Beyond configuring the client's identity, via the "http-client- 310 identity-grouping" grouping discussed in Section 2.1.2.1, this 311 grouping defines support for HTTP-proxies, albeit it must be 312 enabled via a "feature" statement. 314 * The "proxy-connect" node is a "presence" container so that its 315 descendent "choice" node's "mandatory true" doesn't imply that a 316 proxy connection must be configured, assuming the server supports 317 the "proxy-connect" feature. 319 * For the referenced grouping statement(s): 321 - The "http-client-identity-grouping" grouping is discussed in 322 Section 2.1.2.1. 323 - The "tcp-client-grouping" grouping is discussed in 324 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 325 - The "tls-client-grouping" grouping is discussed in 326 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 328 2.1.2.3. The "http-client-stack-grouping" Grouping 330 The following tree diagram [RFC8340] illustrates the "http-client- 331 stack-grouping" grouping: 333 grouping http-client-stack-grouping 334 +-- (transport) 335 +--:(tcp) {tcp-supported}? 336 | +-- tcp 337 | +-- tcp-client-parameters 338 | | +---u tcpc:tcp-client-grouping 339 | +-- http-client-parameters 340 | +---u http-client-grouping 341 +--:(tls) {tls-supported}? 342 +-- tls 343 +-- tcp-client-parameters 344 | +---u tcpc:tcp-client-grouping 345 +-- tls-client-parameters 346 | +---u tlsc:tls-client-grouping 347 +-- http-client-parameters 348 +---u http-client-grouping 350 Comments: 352 * The "http-client-stack-grouping" is a convenience grouping for 353 downstream modules. It defines both the "HTTP" and "HTTPS" 354 protocol stacks, with each option enabled by a "feature" statement 355 for application control. 357 * For the referenced grouping statement(s): 359 - The "tcp-client-grouping" grouping is discussed in 360 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 362 - The "tls-client-grouping" grouping is discussed in 363 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 364 - The "http-client-grouping" grouping is discussed in 365 Section 2.1.2.2 in this document. 367 2.1.3. Protocol-accessible Nodes 369 The "ietf-http-client" module does not contain any protocol- 370 accessible nodes. 372 2.2. Example Usage 374 This section presents two examples showing the http-client-grouping 375 populated with some data. 377 The following example illustrates an HTTP client connecting directly 378 to an HTTP server. 380 381 382 383 bob 384 secret 385 386 387 389 The following example illustrates the same client connecting through 390 an HTTP proxy. This example is consistent with examples presented in 391 Section 2.2 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 392 [I-D.ietf-netconf-keystore]. 394 =============== NOTE: '\' line wrapping per RFC 8792 ================ 396 397 398 399 bob 400 secret 401 402 403 404 405 406 corp-fw2.example.com 407 408 15 409 3 410 30 411 412 413 414 415 416 417 rsa-asymmetric-key 418 ex-rsa-cert 419 420 421 422 423 424 trusted-server-ca-certs 426 427 428 trusted-server-ee-certs 430 431 432 433 434 435 436 local-app-1 437 secret 438 439 440 441 442 443 445 2.3. YANG Module 447 This YANG module has normative references to [RFC6991]. 449 file "ietf-http-client@2021-02-10.yang" 451 module ietf-http-client { 452 yang-version 1.1; 453 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 454 prefix httpc; 456 import ietf-netconf-acm { 457 prefix nacm; 458 reference 459 "RFC 8341: Network Configuration Access Control Model"; 460 } 462 import ietf-crypto-types { 463 prefix ct; 464 reference 465 "RFC AAAA: YANG Data Types and Groupings for Cryptography"; 466 } 468 import ietf-tcp-client { 469 prefix tcpc; 470 reference 471 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 472 } 474 import ietf-tls-client { 475 prefix tlsc; 476 reference 477 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 478 } 480 organization 481 "IETF NETCONF (Network Configuration) Working Group"; 483 contact 484 "WG Web: 485 WG List: 486 Author: Kent Watsen "; 488 description 489 "This module defines reusable groupings for HTTP clients that 490 can be used as a basis for specific HTTP client instances. 492 Copyright (c) 2020 IETF Trust and the persons identified 493 as authors of the code. All rights reserved. 495 Redistribution and use in source and binary forms, with 496 or without modification, is permitted pursuant to, and 497 subject to the license terms contained in, the Simplified 498 BSD License set forth in Section 4.c of the IETF Trust's 499 Legal Provisions Relating to IETF Documents 500 (https://trustee.ietf.org/license-info). 502 This version of this YANG module is part of RFC GGGG 503 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 504 itself for full legal notices. 506 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 507 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 508 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 509 are to be interpreted as described in BCP 14 (RFC 2119) 510 (RFC 8174) when, and only when, they appear in all 511 capitals, as shown here."; 513 revision 2021-02-10 { 514 description 515 "Initial version"; 516 reference 517 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 518 } 520 // Features 522 feature proxy-connect { 523 description 524 "Proxy connection configuration is configurable for 525 HTTP clients on the server implementing this feature."; 526 } 528 feature basic-auth { 529 description 530 "The 'basic-auth' feature indicates that the client 531 may be configured to use the 'basic' HTTP authentication 532 scheme."; 533 reference 534 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 535 } 537 feature tcp-supported { 538 description 539 "Indicates that the server supports HTTP/TCP."; 540 } 542 feature tls-supported { 543 description 544 "Indicates that the server supports HTTP/TLS."; 545 } 547 // Groupings 549 grouping http-client-identity-grouping { 550 description 551 "A grouping to provide HTTP credentials used by the 552 client to authenticate itself to the HTTP server."; 554 container client-identity { 555 nacm:default-deny-write; 556 presence 557 "Indicates that HTTP-level client authentication 558 is sent. Present so that the 'choice' node's 559 mandatory true doesn't imply that a client 560 identity must be configured."; 561 description 562 "The identity the HTTP client should use when 563 authenticating itself to the HTTP server."; 564 choice auth-type { 565 mandatory true; 566 description 567 "A choice amongst available authentication types."; 568 case basic { 569 container basic { 570 if-feature "basic-auth"; 571 leaf user-id { 572 type string; 573 mandatory true; 574 description 575 "The user-id for the authenticating client."; 576 } 577 uses ct:password-grouping { 578 description 579 "The password for the authenticating client."; 580 } 581 description 582 "The 'basic' HTTP scheme credentials."; 583 reference 584 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 585 } 586 } 587 } 588 } 589 } // grouping http-client-identity-grouping 591 grouping http-client-grouping { 592 description 593 "A reusable grouping for configuring a HTTP client. 595 This grouping is expected to be used in conjunction with 596 other configurations providing, e.g., the hostname or IP 597 address and port number the client initiates connections 598 to. 600 Note that this grouping uses fairly typical descendent 601 node names such that a stack of 'uses' statements will 602 have name conflicts. It is intended that the consuming 603 data model will resolve the issue (e.g., by wrapping 604 the 'uses' statement in a container called 605 'http-client-parameters'). This model purposely does 606 not do this itself so as to provide maximum flexibility 607 to consuming models."; 609 uses http-client-identity-grouping; 611 container proxy-connect { 612 nacm:default-deny-write; 613 if-feature "proxy-connect"; 614 presence 615 "Indicates that the HTTP-client is to connect thru an 616 HTTP-level proxy server. Present so that the 'choice' 617 node's mandatory true doesn't imply that a proxy 618 connection must be configured."; 619 choice proxy-type { 620 mandatory true; 621 description 622 "Choice amongst proxy server types."; 623 case http { 624 container http-proxy { 625 description 626 "Container for HTTP Proxy (Web Proxy) server 627 configuration parameters."; 628 container tcp-client-parameters { 629 description 630 "A wrapper around the TCP parameters to avoid 631 name collisions."; 632 uses "tcpc:tcp-client-grouping"; 633 } 634 container http-client-parameters { 635 description 636 "A wrapper around the HTTP parameters to avoid 637 name collisions."; 638 uses http-client-identity-grouping; 639 } 640 } 641 } 642 case https { 643 container https-proxy { 644 description 645 "Container for HTTPS Proxy (Secure Web Proxy) server 646 configuration parameters."; 647 container tcp-client-parameters { 648 description 649 "A wrapper around the TCP parameters to avoid 650 name collisions."; 651 uses "tcpc:tcp-client-grouping"; 652 } 653 container tls-client-parameters { 654 description 655 "A wrapper around the TLS parameters to avoid 656 name collisions."; 657 uses "tlsc:tls-client-grouping"; 658 } 659 container http-client-parameters { 660 description 661 "A wrapper around the HTTP parameters to avoid 662 name collisions."; 663 uses http-client-identity-grouping; 664 } 665 } 666 } 667 } 668 description 669 "Proxy server settings."; 670 } 671 } // grouping http-client-grouping 673 grouping http-client-stack-grouping { 674 description 675 "A grouping that defines common HTTP-based protocol stacks."; 676 choice transport { 677 mandatory true; 678 description 679 "Choice amongst various transports type. TCP, with and 680 without TLS are defined here, with 'feature' statements 681 so that they may be disabled. Other transports MAY be 682 augmented in as 'case' statements by future efforts."; 683 case tcp { 684 if-feature tcp-supported; 685 container tcp { 686 description 687 "Container for TCP-based HTTP protocols."; 688 container tcp-client-parameters { 689 description 690 "A wrapper around the TCP parameters to avoid 691 name collisions."; 692 uses "tcpc:tcp-client-grouping"; 693 } 694 container http-client-parameters { 695 description 696 "A wrapper around the HTTP parameters to avoid 697 name collisions."; 698 uses http-client-grouping; 699 } 700 } 701 } 702 case tls { 703 if-feature tls-supported; 704 container tls { 705 description 706 "Container for TLS-based HTTP protocols."; 707 container tcp-client-parameters { 708 description 709 "A wrapper around the TCP parameters to avoid 710 name collisions."; 711 uses "tcpc:tcp-client-grouping"; 712 } 713 container tls-client-parameters { 714 description 715 "A wrapper around the TLS parameters to avoid 716 name collisions."; 717 uses "tlsc:tls-client-grouping"; 718 } 719 container http-client-parameters { 720 description 721 "A wrapper around the HTTP parameters to avoid 722 name collisions."; 723 uses http-client-grouping; 724 } 725 } 726 } 727 } 728 } 730 } // module ietf-http-client 732 734 3. The "ietf-http-server" Module 736 This section defines a YANG 1.1 [RFC7950] module called "ietf-http- 737 server". A high-level overview of the module is provided in 738 Section 3.1. Examples illustatrating the module's use are provided 739 in Examples (Section 3.2). The YANG module itself is defined in 740 Section 3.3. 742 3.1. Data Model Overview 744 This section provides an overview of the "ietf-http-server" module in 745 terms of its features and groupings. 747 3.1.1. Features 749 The following diagram lists all the "feature" statements defined in 750 the "ietf-http-server" module: 752 Features: 753 +-- client-auth-config-supported 754 +-- basic-auth 755 +-- tcp-supported 756 +-- tls-supported 758 | The diagram above uses syntax that is similar to but not 759 | defined in [RFC8340]. 761 3.1.2. Groupings 763 The "ietf-http-server" module defines the following "grouping" 764 statements: 766 * http-server-grouping 767 * http-server-stack-grouping 769 Each of these groupings are presented in the following subsections. 771 3.1.2.1. The "http-server-grouping" Grouping 773 The following tree diagram [RFC8340] illustrates the "http-server- 774 grouping" grouping: 776 grouping http-server-grouping 777 +-- server-name? string 778 +-- client-authentication! {client-auth-config-supported}? 779 +-- users 780 +-- user* [user-id] 781 +-- user-id? string 782 +-- (auth-type)? 783 +--:(basic) 784 +-- basic {basic-auth}? 785 +-- user-id? string 786 +-- password? ianach:crypt-hash 788 Comments: 790 * The "http-server-grouping" defines the configuration for just 791 "HTTP" part of a protocol stack. It does not, for instance, 792 define any configuration for the "TCP" or "TLS" protocol layers 793 (for that, see Section 3.1.2.2). 795 * The "server-name" node defines the HTTP server's name, as 796 presented to HTTP clients. 798 * The "client-authentication" node, which must by enabled by a 799 feature, defines a very simple user-database. Only the "basic" 800 authentication scheme is supported, albiet it must be enabled by a 801 "feature". Other authentication schemes MAY be augmented in. 803 3.1.2.2. The "http-server-stack-grouping" Grouping 805 The following tree diagram [RFC8340] illustrates the "http-server- 806 stack-grouping" grouping: 808 grouping http-server-stack-grouping 809 +-- (transport) 810 +--:(tcp) {tcp-supported}? 811 | +-- tcp 812 | +-- tcp-server-parameters 813 | | +---u tcps:tcp-server-grouping 814 | +-- http-server-parameters 815 | +---u http-server-grouping 816 +--:(tls) {tls-supported}? 817 +-- tls 818 +-- tcp-server-parameters 819 | +---u tcps:tcp-server-grouping 820 +-- tls-server-parameters 821 | +---u tlss:tls-server-grouping 822 +-- http-server-parameters 823 +---u http-server-grouping 825 Comments: 827 * The "http-server-stack-grouping" is a convenience grouping for 828 downstream modules. It defines both the "HTTP" and "HTTPS" 829 protocol stacks, with each option enabled by a "feature" statement 830 for application control. 832 * For the referenced grouping statement(s): 834 - The "tcp-server-grouping" grouping is discussed in 835 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 836 - The "tls-server-grouping" grouping is discussed in 837 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 839 - The "http-server-grouping" grouping is discussed in 840 Section 3.1.2.1 in this document. 842 3.1.3. Protocol-accessible Nodes 844 The "ietf-http-server" module does not contain any protocol- 845 accessible nodes. 847 3.2. Example Usage 849 This section presents an example showing the http-server-grouping 850 populated with some data. 852 853 foo.example.com 854 856 3.3. YANG Module 858 This YANG module has normative references to [RFC6991]. 860 file "ietf-http-server@2021-02-10.yang" 862 module ietf-http-server { 863 yang-version 1.1; 864 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 865 prefix https; 867 import iana-crypt-hash { 868 prefix ianach; 869 reference 870 "RFC 7317: A YANG Data Model for System Management"; 871 } 873 import ietf-netconf-acm { 874 prefix nacm; 875 reference 876 "RFC 8341: Network Configuration Access Control Model"; 877 } 879 import ietf-tcp-server { 880 prefix tcps; 881 reference 882 "RFC DDDD: YANG Groupings for TCP Clients and TCP Servers"; 883 } 885 import ietf-tls-server { 886 prefix tlss; 887 reference 888 "RFC FFFF: YANG Groupings for TLS Clients and TLS Servers"; 889 } 891 organization 892 "IETF NETCONF (Network Configuration) Working Group"; 894 contact 895 "WG Web: 896 WG List: 897 Author: Kent Watsen "; 899 description 900 "This module defines reusable groupings for HTTP servers that 901 can be used as a basis for specific HTTP server instances. 903 Copyright (c) 2020 IETF Trust and the persons identified 904 as authors of the code. All rights reserved. 906 Redistribution and use in source and binary forms, with 907 or without modification, is permitted pursuant to, and 908 subject to the license terms contained in, the Simplified 909 BSD License set forth in Section 4.c of the IETF Trust's 910 Legal Provisions Relating to IETF Documents 911 (https://trustee.ietf.org/license-info). 913 This version of this YANG module is part of RFC GGGG 914 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 915 itself for full legal notices. 917 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 918 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 919 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 920 are to be interpreted as described in BCP 14 (RFC 2119) 921 (RFC 8174) when, and only when, they appear in all 922 capitals, as shown here."; 924 revision 2021-02-10 { 925 description 926 "Initial version"; 927 reference 928 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 929 } 931 // Features 933 feature client-auth-config-supported { 934 description 935 "Indicates that the configuration for how to authenticate 936 clients can be configured herein, as opposed to in an 937 application specific location. That is, to support the 938 consuming data models that prefer to place client 939 authentication with client definitions, rather then 940 in a data model principally concerned with configuring 941 the transport."; 942 } 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 descendent 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-config-supported"; 989 nacm:default-deny-write; 990 presence 991 "Indicates that HTTP based client authentication is 992 supported (i.e., the server will request that the 993 HTTP client send authenticate when needed). This 994 is needed as some HTTP-based protocols may only 995 support, e.g., TLS-level client authentication."; 996 description 997 "Specifies how the HTTP server can authenticate HTTP 998 clients."; 999 container users { 1000 description 1001 "A list of locally configured users."; 1002 list user { 1003 key user-id; 1004 description 1005 "The list of local users configured on this device."; 1006 leaf user-id { 1007 type string; 1008 description 1009 "The user-id for the authenticating client."; 1010 } 1011 choice auth-type { 1012 description 1013 "The authentication type."; 1014 container basic { 1015 if-feature "basic-auth"; 1016 leaf user-id { 1017 type string; 1018 description 1019 "The user-id for the authenticating client."; 1020 } 1021 leaf password { 1022 nacm:default-deny-write; 1023 type ianach:crypt-hash; 1024 description 1025 "The password for the authenticating client."; 1026 } 1027 description 1028 "The 'basic' HTTP scheme credentials."; 1029 reference 1030 "RFC 7617: 1032 The 'Basic' HTTP Authentication Scheme"; 1033 } 1034 } 1035 } 1036 } 1037 } // container client-authentication 1038 } // grouping http-server-grouping 1040 grouping http-server-stack-grouping { 1041 description 1042 "A grouping that defines common HTTP-based protocol stacks."; 1043 choice transport { 1044 mandatory true; 1045 description 1046 "Choice amongst various transports type. TCP, with and 1047 without TLS are defined here, with 'feature' statements 1048 so that they may be disabled. Other transports MAY be 1049 augmented in as 'case' statements by future efforts."; 1050 case tcp { 1051 if-feature tcp-supported; 1052 container tcp { 1053 description 1054 "Container for TCP-based HTTP protocols."; 1055 container tcp-server-parameters { 1056 description 1057 "A wrapper around the TCP parameters to avoid 1058 name collisions."; 1059 uses "tcps:tcp-server-grouping"; 1060 } 1061 container http-server-parameters { 1062 description 1063 "A wrapper around the HTTP parameters to avoid 1064 name collisions."; 1065 uses http-server-grouping; 1066 } 1067 } 1068 } 1069 case tls { 1070 if-feature tls-supported; 1071 container tls { 1072 description 1073 "Container for TLS-based HTTP protocols."; 1074 container tcp-server-parameters { 1075 description 1076 "A wrapper around the TCP parameters to avoid 1077 name collisions."; 1078 uses "tcps:tcp-server-grouping"; 1080 } 1081 container tls-server-parameters { 1082 description 1083 "A wrapper around the TLS parameters to avoid 1084 name collisions."; 1085 uses "tlss:tls-server-grouping"; 1086 } 1087 container http-server-parameters { 1088 description 1089 "A wrapper around the HTTP parameters to avoid 1090 name collisions."; 1091 uses http-server-grouping; 1092 } 1093 } 1094 } 1095 } 1096 } 1097 } 1099 1101 4. Security Considerations 1103 4.1. The "ietf-http-client" YANG Module 1105 The "ietf-http-client" YANG module defines "grouping" statements that 1106 are designed to be accessed via YANG based management protocols, such 1107 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1108 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1109 with mutual authentication. 1111 The NETCONF access control model (NACM) [RFC8341] provides the means 1112 to restrict access for particular users to a pre-configured subset of 1113 all available protocol operations and content. 1115 Since the module in this document only define groupings, these 1116 considerations are primarily for the designers of other modules that 1117 use these groupings. 1119 One readable data node defined in this YANG module may be considered 1120 sensitive or vulnerable in some network environments. This node is 1121 as follows: 1123 * The "client-identity/basic/password" node: 1125 The cleartext "password" node defined in the "http-client- 1126 identity-grouping" grouping is additionally sensitive to read 1127 operations such that, in normal use cases, it should never be 1128 returned to a client. For this reason, the NACM extension 1129 "default-deny-all" has been applied to it. 1131 | Please be aware that this module uses the "key" and "private- 1132 | key" nodes from the "ietf-crypto-types" module 1133 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 1134 | extension "default-deny-all" set, thus preventing unrestricted 1135 | read-access to the cleartext key values. 1137 None of the writable data nodes defined in this YANG module are 1138 considered sensitive or vulnerable in network environments. The NACM 1139 "default-deny-write" extension has not been set for any data nodes 1140 defined in this module. 1142 | Please be aware that this module uses groupings from the "ietf- 1143 | tls-client" and "ietf-tls-server" modules defined in 1144 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1145 | defined in these groupings have the NACM extension "default- 1146 | deny-write" set, thus preventing unrestricted write-access to 1147 | the data nodes defined in those groupings. 1149 This module does not define any RPCs, actions, or notifications, and 1150 thus the security consideration for such is not provided here. 1152 4.2. The "ietf-http-server" YANG Module 1154 The "ietf-http-server" YANG module defines "grouping" statements that 1155 are designed to be accessed via YANG based management protocols, such 1156 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1157 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1158 with mutual authentication. 1160 The NETCONF access control model (NACM) [RFC8341] provides the means 1161 to restrict access for particular users to a pre-configured subset of 1162 all available protocol operations and content. 1164 Since the module in this document only define groupings, these 1165 considerations are primarily for the designers of other modules that 1166 use these groupings. 1168 None of the readable data nodes defined in this YANG module are 1169 considered sensitive or vulnerable in network environments. The NACM 1170 "default-deny-all" extension has not been set for any data nodes 1171 defined in this module. 1173 None of the writable data nodes defined in this YANG module are 1174 considered sensitive or vulnerable in network environments. The NACM 1175 "default-deny-write" extension has not been set for any data nodes 1176 defined in this module. 1178 | Please be aware that this module uses groupings from the "ietf- 1179 | tls-client" and "ietf-tls-server" modules defined in 1180 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1181 | defined in these groupings have the NACM extension "default- 1182 | deny-write" set, thus preventing unrestricted write-access to 1183 | the data nodes defined in those groupings. 1185 This module does not define any RPCs, actions, or notifications, and 1186 thus the security consideration for such is not provided here. 1188 5. IANA Considerations 1190 5.1. The "IETF XML" Registry 1192 This document registers two URIs in the "ns" subregistry of the IETF 1193 XML Registry [RFC3688]. Following the format in [RFC3688], the 1194 following registrations are requested: 1196 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 1197 Registrant Contact: The IESG 1198 XML: N/A, the requested URI is an XML namespace. 1200 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 1201 Registrant Contact: The IESG 1202 XML: N/A, the requested URI is an XML namespace. 1204 5.2. The "YANG Module Names" Registry 1206 This document registers two YANG modules in the YANG Module Names 1207 registry [RFC6020]. Following the format in [RFC6020], the following 1208 registrations are requested: 1210 name: ietf-http-client 1211 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 1212 prefix: httpc 1213 reference: RFC GGGG 1215 name: ietf-http-server 1216 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 1217 prefix: https 1218 reference: RFC GGGG 1220 6. References 1221 6.1. Normative References 1223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1224 Requirement Levels", BCP 14, RFC 2119, 1225 DOI 10.17487/RFC2119, March 1997, 1226 . 1228 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1229 the Network Configuration Protocol (NETCONF)", RFC 6020, 1230 DOI 10.17487/RFC6020, October 2010, 1231 . 1233 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1234 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1235 . 1237 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1238 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1239 . 1241 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1242 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1243 May 2017, . 1245 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1246 Access Control Model", STD 91, RFC 8341, 1247 DOI 10.17487/RFC8341, March 2018, 1248 . 1250 6.2. Informative References 1252 [I-D.ietf-netconf-crypto-types] 1253 Watsen, K., "YANG Data Types and Groupings for 1254 Cryptography", Work in Progress, Internet-Draft, draft- 1255 ietf-netconf-crypto-types-18, 20 August 2020, 1256 . 1259 [I-D.ietf-netconf-http-client-server] 1260 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1261 Servers", Work in Progress, Internet-Draft, draft-ietf- 1262 netconf-http-client-server-05, 20 August 2020, 1263 . 1266 [I-D.ietf-netconf-keystore] 1267 Watsen, K., "A YANG Data Model for a Keystore", Work in 1268 Progress, Internet-Draft, draft-ietf-netconf-keystore-20, 1269 20 August 2020, . 1272 [I-D.ietf-netconf-netconf-client-server] 1273 Watsen, K., "NETCONF Client and Server Models", Work in 1274 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1275 client-server-21, 20 August 2020, 1276 . 1279 [I-D.ietf-netconf-restconf-client-server] 1280 Watsen, K., "RESTCONF Client and Server Models", Work in 1281 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1282 client-server-21, 20 August 2020, 1283 . 1286 [I-D.ietf-netconf-ssh-client-server] 1287 Watsen, K., "YANG Groupings for SSH Clients and SSH 1288 Servers", Work in Progress, Internet-Draft, draft-ietf- 1289 netconf-ssh-client-server-22, 20 August 2020, 1290 . 1293 [I-D.ietf-netconf-tcp-client-server] 1294 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1295 and TCP Servers", Work in Progress, Internet-Draft, draft- 1296 ietf-netconf-tcp-client-server-08, 20 August 2020, 1297 . 1300 [I-D.ietf-netconf-tls-client-server] 1301 Watsen, K., "YANG Groupings for TLS Clients and TLS 1302 Servers", Work in Progress, Internet-Draft, draft-ietf- 1303 netconf-tls-client-server-22, 20 August 2020, 1304 . 1307 [I-D.ietf-netconf-trust-anchors] 1308 Watsen, K., "A YANG Data Model for a Truststore", Work in 1309 Progress, Internet-Draft, draft-ietf-netconf-trust- 1310 anchors-13, 20 August 2020, . 1313 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1314 DOI 10.17487/RFC3688, January 2004, 1315 . 1317 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1318 and A. Bierman, Ed., "Network Configuration Protocol 1319 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1320 . 1322 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1323 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1324 . 1326 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1327 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1328 . 1330 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1331 and R. Wilton, "Network Management Datastore Architecture 1332 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1333 . 1335 Appendix A. Change Log 1337 This section is to be removed before publishing as an RFC. 1339 A.1. 00 to 01 1341 * Modified Abstract and Intro to be more accurate wrt intended 1342 applicability. 1344 * In ietf-http-client, removed "protocol-version" and all auth 1345 schemes except "basic". 1347 * In ietf-http-client, factored out "client-identity-grouping" for 1348 proxy connections. 1350 * In ietf-http-server, removed "choice required-or-optional" and 1351 "choice local-or-external". 1353 * In ietf-http-server, moved the basic auth under a "choice auth- 1354 type" limited by new "feature basic-auth". 1356 A.2. 01 to 02 1358 * Removed the unused "external-client-auth-supported" feature from 1359 ietf-http-server. 1361 A.3. 02 to 03 1363 * Removed "protocol-versions" from ietf-http-server based on HTTP WG 1364 feedback. 1366 * Slightly restructured the "proxy-server" definition in ietf-http- 1367 client. 1369 * Added http-client example show proxy server use. 1371 * Added a "Note to Reviewers" note to first page. 1373 A.4. 03 to 04 1375 * Added a parent "container" to "client-identity-grouping" so that 1376 it could be better used by the proxy model. 1378 * Added a "choice" to the proxy model enabling selection of proxy 1379 types. 1381 * Added 'http-client-stack-grouping' and 'http-server-stack- 1382 grouping' convenience groupings. 1384 * Expanded "Data Model Overview section(s) [remove "wall" of tree 1385 diagrams]. 1387 * Updated the Security Considerations section. 1389 A.5. 04 to 05 1391 * Fixed titles and a ref in the IANA Considerations section 1393 * Cleaned up examples (e.g., removed FIXMEs) 1395 * Fixed issues found by the SecDir review of the "keystore" draft. 1397 * Updated the "ietf-http-client" module to use the new "password- 1398 grouping" grouping from the "crypto-types" module. 1400 A.6. 05 to 06 1402 * Removed note questioning if okay for app to augment-in a 'path' 1403 node when needed, discussed during the 108 session. 1405 * Addressed comments raised by YANG Doctor in the ct/ts/ks drafts. 1407 Acknowledgements 1409 The authors would like to thank for following for lively discussions 1410 on list and in the halls (ordered by last name): Mark Nottingham, Ben 1411 Schwartz, Rob Wilton (contributor), and Willy Tarreau. 1413 Author's Address 1415 Kent Watsen 1416 Watsen Networks 1418 Email: kent+ietf@watsen.net