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