idnits 2.17.1 draft-ietf-netconf-http-client-server-01.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 121 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 (November 20, 2019) is 1609 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 November 20, 2019 5 Expires: May 23, 2020 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-ietf-netconf-http-client-server-01 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 "2019-11-20" --> 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 May 23, 2020. 51 Copyright Notice 53 Copyright (c) 2019 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 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 16 88 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 90 1. Introduction 92 This document defines two YANG 1.1 [RFC7950] modules: the first 93 defines a minimal grouping for configuring an HTTP client, and the 94 second defines a minimal grouping for configuring an HTTP server. It 95 is intended that these groupings will be used to help define the 96 configuration for simple HTTP-based protocols (not for complete 97 webservers or browsers). 99 2. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 103 "OPTIONAL" in this document are to be interpreted as described in BCP 104 14 [RFC2119] [RFC8174] when, and only when, they appear in all 105 capitals, as shown here. 107 3. The HTTP Client Model 109 3.1. Tree Diagram 111 This section provides a tree diagram [RFC8340] for the "ietf-http- 112 client" module. 114 module: ietf-http-client 116 grouping client-identity-grouping 117 +-- (auth-type) 118 +--:(basic) 119 +-- basic {basic-auth}? 120 +-- user-id string 121 +-- password string 122 grouping http-client-grouping 123 +-- client-identity 124 | +---u client-identity-grouping 125 +-- proxy-server! {proxy-connect}? 126 +-- tcp-client-parameters 127 | +---u tcpc:tcp-client-grouping 128 +-- tls-client-parameters 129 | +---u tlsc:tls-client-grouping 130 +-- proxy-client-identity 131 +---u client-identity-grouping 133 3.2. Example Usage 135 This section presents an example showing the http-client-grouping 136 populated with some data. 138 139 140 141 bob 142 secret 143 144 145 147 3.3. YANG Module 149 This YANG module has normative references to [RFC6991]. 151 file "ietf-http-client@2019-11-20.yang" 153 module ietf-http-client { 154 yang-version 1.1; 155 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 156 prefix httpc; 158 import ietf-tcp-client { 159 prefix tcpc; 160 reference 161 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 162 } 164 import ietf-tls-client { 165 prefix tlsc; 166 reference 167 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 168 } 170 import ietf-netconf-acm { 171 prefix nacm; 172 reference 173 "RFC 8341: Network Configuration Access Control Model"; 174 } 176 organization 177 "IETF NETCONF (Network Configuration) Working Group"; 179 contact 180 "WG Web: 181 WG List: 182 Author: Kent Watsen "; 184 description 185 "This module defines reusable groupings for HTTP clients that 186 can be used as a basis for specific HTTP client instances. 188 Copyright (c) 2019 IETF Trust and the persons identified 189 as authors of the code. All rights reserved. 191 Redistribution and use in source and binary forms, with 192 or without modification, is permitted pursuant to, and 193 subject to the license terms contained in, the Simplified 194 BSD License set forth in Section 4.c of the IETF Trust's 195 Legal Provisions Relating to IETF Documents 196 (https://trustee.ietf.org/license-info). 198 This version of this YANG module is part of RFC XXXX 199 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 200 itself for full legal notices. 202 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 203 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 204 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 205 are to be interpreted as described in BCP 14 (RFC 2119) 206 (RFC 8174) when, and only when, they appear in all 207 capitals, as shown here."; 209 revision 2019-11-20 { 210 description 211 "Initial version"; 212 reference 213 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 214 } 216 // Features 218 feature proxy-connect { 219 description 220 "Proxy connection configuration is configurable for 221 HTTP clients on the server implementing this feature."; 222 } 224 feature basic-auth { 225 description 226 "The 'basic-auth' feature indicates that the client 227 may be configured to use the 'basic' HTTP authentication 228 scheme."; 229 reference 230 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 231 } 233 // Groupings 234 grouping client-identity-grouping { 235 description 236 "The credentials used by the client to authenticate to 237 the HTTP server."; 238 choice auth-type { 239 nacm:default-deny-write; 240 mandatory true; 241 description 242 "The authentication type."; 243 case basic { 244 container basic { 245 if-feature "basic-auth"; 246 leaf user-id { 247 type string; 248 mandatory true; 249 description 250 "The user-id for the authenticating client."; 251 } 252 leaf password { 253 nacm:default-deny-all; 254 type string; 255 mandatory true; 256 description 257 "The password for the authenticating client."; 258 } 259 description 260 "The 'basic' HTTP scheme credentials."; 261 reference 262 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 263 } 264 } 265 } 266 } // grouping client-identity-grouping 268 grouping http-client-grouping { 269 description 270 "A reusable grouping for configuring a HTTP client, 271 including the IP address and port number it initiates 272 a connections to. 274 Note that this grouping uses fairly typical descendent 275 node names such that a stack of 'uses' statements will 276 have name conflicts. It is intended that the consuming 277 data model will resolve the issue (e.g., by wrapping 278 the 'uses' statement in a container called 279 'http-client-parameters'). This model purposely does 280 not do this itself so as to provide maximum flexibility 281 to consuming models."; 283 container client-identity { 284 description 285 "The identity the HTTP client should use when 286 authenticating itself to the HTTP server."; 287 uses client-identity-grouping; 288 } 290 container proxy-server { 291 nacm:default-deny-write; 292 if-feature "proxy-connect"; 293 presence true; // only so ex-http-client can pass validation? 294 container tcp-client-parameters { 295 description 296 "A wrapper around the TCP parameters to avoid 297 name collisions."; 298 uses "tcpc:tcp-client-grouping"; 299 } 300 container tls-client-parameters { 301 description 302 "A wrapper around the TLS parameters to avoid 303 name collisions."; 304 uses "tlsc:tls-client-grouping"; 305 } 306 container proxy-client-identity { 307 description 308 "The identity the HTTP client should use when 309 authenticating itself to the HTTP server."; 310 uses client-identity-grouping; 311 } 312 description 313 "Proxy server settings."; 314 } 315 } // grouping http-client-grouping 317 } // module ietf-http-client 319 321 4. The HTTP Server Model 323 4.1. Tree Diagram 325 This section provides a tree diagram [RFC8340] for the "ietf-http- 326 server" module. 328 module: ietf-http-server 330 grouping http-server-grouping 331 +-- server-name? string 332 +-- protocol-versions 333 | +-- protocol-version* enumeration 334 +-- client-authentication! {client-auth-config-supported}? 335 +-- users 336 +-- user* [user-id] 337 +-- user-id? string 338 +-- (auth-type)? 339 +--:(basic) 340 +-- basic {basic-auth}? 341 +-- user-id? string 342 +-- password? ianach:crypt-hash 344 4.2. Example Usage 346 This section presents an example showing the http-server-grouping 347 populated with some data. 349 350 foo.example.com 351 352 HTTP/1.1 353 HTTP/2.0 354 355 357 4.3. YANG Module 359 This YANG module has normative references to [RFC6991]. 361 file "ietf-http-server@2019-11-20.yang" 363 module ietf-http-server { 364 yang-version 1.1; 365 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 366 prefix https; 368 import iana-crypt-hash { 369 prefix ianach; 370 reference 371 "RFC 7317: A YANG Data Model for System Management"; 372 } 374 import ietf-netconf-acm { 375 prefix nacm; 376 reference 377 "RFC 8341: Network Configuration Access Control Model"; 378 } 380 organization 381 "IETF NETCONF (Network Configuration) Working Group"; 383 contact 384 "WG Web: 385 WG List: 386 Author: Kent Watsen "; 388 description 389 "This module defines reusable groupings for HTTP servers that 390 can be used as a basis for specific HTTP server instances. 392 Copyright (c) 2019 IETF Trust and the persons identified 393 as authors of the code. All rights reserved. 395 Redistribution and use in source and binary forms, with 396 or without modification, is permitted pursuant to, and 397 subject to the license terms contained in, the Simplified 398 BSD License set forth in Section 4.c of the IETF Trust's 399 Legal Provisions Relating to IETF Documents 400 (https://trustee.ietf.org/license-info). 402 This version of this YANG module is part of RFC XXXX 403 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 404 itself for full legal notices. 406 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 407 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 408 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 409 are to be interpreted as described in BCP 14 (RFC 2119) 410 (RFC 8174) when, and only when, they appear in all 411 capitals, as shown here."; 413 revision 2019-11-20 { 414 description 415 "Initial version"; 416 reference 417 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 418 } 420 // Features 422 feature client-auth-config-supported { 423 description 424 "Indicates that the configuration for how to authenticate 425 clients can be configured herein, as opposed to in an 426 application specific location. That is, to support the 427 consuming data models that prefer to place client 428 authentication with client definitions, rather then 429 in a data model principally concerned with configuring 430 the transport."; 431 } 433 feature external-client-auth-supported { 434 description 435 "Indicates that the HTTP server supports external configuration 436 of client credentials."; 437 } 439 feature basic-auth { 440 description 441 "The 'basic-auth' feature indicates that the server 442 may be configured authenticate users using the 'basic' 443 HTTP authentication scheme."; 444 reference 445 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 446 } 448 // Groupings 450 grouping http-server-grouping { 451 description 452 "A reusable grouping for configuring an HTTP server. 454 Note that this grouping uses fairly typical descendent 455 node names such that a stack of 'uses' statements will 456 have name conflicts. It is intended that the consuming 457 data model will resolve the issue (e.g., by wrapping 458 the 'uses' statement in a container called 459 'http-server-parameters'). This model purposely does 460 not do this itself so as to provide maximum flexibility 461 to consuming models."; 463 leaf server-name { 464 nacm:default-deny-write; 465 type string; 466 description 467 "The value of the 'Server' header field. If not set, then 468 underlying software's default value is used. Set to the 469 empty string to disable."; 470 } 471 container protocol-versions { 472 nacm:default-deny-write; 473 description 474 "A list of HTTP protocol versions supported by this 475 server."; 476 leaf-list protocol-version { 477 type enumeration { 478 enum "HTTP/1.0" { 479 description 480 "The server supports the 'HTTP/1.0' protocol."; 481 } 482 enum "HTTP/1.1" { 483 description 484 "The server supports the 'HTTP/1.1' protocol."; 485 } 486 enum "HTTP/2.0" { 487 description 488 "The server supports the 'HTTP/2.0' protocol."; 489 } 490 } 491 description 492 "An HTTP protocol version supported by this server."; 493 } 494 } 496 container client-authentication { 497 if-feature "client-auth-config-supported"; 498 nacm:default-deny-write; 499 presence 500 "Indicates that HTTP based client authentication is 501 supported (i.e., the server will request that the 502 HTTP client send authenticate when needed). This 503 is needed as some HTTP-based protocols may only 504 support, e.g., TLS-level client authentication."; 505 description 506 "Specifies how the HTTP server can authenticate HTTP 507 clients."; 508 container users { 509 description 510 "A list of locally configured users."; 511 list user { 512 key user-id; 513 description 514 "The list of local users configured on this device."; 515 leaf user-id { 516 type string; 517 description 518 "The user-id for the authenticating client."; 520 } 521 choice auth-type { 522 description 523 "The authentication type."; 524 container basic { 525 if-feature "basic-auth"; 526 leaf user-id { 527 type string; 528 description 529 "The user-id for the authenticating client."; 530 } 531 leaf password { 532 nacm:default-deny-write; 533 type ianach:crypt-hash; 534 description 535 "The password for the authenticating client."; 536 } 537 description 538 "The 'basic' HTTP scheme credentials."; 539 reference 540 "RFC 7617: 541 The 'Basic' HTTP Authentication Scheme"; 542 } 543 } 544 } 545 } 546 } // container client-authentication 547 } // grouping http-server-grouping 548 } 550 552 5. Security Considerations 554 The YANG modules defined in this document are designed to be accessed 555 via YANG based management protocols, such as NETCONF [RFC6241] and 556 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 557 implement secure transport layers (e.g., SSH, HTTP) with mutual 558 authentication. 560 The NETCONF access control model (NACM) [RFC8341] provides the means 561 to restrict access for particular users to a pre-configured subset of 562 all available protocol operations and content. 564 Since the modules defined in this document only define groupings, 565 these considerations are primarily for the designers of other modules 566 that use these groupings. 568 There are a number of data nodes defined in the YANG modules that are 569 writable/creatable/deletable (i.e., config true, which is the 570 default). These data nodes may be considered sensitive or vulnerable 571 in some network environments. Write operations (e.g., edit-config) 572 to these data nodes without proper protection can have a negative 573 effect on network operations. These are the subtrees and data nodes 574 and their sensitivity/vulnerability: 576 FIXME: (pending - TBD) 578 Some of the readable data nodes in the YANG modules may be considered 579 sensitive or vulnerable in some network environments. It is thus 580 important to control read access (e.g., via get, get-config, or 581 notification) to these data nodes. These are the subtrees and data 582 nodes and their sensitivity/vulnerability: 584 FIXME: (pending client auth params?) 586 Some of the RPC operations in this YANG module may be considered 587 sensitive or vulnerable in some network environments. It is thus 588 important to control access to these operations. These are the 589 operations and their sensitivity/vulnerability: 591 The modules defined in this document do not define any 'RPC' or 592 'action' statements. 594 6. IANA Considerations 596 6.1. The IETF XML Registry 598 This document registers two URIs in the "ns" subregistry of the IETF 599 XML Registry [RFC3688]. Following the format in [RFC3688], the 600 following registrations are requested: 602 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 603 Registrant Contact: The NETCONF WG of the IETF. 604 XML: N/A, the requested URI is an XML namespace. 606 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 607 Registrant Contact: The NETCONF WG of the IETF. 608 XML: N/A, the requested URI is an XML namespace. 610 6.2. The YANG Module Names Registry 612 This document registers two YANG modules in the YANG Module Names 613 registry [RFC6020]. Following the format in [RFC6020], the following 614 registrations are requested: 616 name: ietf-http-client 617 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 618 prefix: httpc 619 reference: RFC XXXX 621 name: ietf-http-server 622 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 623 prefix: https 624 reference: RFC XXXX 626 7. References 628 7.1. Normative References 630 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 631 Requirement Levels", BCP 14, RFC 2119, 632 DOI 10.17487/RFC2119, March 1997, 633 . 635 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 636 the Network Configuration Protocol (NETCONF)", RFC 6020, 637 DOI 10.17487/RFC6020, October 2010, 638 . 640 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 641 RFC 6991, DOI 10.17487/RFC6991, July 2013, 642 . 644 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 645 RFC 7950, DOI 10.17487/RFC7950, August 2016, 646 . 648 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 649 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 650 May 2017, . 652 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 653 Access Control Model", STD 91, RFC 8341, 654 DOI 10.17487/RFC8341, March 2018, 655 . 657 7.2. Informative References 659 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 660 DOI 10.17487/RFC3688, January 2004, 661 . 663 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 664 and A. Bierman, Ed., "Network Configuration Protocol 665 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 666 . 668 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 669 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 670 . 672 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 673 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 674 . 676 Appendix A. Change Log 678 A.1. 00 to 01 680 o Modified Abstract and Intro to be more accurate wrt intended 681 applicability. 683 o In ietf-http-client, removed "protocol-version" and all auth 684 schemes except "basic". 686 o In ietf-http-client, factored out "client-identity-grouping" for 687 proxy connections. 689 o In ietf-http-server, removed "choice required-or-optional" and 690 "choice local-or-external". 692 o In ietf-http-server, moved the basic auth under a "choice auth- 693 type" limited by new "feature basic-auth". 695 Acknowledgements 697 The authors would like to thank for following for lively discussions 698 on list and in the halls (ordered by last name): TBD 700 Author's Address 702 Kent Watsen 703 Watsen Networks 705 EMail: kent+ietf@watsen.net