idnits 2.17.1 draft-ietf-dots-telemetry-14.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 699 has weird spacing: '...-status boo...' == Line 715 has weird spacing: '...-status boo...' == Line 958 has weird spacing: '...apacity uin...' == Line 1302 has weird spacing: '...er-port ine...' == Line 1656 has weird spacing: '...er-port ine...' == (8 more instances...) -- The document date (November 15, 2020) is 1257 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 4579, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'Enterprise-Numbers' == Outdated reference: A later version (-08) exists of draft-ietf-dots-rfc8782-bis-01 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-14) exists of draft-ietf-core-new-block-02 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-04 Summary: 1 error (**), 0 flaws (~~), 11 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy, Ed. 5 Expires: May 19, 2021 McAfee 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 J. Shallow 11 November 15, 2020 13 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 14 draft-ietf-dots-telemetry-14 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 May 19, 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 . . . 19 86 6.1.4. Delete DOTS Telemetry Configuration . . . . . . . . . 20 87 6.2. Total Pipe Capacity . . . . . . . . . . . . . . . . . . . 20 88 6.2.1. Convey DOTS Client Domain Pipe Capacity . . . . . . . 21 89 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity . 27 90 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity . . 27 91 6.3. Telemetry Baseline . . . . . . . . . . . . . . . . . . . 27 92 6.3.1. Convey DOTS Client Domain Baseline Information . . . 30 93 6.3.2. Retrieve Installed Normal Traffic Baseline . . . . . 33 94 6.3.3. Delete Installed Normal Traffic Baseline . . . . . . 33 95 6.4. Reset Installed Telemetry Setup . . . . . . . . . . . . . 33 96 6.5. Conflict with Other DOTS Clients of the Same Domain . . . 33 97 7. DOTS Pre-or-Ongoing Mitigation Telemetry . . . . . . . . . . 34 98 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes . . . 36 99 7.1.1. Target . . . . . . . . . . . . . . . . . . . . . . . 37 100 7.1.2. Total Traffic . . . . . . . . . . . . . . . . . . . . 38 101 7.1.3. Total Attack Traffic . . . . . . . . . . . . . . . . 39 102 7.1.4. Total Attack Connections . . . . . . . . . . . . . . 41 103 7.1.5. Attack Details . . . . . . . . . . . . . . . . . . . 44 104 7.2. From DOTS Clients to DOTS Servers . . . . . . . . . . . . 50 105 7.3. From DOTS Servers to DOTS Clients . . . . . . . . . . . . 53 106 8. DOTS Telemetry Mitigation Status Update . . . . . . . . . . . 58 107 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS 108 Telemetry Attributes . . . . . . . . . . . . . . . . . . 58 109 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 110 Attributes . . . . . . . . . . . . . . . . . . . . . . . 60 111 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 64 112 10. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 64 113 10.1. DOTS Signal Channel Telemetry YANG Module . . . . . . . 64 114 10.2. Vendor Attack Mapping Details YANG Module . . . . . . . 92 115 11. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 95 116 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 97 117 12.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 97 118 12.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 100 119 12.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 100 120 13. Security Considerations . . . . . . . . . . . . . . . . . . . 101 121 13.1. DOTS Signal Channel Telemetry . . . . . . . . . . . . . 101 122 13.2. Vendor Attack Mapping . . . . . . . . . . . . . . . . . 102 123 14. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 103 124 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 103 125 16. References . . . . . . . . . . . . . . . . . . . . . . . . . 103 126 16.1. Normative References . . . . . . . . . . . . . . . . . . 103 127 16.2. Informative References . . . . . . . . . . . . . . . . . 105 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 106 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.ietf-dots-rfc8782-bis] is used 181 to carry information about a network resource or a network (or a part 182 thereof) that is under a DDoS attack. Such information is sent by a 183 DOTS client to one or multiple DOTS servers so that appropriate 184 mitigation actions are undertaken on traffic deemed suspicious. 185 Various use cases are discussed in [I-D.ietf-dots-use-cases]. 187 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.ietf-dots-rfc8782-bis]. Nevertheless, when DOTS 221 telemetry attributes are available to a DOTS agent, and absent any 222 policy, it can signal the attributes in order to optimize the overall 223 mitigation service provisioned using DOTS. 225 2. Terminology 227 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 228 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 229 "OPTIONAL" in this document are to be interpreted as described in BCP 230 14 [RFC2119][RFC8174] when, and only when, they appear in all 231 capitals, as shown here. 233 The reader should be familiar with the terms defined in [RFC8612]. 235 "DOTS Telemetry" is defined as the collection of attributes that are 236 used to characterize normal traffic baseline, attacks and their 237 mitigation measures, and any related information that may help in 238 enforcing countermeasures. The DOTS Telemetry is an optional set of 239 attributes that can be signaled in the DOTS signal channel protocol. 241 Telemetry Setup Identifier (tsid) is an identifier that is generated 242 by DOTS clients to uniquely identify DOTS telemetry setup 243 configuration data. 245 Telemetry Identifier (tmid) is an identifier that is generated by 246 DOTS clients to uniquely identify DOTS telemetry data that is 247 communicated prior or during a mitigation. 249 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 information, 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.ietf-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 4.4.1 of [I-D.ietf-dots-rfc8782-bis], 449 a unique identifier is generated by a DOTS client to prevent request 450 collisions ('cuid'). 452 As a reminder, [I-D.ietf-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 4.4.1 of 459 [I-D.ietf-dots-rfc8782-bis] must be followed. In particular, 'cdid' 460 attribute is used to unambiguously identify a DOTS client domain. 462 As a reminder, [I-D.ietf-dots-rfc8782-bis] forbids 'cdid' (if 463 present) to be returned in a response message body. 465 4.2.3. Empty URI Paths 467 Uri-Path parameters and attributes with empty values MUST NOT be 468 present in a request and render an entire message invalid. 470 4.2.4. Controlling Configuration Data 472 The DOTS server follows the same considerations discussed in 473 Section of 4.5.3 of [I-D.ietf-dots-rfc8782-bis] for managing DOTS 474 telemetry configuration freshness and notification. 476 Likewise, a DOTS client may control the selection of configuration 477 and non-configuration data nodes when sending a GET request by means 478 of the 'c' Uri-Query option and following the procedure specified in 479 Section of 4.4.2 of [I-D.ietf-dots-rfc8782-bis]. These 480 considerations are not reiterated in the following sections. 482 4.3. Block-wise Transfer 484 DOTS clients can use block wise transfer [RFC7959] with the 485 recommendation detailed in Section 4.4.2 of 486 [I-D.ietf-dots-rfc8782-bis] to control the size of a response when 487 the data to be returned does not fit within a single datagram. 489 DOTS clients can also use CoAP Block1 Option in a PUT request (see 490 Section 2.5 of [RFC7959]) to initiate large transfers, but these 491 Block1 transfers will fail if the inbound "pipe" is running full, so 492 consideration needs to be made to try to fit this PUT into a single 493 transfer, or to separate out the PUT into several discrete PUTs where 494 each of them fits into a single packet. 496 Q-Block1 and Q-Block2 Options that are similar to the CoAP Block1 and 497 Block2 Options, but enable faster transmissions of big blocks of data 498 with less packet interchanges, are defined in 499 [I-D.ietf-core-new-block]. DOTS implementations can consider the use 500 of Q-Block1 and Q-Block2 Options. 502 4.4. DOTS Multi-homing Considerations 504 Multi-homed DOTS clients are assumed to follow the recommendations in 505 [I-D.ietf-dots-multihoming] to select which DOTS server to contact 506 and which IP prefixes to include in a telemetry message to a given 507 peer DOTS server. For example, if each upstream network exposes a 508 DOTS server and the DOTS client maintains DOTS channels with all of 509 them, only the information related to prefixes assigned by an 510 upstream network to the DOTS client domain will be signaled via the 511 DOTS channel established with the DOTS server of that upstream 512 network. 514 Considerations related to whether (and how) a DOTS client gleans some 515 telemetry information (e.g., attack details) it receives from a first 516 DOTS server and share it with a second DOTS server are implementation 517 and deployment specific. 519 4.5. YANG Considerations 521 Telemetry messages exchanged between DOTS agents are serialized using 522 Concise Binary Object Representation (CBOR) [RFC7049]. CBOR-encoded 523 payloads are used to carry signal channel specific payload messages 524 which convey request parameters and response information such as 525 errors. 527 This document specifies a YANG module [RFC7950] for representing DOTS 528 telemetry message types (Section 10.1). All parameters in the 529 payload of the DOTS signal channel are mapped to CBOR types as 530 specified in Section 11. 532 The DOTS telemetry module (Section 10.1) is not intended to be used 533 via NETCONF/RESTCONF for DOTS server management purposes. It serves 534 only to provide a data model and encoding following [RFC8791]. 536 The DOTS telemetry module (Section 10.1) uses "enumerations" rather 537 than "identities" to define units, samples, and intervals because 538 otherwise the namespace identifier "ietf-dots-telemetry" must be 539 included when a telemetry attribute is included (e.g., in a 540 mitigation efficacy update). The use of "identities" is thus 541 suboptimal from a message compactness standpoint. 543 4.6. A Note About Examples 545 Examples are provided for illustration purposes. The document does 546 not aim to provide a comprehensive list of message examples. 548 The authoritative reference for validating telemetry messages is the 549 YANG module (Section 10.1) and the mapping table established in 550 Section 11. 552 5. Telemetry Operation Paths 554 As discussed in Section 4.2 of [I-D.ietf-dots-rfc8782-bis], each DOTS 555 operation is indicated by a path suffix that indicates the intended 556 operation. The operation path is appended to the path prefix to form 557 the URI used with a CoAP request to perform the desired DOTS 558 operation. The following telemetry path suffixes are defined 559 (Table 1): 561 +-----------------+----------------+-----------+ 562 | Operation | Operation Path | Details | 563 +=================+================+===========+ 564 | Telemetry Setup | /tm-setup | Section 6 | 565 | Telemetry | /tm | Section 7 | 566 +-----------------+----------------+-----------+ 568 Table 1: DOTS Telemetry Operations 570 Consequently, the "ietf-dots-telemetry" YANG module defined in 571 Section 10.1 defines data structure to represent new DOTS message 572 types called 'telemetry-setup' and 'telemetry'. The tree structure 573 is shown in Figure 1. More details are provided in Sections 6 and 7 574 about the exact structure of 'telemetry-setup' and 'telemetry' 575 message types. 577 structure dots-telemetry: 578 +-- (telemetry-message-type)? 579 +--:(telemetry-setup) 580 | ... 581 | +-- telemetry* [] 582 | ... 583 | +-- (setup-type)? 584 | +--:(telemetry-config) 585 | | ... 586 | +--:(pipe) 587 | | ... 588 | +--:(baseline) 589 | ... 590 +--:(telemetry) 591 ... 593 Figure 1: New DOTS Message Types (YANG Tree Structure) 595 6. DOTS Telemetry Setup Configuration 597 In reference to Figure 1, a DOTS telemetry setup message MUST include 598 only telemetry-related configuration parameters (Section 6.1) or 599 information about DOTS client domain pipe capacity (Section 6.2) or 600 telemetry traffic baseline (Section 6.3). As such, requests that 601 include a mix of telemetry configuration, pipe capacity, or traffic 602 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 604 A DOTS client can reset all installed DOTS telemetry setup 605 configuration data following the considerations detailed in 606 Section 6.4. 608 A DOTS server may detect conflicts when processing requests related 609 to DOTS client domain pipe capacity or telemetry traffic baseline 610 with requests from other DOTS clients of the same DOTS client domain. 611 More details are included in Section 6.5. 613 Telemetry setup configuration is bound to a DOTS client domain. DOTS 614 servers MUST NOT expect DOTS clients to send regular requests to 615 refresh the telemetry setup configuration. Any available telemetry 616 setup configuration has a validity timeout of the DOTS association 617 with a DOTS client domain. DOTS servers MUST NOT reset 'tsid' 618 because a session failed with a DOTS client. DOTS clients update 619 their telemetry setup configuration upon change of a parameter that 620 may impact attack mitigation. 622 DOTS telemetry setup configuration request and response messages are 623 marked as Confirmable messages (Section 2.1 of [RFC7252]). 625 6.1. Telemetry Configuration 627 A DOTS client can negotiate with its server(s) a set of telemetry 628 configuration parameters to be used for telemetry. Such parameters 629 include: 631 o Percentile-related measurement parameters 633 o Measurement units 635 o Acceptable percentile values 637 o Telemetry notification interval 639 o Acceptable Server-originated telemetry 641 Section 11.3 of [RFC2330] includes more details about computing 642 percentiles. 644 6.1.1. Retrieve Current DOTS Telemetry Configuration 646 A GET request is used to obtain acceptable and current telemetry 647 configuration parameters on the DOTS server. This request may 648 include a 'cdid' Uri-Path when the request is relayed by a DOTS 649 gateway. An example of such request is depicted in Figure 2. 651 Header: GET (Code=0.01) 652 Uri-Path: ".well-known" 653 Uri-Path: "dots" 654 Uri-Path: "tm-setup" 655 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 657 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 658 Configuration 660 Upon receipt of such request, and assuming no error is encountered by 661 processing the request, the DOTS server replies with a 2.05 (Content) 662 response that conveys the current and telemetry parameters acceptable 663 by the DOTS server. The tree structure of the response message body 664 is provided in Figure 3. Note that the response also includes any 665 pipe (Section 6.2) and baseline information (Section 6.3) maintained 666 by the DOTS server for this DOTS client. 668 DOTS servers that support the capability of sending telemetry 669 information to DOTS clients prior or during a mitigation 670 (Section 8.2) sets 'server-originated-telemetry' under 'max-config- 671 values' to 'true' ('false' is used otherwise). If 'server- 672 originated-telemetry' is not present in a response, this is 673 equivalent to receiving a request with 'server-originated-telemetry' 674 set to 'false'. 676 structure dots-telemetry: 677 +-- (telemetry-message-type)? 678 +--:(telemetry-setup) 679 | +-- (direction)? 680 | | +--:(server-to-client-only) 681 | | +-- max-config-values 682 | | | +-- measurement-interval? interval 683 | | | +-- measurement-sample? sample 684 | | | +-- low-percentile? percentile 685 | | | +-- mid-percentile? percentile 686 | | | +-- high-percentile? percentile 687 | | | +-- server-originated-telemetry? boolean 688 | | | +-- telemetry-notify-interval? uint32 689 | | +-- min-config-values 690 | | | +-- measurement-interval? interval 691 | | | +-- measurement-sample? sample 692 | | | +-- low-percentile? percentile 693 | | | +-- mid-percentile? percentile 694 | | | +-- high-percentile? percentile 695 | | | +-- telemetry-notify-interval? uint32 696 | | +-- supported-units 697 | | | +-- unit-config* [unit] 698 | | | +-- unit unit-type 699 | | | +-- unit-status boolean 700 | | +-- query-type* query-type 701 | +-- telemetry* [] 702 | +-- (direction)? 703 | | +--:(server-to-client-only) 704 | | +-- tsid? uint32 705 | +-- (setup-type)? 706 | +--:(telemetry-config) 707 | | +-- current-config 708 | | +-- measurement-interval? interval 709 | | +-- measurement-sample? sample 710 | | +-- low-percentile? percentile 711 | | +-- mid-percentile? percentile 712 | | +-- high-percentile? percentile 713 | | +-- unit-config* [unit] 714 | | | +-- unit unit-type 715 | | | +-- unit-status boolean 716 | | +-- server-originated-telemetry? boolean 717 | | +-- telemetry-notify-interval? uint32 718 | +--:(pipe) 719 | | ... 720 | +--:(baseline) 721 | ... 722 +--:(telemetry) 723 ... 725 Figure 3: Telemetry Configuration Tree Structure 727 When both 'min-config-values' and 'max-config-values' attributes are 728 present, the values carried in 'max-config-values' attributes MUST be 729 greater or equal to their counterpart in 'min-config-values' 730 attributes. 732 6.1.2. Convey DOTS Telemetry Configuration 734 PUT request is used to convey the configuration parameters for the 735 telemetry data (e.g., low, mid, or high percentile values). For 736 example, a DOTS client may contact its DOTS server to change the 737 default percentile values used as baseline for telemetry data. 738 Figure 3 lists the attributes that can be set by a DOTS client in 739 such PUT request. An example of a DOTS client that modifies all 740 percentile reference values is shown in Figure 4. 742 Header: PUT (Code=0.03) 743 Uri-Path: ".well-known" 744 Uri-Path: "dots" 745 Uri-Path: "tm-setup" 746 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 747 Uri-Path: "tsid=123" 748 Content-Format: "application/dots+cbor" 750 { 751 "ietf-dots-telemetry:telemetry-setup": { 752 "telemetry": [ 753 { 754 "current-config": { 755 "low-percentile": "5.00", 756 "mid-percentile": "65.00", 757 "high-percentile": "95.00" 758 } 759 } 760 ] 761 } 762 } 764 Figure 4: PUT to Convey the DOTS Telemetry Configuration 766 'cuid' is a mandatory Uri-Path parameter for PUT requests. 768 The following additional Uri-Path parameter is defined: 770 tsid: Telemetry Setup Identifier is an identifier for the DOTS 771 telemetry setup configuration data represented as an integer. 772 This identifier MUST be generated by DOTS clients. 'tsid' 773 values MUST increase monotonically (when a new PUT is generated 774 by a DOTS client to convey new configuration parameters for the 775 telemetry). 777 The procedure specified in Section 4.4.1 of 778 [I-D.ietf-dots-rfc8782-bis] MUST be followed for 'tsid' 779 rollover. 781 This is a mandatory attribute. 'tsid' MUST follow 'cuid'. 783 'cuid' and 'tsid' MUST NOT appear in the PUT request message body. 785 At least one configurable attribute MUST be present in the PUT 786 request. 788 The PUT request with a higher numeric 'tsid' value overrides the DOTS 789 telemetry configuration data installed by a PUT request with a lower 790 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 791 requests for requests carrying telemetry configuration data from a 792 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 793 and no longer be available at the DOTS server. 795 The DOTS server indicates the result of processing the PUT request 796 using the following Response Codes: 798 o If the request is missing a mandatory attribute, does not include 799 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 800 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 801 in the response. 803 o If the DOTS server does not find the 'tsid' parameter value 804 conveyed in the PUT request in its configuration data and if the 805 DOTS server has accepted the configuration parameters, then a 2.01 806 (Created) Response Code MUST be returned in the response. 808 o If the DOTS server finds the 'tsid' parameter value conveyed in 809 the PUT request in its configuration data and if the DOTS server 810 has accepted the updated configuration parameters, 2.04 (Changed) 811 MUST be returned in the response. 813 o If any of the enclosed configurable attribute values are not 814 acceptable to the DOTS server (Section 6.1.1), 4.22 (Unprocessable 815 Entity) MUST be returned in the response. 817 The DOTS client may retry and send the PUT request with updated 818 attribute values acceptable to the DOTS server. 820 By default, low percentile (10th percentile), mid percentile (50th 821 percentile), high percentile (90th percentile), and peak (100th 822 percentile) values are used to represent telemetry data. 823 Nevertheless, a DOTS client can disable some percentile types (low, 824 mid, high). In particular, setting 'low-percentile' to '0.00' 825 indicates that the DOTS client is not interested in receiving low- 826 percentiles. Likewise, setting 'mid-percentile' (or 'high- 827 percentile') to the same value as 'low-percentile' (or 'mid- 828 percentile') indicates that the DOTS client is not interested in 829 receiving mid-percentiles (or high-percentiles). For example, a DOTS 830 client can send the request depicted in Figure 5 to inform the server 831 that it is interested in receiving only high-percentiles. This 832 assumes that the client will only use that percentile type when 833 sharing telemetry data with the server. 835 Header: PUT (Code=0.03) 836 Uri-Path: ".well-known" 837 Uri-Path: "dots" 838 Uri-Path: "tm-setup" 839 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 840 Uri-Path: "tsid=569" 841 Content-Format: "application/dots+cbor" 843 { 844 "ietf-dots-telemetry:telemetry-setup": { 845 "telemetry": [ 846 { 847 "current-config": { 848 "low-percentile": "0.00", 849 "mid-percentile": "0.00", 850 "high-percentile": "95.00" 851 } 852 } 853 ] 854 } 855 } 857 Figure 5: PUT to Disable Low- and Mid-Percentiles 859 DOTS clients can also configure the unit type(s) to be used for 860 traffic-related telemetry data. Typically, the supported unit types 861 are: packets per second, bits per second, and bytes per second. 863 DOTS clients that are interested to receive pre or ongoing mitigation 864 telemetry (pre-or-ongoing-mitigation) information from a DOTS server 865 (Section 8.2) MUST set 'server-originated-telemetry' to 'true'. If 866 'server-originated-telemetry' is not present in a PUT request, this 867 is equivalent to receiving a request with 'server-originated- 868 telemetry' set to 'false'. An example of a request to enable pre-or- 869 ongoing-mitigation telemetry from DOTS servers is shown in Figure 6. 871 Header: PUT (Code=0.03) 872 Uri-Path: ".well-known" 873 Uri-Path: "dots" 874 Uri-Path: "tm-setup" 875 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 876 Uri-Path: "tsid=569" 877 Content-Format: "application/dots+cbor" 879 { 880 "ietf-dots-telemetry:telemetry-setup": { 881 "telemetry": [ 882 { 883 "current-config": { 884 "server-originated-telemetry": true 885 } 886 } 887 ] 888 } 889 } 891 Figure 6: PUT to Enable Pre-or-ongoing-mitigation Telemetry from the 892 DOTS server 894 6.1.3. Retrieve Installed DOTS Telemetry Configuration 896 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 897 to retrieve the current DOTS telemetry configuration. An example of 898 such request is depicted in Figure 7. 900 Header: GET (Code=0.01) 901 Uri-Path: ".well-known" 902 Uri-Path: "dots" 903 Uri-Path: "tm-setup" 904 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 905 Uri-Path: "tsid=123" 907 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 909 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 910 in the GET request in its configuration data for the requesting DOTS 911 client, it MUST respond with a 4.04 (Not Found) error Response Code. 913 6.1.4. Delete DOTS Telemetry Configuration 915 A DELETE request is used to delete the installed DOTS telemetry 916 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 917 Path parameters for such DELETE requests. 919 Header: DELETE (Code=0.04) 920 Uri-Path: ".well-known" 921 Uri-Path: "dots" 922 Uri-Path: "tm-setup" 923 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 924 Uri-Path: "tsid=123" 926 Figure 8: Delete Telemetry Configuration 928 The DOTS server resets the DOTS telemetry configuration back to the 929 default values and acknowledges a DOTS client's request to remove the 930 DOTS telemetry configuration using 2.02 (Deleted) Response Code. A 931 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 932 value conveyed in the DELETE request does not exist in its 933 configuration data before the request. 935 Section 6.4 discusses the procedure to reset all DOTS telemetry setup 936 configuration. 938 6.2. Total Pipe Capacity 940 A DOTS client can communicate to the DOTS server(s) its DOTS client 941 domain pipe information. The tree structure of the pipe information 942 is shown in Figure 9. 944 structure dots-telemetry: 945 +-- (telemetry-message-type)? 946 +--:(telemetry-setup) 947 | ... 948 | +-- telemetry* [] 949 | +-- (direction)? 950 | | +--:(server-to-client-only) 951 | | +-- tsid? uint32 952 | +-- (setup-type)? 953 | +--:(telemetry-config) 954 | | ... 955 | +--:(pipe) 956 | | +-- total-pipe-capacity* [link-id unit] 957 | | +-- link-id nt:link-id 958 | | +-- capacity uint64 959 | | +-- unit unit 960 | +--:(baseline) 961 | ... 962 +--:(telemetry) 963 ... 965 Figure 9: Pipe Tree Structure 967 A DOTS client domain pipe is defined as a list of limits of 968 (incoming) traffic volume ('total-pipe-capacity') that can be 969 forwarded over ingress interconnection links of a DOTS client domain. 970 Each of these links is identified with a 'link-id' [RFC8345]. 972 The unit used by a DOTS client when conveying pipe information is 973 captured in 'unit' attribute. 975 6.2.1. Convey DOTS Client Domain Pipe Capacity 977 Similar considerations to those specified in Section 6.1.2 are 978 followed with one exception: 980 The relative order of two PUT requests carrying DOTS client domain 981 pipe attributes from a DOTS client is determined by comparing 982 their respective 'tsid' values. If such two requests have 983 overlapping 'link-id' and 'unit', the PUT request with higher 984 numeric 'tsid' value will override the request with a lower 985 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 986 automatically deleted and no longer be available. 988 DOTS clients SHOULD minimize the number of active 'tsids' used for 989 pipe information. Typically, in order to avoid maintaining a long 990 list of 'tsids' for pipe information, it is RECOMMENDED that DOTS 991 clients include in any request to update information related to a 992 given link the information of other links (already communicated using 993 a lower 'tsid' value). Doing so, this update request will override 994 these existing requests and hence optimize the number of 'tsid' 995 request per DOTS client. 997 o Note: This assumes that all link information can fit in one single 998 message. 1000 For example, a DOTS client managing a single homed domain (Figure 10) 1001 can send a PUT request (shown in Figure 11) to communicate the 1002 capacity of "link1" used to connect to its ISP. 1004 ,--,--,--. ,--,--,--. 1005 ,-' `-. ,-' `-. 1006 ( DOTS Client )=====( ISP#A ) 1007 `-. Domain ,-' link1 `-. ,-' 1008 `--'--'--' `--'--'--' 1010 Figure 10: Single Homed DOTS Client Domain 1012 Header: PUT (Code=0.03) 1013 Uri-Path: ".well-known" 1014 Uri-Path: "dots" 1015 Uri-Path: "tm-setup" 1016 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1017 Uri-Path: "tsid=457" 1018 Content-Format: "application/dots+cbor" 1020 { 1021 "ietf-dots-telemetry:telemetry-setup": { 1022 "telemetry": [ 1023 { 1024 "total-pipe-capacity": [ 1025 { 1026 "link-id": "link1", 1027 "capacity": "500", 1028 "unit": "megabit-ps" 1029 } 1030 ] 1031 } 1032 ] 1033 } 1034 } 1036 Figure 11: Example of a PUT Request to Convey Pipe Information 1037 (Single Homed) 1039 DOTS clients may be instructed to signal a link aggregate instead of 1040 individual links. For example, a DOTS client that manages a DOTS 1041 client domain having two interconnection links with an upstream ISP 1042 (Figure 12) can send a PUT request (shown in Figure 13) to 1043 communicate the aggregate link capacity with its ISP. Signalling 1044 individual or aggregate link capacity is deployment specific. 1046 ,--,--,--. ,--,--,--. 1047 ,-' `-.===== ,-' `-. 1048 ( DOTS Client ) ( ISP#C ) 1049 `-. Domain ,-'====== `-. ,-' 1050 `--'--'--' `--'--'--' 1052 Figure 12: DOTS Client Domain with Two Interconnection Links 1054 Header: PUT (Code=0.03) 1055 Uri-Path: ".well-known" 1056 Uri-Path: "dots" 1057 Uri-Path: "tm-setup" 1058 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1059 Uri-Path: "tsid=896" 1060 Content-Format: "application/dots+cbor" 1062 { 1063 "ietf-dots-telemetry:telemetry-setup": { 1064 "telemetry": [ 1065 { 1066 "total-pipe-capacity": [ 1067 { 1068 "link-id": "aggregate", 1069 "capacity": "700", 1070 "unit": "megabit-ps" 1071 } 1072 ] 1073 } 1074 ] 1075 } 1076 } 1078 Figure 13: Example of a PUT Request to Convey Pipe Information 1079 (Aggregated Link) 1081 Now consider that the DOTS client domain was upgraded to connect to 1082 an additional ISP (e.g., ISP#B of Figure 14), the DOTS client can 1083 inform a third-party DOTS server (that is, not hosted with ISP#A and 1084 ISP#B domains) about this update by sending the PUT request depicted 1085 in Figure 15. This request also includes information related to 1086 "link1" even if that link is not upgraded. Upon receipt of this 1087 request, the DOTS server removes the request with 'tsid=457' and 1088 updates its configuration base to maintain two links (link#1 and 1089 link#2). 1091 ,--,--,--. 1092 ,-' `-. 1093 ( ISP#B ) 1094 `-. ,-' 1095 `--'--'--' 1096 || 1097 || link2 1098 ,--,--,--. ,--,--,--. 1099 ,-' `-. ,-' `-. 1100 ( DOTS Client )=====( ISP#A ) 1101 `-. Domain ,-' link1 `-. ,-' 1102 `--'--'--' `--'--'--' 1104 Figure 14: Multi-Homed DOTS Client Domain 1106 Header: PUT (Code=0.03) 1107 Uri-Path: ".well-known" 1108 Uri-Path: "dots" 1109 Uri-Path: "tm-setup" 1110 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1111 Uri-Path: "tsid=458" 1112 Content-Format: "application/dots+cbor" 1114 { 1115 "ietf-dots-telemetry:telemetry-setup": { 1116 "telemetry": [ 1117 { 1118 "total-pipe-capacity": [ 1119 { 1120 "link-id": "link1", 1121 "capacity": "500", 1122 "unit": "megabit-ps" 1123 }, 1124 { 1125 "link-id": "link2", 1126 "capacity": "500", 1127 "unit": "megabit-ps" 1128 } 1129 ] 1130 } 1131 ] 1132 } 1133 } 1135 Figure 15: Example of a PUT Request to Convey Pipe Information 1136 (Multi-Homed) 1138 A DOTS client can delete a link by sending a PUT request with the 1139 'capacity' attribute set to "0" if other links are still active for 1140 the same DOTS client domain (see Section 6.2.3 for other delete 1141 cases). For example, if a DOTS client domain re-homes (that is, it 1142 changes its ISP), the DOTS client can inform its DOTS server about 1143 this update (e.g., from the network configuration in Figure 10 to the 1144 one shown in Figure 16) by sending the PUT request depicted in 1145 Figure 17. Upon receipt of this request, and assuming no error is 1146 encountered when processing the request, the DOTS server removes 1147 "link1" from its configuration bases for this DOTS client domain. 1148 Note that if the DOTS server receives a PUT request with a 'capacity' 1149 attribute set to "0" for all included links, it MUST reject the 1150 request with a 4.00 (Bad Request). 1152 ,--,--,--. 1153 ,-' `-. 1154 ( ISP#B ) 1155 `-. ,-' 1156 `--'--'--' 1157 || 1158 || link2 1159 ,--,--,--. 1160 ,-' `-. 1161 ( DOTS Client ) 1162 `-. Domain ,-' 1163 `--'--'--' 1165 Figure 16: Multi-Homed DOTS Client Domain 1167 Header: PUT (Code=0.03) 1168 Uri-Path: ".well-known" 1169 Uri-Path: "dots" 1170 Uri-Path: "tm-setup" 1171 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1172 Uri-Path: "tsid=459" 1173 Content-Format: "application/dots+cbor" 1175 { 1176 "ietf-dots-telemetry:telemetry-setup": { 1177 "telemetry": [ 1178 { 1179 "total-pipe-capacity": [ 1180 { 1181 "link-id": "link1", 1182 "capacity": "0", 1183 "unit": "megabit-ps" 1184 }, 1185 { 1186 "link-id": "link2", 1187 "capacity": "500", 1188 "unit": "megabit-ps" 1189 } 1190 ] 1191 } 1192 ] 1193 } 1194 } 1196 Figure 17: Example of a PUT Request to Convey Pipe Information 1197 (Multi-Homed) 1199 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity 1201 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1202 specific installed DOTS client domain pipe related information. The 1203 same procedure as defined in Section 6.1.3 is followed. 1205 To retrieve all pipe information bound to a DOTS client, the DOTS 1206 client proceeds as specified in Section 6.1.1. 1208 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity 1210 A DELETE request is used to delete the installed DOTS client domain 1211 pipe related information. The same procedure as defined in 1212 Section 6.1.4 is followed. 1214 6.3. Telemetry Baseline 1216 A DOTS client can communicate to its DOTS server(s) its normal 1217 traffic baseline and connections capacity: 1219 Total traffic normal baseline: The percentile values representing 1220 the total traffic normal baseline. It can be represented for a 1221 target using 'total-traffic-normal'. 1223 The traffic normal per protocol ('total-traffic-normal-per- 1224 protocol') baseline is represented for a target and is transport- 1225 protocol specific. 1227 The traffic normal per port number ('total-traffic-normal-per- 1228 port') baseline is represented for each port number bound to a 1229 target. 1231 If the DOTS client negotiated percentile values and units 1232 (Section 6.1), these negotiated values will be used instead of the 1233 default ones. 1235 Total connections capacity: If the target is subjected to resource 1236 consuming DDoS attacks, the following optional attributes for the 1237 target per transport protocol are useful to detect resource 1238 consuming DDoS attacks: 1240 * The maximum number of simultaneous connections that are allowed 1241 to the target. 1243 * The maximum number of simultaneous connections that are allowed 1244 to the target per client. 1246 * The maximum number of simultaneous embryonic connections that 1247 are allowed to the target. The term "embryonic connection" 1248 refers to a connection whose connection handshake is not 1249 finished. Embryonic connection is only possible in connection- 1250 oriented transport protocols like TCP or SCTP. 1252 * The maximum number of simultaneous embryonic connections that 1253 are allowed to the target per client. 1255 * The maximum number of connections allowed per second to the 1256 target. 1258 * The maximum number of connections allowed per second to the 1259 target per client. 1261 * The maximum number of requests allowed per second to the 1262 target. 1264 * The maximum number of requests allowed per second to the target 1265 per client. 1267 * The maximum number of partial requests allowed per second to 1268 the target. Attacks relying upon partial requests create a 1269 connection with a target but do not send a complete request 1270 (e.g., HTTP request). 1272 * The maximum number of partial requests allowed per second to 1273 the target per client. 1275 The aggregate per transport protocol is captured in 'total- 1276 connection-capacity', while port specific capabilities are 1277 represented using 'total-connection-capacity-per-port'. 1279 The tree structure of the normal traffic baseline is shown in 1280 Figure 18. 1282 structure dots-telemetry: 1283 +-- (telemetry-message-type)? 1284 +--:(telemetry-setup) 1285 | ... 1286 | +-- telemetry* [] 1287 | +-- (direction)? 1288 | | +--:(server-to-client-only) 1289 | | +-- tsid? uint32 1290 | +-- (setup-type)? 1291 | +--:(telemetry-config) 1292 | | ... 1293 | +--:(pipe) 1294 | | ... 1295 | +--:(baseline) 1296 | +-- baseline* [id] 1297 | +-- id 1298 | | uint32 1299 | +-- target-prefix* 1300 | | inet:ip-prefix 1301 | +-- target-port-range* [lower-port] 1302 | | +-- lower-port inet:port-number 1303 | | +-- upper-port? inet:port-number 1304 | +-- target-protocol* uint8 1305 | +-- target-fqdn* 1306 | | inet:domain-name 1307 | +-- target-uri* 1308 | | inet:uri 1309 | +-- alias-name* 1310 | | string 1311 | +-- total-traffic-normal* [unit] 1312 | | +-- unit unit 1313 | | +-- low-percentile-g? yang:gauge64 1314 | | +-- mid-percentile-g? yang:gauge64 1315 | | +-- high-percentile-g? yang:gauge64 1316 | | +-- peak-g? yang:gauge64 1317 | +-- total-traffic-normal-per-protocol* 1318 | | [unit protocol] 1319 | | +-- protocol uint8 1320 | | +-- unit unit 1321 | | +-- low-percentile-g? yang:gauge64 1322 | | +-- mid-percentile-g? yang:gauge64 1323 | | +-- high-percentile-g? yang:gauge64 1324 | | +-- peak-g? yang:gauge64 1325 | +-- total-traffic-normal-per-port* [unit port] 1326 | | +-- port inet:port-number 1327 | | +-- unit unit 1328 | | +-- low-percentile-g? yang:gauge64 1329 | | +-- mid-percentile-g? yang:gauge64 1330 | | +-- high-percentile-g? yang:gauge64 1331 | | +-- peak-g? yang:gauge64 1332 | +-- total-connection-capacity* [protocol] 1333 | | +-- protocol uint8 1334 | | +-- connection? uint64 1335 | | +-- connection-client? uint64 1336 | | +-- embryonic? uint64 1337 | | +-- embryonic-client? uint64 1338 | | +-- connection-ps? uint64 1339 | | +-- connection-client-ps? uint64 1340 | | +-- request-ps? uint64 1341 | | +-- request-client-ps? uint64 1342 | | +-- partial-request-ps? uint64 1343 | | +-- partial-request-client-ps? uint64 1344 | +-- total-connection-capacity-per-port* 1345 | [protocol port] 1346 | +-- port 1347 | | inet:port-number 1348 | +-- protocol uint8 1349 | +-- connection? uint64 1350 | +-- connection-client? uint64 1351 | +-- embryonic? uint64 1352 | +-- embryonic-client? uint64 1353 | +-- connection-ps? uint64 1354 | +-- connection-client-ps? uint64 1355 | +-- request-ps? uint64 1356 | +-- request-client-ps? uint64 1357 | +-- partial-request-ps? uint64 1358 | +-- partial-request-client-ps? uint64 1359 +--:(telemetry) 1360 ... 1362 Figure 18: Telemetry Baseline Tree Structure 1364 6.3.1. Convey DOTS Client Domain Baseline Information 1366 Similar considerations to those specified in Section 6.1.2 are 1367 followed with one exception: 1369 The relative order of two PUT requests carrying DOTS client domain 1370 baseline attributes from a DOTS client is determined by comparing 1371 their respective 'tsid' values. If such two requests have 1372 overlapping targets, the PUT request with higher numeric 'tsid' 1373 value will override the request with a lower numeric 'tsid' value. 1374 The overlapped lower numeric 'tsid' MUST be automatically deleted 1375 and no longer be available. 1377 Two PUT requests from a DOTS client have overlapping targets if there 1378 is a common IP address, IP prefix, FQDN, URI, or alias-name. Also, 1379 two PUT requests from a DOTS client have overlapping targets if the 1380 addresses associated with the FQDN, URI, or alias are overlapping 1381 with each other or with 'target-prefix'. 1383 DOTS clients SHOULD minimize the number of active 'tsids' used for 1384 baseline information. Typically, in order to avoid maintaining a 1385 long list of 'tsids' for baseline information, it is RECOMMENDED that 1386 DOTS clients include in a request to update information related to a 1387 given target, the information of other targets (already communicated 1388 using a lower 'tsid' value) (assuming this fits within one single 1389 datagram). This update request will override these existing requests 1390 and hence optimize the number of 'tsid' request per DOTS client. 1392 If no target clause is included in the request, this is an indication 1393 that the baseline information applies for the DOTS client domain as a 1394 whole. 1396 An example of a PUT request to convey the baseline information is 1397 shown in Figure 19. 1399 Header: PUT (Code=0.03) 1400 Uri-Path: ".well-known" 1401 Uri-Path: "dots" 1402 Uri-Path: "tm-setup" 1403 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1404 Uri-Path: "tsid=126" 1405 Content-Format: "application/dots+cbor" 1407 { 1408 "ietf-dots-telemetry:telemetry-setup": { 1409 "telemetry": [ 1410 { 1411 "baseline": [ 1412 { 1413 "id": 1, 1414 "target-prefix": [ 1415 "2001:db8:6401::1/128", 1416 "2001:db8:6401::2/128" 1417 ], 1418 "total-traffic-normal": [ 1419 { 1420 "unit": "megabit-ps", 1421 "peak-g": "60" 1422 } 1423 ] 1424 } 1425 ] 1426 } 1427 ] 1428 } 1429 } 1431 Figure 19: PUT to Convey the DOTS Traffic Baseline 1433 The DOTS client may share protocol specific baseline information 1434 (e.g., TCP and UDP) as shown in Figure 19. 1436 Header: PUT (Code=0.03) 1437 Uri-Path: ".well-known" 1438 Uri-Path: "dots" 1439 Uri-Path: "tm-setup" 1440 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1441 Uri-Path: "tsid=128" 1442 Content-Format: "application/dots+cbor" 1444 { 1445 "ietf-dots-telemetry:telemetry-setup": { 1446 "telemetry": [ 1447 { 1448 "baseline": [ 1449 { 1450 "id": 1, 1451 "target-prefix": [ 1452 "2001:db8:6401::1/128", 1453 "2001:db8:6401::2/128" 1454 ], 1455 "total-traffic-normal-per-protocol": [ 1456 { 1457 "unit": "megabit-ps", 1458 "protocol": 6, 1459 "peak-g": "50" 1460 }, 1461 { 1462 "unit": "megabit-ps", 1463 "protocol": 17, 1464 "peak-g": "10" 1465 } 1466 ] 1467 } 1468 ] 1469 } 1470 ] 1471 } 1472 } 1474 Figure 20: PUT to Convey the DOTS Traffic Baseline (2) 1476 The normal traffic baseline information should be updated to reflect 1477 legitimate overloads (e.g., flash crowds) to prevent unnecessary 1478 mitigation. 1480 6.3.2. Retrieve Installed Normal Traffic Baseline 1482 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1483 specific installed DOTS client domain baseline traffic information. 1484 The same procedure as defined in Section 6.1.3 is followed. 1486 To retrieve all baseline information bound to a DOTS client, the DOTS 1487 client proceeds as specified in Section 6.1.1. 1489 6.3.3. Delete Installed Normal Traffic Baseline 1491 A DELETE request is used to delete the installed DOTS client domain 1492 normal traffic baseline. The same procedure as defined in 1493 Section 6.1.4 is followed. 1495 6.4. Reset Installed Telemetry Setup 1497 Upon bootstrapping (or reboot or any other event that may alter the 1498 DOTS client setup), a DOTS client MAY send a DELETE request to set 1499 the telemetry parameters to default values. Such a request does not 1500 include any 'tsid'. An example of such request is depicted in 1501 Figure 21. 1503 Header: DELETE (Code=0.04) 1504 Uri-Path: ".well-known" 1505 Uri-Path: "dots" 1506 Uri-Path: "tm-setup" 1507 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1509 Figure 21: Delete Telemetry Configuration 1511 6.5. Conflict with Other DOTS Clients of the Same Domain 1513 A DOTS server may detect conflicts between requests to convey pipe 1514 and baseline information received from DOTS clients of the same DOTS 1515 client domain. 'conflict-information' is used to report the conflict 1516 to the DOTS client following similar conflict handling discussed in 1517 Section 4.4.1 of [I-D.ietf-dots-rfc8782-bis]. The conflict cause can 1518 be set to one of these values: 1520 1: Overlapping targets (Section 4.4.1 of 1521 [I-D.ietf-dots-rfc8782-bis]). 1523 TBA: Overlapping pipe scope (see Section 12). 1525 7. DOTS Pre-or-Ongoing Mitigation Telemetry 1527 There are two broad types of DDoS attacks, one is bandwidth consuming 1528 attack, the other is target resource consuming attack. This section 1529 outlines the set of DOTS telemetry attributes (Section 7.1) that 1530 covers both the types of attacks. The objective of these attributes 1531 is to allow for the complete knowledge of attacks and the various 1532 particulars that can best characterize attacks. 1534 The "ietf-dots-telemetry" YANG module (Section 10.1) defines the data 1535 structure of a new message type called 'telemetry'. The tree 1536 structure of the 'telemetry' message type is shown in Figure 24. 1538 The pre-or-ongoing-mitigation telemetry attributes are indicated by 1539 the path suffix '/tm'. The '/tm' is appended to the path prefix to 1540 form the URI used with a CoAP request to signal the DOTS telemetry. 1541 Pre-or-ongoing-mitigation telemetry attributes specified in 1542 Section 7.1 can be signaled between DOTS agents. 1544 Pre-or-ongoing-mitigation telemetry attributes may be sent by a DOTS 1545 client or a DOTS server. 1547 DOTS agents SHOULD bind pre-or-ongoing-mitigation telemetry data with 1548 mitigation requests relying upon the target clause. In particular, a 1549 telemetry PUT request sent after a mitigation request may include a 1550 reference to that mitigation request ('mid-list') as shown in 1551 Figure 22. An example illustrating requests correlation by means of 1552 'target-prefix' is shown in Figure 23. 1554 When generating telemetry data to send to a peer, the DOTS agent MUST 1555 auto-scale so that appropriate unit(s) are used. 1557 +-----------+ +-----------+ 1558 |DOTS client| |DOTS server| 1559 +-----------+ +-----------+ 1560 | | 1561 |=========Mitigation Request (mid)=====================>| 1562 | | 1563 |================ Telemetry (mid-list{mid})============>| 1564 | | 1566 Figure 22: Example of Request Correlation using 'mid' 1568 +-----------+ +-----------+ 1569 |DOTS client| |DOTS server| 1570 +-----------+ +-----------+ 1571 | | 1572 |<=============== Telemetry (target-prefix)=============| 1573 | | 1574 |=========Mitigation Request (target-prefix)===========>| 1575 | | 1577 Figure 23: Example of Request Correlation using Target Prefix 1579 DOTS agents MUST NOT send pre-or-ongoing-mitigation telemetry 1580 notifications to the same peer more frequently than once every 1581 'telemetry-notify-interval' (Section 6.1). If a telemetry 1582 notification is sent using a block-like transfer mechanism (e.g., 1583 [I-D.ietf-core-new-block]), this rate limit policy MUST NOT consider 1584 these individual blocks as separate notifications, but as a single 1585 notification. 1587 DOTS pre-or-ongoing-mitigation telemetry request and response 1588 messages MUST be marked as Non-Confirmable messages (Section 2.1 of 1589 [RFC7252]). 1591 structure dots-telemetry: 1592 +-- (telemetry-message-type)? 1593 +--:(telemetry-setup) 1594 | ... 1595 | +-- telemetry* [] 1596 | +-- (direction)? 1597 | | +--:(server-to-client-only) 1598 | | +-- tsid? uint32 1599 | +-- (setup-type)? 1600 | +--:(telemetry-config) 1601 | | ... 1602 | +--:(pipe) 1603 | | ... 1604 | +--:(baseline) 1605 | ... 1606 +--:(telemetry) 1607 +-- pre-or-ongoing-mitigation* [] 1608 +-- (direction)? 1609 | +--:(server-to-client-only) 1610 | +-- tmid? uint32 1611 +-- target 1612 | ... 1613 +-- total-traffic* [unit] 1614 | ... 1615 +-- total-traffic-protocol* [unit protocol] 1616 | ... 1617 +-- total-traffic-port* [unit port] 1618 | ... 1619 +-- total-attack-traffic* [unit] 1620 | ... 1621 +-- total-attack-traffic-protocol* [unit protocol] 1622 | ... 1623 +-- total-attack-traffic-port* [unit port] 1624 | ... 1625 +-- total-attack-connection 1626 | ... 1627 +-- total-attack-connection-port 1628 | ... 1629 +-- attack-detail* [vendor-id attack-id] 1630 ... 1632 Figure 24: Telemetry Message Type Tree Structure 1634 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes 1636 The description and motivation behind each attribute are presented in 1637 Section 3. DOTS telemetry attributes are optionally signaled and 1638 therefore MUST NOT be treated as mandatory fields in the DOTS signal 1639 channel protocol. 1641 7.1.1. Target 1643 A target resource (Figure 25) is identified using the attributes 1644 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1645 fqdn', 'target-uri', 'alias-name', or a pointer to a mitigation 1646 request ('mid-list'). 1648 +--:(telemetry) 1649 +-- pre-or-ongoing-mitigation* [] 1650 +-- (direction)? 1651 | +--:(server-to-client-only) 1652 | +-- tmid? uint32 1653 +-- target 1654 | +-- target-prefix* inet:ip-prefix 1655 | +-- target-port-range* [lower-port] 1656 | | +-- lower-port inet:port-number 1657 | | +-- upper-port? inet:port-number 1658 | +-- target-protocol* uint8 1659 | +-- target-fqdn* inet:domain-name 1660 | +-- target-uri* inet:uri 1661 | +-- alias-name* string 1662 | +-- mid-list* uint32 1663 +-- total-traffic* [unit] 1664 | ... 1665 +-- total-traffic-protocol* [unit protocol] 1666 | ... 1667 +-- total-traffic-port* [unit port] 1668 | ... 1669 +-- total-attack-traffic* [unit] 1670 | ... 1671 +-- total-attack-traffic-protocol* [unit protocol] 1672 | ... 1673 +-- total-attack-traffic-port* [unit port] 1674 | ... 1675 +-- total-attack-connection 1676 | ... 1677 +-- total-attack-connection-port 1678 | ... 1679 +-- attack-detail* [vendor-id attack-id] 1680 ... 1682 Figure 25: Target Tree Structure 1684 At least one of the attributes 'target-prefix', 'target-fqdn', 1685 'target-uri', 'alias-name', or 'mid-list' MUST be present in the 1686 target definition. 1688 If the target is subjected to bandwidth consuming attack, the 1689 attributes representing the percentile values of the 'attack-id' 1690 attack traffic are included. 1692 If the target is subjected to resource consuming DDoS attacks, the 1693 same attributes defined for Section 7.1.4 are applicable for 1694 representing the attack. 1696 This is an optional subattribute. 1698 7.1.2. Total Traffic 1700 The 'total-traffic' attribute (Figure 26) conveys the percentile 1701 values of total traffic observed during a DDoS attack. More granular 1702 total traffic can be conveyed in 'total-traffic-protocol' and 'total- 1703 traffic-port'. 1705 The 'total-traffic-protocol' represents the total traffic for a 1706 target and is transport-protocol specific. 1708 The 'total-traffic-port' represents the total traffic for a target 1709 per port number. 1711 +--:(telemetry) 1712 +-- pre-or-ongoing-mitigation* [] 1713 +-- (direction)? 1714 | +--:(server-to-client-only) 1715 | +-- tmid? uint32 1716 +-- target 1717 | ... 1718 +-- total-traffic* [unit] 1719 | +-- unit unit 1720 | +-- low-percentile-g? yang:gauge64 1721 | +-- mid-percentile-g? yang:gauge64 1722 | +-- high-percentile-g? yang:gauge64 1723 | +-- peak-g? yang:gauge64 1724 +-- total-traffic-protocol* [unit protocol] 1725 | +-- protocol uint8 1726 | +-- unit unit 1727 | +-- low-percentile-g? yang:gauge64 1728 | +-- mid-percentile-g? yang:gauge64 1729 | +-- high-percentile-g? yang:gauge64 1730 | +-- peak-g? yang:gauge64 1731 +-- total-traffic-port* [unit port] 1732 | +-- port inet:port-number 1733 | +-- unit unit 1734 | +-- low-percentile-g? yang:gauge64 1735 | +-- mid-percentile-g? yang:gauge64 1736 | +-- high-percentile-g? yang:gauge64 1737 | +-- peak-g? yang:gauge64 1738 +-- total-attack-traffic* [unit] 1739 | ... 1740 +-- total-attack-traffic-protocol* [unit protocol] 1741 | ... 1742 +-- total-attack-traffic-port* [unit port] 1743 | ... 1744 +-- total-attack-connection 1745 | ... 1746 +-- total-attack-connection-port 1747 | ... 1748 +-- attack-detail* [vendor-id attack-id] 1749 ... 1751 Figure 26: Total Traffic Tree Structure 1753 7.1.3. Total Attack Traffic 1755 The 'total-attack-traffic' attribute (Figure 27) conveys the total 1756 attack traffic identified by the DOTS client domain's DDoS Mitigation 1757 System (or DDoS Detector). More granular total traffic can be 1758 conveyed in 'total-attack-traffic-protocol' and 'total-attack- 1759 traffic-port'. 1761 The 'total-attack-traffic-protocol' represents the total attack 1762 traffic for a target and is transport-protocol specific. 1764 The 'total-attack-traffic-port' represents the total attack traffic 1765 for a target per port number. 1767 +--:(telemetry) 1768 +-- pre-or-ongoing-mitigation* [] 1769 +-- (direction)? 1770 | +--:(server-to-client-only) 1771 | +-- tmid? uint32 1772 +-- target 1773 | ... 1774 +-- total-traffic* [unit] 1775 | ... 1776 +-- total-traffic-protocol* [unit protocol] 1777 | ... 1778 +-- total-traffic-port* [unit port] 1779 | ... 1780 +-- total-attack-traffic* [unit] 1781 | +-- protocol? uint8 1782 | +-- unit unit 1783 | +-- low-percentile-g? yang:gauge64 1784 | +-- mid-percentile-g? yang:gauge64 1785 | +-- high-percentile-g? yang:gauge64 1786 | +-- peak-g? yang:gauge64 1787 +-- total-attack-traffic-protocol* [unit protocol] 1788 | +-- protocol uint8 1789 | +-- unit unit 1790 | +-- low-percentile-g? yang:gauge64 1791 | +-- mid-percentile-g? yang:gauge64 1792 | +-- high-percentile-g? yang:gauge64 1793 | +-- peak-g? yang:gauge64 1794 +-- total-attack-traffic-port* [unit port] 1795 | +-- port inet:port-number 1796 | +-- unit unit 1797 | +-- low-percentile-g? yang:gauge64 1798 | +-- mid-percentile-g? yang:gauge64 1799 | +-- high-percentile-g? yang:gauge64 1800 | +-- peak-g? yang:gauge64 1801 +-- total-attack-connection 1802 | ... 1803 +-- total-attack-connection-port 1804 | ... 1805 +-- attack-detail* [vendor-id attack-id] 1806 ... 1808 Figure 27: Total Attack Traffic Tree Structure 1810 7.1.4. Total Attack Connections 1812 If the target is subjected to resource consuming DDoS attack, the 1813 'total-attack-connection' attribute is used to convey the percentile 1814 values of total attack connections. The following optional 1815 subattributes for the target per transport protocol are included to 1816 represent the attack characteristics: 1818 o The number of simultaneous attack connections to the target. 1819 o The number of simultaneous embryonic connections to the target. 1820 o The number of attack connections per second to the target. 1821 o The number of attack requests to the target. 1823 The total attack connections per port number is represented using 1824 'total-attack-connection-port' attribute. 1826 +--:(telemetry) 1827 +-- pre-or-ongoing-mitigation* [] 1828 +-- (direction)? 1829 | +--:(server-to-client-only) 1830 | +-- tmid? uint32 1831 +-- target 1832 | ... 1833 +-- total-traffic* [unit] 1834 | ... 1835 +-- total-traffic-protocol* [unit protocol] 1836 | ... 1837 +-- total-traffic-port* [unit port] 1838 | ... 1839 +-- total-attack-traffic* [unit] 1840 | ... 1841 +-- total-attack-traffic-protocol* [unit protocol] 1842 | ... 1843 +-- total-attack-traffic-port* [unit port] 1844 | ... 1845 +-- total-attack-connection 1846 | +-- low-percentile-l* [protocol] 1847 | | +-- protocol uint8 1848 | | +-- connection? yang:gauge64 1849 | | +-- embryonic? yang:gauge64 1850 | | +-- connection-ps? yang:gauge64 1851 | | +-- request-ps? yang:gauge64 1852 | | +-- partial-request-ps? yang:gauge64 1853 | +-- mid-percentile-l* [protocol] 1854 | | +-- protocol uint8 1855 | | +-- connection? yang:gauge64 1856 | | +-- embryonic? yang:gauge64 1857 | | +-- connection-ps? yang:gauge64 1858 | | +-- request-ps? yang:gauge64 1859 | | +-- partial-request-ps? yang:gauge64 1860 | +-- high-percentile-l* [protocol] 1861 | | +-- protocol uint8 1862 | | +-- connection? yang:gauge64 1863 | | +-- embryonic? yang:gauge64 1864 | | +-- connection-ps? yang:gauge64 1865 | | +-- request-ps? yang:gauge64 1866 | | +-- partial-request-ps? yang:gauge64 1867 | +-- peak-l* [protocol] 1868 | +-- protocol uint8 1869 | +-- connection? yang:gauge64 1870 | +-- embryonic? yang:gauge64 1871 | +-- connection-ps? yang:gauge64 1872 | +-- request-ps? yang:gauge64 1873 | +-- partial-request-ps? yang:gauge64 1874 +-- total-attack-connection-port 1875 | +-- low-percentile-l* [protocol port] 1876 | | +-- port inet:port-number 1877 | | +-- protocol uint8 1878 | | +-- connection? yang:gauge64 1879 | | +-- embryonic? yang:gauge64 1880 | | +-- connection-ps? yang:gauge64 1881 | | +-- request-ps? yang:gauge64 1882 | | +-- partial-request-ps? yang:gauge64 1883 | +-- mid-percentile-l* [protocol port] 1884 | | +-- port inet:port-number 1885 | | +-- protocol uint8 1886 | | +-- connection? yang:gauge64 1887 | | +-- embryonic? yang:gauge64 1888 | | +-- connection-ps? yang:gauge64 1889 | | +-- request-ps? yang:gauge64 1890 | | +-- partial-request-ps? yang:gauge64 1891 | +-- high-percentile-l* [protocol port] 1892 | | +-- port inet:port-number 1893 | | +-- protocol uint8 1894 | | +-- connection? yang:gauge64 1895 | | +-- embryonic? yang:gauge64 1896 | | +-- connection-ps? yang:gauge64 1897 | | +-- request-ps? yang:gauge64 1898 | | +-- partial-request-ps? yang:gauge64 1899 | +-- peak-l* [protocol port] 1900 | +-- port inet:port-number 1901 | +-- protocol uint8 1902 | +-- connection? yang:gauge64 1903 | +-- embryonic? yang:gauge64 1904 | +-- connection-ps? yang:gauge64 1905 | +-- request-ps? yang:gauge64 1906 | +-- partial-request-ps? yang:gauge64 1907 +-- attack-detail* [vendor-id attack-id] 1908 ... 1910 Figure 28: Total Attack Connections Tree Structure 1912 7.1.5. Attack Details 1914 This attribute (Figure 29) is used to signal a set of details 1915 characterizing an attack. The following subattributes describing the 1916 ongoing attack can be signal as attack details. 1918 vendor-id: Vendor ID is a security vendor's Enterprise Number as 1919 registered with IANA [Enterprise-Numbers]. It is a four-byte 1920 integer value. 1922 attack-id: Unique identifier assigned for the attack. 1924 attack-description: Textual representation of the attack 1925 description. Natural Language Processing techniques (e.g., word 1926 embedding) can possibly be used to map the attack description to 1927 an attack type. Textual representation of attack solves two 1928 problems: (a) avoids the need to create mapping tables manually 1929 between vendors and (b) avoids the need to standardize attack 1930 types which keep evolving. 1932 attack-severity: Attack severity level. This attribute takes one of 1933 the values defined in Section 3.12.2 of [RFC7970]. 1935 start-time: The time the attack started. The attack's start time is 1936 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1937 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1938 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1940 end-time: The time the attack ended. The attack end time is 1941 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1942 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1943 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1945 source-count: A count of sources involved in the attack targeting 1946 the victim. 1948 top-talkers: A list of top talkers among attack sources. The top 1949 talkers are represented using the 'source-prefix'. 1951 'spoofed-status' indicates whether a top talker is a spoofed IP 1952 address (e.g., reflection attacks) or not. 1954 If the target is subjected to a bandwidth consuming attack, the 1955 attack traffic from each of the top talkers is included ('total- 1956 attack-traffic', Section 7.1.3). 1958 If the target is subjected to a resource consuming DDoS attack, 1959 the same attributes defined in Section 7.1.4 are applicable for 1960 representing the attack per talker. 1962 +--:(telemetry) 1963 +-- pre-or-ongoing-mitigation* [] 1964 +-- (direction)? 1965 | +--:(server-to-client-only) 1966 | +-- tmid? uint32 1967 +-- target 1968 | ... 1969 +-- total-traffic* [unit] 1970 | ... 1971 +-- total-traffic-protocol* [unit protocol] 1972 | ... 1973 +-- total-traffic-port* [unit port] 1974 | ... 1975 +-- total-attack-traffic* [unit] 1976 | ... 1977 +-- total-attack-traffic-protocol* [unit protocol] 1978 | ... 1979 +-- total-attack-traffic-port* [unit port] 1980 | ... 1981 +-- total-attack-connection 1982 | ... 1983 +-- total-attack-connection-port 1984 | ... 1985 +-- attack-detail* [vendor-id attack-id] 1986 +-- vendor-id uint32 1987 +-- attack-id uint32 1988 +-- attack-description? string 1989 +-- attack-severity? attack-severity 1990 +-- start-time? uint64 1991 +-- end-time? uint64 1992 +-- source-count 1993 | +-- low-percentile-g? yang:gauge64 1994 | +-- mid-percentile-g? yang:gauge64 1995 | +-- high-percentile-g? yang:gauge64 1996 | +-- peak-g? yang:gauge64 1997 +-- top-talker 1998 +-- talker* [source-prefix] 1999 +-- spoofed-status? boolean 2000 +-- source-prefix inet:ip-prefix 2001 +-- source-port-range* [lower-port] 2002 | +-- lower-port inet:port-number 2003 | +-- upper-port? inet:port-number 2004 +-- source-icmp-type-range* [lower-type] 2005 | +-- lower-type uint8 2006 | +-- upper-type? uint8 2007 +-- total-attack-traffic* [unit] 2008 | +-- unit unit 2009 | +-- low-percentile-g? yang:gauge64 2010 | +-- mid-percentile-g? yang:gauge64 2011 | +-- high-percentile-g? yang:gauge64 2012 | +-- peak-g? yang:gauge64 2013 +-- total-attack-connection 2014 +-- low-percentile-l* [protocol] 2015 | +-- protocol uint8 2016 | +-- connection? yang:gauge64 2017 | +-- embryonic? yang:gauge64 2018 | +-- connection-ps? yang:gauge64 2019 | +-- request-ps? yang:gauge64 2020 | +-- partial-request-ps? yang:gauge64 2021 +-- mid-percentile-l* [protocol] 2022 | +-- protocol uint8 2023 | +-- connection? yang:gauge64 2024 | +-- embryonic? yang:gauge64 2025 | +-- connection-ps? yang:gauge64 2026 | +-- request-ps? yang:gauge64 2027 | +-- partial-request-ps? yang:gauge64 2028 +-- high-percentile-l* [protocol] 2029 | +-- protocol uint8 2030 | +-- connection? yang:gauge64 2031 | +-- embryonic? yang:gauge64 2032 | +-- connection-ps? yang:gauge64 2033 | +-- request-ps? yang:gauge64 2034 | +-- partial-request-ps? yang:gauge64 2035 +-- peak-l* [protocol] 2036 +-- protocol uint8 2037 +-- connection? yang:gauge64 2038 +-- embryonic? yang:gauge64 2039 +-- connection-ps? yang:gauge64 2040 +-- request-ps? yang:gauge64 2041 +-- partial-request-ps? yang:gauge64 2043 Figure 29: Attack Detail Tree Structure 2045 In order to optimize the size of telemetry data conveyed over the 2046 DOTS signal channel, DOTS agents MAY use the DOTS data channel 2047 [RFC8783] to exchange vendor specific attack mapping details (that 2048 is, {vendor identifier, attack identifier} ==> attack description). 2049 As such, DOTS agents do not have to convey systematically an attack 2050 description in their telemetry messages over the DOTS signal channel. 2052 Multiple mappings for different vendor identifiers may be used; the 2053 DOTS agent transmitting telemetry information can elect to use one or 2054 more vendor mappings even in the same telemetry message. 2056 Note: It is possible that a DOTS server is making use of multiple 2057 DOTS mitigators; each from a different vendor. How telemetry 2058 information and vendor mappings are exchanged between DOTS servers 2059 and DOTS mitigators is outside the scope of this document. 2061 DOTS clients and servers may be provided with mappings from different 2062 vendors and so have their own different sets of vendor attack 2063 mappings. A DOTS agent MUST accept receipt of telemetry data with a 2064 vendor identifier that is different to the one it uses to transmit 2065 telemetry data. Furthermore, it is possible that the DOTS client and 2066 DOTS server are provided by the same vendor, but the vendor mapping 2067 tables are at different revisions. The DOTS client SHOULD transmit 2068 telemetry information using the vendor mapping(s) that it provided to 2069 the DOTS server and the DOTS server SHOULD use the vendor mappings(s) 2070 provided to the DOTS client when transmitting telemetry data to peer 2071 DOTS agent. 2073 The "ietf-dots-mapping" YANG module defined in Section 10.2 augments 2074 the "ietf-dots-data-channel" [RFC8783]. The tree structure of the 2075 "ietf-dots-mapping" module is shown in Figure 30. 2077 module: ietf-dots-mapping 2078 augment /data-channel:dots-data/data-channel:dots-client: 2079 +--rw vendor-mapping {dots-telemetry}? 2080 +--rw vendor* [vendor-id] 2081 +--rw vendor-id uint32 2082 +--rw vendor-name? string 2083 +--rw last-updated uint64 2084 +--rw attack-mapping* [attack-id] 2085 +--rw attack-id uint32 2086 +--rw attack-description string 2087 augment /data-channel:dots-data/data-channel:capabilities: 2088 +--ro vendor-mapping-enabled? boolean {dots-telemetry}? 2089 augment /data-channel:dots-data: 2090 +--ro vendor-mapping {dots-telemetry}? 2091 +--ro vendor* [vendor-id] 2092 +--ro vendor-id uint32 2093 +--ro vendor-name? string 2094 +--ro last-updated uint64 2095 +--ro attack-mapping* [attack-id] 2096 +--ro attack-id uint32 2097 +--ro attack-description string 2099 Figure 30: Vendor Attack Mapping Tree Structure 2101 A DOTS client sends a GET request to retrieve the capabilities 2102 supported by a DOTS server as per Section 7.1 of [RFC8783]. This 2103 request is meant to assess whether vendor attack mapping details 2104 feature is supported by the server (i.e., check the value of 'vendor- 2105 mapping-enabled'). 2107 If 'vendor-mapping-enabled' is set to 'true', A DOTS client MAY send 2108 a GET request to retrieve the DOTS server's vendor attack mapping 2109 details. An example of such GET request is shown in Figure 31. 2111 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2112 /ietf-dots-mapping:vendor-mapping HTTP/1.1 2113 Host: example.com 2114 Accept: application/yang-data+json 2116 Figure 31: GET to Retrieve the Vendor Attack Mappings of a DOTS 2117 Server 2119 A DOTS client MAY retrieve only the list of vendors supported by the 2120 DOTS server. It does so by setting the "depth" parameter 2121 (Section 4.8.2 of [RFC8040]) to "3" in the GET request as shown in 2122 Figure 32. An example of a response body received from the DOTS 2123 server as a response to such request is illustrated in Figure 33. 2125 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2126 /ietf-dots-mapping:vendor-mapping?depth=3 HTTP/1.1 2127 Host: example.com 2128 Accept: application/yang-data+json 2130 Figure 32: GET to Retrieve the Vendors List used by a DOTS Server 2132 { 2133 "ietf-dots-mapping:vendor-mapping": { 2134 "vendor": [ 2135 { 2136 "vendor-id": 1234, 2137 "vendor-name": "mitigator-s", 2138 "last-updated": "1576856561", 2139 "attack-mapping": [] 2140 } 2141 ] 2142 } 2143 } 2145 Figure 33: Response to a GET to Retrieve the Vendors List used by a 2146 DOTS Server 2148 The DOTS client reiterates the above procedure regularly (e.g., once 2149 a week) to update the DOTS server's vendor attack mapping details. 2151 If the DOTS client concludes that the DOTS server does not have any 2152 reference to the specific vendor attack mapping details, the DOTS 2153 client uses a POST request to install its vendor attack mapping 2154 details. An example of such POST request is depicted in Figure 34. 2156 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2157 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2158 Host: example.com 2159 Content-Type: application/yang-data+json 2161 { 2162 "ietf-dots-mapping:vendor-mapping": { 2163 "vendor": [ 2164 { 2165 "vendor-id": 345, 2166 "vendor-name": "mitigator-c", 2167 "last-updated": "1576812345", 2168 "attack-mapping": [ 2169 { 2170 "attack-id": 1, 2171 "attack-description": 2172 "Include a description of this attack" 2173 }, 2174 { 2175 "attack-id": 2, 2176 "attack-description": 2177 "Again, include a description of the attack" 2178 } 2179 ] 2180 } 2181 ] 2182 } 2183 } 2185 Figure 34: POST to Install Vendor Attack Mapping Details 2187 The DOTS server indicates the result of processing the POST request 2188 using the status-line. Concretely, "201 Created" status-line MUST be 2189 returned in the response if the DOTS server has accepted the vendor 2190 attack mapping details. If the request is missing a mandatory 2191 attribute or contains an invalid or unknown parameter, "400 Bad 2192 Request" status-line MUST be returned by the DOTS server in the 2193 response. The error-tag is set to "missing-attribute", "invalid- 2194 value", or "unknown-element" as a function of the encountered error. 2196 If the request is received via a server-domain DOTS gateway, but the 2197 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2198 is expected to be supplied, the DOTS server MUST reply with "403 2199 Forbidden" status-line and the error-tag "access-denied". Upon 2200 receipt of this message, the DOTS client MUST register (Section 5.1 2201 of [RFC8783]). 2203 The DOTS client uses the PUT request to modify its vendor attack 2204 mapping details maintained by the DOTS server (e.g., add a new 2205 mapping). 2207 A DOTS client uses a GET request to retrieve its vendor attack 2208 mapping details as maintained by the DOTS server (Figure 35). 2210 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2211 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2212 /ietf-dots-mapping:vendor-mapping?\ 2213 content=all HTTP/1.1 2214 Host: example.com 2215 Accept: application/yang-data+json 2217 Figure 35: GET to Retrieve Installed Vendor Attack Mapping Details 2219 When conveying attack details in DOTS telemetry messages (Sections 2220 7.2, 7.3, and 8), DOTS agents MUST NOT include 'attack-description' 2221 attribute except if the corresponding attack mapping details were not 2222 shared with the peer DOTS agent. 2224 7.2. From DOTS Clients to DOTS Servers 2226 DOTS clients uses PUT request to signal pre-or-ongoing-mitigation 2227 telemetry to DOTS servers. An example of such request is shown in 2228 Figure 36. 2230 Header: PUT (Code=0.03) 2231 Uri-Path: ".well-known" 2232 Uri-Path: "dots" 2233 Uri-Path: "tm" 2234 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2235 Uri-Path: "tmid=123" 2236 Content-Format: "application/dots+cbor" 2238 { 2239 "ietf-dots-telemetry:telemetry": { 2240 "pre-or-ongoing-mitigation": [ 2241 { 2242 "target": { 2243 "target-prefix": [ 2244 "2001:db8::1/128" 2245 ] 2246 }, 2247 "total-attack-traffic-protocol": [ 2248 { 2249 "protocol": 17, 2250 "unit": "megabit-ps", 2251 "mid-percentile-g": "900" 2252 } 2253 ], 2254 "attack-detail": [ 2255 { 2256 "vendor-id": 1234, 2257 "attack-id": 77, 2258 "start-time": "1957811234", 2259 "attack-severity": "high" 2260 } 2261 ] 2262 } 2263 ] 2264 } 2265 } 2267 Figure 36: PUT to Send Pre-or-Ongoing-Mitigation Telemetry 2269 'cuid' is a mandatory Uri-Path parameter for PUT requests. 2271 The following additional Uri-Path parameter is defined: 2273 tmid: Telemetry Identifier is an identifier for the DOTS pre-or- 2274 ongoing-mitigation telemetry data represented as an integer. 2275 This identifier MUST be generated by DOTS clients. 'tmid' values 2276 MUST increase monotonically (when a new PUT is generated by a 2277 DOTS client to convey pre-or-ongoing-mitigation telemetry). 2279 The procedure specified in Section 4.4.1 of 2280 [I-D.ietf-dots-rfc8782-bis] MUST be followed for 'tmid' 2281 rollover. 2283 This is a mandatory attribute. 'tmid' MUST follow 'cuid'. 2285 'cuid' and 'tmid' MUST NOT appear in the PUT request message body. 2287 At least 'target' attribute and another pre-or-ongoing-mitigation 2288 attributes (Section 7.1) MUST be present in the PUT request. If only 2289 the 'target' attribute is present, this request is handled as per 2290 Section 7.3. 2292 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2293 mitigation telemetry from a DOTS client is determined by comparing 2294 their respective 'tmid' values. If such two requests have 2295 overlapping 'target', the PUT request with higher numeric 'tmid' 2296 value will override the request with a lower numeric 'tmid' value. 2297 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2298 no longer be available. 2300 The DOTS server indicates the result of processing a PUT request 2301 using CoAP Response Codes. In particular, the 2.04 (Changed) 2302 Response Code is returned if the DOTS server has accepted the pre-or- 2303 ongoing-mitigation telemetry. The 5.03 (Service Unavailable) 2304 Response Code is returned if the DOTS server has erred. 5.03 uses 2305 Max-Age Option to indicate the number of seconds after which to 2306 retry. 2308 How long a DOTS server maintains a 'tmid' as active or logs the 2309 enclosed telemetry information is implementation specific. Note that 2310 if a 'tmid' is still active, then logging details are updated by the 2311 DOTS server as a function of the updates received from the peer DOTS 2312 client. 2314 A DOTS client that lost the state of its active 'tmids' or has to set 2315 'tmid' back to zero (e.g., crash or restart) MUST send a GET request 2316 to the DOTS server to retrieve the list of active 'tmid'. The DOTS 2317 client may then delete 'tmids' that should not be active anymore 2318 (Figure 37). Sending a DELETE with no 'tmid' indicates that all 2319 'tmids' must be deactivated (Figure 38). 2321 Header: DELETE (Code=0.04) 2322 Uri-Path: ".well-known" 2323 Uri-Path: "dots" 2324 Uri-Path: "tm" 2325 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2326 Uri-Path: "tmid=123" 2328 Figure 37: Delete a Pre-or-Ongoing-Mitigation Telemetry 2330 Header: DELETE (Code=0.04) 2331 Uri-Path: ".well-known" 2332 Uri-Path: "dots" 2333 Uri-Path: "tm" 2334 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2336 Figure 38: Delete All Pre-or-Ongoing-Mitigation Telemetry 2338 7.3. From DOTS Servers to DOTS Clients 2340 The pre-or-ongoing-mitigation (attack details, in particular) can 2341 also be signaled from DOTS servers to DOTS clients. For example, the 2342 DOTS server co-located with a DDoS detector collects monitoring 2343 information from the target network, identifies DDoS attack using 2344 statistical analysis or deep learning techniques, and signals the 2345 attack details to the DOTS client. 2347 The DOTS client can use the attack details to decide whether to 2348 trigger a DOTS mitigation request or not. Furthermore, the security 2349 operation personnel at the DOTS client domain can use the attack 2350 details to determine the protection strategy and select the 2351 appropriate DOTS server for mitigating the attack. 2353 In order to receive pre-or-ongoing-mitigation telemetry notifications 2354 from a DOTS server, a DOTS client MUST send a PUT (followed by a GET) 2355 with the target filter. An example of such PUT request is shown in 2356 Figure 39. In order to avoid maintaining a long list of such 2357 requests, it is RECOMMENDED that DOTS clients include all targets in 2358 the same request. DOTS servers may be instructed to restrict the 2359 number of pre-or-ongoing-mitigation requests per DOTS client domain. 2360 This request MUST be maintained active by the DOTS server until a 2361 delete request is received from the same DOTS client to clear this 2362 pre-or-ongoing-mitigation telemetry. 2364 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2365 mitigation telemetry from a DOTS client is determined by comparing 2366 their respective 'tmid' values. If such two requests have 2367 overlapping 'target', the PUT request with higher numeric 'tmid' 2368 value will override the request with a lower numeric 'tmid' value. 2370 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2371 no longer be available. 2373 Header: PUT (Code=0.03) 2374 Uri-Path: ".well-known" 2375 Uri-Path: "dots" 2376 Uri-Path: "tm" 2377 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2378 Uri-Path: "tmid=567" 2379 Content-Format: "application/dots+cbor" 2381 { 2382 "ietf-dots-telemetry:telemetry": { 2383 "pre-or-ongoing-mitigation": [ 2384 { 2385 "target": { 2386 "target-prefix": [ 2387 "2001:db8::/32" 2388 ] 2389 } 2390 } 2391 ] 2392 } 2393 } 2395 Figure 39: PUT to Request Pre-or-Ongoing-Mitigation Telemetry 2397 DOTS clients of the same domain can request to receive pre-or- 2398 ongoing-mitigation telemetry bound to the same target. 2400 The DOTS client conveys the Observe Option set to '0' in the GET 2401 request to receive asynchronous notifications carrying pre-or- 2402 ongoing-mitigation telemetry data from the DOTS server. The GET 2403 request specifies a 'tmid' (Figure 40) or not (Figure 41). 2405 Header: GET (Code=0.01) 2406 Uri-Path: ".well-known" 2407 Uri-Path: "dots" 2408 Uri-Path: "tm" 2409 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2410 Uri-Path: "tmid=567" 2411 Observe: 0 2413 Figure 40: GET to Subscribe to Telemetry Asynchronous Notifications 2414 for a Specific 'tmid' 2416 Header: GET (Code=0.01) 2417 Uri-Path: ".well-known" 2418 Uri-Path: "dots" 2419 Uri-Path: "tm" 2420 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2421 Observe: 0 2423 Figure 41: GET to Subscribe to Telemetry Asynchronous Notifications 2424 for All 'tmids' 2426 The DOTS client can filter out the asynchronous notifications from 2427 the DOTS server by indicating one or more Uri-Query options in its 2428 GET request. A Uri-Query option can include the following 2429 parameters: 'target-prefix', 'target-port', 'target-protocol', 2430 'target-fqdn', 'target-uri', 'alias-name', 'mid', and 'c' (content) 2431 (Section 4.2.4). Furthermore: 2433 If more than one Uri-Query option is included in a request, these 2434 options are interpreted in the same way as when multiple target 2435 clauses are included in a message body. 2437 If multiple values of a query parameter are to be included in a 2438 request, these values MUST be included in the same Uri-Query 2439 option and separated by a "," character without any spaces. 2441 Range values (i.e., contiguous inclusive block) can be included 2442 for 'target-port', 'target-protocol', and 'mid' parameters by 2443 indicating two bound values separated by a "-" character. 2445 Wildcard names (i.e., a name with the leftmost label is the "*" 2446 character) can be included in 'target-fqdn' or 'target-uri' 2447 parameters. DOTS clients MUST NOT include a name in which the "*" 2448 character is included in a label other than the leftmost label. 2449 "*.example.com" is an example of a valid wildcard name that can be 2450 included as a value of the 'target-fqdn' parameter in an Uri-Query 2451 option. 2453 DOTS clients may also filter out the asynchronous notifications from 2454 the DOTS server by indicating a specific source information. To that 2455 aim, a DOTS client may include 'source-prefix', 'source-port', or 2456 'source-icmp-type' in a Uri-Query option. The same considerations 2457 (ranges, multiple values) specified for target clauses apply for 2458 source clauses. Special care SHOULD be taken when using these 2459 filters as some attacks may be hidden to the requesting DOTS client 2460 (e.g., the attack changes its source information). 2462 Requests with invalid query types (e.g., not supported, malformed) by 2463 the DOTS server MUST be rejected by DOTS servers with a 4.00 (Bad 2464 Request). 2466 An example of request to subscribe to asynchronous UDP telemetry 2467 notifications is shown in Figure 42. This filter will be applied for 2468 all 'tmids'. 2470 Header: GET (Code=0.01) 2471 Uri-Path: ".well-known" 2472 Uri-Path: "dots" 2473 Uri-Path: "tm" 2474 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2475 Uri-Query: "target-protocol=17" 2476 Observe: 0 2478 Figure 42: GET Request to Receive Telemetry Asynchronous 2479 Notifications Filtered using Uri-Query 2481 The DOTS server will send asynchronous notifications to the DOTS 2482 client when an attack event is detected following similar 2483 considerations as in Section 4.4.2.1 of [I-D.ietf-dots-rfc8782-bis]. 2484 An example of a pre-or-ongoing-mitigation telemetry notification is 2485 shown in Figure 43. 2487 { 2488 "ietf-dots-telemetry:telemetry": { 2489 "pre-or-ongoing-mitigation": [ 2490 { 2491 "tmid": 567, 2492 "target": { 2493 "target-prefix": [ 2494 "2001:db8::1/128" 2495 ] 2496 }, 2497 "target-protocol": [ 2498 17 2499 ], 2500 "total-attack-traffic": [ 2501 { 2502 "unit": "megabit-ps", 2503 "mid-percentile-g": "900" 2504 } 2505 ], 2506 "attack-detail": [ 2507 { 2508 "vendor-id": 1234, 2509 "attack-id": 77, 2510 "start-time": "1957818434", 2511 "attack-severity": "high" 2512 } 2513 ] 2514 } 2515 ] 2516 } 2517 } 2519 Figure 43: Message Body of a Pre-or-Ongoing-Mitigation Telemetry 2520 Notification from the DOTS Server 2522 A DOTS server sends the aggregate data for a target using 'total- 2523 attack-traffic' attribute. The aggregate assumes that Uri-Query 2524 filters are applied on the target. The DOTS server MAY include more 2525 granular data when needed (that is, 'total-attack-traffic-protocol' 2526 and 'total-attack-traffic-port'). If a port filter (or protocol 2527 filter) is included in a request, 'total-attack-traffic-protocol' (or 2528 'total-attack-traffic-port') conveys the data with the port (or 2529 protocol) filter applied. 2531 A DOTS server may aggregate pre-or-ongoing-mitigation data (e.g., 2532 'top-talkers') for all targets of a domain, or when justified, send 2533 specific information (e.g., 'top-talkers') per individual targets. 2535 The DOTS client may log pre-or-ongoing-mitigation telemetry data with 2536 an alert sent to an administrator or a network controller. The DOTS 2537 client may send a mitigation request if the attack cannot be handled 2538 locally. 2540 A DOTS client that is not interested to receive pre-or-ongoing- 2541 mitigation telemetry data for a target MUST send a delete request 2542 similar to the one depicted in Figure 37. 2544 8. DOTS Telemetry Mitigation Status Update 2546 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 2547 Attributes 2549 The mitigation efficacy telemetry attributes can be signaled from 2550 DOTS clients to DOTS servers as part of the periodic mitigation 2551 efficacy updates to the server (Section 4.4.3 of 2552 [I-D.ietf-dots-rfc8782-bis]). 2554 Total Attack Traffic: The overall attack traffic as observed from 2555 the DOTS client perspective during an active mitigation. See 2556 Figure 27. 2558 Attack Details: The overall attack details as observed from the 2559 DOTS client perspective during an active mitigation. See 2560 Section 7.1.5. 2562 The "ietf-dots-telemetry" YANG module (Section 10.1) augments the 2563 'mitigation-scope' message type defined in "ietf-dots-signal" 2564 [I-D.ietf-dots-rfc8782-bis] so that these attributes can be signalled 2565 by a DOTS client in a mitigation efficacy update (Figure 44). 2567 augment-structure /dots-signal:dots-signal/dots-signal:message-type 2568 /dots-signal:mitigation-scope/dots-signal:scope: 2569 +-- total-attack-traffic* [unit] 2570 | +-- unit unit 2571 | +-- low-percentile-g? yang:gauge64 2572 | +-- mid-percentile-g? yang:gauge64 2573 | +-- high-percentile-g? yang:gauge64 2574 | +-- peak-g? yang:gauge64 2575 +-- attack-detail* [vendor-id attack-id] 2576 +-- vendor-id uint32 2577 +-- attack-id uint32 2578 +-- attack-description? string 2579 +-- attack-severity? attack-severity 2580 +-- start-time? uint64 2581 +-- end-time? uint64 2582 +-- source-count 2583 | +-- low-percentile-g? yang:gauge64 2584 | +-- mid-percentile-g? yang:gauge64 2585 | +-- high-percentile-g? yang:gauge64 2586 | +-- peak-g? yang:gauge64 2587 +-- top-talker 2588 +-- talker* [source-prefix] 2589 +-- spoofed-status? boolean 2590 +-- source-prefix inet:ip-prefix 2591 +-- source-port-range* [lower-port] 2592 | +-- lower-port inet:port-number 2593 | +-- upper-port? inet:port-number 2594 +-- source-icmp-type-range* [lower-type] 2595 | +-- lower-type uint8 2596 | +-- upper-type? uint8 2597 +-- total-attack-traffic* [unit] 2598 | +-- unit unit 2599 | +-- low-percentile-g? yang:gauge64 2600 | +-- mid-percentile-g? yang:gauge64 2601 | +-- high-percentile-g? yang:gauge64 2602 | +-- peak-g? yang:gauge64 2603 +-- total-attack-connection 2604 +-- low-percentile-c 2605 | +-- connection? yang:gauge64 2606 | +-- embryonic? yang:gauge64 2607 | +-- connection-ps? yang:gauge64 2608 | +-- request-ps? yang:gauge64 2609 | +-- partial-request-ps? yang:gauge64 2610 +-- mid-percentile-c 2611 | ... 2612 +-- high-percentile-c 2613 | ... 2614 +-- peak-c 2615 ... 2617 Figure 44: Telemetry Efficacy Update Tree Structure 2619 In order to signal telemetry data in a mitigation efficacy update, it 2620 is RECOMMENDED that the DOTS client has already established a DOTS 2621 telemetry setup session with the server in 'idle' time. 2623 An example of an efficacy update with telemetry attributes is 2624 depicted in Figure 45. 2626 Header: PUT (Code=0.03) 2627 Uri-Path: ".well-known" 2628 Uri-Path: "dots" 2629 Uri-Path: "mitigate" 2630 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2631 Uri-Path: "mid=123" 2632 If-Match: 2633 Content-Format: "application/dots+cbor" 2635 { 2636 "ietf-dots-signal-channel:mitigation-scope": { 2637 "scope": [ 2638 { 2639 "alias-name": [ 2640 "https1", 2641 "https2" 2642 ], 2643 "attack-status": "under-attack", 2644 "ietf-dots-telemetry:total-attack-traffic": [ 2645 { 2646 "unit": "megabit-ps", 2647 "mid-percentile-g": "900" 2648 } 2649 ] 2650 } 2651 ] 2652 } 2653 } 2655 Figure 45: An Example of Mitigation Efficacy Update with Telemetry 2656 Attributes 2658 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 2659 Attributes 2661 The mitigation status telemetry attributes can be signaled from the 2662 DOTS server to the DOTS client as part of the periodic mitigation 2663 status update (Section 4.4.2.2 of [I-D.ietf-dots-rfc8782-bis]). In 2664 particular, DOTS clients can receive asynchronous notifications of 2665 the attack details from DOTS servers using the Observe option defined 2666 in [RFC7641]. 2668 In order to make use of this feature, DOTS clients MUST establish a 2669 telemetry setup session with the DOTS server in 'idle' time and MUST 2670 set the 'server-originated-telemetry' attribute to 'true'. 2672 DOTS servers MUST NOT include telemetry attributes in mitigation 2673 status updates sent to DOTS clients for which 'server-originated- 2674 telemetry' attribute is set to 'false'. 2676 As defined in [RFC8612], the actual mitigation activities can include 2677 several countermeasure mechanisms. The DOTS server signals the 2678 current operational status of relevant countermeasures. A list of 2679 attacks detected by each countermeasure MAY also be included. The 2680 same attributes defined in Section 7.1.5 are applicable for 2681 describing the attacks detected and mitigated at the DOTS server 2682 domain. 2684 The "ietf-dots-telemetry" YANG module (Section 10.1) augments the 2685 'mitigation-scope' message type defined in "ietf-dots-signal" 2686 [I-D.ietf-dots-rfc8782-bis] with telemetry data as depicted in the 2687 following tree structure: 2689 augment-structure /dots-signal:dots-signal/dots-signal:message-type 2690 /dots-signal:mitigation-scope/dots-signal:scope: 2691 +-- (direction)? 2692 | +--:(server-to-client-only) 2693 | +-- total-traffic* [unit] 2694 | | +-- unit unit 2695 | | +-- low-percentile-g? yang:gauge64 2696 | | +-- mid-percentile-g? yang:gauge64 2697 | | +-- high-percentile-g? yang:gauge64 2698 | | +-- peak-g? yang:gauge64 2699 | +-- total-attack-connection 2700 | +-- low-percentile-c 2701 | | +-- connection? yang:gauge64 2702 | | +-- embryonic? yang:gauge64 2703 | | +-- connection-ps? yang:gauge64 2704 | | +-- request-ps? yang:gauge64 2705 | | +-- partial-request-ps? yang:gauge64 2706 | +-- mid-percentile-c 2707 | | ... 2708 | +-- high-percentile-c 2709 | | ... 2710 | +-- peak-c 2711 | ... 2712 +-- total-attack-traffic* [unit] 2713 | +-- unit unit 2714 | +-- low-percentile-g? yang:gauge64 2715 | +-- mid-percentile-g? yang:gauge64 2716 | +-- high-percentile-g? yang:gauge64 2717 | +-- peak-g? yang:gauge64 2718 +-- attack-detail* [vendor-id attack-id] 2719 +-- vendor-id uint32 2720 +-- attack-id uint32 2721 +-- attack-description? string 2722 +-- attack-severity? attack-severity 2723 +-- start-time? uint64 2724 +-- end-time? uint64 2725 +-- source-count 2726 | +-- low-percentile-g? yang:gauge64 2727 | +-- mid-percentile-g? yang:gauge64 2728 | +-- high-percentile-g? yang:gauge64 2729 | +-- peak-g? yang:gauge64 2730 +-- top-talker 2731 +-- talker* [source-prefix] 2732 +-- spoofed-status? boolean 2733 +-- source-prefix inet:ip-prefix 2734 +-- source-port-range* [lower-port] 2735 | +-- lower-port inet:port-number 2736 | +-- upper-port? inet:port-number 2737 +-- source-icmp-type-range* [lower-type] 2738 | +-- lower-type uint8 2739 | +-- upper-type? uint8 2740 +-- total-attack-traffic* [unit] 2741 | +-- unit unit 2742 | +-- low-percentile-g? yang:gauge64 2743 | +-- mid-percentile-g? yang:gauge64 2744 | +-- high-percentile-g? yang:gauge64 2745 | +-- peak-g? yang:gauge64 2746 +-- total-attack-connection 2747 +-- low-percentile-c 2748 | +-- connection? yang:gauge64 2749 | +-- embryonic? yang:gauge64 2750 | +-- connection-ps? yang:gauge64 2751 | +-- request-ps? yang:gauge64 2752 | +-- partial-request-ps? yang:gauge64 2753 +-- mid-percentile-c 2754 | ... 2755 +-- high-percentile-c 2756 | ... 2757 +-- peak-c 2758 ... 2760 Figure 46 shows an example of an asynchronous notification of attack 2761 mitigation status from the DOTS server. This notification signals 2762 both the mid-percentile value of processed attack traffic and the 2763 peak percentile value of unique sources involved in the attack. 2765 { 2766 "ietf-dots-signal-channel:mitigation-scope": { 2767 "scope": [ 2768 { 2769 "mid": 12332, 2770 "mitigation-start": "1507818434", 2771 "alias-name": [ 2772 "https1", 2773 "https2" 2774 ], 2775 "lifetime": 1600, 2776 "status": "attack-successfully-mitigated", 2777 "bytes-dropped": "134334555", 2778 "bps-dropped": "43344", 2779 "pkts-dropped": "333334444", 2780 "pps-dropped": "432432", 2781 "ietf-dots-telemetry:total-attack-traffic": [ 2782 { 2783 "unit": "megabit-ps", 2784 "mid-percentile-g": "900" 2785 } 2786 ], 2787 "ietf-dots-telemetry:attack-detail": [ 2788 { 2789 "vendor-id": 1234, 2790 "attack-id": 77, 2791 "source-count": { 2792 "peak-g": "10000" 2793 } 2794 } 2795 ] 2796 } 2797 ] 2798 } 2799 } 2801 Figure 46: Response Body of a Mitigation Status With Telemetry 2802 Attributes 2804 DOTS clients can filter out the asynchronous notifications from the 2805 DOTS server by indicating one or more Uri-Query options in its GET 2806 request. A Uri-Query option can include the following parameters: 2807 'target-prefix', 'target-port', 'target-protocol', 'target-fqdn', 2808 'target-uri', 'alias-name', and 'c' (content) (Section 4.2.4). The 2809 considerations discussed in Section 7.3 MUST be followed to include 2810 multiple query values, ranges ('target-port', 'target-protocol'), and 2811 wildcard name ('target-fqdn', 'target-uri'). 2813 An example of request to subscribe to asynchronous notifications 2814 bound to the "http1" alias is shown in Figure 47. 2816 Header: GET (Code=0.01) 2817 Uri-Path: ".well-known" 2818 Uri-Path: "dots" 2819 Uri-Path: "mitigate" 2820 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2821 Uri-Path: "mid=12332" 2822 Uri-Query: "target-alias=https1" 2823 Observe: 0 2825 Figure 47: GET Request to Receive Asynchronous Notifications Filtered 2826 using Uri-Query 2828 If the target query does not match the target of the enclosed 'mid' 2829 as maintained by the DOTS server, the latter MUST respond with a 4.04 2830 (Not Found) error Response Code. The DOTS server MUST NOT add a new 2831 observe entry if this query overlaps with an existing one. 2833 9. Error Handling 2835 A list of common CoAP errors that are implemented by DOTS servers are 2836 provided in Section 9 of [I-D.ietf-dots-rfc8782-bis]. The following 2837 additional error cases apply for the telemetry extension: 2839 o 4.00 (Bad Request) is returned by the DOTS server when the DOTS 2840 client has sent a request that violates the DOTS telemetry 2841 extension. 2843 o 4.04 (Not Found) is returned by the DOTS server when the DOTS 2844 client is requesting a 'tsid' or 'tmid' that is not valid. 2846 o 4.00 (Bad Request) is returned by the DOTS server when the DOTS 2847 client has sent a request with invalid query types (e.g., not 2848 supported, malformed). 2850 o 4.04 (Not Found) is returned by the DOTS server when the DOTS 2851 client has sent a request with a target query that does not match 2852 the target of the enclosed 'mid' as maintained by the DOTS server. 2854 10. YANG Modules 2856 10.1. DOTS Signal Channel Telemetry YANG Module 2858 This module uses types defined in [RFC6991] and [RFC8345]. 2860 file "ietf-dots-telemetry@2020-10-08.yang" 2861 module ietf-dots-telemetry { 2862 yang-version 1.1; 2863 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 2864 prefix dots-telemetry; 2866 import ietf-dots-signal-channel { 2867 prefix dots-signal; 2868 reference 2869 "RFC UUUU: Distributed Denial-of-Service Open Threat Signaling 2870 (DOTS) Signal Channel Specification"; 2871 } 2872 import ietf-dots-data-channel { 2873 prefix data-channel; 2874 reference 2875 "RFC 8783: Distributed Denial-of-Service Open Threat 2876 Signaling (DOTS) Data Channel Specification"; 2877 } 2878 import ietf-yang-types { 2879 prefix yang; 2880 reference 2881 "Section 3 of RFC 6991"; 2882 } 2883 import ietf-inet-types { 2884 prefix inet; 2885 reference 2886 "Section 4 of RFC 6991"; 2887 } 2888 import ietf-network-topology { 2889 prefix nt; 2890 reference 2891 "Section 6.2 of RFC 8345: A YANG Data Model for Network 2892 Topologies"; 2893 } 2894 import ietf-yang-structure-ext { 2895 prefix sx; 2896 reference 2897 "RFC 8791: YANG Data Structure Extensions"; 2898 } 2900 organization 2901 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2902 contact 2903 "WG Web: 2904 WG List: 2906 Author: Mohamed Boucadair 2907 2909 Author: Konda, Tirumaleswar Reddy 2910 "; 2911 description 2912 "This module contains YANG definitions for the signaling 2913 of DOTS telemetry exchanged between a DOTS client and 2914 a DOTS server by means of the DOTS signal channel. 2916 Copyright (c) 2020 IETF Trust and the persons identified as 2917 authors of the code. All rights reserved. 2919 Redistribution and use in source and binary forms, with or 2920 without modification, is permitted pursuant to, and subject 2921 to the license terms contained in, the Simplified BSD License 2922 set forth in Section 4.c of the IETF Trust's Legal Provisions 2923 Relating to IETF Documents 2924 (http://trustee.ietf.org/license-info). 2926 This version of this YANG module is part of RFC XXXX; see 2927 the RFC itself for full legal notices."; 2929 revision 2020-10-08 { 2930 description 2931 "Initial revision."; 2932 reference 2933 "RFC XXXX: Distributed Denial-of-Service Open Threat 2934 Signaling (DOTS) Telemetry"; 2935 } 2937 typedef attack-severity { 2938 type enumeration { 2939 enum none { 2940 value 1; 2941 description 2942 "No effect on the DOTS client domain."; 2943 } 2944 enum low { 2945 value 2; 2946 description 2947 "Minimal effect on the DOTS client domain."; 2948 } 2949 enum medium { 2950 value 3; 2951 description 2952 "A subset of DOTS client domain resources are 2953 out of service."; 2954 } 2955 enum high { 2956 value 4; 2957 description 2958 "The DOTS client domain is under extremly severe 2959 conditions."; 2960 } 2961 enum unknown { 2962 value 5; 2963 description 2964 "The impact of the attack is not known."; 2965 } 2966 } 2967 description 2968 "Enumeration for attack severity."; 2969 reference 2970 "RFC 7970: The Incident Object Description Exchange 2971 Format Version 2"; 2972 } 2974 typedef unit-type { 2975 type enumeration { 2976 enum packet-ps { 2977 value 1; 2978 description 2979 "Packets per second (pps)."; 2980 } 2981 enum bit-ps { 2982 value 2; 2983 description 2984 "Bits per Second (bit/s)."; 2985 } 2986 enum byte-ps { 2987 value 3; 2988 description 2989 "Bytes per second (Byte/s)."; 2990 } 2991 } 2992 description 2993 "Enumeration to indicate which unit type is used."; 2994 } 2996 typedef unit { 2997 type enumeration { 2998 enum packet-ps { 2999 value 1; 3000 description 3001 "Packets per second (pps)."; 3002 } 3003 enum bit-ps { 3004 value 2; 3005 description 3006 "Bits per Second (bps)."; 3007 } 3008 enum byte-ps { 3009 value 3; 3010 description 3011 "Bytes per second (Bps)."; 3012 } 3013 enum kilopacket-ps { 3014 value 4; 3015 description 3016 "Kilo packets per second (kpps)."; 3017 } 3018 enum kilobit-ps { 3019 value 5; 3020 description 3021 "Kilobits per second (kbps)."; 3022 } 3023 enum kilobyte-ps { 3024 value 6; 3025 description 3026 "Kilobytes per second (kBps)."; 3027 } 3028 enum megapacket-ps { 3029 value 7; 3030 description 3031 "Mega packets per second (Mpps)."; 3032 } 3033 enum megabit-ps { 3034 value 8; 3035 description 3036 "Megabits per second (Mbps)."; 3037 } 3038 enum megabyte-ps { 3039 value 9; 3040 description 3041 "Megabytes per second (MBps)."; 3042 } 3043 enum gigapacket-ps { 3044 value 10; 3045 description 3046 "Giga packets per second (Gpps)."; 3047 } 3048 enum gigabit-ps { 3049 value 11; 3050 description 3051 "Gigabits per second (Gbps)."; 3052 } 3053 enum gigabyte-ps { 3054 value 12; 3055 description 3056 "Gigabytes per second (GBps)."; 3057 } 3058 enum terapacket-ps { 3059 value 13; 3060 description 3061 "Tera packets per second (Tpps)."; 3062 } 3063 enum terabit-ps { 3064 value 14; 3065 description 3066 "Terabits per second (Tbps)."; 3067 } 3068 enum terabyte-ps { 3069 value 15; 3070 description 3071 "Terabytes per second (TBps)."; 3072 } 3073 } 3074 description 3075 "Enumeration to indicate which unit is used."; 3076 } 3078 typedef interval { 3079 type enumeration { 3080 enum hour { 3081 value 1; 3082 description 3083 "Hour."; 3084 } 3085 enum day { 3086 value 2; 3087 description 3088 "Day."; 3089 } 3090 enum week { 3091 value 3; 3092 description 3093 "Week."; 3094 } 3095 enum month { 3096 value 4; 3097 description 3098 "Month."; 3099 } 3100 } 3101 description 3102 "Enumeration to indicate the overall measurement period."; 3103 } 3105 typedef sample { 3106 type enumeration { 3107 enum second { 3108 value 1; 3109 description 3110 " A one second measurement period."; 3111 } 3112 enum 5-seconds { 3113 value 2; 3114 description 3115 "5 seconds measurement period."; 3116 } 3117 enum 30-seconds { 3118 value 3; 3119 description 3120 "30 seconds measurement period."; 3121 } 3122 enum minute { 3123 value 4; 3124 description 3125 "One minute measurement period."; 3126 } 3127 enum 5-minutes { 3128 value 5; 3129 description 3130 "5 minutes measurement period."; 3131 } 3132 enum 10-minutes { 3133 value 6; 3134 description 3135 "10 minutes measurement period."; 3136 } 3137 enum 30-minutes { 3138 value 7; 3139 description 3140 "30 minutes measurement period."; 3141 } 3142 enum hour { 3143 value 8; 3144 description 3145 "One hour measurement period."; 3146 } 3147 } 3148 description 3149 "Enumeration to indicate the measurement period."; 3150 } 3152 typedef percentile { 3153 type decimal64 { 3154 fraction-digits 2; 3155 } 3156 description 3157 "The nth percentile of a set of data is the 3158 value at which n percent of the data is below it."; 3159 } 3161 typedef query-type { 3162 type enumeration { 3163 enum target-prefix { 3164 value 1; 3165 description 3166 "Query based on target prefix."; 3167 } 3168 enum target-port { 3169 value 2; 3170 description 3171 "Query based on target port number."; 3172 } 3173 enum target-protocol { 3174 value 3; 3175 description 3176 "Query based on target protocol."; 3177 } 3178 enum target-fqdn { 3179 value 4; 3180 description 3181 "Query based on target FQDN."; 3182 } 3183 enum target-uri { 3184 value 5; 3185 description 3186 "Query based on target URI."; 3187 } 3188 enum target-alias { 3189 value 6; 3190 description 3191 "Query based on target alias."; 3192 } 3193 enum mid { 3194 value 7; 3195 description 3196 "Query based on mitigation identifier (mid)."; 3198 } 3199 enum source-prefix { 3200 value 8; 3201 description 3202 "Query based on source prefix."; 3203 } 3204 enum source-port { 3205 value 9; 3206 description 3207 "Query based on source port number."; 3208 } 3209 enum source-icmp-type { 3210 value 10; 3211 description 3212 "Query based on ICMP type"; 3213 } 3214 enum content { 3215 value 11; 3216 description 3217 "Query based on 'c' Uri-Query option that is used 3218 to control the selection of configuration 3219 and non-configuration data nodes."; 3220 reference 3221 "Section 4.4.2 of RFC 8782."; 3222 } 3223 } 3224 description 3225 "Enumeration support for query types that can be used 3226 in a GET request to filter out data."; 3227 } 3229 grouping percentile-config { 3230 description 3231 "Configuration of low, mid, and high percentile values."; 3232 leaf measurement-interval { 3233 type interval; 3234 description 3235 "Defines the period on which percentiles are computed."; 3236 } 3237 leaf measurement-sample { 3238 type sample; 3239 description 3240 "Defines the time distribution for measuring 3241 values that are used to compute percentiles."; 3242 } 3243 leaf low-percentile { 3244 type percentile; 3245 default "10.00"; 3246 description 3247 "Low percentile. If set to '0', this means low-percentiles 3248 are disabled."; 3249 } 3250 leaf mid-percentile { 3251 type percentile; 3252 must '. >= ../low-percentile' { 3253 error-message 3254 "The mid-percentile must be greater than 3255 or equal to the low-percentile."; 3256 } 3257 default "50.00"; 3258 description 3259 "Mid percentile. If set to the same value as low-percentiles, 3260 this means mid-percentiles are disabled."; 3261 } 3262 leaf high-percentile { 3263 type percentile; 3264 must '. >= ../mid-percentile' { 3265 error-message 3266 "The high-percentile must be greater than 3267 or equal to the mid-percentile."; 3268 } 3269 default "90.00"; 3270 description 3271 "High percentile. If set to the same value as mid-percentiles, 3272 this means high-percentiles are disabled."; 3273 } 3274 } 3276 grouping percentile { 3277 description 3278 "Generic grouping for percentile."; 3279 leaf low-percentile-g { 3280 type yang:gauge64; 3281 description 3282 "Low percentile value."; 3283 } 3284 leaf mid-percentile-g { 3285 type yang:gauge64; 3286 description 3287 "Mid percentile value."; 3288 } 3289 leaf high-percentile-g { 3290 type yang:gauge64; 3291 description 3292 "High percentile value."; 3293 } 3294 leaf peak-g { 3295 type yang:gauge64; 3296 description 3297 "Peak value."; 3298 } 3299 } 3301 grouping unit-config { 3302 description 3303 "Generic grouping for unit configuration."; 3304 list unit-config { 3305 key "unit"; 3306 description 3307 "Controls which unit types are allowed when sharing 3308 telemetry data."; 3309 leaf unit { 3310 type unit-type; 3311 description 3312 "Can be packet-ps, bit-ps, or byte-ps."; 3313 } 3314 leaf unit-status { 3315 type boolean; 3316 mandatory true; 3317 description 3318 "Enable/disable the use of the measurement unit type."; 3319 } 3320 } 3321 } 3323 grouping traffic-unit { 3324 description 3325 "Grouping of traffic as a function of the measurement unit."; 3326 leaf unit { 3327 type unit; 3328 description 3329 "The traffic can be measured using unit types: packet-ps, 3330 bit-ps, or byte-ps. DOTS agents auto-scale to the appropriate 3331 units (e.g., megabit-ps, kilobit-ps)."; 3332 } 3333 uses percentile; 3334 } 3336 grouping traffic-unit-protocol { 3337 description 3338 "Grouping of traffic of a given transport protocol as 3339 a function of the measurement unit."; 3340 leaf protocol { 3341 type uint8; 3342 description 3343 "The transport protocol. 3344 Values are taken from the IANA Protocol Numbers registry: 3345 . 3347 For example, this parameter contains 6 for TCP, 3348 17 for UDP, 33 for DCCP, or 132 for SCTP."; 3349 } 3350 uses traffic-unit; 3351 } 3353 grouping traffic-unit-port { 3354 description 3355 "Grouping of traffic bound to a port number as 3356 a function of the measurement unit."; 3357 leaf port { 3358 type inet:port-number; 3359 description 3360 "Port number."; 3361 } 3362 uses traffic-unit; 3363 } 3365 grouping total-connection-capacity { 3366 description 3367 "Total Connections Capacity. These data nodes are 3368 useful to detect resource consuming DDoS attacks"; 3369 leaf connection { 3370 type uint64; 3371 description 3372 "The maximum number of simultaneous connections that 3373 are allowed to the target server."; 3374 } 3375 leaf connection-client { 3376 type uint64; 3377 description 3378 "The maximum number of simultaneous connections that 3379 are allowed to the target server per client."; 3380 } 3381 leaf embryonic { 3382 type uint64; 3383 description 3384 "The maximum number of simultaneous embryonic connections 3385 that are allowed to the target server. The term 'embryonic 3386 connection' refers to a connection whose connection handshake 3387 is not finished. Embryonic connection is only possible in 3388 connection-oriented transport protocols like TCP or SCTP."; 3389 } 3390 leaf embryonic-client { 3391 type uint64; 3392 description 3393 "The maximum number of simultaneous embryonic connections 3394 that are allowed to the target server per client."; 3395 } 3396 leaf connection-ps { 3397 type uint64; 3398 description 3399 "The maximum number of connections allowed per second 3400 to the target server."; 3401 } 3402 leaf connection-client-ps { 3403 type uint64; 3404 description 3405 "The maximum number of connections allowed per second 3406 to the target server per client."; 3407 } 3408 leaf request-ps { 3409 type uint64; 3410 description 3411 "The maximum number of requests allowed per second 3412 to the target server."; 3413 } 3414 leaf request-client-ps { 3415 type uint64; 3416 description 3417 "The maximum number of requests allowed per second 3418 to the target server per client."; 3419 } 3420 leaf partial-request-ps { 3421 type uint64; 3422 description 3423 "The maximum number of partial requests allowed per 3424 second to the target server."; 3425 } 3426 leaf partial-request-client-ps { 3427 type uint64; 3428 description 3429 "The maximum number of partial requests allowed per 3430 second to the target server per client."; 3431 } 3432 } 3434 grouping total-connection-capacity-protocol { 3435 description 3436 "Total Connections Capacity per protocol. These data nodes are 3437 useful to detect resource consuming DDoS attacks."; 3439 leaf protocol { 3440 type uint8; 3441 description 3442 "The transport protocol. 3443 Values are taken from the IANA Protocol Numbers registry: 3444 ."; 3445 } 3446 uses total-connection-capacity; 3447 } 3449 grouping connection { 3450 description 3451 "A set of data nodes which represent the attack 3452 characteristics"; 3453 leaf connection { 3454 type yang:gauge64; 3455 description 3456 "The number of simultaneous attack connections to 3457 the target server."; 3458 } 3459 leaf embryonic { 3460 type yang:gauge64; 3461 description 3462 "The number of simultaneous embryonic connections to 3463 the target server."; 3464 } 3465 leaf connection-ps { 3466 type yang:gauge64; 3467 description 3468 "The number of attack connections per second to 3469 the target server."; 3470 } 3471 leaf request-ps { 3472 type yang:gauge64; 3473 description 3474 "The number of attack requests per second to 3475 the target server."; 3476 } 3477 leaf partial-request-ps { 3478 type yang:gauge64; 3479 description 3480 "The number of attack partial requests to 3481 the target server."; 3482 } 3483 } 3485 grouping connection-percentile { 3486 description 3487 "Total attack connections."; 3488 container low-percentile-c { 3489 description 3490 "Low percentile of attack connections."; 3491 uses connection; 3492 } 3493 container mid-percentile-c { 3494 description 3495 "Mid percentile of attack connections."; 3496 uses connection; 3497 } 3498 container high-percentile-c { 3499 description 3500 "High percentile of attack connections."; 3501 uses connection; 3502 } 3503 container peak-c { 3504 description 3505 "Peak attack connections."; 3506 uses connection; 3507 } 3508 } 3510 grouping connection-protocol { 3511 description 3512 "Total attack connections."; 3513 leaf protocol { 3514 type uint8; 3515 description 3516 "The transport protocol. 3517 Values are taken from the IANA Protocol Numbers registry: 3518 ."; 3519 } 3520 uses connection; 3521 } 3523 grouping connection-port { 3524 description 3525 "Total attack connections per port number."; 3526 leaf port { 3527 type inet:port-number; 3528 description 3529 "Port number."; 3530 } 3531 uses connection-protocol; 3532 } 3534 grouping connection-protocol-percentile { 3535 description 3536 "Total attack connections per protocol."; 3537 list low-percentile-l { 3538 key "protocol"; 3539 description 3540 "Low percentile of attack connections per protocol."; 3541 uses connection-protocol; 3542 } 3543 list mid-percentile-l { 3544 key "protocol"; 3545 description 3546 "Mid percentile of attack connections per protocol."; 3547 uses connection-protocol; 3548 } 3549 list high-percentile-l { 3550 key "protocol"; 3551 description 3552 "High percentile of attack connections per protocol."; 3553 uses connection-protocol; 3554 } 3555 list peak-l { 3556 key "protocol"; 3557 description 3558 "Peak attack connections per protocol."; 3559 uses connection-protocol; 3560 } 3561 } 3563 grouping connection-protocol-port-percentile { 3564 description 3565 "Total attack connections per port number."; 3566 list low-percentile-l { 3567 key "protocol port"; 3568 description 3569 "Low percentile of attack connections per port number."; 3570 uses connection-port; 3571 } 3572 list mid-percentile-l { 3573 key "protocol port"; 3574 description 3575 "Mid percentile of attack connections per port number."; 3576 uses connection-port; 3577 } 3578 list high-percentile-l { 3579 key "protocol port"; 3580 description 3581 "High percentile of attack connections per port number."; 3582 uses connection-port; 3584 } 3585 list peak-l { 3586 key "protocol port"; 3587 description 3588 "Peak attack connections per port number."; 3589 uses connection-port; 3590 } 3591 } 3593 grouping attack-detail { 3594 description 3595 "Various details that describe the on-going 3596 attacks that need to be mitigated by the DOTS server. 3597 The attack details need to cover well-known and common attacks 3598 (such as a SYN Flood) along with new emerging or vendor-specific 3599 attacks."; 3600 leaf vendor-id { 3601 type uint32; 3602 description 3603 "Vendor ID is a security vendor's Enterprise Number."; 3604 } 3605 leaf attack-id { 3606 type uint32; 3607 description 3608 "Unique identifier assigned by the vendor for the attack."; 3609 } 3610 leaf attack-description { 3611 type string; 3612 description 3613 "Textual representation of attack description. Natural Language 3614 Processing techniques (e.g., word embedding) can possibly be 3615 used to map the attack description to an attack type."; 3616 } 3617 leaf attack-severity { 3618 type attack-severity; 3619 description 3620 "Severity level of an attack. How this level is determined 3621 is implementation-specific."; 3622 } 3623 leaf start-time { 3624 type uint64; 3625 description 3626 "The time the attack started. Start time is represented in 3627 seconds relative to 1970-01-01T00:00:00Z in UTC time."; 3628 } 3629 leaf end-time { 3630 type uint64; 3631 description 3632 "The time the attack ended. End time is represented in seconds 3633 relative to 1970-01-01T00:00:00Z in UTC time."; 3634 } 3635 container source-count { 3636 description 3637 "Indicates the count of unique sources involved 3638 in the attack."; 3639 uses percentile; 3640 } 3641 } 3643 grouping top-talker-aggregate { 3644 description 3645 "Top attack sources."; 3646 list talker { 3647 key "source-prefix"; 3648 description 3649 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3650 leaf spoofed-status { 3651 type boolean; 3652 description 3653 "Indicates whether this address is spoofed."; 3654 } 3655 leaf source-prefix { 3656 type inet:ip-prefix; 3657 description 3658 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3659 } 3660 list source-port-range { 3661 key "lower-port"; 3662 description 3663 "Port range. When only lower-port is 3664 present, it represents a single port number."; 3665 leaf lower-port { 3666 type inet:port-number; 3667 mandatory true; 3668 description 3669 "Lower port number of the port range."; 3670 } 3671 leaf upper-port { 3672 type inet:port-number; 3673 must '. >= ../lower-port' { 3674 error-message 3675 "The upper port number must be greater than 3676 or equal to lower port number."; 3677 } 3678 description 3679 "Upper port number of the port range."; 3681 } 3682 } 3683 list source-icmp-type-range { 3684 key "lower-type"; 3685 description 3686 "ICMP type range. When only lower-type is 3687 present, it represents a single ICMP type."; 3688 leaf lower-type { 3689 type uint8; 3690 mandatory true; 3691 description 3692 "Lower ICMP type of the ICMP type range."; 3693 } 3694 leaf upper-type { 3695 type uint8; 3696 must '. >= ../lower-type' { 3697 error-message 3698 "The upper ICMP type must be greater than 3699 or equal to lower ICMP type."; 3700 } 3701 description 3702 "Upper type of the ICMP type range."; 3703 } 3704 } 3705 list total-attack-traffic { 3706 key "unit"; 3707 description 3708 "Total attack traffic issued from this source."; 3709 uses traffic-unit; 3710 } 3711 container total-attack-connection { 3712 description 3713 "Total attack connections issued from this source."; 3714 uses connection-percentile; 3715 } 3716 } 3717 } 3719 grouping top-talker { 3720 description 3721 "Top attack sources."; 3722 list talker { 3723 key "source-prefix"; 3724 description 3725 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3726 leaf spoofed-status { 3727 type boolean; 3728 description 3729 "Indicates whether this address is spoofed."; 3730 } 3731 leaf source-prefix { 3732 type inet:ip-prefix; 3733 description 3734 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3735 } 3736 list source-port-range { 3737 key "lower-port"; 3738 description 3739 "Port range. When only lower-port is 3740 present, it represents a single port number."; 3741 leaf lower-port { 3742 type inet:port-number; 3743 mandatory true; 3744 description 3745 "Lower port number of the port range."; 3746 } 3747 leaf upper-port { 3748 type inet:port-number; 3749 must '. >= ../lower-port' { 3750 error-message 3751 "The upper port number must be greater than 3752 or equal to lower port number."; 3753 } 3754 description 3755 "Upper port number of the port range."; 3756 } 3757 } 3758 list source-icmp-type-range { 3759 key "lower-type"; 3760 description 3761 "ICMP type range. When only lower-type is 3762 present, it represents a single ICMP type."; 3763 leaf lower-type { 3764 type uint8; 3765 mandatory true; 3766 description 3767 "Lower ICMP type of the ICMP type range."; 3768 } 3769 leaf upper-type { 3770 type uint8; 3771 must '. >= ../lower-type' { 3772 error-message 3773 "The upper ICMP type must be greater than 3774 or equal to lower ICMP type."; 3775 } 3776 description 3777 "Upper type of the ICMP type range."; 3778 } 3779 } 3780 list total-attack-traffic { 3781 key "unit"; 3782 description 3783 "Total attack traffic issued from this source."; 3784 uses traffic-unit; 3785 } 3786 container total-attack-connection { 3787 description 3788 "Total attack connections issued from this source."; 3789 uses connection-protocol-percentile; 3790 } 3791 } 3792 } 3794 grouping baseline { 3795 description 3796 "Grouping for the telemetry baseline."; 3797 uses data-channel:target; 3798 leaf-list alias-name { 3799 type string; 3800 description 3801 "An alias name that points to a resource."; 3802 } 3803 list total-traffic-normal { 3804 key "unit"; 3805 description 3806 "Total traffic normal baselines."; 3807 uses traffic-unit; 3808 } 3809 list total-traffic-normal-per-protocol { 3810 key "unit protocol"; 3811 description 3812 "Total traffic normal baselines per protocol."; 3813 uses traffic-unit-protocol; 3814 } 3815 list total-traffic-normal-per-port { 3816 key "unit port"; 3817 description 3818 "Total traffic normal baselines per port number."; 3819 uses traffic-unit-port; 3820 } 3821 list total-connection-capacity { 3822 key "protocol"; 3823 description 3824 "Total connection capacity."; 3826 uses total-connection-capacity-protocol; 3827 } 3828 list total-connection-capacity-per-port { 3829 key "protocol port"; 3830 description 3831 "Total connection capacity per port number."; 3832 leaf port { 3833 type inet:port-number; 3834 description 3835 "The target port number."; 3836 } 3837 uses total-connection-capacity-protocol; 3838 } 3839 } 3841 grouping pre-or-ongoing-mitigation { 3842 description 3843 "Grouping for the telemetry data."; 3844 list total-traffic { 3845 key "unit"; 3846 description 3847 "Total traffic."; 3848 uses traffic-unit; 3849 } 3850 list total-traffic-protocol { 3851 key "unit protocol"; 3852 description 3853 "Total traffic per protocol."; 3854 uses traffic-unit-protocol; 3855 } 3856 list total-traffic-port { 3857 key "unit port"; 3858 description 3859 "Total traffic per port."; 3860 uses traffic-unit-port; 3861 } 3862 list total-attack-traffic { 3863 key "unit"; 3864 description 3865 "Total attack traffic."; 3866 uses traffic-unit-protocol; 3867 } 3868 list total-attack-traffic-protocol { 3869 key "unit protocol"; 3870 description 3871 "Total attack traffic per protocol."; 3872 uses traffic-unit-protocol; 3873 } 3874 list total-attack-traffic-port { 3875 key "unit port"; 3876 description 3877 "Total attack traffic per port."; 3878 uses traffic-unit-port; 3879 } 3880 container total-attack-connection { 3881 description 3882 "Total attack connections."; 3883 uses connection-protocol-percentile; 3884 } 3885 container total-attack-connection-port { 3886 description 3887 "Total attack connections."; 3888 uses connection-protocol-port-percentile; 3889 } 3890 list attack-detail { 3891 key "vendor-id attack-id"; 3892 description 3893 "Provides a set of attack details."; 3894 uses attack-detail; 3895 container top-talker { 3896 description 3897 "Lists the top attack sources."; 3898 uses top-talker; 3899 } 3900 } 3901 } 3903 sx:augment-structure "/dots-signal:dots-signal" 3904 + "/dots-signal:message-type" 3905 + "/dots-signal:mitigation-scope" 3906 + "/dots-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; 3923 } 3924 container total-attack-connection { 3925 description 3926 "Total attack connections."; 3927 uses connection-percentile; 3928 } 3929 } 3930 } 3931 list total-attack-traffic { 3932 key "unit"; 3933 description 3934 "Total attack traffic."; 3935 uses traffic-unit; 3936 } 3937 list attack-detail { 3938 key "vendor-id attack-id"; 3939 description 3940 "Attack details"; 3941 uses attack-detail; 3942 container top-talker { 3943 description 3944 "Top attack sources."; 3945 uses top-talker-aggregate; 3946 } 3947 } 3948 } 3949 sx:structure dots-telemetry { 3950 description 3951 "Main structure for DOTS telemetry messages."; 3952 choice telemetry-message-type { 3953 description 3954 "Can be a telemetry-setup or telemetry data."; 3955 case telemetry-setup { 3956 description 3957 "Indicates the message is about telemetry."; 3958 choice direction { 3959 description 3960 "Indicates the communication direction in which the 3961 data nodes can be included."; 3962 case server-to-client-only { 3963 description 3964 "These data nodes appear only in a mitigation message 3965 sent from the server to the client."; 3966 container max-config-values { 3967 description 3968 "Maximum acceptable configuration values."; 3969 uses percentile-config; 3970 leaf server-originated-telemetry { 3971 type boolean; 3972 description 3973 "Indicates whether the DOTS server can be instructed 3974 to send pre-or-ongoing-mitigation telemetry. If set 3975 to FALSE or the data node is not present, this is 3976 an indication that the server does not support this 3977 capability."; 3978 } 3979 leaf telemetry-notify-interval { 3980 type uint32 { 3981 range "1 .. 3600"; 3982 } 3983 units "seconds"; 3984 must ". >= ../../min-config-values" 3985 + "/telemetry-notify-interval" { 3986 error-message 3987 "The value must be greater than or equal 3988 to the telemetry-notify-interval in the 3989 min-config-values"; 3990 } 3991 description 3992 "Minimum number of seconds between successive 3993 telemetry notifications."; 3994 } 3995 } 3996 container min-config-values { 3997 description 3998 "Minimum acceptable configuration values."; 3999 uses percentile-config; 4000 leaf telemetry-notify-interval { 4001 type uint32 { 4002 range "1 .. 3600"; 4003 } 4004 units "seconds"; 4005 description 4006 "Minimum number of seconds between successive 4007 telemetry notifications."; 4008 } 4009 } 4010 container supported-units { 4011 description 4012 "Supported units and default activation status."; 4013 uses unit-config; 4014 } 4015 leaf-list query-type { 4016 type query-type; 4017 description 4018 "Indicates which query types are supported by 4019 the server."; 4020 } 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."; 4069 } 4070 } 4071 } 4072 case pipe { 4073 description 4074 "Total pipe capacity of a DOTS client domain"; 4075 list total-pipe-capacity { 4076 key "link-id unit"; 4077 description 4078 "Total pipe capacity of a DOTS client domain."; 4079 leaf link-id { 4080 type nt:link-id; 4081 description 4082 "Identifier of an interconnection link."; 4083 } 4084 leaf capacity { 4085 type uint64; 4086 mandatory true; 4087 description 4088 "Pipe capacity."; 4089 } 4090 leaf unit { 4091 type unit; 4092 description 4093 "The traffic can be measured using unit types: 4094 packets per second (PPS), Bits per Second (BPS), 4095 and/or bytes per second. DOTS agents auto-scale 4096 to the appropriate units (e.g., megabit-ps, 4097 kilobit-ps)."; 4098 } 4099 } 4100 } 4101 case baseline { 4102 description 4103 "Traffic baseline information"; 4104 list baseline { 4105 key "id"; 4106 description 4107 "Traffic baseline information"; 4108 leaf id { 4109 type uint32; 4110 must '. >= 1'; 4111 description 4112 "A baseline entry identifier."; 4113 } 4114 uses baseline; 4116 } 4117 } 4118 } 4119 } 4120 } 4121 case telemetry { 4122 description 4123 "Indicates the message is about telemetry."; 4124 list pre-or-ongoing-mitigation { 4125 description 4126 "Pre-or-ongoing-mitigation telemetry per DOTS client."; 4127 choice direction { 4128 description 4129 "Indicates the communication direction in which the 4130 data nodes can be included."; 4131 case server-to-client-only { 4132 description 4133 "These data nodes appear only in a mitigation message 4134 sent from the server to the client."; 4135 leaf tmid { 4136 type uint32; 4137 description 4138 "An identifier to uniquely demux telemetry data sent 4139 using the same message."; 4140 } 4141 } 4142 } 4143 container target { 4144 description 4145 "Indicates the target."; 4146 uses data-channel:target; 4147 leaf-list alias-name { 4148 type string; 4149 description 4150 "An alias name that points to a resource."; 4151 } 4152 leaf-list mid-list { 4153 type uint32; 4154 description 4155 "Reference a list of associated mitigation requests."; 4156 } 4157 } 4158 uses pre-or-ongoing-mitigation; 4159 } 4160 } 4161 } 4162 } 4163 } 4164 4166 10.2. Vendor Attack Mapping Details YANG Module 4168 file "ietf-dots-mapping@2020-06-26.yang" 4169 module ietf-dots-mapping { 4170 yang-version 1.1; 4171 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-mapping"; 4172 prefix dots-mapping; 4174 import ietf-dots-data-channel { 4175 prefix data-channel; 4176 reference 4177 "RFC 8783: Distributed Denial-of-Service Open Threat 4178 Signaling (DOTS) Data Channel Specification"; 4179 } 4181 organization 4182 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 4183 contact 4184 "WG Web: 4185 WG List: 4187 Author: Mohamed Boucadair 4188 4190 Author: Jon Shallow 4191 "; 4192 description 4193 "This module contains YANG definitions for the sharing 4194 DDoS attack mapping details between a DOTS client and 4195 a DOTS server, by means of the DOTS data channel. 4197 Copyright (c) 2020 IETF Trust and the persons identified as 4198 authors of the code. All rights reserved. 4200 Redistribution and use in source and binary forms, with or 4201 without modification, is permitted pursuant to, and subject 4202 to the license terms contained in, the Simplified BSD License 4203 set forth in Section 4.c of the IETF Trust's Legal Provisions 4204 Relating to IETF Documents 4205 (http://trustee.ietf.org/license-info). 4207 This version of this YANG module is part of RFC XXXX; see 4208 the RFC itself for full legal notices."; 4210 revision 2020-06-26 { 4211 description 4212 "Initial revision."; 4213 reference 4214 "RFC XXXX: Distributed Denial-of-Service Open Threat 4215 Signaling (DOTS) Telemetry"; 4216 } 4218 feature dots-telemetry { 4219 description 4220 "This feature indicates that DOTS telemetry data can be 4221 shared between DOTS clients and servers."; 4222 } 4224 grouping attack-mapping { 4225 description 4226 "A set of information used for sharing vendor attack mapping 4227 information with a peer."; 4228 list vendor { 4229 key "vendor-id"; 4230 description 4231 "Vendor attack mapping information of the client/server"; 4232 leaf vendor-id { 4233 type uint32; 4234 description 4235 "Vendor ID is a security vendor's Enterprise Number."; 4236 } 4237 leaf vendor-name { 4238 type string; 4239 description 4240 "The name of the vendor (e.g., company A)."; 4241 } 4242 leaf last-updated { 4243 type uint64; 4244 mandatory true; 4245 description 4246 "The time the mapping table was updated. It is represented 4247 in seconds relative to 1970-01-01T00:00:00Z in UTC time."; 4248 } 4249 list attack-mapping { 4250 key "attack-id"; 4251 description 4252 "Attack mapping details."; 4253 leaf attack-id { 4254 type uint32; 4255 description 4256 "Unique identifier assigned by the vendor for the attack."; 4257 } 4258 leaf attack-description { 4259 type string; 4260 mandatory true; 4261 description 4262 "Textual representation of attack description. Natural 4263 Language Processing techniques (e.g., word embedding) 4264 can possibly be used to map the attack description to 4265 an attack type."; 4266 } 4267 } 4268 } 4269 } 4271 augment "/data-channel:dots-data/data-channel:dots-client" { 4272 if-feature "dots-telemetry"; 4273 description 4274 "Augments the data channel with a vendor attack 4275 mapping table of the DOTS client."; 4276 container vendor-mapping { 4277 description 4278 "Used by DOTS clients to share their vendor 4279 attack mapping information with DOTS servers."; 4280 uses attack-mapping; 4281 } 4282 } 4284 augment "/data-channel:dots-data/data-channel:capabilities" { 4285 if-feature "dots-telemetry"; 4286 description 4287 "Augments the DOTS server capabilities with a 4288 parameter to indicate whether they can share 4289 attack mapping details."; 4290 leaf vendor-mapping-enabled { 4291 type boolean; 4292 config false; 4293 description 4294 "Indicates that the server supports sharing 4295 attack vendor mapping details with DOTS clients."; 4296 } 4297 } 4299 augment "/data-channel:dots-data" { 4300 if-feature "dots-telemetry"; 4301 description 4302 "Augments the data channel with a vendor attack 4303 mapping table of the DOTS server."; 4304 container vendor-mapping { 4305 config false; 4306 description 4307 "Includes the list of vendor attack mapping details 4308 that will be shared upon request with DOTS clients."; 4309 uses attack-mapping; 4310 } 4311 } 4312 } 4313 4315 11. YANG/JSON Mapping Parameters to CBOR 4317 All DOTS telemetry parameters in the payload of the DOTS signal 4318 channel MUST be mapped to CBOR types as shown in the following table: 4320 o Implementers may use the values in: https://github.com/boucadair/ 4321 draft-dots-telemetry/blob/master/mapping-table.txt 4323 +----------------------+-------------+------+---------------+--------+ 4324 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 4325 | | Type | Key | Type & | Type | 4326 | | | | Information | | 4327 +======================+=============+======+===============+========+ 4328 | tsid | uint32 |TBA1 | 0 unsigned | Number | 4329 | telemetry | container |TBA2 | 5 map | Object | 4330 | low-percentile | decimal64 |TBA3 | 6 tag 4 | | 4331 | | | | [-2, integer]| String | 4332 | mid-percentile | decimal64 |TBA4 | 6 tag 4 | | 4333 | | | | [-2, integer]| String | 4334 | high-percentile | decimal64 |TBA5 | 6 tag 4 | | 4335 | | | | [-2, integer]| String | 4336 | unit-config | list |TBA6 | 4 array | Array | 4337 | unit | enumeration |TBA7 | 0 unsigned | String | 4338 | unit-status | boolean |TBA8 | 7 bits 20 | False | 4339 | | | | 7 bits 21 | True | 4340 | total-pipe-capability| list |TBA9 | 4 array | Array | 4341 | link-id | string |TBA10 | 3 text string | String | 4342 | pre-or-ongoing- | list |TBA11 | 4 array | Array | 4343 | mitigation | | | | | 4344 | total-traffic-normal | list |TBA12 | 4 array | Array | 4345 | low-percentile-g | yang:gauge64|TBA13 | 0 unsigned | String | 4346 | mid-percentile-g | yang:gauge64|TBA14 | 0 unsigned | String | 4347 | high-percentile-g | yang:gauge64|TBA15 | 0 unsigned | String | 4348 | peak-g | yang:gauge64|TBA16 | 0 unsigned | String | 4349 | total-attack-traffic | list |TBA17 | 4 array | Array | 4350 | total-traffic | list |TBA18 | 4 array | Array | 4351 | total-connection- | | | | | 4352 | capacity | list |TBA19 | 4 array | Array | 4353 | connection | uint64 |TBA20 | 0 unsigned | String | 4354 | connection-client | uint64 |TBA21 | 0 unsigned | String | 4355 | embryonic | uint64 |TBA22 | 0 unsigned | String | 4356 | embryonic-client | uint64 |TBA23 | 0 unsigned | String | 4357 | connection-ps | uint64 |TBA24 | 0 unsigned | String | 4358 | connection-client-ps | uint64 |TBA25 | 0 unsigned | String | 4359 | request-ps | uint64 |TBA26 | 0 unsigned | String | 4360 | request-client-ps | uint64 |TBA27 | 0 unsigned | String | 4361 | partial-request-ps | uint64 |TBA28 | 0 unsigned | String | 4362 | partial-request- | | | | | 4363 | client-ps | uint64 |TBA29 | 0 unsigned | String | 4364 | total-attack- | | | | | 4365 | connection | container |TBA30 | 5 map | Object | 4366 | low-percentile-l | list |TBA31 | 4 array | Array | 4367 | mid-percentile-l | list |TBA32 | 4 array | Array | 4368 | high-percentile-l | list |TBA33 | 4 array | Array | 4369 | peak-l | list |TBA34 | 4 array | Array | 4370 | attack-detail | list |TBA35 | 4 array | Array | 4371 | id | uint32 |TBA36 | 0 unsigned | Number | 4372 | attack-id | uint32 |TBA37 | 0 unsigned | Number | 4373 | attack-description | string |TBA38 | 3 text string | String | 4374 | attack-severity | enumeration |TBA39 | 0 unsigned | String | 4375 | start-time | uint64 |TBA40 | 0 unsigned | String | 4376 | end-time | uint64 |TBA41 | 0 unsigned | String | 4377 | source-count | container |TBA42 | 5 map | Object | 4378 | top-talker | container |TBA43 | 5 map | Object | 4379 | spoofed-status | boolean |TBA44 | 7 bits 20 | False | 4380 | | | | 7 bits 21 | True | 4381 | low-percentile-c | container |TBA45 | 5 map | Object | 4382 | mid-percentile-c | container |TBA46 | 5 map | Object | 4383 | high-percentile-c | container |TBA47 | 5 map | Object | 4384 | peak-c | container |TBA48 | 5 map | Object | 4385 | baseline | container |TBA49 | 5 map | Object | 4386 | current-config | container |TBA50 | 5 map | Object | 4387 | max-config-values | container |TBA51 | 5 map | Object | 4388 | min-config-values | container |TBA52 | 5 map | Object | 4389 | supported-units | container |TBA53 | 5 map | Object | 4390 | server-originated- | boolean |TBA54 | 7 bits 20 | False | 4391 | telemetry | | | 7 bits 21 | True | 4392 | telemetry-notify- | uint32 |TBA55 | 0 unsigned | Number | 4393 | interval | | | | | 4394 | tmid | uint32 |TBA56 | 0 unsigned | Number | 4395 | measurement-interval | enumeration |TBA57 | 0 unsigned | String | 4396 | measurement-sample | enumeration |TBA58 | 0 unsigned | String | 4397 | talker | list |TBA59 | 4 array | Array | 4398 | source-prefix | inet: |TBA60 | 3 text string | String | 4399 | | ip-prefix | | | | 4400 | mid-list | leaf-list |TBA61 | 4 array | Array | 4401 | | uint32 | | 0 unsigned | Number | 4402 | source-port-range | list |TBA62 | 4 array | Array | 4403 | source-icmp-type- | list |TBA63 | 4 array | Array | 4404 | range | | | | | 4405 | lower-type | uint8 |TBA64 | 0 unsigned | Number | 4406 | upper-type | uint8 |TBA65 | 0 unsigned | Number | 4407 | target | container |TBA66 | 5 map | Object | 4408 | capacity | uint64 |TBA67 | 0 unsigned | String | 4409 | protocol | uint8 |TBA68 | 0 unsigned | Number | 4410 | total-traffic- | | | | | 4411 | normal-per-protocol | list |TBA69 | 4 array | Array | 4412 | total-traffic- | | | | | 4413 | normal-per-port | list |TBA70 | 4 array | Array | 4414 | total-connection- | | | | | 4415 | capacity-per-port | list |TBA71 | 4 array | Array | 4416 | total-traffic- | | | | | 4417 | -protocol | list |TBA72 | 4 array | Array | 4418 | total-traffic- port | list |TBA73 | 4 array | Array | 4419 | total-attack- | | | | | 4420 | traffic-protocol | list |TBA74 | 4 array | Array | 4421 | total-attack- | | | | | 4422 | traffic-port | list |TBA75 | 4 array | Array | 4423 | total-attack- | | | | | 4424 | connection-port | list |TBA76 | 4 array | Array | 4425 | port | inet: | | | | 4426 | | port-number|TBA77 | 0 unsigned | Number | 4427 | query-type | leaf-list |TBA78 | 4 array | Array | 4428 | | | | 0 unsigned | String | 4429 | vendor-id | uint32 |TBA79 | 0 unsigned | Number | 4430 | ietf-dots-telemetry: | | | | | 4431 | telemetry-setup | container |TBA80 | 5 map | Object | 4432 | ietf-dots-telemetry: | | | | | 4433 | total-traffic | list |TBA81 | 4 array | Array | 4434 | ietf-dots-telemetry: | | | | | 4435 | total-attack-traffic | list |TBA82 | 4 array | Array | 4436 | ietf-dots-telemetry: | | | | | 4437 | total-attack- | | | | | 4438 | connection | container |TBA83 | 5 map | Object | 4439 | ietf-dots-telemetry: | | | | | 4440 | attack-detail | list |TBA84 | 4 array | Array | 4441 | ietf-dots-telemetry: | | | | | 4442 | telemetry | container |TBA85 | 5 map | Object | 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 | ietf-dots-telemetry: | TBA85 | 5 | IESG | [RFCXXXX] | 4568 | telemetry | | | | | 4569 +----------------------+-------+-------+------------+---------------+ 4571 12.2. DOTS Signal Channel Conflict Cause Codes 4573 This specification requests IANA to assign a new code from the "DOTS 4574 Signal Channel Conflict Cause Codes" registry [Cause]. 4576 +------+-------------------+------------------------+-------------+ 4577 | Code | Label | Description | Reference | 4578 +======+===================+========================+=============+ 4579 | TBA | overlapping-pipes | Overlapping pipe scope | [RFCXXXX] | 4580 +------+-------------------+------------------------+-------------+ 4582 12.3. DOTS Signal Telemetry YANG Module 4584 This document requests IANA to register the following URIs in the 4585 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4587 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4588 Registrant Contact: The IESG. 4589 XML: N/A; the requested URI is an XML namespace. 4591 URI: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4592 Registrant Contact: The IESG. 4593 XML: N/A; the requested URI is an XML namespace. 4595 This document requests IANA to register the following YANG modules in 4596 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4597 Parameters" registry. 4599 name: ietf-dots-telemetry 4600 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4601 maintained by IANA: N 4602 prefix: dots-telemetry 4603 reference: RFC XXXX 4605 name: ietf-dots-mapping 4606 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4607 maintained by IANA: N 4608 prefix: dots-mapping 4609 reference: RFC XXXX 4611 13. Security Considerations 4613 13.1. DOTS Signal Channel Telemetry 4615 The security considerations for the DOTS signal channel protocol are 4616 discussed in Section 11 of [I-D.ietf-dots-rfc8782-bis]. The 4617 following discusses the security considerations that are specific to 4618 the DOTS signal channel extension defined in this document. 4620 The DOTS telemetry information includes DOTS client network topology, 4621 DOTS client domain pipe capacity, normal traffic baseline and 4622 connections capacity, and threat and mitigation information. Such 4623 information is sensitive; it MUST be protected at rest by the DOTS 4624 server domain to prevent data leakage. 4626 DOTS clients are typically trusted devices by the DOTS client domain. 4627 DOTS clients may be co-located on network security services (e.g., 4628 firewall) and a compromised security service potentially can do a lot 4629 more damage to the network. This assumption differs from the often 4630 held view that devices are untrusted, often referred to as the "zero- 4631 trust model". A compromised DOTS client can send fake DOTS telemetry 4632 data to a DOTS server to mislead the DOTS server. This attack can be 4633 prevented by monitoring and auditing DOTS clients to detect 4634 misbehavior and to deter misuse, and by only authorizing the DOTS 4635 client to convey the DOTS telemetry for specific target resources 4636 (e.g., an application server is authorized to exchange DOTS telemetry 4637 for its IP addresses but a DDoS mitigator can exchange DOTS telemetry 4638 for any target resource in the network). As a reminder, this is 4639 variation of dealing with compromised DOTS clients as discussed in 4640 Section 11 of [I-D.ietf-dots-rfc8782-bis]. 4642 DOTS servers must be capable of defending themselves against DoS 4643 attacks from compromised DOTS clients. The following non- 4644 comprehensive list of mitigation techniques can be used by a DOTS 4645 server to handle misbehaving DOTS clients: 4647 o The probing rate (defined in Section 4.5 of 4648 [I-D.ietf-dots-rfc8782-bis]) can be used to limit the average data 4649 rate to the DOTS server. 4651 o Rate-limiting DOTS telemetry, including those with new 'tmid' 4652 values, from the same DOTS client defends against DoS attacks that 4653 would result in varying the 'tmid' to exhaust DOTS server 4654 resources. Likewise, the DOTS server can enforce a quota and 4655 time-limit on the number of active pre-or-ongoing-mitigation 4656 telemetry data (identified by 'tmid') from the DOTS client. 4658 Note also that telemetry notification interval may be used to rate- 4659 limit the pre-or-ongoing-mitigation telemetry notifications received 4660 by a DOTS client domain. 4662 13.2. Vendor Attack Mapping 4664 The security considerations for the DOTS data channel protocol are 4665 discussed in Section 10 of [RFC8783]. The following discusses the 4666 security considerations that are specific to the DOTS data channel 4667 extension defined in this document. 4669 All data nodes defined in the YANG module specified in Section 10.2 4670 which can be created, modified, and deleted (i.e., config true, which 4671 is the default) are considered sensitive. Write operations to these 4672 data nodes without proper protection can have a negative effect on 4673 network operations. Appropriate security measures are recommended to 4674 prevent illegitimate users from invoking DOTS data channel primitives 4675 as discussed in [RFC8783]. Nevertheless, an attacker who can access 4676 a DOTS client is technically capable of undertaking various attacks, 4677 such as: 4679 o Communicating invalid attack mapping details to the server 4680 ('/data-channel:dots-data/data-channel:dots-client/dots- 4681 telemetry:vendor-mapping'), which will mislead the server when 4682 correlating attack details. 4684 Some of the readable data nodes in the YANG module specified in 4685 Section 10.2 may be considered sensitive. It is thus important to 4686 control read access to these data nodes. These are the data nodes 4687 and their sensitivity: 4689 o '/data-channel:dots-data/data-channel:dots-client/dots- 4690 telemetry:vendor-mapping' can be misused to infer the DDoS 4691 protection technology deployed in a DOTS client domain. 4693 o '/data-channel:dots-data/dots-telemetry:vendor-mapping' can be 4694 used by a compromised DOTS client to leak the attack detection 4695 capabilities of the DOTS server. This is a variation of the 4696 compromised DOTS client attacks discussed in Section 13.1. 4698 14. Contributors 4700 The following individuals have contributed to this document: 4702 o Li Su, CMCC, Email: suli@chinamobile.com 4704 o Pan Wei, Huawei, Email: william.panwei@huawei.com 4706 15. Acknowledgements 4708 The authors would like to thank Flemming Andreasen, Liang Xia, and 4709 Kaname Nishizuka co-authors of [I-D.doron-dots-telemetry] and 4710 everyone who had contributed to that document. 4712 The authors would like to thank Kaname Nishizuka, Wei Pan, and Yuuhei 4713 Hayashi for comments and review. 4715 Special thanks to Jon Shallow and Kaname Nishizuka for their 4716 implementation and interoperability work. 4718 Many thanks to Jan Lindblad for the yangdoctors review and Nagendra 4719 Nainar for the opsdir review. 4721 16. References 4723 16.1. Normative References 4725 [Enterprise-Numbers] 4726 "Private Enterprise Numbers", May 2020, 4727 . 4729 [I-D.ietf-dots-rfc8782-bis] 4730 Boucadair, M., Shallow, J., and T. Reddy.K, "Distributed 4731 Denial-of-Service Open Threat Signaling (DOTS) Signal 4732 Channel Specification", draft-ietf-dots-rfc8782-bis-01 4733 (work in progress), September 2020. 4735 [I-D.ietf-dots-signal-filter-control] 4736 Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 4737 "Controlling Filtering Rules Using Distributed Denial-of- 4738 Service Open Threat Signaling (DOTS) Signal Channel", 4739 draft-ietf-dots-signal-filter-control-07 (work in 4740 progress), June 2020. 4742 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4743 Requirement Levels", BCP 14, RFC 2119, 4744 DOI 10.17487/RFC2119, March 1997, 4745 . 4747 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4748 DOI 10.17487/RFC3688, January 2004, 4749 . 4751 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 4752 the Network Configuration Protocol (NETCONF)", RFC 6020, 4753 DOI 10.17487/RFC6020, October 2010, 4754 . 4756 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4757 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4758 . 4760 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4761 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4762 October 2013, . 4764 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4765 Application Protocol (CoAP)", RFC 7252, 4766 DOI 10.17487/RFC7252, June 2014, 4767 . 4769 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4770 Application Protocol (CoAP)", RFC 7641, 4771 DOI 10.17487/RFC7641, September 2015, 4772 . 4774 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4775 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4776 . 4778 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4779 the Constrained Application Protocol (CoAP)", RFC 7959, 4780 DOI 10.17487/RFC7959, August 2016, 4781 . 4783 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 4784 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 4785 November 2016, . 4787 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 4788 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 4789 . 4791 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4792 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4793 May 2017, . 4795 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 4796 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 4797 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 4798 2018, . 4800 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 4801 Denial-of-Service Open Threat Signaling (DOTS) Data 4802 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 4803 May 2020, . 4805 [RFC8791] Bierman, A., Bjoerklund, M., and K. Watsen, "YANG Data 4806 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 4807 June 2020, . 4809 16.2. Informative References 4811 [Cause] IANA, "DOTS Signal Channel Conflict Cause Codes", 4812 . 4815 [I-D.doron-dots-telemetry] 4816 Doron, E., Reddy, T., Andreasen, F., Xia, L., and K. 4817 Nishizuka, "Distributed Denial-of-Service Open Threat 4818 Signaling (DOTS) Telemetry Specifications", draft-doron- 4819 dots-telemetry-00 (work in progress), October 2016. 4821 [I-D.ietf-core-new-block] 4822 Boucadair, M. and J. Shallow, "Constrained Application 4823 Protocol (CoAP) Block-Wise Transfer Options for Faster 4824 Transmission", draft-ietf-core-new-block-02 (work in 4825 progress), October 2020. 4827 [I-D.ietf-dots-multihoming] 4828 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 4829 Deployment Considerations for Distributed-Denial-of- 4830 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 4831 multihoming-04 (work in progress), May 2020. 4833 [I-D.ietf-dots-use-cases] 4834 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 4835 L., and K. Nishizuka, "Use cases for DDoS Open Threat 4836 Signaling", draft-ietf-dots-use-cases-25 (work in 4837 progress), July 2020. 4839 [Key-Map] IANA, "DOTS Signal Channel CBOR Key Values", 4840 . 4843 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 4844 "Framework for IP Performance Metrics", RFC 2330, 4845 DOI 10.17487/RFC2330, May 1998, 4846 . 4848 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4849 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4850 . 4852 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4853 Threat Signaling (DOTS) Requirements", RFC 8612, 4854 DOI 10.17487/RFC8612, May 2019, 4855 . 4857 Authors' Addresses 4859 Mohamed Boucadair (editor) 4860 Orange 4861 Rennes 35000 4862 France 4864 Email: mohamed.boucadair@orange.com 4866 Tirumaleswar Reddy (editor) 4867 McAfee, Inc. 4868 Embassy Golf Link Business Park 4869 Bangalore, Karnataka 560071 4870 India 4872 Email: kondtir@gmail.com 4873 Ehud Doron 4874 Radware Ltd. 4875 Raoul Wallenberg Street 4876 Tel-Aviv 69710 4877 Israel 4879 Email: ehudd@radware.com 4881 Meiling Chen 4882 CMCC 4883 32, Xuanwumen West 4884 BeiJing, BeiJing 100053 4885 China 4887 Email: chenmeiling@chinamobile.com 4889 Jon Shallow 4890 United Kingdom 4892 Email: supjps-ietf@jpshallow.com