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