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