idnits 2.17.1 draft-ietf-netconf-https-notif-06.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 are 3 instances of too long lines in the document, the longest one being 16 characters in excess of 72. == There are 8 instances of lines with non-RFC2606-compliant FQDNs in the document. -- 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 315 has weird spacing: '...rw name str...' -- The document date (November 16, 2020) is 1251 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 (-20) exists of draft-ietf-netconf-http-client-server-05 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF M. Jethanandani 3 Internet-Draft Kloud Services 4 Intended status: Standards Track K. Watsen 5 Expires: May 20, 2021 Watsen Networks 6 November 16, 2020 8 An HTTPS-based Transport for Configured Subscriptions 9 draft-ietf-netconf-https-notif-06 11 Abstract 13 This document defines a YANG data module for configuring HTTPS based 14 configured subscription, as defined in RFC 8639. The use of HTTPS 15 maximizes transport-level interoperability, while allowing for 16 encoding selection from text, e.g. XML or JSON, to binary. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 20, 2021. 35 Copyright Notice 37 Copyright (c) 2020 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Applicability Statement . . . . . . . . . . . . . . . . . 3 54 1.2. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 55 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 3 56 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.4.1. Subscribed Notifications . . . . . . . . . . . . . . 4 58 1.5. Receiver and Publisher Interaction . . . . . . . . . . . 4 59 1.5.1. Pipelining of messages . . . . . . . . . . . . . . . 4 60 2. Learning Receiver Capabilities . . . . . . . . . . . . . . . 7 61 2.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 7 62 2.2. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 3. The "ietf-sub-notif-recv-list" Module . . . . . . . . . . . . 8 64 3.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 8 65 3.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. The "ietf-https-notif" Module . . . . . . . . . . . . . . . . 10 67 4.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 10 68 4.2. YANG module . . . . . . . . . . . . . . . . . . . . . . . 11 69 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 70 6. Receiving Event Notifications . . . . . . . . . . . . . . . . 15 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 72 7.1. URI Registration . . . . . . . . . . . . . . . . . . . . 15 73 7.2. YANG Module Name Registration . . . . . . . . . . . . . . 15 74 7.3. Media Types . . . . . . . . . . . . . . . . . . . . . . . 16 75 7.3.1. Media Type "application/ietf-https-notif-cap+xml . . 16 76 7.3.2. Media Type "application/ietf-https-notif-cap+json . . 17 77 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 8.1. Subscribed Notification based Configuration . . . . . . . 18 79 8.2. Non Subscribed Notification based Configuration . . . . . 20 80 8.3. Bundled Message . . . . . . . . . . . . . . . . . . . . . 24 81 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 25 82 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 83 11. Normative references . . . . . . . . . . . . . . . . . . . . 25 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 86 1. Introduction 88 Subscription to YANG Notifications [RFC8639] defines a YANG data 89 module for configuring subscribed notifications. It defines a 90 "subscriptions" container that contains a list of receivers, but it 91 defers the configuration and management of those receivers to other 92 documents. This document defines two YANG 1.1 [RFC7950] data 93 modules, one for augmenting the Subscription to YANG Notifications 94 [RFC8639] to add a transport type, and another for configuring and 95 managing HTTPS based receivers for the notifications. 97 The first module allows for different transports to be configured for 98 the same receiver instance. The second module describes how to 99 enable the transmission of YANG modeled notifications, in the 100 configured encoding (i.e., XML, JSON) over HTTPS. Notifications are 101 delivered in the form of a HTTPS POST. The use of HTTPS maximizes 102 transport-level interoperability, while the encoding selection pivots 103 between implementation simplicity (XML, JSON) and throughput (text 104 versus binary). 106 Configured subscriptions enable a server, acting as a publisher of 107 notifications, to proactively push notifications to external 108 receivers without the receivers needing to first connect to the 109 server, as is the case with dynamic subscriptions. 111 1.1. Applicability Statement 113 While the YANG modules have been defined as an augmentation of 114 Subscription to YANG Notifications [RFC8639], the notification method 115 defined in this document MAY be used outside of Subscription to YANG 116 Notifications [RFC8639] by using some of the definitions from this 117 module along with the grouping defined in Groupings for HTTP Clients 118 and Servers [I-D.ietf-netconf-http-client-server]. For an example on 119 how that can be done, see Section 8.2. 121 1.2. Note to RFC Editor 123 This document uses several placeholder values throughout the 124 document. Please replace them as follows and remove this section 125 before publication. 127 RFC XXXX, where XXXX is the number assigned to this document at the 128 time of publication. 130 2020-11-16 with the actual date of the publication of this document. 132 1.3. Abbreviations 134 +---------+--------------------------------------+ 135 | Acronym | Expansion | 136 +---------+--------------------------------------+ 137 | HTTP | Hyper Text Transport Protocol | 138 | | | 139 | HTTPS | Hyper Text Transport Protocol Secure | 140 | | | 141 | TCP | Transmission Control Protocol | 142 | | | 143 | TLS | Transport Layer Security | 144 +---------+--------------------------------------+ 146 1.4. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 150 "OPTIONAL" in this document are to be interpreted as described in BCP 151 14 [RFC2119] [RFC8174] when, and only when, they appear in all 152 capitals, as shown here. 154 1.4.1. Subscribed Notifications 156 The following terms are defined in Subscription to YANG Notifications 157 [RFC8639]. 159 o Subscribed Notifications 161 1.5. Receiver and Publisher Interaction 163 The interaction between the receiver and the publisher can be of type 164 "pipelining" or send multiple notifications as part of a "bundled- 165 message", as defined in Notification Message Headers and Bundles 166 [I-D.ietf-netconf-notification-messages] 168 1.5.1. Pipelining of messages 170 In the case of "pipelining", the flow of messages would look 171 something like this. This example shows the flow assuming that 172 Subscribed Notifications is used and therefore a notification is sent before sending the first notification. 174 The example would be the same for when Subscribed Notification is not 175 used by removing the first POST message for . 177 ------------- -------------- 178 | Publisher | | Receiver | 179 ------------- -------------- 181 Establish TCP ------> 183 Establish TLS ------> 185 Send HTTPS POST message 186 with 187 started> notification 189 Send 200 (OK) for 190 <------ 192 Send HTTPS POST message 193 with YANG defined ------> 194 notification #1 196 Send HTTPS POST message 197 with YANG defined ------> 198 notification #2 199 Send 204 (No Content) 200 <------ for notification #1 202 Send 204 (No Content) 203 <------ for notification #2 205 Send HTTPS POST message 206 with YANG defined -------> 207 notification #3 209 Send 204 (No Content) 210 <------ for notification #3 212 The content of the exchange would look something like this. 214 Request: 216 POST /some/path HTTP/1.1 217 Host: my-receiver.my-domain.com 218 Content-Type: application/yang-data+xml 220 222 2019-03-22T12:35:00Z 223 224 ... 225 226 228 230 2019-03-22T12:35:00Z 231 232 ... 233 234 236 238 2019-03-22T12:35:01Z 239 240 ... 241 242 244 Response: 246 HTTP/1.1 204 No Content 247 Date: Fri, 03 Mar 2019 12:35:00 GMT 248 Server: my-receiver.my-domain.com 250 HTTP/1.1 204 No Content 251 Date: Fri, 03 Mar 2019 12:35:00 GMT 252 Server: my-receiver.my-domain.com 254 HTTP/1.1 204 No Content 255 Date: Fri, 03 Mar 2019 12:35:01 GMT 256 Server: my-receiver.my-domain.com 258 2. Learning Receiver Capabilities 260 2.1. Introduction 262 To learn the capabilities of the receiver, the publisher can issue a 263 HTTPS GET request with Accept-Type set to application/ietf-https- 264 notif-cap+xml or application/ietf-https-notif-cap+json, with latter 265 as the mandatory to implement, and the default in case the type is 266 not specified. If the receiver supports capabilities such as binary 267 encoding of data, it can return that as a capability in a response. 268 Please note that, when used in conjunction with Subscription to YANG 269 Notifications [RFC8639], dynamic discovery of the receiver's 270 supported encoding is considered only when the 271 "/subscriptions/subscription/encoding" leaf is not configured, per 272 the "encoding" leaf's description statement. 274 2.2. Example 276 The publisher can send the following request to learn the receiver 277 capabilities. The Accept-Type states its preferred order for 278 Content-Type that it wants to receive starting with XML, and if not 279 supported, to use JSON encoding. Currently, there is only one 280 capability of binary encoding defined. 282 GET / HTTP/1.1 283 Host: example.com 284 Accept-Type: application/ietf-https-notif-cap+xml, application/ietf-https-notif-cap+json 286 In case the receiver supports the first Accept-Type, its response 287 should look like this: 289 HTTP/1.1 200 OK 290 Date: Wed, 26 Feb 2020 20:33:30 GMT 291 Server: example-server 292 Cache-Control: no-cache 293 Content-Type: application/ietf-https-notif-cap+xml 294 Content-Length: nnn 296 297 298 299 300 302 3. The "ietf-sub-notif-recv-list" Module 304 3.1. Data Model Overview 306 This YANG module augments ietf-subscribed-notifications module to 307 define a choice of transport types that other modules such as the 308 ietf-https-notif module can use to define a transport specific 309 receiver. 311 module: ietf-sub-notif-recv-list 312 augment /sn:subscriptions: 313 +--rw receiver-instances 314 +--rw receiver-instance* [name] 315 +--rw name string 316 +--rw (transport-type) 317 augment /sn:subscriptions/sn:subscription/sn:receivers/sn:receiver: 318 +--rw receiver-instance-ref? leafref 320 3.2. YANG Module 322 file "ietf-sub-notif-recv-list@2020-11-16.yang" 323 module ietf-sub-notif-recv-list { 324 yang-version 1.1; 325 namespace "urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list"; 326 prefix "snrl"; 328 import ietf-subscribed-notifications { 329 prefix sn; 331 reference 332 "I-D.ietf-netconf-subscribed-notifications"; 333 } 335 organization 336 "IETF NETCONF Working Group"; 338 contact 339 "WG Web: 340 WG List: 342 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 343 Kent Watsen (kent plus ietf at watsen dot net)"; 344 description 345 "YANG module for augmenting Subscribed Notifications to add 346 a transport type. 348 Copyright (c) 2018 IETF Trust and the persons identified as 349 the document authors. All rights reserved. 350 Redistribution and use in source and binary forms, with or 351 without modification, is permitted pursuant to, and subject 352 to the license terms contained in, the Simplified BSD 353 License set forth in Section 4.c of the IETF Trust's Legal 354 Provisions Relating to IETF Documents 355 (http://trustee.ietf.org/license-info). 357 This version of this YANG module is part of RFC XXXX; see 358 the RFC itself for full legal notices. 360 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 361 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 362 'MAY', and 'OPTIONAL' in this document are to be interpreted as 363 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 364 they appear in all capitals, as shown here."; 366 revision "2020-11-16" { 367 description 368 "Initial Version."; 369 reference 370 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 371 } 373 augment "/sn:subscriptions" { 374 container receiver-instances { 375 description 376 "A container for all instances of receivers."; 378 list receiver-instance { 379 key "name"; 381 leaf name { 382 type string; 383 description 384 "An arbitrary but unique name for this receiver instance."; 385 } 387 choice transport-type { 388 mandatory true; 389 description 390 "Choice of different types of transports used to send 391 notifications."; 392 } 393 description 394 "A list of all receiver instances."; 395 } 397 } 398 description 399 "Augment the subscriptions container to define the transport 400 type."; 401 } 403 augment "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 404 leaf receiver-instance-ref { 405 type leafref { 406 path "/sn:subscriptions/snrl:receiver-instances/" + 407 "snrl:receiver-instance/snrl:name"; 408 } 409 description 410 "Reference to a receiver instance."; 411 } 412 description 413 "Augment the subscriptions container to define an optional 414 reference to a receiver instance."; 415 } 417 } 418 420 4. The "ietf-https-notif" Module 422 4.1. Data Model Overview 424 This YANG module is a definition of a set of receivers that are 425 interested in the notifications published by the publisher. The 426 module contains the TCP, TLS and HTTPS parameters that are needed to 427 communicate with the receiver. The module augments the ietf-sub- 428 notif-recv-list module to define a transport specific receiver. As 429 mentioned earlier, it uses POST method to deliver the notification. 430 The attribute 'path' defines the path for the resource on the 431 receiver, as defined by 'path-absolute' in URI Generic Syntax 432 [RFC3986]. The user-id used by Network Configuration Access Control 433 Model [RFC8341], is that of the receiver and is derived from the 434 certificate presented by the receiver as part of 'receiver-identity'. 436 An abridged tree diagram representing the module is shown below. 438 module: ietf-https-notif 439 augment /sn:subscriptions/snrl:receiver-instances 440 /snrl:receiver-instance/snrl:transport-type: 441 +--:(https) 442 +--rw https-receiver 443 +--rw (transport) 444 | +--:(tcp) {tcp-supported,not httpc:tcp-supported}? 445 | | ... 446 | +--:(tls) {tls-supported}? 447 | ... 448 +--rw receiver-identity 449 +--rw cert-maps 450 ... 452 4.2. YANG module 454 The YANG module imports Common YANG Data Types [RFC6991], A YANG Data 455 Model for SNMP Configuration [RFC7407], JSON Encoding of Data Modeled 456 with YANG [RFC7951], and Subscription to YANG Notifications 457 [RFC8639]. 459 The YANG module is shown below. 461 file "ietf-https-notif@2020-11-16.yang" 462 module ietf-https-notif { 463 yang-version 1.1; 464 namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif"; 465 prefix "hn"; 467 import ietf-subscribed-notifications { 468 prefix sn; 469 reference 470 "I-D.ietf-netconf-subscribed-notifications"; 471 } 473 import ietf-http-client { 474 prefix httpc; 476 reference 477 "I-D.ietf-netconf-http-client-server"; 478 } 480 import ietf-sub-notif-recv-list { 481 prefix snrl; 483 reference 484 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 486 } 488 import ietf-x509-cert-to-name { 489 prefix x509c2n; 491 reference 492 "RFC 7407: YANG Data Model for SNMP Configuration."; 493 } 495 organization 496 "IETF NETCONF Working Group"; 498 contact 499 "WG Web: 500 WG List: 502 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 503 Kent Watsen (kent plus ietf at watsen dot net)"; 504 description 505 "YANG module for configuring HTTPS base configuration. 507 Copyright (c) 2018 IETF Trust and the persons identified as 508 the document authors. All rights reserved. 509 Redistribution and use in source and binary forms, with or 510 without modification, is permitted pursuant to, and subject 511 to the license terms contained in, the Simplified BSD 512 License set forth in Section 4.c of the IETF Trust's Legal 513 Provisions Relating to IETF Documents 514 (http://trustee.ietf.org/license-info). 516 This version of this YANG module is part of RFC XXXX; see 517 the RFC itself for full legal notices. 519 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 520 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 521 'MAY', and 'OPTIONAL' in this document are to be interpreted as 522 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 523 they appear in all capitals, as shown here."; 525 revision "2020-11-16" { 526 description 527 "Initial Version."; 528 reference 529 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 530 } 532 identity https { 533 base sn:transport; 534 description 535 "HTTPS transport for notifications."; 536 } 538 augment "/sn:subscriptions/snrl:receiver-instances/" + 539 "snrl:receiver-instance/snrl:transport-type" { 540 case https { 541 container https-receiver { 542 description 543 "HTTPS receiver for notification"; 545 uses httpc:http-client-stack-grouping { 546 refine "transport/tcp" { 547 // create the logical impossibility of enabling "tcp" 548 // transport 549 if-feature "not httpc:tcp-supported"; 550 } 551 augment "transport/tls/tls/http-client-parameters" { 552 leaf path { 553 type string; 554 description 555 "Relative URI to the target resource."; 556 } 557 description 558 "Augmentation to add a path to the target resource."; 559 } 560 } 562 container receiver-identity { 563 description 564 "Specifies mechanism for identifying the receiver. 565 The publisher MUST NOT include any content in a 566 notification that the user is not authorized to view."; 568 container cert-maps { 569 uses x509c2n:cert-to-name; 570 description 571 "The cert-maps container is used by a TLS-based HTTP 572 server to map the HTTPS client's presented X.509 573 certificate to a 'local' username. If no matching and 574 valid cert-to-name list entry is found, the publisher 575 MUST close the connection, and MUST NOT 576 not send any notifications over it."; 577 reference 578 "RFC 7407: A YANG Data Model for SNMP Configuration."; 579 } 580 } 581 } 583 } 584 description 585 "Augment the transport-type choice to define this transport."; 586 } 587 } 588 590 5. Security Considerations 592 The YANG module specified in this document defines a schema for data 593 that is designed to be accessed via network management protocols such 594 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 595 is the secure transport layer, and the mandatory-to-implement secure 596 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 597 is HTTPS, and the mandatory-to-implement secure transport is TLS 598 [RFC8446]. The NETCONF Access Control Model (NACM) [RFC8341] 599 provides the means to restrict access for particular NETCONF or 600 RESTCONF users to a preconfigured subset of all available NETCONF or 601 RESTCONF protocol operations and content. 603 The YANG module in this document makes use of grouping that are 604 defined in YANG Groupings for HTTP Clients and HTTP Servers 605 [I-D.ietf-netconf-http-client-server], and A YANG Data Model for SNMP 606 Configuration [RFC7407]. Please see the Security Considerations 607 section of those documents for considerations related to sensitivity 608 and vulnerability of the data nodes defined in them. 610 There are a number of data nodes defined in this YANG module that are 611 writable/creatable/deletable (i.e., config true, which is the 612 default). These data nodes may be considered sensitive or vulnerable 613 in some network environments. Write operations (e.g., edit-config) 614 to these data nodes without proper protection can have a negative 615 effect on network operations. These are the subtrees and data nodes 616 and their sensitivity/vulnerability: 618 o The 'path' node in ietf-https-notif module can be modified by a 619 malcious user to point to an invalid URI. 621 Some of the readable data nodes in YANG module may be considered 622 sensitive or vulnerable in some network environments. It is thus 623 important to control read access (e.g., via get, get-config, or 624 notification) to these data nodes. The model does not define any 625 readable subtrees and data nodes. 627 Some of the RPC operations in YANG module may be considered sensitive 628 or vulnerable in some network environments. It is thus important to 629 control access to these operations. The model does not define any 630 RPC operations. 632 6. Receiving Event Notifications 634 Encoding notifications for the HTTPS notifications is the same as the 635 encoding notifications as defined in RESTCONF [RFC8040] Section 6.4, 636 with the following changes. Instead of saying that for JSON-encoding 637 purposes, the module name for "notification" element will be "ietf- 638 restconf, it will say that for JSON-encoding purposes, the module 639 name for "notification" element will be "ietf-https-notif". 641 With those changes, the SSE event notification encoded JSON example 642 that would be sent over the HTTPS notif transport would appear as 643 follows: 645 data: { 646 data: "ietf-https-notif:notification" : { 647 data: "eventTime" : "2013-12-21T00:01:00Z", 648 data: "example-mod:event" : { 649 data: "event-class" : "fault", 650 data: "reporting-entity" : { "card" : "Ethernet0" }, 651 data: "severity" : "major" 652 data: } 653 data: } 654 data: } 656 7. IANA Considerations 658 This document registers two URI, two YANG module and two Media Types. 660 7.1. URI Registration 662 in the IETF XML registry [RFC3688]. Following the format in RFC 663 3688, the following registration is requested to be made: 665 URI: urn:ietf:params:xml:ns:yang:ietf-http-notif 666 URI: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list 668 Registrant Contact: The IESG. XML: N/A, the requested URI is an XML 669 namespace. 671 7.2. YANG Module Name Registration 673 This document registers one YANG module in the YANG Module Names 674 registry YANG [RFC6020]. 676 name: ietf-https-notif 677 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif 678 prefix: hn 679 reference: RFC XXXX 681 name: ietf-sub-recv-list 682 namespace: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list 683 prefix: snrl 684 reference: RFC XXXX 686 7.3. Media Types 688 7.3.1. Media Type "application/ietf-https-notif-cap+xml 690 Type name: application 692 Subtype name: ietf-https-notif-cap+xml 694 Required parameters: None 696 Optional parameters: None 698 Encoding considerations: 699 8-bit Each conceptual YANG data node is encoded according to the XML 700 Encoding Rules and Canonical Format for the specific YANG data node 701 type defined in YANG 1.1 [RFC7950]. 703 Security considerations: 704 Security considerations related to the generation and consumption of 705 RESTCONF messages are discussed in Section NN of RFC XXXX. 707 Additional security considerations are specific to the semantics of 708 particular YANG data models. Each YANG module is expected to specify 709 security considerations for the YANG data defined in that module. 711 Interoperability considerations: N/A 713 Published specification: RFC XXXX 715 Applications that use this media type: 716 Instance document data parsers used within a protocol or automation 717 tool that utilize YANG-defined data structures. 719 Fragment identifier considerations: 720 Fragment identifiers for this type are not defined. All YANG data 721 nodes are accessible as resources using the path in the request URI. 723 Additional information: 725 Deprecated alias names for this type: N/A 726 Magic number(s): N/A 727 File extension(s): None 728 Macintosh file type code(s): "TEXT" 730 Person & email address to contact for further information: 731 See Author's Address section of RFC XXXX. 733 Intended usage: COMMON 735 Restrictions on usage: N/A 737 Author: See Author's Address section of RFC XXXX 739 Change controller: 740 Internet Engineering Task Force (mailto:iesg@ietf.org) 742 Provisional registration? (standards tree only): no 744 7.3.2. Media Type "application/ietf-https-notif-cap+json 746 Type name: application 748 Subtype name: ietf-https-notif-cap+json 750 Required parameters: None 752 Optional parameters: None 754 Encoding considerations: 755 8-bit Each conceptual YANG data node is encoded according to the XML 756 Encoding Rules and Canonical Format for the specific YANG data node 757 type defined in JSON Encoding of Data Modeled with YANG [RFC7951]. 759 Security considerations: 760 Security considerations related to the generation and consumption of 761 RESTCONF messages are discussed in Section NN of RFC XXXX. 763 Additional security considerations are specific to the semantics of 764 particular YANG data models. Each YANG module is expected to specify 765 security considerations for the YANG data defined in that module. 767 Interoperability considerations: N/A 769 Published specification: RFC XXXX 771 Applications that use this media type: 772 Instance document data parsers used within a protocol or automation 773 tool that utilize YANG-defined data structures. 775 Fragment identifier considerations: 776 Fragment identifiers for this type are not defined. All YANG data 777 nodes are accessible as resources using the path in the request URI. 779 Additional information: 781 Deprecated alias names for this type: N/A 782 Magic number(s): N/A 783 File extension(s): None 784 Macintosh file type code(s): "TEXT" 786 Person & email address to contact for further information: 787 See Author's Address section of RFC XXXX. 789 Intended usage: COMMON 791 Restrictions on usage: N/A 793 Author: See Author's Address section of RFC XXXX 795 Change controller: 796 Internet Engineering Task Force (mailto:iesg@ietf.org) 798 Provisional registration? (standards tree only): no 800 8. Examples 802 This section shows some examples in how the module can be used. 804 8.1. Subscribed Notification based Configuration 806 This example shows how a HTTPS client can be configured to send 807 notifications to a receiver at address 192.0.2.1, port 443, a 'path', 808 with server certificates, and the corresponding trust store that is 809 used to authenticate a connection. 811 [note: '\' line wrapping for formatting only] 813 814 815 818 820 821 foo 822 826 827 828 my-receiver.my-domain.com 829 443 830 831 832 833 834 835 836 Server Cert Issuer #1 837 base64encodedvalue== 838 839 840 841 842 843 844 845 846 my-name 847 my-password 848 849 850 /some/path 851 852 853 854 855 856 1 857 11:0A:05:11:00 858 x509c2n:san-any 859 860 861 862 863 864 865 866 6666 867 869 hn:https 870 871 foo 872 some-stream 873 874 875 my-receiver 876 \ 878 foo 879 880 881 882 884 885 886 887 explicitly-trusted-server-ca-certs 888 889 Trust anchors (i.e. CA certs) that are used to authenticat\ 890 e 891 server connections. Servers are authenticated if their 892 certificate has a chain of trust to one of these CA 893 certificates. 894 895 896 ca.example.com 897 base64encodedvalue== 898 899 900 Fred Flintstone 901 base64encodedvalue== 902 903 904 905 906 908 8.2. Non Subscribed Notification based Configuration 910 In the case that it is desired to use HTTPS notif outside of 911 Subscribed Notifications, there would have to be a module to define 912 the configuration for where and how to send the notification, such as 913 the following: 915 [note: '\' line wrapping for formatting only] 916 module example-custom-module { 917 yang-version 1.1; 918 namespace "http://example.com/example-custom-module"; 919 prefix "custom"; 921 import ietf-http-client { 922 prefix httpc; 923 reference 924 "I-D.ietf-netconf-http-client-server"; 925 } 927 organization 928 "Example, Inc."; 930 contact 931 "Support at example.com"; 933 description 934 "Example of module not using Subscribed Notifications module."; 936 revision "2020-11-16" { 937 description 938 "Initial Version."; 939 reference 940 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 941 } 943 container example-module { 944 description 945 "Example of using HTTPS notif without having to 946 implement Subscribed Notifications."; 948 container https-receivers { 949 description 950 "A container of all HTTPS notif receivers."; 952 list https-receiver { 953 key "name"; 955 leaf name { 956 type string; 957 description 958 "A unique name for the https notif receiver."; 959 } 961 uses httpc:http-client-stack-grouping { 962 refine "transport/tcp" { 963 // create the logical impossibility of enabling "tcp" 964 // transport 965 if-feature "not httpc:tcp-supported"; 966 } 967 augment "transport/tls/tls/http-client-parameters" { 968 leaf path { 969 type string; 970 description 971 "Relative URI to the target resource."; 972 } 973 description 974 "Augmentation to add a path to the target resource."; 975 } 976 } 977 description 978 "Just include the grouping from ietf-http-client to 979 realize the 'HTTPS stack'."; 980 } 981 } 982 } 983 } 985 This example shows how a HTTPS client can be configured to send 986 notifications to a receiver at address 192.0.2.1, port 443, a 'path', 987 with server certificates, and the corresponding trust store that is 988 used to authenticate a connection. 990 [note: '\' line wrapping for formatting only] 992 993 994 996 997 998 foo 999 1000 1001 my-receiver.my-domain.com 1002 443 1003 1004 1005 1006 1007 1008 1009 Server Cert Issuer #1 1010 base64encodedvalue== 1012 1013 1014 1015 1016 1017 1018 1019 1020 my-name 1021 my-password 1022 1023 1024 /some/path 1025 1026 1027 1028 1029 1031 1032 1033 1034 explicitly-trusted-server-ca-certs 1035 1036 Trust anchors (i.e. CA certs) that are used to authenticat\ 1037 e 1038 server connections. Servers are authenticated if their 1039 certificate has a chain of trust to one of these CA 1040 certificates. 1041 1042 1043 ca.example.com 1044 base64encodedvalue== 1045 1046 1047 Fred Flintstone 1048 base64encodedvalue== 1049 1050 1051 1052 1053 1055 8.3. Bundled Message 1057 In the case of "bundled-message" as defined in Notification Message 1058 Headers and Bundles [I-D.ietf-netconf-notification-messages], 1059 something that this module supports, the flow of messages would look 1060 something like this. 1062 ------------- -------------- 1063 | Publisher | | Receiver | 1064 ------------- -------------- 1065 Establish TCP ------> 1066 Establish TLS ------> 1067 Send HTTPS POST message 1068 with YANG defined ------> 1069 notification #1 1070 Send HTTPS POST message 1071 with YANG defined ------> 1072 notification #2 1073 Send 204 (No Content) 1074 <------ for notification #1 1076 Send 204 (No Content) 1077 <------ for notification #2 1078 Send HTTPS POST message 1079 with YANG defined -------> 1080 notification #3 1081 Send 204 (No Content) 1082 <------ for notification #3 1084 The content of the exchange would look something like this. 1086 Request: 1087 POST /some/path HTTP/1.1 1088 Host: my-receiver.my-domain.com 1089 Content-Type: application/yang-data+xml 1090 1092 2019-03-22T12:35:00Z 1093 1094 ... 1095 1096 1097 1099 2019-03-22T12:35:00Z 1100 1101 ... 1102 1103 1104 1106 2019-03-22T12:35:01Z 1107 1108 ... 1109 1110 1111 Response: 1112 HTTP/1.1 204 No Content 1113 Date: Fri, 03 Mar 2019 12:35:00 GMT 1114 Server: my-receiver.my-domain.com 1115 HTTP/1.1 204 No Content 1116 Date: Fri, 03 Mar 2019 12:35:00 GMT 1117 Server: my-receiver.my-domain.com 1118 HTTP/1.1 204 No Content 1119 Date: Fri, 03 Mar 2019 12:35:01 GMT 1120 Server: my-receiver.my-domain.com 1122 9. Contributors 1124 10. Acknowledgements 1126 11. Normative references 1128 [I-D.ietf-netconf-http-client-server] 1129 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1130 Servers", draft-ietf-netconf-http-client-server-05 (work 1131 in progress), August 2020. 1133 [I-D.ietf-netconf-notification-messages] 1134 Voit, E., Jenkins, T., Birkholz, H., Bierman, A., and A. 1135 Clemm, "Notification Message Headers and Bundles", draft- 1136 ietf-netconf-notification-messages-08 (work in progress), 1137 November 2019. 1139 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1140 Requirement Levels", BCP 14, RFC 2119, 1141 DOI 10.17487/RFC2119, March 1997, 1142 . 1144 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1145 DOI 10.17487/RFC3688, January 2004, 1146 . 1148 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1149 Resource Identifier (URI): Generic Syntax", STD 66, 1150 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1151 . 1153 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1154 the Network Configuration Protocol (NETCONF)", RFC 6020, 1155 DOI 10.17487/RFC6020, October 2010, 1156 . 1158 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1159 and A. Bierman, Ed., "Network Configuration Protocol 1160 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1161 . 1163 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1164 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1165 . 1167 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1168 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1169 . 1171 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1172 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1173 December 2014, . 1175 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1176 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1177 . 1179 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1180 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1181 . 1183 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1184 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1185 . 1187 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1188 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1189 May 2017, . 1191 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1192 Access Control Model", STD 91, RFC 8341, 1193 DOI 10.17487/RFC8341, March 2018, 1194 . 1196 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1197 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1198 . 1200 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 1201 E., and A. Tripathy, "Subscription to YANG Notifications", 1202 RFC 8639, DOI 10.17487/RFC8639, September 2019, 1203 . 1205 Authors' Addresses 1207 Mahesh Jethanandani 1208 Kloud Services 1210 Email: mjethanandani@gmail.com 1212 Kent Watsen 1213 Watsen Networks 1214 USA 1216 Email: kent+ietf@watsen.net