idnits 2.17.1 draft-ietf-netconf-https-notif-08.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 9 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 393 has weird spacing: '...rw name str...' == Line 546 has weird spacing: '...address ine...' == Line 564 has weird spacing: '...address ine...' == Line 594 has weird spacing: '...erprint x50...' -- The document date (February 22, 2021) is 1152 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 (~~), 6 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: August 26, 2021 Watsen Networks 6 February 22, 2021 8 An HTTPS-based Transport for YANG Notifications 9 draft-ietf-netconf-https-notif-08 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 August 26, 2021. 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 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Applicability Statement . . . . . . . . . . . . . . . . . 3 58 1.2. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 59 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 4 60 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 61 1.4.1. Subscribed Notifications . . . . . . . . . . . . . . 4 62 2. Overview of Publisher to Receiver Interaction . . . . . . . . 4 63 3. Discovering a Receiver's Capabilities . . . . . . . . . . . . 5 64 3.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 65 3.2. Request . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4. Sending Event Notifications . . . . . . . . . . . . . . . . . 7 69 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 7 70 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 71 4.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 5. The "ietf-subscribed-notif-receivers" Module . . . . . . . . 9 73 5.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 9 74 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 75 6. The "ietf-https-notif-transport" Module . . . . . . . . . . . 12 76 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 12 77 6.2. YANG module . . . . . . . . . . . . . . . . . . . . . . . 14 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 80 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 18 81 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 18 82 8.3. The "Capabilities for HTTPS Notification Receivers" 83 Registry . . . . . . . . . . . . . . . . . . . . . . . . 18 84 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 85 9.1. Normative references . . . . . . . . . . . . . . . . . . 20 86 9.2. Informative references . . . . . . . . . . . . . . . . . 21 87 Appendix A. Configuration Examples . . . . . . . . . . . . . . . 22 88 A.1. Using Subscribed Notifications (RFC 8639) . . . . . . . . 22 89 A.2. Not Using Subscribed Notifications . . . . . . . . . . . 24 90 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 27 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 93 1. Introduction 95 This document defines a protocol for sending notifications over 96 HTTPS. Using HTTPS maximizes transport-level interoperability, while 97 allowing for a variety of encoding options. This document defines 98 support for JSON and XML; future efforts may define support for other 99 encodings (e.g., binary). 101 This document also defines two YANG 1.1 [RFC7950] modules that extend 102 the data model defined in Subscription to YANG Notifications 103 [RFC8639], enabling the configuration of HTTPS-based receivers. 105 An example module illustrating the configuration of a publisher not 106 using the data model defined in RFC 8639 is also provided. 108 Configured subscriptions enable a server, acting as a publisher of 109 notifications, to proactively push notifications to external 110 receivers without the receivers needing to first connect to the 111 server, as is the case with dynamic subscriptions. 113 1.1. Applicability Statement 115 While the YANG modules have been defined as an augmentation of 116 Subscription to YANG Notifications [RFC8639], the notification method 117 defined in this document MAY be used outside of Subscription to YANG 118 Notifications [RFC8639] by using some of the definitions from this 119 module along with the grouping defined in Groupings for HTTP Clients 120 and Servers [I-D.ietf-netconf-http-client-server]. For an example on 121 how that can be done, see Section A.2. 123 1.2. Note to RFC Editor 125 This document uses several placeholder values throughout the 126 document. Please replace them as follows and remove this section 127 before publication. 129 RFC XXXX, where XXXX is the number assigned to this document at the 130 time of publication. 132 RFC YYYY, where YYYY is the number assigned to 133 [I-D.ietf-netconf-http-client-server]. 135 2021-02-22 with the actual date of the publication of this document. 137 1.3. Abbreviations 139 +---------+--------------------------------------+ 140 | Acronym | Expansion | 141 +---------+--------------------------------------+ 142 | HTTP | Hyper Text Transport Protocol | 143 | | | 144 | HTTPS | Hyper Text Transport Protocol Secure | 145 | | | 146 | TCP | Transmission Control Protocol | 147 | | | 148 | TLS | Transport Layer Security | 149 +---------+--------------------------------------+ 151 1.4. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in BCP 156 14 [RFC2119] [RFC8174] when, and only when, they appear in all 157 capitals, as shown here. 159 1.4.1. Subscribed Notifications 161 The following terms are defined in Subscription to YANG Notifications 162 [RFC8639]. 164 o Subscribed Notifications 166 2. Overview of Publisher to Receiver Interaction 168 The protocol consists of two HTTP-based target resources presented by 169 the receiver. These two resources are sub-paths of a common resource 170 that the publisher must know (e.g. specified in its configuration 171 data model). 173 o A target resource enabling the publisher to discover what optional 174 capabilities a receiver supports. Publishers SHOULD query this 175 target before sending any notifications or if ever an error 176 occurs. 178 o A target resource enabling the publisher to send one or more 179 notification to a receiver. This document defines support for 180 sending only one notification per message; a future effort MAY 181 extend the protocol to send multiple notifications per message. 183 The protocol is illustrated in the diagram below: 185 ------------- -------------- 186 | Publisher | | Receiver | 187 ------------- -------------- 189 Send HTTPS GET message ------> 190 to discover receiver's 191 capabilities 193 <------ Send 200 (OK) containing 194 capabilities supported 195 by the receiver 197 +-- For Each Notification (MAY be pipelined) ---------------------+ 198 | | 199 | Send HTTPS POST message ------> | 200 | with YANG defined | 201 | notification | 202 | | 203 | <------ Send 204 (No Content) | 204 +-----------------------------------------------------------------+ 206 Note that, for RFC 8639 configured subscriptions, the very first 207 notification must be the "subscription-started" notification. 209 The POST messages MAY be "pipelined" (not illustrated in the diagram 210 above), whereby multiple notifications are sent without waiting for 211 the HTTP response for a previous POST. 213 3. Discovering a Receiver's Capabilities 215 3.1. Applicability 217 For publishers using Subscription to YANG Notifications [RFC8639], 218 dynamic discovery of a receiver's supported encoding is necessary 219 only when the "/subscriptions/subscription/encoding" leaf is not 220 configured, per the "encoding" leaf's description statement in the 221 "ietf-subscribed-notification" module. 223 3.2. Request 225 To learn the capabilities of a receiver, a publisher can issue an 226 HTTPS GET request to the "capabilities" resource under a known path 227 on the receiver with "Accept" header set using the "application/xml" 228 and/or "application/json" media-types, with the latter as mandatory 229 to implement, and the default in case the type is not specified. 231 3.3. Response 233 The receiver responds with a "200 (OK)" message, having the "Content- 234 Type" header set to either "application/xml" or "application/json" 235 (which ever was selected), and containing in the response body a list 236 of the receiver's capabilities encoded in the selected format. 238 Even though a YANG module is not defined for this interaction, the 239 response body MUST conform to the following YANG-modeled format: 241 container receiver-capabilities { 242 description 243 "A container for a list of capabilities supported by 244 the receiver."; 245 leaf-list receiver-capability { 246 type "inet:uri"; 247 description 248 "A capability supported by the receiver. A full list of 249 capabilities is defined in the 'Capabilities for HTTPS 250 Notification Receivers' registry (see RFC XXXX)."; 251 } 252 } 254 As it is possible that the receiver may return custom capability 255 URIs, the publisher MUST ignore any capabilities that it does not 256 recognize. 258 3.4. Example 260 The publisher can send the following request to learn the receiver 261 capabilities. In this example, the "Accept" states that the receiver 262 wants to receive the capabilities response in XML but, if not 263 supported, then in JSON. 265 GET /some/path/capabilities HTTP/1.1 266 Host: example.com 267 Accept: application/xml, application/json 269 If the receiver is able to reply using "application/xml", and 270 assuming it is able to receive JSON and XML encoded notifications, 271 and it is able to process the RFC 8639 state machine, the response 272 might look like this: 274 HTTP/1.1 200 OK 275 Date: Wed, 26 Feb 2020 20:33:30 GMT 276 Server: example-server 277 Cache-Control: no-cache 278 Content-Type: application/xml 279 Content-Length: nnn 281 282 \ 283 urn:ietf:capability:https-notif-receiver:encoding:json\ 284 285 \ 286 urn:ietf:capability:https-notif-receiver:encoding:xml\ 287 288 \ 289 urn:ietf:capability:https-notif-receiver:encoding:rfc8639-enabled\ 290 291 293 If the receiver is unable to reply using "application/xml", the 294 response might look like this: 296 HTTP/1.1 200 OK 297 Date: Wed, 26 Feb 2020 20:33:30 GMT 298 Server: example-server 299 Cache-Control: no-cache 300 Content-Type: application/json 301 Content-Length: nnn 303 { 304 receiver-capabilities { 305 "receiver-capability": [ 306 "urn:ietf:capability:https-notif-receiver:encoding:json", 307 "urn:ietf:capability:https-notif-receiver:encoding:xml", 308 "urn:ietf:capability:https-notif-receiver:encoding:rfc8639-enabled" 309 ] 310 } 311 } 313 4. Sending Event Notifications 315 4.1. Request 317 The publisher sends an HTTPS POST request to the "relay-notification" 318 resource under a known path on the receiver with the "Content-Type" 319 header set to either "application/json" or "application/xml" and a 320 body containing the notification encoded using the specified format. 322 XML-encoded notifications are encoded using the format defined by 323 NETCONF Event Notifications [RFC5277] for XML. 325 JSON-encoded notifications are encoded the same as specified in 326 Section 6.4 in RESTCONF [RFC8040] with the following deviations: 328 o The notifications do not contain the "data:" prefix used by SSE. 330 o Instead of saying that, for JSON-encoding purposes, the module 331 name for the "notification" element is "ietf-restconf, the module 332 name will instead be "ietf-https-notif". 334 4.2. Response 336 The response should be "204 (No Content)". 338 4.3. Example 340 An XML-encoded notification might be sent as follows: 342 POST /some/path/relay-notification HTTP/1.1 343 Host: example.com 344 Content-Type: application/xml 346 347 2019-03-22T12:35:00Z 348 349 fault 350 351 Ethernet0 352 353 major 354 355 357 A JSON-encoded notification might be sent as follows: 359 POST /some/path/relay-notification HTTP/1.1 360 Host: example.com 361 Content-Type: application/json 363 { 364 "ietf-https-notif:notification": { 365 "eventTime": "2013-12-21T00:01:00Z", 366 "example-mod:event" : { 367 "event-class" : "fault", 368 "reporting-entity" : { "card" : "Ethernet0" }, 369 "severity" : "major" 370 } 371 } 372 } 374 And, in either case, the response might be as follows: 376 HTTP/1.1 204 No Content 377 Date: Wed, 26 Feb 2020 20:33:30 GMT 378 Server: example-server 380 5. The "ietf-subscribed-notif-receivers" Module 382 5.1. Data Model Overview 384 This YANG module augments the "ietf-subscribed-notifications" module 385 to define a choice of transport types that other modules such as the 386 "ietf-https-notif-transport" module can use to define a transport 387 specific receiver. 389 module: ietf-subscribed-notif-receivers 390 augment /sn:subscriptions: 391 +--rw receiver-instances 392 +--rw receiver-instance* [name] 393 +--rw name string 394 +--rw (transport-type) 395 augment /sn:subscriptions/sn:subscription/sn:receivers/sn:receiver: 396 +--rw receiver-instance-ref? leafref 398 5.2. YANG Module 400 The YANG module imports Subscription to YANG Notifications [RFC8639]. 402 file "ietf-subscribed-notif-receivers@2021-02-22.yang" 403 module ietf-subscribed-notif-receivers { 404 yang-version 1.1; 405 namespace 406 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers"; 407 prefix "snr"; 409 import ietf-subscribed-notifications { 410 prefix sn; 411 reference 412 "RFC 8639: Subscription to YANG Notifications"; 413 } 415 organization 416 "IETF NETCONF Working Group"; 418 contact 419 "WG Web: 420 WG List: 422 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 423 Kent Watsen (kent plus ietf at watsen dot net)"; 425 description 426 "This YANG module is implemented by Publishers implementing 427 the 'ietf-subscribed-notifications' module defined in RFC 8639. 429 While this module is defined in RFC XXXX, which primarily 430 defines an HTTPS-based transport for notifications, this module 431 is not HTTP-specific. It is a generic extension that can be 432 used by any 'notif' transport. 434 This module defines two 'augment' statements. One statement 435 augments a 'container' statement called 'receiver-instances' 436 into the top-level 'subscriptions' container. The other 437 statement, called 'receiver-instance-ref', augemnts a 'leaf' 438 statement into each 'receiver' that references one of the 439 afore mentioned receiver instances. This indirection enables 440 multiple configured subscriptions to send notifications to 441 the same receiver instance. 443 Copyright (c) 2021 IETF Trust and the persons identified as 444 the document authors. All rights reserved. 445 Redistribution and use in source and binary forms, with or 446 without modification, is permitted pursuant to, and subject 447 to the license terms contained in, the Simplified BSD 448 License set forth in Section 4.c of the IETF Trust's Legal 449 Provisions Relating to IETF Documents 450 (http://trustee.ietf.org/license-info). 452 This version of this YANG module is part of RFC XXXX; see 453 the RFC itself for full legal notices. 455 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 456 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 457 'MAY', and 'OPTIONAL' in this document are to be interpreted as 458 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 459 they appear in all capitals, as shown here."; 461 revision "2021-02-22" { 462 description 463 "Initial Version."; 464 reference 465 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 466 } 468 augment "/sn:subscriptions" { 469 container receiver-instances { 470 description 471 "A container for all instances of receivers."; 473 list receiver-instance { 474 key "name"; 476 leaf name { 477 type string; 478 description 479 "An arbitrary but unique name for this receiver 480 instance."; 481 } 483 choice transport-type { 484 mandatory true; 485 description 486 "Choice of different types of transports used to 487 send notifications. The 'case' statements must 488 be augmented in by other modules."; 489 } 490 description 491 "A list of all receiver instances."; 492 } 493 } 494 description 495 "Augment the subscriptions container to define the 496 transport type."; 497 } 499 augment 500 "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { 501 leaf receiver-instance-ref { 502 type leafref { 503 path "/sn:subscriptions/snr:receiver-instances/" + 504 "snr:receiver-instance/snr:name"; 505 } 506 description 507 "Reference to a receiver instance."; 508 } 509 description 510 "Augment the subscriptions container to define an optional 511 reference to a receiver instance."; 512 } 513 } 514 516 6. The "ietf-https-notif-transport" Module 518 6.1. Data Model Overview 520 This YANG module is a definition of a set of receivers that are 521 interested in the notifications published by the publisher. The 522 module contains the TCP, TLS and HTTPS parameters that are needed to 523 communicate with the receiver. The module augments the "ietf- 524 subscribed-notif-receivers" module to define a transport specific 525 receiver. 527 As mentioned earlier, it uses a POST method to deliver the 528 notification. The "http-receiver/tls/http-client-parameters/path" 529 leaf defines the path for the resource on the receiver, as defined by 530 "path-absolute" in URI Generic Syntax [RFC3986]. The user-id used by 531 Network Configuration Access Control Model [RFC8341], is that of the 532 receiver and is derived from the certificate presented by the 533 receiver as part of "receiver-identity". 535 An abridged tree diagram representing the module is shown below. 537 module: ietf-https-notif-transport 538 augment /sn:subscriptions/snr:receiver-instances 539 /snr:receiver-instance/snr:transport-type: 540 +--:(https) 541 +--rw https-receiver 542 +--rw (transport) 543 | +--:(tcp) {tcp-supported,not httpc:tcp-supported}? 544 | | +--rw tcp 545 | | +--rw tcp-client-parameters 546 | | | +--rw remote-address inet:host 547 | | | +--rw remote-port? inet:port-number 548 | | | +--rw local-address? inet:ip-address 549 | | | | {local-binding-supported}? 550 | | | +--rw local-port? inet:port-number 551 | | | | {local-binding-supported}? 552 | | | +--rw proxy-server! {proxy-connect}? 553 | | | | ... 554 | | | +--rw keepalives! 555 | | | ... 556 | | +--rw http-client-parameters 557 | | +--rw client-identity! 558 | | | ... 559 | | +--rw proxy-connect! {proxy-connect}? 560 | | ... 561 | +--:(tls) {tls-supported}? 562 | +--rw tls 563 | +--rw tcp-client-parameters 564 | | +--rw remote-address inet:host 565 | | +--rw remote-port? inet:port-number 566 | | +--rw local-address? inet:ip-address 567 | | | {local-binding-supported}? 568 | | +--rw local-port? inet:port-number 569 | | | {local-binding-supported}? 570 | | +--rw proxy-server! {proxy-connect}? 571 | | | ... 572 | | +--rw keepalives! 573 | | ... 574 | +--rw tls-client-parameters 575 | | +--rw client-identity! 576 | | | ... 577 | | +--rw server-authentication 578 | | | ... 579 | | +--rw hello-params 580 | | | {tls-client-hello-params-config}? 581 | | | ... 582 | | +--rw keepalives {tls-client-keepalives}? 583 | | ... 584 | +--rw http-client-parameters 585 | +--rw client-identity! 586 | | ... 587 | +--rw proxy-connect! {proxy-connect}? 588 | | ... 589 | +--rw path string 590 +--rw receiver-identity {receiver-identity}? 591 +--rw cert-maps 592 +--rw cert-to-name* [id] 593 +--rw id uint32 594 +--rw fingerprint x509c2n:tls-fingerprint 595 +--rw map-type identityref 596 +--rw name string 598 6.2. YANG module 600 The YANG module imports A YANG Data Model for SNMP Configuration 601 [RFC7407], Subscription to YANG Notifications [RFC8639], and YANG 602 Groupings for HTTP Clients and HTTP Servers 603 [I-D.ietf-netconf-http-client-server]. 605 The YANG module is shown below. 607 file "ietf-https-notif-transport@2021-02-22.yang" 608 module ietf-https-notif-transport { 609 yang-version 1.1; 610 namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif-transport"; 611 prefix "hnt"; 613 import ietf-x509-cert-to-name { 614 prefix x509c2n; 615 reference 616 "RFC 7407: YANG Data Model for SNMP Configuration."; 617 } 619 import ietf-subscribed-notifications { 620 prefix sn; 621 reference 622 "RFC 8639: Subscription to YANG Notifications"; 623 } 625 import ietf-subscribed-notif-receivers { 626 prefix snr; 627 reference 628 "RFC XXXX: An HTTPS-based Transport for 629 Configured Subscriptions"; 630 } 632 import ietf-http-client { 633 prefix httpc; 634 reference 635 "RFC YYYY: YANG Groupings for HTTP Clients and HTTP Servers"; 636 } 638 organization 639 "IETF NETCONF Working Group"; 641 contact 642 "WG Web: 643 WG List: 645 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 646 Kent Watsen (kent plus ietf at watsen dot net)"; 648 description 649 "This YANG module is implemented by Publishers that implement 650 the 'ietf-subscribed-notifications' module defined in RFC 8639. 652 This module augments a 'case' statement called 'https' into 653 the 'choice' statement called 'transport-type' defined 654 by the 'ietf-https-notif-transport' module defined in RFC XXXX. 656 Copyright (c) 2021 IETF Trust and the persons identified as 657 the document authors. All rights reserved. 658 Redistribution and use in source and binary forms, with or 659 without modification, is permitted pursuant to, and subject 660 to the license terms contained in, the Simplified BSD 661 License set forth in Section 4.c of the IETF Trust's Legal 662 Provisions Relating to IETF Documents 663 (http://trustee.ietf.org/license-info). 665 This version of this YANG module is part of RFC XXXX; see 666 the RFC itself for full legal notices. 668 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 669 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 670 'MAY', and 'OPTIONAL' in this document are to be interpreted as 671 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 672 they appear in all capitals, as shown here."; 674 revision "2021-02-22" { 675 description 676 "Initial Version."; 677 reference 678 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 679 } 681 feature receiver-identity { 682 description 683 "Indicates that the server supports filtering notifications 684 based on the receiver's identity derived from its TLS 685 certificate."; 686 } 688 identity https { 689 base sn:transport; 690 description 691 "HTTPS transport for notifications."; 692 } 693 grouping https-receiver-grouping { 694 description 695 "A grouping that may be used by other modules wishing to 696 configure HTTPS-based notifications without using RFC 8639."; 697 uses httpc:http-client-stack-grouping { 698 refine "transport/tcp" { 699 // create the logical impossibility of enabling the 700 // "tcp" transport (i.e., "HTTP" without the 'S'). 701 if-feature "not httpc:tcp-supported"; 702 } 703 augment "transport/tls/tls/http-client-parameters" { 704 leaf path { 705 type string; 706 mandatory true; 707 description 708 "URI prefix to the target resources. Under this 709 path the receiver must support both the 'capabilities' 710 and 'relay-notification' resource targets, as described 711 in RFC XXXX."; 712 } 713 description 714 "Augmentation to add a receiver-specific path for the 715 'capabilities' and 'relay-notification' resources."; 716 } 717 } 718 container receiver-identity { 719 if-feature receiver-identity; 720 description 721 "Maps the receiver's TLS certificate to a local identity 722 enabling access control to be applied to filter out 723 notifications that the receiver may not be authorized 724 to view."; 725 container cert-maps { 726 uses x509c2n:cert-to-name; 727 description 728 "The cert-maps container is used by a TLS-based HTTP 729 server to map the HTTPS client's presented X.509 730 certificate to a 'local' username. If no matching and 731 valid cert-to-name list entry is found, the publisher 732 MUST close the connection, and MUST NOT not send any 733 notifications over it."; 734 reference 735 "RFC 7407: A YANG Data Model for SNMP Configuration."; 736 } 737 } 738 } 740 augment "/sn:subscriptions/snr:receiver-instances/" + 741 "snr:receiver-instance/snr:transport-type" { 742 case https { 743 container https-receiver { 744 description 745 "The HTTPS receiver to send notifications to."; 746 uses https-receiver-grouping; 747 } 748 } 749 description 750 "Augment the transport-type choice to include the 'https' 751 transport."; 752 } 753 } 754 756 7. Security Considerations 758 The YANG module specified in this document defines a schema for data 759 that is designed to be accessed via network management protocols such 760 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 761 is the secure transport layer, and the mandatory-to-implement secure 762 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 763 is HTTPS, and the mandatory-to-implement secure transport is TLS 764 [RFC8446]. The NETCONF Access Control Model (NACM) [RFC8341] 765 provides the means to restrict access for particular NETCONF or 766 RESTCONF users to a preconfigured subset of all available NETCONF or 767 RESTCONF protocol operations and content. 769 The YANG module in this document makes use of grouping that are 770 defined in YANG Groupings for HTTP Clients and HTTP Servers 771 [I-D.ietf-netconf-http-client-server], and A YANG Data Model for SNMP 772 Configuration [RFC7407]. Please see the Security Considerations 773 section of those documents for considerations related to sensitivity 774 and vulnerability of the data nodes defined in them. 776 There are a number of data nodes defined in this YANG module that are 777 writable/creatable/deletable (i.e., config true, which is the 778 default). These data nodes may be considered sensitive or vulnerable 779 in some network environments. Write operations (e.g., edit-config) 780 to these data nodes without proper protection can have a negative 781 effect on network operations. These are the subtrees and data nodes 782 and their sensitivity/vulnerability: 784 o The "path" node in "ietf-subscribed-notif-receivers" module can be 785 modified by a malicious user to point to an invalid URI. 787 Some of the readable data nodes in YANG module may be considered 788 sensitive or vulnerable in some network environments. It is thus 789 important to control read access (e.g., via get, get-config, or 790 notification) to these data nodes. The model does not define any 791 readable subtrees and data nodes. 793 Some of the RPC operations in YANG module may be considered sensitive 794 or vulnerable in some network environments. It is thus important to 795 control access to these operations. The model does not define any 796 RPC operations. 798 8. IANA Considerations 800 8.1. The "IETF XML" Registry 802 This document registers two URIs in the "ns" subregistry of the "IETF 803 XML" registry [RFC3688]. Following the format in [RFC3688], the 804 following registrations are requested: 806 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 807 Registrant Contact: The IESG 808 XML: N/A, the requested URI is an XML namespace. 810 URI: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 811 Registrant Contact: The IESG 812 XML: N/A, the requested URI is an XML namespace. 814 8.2. The "YANG Module Names" Registry 816 This document registers two YANG modules in the "YANG Module Names" 817 registry [RFC6020]. Following the format in [RFC6020], the following 818 registrations are requested: 820 name: ietf-subscribed-notif-receivers 821 namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 822 prefix: snr 823 reference: RFC XXXX 825 name: ietf-https-notif-transport 826 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 827 prefix: hnt 828 reference: RFC XXXX 830 8.3. The "Capabilities for HTTPS Notification Receivers" Registry 832 Following the guidelines defined in [RFC8126], this document defines 833 a new registry called "Capabilities for HTTPS Notification 834 Receivers". This registry defines capabilities that can be supported 835 by HTTPS-based notification receivers. 837 The following note shall be at the top of the registry: 839 This registry defines capabilities that can be 840 supported by HTTPS-based notification receivers. 842 The fields for each registry are: 844 o URN 846 * The name of the URN (required). 848 * The URN must conform to the syntax described by [RFC8141]. 850 * The URN must begin with the string "urn:ietf:capability:https- 851 notif-receiver". 853 o Reference 855 * The RFC that defined the URN. 857 * The RFC must be in the form "RFC : . 859 o Description 861 * An arbitrary description of the algorithm (optional). 863 * The description should be no more than a few sentences. 865 * The description is to be in English, but may contain UTF-8 866 characters as may be needed in some cases. 868 The update policy is either "RFC Required". Updates do not otherwise 869 require an expert review by a Designated Expert. 871 Following is the initial assignment for this registry: 873 Record: 874 Name: urn:ietf:capability:https-notif-receiver:encoding:json 875 Reference: RFC XXXX 876 Description: Identifies support for JSON-encoded notifications. 878 Record: 879 Name: urn:ietf:capability:https-notif-receiver:encoding:xml 880 Reference: RFC XXXX 881 Description: Identifies support for XML-encoded notifications. 883 Record: 884 Name: urn:ietf:capability:https-notif-receiver:encoding:rfc8639-enabled 885 Reference: RFC XXXX 886 Description: Identifies support for RFC 8639 state machine. 888 9. References 890 9.1. Normative references 892 [I-D.ietf-netconf-http-client-server] 893 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 894 Servers", draft-ietf-netconf-http-client-server-05 (work 895 in progress), August 2020. 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 9.2. Informative references 961 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 962 Writing an IANA Considerations Section in RFCs", BCP 26, 963 RFC 8126, DOI 10.17487/RFC8126, June 2017, 964 <https://www.rfc-editor.org/info/rfc8126>. 966 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names 967 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, 968 <https://www.rfc-editor.org/info/rfc8141>. 970 Appendix A. Configuration Examples 972 This non-normative section shows two examples for how the "ietf- 973 https-notif-transport" module can be used to configure a publisher to 974 send notifications to a receiver. 976 In both examples, the Publisher, acting as an HTTPS client, is 977 configured to send notifications to a receiver at address 192.0.2.1, 978 port 443, and configures the "path" leaf value to "/some/path", with 979 server certificates, and the corresponding trust store that is used 980 to authenticate a connection. 982 A.1. Using Subscribed Notifications (RFC 8639) 984 This example shows how an RFC 8639 [RFC8639] based publisher can be 985 configured to send notifications to a receiver. 987 =============== NOTE: '\' line wrapping per RFC 8792 ================ 989 <?xml version="1.0" encoding="UTF-8"?> 990 <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 991 <subscriptions 992 xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notificatio\ 993 ns"> 994 <receiver-instances 995 xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-rec\ 996 eivers"> 997 <receiver-instance> 998 <name>global-receiver-def</name> 999 <https-receiver 1000 xmlns="urn:ietf:params:xml:ns:yang:ietf-https-notif-tran\ 1001 sport" 1002 xmlns:x509c2n="urn:ietf:params:xml:ns:yang:ietf-x509-cert-\ 1003 to-name"> 1004 <tls> 1005 <tcp-client-parameters> 1006 <remote-address>receiver.example.com</remote-address> 1007 <remote-port>443</remote-port> 1008 </tcp-client-parameters> 1009 <tls-client-parameters> 1010 <server-authentication> 1011 <ca-certs> 1012 <local-definition> 1013 <certificate> 1014 <name>Server Cert Issuer #1</name> 1015 <cert-data>base64encodedvalue==</cert-data> 1016 </certificate> 1017 </local-definition> 1018 </ca-certs> 1019 </server-authentication> 1020 </tls-client-parameters> 1021 <http-client-parameters> 1022 <client-identity> 1023 <basic> 1024 <user-id>my-name</user-id> 1025 <cleartext-password>my-password</cleartext-passwor\ 1026 d> 1027 </basic> 1028 </client-identity> 1029 <path>/some/path</path> 1030 </http-client-parameters> 1031 </tls> 1032 <receiver-identity> 1033 <cert-maps> 1034 <cert-to-name> 1035 <id>1</id> 1036 <fingerprint>11:0A:05:11:00</fingerprint> 1037 <map-type>x509c2n:san-any</map-type> 1038 </cert-to-name> 1039 </cert-maps> 1040 </receiver-identity> 1041 </https-receiver> 1042 </receiver-instance> 1043 </receiver-instances> 1044 <subscription> 1045 <id>6666</id> 1046 <transport xmlns:ph="urn:ietf:params:xml:ns:yang:ietf-https-no\ 1047 tif-transport">ph:https</transport> 1048 <stream-subtree-filter>some-subtree-filter</stream-subtree-fil\ 1049 ter> 1050 <stream>some-stream</stream> 1051 <receivers> 1052 <receiver> 1053 <name>subscription-specific-receiver-def</name> 1054 <receiver-instance-ref xmlns="urn:ietf:params:xml:ns:yang:\ 1055 ietf-subscribed-notif-receivers">global-receiver-def</receiver-insta\ 1056 nce-ref> 1057 </receiver> 1058 </receivers> 1059 </subscription> 1060 </subscriptions> 1061 <truststore xmlns="urn:ietf:params:xml:ns:yang:ietf-truststore"> 1062 <certificate-bags> 1063 <certificate-bag> 1064 <name>explicitly-trusted-server-ca-certs</name> 1065 <description> 1066 Trust anchors (i.e. CA certs) that are used to 1067 authenticate connections to receivers. Receivers 1068 are authenticated if their certificate has a chain 1069 of trust to one of these CA certificates. 1070 certificates. 1071 </description> 1072 <certificate> 1073 <name>ca.example.com</name> 1074 <cert-data>base64encodedvalue==</cert-data> 1075 </certificate> 1076 <certificate> 1077 <name>Fred Flintstone</name> 1078 <cert-data>base64encodedvalue==</cert-data> 1079 </certificate> 1080 </certificate-bag> 1081 </certificate-bags> 1082 </truststore> 1083 </config> 1085 A.2. Not Using Subscribed Notifications 1087 In the case that it is desired to use HTTPS-based notifications 1088 outside of Subscribed Notifications, an application-specific module 1089 would to need define the configuration for sending the notification. 1091 Following is an example module. Note that the module is "uses" the 1092 "https-receiver-grouping" grouping from the "ietf-https-notif- 1093 transport" module. 1095 module example-custom-module { 1096 yang-version 1.1; 1097 namespace "http://example.com/example-custom-module"; 1098 prefix "custom"; 1100 import ietf-https-notif-transport { 1101 prefix "hnt"; 1102 reference 1103 "RFC XXXX: 1104 An HTTPS-based Transport for Configured Subscriptions"; 1105 } 1107 organization 1108 "Example, Inc."; 1110 contact 1111 "Support at example.com"; 1113 description 1114 "Example of module not using Subscribed Notifications module."; 1116 revision "2021-02-22" { 1117 description 1118 "Initial Version."; 1119 reference 1120 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 1121 } 1123 container example-module { 1124 description 1125 "Example of using HTTPS notif without having to 1126 implement Subscribed Notifications."; 1128 container https-receivers { 1129 description 1130 "A container of all HTTPS notif receivers."; 1131 list https-receiver { 1132 key "name"; 1133 description 1134 "A list of HTTPS nofif receivers."; 1135 leaf name { 1136 type string; 1137 description 1138 "A unique name for the https notif receiver."; 1139 } 1140 uses hnt:https-receiver-grouping; 1141 } 1142 } 1143 } 1144 } 1146 Following is what the corresponding configuration looks like: 1148 <?xml version="1.0" encoding="UTF-8"?> 1149 <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 1150 <example-module xmlns="http://example.com/example-custom-module"> 1151 <https-receivers> 1152 <https-receiver> 1153 <name>foo</name> 1154 <tls> 1155 <tcp-client-parameters> 1156 <remote-address>receiver.example.com</remote-address> 1157 <remote-port>443</remote-port> 1159 </tcp-client-parameters> 1160 <tls-client-parameters> 1161 <server-authentication> 1162 <ca-certs> 1163 <local-definition> 1164 <certificate> 1165 <name>Server Cert Issuer #1</name> 1166 <cert-data>base64encodedvalue==</cert-data> 1167 </certificate> 1168 </local-definition> 1169 </ca-certs> 1170 </server-authentication> 1171 </tls-client-parameters> 1172 <http-client-parameters> 1173 <client-identity> 1174 <basic> 1175 <user-id>my-name</user-id> 1176 <cleartext-password>my-password</cleartext-password> 1177 </basic> 1178 </client-identity> 1179 <path>/some/path</path> 1180 </http-client-parameters> 1181 </tls> 1182 </https-receiver> 1183 </https-receivers> 1184 </example-module> 1185 <truststore xmlns="urn:ietf:params:xml:ns:yang:ietf-truststore"> 1186 <certificate-bags> 1187 <certificate-bag> 1188 <name>explicitly-trusted-server-ca-certs</name> 1189 <description> 1190 Trust anchors (i.e. CA certs) that are used to 1191 authenticate connections to receivers. Receivers 1192 are authenticated if their certificate has a chain 1193 of trust to one of these CA certificates. 1194 </description> 1195 <certificate> 1196 <name>ca.example.com</name> 1197 <cert-data>base64encodedvalue==</cert-data> 1198 </certificate> 1199 <certificate> 1200 <name>Fred Flintstone</name> 1201 <cert-data>base64encodedvalue==</cert-data> 1202 </certificate> 1203 </certificate-bag> 1204 </certificate-bags> 1205 </truststore> 1206 </config> 1208 Acknowledgements 1210 The authors would like to thank for following for lively discussions 1211 on list and in the halls (ordered by first name): Eric Voit, Henning 1212 Rogge, Martin Bjorklund, Reshad Rahman, and Rob Wilton. 1214 Authors' Addresses 1216 Mahesh Jethanandani 1217 Kloud Services 1219 Email: mjethanandani@gmail.com 1221 Kent Watsen 1222 Watsen Networks 1224 Email: kent+ietf@watsen.net