From 4bfd864f10b68b71482b35c818559068ef8d5797 Mon Sep 17 00:00:00 2001 From: Thomas Voss Date: Wed, 27 Nov 2024 20:54:24 +0100 Subject: doc: Add RFC documents --- doc/rfc/rfc7758.txt | 1795 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1795 insertions(+) create mode 100644 doc/rfc/rfc7758.txt (limited to 'doc/rfc/rfc7758.txt') diff --git a/doc/rfc/rfc7758.txt b/doc/rfc/rfc7758.txt new file mode 100644 index 0000000..d2715ab --- /dev/null +++ b/doc/rfc/rfc7758.txt @@ -0,0 +1,1795 @@ + + + + + + +Internet Engineering Task Force (IETF) T. Mizrahi +Request for Comments: 7758 Y. Moses +Category: Experimental Technion +ISSN: 2070-1721 February 2016 + + + Time Capability in NETCONF + +Abstract + + This document defines a capability-based extension to the Network + Configuration Protocol (NETCONF) that allows time-triggered + configuration and management operations. This extension allows + NETCONF clients to invoke configuration updates according to + scheduled times and allows NETCONF servers to attach timestamps to + the data they send to NETCONF clients. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + published for examination, experimental implementation, and + evaluation. + + This document defines an Experimental Protocol for the Internet + community. This document is a product of the Internet Engineering + Task Force (IETF). It represents the consensus of the IETF + community. It has received public review and has been approved for + publication by the Internet Engineering Steering Group (IESG). Not + all documents approved by the IESG are a candidate for any level of + Internet Standard; see Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7758. + + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 1] + +RFC 7758 Time Capability in NETCONF February 2016 + + +Copyright Notice + + Copyright (c) 2016 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 2] + +RFC 7758 Time Capability in NETCONF February 2016 + + +Table of Contents + + 1. Introduction ....................................................4 + 2. Conventions Used in This Document ...............................4 + 2.1. Key Words ..................................................4 + 2.2. Abbreviations ..............................................5 + 2.3. Terminology ................................................5 + 3. Using Time in NETCONF ...........................................5 + 3.1. The Time Capability in a Nutshell ..........................5 + 3.2. Notifications and Cancellation Messages ....................7 + 3.3. Synchronization Aspects ....................................9 + 3.4. Scheduled Time Format .....................................10 + 3.5. Scheduling Tolerance ......................................10 + 3.6. Scheduling the Near vs. Far Future ........................11 + 3.7. Time-Interval Format ......................................13 + 4. Time Capability ................................................14 + 4.1. Overview ..................................................14 + 4.2. Dependencies ..............................................14 + 4.3. Capability Identifier .....................................14 + 4.4. New Operations ............................................14 + 4.5. Modifications to Existing Operations ......................15 + 4.5.1. Affected Operations ................................15 + 4.5.2. Processing Scheduled Operations ....................16 + 4.6. Interactions with Other Capabilities ......................16 + 5. Examples .......................................................17 + 5.1. Example ..................................17 + 5.2. Example ........................................18 + 5.3. Error Example .............................................19 + 6. Security Considerations ........................................19 + 6.1. General Security Considerations ...........................19 + 6.2. YANG Module Security Considerations .......................20 + 7. IANA Considerations ............................................21 + 8. References .....................................................22 + 8.1. Normative References ......................................22 + 8.2. Informative References ....................................22 + Appendix A. YANG Module for the Time Capability ...................24 + Acknowledgments ...................................................32 + Authors' Addresses ................................................32 + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 3] + +RFC 7758 Time Capability in NETCONF February 2016 + + +1. Introduction + + The Network Configuration Protocol (NETCONF), defined in [RFC6241], + provides mechanisms to install, manipulate, and delete the + configuration of network devices. NETCONF allows clients to + configure and monitor NETCONF servers using remote procedure calls + (RPCs). + + NETCONF is asynchronous; when a client invokes an RPC, it has no + control over the time at which the RPC is executed, nor does it have + any feedback from the server about the execution time. + + Time-based configuration ([OneClock] [Time4]) can be a useful tool + that enables an entire class of coordinated and scheduled + configuration procedures. Time-triggered configuration allows + coordinated network updates in multiple devices; a client can invoke + a coordinated configuration change by sending RPCs to multiple + servers with the same scheduled execution time. A client can also + invoke a time-based sequence of updates by sending n RPCs with n + different update times, T1, T2, ..., Tn, determining the order in + which the RPCs are executed. + + This memo defines the :time capability in NETCONF. This extension + allows clients to determine the scheduled execution time of RPCs they + send. It also allows a server that receives an RPC to report its + actual execution time to the client. + + The NETCONF time capability is intended for scheduling RPCs that + should be performed in the near future, allowing the coordination of + simultaneous configuration changes or specification of an order of + configuration updates. Time-of-day-based policies and far-future + scheduling, e.g., [Cond], are outside the scope of this memo. + + This memo is defined for experimental purposes and will allow the + community to experiment with the NETCONF time capability. Based on + the lessons learned from this experience, it is expected that the + NETCONF working group will be able to consider whether to adopt the + time capability. + +2. Conventions Used in This Document + +2.1. Key Words + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + + + + +Mizrahi & Moses Experimental [Page 4] + +RFC 7758 Time Capability in NETCONF February 2016 + + +2.2. Abbreviations + + NETCONF Network Configuration Protocol + + RPC Remote Procedure Call + +2.3. Terminology + + o Capability [RFC6241]: A functionality that supplements the base + NETCONF specification. + + o Client [RFC6241]: Invokes protocol operations on a server. In + addition, a client can subscribe to receive notifications from a + server. + + o Execution time: The execution time of an RPC is defined as the + time at which a server completes the execution of an RPC, before + it sends the message. + + o Scheduled RPC: an RPC that is scheduled to be performed at a + predetermined time, which is included in the message. + + o Scheduled time: The scheduled time of an RPC is the time at which + the RPC should be started, as determined by the client. It is the + server's role to enforce the execution of the scheduled time. + + o Server [RFC6241]: Executes protocol operations invoked by a + client. In addition, a server can send notifications to a client. + +3. Using Time in NETCONF + +3.1. The Time Capability in a Nutshell + + The :time capability provides two main functions: + + o Scheduling: + + When a client sends an RPC to a server, the message MAY + include the scheduled-time element, denoted by Ts in Figure 1. + The server then executes the RPC at the scheduled time Ts; once + completed, the server can respond with an RPC reply message. + + + + + + + + + + +Mizrahi & Moses Experimental [Page 5] + +RFC 7758 Time Capability in NETCONF February 2016 + + + o Reporting: + + When a client sends an RPC to a server, the message MAY + include a get-time element (see Figure 2), requesting the server + to return the execution time of the RPC. In this case, after the + server performs the RPC, it responds with an RPC reply that + includes the execution time, Te. + + RPC _________ + executed \ + \/ + Ts + server ---------------+------------- ----> time + /\ \ + rpc / \ rpc-reply + (Ts)/ \ + / \/ + client ----------------------------- + + Figure 1: Scheduled RPC + + RPC _________ + executed \ + \/ + Te + server ------------+---------------- ----> time + /\ \ + rpc / \ rpc-reply + (get-time)/ \ (Te) + / \/ + client ----------------------------- + + Figure 2: Reporting the Execution Time of an RPC + + Example 1. A client needs to trigger a commit at n servers, so that + the n servers perform the commit as close as possible to + simultaneously. Without the time capability, the client sends a + sequence of n commit messages; thus, each server performs the commit + at a different time. By using the time capability, the client can + send commit messages that are scheduled to take place at a chosen + time Ts, for example, 5 seconds in the future, causing the servers to + invoke the commit as close as possible to time Ts. + + Example 2. In many applications, it is desirable to monitor events + or collect statistics regarding a common time reference. A client + can send a set of get-config messages that is scheduled to be + executed at multiple servers at the same time, providing a + + + + +Mizrahi & Moses Experimental [Page 6] + +RFC 7758 Time Capability in NETCONF February 2016 + + + simultaneous system-wide view of the state of the servers. Moreover, + a client can use the get-time element in its get-config messages, + providing a time reference to the sampled element. + + The scenarios of Figures 1 and 2 imply that a third scenario can also + be supported (Figure 3), where the client invokes an RPC that + includes a scheduled time, Ts, as well as the get-time element. This + allows the client to receive feedback about the actual execution + time, Te. Ideally, Ts=Te. However, the server may execute the RPC + at a slightly different time than Ts, for example, if the server is + tied up with other tasks at Ts. + + RPC _________ + executed \ + \/ + Ts Te + server -------------+-+------------- ----> time + /\ \ + rpc / \ rpc-reply + (Ts + get-time)/ \ (Te) + / \/ + client ----------------------------- + + Figure 3: Scheduling and Reporting + +3.2. Notifications and Cancellation Messages + + Notifications + + As illustrated in Figure 1, after a scheduled RPC is executed, the + server sends an . The may arrive a long + period of time after the RPC was sent by the client, leaving the + client without a clear indication of whether the RPC was received. + + This document defines a new notification, the netconf-scheduled- + message notification, which provides an immediate acknowledgement + of the scheduled RPC. + + The notification is sent to the client + if it is subscribed to the NETCONF notifications [RFC6470]; as + illustrated in Figure 4, when the server receives a scheduled RPC, + it sends a notification to the client. + + + + + + + + + +Mizrahi & Moses Experimental [Page 7] + +RFC 7758 Time Capability in NETCONF February 2016 + + + The notification includes a element. The is a unique identifier that the + server assigns to every scheduled RPC it receives. Thus, a client + can keep track of all the pending scheduled RPCs; a client can + uniquely identify a scheduled RPC by the tuple {server, schedule- + id}. + + RPC ____________ + executed \ + \/ + Ts + server -------------------+--------- ----> time + /\ \ \ + rpc / \notifi- \ rpc-reply + (Ts)/ \cation \ + / \/ \/ + client ----------------------------- + + Figure 4: Scheduled RPC with Notification + + Cancellation Messages + + A client can cancel a scheduled RPC by sending a + RPC. The RPC includes the of the + scheduled RPC that needs to be cancelled. + + The RPC, defined in this document, can be used + to perform a coordinated all-or-none procedure, where either all + the servers perform the operation on schedule or the operation is + aborted. + + Example 3. A client sends scheduled messages to server 1 + and server 2, both scheduled to be performed at time Ts. Server 1 + sends a notification indicating that it has successfully scheduled + the RPC, while server 2 replies with an unknown-element error + [RFC6241] that indicates that it does not support the time + capability. The client sends a RPC to server 1 + and receives an . The message exchange between the + client and server 1 in this example is illustrated in Figure 5. + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 8] + +RFC 7758 Time Capability in NETCONF February 2016 + + + RPC not __________ + executed \ + \/ + Ts + server --------------------------------+--- ----> time + /\ \ /\ \ + rpc / \notifi- /cancel- \ rpc-reply + (Ts)/ \cation /schedule \ + / \/ / \/ + client ------------------------------------ + + Figure 5: Cancellation Message + + A RPC MUST NOT include the scheduled-time + parameter. A server that receives a RPC should try + to cancel the schedule as soon as possible. If the server is unable + to cancel the scheduled RPC, for example, because it has already been + executed, it should respond with an [RFC6241], in which + the error-type is 'protocol', and the error-tag is 'operation- + failed'. + +3.3. Synchronization Aspects + + The time capability defined in this document requires clients and + servers to maintain clocks. It is assumed that clocks are + synchronized by a method that is outside the scope of this document, + e.g., [RFC5905] or [IEEE1588]. + + This document does not define any requirements pertaining to the + degree of accuracy of performing scheduled RPCs. Note that two + factors affect how accurately the server can perform a scheduled RPC: + one factor is the accuracy of the clock synchronization method used + to synchronize the clients and servers and the second factor is the + server's ability to execute real-time configuration changes, which + greatly depends on how it is implemented. Typical networking devices + are implemented by a combination of hardware and software. While the + execution time of a hardware module can typically be predicted with a + high level of accuracy, the execution time of a software module may + be variable and hard to predict. A configuration update would + typically require the server's software to be involved, thus + affecting how accurately the RPC can be scheduled. + + Another important aspect of synchronization is monitoring; a client + should be able to check whether a server is synchronized to a + reference time source. Typical synchronization protocols, such as + the Network Time Protocol [RFC5905], provide the means ([RFC5907], + [RFC7317]) to verify that a clock is synchronized to a time reference + by querying its Management Information Base (MIB). The get-time + + + +Mizrahi & Moses Experimental [Page 9] + +RFC 7758 Time Capability in NETCONF February 2016 + + + feature defined in this document (see Figure 2) allows a client to + obtain a rough estimate of the time offset between the client's clock + and the server's clock. + + Since servers do not perform configuration changes instantaneously, + the processing time of an RPC should not be overlooked. The + scheduled time always refers to the start time of the RPC, and the + execution time always refers to its completion time. + +3.4. Scheduled Time Format + + The scheduled time and execution time fields in messages use a + common time format field. + + The time format used in this document is the date-and-time format, + defined in Section 5.6 of [RFC3339] and Section 3 of [RFC6991]. + + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + +3.5. Scheduling Tolerance + + When a client sends an RPC that is scheduled to Ts, the server MUST + verify that the value Ts is not too far in the past or in the future. + As illustrated in Figure 6, the server verifies that Ts is within the + scheduling-tolerance range. + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 10] + +RFC 7758 Time Capability in NETCONF February 2016 + + + RPC _________ + received \ + \/ + Ts + -----+--------------+-----+------------+-------> time + + <------------> <----------------> + sched-max-past sched-max-future + + <-------------------------------> + scheduling tolerance + + Figure 6: Scheduling Tolerance + + The scheduling tolerance is determined by two parameters: sched-max- + future and sched-max-past. These two parameters use the time- + interval format (Section 3.7.), and their default value is 15 + seconds. + + If the scheduled time, Ts, is within the scheduling-tolerance range, + the scheduled RPC is performed; if Ts occurs in the past and within + the scheduling tolerance, the server performs the RPC as soon as + possible; whereas if Ts is a future time, the server performs the RPC + at Ts. + + If Ts is not within the scheduling-tolerance range, the scheduled RPC + is discarded, and the server responds with an error message [RFC6241] + including a bad-element error-tag. An example is provided in Section + 5.3. + +3.6. Scheduling the Near vs. Far Future + + The scheduling bound defined by sched-max-future guarantees that + every scheduled RPC is restricted to a scheduling time in the near + future. + + The scheduling mechanism defined in this document is intended for + near-future scheduling, on the order of seconds. Far-future + scheduling is outside the scope of this document. + + Example 1 is a typical example of using near-future scheduling; the + goal in the example is to perform the RPC at multiple servers at the + same time; therefore, it is best to schedule the RPC to be performed + a few seconds in the future. + + + + + + + +Mizrahi & Moses Experimental [Page 11] + +RFC 7758 Time Capability in NETCONF February 2016 + + + The Challenges of Far-Future Scheduling + + When an RPC is scheduled to be performed at a far-future time, + during the long period between the time at which the RPC is sent + and the time at which it is scheduled to be executed, the + following erroneous events may occur: + + o The server may restart. + + o The client's authorization level may be changed. + + o The client may restart and send a conflicting RPC. + + o A different client may send a conflicting RPC. + + In these cases, if the server performs the scheduled operation, it + may perform an action that is inconsistent with the current + network policy or inconsistent with the currently active clients. + + Near-future scheduling guarantees that external events, such as + the examples above, have a low probability of occurring during the + sched-max-future period, and even when they do, the period of + inconsistency is limited to sched-max-future, which is a short + period of time. + + The Trade-off in Setting the sched-max-future Value + + The sched-max-future parameter should be configured to a value + that is high enough to allow the client to: + + 1. Send the scheduled RPC, potentially to multiple servers. + + 2. Receive notifications or messages from the + server(s) or wait for a timeout and decide that if no response + has arrived then something is wrong. + + 3. If necessary, send a cancellation message, potentially to + multiple servers. + + On the other hand, sched-max-future should be configured to a + value that is low enough to allow a low probability of the + erroneous events above, typically on the order of a few seconds. + Note that, even if sched-max-future is configured to a low value, + it is still possible (with a low probability) that an erroneous + event will occur. However, this short, potentially hazardous + period is not significantly worse than in conventional + (unscheduled) RPCs, as even a conventional RPC may in some cases + be executed a few seconds after it was sent by the client. + + + +Mizrahi & Moses Experimental [Page 12] + +RFC 7758 Time Capability in NETCONF February 2016 + + + The Default Value of sched-max-future + + The default value of sched-max-future is defined to be 15 seconds. + This duration is long enough to allow the scheduled RPC to be sent + by the client, potentially to multiple servers, and in some cases + to send a cancellation message, as described in Section 3.2. On + the other hand, the 15-second duration yields a very low + probability of a reboot or a permission change. + +3.7. Time-Interval Format + + The time-interval format is used for representing the length of a + time interval and is based on the date-and-time format. It is used + for representing the scheduling tolerance parameters, as described in + the previous section. + + While the date-and-time type uniquely represents a specific point in + time, the time-interval type defined below can be used to represent + the length of a time interval without specifying a specific date. + + The time-interval type is defined as follows: + + typedef time-interval { + type string { + pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; + } + description + "Defines a time interval, up to 24 hours. + The format is specified as HH:mm:ss.f, + consisting of two digits for hours, + two digits for minutes, two digits + for seconds, and zero or more digits + representing second fractions."; + } + + Example + + The sched-max-future parameter is defined (Appendix A) as a time- + interval, as follows: + + leaf sched-max-future { + type time-interval; + default 00:00:15.0; + } + + The default value specified for sched-max-future is 0 hours, 0 + minutes, and 15 seconds. + + + + +Mizrahi & Moses Experimental [Page 13] + +RFC 7758 Time Capability in NETCONF February 2016 + + +4. Time Capability + + The structure of this section is as defined in Appendix D of + [RFC6241]. + +4.1. Overview + + A server that supports the time capability can perform time-triggered + operations as defined in this document. + + A server implementing the :time capability: + + o MUST support the ability to receive messages that include a + time element and perform a time-triggered operation accordingly. + + o MUST support the ability to include a time element in the messages that it transmits. + +4.2. Dependencies + + With-defaults Capability + + The time-capability YANG module (Appendix A) uses default values; + thus, it is assumed that the with-defaults capability [RFC6243] is + supported. + +4.3. Capability Identifier + + The :time capability is identified by the following capability + string: + + urn:ietf:params:netconf:capability:time:1.0 + +4.4. New Operations + + + + The RPC is used for cancelling an RPC that was + previously scheduled. + + A RPC MUST include the + element, which specifies the message ID of the scheduled RPC that + needs to be cancelled. + + A RPC MAY include the element. In + this case, the includes the element, + specifying the time at which the scheduled RPC was cancelled. + + + + +Mizrahi & Moses Experimental [Page 14] + +RFC 7758 Time Capability in NETCONF February 2016 + + +4.5. Modifications to Existing Operations + +4.5.1. Affected Operations + + The :time capability defined in this memo can be applied to any of + the following operations: + + o get-config + + o get + + o copy-config + + o edit-config + + o delete-config + + o lock + + o unlock + + o commit + + Three new elements are added to each of these operations: + + o This element is added to the input of each + operation, indicating the time at which the server is scheduled to + invoke the operation. Every message MAY include the + element. A server that supports the :time + capability and receives an message with a + element MUST perform the operation as close as possible to the + scheduled time. + + The element uses the date-and-time format + (Section 3.4.). + + o This element is added to the input of each operation. + An message MAY include a element, indicating that + the server MUST include an element in its + corresponding . + + o This element is added to the output of each + operation, indicating the time at which the server completed the + operation. An MAY include the + element. A server that supports the :time capability and receives + an operation with the element MUST include the + execution time in its response. + + + + +Mizrahi & Moses Experimental [Page 15] + +RFC 7758 Time Capability in NETCONF February 2016 + + + The element uses the date-and-time format + (Section 3.4.). + +4.5.2. Processing Scheduled Operations + + A server that receives a scheduled RPC MUST start executing the RPC + as close as possible to its scheduled execution time. + + If a session between a client and a server is terminated, the server + MUST cancel all pending scheduled RPCs that were received in this + session. + + Scheduled RPCs are processed serially, in an order that is defined by + their scheduled times. Thus, the server sends messages + to scheduled RPCs according to the order of their corresponding + schedules. Note that this is a modification to the behavior defined + in [RFC6241], which states that replies are sent in the order the + requests were received. Interoperability with [RFC6241] is + guaranteed by the NETCONF capability exchange; a server that does not + support the :time capability responds to RPCs in the order the + requests were received. A server that supports the :time capability + replies to conventional (non-scheduled) RPCs in the order they were + received and replies to scheduled RPCs in the order of their + scheduled times. + + If a server receives two or more RPCs that are scheduled to be + performed at the same time, the server executes the RPCs serially in + an arbitrary order. + +4.6. Interactions with Other Capabilities + + Confirmed Commit Capability + + The confirmed commit capability is defined in Section 8.4 of + [RFC6241]. According to that document, a confirmed + operation MUST be reverted if a confirming commit is not issued + within the timeout period (which is 600 seconds by default). + + When the time capability is supported, and a confirmed + operation is used with the element, the + confirmation timeout MUST be counted from the scheduled time, + i.e., the client begins the timeout measurement starting at the + scheduled time. + + + + + + + + +Mizrahi & Moses Experimental [Page 16] + +RFC 7758 Time Capability in NETCONF February 2016 + + +5. Examples + +5.1. Example + + The following example extends the example presented in Section 7.2 of + [RFC6241] by adding the time capability. In this example, the + element is used to specify the scheduled execution + time of the configuration update (as shown in Figure 1). + + + + + + + + 2015-10-21T04:29:00.235Z + + + + + Ethernet0/0 + 1500 + + + + + + + + + + + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 17] + +RFC 7758 Time Capability in NETCONF February 2016 + + +5.2. Example + + The following example is similar to the one presented in Section 5.1, + except that, in this example, the client includes a + element in its RPC and the server consequently responds with an + element (as shown in Figure 2). + + + + + + + + + + + + Ethernet0/0 + 1500 + + + + + + + + + + 2015-10-21T04:29:00.235Z + + + + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 18] + +RFC 7758 Time Capability in NETCONF February 2016 + + +5.3. Error Example + + The following example presents a scenario in which the scheduled-time + is not within the scheduling tolerance, i.e., it is too far in the + past; therefore, an is returned. + + + + + + + + 2010-10-21T04:29:00.235Z + + + + + Ethernet0/0 + 1500 + + + + + + + + + application + bad-element + error + + scheduled-time + + + + +6. Security Considerations + +6.1. General Security Considerations + + The security considerations of the NETCONF protocol in general are + discussed in [RFC6241]. + + + + + + +Mizrahi & Moses Experimental [Page 19] + +RFC 7758 Time Capability in NETCONF February 2016 + + + The usage of the time capability defined in this document can assist + an attacker in gathering information about the system, such as the + exact time of future configuration changes. Moreover, the time + elements can potentially allow an attacker to learn information about + the system's performance. Furthermore, an attacker that sends + malicious messages can use the time capability to amplify her + attack; for example, by sending multiple messages with the same + scheduled time. It is important to note that the security measures + described in [RFC6241] can prevent these vulnerabilities. + + The time capability relies on an underlying time synchronization + protocol. Thus, by attacking the time protocol, an attack can + potentially compromise NETCONF when using the time capability. A + detailed discussion about the threats against time protocols and how + to mitigate them is presented in [RFC7384]. + + The time capability can allow an attacker to attack a NETCONF server + by sending malicious RPCs that are scheduled to take place in the + future. For example, an attacker can send multiple scheduled RPCs + that are scheduled to be performed at the same time. Another + possible attack is to send a large number of scheduled RPCs to a + NETCONF server, potentially causing the server's buffers to overflow. + These attacks can be mitigated by a carefully designed NETCONF + server; when a server receives a scheduled RPC that exceeds its + currently available resources, it should reply with an + and discard the scheduled RPC. + + Note that if an attacker has been detected and revoked, its future + scheduled RPCs are not executed; as defined in Section 4.5.2, once + the session with the attacker has been terminated, the corresponding + scheduled RPCs are discarded. + +6.2. YANG Module Security Considerations + + This memo defines a new YANG module, as specified in Appendix A. + + The YANG module defined in this memo is designed to be accessed via + the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the + secure transport layer and the mandatory-to-implement secure + transport is Secure SHell (SSH) [RFC6242]. The NETCONF access + control model [RFC6536] provides the means to restrict access for + particular NETCONF users to a preconfigured subset of all available + NETCONF protocol operations and content. + + This YANG module defines and , + which are writable/creatable/deletable. These data nodes may be + considered sensitive or vulnerable in some network environments. An + attacker may attempt to maliciously configure these parameters to a + + + +Mizrahi & Moses Experimental [Page 20] + +RFC 7758 Time Capability in NETCONF February 2016 + + + low value, thereby causing all scheduled RPCs to be discarded. For + instance, if a client expects to be 15 seconds, + but in practice it is maliciously configured to 1 second, then a + legitimate scheduled RPC that is scheduled to be performed 5 seconds + in the future will be discarded by the server. + + This YANG module defines the RPC. This RPC may be + considered sensitive or vulnerable in some network environments. + Since the value of the is known to all the clients that + are subscribed to notifications from the server, the RPC may be used maliciously to attack servers by cancelling + their pending RPCs. This attack is addressed in two layers: (i) + security at the transport layer, limiting the attack only to clients + that have successfully initiated a secure session with the server, + and (ii) the authorization level required to cancel an RPC should be + the same as the level required to schedule it, limiting the attack + only to attackers with an authorization level that is equal to or + higher than that of the client that initiated the scheduled RPC. + +7. IANA Considerations + + The following capability identifier URN has been registered in the + "Network Configuration Protocol (NETCONF) Capability URNs" registry: + + urn:ietf:params:netconf:capability:time:1.0 + + The following XML namespace URN has been registered in the "IETF XML + Registry", following the format defined in [RFC3688]: + + URI: urn:ietf:params:xml:ns:yang:ietf-netconf-time + + Registrant Contact: The IESG. + + XML: N/A, the requested URI is an XML namespace. + + The following module name has been registered in the "YANG Module + Names" registry, defined in [RFC6020]. + + name: ietf-netconf-time + + prefix: nct + + namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-time + + RFC: 7758 + + + + + + +Mizrahi & Moses Experimental [Page 21] + +RFC 7758 Time Capability in NETCONF February 2016 + + +8. References + +8.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, + . + + [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: + Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, + . + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, + RFC 3688, DOI 10.17487/RFC3688, January 2004, + . + + [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, + . + + [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) + Base Notifications", RFC 6470, DOI 10.17487/RFC6470, + February 2012, + . + + [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6991, DOI 10.17487/RFC6991, July 2013, + . + +8.2. Informative References + + [Cond] Watsen, K., "Conditional Enablement of Configuration + Nodes", draft-kwatsen-conditional-enablement-00, Work in + Progress, February 2013. + + [IEEE1588] IEEE, "IEEE Standard for a Precision Clock + Synchronization Protocol for Networked Measurement and + Control Systems Version 2", IEEE Standard 1588. + + [OneClock] Mizrahi, T. and Y. Moses, "OneClock to Rule Them All: + Using Time in Networked Applications", IEEE/IFIP Network + Operations and Management Symposium (NOMS), 2016. + + + + + + + +Mizrahi & Moses Experimental [Page 22] + +RFC 7758 Time Capability in NETCONF February 2016 + + + [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, + "Network Time Protocol Version 4: Protocol and Algorithms + Specification", RFC 5905, + DOI 10.17487/RFC5905, June 2010, + . + + [RFC5907] Gerstung, H., Elliott, C., and B. Haberman, Ed., + "Definitions of Managed Objects for Network Time Protocol + Version 4 (NTPv4)", RFC 5907, + DOI 10.17487/RFC5907, June 2010, + . + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", + RFC 6020, DOI 10.17487/RFC6020, October 2010, + . + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + . + + [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for + NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, + . + + [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration + Protocol (NETCONF) Access Control Model", RFC 6536, DOI + 10.17487/RFC6536, March 2012, + . + + [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for + System Management", RFC 7317, DOI 10.17487/RFC7317, + August 2014, . + + [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in + Packet Switched Networks", RFC 7384, + DOI 10.17487/RFC7384, October 2014, + . + + [Time4] Mizrahi, T. and Y. Moses, "Software Defined Networks: + It's About Time", IEEE INFOCOM, 2016. + + + + + + + + + + +Mizrahi & Moses Experimental [Page 23] + +RFC 7758 Time Capability in NETCONF February 2016 + + +Appendix A. YANG Module for the Time Capability + + This section is normative. + + file "ietf-netconf-time@2016-01-26.yang" + +module ietf-netconf-time { + + namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-time"; + + prefix nct; + import ietf-netconf { prefix nc; } + + import ietf-yang-types { prefix yang; } + + import ietf-netconf-monitoring { prefix ncm; } + + organization + "IETF"; + + contact + "Editor: Tal Mizrahi + + Editor: Yoram Moses + "; + + description + "This module defines a capability-based extension to the + Network Configuration Protocol (NETCONF) that allows + time-triggered configuration and management operations. + This extension allows NETCONF clients to invoke configuration + updates according to scheduled times and allows NETCONF + servers to attach timestamps to the data they send to NETCONF + clients. + + Copyright (c) 2016 IETF Trust and the persons identified as + the authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info)."; + + revision 2016-01-26 { + description + "Initial version."; + + + +Mizrahi & Moses Experimental [Page 24] + +RFC 7758 Time Capability in NETCONF February 2016 + + + reference + "RFC 7758: + Time Capability in NETCONF"; + } + + typedef time-interval { + type string { + pattern '\d{2}:\d{2}:\d{2}(\.\d+)?'; + } + description + "Defines a time interval, up to 24 hours. + The format is specified as HH:mm:ss.f, + consisting of two digits for hours, + two digits for minutes, two digits + for seconds, and zero or more digits + representing second fractions."; + } + + grouping scheduling-tolerance-parameters { + leaf sched-max-future { + type time-interval; + default 00:00:15.0; + description + "When the scheduled time is in the future, i.e., greater + than the present time, this leaf defines the maximal + difference between the scheduled time + and the present time that the server is willing to + accept. If the difference exceeds this number, the + server responds with an error."; + } + + leaf sched-max-past { + type time-interval; + default 00:00:15.0; + description + "When the scheduled time is in the past, i.e., less + than the present time, this leaf defines the maximal + difference between the present time + and the scheduled time that the server is willing to + accept. If the difference exceeds this number, the + server responds with an error."; + } + + description + "Contains the parameters of the scheduling tolerance."; + } + // extending the get-config operation + augment /nc:get-config/nc:input { + + + +Mizrahi & Moses Experimental [Page 25] + +RFC 7758 Time Capability in NETCONF February 2016 + + + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:get-config/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /nc:get/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:get/nc:output { + leaf execution-time { + + + +Mizrahi & Moses Experimental [Page 26] + +RFC 7758 Time Capability in NETCONF February 2016 + + + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /nc:copy-config/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:copy-config/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /nc:edit-config/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + + + +Mizrahi & Moses Experimental [Page 27] + +RFC 7758 Time Capability in NETCONF February 2016 + + + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:edit-config/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /nc:delete-config/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:delete-config/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + description + "Adds the time element to ."; + } + + augment /nc:lock/nc:input { + + + +Mizrahi & Moses Experimental [Page 28] + +RFC 7758 Time Capability in NETCONF February 2016 + + + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + augment /nc:lock/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /nc:unlock/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:unlock/nc:output { + leaf execution-time { + type yang:date-and-time; + + + +Mizrahi & Moses Experimental [Page 29] + +RFC 7758 Time Capability in NETCONF February 2016 + + + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + augment /nc:commit/nc:input { + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include the + execution-time."; + } + + description + "Adds the time element to ."; + } + + augment /nc:commit/nc:output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + + description + "Adds the time element to ."; + } + + augment /ncm:netconf-state { + container scheduling-tolerance { + uses scheduling-tolerance-parameters; + description + "The scheduling tolerance when the time capability + is enabled."; + } + description + "The scheduling tolerance of the server."; + } + + rpc cancel-schedule { + + + +Mizrahi & Moses Experimental [Page 30] + +RFC 7758 Time Capability in NETCONF February 2016 + + + description + "Cancels a scheduled message."; + reference + "RFC 7758: + Time Capability in NETCONF"; + + input { + leaf cancelled-message-id { + type string; + description + "The ID of the message to be cancelled."; + } + leaf get-time { + type empty; + description + "Indicates that the rpc-reply should include + the execution-time."; + } + } + output { + leaf execution-time { + type yang:date-and-time; + description + "The time at which the RPC was executed."; + } + } + } + + notification netconf-scheduled-message { + leaf schedule-id { + type string; + description + "The ID of the scheduled message."; + } + + leaf scheduled-time { + type yang:date-and-time; + description + "The time at which the RPC is scheduled to be performed."; + } + description + "Indicates that a scheduled message was received."; + reference + "RFC 7758: + Time Capability in NETCONF"; + } + +} + + + +Mizrahi & Moses Experimental [Page 31] + +RFC 7758 Time Capability in NETCONF February 2016 + + + + +Acknowledgments + + The authors gratefully acknowledge Joe Marcus Clarke, Andy Bierman, + Balazs Lengyel, Jonathan Hansford, John Heasley, Robert Sparks, Al + Morton, Olafur Gudmundsson, Juergen Schoenwaelder, Joel Jaeggli, Alon + Schneider, and Eylon Egozi for their insightful comments. + + This work was supported in part by Israel Science Foundation grant + ISF 1520/11. + +Authors' Addresses + + Tal Mizrahi + Department of Electrical Engineering + Technion - Israel Institute of Technology + Technion City, Haifa, 32000 + Israel + + Email: dew@tx.technion.ac.il + + + Yoram Moses + Department of Electrical Engineering + Technion - Israel Institute of Technology + Technion City, Haifa, 32000 + Israel + + Email: moses@ee.technion.ac.il + + + + + + + + + + + + + + + + + + + + + +Mizrahi & Moses Experimental [Page 32] + -- cgit v1.2.3