idnits 2.17.00 (12 Aug 2021) /tmp/idnits19407/draft-ietf-netconf-https-notif-09.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 2 instances of too long lines in the document, the longest one being 3 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 396 has weird spacing: '...rw name str...' == Line 549 has weird spacing: '...address ine...' == Line 567 has weird spacing: '...address ine...' == Line 596 has weird spacing: '...erprint x50...' -- The document date (24 October 2021) is 202 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 (-09) exists of draft-ietf-netconf-http-client-server-07 Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF M.J. Jethanandani 3 Internet-Draft Kloud Services 4 Intended status: Standards Track K.W. Watsen 5 Expires: 27 April 2022 Watsen Networks 6 24 October 2021 8 An HTTPS-based Transport for YANG Notifications 9 draft-ietf-netconf-https-notif-09 11 Abstract 13 This document defines a protocol for sending notifications over 14 HTTPS. YANG modules for configuring publishers are also defined. 15 Examples are provided illustrating how to configure various 16 publishers. 18 This document requires that the publisher is a "server" (e.g., a 19 NETCONF or RESTCONF server), but does not assume that the receiver is 20 a server. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 27 April 2022. 39 Copyright Notice 41 Copyright (c) 2021 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 49 extracted from this document must include Simplified BSD License text 50 as described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.1. Applicability Statement . . . . . . . . . . . . . . . . . 3 57 1.2. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 58 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 4 59 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 60 1.4.1. Subscribed Notifications . . . . . . . . . . . . . . 4 61 2. Overview of Publisher to Receiver Interaction . . . . . . . . 4 62 3. Discovering a Receiver's Capabilities . . . . . . . . . . . . 5 63 3.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 64 3.2. Request . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6 66 3.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 4. Sending Event Notifications . . . . . . . . . . . . . . . . . 7 68 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 8 69 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 70 4.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 5. The "ietf-subscribed-notif-receivers" Module . . . . . . . . 9 72 5.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 9 73 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 74 6. The "ietf-https-notif-transport" Module . . . . . . . . . . . 12 75 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 12 76 6.2. YANG module . . . . . . . . . . . . . . . . . . . . . . . 14 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 78 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 79 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 18 80 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 18 81 8.3. The "Capabilities for HTTPS Notification Receivers" 82 Registry . . . . . . . . . . . . . . . . . . . . . . . . 19 83 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 84 9.1. Normative references . . . . . . . . . . . . . . . . . . 20 85 9.2. Informative references . . . . . . . . . . . . . . . . . 21 86 Appendix A. Configuration Examples . . . . . . . . . . . . . . . 22 87 A.1. Using Subscribed Notifications (RFC 8639) . . . . . . . . 22 88 A.2. Not Using Subscribed Notifications . . . . . . . . . . . 24 89 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 92 1. Introduction 94 This document defines a protocol for sending notifications over 95 HTTPS. Using HTTPS maximizes transport-level interoperability, while 96 allowing for a variety of encoding options. This document defines 97 support for JSON and XML; future efforts may define support for other 98 encodings (e.g., binary). 100 This document also defines two YANG 1.1 [RFC7950] modules that extend 101 the data model defined in Subscription to YANG Notifications 102 [RFC8639], enabling the configuration of HTTPS-based receivers. 104 An example module illustrating the configuration of a publisher not 105 using the data model defined in RFC 8639 is also provided. 107 Configured subscriptions enable a server, acting as a publisher of 108 notifications, to proactively push notifications to external 109 receivers without the receivers needing to first connect to the 110 server, as is the case with dynamic subscriptions. 112 1.1. Applicability Statement 114 While the YANG modules have been defined as an augmentation of 115 Subscription to YANG Notifications [RFC8639], the notification method 116 defined in this document MAY be used outside of Subscription to YANG 117 Notifications [RFC8639] by using some of the definitions from this 118 module along with the grouping defined in Groupings for HTTP Clients 119 and Servers [I-D.ietf-netconf-http-client-server]. For an example on 120 how that can be done, see Section A.2. 122 1.2. Note to RFC Editor 124 This document uses several placeholder values throughout the 125 document. Please replace them as follows and remove this section 126 before publication. 128 RFC XXXX, where XXXX is the number assigned to this document at the 129 time of publication. 131 RFC YYYY, where YYYY is the number assigned to 132 [I-D.ietf-netconf-http-client-server]. 134 2021-10-24 with the actual date of the publication of this document. 136 1.3. Abbreviations 138 +=========+======================================+ 139 | Acronym | Expansion | 140 +=========+======================================+ 141 | HTTP | Hyper Text Transport Protocol | 142 +---------+--------------------------------------+ 143 | HTTPS | Hyper Text Transport Protocol Secure | 144 +---------+--------------------------------------+ 145 | TCP | Transmission Control Protocol | 146 +---------+--------------------------------------+ 147 | TLS | Transport Layer Security | 148 +---------+--------------------------------------+ 150 Table 1 152 1.4. Terminology 154 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 155 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 156 "OPTIONAL" in this document are to be interpreted as described in BCP 157 14 [RFC2119] [RFC8174] when, and only when, they appear in all 158 capitals, as shown here. 160 1.4.1. Subscribed Notifications 162 The following terms are defined in Subscription to YANG Notifications 163 [RFC8639]. 165 * Subscribed Notifications 167 2. Overview of Publisher to Receiver Interaction 169 The protocol consists of two HTTP-based target resources presented by 170 the receiver. These two resources share a common prefix that the 171 publisher must know. If the data model in section 6.2 is used, this 172 common prefix is defined by the "path" leaf in the "http-client- 173 parameters" container. 175 * "capabilities": A target resource enabling the publisher to 176 discover what optional capabilities a receiver supports. 177 Publishers SHOULD query this target before sending any 178 notifications or if ever an error occurs. 180 * "relay-notifications": A target resource enabling the publisher to 181 send one or more notification to a receiver. This document 182 defines support for sending only one notification per message; a 183 future effort MAY extend the protocol to send multiple 184 notifications per message. 186 The protocol is illustrated in the diagram below: 188 ------------- -------------- 189 | Publisher | | Receiver | 190 ------------- -------------- 192 Send HTTPS GET message ------> 193 to discover receiver's 194 capabilities 196 <------ Send 200 (OK) containing 197 capabilities supported 198 by the receiver 200 +-- For Each Notification (MAY be pipelined) ---------------------+ 201 | | 202 | Send HTTPS POST message ------> | 203 | with YANG defined | 204 | notification | 205 | | 206 | <------ Send 204 (No Content) | 207 +-----------------------------------------------------------------+ 209 Note that, for RFC 8639 configured subscriptions, the very first 210 notification must be the "subscription-started" notification. 212 The POST messages MAY be "pipelined" (not illustrated in the diagram 213 above), whereby multiple notifications are sent without waiting for 214 the HTTP response for a previous POST. 216 3. Discovering a Receiver's Capabilities 218 3.1. Applicability 220 For publishers using Subscription to YANG Notifications [RFC8639], 221 dynamic discovery of a receiver's supported encoding is necessary 222 only when the "/subscriptions/subscription/encoding" leaf is not 223 configured, per the "encoding" leaf's description statement in the 224 "ietf-subscribed-notification" module. 226 3.2. Request 228 To learn the capabilities of a receiver, a publisher can issue an 229 HTTPS GET request to the "capabilities" resource (see Section 2) on 230 the receiver with "Accept" header set using the "application/xml" 231 and/or "application/json" media-types, with the latter as mandatory 232 to implement, and the default in case the type is not specified. 234 3.3. Response 236 The receiver responds with a "200 (OK)" message, having the "Content- 237 Type" header set to either "application/xml" or "application/json" 238 (which ever was selected), and containing in the response body a list 239 of the receiver's capabilities encoded in the selected format. 241 Even though a YANG module is not defined for this interaction, the 242 response body MUST conform to the following YANG-modeled format: 244 container receiver-capabilities { 245 description 246 "A container for a list of capabilities supported by 247 the receiver."; 248 leaf-list receiver-capability { 249 type "inet:uri"; 250 description 251 "A capability supported by the receiver. A partial list of 252 capabilities is defined in the 'Capabilities for HTTPS 253 Notification Receivers' registry (see RFC XXXX). Additional 254 custom capabilities MAY be defined."; 255 } 256 } 258 As it is possible that the receiver may return custom capability 259 URIs, the publisher MUST ignore any capabilities that it does not 260 recognize. 262 3.4. Example 264 The publisher can send the following request to learn the receiver 265 capabilities. In this example, the "Accept" states that the receiver 266 wants to receive the capabilities response in XML but, if not 267 supported, then in JSON. 269 GET /some/path/capabilities HTTP/1.1 270 Host: example.com 271 Accept: application/xml, application/json 272 If the receiver is able to reply using "application/xml", and 273 assuming it is able to receive JSON and XML encoded notifications, 274 and it is able to process the RFC 8639 state machine, the response 275 might look like this: 277 HTTP/1.1 200 OK 278 Date: Wed, 26 Feb 2020 20:33:30 GMT 279 Server: example-server 280 Cache-Control: no-cache 281 Content-Type: application/xml 282 Content-Length: nnn 284 285 \ 286 urn:ietf:capability:https-notif-receiver:encoding:json\ 287 288 \ 289 urn:ietf:capability:https-notif-receiver:encoding:xml\ 290 291 \ 292 urn:ietf:capability:https-notif-receiver:encoding:sub-notif\ 293 294 296 If the receiver is unable to reply using "application/xml", the 297 response might look like this: 299 HTTP/1.1 200 OK 300 Date: Wed, 26 Feb 2020 20:33:30 GMT 301 Server: example-server 302 Cache-Control: no-cache 303 Content-Type: application/json 304 Content-Length: nnn 306 { 307 receiver-capabilities { 308 "receiver-capability": [ 309 "urn:ietf:capability:https-notif-receiver:encoding:json", 310 "urn:ietf:capability:https-notif-receiver:encoding:xml", 311 "urn:ietf:capability:https-notif-receiver:encoding:sub-notif" 312 ] 313 } 314 } 316 4. Sending Event Notifications 317 4.1. Request 319 The publisher sends an HTTPS POST request to the "relay-notification" 320 resource (see Section 2) on the receiver with the "Content-Type" 321 header set to either "application/json" or "application/xml" and a 322 body containing the notification encoded using the specified format. 324 XML-encoded notifications are encoded using the format defined by 325 NETCONF Event Notifications [RFC5277] for XML. 327 JSON-encoded notifications are encoded the same as specified in 328 Section 6.4 in RESTCONF [RFC8040] with the following deviations: 330 * The notifications do not contain the "data:" prefix used by SSE. 332 * Instead of saying that, for JSON-encoding purposes, the module 333 name for the "notification" element is "ietf-restconf, the module 334 name will instead be "ietf-https-notif". 336 4.2. Response 338 The response should be "204 (No Content)". 340 4.3. Example 342 An XML-encoded notification might be sent as follows: 344 POST /some/path/relay-notification HTTP/1.1 345 Host: example.com 346 Content-Type: application/xml 348 349 2019-03-22T12:35:00Z 350 351 fault 352 353 Ethernet0 354 355 major 356 357 359 A JSON-encoded notification might be sent as follows: 361 POST /some/path/relay-notification HTTP/1.1 362 Host: example.com 363 Content-Type: application/json 365 { 366 "ietf-https-notif:notification": { 367 "eventTime": "2013-12-21T00:01:00Z", 368 "example-mod:event" : { 369 "event-class" : "fault", 370 "reporting-entity" : { "card" : "Ethernet0" }, 371 "severity" : "major" 372 } 373 } 374 } 376 And, in either case, the response might be as follows: 378 HTTP/1.1 204 No Content 379 Date: Wed, 26 Feb 2020 20:33:30 GMT 380 Server: example-server 382 5. The "ietf-subscribed-notif-receivers" Module 384 5.1. Data Model Overview 386 This YANG module augments the "ietf-subscribed-notifications" module 387 to define a choice of transport types that other modules such as the 388 "ietf-https-notif-transport" module can use to define a transport 389 specific receiver. 391 module: ietf-subscribed-notif-receivers 393 augment /sn:subscriptions: 394 +--rw receiver-instances 395 +--rw receiver-instance* [name] 396 +--rw name string 397 +--rw (transport-type) 398 augment /sn:subscriptions/sn:subscription/sn:receivers/sn:receiver: 399 +--rw receiver-instance-ref? leafref 401 5.2. YANG Module 403 The YANG module imports Subscription to YANG Notifications [RFC8639]. 405 file "ietf-subscribed-notif-receivers@2021-10-24.yang" 406 module ietf-subscribed-notif-receivers { 407 yang-version 1.1; 408 namespace 409 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers"; 410 prefix "snr"; 412 import ietf-subscribed-notifications { 413 prefix sn; 414 reference 415 "RFC 8639: Subscription to YANG Notifications"; 416 } 418 organization 419 "IETF NETCONF Working Group"; 421 contact 422 "WG Web: 423 WG List: 425 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 426 Kent Watsen (kent plus ietf at watsen dot net)"; 428 description 429 "This YANG module is implemented by Publishers implementing 430 the 'ietf-subscribed-notifications' module defined in RFC 8639. 432 While this module is defined in RFC XXXX, which primarily 433 defines an HTTPS-based transport for notifications, this module 434 is not HTTP-specific. It is a generic extension that can be 435 used by any 'notif' transport. 437 This module defines two 'augment' statements. One statement 438 augments a 'container' statement called 'receiver-instances' 439 into the top-level 'subscriptions' container. The other 440 statement, called 'receiver-instance-ref', augemnts a 'leaf' 441 statement into each 'receiver' that references one of the 442 afore mentioned receiver instances. This indirection enables 443 multiple configured subscriptions to send notifications to 444 the same receiver instance. 446 Copyright (c) 2021 IETF Trust and the persons identified as 447 the document authors. All rights reserved. 448 Redistribution and use in source and binary forms, with or 449 without modification, is permitted pursuant to, and subject 450 to the license terms contained in, the Simplified BSD 451 License set forth in Section 4.c of the IETF Trust's Legal 452 Provisions Relating to IETF Documents 453 (http://trustee.ietf.org/license-info). 455 This version of this YANG module is part of RFC XXXX; see 456 the RFC itself for full legal notices. 458 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 459 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 460 'MAY', and 'OPTIONAL' in this document are to be interpreted as 461 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 462 they appear in all capitals, as shown here."; 464 revision "2021-10-24" { 465 description 466 "Initial Version."; 467 reference 468 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 469 } 471 augment "/sn:subscriptions" { 472 container receiver-instances { 473 description 474 "A container for all instances of receivers."; 476 list receiver-instance { 477 key "name"; 479 leaf name { 480 type string; 481 description 482 "An arbitrary but unique name for this receiver 483 instance."; 484 } 486 choice transport-type { 487 mandatory true; 488 description 489 "Choice of different types of transports used to 490 send notifications. The 'case' statements must 491 be augmented in by other modules."; 492 } 493 description 494 "A list of all receiver instances."; 495 } 496 } 497 description 498 "Augment the subscriptions container to define the 499 transport type."; 500 } 501 augment 502 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 503 leaf receiver-instance-ref { 504 type leafref { 505 path "/sn:subscriptions/snr:receiver-instances/" + 506 "snr:receiver-instance/snr:name"; 507 } 508 description 509 "Reference to a receiver instance."; 510 } 511 description 512 "Augment the subscriptions container to define an optional 513 reference to a receiver instance."; 514 } 515 } 516 518 6. The "ietf-https-notif-transport" Module 520 6.1. Data Model Overview 522 This YANG module is a definition of a set of receivers that are 523 interested in the notifications published by the publisher. The 524 module contains the TCP, TLS and HTTPS parameters that are needed to 525 communicate with the receiver. The module augments the "ietf- 526 subscribed-notif-receivers" module to define a transport specific 527 receiver. 529 As mentioned earlier, it uses a POST method to deliver the 530 notification. The "http-receiver/tls/http-client-parameters/path" 531 leaf defines the path for the resource on the receiver, as defined by 532 "path-absolute" in URI Generic Syntax [RFC3986]. The user-id used by 533 Network Configuration Access Control Model [RFC8341], is that of the 534 receiver and is derived from the certificate presented by the 535 receiver as part of "receiver-identity". 537 An abridged tree diagram representing the module is shown below. 539 module: ietf-https-notif-transport 541 augment /sn:subscriptions/snr:receiver-instances 542 /snr:receiver-instance/snr:transport-type: 543 +--:(https) 544 +--rw https-receiver 545 +--rw (transport) 546 | +--:(tcp) {tcp-supported,not httpc:tcp-supported}? 547 | | +--rw tcp 548 | | +--rw tcp-client-parameters 549 | | | +--rw remote-address inet:host 550 | | | +--rw remote-port? inet:port-number 551 | | | +--rw local-address? inet:ip-address 552 | | | | {local-binding-supported}? 553 | | | +--rw local-port? inet:port-number 554 | | | | {local-binding-supported}? 555 | | | +--rw proxy-server! {proxy-connect}? 556 | | | | ... 557 | | | +--rw keepalives! {keepalives-supported}? 558 | | | ... 559 | | +--rw http-client-parameters 560 | | +--rw client-identity! 561 | | | ... 562 | | +--rw proxy-connect! {proxy-connect}? 563 | | ... 564 | +--:(tls) {tls-supported}? 565 | +--rw tls 566 | +--rw tcp-client-parameters 567 | | +--rw remote-address inet:host 568 | | +--rw remote-port? inet:port-number 569 | | +--rw local-address? inet:ip-address 570 | | | {local-binding-supported}? 571 | | +--rw local-port? inet:port-number 572 | | | {local-binding-supported}? 573 | | +--rw proxy-server! {proxy-connect}? 574 | | | ... 575 | | +--rw keepalives! {keepalives-supported}? 576 | | ... 577 | +--rw tls-client-parameters 578 | | +--rw client-identity! 579 | | | ... 580 | | +--rw server-authentication 581 | | | ... 582 | | +--rw hello-params {tlscmn:hello-params}? 583 | | | ... 584 | | +--rw keepalives {tls-client-keepalives}? 585 | | ... 586 | +--rw http-client-parameters 587 | +--rw client-identity! 588 | | ... 589 | +--rw proxy-connect! {proxy-connect}? 590 | | ... 591 | +--rw path string 592 +--rw receiver-identity {receiver-identity}? 593 +--rw cert-maps 594 +--rw cert-to-name* [id] 595 +--rw id uint32 596 +--rw fingerprint x509c2n:tls-fingerprint 597 +--rw map-type identityref 598 +--rw name string 600 6.2. YANG module 602 The YANG module imports A YANG Data Model for SNMP Configuration 603 [RFC7407], Subscription to YANG Notifications [RFC8639], and YANG 604 Groupings for HTTP Clients and HTTP Servers 605 [I-D.ietf-netconf-http-client-server]. 607 The YANG module is shown below. 609 file "ietf-https-notif-transport@2021-10-24.yang" 610 module ietf-https-notif-transport { 611 yang-version 1.1; 612 namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif-transport"; 613 prefix "hnt"; 615 import ietf-x509-cert-to-name { 616 prefix x509c2n; 617 reference 618 "RFC 7407: YANG Data Model for SNMP Configuration."; 619 } 621 import ietf-subscribed-notifications { 622 prefix sn; 623 reference 624 "RFC 8639: Subscription to YANG Notifications"; 625 } 627 import ietf-subscribed-notif-receivers { 628 prefix snr; 629 reference 630 "RFC XXXX: An HTTPS-based Transport for 631 Configured Subscriptions"; 632 } 634 import ietf-http-client { 635 prefix httpc; 636 reference 637 "RFC YYYY: YANG Groupings for HTTP Clients and HTTP Servers"; 638 } 640 organization 641 "IETF NETCONF Working Group"; 643 contact 644 "WG Web: 645 WG List: 647 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 648 Kent Watsen (kent plus ietf at watsen dot net)"; 650 description 651 "This YANG module is implemented by Publishers that implement 652 the 'ietf-subscribed-notifications' module defined in RFC 8639. 654 This module augments a 'case' statement called 'https' into 655 the 'choice' statement called 'transport-type' defined 656 by the 'ietf-https-notif-transport' module defined in RFC XXXX. 658 Copyright (c) 2021 IETF Trust and the persons identified as 659 the document authors. All rights reserved. 660 Redistribution and use in source and binary forms, with or 661 without modification, is permitted pursuant to, and subject 662 to the license terms contained in, the Simplified BSD 663 License set forth in Section 4.c of the IETF Trust's Legal 664 Provisions Relating to IETF Documents 665 (http://trustee.ietf.org/license-info). 667 This version of this YANG module is part of RFC XXXX; see 668 the RFC itself for full legal notices. 670 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 671 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 672 'MAY', and 'OPTIONAL' in this document are to be interpreted as 673 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 674 they appear in all capitals, as shown here."; 676 revision "2021-10-24" { 677 description 678 "Initial Version."; 679 reference 680 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 681 } 683 feature receiver-identity { 684 description 685 "Indicates that the server supports filtering notifications 686 based on the receiver's identity derived from its TLS 687 certificate."; 688 } 690 identity https { 691 base sn:transport; 692 description 693 "HTTPS transport for notifications."; 694 } 696 grouping https-receiver-grouping { 697 description 698 "A grouping that may be used by other modules wishing to 699 configure HTTPS-based notifications without using RFC 8639."; 700 uses httpc:http-client-stack-grouping { 701 refine "transport/tcp" { 702 // create the logical impossibility of enabling the 703 // "tcp" transport (i.e., "HTTP" without the 'S'). 704 if-feature "not httpc:tcp-supported"; 705 } 706 augment "transport/tls/tls/http-client-parameters" { 707 leaf path { 708 type string; 709 mandatory true; 710 description 711 "URI prefix to the target resources. Under this 712 path the receiver must support both the 'capabilities' 713 and 'relay-notification' resource targets, as described 714 in RFC XXXX."; 715 } 716 description 717 "Augmentation to add a receiver-specific path for the 718 'capabilities' and 'relay-notification' resources."; 719 } 720 } 721 container receiver-identity { 722 if-feature receiver-identity; 723 description 724 "Maps the receiver's TLS certificate to a local identity 725 enabling access control to be applied to filter out 726 notifications that the receiver may not be authorized 727 to view."; 728 container cert-maps { 729 uses x509c2n:cert-to-name; 730 description 731 "The cert-maps container is used by a TLS-based HTTP 732 server to map the HTTPS client's presented X.509 733 certificate to a 'local' username. If no matching and 734 valid cert-to-name list entry is found, the publisher 735 MUST close the connection, and MUST NOT not send any 736 notifications over it."; 737 reference 738 "RFC 7407: A YANG Data Model for SNMP Configuration."; 739 } 740 } 742 } 744 augment "/sn:subscriptions/snr:receiver-instances/" + 745 "snr:receiver-instance/snr:transport-type" { 746 case https { 747 container https-receiver { 748 description 749 "The HTTPS receiver to send notifications to."; 750 uses https-receiver-grouping; 751 } 752 } 753 description 754 "Augment the transport-type choice to include the 'https' 755 transport."; 756 } 757 } 758 760 7. Security Considerations 762 The YANG module specified in this document defines a schema for data 763 that is designed to be accessed via network management protocols such 764 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 765 is the secure transport layer, and the mandatory-to-implement secure 766 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 767 is HTTPS, and the mandatory-to-implement secure transport is TLS 768 [RFC8446]. The NETCONF Access Control Model (NACM) [RFC8341] 769 provides the means to restrict access for particular NETCONF or 770 RESTCONF users to a preconfigured subset of all available NETCONF or 771 RESTCONF protocol operations and content. 773 The YANG module in this document makes use of grouping that are 774 defined in YANG Groupings for HTTP Clients and HTTP Servers 775 [I-D.ietf-netconf-http-client-server], and A YANG Data Model for SNMP 776 Configuration [RFC7407]. Please see the Security Considerations 777 section of those documents for considerations related to sensitivity 778 and vulnerability of the data nodes defined in them. 780 There are a number of data nodes defined in this YANG module that are 781 writable/creatable/deletable (i.e., config true, which is the 782 default). These data nodes may be considered sensitive or vulnerable 783 in some network environments. Write operations (e.g., edit-config) 784 to these data nodes without proper protection can have a negative 785 effect on network operations. These are the subtrees and data nodes 786 and their sensitivity/vulnerability: 788 * The "path" node in "ietf-subscribed-notif-receivers" module can be 789 modified by a malicious user to point to an invalid URI. 791 Some of the readable data nodes in YANG module may be considered 792 sensitive or vulnerable in some network environments. It is thus 793 important to control read access (e.g., via get, get-config, or 794 notification) to these data nodes. The model does not define any 795 readable subtrees and data nodes. 797 Some of the RPC operations in YANG module may be considered sensitive 798 or vulnerable in some network environments. It is thus important to 799 control access to these operations. The model does not define any 800 RPC operations. 802 8. IANA Considerations 804 8.1. The "IETF XML" Registry 806 This document registers two URIs in the "ns" subregistry of the "IETF 807 XML" registry [RFC3688]. Following the format in [RFC3688], the 808 following registrations are requested: 810 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 811 Registrant Contact: The IESG 812 XML: N/A, the requested URI is an XML namespace. 814 URI: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 815 Registrant Contact: The IESG 816 XML: N/A, the requested URI is an XML namespace. 818 8.2. The "YANG Module Names" Registry 820 This document registers two YANG modules in the "YANG Module Names" 821 registry [RFC6020]. Following the format in [RFC6020], the following 822 registrations are requested: 824 name: ietf-subscribed-notif-receivers 825 namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 826 prefix: snr 827 reference: RFC XXXX 829 name: ietf-https-notif-transport 830 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 831 prefix: hnt 832 reference: RFC XXXX 833 8.3. The "Capabilities for HTTPS Notification Receivers" Registry 835 Following the guidelines defined in [RFC8126], this document defines 836 a new registry called "Capabilities for HTTPS Notification 837 Receivers". This registry defines capabilities that can be supported 838 by HTTPS-based notification receivers. 840 The following note shall be at the top of the registry: 842 This registry defines capabilities that can be 843 supported by HTTPS-based notification receivers. 845 The fields for each registry are: 847 * URN 849 - The name of the URN (required). 851 - The URN must conform to the syntax described by [RFC8141]. 853 - The URN must begin with the string "urn:ietf:capability:https- 854 notif-receiver". 856 * Reference 858 - The RFC that defined the URN. 860 - The RFC must be in the form "RFC : . 862 * Description 864 - An arbitrary description of the algorithm (optional). 866 - The description should be no more than a few sentences. 868 - The description is to be in English, but may contain UTF-8 869 characters as may be needed in some cases. 871 The update policy is either "RFC Required". Updates do not otherwise 872 require an expert review by a Designated Expert. 874 Following is the initial assignment for this registry: 876 Record: 877 Name: urn:ietf:capability:https-notif-receiver:encoding:json 878 Reference: RFC XXXX 879 Description: Identifies support for JSON-encoded notifications. 881 Record: 882 Name: urn:ietf:capability:https-notif-receiver:encoding:xml 883 Reference: RFC XXXX 884 Description: Identifies support for XML-encoded notifications. 886 Record: 887 Name: urn:ietf:capability:https-notif-receiver:encoding:sub-notif 888 Reference: RFC XXXX 889 Description: Identifies support for state machine described in 890 RFC 8639, enabling the publisher to send, e.g., the 891 "subscription-started" notification. 893 9. References 895 9.1. Normative references 897 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 898 Requirement Levels", BCP 14, RFC 2119, 899 DOI 10.17487/RFC2119, March 1997, 900 <https://www.rfc-editor.org/info/rfc2119>. 902 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 903 DOI 10.17487/RFC3688, January 2004, 904 <https://www.rfc-editor.org/info/rfc3688>. 906 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 907 Resource Identifier (URI): Generic Syntax", STD 66, 908 RFC 3986, DOI 10.17487/RFC3986, January 2005, 909 <https://www.rfc-editor.org/info/rfc3986>. 911 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 912 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 913 <https://www.rfc-editor.org/info/rfc5277>. 915 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 916 the Network Configuration Protocol (NETCONF)", RFC 6020, 917 DOI 10.17487/RFC6020, October 2010, 918 <https://www.rfc-editor.org/info/rfc6020>. 920 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 921 and A. Bierman, Ed., "Network Configuration Protocol 922 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 923 <https://www.rfc-editor.org/info/rfc6241>. 925 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 926 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 927 <https://www.rfc-editor.org/info/rfc6242>. 929 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 930 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 931 December 2014, <https://www.rfc-editor.org/info/rfc7407>. 933 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 934 RFC 7950, DOI 10.17487/RFC7950, August 2016, 935 <https://www.rfc-editor.org/info/rfc7950>. 937 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 938 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 939 <https://www.rfc-editor.org/info/rfc8040>. 941 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 942 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 943 May 2017, <https://www.rfc-editor.org/info/rfc8174>. 945 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 946 Access Control Model", STD 91, RFC 8341, 947 DOI 10.17487/RFC8341, March 2018, 948 <https://www.rfc-editor.org/info/rfc8341>. 950 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 951 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 952 <https://www.rfc-editor.org/info/rfc8446>. 954 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 955 E., and A. Tripathy, "Subscription to YANG Notifications", 956 RFC 8639, DOI 10.17487/RFC8639, September 2019, 957 <https://www.rfc-editor.org/info/rfc8639>. 959 [I-D.ietf-netconf-http-client-server] 960 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 961 Servers", Work in Progress, Internet-Draft, draft-ietf- 962 netconf-http-client-server-07, 18 May 2021, 963 <https://www.ietf.org/archive/id/draft-ietf-netconf-http- 964 client-server-07.txt>. 966 9.2. Informative references 968 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 969 Writing an IANA Considerations Section in RFCs", BCP 26, 970 RFC 8126, DOI 10.17487/RFC8126, June 2017, 971 <https://www.rfc-editor.org/info/rfc8126>. 973 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names 974 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, 975 <https://www.rfc-editor.org/info/rfc8141>. 977 Appendix A. Configuration Examples 979 This non-normative section shows two examples for how the "ietf- 980 https-notif-transport" module can be used to configure a publisher to 981 send notifications to a receiver. 983 In both examples, the Publisher, acting as an HTTPS client, is 984 configured to send notifications to a receiver at address 192.0.2.1, 985 port 443, and configures the "path" leaf value to "/some/path", with 986 server certificates, and the corresponding trust store that is used 987 to authenticate a connection. 989 A.1. Using Subscribed Notifications (RFC 8639) 991 This example shows how an RFC 8639 [RFC8639] based publisher can be 992 configured to send notifications to a receiver. 994 =============== NOTE: '\' line wrapping per RFC 8792 ================ 996 <?xml version="1.0" encoding="UTF-8"?> 997 <subscriptions 998 xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications\ 999 "> 1000 <receiver-instances 1001 xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-recei\ 1002 vers"> 1003 <receiver-instance> 1004 <name>global-receiver-def</name> 1005 <https-receiver 1006 xmlns="urn:ietf:params:xml:ns:yang:ietf-https-notif-transp\ 1007 ort" 1008 xmlns:x509c2n="urn:ietf:params:xml:ns:yang:ietf-x509-cert-\ 1009 to-name"> 1010 <tls> 1011 <tcp-client-parameters> 1012 <remote-address>receiver.example.com</remote-address> 1013 <remote-port>443</remote-port> 1014 </tcp-client-parameters> 1015 <tls-client-parameters> 1016 <server-authentication> 1017 <ca-certs> 1018 <local-definition> 1019 <certificate> 1020 <name>Server Cert Issuer #1</name> 1021 <cert-data>base64encodedvalue==</cert-data> 1022 </certificate> 1023 </local-definition> 1024 </ca-certs> 1025 </server-authentication> 1026 </tls-client-parameters> 1027 <http-client-parameters> 1028 <client-identity> 1029 <basic> 1030 <user-id>my-name</user-id> 1031 <cleartext-password>my-password</cleartext-password> 1032 </basic> 1033 </client-identity> 1034 <path>/some/path</path> 1035 </http-client-parameters> 1036 </tls> 1037 <receiver-identity> 1038 <cert-maps> 1039 <cert-to-name> 1040 <id>1</id> 1041 <fingerprint>11:0A:05:11:00</fingerprint> 1042 <map-type>x509c2n:san-any</map-type> 1043 </cert-to-name> 1044 </cert-maps> 1045 </receiver-identity> 1046 </https-receiver> 1047 </receiver-instance> 1048 </receiver-instances> 1049 <subscription> 1050 <id>6666</id> 1051 <transport xmlns:ph="urn:ietf:params:xml:ns:yang:ietf-https-noti\ 1052 f-transport">ph:https</transport> 1053 <stream-subtree-filter>some-subtree-filter</stream-subtree-filte\ 1054 r> 1055 <stream>some-stream</stream> 1056 <receivers> 1057 <receiver> 1058 <name>subscription-specific-receiver-def</name> 1059 <receiver-instance-ref xmlns="urn:ietf:params:xml:ns:yang:ie\ 1060 tf-subscribed-notif-receivers">global-receiver-def</receiver-instanc\ 1061 e-ref> 1062 </receiver> 1063 </receivers> 1064 </subscription> 1065 </subscriptions> 1066 <truststore xmlns="urn:ietf:params:xml:ns:yang:ietf-truststore"> 1067 <certificate-bags> 1068 <certificate-bag> 1069 <name>explicitly-trusted-server-ca-certs</name> 1070 <description> 1071 Trust anchors (i.e. CA certs) that are used to 1072 authenticate connections to receivers. Receivers 1073 are authenticated if their certificate has a chain 1074 of trust to one of these CA certificates. 1075 certificates. 1076 </description> 1077 <certificate> 1078 <name>ca.example.com</name> 1079 <cert-data>base64encodedvalue==</cert-data> 1080 </certificate> 1081 <certificate> 1082 <name>Fred Flintstone</name> 1083 <cert-data>base64encodedvalue==</cert-data> 1084 </certificate> 1085 </certificate-bag> 1086 </certificate-bags> 1087 </truststore> 1089 A.2. Not Using Subscribed Notifications 1091 In the case that it is desired to use HTTPS-based notifications 1092 outside of Subscribed Notifications, an application-specific module 1093 would to need define the configuration for sending the notification. 1095 Following is an example module. Note that the module is "uses" the 1096 "https-receiver-grouping" grouping from the "ietf-https-notif- 1097 transport" module. 1099 module example-custom-module { 1100 yang-version 1.1; 1101 namespace "http://example.com/example-custom-module"; 1102 prefix "custom"; 1104 import ietf-https-notif-transport { 1105 prefix "hnt"; 1106 reference 1107 "RFC XXXX: 1108 An HTTPS-based Transport for Configured Subscriptions"; 1109 } 1111 organization 1112 "Example, Inc."; 1114 contact 1115 "Support at example.com"; 1117 description 1118 "Example of module not using Subscribed Notifications module."; 1120 revision "2021-10-24" { 1121 description 1122 "Initial Version."; 1123 reference 1124 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 1125 } 1127 container example-module { 1128 description 1129 "Example of using HTTPS notif without having to 1130 implement Subscribed Notifications."; 1132 container https-receivers { 1133 description 1134 "A container of all HTTPS notif receivers."; 1135 list https-receiver { 1136 key "name"; 1137 description 1138 "A list of HTTPS nofif receivers."; 1139 leaf name { 1140 type string; 1141 description 1142 "A unique name for the https notif receiver."; 1143 } 1144 uses hnt:https-receiver-grouping; 1145 } 1146 } 1147 } 1148 } 1150 Following is what the corresponding configuration looks like: 1152 <?xml version="1.0" encoding="UTF-8"?> 1153 <example-module xmlns="http://example.com/example-custom-module"> 1154 <https-receivers> 1155 <https-receiver> 1156 <name>foo</name> 1157 <tls> 1158 <tcp-client-parameters> 1159 <remote-address>receiver.example.com</remote-address> 1160 <remote-port>443</remote-port> 1161 </tcp-client-parameters> 1162 <tls-client-parameters> 1163 <server-authentication> 1164 <ca-certs> 1165 <local-definition> 1166 <certificate> 1167 <name>Server Cert Issuer #1</name> 1168 <cert-data>base64encodedvalue==</cert-data> 1169 </certificate> 1170 </local-definition> 1171 </ca-certs> 1172 </server-authentication> 1173 </tls-client-parameters> 1174 <http-client-parameters> 1175 <client-identity> 1176 <basic> 1177 <user-id>my-name</user-id> 1178 <cleartext-password>my-password</cleartext-password> 1179 </basic> 1180 </client-identity> 1181 <path>/some/path</path> 1182 </http-client-parameters> 1183 </tls> 1184 </https-receiver> 1185 </https-receivers> 1186 </example-module> 1188 Acknowledgements 1190 The authors would like to thank for following for lively discussions 1191 on list and in the halls (ordered by first name): Eric Voit, Henning 1192 Rogge, Martin Bjorklund, Reshad Rahman, and Rob Wilton. 1194 Authors' Addresses 1196 Mahesh Jethanandani 1197 Kloud Services 1199 Email: mjethanandani@gmail.com 1200 Kent Watsen 1201 Watsen Networks 1203 Email: kent+ietf@watsen.net