RFC 8639
Subscription to YANG Notifications
5. IANA Considerations
IANA has registered one URI in the "ns" subregistry of the "IETF XML Registry" [RFC3688] maintained at <https://www.iana.org/assignments/ xml-registry>. The following registration has been made per the format in [RFC3688]: URI: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications Registrant Contact: The NETCONF WG of the IETF. XML: N/A; the requested URI is an XML namespace. IANA has registered one YANG module in the "YANG Module Names" registry [RFC6020] maintained at <https://www.iana.org/assignments/ yang-parameters>. The following registration has been made per the format in [RFC6020]: Name: ietf-subscribed-notifications Namespace: urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications Prefix: sn Reference: RFC 86396. Implementation Considerations
To support deployments that include both configured and dynamic subscriptions, it is recommended that the subscription "id" domain be split into static and dynamic halves. This will eliminate the possibility of collisions if the configured subscriptions attempt to set a "subscription-id" that might have already been dynamically allocated. A best practice is to use the lower half of the "id" object's integer space when that "id" is assigned by an external entity (such as with a configured subscription). This leaves the upper half of the subscription integer space available to be dynamically assigned by the publisher. If a subscription is unable to marshal a series of filtered event records into transmittable notification messages, the receiver should be suspended with the reason "unsupportable-volume". For configured subscriptions, operations are performed against the set of receivers using the subscription "id" as a handle for that set. But for streaming updates, subscription state change notifications are local to a receiver. In the case of this specification, receivers do not get any information from the publisher about the existence of other receivers. But if a network operator wants to let the receivers correlate results, it is useful to use the subscription "id" across the receivers to allow that
correlation. Note that due to the possibility of different access control permissions per receiver, each receiver may actually get a different set of event records. For configured replay subscriptions, the receiver is protected from duplicated events being pushed after a publisher is rebooted. However, it is possible that a receiver might want to acquire event records that failed to be delivered just prior to the reboot. Delivering these event records can be accomplished by leveraging the <eventTime> [RFC5277] from the last event record received prior to the receipt of a "subscription-started" subscription state change notification. With this <eventTime> and the "replay-start-time" from the "subscription-started" notification, an independent dynamic subscription can be established that retrieves any event records that may have been generated but not sent to the receiver.7. Transport Requirements
This section provides requirements for any subscribed notification transport supporting the solution presented in this document. The transport selected by the subscriber to reach the publisher MUST be able to support multiple "establish-subscription" requests made in the same transport session. For both configured and dynamic subscriptions, the publisher MUST authenticate a receiver via some transport-level mechanism before sending any event records that the receiver is authorized to see. In addition, the receiver MUST authenticate the publisher at the transport level. The result is mutual authentication between the two. A secure transport is highly recommended. Beyond this, the publisher MUST ensure that the receiver has sufficient authorization to perform the function it is requesting against the specific subset of content involved. A specification for a transport built upon this document may or may not choose to require the use of the same logical channel for the RPCs and the event records. However, the event records and the subscription state change notifications MUST be sent on the same transport session to ensure properly ordered delivery. A specification for a transport MUST identify any encodings that are supported. If a configured subscription's transport allows different encodings, the specification MUST identify the default encoding.
A subscriber that includes a "dscp" leaf in an "establish- subscription" request will need to understand and consider what the corresponding DSCP value represents in the domain of the publisher. Additional transport requirements will be dictated by the choice of transport used with a subscription. For an example of such requirements, see [RFC8640].8. Security Considerations
The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC5246]. The Network Configuration Access Control Model (NACM) [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. With configured subscriptions, one or more publishers could be used to overwhelm a receiver. To counter this, notification messages SHOULD NOT be sent to any receiver that does not support this specification. Receivers that do not want notification messages need only terminate or refuse any transport sessions from the publisher. When a receiver of a configured subscription gets a new "subscription-started" message for a known subscription where it is already consuming events, it may indicate that an attacker has done something that has momentarily disrupted receiver connectivity. To acquire events lost during this interval, the receiver SHOULD retrieve any event records generated since the last event record was received. This can be accomplished by establishing a separate dynamic replay subscription with the same filtering criteria with the publisher, assuming that the publisher supports the "replay" feature. For dynamic subscriptions, implementations need to protect against malicious or buggy subscribers that may send a large number of "establish-subscription" requests and thereby use up system resources. To cover this possibility, operators SHOULD monitor for such cases and, if discovered, take remedial action to limit the resources used, such as suspending or terminating a subset of the subscriptions or, if the underlying transport is session based, terminating the underlying transport session.
The replay mechanisms described in Sections 2.4.2.1 and 2.5.6 provide access to historical event records. By design, the access control model that protects these records could enable subscribers to view data to which they were not authorized at the time of collection. Using DNS names for configured subscription's receiver "name" lookups can cause situations where the name resolves differently than expected on the publisher, so the recipient would be different than expected. An attacker that can cause the publisher to use an incorrect time can induce message replay by setting the time in the past and can introduce a risk of message loss by setting the time in the future. There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability: Container: "/filters" o "stream-subtree-filter": Updating a filter could increase the computational complexity of all referencing subscriptions. o "stream-xpath-filter": Updating a filter could increase the computational complexity of all referencing subscriptions. Container: "/subscriptions" The following considerations are only relevant for configuration operations made upon configured subscriptions: o "configured-replay": Can be used to send a large number of event records to a receiver. o "dependency": Can be used to force important traffic to be queued behind updates that are not as important. o "dscp": If unvalidated, can result in the sending of traffic with a higher-priority marking than warranted. o "id": Can overwrite an existing subscription, perhaps one configured by another entity.
o "name": Adding a new key entry can be used to attempt to send
traffic to an unwilling receiver.
o "replay-start-time": Can be used to push very large logs, wasting
resources.
o "source-address": The configured address might not be able to
reach a desired receiver.
o "source-interface": The configured interface might not be able to
reach a desired receiver.
o "source-vrf": Can place a subscription in a virtual network where
receivers are not entitled to view the subscribed content.
o "stop-time": Could be used to terminate content at an inopportune
time.
o "stream": Could set a subscription to an event stream that does
not contain content permitted for the targeted receivers.
o "stream-filter-name": Could be set to a filter that is not
relevant to the event stream.
o "stream-subtree-filter": A complex filter can increase the
computational resources for this subscription.
o "stream-xpath-filter": A complex filter can increase the
computational resources for this subscription.
o "weighting": Allocating a large weight can overwhelm the dequeuing
of other subscriptions.
Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes. These are the subtrees and data
nodes and their sensitivity/vulnerability:
Container: "/streams"
o "name": If access control is not properly configured, can expose
system internals to those who should not have access to this
information.
o "replay-support": If access control is not properly configured,
can expose logs to those who should not have access.
Container: "/subscriptions"
o "excluded-event-records": This leaf can provide information about
filtered event records. A network operator should have the proper
permissions to know about such filtering. However, exposing the
count of excluded events to a receiver could leak information
about the presence of access control filters that might be in
place for that receiver.
o "subscription": Different operational teams might have a desire to
set varying subsets of subscriptions. Access control should be
designed to permit read access to just the allowed set.
Some of the RPC operations in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control access to these operations. These are the
operations and their sensitivity/vulnerability:
RPC: all
o If a malicious or buggy subscriber sends an unexpectedly large
number of RPCs, the result might be an excessive use of system
resources on the publisher just to determine that these
subscriptions should be declined. In such a situation,
subscription interactions MAY be terminated by terminating the
transport session.
RPC: "delete-subscription"
o No special considerations.
RPC: "establish-subscription"
o Subscriptions could overload a publisher's resources. For this
reason, publishers MUST ensure that they have sufficient resources
to fulfill this request; otherwise, they MUST reject the request.
RPC: "kill-subscription"
o The "kill-subscription" RPC MUST be secured so that only
connections with administrative rights are able to invoke
this RPC.
RPC: "modify-subscription"
o Subscriptions could overload a publisher's resources. For this
reason, publishers MUST ensure that they have sufficient resources
to fulfill this request; otherwise, they MUST reject the request.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>. [RFC2474] Nichols, K., Blake, S., Baker, F., and D. Black, "Definition of the Differentiated Services Field (DS Field) in the IPv4 and IPv6 Headers", RFC 2474, DOI 10.17487/RFC2474, December 1998, <https://www.rfc-editor.org/info/rfc2474>. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/info/rfc5246>. [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, <https://www.rfc-editor.org/info/rfc5277>. [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>. [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>. [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>. [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>. [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>. [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>. [RFC8343] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>. [RFC8529] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, "YANG Data Model for Network Instances", RFC 8529, DOI 10.17487/RFC8529, March 2019, <https://www.rfc-editor.org/info/rfc8529>. [W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <https://www.w3.org/TR/2008/REC-xml-20081126>. [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", November 1999, <https://www.w3.org/TR/1999/REC-xpath-19991116>.
9.2. Informative References
[RESTCONF-Notif] Voit, E., Rahman, R., Nilsen-Nygaard, E., Clemm, A., and A. Bierman, "Dynamic subscription to YANG Events and Datastores over RESTCONF", Work in Progress, draft-ietf-netconf-restconf-notif-15, June 2019. [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, <https://www.rfc-editor.org/info/rfc7049>. [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, May 2015, <https://www.rfc-editor.org/info/rfc7540>. [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements for Subscription to YANG Datastores", RFC 7923, DOI 10.17487/RFC7923, June 2016, <https://www.rfc-editor.org/info/rfc7923>. [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", RFC 8071, DOI 10.17487/RFC8071, February 2017, <https://www.rfc-editor.org/info/rfc8071>. [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>. [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>. [RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, "Dynamic Subscription to YANG Events and Datastores over NETCONF", RFC 8640, DOI 10.17487/RFC8640, September 2019, <https://www.rfc-editor.org/info/rfc8640>. [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, September 2019, <https://www.rfc-editor.org/info/rfc8641>.
Appendix A. Example Configured Transport Augmentation
This appendix provides a non-normative example of how the YANG module defined in Section 4 may be enhanced to incorporate the configuration parameters needed to support the transport connectivity process. This example is not intended to be a complete transport model. In this example, connectivity via an imaginary transport type of "foo" is explored. For more on the overall objectives behind configuring transport connectivity for a configured subscription, see Section 2.5.7. The YANG module example defined in this appendix contains two main elements. First is a transport identity "foo". This transport identity allows a configuration agent to define "foo" as the selected type of transport for a subscription. Second is a YANG case augmentation "foo", which is made to the "/subscriptions/subscription/receivers/receiver" node of Section 4. In this augmentation are the transport configuration parameters "address" and "port", which are necessary to make the connection to the receiver. module example-foo-subscribed-notifications { yang-version 1.1; namespace "urn:example:foo-subscribed-notifications"; prefix fsn; import ietf-subscribed-notifications { prefix sn; } import ietf-inet-types { prefix inet; } description "Defines 'foo' as a supported type of configured transport for subscribed event notifications."; identity foo { base sn:transport; description "Transport type 'foo' is available for use as a configured subscription's transport protocol for subscribed notifications."; }
augment "/sn:subscriptions/sn:subscription/sn:receivers/sn:receiver" { when 'derived-from(../../../transport, "fsn:foo")'; description "This augmentation makes transport parameters specific to 'foo' available for a receiver."; leaf address { type inet:host; mandatory true; description "Specifies the address to use for messages destined for a receiver."; } leaf port { type inet:port-number; mandatory true; description "Specifies the port number to use for messages destined for a receiver."; } } } Figure 21: Example Transport Augmentation for the Fictitious Protocol "foo" This example YANG module for transport "foo" will not be seen in a real-world deployment. For a real-world deployment supporting an actual transport technology, a similar YANG module must be defined.
Acknowledgments
For their valuable comments, discussions, and feedback, we wish to acknowledge Andy Bierman, Tim Jenkins, Martin Bjorklund, Kent Watsen, Balazs Lengyel, Robert Wilton, Sharon Chisholm, Hector Trevino, Susan Hares, Michael Scharf, and Guangying Zheng.Authors' Addresses
Eric Voit Cisco Systems Email: evoit@cisco.com Alexander Clemm Futurewei Email: ludwig@clemm.org Alberto Gonzalez Prieto Microsoft Email: alberto.gonzalez@microsoft.com Einar Nilsen-Nygaard Cisco Systems Email: einarnn@cisco.com Ambika Prasad Tripathy Cisco Systems Email: ambtripa@cisco.com