idnits 2.17.1 draft-ietf-netconf-https-notif-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 : ---------------------------------------------------------------------------- ** There are 6 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 (October 23, 2020) is 1281 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: April 26, 2021 Watsen Networks 6 October 23, 2020 8 An HTTPS-based Transport for Configured Subscriptions 9 draft-ietf-netconf-https-notif-05 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 April 26, 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. Encoding Event Notifications . . . . . . . . . . . . . . . . 14 71 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 72 7.1. URI Registration . . . . . . . . . . . . . . . . . . . . 16 73 7.2. YANG Module Name Registration . . . . . . . . . . . . . . 16 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 19 78 8.1. Subscribed Notification based Configuration . . . . . . . 19 79 8.2. Non Subscribed Notification based Configuration . . . . . 21 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-10-21 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-10-21.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-10-21" { 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-10-21.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-10-21" { 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 There are a number of data nodes defined in this YANG module that are 604 writable/creatable/deletable (i.e., config true, which is the 605 default). These data nodes may be considered sensitive or vulnerable 606 in some network environments. Write operations (e.g., edit-config) 607 to these data nodes without proper protection can have a negative 608 effect on network operations. These are the subtrees and data nodes 609 and their sensitivity/vulnerability: 611 Some of the readable data nodes in this YANG module may be considered 612 sensitive or vulnerable in some network environments. It is thus 613 important to control read access (e.g., via get, get-config, or 614 notification) to these data nodes. These are the subtrees and data 615 nodes and their sensitivity/vulnerability: 617 Some of the RPC operations in this YANG module may be considered 618 sensitive or vulnerable in some network environments. It is thus 619 important to control access to these operations. These are the 620 operations and their sensitivity/vulnerability: 622 6. Encoding Event Notifications 624 Notifications are encoded as defined in RESTCONF [RFC8040] 625 Section 6.4. The examples in that section apply for sending 626 notifications over the "https-notif" based transport. 628 An example of YANG-Push in JSON would look something like this: 630 data: { 631 data: "ietf-restconf:notification" : { 632 data: "eventTime" : "2017-10-25T08:00:11.22Z", 633 data: "ietf-yang-push:push-update" : { 634 data: "id" : 1011, 635 data: "datastore-contents" : { 636 data: "ietf-interfaces:interfaces" : { 637 data: "interface": [ 638 data: { 639 data: "name": "eth0", 640 data: "oper-status": "up" 641 data: } 642 data: ], 643 data: }, 644 data: "eventClass" : "state", 645 data: "reportingEntity": { 646 data: "card": "Ethernet0" 647 data: } 648 data: "severity" : "minor" 649 data: } 650 data: } 651 data: } 652 data: } 654 An example of YANG-Push in XML would look something like this: 656 data: 657 data: 2017-10-25T08:00:11.22Z 658 data: 659 data: 1011 660 data: 661 data: 662 data: 663 data: eth0 664 data: up 665 data: 666 data: 667 data: state 668 data: 669 data: Ethernet0 670 data: 671 data: minor 672 data: 673 data: 674 data: 676 7. IANA Considerations 678 This document registers two URI, two YANG module and two Media Types. 680 7.1. URI Registration 682 in the IETF XML registry [RFC3688]. Following the format in RFC 683 3688, the following registration is requested to be made: 685 URI: urn:ietf:params:xml:ns:yang:ietf-http-notif 686 URI: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list 688 Registrant Contact: The IESG. XML: N/A, the requested URI is an XML 689 namespace. 691 7.2. YANG Module Name Registration 693 This document registers one YANG module in the YANG Module Names 694 registry YANG [RFC6020]. 696 name: ietf-https-notif 697 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif 698 prefix: hn 699 reference: RFC XXXX 701 name: ietf-sub-recv-list 702 namespace: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list 703 prefix: snrl 704 reference: RFC XXXX 706 7.3. Media Types 708 7.3.1. Media Type "application/ietf-https-notif-cap+xml 710 Type name: application 712 Subtype name: ietf-https-notif-cap+xml 714 Required parameters: None 716 Optional parameters: None 718 Encoding considerations: 719 8-bit Each conceptual YANG data node is encoded according to the XML 720 Encoding Rules and Canonical Format for the specific YANG data node 721 type defined in YANG 1.1 [RFC7950]. 723 Security considerations: 725 Security considerations related to the generation and consumption of 726 RESTCONF messages are discussed in Section NN of RFC XXXX. 728 Additional security considerations are specific to the semantics of 729 particular YANG data models. Each YANG module is expected to specify 730 security considerations for the YANG data defined in that module. 732 Interoperability considerations: N/A 734 Published specification: RFC XXXX 736 Applications that use this media type: 737 Instance document data parsers used within a protocol or automation 738 tool that utilize YANG-defined data structures. 740 Fragment identifier considerations: 741 Fragment identifiers for this type are not defined. All YANG data 742 nodes are accessible as resources using the path in the request URI. 744 Additional information: 746 Deprecated alias names for this type: N/A 747 Magic number(s): N/A 748 File extension(s): None 749 Macintosh file type code(s): "TEXT" 751 Person & email address to contact for further information: 752 See Author's Address section of RFC XXXX. 754 Intended usage: COMMON 756 Restrictions on usage: N/A 758 Author: See Author's Address section of RFC XXXX 760 Change controller: 761 Internet Engineering Task Force (mailto:iesg@ietf.org) 763 Provisional registration? (standards tree only): no 765 7.3.2. Media Type "application/ietf-https-notif-cap+json 767 Type name: application 769 Subtype name: ietf-https-notif-cap+json 771 Required parameters: None 772 Optional parameters: None 774 Encoding considerations: 775 8-bit Each conceptual YANG data node is encoded according to the XML 776 Encoding Rules and Canonical Format for the specific YANG data node 777 type defined in JSON Encoding of Data Modeled with YANG [RFC7951]. 779 Security considerations: 780 Security considerations related to the generation and consumption of 781 RESTCONF messages are discussed in Section NN of RFC XXXX. 783 Additional security considerations are specific to the semantics of 784 particular YANG data models. Each YANG module is expected to specify 785 security considerations for the YANG data defined in that module. 787 Interoperability considerations: N/A 789 Published specification: RFC XXXX 791 Applications that use this media type: 792 Instance document data parsers used within a protocol or automation 793 tool that utilize YANG-defined data structures. 795 Fragment identifier considerations: 796 Fragment identifiers for this type are not defined. All YANG data 797 nodes are accessible as resources using the path in the request URI. 799 Additional information: 801 Deprecated alias names for this type: N/A 802 Magic number(s): N/A 803 File extension(s): None 804 Macintosh file type code(s): "TEXT" 806 Person & email address to contact for further information: 807 See Author's Address section of RFC XXXX. 809 Intended usage: COMMON 811 Restrictions on usage: N/A 813 Author: See Author's Address section of RFC XXXX 815 Change controller: 816 Internet Engineering Task Force (mailto:iesg@ietf.org) 818 Provisional registration? (standards tree only): no 819 8. Examples 821 This section shows some examples in how the module can be used. 823 8.1. Subscribed Notification based Configuration 825 This example shows how a HTTPS client can be configured to send 826 notifications to a receiver at address 192.0.2.1, port 443, a 'path', 827 with server certificates, and the corresponding trust store that is 828 used to authenticate a connection. 830 [note: '\' line wrapping for formatting only] 832 833 834 837 839 840 foo 841 845 846 847 my-receiver.my-domain.com 848 443 849 850 851 852 853 854 855 Server Cert Issuer #1 856 base64encodedvalue== 857 858 859 860 861 862 863 864 865 my-name 866 my-password 868 869 870 /some/path 871 872 873 874 875 876 1 877 11:0A:05:11:00 878 x509c2n:san-any 879 880 881 882 883 884 885 886 6666 887 889 hn:https 890 891 foo 892 some-stream 893 894 895 my-receiver 896 \ 898 foo 899 900 901 902 904 905 906 907 explicitly-trusted-server-ca-certs 908 909 Trust anchors (i.e. CA certs) that are used to authenticat\ 910 e 911 server connections. Servers are authenticated if their 912 certificate has a chain of trust to one of these CA 913 certificates. 914 915 916 ca.example.com 917 base64encodedvalue== 918 919 920 Fred Flintstone 921 base64encodedvalue== 922 923 924 925 926 928 8.2. Non Subscribed Notification based Configuration 930 In the case that it is desired to use HTTPS notif outside of 931 Subscribed Notifications, there would have to be a module to define 932 the configuration for where and how to send the notification, such as 933 the following: 935 [note: '\' line wrapping for formatting only] 937 module example-custom-module { 938 yang-version 1.1; 939 namespace "http://example.com/example-custom-module"; 940 prefix "custom"; 942 import ietf-http-client { 943 prefix httpc; 944 reference 945 "I-D.ietf-netconf-http-client-server"; 946 } 948 organization 949 "Example, Inc."; 951 contact 952 "Support at example.com"; 954 description 955 "Example of module not using Subscribed Notifications module."; 957 revision "2020-10-21" { 958 description 959 "Initial Version."; 960 reference 961 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 962 } 963 container example-module { 964 description 965 "Example of using HTTPS notif without having to 966 implement Subscribed Notifications."; 968 container https-receivers { 969 description 970 "A container of all HTTPS notif receivers."; 972 list https-receiver { 973 key "name"; 975 leaf name { 976 type string; 977 description 978 "A unique name for the https notif receiver."; 979 } 981 uses httpc:http-client-stack-grouping { 982 refine "transport/tcp" { 983 // create the logical impossibility of enabling "tcp" 984 // transport 985 if-feature "not httpc:tcp-supported"; 986 } 987 augment "transport/tls/tls/http-client-parameters" { 988 leaf path { 989 type string; 990 description 991 "Relative URI to the target resource."; 992 } 993 description 994 "Augmentation to add a path to the target resource."; 995 } 996 } 997 description 998 "Just include the grouping from ietf-http-client to 999 realize the 'HTTPS stack'."; 1000 } 1001 } 1002 } 1003 } 1005 This example shows how a HTTPS client can be configured to send 1006 notifications to a receiver at address 192.0.2.1, port 443, a 'path', 1007 with server certificates, and the corresponding trust store that is 1008 used to authenticate a connection. 1010 [note: '\' line wrapping for formatting only] 1012 1013 1014 1016 1017 1018 foo 1019 1020 1021 my-receiver.my-domain.com 1022 443 1023 1024 1025 1026 1027 1028 1029 Server Cert Issuer #1 1030 base64encodedvalue== 1031 1032 1033 1034 1035 1036 1037 1038 1039 my-name 1040 my-password 1041 1042 1043 /some/path 1044 1045 1046 1047 1048 1050 1051 1052 1053 explicitly-trusted-server-ca-certs 1054 1055 Trust anchors (i.e. CA certs) that are used to authenticat\ 1056 e 1057 server connections. Servers are authenticated if their 1058 certificate has a chain of trust to one of these CA 1059 certificates. 1060 1061 1062 ca.example.com 1063 base64encodedvalue== 1064 1065 1066 Fred Flintstone 1067 base64encodedvalue== 1068 1069 1070 1071 1072 1074 8.3. Bundled Message 1076 In the case of "bundled-message" as defined in Notification Message 1077 Headers and Bundles [I-D.ietf-netconf-notification-messages], 1078 something that this module supports, the flow of messages would look 1079 something like this. 1081 ------------- -------------- 1082 | Publisher | | Receiver | 1083 ------------- -------------- 1084 Establish TCP ------> 1085 Establish TLS ------> 1086 Send HTTPS POST message 1087 with YANG defined ------> 1088 notification #1 1089 Send HTTPS POST message 1090 with YANG defined ------> 1091 notification #2 1092 Send 204 (No Content) 1093 <------ for notification #1 1095 Send 204 (No Content) 1096 <------ for notification #2 1097 Send HTTPS POST message 1098 with YANG defined -------> 1099 notification #3 1100 Send 204 (No Content) 1101 <------ for notification #3 1103 The content of the exchange would look something like this. 1105 Request: 1106 POST /some/path HTTP/1.1 1107 Host: my-receiver.my-domain.com 1108 Content-Type: application/yang-data+xml 1109 1111 2019-03-22T12:35:00Z 1112 1113 ... 1114 1115 1116 1118 2019-03-22T12:35:00Z 1119 1120 ... 1121 1122 1123 1125 2019-03-22T12:35:01Z 1126 1127 ... 1128 1129 1130 Response: 1131 HTTP/1.1 204 No Content 1132 Date: Fri, 03 Mar 2019 12:35:00 GMT 1133 Server: my-receiver.my-domain.com 1134 HTTP/1.1 204 No Content 1135 Date: Fri, 03 Mar 2019 12:35:00 GMT 1136 Server: my-receiver.my-domain.com 1137 HTTP/1.1 204 No Content 1138 Date: Fri, 03 Mar 2019 12:35:01 GMT 1139 Server: my-receiver.my-domain.com 1141 9. Contributors 1143 10. Acknowledgements 1145 11. Normative references 1147 [I-D.ietf-netconf-http-client-server] 1148 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 1149 Servers", draft-ietf-netconf-http-client-server-05 (work 1150 in progress), August 2020. 1152 [I-D.ietf-netconf-notification-messages] 1153 Voit, E., Jenkins, T., Birkholz, H., Bierman, A., and A. 1154 Clemm, "Notification Message Headers and Bundles", draft- 1155 ietf-netconf-notification-messages-08 (work in progress), 1156 November 2019. 1158 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1159 Requirement Levels", BCP 14, RFC 2119, 1160 DOI 10.17487/RFC2119, March 1997, 1161 . 1163 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1164 DOI 10.17487/RFC3688, January 2004, 1165 . 1167 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1168 Resource Identifier (URI): Generic Syntax", STD 66, 1169 RFC 3986, DOI 10.17487/RFC3986, January 2005, 1170 . 1172 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1173 the Network Configuration Protocol (NETCONF)", RFC 6020, 1174 DOI 10.17487/RFC6020, October 2010, 1175 . 1177 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1178 and A. Bierman, Ed., "Network Configuration Protocol 1179 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1180 . 1182 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1183 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1184 . 1186 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1187 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1188 . 1190 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 1191 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 1192 December 2014, . 1194 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1195 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1196 . 1198 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1199 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1200 . 1202 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1203 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1204 . 1206 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1207 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1208 May 2017, . 1210 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1211 Access Control Model", STD 91, RFC 8341, 1212 DOI 10.17487/RFC8341, March 2018, 1213 . 1215 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1216 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1217 . 1219 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 1220 E., and A. Tripathy, "Subscription to YANG Notifications", 1221 RFC 8639, DOI 10.17487/RFC8639, September 2019, 1222 . 1224 Authors' Addresses 1226 Mahesh Jethanandani 1227 Kloud Services 1229 Email: mjethanandani@gmail.com 1231 Kent Watsen 1232 Watsen Networks 1233 USA 1235 Email: kent+ietf@watsen.net