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 .
902 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
903 DOI 10.17487/RFC3688, January 2004,
904 .
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 .
911 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
912 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
913 .
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 .
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 .
925 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
926 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
927 .
929 [RFC7407] Bjorklund, M. and J. Schoenwaelder, "A YANG Data Model for
930 SNMP Configuration", RFC 7407, DOI 10.17487/RFC7407,
931 December 2014, .
933 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
934 RFC 7950, DOI 10.17487/RFC7950, August 2016,
935 .
937 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
938 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
939 .
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, .
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 .
950 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
951 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
952 .
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 .
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 .
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 .
973 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names
974 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
975 .
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
997
1000
1003
1004 global-receiver-def
1005
1010
1011
1012 receiver.example.com
1013 443
1014
1015
1016
1017
1018
1019
1020 Server Cert Issuer #1
1021 base64encodedvalue==
1022
1023
1024
1025
1026
1027
1028
1029
1030 my-name
1031 my-password
1032
1033
1034 /some/path
1035
1036
1037
1038
1039
1040 1
1041 11:0A:05:11:00
1042 x509c2n:san-any
1043
1044
1045
1046
1047
1048
1049
1050 6666
1051 ph:https
1053 some-subtree-filter
1055 some-stream
1056
1057
1058 subscription-specific-receiver-def
1059 global-receiver-def
1062
1063
1064
1065
1066
1067
1068
1069 explicitly-trusted-server-ca-certs
1070
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
1077
1078 ca.example.com
1079 base64encodedvalue==
1080
1081
1082 Fred Flintstone
1083 base64encodedvalue==
1084
1085
1086
1087
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
1153
1154
1155
1156 foo
1157
1158
1159 receiver.example.com
1160 443
1161
1162
1163
1164
1165
1166
1167 Server Cert Issuer #1
1168 base64encodedvalue==
1169
1170
1171
1172
1173
1174
1175
1176
1177 my-name
1178 my-password
1179
1180
1181 /some/path
1182
1183
1184
1185
1186
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