idnits 2.17.1 draft-ietf-netconf-https-notif-07.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 389 has weird spacing: '...rw name str...' == Line 551 has weird spacing: '...address ine...' == Line 570 has weird spacing: '...address ine...' == Line 600 has weird spacing: '...erprint x50...' -- The document date (February 2, 2021) is 1169 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) == Unused Reference: 'I-D.ietf-netconf-notification-messages' is defined on line 902, but no explicit reference was found in the text == Outdated reference: A later version (-20) exists of draft-ietf-netconf-http-client-server-05 -- Obsolete informational reference (is this intentional?): RFC 5226 (Obsoleted by RFC 8126) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 3 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 6, 2021 Watsen Networks 6 February 2, 2021 8 An HTTPS-based Transport for Configured Subscriptions 9 draft-ietf-netconf-https-notif-07 11 Abstract 13 This document defines both a protocol for sending notifications over 14 HTTPS as well as extensions to the data model for configured 15 subscriptions defined in RFC 8639. It also presents an example 16 module for configuration without using the data model defined in RFC 17 8639. 19 This document requires that the publisher is a "server" (e.g., a 20 NETCONF or RESTCONF server), but does not assume that the receiver is 21 a server. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at https://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on August 6, 2021. 40 Copyright Notice 42 Copyright (c) 2021 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (https://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Applicability Statement . . . . . . . . . . . . . . . . . 3 59 1.2. Note to RFC Editor . . . . . . . . . . . . . . . . . . . 3 60 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 4 61 1.4. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 62 1.4.1. Subscribed Notifications . . . . . . . . . . . . . . 4 63 2. Overview of Publisher to Receiver Interaction . . . . . . . . 4 64 3. Discovering a Receiver's Capabilities . . . . . . . . . . . . 5 65 3.1. Applicability . . . . . . . . . . . . . . . . . . . . . . 5 66 3.2. Request . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 3.3. Response . . . . . . . . . . . . . . . . . . . . . . . . 6 68 3.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 4. Sending Event Notifications . . . . . . . . . . . . . . . . . 7 70 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 8 72 4.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 5. The "ietf-subscribed-notif-receivers" Module . . . . . . . . 9 74 5.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 9 75 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 9 76 6. The "ietf-https-notif-transport" Module . . . . . . . . . . . 12 77 6.1. Data Model Overview . . . . . . . . . . . . . . . . . . . 12 78 6.2. YANG module . . . . . . . . . . . . . . . . . . . . . . . 13 79 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 81 8.1. The "IETF XML" Registry . . . . . . . . . . . . . . . . . 18 82 8.2. The "YANG Module Names" Registry . . . . . . . . . . . . 18 83 8.3. The "Capabilities for HTTPS Notification Receivers" 84 Registry . . . . . . . . . . . . . . . . . . . . . . . . 18 85 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 9.1. Normative references . . . . . . . . . . . . . . . . . . 19 87 9.2. Informative references . . . . . . . . . . . . . . . . . 21 88 Appendix A. Configuration Examples . . . . . . . . . . . . . . . 21 89 A.1. Using Subscribed Notifications (RFC 8639) . . . . . . . . 22 90 A.2. Not Using Subscribed Notifications . . . . . . . . . . . 24 91 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 26 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 94 1. Introduction 96 This document defines a protocol for sending notifications over 97 HTTPS. Using HTTPS maximizes transport-level interoperability, while 98 allowing for a variety of encoding options. This document defines 99 support for JSON and XML; future efforts may define support for other 100 encodings (e.g., binary). 102 This document also defines two YANG 1.1 [RFC7950] modules that extend 103 the data model defined in Subscription to YANG Notifications 104 [RFC8639], enabling the configuration of HTTPS-based receivers. 106 An example module illustrating the configuration of a publisher not 107 using the data model defined in RFC 8639 is also provided. 109 Configured subscriptions enable a server, acting as a publisher of 110 notifications, to proactively push notifications to external 111 receivers without the receivers needing to first connect to the 112 server, as is the case with dynamic subscriptions. 114 1.1. Applicability Statement 116 While the YANG modules have been defined as an augmentation of 117 Subscription to YANG Notifications [RFC8639], the notification method 118 defined in this document MAY be used outside of Subscription to YANG 119 Notifications [RFC8639] by using some of the definitions from this 120 module along with the grouping defined in Groupings for HTTP Clients 121 and Servers [I-D.ietf-netconf-http-client-server]. For an example on 122 how that can be done, see Section 8.2. 124 1.2. Note to RFC Editor 126 This document uses several placeholder values throughout the 127 document. Please replace them as follows and remove this section 128 before publication. 130 RFC XXXX, where XXXX is the number assigned to this document at the 131 time of publication. 133 RFC YYYY, where YYYY is the number assigned to 134 [I-D.ietf-netconf-http-client-server]. 136 2021-02-02 with the actual date of the publication of this document. 138 1.3. Abbreviations 140 +---------+--------------------------------------+ 141 | Acronym | Expansion | 142 +---------+--------------------------------------+ 143 | HTTP | Hyper Text Transport Protocol | 144 | | | 145 | HTTPS | Hyper Text Transport Protocol Secure | 146 | | | 147 | TCP | Transmission Control Protocol | 148 | | | 149 | TLS | Transport Layer Security | 150 +---------+--------------------------------------+ 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 o 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: 172 o A target resource enabling the publisher to discover what optional 173 capabilities a receiver supports. Publishers SHOULD query this 174 target when before sending any notifications or if ever an error 175 occurs. 177 o A target resource enabling to publish to send one or more 178 notification to a receiver. This document defines support for 179 sending only one notification per message; a future effort MAY 180 extend the protocol to send multiple notifications per message. 182 The protocol is illustrated in the diagram below: 184 ------------- -------------- 185 | Publisher | | Receiver | 186 ------------- -------------- 188 Send HTTPS GET message ------> 189 to discover receiver's 190 capabilities 192 <------ Send 200 (OK) containing 193 capabilities supported 194 by the receiver 196 +-- For Each Notification (MAY be pipelined) ---------------------+ 197 | | 198 | Send HTTPS POST message ------> | 199 | with YANG defined | 200 | notification | 201 | | 202 | <------ Send 204 (No Content) | 203 +-----------------------------------------------------------------+ 205 Note that, for RFC 8639 configured subscriptions, the very first 206 notification must be the "subscription-started" notification. 208 The POST messages MAY be "pipelined" (not illustrated in the diagram 209 above), whereby multiple notifications are sent without waiting for 210 the HTTP response for a previous request. 212 3. Discovering a Receiver's Capabilities 214 3.1. Applicability 216 For publishers using Subscription to YANG Notifications [RFC8639], 217 dynamic discovery of a receiver's supported encoding is necessary 218 only when the "/subscriptions/subscription/encoding" leaf is not 219 configured, per the "encoding" leaf's description statement in the 220 "ietf-subscribed-notification" module. FIXME: do they need to 221 discover *any* capabilities? 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 latter as the 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 string { 247 pattern "urn:ietf:capability:https-notif-receiver:*"; 248 } 249 description 250 "A capability supported by the receiver. A full list of 251 capabilities is defined in the 'Capabilities for HTTPS 252 Notification Receivers' registry (see RFC XXXX)."; 253 } 254 } 256 3.4. Example 258 The publisher can send the following request to learn the receiver 259 capabilities. In this example, the "Accept" states that the receiver 260 wants to receive notifications in XML but, if not supported, to use 261 JSON encoding. 263 GET /some/path/capabilities HTTP/1.1 264 Host: example.com 265 Accept: application/xml, application/json 267 If the receiver is able to reply using "application/xml", and 268 assuming it is able to receive JSON and XML encoded notifications, 269 the response might look like this: 271 HTTP/1.1 200 OK 272 Date: Wed, 26 Feb 2020 20:33:30 GMT 273 Server: example-server 274 Cache-Control: no-cache 275 Content-Type: application/xml 276 Content-Length: nnn 278 279 \ 280 urn:ietf:capability:https-notif-receiver:encoding:json\ 281 282 \ 283 urn:ietf:capability:https-notif-receiver:encoding:xml\ 284 285 287 If the receiver is unable to reply using "application/xml", the 288 response might look like this: 290 HTTP/1.1 200 OK 291 Date: Wed, 26 Feb 2020 20:33:30 GMT 292 Server: example-server 293 Cache-Control: no-cache 294 Content-Type: application/json 295 Content-Length: nnn 297 { 298 receiver-capabilities { 299 "receiver-capability": [ 300 "urn:ietf:capability:https-notif-receiver:encoding:json", 301 "urn:ietf:capability:https-notif-receiver:encoding:xml" 302 ] 303 } 304 } 306 4. Sending Event Notifications 308 4.1. Request 310 The publisher sends an HTTPS POST request to the "relay- 311 notifications" resource under a known path on the receiver with the 312 "Content-Type" header set to either "application/json" or 313 "application/xml" and a request body containing the notification 314 encoded using the specified format. 316 XML-encoded notifications are encoded using the format defined by 317 NETCONF Event Notifications [RFC5277] for XML. 319 JSON-encoded notifications are encoded the same as specified in 320 Section 6.4 in RESTCONF [RFC8040] with the following deviations: 322 o The notifications do not contain the "data:" prefix used by SSE. 324 o Instead of saying that, for JSON-encoding purposes, the module 325 name for the "notification" element is "ietf-restconf, the module 326 name will instead by "ietf-https-notif". 328 4.2. Response 330 The response should be "204 (No Content)". 332 4.3. Example 334 An XML-encoded notification might be sent as follows: 336 POST /some/path/relay-notification HTTP/1.1 337 Host: example.com 338 Content-Type: application/xml 340 341 2019-03-22T12:35:00Z 342 343 fault 344 345 Ethernet0 346 347 major 348 349 351 A JSON-encoded notification might be sent as follows: 353 POST /some/path/relay-notification HTTP/1.1 354 Host: example.com 355 Content-Type: application/json 357 { 358 "ietf-https-notif:notification": { 359 "eventTime": "2013-12-21T00:01:00Z", 360 "example-mod:event" : { 361 "event-class" : "fault", 362 "reporting-entity" : { "card" : "Ethernet0" }, 363 "severity" : "major" 364 } 365 } 366 } 367 And, in either case, the response might be as follows: 369 HTTP/1.1 204 No Content 370 Date: Wed, 26 Feb 2020 20:33:30 GMT 371 Server: example-server 373 5. The "ietf-subscribed-notif-receivers" Module 375 5.1. Data Model Overview 377 This YANG module augments the "ietf-subscribed-notifications" module 378 to define a choice of transport types that other modules such as the 379 "ietf-https-notif-transport" module can use to define a transport 380 specific receiver. 382 [note: '\' line wrapping for formatting only] 384 module: ietf-subscribed-notif-receivers 386 augment /sn:subscriptions: 387 +--rw receiver-instances 388 +--rw receiver-instance* [name] 389 +--rw name string 390 +--rw (transport-type) 391 augment /sn:subscriptions/sn:subscription/sn:receivers/sn:receiver:\ 393 +--rw receiver-instance-ref? leafref 395 5.2. YANG Module 397 The YANG module imports Subscription to YANG Notifications [RFC8639]. 399 file "ietf-subscribed-notif-receivers@2021-02-02.yang" 400 [note: '\' line wrapping for formatting only] 402 module ietf-subscribed-notif-receivers { 403 yang-version 1.1; 404 namespace 405 "urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers"; 406 prefix "snr"; 408 import ietf-subscribed-notifications { 409 prefix sn; 410 reference 411 "RFC 8639: Subscription to YANG Notifications"; 412 } 414 organization 415 "IETF NETCONF Working Group"; 417 contact 418 "WG Web: 419 WG List: 421 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 422 Kent Watsen (kent plus ietf at watsen dot net)"; 424 description 425 "This YANG module is implemented by Publishers implementing 426 the 'ietf-subscribed-notifications' module defined in RFC 8639. 428 While this module is defined in RFC XXXX, which primarily 429 defines an HTTPS-based transport for notifications, this module 430 is not HTTP-specific. It is a generic extension that can be 431 used by any 'notif' transport. 433 This module defines two 'augment' statements. One statement 434 augments a 'container' statement called 'receiver-instances' 435 into the top-level 'subscriptions' container. The other 436 statement, called 'receiver-instance-ref', augemnts a 'leaf' 437 statement into each 'receiver' that references one of the 438 afore mentioned receiver instances. This indirection enables 439 multiple configured subscriptions to send notifications to 440 the same receiver instance. 442 Copyright (c) 2021 IETF Trust and the persons identified as 443 the document authors. All rights reserved. 444 Redistribution and use in source and binary forms, with or 445 without modification, is permitted pursuant to, and subject 446 to the license terms contained in, the Simplified BSD 447 License set forth in Section 4.c of the IETF Trust's Legal 448 Provisions Relating to IETF Documents 449 (http://trustee.ietf.org/license-info). 451 This version of this YANG module is part of RFC XXXX; see 452 the RFC itself for full legal notices. 454 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 455 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 456 'MAY', and 'OPTIONAL' in this document are to be interpreted as 457 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 458 they appear in all capitals, as shown here."; 460 revision "2021-02-02" { 461 description 462 "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."; 513 } 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 [note: '\' line wrapping for formatting only] 541 module: ietf-https-notif-transport 543 augment /sn:subscriptions/snr:receiver-instances 544 /snr:receiver-instance/snr:transport-type: 545 +--:(https) 546 +--rw https-receiver 547 +--rw (transport) 548 | +--:(tcp) {tcp-supported,not httpc:tcp-supported}? 549 | | +--rw tcp 550 | | +--rw tcp-client-parameters 551 | | | +--rw remote-address inet:host 552 | | | +--rw remote-port? inet:port-number 553 | | | +--rw local-address? inet:ip-address 554 | | | | {local-binding-supported}? 555 | | | +--rw local-port? inet:port-number 556 | | | | {local-binding-supported}? 557 | | | +--rw proxy-server! {proxy-connect}? 558 | | | | ... 559 | | | +--rw keepalives! {keepalives-supported}? 560 | | | ... 562 | | +--rw http-client-parameters 563 | | +--rw client-identity! 564 | | | ... 565 | | +--rw proxy-connect! {proxy-connect}? 566 | | ... 567 | +--:(tls) {tls-supported}? 568 | +--rw tls 569 | +--rw tcp-client-parameters 570 | | +--rw remote-address inet:host 571 | | +--rw remote-port? inet:port-number 572 | | +--rw local-address? inet:ip-address 573 | | | {local-binding-supported}? 574 | | +--rw local-port? inet:port-number 575 | | | {local-binding-supported}? 576 | | +--rw proxy-server! {proxy-connect}? 577 | | | ... 578 | | +--rw keepalives! {keepalives-supported}? 579 | | ... 580 | +--rw tls-client-parameters 581 | | +--rw client-identity! 582 | | | ... 583 | | +--rw server-authentication 584 | | | ... 585 | | +--rw hello-params 586 | | | {tls-client-hello-params-config}? 587 | | | ... 588 | | +--rw keepalives {tls-client-keepalives}? 589 | | ... 590 | +--rw http-client-parameters 591 | +--rw client-identity! 592 | | ... 593 | +--rw proxy-connect! {proxy-connect}? 594 | | ... 595 | +--rw path string 596 +--rw receiver-identity {receiver-identity}? 597 +--rw cert-maps 598 +--rw cert-to-name* [id] 599 +--rw id uint32 600 +--rw fingerprint x509c2n:tls-fingerprint 601 +--rw map-type identityref 602 +--rw name string 604 6.2. YANG module 606 The YANG module imports A YANG Data Model for SNMP Configuration 607 [RFC7407], Subscription to YANG Notifications [RFC8639], and YANG 608 Groupings for HTTP Clients and HTTP Servers 609 [I-D.ietf-netconf-http-client-server]. 611 The YANG module is shown below. 613 file "ietf-https-notif-transport@2021-02-02.yang" 614 [note: '\' line wrapping for formatting only] 616 module ietf-https-notif-transport { 617 yang-version 1.1; 618 namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif-transport";\ 620 prefix "hnt"; 622 import ietf-x509-cert-to-name { 623 prefix x509c2n; 624 reference 625 "RFC 7407: YANG Data Model for SNMP Configuration."; 626 } 628 import ietf-subscribed-notifications { 629 prefix sn; 630 reference 631 "RFC 8639: Subscription to YANG Notifications"; 632 } 634 import ietf-subscribed-notif-receivers { 635 prefix snr; 636 reference 637 "RFC XXXX: An HTTPS-based Transport for 638 Configured Subscriptions"; 639 } 641 import ietf-http-client { 642 prefix httpc; 643 reference 644 "RFC YYYY: YANG Groupings for HTTP Clients and HTTP Servers"; 645 } 647 organization 648 "IETF NETCONF Working Group"; 650 contact 651 "WG Web: 652 WG List: 654 Authors: Mahesh Jethanandani (mjethanandani at gmail dot com) 655 Kent Watsen (kent plus ietf at watsen dot net)"; 657 description 658 "This YANG module is implemented by Publishers that implement 659 the 'ietf-subscribed-notifications' module defined in RFC 8639. 661 This module augments a 'case' statement called 'https' into 662 the 'choice' statement called 'transport-type' defined 663 by the 'ietf-https-notif-transport' module defined in RFC XXXX. \ 665 Copyright (c) 2021 IETF Trust and the persons identified as 666 the document authors. All rights reserved. 667 Redistribution and use in source and binary forms, with or 668 without modification, is permitted pursuant to, and subject 669 to the license terms contained in, the Simplified BSD 670 License set forth in Section 4.c of the IETF Trust's Legal 671 Provisions Relating to IETF Documents 672 (http://trustee.ietf.org/license-info). 674 This version of this YANG module is part of RFC XXXX; see 675 the RFC itself for full legal notices. 677 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL 678 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED', 679 'MAY', and 'OPTIONAL' in this document are to be interpreted as 680 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when, 681 they appear in all capitals, as shown here."; 683 revision "2021-02-02" { 684 description 685 "Initial Version."; 686 reference 687 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 688 } 690 feature receiver-identity { 691 description 692 "Indicates if the server supports filtering notifications 693 based on the receiver's identity derived from its TLS 694 certificate."; 695 } 697 identity https { 698 base sn:transport; 699 description 700 "HTTPS transport for notifications."; 701 } 703 grouping https-receiver-grouping { 704 description 705 "A grouping that may be used by other modules wishing to 706 configure HTTPS-based notifications without using RFC 8639."; 707 uses httpc:http-client-stack-grouping { 708 refine "transport/tcp" { 709 // create the logical impossibility of enabling the 710 // "tcp" transport (i.e., "HTTP" without the 'S'). 711 if-feature "not httpc:tcp-supported"; 712 } 713 augment "transport/tls/tls/http-client-parameters" { 714 leaf path { 715 type string; 716 mandatory true; 717 description 718 "URI prefix to the target resources. Under this 719 path the receiver must support both the 'capabilities' 720 and 'relay-notification' resource targets, as described 721 in RFC XXXX."; 722 } 723 description 724 "Augmentation to add a receiver-specific path for the 725 'capabilities' and 'relay-notification' resources."; 726 } 727 } 728 container receiver-identity { 729 if-feature receiver-identity; 730 description 731 "Maps the receiver's TLS certificate to a local identity 732 enabling access control to be applied to filter out 733 notifications that the receiver may not be authorized 734 to view."; 735 container cert-maps { 736 uses x509c2n:cert-to-name; 737 description 738 "The cert-maps container is used by a TLS-based HTTP 739 server to map the HTTPS client's presented X.509 740 certificate to a 'local' username. If no matching and 741 valid cert-to-name list entry is found, the publisher 742 MUST close the connection, and MUST NOT not send any 743 notifications over it."; 744 reference 745 "RFC 7407: A YANG Data Model for SNMP Configuration."; 746 } 747 } 748 } 750 augment "/sn:subscriptions/snr:receiver-instances/" + 751 "snr:receiver-instance/snr:transport-type" { 752 case https { 753 container https-receiver { 754 description 755 "The HTTPS receiver to send notifications to."; 756 uses https-receiver-grouping; 757 } 758 } 759 description 760 "Augment the transport-type choice to include the 'https' 761 transport."; 762 } 763 } 764 766 7. Security Considerations 768 The YANG module specified in this document defines a schema for data 769 that is designed to be accessed via network management protocols such 770 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer 771 is the secure transport layer, and the mandatory-to-implement secure 772 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 773 is HTTPS, and the mandatory-to-implement secure transport is TLS 774 [RFC8446]. The NETCONF Access Control Model (NACM) [RFC8341] 775 provides the means to restrict access for particular NETCONF or 776 RESTCONF users to a preconfigured subset of all available NETCONF or 777 RESTCONF protocol operations and content. 779 The YANG module in this document makes use of grouping that are 780 defined in YANG Groupings for HTTP Clients and HTTP Servers 781 [I-D.ietf-netconf-http-client-server], and A YANG Data Model for SNMP 782 Configuration [RFC7407]. Please see the Security Considerations 783 section of those documents for considerations related to sensitivity 784 and vulnerability of the data nodes defined in them. 786 There are a number of data nodes defined in this YANG module that are 787 writable/creatable/deletable (i.e., config true, which is the 788 default). These data nodes may be considered sensitive or vulnerable 789 in some network environments. Write operations (e.g., edit-config) 790 to these data nodes without proper protection can have a negative 791 effect on network operations. These are the subtrees and data nodes 792 and their sensitivity/vulnerability: 794 o The "path" node in "ietf-subscribed-notif-receivers" module can be 795 modified by a malicious user to point to an invalid URI. 797 Some of the readable data nodes in YANG module may be considered 798 sensitive or vulnerable in some network environments. It is thus 799 important to control read access (e.g., via get, get-config, or 800 notification) to these data nodes. The model does not define any 801 readable subtrees and data nodes. 803 Some of the RPC operations in YANG module may be considered sensitive 804 or vulnerable in some network environments. It is thus important to 805 control access to these operations. The model does not define any 806 RPC operations. 808 8. IANA Considerations 810 8.1. The "IETF XML" Registry 812 This document registers two URIs in the "ns" subregistry of the "IETF 813 XML" registry [RFC3688]. Following the format in [RFC3688], the 814 following registrations are requested: 816 URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 817 Registrant Contact: The IESG 818 XML: N/A, the requested URI is an XML namespace. 820 URI: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 821 Registrant Contact: The IESG 822 XML: N/A, the requested URI is an XML namespace. 824 8.2. The "YANG Module Names" Registry 826 This document registers two YANG modules in the "YANG Module Names" 827 registry [RFC6020]. Following the format in [RFC6020], the following 828 registrations are requested: 830 name: ietf-subscribed-notif-receivers 831 namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notif-receivers 832 prefix: snr 833 reference: RFC XXXX 835 name: ietf-https-notif-transport 836 namespace: urn:ietf:params:xml:ns:yang:ietf-https-notif-transport 837 prefix: hnt 838 reference: RFC XXXX 840 8.3. The "Capabilities for HTTPS Notification Receivers" Registry 842 Following the guidelines defined in [RFC5226], this document defines 843 a new registry called "Capabilities for HTTPS Notification 844 Receivers". This registry defines capabilities that can be supported 845 by HTTPS-based notification receivers. 847 The following note shall be at the top of the registry: 849 This registry defines capabilities that can be 850 supported by HTTPS-based notification receivers. 852 The fields for each registry are: 854 o URN 856 * The name of the URN (required). 858 * The URN must conform to the syntax described by [RFC8141]. 860 * The URN must begin with the string "urn:ietf:capability:https- 861 notif-receiver". 863 o Reference 865 * The RFC that defined the URN. 867 * The RFC must be in the form "RFC : . 869 o Description 871 * An arbitrary description of the algorithm (optional). 873 * The description should be no more than a few sentences. 875 * The description is to be in English, but may contain UTF-8 876 characters as may be needed in some cases. 878 The update policy is either "RFC Required". Updates do not otherwise 879 require an expert review by a Designated Expert. 881 Following is the initial assignment for this registry: 883 Record: 884 Name: urn:ietf:capability:https-notif-receiver:encoding:json 885 Reference: RFC XXXX 886 Description: Identifies support for JSON-encoded notifications. 888 Record: 889 Name: urn:ietf:capability:https-notif-receiver:encoding:xml 890 Reference: RFC XXXX 891 Description: Identifies support for XML-encoded notifications. 893 9. References 895 9.1. Normative references 897 [I-D.ietf-netconf-http-client-server] 898 Watsen, K., "YANG Groupings for HTTP Clients and HTTP 899 Servers", draft-ietf-netconf-http-client-server-05 (work 900 in progress), August 2020. 902 [I-D.ietf-netconf-notification-messages] 903 Voit, E., Jenkins, T., Birkholz, H., Bierman, A., and A. 904 Clemm, "Notification Message Headers and Bundles", draft- 905 ietf-netconf-notification-messages-08 (work in progress), 906 November 2019. 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, 910 DOI 10.17487/RFC2119, March 1997, 911 <https://www.rfc-editor.org/info/rfc2119>. 913 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 914 DOI 10.17487/RFC3688, January 2004, 915 <https://www.rfc-editor.org/info/rfc3688>. 917 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 918 Resource Identifier (URI): Generic Syntax", STD 66, 919 RFC 3986, DOI 10.17487/RFC3986, January 2005, 920 <https://www.rfc-editor.org/info/rfc3986>. 922 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 923 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 924 <https://www.rfc-editor.org/info/rfc5277>. 926 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 927 the Network Configuration Protocol (NETCONF)", RFC 6020, 928 DOI 10.17487/RFC6020, October 2010, 929 <https://www.rfc-editor.org/info/rfc6020>. 931 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 932 and A. Bierman, Ed., "Network Configuration Protocol 933 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 934 <https://www.rfc-editor.org/info/rfc6241>. 936 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 937 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 938 <https://www.rfc-editor.org/info/rfc6242>. 940 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for 941 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407, 942 December 2014, <https://www.rfc-editor.org/info/rfc7407>. 944 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 945 RFC 7950, DOI 10.17487/RFC7950, August 2016, 946 <https://www.rfc-editor.org/info/rfc7950>. 948 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 949 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 950 <https://www.rfc-editor.org/info/rfc8040>. 952 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 953 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 954 May 2017, <https://www.rfc-editor.org/info/rfc8174>. 956 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 957 Access Control Model", STD 91, RFC 8341, 958 DOI 10.17487/RFC8341, March 2018, 959 <https://www.rfc-editor.org/info/rfc8341>. 961 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 962 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 963 <https://www.rfc-editor.org/info/rfc8446>. 965 [RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, 966 E., and A. Tripathy, "Subscription to YANG Notifications", 967 RFC 8639, DOI 10.17487/RFC8639, September 2019, 968 <https://www.rfc-editor.org/info/rfc8639>. 970 9.2. Informative references 972 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 973 IANA Considerations Section in RFCs", RFC 5226, 974 DOI 10.17487/RFC5226, May 2008, 975 <https://www.rfc-editor.org/info/rfc5226>. 977 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names 978 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017, 979 <https://www.rfc-editor.org/info/rfc8141>. 981 Appendix A. Configuration Examples 983 This non-normative section shows two examples for how the "ietf- 984 https-notif-transport" module can be used to configure a publisher to 985 send notifications to a receiver. 987 In both examples, the Publisher, acting as an HTTPS client, is 988 configured to send notifications to a receiver at address 192.0.2.1, 989 port 443, and configures the "path" leaf value to "/some/path", with 990 server certificates, and the corresponding trust store that is used 991 to authenticate a connection. 993 A.1. Using Subscribed Notifications (RFC 8639) 995 This example shows how an RFC 8639 [RFC8639] based publisher can be 996 configured to send notifications to a receiver. 998 [note: '\' line wrapping for formatting only] 1000 <?xml version="1.0" encoding="UTF-8"?> 1001 <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 1002 <subscriptions xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-n\ 1003 otifications"> 1004 <receiver-instances xmlns="urn:ietf:params:xml:ns:yang:ietf-subsc\ 1005 ribed-notif-receivers"> 1006 <receiver-instance> 1007 <name>global-receiver-def</name> 1008 <https-receiver xmlns="urn:ietf:params:xml:ns:yang:ietf-https\ 1009 -notif-transport" 1010 xmlns:x509c2n="urn:ietf:params:xml:ns:yang:ietf-x509-cert-t\ 1011 o-name"> 1012 <tls> 1013 <tcp-client-parameters> 1014 <remote-address>receiver.example.com</remote-address> 1015 <remote-port>443</remote-port> 1016 </tcp-client-parameters> 1017 <tls-client-parameters> 1018 <server-authentication> 1019 <ca-certs> 1020 <local-definition> 1021 <certificate> 1022 <name>Server Cert Issuer #1</name> 1023 <cert-data>base64encodedvalue==</cert-data> 1024 </certificate> 1025 </local-definition> 1026 </ca-certs> 1027 </server-authentication> 1028 </tls-client-parameters> 1029 <http-client-parameters> 1030 <client-identity> 1031 <basic> 1032 <user-id>my-name</user-id> 1033 <cleartext-password>my-password</cleartext-password\ 1034 > 1035 </basic> 1036 </client-identity> 1037 <path>/some/path</path> 1038 </http-client-parameters> 1039 </tls> 1040 <receiver-identity> 1041 <cert-maps> 1042 <cert-to-name> 1043 <id>1</id> 1044 <fingerprint>11:0A:05:11:00</fingerprint> 1045 <map-type>x509c2n:san-any</map-type> 1046 </cert-to-name> 1047 </cert-maps> 1048 </receiver-identity> 1049 </https-receiver> 1050 </receiver-instance> 1051 </receiver-instances> 1052 <subscription> 1053 <id>6666</id> 1054 <transport xmlns:ph="urn:ietf:params:xml:ns:yang:ietf-https-not\ 1055 if-transport">ph:https</transport> 1056 <stream-subtree-filter>some-subtree-filter</stream-subtree-filt\ 1057 er> 1058 <stream>some-stream</stream> 1059 <receivers> 1060 <receiver> 1061 <name>subscription-specific-receiver-def</name> 1062 <receiver-instance-ref xmlns="urn:ietf:params:xml:ns:yang:i\ 1063 etf-subscribed-notif-receivers">global-receiver-def</receiver-instance-ref> 1064 </receiver> 1065 </receivers> 1066 </subscription> 1067 </subscriptions> 1068 <truststore xmlns="urn:ietf:params:xml:ns:yang:ietf-truststore"> 1069 <certificate-bags> 1070 <certificate-bag> 1071 <name>explicitly-trusted-server-ca-certs</name> 1072 <description> 1073 Trust anchors (i.e. CA certs) that are used to 1074 authenticate connections to receivers. Receivers 1075 are authenticated if their certificate has a chain 1076 of trust to one of these CA certificates. 1077 certificates. 1078 </description> 1079 <certificate> 1080 <name>ca.example.com</name> 1081 <cert-data>base64encodedvalue==</cert-data> 1082 </certificate> 1083 <certificate> 1084 <name>Fred Flintstone</name> 1085 <cert-data>base64encodedvalue==</cert-data> 1086 </certificate> 1087 </certificate-bag> 1088 </certificate-bags> 1090 </truststore> 1091 </config> 1093 A.2. Not Using Subscribed Notifications 1095 In the case that it is desired to use HTTPS-based notifications 1096 outside of Subscribed Notifications, an application-specific module 1097 would to need define the configuration for sending the notification. 1099 Following is an example module. Note that the module is "uses" the 1100 "https-receiver-grouping" grouping from the "ietf-https-notif- 1101 transport" module. 1103 [note: '\' line wrapping for formatting only] 1105 module example-custom-module { 1106 yang-version 1.1; 1107 namespace "http://example.com/example-custom-module"; 1108 prefix "custom"; 1110 import ietf-https-notif-transport { 1111 prefix "hnt"; 1112 reference 1113 "RFC XXXX: 1114 An HTTPS-based Transport for Configured Subscriptions"; 1115 } 1117 organization 1118 "Example, Inc."; 1120 contact 1121 "Support at example.com"; 1123 description 1124 "Example of module not using Subscribed Notifications module."; 1126 revision "2021-02-02" { 1127 description 1128 "Initial Version."; 1129 reference 1130 "RFC XXXX, YANG Data Module for HTTPS Notifications."; 1131 } 1133 container example-module { 1134 description 1135 "Example of using HTTPS notif without having to 1136 implement Subscribed Notifications."; 1138 container https-receivers { 1139 description 1140 "A container of all HTTPS notif receivers."; 1141 list https-receiver { 1142 key "name"; 1143 description 1144 "A list of HTTPS nofif receivers."; 1145 leaf name { 1146 type string; 1147 description 1148 "A unique name for the https notif receiver."; 1149 } 1150 uses hnt:https-receiver-grouping; 1151 } 1152 } 1153 } 1154 } 1156 Following is what the corresponding configuration looks like: 1158 [note: '\' line wrapping for formatting only] 1160 <?xml version="1.0" encoding="UTF-8"?> 1161 <config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 1162 <example-module xmlns="http://example.com/example-custom-module"> 1163 <https-receivers> 1164 <https-receiver> 1165 <name>foo</name> 1166 <tls> 1167 <tcp-client-parameters> 1168 <remote-address>receiver.example.com</remote-address> 1169 <remote-port>443</remote-port> 1170 </tcp-client-parameters> 1171 <tls-client-parameters> 1172 <server-authentication> 1173 <ca-certs> 1174 <local-definition> 1175 <certificate> 1176 <name>Server Cert Issuer #1</name> 1177 <cert-data>base64encodedvalue==</cert-data> 1178 </certificate> 1179 </local-definition> 1180 </ca-certs> 1181 </server-authentication> 1182 </tls-client-parameters> 1183 <http-client-parameters> 1184 <client-identity> 1185 <basic> 1186 <user-id>my-name</user-id> 1187 <cleartext-password>my-password</cleartext-password> 1188 </basic> 1189 </client-identity> 1190 <path>/some/path</path> 1191 </http-client-parameters> 1192 </tls> 1193 </https-receiver> 1194 </https-receivers> 1195 </example-module> 1196 <truststore xmlns="urn:ietf:params:xml:ns:yang:ietf-truststore"> 1197 <certificate-bags> 1198 <certificate-bag> 1199 <name>explicitly-trusted-server-ca-certs</name> 1200 <description> 1201 Trust anchors (i.e. CA certs) that are used to 1202 authenticate connections to receivers. Receivers 1203 are authenticated if their certificate has a chain 1204 of trust to one of these CA certificates. 1205 </description> 1206 <certificate> 1207 <name>ca.example.com</name> 1208 <cert-data>base64encodedvalue==</cert-data> 1209 </certificate> 1210 <certificate> 1211 <name>Fred Flintstone</name> 1212 <cert-data>base64encodedvalue==</cert-data> 1213 </certificate> 1214 </certificate-bag> 1215 </certificate-bags> 1216 </truststore> 1217 </config> 1219 Acknowledgements 1221 The authors would like to thank for following for lively discussions 1222 on list and in the halls (ordered by first name): Eric Voit, Henning 1223 Rogge, Martin Bjorklund, Reshad Rahman, and Rob Wilton. 1225 Authors' Addresses 1227 Mahesh Jethanandani 1228 Kloud Services 1230 Email: mjethanandani@gmail.com 1231 Kent Watsen 1232 Watsen Networks 1234 Email: kent+ietf@watsen.net