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