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