idnits 2.17.1 draft-ietf-netconf-http-client-server-02.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 122 has weird spacing: '...assword str...' == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (March 8, 2020) is 1510 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 3 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 March 8, 2020 5 Expires: September 9, 2020 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-02 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 webservers or 17 browsers). 19 Editorial Note (To be removed by RFC Editor) 21 This draft contains many placeholder values that need to be replaced 22 with finalized values at the time of publication. This note 23 summarizes all of the substitutions that are needed. No other RFC 24 Editor instructions are specified elsewhere in this document. 26 Artwork in this document contains placeholder values for the date of 27 publication of this draft. Please apply the following replacement: 29 o "2020-03-08" --> the publication date of this draft 31 The following Appendix section is to be removed prior to publication: 33 o Appendix A. Change Log 35 Status of This Memo 37 This Internet-Draft is submitted in full conformance with the 38 provisions of BCP 78 and BCP 79. 40 Internet-Drafts are working documents of the Internet Engineering 41 Task Force (IETF). Note that other groups may also distribute 42 working documents as Internet-Drafts. The list of current Internet- 43 Drafts is at https://datatracker.ietf.org/drafts/current/. 45 Internet-Drafts are draft documents valid for a maximum of six months 46 and may be updated, replaced, or obsoleted by other documents at any 47 time. It is inappropriate to use Internet-Drafts as reference 48 material or to cite them other than as "work in progress." 49 This Internet-Draft will expire on September 9, 2020. 51 Copyright Notice 53 Copyright (c) 2020 IETF Trust and the persons identified as the 54 document authors. All rights reserved. 56 This document is subject to BCP 78 and the IETF Trust's Legal 57 Provisions Relating to IETF Documents 58 (https://trustee.ietf.org/license-info) in effect on the date of 59 publication of this document. Please review these documents 60 carefully, as they describe your rights and restrictions with respect 61 to this document. Code Components extracted from this document must 62 include Simplified BSD License text as described in Section 4.e of 63 the Trust Legal Provisions and are provided without warranty as 64 described in the Simplified BSD License. 66 Table of Contents 68 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 69 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 70 3. The HTTP Client Model . . . . . . . . . . . . . . . . . . . . 3 71 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 72 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3 73 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4 74 4. The HTTP Server Model . . . . . . . . . . . . . . . . . . . . 7 75 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 76 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 77 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 78 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 79 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 80 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 13 81 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 13 82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 83 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 84 7.2. Informative References . . . . . . . . . . . . . . . . . 14 85 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 16 86 A.1. 00 to 01 . . . . . . . . . . . . . . . . . . . . . . . . 16 87 A.2. 01 to 02 . . . . . . . . . . . . . . . . . . . . . . . . 16 88 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16 89 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 91 1. Introduction 93 This document defines two YANG 1.1 [RFC7950] modules: the first 94 defines a minimal grouping for configuring an HTTP client, and the 95 second defines a minimal grouping for configuring an HTTP server. It 96 is intended that these groupings will be used to help define the 97 configuration for simple HTTP-based protocols (not for complete 98 webservers or browsers). 100 2. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 3. The HTTP Client Model 110 3.1. Tree Diagram 112 This section provides a tree diagram [RFC8340] for the "ietf-http- 113 client" module. 115 module: ietf-http-client 117 grouping client-identity-grouping 118 +-- (auth-type) 119 +--:(basic) 120 +-- basic {basic-auth}? 121 +-- user-id string 122 +-- password string 123 grouping http-client-grouping 124 +-- client-identity 125 | +---u client-identity-grouping 126 +-- proxy-server! {proxy-connect}? 127 +-- tcp-client-parameters 128 | +---u tcpc:tcp-client-grouping 129 +-- tls-client-parameters 130 | +---u tlsc:tls-client-grouping 131 +-- proxy-client-identity 132 +---u client-identity-grouping 134 3.2. Example Usage 136 This section presents an example showing the http-client-grouping 137 populated with some data. 139 140 141 142 bob 143 secret 144 145 146 148 3.3. YANG Module 150 This YANG module has normative references to [RFC6991]. 152 file "ietf-http-client@2020-03-08.yang" 154 module ietf-http-client { 155 yang-version 1.1; 156 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 157 prefix httpc; 159 import ietf-tcp-client { 160 prefix tcpc; 161 reference 162 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 163 } 165 import ietf-tls-client { 166 prefix tlsc; 167 reference 168 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 169 } 171 import ietf-netconf-acm { 172 prefix nacm; 173 reference 174 "RFC 8341: Network Configuration Access Control Model"; 175 } 177 organization 178 "IETF NETCONF (Network Configuration) Working Group"; 180 contact 181 "WG Web: 182 WG List: 183 Author: Kent Watsen "; 185 description 186 "This module defines reusable groupings for HTTP clients that 187 can be used as a basis for specific HTTP client instances. 189 Copyright (c) 2019 IETF Trust and the persons identified 190 as authors of the code. All rights reserved. 192 Redistribution and use in source and binary forms, with 193 or without modification, is permitted pursuant to, and 194 subject to the license terms contained in, the Simplified 195 BSD License set forth in Section 4.c of the IETF Trust's 196 Legal Provisions Relating to IETF Documents 197 (https://trustee.ietf.org/license-info). 199 This version of this YANG module is part of RFC XXXX 200 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 201 itself for full legal notices. 203 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 204 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 205 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 206 are to be interpreted as described in BCP 14 (RFC 2119) 207 (RFC 8174) when, and only when, they appear in all 208 capitals, as shown here."; 210 revision 2020-03-08 { 211 description 212 "Initial version"; 213 reference 214 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 215 } 217 // Features 219 feature proxy-connect { 220 description 221 "Proxy connection configuration is configurable for 222 HTTP clients on the server implementing this feature."; 223 } 225 feature basic-auth { 226 description 227 "The 'basic-auth' feature indicates that the client 228 may be configured to use the 'basic' HTTP authentication 229 scheme."; 230 reference 231 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 232 } 234 // Groupings 235 grouping client-identity-grouping { 236 description 237 "The credentials used by the client to authenticate to 238 the HTTP server."; 239 choice auth-type { 240 nacm:default-deny-write; 241 mandatory true; 242 description 243 "The authentication type."; 244 case basic { 245 container basic { 246 if-feature "basic-auth"; 247 leaf user-id { 248 type string; 249 mandatory true; 250 description 251 "The user-id for the authenticating client."; 252 } 253 leaf password { 254 nacm:default-deny-all; 255 type string; 256 mandatory true; 257 description 258 "The password for the authenticating client."; 259 } 260 description 261 "The 'basic' HTTP scheme credentials."; 262 reference 263 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 264 } 265 } 266 } 267 } // grouping client-identity-grouping 269 grouping http-client-grouping { 270 description 271 "A reusable grouping for configuring a HTTP client, 272 including the IP address and port number it initiates 273 a connections to. 275 Note that this grouping uses fairly typical descendent 276 node names such that a stack of 'uses' statements will 277 have name conflicts. It is intended that the consuming 278 data model will resolve the issue (e.g., by wrapping 279 the 'uses' statement in a container called 280 'http-client-parameters'). This model purposely does 281 not do this itself so as to provide maximum flexibility 282 to consuming models."; 284 container client-identity { 285 description 286 "The identity the HTTP client should use when 287 authenticating itself to the HTTP server."; 288 uses client-identity-grouping; 289 } 291 container proxy-server { 292 nacm:default-deny-write; 293 if-feature "proxy-connect"; 294 presence true; // only so ex-http-client can pass validation? 295 container tcp-client-parameters { 296 description 297 "A wrapper around the TCP parameters to avoid 298 name collisions."; 299 uses "tcpc:tcp-client-grouping"; 300 } 301 container tls-client-parameters { 302 description 303 "A wrapper around the TLS parameters to avoid 304 name collisions."; 305 uses "tlsc:tls-client-grouping"; 306 } 307 container proxy-client-identity { 308 description 309 "The identity the HTTP client should use when 310 authenticating itself to the HTTP server."; 311 uses client-identity-grouping; 312 } 313 description 314 "Proxy server settings."; 315 } 316 } // grouping http-client-grouping 318 } // module ietf-http-client 320 322 4. The HTTP Server Model 324 4.1. Tree Diagram 326 This section provides a tree diagram [RFC8340] for the "ietf-http- 327 server" module. 329 module: ietf-http-server 331 grouping http-server-grouping 332 +-- server-name? string 333 +-- protocol-versions 334 | +-- protocol-version* enumeration 335 +-- client-authentication! {client-auth-config-supported}? 336 +-- users 337 +-- user* [user-id] 338 +-- user-id? string 339 +-- (auth-type)? 340 +--:(basic) 341 +-- basic {basic-auth}? 342 +-- user-id? string 343 +-- password? ianach:crypt-hash 345 4.2. Example Usage 347 This section presents an example showing the http-server-grouping 348 populated with some data. 350 351 foo.example.com 352 353 HTTP/1.1 354 HTTP/2.0 355 356 358 4.3. YANG Module 360 This YANG module has normative references to [RFC6991]. 362 file "ietf-http-server@2020-03-08.yang" 364 module ietf-http-server { 365 yang-version 1.1; 366 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 367 prefix https; 369 import iana-crypt-hash { 370 prefix ianach; 371 reference 372 "RFC 7317: A YANG Data Model for System Management"; 373 } 375 import ietf-netconf-acm { 376 prefix nacm; 377 reference 378 "RFC 8341: Network Configuration Access Control Model"; 379 } 381 organization 382 "IETF NETCONF (Network Configuration) Working Group"; 384 contact 385 "WG Web: 386 WG List: 387 Author: Kent Watsen "; 389 description 390 "This module defines reusable groupings for HTTP servers that 391 can be used as a basis for specific HTTP server instances. 393 Copyright (c) 2019 IETF Trust and the persons identified 394 as authors of the code. All rights reserved. 396 Redistribution and use in source and binary forms, with 397 or without modification, is permitted pursuant to, and 398 subject to the license terms contained in, the Simplified 399 BSD License set forth in Section 4.c of the IETF Trust's 400 Legal Provisions Relating to IETF Documents 401 (https://trustee.ietf.org/license-info). 403 This version of this YANG module is part of RFC XXXX 404 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 405 itself for full legal notices. 407 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 408 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 409 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 410 are to be interpreted as described in BCP 14 (RFC 2119) 411 (RFC 8174) when, and only when, they appear in all 412 capitals, as shown here."; 414 revision 2020-03-08 { 415 description 416 "Initial version"; 417 reference 418 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 419 } 421 // Features 423 feature client-auth-config-supported { 424 description 425 "Indicates that the configuration for how to authenticate 426 clients can be configured herein, as opposed to in an 427 application specific location. That is, to support the 428 consuming data models that prefer to place client 429 authentication with client definitions, rather then 430 in a data model principally concerned with configuring 431 the transport."; 432 } 434 feature basic-auth { 435 description 436 "The 'basic-auth' feature indicates that the server 437 may be configured authenticate users using the 'basic' 438 HTTP authentication scheme."; 439 reference 440 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 441 } 443 // Groupings 445 grouping http-server-grouping { 446 description 447 "A reusable grouping for configuring an HTTP server. 449 Note that this grouping uses fairly typical descendent 450 node names such that a stack of 'uses' statements will 451 have name conflicts. It is intended that the consuming 452 data model will resolve the issue (e.g., by wrapping 453 the 'uses' statement in a container called 454 'http-server-parameters'). This model purposely does 455 not do this itself so as to provide maximum flexibility 456 to consuming models."; 458 leaf server-name { 459 nacm:default-deny-write; 460 type string; 461 description 462 "The value of the 'Server' header field. If not set, then 463 underlying software's default value is used. Set to the 464 empty string to disable."; 465 } 467 container protocol-versions { 468 nacm:default-deny-write; 469 description 470 "A list of HTTP protocol versions supported by this 471 server."; 473 leaf-list protocol-version { 474 type enumeration { 475 enum "HTTP/1.0" { 476 description 477 "The server supports the 'HTTP/1.0' protocol."; 478 } 479 enum "HTTP/1.1" { 480 description 481 "The server supports the 'HTTP/1.1' protocol."; 482 } 483 enum "HTTP/2.0" { 484 description 485 "The server supports the 'HTTP/2.0' protocol."; 486 } 487 } 488 description 489 "An HTTP protocol version supported by this server."; 490 } 491 } 493 container client-authentication { 494 if-feature "client-auth-config-supported"; 495 nacm:default-deny-write; 496 presence 497 "Indicates that HTTP based client authentication is 498 supported (i.e., the server will request that the 499 HTTP client send authenticate when needed). This 500 is needed as some HTTP-based protocols may only 501 support, e.g., TLS-level client authentication."; 502 description 503 "Specifies how the HTTP server can authenticate HTTP 504 clients."; 505 container users { 506 description 507 "A list of locally configured users."; 508 list user { 509 key user-id; 510 description 511 "The list of local users configured on this device."; 512 leaf user-id { 513 type string; 514 description 515 "The user-id for the authenticating client."; 516 } 517 choice auth-type { 518 description 519 "The authentication type."; 520 container basic { 521 if-feature "basic-auth"; 522 leaf user-id { 523 type string; 524 description 525 "The user-id for the authenticating client."; 526 } 527 leaf password { 528 nacm:default-deny-write; 529 type ianach:crypt-hash; 530 description 531 "The password for the authenticating client."; 532 } 533 description 534 "The 'basic' HTTP scheme credentials."; 535 reference 536 "RFC 7617: 537 The 'Basic' HTTP Authentication Scheme"; 538 } 539 } 540 } 541 } 542 } // container client-authentication 543 } // grouping http-server-grouping 544 } 546 548 5. Security Considerations 550 The YANG modules defined in this document are designed to be accessed 551 via YANG based management protocols, such as NETCONF [RFC6241] and 552 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 553 implement secure transport layers (e.g., SSH, HTTP) with mutual 554 authentication. 556 The NETCONF access control model (NACM) [RFC8341] provides the means 557 to restrict access for particular users to a pre-configured subset of 558 all available protocol operations and content. 560 Since the modules defined in this document only define groupings, 561 these considerations are primarily for the designers of other modules 562 that use these groupings. 564 There are a number of data nodes defined in the YANG modules that are 565 writable/creatable/deletable (i.e., config true, which is the 566 default). These data nodes may be considered sensitive or vulnerable 567 in some network environments. Write operations (e.g., edit-config) 568 to these data nodes without proper protection can have a negative 569 effect on network operations. These are the subtrees and data nodes 570 and their sensitivity/vulnerability: 572 FIXME: (pending - TBD) 574 Some of the readable data nodes in the YANG modules may be considered 575 sensitive or vulnerable in some network environments. It is thus 576 important to control read access (e.g., via get, get-config, or 577 notification) to these data nodes. These are the subtrees and data 578 nodes and their sensitivity/vulnerability: 580 FIXME: (pending client auth params?) 582 Some of the RPC operations in this YANG module may be considered 583 sensitive or vulnerable in some network environments. It is thus 584 important to control access to these operations. These are the 585 operations and their sensitivity/vulnerability: 587 The modules defined in this document do not define any 'RPC' or 588 'action' statements. 590 6. IANA Considerations 592 6.1. The IETF XML Registry 594 This document registers two URIs in the "ns" subregistry of the IETF 595 XML Registry [RFC3688]. Following the format in [RFC3688], the 596 following registrations are requested: 598 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 599 Registrant Contact: The NETCONF WG of the IETF. 600 XML: N/A, the requested URI is an XML namespace. 602 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 603 Registrant Contact: The NETCONF WG of the IETF. 604 XML: N/A, the requested URI is an XML namespace. 606 6.2. The YANG Module Names Registry 608 This document registers two YANG modules in the YANG Module Names 609 registry [RFC6020]. Following the format in [RFC6020], the following 610 registrations are requested: 612 name: ietf-http-client 613 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 614 prefix: httpc 615 reference: RFC XXXX 617 name: ietf-http-server 618 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 619 prefix: https 620 reference: RFC XXXX 622 7. References 624 7.1. Normative References 626 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 627 Requirement Levels", BCP 14, RFC 2119, 628 DOI 10.17487/RFC2119, March 1997, 629 . 631 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 632 the Network Configuration Protocol (NETCONF)", RFC 6020, 633 DOI 10.17487/RFC6020, October 2010, 634 . 636 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 637 RFC 6991, DOI 10.17487/RFC6991, July 2013, 638 . 640 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 641 RFC 7950, DOI 10.17487/RFC7950, August 2016, 642 . 644 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 645 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 646 May 2017, . 648 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 649 Access Control Model", STD 91, RFC 8341, 650 DOI 10.17487/RFC8341, March 2018, 651 . 653 7.2. Informative References 655 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 656 DOI 10.17487/RFC3688, January 2004, 657 . 659 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 660 and A. Bierman, Ed., "Network Configuration Protocol 661 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 662 . 664 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 665 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 666 . 668 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 669 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 670 . 672 Appendix A. Change Log 674 A.1. 00 to 01 676 o Modified Abstract and Intro to be more accurate wrt intended 677 applicability. 679 o In ietf-http-client, removed "protocol-version" and all auth 680 schemes except "basic". 682 o In ietf-http-client, factored out "client-identity-grouping" for 683 proxy connections. 685 o In ietf-http-server, removed "choice required-or-optional" and 686 "choice local-or-external". 688 o In ietf-http-server, moved the basic auth under a "choice auth- 689 type" limited by new "feature basic-auth". 691 A.2. 01 to 02 693 o Removed the unused "external-client-auth-supported" feature from 694 ietf-http-server. 696 Acknowledgements 698 The authors would like to thank for following for lively discussions 699 on list and in the halls (ordered by last name): TBD 701 Author's Address 703 Kent Watsen 704 Watsen Networks 706 EMail: kent+ietf@watsen.net