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 .
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 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 .
966 [RFC8141] Saint-Andre, P. and J. Klensin, "Uniform Resource Names
967 (URNs)", RFC 8141, DOI 10.17487/RFC8141, April 2017,
968 .
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
990
991
994
997
998 global-receiver-def
999
1004
1005
1006 receiver.example.com
1007 443
1008
1009
1010
1011
1012
1013
1014 Server Cert Issuer #1
1015 base64encodedvalue==
1016
1017
1018
1019
1020
1021
1022
1023
1024 my-name
1025 my-password
1027
1028
1029 /some/path
1030
1031
1032
1033
1034
1035 1
1036 11:0A:05:11:00
1037 x509c2n:san-any
1038
1039
1040
1041
1042
1043
1044
1045 6666
1046 ph:https
1048 some-subtree-filter
1050 some-stream
1051
1052
1053 subscription-specific-receiver-def
1054 global-receiver-def
1057
1058
1059
1060
1061
1062
1063
1064 explicitly-trusted-server-ca-certs
1065
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
1072
1073 ca.example.com
1074 base64encodedvalue==
1075
1076
1077 Fred Flintstone
1078 base64encodedvalue==
1079
1080
1081
1082
1083
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
1149
1150
1151
1152
1153 foo
1154
1155
1156 receiver.example.com
1157 443
1159
1160
1161
1162
1163
1164
1165 Server Cert Issuer #1
1166 base64encodedvalue==
1167
1168
1169
1170
1171
1172
1173
1174
1175 my-name
1176 my-password
1177
1178
1179 /some/path
1180
1181
1182
1183
1184
1185
1186
1187
1188 explicitly-trusted-server-ca-certs
1189
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
1195
1196 ca.example.com
1197 base64encodedvalue==
1198
1199
1200 Fred Flintstone
1201 base64encodedvalue==
1202
1203
1204
1205
1206
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