RFC 8533
A YANG Data Model for Retrieval Methods for the Management of Operations, Administration, and Maintenance (OAM) Protocols That Use Connectionless Communications
Pages: 41
Proposed Standard
Proposed Standard
Part 2 of 2 – Pages 26 to 41
5. 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 [RFC8446]. 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. 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: o continuity-check: Generates Continuity Check. o path-discovery: Generates path discovery. These operations are used to retrieve the data from the device that needs to execute the OAM command. Unauthorized source access to some sensitive information in the above data may be used for network reconnaissance or lead to denial-of-service attacks on both the local device and the network.6. IANA Considerations
This document registers a URI in the "IETF XML Registry" [RFC3688]. The following registration has been made: URI: urn:ietf:params:xml:ns:yang:ietf-connectionless-oam-methods Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace. This document registers a YANG module in the "YANG Module Names" registry [RFC6020]. name: ietf-connectionless-oam-methods namespace: urn:ietf:params:xml:ns:yang:ietf-connectionless-oam-methods prefix: cloam-methods reference: RFC 8533
7. References
7.1. Normative References
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>. [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>. [RFC7011] Claise, B., Ed., Trammell, B., Ed., and P. Aitken, "Specification of the IP Flow Information Export (IPFIX) Protocol for the Exchange of Flow Information", STD 77, RFC 7011, DOI 10.17487/RFC7011, September 2013, <https://www.rfc-editor.org/info/rfc7011>. [RFC792] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, DOI 10.17487/RFC0792, September 1981. [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>. [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>. [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8532] Kumar, D., Wang, M., Wu, Q., Ed., Rahman, R., and S. Raghavan, "Generic YANG Data Model for the Management of Operations, Administration, and Maintenance (OAM) Protocols That Use Connectionless Communications", RFC 8532, DOI 10.17487/RFC8532, April 2019, <https://www.rfc-editor.org/info/rfc8532>.7.2. Informative References
[RFC4443] Conta, A., Deering, S., and M. Gupta, Ed., "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification", STD 89, RFC 4443, DOI 10.17487/RFC4443, March 2006, <https://www.rfc-editor.org/info/rfc4443>. [RFC5880] Katz, D. and D. Ward, "Bidirectional Forwarding Detection (BFD)", RFC 5880, DOI 10.17487/RFC5880, June 2010, <https://www.rfc-editor.org/info/rfc5880>. [RFC7276] Mizrahi, T., Sprecher, N., Bellagamba, E., and Y. Weingarten, "An Overview of Operations, Administration, and Maintenance (OAM) Tools", RFC 7276, DOI 10.17487/RFC7276, June 2014, <https://www.rfc-editor.org/info/rfc7276>. [RFC8029] Kompella, K., Swallow, G., Pignataro, C., Ed., Kumar, N., Aldrin, S., and M. Chen, "Detecting Multiprotocol Label Switched (MPLS) Data-Plane Failures", RFC 8029, DOI 10.17487/RFC8029, March 2017, <https://www.rfc-editor.org/info/rfc8029>. [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>. [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of Documents Containing YANG Data Models", BCP 216, RFC 8407, DOI 10.17487/RFC8407, October 2018, <https://www.rfc-editor.org/info/rfc8407>. [YANG-Push] Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen- Nygaard, E., Bierman, A., and B. Lengyel, "Subscription to YANG Datastores", Work in Progress, draft-ietf-netconf- yang-push-22, February 2019.
Appendix A. Extending Connectionless OAM Method Module Example
The following is an example of extensions possible to the "ietf-connectionless-oam-methods" YANG data model defined in this document. The snippet below depicts an example of augmenting the "ietf-connectionless-oam-methods" YANG data model with ICMP ping attributes: augment "/cloam-methods:continuity-check" +"/cloam-methods:output"{ container session-rtt-statistics{ leaf min-rtt{ type uint32; description "This minimum ping round-trip-time (RTT) received."; } leaf max-rtt{ type uint32; description "This maximum ping RTT received."; } leaf avg-rtt{ type uint32; description "The current average ping RTT."; } description "This container presents the ping RTT statistics."; } }A.1. Example of New Retrieval Procedures Model
As discussed in the Introduction section of this document, the new retrieval procedures can be defined for retrieval of the same data defined by the base YANG data model for connectionless OAM protocols. This appendix demonstrates how the base connectionless OAM data model can be extended to support persistent data retrieval besides on-demand retrieval procedures defined in Section 3, i.e., first retrieve a persistent-id based on the destination test point location information, and then retrieve the export details based on persistent-id. Internet Protocol Flow Information Export (IPFIX) [RFC7011] or YANG-Push [YANG-Push] are currently outlined here as data export options. Additional export options can be added in the future.
The YANG module "example-cl-oam-persistent-methods" shown below is intended as an illustration rather than a real definition of an RPC operation model for persistent data retrieval. For the sake of brevity, this module does not obey all the guidelines specified in [RFC8407]. module example-cl-oam-persistent-methods { namespace "http://example.com/cl-oam-persistent-methods"; prefix pcloam-methods; import ietf-interfaces { prefix if; } import ietf-connectionless-oam { prefix cl-oam; } import ietf-yang-types { prefix yang; } identity export-method { description "Base identity to represent a conceptual export-method."; } identity ipfix-export { base export-method; description "IPFIX-based export. Configuration provided separately."; } identity yang-push-export { base export-method; description "YANG-Push from draft-ietf-netconf-yang-push."; } identity protocol-id { description "A generic protocol identifier."; } identity status-code { description "Base status code."; }
identity success-reach {
base status-code;
description
"Indicates that the destination being verified
is reachable.";
}
identity fail-reach {
base status-code;
description
"Indicates that the destination being verified
is not reachable";
}
identity success-path-verification {
base status-code;
description
"Indicates that the path verification is performed
successfully.";
}
identity fail-path-verification {
base status-code;
description
"Indicates that the path verification fails.";
}
identity status-sub-code {
description
"Base status-sub-code.";
}
identity invalid-cc {
base status-sub-code;
description
"Indicates that the Continuity Check message is
invalid.";
}
identity invalid-pd {
base status-sub-code;
description
"Indicates that the path discovery message is invalid.";
}
typedef export-method {
type identityref {
base export-method;
}
description
"Export method type.";
}
typedef change-type {
type enumeration {
enum create {
description
"Change due to a create.";
}
enum delete {
description
"Change due to a delete.";
}
enum modify {
description
"Change due to an update.";
}
}
description
"Different types of changes that may occur.";
}
rpc cc-get-persistent-id {
if-feature "cl-oam:continuity-check";
description
"Obtains Continuity Check persistent identification
given mapping parameters as input.";
input {
container destination-tp {
uses cl-oam:tp-address;
description
"Destination test point.";
}
uses cl-oam:session-type;
leaf source-interface {
type if:interface-ref;
description
"Source interface.";
}
leaf outbound-interface {
type if:interface-ref;
description
"Outbound interface.";
}
leaf vrf {
type cl-oam:routing-instance-ref;
description
"VRF instance.";
}
}
output {
container error-code {
leaf protocol-id {
type identityref {
base protocol-id;
}
mandatory true;
description
"Protocol used. This could be a standard
protocol (e.g., TCP/IP protocols, MPLS, etc.)
or a proprietary protocol as identified by
this field.";
}
leaf protocol-id-meta-data {
type uint64;
description
"An optional metadata related to the protocol ID.
For example, this could be the Internet Protocol
number for standard Internet Protocols used for
help with protocol processing.";
}
leaf status-code {
type identityref {
base status-code;
}
mandatory true;
description
"Status code.";
}
leaf status-sub-code {
type identityref {
base status-sub-code;
}
mandatory true;
description
"Sub code for the Continuity Check.";
}
description
"Status code and sub code.";
}
leaf cc-persistent-id {
type string;
description
"Id to act as a cookie.";
}
}
}
rpc cc-persistent-get-export-details {
if-feature "cl-oam:continuity-check";
description
"Given the persistent ID, gets the configuration
options and details related to the configured data
export.";
input {
leaf cc-persistent-id {
type string;
description
"Persistent ID for use as a key in search.";
}
}
output {
container error-code {
leaf protocol-id {
type identityref {
base protocol-id;
}
mandatory true;
description
"Protocol used. This could be a standard
protocol (e.g., TCP/IP protocols, MPLS, etc.)
or a proprietary protocol as identified by
this field.";
}
leaf protocol-id-meta-data {
type uint64;
description
"An optional metadata related to the protocol ID.
For example, this could be the Internet Protocol
number for standard Internet Protocols used for
help with protocol processing.";
}
leaf status-code {
type identityref {
base status-code;
}
mandatory true;
description
"Status code.";
}
leaf status-sub-code {
type identityref {
base status-sub-code;
}
mandatory true;
description
"Sub code for the Continuity Check.";
}
description
"Status code and sub code.";
}
leaf data-export-method {
type export-method;
description
"Type of export in use.";
}
choice cc-trigger {
description
"Necessary conditions for
periodic or on-change trigger.";
case periodic {
description
"Periodic reports.";
leaf period {
type yang:timeticks;
description
"Time interval between reports.";
}
leaf start-time {
type yang:date-and-time;
description
"Timestamp from which reports were started.";
}
}
case on-change {
description
"On-change trigger and not periodic.";
leaf all-data-on-start {
type boolean;
description
"Full update done on start or not.";
}
leaf-list excluded-change {
type change-type;
description
"Changes that will not trigger an update.";
}
}
}
}
}
rpc pd-get-persistent-id {
if-feature "cl-oam:path-discovery";
description
"Obtains persistent path discovery identification.";
input {
container destination-tp {
uses cl-oam:tp-address;
description
"Destination test point.";
}
uses cl-oam:session-type;
leaf source-interface {
type if:interface-ref;
description
"Source interface.";
}
leaf outbound-interface {
type if:interface-ref;
description
"Outbound interface.";
}
leaf vrf {
type cl-oam:routing-instance-ref;
description
"VRF";
}
}
output {
list response-list {
key "response-index";
description
"Path discovery response list.";
leaf response-index {
type uint32;
mandatory true;
description
"Response index.";
}
leaf protocol-id {
type identityref {
base protocol-id;
}
mandatory true;
description
"Protocol used. This could be a standard
protocol (e.g., TCP/IP protocols, MPLS, etc.)
or a proprietary protocol as identified by
this field.";
}
leaf protocol-id-meta-data {
type uint64;
description
"An optional metadata related to the protocol ID.
For example, this could be the Internet Protocol
number for standard Internet Protocols used for
help with protocol processing.";
}
leaf status-code {
type identityref {
base status-code;
}
mandatory true;
description
"Status code for persistent path discovery
information.";
}
leaf status-sub-code {
type identityref {
base status-sub-code;
}
mandatory true;
description
"Sub code for persistent path discovery
information.";
}
leaf pd-persistent-id {
type string;
description
"Id to act as a cookie.";
}
}
}
}
rpc pd-persistent-get-export-details {
if-feature "cl-oam:path-discovery";
description
"Given the persistent ID, gets the configuration
options and details related to the configured data
export.";
input {
leaf cc-persistent-id {
type string;
description
"Persistent ID for use as a key in search.";
}
}
output {
list response-list {
key "response-index";
description
"Path discovery response list.";
leaf response-index {
type uint32;
mandatory true;
description
"Response index.";
}
leaf protocol-id {
type identityref {
base protocol-id;
}
mandatory true;
description
"Protocol used. This could be a standard
protocol (e.g., TCP/IP protocols, MPLS, etc.)
or a proprietary protocol as identified by
this field.";
}
leaf protocol-id-meta-data {
type uint64;
description
"An optional metadata related to the protocol ID.
For example, this could be the Internet Protocol
number for standard Internet Protocols used for
help with protocol processing.";
}
leaf status-code {
type identityref {
base status-code;
}
mandatory true;
description
"Status code for persistent path discovery
creation.";
}
leaf status-sub-code {
type identityref {
base status-sub-code;
}
mandatory true;
description
"Sub code for persistent path discovery
creation.";
}
leaf data-export-method {
type export-method;
description
"Type of export.";
}
choice pd-trigger {
description
"Necessary conditions
for periodic or on-change
trigger.";
case periodic {
description
"Periodic reports.";
leaf period {
type yang:timeticks;
description
"Time interval between reports.";
}
leaf start-time {
type yang:date-and-time;
description
"Timestamp from which reports are started.";
}
}
case on-change {
description
"On-change trigger and not periodic.";
leaf all-data-on-start {
type boolean;
description
"Full update done on start or not.";
}
leaf-list excluded-change {
type change-type;
description
"Changes that will not trigger an update.";
}
}
}
}
}
}
}
Acknowledgements
The authors of this document would like to thank Elwyn Davies, Alia Atlas, Brian E. Carpenter, Greg Mirsky, Adam Roach, Alissa Cooper, Eric Rescorla, Ben Campbell, Benoit Claise, Kathleen Moriarty, Carlos Pignataro, Benjamin Kaduk, and others for their substantive review, comments, and proposals to improve the document.
Authors' Addresses
Deepak Kumar CISCO Systems 510 McCarthy Blvd. Milpitas, CA 95035 United States of America Email: dekumar@cisco.com Michael Wang Huawei Technologies, Co., Ltd 101 Software Avenue, Yuhua District Nanjing 210012 China Email: wangzitao@huawei.com Qin Wu (editor) Huawei 101 Software Avenue, Yuhua District Nanjing, Jiangsu 210012 China Email: bill.wu@huawei.com Reshad Rahman CISCO Systems 2000 Innovation Drive Kanata, Ontario K2K 3E8 Canada Email: rrahman@cisco.com Srihari Raghavan CISCO Systems Tril Infopark Sez, Ramanujan IT City Neville Block, 2nd floor, Old Mahabalipuram Road Chennai, Tamil Nadu 600113 India Email: srihari@cisco.com