idnits 2.17.1 draft-ietf-netconf-http-client-server-04.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 == Line 246 has weird spacing: '...assword str...' -- The document date (8 July 2020) is 1388 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-15 == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-03 == Outdated reference: A later version (-35) exists of draft-ietf-netconf-keystore-17 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-19 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-restconf-client-server-19 == Outdated reference: A later version (-40) exists of draft-ietf-netconf-ssh-client-server-19 == Outdated reference: A later version (-26) exists of draft-ietf-netconf-tcp-client-server-06 == Outdated reference: A later version (-41) exists of draft-ietf-netconf-tls-client-server-19 == Outdated reference: A later version (-28) exists of draft-ietf-netconf-trust-anchors-10 Summary: 0 errors (**), 0 flaws (~~), 11 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 8 July 2020 5 Expires: 9 January 2021 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-04 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 * "2020-07-08" --> 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 9 January 2021. 74 Copyright Notice 76 Copyright (c) 2020 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 . . . . . . . . . . . . . . . . . . . 5 96 2.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 97 2.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 10 98 3. The "ietf-http-server" Module . . . . . . . . . . . . . . . . 16 99 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 16 100 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 18 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 . . . . . . . . . . . . . . . . . . . . . 25 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 . . . . . . . . . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . . . . . . . . 29 115 A.4. 03 to 04 . . . . . . . . . . . . . . . . . . . . . . . . 29 116 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 30 117 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30 119 1. Introduction 121 This document defines two YANG 1.1 [RFC7950] modules: the first 122 defines a minimal grouping for configuring an HTTP client, and the 123 second defines a minimal grouping for configuring an HTTP server. It 124 is intended that these groupings will be used to help define the 125 configuration for simple HTTP-based protocols (not for complete web 126 servers or browsers). 128 1.1. Relation to other RFCs 130 This document presents one or more YANG modules [RFC7950] that are 131 part of a collection of RFCs that work together to define 132 configuration modules for clients and servers of both the NETCONF 133 [RFC6241] and RESTCONF [RFC8040] protocols. 135 The modules have been defined in a modular fashion to enable their 136 use by other efforts, some of which are known to be in progress at 137 the time of this writing, with many more expected to be defined in 138 time. 140 The relationship between the various RFCs in the collection is 141 presented in the below diagram. The labels in the diagram represent 142 the primary purpose provided by each RFC. Links the each RFC are 143 provided below the diagram. 145 crypto-types 146 ^ ^ 147 / \ 148 / \ 149 truststore keystore 150 ^ ^ ^ ^ 151 | +---------+ | | 152 | | | | 153 | +------------+ | 154 tcp-client-server | / | | 155 ^ ^ ssh-client-server | | 156 | | ^ tls-client-server 157 | | | ^ ^ http-client-server 158 | | | | | ^ 159 | | | +-----+ +---------+ | 160 | | | | | | 161 | +-----------|--------|--------------+ | | 162 | | | | | | 163 +-----------+ | | | | | 164 | | | | | | 165 | | | | | | 166 netconf-client-server restconf-client-server 168 +=======================+===========================================+ 169 | Label in Diagram | Originating RFC | 170 +=======================+===========================================+ 171 | crypto-types | [I-D.ietf-netconf-crypto-types] | 172 +-----------------------+-------------------------------------------+ 173 | truststore | [I-D.ietf-netconf-trust-anchors] | 174 +-----------------------+-------------------------------------------+ 175 | keystore | [I-D.ietf-netconf-keystore] | 176 +-----------------------+-------------------------------------------+ 177 | tcp-client-server | [I-D.ietf-netconf-tcp-client-server] | 178 +-----------------------+-------------------------------------------+ 179 | ssh-client-server | [I-D.ietf-netconf-ssh-client-server] | 180 +-----------------------+-------------------------------------------+ 181 | tls-client-server | [I-D.ietf-netconf-tls-client-server] | 182 +-----------------------+-------------------------------------------+ 183 | http-client-server | [I-D.ietf-netconf-http-client-server] | 184 +-----------------------+-------------------------------------------+ 185 | netconf-client-server | [I-D.ietf-netconf-netconf-client-server] | 186 +-----------------------+-------------------------------------------+ 187 |restconf-client-server | [I-D.ietf-netconf-restconf-client-server] | 188 +-----------------------+-------------------------------------------+ 190 Table 1: Label to RFC Mapping 192 1.2. Specification Language 194 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 195 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 196 "OPTIONAL" in this document are to be interpreted as described in BCP 197 14 [RFC2119] [RFC8174] when, and only when, they appear in all 198 capitals, as shown here. 200 1.3. Adherence to the NMDA 202 This document in compliant with the Network Management Datastore 203 Architecture (NMDA) [RFC8342]. For instance, as described in 204 [I-D.ietf-netconf-trust-anchors] and [I-D.ietf-netconf-keystore], 205 trust anchors and keys installed during manufacturing are expected to 206 appear in . 208 2. The "ietf-http-client" Module 210 2.1. Data Model Overview 212 2.1.1. Features 214 The following diagram lists all the "feature" statements defined in 215 the "ietf-http-client" module: 217 Features: 218 +-- proxy-connect 219 +-- basic-auth 220 +-- tcp-supported 221 +-- tls-supported 223 2.1.2. Groupings 225 The following diagram lists all the "grouping" statements defined in 226 the "ietf-http-client" module: 228 Groupings: 229 +-- http-client-identity-grouping 230 +-- http-client-grouping 231 +-- http-client-stack-grouping 233 Each of these groupings are presented in the following subsections. 235 2.1.2.1. The "http-client-identity-grouping" Grouping 237 The following tree diagram [RFC8340] illustrates the "http-client- 238 identity-grouping" grouping: 240 grouping http-client-identity-grouping 241 +-- client-identity! 242 +-- (auth-type) 243 +--:(basic) 244 +-- basic {basic-auth}? 245 +-- user-id string 246 +-- password string 248 Comments: 250 * This grouping exists because it is used three times by the "http- 251 client-grouping" discussed in Section 2.1.2.2. 253 * The "client-identity" node is a "presence" container so that its 254 descendent "choice" node's "mandatory true" doesn't imply that a 255 client identity must be configured, as a client identity may be 256 configured at protocol layers. 258 * The "basic" authentication scheme is the only scheme defined by 259 this module, albeit it must be enabled via the "basic-auth" 260 feature (see Section 2.1.1). 262 * Other authentication schemes MAY be augmented in as needed by the 263 application. 265 2.1.2.2. The "http-client-grouping" Grouping 267 The following tree diagram [RFC8340] illustrates the "http-client- 268 grouping" grouping: 270 grouping http-client-grouping 271 +---u http-client-identity-grouping 272 +-- proxy-connect! {proxy-connect}? 273 +-- (proxy-type) 274 +--:(http) 275 | +-- http-proxy 276 | +-- tcp-client-parameters 277 | | +---u tcpc:tcp-client-grouping 278 | +-- http-client-parameters 279 | +---u http-client-identity-grouping 280 +--:(https) 281 +-- https-proxy 282 +-- tcp-client-parameters 283 | +---u tcpc:tcp-client-grouping 284 +-- tls-client-parameters 285 | +---u tlsc:tls-client-grouping 286 +-- http-client-parameters 287 +---u http-client-identity-grouping 289 Comments: 291 * The "http-client-grouping" defines the configuration for just 292 "HTTP" part of a protocol stack. It does not, for instance, 293 define any configuration for the "TCP" or "TLS" protocol layers 294 (for that, see Section 2.1.2.3). 296 * Beyond configuring the client's identity, via the "http-client- 297 identity-grouping" grouping discussed in Section 2.1.2.1, this 298 grouping defines support for HTTP-proxies, albeit it must be 299 enabled via a "feature" statement. 301 * The "proxy-connect" node is a "presence" container so that its 302 descendent "choice" node's "mandatory true" doesn't imply that a 303 proxy connection must be configured, assuming the server supports 304 the "proxy-connect" feature. 306 * For the referenced grouping statement(s): 308 - The "http-client-identity-grouping" grouping is discussed in 309 Section 2.1.2.1. 310 - The "tcp-client-grouping" grouping is discussed in 311 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 312 - The "tls-client-grouping" grouping is discussed in 313 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 315 2.1.2.3. The "http-client-stack-grouping" Grouping 317 The following tree diagram [RFC8340] illustrates the "http-client- 318 stack-grouping" grouping: 320 grouping http-client-stack-grouping 321 +-- (transport) 322 +--:(tcp) {tcp-supported}? 323 | +-- tcp 324 | +-- tcp-client-parameters 325 | | +---u tcpc:tcp-client-grouping 326 | +-- http-client-parameters 327 | +---u http-client-grouping 328 +--:(tls) {tls-supported}? 329 +-- tls 330 +-- tcp-client-parameters 331 | +---u tcpc:tcp-client-grouping 332 +-- tls-client-parameters 333 | +---u tlsc:tls-client-grouping 334 +-- http-client-parameters 335 +---u http-client-grouping 337 Comments: 339 * The "http-client-stack-grouping" is a convenience grouping for 340 downstream modules. It defines both the "HTTP" and "HTTPS" 341 protocol stacks, with each option enabled by a "feature" statement 342 for application control. 344 * For the referenced grouping statement(s): 346 - The "tcp-client-grouping" grouping is discussed in 347 Section 3.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 348 - The "tls-client-grouping" grouping is discussed in 349 Section 3.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 350 - The "http-client-grouping" grouping is discussed in 351 Section 2.1.2.2 in this document. 353 2.1.3. Protocol-accessible Nodes 355 The "ietf-http-client" module does not contain any protocol- 356 accessible nodes. 358 2.2. Example Usage 360 This section presents two examples showing the http-client-grouping 361 populated with some data. 363 The following example illustrates an HTTP client connecting directly 364 to an HTTP server. 366 367 368 369 bob 370 secret 371 372 373 375 The following example illustrates the same client connecting through 376 an HTTP proxy. This example is consistent with examples presented in 377 Section 2.2 of [I-D.ietf-netconf-trust-anchors] and Section 2.2 of 378 [I-D.ietf-netconf-keystore]. 380 =============== NOTE: '\' line wrapping per RFC 8792 ================ 382 383 384 385 bob 386 secret 387 388 389 390 391 392 corp-fw2.example.com 393 394 15 395 3 396 30 397 398 399 400 401 402 403 rsa-asymmetric-key 404 ex-rsa-cert 405 406 407 408 409 410 trusted-server-ca-certs 412 413 414 trusted-server-ee-certs 416 417 418 419 420 421 422 local-app-1 423 secret 424 425 426 427 429 430 432 2.3. YANG Module 434 This YANG module has normative references to [RFC6991]. 436 file "ietf-http-client@2020-07-08.yang" 438 module ietf-http-client { 439 yang-version 1.1; 440 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 441 prefix httpc; 443 import ietf-netconf-acm { 444 prefix nacm; 445 reference 446 "RFC 8341: Network Configuration Access Control Model"; 447 } 449 import ietf-tcp-client { 450 prefix tcpc; 451 reference 452 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 453 } 455 import ietf-tls-client { 456 prefix tlsc; 457 reference 458 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 459 } 461 organization 462 "IETF NETCONF (Network Configuration) Working Group"; 464 contact 465 "WG Web: 466 WG List: 467 Author: Kent Watsen "; 469 description 470 "This module defines reusable groupings for HTTP clients that 471 can be used as a basis for specific HTTP client instances. 473 Copyright (c) 2020 IETF Trust and the persons identified 474 as authors of the code. All rights reserved. 476 Redistribution and use in source and binary forms, with 477 or without modification, is permitted pursuant to, and 478 subject to the license terms contained in, the Simplified 479 BSD License set forth in Section 4.c of the IETF Trust's 480 Legal Provisions Relating to IETF Documents 481 (https://trustee.ietf.org/license-info). 483 This version of this YANG module is part of RFC GGGG 484 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 485 itself for full legal notices. 487 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 488 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 489 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 490 are to be interpreted as described in BCP 14 (RFC 2119) 491 (RFC 8174) when, and only when, they appear in all 492 capitals, as shown here."; 494 revision 2020-07-08 { 495 description 496 "Initial version"; 497 reference 498 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 499 } 501 // Features 503 feature proxy-connect { 504 description 505 "Proxy connection configuration is configurable for 506 HTTP clients on the server implementing this feature."; 507 } 509 feature basic-auth { 510 description 511 "The 'basic-auth' feature indicates that the client 512 may be configured to use the 'basic' HTTP authentication 513 scheme."; 514 reference 515 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 516 } 518 feature tcp-supported { 519 description 520 "Indicates that the server supports HTTP/TCP."; 521 } 523 feature tls-supported { 524 description 525 "Indicates that the server supports HTTP/TLS."; 526 } 528 // Groupings 530 grouping http-client-identity-grouping { 531 description 532 "A grouping to provide HTTP credentials used by the 533 client to authenticate itself to the HTTP server."; 534 container client-identity { 535 nacm:default-deny-write; 536 presence 537 "Indicates that HTTP-level client authentication 538 is sent. Present so that the 'choice' node's 539 mandatory true doesn't imply that a client 540 identity must be configured."; 541 description 542 "The identity the HTTP client should use when 543 authenticating itself to the HTTP server."; 544 choice auth-type { 545 mandatory true; 546 description 547 "A choice amongst available authentication types."; 548 case basic { 549 container basic { 550 if-feature "basic-auth"; 551 leaf user-id { 552 type string; 553 mandatory true; 554 description 555 "The user-id for the authenticating client."; 556 } 557 leaf password { 558 nacm:default-deny-all; 559 type string; 560 mandatory true; 561 description 562 "The password for the authenticating client."; 563 } 564 description 565 "The 'basic' HTTP scheme credentials."; 566 reference 567 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 568 } 569 } 570 } 571 } 573 } // grouping http-client-identity-grouping 575 grouping http-client-grouping { 576 description 577 "A reusable grouping for configuring a HTTP client. 579 This grouping is expected to be used in conjunction with 580 other configurations providing, e.g., the hostname or IP 581 address and port number the client initiates connections 582 to. 584 Note that this grouping uses fairly typical descendent 585 node names such that a stack of 'uses' statements will 586 have name conflicts. It is intended that the consuming 587 data model will resolve the issue (e.g., by wrapping 588 the 'uses' statement in a container called 589 'http-client-parameters'). This model purposely does 590 not do this itself so as to provide maximum flexibility 591 to consuming models. 593 FIXME: it is assumed that the application can construct any 594 necessary HTTP path, e.g., via a YANG 'rpc' definition...ok?"; 596 uses http-client-identity-grouping; 598 container proxy-connect { 599 nacm:default-deny-write; 600 if-feature "proxy-connect"; 601 presence 602 "Indicates that the HTTP-client is to connect thru an 603 HTTP-level proxy server. Present so that the 'choice' 604 node's mandatory true doesn't imply that a proxy 605 connection must be configured."; 606 choice proxy-type { 607 mandatory true; 608 description 609 "Choice amongst proxy server types."; 610 case http { 611 container http-proxy { 612 /* FIXME: THIS ISN'T NEEDED...because in a 'case' 613 presence 614 "Indicates that a HTTP proxy (Web proxy) connection 615 is configured."; 616 */ 617 description 618 "Container for HTTP Proxy (Web Proxy) server 619 configuration parameters."; 620 container tcp-client-parameters { 621 description 622 "A wrapper around the TCP parameters to avoid 623 name collisions."; 624 uses "tcpc:tcp-client-grouping"; 625 } 626 container http-client-parameters { 627 description 628 "A wrapper around the HTTP parameters to avoid 629 name collisions."; 630 uses http-client-identity-grouping; 631 /* FIXME: is HTTP Proxy auth *required* 632 refine client-identity/auth-type { 633 mandatory true; 634 } 635 */ 636 } 637 } 638 } 639 case https { 640 container https-proxy { 641 /* FIXME: THIS ISN'T NEEDED...because in a 'case' 642 presence 643 "Indicates that a HTTPS proxy (Secure web proxy) 644 connection is configured."; 645 */ 646 /* FIXME: is HTTP Proxy auth *required* 647 must 648 "tls-client-parameters/client-identity 649 or http-client-parameters/client-identity"; 650 */ 651 description 652 "Container for HTTPS Proxy (Secure Web Proxy) server 653 configuration parameters."; 654 container tcp-client-parameters { 655 description 656 "A wrapper around the TCP parameters to avoid 657 name collisions."; 658 uses "tcpc:tcp-client-grouping"; 659 } 660 container tls-client-parameters { 661 description 662 "A wrapper around the TLS parameters to avoid 663 name collisions."; 664 uses "tlsc:tls-client-grouping"; 665 } 666 container http-client-parameters { 667 description 668 "A wrapper around the HTTP parameters to avoid 669 name collisions."; 670 uses http-client-identity-grouping; 671 } 672 } 673 } 674 } 675 description 676 "Proxy server settings."; 677 } 678 } // grouping http-client-grouping 680 grouping http-client-stack-grouping { 681 description 682 "A grouping that defines common HTTP-based protocol stacks."; 683 choice transport { 684 mandatory true; 685 description 686 "Choice amongst various transports type. TCP, with and 687 without TLS are defined here, with 'feature' statements 688 so that they may be disabled. Other transports MAY be 689 augmented in as 'case' statements by future efforts."; 690 case tcp { 691 if-feature tcp-supported; 692 container tcp { 693 description 694 "Container for TCP-based HTTP protocols."; 695 container tcp-client-parameters { 696 description 697 "A wrapper around the TCP parameters to avoid 698 name collisions."; 699 uses "tcpc:tcp-client-grouping"; 700 } 701 container http-client-parameters { 702 description 703 "A wrapper around the HTTP parameters to avoid 704 name collisions."; 705 uses http-client-grouping; 706 } 707 } 708 } 709 case tls { 710 if-feature tls-supported; 711 container tls { 712 description 713 "Container for TLS-based HTTP protocols."; 714 container tcp-client-parameters { 715 description 716 "A wrapper around the TCP parameters to avoid 717 name collisions."; 718 uses "tcpc:tcp-client-grouping"; 719 } 720 container tls-client-parameters { 721 description 722 "A wrapper around the TLS parameters to avoid 723 name collisions."; 724 uses "tlsc:tls-client-grouping"; 725 } 726 container http-client-parameters { 727 description 728 "A wrapper around the HTTP parameters to avoid 729 name collisions."; 730 uses http-client-grouping; 731 } 732 } 733 } 734 } 735 } 737 } // module ietf-http-client 739 741 3. The "ietf-http-server" Module 743 3.1. Data Model Overview 745 3.1.1. Features 747 The following diagram lists all the "feature" statements defined in 748 the "ietf-http-server" module: 750 Features: 751 +-- client-auth-config-supported 752 +-- basic-auth 753 +-- tcp-supported 754 +-- tls-supported 756 3.1.2. Groupings 758 The following diagram lists all the "grouping" statements defined in 759 the "ietf-http-server" module: 761 Groupings: 762 +-- http-server-grouping 763 +-- http-server-stack-grouping 765 Each of these groupings are presented in the following subsections. 767 3.1.2.1. The "http-server-grouping" Grouping 769 The following tree diagram [RFC8340] illustrates the "http-server- 770 grouping" grouping: 772 grouping http-server-grouping 773 +-- server-name? string 774 +-- client-authentication! {client-auth-config-supported}? 775 +-- users 776 +-- user* [user-id] 777 +-- user-id? string 778 +-- (auth-type)? 779 +--:(basic) 780 +-- basic {basic-auth}? 781 +-- user-id? string 782 +-- password? ianach:crypt-hash 784 Comments: 786 * The "http-server-grouping" defines the configuration for just 787 "HTTP" part of a protocol stack. It does not, for instance, 788 define any configuration for the "TCP" or "TLS" protocol layers 789 (for that, see Section 3.1.2.2). 791 * The "server-name" node defines the HTTP server's name, as 792 presented to HTTP clients. 794 * The "client-authentication" node, which must by enabled by a 795 feature, defines a very simple user-database. Only the "basic" 796 authentication scheme is supported, albiet it must be enabled by a 797 "feature". Other authentication schemes MAY be augmented in. 799 3.1.2.2. The "http-server-stack-grouping" Grouping 801 The following tree diagram [RFC8340] illustrates the "http-server- 802 stack-grouping" grouping: 804 grouping http-server-stack-grouping 805 +-- (transport) 806 +--:(tcp) {tcp-supported}? 807 | +-- tcp 808 | +-- tcp-server-parameters 809 | | +---u tcps:tcp-server-grouping 810 | +-- http-server-parameters 811 | +---u http-server-grouping 812 +--:(tls) {tls-supported}? 813 +-- tls 814 +-- tcp-server-parameters 815 | +---u tcps:tcp-server-grouping 816 +-- tls-server-parameters 817 | +---u tlss:tls-server-grouping 818 +-- http-server-parameters 819 +---u http-server-grouping 821 Comments: 823 * The "http-server-stack-grouping" is a convenience grouping for 824 downstream modules. It defines both the "HTTP" and "HTTPS" 825 protocol stacks, with each option enabled by a "feature" statement 826 for application control. 828 * For the referenced grouping statement(s): 830 - The "tcp-server-grouping" grouping is discussed in 831 Section 4.1.2.1 of [I-D.ietf-netconf-tcp-client-server]. 832 - The "tls-server-grouping" grouping is discussed in 833 Section 4.1.2.1 of [I-D.ietf-netconf-tls-client-server]. 834 - The "http-server-grouping" grouping is discussed in 835 Section 3.1.2.1 in this document. 837 3.1.3. Protocol-accessible Nodes 839 The "ietf-http-server" module does not contain any protocol- 840 accessible nodes. 842 3.2. Example Usage 844 This section presents an example showing the http-server-grouping 845 populated with some data. 847 848 foo.example.com 849 851 3.3. YANG Module 853 This YANG module has normative references to [RFC6991]. 855 file "ietf-http-server@2020-07-08.yang" 857 module ietf-http-server { 858 yang-version 1.1; 859 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 860 prefix https; 862 import iana-crypt-hash { 863 prefix ianach; 864 reference 865 "RFC 7317: A YANG Data Model for System Management"; 866 } 868 import ietf-netconf-acm { 869 prefix nacm; 870 reference 871 "RFC 8341: Network Configuration Access Control Model"; 872 } 874 import ietf-tcp-server { 875 prefix tcps; 876 reference 877 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 878 } 880 import ietf-tls-server { 881 prefix tlss; 882 reference 883 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 884 } 886 organization 887 "IETF NETCONF (Network Configuration) Working Group"; 889 contact 890 "WG Web: 891 WG List: 892 Author: Kent Watsen "; 894 description 895 "This module defines reusable groupings for HTTP servers that 896 can be used as a basis for specific HTTP server instances. 898 Copyright (c) 2020 IETF Trust and the persons identified 899 as authors of the code. All rights reserved. 901 Redistribution and use in source and binary forms, with 902 or without modification, is permitted pursuant to, and 903 subject to the license terms contained in, the Simplified 904 BSD License set forth in Section 4.c of the IETF Trust's 905 Legal Provisions Relating to IETF Documents 906 (https://trustee.ietf.org/license-info). 908 This version of this YANG module is part of RFC GGGG 909 (https://www.rfc-editor.org/info/rfcGGGG); see the RFC 910 itself for full legal notices. 912 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 913 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 914 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 915 are to be interpreted as described in BCP 14 (RFC 2119) 916 (RFC 8174) when, and only when, they appear in all 917 capitals, as shown here."; 919 revision 2020-07-08 { 920 description 921 "Initial version"; 922 reference 923 "RFC GGGG: YANG Groupings for HTTP Clients and HTTP Servers"; 924 } 926 // Features 928 feature client-auth-config-supported { 929 description 930 "Indicates that the configuration for how to authenticate 931 clients can be configured herein, as opposed to in an 932 application specific location. That is, to support the 933 consuming data models that prefer to place client 934 authentication with client definitions, rather then 935 in a data model principally concerned with configuring 936 the transport."; 937 } 939 feature basic-auth { 940 description 941 "The 'basic-auth' feature indicates that the server 942 may be configured authenticate users using the 'basic' 943 HTTP authentication scheme."; 944 reference 945 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 946 } 947 feature tcp-supported { 948 description 949 "Indicates that the server supports HTTP/TCP."; 950 } 952 feature tls-supported { 953 description 954 "Indicates that the server supports HTTP/TLS."; 955 } 957 // Groupings 959 grouping http-server-grouping { 960 description 961 "A reusable grouping for configuring an HTTP server. 963 Note that this grouping uses fairly typical descendent 964 node names such that a stack of 'uses' statements will 965 have name conflicts. It is intended that the consuming 966 data model will resolve the issue (e.g., by wrapping 967 the 'uses' statement in a container called 968 'http-server-parameters'). This model purposely does 969 not do this itself so as to provide maximum flexibility 970 to consuming models."; 972 leaf server-name { 973 nacm:default-deny-write; 974 type string; 975 description 976 "The value of the 'Server' header field. If not set, then 977 underlying software's default value is used. Set to the 978 empty string to disable."; 979 } 981 container client-authentication { 982 if-feature "client-auth-config-supported"; 983 nacm:default-deny-write; 984 presence 985 "Indicates that HTTP based client authentication is 986 supported (i.e., the server will request that the 987 HTTP client send authenticate when needed). This 988 is needed as some HTTP-based protocols may only 989 support, e.g., TLS-level client authentication."; 990 description 991 "Specifies how the HTTP server can authenticate HTTP 992 clients."; 993 container users { 994 description 995 "A list of locally configured users."; 996 list user { 997 key user-id; 998 description 999 "The list of local users configured on this device."; 1000 leaf user-id { 1001 type string; 1002 description 1003 "The user-id for the authenticating client."; 1004 } 1005 choice auth-type { 1006 description 1007 "The authentication type."; 1008 container basic { 1009 if-feature "basic-auth"; 1010 leaf user-id { 1011 type string; 1012 description 1013 "The user-id for the authenticating client."; 1014 } 1015 leaf password { 1016 nacm:default-deny-write; 1017 type ianach:crypt-hash; 1018 description 1019 "The password for the authenticating client."; 1020 } 1021 description 1022 "The 'basic' HTTP scheme credentials."; 1023 reference 1024 "RFC 7617: 1025 The 'Basic' HTTP Authentication Scheme"; 1026 } 1027 } 1028 } 1029 } 1030 } // container client-authentication 1031 } // grouping http-server-grouping 1033 grouping http-server-stack-grouping { 1034 description 1035 "A grouping that defines common HTTP-based protocol stacks."; 1036 choice transport { 1037 mandatory true; 1038 description 1039 "Choice amongst various transports type. TCP, with and 1040 without TLS are defined here, with 'feature' statements 1041 so that they may be disabled. Other transports MAY be 1042 augmented in as 'case' statements by future efforts."; 1043 case tcp { 1044 if-feature tcp-supported; 1045 container tcp { 1046 description 1047 "Container for TCP-based HTTP protocols."; 1048 container tcp-server-parameters { 1049 description 1050 "A wrapper around the TCP parameters to avoid 1051 name collisions."; 1052 uses "tcps:tcp-server-grouping"; 1053 } 1054 container http-server-parameters { 1055 description 1056 "A wrapper around the HTTP parameters to avoid 1057 name collisions."; 1058 uses http-server-grouping; 1059 } 1060 } 1061 } 1062 case tls { 1063 if-feature tls-supported; 1064 container tls { 1065 description 1066 "Container for TLS-based HTTP protocols."; 1067 container tcp-server-parameters { 1068 description 1069 "A wrapper around the TCP parameters to avoid 1070 name collisions."; 1071 uses "tcps:tcp-server-grouping"; 1072 } 1073 container tls-server-parameters { 1074 description 1075 "A wrapper around the TLS parameters to avoid 1076 name collisions."; 1077 uses "tlss:tls-server-grouping"; 1078 } 1079 container http-server-parameters { 1080 description 1081 "A wrapper around the HTTP parameters to avoid 1082 name collisions."; 1083 uses http-server-grouping; 1084 } 1085 } 1086 } 1087 } 1088 } 1089 } 1090 1092 4. Security Considerations 1094 4.1. The "ietf-http-client" YANG Module 1096 The "ietf-http-client" YANG module defines "grouping" statements that 1097 are designed to be accessed via YANG based management protocols, such 1098 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1099 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1100 with mutual authentication. 1102 The NETCONF access control model (NACM) [RFC8341] provides the means 1103 to restrict access for particular users to a pre-configured subset of 1104 all available protocol operations and content. 1106 Since the module in this document only define groupings, these 1107 considerations are primarily for the designers of other modules that 1108 use these groupings. 1110 One readable data node defined in this YANG module may be considered 1111 sensitive or vulnerable in some network environments. This node is 1112 as follows: 1114 * The "client-identity/basic/password" node: 1116 The cleartext "password" node defined in the "http-client- 1117 identity-grouping" grouping is additionally sensitive to read 1118 operations such that, in normal use cases, it should never be 1119 returned to a client. For this reason, the NACM extension 1120 "default-deny-all" has been applied to it. 1122 | Please be aware that this module uses the "key" and "private- 1123 | key" nodes from the "ietf-crypto-types" module 1124 | [I-D.ietf-netconf-crypto-types], where said nodes have the NACM 1125 | extension "default-deny-all" set, thus preventing unrestricted 1126 | read-access to the cleartext key values. 1128 None of the writable data nodes defined in this YANG module are 1129 considered sensitive or vulnerable in network environments. The NACM 1130 "default-deny-write" extension has not been set for any data nodes 1131 defined in this module. 1133 | Please be aware that this module uses groupings from the "ietf- 1134 | tls-client" and "ietf-tls-server" modules defined in 1135 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1136 | defined in these groupings have the NACM extension "default- 1137 | deny-write" set, thus preventing unrestricted write-access to 1138 | the data nodes defined in those groupings. 1140 This module does not define any RPCs, actions, or notifications, and 1141 thus the security consideration for such is not provided here. 1143 4.2. The "ietf-http-server" YANG Module 1145 The "ietf-http-server" YANG module defines "grouping" statements that 1146 are designed to be accessed via YANG based management protocols, such 1147 as NETCONF [RFC6241] and RESTCONF [RFC8040]. Both of these protocols 1148 have mandatory-to-implement secure transport layers (e.g., SSH, TLS) 1149 with mutual authentication. 1151 The NETCONF access control model (NACM) [RFC8341] provides the means 1152 to restrict access for particular users to a pre-configured subset of 1153 all available protocol operations and content. 1155 Since the module in this document only define groupings, these 1156 considerations are primarily for the designers of other modules that 1157 use these groupings. 1159 None of the readable data nodes defined in this YANG module are 1160 considered sensitive or vulnerable in network environments. The NACM 1161 "default-deny-all" extension has not been set for any data nodes 1162 defined in this module. 1164 None of the writable data nodes defined in this YANG module are 1165 considered sensitive or vulnerable in network environments. The NACM 1166 "default-deny-write" extension has not been set for any data nodes 1167 defined in this module. 1169 | Please be aware that this module uses groupings from the "ietf- 1170 | tls-client" and "ietf-tls-server" modules defined in 1171 | [I-D.ietf-netconf-tls-client-server]. All of the data nodes 1172 | defined in these groupings have the NACM extension "default- 1173 | deny-write" set, thus preventing unrestricted write-access to 1174 | the data nodes defined in those groupings. 1176 This module does not define any RPCs, actions, or notifications, and 1177 thus the security consideration for such is not provided here. 1179 5. IANA Considerations 1180 5.1. The IETF XML Registry 1182 This document registers two URIs in the "ns" subregistry of the IETF 1183 XML Registry [RFC3688]. Following the format in [RFC3688], the 1184 following registrations are requested: 1186 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 1187 Registrant Contact: The NETCONF WG of the IETF. 1188 XML: N/A, the requested URI is an XML namespace. 1190 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 1191 Registrant Contact: The NETCONF WG of the IETF. 1192 XML: N/A, the requested URI is an XML namespace. 1194 5.2. The YANG Module Names Registry 1196 This document registers two YANG modules in the YANG Module Names 1197 registry [RFC6020]. Following the format in [RFC6020], the following 1198 registrations are requested: 1200 name: ietf-http-client 1201 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 1202 prefix: httpc 1203 reference: RFC XXXX 1205 name: ietf-http-server 1206 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 1207 prefix: https 1208 reference: RFC XXXX 1210 6. References 1212 6.1. Normative References 1214 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1215 Requirement Levels", BCP 14, RFC 2119, 1216 DOI 10.17487/RFC2119, March 1997, 1217 . 1219 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1220 the Network Configuration Protocol (NETCONF)", RFC 6020, 1221 DOI 10.17487/RFC6020, October 2010, 1222 . 1224 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1225 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1226 . 1228 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1229 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1230 . 1232 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1233 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1234 May 2017, . 1236 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1237 Access Control Model", STD 91, RFC 8341, 1238 DOI 10.17487/RFC8341, March 2018, 1239 . 1241 6.2. Informative References 1243 [I-D.ietf-netconf-crypto-types] 1244 Watsen, K., "Common YANG Data Types for Cryptography", 1245 Work in Progress, Internet-Draft, draft-ietf-netconf- 1246 crypto-types-15, 20 May 2020, 1247 . 1250 [I-D.ietf-netconf-http-client-server] 1251 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1252 Servers", Work in Progress, Internet-Draft, draft-ietf- 1253 netconf-http-client-server-03, 20 May 2020, 1254 . 1257 [I-D.ietf-netconf-keystore] 1258 Watsen, K., "A YANG Data Model for a Keystore", Work in 1259 Progress, Internet-Draft, draft-ietf-netconf-keystore-17, 1260 20 May 2020, . 1263 [I-D.ietf-netconf-netconf-client-server] 1264 Watsen, K., "NETCONF Client and Server Models", Work in 1265 Progress, Internet-Draft, draft-ietf-netconf-netconf- 1266 client-server-19, 20 May 2020, 1267 . 1270 [I-D.ietf-netconf-restconf-client-server] 1271 Watsen, K., "RESTCONF Client and Server Models", Work in 1272 Progress, Internet-Draft, draft-ietf-netconf-restconf- 1273 client-server-19, 20 May 2020, 1274 . 1277 [I-D.ietf-netconf-ssh-client-server] 1278 Watsen, K. and G. Wu, "YANG Groupings for SSH Clients and 1279 SSH Servers", Work in Progress, Internet-Draft, draft- 1280 ietf-netconf-ssh-client-server-19, 20 May 2020, 1281 . 1284 [I-D.ietf-netconf-tcp-client-server] 1285 Watsen, K. and M. Scharf, "YANG Groupings for TCP Clients 1286 and TCP Servers", Work in Progress, Internet-Draft, draft- 1287 ietf-netconf-tcp-client-server-06, 16 June 2020, 1288 . 1291 [I-D.ietf-netconf-tls-client-server] 1292 Watsen, K. and G. Wu, "YANG Groupings for TLS Clients and 1293 TLS Servers", Work in Progress, Internet-Draft, draft- 1294 ietf-netconf-tls-client-server-19, 20 May 2020, 1295 . 1298 [I-D.ietf-netconf-trust-anchors] 1299 Watsen, K., "A YANG Data Model for a Truststore", Work in 1300 Progress, Internet-Draft, draft-ietf-netconf-trust- 1301 anchors-10, 20 May 2020, . 1304 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1305 DOI 10.17487/RFC3688, January 2004, 1306 . 1308 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1309 and A. Bierman, Ed., "Network Configuration Protocol 1310 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1311 . 1313 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1314 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1315 . 1317 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1318 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1319 . 1321 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1322 and R. Wilton, "Network Management Datastore Architecture 1323 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1324 . 1326 Appendix A. Change Log 1328 This section is to be removed before publishing as an RFC. 1330 A.1. 00 to 01 1332 * Modified Abstract and Intro to be more accurate wrt intended 1333 applicability. 1335 * In ietf-http-client, removed "protocol-version" and all auth 1336 schemes except "basic". 1338 * In ietf-http-client, factored out "client-identity-grouping" for 1339 proxy connections. 1341 * In ietf-http-server, removed "choice required-or-optional" and 1342 "choice local-or-external". 1344 * In ietf-http-server, moved the basic auth under a "choice auth- 1345 type" limited by new "feature basic-auth". 1347 A.2. 01 to 02 1349 * Removed the unused "external-client-auth-supported" feature from 1350 ietf-http-server. 1352 A.3. 02 to 03 1354 * Removed "protocol-versions" from ietf-http-server based on HTTP WG 1355 feedback. 1357 * Slightly restructured the "proxy-server" definition in ietf-http- 1358 client. 1360 * Added http-client example show proxy server use. 1362 * Added a "Note to Reviewers" note to first page. 1364 A.4. 03 to 04 1366 * Added a parent "container" to "client-identity-grouping" so that 1367 it could be better used by the proxy model. 1369 * Added a "choice" to the proxy model enabling selection of proxy 1370 types. 1372 * Added 'http-client-stack-grouping' and 'http-server-stack- 1373 grouping' convenience groupings. 1375 * Expanded "Data Model Overview section(s) [remove "wall" of tree 1376 diagrams]. 1378 * Updated the Security Considerations section. 1380 Acknowledgements 1382 The authors would like to thank for following for lively discussions 1383 on list and in the halls (ordered by last name): Mark Nottingham, Ben 1384 Schwartz, and Willy Tarreau. 1386 Author's Address 1388 Kent Watsen 1389 Watsen Networks 1391 Email: kent+ietf@watsen.net