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