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