idnits 2.17.1 draft-ietf-netconf-https-notif-00.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 11 characters in excess of 72. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 152 has weird spacing: '...address ine...' == The document doesn't use any RFC 2119 keywords, yet has text resembling RFC 2119 boilerplate text. -- The document date (September 17, 2019) is 1676 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: 1 error (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF M. Jethanandani 3 Internet-Draft VMware 4 Intended status: Standards Track K. Watsen 5 Expires: March 20, 2020 Watsen Networks 6 September 17, 2019 8 An HTTPS-based Transport for Configured Subscriptions 9 draft-ietf-netconf-https-notif-00 11 Abstract 13 This document defines a YANG data module for configuring HTTPS based 14 configured subscription, as defined I-D.ietf-netconf-subscribed- 15 notifications. The use of HTTPS maximizes transport-level 16 interoperability, while allowing for encoding selection from text, 17 e.g. XML or JSON, to binary. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on March 20, 2020. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 55 1.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 3 56 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.3.1. Subscribed Notifications . . . . . . . . . . . . . . 3 58 2. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2.2. YANG module . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. Security Considerations . . . . . . . . . . . . . . . . . . . 7 62 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 4.1. URI Registration . . . . . . . . . . . . . . . . . . . . 7 64 4.2. YANG Module Name Registration . . . . . . . . . . . . . . 8 65 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 5.1. HTTPS Configured Subscription . . . . . . . . . . . . . . 8 67 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 10 68 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 69 8. Normative references . . . . . . . . . . . . . . . . . . . . 10 70 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 72 1. Introduction 74 Subscribed Notifications [I-D.ietf-netconf-subscribed-notifications] 75 defines a YANG data module for configuring subscribed notifications. 76 It even defines a subscriptions container that contains a list of 77 receivers. But it defers the configuration and management of those 78 receivers to other documents. This document defines a YANG [RFC7950] 79 data module for configuring and managing HTTPS based receivers for 80 the notifications. Such a configured receiver can be a third party 81 collector, collecting events on behalf of receivers that want to co- 82 relate events from different publishers. Configured subscriptions 83 enable a server, acting as a publisher of notifications, to 84 proactively push notifications to external receivers without the 85 receivers needing to first connect to the server, as is the case with 86 dynamic subscriptions. 88 This document describes how to enable the transmission of YANG 89 modeled notifications, in the configured encoding (i.e., XML, JSON) 90 over HTTPS. The use of HTTPS maximizes transport-level 91 interoperability, while the encoding selection pivots between 92 implementation simplicity (XML, JSON) and throughput (text versus 93 binary). 95 1.1. Note to RFC Editor 97 This document uses several placeholder values throughout the 98 document. Please replace them as follows and remove this section 99 before publication. 101 RFC XXXX, where XXXX is the number assigned to this document at the 102 time of publication. 104 2019-09-17 with the actual date of the publication of this document. 106 1.2. Abbreviations 108 +---------+-------------------------------+ 109 | Acronym | Expansion | 110 +---------+-------------------------------+ 111 | HTTP | Hyper Text Transport Protocol | 112 | | | 113 | TCP | Transmission Control Protocol | 114 | | | 115 | TLS | Transport Layer Security | 116 +---------+-------------------------------+ 118 1.3. Terminology 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 122 "OPTIONAL" in this document are to be interpreted as described in BCP 123 14 RFC2119 [RFC2119] RFC8174 [RFC8174] when, and only when, they 124 appear in all capitals, as shown here. 126 1.3.1. Subscribed Notifications 128 The following terms are defined in Subscribed Notifications 129 [I-D.ietf-netconf-subscribed-notifications]. 131 o Subscribed Notifications 133 2. YANG module 135 2.1. Overview 137 The YANG module is a definition of a set of receivers that are 138 interested in the notifications published by the publisher. The 139 module contains the TCP, TLS and HTTPS parameters that are needed to 140 communicate with the receiver. The module augments the Subscribed 141 Notifications [I-D.ietf-netconf-subscribed-notifications] receiver 142 container to create a reference to a receiver defined by the YANG 143 module. 145 An abridged tree diagram representing the module is shown below. 147 module: ietf-https-notif 148 +--rw receivers 149 +--rw receiver* [name] 150 +--rw name string 151 +--rw tcp-params 152 | +--rw remote-address inet:host 153 | +--rw remote-port? inet:port-number 154 | +--rw local-address? inet:ip-address 155 | +--rw local-port? inet:port-number 156 | +--rw keepalives! 157 | ... 158 +--rw tls-params 159 | +--rw client-identity 160 | | ... 161 | +--rw server-authentication 162 | | ... 163 | +--rw hello-params {tls-client-hello-params-config}? 164 | | ... 165 | +--rw keepalives! {tls-client-keepalives}? 166 | ... 167 +--rw http-params 168 +--rw protocol-version? enumeration 169 +--rw client-identity 170 | ... 171 +--rw proxy-server! {proxy-connect}? 172 ... 174 augment /sn:subscriptions/sn:subscription/sn:receivers/sn:receiver: 175 +--rw receiver-ref? -> /receivers/receiver/name 177 2.2. YANG module 179 The YANG module is shown below. 181 file "ietf-https-notif@2019-09-17.yang" 182 module ietf-https-notif { 183 yang-version 1.1; 184 namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif"; 185 prefix "hsn"; 187 import ietf-subscribed-notifications { 188 prefix sn; 189 reference 190 "I-D.ietf-netconf-subscribed-notifications"; 191 } 193 import ietf-tcp-client { 194 prefix tcpc; 195 } 197 import ietf-tls-client { 198 prefix tlsc; 199 } 201 import ietf-http-client { 202 prefix httpc; 203 } 205 organization 206 "IETF NETCONF Working Group"; 208 contact 209 "WG Web: 210 WG List: 212 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 213 Kent Watsen (kent plus ietf at watsen dot net)"; 214 description 215 "YANG module for configuring HTTPS base configuration. 217 Copyright (c) 2018 IETF Trust and the persons identified as 218 the document authors. All rights reserved. 219 Redistribution and use in source and binary forms, with or 220 without modification, is permitted pursuant to, and subject 221 to the license terms contained in, the Simplified BSD 222 License set forth in Section 4.c of the IETF Trust's Legal 223 Provisions Relating to IETF Documents 224 (http://trustee.ietf.org/license-info). 226 This version of this YANG module is part of RFC XXXX; see 227 the RFC itself for full legal notices."; 229 revision "2019-09-17" { 230 description 231 "Initial Version."; 232 reference 233 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 234 } 236 identity https { 237 base sn:transport; 238 description 239 "HTTPS transport for notifications."; 240 } 242 container receivers { 243 list receiver { 244 key "name"; 246 leaf name { 247 type string; 248 description 249 "A name that uniquely identifies this receiver."; 250 } 252 container tcp-params { 253 uses tcpc:tcp-client-grouping; 254 description 255 "TCP client parameters."; 256 } 258 container tls-params { 259 uses tlsc:tls-client-grouping; 260 description 261 "TLS client parameters."; 262 } 264 container http-params { 265 uses httpc:http-client-grouping; 266 description 267 "HTTP client parameters."; 268 } 269 description 270 "All receivers interested in this notification."; 271 } 272 description 273 "HTTPS based notifications."; 274 } 276 augment "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 277 leaf receiver-ref { 278 type leafref { 279 path "/receivers/receiver/name"; 280 } 281 description 282 "Reference to a receiver."; 283 } 284 description 285 "Augment the subscriptions container to define the receiver."; 286 } 287 } 288 290 3. Security Considerations 292 The YANG module specified in this document defines a schema for data 293 that is designed to be accessed via network management protocols such 294 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 295 is the secure transport layer, and the mandatory-to-implement secure 296 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 297 is HTTPS, and the mandatory-to-implement secure transport is TLS 298 [RFC8446]. The NETCONF Access Control Model (NACM) [RFC8341] 299 provides the means to restrict access for particular NETCONF or 300 RESTCONF users to a preconfigured subset of all available NETCONF or 301 RESTCONF protocol operations and content. 303 There are a number of data nodes defined in this YANG module that are 304 writable/creatable/deletable (i.e., config true, which is the 305 default). These data nodes may be considered sensitive or vulnerable 306 in some network environments. Write operations (e.g., edit-config) 307 to these data nodes without proper protection can have a negative 308 effect on network operations. These are the subtrees and data nodes 309 and their sensitivity/vulnerability: 311 Some of the readable data nodes in this YANG module may be considered 312 sensitive or vulnerable in some network environments. It is thus 313 important to control read access (e.g., via get, get-config, or 314 notification) to these data nodes. These are the subtrees and data 315 nodes and their sensitivity/vulnerability: 317 Some of the RPC operations in this YANG module may be considered 318 sensitive or vulnerable in some network environments. It is thus 319 important to control access to these operations. These are the 320 operations and their sensitivity/vulnerability: 322 4. IANA Considerations 324 This document registers one URI and one YANG module. 326 4.1. URI Registration 328 in the IETF XML registry [RFC3688] [RFC3688]. Following the format 329 in RFC 3688, the following registration is requested to be made: 331 URI: urn:ietf:params:xml:ns:yang:ietf-http-notif 332 Registrant Contact: The IESG. XML: N/A, the requested URI is an XML 333 namespace. 335 4.2. YANG Module Name Registration 337 This document registers three YANG module in the YANG Module Names 338 registry YANG [RFC6020]. 340 name: ietf-https-notif 341 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif 342 prefix: hn 343 reference: RFC XXXX 345 5. Examples 347 This section tries to show some examples in how the model can be 348 used. 350 5.1. HTTPS Configured Subscription 352 This example shows how a HTTPS client can be configured to send 353 notifications to a receiver at address 192.0.2.1, port 443 with 354 server certificates, and the corresponding trust store that is used 355 to authenticate a connection. 357 [note: '\' line wrapping for formatting only] 359 360 361 363 364 foo 365 366 192.0.2.1 367 443 368 192.0.3.1 369 63001 370 371 372 373 explicitly-trusted-server-ca-certs 374 explicitly-trusted-server-certs 376 377 378 379 380 383 384 6666 385 foo 386 some-stream 387 388 389 my-receiver 390 foo 393 394 395 396 398 399 400 explicitly-trusted-server-certs 401 402 Specific server authentication certificates for explicitly 403 trusted servers. These are needed for server certificates 404 that are not signed by a pinned CA. 405 406 407 Fred Flintstone 408 base64encodedvalue== 409 410 411 412 explicitly-trusted-server-ca-certs 413 414 Trust anchors (i.e. CA certs) that are used to authenticate\ 416 server connections. Servers are authenticated if their 417 certificate has a chain of trust to one of these CA 418 certificates. 419 420 421 ca.example.com 422 base64encodedvalue== 423 424 425 426 427 6. Contributors 429 7. Acknowledgements 431 8. Normative references 433 [I-D.ietf-netconf-subscribed-notifications] 434 Voit, E., Clemm, A., Prieto, A., Nilsen-Nygaard, E., and 435 A. Tripathy, "Subscription to YANG Event Notifications", 436 draft-ietf-netconf-subscribed-notifications-26 (work in 437 progress), May 2019. 439 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 440 Requirement Levels", BCP 14, RFC 2119, 441 DOI 10.17487/RFC2119, March 1997, 442 . 444 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 445 DOI 10.17487/RFC3688, January 2004, 446 . 448 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 449 the Network Configuration Protocol (NETCONF)", RFC 6020, 450 DOI 10.17487/RFC6020, October 2010, 451 . 453 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 454 and A. Bierman, Ed., "Network Configuration Protocol 455 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 456 . 458 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 459 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 460 . 462 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 463 RFC 7950, DOI 10.17487/RFC7950, August 2016, 464 . 466 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 467 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 468 . 470 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 471 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 472 May 2017, . 474 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 475 Access Control Model", STD 91, RFC 8341, 476 DOI 10.17487/RFC8341, March 2018, 477 . 479 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 480 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 481 . 483 Authors' Addresses 485 Mahesh Jethanandani 486 VMware 488 Email: mjethanandani@gmail.com 490 Kent Watsen 491 Watsen Networks 492 USA 494 Email: kent+ietf@watsen.net