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