idnits 2.17.1 draft-kwatsen-netconf-http-client-server-05.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 116 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 1, 2019) is 1610 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 1, 2019 5 Expires: May 4, 2020 7 YANG Groupings for HTTP Clients and HTTP Servers 8 draft-kwatsen-netconf-http-client-server-05 10 Abstract 12 This document defines two YANG modules: the first defines a minimal 13 grouping for configuring a generic HTTP client, and the second 14 defines a minimal grouping for configuring a generic HTTP server. It 15 is intended that these groupings will be used by higher-level HTTP- 16 based protocols. 18 Editorial Note (To be removed by RFC Editor) 20 This draft contains many placeholder values that need to be replaced 21 with finalized values at the time of publication. This note 22 summarizes all of the substitutions that are needed. No other RFC 23 Editor instructions are specified elsewhere in this document. 25 Artwork in this document contains placeholder values for the date of 26 publication of this draft. Please apply the following replacement: 28 o "2019-11-02" --> the publication date of this draft 30 The following Appendix section is to be removed prior to publication: 32 o Appendix A. Change Log 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on May 4, 2020. 50 Copyright Notice 52 Copyright (c) 2019 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. The HTTP Client Model . . . . . . . . . . . . . . . . . . . . 3 70 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 3 71 3.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 3 72 3.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 4 73 4. The HTTP Server Model . . . . . . . . . . . . . . . . . . . . 7 74 4.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 7 75 4.2. Example Usage . . . . . . . . . . . . . . . . . . . . . . 8 76 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 77 5. Security Considerations . . . . . . . . . . . . . . . . . . . 13 78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 79 6.1. The IETF XML Registry . . . . . . . . . . . . . . . . . . 14 80 6.2. The YANG Module Names Registry . . . . . . . . . . . . . 15 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 7.1. Normative References . . . . . . . . . . . . . . . . . . 15 83 7.2. Informative References . . . . . . . . . . . . . . . . . 16 84 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 86 1. Introduction 88 This document defines two YANG 1.1 [RFC7950] modules: the first 89 defines a grouping for configuring a generic HTTP client, and the 90 second defines a grouping for configuring a generic HTTP server. It 91 is intended that these groupings will be used by higher-level HTTP- 92 based protocols. 94 2. Terminology 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14 [RFC2119] [RFC8174] when, and only when, they appear in all 100 capitals, as shown here. 102 3. The HTTP Client Model 104 3.1. Tree Diagram 106 This section provides a tree diagram [RFC8340] for the "ietf-http- 107 client" module. 109 module: ietf-http-client 111 grouping client-identity-grouping 112 +-- (auth-type) 113 +--:(basic) 114 +-- basic {basic-auth}? 115 +-- user-id string 116 +-- password string 117 grouping http-client-grouping 118 +-- client-identity 119 | +---u client-identity-grouping 120 +-- proxy-server! {proxy-connect}? 121 +-- tcp-client-parameters 122 | +---u tcpc:tcp-client-grouping 123 +-- tls-client-parameters 124 | +---u tlsc:tls-client-grouping 125 +-- proxy-client-identity 126 +---u client-identity-grouping 128 3.2. Example Usage 130 This section presents an example showing the http-client-grouping 131 populated with some data. 133 134 135 136 bob 137 secret 138 139 140 142 3.3. YANG Module 144 This YANG module has normative references to [RFC6991]. 146 file "ietf-http-client@2019-11-02.yang" 148 module ietf-http-client { 149 yang-version 1.1; 150 namespace "urn:ietf:params:xml:ns:yang:ietf-http-client"; 151 prefix httpc; 153 import ietf-tcp-client { 154 prefix tcpc; 155 reference 156 "RFC AAAA: YANG Groupings for TCP Clients and TCP Servers"; 157 } 159 import ietf-tls-client { 160 prefix tlsc; 161 reference 162 "RFC BBBB: YANG Groupings for TLS Clients and TLS Servers"; 163 } 165 import ietf-netconf-acm { 166 prefix nacm; 167 reference 168 "RFC 8341: Network Configuration Access Control Model"; 169 } 171 organization 172 "IETF NETCONF (Network Configuration) Working Group"; 174 contact 175 "WG Web: 176 WG List: 177 Author: Kent Watsen "; 179 description 180 "This module defines reusable groupings for HTTP clients that 181 can be used as a basis for specific HTTP client instances. 183 Copyright (c) 2019 IETF Trust and the persons identified 184 as authors of the code. All rights reserved. 186 Redistribution and use in source and binary forms, with 187 or without modification, is permitted pursuant to, and 188 subject to the license terms contained in, the Simplified 189 BSD License set forth in Section 4.c of the IETF Trust's 190 Legal Provisions Relating to IETF Documents 191 (https://trustee.ietf.org/license-info). 193 This version of this YANG module is part of RFC XXXX 194 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 195 itself for full legal notices.; 197 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 198 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 199 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 200 are to be interpreted as described in BCP 14 (RFC 2119) 201 (RFC 8174) when, and only when, they appear in all 202 capitals, as shown here."; 204 revision 2019-11-02 { 205 description 206 "Initial version"; 207 reference 208 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 209 } 211 // Features 213 feature proxy-connect { 214 description 215 "Proxy connection configuration is configurable for 216 HTTP clients on the server implementing this feature."; 217 } 219 feature basic-auth { 220 description 221 "The 'basic-auth' feature indicates that the client 222 may be configured to use the 'basic' HTTP authentication 223 scheme."; 224 reference 225 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 226 } 228 // Groupings 230 grouping client-identity-grouping { 231 description 232 "The credentials used by the client to authenticate to 233 the HTTP server."; 234 choice auth-type { 235 nacm:default-deny-write; 236 mandatory true; 237 description 238 "The authentication type."; 239 case basic { 240 container basic { 241 if-feature "basic-auth"; 242 leaf user-id { 243 type string; 244 mandatory true; 245 description 246 "The user-id for the authenticating client."; 247 } 248 leaf password { 249 nacm:default-deny-all; 250 type string; 251 mandatory true; 252 description 253 "The password for the authenticating client."; 254 } 255 description 256 "The 'basic' HTTP scheme credentials."; 257 reference 258 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 259 } 260 } 261 } 262 } // grouping client-identity-grouping 264 grouping http-client-grouping { 265 description 266 "A reusable grouping for configuring a HTTP client, 267 including the IP address and port number it initiates 268 a connections to. 270 Note that this grouping uses fairly typical descendent 271 node names such that a stack of 'uses' statements will 272 have name conflicts. It is intended that the consuming 273 data model will resolve the issue (e.g., by wrapping 274 the 'uses' statement in a container called 275 'http-client-parameters'). This model purposely does 276 not do this itself so as to provide maximum flexibility 277 to consuming models."; 279 container client-identity { 280 description 281 "The identity the HTTP client should use when 282 authenticating itself to the HTTP server."; 283 uses client-identity-grouping; 284 } 285 container proxy-server { 286 nacm:default-deny-write; 287 if-feature "proxy-connect"; 288 presence true; // only so ex-http-client can pass validation? 289 container tcp-client-parameters { 290 description 291 "A wrapper around the TCP parameters to avoid 292 name collisions."; 293 uses "tcpc:tcp-client-grouping"; 294 } 295 container tls-client-parameters { 296 description 297 "A wrapper around the TLS parameters to avoid 298 name collisions."; 299 uses "tlsc:tls-client-grouping"; 300 } 301 container proxy-client-identity { 302 description 303 "The identity the HTTP client should use when 304 authenticating itself to the HTTP server."; 305 uses client-identity-grouping; 306 } 307 description 308 "Proxy server settings."; 309 } 310 } // grouping http-client-grouping 312 } // module ietf-http-client 314 316 4. The HTTP Server Model 318 4.1. Tree Diagram 320 This section provides a tree diagram [RFC8340] for the "ietf-http- 321 server" module. 323 module: ietf-http-server 325 grouping http-server-grouping 326 +-- server-name? string 327 +-- protocol-versions 328 | +-- protocol-version* enumeration 329 +-- client-authentication! 330 +-- (required-or-optional) 331 | +--:(required) 332 | | +-- required? empty 333 | +--:(optional) 334 | +-- optional? empty 335 +-- (local-or-external) 336 +--:(local) {local-client-auth-supported}? 337 | +-- users 338 | +-- user* [user-id] 339 | +-- user-id? string 340 | +-- (auth-type)? 341 | +--:(basic) 342 | +-- basic {basic-auth}? 343 | +-- user-id? string 344 | +-- password? ianach:crypt-hash 345 +--:(external) {external-client-auth-supported}? 346 +-- client-auth-defined-elsewhere? empty 348 4.2. Example Usage 350 This section presents an example showing the http-server-grouping 351 populated with some data. 353 354 foo.example.com 355 356 HTTP/1.1 357 HTTP/2.0 358 359 360 361 362 363 365 4.3. YANG Module 367 This YANG module has normative references to [RFC6991]. 369 file "ietf-http-server@2019-11-02.yang" 370 module ietf-http-server { 371 yang-version 1.1; 372 namespace "urn:ietf:params:xml:ns:yang:ietf-http-server"; 373 prefix https; 375 import iana-crypt-hash { 376 prefix ianach; 377 reference 378 "RFC 7317: A YANG Data Model for System Management"; 379 } 381 import ietf-netconf-acm { 382 prefix nacm; 383 reference 384 "RFC 8341: Network Configuration Access Control Model"; 385 } 387 organization 388 "IETF NETCONF (Network Configuration) Working Group"; 390 contact 391 "WG Web: 392 WG List: 393 Author: Kent Watsen "; 395 description 396 "This module defines reusable groupings for HTTP servers that 397 can be used as a basis for specific HTTP server instances. 399 Copyright (c) 2019 IETF Trust and the persons identified 400 as authors of the code. All rights reserved. 402 Redistribution and use in source and binary forms, with 403 or without modification, is permitted pursuant to, and 404 subject to the license terms contained in, the Simplified 405 BSD License set forth in Section 4.c of the IETF Trust's 406 Legal Provisions Relating to IETF Documents 407 (https://trustee.ietf.org/license-info). 409 This version of this YANG module is part of RFC XXXX 410 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC 411 itself for full legal notices.; 413 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 414 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 415 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 416 are to be interpreted as described in BCP 14 (RFC 2119) 417 (RFC 8174) when, and only when, they appear in all 418 capitals, as shown here."; 420 revision 2019-11-02 { 421 description 422 "Initial version"; 423 reference 424 "RFC XXXX: YANG Groupings for HTTP Clients and HTTP Servers"; 425 } 427 // Features 429 feature local-client-auth-supported { 430 description 431 "Indicates that the HTTP server supports local configuration 432 of client credentials."; 433 } 435 feature external-client-auth-supported { 436 description 437 "Indicates that the HTTP server supports external configuration 438 of client credentials."; 439 } 441 feature basic-auth { 442 description 443 "The 'basic-auth' feature indicates that the server 444 may be configured authenticate users using the 'basic' 445 HTTP authentication scheme."; 446 reference 447 "RFC 7617: The 'Basic' HTTP Authentication Scheme"; 448 } 450 // Groupings 452 grouping http-server-grouping { 453 description 454 "A reusable grouping for configuring an HTTP server. 456 Note that this grouping uses fairly typical descendent 457 node names such that a stack of 'uses' statements will 458 have name conflicts. It is intended that the consuming 459 data model will resolve the issue (e.g., by wrapping 460 the 'uses' statement in a container called 461 'http-server-parameters'). This model purposely does 462 not do this itself so as to provide maximum flexibility 463 to consuming models."; 465 leaf server-name { 466 nacm:default-deny-write; 467 type string; 468 description 469 "The value of the 'Server' header field. If not set, then 470 underlying software's default value is used. Set to the 471 empty string to disable."; 472 } 474 container protocol-versions { 475 nacm:default-deny-write; 476 description 477 "A list of HTTP protocol versions supported by this 478 server."; 479 leaf-list protocol-version { 480 type enumeration { 481 enum "HTTP/1.0" { 482 description 483 "The server supports the 'HTTP/1.0' protocol."; 484 } 485 enum "HTTP/1.1" { 486 description 487 "The server supports the 'HTTP/1.1' protocol."; 488 } 489 enum "HTTP/2.0" { 490 description 491 "The server supports the 'HTTP/2.0' protocol."; 492 } 493 } 494 description 495 "An HTTP protocol version supported by this server."; 496 } 497 } 499 container client-authentication { 500 nacm:default-deny-write; 501 presence 502 "Indicates that HTTP based client authentication is 503 supported (i.e., the server will request that the 504 HTTP client send authenticate when needed). This 505 is needed as some HTTP-based protocols may only 506 support, e.g., TLS-level client authentication."; 507 description 508 "Specifies if HTTP client authentication is required or 509 optional, and specifies if the credentials needed to 510 authenticate the HTTP client are configured locally 511 or externally."; 512 choice required-or-optional { 513 mandatory true; // or default to 'required' ? 514 description 515 "Indicates if HTTP-level client authentication is required 516 or optional. This is necessary for some protocols (e.g., 517 RESTCONF) that may optionally authenticate a client via 518 TLS-level authentication, HTTP-level authentication, or 519 both simultaneously)."; 520 leaf required { 521 type empty; 522 description 523 "Indicates that HTTP-level client authentication is 524 required to access protected resources."; 525 } 526 leaf optional { 527 type empty; 528 description 529 "Indicates that HTTP-level client authentication is 530 optional to access protected resources."; 531 } 532 } 533 choice local-or-external { 534 mandatory true; 535 description 536 "Indicates if the client credentials are configured 537 locally or externally. The need to support external 538 configuration for client authentication stems from 539 the desire to support consuming data models that 540 prefer to place client authentication with client 541 definitions, rather then in a data model principally 542 concerned with configuring the transport."; 543 case local { 544 if-feature "local-client-auth-supported"; 545 description 546 "Client credentials are configured locally."; 547 container users { 548 description 549 "A list of locally configured users."; 550 list user { 551 key user-id; 552 description 553 "The list of local users configured on this device."; 554 leaf user-id { 555 type string; 556 description 557 "The user-id for the authenticating client."; 558 } 559 choice auth-type { 560 description 561 "The authentication type."; 562 container basic { 563 if-feature "basic-auth"; 564 leaf user-id { 565 type string; 566 description 567 "The user-id for the authenticating client."; 568 } 569 leaf password { 570 nacm:default-deny-write; 571 type ianach:crypt-hash; 572 description 573 "The password for the authenticating client."; 574 } 575 description 576 "The 'basic' HTTP scheme credentials."; 577 reference 578 "RFC 7617: 579 The 'Basic' HTTP Authentication Scheme"; 580 } 581 } 582 } 583 } 584 } 585 case external { 586 if-feature "external-client-auth-supported"; 587 description 588 "Client credentials are configured externally."; 589 leaf client-auth-defined-elsewhere { 590 type empty; 591 description 592 "Indicates that credentials needed to authenticate 593 clients are configured elsewhere."; 594 } 595 } 596 } // choice local-or-external 597 } // container client-authentication 599 } 600 } 602 604 5. Security Considerations 606 The YANG modules defined in this document are designed to be accessed 607 via YANG based management protocols, such as NETCONF [RFC6241] and 608 RESTCONF [RFC8040]. Both of these protocols have mandatory-to- 609 implement secure transport layers (e.g., SSH, HTTP) with mutual 610 authentication. 612 The NETCONF access control model (NACM) [RFC8341] provides the means 613 to restrict access for particular users to a pre-configured subset of 614 all available protocol operations and content. 616 Since the modules defined in this document only define groupings, 617 these considerations are primarily for the designers of other modules 618 that use these groupings. 620 There are a number of data nodes defined in the YANG modules that are 621 writable/creatable/deletable (i.e., config true, which is the 622 default). These data nodes may be considered sensitive or vulnerable 623 in some network environments. Write operations (e.g., edit-config) 624 to these data nodes without proper protection can have a negative 625 effect on network operations. These are the subtrees and data nodes 626 and their sensitivity/vulnerability: 628 FIXME: (pending - TBD) 630 Some of the readable data nodes in the YANG modules may be considered 631 sensitive or vulnerable in some network environments. It is thus 632 important to control read access (e.g., via get, get-config, or 633 notification) to these data nodes. These are the subtrees and data 634 nodes and their sensitivity/vulnerability: 636 FIXME: (pending client auth params?) 638 Some of the RPC operations in this YANG module may be considered 639 sensitive or vulnerable in some network environments. It is thus 640 important to control access to these operations. These are the 641 operations and their sensitivity/vulnerability: 643 The modules defined in this document do not define any 'RPC' or 644 'action' statements. 646 6. IANA Considerations 648 6.1. The IETF XML Registry 650 This document registers two URIs in the "ns" subregistry of the IETF 651 XML Registry [RFC3688]. Following the format in [RFC3688], the 652 following registrations are requested: 654 URI: urn:ietf:params:xml:ns:yang:ietf-http-client 655 Registrant Contact: The NETCONF WG of the IETF. 656 XML: N/A, the requested URI is an XML namespace. 658 URI: urn:ietf:params:xml:ns:yang:ietf-http-server 659 Registrant Contact: The NETCONF WG of the IETF. 660 XML: N/A, the requested URI is an XML namespace. 662 6.2. The YANG Module Names Registry 664 This document registers two YANG modules in the YANG Module Names 665 registry [RFC6020]. Following the format in [RFC6020], the following 666 registrations are requested: 668 name: ietf-http-client 669 namespace: urn:ietf:params:xml:ns:yang:ietf-http-client 670 prefix: httpc 671 reference: RFC XXXX 673 name: ietf-http-server 674 namespace: urn:ietf:params:xml:ns:yang:ietf-http-server 675 prefix: https 676 reference: RFC XXXX 678 7. References 680 7.1. Normative References 682 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 683 Requirement Levels", BCP 14, RFC 2119, 684 DOI 10.17487/RFC2119, March 1997, 685 . 687 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 688 the Network Configuration Protocol (NETCONF)", RFC 6020, 689 DOI 10.17487/RFC6020, October 2010, 690 . 692 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 693 RFC 6991, DOI 10.17487/RFC6991, July 2013, 694 . 696 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 697 RFC 7950, DOI 10.17487/RFC7950, August 2016, 698 . 700 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 701 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 702 May 2017, . 704 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 705 Access Control Model", STD 91, RFC 8341, 706 DOI 10.17487/RFC8341, March 2018, 707 . 709 7.2. Informative References 711 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 712 DOI 10.17487/RFC3688, January 2004, 713 . 715 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 716 and A. Bierman, Ed., "Network Configuration Protocol 717 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 718 . 720 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 721 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 722 . 724 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 725 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 726 . 728 Author's Address 730 Kent Watsen 731 Watsen Networks 733 EMail: kent+ietf@watsen.net