idnits 2.17.00 (12 Aug 2021) /tmp/idnits24417/draft-ietf-dots-telemetry-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 855 has weird spacing: '...-status boo...' == Line 871 has weird spacing: '...-status boo...' == Line 1117 has weird spacing: '...apacity uin...' == Line 1471 has weird spacing: '...er-port ine...' == Line 1832 has weird spacing: '...er-port ine...' == (8 more instances...) -- The document date (24 January 2022) is 116 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 4929, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'Private-Enterprise-Numbers' == Outdated reference: draft-ietf-core-new-block has been published as RFC 9177 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-10 == Outdated reference: A later version (-03) exists of draft-ietf-dots-robust-blocks-01 Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy.K, Ed. 5 Expires: 28 July 2022 Akamai 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 J. Shallow 11 24 January 2022 13 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 14 draft-ietf-dots-telemetry-20 16 Abstract 18 This document aims to enrich the DOTS signal channel protocol with 19 various telemetry attributes, allowing for optimal Distributed 20 Denial-of-Service (DDoS) attack mitigation. It specifies the normal 21 traffic baseline and attack traffic telemetry attributes a DOTS 22 client can convey to its DOTS server in the mitigation request, the 23 mitigation status telemetry attributes a DOTS server can communicate 24 to a DOTS client, and the mitigation efficacy telemetry attributes a 25 DOTS client can communicate to a DOTS server. The telemetry 26 attributes can assist the mitigator to choose the DDoS mitigation 27 techniques and perform optimal DDoS attack mitigation. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 28 July 2022. 46 Copyright Notice 48 Copyright (c) 2022 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Revised BSD License text as 57 described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Revised BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. DOTS Telemetry: Overview and Purpose . . . . . . . . . . . . 7 65 3.1. Need More Visibility . . . . . . . . . . . . . . . . . . 7 66 3.2. Enhanced Detection . . . . . . . . . . . . . . . . . . . 8 67 3.3. Efficient Mitigation . . . . . . . . . . . . . . . . . . 10 68 4. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 10 69 4.1. Overview of Telemetry Operations . . . . . . . . . . . . 10 70 4.2. Block-wise Transfer . . . . . . . . . . . . . . . . . . . 12 71 4.3. DOTS Multi-homing Considerations . . . . . . . . . . . . 12 72 4.4. YANG Considerations . . . . . . . . . . . . . . . . . . . 12 73 5. Generic Considerations . . . . . . . . . . . . . . . . . . . 14 74 5.1. DOTS Client Identification . . . . . . . . . . . . . . . 14 75 5.2. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 14 76 5.3. Empty URI Paths . . . . . . . . . . . . . . . . . . . . . 14 77 5.4. Controlling Configuration Data . . . . . . . . . . . . . 14 78 5.5. Message Validation . . . . . . . . . . . . . . . . . . . 15 79 5.6. A Note About Examples . . . . . . . . . . . . . . . . . . 15 80 6. Telemetry Operation Paths . . . . . . . . . . . . . . . . . . 15 81 7. DOTS Telemetry Setup Configuration . . . . . . . . . . . . . 16 82 7.1. Telemetry Configuration . . . . . . . . . . . . . . . . . 17 83 7.1.1. Retrieve Current DOTS Telemetry Configuration . . . . 18 84 7.1.2. Conveying DOTS Telemetry Configuration . . . . . . . 20 85 7.1.3. Retrieve Installed DOTS Telemetry Configuration . . . 23 86 7.1.4. Delete DOTS Telemetry Configuration . . . . . . . . . 24 87 7.2. Total Pipe Capacity . . . . . . . . . . . . . . . . . . . 24 88 7.2.1. Conveying DOTS Client Domain Pipe Capacity . . . . . 25 89 7.2.2. Retrieve Installed DOTS Client Domain Pipe 90 Capacity . . . . . . . . . . . . . . . . . . . . . . 31 91 7.2.3. Delete Installed DOTS Client Domain Pipe Capacity . . 31 92 7.3. Telemetry Baseline . . . . . . . . . . . . . . . . . . . 31 93 7.3.1. Conveying DOTS Client Domain Baseline Information . . 34 94 7.3.2. Retrieve Installed Normal Traffic Baseline . . . . . 38 95 7.3.3. Delete Installed Normal Traffic Baseline . . . . . . 38 96 7.4. Reset Installed Telemetry Setup . . . . . . . . . . . . . 38 97 7.5. Conflict with Other DOTS Clients of the Same Domain . . . 38 98 8. DOTS Pre-or-Ongoing Mitigation Telemetry . . . . . . . . . . 39 99 8.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes . . . 41 100 8.1.1. Target . . . . . . . . . . . . . . . . . . . . . . . 42 101 8.1.2. Total Traffic . . . . . . . . . . . . . . . . . . . . 43 102 8.1.3. Total Attack Traffic . . . . . . . . . . . . . . . . 45 103 8.1.4. Total Attack Connections . . . . . . . . . . . . . . 47 104 8.1.5. Attack Details . . . . . . . . . . . . . . . . . . . 49 105 8.1.6. Vendor Attack Mapping . . . . . . . . . . . . . . . . 52 106 8.2. From DOTS Clients to DOTS Servers . . . . . . . . . . . . 56 107 8.3. From DOTS Servers to DOTS Clients . . . . . . . . . . . . 59 108 9. DOTS Telemetry Mitigation Status Update . . . . . . . . . . . 64 109 9.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 110 Attributes . . . . . . . . . . . . . . . . . . . . . . . 64 111 9.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 112 Attributes . . . . . . . . . . . . . . . . . . . . . . . 66 113 10. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 70 114 11. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 71 115 11.1. DOTS Signal Channel Telemetry YANG Module . . . . . . . 71 116 11.2. Vendor Attack Mapping Details YANG Module . . . . . . . 100 117 12. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 103 118 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 106 119 13.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 106 120 13.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 109 121 13.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 109 122 14. Security Considerations . . . . . . . . . . . . . . . . . . . 110 123 14.1. DOTS Signal Channel Telemetry . . . . . . . . . . . . . 110 124 14.2. Vendor Attack Mapping . . . . . . . . . . . . . . . . . 111 125 15. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 112 126 16. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 112 127 17. References . . . . . . . . . . . . . . . . . . . . . . . . . 112 128 17.1. Normative References . . . . . . . . . . . . . . . . . . 112 129 17.2. Informative References . . . . . . . . . . . . . . . . . 114 130 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 116 132 1. Introduction 134 IT organizations and service providers are facing Distributed Denial 135 of Service (DDoS) attacks that fall into two broad categories: 137 1. Network/Transport layer attacks target the victim's 138 infrastructure. These attacks are not necessarily aimed at 139 taking down the actual delivered services, but rather to prevent 140 various network elements (routers, switches, firewalls, transit 141 links, and so on) from serving legitimate users' traffic. 143 The main method of such attacks is to send a large volume or high 144 packet per second (pps) of traffic toward the victim's 145 infrastructure. Typically, attack volumes may vary from a few 146 100 Mbps to 100s of Gbps or even Tbps. Attacks are commonly 147 carried out leveraging botnets and attack reflectors for 148 amplification attacks (Section 3.1 of [RFC4732]) such as NTP 149 (Network Time Protocol), DNS (Domain Name System), SNMP (Simple 150 Network Management Protocol), or SSDP (Simple Service Discovery 151 Protocol). 153 2. Application layer attacks target various applications. Typical 154 examples include attacks against HTTP/HTTPS, DNS, SIP (Session 155 Initiation Protocol), or SMTP (Simple Mail Transfer Protocol). 156 However, all applications with their port numbers open at network 157 edges can be attractive attack targets. 159 Application layer attacks are considered more complex and hard to 160 categorize, and therefore harder to detect and mitigate 161 efficiently. 163 To compound the problem, attackers also leverage multi-vectored 164 attacks. These attacks are assembled from dynamic attack vectors 165 (Network/Application) and tactics. As such, multiple attack vectors 166 formed by multiple attack types and volumes are launched 167 simultaneously towards a victim. Multi-vector attacks are harder to 168 detect and defend against. Multiple and simultaneous mitigation 169 techniques are needed to defeat such attack campaigns. It is also 170 common for attackers to change attack vectors right after a 171 successful mitigation, burdening their opponents with changing their 172 defense methods. 174 The conclusion derived from these real scenarios is that modern 175 attacks detection and mitigation are most certainly complicated and 176 highly convoluted tasks. They demand a comprehensive knowledge of 177 the attack attributes, the normal behavior of the targeted systems 178 (including normal traffic patterns), as well as the attacker's 179 ongoing and past actions. Even more challenging, retrieving all the 180 analytics needed for detecting these attacks is not simple with the 181 industry's current reporting capabilities. 183 The DOTS signal channel protocol [RFC9132] is used to carry 184 information about a network resource or a network (or a part thereof) 185 that is under a DDoS attack. Such information is sent by a DOTS 186 client to one or multiple DOTS servers so that appropriate mitigation 187 actions are undertaken on traffic deemed suspicious. Various use 188 cases are discussed in [RFC8903]. 190 DOTS clients can be integrated within a DDoS attack detector, or 191 network and security elements that have been actively engaged with 192 ongoing attacks. The DOTS client mitigation environment determines 193 that it is no longer possible or practical for it to handle these 194 attacks itself. This can be due to a lack of resources or security 195 capabilities, as derived from the complexities and the intensity of 196 these attacks. In this circumstance, the DOTS client has invaluable 197 knowledge about the actual attacks that need to be handled by its 198 DOTS server(s). By enabling the DOTS client to share this 199 comprehensive knowledge of an ongoing attack under specific 200 circumstances, the DOTS server can drastically increase its ability 201 to accomplish successful mitigation. While the attack is being 202 handled by the mitigation resources associated with the DOTS server, 203 the DOTS server has knowledge about the ongoing attack mitigation. 204 The DOTS server can share this information with the DOTS client so 205 that the client can better assess and evaluate the actual mitigation 206 realized. 208 DOTS clients can send mitigation hints derived from attack details to 209 DOTS servers, with the full understanding that the DOTS server may 210 ignore mitigation hints, as described in [RFC8612] (Gen-004). 211 Mitigation hints will be transmitted across the DOTS signal channel, 212 as the data channel may not be functional during an attack. How a 213 DOTS server is handling normal and attack traffic attributes, and 214 mitigation hints, is implementation specific. 216 Both DOTS clients and servers can benefit from this information by 217 presenting various information in relevant management, reporting, and 218 portal systems. 220 This document defines DOTS telemetry attributes that can be conveyed 221 by DOTS clients to DOTS servers, and vice versa. The DOTS telemetry 222 attributes are not mandatory attributes of the DOTS signal channel 223 protocol [RFC9132]. When no limitation policy is provided to a DOTS 224 agent, it can signal available telemetry attributes to it peers in 225 order to optimize the overall mitigation service provisioned using 226 DOTS. The aforementioned policy can be, for example, agreed during a 227 service subscription (that is out of scope) to identify a subset of 228 DOTS clients among those deployed in a DOTS client domain that are 229 allowed to send or receive telemetry data. 231 2. Terminology 233 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 234 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 235 "OPTIONAL" in this document are to be interpreted as described in BCP 236 14 [RFC2119][RFC8174] when, and only when, they appear in all 237 capitals, as shown here. 239 The reader should be familiar with the terms defined in [RFC8612]. 241 "DOTS Telemetry" is defined as the collection of attributes that are 242 used to characterize the normal traffic baseline, attacks and their 243 mitigation measures, and any related information that may help in 244 enforcing countermeasures. DOTS Telemetry is an optional set of 245 attributes that can be signaled in the DOTS signal channel protocol. 247 Telemetry Setup Identifier (tsid) is an identifier that is generated 248 by DOTS clients to uniquely identify DOTS telemetry setup 249 configuration data. 251 Telemetry Identifier (tmid) is an identifier that is generated by 252 DOTS clients to uniquely identify DOTS telemetry data that is 253 communicated prior to or during a mitigation. 255 When two telemetry requests overlap, "overlapped" lower numeric 256 'tsid' (or 'tmid') refers to the lower 'tsid' (or 'tmid') value of 257 these overlapping requests. 259 The term "pipe" represents the maximum level of traffic that the DOTS 260 client domain can receive. Whether a "pipe" is mapped to one or a 261 group of network interfaces is deployment-specific. For example, 262 each interconnection link may be considered as a specific pipe if the 263 DOTS server is hosted by each upstream provider, whike the aggregate 264 of all links to connect to upstream network providers can be 265 considered by a DOTS client domain as a single pipe when 266 communicating with a DOTS server not hosted by these upstream 267 providers. 269 The document uses IANA-assigned Enterprise Numbers. These numbers 270 are also known as "Private Enterprise Numbers" and "SMI (Structure of 271 Management Information) Network Management Private Enterprise Codes" 272 [Private-Enterprise-Numbers]. 274 The meaning of the symbols in YANG tree diagrams are defined in 275 [RFC8340] and [RFC8791]. 277 Consistent with the convention set in Section 2 of [RFC8783], the 278 examples in Section 8.1.6 use "/restconf" as the discovered RESTCONF 279 API root path. Within these examples, some protocol header lines are 280 split into multiple lines for display purposes only. When a line 281 ends with backslash ('\') as the last character, the line is wrapped 282 for display purposes. It is to be considered to be joined to the 283 next line by deleting the backslash, the following line break, and 284 the leading whitespace of the next line. 286 3. DOTS Telemetry: Overview and Purpose 288 Timely and effective signaling of up-to-date DDoS telemetry to all 289 elements involved in the mitigation process is essential and improves 290 the overall DDoS mitigation service effectiveness. Bi-directional 291 feedback between DOTS agents is required for increased awareness by 292 each party of the attack and mitigation efforts, supporting a 293 superior and highly efficient attack mitigation service. 295 3.1. Need More Visibility 297 When signaling a mitigation request, it is most certainly beneficial 298 for DOTS clients to signal to DOTS servers any knowledge regarding 299 ongoing attacks. This can happen in cases where DOTS clients are 300 asking DOTS servers for support in defending against attacks that 301 they have already detected and/or (partially) mitigated. 303 If attacks are already detected and categorized within a DOTS client 304 domain, the DOTS server, and its associated mitigation services, can 305 proactively benefit from this information and optimize the overall 306 service delivery. It is important to note that DOTS client domains' 307 and DOTS server domains' detection and mitigation approaches can be 308 different, and can potentially result in different results and attack 309 classifications. The DDoS mitigation service treats the ongoing 310 attack details received from DOTS clients as hints and cannot 311 completely rely or trust the attack details conveyed by DOTS clients. 313 In addition to the DOTS server directly using telemetry data as 314 operational hints, the DOTS server security operation team also 315 benefits from telemetry data. A basic requirement of security 316 operation teams is to be aware of and get visibility into the attacks 317 they need to handle. This holds especially for the case of ongoing 318 attacks, where DOTS telemetry provides data about the current attack 319 status. Even if some mitigation can be automated, operational teams 320 can use the DOTS telemetry information to be prepared for attack 321 mitigation and to assign the correct resources (operation staff, 322 networking and mitigation) for the specific service. Similarly, 323 security operations personnel at the DOTS client side ask for 324 feedback about their requests for protection. Therefore, it is 325 valuable for DOTS servers to share DOTS telemetry with DOTS clients. 327 Mutual sharing of information is thus crucial for "closing the 328 mitigation loop" between DOTS clients and servers. For the server 329 side team, it is important to confirm that the same attacks that the 330 DOTS server's mitigation resources are seeing are those that a DOTS 331 client is asking for mitigation of. For the DOTS client side team, 332 it is important to realize that the DOTS clients receive the required 333 service. For example, understanding that "I asked for mitigation of 334 two attacks and my DOTS server detects and mitigates only one of 335 them". Cases of inconsistency in attack classification between DOTS 336 clients and servers can be highlighted, and maybe handled, using the 337 DOTS telemetry attributes. 339 In addition, management and orchestration systems, at both DOTS 340 client and server sides, can use DOTS telemetry as a feedback to 341 automate various control and management activities derived from 342 signaled telemetry information. 344 If the DOTS server's mitigation resources have the capabilities to 345 facilitate the DOTS telemetry, the DOTS server adapts its protection 346 strategy and activates the required countermeasures immediately 347 (automation enabled) for the sake of optimized attack mitigation 348 decisions and actions. The interface from the DOTS server to the 349 mitigator to signal the telemetry data is out of scope. 351 3.2. Enhanced Detection 353 DOTS telemetry can also be used as input for determining what values 354 to use for the tuning parameters available on the mitigation 355 resources. During the last few years, DDoS attack detection 356 technologies have evolved from threshold-based detection (that is, 357 cases when all or specific parts of traffic cross a predefined 358 threshold for a certain period of time is considered as an attack) to 359 an "anomaly detection" approach. For the latter, it is required to 360 maintain rigorous learning of "normal" behavior, and an "anomaly" (or 361 an attack) is identified and categorized based on the knowledge about 362 the normal behavior and a deviation from this normal behavior. 363 Machine learning approaches are used such that the actual traffic 364 thresholds are automatically calculated by learning the protected 365 entity's normal traffic behavior during 'idle' time (i.e., no 366 mitigation is active). The normal traffic characterization learned 367 is referred to as the "normal traffic baseline". An attack is 368 detected when the victim's actual traffic is deviating from this 369 normal baseline pattern. 371 In addition, subsequent activities toward mitigating an attack are 372 much more challenging. The ability to distinguish legitimate traffic 373 from attacker traffic on a per packet basis is complex. For example, 374 a packet may look "legitimate" and no attack signature can be 375 identified. The anomaly can be identified only after detailed 376 statistical analysis. DDoS attack mitigators use the normal baseline 377 during the mitigation of an attack to identify and categorize the 378 expected appearance of a specific traffic pattern. Particularly, the 379 mitigators use the normal baseline to recognize the "level of 380 normality" that needs to be achieved during the various mitigation 381 process. 383 Normal baseline calculation is performed based on continuous learning 384 of the normal behavior of the protected entities. The minimum 385 learning period varies from hours to days and even weeks, depending 386 on the protected application behavior. The baseline cannot be 387 learned during active attacks because attack conditions do not 388 characterize the protected entities' normal behavior. 390 If the DOTS client has calculated the normal baseline of its 391 protected entities, signaling such information to the DOTS server 392 along with the attack traffic levels provides value. The DOTS server 393 benefits from this telemetry by tuning its mitigation resources with 394 the DOTS client's normal baseline. The DOTS server mitigators use 395 the baseline to familiarize themselves with the attack victim's 396 normal behavior and target the baseline as the level of normality 397 they need to achieve. Fed with this information, the overall 398 mitigation performances is expected to be improved in terms of time 399 to mitigate, accuracy, and false-negative and false-positive rates. 401 Mitigation of attacks without having certain knowledge of normal 402 traffic can be inaccurate at best. This is especially true for 403 recursive signaling (see Section 3.2.3 of [RFC8811]). Given that 404 DOTS clients can be integrated in a highly diverse set of scenarios 405 and use cases, this emphasizes the need for knowledge of each DOTS 406 client domain behavior, especially given that common global 407 thresholds for attack detection practically cannot be realized. Each 408 DOTS client domain can have its own levels of traffic and normal 409 behavior. Without facilitating normal baseline signaling, it may be 410 very difficult for DOTS servers in some cases to detect and mitigate 411 the attacks accurately: 413 It is important to emphasize that it is practically impossible for 414 the DOTS server's mitigators to calculate the normal baseline in 415 cases where they do not have any knowledge of the traffic 416 beforehand. 418 Of course, this information can be provided using out-of-band 419 mechanisms or manual configuration at the risk of unmaintained 420 information becoming inaccurate as the network evolves and "normal" 421 patterns change. The use of a dynamic and collaborative means 422 between the DOTS client and server to identify and share key 423 parameters for the sake of efficient DDoS protection is valuable. 425 3.3. Efficient Mitigation 427 During a high volume attack, DOTS client pipes can be totally 428 saturated. DOTS clients ask their DOTS servers to handle the attack 429 upstream so that DOTS client pipes return to a reasonable load level 430 (normal pattern, ideally). At this point, it is essential to ensure 431 that the mitigator does not overwhelm the DOTS client pipes by 432 sending back large volumes of "clean traffic", or what it believes is 433 "clean". This can happen when the mitigator has not managed to 434 detect and mitigate all the attacks launched towards the DOTS client 435 domain. 437 In this case, it can be valuable to DOTS clients to signal to DOTS 438 servers the total pipe capacity, which is the level of traffic the 439 DOTS client domain can absorb from its upstream network. Dynamic 440 updates of the condition of pipes between DOTS agents while they are 441 under a DDoS attack is essential (e.g., where multiple DOTS clients 442 share the same physical connectivity pipes). The DOTS server should 443 activate other mechanisms to ensure it does not allow the DOTS client 444 domain's pipes to be saturated unintentionally. The rate-limit 445 action defined in [RFC8783] is a reasonable candidate to achieve this 446 objective; the DOTS client can indicate the type(s) of traffic (such 447 as ICMP, UDP, TCP port number 80) it prefers to limit. The rate- 448 limit action can be controlled via the signal channel [RFC9133] even 449 when the pipe is overwhelmed. 451 4. Design Overview 453 4.1. Overview of Telemetry Operations 455 The DOTS protocol suite is divided into two logical channels: the 456 signal channel [RFC9132] and data channel [RFC8783]. This division 457 is due to the vastly different requirements placed upon the traffic 458 they carry. The DOTS signal channel must remain available and usable 459 even in the face of attack traffic that might, e.g., saturate one 460 direction of the links involved, rendering acknowledgment-based 461 mechanisms unreliable and strongly incentivizing messages to be small 462 enough to be contained in a single IP packet (Section 2.2 of 463 [RFC8612]). In contrast, the DOTS data channel is available for 464 high-bandwidth data transfer before or after an attack, using more 465 conventional transport protocol techniques (Section 2.3 of 466 [RFC8612]). It is generally preferable to perform advance 467 configuration over the DOTS data channel, including configuring 468 aliases for static or nearly static data sets such as sets of network 469 addresses/prefixes that might be subject to related attacks. This 470 design helps to optimize the use of the DOTS signal channel for the 471 small messages that are important to deliver during an attack. As a 472 reminder, both DOTS signal and data channels require secure 473 communication channels (Section 11 of [RFC9132] and Section 10 of 474 [RFC8783]). 476 Telemetry information has aspects that correspond to both operational 477 modes (i.e., signal and data channels): there is certainly a need to 478 convey updated information about ongoing attack traffic and targets 479 during an attack, so as to convey detailed information about 480 mitigation status and inform updates to mitigation strategy in the 481 face of adaptive attacks, but it is also useful to provide mitigation 482 services with a picture of normal or "baseline" traffic towards 483 potential targets, to aid in detecting when incoming traffic deviates 484 from normal into being an attack. Also, one might populate a 485 "database" of classifications of known types of attack so that a 486 short attack identifier can be used during attack time to describe an 487 observed attack. This specification does make provision for use of 488 the DOTS data channel for the latter function (Section 8.1.6), but 489 otherwise retains most telemetry functionality in the DOTS signal 490 channel. 492 Note that it is a functional requirement to convey information about 493 ongoing attack traffic during an attack, and information about 494 baseline traffic uses an essentially identical data structure that is 495 naturally defined to sit next to the description of attack traffic. 496 The related telemetry setup information used to parameterize actual 497 traffic data is also sent over the signal channel, out of expediency. 499 This document specifies an extension to the DOTS signal channel 500 protocol. Considerations about how to establish, maintain, and make 501 use of the DOTS signal channel are specified in [RFC9132]. 503 Once the DOTS signal channel is established, DOTS clients that 504 support the DOTS telemetry extension proceed with the telemetry setup 505 configuration (e.g., measurement interval, telemetry notification 506 interval, pipe capacity, normal traffic baseline) as detailed in 507 Section 7. DOTS agents can then include DOTS telemetry attributes 508 using the DOTS signal channel (Section 8.1). A DOTS client can use 509 separate messages to share with its DOTS server(s) a set of telemetry 510 data bound to an ongoing mitigation (Section 8.2). Also, a DOTS 511 client that is interested in receiving telemetry notifications 512 related to some of its resources follows the procedure defined in 513 Section 8.3. The DOTS client can then decide to send a mitigation 514 request if the notified attack cannot be mitigated locally within the 515 DOTS client domain. 517 Aggregate DOTS telemetry data can also be included in efficacy update 518 (Section 9.1) or mitigation update (Section 9.2) messages. 520 4.2. Block-wise Transfer 522 DOTS clients can use block wise transfer [RFC7959] with the 523 recommendation detailed in Section 4.4.2 of [RFC9132] to control the 524 size of a response when the data to be returned does not fit within a 525 single datagram. 527 DOTS clients can also use CoAP Block1 Option in a PUT request 528 (Section 2.5 of [RFC7959]) to initiate large transfers, but these 529 Block1 transfers are likely to fail if the inbound "pipe" is running 530 full because the transfer requires a message from the server for each 531 block, which would likely be lost in the incoming flood. 532 Consideration needs to be made to try to fit this PUT into a single 533 transfer or to separate out the PUT into several discrete PUTs where 534 each of them fits into a single packet. 536 Q-Block1 and Q-Block2 Options that are similar to the CoAP Block1 and 537 Block2 Options, but enable robust transmissions of big blocks of data 538 with less packet interchanges using NON messages, are defined in 539 [I-D.ietf-core-new-block]. DOTS implementations can consider the use 540 of Q-Block1 and Q-Block2 Options [I-D.ietf-dots-robust-blocks]. 542 4.3. DOTS Multi-homing Considerations 544 Considerations for multi-homed DOTS clients to select which DOTS 545 server to contact and which IP prefixes to include in a telemetry 546 message to a given peer DOTS server are discussed in 547 [I-D.ietf-dots-multihoming]. For example, if each upstream network 548 exposes a DOTS server and the DOTS client maintains DOTS channels 549 with all of them, only the information related to prefixes assigned 550 by an upstream network to the DOTS client domain will be signaled via 551 the DOTS channel established with the DOTS server of that upstream 552 network. 554 Considerations related to whether (and how) a DOTS client gleans some 555 telemetry information (e.g., attack details) it receives from a first 556 DOTS server and share it with a second DOTS server are implementation 557 and deployment specific. 559 4.4. YANG Considerations 561 Telemetry messages exchanged between DOTS agents are serialized using 562 Concise Binary Object Representation (CBOR) [RFC8949]. CBOR-encoded 563 payloads are used to carry signal-channel-specific payload messages 564 which convey request parameters and response information such as 565 errors. 567 This document specifies a YANG module [RFC7950] for representing DOTS 568 telemetry message types (Section 11.1). All parameters in the 569 payload of the DOTS signal channel are mapped to CBOR types as 570 specified in Section 12. As a reminder, Section 3 of [RFC9132] 571 defines the rules for mapping YANG-modeled data to CBOR. 573 The DOTS telemetry module (Section 11.1) is not intended to be used 574 via NETCONF/RESTCONF for DOTS server management purposes. It serves 575 only to provide a data model and encoding following [RFC8791]. 576 Server deviations are strongly discouraged, as the peer DOTS agent 577 does not have means to retrieve the list of deviations and thus 578 interoperability issues are likely to be encountered. 580 The DOTS telemetry module (Section 11.1) uses "enumerations" rather 581 than "identities" to define units, samples, and intervals because 582 otherwise the namespace identifier "ietf-dots-telemetry" must be 583 included when a telemetry attribute is included (e.g., in a 584 mitigation efficacy update). The use of "identities" is thus 585 suboptimal from a message compactness standpoint; one of the key 586 requirements for DOTS Signal Channel messages. 588 The DOTS telemetry module (Section 11.1) includes some lists for 589 which no key statement is included. This behavior is compliant with 590 [RFC8791]. The reason for not including these keys is because they 591 are not included in the message body of DOTS requests; such keys are 592 included as mandatory Uri-Paths in requests (Sections 7 and 8). 593 Otherwise, whenever a key statement is used in the module, the same 594 definition as in Section 7.8.2 of [RFC7950] is assumed. 596 Some parameters (e.g., low percentile values) may be associated with 597 different YANG types (e.g., decimal64 and yang:gauge64). To easily 598 distinguish the types of these parameters while using meaningful 599 names, the following suffixes are used: 601 +========+==============+==================+ 602 | Suffix | YANG Type | Example | 603 +========+==============+==================+ 604 | -g | yang:gauge64 | low-percentile-g | 605 +--------+--------------+------------------+ 606 | -c | container | connection-c | 607 +--------+--------------+------------------+ 608 | -ps | per second | connection-ps | 609 +--------+--------------+------------------+ 611 Table 1 613 The full tree diagram of the DOTS telemetry module can be generated 614 using the "pyang" tool [PYANG]. That tree is not included here 615 because it is too long (Section 3.3 of [RFC8340]). Instead, subtrees 616 are provided for the reader's convenience. 618 In order to optimize the data exchanged over the DOTS signal channel, 619 the document specifies a second YANG module ("ietf-dots-mapping", 620 Section 11.2) that augments the DOTS data channel [RFC8783]. This 621 augmentation can be used during 'idle' time to share the attack 622 mapping details (Section 8.1.5). DOTS clients can use tools, e.g., 623 YANG Library [RFC8525], to retrieve the list of features and 624 deviations supported by the DOTS server over the data channel. 626 5. Generic Considerations 628 5.1. DOTS Client Identification 630 Following the rules in Section 4.4.1 of [RFC9132], a unique 631 identifier is generated by a DOTS client to prevent request 632 collisions ('cuid'). 634 As a reminder, [RFC9132] forbids 'cuid' to be returned in a response 635 message body. 637 5.2. DOTS Gateways 639 DOTS gateways may be located between DOTS clients and servers. The 640 considerations elaborated in Section 4.4.1 of [RFC9132] must be 641 followed. In particular, 'cdid' attribute is used to unambiguously 642 identify a DOTS client domain. 644 As a reminder, Section 4.4.1.3 of [RFC9132] forbids 'cdid' (if 645 present) to be returned in a response message body. 647 5.3. Empty URI Paths 649 Uri-Path parameters and attributes with empty values MUST NOT be 650 present in a request. The presence of such an empty value renders 651 the entire containing message invalid. 653 5.4. Controlling Configuration Data 655 The DOTS server follows the same considerations discussed in 656 Section of 4.5.3 of [RFC9132] for managing DOTS telemetry 657 configuration freshness and notification. 659 Likewise, a DOTS client may control the selection of configuration 660 and non-configuration data nodes when sending a GET request by means 661 of the 'c' Uri-Query option and following the procedure specified in 662 Section of 4.4.2 of [RFC9132]. These considerations are not 663 reiterated in the following sections. 665 5.5. Message Validation 667 The authoritative reference for validating telemetry messages 668 exchanged over the DOTS signal channel are Sections 7, 8, and 9 669 together with the mapping table established in Section 12. The 670 structure of telemetry message bodies is represented as a YANG data 671 structure (Section 11.1). 673 5.6. A Note About Examples 675 Examples are provided for illustration purposes. The document does 676 not aim to provide a comprehensive list of message examples. 678 JSON encoding of YANG-modeled data is used to illustrate the various 679 telemetry operations. 681 The examples use the Enterprise Number 32473 defined for 682 documentation use [RFC5612]. 684 6. Telemetry Operation Paths 686 As discussed in Section 4.2 of [RFC9132], each DOTS operation is 687 indicated by a path suffix that indicates the intended operation. 688 The operation path is appended to the path prefix to form the URI 689 used with a CoAP request to perform the desired DOTS operation. The 690 following telemetry path suffixes are defined (Table 2): 692 +-----------------+----------------+-----------+ 693 | Operation | Operation Path | Details | 694 +=================+================+===========+ 695 | Telemetry Setup | /tm-setup | Section 6 | 696 | Telemetry | /tm | Section 7 | 697 +-----------------+----------------+-----------+ 699 Table 2: DOTS Telemetry Operations 701 Consequently, the "ietf-dots-telemetry" YANG module defined in 702 Section 11.1 defines data structure to represent new DOTS message 703 types called 'telemetry-setup' and 'telemetry'. The tree structure 704 is shown in Figure 1. More details are provided in Sections 7 and 8 705 about the exact structure of 'telemetry-setup' and 'telemetry' 706 message types. 708 structure dots-telemetry: 709 +-- (telemetry-message-type)? 710 +--:(telemetry-setup) 711 | ... 712 | +-- telemetry* [] 713 | ... 714 | +-- (setup-type)? 715 | +--:(telemetry-config) 716 | | ... 717 | +--:(pipe) 718 | | ... 719 | +--:(baseline) 720 | ... 721 +--:(telemetry) 722 ... 724 Figure 1: New DOTS Message Types (YANG Tree Structure) 726 DOTS implementations MUST support the Observe Option [RFC7641] for 727 'tm' (Section 8). 729 7. DOTS Telemetry Setup Configuration 731 In reference to Figure 1, a DOTS telemetry setup message MUST include 732 only telemetry-related configuration parameters (Section 7.1) or 733 information about DOTS client domain pipe capacity (Section 7.2) or 734 telemetry traffic baseline (Section 7.3). As such, requests that 735 include a mix of telemetry configuration, pipe capacity, and traffic 736 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 738 A DOTS client can reset all installed DOTS telemetry setup 739 configuration data following the considerations detailed in 740 Section 7.4. 742 A DOTS server may detect conflicts when processing requests related 743 to DOTS client domain pipe capacity or telemetry traffic baseline 744 with requests from other DOTS clients of the same DOTS client domain. 745 More details are included in Section 7.5. 747 Telemetry setup configuration is bound to a DOTS client domain. DOTS 748 servers MUST NOT expect DOTS clients to send regular requests to 749 refresh the telemetry setup configuration. Any available telemetry 750 setup configuration is valid till the DOTS server ceases to service a 751 DOTS client domain. DOTS servers MUST NOT reset 'tsid' because a 752 session failed with a DOTS client. DOTS clients update their 753 telemetry setup configuration upon change of a parameter that may 754 impact attack mitigation. 756 DOTS telemetry setup configuration request and response messages are 757 marked as Confirmable messages (Section 2.1 of [RFC7252]). 759 7.1. Telemetry Configuration 761 DOTS telemetry uses several percentile values to provide a picture of 762 a traffic distribution overall, as opposed to just a single snapshot 763 of observed traffic at a single point in time. Modeling raw traffic 764 flow data as a distribution and describing that distribution entails 765 choosing a measurement period that the distribution will describe, 766 and a number of sampling intervals, or "buckets", within that 767 measurement period. Traffic within each bucket is treated as a 768 single event (i.e., averaged), and then the distribution of buckets 769 is used to describe the distribution of traffic over the measurement 770 period. A distribution can be characterized by statistical measures 771 (e.g., mean, median, and standard deviation), and also by reporting 772 the value of the distribution at various percentile levels of the 773 data set in question (e.g., "quartiles" that correspond to 25th, 774 50th, and 75th percentile). More details about percentile values and 775 their computation are found in Section 11.3 of [RFC2330]. 777 DOTS telemetry uses up to three percentile values, plus the overall 778 peak, to characterize traffic distributions. Which percentile 779 thresholds are used for these "low", "medium", and "high" percentile 780 values is configurable. Default values are defined in Section 7.1.2. 782 A DOTS client can negotiate with its server(s) a set of telemetry 783 configuration parameters to be used for telemetry. Such parameters 784 include: 786 * Percentile-related measurement parameters. In particular, 787 'measurement-interval' defines the period on which percentiles are 788 computed, while 'measurement-sample' defines the time distribution 789 for measuring values that are used to compute percentiles. 791 * Measurement units 793 * Acceptable percentile values 795 * Telemetry notification interval 797 * Acceptable Server-originated telemetry 799 7.1.1. Retrieve Current DOTS Telemetry Configuration 801 A GET request is used to obtain acceptable and current telemetry 802 configuration parameters on the DOTS server. This request may 803 include a 'cdid' Uri-Path when the request is relayed by a DOTS 804 gateway. An example of such a GET request (without gateway) is 805 depicted in Figure 2. 807 Header: GET (Code=0.01) 808 Uri-Path: ".well-known" 809 Uri-Path: "dots" 810 Uri-Path: "tm-setup" 811 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 813 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 814 Configuration 816 Upon receipt of such a request, and assuming no error is encountered 817 when processing the request, the DOTS server replies with a 2.05 818 (Content) response that conveys the telemetry parameters that are 819 acceptable by the DOTS server, any pipe information (Section 7.2), 820 and the current baseline information (Section 7.3) maintained by the 821 DOTS server for this DOTS client. The tree structure of the response 822 message body is provided in Figure 3. 824 DOTS servers that support the capability of sending telemetry 825 information to DOTS clients prior to or during a mitigation 826 (Section 9.2) sets 'server-originated-telemetry' under 'max-config- 827 values' to 'true' ('false' is used otherwise). If 'server- 828 originated-telemetry' is not present in a response, this is 829 equivalent to receiving a response with 'server-originated-telemetry' 830 set to 'false'. 832 structure dots-telemetry: 833 +-- (telemetry-message-type)? 834 +--:(telemetry-setup) 835 | +-- (direction)? 836 | | +--:(server-to-client-only) 837 | | +-- max-config-values 838 | | | +-- measurement-interval? interval 839 | | | +-- measurement-sample? sample 840 | | | +-- low-percentile? percentile 841 | | | +-- mid-percentile? percentile 842 | | | +-- high-percentile? percentile 843 | | | +-- server-originated-telemetry? boolean 844 | | | +-- telemetry-notify-interval? uint16 845 | | +-- min-config-values 846 | | | +-- measurement-interval? interval 847 | | | +-- measurement-sample? sample 848 | | | +-- low-percentile? percentile 849 | | | +-- mid-percentile? percentile 850 | | | +-- high-percentile? percentile 851 | | | +-- telemetry-notify-interval? uint16 852 | | +-- supported-unit-classes 853 | | | +-- unit-config* [unit] 854 | | | +-- unit unit-class 855 | | | +-- unit-status boolean 856 | | +-- supported-query-type* query-type 857 | +-- telemetry* [] 858 | +-- (direction)? 859 | | +--:(server-to-client-only) 860 | | +-- tsid? uint32 861 | +-- (setup-type)? 862 | +--:(telemetry-config) 863 | | +-- current-config 864 | | +-- measurement-interval? interval 865 | | +-- measurement-sample? sample 866 | | +-- low-percentile? percentile 867 | | +-- mid-percentile? percentile 868 | | +-- high-percentile? percentile 869 | | +-- unit-config* [unit] 870 | | | +-- unit unit-class 871 | | | +-- unit-status boolean 872 | | +-- server-originated-telemetry? boolean 873 | | +-- telemetry-notify-interval? uint16 874 | +--:(pipe) 875 | | ... 876 | +--:(baseline) 877 | ... 878 +--:(telemetry) 879 ... 881 Figure 3: Telemetry Configuration Tree Structure 883 When both 'min-config-values' and 'max-config-values' attributes are 884 present, the values carried in 'max-config-values' attributes MUST be 885 greater or equal to their counterpart in 'min-config-values' 886 attributes. 888 7.1.2. Conveying DOTS Telemetry Configuration 890 A PUT request is used to convey the configuration parameters for the 891 telemetry data (e.g., low, mid, or high percentile values). For 892 example, a DOTS client may contact its DOTS server to change the 893 default percentile values used as baseline for telemetry data. 894 Figure 3 lists the attributes that can be set by a DOTS client in 895 such a PUT request. An example of a DOTS client that modifies all 896 percentile reference values is shown in Figure 4. 898 Header: PUT (Code=0.03) 899 Uri-Path: ".well-known" 900 Uri-Path: "dots" 901 Uri-Path: "tm-setup" 902 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 903 Uri-Path: "tsid=123" 904 Content-Format: "application/dots+cbor" 906 { 907 "ietf-dots-telemetry:telemetry-setup": { 908 "telemetry": [ 909 { 910 "current-config": { 911 "low-percentile": "5.00", 912 "mid-percentile": "65.00", 913 "high-percentile": "95.00" 914 } 915 } 916 ] 917 } 918 } 920 Figure 4: PUT to Convey the DOTS Telemetry Configuration 922 'cuid' is a mandatory Uri-Path parameter for PUT requests. 924 The following additional Uri-Path parameter is defined: 926 tsid: Telemetry Setup Identifier is an identifier for the DOTS 927 telemetry setup configuration data represented as an integer. 928 This identifier MUST be generated by DOTS clients. 'tsid' 929 values MUST increase monotonically (when a new PUT is generated 930 by a DOTS client to convey new configuration parameters for the 931 telemetry). 933 The procedure specified in Section 4.4.1 of [RFC9132] for 'mid' 934 rollover MUST also be followed for 'tsid' rollover. 936 This is a mandatory attribute. 'tsid' MUST follow 'cuid'. 938 'cuid' and 'tsid' MUST NOT appear in the PUT request message body. 940 At least one configurable attribute MUST be present in the PUT 941 request. 943 A PUT request with a higher numeric 'tsid' value overrides the DOTS 944 telemetry configuration data installed by a PUT request with a lower 945 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 946 requests for requests carrying telemetry configuration data from a 947 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 948 and no longer be available at the DOTS server. 950 The DOTS server indicates the result of processing the PUT request 951 using the following Response Codes: 953 * If the request is missing a mandatory attribute, does not include 954 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 955 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 956 in the response. 958 * If the DOTS server does not find the 'tsid' parameter value 959 conveyed in the PUT request in its configuration data and if the 960 DOTS server has accepted the configuration parameters, then a 2.01 961 (Created) Response Code MUST be returned in the response. 963 * If the DOTS server finds the 'tsid' parameter value conveyed in 964 the PUT request in its configuration data and if the DOTS server 965 has accepted the updated configuration parameters, 2.04 (Changed) 966 MUST be returned in the response. 968 * If any of the enclosed configurable attribute values are not 969 acceptable to the DOTS server (Section 7.1.1), 4.22 (Unprocessable 970 Entity) MUST be returned in the response. 972 The DOTS client may retry and send the PUT request with updated 973 attribute values acceptable to the DOTS server. 975 By default, low percentile (10th percentile), mid percentile (50th 976 percentile), high percentile (90th percentile), and peak (100th 977 percentile) values are used to represent telemetry data. 978 Nevertheless, a DOTS client can disable some percentile types (low, 979 mid, high). In particular, setting 'low-percentile' to '0.00' 980 indicates that the DOTS client is not interested in receiving low- 981 percentiles. Likewise, setting 'mid-percentile' (or 'high- 982 percentile') to the same value as 'low-percentile' (or 'mid- 983 percentile') indicates that the DOTS client is not interested in 984 receiving mid-percentiles (or high-percentiles). For example, a DOTS 985 client can send the request depicted in Figure 5 to inform the server 986 that it is interested in receiving only high-percentiles. This 987 assumes that the client will only use that percentile type when 988 sharing telemetry data with the server. 990 Header: PUT (Code=0.03) 991 Uri-Path: ".well-known" 992 Uri-Path: "dots" 993 Uri-Path: "tm-setup" 994 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 995 Uri-Path: "tsid=124" 996 Content-Format: "application/dots+cbor" 998 { 999 "ietf-dots-telemetry:telemetry-setup": { 1000 "telemetry": [ 1001 { 1002 "current-config": { 1003 "low-percentile": "0.00", 1004 "mid-percentile": "0.00", 1005 "high-percentile": "95.00" 1006 } 1007 } 1008 ] 1009 } 1010 } 1012 Figure 5: PUT to Disable Low- and Mid-Percentiles 1014 DOTS clients can also configure the unit class(es) to be used for 1015 traffic-related telemetry data among the following supported unit 1016 classes: packets per second, bits per second, and bytes per second. 1017 Supplying both bits per second and bytes per second unit-classes is 1018 allowed for a given telemetry data. However, receipt of conflicting 1019 values is treated as invalid parameters and rejected with 4.00 (Bad 1020 Request). 1022 DOTS clients that are interested to receive pre or ongoing mitigation 1023 telemetry (pre-or-ongoing-mitigation) information from a DOTS server 1024 (Section 9.2) MUST set 'server-originated-telemetry' to 'true'. If 1025 'server-originated-telemetry' is not present in a PUT request, this 1026 is equivalent to receiving a request with 'server-originated- 1027 telemetry' set to 'false'. An example of a request to enable pre-or- 1028 ongoing-mitigation telemetry from DOTS servers is shown in Figure 6. 1030 Header: PUT (Code=0.03) 1031 Uri-Path: ".well-known" 1032 Uri-Path: "dots" 1033 Uri-Path: "tm-setup" 1034 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1035 Uri-Path: "tsid=125" 1036 Content-Format: "application/dots+cbor" 1038 { 1039 "ietf-dots-telemetry:telemetry-setup": { 1040 "telemetry": [ 1041 { 1042 "current-config": { 1043 "server-originated-telemetry": true 1044 } 1045 } 1046 ] 1047 } 1048 } 1050 Figure 6: PUT to Enable Pre-or-ongoing-mitigation Telemetry from 1051 the DOTS server 1053 7.1.3. Retrieve Installed DOTS Telemetry Configuration 1055 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 1056 to retrieve the current DOTS telemetry configuration. An example of 1057 such a request is depicted in Figure 7. 1059 Header: GET (Code=0.01) 1060 Uri-Path: ".well-known" 1061 Uri-Path: "dots" 1062 Uri-Path: "tm-setup" 1063 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1064 Uri-Path: "tsid=123" 1066 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 1068 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 1069 in the GET request in its configuration data for the requesting DOTS 1070 client, it MUST respond with a 4.04 (Not Found) error Response Code. 1072 7.1.4. Delete DOTS Telemetry Configuration 1074 A DELETE request is used to delete the installed DOTS telemetry 1075 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 1076 Path parameters for such DELETE requests. 1078 Header: DELETE (Code=0.04) 1079 Uri-Path: ".well-known" 1080 Uri-Path: "dots" 1081 Uri-Path: "tm-setup" 1082 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1083 Uri-Path: "tsid=123" 1085 Figure 8: Delete Telemetry Configuration 1087 The DOTS server resets the DOTS telemetry configuration back to the 1088 default values and acknowledges a DOTS client's request to remove the 1089 DOTS telemetry configuration using 2.02 (Deleted) Response Code. A 1090 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 1091 value conveyed in the DELETE request does not exist in its 1092 configuration data before the request. 1094 Section 7.4 discusses the procedure to reset all DOTS telemetry setup 1095 configuration. 1097 7.2. Total Pipe Capacity 1099 A DOTS client can communicate to the DOTS server(s) its DOTS client 1100 domain pipe information. The tree structure of the pipe information 1101 is shown in Figure 9. 1103 structure dots-telemetry: 1104 +-- (telemetry-message-type)? 1105 +--:(telemetry-setup) 1106 | ... 1107 | +-- telemetry* [] 1108 | +-- (direction)? 1109 | | +--:(server-to-client-only) 1110 | | +-- tsid? uint32 1111 | +-- (setup-type)? 1112 | +--:(telemetry-config) 1113 | | ... 1114 | +--:(pipe) 1115 | | +-- total-pipe-capacity* [link-id unit] 1116 | | +-- link-id nt:link-id 1117 | | +-- capacity uint64 1118 | | +-- unit unit 1119 | +--:(baseline) 1120 | ... 1121 +--:(telemetry) 1122 ... 1124 Figure 9: Pipe Tree Structure 1126 A DOTS client domain pipe is defined as a list of limits of 1127 (incoming) traffic volume ('total-pipe-capacity') that can be 1128 forwarded over ingress interconnection links of a DOTS client domain. 1129 Each of these links is identified with a 'link-id' [RFC8345]. 1131 The unit used by a DOTS client when conveying pipe information is 1132 captured in the 'unit' attribute. The DOTS client MUST auto-scale so 1133 that the appropriate unit is used. That is, for a given unit class, 1134 the DOTS client uses the largest unit that gives a value greater than 1135 one. As such, only one unit per unit class is allowed. 1137 7.2.1. Conveying DOTS Client Domain Pipe Capacity 1139 Similar considerations to those specified in Section 7.1.2 are 1140 followed with one exception: 1142 The relative order of two PUT requests carrying DOTS client domain 1143 pipe attributes from a DOTS client is determined by comparing 1144 their respective 'tsid' values. If such two requests have 1145 overlapping 'link-id' and 'unit', the PUT request with higher 1146 numeric 'tsid' value will override the request with a lower 1147 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 1148 automatically deleted and no longer be available. 1150 DOTS clients SHOULD minimize the number of active 'tsid's used for 1151 pipe information. In order to avoid maintaining a long list of 1152 'tsid's for pipe information, it is RECOMMENDED that DOTS clients 1153 include in any request to update information related to a given link 1154 the information of other links (already communicated using a lower 1155 'tsid' value). Doing so, this update request will override these 1156 existing requests and hence optimize the number of 'tsid' request per 1157 DOTS client. 1159 * Note: This assumes that all link information can fit in one single 1160 message. 1162 As an example of configuring pipe information, a DOTS client managing 1163 a single homed domain (Figure 10) can send a PUT request (shown in 1164 Figure 11) to communicate the capacity of "link1" used to connect to 1165 its ISP. 1167 ,--,--,--. ,--,--,--. 1168 ,-' `-. ,-' `-. 1169 ( DOTS Client )=====( ISP#A ) 1170 `-. Domain ,-' link1 `-. ,-' 1171 `--'--'--' `--'--'--' 1173 Figure 10: Single Homed DOTS Client Domain 1175 Header: PUT (Code=0.03) 1176 Uri-Path: ".well-known" 1177 Uri-Path: "dots" 1178 Uri-Path: "tm-setup" 1179 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1180 Uri-Path: "tsid=126" 1181 Content-Format: "application/dots+cbor" 1183 { 1184 "ietf-dots-telemetry:telemetry-setup": { 1185 "telemetry": [ 1186 { 1187 "total-pipe-capacity": [ 1188 { 1189 "link-id": "link1", 1190 "capacity": "500", 1191 "unit": "megabit-ps" 1192 } 1193 ] 1194 } 1195 ] 1196 } 1197 } 1198 Figure 11: Example of a PUT Request to Convey Pipe Information 1199 (Single Homed) 1201 DOTS clients may be instructed to signal a link aggregate instead of 1202 individual links. For example, a DOTS client that manages a DOTS 1203 client domain having two interconnection links with an upstream ISP 1204 (Figure 12) can send a PUT request (shown in Figure 13) to 1205 communicate the aggregate link capacity with its ISP. Signaling 1206 individual or aggregate link capacity is deployment specific. 1208 ,--,--,--. ,--,--,--. 1209 ,-' `-.===== ,-' `-. 1210 ( DOTS Client ) ( ISP#C ) 1211 `-. Domain ,-'====== `-. ,-' 1212 `--'--'--' `--'--'--' 1214 Figure 12: DOTS Client Domain with Two Interconnection Links 1216 Header: PUT (Code=0.03) 1217 Uri-Path: ".well-known" 1218 Uri-Path: "dots" 1219 Uri-Path: "tm-setup" 1220 Uri-Path: "cuid=hmcpH87lmPGsSTjkhXCbin" 1221 Uri-Path: "tsid=896" 1222 Content-Format: "application/dots+cbor" 1224 { 1225 "ietf-dots-telemetry:telemetry-setup": { 1226 "telemetry": [ 1227 { 1228 "total-pipe-capacity": [ 1229 { 1230 "link-id": "aggregate", 1231 "capacity": "700", 1232 "unit": "megabit-ps" 1233 } 1234 ] 1235 } 1236 ] 1237 } 1238 } 1240 Figure 13: Example of a PUT Request to Convey Pipe Information 1241 (Aggregated Link) 1243 Now consider that the DOTS client domain was upgraded to connect to 1244 an additional ISP (e.g., ISP#B of Figure 14); the DOTS client can 1245 inform a DOTS server that is not hosted with ISP#A and ISP#B domains 1246 about this update by sending the PUT request depicted in Figure 15. 1247 This request also includes information related to "link1" even if 1248 that link is not upgraded. Upon receipt of this request, the DOTS 1249 server removes the request with 'tsid=126' and updates its 1250 configuration base to maintain two links (link#1 and link#2). 1252 ,--,--,--. 1253 ,-' `-. 1254 ( ISP#B ) 1255 `-. ,-' 1256 `--'--'--' 1257 || 1258 || link2 1259 ,--,--,--. ,--,--,--. 1260 ,-' `-. ,-' `-. 1261 ( DOTS Client )=====( ISP#A ) 1262 `-. Domain ,-' link1 `-. ,-' 1263 `--'--'--' `--'--'--' 1265 Figure 14: Multi-Homed DOTS Client Domain 1267 Header: PUT (Code=0.03) 1268 Uri-Path: ".well-known" 1269 Uri-Path: "dots" 1270 Uri-Path: "tm-setup" 1271 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1272 Uri-Path: "tsid=127" 1273 Content-Format: "application/dots+cbor" 1275 { 1276 "ietf-dots-telemetry:telemetry-setup": { 1277 "telemetry": [ 1278 { 1279 "total-pipe-capacity": [ 1280 { 1281 "link-id": "link1", 1282 "capacity": "500", 1283 "unit": "megabit-ps" 1284 }, 1285 { 1286 "link-id": "link2", 1287 "capacity": "500", 1288 "unit": "megabit-ps" 1289 } 1290 ] 1291 } 1292 ] 1293 } 1294 } 1296 Figure 15: Example of a PUT Request to Convey Pipe Information 1297 (Multi-Homed) 1299 A DOTS client can delete a link by sending a PUT request with the 1300 'capacity' attribute set to "0" if other links are still active for 1301 the same DOTS client domain (see Section 7.2.3 for other delete 1302 cases). For example, if a DOTS client domain re-homes (that is, it 1303 changes its ISP), the DOTS client can inform its DOTS server about 1304 this update (e.g., from the network configuration in Figure 10 to the 1305 one shown in Figure 16) by sending the PUT request depicted in 1306 Figure 17. Upon receipt of this request, and assuming no error is 1307 encountered when processing the request, the DOTS server removes 1308 "link1" from its configuration bases for this DOTS client domain. 1309 Note that if the DOTS server receives a PUT request with a 'capacity' 1310 attribute set to "0" for all included links, it MUST reject the 1311 request with a 4.00 (Bad Request). Instead, the DOTS client can use 1312 a DELETE request to delete all links (Section 7.2.3). 1314 ,--,--,--. 1315 ,-' `-. 1316 ( ISP#B ) 1317 `-. ,-' 1318 `--'--'--' 1319 || 1320 || link2 1321 ,--,--,--. 1322 ,-' `-. 1323 ( DOTS Client ) 1324 `-. Domain ,-' 1325 `--'--'--' 1327 Figure 16: Multi-Homed DOTS Client Domain 1329 Header: PUT (Code=0.03) 1330 Uri-Path: ".well-known" 1331 Uri-Path: "dots" 1332 Uri-Path: "tm-setup" 1333 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1334 Uri-Path: "tsid=128" 1335 Content-Format: "application/dots+cbor" 1337 { 1338 "ietf-dots-telemetry:telemetry-setup": { 1339 "telemetry": [ 1340 { 1341 "total-pipe-capacity": [ 1342 { 1343 "link-id": "link1", 1344 "capacity": "0", 1345 "unit": "megabit-ps" 1346 }, 1347 { 1348 "link-id": "link2", 1349 "capacity": "500", 1350 "unit": "megabit-ps" 1351 } 1352 ] 1353 } 1354 ] 1355 } 1356 } 1358 Figure 17: Example of a PUT Request to Convey Pipe Information 1359 (Multi-Homed) 1361 7.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity 1363 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1364 specific installed DOTS client domain pipe related information. The 1365 same procedure as defined in Section 7.1.3 is followed. 1367 To retrieve all pipe information bound to a DOTS client, the DOTS 1368 client proceeds as specified in Section 7.1.1. 1370 7.2.3. Delete Installed DOTS Client Domain Pipe Capacity 1372 A DELETE request is used to delete the installed DOTS client domain 1373 pipe related information. The same procedure as defined in 1374 Section 7.1.4 is followed. 1376 7.3. Telemetry Baseline 1378 A DOTS client can communicate to its DOTS server(s) its normal 1379 traffic baseline and connections capacity: 1381 Total traffic normal baseline: The percentile values representing 1382 the total traffic normal baseline. It can be represented for a 1383 target using 'total-traffic-normal'. 1385 The traffic normal per-protocol ('total-traffic-normal-per- 1386 protocol') baseline is represented for a target and is transport- 1387 protocol specific. 1389 The traffic normal per-port-number ('total-traffic-normal-per- 1390 port') baseline is represented for each port number bound to a 1391 target. 1393 If the DOTS client negotiated percentile values and units 1394 (Section 7.1), these negotiated parameters will be used instead of 1395 the default ones. For each used unit class, the DOTS client MUST 1396 auto-scale so that the appropriate unit is used. 1398 Total connections capacity: If the target is susceptible to 1399 resource-consuming DDoS attacks, the following optional attributes 1400 for the target per transport protocol are useful to detect 1401 resource-consuming DDoS attacks: 1403 * The maximum number of simultaneous connections that are allowed 1404 to the target. 1406 * The maximum number of simultaneous connections that are allowed 1407 to the target per client. 1409 * The maximum number of simultaneous embryonic connections that 1410 are allowed to the target. The term "embryonic connection" 1411 refers to a connection whose connection handshake is not 1412 finished. Embryonic connection is only possible in connection- 1413 oriented transport protocols like TCP or Stream Control 1414 Transmission Protocol (SCTP) [RFC4960]. 1416 * The maximum number of simultaneous embryonic connections that 1417 are allowed to the target per client. 1419 * The maximum number of connections allowed per second to the 1420 target. 1422 * The maximum number of connections allowed per second to the 1423 target per client. 1425 * The maximum number of requests (e.g., HTTP/DNS/SIP requests) 1426 allowed per second to the target. 1428 * The maximum number of requests allowed per second to the target 1429 per client. 1431 * The maximum number of outstanding partial requests allowed to 1432 the target. Attacks relying upon partial requests create a 1433 connection with a target but do not send a complete request 1434 (e.g., HTTP request). 1436 * The maximum number of outstanding partial requests allowed to 1437 the target per client. 1439 The aggregate per transport protocol is captured in 'total- 1440 connection-capacity', while port-specific capabilities are 1441 represented using 'total-connection-capacity-per-port'. 1443 Note that a target resource is identified using the attributes 1444 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1445 fqdn', 'target-uri', or 'alias-name' defined in Section 4.4.1.1 of 1446 [RFC9132]. 1448 The tree structure of the normal traffic baseline is shown in 1449 Figure 18. 1451 structure dots-telemetry: 1452 +-- (telemetry-message-type)? 1453 +--:(telemetry-setup) 1454 | ... 1455 | +-- telemetry* [] 1456 | +-- (direction)? 1457 | | +--:(server-to-client-only) 1458 | | +-- tsid? uint32 1459 | +-- (setup-type)? 1460 | +--:(telemetry-config) 1461 | | ... 1462 | +--:(pipe) 1463 | | ... 1464 | +--:(baseline) 1465 | +-- baseline* [id] 1466 | +-- id 1467 | | uint32 1468 | +-- target-prefix* 1469 | | inet:ip-prefix 1470 | +-- target-port-range* [lower-port] 1471 | | +-- lower-port inet:port-number 1472 | | +-- upper-port? inet:port-number 1473 | +-- target-protocol* uint8 1474 | +-- target-fqdn* 1475 | | inet:domain-name 1476 | +-- target-uri* 1477 | | inet:uri 1478 | +-- alias-name* 1479 | | string 1480 | +-- total-traffic-normal* [unit] 1481 | | +-- unit unit 1482 | | +-- low-percentile-g? yang:gauge64 1483 | | +-- mid-percentile-g? yang:gauge64 1484 | | +-- high-percentile-g? yang:gauge64 1485 | | +-- peak-g? yang:gauge64 1486 | +-- total-traffic-normal-per-protocol* 1487 | | [unit protocol] 1488 | | +-- protocol uint8 1489 | | +-- unit unit 1490 | | +-- low-percentile-g? yang:gauge64 1491 | | +-- mid-percentile-g? yang:gauge64 1492 | | +-- high-percentile-g? yang:gauge64 1493 | | +-- peak-g? yang:gauge64 1494 | +-- total-traffic-normal-per-port* [unit port] 1495 | | +-- port inet:port-number 1496 | | +-- unit unit 1497 | | +-- low-percentile-g? yang:gauge64 1498 | | +-- mid-percentile-g? yang:gauge64 1499 | | +-- high-percentile-g? yang:gauge64 1500 | | +-- peak-g? yang:gauge64 1501 | +-- total-connection-capacity* [protocol] 1502 | | +-- protocol uint8 1503 | | +-- connection? uint64 1504 | | +-- connection-client? uint64 1505 | | +-- embryonic? uint64 1506 | | +-- embryonic-client? uint64 1507 | | +-- connection-ps? uint64 1508 | | +-- connection-client-ps? uint64 1509 | | +-- request-ps? uint64 1510 | | +-- request-client-ps? uint64 1511 | | +-- partial-request-max? uint64 1512 | | +-- partial-request-client-max? uint64 1513 | +-- total-connection-capacity-per-port* 1514 | [protocol port] 1515 | +-- port 1516 | | inet:port-number 1517 | +-- protocol uint8 1518 | +-- connection? uint64 1519 | +-- connection-client? uint64 1520 | +-- embryonic? uint64 1521 | +-- embryonic-client? uint64 1522 | +-- connection-ps? uint64 1523 | +-- connection-client-ps? uint64 1524 | +-- request-ps? uint64 1525 | +-- request-client-ps? uint64 1526 | +-- partial-request-max? uint64 1527 | +-- partial-request-client-max? uint64 1528 +--:(telemetry) 1529 ... 1531 Figure 18: Telemetry Baseline Tree Structure 1533 A DOTS client can share one or multiple normal traffic baselines 1534 (e.g., aggregate or per-prefix baselines), each are uniquely 1535 identified within the DOTS client domain with an identifier 'id'. 1536 This identifier can be used to update a baseline entry, delete a 1537 specific entry, etc. 1539 7.3.1. Conveying DOTS Client Domain Baseline Information 1541 Similar considerations to those specified in Section 7.1.2 are 1542 followed with one exception: 1544 The relative order of two PUT requests carrying DOTS client domain 1545 baseline attributes from a DOTS client is determined by comparing 1546 their respective 'tsid' values. If such two requests have 1547 overlapping targets, the PUT request with higher numeric 'tsid' 1548 value will override the request with a lower numeric 'tsid' value. 1549 The overlapped lower numeric 'tsid' MUST be automatically deleted 1550 and no longer be available. 1552 Two PUT requests from a DOTS client have overlapping targets if there 1553 is a common IP address, IP prefix, FQDN, URI, or alias-name. Also, 1554 two PUT requests from a DOTS client have overlapping targets from the 1555 perspective of the DOTS server if the addresses associated with the 1556 FQDN, URI, or alias are overlapping with each other or with 'target- 1557 prefix'. 1559 DOTS clients SHOULD minimize the number of active 'tsid's used for 1560 baseline information. In order to avoid maintaining a long list of 1561 'tsid's for baseline information, it is RECOMMENDED that DOTS clients 1562 include in a request to update information related to a given target, 1563 the information of other targets (already communicated using a lower 1564 'tsid' value) (assuming this fits within one single datagram). This 1565 update request will override these existing requests and hence 1566 optimize the number of 'tsid' request per DOTS client. 1568 If no target attribute is included in the request, this is an 1569 indication that the baseline information applies for the DOTS client 1570 domain as a whole. 1572 An example of a PUT request to convey the baseline information is 1573 shown in Figure 19. 1575 Header: PUT (Code=0.03) 1576 Uri-Path: ".well-known" 1577 Uri-Path: "dots" 1578 Uri-Path: "tm-setup" 1579 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1580 Uri-Path: "tsid=129" 1581 Content-Format: "application/dots+cbor" 1583 { 1584 "ietf-dots-telemetry:telemetry-setup": { 1585 "telemetry": [ 1586 { 1587 "baseline": [ 1588 { 1589 "id": 1, 1590 "target-prefix": [ 1591 "2001:db8:6401::1/128", 1592 "2001:db8:6401::2/128" 1593 ], 1594 "total-traffic-normal": [ 1595 { 1596 "unit": "megabit-ps", 1597 "peak-g": "60" 1598 } 1599 ] 1600 } 1601 ] 1602 } 1603 ] 1604 } 1605 } 1607 Figure 19: PUT to Conveying the DOTS Traffic Baseline 1609 The DOTS client may share protocol specific baseline information 1610 (e.g., TCP and UDP) as shown in Figure 20. 1612 Header: PUT (Code=0.03) 1613 Uri-Path: ".well-known" 1614 Uri-Path: "dots" 1615 Uri-Path: "tm-setup" 1616 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1617 Uri-Path: "tsid=130" 1618 Content-Format: "application/dots+cbor" 1620 { 1621 "ietf-dots-telemetry:telemetry-setup": { 1622 "telemetry": [ 1623 { 1624 "baseline": [ 1625 { 1626 "id": 1, 1627 "target-prefix": [ 1628 "2001:db8:6401::1/128", 1629 "2001:db8:6401::2/128" 1630 ], 1631 "total-traffic-normal-per-protocol": [ 1632 { 1633 "unit": "megabit-ps", 1634 "protocol": 6, 1635 "peak-g": "50" 1636 }, 1637 { 1638 "unit": "megabit-ps", 1639 "protocol": 17, 1640 "peak-g": "10" 1641 } 1642 ] 1643 } 1644 ] 1645 } 1646 ] 1647 } 1648 } 1650 Figure 20: PUT to Convey the DOTS Traffic Baseline (2) 1652 The normal traffic baseline information should be updated to reflect 1653 legitimate overloads (e.g., flash crowds) to prevent unnecessary 1654 mitigation. 1656 7.3.2. Retrieve Installed Normal Traffic Baseline 1658 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1659 specific installed DOTS client domain baseline traffic information. 1660 The same procedure as defined in Section 7.1.3 is followed. 1662 To retrieve all baseline information bound to a DOTS client, the DOTS 1663 client proceeds as specified in Section 7.1.1. 1665 7.3.3. Delete Installed Normal Traffic Baseline 1667 A DELETE request is used to delete the installed DOTS client domain 1668 normal traffic baseline. The same procedure as defined in 1669 Section 7.1.4 is followed. 1671 7.4. Reset Installed Telemetry Setup 1673 Upon bootstrapping (or reboot or any other event that may alter the 1674 DOTS client setup), a DOTS client MAY send a DELETE request to set 1675 the telemetry parameters to default values. Such a request does not 1676 include any 'tsid'. An example of such a request is depicted in 1677 Figure 21. 1679 Header: DELETE (Code=0.04) 1680 Uri-Path: ".well-known" 1681 Uri-Path: "dots" 1682 Uri-Path: "tm-setup" 1683 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1685 Figure 21: Delete Telemetry Configuration 1687 7.5. Conflict with Other DOTS Clients of the Same Domain 1689 A DOTS server may detect conflicts between requests conveying pipe 1690 and baseline information received from DOTS clients of the same DOTS 1691 client domain. 'conflict-information' is used to report the conflict 1692 to the DOTS client following similar conflict handling discussed in 1693 Section 4.4.1 of [RFC9132]. The conflict cause can be set to one of 1694 these values: 1696 1: Overlapping targets (Section 4.4.1 of [RFC9132]). 1698 TBA: Overlapping pipe scope (see Section 13). 1700 8. DOTS Pre-or-Ongoing Mitigation Telemetry 1702 There are two broad types of DDoS attacks: one is a bandwidth 1703 consuming attack, the other is a target-resource-consuming attack. 1704 This section outlines the set of DOTS telemetry attributes 1705 (Section 8.1) that covers both types of attack. The objective of 1706 these attributes is to allow for the complete knowledge of attacks 1707 and the various particulars that can best characterize attacks. 1709 The "ietf-dots-telemetry" YANG module (Section 11.1) defines the data 1710 structure of a new message type called 'telemetry'. The tree 1711 structure of the 'telemetry' message type is shown in Figure 24. 1713 The pre-or-ongoing-mitigation telemetry attributes are indicated by 1714 the path suffix '/tm'. The '/tm' is appended to the path prefix to 1715 form the URI used with a CoAP request to signal the DOTS telemetry. 1716 Pre-or-ongoing-mitigation telemetry attributes specified in 1717 Section 8.1 can be signaled between DOTS agents. 1719 Pre-or-ongoing-mitigation telemetry attributes may be sent by a DOTS 1720 client or a DOTS server. 1722 DOTS agents SHOULD bind pre-or-ongoing-mitigation telemetry data to 1723 mitigation requests associated with the resources under attack. In 1724 particular, a telemetry PUT request sent after a mitigation request 1725 may include a reference to that mitigation request ('mid-list') as 1726 shown in Figure 22. An example illustrating request correlation by 1727 means of 'target-prefix' is shown in Figure 23. 1729 Many of the pre-or-ongoing-mitigation telemetry data use a unit that 1730 falls under the unit class that is configured following the procedure 1731 described in Section 7.1.2. When generating telemetry data to send 1732 to a peer, the DOTS agent MUST auto-scale so that appropriate unit(s) 1733 are used. 1735 +-----------+ +-----------+ 1736 |DOTS client| |DOTS server| 1737 +-----------+ +-----------+ 1738 | | 1739 |===============Mitigation Request (mid)===============>| 1740 | | 1741 |===============Telemetry (mid-list{mid})==============>| 1742 | | 1744 Figure 22: Example of Request Correlation using 'mid' 1746 +-----------+ +-----------+ 1747 |DOTS client| |DOTS server| 1748 +-----------+ +-----------+ 1749 | | 1750 |<================Telemetry (target-prefix)=============| 1751 | | 1752 |=========Mitigation Request (target-prefix)===========>| 1753 | | 1755 Figure 23: Example of Request Correlation using Target Prefix 1757 DOTS agents MUST NOT send pre-or-ongoing-mitigation telemetry 1758 notifications to the same peer more frequently than once every 1759 'telemetry-notify-interval' (Section 7.1). If a telemetry 1760 notification is sent using a block-like transfer mechanism (e.g., 1761 [I-D.ietf-core-new-block]), this rate limit policy MUST NOT consider 1762 these individual blocks as separate notifications, but as a single 1763 notification. 1765 DOTS pre-or-ongoing-mitigation telemetry request and response 1766 messages MUST be marked as Non-Confirmable messages (Section 2.1 of 1767 [RFC7252]). 1769 structure dots-telemetry: 1770 +-- (telemetry-message-type)? 1771 +--:(telemetry-setup) 1772 | ... 1773 | +-- telemetry* [] 1774 | +-- (direction)? 1775 | | +--:(server-to-client-only) 1776 | | +-- tsid? uint32 1777 | +-- (setup-type)? 1778 | +--:(telemetry-config) 1779 | | ... 1780 | +--:(pipe) 1781 | | ... 1782 | +--:(baseline) 1783 | ... 1784 +--:(telemetry) 1785 +-- pre-or-ongoing-mitigation* [] 1786 +-- (direction)? 1787 | +--:(server-to-client-only) 1788 | +-- tmid? uint32 1789 +-- target 1790 | ... 1791 +-- total-traffic* [unit] 1792 | ... 1793 +-- total-traffic-protocol* [unit protocol] 1794 | ... 1795 +-- total-traffic-port* [unit port] 1796 | ... 1797 +-- total-attack-traffic* [unit] 1798 | ... 1799 +-- total-attack-traffic-protocol* [unit protocol] 1800 | ... 1801 +-- total-attack-traffic-port* [unit port] 1802 | ... 1803 +-- total-attack-connection-protocol* [protocol] 1804 | ... 1805 +-- total-attack-connection-port* [protocol port] 1806 | ... 1807 +-- attack-detail* [vendor-id attack-id] 1808 ... 1810 Figure 24: Telemetry Message Type Tree Structure 1812 8.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes 1814 The description and motivation behind each attribute are presented in 1815 Section 3. 1817 8.1.1. Target 1819 A target resource (Figure 25) is identified using the attributes 1820 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1821 fqdn', 'target-uri', 'alias-name', or a pointer to a mitigation 1822 request ('mid-list'). 1824 +--:(telemetry) 1825 +-- pre-or-ongoing-mitigation* [] 1826 +-- (direction)? 1827 | +--:(server-to-client-only) 1828 | +-- tmid? uint32 1829 +-- target 1830 | +-- target-prefix* inet:ip-prefix 1831 | +-- target-port-range* [lower-port] 1832 | | +-- lower-port inet:port-number 1833 | | +-- upper-port? inet:port-number 1834 | +-- target-protocol* uint8 1835 | +-- target-fqdn* inet:domain-name 1836 | +-- target-uri* inet:uri 1837 | +-- alias-name* string 1838 | +-- mid-list* uint32 1839 +-- total-traffic* [unit] 1840 | ... 1841 +-- total-traffic-protocol* [unit protocol] 1842 | ... 1843 +-- total-traffic-port* [unit port] 1844 | ... 1845 +-- total-attack-traffic* [unit] 1846 | ... 1847 +-- total-attack-traffic-protocol* [unit protocol] 1848 | ... 1849 +-- total-attack-traffic-port* [unit port] 1850 | ... 1851 +-- total-attack-connection-protocol* [protocol] 1852 | ... 1853 +-- total-attack-connection-port* [protocol port] 1854 | ... 1855 +-- attack-detail* [vendor-id attack-id] 1856 ... 1858 Figure 25: Target Tree Structure 1860 At least one of the attributes 'target-prefix', 'target-fqdn', 1861 'target-uri', 'alias-name', or 'mid-list' MUST be present in the 1862 target definition. 1864 If the target is susceptible to bandwidth-consuming attacks, the 1865 attributes representing the percentile values of the 'attack-id' 1866 attack traffic are included. 1868 If the target is susceptible to resource-consuming DDoS attacks, the 1869 attributes defined in Section 8.1.4 are applicable for representing 1870 the attack. 1872 At least the 'target' attribute and one other pre-or-ongoing- 1873 mitigation attribute MUST be present in the DOTS telemetry message. 1875 8.1.2. Total Traffic 1877 The 'total-traffic' attribute (Figure 26) conveys the percentile 1878 values (including peak and current observed values) of the total 1879 observed traffic. More fine-grained information about the total 1880 traffic can be conveyed in the 'total-traffic-protocol' and 'total- 1881 traffic-port' attributes. 1883 The 'total-traffic-protocol' attribute represents the total traffic 1884 for a target and is transport-protocol specific. 1886 The 'total-traffic-port' represents the total traffic for a target 1887 per port number. 1889 +--:(telemetry) 1890 +-- pre-or-ongoing-mitigation* [] 1891 +-- (direction)? 1892 | +--:(server-to-client-only) 1893 | +-- tmid? uint32 1894 +-- target 1895 | ... 1896 +-- total-traffic* [unit] 1897 | +-- unit unit 1898 | +-- low-percentile-g? yang:gauge64 1899 | +-- mid-percentile-g? yang:gauge64 1900 | +-- high-percentile-g? yang:gauge64 1901 | +-- peak-g? yang:gauge64 1902 | +-- current-g? yang:gauge64 1903 +-- total-traffic-protocol* [unit protocol] 1904 | +-- protocol uint8 1905 | +-- unit unit 1906 | +-- low-percentile-g? yang:gauge64 1907 | +-- mid-percentile-g? yang:gauge64 1908 | +-- high-percentile-g? yang:gauge64 1909 | +-- peak-g? yang:gauge64 1910 | +-- current-g? yang:gauge64 1911 +-- total-traffic-port* [unit port] 1912 | +-- port inet:port-number 1913 | +-- unit unit 1914 | +-- low-percentile-g? yang:gauge64 1915 | +-- mid-percentile-g? yang:gauge64 1916 | +-- high-percentile-g? yang:gauge64 1917 | +-- peak-g? yang:gauge64 1918 | +-- current-g? yang:gauge64 1919 +-- total-attack-traffic* [unit] 1920 | ... 1921 +-- total-attack-traffic-protocol* [unit protocol] 1922 | ... 1923 +-- total-attack-traffic-port* [unit port] 1924 | ... 1925 +-- total-attack-connection-protocol* [protocol] 1926 | ... 1927 +-- total-attack-connection-port* [protocol port] 1928 | ... 1929 +-- attack-detail* [vendor-id attack-id] 1930 ... 1932 Figure 26: Total Traffic Tree Structure 1934 8.1.3. Total Attack Traffic 1936 The 'total-attack-traffic' attribute (Figure 27) conveys the total 1937 observed attack traffic. More fine-grained information about the 1938 total attack traffic can be conveyed in the 'total-attack-traffic- 1939 protocol' and 'total-attack-traffic-port' attributes. 1941 The 'total-attack-traffic-protocol' attribute represents the total 1942 attack traffic for a target and is transport-protocol specific. 1944 The 'total-attack-traffic-port' attribute represents the total attack 1945 traffic for a target per port number. 1947 +--:(telemetry) 1948 +-- pre-or-ongoing-mitigation* [] 1949 +-- (direction)? 1950 | +--:(server-to-client-only) 1951 | +-- tmid? uint32 1952 +-- target 1953 | ... 1954 +-- total-traffic* [unit] 1955 | ... 1956 +-- total-traffic-protocol* [unit protocol] 1957 | ... 1958 +-- total-traffic-port* [unit port] 1959 | ... 1960 +-- total-attack-traffic* [unit] 1961 | +-- unit unit 1962 | +-- low-percentile-g? yang:gauge64 1963 | +-- mid-percentile-g? yang:gauge64 1964 | +-- high-percentile-g? yang:gauge64 1965 | +-- peak-g? yang:gauge64 1966 | +-- current-g? yang:gauge64 1967 +-- total-attack-traffic-protocol* [unit protocol] 1968 | +-- protocol uint8 1969 | +-- unit unit 1970 | +-- low-percentile-g? yang:gauge64 1971 | +-- mid-percentile-g? yang:gauge64 1972 | +-- high-percentile-g? yang:gauge64 1973 | +-- peak-g? yang:gauge64 1974 | +-- current-g? yang:gauge64 1975 +-- total-attack-traffic-port* [unit port] 1976 | +-- port inet:port-number 1977 | +-- unit unit 1978 | +-- low-percentile-g? yang:gauge64 1979 | +-- mid-percentile-g? yang:gauge64 1980 | +-- high-percentile-g? yang:gauge64 1981 | +-- peak-g? yang:gauge64 1982 | +-- current-g? yang:gauge64 1983 +-- total-attack-connection-protocol* [protocol] 1984 | ... 1985 +-- total-attack-connection-port* [protocol port] 1986 | ... 1987 +-- attack-detail* [vendor-id attack-id] 1988 ... 1990 Figure 27: Total Attack Traffic Tree Structure 1992 8.1.4. Total Attack Connections 1994 If the target is susceptible to resource-consuming DDoS attacks, the 1995 'total-attack-connection-protocol' attribute is used to convey the 1996 percentile values (including peak and current observed values) of 1997 various attributes related to the total attack connections. The 1998 following optional subattributes for the target per transport 1999 protocol are included to represent the attack characteristics: 2001 * The number of simultaneous attack connections to the target. 2002 * The number of simultaneous embryonic connections to the target. 2003 * The number of attack connections per second to the target. 2004 * The number of attack requests per second to the target. 2005 * The number of attack partial requests to the target. 2007 The total attack connections per port number is represented using the 2008 'total-attack-connection-port' attribute. 2010 +--:(telemetry) 2011 +-- pre-or-ongoing-mitigation* [] 2012 +-- (direction)? 2013 | +--:(server-to-client-only) 2014 | +-- tmid? uint32 2015 +-- target 2016 | ... 2017 +-- total-traffic* [unit] 2018 | ... 2019 +-- total-traffic-protocol* [unit protocol] 2020 | ... 2021 +-- total-traffic-port* [unit port] 2022 | ... 2023 +-- total-attack-traffic* [unit] 2024 | ... 2025 +-- total-attack-traffic-protocol* [unit protocol] 2026 | ... 2027 +-- total-attack-traffic-port* [unit port] 2028 | ... 2029 +-- total-attack-connection-protocol* [protocol] 2030 | +-- protocol uint8 2031 | +-- connection-c 2032 | | +-- low-percentile-g? yang:gauge64 2033 | | +-- mid-percentile-g? yang:gauge64 2034 | | +-- high-percentile-g? yang:gauge64 2035 | | +-- peak-g? yang:gauge64 2036 | | +-- current-g? yang:gauge64 2037 | +-- embryonic-c 2038 | | +-- low-percentile-g? yang:gauge64 2039 | | +-- mid-percentile-g? yang:gauge64 2040 | | +-- high-percentile-g? yang:gauge64 2041 | | +-- peak-g? yang:gauge64 2042 | | +-- current-g? yang:gauge64 2043 | +-- connection-ps-c 2044 | | +-- low-percentile-g? yang:gauge64 2045 | | +-- mid-percentile-g? yang:gauge64 2046 | | +-- high-percentile-g? yang:gauge64 2047 | | +-- peak-g? yang:gauge64 2048 | | +-- current-g? yang:gauge64 2049 | +-- request-ps-c 2050 | | +-- low-percentile-g? yang:gauge64 2051 | | +-- mid-percentile-g? yang:gauge64 2052 | | +-- high-percentile-g? yang:gauge64 2053 | | +-- peak-g? yang:gauge64 2054 | | +-- current-g? yang:gauge64 2055 | +-- partial-request-c 2056 | +-- low-percentile-g? yang:gauge64 2057 | +-- mid-percentile-g? yang:gauge64 2058 | +-- high-percentile-g? yang:gauge64 2059 | +-- peak-g? yang:gauge64 2060 | +-- current-g? yang:gauge64 2061 +-- total-attack-connection-port* [protocol port] 2062 | +-- protocol uint8 2063 | +-- port inet:port-number 2064 | +-- connection-c 2065 | | +-- low-percentile-g? yang:gauge64 2066 | | +-- mid-percentile-g? yang:gauge64 2067 | | +-- high-percentile-g? yang:gauge64 2068 | | +-- peak-g? yang:gauge64 2069 | | +-- current-g? yang:gauge64 2070 | +-- embryonic-c 2071 | | +-- low-percentile-g? yang:gauge64 2072 | | +-- mid-percentile-g? yang:gauge64 2073 | | +-- high-percentile-g? yang:gauge64 2074 | | +-- peak-g? yang:gauge64 2075 | | +-- current-g? yang:gauge64 2076 | +-- connection-ps-c 2077 | | +-- low-percentile-g? yang:gauge64 2078 | | +-- mid-percentile-g? yang:gauge64 2079 | | +-- high-percentile-g? yang:gauge64 2080 | | +-- peak-g? yang:gauge64 2081 | | +-- current-g? yang:gauge64 2082 | +-- request-ps-c 2083 | | +-- low-percentile-g? yang:gauge64 2084 | | +-- mid-percentile-g? yang:gauge64 2085 | | +-- high-percentile-g? yang:gauge64 2086 | | +-- peak-g? yang:gauge64 2087 | | +-- current-g? yang:gauge64 2088 | +-- partial-request-c 2089 | +-- low-percentile-g? yang:gauge64 2090 | +-- mid-percentile-g? yang:gauge64 2091 | +-- high-percentile-g? yang:gauge64 2092 | +-- peak-g? yang:gauge64 2093 | +-- current-g? yang:gauge64 2094 +-- attack-detail* [vendor-id attack-id] 2095 ... 2097 Figure 28: Total Attack Connections Tree Structure 2099 8.1.5. Attack Details 2101 This attribute (depicted in Figure 29) is used to signal a set of 2102 details characterizing an attack. The following subattributes 2103 describing the ongoing attack can be signalled as attack details: 2105 vendor-id: Vendor ID is a security vendor's enterprise number as 2106 registered in the IANA's "Private Enterprise Numbers" registry 2107 [Private-Enterprise-Numbers]. 2109 attack-id: Unique identifier assigned for the attack by a vendor. 2110 This parameter MUST be present independent of whether 'attack- 2111 description' is included or not. 2113 attack-description: Textual representation of the attack 2114 description. Natural Language Processing techniques (e.g., word 2115 embedding) might provide some utility in mapping the attack 2116 description to an attack type. Textual representation of attack 2117 solves two problems: (a) avoids the need to create mapping tables 2118 manually between vendors and (b) avoids the need to standardize 2119 attack types which keep evolving. 2121 attack-severity: Attack severity level. This attribute takes one of 2122 the values defined in Section 3.12.2 of [RFC7970]. 2124 start-time: The time the attack started. The attack's start time is 2125 expressed in seconds relative to 1970-01-01T00:00Z (Section 3.4.2 2126 of [RFC8949]). The CBOR encoding is modified so that the leading 2127 tag 1 (epoch-based date/time) MUST be omitted. 2129 end-time: The time the attack ended. The attack end time is 2130 expressed in seconds relative to 1970-01-01T00:00Z (Section 3.4.2 2131 of [RFC8949]). The CBOR encoding is modified so that the leading 2132 tag 1 (epoch-based date/time) MUST be omitted. 2134 source-count: A count of sources involved in the attack targeting 2135 the victim. 2137 top-talker: A list of attack sources that are involved in an attack 2138 and which are generating an important part of the attack traffic. 2139 The top talkers are represented using the 'source-prefix'. 2141 'spoofed-status' indicates whether a top talker is a spoofed IP 2142 address (e.g., reflection attacks) or not. If no 'spoofed-status' 2143 data node is included, this means that the spoofing status is 2144 unknown. 2146 If the target is being subjected to a bandwidth-consuming attack, 2147 a statistical profile of the attack traffic from each of the top 2148 talkers is included ('total-attack-traffic', Section 8.1.3). 2150 If the target is being subjected to a resource-consuming DDoS 2151 attack, the same attributes defined in Section 8.1.4 are 2152 applicable for characterizing the attack on a per-talker basis. 2154 +--:(telemetry) 2155 +-- pre-or-ongoing-mitigation* [] 2156 +-- (direction)? 2157 | +--:(server-to-client-only) 2158 | +-- tmid? uint32 2159 +-- target 2160 | ... 2161 +-- total-traffic* [unit] 2162 | ... 2163 +-- total-traffic-protocol* [unit protocol] 2164 | ... 2165 +-- total-traffic-port* [unit port] 2166 | ... 2167 +-- total-attack-traffic* [unit] 2168 | ... 2169 +-- total-attack-traffic-protocol* [unit protocol] 2170 | ... 2171 +-- total-attack-traffic-port* [unit port] 2172 | ... 2173 +-- total-attack-connection-protocol* [protocol] 2174 | ... 2175 +-- total-attack-connection-port* [protocol port] 2176 | ... 2177 +-- attack-detail* [vendor-id attack-id] 2178 +-- vendor-id uint32 2179 +-- attack-id uint32 2180 +-- attack-description? string 2181 +-- attack-severity? attack-severity 2182 +-- start-time? uint64 2183 +-- end-time? uint64 2184 +-- source-count 2185 | +-- low-percentile-g? yang:gauge64 2186 | +-- mid-percentile-g? yang:gauge64 2187 | +-- high-percentile-g? yang:gauge64 2188 | +-- peak-g? yang:gauge64 2189 | +-- current-g? yang:gauge64 2190 +-- top-talker 2191 +-- talker* [source-prefix] 2192 +-- spoofed-status? boolean 2193 +-- source-prefix inet:ip-prefix 2194 +-- source-port-range* [lower-port] 2195 | +-- lower-port inet:port-number 2196 | +-- upper-port? inet:port-number 2197 +-- source-icmp-type-range* [lower-type] 2198 | +-- lower-type uint8 2199 | +-- upper-type? uint8 2200 +-- total-attack-traffic* [unit] 2201 | +-- unit unit 2202 | +-- low-percentile-g? yang:gauge64 2203 | +-- mid-percentile-g? yang:gauge64 2204 | +-- high-percentile-g? yang:gauge64 2205 | +-- peak-g? yang:gauge64 2206 | +-- current-g? yang:gauge64 2207 +-- total-attack-connection-protocol* 2208 [protocol] 2209 +-- protocol uint8 2210 +-- connection-c 2211 | +-- low-percentile-g? yang:gauge64 2212 | +-- mid-percentile-g? yang:gauge64 2213 | +-- high-percentile-g? yang:gauge64 2214 | +-- peak-g? yang:gauge64 2215 | +-- current-g? yang:gauge64 2216 +-- embryonic-c 2217 | +-- low-percentile-g? yang:gauge64 2218 | +-- mid-percentile-g? yang:gauge64 2219 | +-- high-percentile-g? yang:gauge64 2220 | +-- peak-g? yang:gauge64 2221 | +-- current-g? yang:gauge64 2222 +-- connection-ps-c 2223 | +-- low-percentile-g? yang:gauge64 2224 | +-- mid-percentile-g? yang:gauge64 2225 | +-- high-percentile-g? yang:gauge64 2226 | +-- peak-g? yang:gauge64 2227 | +-- current-g? yang:gauge64 2228 +-- request-ps-c 2229 | +-- low-percentile-g? yang:gauge64 2230 | +-- mid-percentile-g? yang:gauge64 2231 | +-- high-percentile-g? yang:gauge64 2232 | +-- peak-g? yang:gauge64 2233 | +-- current-g? yang:gauge64 2234 +-- partial-request-c 2235 +-- low-percentile-g? yang:gauge64 2236 +-- mid-percentile-g? yang:gauge64 2237 +-- high-percentile-g? yang:gauge64 2238 +-- peak-g? yang:gauge64 2239 +-- current-g? yang:gauge64 2241 Figure 29: Attack Detail Tree Structure 2243 In order to optimize the size of telemetry data conveyed over the 2244 DOTS signal channel, DOTS agents MAY use the DOTS data channel 2245 [RFC8783] to exchange vendor specific attack mapping details (that 2246 is, {vendor identifier, attack identifier} ==> textual representation 2247 of the attack description). As such, DOTS agents do not have to 2248 convey systematically an attack description in their telemetry 2249 messages over the DOTS signal channel. Refer to Section 8.1.6. 2251 8.1.6. Vendor Attack Mapping 2253 Multiple mappings for different vendor identifiers may be used; the 2254 DOTS agent transmitting telemetry information can elect to use one or 2255 more vendor mappings even in the same telemetry message. 2257 Note: It is possible that a DOTS server is making use of multiple 2258 DOTS mitigators; each from a different vendor. How telemetry 2259 information and vendor mappings are exchanged between DOTS servers 2260 and DOTS mitigators is outside the scope of this document. 2262 DOTS clients and servers may be provided with mappings from different 2263 vendors and so have their own different sets of vendor attack 2264 mappings. A DOTS agent MUST accept receipt of telemetry data with a 2265 vendor identifier that is different to the one it uses to transmit 2266 telemetry data. Furthermore, it is possible that the DOTS client and 2267 DOTS server are provided by the same vendor, but the vendor mapping 2268 tables are at different revisions. The DOTS client SHOULD transmit 2269 telemetry information using any vendor mapping(s) that it provided to 2270 the DOTS server (e.g., using a POST as depicted in Figure 34) and the 2271 DOTS server SHOULD use any vendor mappings(s) provided to the DOTS 2272 client when transmitting telemetry data to the peer DOTS agent. 2274 The "ietf-dots-mapping" YANG module defined in Section 11.2 augments 2275 the "ietf-dots-data-channel" [RFC8783] module. The tree structure of 2276 the "ietf-dots-mapping" module is shown in Figure 30. 2278 module: ietf-dots-mapping 2279 augment /data-channel:dots-data/data-channel:dots-client: 2280 +--rw vendor-mapping {dots-telemetry}? 2281 +--rw vendor* [vendor-id] 2282 +--rw vendor-id uint32 2283 +--rw vendor-name? string 2284 +--rw last-updated uint64 2285 +--rw attack-mapping* [attack-id] 2286 +--rw attack-id uint32 2287 +--rw attack-description string 2288 augment /data-channel:dots-data/data-channel:capabilities: 2289 +--ro vendor-mapping-enabled? boolean {dots-telemetry}? 2290 augment /data-channel:dots-data: 2291 +--ro vendor-mapping {dots-telemetry}? 2292 +--ro vendor* [vendor-id] 2293 +--ro vendor-id uint32 2294 +--ro vendor-name? string 2295 +--ro last-updated uint64 2296 +--ro attack-mapping* [attack-id] 2297 +--ro attack-id uint32 2298 +--ro attack-description string 2300 Figure 30: Vendor Attack Mapping Tree Structure 2302 A DOTS client sends a GET request to retrieve the capabilities 2303 supported by a DOTS server as per Section 7.1 of [RFC8783]. This 2304 request is meant to assess whether the capability of sharing vendor 2305 attack mapping details is supported by the server (i.e., check the 2306 value of 'vendor-mapping-enabled'). 2308 If 'vendor-mapping-enabled' is set to 'true', a DOTS client MAY send 2309 a GET request to retrieve the DOTS server's vendor attack mapping 2310 details. An example of such a GET request is shown in Figure 31. 2312 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2313 /ietf-dots-mapping:vendor-mapping HTTP/1.1 2314 Host: example.com 2315 Accept: application/yang-data+json 2317 Figure 31: GET to Retrieve the Vendor Attack Mappings of a DOTS 2318 Server 2320 A DOTS client can retrieve only the list of vendors supported by the 2321 DOTS server. It does so by setting the "depth" parameter 2322 (Section 4.8.2 of [RFC8040]) to "3" in the GET request as shown in 2323 Figure 32. An example of a response body received from the DOTS 2324 server as a response to such a request is illustrated in Figure 33. 2326 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2327 /ietf-dots-mapping:vendor-mapping?depth=3 HTTP/1.1 2328 Host: example.com 2329 Accept: application/yang-data+json 2331 Figure 32: GET to Retrieve the Vendors List used by a DOTS Server 2333 { 2334 "ietf-dots-mapping:vendor-mapping": { 2335 "vendor": [ 2336 { 2337 "vendor-id": 32473, 2338 "vendor-name": "mitigator-s", 2339 "last-updated": "1629898758", 2340 "attack-mapping": [] 2341 } 2342 ] 2343 } 2344 } 2346 Figure 33: Response to a GET to Retrieve the Vendors List used by 2347 a DOTS Server 2349 The DOTS client repeats the above procedure regularly (e.g., once a 2350 week) to update the DOTS server's vendor attack mapping details. 2352 If the DOTS client concludes that the DOTS server does not have any 2353 reference to the specific vendor attack mapping details, the DOTS 2354 client uses a POST request to install its vendor attack mapping 2355 details. An example of such a POST request is depicted in Figure 34. 2357 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2358 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2359 Host: example.com 2360 Content-Type: application/yang-data+json 2362 { 2363 "ietf-dots-mapping:vendor-mapping": { 2364 "vendor": [ 2365 { 2366 "vendor-id": 345, 2367 "vendor-name": "mitigator-c", 2368 "last-updated": "1629898958", 2369 "attack-mapping": [ 2370 { 2371 "attack-id": 1, 2372 "attack-description": 2373 "Include a description of this attack" 2374 }, 2375 { 2376 "attack-id": 2, 2377 "attack-description": 2378 "Again, include a description of the attack" 2379 } 2380 ] 2381 } 2382 ] 2383 } 2384 } 2386 Figure 34: POST to Install Vendor Attack Mapping Details 2388 The DOTS server indicates the result of processing the POST request 2389 using the status-line. A "201 Created" status-line MUST be returned 2390 in the response if the DOTS server has accepted the vendor attack 2391 mapping details. If the request is missing a mandatory attribute or 2392 contains an invalid or unknown parameter, "400 Bad Request" status- 2393 line MUST be returned by the DOTS server in the response. The error- 2394 tag is set to "missing-attribute", "invalid-value", or "unknown- 2395 element" as a function of the encountered error. 2397 If the request is received via a server-domain DOTS gateway, but the 2398 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2399 is expected to be supplied, the DOTS server MUST reply with "403 2400 Forbidden" status-line and the error-tag "access-denied". Upon 2401 receipt of this message, the DOTS client MUST register (Section 5.1 2402 of [RFC8783]). 2404 The DOTS client uses the PUT request to modify its vendor attack 2405 mapping details maintained by the DOTS server (e.g., add a new 2406 mapping entry, update an existing mapping). 2408 A DOTS client uses a GET request to retrieve its vendor attack 2409 mapping details as maintained by the DOTS server (Figure 35). 2411 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2412 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2413 /ietf-dots-mapping:vendor-mapping?\ 2414 content=all HTTP/1.1 2415 Host: example.com 2416 Accept: application/yang-data+json 2418 Figure 35: GET to Retrieve Installed Vendor Attack Mapping Details 2420 When conveying attack details in DOTS telemetry messages (Sections 2421 8.2, 8.3, and 9), DOTS agents MUST NOT include the 'attack- 2422 description' attribute unless the corresponding attack mapping 2423 details were not previously shared with the peer DOTS agent. 2425 8.2. From DOTS Clients to DOTS Servers 2427 DOTS clients use PUT requests to signal pre-or-ongoing-mitigation 2428 telemetry to DOTS servers. An example of such a request is shown in 2429 Figure 36. 2431 Header: PUT (Code=0.03) 2432 Uri-Path: ".well-known" 2433 Uri-Path: "dots" 2434 Uri-Path: "tm" 2435 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2436 Uri-Path: "tmid=123" 2437 Content-Format: "application/dots+cbor" 2439 { 2440 "ietf-dots-telemetry:telemetry": { 2441 "pre-or-ongoing-mitigation": [ 2442 { 2443 "target": { 2444 "target-prefix": [ 2445 "2001:db8::1/128" 2446 ] 2447 }, 2448 "total-attack-traffic-protocol": [ 2449 { 2450 "protocol": 17, 2451 "unit": "megabit-ps", 2452 "mid-percentile-g": "900" 2453 } 2454 ], 2455 "attack-detail": [ 2456 { 2457 "vendor-id": 32473, 2458 "attack-id": 77, 2459 "start-time": "1608336568", 2460 "attack-severity": "high" 2461 } 2462 ] 2463 } 2464 ] 2465 } 2466 } 2468 Figure 36: PUT to Send Pre-or-Ongoing-Mitigation Telemetry 2470 'cuid' is a mandatory Uri-Path parameter for DOTS PUT requests. 2472 The following additional Uri-Path parameter is defined: 2474 tmid: Telemetry Identifier is an identifier for the DOTS pre-or- 2475 ongoing-mitigation telemetry data represented as an integer. 2476 This identifier MUST be generated by DOTS clients. 'tmid' values 2477 MUST increase monotonically (when a new PUT is generated by a 2478 DOTS client to convey pre-or-ongoing-mitigation telemetry). 2480 The procedure specified in Section 4.4.1 of [RFC9132] for 'mid' 2481 rollover MUST be followed for 'tmid' rollover. 2483 This is a mandatory attribute. 'tmid' MUST follow 'cuid'. 2485 'cuid' and 'tmid' MUST NOT appear in the PUT request message body. 2487 At least the 'target' attribute and another pre-or-ongoing-mitigation 2488 attribute (Section 8.1) MUST be present in the PUT request. If only 2489 the 'target' attribute is present, this request is handled as per 2490 Section 8.3. 2492 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2493 mitigation telemetry from a DOTS client is determined by comparing 2494 their respective 'tmid' values. If two such requests have an 2495 overlapping 'target', the PUT request with higher numeric 'tmid' 2496 value will override the request with a lower numeric 'tmid' value. 2497 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2498 no longer be available. 2500 The DOTS server indicates the result of processing a PUT request 2501 using CoAP Response Codes. In particular, the 2.04 (Changed) 2502 Response Code is returned if the DOTS server has accepted the pre-or- 2503 ongoing-mitigation telemetry. The 5.03 (Service Unavailable) 2504 Response Code is returned if the DOTS server has erred. 5.03 uses the 2505 Max-Age Option to indicate the number of seconds after which to 2506 retry. 2508 How long a DOTS server maintains a 'tmid' as active or logs the 2509 enclosed telemetry information is implementation specific. Note that 2510 if a 'tmid' is still active, then logging details are updated by the 2511 DOTS server as a function of the updates received from the peer DOTS 2512 client. 2514 A DOTS client that lost the state of its active 'tmid's or has to set 2515 'tmid' back to zero (e.g., crash or restart) MUST send a GET request 2516 to the DOTS server to retrieve the list of active 'tmid' values. The 2517 DOTS client may then delete 'tmid's that should not be active anymore 2518 (Figure 37). Sending a DELETE with no 'tmid' indicates that all 2519 'tmid's must be deactivated (Figure 38). 2521 Header: DELETE (Code=0.04) 2522 Uri-Path: ".well-known" 2523 Uri-Path: "dots" 2524 Uri-Path: "tm" 2525 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2526 Uri-Path: "tmid=123" 2527 Figure 37: Delete a Pre-or-Ongoing-Mitigation Telemetry 2529 Header: DELETE (Code=0.04) 2530 Uri-Path: ".well-known" 2531 Uri-Path: "dots" 2532 Uri-Path: "tm" 2533 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2535 Figure 38: Delete All Pre-or-Ongoing-Mitigation Telemetry 2537 8.3. From DOTS Servers to DOTS Clients 2539 The pre-or-ongoing-mitigation data (attack details, in particular) 2540 can also be signaled from DOTS servers to DOTS clients. For example, 2541 a DOTS server co-located with a DDoS detector can collect monitoring 2542 information from the target network, identify a DDoS attack using 2543 statistical analysis or deep learning techniques, and signal the 2544 attack details to the DOTS client. 2546 The DOTS client can use the attack details to decide whether to 2547 trigger a DOTS mitigation request or not. Furthermore, the security 2548 operations personnel at the DOTS client domain can use the attack 2549 details to determine the protection strategy and select the 2550 appropriate DOTS server for mitigating the attack. 2552 In order to receive pre-or-ongoing-mitigation telemetry notifications 2553 from a DOTS server, a DOTS client MUST send a PUT (followed by a GET) 2554 with the target filter. An example of such a PUT request is shown in 2555 Figure 39. In order to avoid maintaining a long list of such 2556 requests, it is RECOMMENDED that DOTS clients include all targets in 2557 the same request (assuming this fits within one single datagram). 2558 DOTS servers may be instructed to restrict the number of pre-or- 2559 ongoing-mitigation requests per DOTS client domain. The pre-or- 2560 ongoing mitigation requests MUST be maintained in an active state by 2561 the DOTS server until a delete request is received from the same DOTS 2562 client to clear this pre-or-ongoing-mitigation telemetry or when the 2563 DOTS client is considered inactive (e.g., Section 3.5 of [RFC8783]). 2565 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2566 mitigation telemetry from a DOTS client is determined by comparing 2567 their respective 'tmid' values. If such two requests have 2568 overlapping 'target', the PUT request with higher numeric 'tmid' 2569 value will override the request with a lower numeric 'tmid' value. 2570 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2571 no longer be available. 2573 Header: PUT (Code=0.03) 2574 Uri-Path: ".well-known" 2575 Uri-Path: "dots" 2576 Uri-Path: "tm" 2577 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2578 Uri-Path: "tmid=567" 2579 Content-Format: "application/dots+cbor" 2581 { 2582 "ietf-dots-telemetry:telemetry": { 2583 "pre-or-ongoing-mitigation": [ 2584 { 2585 "target": { 2586 "target-prefix": [ 2587 "2001:db8::/32" 2588 ] 2589 } 2590 } 2591 ] 2592 } 2593 } 2595 Figure 39: PUT to Request Pre-or-Ongoing-Mitigation Telemetry 2597 DOTS clients of the same domain can request to receive pre-or- 2598 ongoing-mitigation telemetry bound to the same target without being 2599 considered to be "overlapping" and in conflict. 2601 Once the PUT request to instantiate request state on the server has 2602 succeeded, the DOTS client issues a GET request to receive ongoing 2603 telemtry updates. The client uses the Observe Option, set to '0' 2604 (register), in the GET request to receive asynchronous notifications 2605 carrying pre-or-ongoing-mitigation telemetry data from the DOTS 2606 server. The GET request can specify a specific 'tmid' (Figure 40) or 2607 omit the 'tmid' (Figure 41) to receive updates on all active requests 2608 from that client. 2610 Header: GET (Code=0.01) 2611 Uri-Path: ".well-known" 2612 Uri-Path: "dots" 2613 Uri-Path: "tm" 2614 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2615 Uri-Path: "tmid=567" 2616 Observe: 0 2618 Figure 40: GET to Subscribe to Telemetry Asynchronous 2619 Notifications for a Specific 'tmid' 2621 Header: GET (Code=0.01) 2622 Uri-Path: ".well-known" 2623 Uri-Path: "dots" 2624 Uri-Path: "tm" 2625 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2626 Observe: 0 2628 Figure 41: GET to Subscribe to Telemetry Asynchronous 2629 Notifications for All 'tmids' 2631 The DOTS client can use a filter to request a subset of the 2632 asynchronous notifications from the DOTS server by indicating one or 2633 more Uri-Query options in its GET request. A Uri-Query option can 2634 include the following parameters to restrict the notifications based 2635 on the attack target: 'target-prefix', 'target-port', 'target- 2636 protocol', 'target-fqdn', 'target-uri', 'alias-name', 'mid', and 'c' 2637 (content) (Section 5.4). Furthermore: 2639 If more than one Uri-Query option is included in a request, these 2640 options are interpreted in the same way as when multiple target 2641 attributes are included in a message body (Section 4.4.1 of 2642 [RFC9132]). 2644 If multiple values of a query parameter are to be included in a 2645 request, these values MUST be included in the same Uri-Query 2646 option and separated by a "," character without any spaces. 2648 Range values (i.e., a contiguous inclusive block) can be included 2649 for the 'target-port', 'target-protocol', and 'mid' parameters by 2650 indicating the two boundary values separated by a "-" character. 2652 Wildcard names (i.e., a name with the leftmost label is the "*" 2653 character) can be included in 'target-fqdn' or 'target-uri' 2654 parameters. DOTS clients MUST NOT include a name in which the "*" 2655 character is included in a label other than the leftmost label. 2656 "*.example.com" is an example of a valid wildcard name that can be 2657 included as a value of the 'target-fqdn' parameter in an Uri-Query 2658 option. 2660 DOTS clients may also filter out the asynchronous notifications from 2661 the DOTS server by indicating information about a specific attack 2662 source. To that aim, a DOTS client may include 'source-prefix', 2663 'source-port', or 'source-icmp-type' in a Uri-Query option. The same 2664 considerations (ranges, multiple values) specified for target 2665 attributes apply for source attributes. Special care SHOULD be taken 2666 when using these filters as their use may cause some attacks may be 2667 hidden to the requesting DOTS client (e.g., if the attack changes its 2668 source information). 2670 Requests with invalid query types (e.g., not supported, malformed) 2671 received by the DOTS server MUST be rejected with a 4.00 (Bad 2672 Request) response code. 2674 An example of a request to subscribe to asynchronous telemetry 2675 notifications regarding UDP traffic is shown in Figure 42. This 2676 filter will be applied for all 'tmid's. 2678 Header: GET (Code=0.01) 2679 Uri-Path: ".well-known" 2680 Uri-Path: "dots" 2681 Uri-Path: "tm" 2682 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2683 Uri-Query: "target-protocol=17" 2684 Observe: 0 2686 Figure 42: GET Request to Receive Telemetry Asynchronous 2687 Notifications Filtered using Uri-Query 2689 The DOTS server will send asynchronous notifications to the DOTS 2690 client when an attack event is detected following similar 2691 considerations as in Section 4.4.2.1 of [RFC9132]. An example of a 2692 pre-or-ongoing-mitigation telemetry notification is shown in 2693 Figure 43. 2695 { 2696 "ietf-dots-telemetry:telemetry": { 2697 "pre-or-ongoing-mitigation": [ 2698 { 2699 "tmid": 567, 2700 "target": { 2701 "target-prefix": [ 2702 "2001:db8::1/128" 2703 ] 2704 }, 2705 "target-protocol": [ 2706 17 2707 ], 2708 "total-attack-traffic": [ 2709 { 2710 "unit": "megabit-ps", 2711 "mid-percentile-g": "900" 2712 } 2713 ], 2714 "attack-detail": [ 2715 { 2716 "vendor-id": 32473, 2717 "attack-id": 77, 2718 "start-time": "1618339785", 2719 "attack-severity": "high" 2720 } 2721 ] 2722 } 2723 ] 2724 } 2725 } 2727 Figure 43: Message Body of a Pre-or-Ongoing-Mitigation Telemetry 2728 Notification from the DOTS Server 2730 A DOTS server sends the aggregate data for a target using 'total- 2731 attack-traffic' attribute. The aggregate assumes that Uri-Query 2732 filters are applied on the target. The DOTS server MAY include more 2733 fine-grained data when needed (that is, 'total-attack-traffic- 2734 protocol' and 'total-attack-traffic-port'). If a port filter (or 2735 protocol filter) is included in a request, 'total-attack-traffic- 2736 protocol' (or 'total-attack-traffic-port') conveys the data with the 2737 port (or protocol) filter applied. 2739 A DOTS server may aggregate pre-or-ongoing-mitigation data (e.g., 2740 'top-talker') for all targets of a domain, or when justified, send 2741 specific information (e.g., 'top-talker') per individual targets. 2743 The DOTS client may log pre-or-ongoing-mitigation telemetry data with 2744 an alert sent to an administrator or a network controller. The DOTS 2745 client may send a mitigation request if the attack cannot be handled 2746 locally. 2748 A DOTS client that is not interested to receive pre-or-ongoing- 2749 mitigation telemetry data for a target sends a delete request similar 2750 to the one depicted in Figure 37. 2752 9. DOTS Telemetry Mitigation Status Update 2754 9.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 2755 Attributes 2757 The mitigation efficacy telemetry attributes can be signaled from 2758 DOTS clients to DOTS servers as part of the periodic mitigation 2759 efficacy updates to the server (Section 4.4.3 of [RFC9132]). 2761 Total Attack Traffic: The overall attack traffic as observed from 2762 the DOTS client perspective during an active mitigation. See 2763 Figure 27. 2765 Attack Details: The overall attack details as observed from the DOTS 2766 client perspective during an active mitigation. See 2767 Section 8.1.5. 2769 The "ietf-dots-telemetry" YANG module (Section 11.1) augments the 2770 'mitigation-scope' message type defined in the "ietf-dots-signal" 2771 module [RFC9132] so that these attributes can be signalled by a DOTS 2772 client in a mitigation efficacy update (Figure 44). 2774 augment-structure /dots-signal:dots-signal/dots-signal:message-type 2775 /dots-signal:mitigation-scope/dots-signal:scope: 2776 +-- total-attack-traffic* [unit] 2777 | +-- unit unit 2778 | +-- low-percentile-g? yang:gauge64 2779 | +-- mid-percentile-g? yang:gauge64 2780 | +-- high-percentile-g? yang:gauge64 2781 | +-- peak-g? yang:gauge64 2782 | +-- current-g? yang:gauge64 2783 +-- attack-detail* [vendor-id attack-id] 2784 +-- vendor-id uint32 2785 +-- attack-id uint32 2786 +-- attack-description? string 2787 +-- attack-severity? attack-severity 2788 +-- start-time? uint64 2789 +-- end-time? uint64 2790 +-- source-count 2791 | +-- low-percentile-g? yang:gauge64 2792 | +-- mid-percentile-g? yang:gauge64 2793 | +-- high-percentile-g? yang:gauge64 2794 | +-- peak-g? yang:gauge64 2795 | +-- current-g? yang:gauge64 2796 +-- top-talker 2797 +-- talker* [source-prefix] 2798 +-- spoofed-status? boolean 2799 +-- source-prefix inet:ip-prefix 2800 +-- source-port-range* [lower-port] 2801 | +-- lower-port inet:port-number 2802 | +-- upper-port? inet:port-number 2803 +-- source-icmp-type-range* [lower-type] 2804 | +-- lower-type uint8 2805 | +-- upper-type? uint8 2806 +-- total-attack-traffic* [unit] 2807 | +-- unit unit 2808 | +-- low-percentile-g? yang:gauge64 2809 | +-- mid-percentile-g? yang:gauge64 2810 | +-- high-percentile-g? yang:gauge64 2811 | +-- peak-g? yang:gauge64 2812 | +-- current-g? yang:gauge64 2813 +-- total-attack-connection 2814 +-- connection-c 2815 | +-- low-percentile-g? yang:gauge64 2816 | +-- mid-percentile-g? yang:gauge64 2817 | +-- high-percentile-g? yang:gauge64 2818 | +-- peak-g? yang:gauge64 2819 | +-- current-g? yang:gauge64 2820 +-- embryonic-c 2821 | ... 2822 +-- connection-ps-c 2823 | ... 2824 +-- request-ps-c 2825 | ... 2826 +-- partial-request-c 2827 ... 2829 Figure 44: Telemetry Efficacy Update Tree Structure 2831 In order to signal telemetry data in a mitigation efficacy update, it 2832 is RECOMMENDED that the DOTS client has already established a DOTS 2833 telemetry setup session with the server in 'idle' time. Such a 2834 session is primarily meant to assess whether the peer DOTS server 2835 supports telemetry extensions and, thus, prevent message processing 2836 failure (Section 3.1 of [RFC9132]). 2838 An example of an efficacy update with telemetry attributes is 2839 depicted in Figure 45. 2841 Header: PUT (Code=0.03) 2842 Uri-Path: ".well-known" 2843 Uri-Path: "dots" 2844 Uri-Path: "mitigate" 2845 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2846 Uri-Path: "mid=123" 2847 If-Match: 2848 Content-Format: "application/dots+cbor" 2850 { 2851 "ietf-dots-signal-channel:mitigation-scope": { 2852 "scope": [ 2853 { 2854 "alias-name": [ 2855 "https1", 2856 "https2" 2857 ], 2858 "attack-status": "under-attack", 2859 "ietf-dots-telemetry:total-attack-traffic": [ 2860 { 2861 "unit": "megabit-ps", 2862 "mid-percentile-g": "900" 2863 } 2864 ] 2865 } 2866 ] 2867 } 2868 } 2870 Figure 45: An Example of Mitigation Efficacy Update with 2871 Telemetry Attributes 2873 9.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 2874 Attributes 2876 The mitigation status telemetry attributes can be signaled from the 2877 DOTS server to the DOTS client as part of the periodic mitigation 2878 status update (Section 4.4.2 of [RFC9132]). In particular, DOTS 2879 clients can receive asynchronous notifications of the attack details 2880 from DOTS servers using the Observe option defined in [RFC7641]. 2882 In order to make use of this feature, DOTS clients MUST establish a 2883 telemetry session with the DOTS server in 'idle' time and MUST set 2884 the 'server-originated-telemetry' attribute to 'true'. 2886 DOTS servers MUST NOT include telemetry attributes in mitigation 2887 status updates sent to DOTS clients for telemetry sessions in which 2888 the 'server-originated-telemetry' attribute is set to 'false'. 2890 As defined in [RFC8612], the actual mitigation activities can include 2891 several countermeasure mechanisms. The DOTS server signals the 2892 current operational status of relevant countermeasures. A list of 2893 attacks detected by these countermeasures MAY also be included. The 2894 same attributes defined in Section 8.1.5 are applicable for 2895 describing the attacks detected and mitigated at the DOTS server 2896 domain. 2898 The "ietf-dots-telemetry" YANG module (Section 11.1) augments the 2899 'mitigation-scope' message type defined in "ietf-dots-signal" 2900 [RFC9132] with telemetry data as depicted in Figure 46. 2902 augment-structure /dots-signal:dots-signal/dots-signal:message-type 2903 /dots-signal:mitigation-scope/dots-signal:scope: 2904 +-- (direction)? 2905 | +--:(server-to-client-only) 2906 | +-- total-traffic* [unit] 2907 | | +-- unit unit 2908 | | +-- low-percentile-g? yang:gauge64 2909 | | +-- mid-percentile-g? yang:gauge64 2910 | | +-- high-percentile-g? yang:gauge64 2911 | | +-- peak-g? yang:gauge64 2912 | | +-- current-g? yang:gauge64 2913 | +-- total-attack-connection 2914 | +-- connection-c 2915 | | +-- low-percentile-g? yang:gauge64 2916 | | +-- mid-percentile-g? yang:gauge64 2917 | | +-- high-percentile-g? yang:gauge64 2918 | | +-- peak-g? yang:gauge64 2919 | | +-- current-g? yang:gauge64 2920 | +-- embryonic-c 2921 | | ... 2922 | +-- connection-ps-c 2923 | | ... 2924 | +-- request-ps-c 2925 | | ... 2926 | +-- partial-request-c 2927 | ... 2928 +-- total-attack-traffic* [unit] 2929 | +-- unit unit 2930 | +-- low-percentile-g? yang:gauge64 2931 | +-- mid-percentile-g? yang:gauge64 2932 | +-- high-percentile-g? yang:gauge64 2933 | +-- peak-g? yang:gauge64 2934 | +-- current-g? yang:gauge64 2935 +-- attack-detail* [vendor-id attack-id] 2936 +-- vendor-id uint32 2937 +-- attack-id uint32 2938 +-- attack-description? string 2939 +-- attack-severity? attack-severity 2940 +-- start-time? uint64 2941 +-- end-time? uint64 2942 +-- source-count 2943 | +-- low-percentile-g? yang:gauge64 2944 | +-- mid-percentile-g? yang:gauge64 2945 | +-- high-percentile-g? yang:gauge64 2946 | +-- peak-g? yang:gauge64 2947 | +-- current-g? yang:gauge64 2948 +-- top-talker 2949 +-- talker* [source-prefix] 2950 +-- spoofed-status? boolean 2951 +-- source-prefix inet:ip-prefix 2952 +-- source-port-range* [lower-port] 2953 | +-- lower-port inet:port-number 2954 | +-- upper-port? inet:port-number 2955 +-- source-icmp-type-range* [lower-type] 2956 | +-- lower-type uint8 2957 | +-- upper-type? uint8 2958 +-- total-attack-traffic* [unit] 2959 | +-- unit unit 2960 | +-- low-percentile-g? yang:gauge64 2961 | +-- mid-percentile-g? yang:gauge64 2962 | +-- high-percentile-g? yang:gauge64 2963 | +-- peak-g? yang:gauge64 2964 | +-- current-g? yang:gauge64 2965 +-- total-attack-connection 2966 +-- connection-c 2967 | +-- low-percentile-g? yang:gauge64 2968 | +-- mid-percentile-g? yang:gauge64 2969 | +-- high-percentile-g? yang:gauge64 2970 | +-- peak-g? yang:gauge64 2971 | +-- current-g? yang:gauge64 2972 +-- embryonic-c 2973 | ... 2974 +-- connection-ps-c 2975 | ... 2976 +-- request-ps-c 2977 | ... 2978 +-- partial-request-c 2979 ... 2981 Figure 46: DOTS Servers to Clients Mitigation Status Telemetry 2982 Tree Structure 2984 Figure 47 shows an example of an asynchronous notification of attack 2985 mitigation status from the DOTS server. This notification signals 2986 both the mid-percentile value of processed attack traffic and the 2987 peak count of unique sources involved in the attack. 2989 { 2990 "ietf-dots-signal-channel:mitigation-scope": { 2991 "scope": [ 2992 { 2993 "mid": 12332, 2994 "mitigation-start": "1507818434", 2995 "alias-name": [ 2996 "https1", 2997 "https2" 2998 ], 2999 "lifetime": 1600, 3000 "status": "attack-successfully-mitigated", 3001 "bytes-dropped": "134334555", 3002 "bps-dropped": "43344", 3003 "pkts-dropped": "333334444", 3004 "pps-dropped": "432432", 3005 "ietf-dots-telemetry:total-attack-traffic": [ 3006 { 3007 "unit": "megabit-ps", 3008 "mid-percentile-g": "752" 3009 } 3010 ], 3011 "ietf-dots-telemetry:attack-detail": [ 3012 { 3013 "vendor-id": 32473, 3014 "attack-id": 77, 3015 "source-count": { 3016 "peak-g": "12683" 3017 } 3018 } 3019 ] 3020 } 3021 ] 3022 } 3023 } 3025 Figure 47: Response Body of a Mitigation Status With Telemetry 3026 Attributes 3028 DOTS clients can filter out the asynchronous notifications from the 3029 DOTS server by indicating one or more Uri-Query options in its GET 3030 request. A Uri-Query option can include the following parameters: 3031 'target-prefix', 'target-port', 'target-protocol', 'target-fqdn', 3032 'target-uri', 'alias-name', and 'c' (content) (Section 5.4). The 3033 considerations discussed in Section 8.3 MUST be followed to include 3034 multiple query values, ranges ('target-port', 'target-protocol'), and 3035 wildcard names ('target-fqdn', 'target-uri'). 3037 An example of request to subscribe to asynchronous notifications 3038 bound to the "https1" alias is shown in Figure 48. 3040 Header: GET (Code=0.01) 3041 Uri-Path: ".well-known" 3042 Uri-Path: "dots" 3043 Uri-Path: "mitigate" 3044 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 3045 Uri-Path: "mid=12332" 3046 Uri-Query: "target-alias=https1" 3047 Observe: 0 3049 Figure 48: GET Request to Receive Asynchronous Notifications 3050 Filtered using Uri- Query 3052 If the target query does not match the target of the enclosed 'mid' 3053 as maintained by the DOTS server, the latter MUST respond with a 4.04 3054 (Not Found) error Response Code. The DOTS server MUST NOT add a new 3055 observe entry if this query overlaps with an existing one. In such a 3056 case, the DOTS server replies with 4.09 (Conflict). 3058 10. Error Handling 3060 A list of common CoAP errors that are implemented by DOTS servers are 3061 provided in Section 9 of [RFC9132]. The following additional error 3062 cases apply for the telemetry extension: 3064 * 4.00 (Bad Request) is returned by the DOTS server when the DOTS 3065 client has sent a request that violates the DOTS telemetry 3066 extension. 3068 * 4.04 (Not Found) is returned by the DOTS server when the DOTS 3069 client is requesting a 'tsid' or 'tmid' that is not valid. 3071 * 4.00 (Bad Request) is returned by the DOTS server when the DOTS 3072 client has sent a request with invalid query types (e.g., not 3073 supported, malformed). 3075 * 4.04 (Not Found) is returned by the DOTS server when the DOTS 3076 client has sent a request with a target query that does not match 3077 the target of the enclosed 'mid' as maintained by the DOTS server. 3079 As indicated in Section 9 of [RFC9132], an additional plain text 3080 diagnostic payload (Section 5.5.2 of [RFC7252]) to help 3081 troubleshooting is returned in the body of the response. 3083 11. YANG Modules 3085 11.1. DOTS Signal Channel Telemetry YANG Module 3087 This module uses types defined in [RFC6991] and [RFC8345]. 3089 file "ietf-dots-telemetry@2021-11-29.yang" 3090 module ietf-dots-telemetry { 3091 yang-version 1.1; 3092 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 3093 prefix dots-telemetry; 3095 import ietf-dots-signal-channel { 3096 prefix dots-signal; 3097 reference 3098 "RFC 9132: Distributed Denial-of-Service Open Threat Signaling 3099 (DOTS) Signal Channel Specification"; 3100 } 3101 import ietf-dots-data-channel { 3102 prefix data-channel; 3103 reference 3104 "RFC 8783: Distributed Denial-of-Service Open Threat 3105 Signaling (DOTS) Data Channel Specification"; 3106 } 3107 import ietf-yang-types { 3108 prefix yang; 3109 reference 3110 "Section 3 of RFC 6991"; 3111 } 3112 import ietf-inet-types { 3113 prefix inet; 3114 reference 3115 "Section 4 of RFC 6991"; 3116 } 3117 import ietf-network-topology { 3118 prefix nt; 3119 reference 3120 "Section 6.2 of RFC 8345: A YANG Data Model for Network 3121 Topologies"; 3123 } 3124 import ietf-yang-structure-ext { 3125 prefix sx; 3126 reference 3127 "RFC 8791: YANG Data Structure Extensions"; 3128 } 3130 organization 3131 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3132 contact 3133 "WG Web: 3134 WG List: 3136 Author: Mohamed Boucadair 3137 3139 Author: Konda, Tirumaleswar Reddy.K 3140 "; 3141 description 3142 "This module contains YANG definitions for the signaling 3143 of DOTS telemetry data exchanged between a DOTS client and 3144 a DOTS server by means of the DOTS signal channel. 3146 Copyright (c) 2022 IETF Trust and the persons identified as 3147 authors of the code. All rights reserved. 3149 Redistribution and use in source and binary forms, with or 3150 without modification, is permitted pursuant to, and subject 3151 to the license terms contained in, the Simplified BSD License 3152 set forth in Section 4.c of the IETF Trust's Legal Provisions 3153 Relating to IETF Documents 3154 (https://trustee.ietf.org/license-info). 3156 This version of this YANG module is part of RFC XXXX; see 3157 the RFC itself for full legal notices."; 3159 revision 2021-11-29 { 3160 description 3161 "Initial revision."; 3162 reference 3163 "RFC XXXX: Distributed Denial-of-Service Open Threat 3164 Signaling (DOTS) Telemetry"; 3165 } 3167 typedef attack-severity { 3168 type enumeration { 3169 enum none { 3170 value 1; 3171 description 3172 "No effect on the DOTS client domain."; 3173 } 3174 enum low { 3175 value 2; 3176 description 3177 "Minimal effect on the DOTS client domain."; 3178 } 3179 enum medium { 3180 value 3; 3181 description 3182 "A subset of DOTS client domain resources are 3183 out of service."; 3184 } 3185 enum high { 3186 value 4; 3187 description 3188 "The DOTS client domain is under extremly severe 3189 conditions."; 3190 } 3191 enum unknown { 3192 value 5; 3193 description 3194 "The impact of the attack is not known."; 3195 } 3196 } 3197 description 3198 "Enumeration for attack severity."; 3199 reference 3200 "RFC 7970: The Incident Object Description Exchange 3201 Format Version 2, Section 3.12.2"; 3202 } 3204 typedef unit-class { 3205 type enumeration { 3206 enum packet-ps { 3207 value 1; 3208 description 3209 "Packets per second (pps)."; 3210 } 3211 enum bit-ps { 3212 value 2; 3213 description 3214 "Bits per Second (bit/s)."; 3215 } 3216 enum byte-ps { 3217 value 3; 3218 description 3219 "Bytes per second (Byte/s)."; 3220 } 3221 } 3222 description 3223 "Enumeration to indicate which unit class is used. 3224 These classes are supported: pps, bit/s, and Byte/s."; 3225 } 3227 typedef unit { 3228 type enumeration { 3229 enum packet-ps { 3230 value 1; 3231 description 3232 "Packets per second (pps)."; 3233 } 3234 enum bit-ps { 3235 value 2; 3236 description 3237 "Bits per Second (bps)."; 3238 } 3239 enum byte-ps { 3240 value 3; 3241 description 3242 "Bytes per second (Bps)."; 3243 } 3244 enum kilopacket-ps { 3245 value 4; 3246 description 3247 "Kilo packets per second (kpps)."; 3248 } 3249 enum kilobit-ps { 3250 value 5; 3251 description 3252 "Kilobits per second (kbps)."; 3253 } 3254 enum kilobyte-ps { 3255 value 6; 3256 description 3257 "Kilobytes per second (kBps)."; 3258 } 3259 enum megapacket-ps { 3260 value 7; 3261 description 3262 "Mega packets per second (Mpps)."; 3263 } 3264 enum megabit-ps { 3265 value 8; 3266 description 3267 "Megabits per second (Mbps)."; 3268 } 3269 enum megabyte-ps { 3270 value 9; 3271 description 3272 "Megabytes per second (MBps)."; 3273 } 3274 enum gigapacket-ps { 3275 value 10; 3276 description 3277 "Giga packets per second (Gpps)."; 3278 } 3279 enum gigabit-ps { 3280 value 11; 3281 description 3282 "Gigabits per second (Gbps)."; 3283 } 3284 enum gigabyte-ps { 3285 value 12; 3286 description 3287 "Gigabytes per second (GBps)."; 3288 } 3289 enum terapacket-ps { 3290 value 13; 3291 description 3292 "Tera packets per second (Tpps)."; 3293 } 3294 enum terabit-ps { 3295 value 14; 3296 description 3297 "Terabits per second (Tbps)."; 3298 } 3299 enum terabyte-ps { 3300 value 15; 3301 description 3302 "Terabytes per second (TBps)."; 3303 } 3304 enum petapacket-ps { 3305 value 16; 3306 description 3307 "Peta packets per second (Ppps)."; 3308 } 3309 enum petabit-ps { 3310 value 17; 3311 description 3312 "Petabits per second (Pbps)."; 3313 } 3314 enum petabyte-ps { 3315 value 18; 3316 description 3317 "Petabytes per second (PBps)."; 3318 } 3319 enum exapacket-ps { 3320 value 19; 3321 description 3322 "Exa packets per second (Epps)."; 3323 } 3324 enum exabit-ps { 3325 value 20; 3326 description 3327 "Exabits per second (Ebps)."; 3328 } 3329 enum exabyte-ps { 3330 value 21; 3331 description 3332 "Exabytes per second (EBps)."; 3333 } 3334 enum zettapacket-ps { 3335 value 22; 3336 description 3337 "Zetta packets per second (Zpps)."; 3338 } 3339 enum zettabit-ps { 3340 value 23; 3341 description 3342 "Zettabits per second (Zbps)."; 3343 } 3344 enum zettabyte-ps { 3345 value 24; 3346 description 3347 "Zettabytes per second (ZBps)."; 3348 } 3349 } 3350 description 3351 "Enumeration to indicate which unit is used. 3352 Only one unit per unit class is used owing to 3353 unit auto-scaling."; 3354 } 3356 typedef interval { 3357 type enumeration { 3358 enum 5-minutes { 3359 value 1; 3360 description 3361 "5 minutes."; 3362 } 3363 enum 10-minutes { 3364 value 2; 3365 description 3366 "10 minutes."; 3367 } 3368 enum 30-minutes { 3369 value 3; 3370 description 3371 "30 minutes."; 3372 } 3373 enum hour { 3374 value 4; 3375 description 3376 "Hour."; 3377 } 3378 enum day { 3379 value 5; 3380 description 3381 "Day."; 3382 } 3383 enum week { 3384 value 6; 3385 description 3386 "Week."; 3387 } 3388 enum month { 3389 value 7; 3390 description 3391 "Month."; 3392 } 3393 } 3394 description 3395 "Enumeration to indicate the overall measurement period."; 3396 } 3398 typedef sample { 3399 type enumeration { 3400 enum second { 3401 value 1; 3402 description 3403 "A one-second measurement period."; 3404 } 3405 enum 5-seconds { 3406 value 2; 3407 description 3408 "5-second measurement period."; 3409 } 3410 enum 30-seconds { 3411 value 3; 3412 description 3413 "30-second measurement period."; 3414 } 3415 enum minute { 3416 value 4; 3417 description 3418 "One-minute measurement period."; 3419 } 3420 enum 5-minutes { 3421 value 5; 3422 description 3423 "5-minute measurement period."; 3424 } 3425 enum 10-minutes { 3426 value 6; 3427 description 3428 "10-minute measurement period."; 3429 } 3430 enum 30-minutes { 3431 value 7; 3432 description 3433 "30-minute measurement period."; 3434 } 3435 enum hour { 3436 value 8; 3437 description 3438 "One-hour measurement period."; 3439 } 3440 } 3441 description 3442 "Enumeration to indicate the sampling period."; 3443 } 3445 typedef percentile { 3446 type decimal64 { 3447 fraction-digits 2; 3448 } 3449 description 3450 "The nth percentile of a set of data is the 3451 value at which n percent of the data is below it."; 3452 } 3454 typedef query-type { 3455 type enumeration { 3456 enum target-prefix { 3457 value 1; 3458 description 3459 "Query based on target prefix."; 3460 } 3461 enum target-port { 3462 value 2; 3463 description 3464 "Query based on target port number."; 3465 } 3466 enum target-protocol { 3467 value 3; 3468 description 3469 "Query based on target protocol."; 3470 } 3471 enum target-fqdn { 3472 value 4; 3473 description 3474 "Query based on target FQDN."; 3475 } 3476 enum target-uri { 3477 value 5; 3478 description 3479 "Query based on target URI."; 3480 } 3481 enum target-alias { 3482 value 6; 3483 description 3484 "Query based on target alias."; 3485 } 3486 enum mid { 3487 value 7; 3488 description 3489 "Query based on mitigation identifier (mid)."; 3490 } 3491 enum source-prefix { 3492 value 8; 3493 description 3494 "Query based on source prefix."; 3495 } 3496 enum source-port { 3497 value 9; 3498 description 3499 "Query based on source port number."; 3500 } 3501 enum source-icmp-type { 3502 value 10; 3503 description 3504 "Query based on ICMP type"; 3505 } 3506 enum content { 3507 value 11; 3508 description 3509 "Query based on 'c' Uri-Query option that is used 3510 to control the selection of configuration 3511 and non-configuration data nodes."; 3512 reference 3513 "Section 4.4.2 of RFC 9132."; 3514 } 3515 } 3516 description 3517 "Enumeration of support for query types that can be used 3518 in a GET request to filter out data. Requests with 3519 invalid query types (e.g., not supported, malformed) 3520 received by the DOTS server are rejected with 3521 a 4.00 (Bad Request) response code."; 3522 } 3524 grouping telemetry-parameters { 3525 description 3526 "A grouping that includes a set of parameters that 3527 are used to prepare the reported telemetry data. 3529 The grouping indicates a measurement interval, 3530 a measurement sample period, and low/mid/high 3531 percentile values."; 3532 leaf measurement-interval { 3533 type interval; 3534 description 3535 "Defines the period on which percentiles are computed."; 3536 } 3537 leaf measurement-sample { 3538 type sample; 3539 description 3540 "Defines the time distribution for measuring 3541 values that are used to compute percentiles. 3543 The measurement sample value must be less than the 3544 measurement interval value."; 3545 } 3546 leaf low-percentile { 3547 type percentile; 3548 default "10.00"; 3549 description 3550 "Low percentile. If set to '0', this means low-percentiles 3551 are disabled."; 3552 } 3553 leaf mid-percentile { 3554 type percentile; 3555 must '. >= ../low-percentile' { 3556 error-message 3557 "The mid-percentile must be greater than 3558 or equal to the low-percentile."; 3559 } 3560 default "50.00"; 3561 description 3562 "Mid percentile. If set to the same value as low-percentile, 3563 this means mid-percentiles are disabled."; 3564 } 3565 leaf high-percentile { 3566 type percentile; 3567 must '. >= ../mid-percentile' { 3568 error-message 3569 "The high-percentile must be greater than 3570 or equal to the mid-percentile."; 3571 } 3572 default "90.00"; 3573 description 3574 "High percentile. If set to the same value as mid-percentile, 3575 this means high-percentiles are disabled."; 3576 } 3577 } 3579 grouping percentile-and-peak { 3580 description 3581 "Generic grouping for percentile and peak values."; 3582 leaf low-percentile-g { 3583 type yang:gauge64; 3584 description 3585 "Low percentile value."; 3586 } 3587 leaf mid-percentile-g { 3588 type yang:gauge64; 3589 description 3590 "Mid percentile value."; 3591 } 3592 leaf high-percentile-g { 3593 type yang:gauge64; 3594 description 3595 "High percentile value."; 3596 } 3597 leaf peak-g { 3598 type yang:gauge64; 3599 description 3600 "Peak value."; 3601 } 3602 } 3603 grouping percentile-peak-and-current { 3604 description 3605 "Generic grouping for percentile and peak values."; 3606 uses percentile-and-peak; 3607 leaf current-g { 3608 type yang:gauge64; 3609 description 3610 "Current value."; 3611 } 3612 } 3614 grouping unit-config { 3615 description 3616 "Generic grouping for unit configuration."; 3617 list unit-config { 3618 key "unit"; 3619 description 3620 "Controls which unit classes are allowed when sharing 3621 telemetry data."; 3622 leaf unit { 3623 type unit-class; 3624 description 3625 "Can be packet-ps, bit-ps, or byte-ps."; 3626 } 3627 leaf unit-status { 3628 type boolean; 3629 mandatory true; 3630 description 3631 "Enable/disable the use of the measurement unit class."; 3632 } 3633 } 3634 } 3636 grouping traffic-unit { 3637 description 3638 "Grouping of traffic as a function of the measurement unit."; 3639 leaf unit { 3640 type unit; 3641 description 3642 "The traffic can be measured using unit classes: packet-ps, 3643 bit-ps, or byte-ps. DOTS agents auto-scale to the 3644 appropriate units (e.g., megabit-ps, kilobit-ps)."; 3645 } 3646 uses percentile-and-peak; 3647 } 3649 grouping traffic-unit-all { 3650 description 3651 "Grouping of traffic as a function of the measurement unit, 3652 including current values."; 3653 uses traffic-unit; 3654 leaf current-g { 3655 type yang:gauge64; 3656 description 3657 "Current observed value."; 3658 } 3659 } 3661 grouping traffic-unit-protocol { 3662 description 3663 "Grouping of traffic of a given transport protocol as 3664 a function of the measurement unit."; 3665 leaf protocol { 3666 type uint8; 3667 description 3668 "The transport protocol. 3669 Values are taken from the IANA Protocol Numbers registry: 3670 . 3672 For example, this parameter contains 6 for TCP, 3673 17 for UDP, 33 for DCCP, or 132 for SCTP."; 3674 } 3675 uses traffic-unit; 3676 } 3678 grouping traffic-unit-protocol-all { 3679 description 3680 "Grouping of traffic of a given transport protocol as 3681 a function of the measurement unit, including current 3682 values."; 3683 uses traffic-unit-protocol; 3684 leaf current-g { 3685 type yang:gauge64; 3686 description 3687 "Current observed value."; 3688 } 3689 } 3691 grouping traffic-unit-port { 3692 description 3693 "Grouping of traffic bound to a port number as 3694 a function of the measurement unit."; 3695 leaf port { 3696 type inet:port-number; 3697 description 3698 "Port number used by a transport protocol."; 3700 } 3701 uses traffic-unit; 3702 } 3704 grouping traffic-unit-port-all { 3705 description 3706 "Grouping of traffic bound to a port number as 3707 a function of the measurement unit, including 3708 current values."; 3709 uses traffic-unit-port; 3710 leaf current-g { 3711 type yang:gauge64; 3712 description 3713 "Current observed value."; 3714 } 3715 } 3717 grouping total-connection-capacity { 3718 description 3719 "Total connection capacities for various types of 3720 connections, as well as overall capacity. These data nodes are 3721 useful to detect resource-consuming DDoS attacks."; 3722 leaf connection { 3723 type uint64; 3724 description 3725 "The maximum number of simultaneous connections that 3726 are allowed to the target server."; 3727 } 3728 leaf connection-client { 3729 type uint64; 3730 description 3731 "The maximum number of simultaneous connections that 3732 are allowed to the target server per client."; 3733 } 3734 leaf embryonic { 3735 type uint64; 3736 description 3737 "The maximum number of simultaneous embryonic connections 3738 that are allowed to the target server. The term 'embryonic 3739 connection' refers to a connection whose connection 3740 handshake is not finished. Embryonic connections are only 3741 possible in connection-oriented transport protocols like 3742 TCP or SCTP."; 3743 } 3744 leaf embryonic-client { 3745 type uint64; 3746 description 3747 "The maximum number of simultaneous embryonic connections 3748 that are allowed to the target server per client."; 3749 } 3750 leaf connection-ps { 3751 type uint64; 3752 description 3753 "The maximum number of new connections allowed per second 3754 to the target server."; 3755 } 3756 leaf connection-client-ps { 3757 type uint64; 3758 description 3759 "The maximum number of new connections allowed per second 3760 to the target server per client."; 3761 } 3762 leaf request-ps { 3763 type uint64; 3764 description 3765 "The maximum number of requests allowed per second 3766 to the target server."; 3767 } 3768 leaf request-client-ps { 3769 type uint64; 3770 description 3771 "The maximum number of requests allowed per second 3772 to the target server per client."; 3773 } 3774 leaf partial-request-max { 3775 type uint64; 3776 description 3777 "The maximum number of outstanding partial requests 3778 that are allowed to the target server."; 3779 } 3780 leaf partial-request-client-max { 3781 type uint64; 3782 description 3783 "The maximum number of outstanding partial requests 3784 that are allowed to the target server per client."; 3785 } 3786 } 3788 grouping total-connection-capacity-protocol { 3789 description 3790 "Total connections capacity per protocol. These data nodes are 3791 useful to detect resource consuming DDoS attacks."; 3792 leaf protocol { 3793 type uint8; 3794 description 3795 "The transport protocol. 3797 Values are taken from the IANA Protocol Numbers registry: 3798 ."; 3799 } 3800 uses total-connection-capacity; 3801 } 3803 grouping connection-percentile-and-peak { 3804 description 3805 "A set of data nodes which represent the attack 3806 characteristics."; 3807 container connection-c { 3808 uses percentile-and-peak; 3809 description 3810 "The number of simultaneous attack connections to 3811 the target server."; 3812 } 3813 container embryonic-c { 3814 uses percentile-and-peak; 3815 description 3816 "The number of simultaneous embryonic connections to 3817 the target server."; 3818 } 3819 container connection-ps-c { 3820 uses percentile-and-peak; 3821 description 3822 "The number of attack connections per second to 3823 the target server."; 3824 } 3825 container request-ps-c { 3826 uses percentile-and-peak; 3827 description 3828 "The number of attack requests per second to 3829 the target server."; 3830 } 3831 container partial-request-c { 3832 uses percentile-and-peak; 3833 description 3834 "The number of attack partial requests to 3835 the target server."; 3836 } 3837 } 3839 grouping connection-all { 3840 description 3841 "Total attack connections including current values."; 3842 container connection-c { 3843 uses percentile-peak-and-current; 3844 description 3845 "The number of simultaneous attack connections to 3846 the target server."; 3847 } 3848 container embryonic-c { 3849 uses percentile-peak-and-current; 3850 description 3851 "The number of simultaneous embryonic connections to 3852 the target server."; 3853 } 3854 container connection-ps-c { 3855 uses percentile-peak-and-current; 3856 description 3857 "The number of attack connections per second to 3858 the target server."; 3859 } 3860 container request-ps-c { 3861 uses percentile-peak-and-current; 3862 description 3863 "The number of attack requests per second to 3864 the target server."; 3865 } 3866 container partial-request-c { 3867 uses percentile-peak-and-current; 3868 description 3869 "The number of attack partial requests to 3870 the target server."; 3871 } 3872 } 3874 grouping connection-protocol { 3875 description 3876 "Total attack connections."; 3877 leaf protocol { 3878 type uint8; 3879 description 3880 "The transport protocol. 3881 Values are taken from the IANA Protocol Numbers registry: 3882 ."; 3883 } 3884 uses connection-percentile-and-peak; 3885 } 3887 grouping connection-port { 3888 description 3889 "Total attack connections per port number."; 3890 leaf protocol { 3891 type uint8; 3892 description 3893 "The transport protocol. 3894 Values are taken from the IANA Protocol Numbers registry: 3895 ."; 3896 } 3897 leaf port { 3898 type inet:port-number; 3899 description 3900 "Port number."; 3901 } 3902 uses connection-percentile-and-peak; 3903 } 3905 grouping connection-protocol-all { 3906 description 3907 "Total attack connections per protocol, including current 3908 values."; 3909 leaf protocol { 3910 type uint8; 3911 description 3912 "The transport protocol. 3913 Values are taken from the IANA Protocol Numbers registry: 3914 ."; 3915 } 3916 uses connection-all; 3917 } 3919 grouping connection-protocol-port-all { 3920 description 3921 "Total attack connections per port number, including current 3922 values."; 3923 leaf protocol { 3924 type uint8; 3925 description 3926 "The transport protocol. 3927 Values are taken from the IANA Protocol Numbers registry: 3928 ."; 3929 } 3930 leaf port { 3931 type inet:port-number; 3932 description 3933 "Port number."; 3934 } 3935 uses connection-all; 3936 } 3938 grouping attack-detail { 3939 description 3940 "Various details that describe the on-going 3941 attacks that need to be mitigated by the DOTS server. 3942 The attack details need to cover well-known and common attacks 3943 (such as a SYN Flood) along with new emerging or 3944 vendor-specific attacks."; 3945 leaf vendor-id { 3946 type uint32; 3947 description 3948 "Vendor ID is a security vendor's Private Enterprise Number 3949 as registered with IANA."; 3950 reference 3951 "IANA: Private Enterprise Numbers"; 3952 } 3953 leaf attack-id { 3954 type uint32; 3955 description 3956 "Unique identifier assigned by the vendor for the attack."; 3957 } 3958 leaf attack-description { 3959 type string; 3960 description 3961 "Textual representation of attack description. Natural 3962 Language Processing techniques (e.g., word embedding) 3963 might provide some utility in mapping the attack 3964 description to an attack type."; 3965 } 3966 leaf attack-severity { 3967 type attack-severity; 3968 description 3969 "Severity level of an attack. How this level is determined 3970 is implementation-specific."; 3971 } 3972 leaf start-time { 3973 type uint64; 3974 description 3975 "The time the attack started. Start time is represented in 3976 seconds relative to 1970-01-01T00:00:00Z."; 3977 } 3978 leaf end-time { 3979 type uint64; 3980 description 3981 "The time the attack ended. End time is represented in 3982 seconds relative to 1970-01-01T00:00:00Z."; 3983 } 3984 container source-count { 3985 description 3986 "Indicates the count of unique sources involved 3987 in the attack."; 3988 uses percentile-and-peak; 3989 leaf current-g { 3990 type yang:gauge64; 3991 description 3992 "Current observed value."; 3993 } 3994 } 3995 } 3997 grouping talker { 3998 description 3999 "Defines generic data related to top-talkers."; 4000 leaf spoofed-status { 4001 type boolean; 4002 description 4003 "When set to 'true', it indicates whether this address 4004 is spoofed."; 4005 } 4006 leaf source-prefix { 4007 type inet:ip-prefix; 4008 description 4009 "IPv4 or IPv6 prefix identifying the attacker(s)."; 4010 } 4011 list source-port-range { 4012 key "lower-port"; 4013 description 4014 "Port range. When only lower-port is 4015 present, it represents a single port number."; 4016 leaf lower-port { 4017 type inet:port-number; 4018 description 4019 "Lower port number of the port range."; 4020 } 4021 leaf upper-port { 4022 type inet:port-number; 4023 must '. >= ../lower-port' { 4024 error-message 4025 "The upper port number must be greater than 4026 or equal to lower port number."; 4027 } 4028 description 4029 "Upper port number of the port range."; 4030 } 4031 } 4032 list source-icmp-type-range { 4033 key "lower-type"; 4034 description 4035 "ICMP type range. When only lower-type is 4036 present, it represents a single ICMP type."; 4038 leaf lower-type { 4039 type uint8; 4040 description 4041 "Lower ICMP type of the ICMP type range."; 4042 } 4043 leaf upper-type { 4044 type uint8; 4045 must '. >= ../lower-type' { 4046 error-message 4047 "The upper ICMP type must be greater than 4048 or equal to lower ICMP type."; 4049 } 4050 description 4051 "Upper type of the ICMP type range."; 4052 } 4053 } 4054 list total-attack-traffic { 4055 key "unit"; 4056 description 4057 "Total attack traffic issued from this source."; 4058 uses traffic-unit-all; 4059 } 4060 } 4062 grouping top-talker-aggregate { 4063 description 4064 "An aggregate of top attack sources. This aggregate is 4065 typically used when included in a mitigation request."; 4066 list talker { 4067 key "source-prefix"; 4068 description 4069 "Refers to a top-talker that is identified by an IPv4 4070 or IPv6 prefix identifying the attacker(s)."; 4071 uses talker; 4072 container total-attack-connection { 4073 description 4074 "Total attack connections issued from this source."; 4075 uses connection-all; 4076 } 4077 } 4078 } 4080 grouping top-talker { 4081 description 4082 "Top attack sources with detailed per-protocol 4083 structure."; 4084 list talker { 4085 key "source-prefix"; 4086 description 4087 "Refers to a top-talker that is identified by an IPv4 4088 or IPv6 prefix identifying the attacker(s)."; 4089 uses talker; 4090 list total-attack-connection-protocol { 4091 key "protocol"; 4092 description 4093 "Total attack connections issued from this source."; 4094 uses connection-protocol-all; 4095 } 4096 } 4097 } 4099 grouping baseline { 4100 description 4101 "Grouping for the telemetry baseline."; 4102 uses data-channel:target; 4103 leaf-list alias-name { 4104 type string; 4105 description 4106 "An alias name that points to an IP resource. 4107 An IP resource can be be a router, a host, 4108 an IoT object, a server, etc."; 4109 } 4110 list total-traffic-normal { 4111 key "unit"; 4112 description 4113 "Total traffic normal baselines."; 4114 uses traffic-unit; 4115 } 4116 list total-traffic-normal-per-protocol { 4117 key "unit protocol"; 4118 description 4119 "Total traffic normal baselines per protocol."; 4120 uses traffic-unit-protocol; 4121 } 4122 list total-traffic-normal-per-port { 4123 key "unit port"; 4124 description 4125 "Total traffic normal baselines per port number."; 4126 uses traffic-unit-port; 4127 } 4128 list total-connection-capacity { 4129 key "protocol"; 4130 description 4131 "Total connection capacity."; 4132 uses total-connection-capacity-protocol; 4133 } 4134 list total-connection-capacity-per-port { 4135 key "protocol port"; 4136 description 4137 "Total connection capacity per port number."; 4138 leaf port { 4139 type inet:port-number; 4140 description 4141 "The target port number."; 4142 } 4143 uses total-connection-capacity-protocol; 4144 } 4145 } 4147 grouping pre-or-ongoing-mitigation { 4148 description 4149 "Grouping for the telemetry data."; 4150 list total-traffic { 4151 key "unit"; 4152 description 4153 "Total traffic."; 4154 uses traffic-unit-all; 4155 } 4156 list total-traffic-protocol { 4157 key "unit protocol"; 4158 description 4159 "Total traffic per protocol."; 4160 uses traffic-unit-protocol-all; 4161 } 4162 list total-traffic-port { 4163 key "unit port"; 4164 description 4165 "Total traffic per port number."; 4166 uses traffic-unit-port-all; 4167 } 4168 list total-attack-traffic { 4169 key "unit"; 4170 description 4171 "Total attack traffic."; 4172 uses traffic-unit-all; 4173 } 4174 list total-attack-traffic-protocol { 4175 key "unit protocol"; 4176 description 4177 "Total attack traffic per protocol."; 4178 uses traffic-unit-protocol-all; 4179 } 4180 list total-attack-traffic-port { 4181 key "unit port"; 4182 description 4183 "Total attack traffic per port number."; 4184 uses traffic-unit-port-all; 4185 } 4186 list total-attack-connection-protocol { 4187 key "protocol"; 4188 description 4189 "Total attack connections."; 4190 uses connection-protocol-all; 4191 } 4192 list total-attack-connection-port { 4193 key "protocol port"; 4194 description 4195 "Total attack connections per target port number."; 4196 uses connection-protocol-port-all; 4197 } 4198 list attack-detail { 4199 key "vendor-id attack-id"; 4200 description 4201 "Provides a set of attack details."; 4202 uses attack-detail; 4203 container top-talker { 4204 description 4205 "Lists the top attack sources."; 4206 uses top-talker; 4207 } 4208 } 4209 } 4211 sx:augment-structure "/dots-signal:dots-signal" 4212 + "/dots-signal:message-type" 4213 + "/dots-signal:mitigation-scope" 4214 + "/dots-signal:scope" { 4215 description 4216 "Extends mitigation scope with telemetry update data."; 4217 choice direction { 4218 description 4219 "Indicates the communication direction in which the 4220 data nodes can be included."; 4221 case server-to-client-only { 4222 description 4223 "These data nodes appear only in a mitigation message 4224 sent from the server to the client."; 4225 list total-traffic { 4226 key "unit"; 4227 description 4228 "Total traffic."; 4229 uses traffic-unit-all; 4231 } 4232 container total-attack-connection { 4233 description 4234 "Total attack connections."; 4235 uses connection-all; 4236 } 4237 } 4238 } 4239 list total-attack-traffic { 4240 key "unit"; 4241 description 4242 "Total attack traffic."; 4243 uses traffic-unit-all; 4244 } 4245 list attack-detail { 4246 key "vendor-id attack-id"; 4247 description 4248 "Attack details"; 4249 uses attack-detail; 4250 container top-talker { 4251 description 4252 "Top attack sources."; 4253 uses top-talker-aggregate; 4254 } 4255 } 4256 } 4257 sx:structure dots-telemetry { 4258 description 4259 "Main structure for DOTS telemetry messages."; 4260 choice telemetry-message-type { 4261 description 4262 "Can be a telemetry-setup or telemetry data."; 4263 case telemetry-setup { 4264 description 4265 "Indicates the message is about telemetry steup."; 4266 choice direction { 4267 description 4268 "Indicates the communication direction in which the 4269 data nodes can be included."; 4270 case server-to-client-only { 4271 description 4272 "These data nodes appear only in a telemetry message 4273 sent from the server to the client."; 4274 container max-config-values { 4275 description 4276 "Maximum acceptable configuration values."; 4277 uses telemetry-parameters; 4278 leaf server-originated-telemetry { 4279 type boolean; 4280 default "false"; 4281 description 4282 "Indicates whether the DOTS server can be 4283 instructed to send pre-or-ongoing-mitigation 4284 telemetry. If set to 'false' or the data node 4285 is not present, this is an indication that 4286 the server does not support this capability."; 4287 } 4288 leaf telemetry-notify-interval { 4289 type uint16 { 4290 range "1 .. 3600"; 4291 } 4292 units "seconds"; 4293 must '. >= ../../min-config-values' 4294 + '/telemetry-notify-interval' { 4295 error-message 4296 "The value must be greater than or equal 4297 to the telemetry-notify-interval in the 4298 min-config-values"; 4299 } 4300 description 4301 "Minimum number of seconds between successive 4302 telemetry notifications."; 4303 } 4304 } 4305 container min-config-values { 4306 description 4307 "Minimum acceptable configuration values."; 4308 uses telemetry-parameters; 4309 leaf telemetry-notify-interval { 4310 type uint16 { 4311 range "1 .. 3600"; 4312 } 4313 units "seconds"; 4314 description 4315 "Minimum number of seconds between successive 4316 telemetry notifications."; 4317 } 4318 } 4319 container supported-unit-classes { 4320 description 4321 "Supported unit classes and default activation 4322 status."; 4323 uses unit-config; 4324 } 4325 leaf-list supported-query-type { 4326 type query-type; 4327 description 4328 "Indicates which query types are supported by 4329 the server. If the server does not announce 4330 the query types it supports, the client will 4331 be unable to use any of the potential 4332 query-type values to reduce the returned data 4333 content from the server."; 4334 } 4335 } 4336 } 4337 list telemetry { 4338 description 4339 "The telemetry data per DOTS client. The keys 4340 of the list are 'cuid' and 'tsid', but these keys are 4341 not represented here because these keys are conveyed 4342 as mandatory Uri-Paths in requests. Omitting keys 4343 is compliant with RFC8791."; 4344 choice direction { 4345 description 4346 "Indicates the communication direction in which the 4347 data nodes can be included."; 4348 case server-to-client-only { 4349 description 4350 "These data nodes appear only in a telemetry message 4351 sent from the server to the client."; 4352 leaf tsid { 4353 type uint32; 4354 description 4355 "A client-assigned identifier for the DOTS 4356 telemetry setup data."; 4357 } 4358 } 4359 } 4360 choice setup-type { 4361 description 4362 "Can be a mitigation configuration, a pipe capacity, 4363 or baseline message."; 4364 case telemetry-config { 4365 description 4366 "Used to set telemetry parameters such as setting 4367 low, mid, and high percentile values."; 4368 container current-config { 4369 description 4370 "Current telemetry configuration values."; 4371 uses telemetry-parameters; 4372 uses unit-config; 4373 leaf server-originated-telemetry { 4374 type boolean; 4375 description 4376 "Used by a DOTS client to enable/disable whether 4377 it requests pre-or-ongoing-mitigation telemetry 4378 from the DOTS server."; 4379 } 4380 leaf telemetry-notify-interval { 4381 type uint16 { 4382 range "1 .. 3600"; 4383 } 4384 units "seconds"; 4385 description 4386 "Minimum number of seconds between successive 4387 telemetry notifications."; 4388 } 4389 } 4390 } 4391 case pipe { 4392 description 4393 "Total pipe capacity of a DOTS client domain."; 4394 list total-pipe-capacity { 4395 key "link-id unit"; 4396 description 4397 "Total pipe capacity of a DOTS client domain."; 4398 leaf link-id { 4399 type nt:link-id; 4400 description 4401 "Identifier of an interconnection link of 4402 the DOTS client domain."; 4403 } 4404 leaf capacity { 4405 type uint64; 4406 mandatory true; 4407 description 4408 "Pipe capacity. This attribute is mandatory when 4409 total-pipe-capacity is included in a message."; 4410 } 4411 leaf unit { 4412 type unit; 4413 description 4414 "The traffic can be measured using unit classes: 4415 packets per second (pps), bits per second 4416 (bit/s), and/or bytes per second (Byte/s). 4418 For a given unit class, the DOTS agents 4419 auto-scales to the appropriate units (e.g., 4420 megabit-ps, kilobit-ps)."; 4421 } 4422 } 4424 } 4425 case baseline { 4426 description 4427 "Traffic baseline information of a DOTS client 4428 domain."; 4429 list baseline { 4430 key "id"; 4431 description 4432 "Traffic baseline information of a DOTS client 4433 domain."; 4434 leaf id { 4435 type uint32; 4436 must '. >= 1'; 4437 description 4438 "An identifier that uniquely identifies a 4439 baseline entry communicated by a DOTS client."; 4440 } 4441 uses baseline; 4442 } 4443 } 4444 } 4445 } 4446 } 4447 case telemetry { 4448 description 4449 "Telemetry information."; 4450 list pre-or-ongoing-mitigation { 4451 description 4452 "Pre-or-ongoing-mitigation telemetry per DOTS client. 4453 The keys of the list are 'cuid' and 'tmid', but these 4454 keys are not represented here because these keys are 4455 conveyed as mandatory Uri-Paths in requests. 4456 Omitting keys is compliant with RFC8791."; 4457 choice direction { 4458 description 4459 "Indicates the communication direction in which the 4460 data nodes can be included."; 4461 case server-to-client-only { 4462 description 4463 "These data nodes appear only in a telemetry message 4464 sent from the server to the client."; 4465 leaf tmid { 4466 type uint32; 4467 description 4468 "A client-assigned identifier for the DOTS 4469 telemetry data."; 4470 } 4471 } 4473 } 4474 container target { 4475 description 4476 "Indicates the target. At least one of the attributes 4477 'target-prefix', 'target-fqdn', 'target-uri', 4478 'alias-name', or 'mid-list' must be present in the 4479 target definition."; 4480 uses data-channel:target; 4481 leaf-list alias-name { 4482 type string; 4483 description 4484 "An alias name that points to a resource."; 4485 } 4486 leaf-list mid-list { 4487 type uint32; 4488 description 4489 "Reference a list of associated mitigation 4490 requests."; 4491 reference 4492 "RFC 9132: Distributed Denial-of-Service Open Threat 4493 Signaling (DOTS) Signal Channel 4494 Specification, Section 4.4.1"; 4495 } 4496 } 4497 uses pre-or-ongoing-mitigation; 4498 } 4499 } 4500 } 4501 } 4502 } 4503 4505 11.2. Vendor Attack Mapping Details YANG Module 4507 file "ietf-dots-mapping@2020-06-26.yang" 4508 module ietf-dots-mapping { 4509 yang-version 1.1; 4510 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-mapping"; 4511 prefix dots-mapping; 4513 import ietf-dots-data-channel { 4514 prefix data-channel; 4515 reference 4516 "RFC 8783: Distributed Denial-of-Service Open Threat 4517 Signaling (DOTS) Data Channel Specification"; 4518 } 4520 organization 4521 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 4522 contact 4523 "WG Web: 4524 WG List: 4526 Author: Mohamed Boucadair 4527 4529 Author: Jon Shallow 4530 "; 4531 description 4532 "This module contains YANG definitions for the sharing 4533 DDoS attack mapping details between a DOTS client and 4534 a DOTS server, by means of the DOTS data channel. 4536 Copyright (c) 2022 IETF Trust and the persons identified as 4537 authors of the code. All rights reserved. 4539 Redistribution and use in source and binary forms, with or 4540 without modification, is permitted pursuant to, and subject 4541 to the license terms contained in, the Simplified BSD License 4542 set forth in Section 4.c of the IETF Trust's Legal Provisions 4543 Relating to IETF Documents 4544 (https://trustee.ietf.org/license-info). 4546 This version of this YANG module is part of RFC XXXX; see 4547 the RFC itself for full legal notices."; 4549 revision 2020-06-26 { 4550 description 4551 "Initial revision."; 4552 reference 4553 "RFC XXXX: Distributed Denial-of-Service Open Threat 4554 Signaling (DOTS) Telemetry"; 4555 } 4557 feature dots-telemetry { 4558 description 4559 "This feature indicates that DOTS telemetry data can be 4560 shared between DOTS clients and servers."; 4561 } 4563 grouping attack-mapping { 4564 description 4565 "A set of information used for sharing vendor attack mapping 4566 information with a peer."; 4567 list vendor { 4568 key "vendor-id"; 4569 description 4570 "Vendor attack mapping information of the client/server"; 4571 leaf vendor-id { 4572 type uint32; 4573 description 4574 "Vendor ID is a security vendor's Private Enterprise Number 4575 as registered with IANA."; 4576 reference 4577 "IANA: Private Enterprise Numbers"; 4578 } 4579 leaf vendor-name { 4580 type string; 4581 description 4582 "The name of the vendor (e.g., company A)."; 4583 } 4584 leaf last-updated { 4585 type uint64; 4586 mandatory true; 4587 description 4588 "The time the mapping table was updated. It is represented 4589 in seconds relative to 1970-01-01T00:00:00Z."; 4590 } 4591 list attack-mapping { 4592 key "attack-id"; 4593 description 4594 "Attack mapping details."; 4595 leaf attack-id { 4596 type uint32; 4597 description 4598 "Unique identifier assigned by the vendor for the 4599 attack."; 4600 } 4601 leaf attack-description { 4602 type string; 4603 mandatory true; 4604 description 4605 "Textual representation of attack description. Natural 4606 Language Processing techniques (e.g., word embedding) 4607 might provide some utility in mapping the attack 4608 description to an attack type."; 4609 } 4610 } 4611 } 4612 } 4614 augment "/data-channel:dots-data/data-channel:dots-client" { 4615 if-feature "dots-telemetry"; 4616 description 4617 "Augments the data channel with a vendor attack 4618 mapping table of the DOTS client."; 4619 container vendor-mapping { 4620 description 4621 "Used by DOTS clients to share their vendor 4622 attack mapping information with DOTS servers."; 4623 uses attack-mapping; 4624 } 4625 } 4627 augment "/data-channel:dots-data/data-channel:capabilities" { 4628 if-feature "dots-telemetry"; 4629 description 4630 "Augments the DOTS server capabilities with a 4631 parameter to indicate whether they can share 4632 attack mapping details."; 4633 leaf vendor-mapping-enabled { 4634 type boolean; 4635 config false; 4636 description 4637 "Indicates that the DOTS server supports sharing 4638 attack vendor mapping details with DOTS clients."; 4639 } 4640 } 4642 augment "/data-channel:dots-data" { 4643 if-feature "dots-telemetry"; 4644 description 4645 "Augments the data channel with a vendor attack 4646 mapping table of the DOTS server."; 4647 container vendor-mapping { 4648 config false; 4649 description 4650 "Includes the list of vendor attack mapping details 4651 that will be shared upon request with DOTS clients."; 4652 uses attack-mapping; 4653 } 4654 } 4655 } 4656 4658 12. YANG/JSON Mapping Parameters to CBOR 4660 All DOTS telemetry parameters in the payload of the DOTS signal 4661 channel MUST be mapped to CBOR types as shown in Table 3: 4663 * Note: Implementers must check that the mapping output provided by 4664 their YANG-to-CBOR encoding schemes is aligned with the content of 4665 Table 2. 4667 +----------------------+-------------+------+---------------+--------+ 4668 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 4669 | | Type | Key | Type & | Type | 4670 | | | | Information | | 4671 +======================+=============+======+===============+========+ 4672 | tsid | uint32 |TBA1 | 0 unsigned | Number | 4673 | telemetry | list |TBA2 | 4 array | Array | 4674 | low-percentile | decimal64 |TBA3 | 6 tag 4 | | 4675 | | | | [-2, integer]| String | 4676 | mid-percentile | decimal64 |TBA4 | 6 tag 4 | | 4677 | | | | [-2, integer]| String | 4678 | high-percentile | decimal64 |TBA5 | 6 tag 4 | | 4679 | | | | [-2, integer]| String | 4680 | unit-config | list |TBA6 | 4 array | Array | 4681 | unit | enumeration |TBA7 | 0 unsigned | String | 4682 | unit-status | boolean |TBA8 | 7 bits 20 | False | 4683 | | | | 7 bits 21 | True | 4684 | total-pipe-capacity | list |TBA9 | 4 array | Array | 4685 | link-id | string |TBA10 | 3 text string | String | 4686 | pre-or-ongoing- | list |TBA11 | 4 array | Array | 4687 | mitigation | | | | | 4688 | total-traffic-normal | list |TBA12 | 4 array | Array | 4689 | low-percentile-g | yang:gauge64|TBA13 | 0 unsigned | String | 4690 | mid-percentile-g | yang:gauge64|TBA14 | 0 unsigned | String | 4691 | high-percentile-g | yang:gauge64|TBA15 | 0 unsigned | String | 4692 | peak-g | yang:gauge64|TBA16 | 0 unsigned | String | 4693 | total-attack-traffic | list |TBA17 | 4 array | Array | 4694 | total-traffic | list |TBA18 | 4 array | Array | 4695 | total-connection- | | | | | 4696 | capacity | list |TBA19 | 4 array | Array | 4697 | connection | uint64 |TBA20 | 0 unsigned | String | 4698 | connection-client | uint64 |TBA21 | 0 unsigned | String | 4699 | embryonic | uint64 |TBA22 | 0 unsigned | String | 4700 | embryonic-client | uint64 |TBA23 | 0 unsigned | String | 4701 | connection-ps | uint64 |TBA24 | 0 unsigned | String | 4702 | connection-client-ps | uint64 |TBA25 | 0 unsigned | String | 4703 | request-ps | uint64 |TBA26 | 0 unsigned | String | 4704 | request-client-ps | uint64 |TBA27 | 0 unsigned | String | 4705 | partial-request-max | uint64 |TBA28 | 0 unsigned | String | 4706 | partial-request- | | | | | 4707 | client-max | uint64 |TBA29 | 0 unsigned | String | 4708 | total-attack- | | | | | 4709 | connection | container |TBA30 | 5 map | Object | 4710 | connection-c | container |TBA31 | 5 map | Object | 4711 | embryonic-c | container |TBA32 | 5 map | Object | 4712 | connection-ps-c | container |TBA33 | 5 map | Object | 4713 | request-ps-c | container |TBA34 | 5 map | Object | 4714 | attack-detail | list |TBA35 | 4 array | Array | 4715 | id | uint32 |TBA36 | 0 unsigned | Number | 4716 | attack-id | uint32 |TBA37 | 0 unsigned | Number | 4717 | attack-description | string |TBA38 | 3 text string | String | 4718 | attack-severity | enumeration |TBA39 | 0 unsigned | String | 4719 | start-time | uint64 |TBA40 | 0 unsigned | String | 4720 | end-time | uint64 |TBA41 | 0 unsigned | String | 4721 | source-count | container |TBA42 | 5 map | Object | 4722 | top-talker | container |TBA43 | 5 map | Object | 4723 | spoofed-status | boolean |TBA44 | 7 bits 20 | False | 4724 | | | | 7 bits 21 | True | 4725 | partial-request-c | container |TBA45 | 5 map | Object | 4726 | total-attack- | | | | | 4727 | connection-protocol | list |TBA46 | 4 array | Array | 4728 | baseline | list |TBA49 | 4 array | Array | 4729 | current-config | container |TBA50 | 5 map | Object | 4730 | max-config-values | container |TBA51 | 5 map | Object | 4731 | min-config-values | container |TBA52 | 5 map | Object | 4732 |supported-unit-classes| container |TBA53 | 5 map | Object | 4733 | server-originated- | boolean |TBA54 | 7 bits 20 | False | 4734 | telemetry | | | 7 bits 21 | True | 4735 | telemetry-notify- | uint16 |TBA55 | 0 unsigned | Number | 4736 | interval | | | | | 4737 | tmid | uint32 |TBA56 | 0 unsigned | Number | 4738 | measurement-interval | enumeration |TBA57 | 0 unsigned | String | 4739 | measurement-sample | enumeration |TBA58 | 0 unsigned | String | 4740 | talker | list |TBA59 | 4 array | Array | 4741 | source-prefix | inet: |TBA60 | 3 text string | String | 4742 | | ip-prefix | | | | 4743 | mid-list | leaf-list |TBA61 | 4 array | Array | 4744 | | uint32 | | 0 unsigned | Number | 4745 | source-port-range | list |TBA62 | 4 array | Array | 4746 | source-icmp-type- | list |TBA63 | 4 array | Array | 4747 | range | | | | | 4748 | target | container |TBA64 | 5 map | Object | 4749 | capacity | uint64 |TBA65 | 0 unsigned | String | 4750 | protocol | uint8 |TBA66 | 0 unsigned | Number | 4751 | total-traffic- | | | | | 4752 | normal-per-protocol | list |TBA67 | 4 array | Array | 4753 | total-traffic- | | | | | 4754 | normal-per-port | list |TBA68 | 4 array | Array | 4755 | total-connection- | | | | | 4756 | capacity-per-port | list |TBA69 | 4 array | Array | 4757 | total-traffic- | | | | | 4758 | protocol | list |TBA70 | 4 array | Array | 4759 | total-traffic-port | list |TBA71 | 4 array | Array | 4760 | total-attack- | | | | | 4761 | traffic-protocol | list |TBA72 | 4 array | Array | 4762 | total-attack- | | | | | 4763 | traffic-port | list |TBA73 | 4 array | Array | 4764 | total-attack- | | | | | 4765 | connection-port | list |TBA74 | 4 array | Array | 4766 | port | inet: | | | | 4767 | | port-number|TBA75 | 0 unsigned | Number | 4768 | supported-query-type | leaf-list |TBA76 | 4 array | Array | 4769 | | | | 0 unsigned | String | 4770 | vendor-id | uint32 |TBA77 | 0 unsigned | Number | 4771 | ietf-dots-telemetry: | | | | | 4772 | telemetry-setup | container |TBA78 | 5 map | Object | 4773 | ietf-dots-telemetry: | | | | | 4774 | total-traffic | list |TBA79 | 4 array | Array | 4775 | ietf-dots-telemetry: | | | | | 4776 | total-attack-traffic | list |TBA80 | 4 array | Array | 4777 | ietf-dots-telemetry: | | | | | 4778 | total-attack- | | | | | 4779 | connection | container |TBA81 | 5 map | Object | 4780 | ietf-dots-telemetry: | | | | | 4781 | attack-detail | list |TBA82 | 4 array | Array | 4782 | ietf-dots-telemetry: | | | | | 4783 | telemetry | container |TBA83 | 5 map | Object | 4784 | current-g | yang:gauge64|TBA84 | 0 unsigned | String | 4785 | lower-type | uint8 |32771 | 0 unsigned | Number | 4786 | upper-type | uint8 |32772 | 0 unsigned | Number | 4787 +----------------------+-------------+------+---------------+--------+ 4789 Table 3: YANG/JSON Mapping Parameters to CBOR 4791 13. IANA Considerations 4793 13.1. DOTS Signal Channel CBOR Key Values 4795 This specification registers the DOTS telemetry attributes in the 4796 IANA "DOTS Signal Channel CBOR Key Values" registry [Key-Map]. 4798 The DOTS telemetry attributes defined in this specification are 4799 comprehension-optional parameters. 4801 * Note to the IANA: CBOR keys are assigned from the "128-255" range. 4802 This specification meets the requirements listed in Section 3.1 4803 [RFC9132] for assignments in the "128-255" range. 4805 * Note to the RFC Editor: Please replace all occurrences of 4806 "TBA1-TBA84" with the assigned values. 4808 +----------------------+-------+-------+------------+---------------+ 4809 | Parameter Name | CBOR | CBOR | Change | Specification | 4810 | | Key | Major | Controller | Document(s) | 4811 | | Value | Type | | | 4812 +======================+=======+=======+============+===============+ 4813 | tsid | TBA1 | 0 | IESG | [RFCXXXX] | 4814 | telemetry | TBA2 | 4 | IESG | [RFCXXXX] | 4815 | low-percentile | TBA3 | 6tag4 | IESG | [RFCXXXX] | 4816 | mid-percentile | TBA4 | 6tag4 | IESG | [RFCXXXX] | 4817 | high-percentile | TBA5 | 6tag4 | IESG | [RFCXXXX] | 4818 | unit-config | TBA6 | 4 | IESG | [RFCXXXX] | 4819 | unit | TBA7 | 0 | IESG | [RFCXXXX] | 4820 | unit-status | TBA8 | 7 | IESG | [RFCXXXX] | 4821 | total-pipe-capacity | TBA9 | 4 | IESG | [RFCXXXX] | 4822 | link-id | TBA10 | 3 | IESG | [RFCXXXX] | 4823 | pre-or-ongoing- | TBA11 | 4 | IESG | [RFCXXXX] | 4824 | mitigation | | | | | 4825 | total-traffic-normal | TBA12 | 4 | IESG | [RFCXXXX] | 4826 | low-percentile-g | TBA13 | 0 | IESG | [RFCXXXX] | 4827 | mid-percentile-g | TBA14 | 0 | IESG | [RFCXXXX] | 4828 | high-percentile-g | TBA15 | 0 | IESG | [RFCXXXX] | 4829 | peak-g | TBA16 | 0 | IESG | [RFCXXXX] | 4830 | total-attack-traffic | TBA17 | 4 | IESG | [RFCXXXX] | 4831 | total-traffic | TBA18 | 4 | IESG | [RFCXXXX] | 4832 | total-connection- | TBA19 | 4 | IESG | [RFCXXXX] | 4833 | capacity | | | | | 4834 | connection | TBA20 | 0 | IESG | [RFCXXXX] | 4835 | connection-client | TBA21 | 0 | IESG | [RFCXXXX] | 4836 | embryonic | TBA22 | 0 | IESG | [RFCXXXX] | 4837 | embryonic-client | TBA23 | 0 | IESG | [RFCXXXX] | 4838 | connection-ps | TBA24 | 0 | IESG | [RFCXXXX] | 4839 | connection-client-ps | TBA25 | 0 | IESG | [RFCXXXX] | 4840 | request-ps | TBA26 | 0 | IESG | [RFCXXXX] | 4841 | request-client-ps | TBA27 | 0 | IESG | [RFCXXXX] | 4842 | partial-request-max | TBA28 | 0 | IESG | [RFCXXXX] | 4843 | partial-request- | TBA29 | 0 | IESG | [RFCXXXX] | 4844 | client-max | | | | | 4845 | total-attack- | TBA30 | 5 | IESG | [RFCXXXX] | 4846 | connection | | | | | 4847 | connection-c | TBA31 | 5 | IESG | [RFCXXXX] | 4848 | embryonic-c | TBA32 | 5 | IESG | [RFCXXXX] | 4849 | connection-ps-c | TBA33 | 5 | IESG | [RFCXXXX] | 4850 | request-ps-c | TBA34 | 5 | IESG | [RFCXXXX] | 4851 | attack-detail | TBA35 | 4 | IESG | [RFCXXXX] | 4852 | id | TBA36 | 0 | IESG | [RFCXXXX] | 4853 | attack-id | TBA37 | 0 | IESG | [RFCXXXX] | 4854 | attack-description | TBA38 | 3 | IESG | [RFCXXXX] | 4855 | attack-severity | TBA39 | 0 | IESG | [RFCXXXX] | 4856 | start-time | TBA40 | 0 | IESG | [RFCXXXX] | 4857 | end-time | TBA41 | 0 | IESG | [RFCXXXX] | 4858 | source-count | TBA42 | 5 | IESG | [RFCXXXX] | 4859 | top-talker | TBA43 | 5 | IESG | [RFCXXXX] | 4860 | spoofed-status | TBA44 | 7 | IESG | [RFCXXXX] | 4861 | partial-request-c | TBA45 | 5 | IESG | [RFCXXXX] | 4862 | total-attack- | TBA46 | 4 | IESG | [RFCXXXX] | 4863 | connection-protocol | | | | | 4864 | baseline | TBA49 | 4 | IESG | [RFCXXXX] | 4865 | current-config | TBA50 | 5 | IESG | [RFCXXXX] | 4866 | max-config-value | TBA51 | 5 | IESG | [RFCXXXX] | 4867 | min-config-values | TBA52 | 5 | IESG | [RFCXXXX] | 4868 |supported-unit-classes| TBA53 | 5 | IESG | [RFCXXXX] | 4869 | server-originated- | TBA54 | 7 | IESG | [RFCXXXX] | 4870 | telemetry | | | | | 4871 | telemetry-notify- | TBA55 | 0 | IESG | [RFCXXXX] | 4872 | interval | | | | | 4873 | tmid | TBA56 | 0 | IESG | [RFCXXXX] | 4874 | measurement-interval | TBA57 | 0 | IESG | [RFCXXXX] | 4875 | measurement-sample | TBA58 | 0 | IESG | [RFCXXXX] | 4876 | talker | TBA59 | 4 | IESG | [RFCXXXX] | 4877 | source-prefix | TBA60 | 3 | IESG | [RFCXXXX] | 4878 | mid-list | TBA61 | 4 | IESG | [RFCXXXX] | 4879 | source-port-range | TBA62 | 4 | IESG | [RFCXXXX] | 4880 | source-icmp-type- | TBA63 | 4 | IESG | [RFCXXXX] | 4881 | range | | | | | 4882 | target | TBA64 | 5 | IESG | [RFCXXXX] | 4883 | capacity | TBA65 | 0 | IESG | [RFCXXXX] | 4884 | protocol | TBA66 | 0 | IESG | [RFCXXXX] | 4885 | total-traffic- | TBA67 | 4 | IESG | [RFCXXXX] | 4886 | normal-per-protocol | | | | | 4887 | total-traffic- | TBA68 | 4 | IESG | [RFCXXXX] | 4888 | normal-per-port | | | | | 4889 | total-connection- | TBA69 | 4 | IESG | [RFCXXXX] | 4890 | capacity-per-port | | | | | 4891 | total-traffic- | TBA70 | 4 | IESG | [RFCXXXX] | 4892 | protocol | | | | | 4893 | total-traffic-port | TBA71 | 4 | IESG | [RFCXXXX] | 4894 | total-attack- | TBA72 | 4 | IESG | [RFCXXXX] | 4895 | traffic-protocol | | | | | 4896 | total-attack- | TBA73 | 4 | IESG | [RFCXXXX] | 4897 | traffic-port | | | | | 4898 | total-attack- | TBA74 | 4 | IESG | [RFCXXXX] | 4899 | connection-port | | | | | 4900 | port | TBA75 | 0 | IESG | [RFCXXXX] | 4901 | supported-query-type | TBA76 | 4 | IESG | [RFCXXXX] | 4902 | vendor-id | TBA77 | 0 | IESG | [RFCXXXX] | 4903 | ietf-dots-telemetry: | TBA78 | 5 | IESG | [RFCXXXX] | 4904 | telemetry-setup | | | | | 4905 | ietf-dots-telemetry: | TBA79 | 4 | IESG | [RFCXXXX] | 4906 | total-traffic | | | | | 4907 | ietf-dots-telemetry: | TBA80 | 4 | IESG | [RFCXXXX] | 4908 | total-attack-traffic | | | | | 4909 | ietf-dots-telemetry: | TBA81 | 5 | IESG | [RFCXXXX] | 4910 | total-attack- | | | | | 4911 | connection | | | | | 4912 | ietf-dots-telemetry: | TBA82 | 4 | IESG | [RFCXXXX] | 4913 | attack-detail | | | | | 4914 | ietf-dots-telemetry: | TBA83 | 5 | IESG | [RFCXXXX] | 4915 | telemetry | | | | | 4916 | current-g | TBA84 | 0 | IESG | [RFCXXXX] | 4917 +----------------------+-------+-------+------------+---------------+ 4919 Table 4: Registered DOTS Signal Channel CBOR Key Values 4921 13.2. DOTS Signal Channel Conflict Cause Codes 4923 This specification requests IANA to assign a new code from the "DOTS 4924 Signal Channel Conflict Cause Codes" registry [Cause]. 4926 +------+-------------------+------------------------+-------------+ 4927 | Code | Label | Description | Reference | 4928 +======+===================+========================+=============+ 4929 | TBA | overlapping-pipes | Overlapping pipe scope | [RFCXXXX] | 4930 +------+-------------------+------------------------+-------------+ 4932 Table 5: Registered DOTS Signal Channel Conflict Cause Code 4934 * Note to the RFC Editor: Please replace all occurrences of "TBA" 4935 with the assigned value. 4937 13.3. DOTS Signal Telemetry YANG Module 4939 This document requests IANA to register the following URIs in the 4940 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4942 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4943 Registrant Contact: The IESG. 4944 XML: N/A; the requested URI is an XML namespace. 4946 URI: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4947 Registrant Contact: The IESG. 4948 XML: N/A; the requested URI is an XML namespace. 4950 This document requests IANA to register the following YANG modules in 4951 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4952 Parameters" registry. 4954 name: ietf-dots-telemetry 4955 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4956 maintained by IANA: N 4957 prefix: dots-telemetry 4958 reference: RFC XXXX 4960 name: ietf-dots-mapping 4961 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4962 maintained by IANA: N 4963 prefix: dots-mapping 4964 reference: RFC XXXX 4966 14. Security Considerations 4968 14.1. DOTS Signal Channel Telemetry 4970 The security considerations for the DOTS signal channel protocol are 4971 discussed in Section 11 of [RFC9132]. The following discusses the 4972 security considerations that are specific to the DOTS signal channel 4973 extension defined in this document. 4975 The DOTS telemetry information includes DOTS client network topology, 4976 DOTS client domain pipe capacity, normal traffic baseline and 4977 connections capacity, and threat and mitigation information. Such 4978 information is sensitive; it MUST be protected at rest by the DOTS 4979 server domain to prevent data leakage. Note that sharing this 4980 sensitive data with a trusted DOTS server does not introduce any new 4981 significant considerations other that the need for the aforementioned 4982 protection. Such a DOTS server is already trusted to have access to 4983 that kind of information by being in the position to observe and 4984 mitigate attacks. 4986 DOTS clients are typically considered to be trusted devices by the 4987 DOTS client domain. DOTS clients may be co-located on network 4988 security services (e.g., firewall devices), and a compromised 4989 security service potentially can do a lot more damage to the network 4990 than just the DOTS client component. This assumption differs from 4991 the often held view that devices are untrusted, often referred to as 4992 the "zero-trust model". A compromised DOTS client can send fake DOTS 4993 telemetry data to a DOTS server to mislead the DOTS server. This 4994 attack can be prevented by monitoring and auditing DOTS clients to 4995 detect misbehavior and to deter misuse, and by only authorizing the 4996 DOTS client to convey DOTS telemetry information for specific target 4997 resources (e.g., an application server is authorized to exchange DOTS 4998 telemetry for its IP addresses but a DDoS mitigator can exchange DOTS 4999 telemetry for any target resource in the network). As a reminder, 5000 this is a variation of dealing with compromised DOTS clients as 5001 discussed in Section 11 of [RFC9132]. 5003 DOTS servers must be capable of defending themselves against DoS 5004 attacks from compromised DOTS clients. The following non- 5005 comprehensive list of mitigation techniques can be used by a DOTS 5006 server to handle misbehaving DOTS clients: 5008 * The probing rate (defined in Section 4.5 of [RFC9132]) can be used 5009 to limit the average data rate to the DOTS server. 5011 * Rate-limiting DOTS telemetry, including those with new 'tmid' 5012 values, from the same DOTS client defends against DoS attacks that 5013 would result in varying the 'tmid' to exhaust DOTS server 5014 resources. Likewise, the DOTS server can enforce a quota and 5015 time-limit on the number of active pre-or-ongoing-mitigation 5016 telemetry data items (identified by 'tmid') from the DOTS client. 5018 Note also that telemetry notification interval may be used to rate- 5019 limit the pre-or-ongoing-mitigation telemetry notifications received 5020 by a DOTS client domain. 5022 14.2. Vendor Attack Mapping 5024 The security considerations for the DOTS data channel protocol are 5025 discussed in Section 10 of [RFC8783]. The following discusses the 5026 security considerations that are specific to the DOTS data channel 5027 extension defined in this document. 5029 All data nodes defined in the YANG module specified in Section 11.2 5030 which can be created, modified, and deleted (i.e., config true, which 5031 is the default) are considered sensitive. Write operations to these 5032 data nodes without proper protection can have a negative effect on 5033 network operations. Appropriate security measures are recommended to 5034 prevent illegitimate users from invoking DOTS data channel primitives 5035 as discussed in [RFC8783]. Nevertheless, an attacker who can access 5036 a DOTS client is technically capable of undertaking various attacks, 5037 such as: 5039 * Communicating invalid attack mapping details to the server 5040 ('/data-channel:dots-data/data-channel:dots-client/dots- 5041 telemetry:vendor-mapping'), which will mislead the server when 5042 correlating attack details. 5044 Some of the readable data nodes in the YANG module specified in 5045 Section 11.2 may be considered sensitive. It is thus important to 5046 control read access to these data nodes. These are the data nodes 5047 and their sensitivity: 5049 * '/data-channel:dots-data/data-channel:dots-client/dots- 5050 telemetry:vendor-mapping' can be misused to infer the DDoS 5051 protection technology deployed in a DOTS client domain. 5053 * '/data-channel:dots-data/dots-telemetry:vendor-mapping' can be 5054 used by a compromised DOTS client to leak the attack detection 5055 capabilities of the DOTS server. This is a variation of the 5056 compromised DOTS client attacks discussed in Section 14.1. 5058 15. Contributors 5060 The following individuals have contributed to this document: 5062 * Li Su, CMCC, Email: suli@chinamobile.com 5064 * Pan Wei, Huawei, Email: william.panwei@huawei.com 5066 16. Acknowledgements 5068 The authors would like to thank Flemming Andreasen, Liang Xia, and 5069 Kaname Nishizuka, co-authors of [I-D.doron-dots-telemetry], and 5070 everyone who had contributed to that document. 5072 Thanks to Kaname Nishizuka, Wei Pan, Yuuhei Hayashi, and Tom Petch 5073 for comments and review. 5075 Special thanks to Jon Shallow and Kaname Nishizuka for their 5076 implementation and interoperability work. 5078 Many thanks to Jan Lindblad for the yangdoctors review, Nagendra 5079 Nainar for the opsdir review, James Gruessing for the artart review, 5080 Michael Scharf for the tsv-art review, Ted Lemon for the int-dir 5081 review, and Robert Sparks for the gen-art review. 5083 Thanks to Benjamin Kaduk for the detailed AD review. 5085 17. References 5087 17.1. Normative References 5089 [Private-Enterprise-Numbers] 5090 "Private Enterprise Numbers", 4 May 2020, 5091 . 5093 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 5094 Requirement Levels", BCP 14, RFC 2119, 5095 DOI 10.17487/RFC2119, March 1997, 5096 . 5098 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 5099 DOI 10.17487/RFC3688, January 2004, 5100 . 5102 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 5103 the Network Configuration Protocol (NETCONF)", RFC 6020, 5104 DOI 10.17487/RFC6020, October 2010, 5105 . 5107 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 5108 RFC 6991, DOI 10.17487/RFC6991, July 2013, 5109 . 5111 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 5112 Application Protocol (CoAP)", RFC 7252, 5113 DOI 10.17487/RFC7252, June 2014, 5114 . 5116 [RFC7641] Hartke, K., "Observing Resources in the Constrained 5117 Application Protocol (CoAP)", RFC 7641, 5118 DOI 10.17487/RFC7641, September 2015, 5119 . 5121 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 5122 RFC 7950, DOI 10.17487/RFC7950, August 2016, 5123 . 5125 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 5126 the Constrained Application Protocol (CoAP)", RFC 7959, 5127 DOI 10.17487/RFC7959, August 2016, 5128 . 5130 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 5131 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 5132 November 2016, . 5134 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 5135 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 5136 . 5138 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5139 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5140 May 2017, . 5142 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 5143 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 5144 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 5145 2018, . 5147 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 5148 Denial-of-Service Open Threat Signaling (DOTS) Data 5149 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 5150 May 2020, . 5152 [RFC8791] Bierman, A., Björklund, M., and K. Watsen, "YANG Data 5153 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 5154 June 2020, . 5156 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 5157 Representation (CBOR)", STD 94, RFC 8949, 5158 DOI 10.17487/RFC8949, December 2020, 5159 . 5161 [RFC9132] Boucadair, M., Ed., Shallow, J., and T. Reddy.K, 5162 "Distributed Denial-of-Service Open Threat Signaling 5163 (DOTS) Signal Channel Specification", RFC 9132, 5164 DOI 10.17487/RFC9132, September 2021, 5165 . 5167 17.2. Informative References 5169 [Cause] IANA, "DOTS Signal Channel Conflict Cause Codes", 5170 . 5173 [I-D.doron-dots-telemetry] 5174 Doron, E., Reddy, T., Andreasen, F., (Frank), L. X., and 5175 K. Nishizuka, "Distributed Denial-of-Service Open Threat 5176 Signaling (DOTS) Telemetry Specifications", Work in 5177 Progress, Internet-Draft, draft-doron-dots-telemetry-00, 5178 30 October 2016, . 5181 [I-D.ietf-core-new-block] 5182 Boucadair, M. and J. Shallow, "Constrained Application 5183 Protocol (CoAP) Block-Wise Transfer Options Supporting 5184 Robust Transmission", Work in Progress, Internet-Draft, 5185 draft-ietf-core-new-block-14, 26 May 2021, 5186 . 5189 [I-D.ietf-dots-multihoming] 5190 Boucadair, M., Reddy, T., and W. Pan, "Multi-homing 5191 Deployment Considerations for Distributed-Denial-of- 5192 Service Open Threat Signaling (DOTS)", Work in Progress, 5193 Internet-Draft, draft-ietf-dots-multihoming-10, 4 January 5194 2022, . 5197 [I-D.ietf-dots-robust-blocks] 5198 Boucadair, M. and J. Shallow, "Distributed Denial-of- 5199 Service Open Threat Signaling (DOTS) Signal Channel 5200 Configuration Attributes for Robust Block Transmission", 5201 Work in Progress, Internet-Draft, draft-ietf-dots-robust- 5202 blocks-01, 5 January 2022, 5203 . 5206 [Key-Map] IANA, "DOTS Signal Channel CBOR Key Values", 5207 . 5210 [PYANG] "pyang", November 2020, 5211 . 5213 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 5214 "Framework for IP Performance Metrics", RFC 2330, 5215 DOI 10.17487/RFC2330, May 1998, 5216 . 5218 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 5219 Denial-of-Service Considerations", RFC 4732, 5220 DOI 10.17487/RFC4732, December 2006, 5221 . 5223 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 5224 RFC 4960, DOI 10.17487/RFC4960, September 2007, 5225 . 5227 [RFC5612] Eronen, P. and D. Harrington, "Enterprise Number for 5228 Documentation Use", RFC 5612, DOI 10.17487/RFC5612, August 5229 2009, . 5231 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 5232 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 5233 . 5235 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 5236 and R. Wilton, "YANG Library", RFC 8525, 5237 DOI 10.17487/RFC8525, March 2019, 5238 . 5240 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 5241 Threat Signaling (DOTS) Requirements", RFC 8612, 5242 DOI 10.17487/RFC8612, May 2019, 5243 . 5245 [RFC8811] Mortensen, A., Ed., Reddy.K, T., Ed., Andreasen, F., 5246 Teague, N., and R. Compton, "DDoS Open Threat Signaling 5247 (DOTS) Architecture", RFC 8811, DOI 10.17487/RFC8811, 5248 August 2020, . 5250 [RFC8903] Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 5251 L., and K. Nishizuka, "Use Cases for DDoS Open Threat 5252 Signaling", RFC 8903, DOI 10.17487/RFC8903, May 2021, 5253 . 5255 [RFC9133] Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 5256 "Controlling Filtering Rules Using Distributed Denial-of- 5257 Service Open Threat Signaling (DOTS) Signal Channel", 5258 RFC 9133, DOI 10.17487/RFC9133, September 2021, 5259 . 5261 Authors' Addresses 5263 Mohamed Boucadair (editor) 5264 Orange 5265 35000 Rennes 5266 France 5268 Email: mohamed.boucadair@orange.com 5270 Tirumaleswar Reddy.K (editor) 5271 Akamai 5272 Embassy Golf Link Business Park 5273 Bangalore 560071 5274 Karnataka 5275 India 5277 Email: kondtir@gmail.com 5279 Ehud Doron 5280 Radware Ltd. 5281 Raoul Wallenberg Street 5282 Tel-Aviv 69710 5283 Israel 5285 Email: ehudd@radware.com 5287 Meiling Chen 5288 CMCC 5289 32, Xuanwumen West 5290 BeiJing 5291 BeiJing, 100053 5292 China 5294 Email: chenmeiling@chinamobile.com 5296 Jon Shallow 5297 United Kingdom 5299 Email: supjps-ietf@jpshallow.com