RFC 7758
Time Capability in NETCONF
Time Capability in NETCONF 💖
Internet Engineering Task Force (IETF) · Request for Comments: 7758 · February 2016 · Category: Experimental · ISSN: 2070-1721
okay so bestie, this RFC is by T. Mizrahi and Y. Moses from the Technion 🎀 It's an Experimental doc (not a Standards Track thing!), published in February 2016 🌸 It doesn't obsolete or update any other RFCs, so it's its own little world ✨ and it's all about adding a time capability to NETCONF ⏰
Abstract
okay so the vibe here is: this doc adds a capability-based extension to the Network Configuration Protocol (NETCONF) 🦋 It lets clients schedule configuration updates for specific times, and lets servers stamp the data they send back with timestamps 🕰️ literally time-travel energy but make it networking 💅
Status of This Memo
ngl this section is the "is this official??" part 🙈 It's not an Internet Standards Track spec. It's published so people can look at it, try implementing it, and evaluate it 🧪 It IS an Experimental Protocol for the Internet community, a product of the IETF, and it has consensus, public review, and IESG approval 👑 but not every IESG-approved doc is up for any level of Internet Standard, so see Section 2 of RFC 5741 for the deets 🌈
Current status, errata, and feedback info live at http://www.rfc-editor.org/info/rfc7758 💜
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved ✨
This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as of the publication date. Read those carefully, because they spell out your rights and restrictions 📜 Any Code Components pulled from this doc must include Simplified BSD License text (per Section 4.e of the Trust Legal Provisions) and come with no warranty, same as that license says 🧾
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. <scheduled-time> Example ..................................17
5.2. <get-time> 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 ................................................321. Introduction 🌸
1.1. Hmm, just Introduction
okay so NETCONF (from [RFC6241]) is how you install, change, and delete config on network devices 🔧 Clients poke servers with remote procedure calls (RPCs) 📞
BUT here's the tea: NETCONF is asynchronous 😭 When a client sends an RPC, it has zero control over when it actually runs, and the server doesn't tell it when it ran either 💀
Time-based config ([OneClock] [Time4]) is lowkey a game changer 🦋 It makes a whole class of coordinated, scheduled config jobs possible ✨ A client can send RPCs to multiple servers all with the same scheduled time, so the network updates together 👯 Or it can send n RPCs with n different times, T1, T2, ..., Tn, to set the order they run in 🎀
This memo defines the :time capability for NETCONF 💅 Clients can figure out the scheduled execution time of the RPCs they send, and a server that gets an RPC can report its actual execution time back to the client 🫶
The time capability is meant for scheduling stuff in the near future, so you can coordinate simultaneous changes or set an order for updates 🚀 Time-of-day policies and far-future scheduling (like [Cond]) are NOT in scope here 🙅♀️
This memo is experimental 🧪 The point is to let the community try out the NETCONF time capability, and then the NETCONF working group will look at what they learned and decide whether to adopt it 🌈
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] 📖
2.2. Abbreviations 🔤
NETCONF Network Configuration Protocol
RPC Remote Procedure Call2.3. Terminology 📚
- Capability [RFC6241]: a functionality that supplements the base NETCONF spec ✨
- Client [RFC6241]: invokes protocol operations on a server, and can also subscribe to get notifications from a server 🔔
- Execution time: the time at which a server finishes executing an RPC, before it sends the
<rpc-reply>message 🏁 - Scheduled RPC: an RPC scheduled to run at a predetermined time, which is included in the
<rpc>message 📅 - Scheduled time: the time the RPC should start, as decided by the client. The server's job is to enforce it 🎯
- Server [RFC6241]: executes protocol operations a client invokes, and can also send notifications to a client 💌
3. Using Time in NETCONF ⏰
3.1. The Time Capability in a Nutshell 🥰
The :time capability has two main jobs 💖
- Scheduling: when a client sends an RPC, the
<rpc>message MAY include the scheduled-time element, shown as Ts in Figure 1 📅 The server then runs the RPC at the scheduled time Ts, and once it's done, it can reply with an RPC reply message 💫 - Reporting: when a client sends an RPC, the
<rpc>message MAY include a get-time element (see Figure 2) asking the server to tell it the RPC's execution time 🕵️♀️ After the server does the RPC, the reply 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 RPCExample 1. Say a client needs to trigger a commit on n servers, and wants them all to commit as close to simultaneously as possible 🤩 Without the time capability, the client sends n commit messages one after another, so every server commits at a different time 😩 With the time capability, the client sends commit messages scheduled for one chosen time Ts (like 5 seconds from now), and the servers commit as close to Ts as they can 🎉
Example 2. Monitoring events or collecting stats usually needs a common time reference 📊 A client can send a set of get-config messages scheduled to run at multiple servers at the same time, which gives a simultaneous, system-wide snapshot of the servers' state 📸 Plus, the client can use the get-time element in its get-config messages, so the sampled data has a time reference attached 🏷️
Figures 1 and 2 imply a third scenario (Figure 3), where the client sends an RPC with BOTH a scheduled time, Ts, AND the get-time element 🙌 That way the client gets feedback on the actual execution time, Te 🔍 Ideally Ts=Te 💯 But the server might run the RPC a bit off from Ts, for example if it's busy with other tasks right at Ts 😅
RPC _________
executed \
\/
Ts Te
server -------------+-+------------- ----> time
/\ \
rpc / \ rpc-reply
(Ts + get-time)/ \ (Te)
/ \/
client -----------------------------
Figure 3: Scheduling and Reporting(Part 1 of 5. More to come, bestie! 🫶)
3.2. Notifications and Cancellation Messages ✨
Notifications 🔔
Okay so, as Figure 1 shows, once a scheduled RPC gets executed, the server sends back an <rpc-reply> 📬. Here's the catch: that <rpc-reply> can show up a long time after the client sent the RPC 😭. So the client is just sitting there with no clue whether the RPC was even received 🫠.
This document defines a new notification, the netconf-scheduled-message notification 🎀. It gives the client an immediate acknowledgement of the scheduled RPC, so no more guessing ✨.
The <netconf-scheduled-message> notification is sent to the client if it's subscribed to the NETCONF notifications [RFC6470] 💌. As Figure 4 shows, when the server receives a scheduled RPC, it sends a notification to the client 🦋.
The <netconf-scheduled-message> notification includes a <schedule-id> element 🪪. The <schedule-id> is a unique identifier that the server assigns to every scheduled RPC it receives 💜. This is what makes tracking easy, bestie: a client can keep track of all its 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 NotificationCancellation Messages 🙅♀️
A client can cancel a scheduled RPC by sending a <cancel-schedule> RPC 🛑. The <cancel-schedule> RPC includes the <schedule-id> of the scheduled RPC that needs to be cancelled 🪄.
The <cancel-schedule> RPC, defined in this document, can be used to perform a coordinated all-or-none procedure 🤝. Either all the servers perform the operation on schedule, or the operation is aborted. No in-between chaos, periodt 💅.
Example 3. A client sends scheduled <rpc> 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 🎉. Server 2 replies with an unknown-element error [RFC6241] that indicates that it does not support the time capability 💀. The client sends a <cancel-schedule> RPC to server 1 and receives an <rpc-reply> 🫶. The message exchange between the client and server 1 in this example is illustrated in Figure 5 🎀.
RPC not __________
executed \
\/
Ts
server --------------------------------+--- ----> time
/\ \ /\ \
rpc / \notifi- /cancel- \ rpc-reply
(Ts)/ \cation /schedule \
/ \/ / \/
client ------------------------------------
Figure 5: Cancellation MessageA <cancel-schedule> RPC MUST NOT include the scheduled-time parameter. 🌈 A server that receives a <cancel-schedule> 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 <rpc-error> [RFC6241] 🙈. In that error, 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's assumed that clocks are synchronized by a method that's 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 🤷♀️. Two factors affect how accurately the server can perform a scheduled RPC 🎯. The first factor is the accuracy of the clock synchronization method used to synchronize the clients and servers. The second is the server's ability to execute real-time configuration changes, which really depends on how it's implemented 🛠️.
Typical networking devices are a combination of hardware and software 🖥️. The execution time of a hardware module can typically be predicted with a high level of accuracy 🎯. The execution time of a software module, though? It may be variable and hard to predict 😵💫. A configuration update would typically require the server's software to be involved, so that affects 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 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 don't 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 <rpc> 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's scheduled to Ts, the server MUST verify that the value Ts is not too far in the past or in the future. 🚦 As Figure 6 illustrates, the server verifies that Ts is within the scheduling-tolerance range 🔎.
RPC _________
received \
\/
Ts
-----+--------------+-----+------------+-------> time
<------------> <---------------->
sched-max-past sched-max-future
<------------------------------->
scheduling tolerance
Figure 6: Scheduling ToleranceThe 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 🏃♀️. 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 🗑️. The server responds with an error message [RFC6241] that includes 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, so it's best to schedule the RPC to be performed a few seconds in the future 🫶.
The Challenges of Far-Future Scheduling 😰
When an RPC is scheduled to be performed at a far-future time, a lot can happen in the long gap between when the RPC is sent and when it's scheduled to run 🕸️. The following erroneous events may occur:
- The server may restart. 🔄
- The client's authorization level may be changed. 🔐
- The client may restart and send a conflicting RPC. 💥
- 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 🍀. 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:
- Send the scheduled RPC, potentially to multiple servers. 📤
- Receive notifications or <rpc-error> messages from the server(s), or wait for a timeout and decide that if no response has arrived then something is wrong. 📬
- 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 🧊. Even if sched-max-future is configured to a low value, it's 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 😌. Even a conventional RPC may in some cases be executed a few seconds after it was sent by the client 💅.
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 ⏳
okay so the time-interval format is all about how long something lasts 🕰️ It's built on the date-and-time format 💅 and it's what we use for the scheduling tolerance parameters from the last bit.
while the date-and-time type pins down one exact moment ⏰, the time-interval type just tells you the length of a stretch of time without attaching any specific date. 🦋
here's how the time-interval type is defined:
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, like so:
leaf sched-max-future {
type time-interval;
default 00:00:15.0;
}the default value for sched-max-future is 0 hours, 0 minutes, and 15 seconds. ✨
4. Time Capability ✨
the structure of this section follows 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:
- MUST support the ability to receive
<rpc>messages that include a time element and perform a time-triggered operation accordingly. - MUST support the ability to include a time element in the
<rpc-reply>messages that it transmits.
4.2. Dependencies 🫶
With-defaults Capability
the time-capability YANG module (Appendix A) uses default values, so it's 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.04.4. New Operations 🍓
<cancel-schedule> 🚫
the <cancel-schedule> RPC is used for cancelling an RPC that was previously scheduled. 💅
a <cancel-schedule> RPC MUST include the <cancelled-message-id> element, which specifies the message ID of the scheduled RPC that needs to be cancelled. 😭
a <cancel-schedule> RPC MAY include the <get-time> element. in this case, the <rpc-reply> includes the <execution-time> element, specifying the time at which the scheduled RPC was cancelled. ⏱️
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:
get-configgetcopy-configedit-configdelete-configlockunlockcommit
three new elements get added to each of these operations: 🎉
<scheduled-time>This element is added to the input of each operation, indicating the time at which the server is scheduled to invoke the operation. Every<rpc>message MAY include the<scheduled-time>element. A server that supports the:timecapability and receives an<rpc>message with a<scheduled-time>element MUST perform the operation as close as possible to the scheduled time.
The <scheduled-time> element uses the date-and-time format (Section 3.4.).
<get-time>This element is added to the input of each operation. An<rpc>message MAY include a<get-time>element, indicating that the server MUST include an<execution-time>element in its corresponding<rpc-reply>.<execution-time>This element is added to the output of each operation, indicating the time at which the server completed the operation. An<rpc-reply>MAY include the<execution-time>element. A server that supports the:timecapability and receives an operation with the<get-time>element MUST include the execution time in its response.
The <execution-time> 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 gets terminated, the server MUST cancel all pending scheduled RPCs that were received in this session. 🙈
scheduled RPCs are processed serially, in an order defined by their scheduled times. so the server sends <rpc-reply> 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 <commit> 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 <commit> operation is used with the <scheduled-time> element, the confirmation timeout MUST be counted from the scheduled time, i.e., the client begins the timeout measurement starting at the scheduled time. ⏳✨
5. Examples 📚
5.1. <scheduled-time> Example 💖
this example extends the one in Section 7.2 of [RFC6241] by adding the time capability. here, the <scheduled-time> element is used to specify the scheduled execution time of the configuration update (as shown in Figure 1). 🎀
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<scheduled-time
xmlns="urn:ietf:params:yang:ietf-netconf-time">
2015-10-21T04:29:00.235Z
</scheduled-time>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>5.2. <get-time> Example 🧚
this one's basically the same as the example in Section 5.1, except this time the client includes a <get-time> element in its RPC, so the server responds with an <execution-time> element (as shown in Figure 2). 🦋
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<get-time
xmlns="urn:ietf:params:yang:ietf-netconf-time">
</get-time>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
<execution-time>
2015-10-21T04:29:00.235Z
</execution-time>
</rpc-reply>5.3. Error Example 💀
this example shows a scenario where the scheduled-time is not within the scheduling tolerance, i.e., it's too far in the past, so an <rpc-error> gets returned. 🙅♀️
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<scheduled-time
xmlns="urn:ietf:params:yang:ietf-netconf-time">
2010-10-21T04:29:00.235Z
</scheduled-time>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>bad-element</error-tag>
<error-severity>error</error-severity>
<error-info>
<bad-element>scheduled-time</bad-element>
</error-info>
</rpc-error>
</rpc-reply>6. Security Considerations 🔐
6.1. General Security Considerations 🚨
the security considerations of the NETCONF protocol in general are discussed in [RFC6241]. 📖
using the time capability defined in this document can help an attacker gather information about the system, like the exact time of future configuration changes. 👀 the time elements can also potentially let an attacker learn information about the system's performance. and here's the spicy part: an attacker who sends malicious <rpc> messages can use the time capability to amplify her attack, for example by sending multiple <rpc> messages with the same scheduled time. 😱 it's important to note that the security measures described in [RFC6241] can prevent these vulnerabilities. 🛡️
the time capability relies on an underlying time synchronization protocol. so if an attacker goes after the time protocol, they can potentially compromise NETCONF when it's using the time capability. 🕵️♀️ a detailed discussion of 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 sending 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 <rpc-error> 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 🔐
okay so this memo defines a brand new YANG module, and Appendix A is where you'll find the full spec for it 🎀
the YANG module is built to be accessed through NETCONF [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] is what lets you restrict particular NETCONF users to a preconfigured subset of all the available NETCONF protocol operations and content 🔒
now for the spicy part 🌶️ this YANG module defines <sched-max-future> and <sched-max-past>, which are writable, creatable, and deletable. these data nodes may be considered sensitive or vulnerable in some network environments 😬 an attacker might try to maliciously configure these parameters to a super low value, which would make all the scheduled RPCs get discarded. for example, say a client expects <sched-max-future> to be 15 seconds, but in practice it's been maliciously set to 1 second. then a totally legit scheduled RPC that's supposed to run 5 seconds from now will get discarded by the server 💀
that's why these knobs need real protection. a wrong value doesn't just look weird, it quietly kills work that was meant to happen.
this YANG module also defines the <cancel-schedule> RPC 🧹 this RPC may be considered sensitive or vulnerable in some network environments too. the value of the <schedule-id> is known to all the clients that are subscribed to notifications from the server, so the <cancel-schedule> RPC could be used maliciously to attack servers by cancelling their pending RPCs 🙈 this attack is handled in two layers:
- (i) security at the transport layer, which limits the attack only to clients that have successfully initiated a secure session with the server 🔐
- (ii) the authorization level required to cancel an RPC should be the same as the level required to schedule it. this limits 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 ✨
okay, IANA stuff time 🗂️ the following capability identifier URN has been registered in the "Network Configuration Protocol (NETCONF) Capability URNs" registry:
urn:ietf:params:netconf:capability:time:1.0the 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.and 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: 77588. 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,
<http://www.rfc-editor.org/info/rfc2119>. 🌸 - [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<http://www.rfc-editor.org/info/rfc3339>. ⏰ - [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004,
<http://www.rfc-editor.org/info/rfc3688>. 🗂️ - [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,
<http://www.rfc-editor.org/info/rfc6241>. 🦋 - [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) Base Notifications", RFC 6470, DOI 10.17487/RFC6470, February 2012,
<http://www.rfc-editor.org/info/rfc6470>. 🔔 - [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013,
<http://www.rfc-editor.org/info/rfc6991>. 💜
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. 🕰️
- [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,
<http://www.rfc-editor.org/info/rfc5905>. ⏱️ - [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,
<http://www.rfc-editor.org/info/rfc5907>. 🧩 - [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010,
<http://www.rfc-editor.org/info/rfc6020>. 🌈 - [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<http://www.rfc-editor.org/info/rfc6242>. 🔐 - [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011,
<http://www.rfc-editor.org/info/rfc6243>. 🎀 - [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6536>. 🛡️ - [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for System Management", RFC 7317, DOI 10.17487/RFC7317, August 2014,
<http://www.rfc-editor.org/info/rfc7317>. 🖥️ - [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in Packet Switched Networks", RFC 7384, DOI 10.17487/RFC7384, October 2014,
<http://www.rfc-editor.org/info/rfc7384>. 🚨 - [Time4] Mizrahi, T. and Y. Moses, "Software Defined Networks: It's About Time", IEEE INFOCOM, 2016. ⭐
Appendix A. YANG Module for the Time Capability 🧚
okay the big finale of the spec 🎉 this section is normative.
<CODE BEGINS> 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
<dew@tx.technion.ac.il>
Editor: Yoram Moses
<moses@ee.technion.ac.il>";
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.";
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 {
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 <get-config>.";
}
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 <get-config>.";
}
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 <get>.";
}
augment /nc:get/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 <get>.";
}
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 <copy-config>.";
}
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 <copy-config>.";
}
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
"Indicates that the rpc-reply should include the
execution-time.";
}
description
"Adds the time element to <edit-config>.";
}
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 <edit-config>.";
}
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 <delete-config>.";
}
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 <delete-config>.";
}
augment /nc:lock/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 <lock>.";
}
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 <lock>.";
}
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 <unlock>.";
}
augment /nc:unlock/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 <unlock>.";
}
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 <commit>.";
}
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 <commit>.";
}
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 {
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";
}
}
<CODE ENDS>Acknowledgments 🙏✨
okay bestie, the authors want to give a huge shoutout to 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 💖 they literally made this so much better 🫶
this work was also 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
📦 where this page comes from
- ietf: rfc7758 2016-02
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms