idnits 2.17.00 (12 Aug 2021) /tmp/idnits37856/draft-ietf-dots-telemetry-09.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 645 has weird spacing: '...-status boo...' == Line 661 has weird spacing: '...-status boo...' == Line 905 has weird spacing: '...apacity uin...' == Line 1241 has weird spacing: '...er-port ine...' == Line 1577 has weird spacing: '...er-port ine...' == (6 more instances...) -- The document date (June 19, 2020) is 700 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 4473, but not defined == Unused Reference: 'I-D.ietf-dots-signal-call-home' is defined on line 4619, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'Enterprise-Numbers' == Outdated reference: draft-ietf-dots-signal-call-home has been published as RFC 9066 == Outdated reference: draft-ietf-dots-signal-filter-control has been published as RFC 9133 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 8782 (Obsoleted by RFC 9132) == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-04 == Outdated reference: draft-ietf-dots-use-cases has been published as RFC 8903 Summary: 3 errors (**), 0 flaws (~~), 13 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: December 21, 2020 McAfee 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 J. Shallow 11 June 19, 2020 13 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 14 draft-ietf-dots-telemetry-09 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 December 21, 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 . . . . . . . . . 19 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 . 26 85 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity . . 26 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 . . . . . . . . . . . . . . . . . . . . . . . 57 106 9. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 61 107 9.1. DOTS Signal Channel Telemetry YANG Module . . . . . . . . 61 108 9.2. Vendor Attack Mapping Details YANG Module . . . . . . . . 88 109 10. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 91 110 11. IANA Considerationsr . . . . . . . . . . . . . . . . . . . . 95 111 11.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 95 112 11.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 99 113 11.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 99 114 12. Security Considerations . . . . . . . . . . . . . . . . . . . 100 115 12.1. DOTS Signal Channel Telemetry . . . . . . . . . . . . . 100 116 12.2. Vendor Attack Mapping . . . . . . . . . . . . . . . . . 101 117 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 102 118 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 102 119 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 102 120 15.1. Normative References . . . . . . . . . . . . . . . . . . 102 121 15.2. Informative References . . . . . . . . . . . . . . . . . 104 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 105 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 conclusion derived from these real scenarios is that modern 166 attacks detection and mitigation are most certainly complicated and 167 highly convoluted tasks. They demand a comprehensive knowledge of 168 the attack attributes, the targeted normal behavior (including, 169 normal traffic patterns), as well as the attacker's on-going and past 170 actions. Even more challenging, retrieving all the analytics needed 171 for detecting these attacks is not simple to obtain with the 172 industry's current capabilities. 174 The DOTS signal channel protocol [RFC8782] is used to carry 175 information about a network resource or a network (or a part thereof) 176 that is under a DDoS attack. Such information is sent by a DOTS 177 client to one or multiple DOTS servers so that appropriate mitigation 178 actions are undertaken on traffic deemed suspicious. Various use 179 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 [RFC8783] is a reasonable candidate to achieve this objective; the 385 DOTS client can ask for the type(s) of traffic (such as ICMP, UDP, 386 TCP port number 80) it prefers to limit. The rate-limit action can 387 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 Section 4.4.1 of [RFC8782], a unique 405 identifier is generated by a DOTS client to prevent request 406 collisions ('cuid'). 408 As a reminder, [RFC8782] forbids 'cuid' to be returned in a response 409 message body. 411 4.2. DOTS Gateways 413 DOTS gateways may be located between DOTS clients and servers. The 414 considerations elaborated in Section 4.4.1 of [RFC8782] must be 415 followed. In particular, 'cdid' attribute is used to unambiguously 416 identify a DOTS client domain. 418 As a reminder, [RFC8782] forbids 'cdid' (if present) to be returned 419 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 [RFC8782] for managing DOTS telemetry 430 configuration freshness and notification. Likewise, a DOTS client 431 may control the selection of configuration and non-configuration data 432 nodes when sending a GET request by means of the 'c' Uri-Query option 433 and following the procedure specified in Section of 4.4.2 of 434 [RFC8782]. These considerations are not re-iterated in the following 435 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 [RFC8782] to control the 441 size of a response when the data to be returned does not fit within a 442 single datagram. 444 DOTS clients can also use CoAP 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. 479 This document specifies a YANG module for representing DOTS telemetry 480 message types (Section 9.1). All parameters in the payload of the 481 DOTS signal channel are mapped to CBOR types as specified in 482 Section 10. 484 The DOTS telemetry module (Section 9.1) is not intended to be used 485 via NETCONF/RESTCONF for DOTS server management purposes. It serves 486 only to provide a data model and encoding, but not a management data 487 model. DOTS servers are allowed to update the non-configurable 'ro' 488 entities in the responses of DOTS telemetry messages. 490 The DOTS telemetry module (Section 9.1) uses "enumerations" rather 491 than "identities" to define units, samples, and intervals because 492 otherwise the namespace identifier "ietf-dots-telemetry" must be 493 included when a telemetry attribute is included (e.g., in a 494 mitigation efficacy update). The use of "identities" is thus 495 suboptimal from a message compactness standpoint. 497 4.8. A Note About Examples 499 Examples are provided for illustration purposes. The document does 500 not aim to provide a comprehensive list of message examples. 502 The authoritative reference for validating telemetry messages is the 503 YANG module (Section 9.1) and the mapping table established in 504 Section 10. 506 5. Telemetry Operation Paths 508 As discussed in Section 4.2 of [RFC8782], each DOTS operation is 509 indicated by a path-suffix that indicates the intended operation. 510 The operation path is appended to the path-prefix to form the URI 511 used with a CoAP request to perform the desired DOTS operation. The 512 following telemetry path-suffixes are defined (Table 1): 514 +-----------------+----------------+-----------+ 515 | Operation | Operation Path | Details | 516 +=================+================+===========+ 517 | Telemetry Setup | /tm-setup | Section 6 | 518 | Telemetry | /tm | Section 7 | 519 +-----------------+----------------+-----------+ 521 Table 1: DOTS Telemetry Operations 523 Consequently, the "ietf-dots-telemetry" YANG module defined in 524 Section 9.1 augments the "ietf-dots-signal" with two new message 525 types called "telemetry-setup" and "telemetry". The tree structure 526 is shown in Figure 1 (more details are provided in the following 527 sections about the exact structure of "telemetry-setup" and 528 "telemetry" message types). 530 augment /ietf-signal:dots-signal/ietf-signal:message-type: 531 +--:(telemetry-setup) {dots-telemetry}? 532 | ... 533 | +--rw (setup-type)? 534 | +--:(telemetry-config) 535 | | ... 536 | +--:(pipe) 537 | | ... 538 | +--:(baseline) 539 | ... 540 +--:(telemetry) {dots-telemetry}? 541 ... 543 Figure 1: New DOTS Message Types (YANG Tree Structure) 545 6. DOTS Telemetry Setup Configuration 547 In reference to Figure 1, a DOTS telemetry setup message MUST include 548 only telemetry-related configuration parameters (Section 6.1) or 549 information about DOTS client domain pipe capacity (Section 6.2) or 550 telemetry traffic baseline (Section 6.3). As such, requests that 551 include a mix of telemetry configuration, pipe capacity, or traffic 552 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 554 A DOTS client can reset all installed DOTS telemetry setup 555 configuration data following the considerations detailed in 556 Section 6.4. 558 A DOTS server may detect conflicts when processing requests related 559 to DOTS client domain pipe capacity or telemetry traffic baseline 560 with requests from other DOTS clients of the same DOTS client domain. 561 More details are included in Section 6.5. 563 Telemetry setup configuration is bound to a DOTS client domain. DOTS 564 servers MUST NOT expect DOTS clients to send regular requests to 565 refresh the telemetry setup configuration. Any available telemetry 566 setup configuration has a validity timeout of the DOTS association 567 with a DOTS client domain. DOTS servers MUST NOT reset 'tsid' 568 because a session failed with a DOTS client. DOTS clients update 569 their telemetry setup configuration upon change of a parameter that 570 may impact attack mitigation. 572 DOTS telemetry setup configuration request and response messages are 573 marked as Confirmable messages. 575 6.1. Telemetry Configuration 577 A DOTS client can negotiate with its server(s) a set of telemetry 578 configuration parameters to be used for telemetry. Such parameters 579 include: 581 o Percentile-related measurement parameters 583 o Measurement units 585 o Acceptable percentile values 587 o Telemetry notification interval 589 o Acceptable Server-originated telemetry 591 Section 11.3 of [RFC2330] includes more details about computing 592 percentiles. 594 6.1.1. Retrieve Current DOTS Telemetry Configuration 596 A GET request is used to obtain acceptable and current telemetry 597 configuration parameters on the DOTS server. This request may 598 include a 'cdid' Path-URI when the request is relayed by a DOTS 599 gateway. An example of such request is depicted in Figure 2. 601 Header: GET (Code=0.01) 602 Uri-Path: ".well-known" 603 Uri-Path: "dots" 604 Uri-Path: "tm-setup" 605 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 607 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 608 Configuration 610 Upon receipt of such request, the DOTS server replies with a 2.05 611 (Content) response that conveys the current and telemetry parameters 612 acceptable by the DOTS server. The tree structure of the response 613 message body is provided in Figure 3. Note that the response also 614 includes any pipe (Section 6.2) and baseline information 615 (Section 6.3) maintained by the DOTS server for this DOTS client. 617 DOTS servers that support the capability of sending telemetry 618 information to DOTS clients prior or during a mitigation 619 (Section 8.2) sets 'server-originated-telemetry' under 'max-config- 620 values' to 'true' ('false' is used otherwise). If 'server- 621 originated-telemetry' is not present in a response, this is 622 equivalent to receiving a request with 'server-originated-telemetry' 623 set to 'false'. 625 augment /ietf-signal:dots-signal/ietf-signal:message-type: 626 +--:(telemetry-setup) {dots-telemetry}? 627 | +--ro max-config-values 628 | | +--ro measurement-interval? interval 629 | | +--ro measurement-sample? sample 630 | | +--ro low-percentile? percentile 631 | | +--ro mid-percentile? percentile 632 | | +--ro high-percentile? percentile 633 | | +--ro server-originated-telemetry? boolean 634 | | +--ro telemetry-notify-interval? uint32 635 | +--ro min-config-values 636 | | +--ro measurement-interval? interval 637 | | +--ro measurement-sample? sample 638 | | +--ro low-percentile? percentile 639 | | +--ro mid-percentile? percentile 640 | | +--ro high-percentile? percentile 641 | | +--ro telemetry-notify-interval? uint32 642 | +--ro supported-units 643 | | +--ro unit-config* [unit] 644 | | +--ro unit unit-type 645 | | +--ro unit-status boolean 646 | +--ro query-type* query-type 647 | +--rw telemetry* [cuid tsid] 648 | +--rw cuid string 649 | +--rw cdid? string 650 | +--rw tsid uint32 651 | +--rw (setup-type)? 652 | +--:(telemetry-config) 653 | | +--rw current-config 654 | | +--rw measurement-interval? interval 655 | | +--rw measurement-sample? sample 656 | | +--rw low-percentile? percentile 657 | | +--rw mid-percentile? percentile 658 | | +--rw high-percentile? percentile 659 | | +--rw unit-config* [unit] 660 | | | +--rw unit unit-type 661 | | | +--rw unit-status boolean 662 | | +--rw server-originated-telemetry? boolean 663 | | +--rw telemetry-notify-interval? uint32 664 | +--:(pipe) 665 | ... 666 | +--:(baseline) 667 | ... 668 +--:(telemetry) {dots-telemetry}? 669 +--rw pre-or-ongoing-mitigation* [cuid tmid] 670 ... 672 Figure 3: Telemetry Configuration Tree Structure 674 When both 'min-config-values' and 'max-config-values' attributes are 675 present, the values carried in 'max-config-values' attributes MUST be 676 greater or equal to their counterpart in 'min-config-values' 677 attributes. 679 6.1.2. Convey DOTS Telemetry Configuration 681 PUT request is used to convey the configuration parameters for the 682 telemetry data (e.g., low, mid, or high percentile values). For 683 example, a DOTS client may contact its DOTS server to change the 684 default percentile values used as baseline for telemetry data. 685 Figure 3 lists the attributes that can be set by a DOTS client in 686 such PUT request. An example of a DOTS client that modifies all 687 percentile reference values is shown in Figure 4. 689 Header: PUT (Code=0.03) 690 Uri-Path: ".well-known" 691 Uri-Path: "dots" 692 Uri-Path: "tm-setup" 693 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 694 Uri-Path: "tsid=123" 695 Content-Format: "application/dots+cbor" 697 { 698 "ietf-dots-telemetry:telemetry-setup": { 699 "telemetry": [ 700 { 701 "current-config": { 702 "low-percentile": "5.00", 703 "mid-percentile": "65.00", 704 "high-percentile": "95.00" 705 } 706 } 707 ] 708 } 709 } 711 Figure 4: PUT to Convey the DOTS Telemetry Configuration 713 'cuid' is a mandatory Uri-Path parameter for PUT requests. 715 The following additional Uri-Path parameter is defined: 717 tsid: Telemetry Setup Identifier is an identifier for the DOTS 718 telemetry setup configuration data represented as an integer. 719 This identifier MUST be generated by DOTS clients. 'tsid' 720 values MUST increase monotonically (when a new PUT is generated 721 by a DOTS client to convey new configuration parameters for the 722 telemetry). 724 The procedure specified in Section 4.4.1 of [RFC8782] MUST be 725 followed for 'tsid' rollover. 727 This is a mandatory attribute. 729 'cuid' and 'tsid' MUST NOT appear in the PUT request message body. 731 At least one configurable attribute MUST be present in the PUT 732 request. 734 The PUT request with a higher numeric 'tsid' value overrides the DOTS 735 telemetry configuration data installed by a PUT request with a lower 736 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 737 requests for requests carrying telemetry configuration data from a 738 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 739 and no longer be available at the DOTS server. 741 The DOTS server indicates the result of processing the PUT request 742 using the following response codes: 744 o If the request is missing a mandatory attribute, does not include 745 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 746 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 747 in the response. 749 o If the DOTS server does not find the 'tsid' parameter value 750 conveyed in the PUT request in its configuration data and if the 751 DOTS server has accepted the configuration parameters, then a 752 response code 2.01 (Created) MUST be returned in the response. 754 o If the DOTS server finds the 'tsid' parameter value conveyed in 755 the PUT request in its configuration data and if the DOTS server 756 has accepted the updated configuration parameters, 2.04 (Changed) 757 MUST be returned in the response. 759 o If any of the enclosed configurable attribute values are not 760 acceptable to the DOTS server (Section 6.1.1), 4.22 (Unprocessable 761 Entity) MUST be returned in the response. 763 The DOTS client may re-try and send the PUT request with updated 764 attribute values acceptable to the DOTS server. 766 By default, low percentile (10th percentile), mid percentile (50th 767 percentile), high percentile (90th percentile), and peak (100th 768 percentile) values are used to represent telemetry data. 770 Nevertheless, a DOTS client can disable some percentile types (low, 771 mid, high). In particular, setting 'low-percentile' to '0.00' 772 indicates that the DOTS client is not interested in receiving low- 773 percentiles. Likewise, setting 'mid-percentile' (or 'high- 774 percentile') to the same value as 'low-percentile' (or 'mid- 775 percentile') indicates that the DOTS client is not interested in 776 receiving mid-percentiles (or high-percentiles). For example, a DOTS 777 client can send the request depicted in Figure 5 to inform the server 778 that it is interested in receiving only high-percentiles. This 779 assumes that the client will only use that percentile type when 780 sharing telemetry data with the server. 782 Header: PUT (Code=0.03) 783 Uri-Path: ".well-known" 784 Uri-Path: "dots" 785 Uri-Path: "tm-setup" 786 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 787 Uri-Path: "tsid=569" 788 Content-Format: "application/dots+cbor" 790 { 791 "ietf-dots-telemetry:telemetry-setup": { 792 "telemetry": [ 793 { 794 "current-config": { 795 "low-percentile": "0.00", 796 "mid-percentile": "0.00", 797 "high-percentile": "95.00" 798 } 799 } 800 ] 801 } 802 } 804 Figure 5: PUT to Disable Low- and Mid-Percentiles 806 DOTS clients can also configure the unit type(s) to be used for 807 traffic-related telemetry data. Typically, the supported unit types 808 are: packets per second, bits per second, and bytes per second. 810 DOTS clients that are interested to receive pre- or ongoing 811 mitigation telemetry (pre-or-ongoing-mitigation) information from a 812 DOTS server (Section 8.2) MUST set 'server-originated-telemetry' to 813 'true'. If 'server-originated-telemetry' is not present in a PUT 814 request, this is equivalent to receiving a request with 'server- 815 originated-telemetry' set to 'false'. An example of a request to 816 enable pre-or-ongoing-mitigation telemetry from DOTS servers is shown 817 in Figure 6. 819 Header: PUT (Code=0.03) 820 Uri-Path: ".well-known" 821 Uri-Path: "dots" 822 Uri-Path: "tm-setup" 823 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 824 Uri-Path: "tsid=569" 825 Content-Format: "application/dots+cbor" 827 { 828 "ietf-dots-telemetry:telemetry-setup": { 829 "telemetry": [ 830 { 831 "current-config": { 832 "server-originated-telemetry": true 833 } 834 } 835 ] 836 } 837 } 839 Figure 6: PUT to Enable Pre-or-ongoing-mitigation Telemetry from the 840 DOTS server 842 6.1.3. Retrieve Installed DOTS Telemetry Configuration 844 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 845 to retrieve the current DOTS telemetry configuration. An example of 846 such request is depicted in Figure 7. 848 Header: GET (Code=0.01) 849 Uri-Path: ".well-known" 850 Uri-Path: "dots" 851 Uri-Path: "tm-setup" 852 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 853 Uri-Path: "tsid=123" 855 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 857 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 858 in the GET request in its configuration data for the requesting DOTS 859 client, it MUST respond with a 4.04 (Not Found) error response code. 861 6.1.4. Delete DOTS Telemetry Configuration 863 A DELETE request is used to delete the installed DOTS telemetry 864 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 865 Path parameters for such DELETE requests. 867 Header: DELETE (Code=0.04) 868 Uri-Path: ".well-known" 869 Uri-Path: "dots" 870 Uri-Path: "tm-setup" 871 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 872 Uri-Path: "tsid=123" 874 Figure 8: Delete Telemetry Configuration 876 The DOTS server resets the DOTS telemetry configuration back to the 877 default values and acknowledges a DOTS client's request to remove the 878 DOTS telemetry configuration using 2.02 (Deleted) response code. A 879 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 880 value conveyed in the DELETE request does not exist in its 881 configuration data before the request. 883 Section 6.4 discusses the procedure to reset all DOTS telemetry setup 884 configuration. 886 6.2. Total Pipe Capacity 888 A DOTS client can communicate to its server(s) its DOTS client domain 889 pipe information. The tree structure of the pipe information is 890 shown in Figure 9. 892 augment /ietf-signal:dots-signal/ietf-signal:message-type: 893 +--:(telemetry-setup) {dots-telemetry}? 894 | ... 895 | +--rw telemetry* [cuid tsid] 896 | +--rw cuid string 897 | +--rw cdid? string 898 | +--rw tsid uint32 899 | +--rw (setup-type)? 900 | +--:(telemetry-config) 901 | | ... 902 | +--:(pipe) 903 | | +--rw total-pipe-capacity* [link-id unit] 904 | | +--rw link-id nt:link-id 905 | | +--rw capacity uint64 906 | | +--rw unit unit 907 | +--:(baseline) 908 | ... 909 +--:(telemetry) {dots-telemetry}? 910 +--rw pre-or-ongoing-mitigation* [cuid tmid] 911 ... 913 Figure 9: Pipe Tree Structure 915 A DOTS client domain pipe is defined as a list of limits of 916 (incoming) traffic volume (total-pipe-capacity") that can be 917 forwarded over ingress interconnection links of a DOTS client domain. 918 Each of these links is identified with a "link-id" [RFC8345]. 920 The unit used by a DOTS client when conveying pipe information is 921 captured in 'unit' attribute. 923 6.2.1. Convey DOTS Client Domain Pipe Capacity 925 Similar considerations to those specified in Section 6.1.2 are 926 followed with one exception: 928 The relative order of two PUT requests carrying DOTS client domain 929 pipe attributes from a DOTS client is determined by comparing 930 their respective 'tsid' values. If such two requests have 931 overlapping "link-id" and "unit", the PUT request with higher 932 numeric 'tsid' value will override the request with a lower 933 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 934 automatically deleted and no longer be available. 936 DOTS clients SHOULD minimize the number of active 'tsids' used for 937 pipe information. Typically, in order to avoid maintaining a long 938 list of 'tsids' for pipe information, it is RECOMMENDED that DOTS 939 clients include in any request to update information related to a 940 given link the information of other links (already communicated using 941 a lower 'tsid' value). Doing so, this update request will override 942 these existing requests and hence optimize the number of 'tsid' 943 request per DOTS client. 945 o Note: This assumes that all link information can fit in one single 946 message. 948 For example, a DOTS client managing a single homed domain (Figure 10) 949 can send a PUT request (shown in Figure 11) to communicate the 950 capacity of "link1" used to connect to its ISP. 952 ,--,--,--. ,--,--,--. 953 ,-' `-. ,-' `-. 954 ( DOTS Client )=====( ISP#A ) 955 `-. Domain ,-' link1 `-. ,-' 956 `--'--'--' `--'--'--' 958 Figure 10: Single Homed DOTS Client Domain 960 Header: PUT (Code=0.03) 961 Uri-Path: ".well-known" 962 Uri-Path: "dots" 963 Uri-Path: "tm-setup" 964 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 965 Uri-Path: "tsid=457" 966 Content-Format: "application/dots+cbor" 968 { 969 "ietf-dots-telemetry:telemetry-setup": { 970 "telemetry": [ 971 { 972 "total-pipe-capacity": [ 973 { 974 "link-id": "link1", 975 "capacity": "500", 976 "unit": "megabit-ps" 977 } 978 ] 979 } 980 ] 981 } 982 } 984 Figure 11: Example of a PUT Request to Convey Pipe Information 985 (Single Homed) 987 DOTS clients may be instructed to signal a link aggregate instead of 988 individual links. For example, a DOTS client managing a DOTS client 989 domain having two interconnection links with an upstream ISP 990 (Figure 12) can send a PUT request (shown in Figure 13) to 991 communicate the aggregate link capacity with its ISP. Signalling 992 individual or aggregate link capacity is deployment-specific. 994 ,--,--,--. ,--,--,--. 995 ,-' `-.===== ,-' `-. 996 ( DOTS Client ) ( ISP#C ) 997 `-. Domain ,-'====== `-. ,-' 998 `--'--'--' `--'--'--' 1000 Figure 12: DOTS Client Domain with Two Interconnection Links 1002 Header: PUT (Code=0.03) 1003 Uri-Path: ".well-known" 1004 Uri-Path: "dots" 1005 Uri-Path: "tm-setup" 1006 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1007 Uri-Path: "tsid=896" 1008 Content-Format: "application/dots+cbor" 1010 { 1011 "ietf-dots-telemetry:telemetry-setup": { 1012 "telemetry": [ 1013 { 1014 "total-pipe-capacity": [ 1015 { 1016 "link-id": "aggregate", 1017 "capacity": "700", 1018 "unit": "megabit-ps" 1019 } 1020 ] 1021 } 1022 ] 1023 } 1024 } 1026 Figure 13: Example of a PUT Request to Convey Pipe Information 1027 (Aggregated Link) 1029 Now consider that the DOTS client domain was upgraded to connect to 1030 an additional ISP (ISP#B of Figure 14), the DOTS client can inform a 1031 third-party DOTS server (that is, not hosted with ISP#A and ISP#B 1032 domains) about this update by sending the PUT request depicted in 1033 Figure 15. This request also includes information related to "link1" 1034 even if that link is not upgraded. Upon receipt of this request, the 1035 DOTS server removes the request with 'tsid=457' and updates its 1036 configuration base to maintain two links (link#1 and link#2). 1038 ,--,--,--. 1039 ,-' `-. 1040 ( ISP#B ) 1041 `-. ,-' 1042 `--'--'--' 1043 || 1044 || link2 1045 ,--,--,--. ,--,--,--. 1046 ,-' `-. ,-' `-. 1047 ( DOTS Client )=====( ISP#A ) 1048 `-. Domain ,-' link1 `-. ,-' 1049 `--'--'--' `--'--'--' 1051 Figure 14: Multi-Homed DOTS Client Domain 1053 Header: PUT (Code=0.03) 1054 Uri-Path: ".well-known" 1055 Uri-Path: "dots" 1056 Uri-Path: "tm-setup" 1057 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1058 Uri-Path: "tsid=458" 1059 Content-Format: "application/dots+cbor" 1061 { 1062 "ietf-dots-telemetry:telemetry-setup": { 1063 "telemetry": [ 1064 { 1065 "total-pipe-capacity": [ 1066 { 1067 "link-id": "link1", 1068 "capacity": "500", 1069 "unit": "megabit-ps" 1070 }, 1071 { 1072 "link-id": "link2", 1073 "capacity": "500", 1074 "unit": "megabit-ps" 1075 } 1076 ] 1077 } 1078 ] 1079 } 1080 } 1082 Figure 15: Example of a PUT Request to Convey Pipe Information 1083 (Multi-Homed) 1085 A DOTS client can delete a link by sending a PUT request with the 1086 'capacity' attribute set to "0" if other links are still active for 1087 the same DOTS client domain (see Section 6.2.3 for other delete 1088 cases). For example, if a DOTS client domain re-homes (that is, it 1089 changes its ISP), the DOTS client can inform its DOTS server about 1090 this update (e.g., from the network configuration in Figure 10 to the 1091 one shown in Figure 16) by sending the PUT request depicted in 1092 Figure 17. Upon receipt of this request, the DOTS server removes 1093 "link1" from its configuration bases for this DOTS client domain. 1095 ,--,--,--. 1096 ,-' `-. 1097 ( ISP#B ) 1098 `-. ,-' 1099 `--'--'--' 1100 || 1101 || link2 1102 ,--,--,--. 1103 ,-' `-. 1104 ( DOTS Client ) 1105 `-. Domain ,-' 1106 `--'--'--' 1108 Figure 16: Multi-Homed DOTS Client Domain 1110 Header: PUT (Code=0.03) 1111 Uri-Path: ".well-known" 1112 Uri-Path: "dots" 1113 Uri-Path: "tm-setup" 1114 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1115 Uri-Path: "tsid=459" 1116 Content-Format: "application/dots+cbor" 1118 { 1119 "ietf-dots-telemetry:telemetry-setup": { 1120 "telemetry": [ 1121 { 1122 "total-pipe-capacity": [ 1123 { 1124 "link-id": "link1", 1125 "capacity": "0", 1126 "unit": "megabit-ps" 1127 }, 1128 { 1129 "link-id": "link2", 1130 "capacity": "500", 1131 "unit": "megabit-ps" 1132 } 1133 ] 1134 } 1135 ] 1136 } 1137 } 1139 Figure 17: Example of a PUT Request to Convey Pipe Information 1140 (Multi-Homed) 1142 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity 1144 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1145 specific installed DOTS client domain pipe related information. The 1146 same procedure as defined in Section 6.1.3 is followed. 1148 To retrieve all pipe information bound to a DOTS client, the DOTS 1149 client proceeds as specified in Section 6.1.1. 1151 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity 1153 A DELETE request is used to delete the installed DOTS client domain 1154 pipe related information. The same procedure as defined in 1155 Section 6.1.4 is followed. 1157 6.3. Telemetry Baseline 1159 A DOTS client can communicate to its server(s) its normal traffic 1160 baseline and connections capacity: 1162 Total traffic normal baseline: The percentile values representing 1163 the total traffic normal baseline. It can be represented for a 1164 target using 'total-traffic-normal'. 1166 The traffic normal per protocol ('total-traffic-normal-per- 1167 protocol') baseline is represented for a target and is transport- 1168 protocol specific. 1170 The traffic normal per port number ('total-traffic-normal-per- 1171 port') baseline is represented for each port number bound to a 1172 target. 1174 If the DOTS client negotiated percentile values and units 1175 (Section 6.1), these negotiated values will be used instead of the 1176 default ones. 1178 Total connections capacity: If the target is subjected to resource 1179 consuming DDoS attacks, the following optional attributes for the 1180 target per transport-protocol are useful to detect resource 1181 consuming DDoS attacks: 1183 * The maximum number of simultaneous connections that are allowed 1184 to the target. 1186 * The maximum number of simultaneous connections that are allowed 1187 to the target per client. 1189 * The maximum number of simultaneous embryonic connections that 1190 are allowed to the target. The term "embryonic connection" 1191 refers to a connection whose connection handshake is not 1192 finished. Embryonic connection is only possible in connection- 1193 oriented transport protocols like TCP or SCTP. 1195 * The maximum number of simultaneous embryonic connections that 1196 are allowed to the target per client. 1198 * The maximum number of connections allowed per second to the 1199 target. 1201 * The maximum number of connections allowed per second to the 1202 target per client. 1204 * The maximum number of requests allowed per second to the 1205 target. 1207 * The maximum number of requests allowed per second to the target 1208 per client. 1210 * The maximum number of partial requests allowed per second to 1211 the target. Attacks relying upon partial requests create a 1212 connection with a target but do not send a complete request 1213 (e.g., HTTP request). 1215 * The maximum number of partial requests allowed per second to 1216 the target per client. 1218 The aggregate per transport protocol is captured in 'total- 1219 connection-capacity', while port-specific capabilities are 1220 represented using 'total-connection-capacity-per-port'. 1222 The tree structure of the baseline is shown in Figure 18. 1224 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1225 +--:(telemetry-setup) {dots-telemetry}? 1226 | ... 1227 | +--rw telemetry* [cuid tsid] 1228 | +--rw cuid string 1229 | +--rw cdid? string 1230 | +--rw tsid uint32 1231 | +--rw (setup-type)? 1232 | +--:(telemetry-config) 1233 | | ... 1234 | +--:(pipe) 1235 | | ... 1236 | +--:(baseline) 1237 | +--rw baseline* [id] 1238 | +--rw id uint32 1239 | +--rw target-prefix* inet:ip-prefix 1240 | +--rw target-port-range* [lower-port] 1241 | | +--rw lower-port inet:port-number 1242 | | +--rw upper-port? inet:port-number 1243 | +--rw target-protocol* uint8 1244 | +--rw target-fqdn* inet:domain-name 1245 | +--rw target-uri* inet:uri 1246 | +--rw alias-name* string 1247 | +--rw total-traffic-normal* [unit] 1248 | | +--rw unit unit 1249 | | +--rw low-percentile-g? yang:gauge64 1250 | | +--rw mid-percentile-g? yang:gauge64 1251 | | +--rw high-percentile-g? yang:gauge64 1252 | | +--rw peak-g? yang:gauge64 1253 | +--rw total-traffic-normal-per-protocol* [unit protocol] 1254 | | +--rw unit unit 1255 | | +--rw protocol uint8 1256 | | +--rw low-percentile-g? yang:gauge64 1257 | | +--rw mid-percentile-g? yang:gauge64 1258 | | +--rw high-percentile-g? yang:gauge64 1259 | | +--rw peak-g? yang:gauge64 1260 | +--rw total-traffic-normal-per-port* [unit port] 1261 | | +--rw port inet:port-number 1262 | | +--rw unit unit 1263 | | +--rw low-percentile-g? yang:gauge64 1264 | | +--rw mid-percentile-g? yang:gauge64 1265 | | +--rw high-percentile-g? yang:gauge64 1266 | | +--rw peak-g? yang:gauge64 1267 | +--rw total-connection-capacity* [protocol] 1268 | | +--rw protocol uint8 1269 | | +--rw connection? uint64 1270 | | +--rw connection-client? uint64 1271 | | +--rw embryonic? uint64 1272 | | +--rw embryonic-client? uint64 1273 | | +--rw connection-ps? uint64 1274 | | +--rw connection-client-ps? uint64 1275 | | +--rw request-ps? uint64 1276 | | +--rw request-client-ps? uint64 1277 | | +--rw partial-request-ps? uint64 1278 | | +--rw partial-request-client-ps? uint64 1279 | +--rw total-connection-capacity-per-port* [protocol port] 1280 | +--rw protocol uint8 1281 | +--rw port inet:port-number 1282 | +--rw connection? uint64 1283 | +--rw connection-client? uint64 1284 | +--rw embryonic? uint64 1285 | +--rw embryonic-client? uint64 1286 | +--rw connection-ps? uint64 1287 | +--rw connection-client-ps? uint64 1288 | +--rw request-ps? uint64 1289 | +--rw request-client-ps? uint64 1290 | +--rw partial-request-ps? uint64 1291 | +--rw partial-request-client-ps? uint64 1292 +--:(telemetry) {dots-telemetry}? 1293 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1294 ... 1296 Figure 18: Telemetry Baseline Tree Structure 1298 6.3.1. Convey DOTS Client Domain Baseline Information 1300 Similar considerations to those specified in Section 6.1.2 are 1301 followed with one exception: 1303 The relative order of two PUT requests carrying DOTS client domain 1304 baseline attributes from a DOTS client is determined by comparing 1305 their respective 'tsid' values. If such two requests have 1306 overlapping targets, the PUT request with higher numeric 'tsid' 1307 value will override the request with a lower numeric 'tsid' value. 1308 The overlapped lower numeric 'tsid' MUST be automatically deleted 1309 and no longer be available. 1311 Two PUT requests from a DOTS client have overlapping targets if there 1312 is a common IP address, IP prefix, FQDN, URI, or alias-name. Also, 1313 two PUT requests from a DOTS client have overlapping targets if the 1314 addresses associated with the FQDN, URI, or alias are overlapping 1315 with each other or with target-prefix. 1317 DOTS clients SHOULD minimize the number of active 'tsids' used for 1318 baseline information. Typically, in order to avoid maintaining a 1319 long list of 'tsids' for baseline information, it is RECOMMENDED that 1320 DOTS clients include in a request to update information related to a 1321 given target, the information of other targets (already communicated 1322 using a lower 'tsid' value) (assuming this fits within one single 1323 datagram). This update request will override these existing requests 1324 and hence optimize the number of 'tsid' request per DOTS client. 1326 If no target clause in included in the request, this is an indication 1327 that the baseline information applies for the DOTS client domain as a 1328 whole. 1330 An example of a PUT request to convey the baseline information is 1331 shown in Figure 19. 1333 Header: PUT (Code=0.03) 1334 Uri-Path: ".well-known" 1335 Uri-Path: "dots" 1336 Uri-Path: "tm-setup" 1337 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1338 Uri-Path: "tsid=126" 1339 Content-Format: "application/dots+cbor" 1341 { 1342 "ietf-dots-telemetry:telemetry-setup": { 1343 "telemetry": [ 1344 { 1345 "baseline": [ 1346 { 1347 "id": 1, 1348 "target-prefix": [ 1349 "2001:db8:6401::1/128", 1350 "2001:db8:6401::2/128" 1351 ], 1352 "total-traffic-normal": [ 1353 { 1354 "unit": "megabit-ps", 1355 "peak-g": "60" 1356 } 1357 ] 1358 } 1359 ] 1360 } 1361 ] 1362 } 1363 } 1365 Figure 19: PUT to Convey the DOTS Traffic Baseline 1367 The DOTS client may share protocol-specific baseline information 1368 (e.g., TCP and UDP) as shown in Figure 19. 1370 Header: PUT (Code=0.03) 1371 Uri-Path: ".well-known" 1372 Uri-Path: "dots" 1373 Uri-Path: "tm-setup" 1374 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1375 Uri-Path: "tsid=128" 1376 Content-Format: "application/dots+cbor" 1378 { 1379 "ietf-dots-telemetry:telemetry-setup": { 1380 "telemetry": [ 1381 { 1382 "baseline": [ 1383 { 1384 "id": 1, 1385 "target-prefix": [ 1386 "2001:db8:6401::1/128", 1387 "2001:db8:6401::2/128" 1388 ], 1389 "total-traffic-normal-per-protocol": [ 1390 { 1391 "unit": "megabit-ps", 1392 "protocol": 6, 1393 "peak-g": "50" 1394 }, 1395 { 1396 "unit": "megabit-ps", 1397 "protocol": 17, 1398 "peak-g": "10" 1399 } 1400 ] 1401 } 1402 ] 1403 } 1404 ] 1405 } 1406 } 1408 Figure 20: PUT to Convey the DOTS Traffic Baseline (2) 1410 The traffic baseline information should be updated to reflect 1411 legitimate overloads (e.g., flash crowds) to prevent unnecessary 1412 mitigation. 1414 6.3.2. Retrieve Installed Normal Traffic Baseline 1416 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1417 specific installed DOTS client domain baseline traffic information. 1418 The same procedure as defined in Section 6.1.3 is followed. 1420 To retrieve all baseline information bound to a DOTS client, the DOTS 1421 client proceeds as specified in Section 6.1.1. 1423 6.3.3. Delete Installed Normal Traffic Baseline 1425 A DELETE request is used to delete the installed DOTS client domain 1426 normal traffic baseline. The same procedure as defined in 1427 Section 6.1.4 is followed. 1429 6.4. Reset Installed Telemetry Setup 1431 Upon bootstrapping (or reboot or any other event that may alter the 1432 DOTS client setup), a DOTS client MAY send a DELETE request to set 1433 the telemetry parameters to default values. Such a request does not 1434 include any 'tsid'. An example of such request is depicted in 1435 Figure 21. 1437 Header: DELETE (Code=0.04) 1438 Uri-Path: ".well-known" 1439 Uri-Path: "dots" 1440 Uri-Path: "tm-setup" 1441 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1443 Figure 21: Delete Telemetry Configuration 1445 6.5. Conflict with Other DOTS Clients of the Same Domain 1447 A DOTS server may detect conflicts between requests to convey pipe 1448 and baseline information received from DOTS clients of the same DOTS 1449 client domain. 'conflict-information' is used to report the conflict 1450 to the DOTS client following similar conflict handling discussed in 1451 Section 4.4.1 of [RFC8782]. The conflict cause can be set to one of 1452 these values: 1454 1: Overlapping targets (Section 4.4.1 of [RFC8782]). 1456 TBA: Overlapping pipe scope (see Section 11). 1458 7. DOTS Pre-or-Ongoing Mitigation Telemetry 1460 There are two broad types of DDoS attacks, one is bandwidth consuming 1461 attack, the other is target resource consuming attack. This section 1462 outlines the set of DOTS telemetry attributes (Section 7.1) that 1463 covers both the types of attacks. The objective of these attributes 1464 is to allow for the complete knowledge of attacks and the various 1465 particulars that can best characterize attacks. 1467 The "ietf-dots-telemetry" YANG module (Section 9.1) augments the 1468 "ietf-dots-signal" with a new message type called "telemetry". The 1469 tree structure of the "telemetry" message type is shown Figure 24. 1471 The pre-or-ongoing-mitigation telemetry attributes are indicated by 1472 the path-suffix '/tm'. The '/tm' is appended to the path-prefix to 1473 form the URI used with a CoAP request to signal the DOTS telemetry. 1474 Pre-or-ongoing-mitigation telemetry attributes specified in 1475 Section 7.1 can be signaled between DOTS agents. 1477 Pre-or-ongoing-mitigation telemetry attributes may be sent by a DOTS 1478 client or a DOTS server. 1480 DOTS agents SHOULD bind pre-or-ongoing-mitigation telemetry data with 1481 mitigation requests relying upon the target clause. In particular, a 1482 telemetry PUT request sent after a mitigation request may include a 1483 reference to that mitigation request ('mid-list') as shown in 1484 Figure 22. An example illustrating requests correlation by means of 1485 'target-prefix' is shown in Figure 23. 1487 When generating telemetry data to send to a peer, the DOTS agent must 1488 auto-scale so that appropriate unit(s) are used. 1490 +-----------+ +-----------+ 1491 |DOTS client| |DOTS server| 1492 +-----------+ +-----------+ 1493 | | 1494 |=========Mitigation Request (mid)=====================>| 1495 | | 1496 |================ Telemetry (mid-list{mid})============>| 1497 | | 1499 Figure 22: Example of Request Correlation using 'mid' 1501 +-----------+ +-----------+ 1502 |DOTS client| |DOTS server| 1503 +-----------+ +-----------+ 1504 | | 1505 |<=============== Telemetry (target-prefix)=============| 1506 | | 1507 |=========Mitigation Request (target-prefix)===========>| 1508 | | 1510 Figure 23: Example of Request Correlation using Target Prefix 1512 DOTS agents MUST NOT send pre-or-ongoing-mitigation telemetry 1513 notifications to the same peer more frequently than once every 1514 'telemetry-notify-interval' (Section 6.1). If a telemetry 1515 notification is sent using a block-like transfer mechanism (e.g., 1516 [I-D.bosh-core-new-block]), this rate limit policy MUST NOT consider 1517 these individual blocks as separate notifications, but as a single 1518 notification. 1520 DOTS pre-or-ongoing-mitigation telemetry request and response 1521 messages MUST be marked as Non-Confirmable messages. 1523 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1524 +--:(telemetry-setup) {dots-telemetry}? 1525 | +--rw telemetry* [cuid tsid] 1526 | ... 1527 +--:(telemetry) {dots-telemetry}? 1528 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1529 +--rw cuid string 1530 +--rw cdid? string 1531 +--rw tmid uint32 1532 +--rw target 1533 | ... 1534 +--rw total-traffic* [unit] 1535 | ... 1536 +--rw total-traffic-protocol* [unit protocol] 1537 | ... 1538 +--rw total-traffic-port* [unit port] 1539 | ... 1540 +--rw total-attack-traffic* [unit] 1541 | ... 1542 +--rw total-attack-traffic-protocol* [unit protocol] 1543 | ... 1544 +--rw total-attack-traffic-port* [unit port] 1545 | ... 1546 +--rw total-attack-connection 1547 | ... 1548 +--rw total-attack-connection-port 1549 | ... 1550 +--rw attack-detail* [vendor-id attack-id] 1551 ... 1553 Figure 24: Telemetry Message Type Tree Structure 1555 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes 1557 The description and motivation behind each attribute are presented in 1558 Section 3. DOTS telemetry attributes are optionally signaled and 1559 therefore MUST NOT be treated as mandatory fields in the DOTS signal 1560 channel protocol. 1562 7.1.1. Target 1564 A target resource (Figure 25) is identified using the attributes 1565 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1566 fqdn', 'target-uri', 'alias-name', or a pointer to a mitigation 1567 request ('mid-list'). 1569 +--:(telemetry) {dots-telemetry}? 1570 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1571 +--rw cuid string 1572 +--rw cdid? string 1573 +--rw tmid uint32 1574 +--rw target 1575 | +--rw target-prefix* inet:ip-prefix 1576 | +--rw target-port-range* [lower-port] 1577 | | +--rw lower-port inet:port-number 1578 | | +--rw upper-port? inet:port-number 1579 | +--rw target-protocol* uint8 1580 | +--rw target-fqdn* inet:domain-name 1581 | +--rw target-uri* inet:uri 1582 | +--rw alias-name* string 1583 | +--rw mid-list* uint32 1584 +--rw total-traffic* [unit] 1585 | ... 1586 +--rw total-traffic-protocol* [unit protocol] 1587 | ... 1588 +--rw total-traffic-port* [unit port] 1589 | ... 1590 +--rw total-attack-traffic* [unit] 1591 | ... 1592 +--rw total-attack-traffic-protocol* [unit protocol] 1593 | ... 1594 +--rw total-attack-traffic-port* [unit port] 1595 | ... 1596 +--rw total-attack-connection 1597 | ... 1598 +--rw total-attack-connection-port 1599 | ... 1600 +--rw attack-detail* [vendor-id attack-id] 1601 ... 1603 Figure 25: Target Tree Structure 1605 At least one of the attributes 'target-prefix', 'target-fqdn', 1606 'target-uri', 'alias-name', or 'mid-list' MUST be present in the 1607 target definition. 1609 If the target is subjected to bandwidth consuming attack, the 1610 attributes representing the percentile values of the 'attack-id' 1611 attack traffic are included. 1613 If the target is subjected to resource consuming DDoS attacks, the 1614 same attributes defined for Section 7.1.4 are applicable for 1615 representing the attack. 1617 This is an optional sub-attribute. 1619 7.1.2. Total Traffic 1621 The 'total-traffic' attribute (Figure 26) conveys the percentile 1622 values of total traffic observed during a DDoS attack. More granular 1623 total traffic can be conveyed in 'total-traffic-protocol' and 'total- 1624 traffic-port'. 1626 The 'total-traffic-protocol' represents the total traffic for a 1627 target and is transport-protocol specific. 1629 The 'total-traffic-port' represents the total traffic for a target 1630 per port number. 1632 +--:(telemetry) {dots-telemetry}? 1633 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1634 +--rw cuid string 1635 +--rw cdid? string 1636 +--rw tmid uint32 1637 +--rw target 1638 | ... 1639 +--rw total-traffic* [unit] 1640 | +--rw unit unit 1641 | +--rw low-percentile-g? yang:gauge64 1642 | +--rw mid-percentile-g? yang:gauge64 1643 | +--rw high-percentile-g? yang:gauge64 1644 | +--rw peak-g? yang:gauge64 1645 +--rw total-traffic-protocol* [unit protocol] 1646 | +--rw protocol uint8 1647 | +--rw unit unit 1648 | +--rw low-percentile-g? yang:gauge64 1649 | +--rw mid-percentile-g? yang:gauge64 1650 | +--rw high-percentile-g? yang:gauge64 1651 | +--rw peak-g? yang:gauge64 1652 +--rw total-traffic-port* [unit port] 1653 | +--rw port inet:port-number 1654 | +--rw unit unit 1655 | +--rw low-percentile-g? yang:gauge64 1656 | +--rw mid-percentile-g? yang:gauge64 1657 | +--rw high-percentile-g? yang:gauge64 1658 | +--rw peak-g? yang:gauge64 1659 +--rw total-attack-traffic* [unit] 1660 | ... 1661 +--rw total-attack-traffic-protocol* [unit protocol] 1662 | ... 1663 +--rw total-attack-traffic-port* [unit port] 1664 | ... 1665 +--rw total-attack-connection 1666 | ... 1667 +--rw total-attack-connection-port 1668 | ... 1669 +--rw attack-detail* [vendor-id attack-id] 1670 ... 1672 Figure 26: Total Traffic Tree Structure 1674 7.1.3. Total Attack Traffic 1676 The 'total-attack-traffic' attribute (Figure 27) conveys the total 1677 attack traffic identified by the DOTS client domain's DMS (or DDoS 1678 Detector). More granular total traffic can be conveyed in 'total- 1679 attack-traffic-protocol' and 'total-attack-traffic-port'. 1681 The 'total-attack-traffic-protocol' represents the total attack 1682 traffic for a target and is transport-protocol specific. 1684 The 'total-attack-traffic-port' represents the total attack traffic 1685 for a target per port number. 1687 +--:(telemetry) {dots-telemetry}? 1688 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1689 +--rw cuid string 1690 +--rw cdid? string 1691 +--rw tmid uint32 1692 +--rw target 1693 | ... 1694 +--rw total-traffic* [unit] 1695 | ... 1696 +--rw total-traffic-protocol* [unit protocol] 1697 | ... 1698 +--rw total-traffic-port* [unit port] 1699 | ... 1700 +--rw total-attack-traffic* [unit] 1701 | +--rw unit unit 1702 | +--rw low-percentile-g? yang:gauge64 1703 | +--rw mid-percentile-g? yang:gauge64 1704 | +--rw high-percentile-g? yang:gauge64 1705 | +--rw peak-g? yang:gauge64 1706 +--rw total-attack-traffic-protocol* [unit protocol] 1707 | +--rw protocol uint8 1708 | +--rw unit unit 1709 | +--rw low-percentile-g? yang:gauge64 1710 | +--rw mid-percentile-g? yang:gauge64 1711 | +--rw high-percentile-g? yang:gauge64 1712 | +--rw peak-g? yang:gauge64 1713 +--rw total-attack-traffic-port* [unit port] 1714 | +--rw port inet:port-number 1715 | +--rw unit unit 1716 | +--rw low-percentile-g? yang:gauge64 1717 | +--rw mid-percentile-g? yang:gauge64 1718 | +--rw high-percentile-g? yang:gauge64 1719 | +--rw peak-g? yang:gauge64 1720 +--rw total-attack-connection 1721 | ... 1722 +--rw total-attack-connection-port 1723 | ... 1724 +--rw attack-detail* [vendor-id attack-id] 1725 ... 1727 Figure 27: Total Attack Traffic Tree Structure 1729 7.1.4. Total Attack Connections 1731 If the target is subjected to resource consuming DDoS attack, the 1732 'total-attack-connection' attribute is used to convey the percentile 1733 values of total attack connections. The following optional sub- 1734 attributes for the target per transport-protocol are included to 1735 represent the attack characteristics: 1737 o The number of simultaneous attack connections to the target. 1738 o The number of simultaneous embryonic connections to the target. 1739 o The number of attack connections per second to the target. 1740 o The number of attack requests to the target. 1742 The total attack connections per port number is represented using 1743 'total-attack-connection-port' attribute. 1745 +--:(telemetry) {dots-telemetry}? 1746 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1747 +--rw cuid string 1748 +--rw cdid? string 1749 +--rw tmid uint32 1750 +--rw target 1751 | ... 1752 +--rw total-attack-connection 1753 | +--rw low-percentile-l* [protocol] 1754 | | +--rw protocol uint8 1755 | | +--rw connection? yang:gauge64 1756 | | +--rw embryonic? yang:gauge64 1757 | | +--rw connection-ps? yang:gauge64 1758 | | +--rw request-ps? yang:gauge64 1759 | | +--rw partial-request-ps? yang:gauge64 1760 | +--rw mid-percentile-l* [protocol] 1761 | | +--rw protocol uint8 1762 | | +--rw connection? yang:gauge64 1763 | | +--rw embryonic? yang:gauge64 1764 | | +--rw connection-ps? yang:gauge64 1765 | | +--rw request-ps? yang:gauge64 1766 | | +--rw partial-request-ps? yang:gauge64 1767 | +--rw high-percentile-l* [protocol] 1768 | | +--rw protocol uint8 1769 | | +--rw connection? yang:gauge64 1770 | | +--rw embryonic? yang:gauge64 1771 | | +--rw connection-ps? yang:gauge64 1772 | | +--rw request-ps? yang:gauge64 1773 | | +--rw partial-request-ps? yang:gauge64 1774 | +--rw peak-l* [protocol] 1775 | +--rw protocol uint8 1776 | +--rw connection? yang:gauge64 1777 | +--rw embryonic? yang:gauge64 1778 | +--rw connection-ps? yang:gauge64 1779 | +--rw request-ps? yang:gauge64 1780 | +--rw partial-request-ps? yang:gauge64 1781 +--rw total-attack-connection-port 1782 | +--rw low-percentile-l* [protocol port] 1783 | | +--rw port inet:port-number 1784 | | +--rw protocol uint8 1785 | | +--rw connection? yang:gauge64 1786 | | +--rw embryonic? yang:gauge64 1787 | | +--rw connection-ps? yang:gauge64 1788 | | +--rw request-ps? yang:gauge64 1789 | | +--rw partial-request-ps? yang:gauge64 1790 | +--rw mid-percentile-l* [protocol port] 1791 | | +--rw port inet:port-number 1792 | | +--rw protocol uint8 1793 | | +--rw connection? yang:gauge64 1794 | | +--rw embryonic? yang:gauge64 1795 | | +--rw connection-ps? yang:gauge64 1796 | | +--rw request-ps? yang:gauge64 1797 | | +--rw partial-request-ps? yang:gauge64 1798 | +--rw high-percentile-l* [protocol port] 1799 | | +--rw port inet:port-number 1800 | | +--rw protocol uint8 1801 | | +--rw connection? yang:gauge64 1802 | | +--rw embryonic? yang:gauge64 1803 | | +--rw connection-ps? yang:gauge64 1804 | | +--rw request-ps? yang:gauge64 1805 | | +--rw partial-request-ps? yang:gauge64 1806 | +--rw peak-l* [protocol port] 1807 | +--rw port inet:port-number 1808 | +--rw protocol uint8 1809 | +--rw connection? yang:gauge64 1810 | +--rw embryonic? yang:gauge64 1811 | +--rw connection-ps? yang:gauge64 1812 | +--rw request-ps? yang:gauge64 1813 | +--rw partial-request-ps? yang:gauge64 1814 +--rw attack-detail* [vendor-id attack-id] 1815 ... 1817 Figure 28: Total Attack Connections Tree Structure 1819 7.1.5. Attack Details 1821 This attribute (Figure 29) is used to signal a set of details 1822 characterizing an attack. The following sub-attributes describing 1823 the on-going attack can be signal as attack details. 1825 vendor-id: Vendor ID is a security vendor's Enterprise Number as 1826 registered with IANA [Enterprise-Numbers]. It is a four-byte 1827 integer value. 1829 attack-id: Unique identifier assigned for the attack. 1831 attack-name: Textual representation of the attack description. 1832 Natural Language Processing techniques (e.g., word embedding) can 1833 possibly be used to map the attack description to an attack type. 1834 Textual representation of attack solves two problems: (a) avoids 1835 the need to create mapping tables manually between vendors and (b) 1836 avoids the need to standardize attack types which keep evolving. 1838 attack-severity: Attack severity level. This attribute takes one of 1839 the values defined in Section 3.12.2 of [RFC7970]. 1841 start-time: The time the attack started. The attack's start time is 1842 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1843 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1844 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1846 end-time: The time the attack ended. The attack end time is 1847 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1848 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1849 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1851 source-count: A count of sources involved in the attack targeting 1852 the victim. 1854 top-talkers: A list of top talkers among attack sources. The top 1855 talkers are represented using the 'source-prefix'. 1857 'spoofed-status' indicates whether a top talker is a spoofed IP 1858 address (e.g., reflection attacks) or not. 1860 If the target is subjected to a bandwidth consuming attack, the 1861 attack traffic from each of the top talkers is included ('total- 1862 attack-traffic', Section 7.1.3). 1864 If the target is subjected to a resource consuming DDoS attack, 1865 the same attributes defined in Section 7.1.4 are applicable for 1866 representing the attack per talker. 1868 +--:(telemetry) {dots-telemetry}? 1869 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1870 +--rw cuid string 1871 +--rw cdid? string 1872 +--rw tmid uint32 1873 +--rw target 1874 | ... 1875 +--rw attack-detail* [vendor-id attack-id] 1876 +--rw vendor-id uint32 1877 +--rw attack-id uint32 1878 +--rw attack-name? string 1879 +--rw attack-severity? attack-severity 1880 +--rw start-time? uint64 1881 +--rw end-time? uint64 1882 +--rw top-talker 1883 +--rw talker* [source-prefix] 1884 +--rw spoofed-status? boolean 1885 +--rw source-prefix inet:ip-prefix 1886 +--rw source-port-range* [lower-port] 1887 | +--rw lower-port inet:port-number 1888 | +--rw upper-port? inet:port-number 1889 +--rw source-icmp-type-range* [lower-type] 1890 | +--rw lower-type uint8 1891 | +--rw upper-type? uint8 1892 +--rw total-attack-traffic* [unit] 1893 | +--rw unit unit 1894 | +--rw low-percentile-g? yang:gauge64 1895 | +--rw mid-percentile-g? yang:gauge64 1896 | +--rw high-percentile-g? yang:gauge64 1897 | +--rw peak-g? yang:gauge64 1898 +--rw total-attack-connection 1899 +--rw low-percentile-l* [protocol] 1900 | ... 1901 +--rw mid-percentile-l* [protocol] 1902 | ... 1903 +--rw high-percentile-l* [protocol] 1904 | ... 1905 +--rw peak-l* [protocol] 1906 ... 1908 Figure 29: Attack Detail Tree Structure 1910 In order to optimize the size of telemetry data conveyed over the 1911 DOTS signal channel, DOTS agents MAY use the DOTS data channel 1912 [RFC8783] to exchange vendor-specific attack mapping details (that 1913 is, {vendor identifier, attack identifier} ==> attack name). As 1914 such, DOTS agents do not have to convey systematically an attack name 1915 in their telemetry messages over the DOTS signal channel. The "ietf- 1916 dots-mapping" YANG module defined in Section 9.2) augments the "ietf- 1917 dots-data-channel". The tree structure of this module is shown in 1918 Figure 30. 1920 module: ietf-dots-mapping 1921 augment /ietf-data:dots-data/ietf-data:dots-client: 1922 +--rw vendor-mapping {dots-telemetry}? 1923 +--rw vendor* [vendor-id] 1924 +--rw vendor-id uint32 1925 +--rw attack-mapping* [attack-id] 1926 +--rw attack-id uint32 1927 +--rw attack-name string 1928 augment /ietf-data:dots-data/ietf-data:capabilities: 1929 +--ro vendor-mapping-enabled? boolean {dots-telemetry}? 1930 augment /ietf-data:dots-data: 1931 +--ro vendor-mapping {dots-telemetry}? 1932 +--ro vendor* [vendor-id] 1933 +--ro vendor-id uint32 1934 +--ro attack-mapping* [attack-id] 1935 +--ro attack-id uint32 1936 +--ro attack-name string 1938 Figure 30: Vendor Attack Mapping Tree Structure 1940 A DOTS client sends a GET request to retrieve the capabilities 1941 supported by a DOTS server as per Section 7.1 of [RFC8783]. This 1942 request is meant to assess whether vendor attack mapping details 1943 feature is supported by the server (i.e., check the value of 'vendor- 1944 mapping-enabled'). 1946 If 'vendor-mapping-enabled' is set to 'true', A DOTS client MAY send 1947 a GET request to retrieve the DOTS server's vendor attack mapping 1948 details. An example of such GET request is shown in Figure 31. 1950 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1951 /ietf-dots-mapping:vendor-mapping HTTP/1.1 1952 Host: example.com 1953 Accept: application/yang-data+json 1955 Figure 31: GET to Retrieve the Vendor Attack Mappings of a DOTS 1956 Server 1958 A DOTS client MAY retrieve only the list of vendors supported by the 1959 DOTS server. It does so by setting the "depth" parameter 1960 (Section 4.8.2 of [RFC8040]) to "3" in the GET request as shown in 1961 Figure 32. An example of a response body received from the DOTS 1962 server as a response to such request is illustrated in Figure 33. 1964 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1965 /ietf-dots-mapping:vendor-mapping?depth=3 HTTP/1.1 1966 Host: example.com 1967 Accept: application/yang-data+json 1969 Figure 32: GET to Retrieve the Vendors List used by a DOTS Server 1971 { 1972 "ietf-dots-mapping:vendor-mapping": { 1973 "ietf-dots-mapping:vendor": [ 1974 { 1975 "ietf-dots-mapping:vendor-id": 1234, 1976 "ietf-dots-mapping:attack-mapping": [] 1977 } 1978 ] 1979 } 1980 } 1982 Figure 33: Response to a GET to Retrieve the Vendors List used by a 1983 DOTS Server 1985 The DOTS client reiterates the above procedure regularly (e.g., once 1986 a week) to update the DOTS server's vendor attack mapping details. 1988 If the DOTS client concludes that the DOTS server does not have any 1989 reference to the specific vendor attack mapping details, the DOTS 1990 client uses a POST request to install its vendor attack mapping 1991 details. An example of such POST request is depicted in Figure 34. 1993 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1994 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1995 Host: example.com 1996 Content-Type: application/yang-data+json 1998 { 1999 "ietf-dots-mapping:vendor-mapping": { 2000 "ietf-dots-mapping:vendor": [ 2001 { 2002 "ietf-dots-mapping:vendor-id": 345, 2003 "ietf-dots-mapping:attack-mapping": [ 2004 { 2005 "ietf-dots-mapping:attack-id": 1, 2006 "ietf-dots-mapping:attack-name": 2007 "Include a description of this attack" 2008 }, 2009 { 2010 "ietf-dots-mapping:attack-id": 2, 2011 "ietf-dots-mapping:attack-name": 2012 "Again, include a description of the attack" 2013 } 2014 ] 2015 } 2016 ] 2017 } 2018 } 2020 Figure 34: POST to Install Vendor Attack Mapping Details 2022 The DOTS server indicates the result of processing the POST request 2023 using the status-line. Concretely, "201 Created" status-line MUST be 2024 returned in the response if the DOTS server has accepted the vendor 2025 attack mapping details. If the request is missing a mandatory 2026 attribute or contains an invalid or unknown parameter, "400 Bad 2027 Request" status-line MUST be returned by the DOTS server in the 2028 response. The error-tag is set to "missing-attribute", "invalid- 2029 value", or "unknown-element" as a function of the encountered error. 2031 If the request is received via a server-domain DOTS gateway, but the 2032 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2033 is expected to be supplied, the DOTS server MUST reply with "403 2034 Forbidden" status-line and the error-tag "access-denied". Upon 2035 receipt of this message, the DOTS client MUST register (Section 5.1 2036 of [RFC8783]). 2038 The DOTS client uses the PUT request to modify its vendor attack 2039 mapping details maintained by the DOTS server (e.g., add a new 2040 mapping). 2042 A DOTS client uses a GET request to retrieve its vendor attack 2043 mapping details as maintained by the DOTS server (Figure 35). 2045 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2046 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2047 /ietf-dots-mapping:vendor-mapping?\ 2048 content=all HTTP/1.1 2049 Host: example.com 2050 Accept: application/yang-data+json 2052 Figure 35: GET to Retrieve Installed Vendor Attack Mapping Details 2054 When conveying attack details in DOTS telemetry messages (Sections 2055 7.2, 7.3, and 8), DOTS agents MUST NOT include 'attack-name' 2056 attribute except if the corresponding attack mapping details were not 2057 shared with the peer DOTS agent (e.g., a DOTS server detects a new 2058 attack type). 2060 7.2. From DOTS Clients to DOTS Servers 2062 DOTS clients uses PUT request to signal pre-or-ongoing-mitigation 2063 telemetry to DOTS servers. An example of such request is shown in 2064 Figure 36. 2066 Header: PUT (Code=0.03) 2067 Uri-Path: ".well-known" 2068 Uri-Path: "dots" 2069 Uri-Path: "tm" 2070 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2071 Uri-Path: "tmid=123" 2072 Content-Format: "application/dots+cbor" 2074 { 2075 "ietf-dots-telemetry:telemetry": { 2076 "pre-or-ongoing-mitigation": [ 2077 { 2078 "target": { 2079 "target-prefix": [ 2080 "2001:db8::1/128" 2081 ] 2082 }, 2083 "total-attack-traffic-protocol": [ 2084 { 2085 "protocol": 17, 2086 "unit": "megabit-ps", 2087 "mid-percentile-g": "900" 2088 } 2089 ], 2090 "attack-detail": [ 2091 { 2092 "vendor-id": 1234, 2093 "attack-id": 77, 2094 "start-time": "1957811234", 2095 "attack-severity": "high" 2096 } 2097 ] 2098 } 2099 ] 2100 } 2101 } 2103 Figure 36: PUT to Send Pre-or-Ongoing-Mitigation Telemetry 2105 'cuid' is a mandatory Uri-Path parameter for PUT requests. 2107 The following additional Uri-Path parameter is defined: 2109 tmid: Telemetry Identifier is an identifier for the DOTS pre-or- 2110 ongoing-mitigation telemetry data represented as an integer. 2111 This identifier MUST be generated by DOTS clients. 'tmid' values 2112 MUST increase monotonically (when a new PUT is generated by a 2113 DOTS client to convey pre-or-ongoing-mitigation telemetry). 2115 The procedure specified in Section 4.4.1 of [RFC8782] MUST be 2116 followed for 'tmid' rollover. 2118 This is a mandatory attribute. 2120 'cuid' and 'tmid' MUST NOT appear in the PUT request message body. 2122 At least 'target' attribute and another pre-or-ongoing-mitigation 2123 attributes (Section 7.1) MUST be present in the PUT request. If only 2124 the 'target' attribute is present, this request is handled as per 2125 Section 7.3. 2127 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2128 mitigation telemetry from a DOTS client is determined by comparing 2129 their respective 'tmid' values. If such two requests have 2130 overlapping 'target', the PUT request with higher numeric 'tmid' 2131 value will override the request with a lower numeric 'tmid' value. 2132 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2133 no longer be available. 2135 The DOTS server indicates the result of processing a PUT request 2136 using CoAP response codes. The response code 2.04 (Changed) is 2137 returned if the DOTS server has accepted the pre-or-ongoing- 2138 mitigation telemetry. The error response code 5.03 (Service 2139 Unavailable) is returned if the DOTS server has erred. 5.03 uses Max- 2140 Age option to indicate the number of seconds after which to retry. 2142 How long a DOTS server maintains a 'tmid' as active or logs the 2143 enclosed telemetry information is implementation-specific. Note that 2144 if a 'tmid' is still active, then logging details are updated by the 2145 DOTS server as a function of the updates received from the peer DOTS 2146 client. 2148 A DOTS client that lost the state of its active 'tmids' or has to set 2149 'tmid' back to zero (e.g., crash or restart) MUST send a GET request 2150 to the DOTS server to retrieve the list of active 'tmid'. The DOTS 2151 client may then delete 'tmids' that should not be active anymore 2152 (Figure 37). Sending a DELETE with no 'tmid' indicates that all 2153 'tmids' must be deactivated (Figure 38). 2155 Header: DELETE (Code=0.04) 2156 Uri-Path: ".well-known" 2157 Uri-Path: "dots" 2158 Uri-Path: "tm" 2159 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2160 Uri-Path: "tmid=123" 2162 Figure 37: Delete a Pre-or-Ongoing-Mitigation Telemetry 2164 Header: DELETE (Code=0.04) 2165 Uri-Path: ".well-known" 2166 Uri-Path: "dots" 2167 Uri-Path: "tm" 2168 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2170 Figure 38: Delete All Pre-or-Ongoing-Mitigation Telemetry 2172 7.3. From DOTS Servers to DOTS Clients 2174 The pre-or-ongoing-mitigation (attack details, in particular) can 2175 also be signaled from DOTS servers to DOTS clients. For example, the 2176 DOTS server co-located with a DDoS detector collects monitoring 2177 information from the target network, identifies DDoS attack using 2178 statistical analysis or deep learning techniques, and signals the 2179 attack details to the DOTS client. 2181 The DOTS client can use the attack details to decide whether to 2182 trigger a DOTS mitigation request or not. Furthermore, the security 2183 operation personnel at the DOTS client domain can use the attack 2184 details to determine the protection strategy and select the 2185 appropriate DOTS server for mitigating the attack. 2187 In order to receive pre-or-ongoing-mitigation telemetry notifications 2188 from a DOTS server, a DOTS client MUST send a PUT (followed by a GET) 2189 with the target filter. An example of such PUT request is shown in 2190 Figure 39. In order to avoid maintaining a long list of such 2191 requests, it is RECOMMENDED that DOTS clients include all targets in 2192 the same request. DOTS servers may be instructed to restrict the 2193 number of pre-or-ongoing-mitigation requests per DOTS client domain. 2194 This request MUST be maintained active by the DOTS server until a 2195 delete request is received from the same DOTS client to clear this 2196 pre-or-ongoing-mitigation telemetry. 2198 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2199 mitigation telemetry from a DOTS client is determined by comparing 2200 their respective 'tmid' values. If such two requests have 2201 overlapping 'target', the PUT request with higher numeric 'tmid' 2202 value will override the request with a lower numeric 'tmid' value. 2203 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2204 no longer be available. 2206 Header: PUT (Code=0.03) 2207 Uri-Path: ".well-known" 2208 Uri-Path: "dots" 2209 Uri-Path: "tm" 2210 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2211 Uri-Path: "tmid=123" 2212 Content-Format: "application/dots+cbor" 2214 { 2215 "ietf-dots-telemetry:telemetry": { 2216 "pre-or-ongoing-mitigation": [ 2217 { 2218 "target": { 2219 "target-prefix": [ 2220 "2001:db8::/32" 2221 ] 2222 } 2223 } 2224 ] 2225 } 2226 } 2228 Figure 39: PUT to Request Pre-or-Ongoing-Mitigation Telemetry 2230 DOTS clients of the same domain can request to receive pre-or- 2231 ongoing-mitigation telemetry bound to the same target. 2233 The DOTS client conveys the Observe Option set to '0' in the GET 2234 request to receive asynchronous notifications carrying pre-or- 2235 ongoing-mitigation telemetry data from the DOTS server. The GET 2236 request specifies a 'tmid' (Figure 40) or not (Figure 41). 2238 Header: GET (Code=0.01) 2239 Uri-Path: ".well-known" 2240 Uri-Path: "dots" 2241 Uri-Path: "tm" 2242 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2243 Uri-Path: "tmid=123" 2244 Observe: 0 2246 Figure 40: GET to Subscribe to Telemetry Asynchronous Notifications 2247 for a Specific 'tmid' 2249 Header: GET (Code=0.01) 2250 Uri-Path: ".well-known" 2251 Uri-Path: "dots" 2252 Uri-Path: "tm" 2253 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2254 Observe: 0 2256 Figure 41: GET to Subscribe to Telemetry Asynchronous Notifications 2257 for All 'tmids' 2259 The DOTS client can filter out the asynchronous notifications from 2260 the DOTS server by indicating one or more Uri-Query options in its 2261 GET request. An Uri-Query option can include the following 2262 parameters: 'target-prefix', 'target-port', 'target-protocol', 2263 'target-fqdn', 'target-uri', 'alias-name', 'mid', and 'c' (content) 2264 (Section 4.4). Furthermore: 2266 If more than one Uri-Query option is included in a request, these 2267 options are interpreted in the same way as when multiple target 2268 clauses are included in a message body. 2270 If multiple values of a query parameter are to be included in a 2271 request, these values MUST be included in the same Uri-Query 2272 option and separated by a "," character without any spaces. 2274 Range values (i.e., contiguous inclusive block) can be included 2275 for 'target-port', 'target-protocol', and 'mid' parameters by 2276 indicating two bound values separated by a "-" character. 2278 Wildcard names (i.e., a name with the leftmost label is the "*" 2279 character) can be included in 'target-fqdn' or 'target-uri' 2280 parameters. DOTS clients MUST NOT include a name in which the "*" 2281 character is included in a label other than the leftmost label. 2282 "*.example.com" is an example of a valid wildcard name that can be 2283 included as a value of the 'target-fqdn' parameter in an Uri-Query 2284 option. 2286 DOTS clients may also filter out the asynchronous notifications from 2287 the DOTS server by indicating a specific source information. To that 2288 aim, a DOTS client may include 'source-prefix', 'source-port', or 2289 'source-icmp-type' in an Uri-Query option. The same considerations 2290 (ranges, multiple values) specified for target clauses apply for 2291 source clauses. Special care SHOULD be taken when using these 2292 filters as some attacks may be hidden to the requesting DOTS client 2293 (e.g., the attack changes its source information). 2295 Requests with invalid query types (e.g., not supported, malformed) by 2296 the DOTS server MUST be rejected by DOTS servers with a 4.00 (Bad 2297 Request). 2299 An example of request to subscribe to asynchronous UDP telemetry 2300 notifications is shown in Figure 42. This filter will be applied for 2301 all 'tmids'. 2303 Header: GET (Code=0.01) 2304 Uri-Path: ".well-known" 2305 Uri-Path: "dots" 2306 Uri-Path: "tm" 2307 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2308 Uri-Query: "target-protocol=17" 2309 Observe: 0 2311 Figure 42: GET Request to Receive Telemetry Asynchronous 2312 Notifications Filtered using Uri-Query 2314 The DOTS server will send asynchronous notifications to the DOTS 2315 client when an attack event is detected following similar 2316 considerations as in Section 4.4.2.1 of [RFC8782]. An example of a 2317 pre-or-ongoing-mitigation telemetry notification is shown in 2318 Figure 43. 2320 { 2321 "ietf-dots-telemetry:telemetry": { 2322 "pre-or-ongoing-mitigation": [ 2323 { 2324 "tmid": 123, 2325 "target": { 2326 "target-prefix": [ 2327 "2001:db8::1/128" 2328 ] 2329 }, 2330 "target-protocol": [ 2331 17 2332 ], 2333 "total-attack-traffic": [ 2334 { 2335 "unit": "megabit-ps", 2336 "mid-percentile-g": "900" 2337 } 2338 ], 2339 "attack-detail": [ 2340 { 2341 "vendor-id": 1234, 2342 "attack-id": 77, 2343 "start-time": "1957818434", 2344 "attack-severity": "high" 2345 } 2346 ] 2347 } 2348 ] 2349 } 2350 } 2352 Figure 43: Message Body of a Pre-or-Ongoing-Mitigation Telemetry 2353 Notification from the DOTS Server 2355 A DOTS server sends the aggregate data for a target using 'total- 2356 attack-traffic' attribute. The aggregate assumes that Uri-Query 2357 filters are applied on the target. The DOTS server MAY include more 2358 granular data when needed (that is, 'total-attack-traffic-protocol' 2359 and 'total-attack-traffic-port'). If a port filter (or protocol 2360 filter) is included in a request, 'total-attack-traffic-protocol' (or 2361 'total-attack-traffic-port') conveys the data with the port (or 2362 protocol) filter applied. 2364 A DOTS server may aggregate pre-or-ongoing-mitigation data (e.g., 2365 'top-talkers') for all targets of a domain, or when justified, send 2366 specific information (e.g., 'top-talkers') per individual targets. 2368 The DOTS client may log pre-or-ongoing-mitigation telemetry data with 2369 an alert sent to an administrator or a network controller. The DOTS 2370 client may send a mitigation request if the attack cannot be handled 2371 locally. 2373 A DOTS client that is not interested to receive pre-or-ongoing- 2374 mitigation telemetry data for a target MUST send a delete request 2375 similar to the one depicted in Figure 37. 2377 8. DOTS Telemetry Mitigation Status Update 2379 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 2380 Attributes 2382 The mitigation efficacy telemetry attributes can be signaled from 2383 DOTS clients to DOTS servers as part of the periodic mitigation 2384 efficacy updates to the server (Section 5.3.4 of [RFC8782]). 2386 Total Attack Traffic: The overall attack traffic as observed from 2387 the DOTS client perspective during an active mitigation. See 2388 Figure 27. 2390 Attack Details: The overall attack details as observed from the 2391 DOTS client perspective during an active mitigation. See 2392 Section 7.1.5. 2394 The "ietf-dots-telemetry" YANG module augments the "mitigation-scope" 2395 type message defined in "ietf-dots-signal" so that these attributes 2396 can be signalled by a DOTS client in a mitigation efficacy update 2397 (Figure 44). 2399 augment /ietf-signal:dots-signal/ietf-signal:message-type 2400 /ietf-signal:mitigation-scope/ietf-signal:scope: 2401 +--rw total-attack-traffic* [unit] {dots-telemetry}? 2402 | ... 2403 +--rw attack-detail* [vendor-id attack-id] {dots-telemetry}? 2404 +--rw vendor-id uint32 2405 +--rw attack-id uint32 2406 +--rw attack-name? string 2407 +--rw attack-severity? attack-severity 2408 +--rw start-time? uint64 2409 +--rw end-time? uint64 2410 +--rw source-count 2411 | ... 2412 +--rw top-talker 2413 ... 2415 Figure 44: Telemetry Efficacy Update Tree Structure 2417 In order to signal telemetry data in a mitigation efficacy update, it 2418 is RECOMMENDED that the DOTS client has already established a DOTS 2419 telemetry setup session with the server in 'idle' time. 2421 Header: PUT (Code=0.03) 2422 Uri-Path: ".well-known" 2423 Uri-Path: "dots" 2424 Uri-Path: "mitigate" 2425 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2426 Uri-Path: "mid=123" 2427 If-Match: 2428 Content-Format: "application/dots+cbor" 2430 { 2431 "ietf-dots-signal-channel:mitigation-scope": { 2432 "scope": [ 2433 { 2434 "alias-name": [ 2435 "https1", 2436 "https2" 2437 ], 2438 "attack-status": "under-attack", 2439 "ietf-dots-telemetry:total-attack-traffic": [ 2440 { 2441 "ietf-dots-telemetry:unit": "megabit-ps", 2442 "ietf-dots-telemetry:mid-percentile-g": "900" 2443 } 2444 ] 2445 } 2446 ] 2447 } 2448 } 2450 Figure 45: An Example of Mitigation Efficacy Update with Telemetry 2451 Attributes 2453 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 2454 Attributes 2456 The mitigation status telemetry attributes can be signaled from the 2457 DOTS server to the DOTS client as part of the periodic mitigation 2458 status update (Section 5.3.3 of [RFC8782]). In particular, DOTS 2459 clients can receive asynchronous notifications of the attack details 2460 from DOTS servers using the Observe option defined in [RFC7641]. 2462 In order to make use of this feature, DOTS clients MUST establish a 2463 telemetry setup session with the DOTS server in 'idle' time and MUST 2464 set the 'server-originated-telemetry' attribute to 'true'. 2466 DOTS servers MUST NOT include telemetry attributes in mitigation 2467 status updates sent to DOTS clients for which 'server-originated- 2468 telemetry' attribute is set to 'false'. 2470 As defined in [RFC8612], the actual mitigation activities can include 2471 several countermeasure mechanisms. The DOTS server signals the 2472 current operational status to each relevant countermeasure. A list 2473 of attacks detected by each countermeasure MAY also be included. The 2474 same attributes defined for Section 7.1.5 are applicable for 2475 describing the attacks detected and mitigated. 2477 The "ietf-dots-telemetry" YANG module (Section 9.1) augments the 2478 "mitigation-scope" type message defined in "ietf-dots-signal" with 2479 telemetry data as depicted in following tree structure: 2481 augment /ietf-signal:dots-signal/ietf-signal:message-type 2482 /ietf-signal:mitigation-scope/ietf-signal:scope: 2483 +--ro total-traffic* [unit] {dots-telemetry}? 2484 | +--ro unit unit 2485 | +--ro low-percentile-g? yang:gauge64 2486 | +--ro mid-percentile-g? yang:gauge64 2487 | +--ro high-percentile-g? yang:gauge64 2488 | +--ro peak-g? yang:gauge64 2489 +--rw total-attack-traffic* [unit] {dots-telemetry}? 2490 | +--rw unit unit 2491 | +--rw low-percentile-g? yang:gauge64 2492 | +--rw mid-percentile-g? yang:gauge64 2493 | +--rw high-percentile-g? yang:gauge64 2494 | +--rw peak-g? yang:gauge64 2495 +--ro total-attack-connection {dots-telemetry}? 2496 | +--ro low-percentile-c 2497 | | +--ro connection? yang:gauge64 2498 | | +--ro embryonic? yang:gauge64 2499 | | +--ro connection-ps? yang:gauge64 2500 | | +--ro request-ps? yang:gauge64 2501 | | +--ro partial-request-ps? yang:gauge64 2502 | +--ro mid-percentile-c 2503 | | ... 2504 | +--ro high-percentile-c 2505 | | ... 2506 | +--ro peak-c 2507 | ... 2508 +--rw attack-detail* [vendor-id attack-id] {dots-telemetry}? 2509 +--rw vendor-id uint32 2510 +--rw attack-id uint32 2511 +--rw attack-name? string 2512 +--rw attack-severity? attack-severity 2513 +--rw start-time? uint64 2514 +--rw end-time? uint64 2515 +--rw source-count 2516 | +--rw low-percentile-g? yang:gauge64 2517 | +--rw mid-percentile-g? yang:gauge64 2518 | +--rw high-percentile-g? yang:gauge64 2519 | +--rw peak-g? yang:gauge64 2520 +--rw top-talker 2521 +--rw talker* [source-prefix] 2522 +--rw spoofed-status? boolean 2523 +--rw source-prefix inet:ip-prefix 2524 +--rw source-port-range* [lower-port] 2525 | +--rw lower-port inet:port-number 2526 | +--rw upper-port? inet:port-number 2527 +--rw source-icmp-type-range* [lower-type] 2528 | +--rw lower-type uint8 2529 | +--rw upper-type? uint8 2530 +--rw total-attack-traffic* [unit] 2531 | +--rw unit unit 2532 | +--rw low-percentile-g? yang:gauge64 2533 | +--rw mid-percentile-g? yang:gauge64 2534 | +--rw high-percentile-g? yang:gauge64 2535 | +--rw peak-g? yang:gauge64 2536 +--rw total-attack-connection 2537 +--rw low-percentile-c 2538 | +--rw connection? yang:gauge64 2539 | +--rw embryonic? yang:gauge64 2540 | +--rw connection-ps? yang:gauge64 2541 | +--rw request-ps? yang:gauge64 2542 | +--rw partial-request-ps? yang:gauge64 2543 +--rw mid-percentile-c 2544 | ... 2545 +--rw high-percentile-c 2546 | ... 2547 +--rw peak-c 2548 ... 2550 Figure 46 shows an example of an asynchronous notification of attack 2551 mitigation status from the DOTS server. This notification signals 2552 both the mid-percentile value of processed attack traffic and the 2553 peak percentile value of unique sources involved in the attack. 2555 { 2556 "ietf-dots-signal-channel:mitigation-scope": { 2557 "scope": [ 2558 { 2559 "mid": 12332, 2560 "mitigation-start": "1507818434", 2561 "alias-name": [ 2562 "https1", 2563 "https2" 2564 ], 2565 "lifetime": 1600, 2566 "status": "attack-successfully-mitigated", 2567 "bytes-dropped": "134334555", 2568 "bps-dropped": "43344", 2569 "pkts-dropped": "333334444", 2570 "pps-dropped": "432432", 2571 "ietf-dots-telemetry:total-attack-traffic": [ 2572 { 2573 "ietf-dots-telemetry:unit": "megabit-ps", 2574 "ietf-dots-telemetry:mid-percentile-g": "900" 2575 } 2576 ], 2577 "ietf-dots-telemetry::attack-detail": [ 2578 { 2579 "ietf-dots-telemetry:vendor-id": 1234, 2580 "ietf-dots-telemetry:attack-id": 77, 2581 "ietf-dots-telemetry:source-count": { 2582 "ietf-dots-telemetry:peak-g": "10000" 2583 } 2584 } 2585 ] 2586 } 2587 ] 2588 } 2589 } 2591 Figure 46: Response Body of a Mitigation Status With Telemetry 2592 Attributes 2594 DOTS clients can filter out the asynchronous notifications from the 2595 DOTS server by indicating one or more Uri-Query options in its GET 2596 request. A Uri-Query option can include the following parameters: 2597 'target-prefix', 'target-port', 'target-protocol', 'target-fqdn', 2598 'target-uri', 'alias-name', and 'c' (content) (Section 4.4). The 2599 considerations discussed in Section 7.3 MUST be followed to include 2600 multiple query values, ranges ('target-port', 'target-protocol'), and 2601 wildcard name ('target-fqdn', 'target-uri'). 2603 An example of request to subscribe to asynchronous notifications 2604 bound to the "http1" alias is shown in Figure 47. 2606 Header: GET (Code=0.01) 2607 Uri-Path: ".well-known" 2608 Uri-Path: "dots" 2609 Uri-Path: "mitigate" 2610 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2611 Uri-Path: "mid=12332" 2612 Uri-Query: "target-alias=https1" 2613 Observe: 0 2615 Figure 47: GET Request to Receive Asynchronous Notifications Filtered 2616 using Uri-Query 2618 If the target query does not match the target of the enclosed 'mid' 2619 as maintained by the DOTS server, the latter MUST respond with a 4.04 2620 (Not Found) error response code. The DOTS server MUST NOT add a new 2621 observe entry if this query overlaps with an existing one. 2623 9. YANG Modules 2625 9.1. DOTS Signal Channel Telemetry YANG Module 2627 This module uses types defined in [RFC6991] and [RFC8345]. 2629 file "ietf-dots-telemetry@2020-05-04.yang" 2630 module ietf-dots-telemetry { 2631 yang-version 1.1; 2632 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 2633 prefix dots-telemetry; 2635 import ietf-dots-signal-channel { 2636 prefix ietf-signal; 2637 reference 2638 "RFC 8782: Distributed Denial-of-Service Open Threat 2639 Signaling (DOTS) Signal Channel Specification"; 2640 } 2641 import ietf-dots-data-channel { 2642 prefix ietf-data; 2643 reference 2644 "RFC 8783: Distributed Denial-of-Service Open Threat 2645 Signaling (DOTS) Data Channel Specification"; 2646 } 2647 import ietf-yang-types { 2648 prefix yang; 2649 reference 2650 "Section 3 of RFC 6991"; 2652 } 2653 import ietf-inet-types { 2654 prefix inet; 2655 reference 2656 "Section 4 of RFC 6991"; 2657 } 2658 import ietf-network-topology { 2659 prefix nt; 2660 reference 2661 "Section 6.2 of RFC 8345: A YANG Data Model for Network 2662 Topologies"; 2663 } 2665 organization 2666 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2667 contact 2668 "WG Web: 2669 WG List: 2671 Author: Mohamed Boucadair 2672 2674 Author: Konda, Tirumaleswar Reddy 2675 "; 2676 description 2677 "This module contains YANG definitions for the signaling 2678 of DOTS telemetry exchanged between a DOTS client and 2679 a DOTS server, by means of the DOTS signal channel. 2681 Copyright (c) 2020 IETF Trust and the persons identified as 2682 authors of the code. All rights reserved. 2684 Redistribution and use in source and binary forms, with or 2685 without modification, is permitted pursuant to, and subject 2686 to the license terms contained in, the Simplified BSD License 2687 set forth in Section 4.c of the IETF Trust's Legal Provisions 2688 Relating to IETF Documents 2689 (http://trustee.ietf.org/license-info). 2691 This version of this YANG module is part of RFC XXXX; see 2692 the RFC itself for full legal notices."; 2694 revision 2020-05-04 { 2695 description 2696 "Initial revision."; 2697 reference 2698 "RFC XXXX: Distributed Denial-of-Service Open Threat 2699 Signaling (DOTS) Telemetry"; 2701 } 2703 feature dots-telemetry { 2704 description 2705 "This feature indicates that the DOTS signal channel is able 2706 to convey DOTS telemetry data between DOTS clients and 2707 servers."; 2708 } 2710 typedef attack-severity { 2711 type enumeration { 2712 enum none { 2713 value 1; 2714 description 2715 "No effect on the DOTS client domain."; 2716 } 2717 enum low { 2718 value 2; 2719 description 2720 "Minimal effect on the DOTS client domain."; 2721 } 2722 enum medium { 2723 value 3; 2724 description 2725 "A subset of DOTS client domain resources are 2726 out of service."; 2727 } 2728 enum high { 2729 value 4; 2730 description 2731 "The DOTS client domain is under extremly severe 2732 conditions."; 2733 } 2734 enum unknown { 2735 value 5; 2736 description 2737 "The impact of the attack is not known."; 2738 } 2739 } 2740 description 2741 "Enumeration for attack severity."; 2742 reference 2743 "RFC 7970: The Incident Object Description Exchange 2744 Format Version 2"; 2745 } 2747 typedef unit-type { 2748 type enumeration { 2749 enum packet-ps { 2750 value 1; 2751 description 2752 "Packets per second (pps)."; 2753 } 2754 enum bit-ps { 2755 value 2; 2756 description 2757 "Bits per Second (bit/s)."; 2758 } 2759 enum byte-ps { 2760 value 3; 2761 description 2762 "Bytes per second (Byte/s)."; 2763 } 2764 } 2765 description 2766 "Enumeration to indicate which unit type is used."; 2767 } 2769 typedef unit { 2770 type enumeration { 2771 enum packet-ps { 2772 value 1; 2773 description 2774 "Packets per second (pps)."; 2775 } 2776 enum bit-ps { 2777 value 2; 2778 description 2779 "Bits per Second (bps)."; 2780 } 2781 enum byte-ps { 2782 value 3; 2783 description 2784 "Bytes per second (Bps)."; 2785 } 2786 enum kilopacket-ps { 2787 value 4; 2788 description 2789 "Kilo packets per second (kpps)."; 2790 } 2791 enum kilobit-ps { 2792 value 5; 2793 description 2794 "Kilobits per second (kbps)."; 2795 } 2796 enum kilobyte-ps { 2797 value 6; 2798 description 2799 "Kilobytes per second (kBps)."; 2800 } 2801 enum megapacket-ps { 2802 value 7; 2803 description 2804 "Mega packets per second (Mpps)."; 2805 } 2806 enum megabit-ps { 2807 value 8; 2808 description 2809 "Megabits per second (Mbps)."; 2810 } 2811 enum megabyte-ps { 2812 value 9; 2813 description 2814 "Megabytes per second (MBps)."; 2815 } 2816 enum gigapacket-ps { 2817 value 10; 2818 description 2819 "Giga packets per second (Gpps)."; 2820 } 2821 enum gigabit-ps { 2822 value 11; 2823 description 2824 "Gigabits per second (Gbps)."; 2825 } 2826 enum gigabyte-ps { 2827 value 12; 2828 description 2829 "Gigabytes per second (GBps)."; 2830 } 2831 enum terapacket-ps { 2832 value 13; 2833 description 2834 "Tera packets per second (Tpps)."; 2835 } 2836 enum terabit-ps { 2837 value 14; 2838 description 2839 "Terabits per second (Tbps)."; 2840 } 2841 enum terabyte-ps { 2842 value 15; 2843 description 2844 "Terabytes per second (TBps)."; 2846 } 2847 } 2848 description 2849 "Enumeration to indicate which unit is used."; 2850 } 2852 typedef interval { 2853 type enumeration { 2854 enum hour { 2855 value 1; 2856 description 2857 "Hour."; 2858 } 2859 enum day { 2860 value 2; 2861 description 2862 "Day."; 2863 } 2864 enum week { 2865 value 3; 2866 description 2867 "Week."; 2868 } 2869 enum month { 2870 value 4; 2871 description 2872 "Month."; 2873 } 2874 } 2875 description 2876 "Enumeration to indicate the overall measurement period."; 2877 } 2879 typedef sample { 2880 type enumeration { 2881 enum second { 2882 value 1; 2883 description 2884 " A one second measurement period."; 2885 } 2886 enum 5-seconds { 2887 value 2; 2888 description 2889 "5 seconds measurement period."; 2890 } 2891 enum 30-seconds { 2892 value 3; 2893 description 2894 "30 seconds measurement period."; 2895 } 2896 enum minute { 2897 value 4; 2898 description 2899 "One minute measurement period."; 2900 } 2901 enum 5-minutes { 2902 value 5; 2903 description 2904 "5 minutes measurement period."; 2905 } 2906 enum 10-minutes { 2907 value 6; 2908 description 2909 "10 minutes measurement period."; 2910 } 2911 enum 30-minutes { 2912 value 7; 2913 description 2914 "30 minutes measurement period."; 2915 } 2916 enum hour { 2917 value 8; 2918 description 2919 "One hour measurement period."; 2920 } 2921 } 2922 description 2923 "Enumeration to indicate the measurement period."; 2924 } 2926 typedef percentile { 2927 type decimal64 { 2928 fraction-digits 2; 2929 } 2930 description 2931 "The nth percentile of a set of data is the 2932 value at which n percent of the data is below it."; 2933 } 2935 typedef query-type { 2936 type enumeration { 2937 enum target-prefix { 2938 value 1; 2939 description 2940 "Query based on target prefix."; 2941 } 2942 enum target-port { 2943 value 2; 2944 description 2945 "Query based on target port number."; 2946 } 2947 enum target-protocol { 2948 value 3; 2949 description 2950 "Query based on target protocol."; 2951 } 2952 enum target-fqdn { 2953 value 4; 2954 description 2955 "Query based on target FQDN."; 2956 } 2957 enum target-uri { 2958 value 5; 2959 description 2960 "Query based on target URI."; 2961 } 2962 enum target-alias { 2963 value 6; 2964 description 2965 "Query based on target alias."; 2966 } 2967 enum mid { 2968 value 7; 2969 description 2970 "Query based on mitigation identifier (mid)."; 2971 } 2972 enum source-prefix { 2973 value 8; 2974 description 2975 "Query based on source prefix."; 2976 } 2977 enum source-port { 2978 value 9; 2979 description 2980 "Query based on source port number."; 2981 } 2982 enum source-icmp-type { 2983 value 10; 2984 description 2985 "Query based on ICMP type"; 2986 } 2987 enum content { 2988 value 11; 2989 description 2990 "Query based on 'c' Uri-Query option that is used 2991 to control the selection of configuration 2992 and non-configuration data nodes."; 2993 reference 2994 "Section 4.4.2 of RFC SSSS."; 2995 } 2996 } 2997 description 2998 "Enumeration support for query types that can be used 2999 in a GET request to filter out data."; 3000 } 3002 grouping percentile-config { 3003 description 3004 "Configuration of low, mid, and high percentile values."; 3005 leaf measurement-interval { 3006 type interval; 3007 description 3008 "Defines the period on which percentiles are computed."; 3009 } 3010 leaf measurement-sample { 3011 type sample; 3012 description 3013 "Defines the time distribution for measuring 3014 values that are used to compute percentiles."; 3015 } 3016 leaf low-percentile { 3017 type percentile; 3018 default "10.00"; 3019 description 3020 "Low percentile. If set to '0', this means low-percentiles 3021 are disabled."; 3022 } 3023 leaf mid-percentile { 3024 type percentile; 3025 must '. >= ../low-percentile' { 3026 error-message 3027 "The mid-percentile must be greater than 3028 or equal to the low-percentile."; 3029 } 3030 default "50.00"; 3031 description 3032 "Mid percentile. If set to the same value as low-percentiles, 3033 this means mid-percentiles are disabled."; 3034 } 3035 leaf high-percentile { 3036 type percentile; 3037 must '. >= ../mid-percentile' { 3038 error-message 3039 "The high-percentile must be greater than 3040 or equal to the mid-percentile."; 3041 } 3042 default "90.00"; 3043 description 3044 "High percentile. If set to the same value as mid-percentiles, 3045 this means high-percentiles are disabled."; 3046 } 3047 } 3049 grouping percentile { 3050 description 3051 "Generic grouping for percentile."; 3052 leaf low-percentile-g { 3053 type yang:gauge64; 3054 description 3055 "Low percentile value."; 3056 } 3057 leaf mid-percentile-g { 3058 type yang:gauge64; 3059 description 3060 "Mid percentile value."; 3061 } 3062 leaf high-percentile-g { 3063 type yang:gauge64; 3064 description 3065 "High percentile value."; 3066 } 3067 leaf peak-g { 3068 type yang:gauge64; 3069 description 3070 "Peak value."; 3071 } 3072 } 3074 grouping unit-config { 3075 description 3076 "Generic grouping for unit configuration."; 3077 list unit-config { 3078 key "unit"; 3079 description 3080 "Controls which unit types are allowed when sharing 3081 telemetry data."; 3082 leaf unit { 3083 type unit-type; 3084 description 3085 "Can be packet-ps, bit-ps, or byte-ps."; 3087 } 3088 leaf unit-status { 3089 type boolean; 3090 mandatory true; 3091 description 3092 "Enable/disable the use of the measurement unit type."; 3093 } 3094 } 3095 } 3097 grouping traffic-unit { 3098 description 3099 "Grouping of traffic as a function of the measurement unit."; 3100 leaf unit { 3101 type unit; 3102 description 3103 "The traffic can be measured using unit types: packet-ps, 3104 bit-ps, or byte-ps. DOTS agents auto-scale to the appropriate 3105 units (e.g., megabit-ps, kilobit-ps)."; 3106 } 3107 uses percentile; 3108 } 3110 grouping traffic-unit-protocol { 3111 description 3112 "Grouping of traffic of a given transport protocol as 3113 a function of the measurement unit."; 3114 leaf protocol { 3115 type uint8; 3116 description 3117 "The transport protocol. 3118 Values are taken from the IANA Protocol Numbers registry: 3119 . 3121 For example, this parameter contains 6 for TCP, 3122 17 for UDP, 33 for DCCP, or 132 for SCTP."; 3123 } 3124 uses traffic-unit; 3125 } 3127 grouping traffic-unit-port { 3128 description 3129 "Grouping of traffic bound to a port number as 3130 a function of the measurement unit."; 3131 leaf port { 3132 type inet:port-number; 3133 description 3134 "Port number."; 3136 } 3137 uses traffic-unit; 3138 } 3140 grouping total-connection-capacity { 3141 description 3142 "Total Connections Capacity. These attributes are 3143 useful to detect resource consuming DDoS attacks"; 3144 leaf connection { 3145 type uint64; 3146 description 3147 "The maximum number of simultaneous connections that 3148 are allowed to the target server."; 3149 } 3150 leaf connection-client { 3151 type uint64; 3152 description 3153 "The maximum number of simultaneous connections that 3154 are allowed to the target server per client."; 3155 } 3156 leaf embryonic { 3157 type uint64; 3158 description 3159 "The maximum number of simultaneous embryonic connections 3160 that are allowed to the target server. The term 'embryonic 3161 connection' refers to a connection whose connection handshake 3162 is not finished. Embryonic connection is only possible in 3163 connection-oriented transport protocols like TCP or SCTP."; 3164 } 3165 leaf embryonic-client { 3166 type uint64; 3167 description 3168 "The maximum number of simultaneous embryonic connections 3169 that are allowed to the target server per client."; 3170 } 3171 leaf connection-ps { 3172 type uint64; 3173 description 3174 "The maximum number of connections allowed per second 3175 to the target server."; 3176 } 3177 leaf connection-client-ps { 3178 type uint64; 3179 description 3180 "The maximum number of connections allowed per second 3181 to the target server per client."; 3182 } 3183 leaf request-ps { 3184 type uint64; 3185 description 3186 "The maximum number of requests allowed per second 3187 to the target server."; 3188 } 3189 leaf request-client-ps { 3190 type uint64; 3191 description 3192 "The maximum number of requests allowed per second 3193 to the target server per client."; 3194 } 3195 leaf partial-request-ps { 3196 type uint64; 3197 description 3198 "The maximum number of partial requests allowed per 3199 second to the target server."; 3200 } 3201 leaf partial-request-client-ps { 3202 type uint64; 3203 description 3204 "The maximum number of partial requests allowed per 3205 second to the target server per client."; 3206 } 3207 } 3209 grouping total-connection-capacity-protocol { 3210 description 3211 "Total Connections Capacity per protocol. These attributes are 3212 useful to detect resource consuming DDoS attacks."; 3213 leaf protocol { 3214 type uint8; 3215 description 3216 "The transport protocol. 3217 Values are taken from the IANA Protocol Numbers registry: 3218 ."; 3219 } 3220 uses total-connection-capacity; 3221 } 3223 grouping connection { 3224 description 3225 "A set of attributes which represent the attack 3226 characteristics"; 3227 leaf connection { 3228 type yang:gauge64; 3229 description 3230 "The number of simultaneous attack connections to 3231 the target server."; 3233 } 3234 leaf embryonic { 3235 type yang:gauge64; 3236 description 3237 "The number of simultaneous embryonic connections to 3238 the target server."; 3239 } 3240 leaf connection-ps { 3241 type yang:gauge64; 3242 description 3243 "The number of attack connections per second to 3244 the target server."; 3245 } 3246 leaf request-ps { 3247 type yang:gauge64; 3248 description 3249 "The number of attack requests per second to 3250 the target server."; 3251 } 3252 leaf partial-request-ps { 3253 type yang:gauge64; 3254 description 3255 "The number of attack partial requests to 3256 the target server."; 3257 } 3258 } 3260 grouping connection-percentile { 3261 description 3262 "Total attack connections."; 3263 container low-percentile-c { 3264 description 3265 "Low percentile of attack connections."; 3266 uses connection; 3267 } 3268 container mid-percentile-c { 3269 description 3270 "Mid percentile of attack connections."; 3271 uses connection; 3272 } 3273 container high-percentile-c { 3274 description 3275 "High percentile of attack connections."; 3276 uses connection; 3277 } 3278 container peak-c { 3279 description 3280 "Peak attack connections."; 3282 uses connection; 3283 } 3284 } 3286 grouping connection-protocol { 3287 description 3288 "Total attack connections."; 3289 leaf protocol { 3290 type uint8; 3291 description 3292 "The transport protocol. 3293 Values are taken from the IANA Protocol Numbers registry: 3294 ."; 3295 } 3296 uses connection; 3297 } 3299 grouping connection-port { 3300 description 3301 "Total attack connections per port number."; 3302 leaf port { 3303 type inet:port-number; 3304 description 3305 "Port number."; 3306 } 3307 uses connection-protocol; 3308 } 3310 grouping connection-protocol-percentile { 3311 description 3312 "Total attack connections per protocol."; 3313 list low-percentile-l { 3314 key "protocol"; 3315 description 3316 "Low percentile of attack connections per protocol."; 3317 uses connection-protocol; 3318 } 3319 list mid-percentile-l { 3320 key "protocol"; 3321 description 3322 "Mid percentile of attack connections per protocol."; 3323 uses connection-protocol; 3324 } 3325 list high-percentile-l { 3326 key "protocol"; 3327 description 3328 "High percentile of attack connections per protocol."; 3329 uses connection-protocol; 3331 } 3332 list peak-l { 3333 key "protocol"; 3334 description 3335 "Peak attack connections per protocol."; 3336 uses connection-protocol; 3337 } 3338 } 3340 grouping connection-protocol-port-percentile { 3341 description 3342 "Total attack connections per port number."; 3343 list low-percentile-l { 3344 key "protocol port"; 3345 description 3346 "Low percentile of attack connections per port number."; 3347 uses connection-port; 3348 } 3349 list mid-percentile-l { 3350 key "protocol port"; 3351 description 3352 "Mid percentile of attack connections per port number."; 3353 uses connection-port; 3354 } 3355 list high-percentile-l { 3356 key "protocol port"; 3357 description 3358 "High percentile of attack connections per port number."; 3359 uses connection-port; 3360 } 3361 list peak-l { 3362 key "protocol port"; 3363 description 3364 "Peak attack connections per port number."; 3365 uses connection-port; 3366 } 3367 } 3369 grouping attack-detail { 3370 description 3371 "Various details that describe the on-going 3372 attacks that need to be mitigated by the DOTS server. 3373 The attack details need to cover well-known and common attacks 3374 (such as a SYN Flood) along with new emerging or vendor-specific 3375 attacks."; 3376 leaf vendor-id { 3377 type uint32; 3378 description 3379 "Vendor ID is a security vendor's Enterprise Number."; 3380 } 3381 leaf attack-id { 3382 type uint32; 3383 description 3384 "Unique identifier assigned by the vendor for the attack."; 3385 } 3386 leaf attack-name { 3387 type string; 3388 description 3389 "Textual representation of attack description. Natural Language 3390 Processing techniques (e.g., word embedding) can possibly be used 3391 to map the attack description to an attack type."; 3392 } 3393 leaf attack-severity { 3394 type attack-severity; 3395 description 3396 "Severity level of an attack. How this level is determined 3397 is implementation-specific."; 3398 } 3399 leaf start-time { 3400 type uint64; 3401 description 3402 "The time the attack started. Start time is represented in seconds 3403 relative to 1970-01-01T00:00:00Z in UTC time."; 3404 } 3405 leaf end-time { 3406 type uint64; 3407 description 3408 "The time the attack ended. End time is represented in seconds 3409 relative to 1970-01-01T00:00:00Z in UTC time."; 3410 } 3411 container source-count { 3412 description 3413 "Indicates the count of unique sources involved 3414 in the attack."; 3415 uses percentile; 3416 } 3417 } 3419 grouping top-talker-aggregate { 3420 description 3421 "Top attack sources."; 3422 list talker { 3423 key "source-prefix"; 3424 description 3425 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3426 leaf spoofed-status { 3427 type boolean; 3428 description 3429 "Indicates whether this address is spoofed."; 3430 } 3431 leaf source-prefix { 3432 type inet:ip-prefix; 3433 description 3434 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3435 } 3436 list source-port-range { 3437 key "lower-port"; 3438 description 3439 "Port range. When only lower-port is 3440 present, it represents a single port number."; 3441 leaf lower-port { 3442 type inet:port-number; 3443 mandatory true; 3444 description 3445 "Lower port number of the port range."; 3446 } 3447 leaf upper-port { 3448 type inet:port-number; 3449 must '. >= ../lower-port' { 3450 error-message 3451 "The upper port number must be greater than 3452 or equal to lower port number."; 3453 } 3454 description 3455 "Upper port number of the port range."; 3456 } 3457 } 3458 list source-icmp-type-range { 3459 key "lower-type"; 3460 description 3461 "ICMP type range. When only lower-type is 3462 present, it represents a single ICMP type."; 3463 leaf lower-type { 3464 type uint8; 3465 mandatory true; 3466 description 3467 "Lower ICMP type of the ICMP type range."; 3468 } 3469 leaf upper-type { 3470 type uint8; 3471 must '. >= ../lower-type' { 3472 error-message 3473 "The upper ICMP type must be greater than 3474 or equal to lower ICMP type."; 3476 } 3477 description 3478 "Upper type of the ICMP type range."; 3479 } 3480 } 3481 list total-attack-traffic { 3482 key "unit"; 3483 description 3484 "Total attack traffic issued from this source."; 3485 uses traffic-unit; 3486 } 3487 container total-attack-connection { 3488 description 3489 "Total attack connections issued from this source."; 3490 uses connection-percentile; 3491 } 3492 } 3493 } 3495 grouping top-talker { 3496 description 3497 "Top attack sources."; 3498 list talker { 3499 key "source-prefix"; 3500 description 3501 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3502 leaf spoofed-status { 3503 type boolean; 3504 description 3505 "Indicates whether this address is spoofed."; 3506 } 3507 leaf source-prefix { 3508 type inet:ip-prefix; 3509 description 3510 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3511 } 3512 list source-port-range { 3513 key "lower-port"; 3514 description 3515 "Port range. When only lower-port is 3516 present, it represents a single port number."; 3517 leaf lower-port { 3518 type inet:port-number; 3519 mandatory true; 3520 description 3521 "Lower port number of the port range."; 3522 } 3523 leaf upper-port { 3524 type inet:port-number; 3525 must '. >= ../lower-port' { 3526 error-message 3527 "The upper port number must be greater than 3528 or equal to lower port number."; 3529 } 3530 description 3531 "Upper port number of the port range."; 3532 } 3533 } 3534 list source-icmp-type-range { 3535 key "lower-type"; 3536 description 3537 "ICMP type range. When only lower-type is 3538 present, it represents a single ICMP type."; 3539 leaf lower-type { 3540 type uint8; 3541 mandatory true; 3542 description 3543 "Lower ICMP type of the ICMP type range."; 3544 } 3545 leaf upper-type { 3546 type uint8; 3547 must '. >= ../lower-type' { 3548 error-message 3549 "The upper ICMP type must be greater than 3550 or equal to lower ICMP type."; 3551 } 3552 description 3553 "Upper type of the ICMP type range."; 3554 } 3555 } 3556 list total-attack-traffic { 3557 key "unit"; 3558 description 3559 "Total attack traffic issued from this source."; 3560 uses traffic-unit; 3561 } 3562 container total-attack-connection { 3563 description 3564 "Total attack connections issued from this source."; 3565 uses connection-protocol-percentile; 3566 } 3567 } 3568 } 3570 grouping baseline { 3571 description 3572 "Grouping for the telemetry baseline."; 3573 uses ietf-data:target; 3574 leaf-list alias-name { 3575 type string; 3576 description 3577 "An alias name that points to a resource."; 3578 } 3579 list total-traffic-normal { 3580 key "unit"; 3581 description 3582 "Total traffic normal baselines."; 3583 uses traffic-unit; 3584 } 3585 list total-traffic-normal-per-protocol { 3586 key "unit protocol"; 3587 description 3588 "Total traffic normal baselines per protocol."; 3589 uses traffic-unit-protocol; 3590 } 3591 list total-traffic-normal-per-port { 3592 key "unit port"; 3593 description 3594 "Total traffic normal baselines per port number."; 3595 uses traffic-unit-port; 3596 } 3597 list total-connection-capacity { 3598 key "protocol"; 3599 description 3600 "Total connection capacity."; 3601 uses total-connection-capacity-protocol; 3602 } 3603 list total-connection-capacity-per-port { 3604 key "protocol port"; 3605 description 3606 "Total connection capacity per port number."; 3607 leaf port { 3608 type inet:port-number; 3609 description 3610 "The target port number."; 3611 } 3612 uses total-connection-capacity-protocol; 3613 } 3614 } 3616 grouping pre-or-ongoing-mitigation { 3617 description 3618 "Grouping for the telemetry data."; 3619 list total-traffic { 3620 key "unit"; 3621 description 3622 "Total traffic."; 3623 uses traffic-unit; 3624 } 3625 list total-traffic-protocol { 3626 key "unit protocol"; 3627 description 3628 "Total traffic per protocol."; 3629 uses traffic-unit-protocol; 3630 } 3631 list total-traffic-port { 3632 key "unit port"; 3633 description 3634 "Total traffic per port."; 3635 uses traffic-unit-port; 3636 } 3637 list total-attack-traffic { 3638 key "unit"; 3639 description 3640 "Total attack traffic."; 3641 uses traffic-unit-protocol; 3642 } 3643 list total-attack-traffic-protocol { 3644 key "unit protocol"; 3645 description 3646 "Total attack traffic per protocol."; 3647 uses traffic-unit-protocol; 3648 } 3649 list total-attack-traffic-port { 3650 key "unit port"; 3651 description 3652 "Total attack traffic per port."; 3653 uses traffic-unit-port; 3654 } 3655 container total-attack-connection { 3656 description 3657 "Total attack connections."; 3658 uses connection-protocol-percentile; 3659 } 3660 container total-attack-connection-port { 3661 description 3662 "Total attack connections."; 3663 uses connection-protocol-port-percentile; 3664 } 3665 list attack-detail { 3666 key "vendor-id attack-id"; 3667 description 3668 "Provides a set of attack details."; 3669 uses attack-detail; 3670 container top-talker { 3671 description 3672 "Lists the top attack sources."; 3673 uses top-talker; 3674 } 3675 } 3676 } 3678 augment "/ietf-signal:dots-signal/ietf-signal:message-type/" 3679 + "ietf-signal:mitigation-scope/ietf-signal:scope" { 3680 if-feature "dots-telemetry"; 3681 description 3682 "Extends mitigation scope with telemetry update data."; 3683 list total-traffic { 3684 key "unit"; 3685 config false; 3686 description 3687 "Total traffic."; 3688 uses traffic-unit; 3689 } 3690 list total-attack-traffic { 3691 key "unit"; 3692 description 3693 "Total attack traffic."; 3694 uses traffic-unit; 3695 } 3696 container total-attack-connection { 3697 config false; 3698 description 3699 "Total attack connections."; 3700 uses connection-percentile; 3701 } 3702 list attack-detail { 3703 key "vendor-id attack-id"; 3704 description 3705 "Atatck details"; 3706 uses attack-detail; 3707 container top-talker { 3708 description 3709 "Top attack sources."; 3710 uses top-talker-aggregate; 3711 } 3712 } 3713 } 3715 augment "/ietf-signal:dots-signal/ietf-signal:message-type" { 3716 if-feature "dots-telemetry"; 3717 description 3718 "Add a new choice to enclose telemetry data in DOTS 3719 signal channel."; 3720 case telemetry-setup { 3721 description 3722 "Indicates the message is about telemetry."; 3723 container max-config-values { 3724 config false; 3725 description 3726 "Maximum acceptable configuration values."; 3727 uses percentile-config; 3728 leaf server-originated-telemetry { 3729 type boolean; 3730 description 3731 "Indicates whether the DOTS server can be instructed 3732 to send pre-or-ongoing-mitigation telemetry. If set to FALSE 3733 or the attribute is not present, this is an indication 3734 that the server does not support this capability."; 3735 } 3736 leaf telemetry-notify-interval { 3737 type uint32 { 3738 range "1 .. 3600"; 3739 } 3740 must '. >= ../../min-config-values/telemetry-notify-interval' { 3741 error-message 3742 "The value must be greater than or equal 3743 to the telemetry-notify-interval in the min-config-values"; 3744 } 3745 units "seconds"; 3746 description 3747 "Minimum number of seconds between successive 3748 telemetry notifications."; 3749 } 3750 } 3751 container min-config-values { 3752 config false; 3753 description 3754 "Minimum acceptable configuration values."; 3755 uses percentile-config; 3756 leaf telemetry-notify-interval { 3757 type uint32 { 3758 range "1 .. 3600"; 3759 } 3760 units "seconds"; 3761 description 3762 "Minimum number of seconds between successive 3763 telemetry notifications."; 3765 } 3766 } 3767 container supported-units { 3768 config false; 3769 description 3770 "Supported units and default activation status."; 3771 uses unit-config; 3772 } 3773 leaf-list query-type { 3774 type query-type; 3775 config false; 3776 description 3777 "Indicates which query types are supported by 3778 the server."; 3779 } 3780 list telemetry { 3781 key "cuid tsid"; 3782 description 3783 "The telemetry data per DOTS client."; 3784 leaf cuid { 3785 type string; 3786 description 3787 "A unique identifier that is 3788 generated by a DOTS client to prevent 3789 request collisions. It is expected that the 3790 cuid will remain consistent throughout the 3791 lifetime of the DOTS client."; 3792 } 3793 leaf cdid { 3794 type string; 3795 description 3796 "The cdid should be included by a server-domain 3797 DOTS gateway to propagate the client domain 3798 identification information from the 3799 gateway's client-facing-side to the gateway's 3800 server-facing-side, and from the gateway's 3801 server-facing-side to the DOTS server. 3803 It may be used by the final DOTS server 3804 for policy enforcement purposes."; 3805 } 3806 leaf tsid { 3807 type uint32; 3808 description 3809 "An identifier for the DOTS telemetry setup 3810 data."; 3811 } 3812 choice setup-type { 3813 description 3814 "Can be a mitigation configuration, a pipe capacity, 3815 or baseline message."; 3816 case telemetry-config { 3817 description 3818 "Uses to set low, mid, and high percentile values."; 3819 container current-config { 3820 description 3821 "Current configuration values."; 3822 uses percentile-config; 3823 uses unit-config; 3824 leaf server-originated-telemetry { 3825 type boolean; 3826 description 3827 "Used by a DOTS client to enable/disable whether it 3828 accepts pre-or-ongoing-mitigation telemetry from 3829 the DOTS server."; 3830 } 3831 leaf telemetry-notify-interval { 3832 type uint32 { 3833 range "1 .. 3600"; 3834 } 3835 units "seconds"; 3836 description 3837 "Minimum number of seconds between successive 3838 telemetry notifications."; 3839 } 3840 } 3841 } 3842 case pipe { 3843 description 3844 "Total pipe capacity of a DOTS client domain"; 3845 list total-pipe-capacity { 3846 key "link-id unit"; 3847 description 3848 "Total pipe capacity of a DOTS client domain."; 3849 leaf link-id { 3850 type nt:link-id; 3851 description 3852 "Identifier of an interconnection link."; 3853 } 3854 leaf capacity { 3855 type uint64; 3856 mandatory true; 3857 description 3858 "Pipe capacity."; 3859 } 3860 leaf unit { 3861 type unit; 3862 description 3863 "The traffic can be measured using unit types: packets 3864 per second (PPS), Bits per Second (BPS), and/or 3865 bytes per second. DOTS agents auto-scale to the 3866 appropriate units (e.g., megabit-ps, kilobit-ps)."; 3867 } 3868 } 3869 } 3870 case baseline { 3871 description 3872 "Traffic baseline information"; 3873 list baseline { 3874 key "id"; 3875 description 3876 "Traffic baseline information"; 3877 leaf id { 3878 type uint32; 3879 must '. >= 1'; 3880 description 3881 "A baseline entry identifier."; 3882 } 3883 uses baseline; 3884 } 3885 } 3886 } 3887 } 3888 } 3889 case telemetry { 3890 description 3891 "Indicates the message is about telemetry."; 3892 list pre-or-ongoing-mitigation { 3893 key "cuid tmid"; 3894 description 3895 "Pre-or-ongoing-mitigation telemetry per DOTS client."; 3896 leaf cuid { 3897 type string; 3898 description 3899 "A unique identifier that is 3900 generated by a DOTS client to prevent 3901 request collisions. It is expected that the 3902 cuid will remain consistent throughout the 3903 lifetime of the DOTS client."; 3904 } 3905 leaf cdid { 3906 type string; 3907 description 3908 "The cdid should be included by a server-domain 3909 DOTS gateway to propagate the client domain 3910 identification information from the 3911 gateway's client-facing-side to the gateway's 3912 server-facing-side, and from the gateway's 3913 server-facing-side to the DOTS server. 3915 It may be used by the final DOTS server 3916 for policy enforcement purposes."; 3917 } 3918 leaf tmid { 3919 type uint32; 3920 description 3921 "An identifier to uniquely demux telemetry data sent 3922 using the same message."; 3923 } 3924 container target { 3925 description 3926 "Indicates the target."; 3927 uses ietf-data:target; 3928 leaf-list alias-name { 3929 type string; 3930 description 3931 "An alias name that points to a resource."; 3932 } 3933 leaf-list mid-list { 3934 type uint32; 3935 description 3936 "Reference a list of associated mitigation requests."; 3937 } 3938 } 3939 uses pre-or-ongoing-mitigation; 3940 } 3941 } 3942 } 3943 } 3944 3946 9.2. Vendor Attack Mapping Details YANG Module 3948 file "ietf-dots-mapping@2020-05-04.yang" 3949 module ietf-dots-mapping { 3950 yang-version 1.1; 3951 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-mapping"; 3952 prefix dots-mapping; 3954 import ietf-dots-data-channel { 3955 prefix ietf-data; 3956 reference 3957 "RFC 8783: Distributed Denial-of-Service Open Threat 3958 Signaling (DOTS) Data Channel Specification"; 3959 } 3961 organization 3962 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3963 contact 3964 "WG Web: 3965 WG List: 3967 Author: Mohamed Boucadair 3968 3970 Author: Jon Shallow 3971 "; 3972 description 3973 "This module contains YANG definitions for the sharing 3974 DDoS attack mapping details between a DOTS client and 3975 a DOTS server, by means of the DOTS data channel. 3977 Copyright (c) 2020 IETF Trust and the persons identified as 3978 authors of the code. All rights reserved. 3980 Redistribution and use in source and binary forms, with or 3981 without modification, is permitted pursuant to, and subject 3982 to the license terms contained in, the Simplified BSD License 3983 set forth in Section 4.c of the IETF Trust's Legal Provisions 3984 Relating to IETF Documents 3985 (http://trustee.ietf.org/license-info). 3987 This version of this YANG module is part of RFC XXXX; see 3988 the RFC itself for full legal notices."; 3990 revision 2020-05-04 { 3991 description 3992 "Initial revision."; 3993 reference 3994 "RFC XXXX: Distributed Denial-of-Service Open Threat 3995 Signaling (DOTS) Telemetry"; 3996 } 3998 feature dots-telemetry { 3999 description 4000 "This feature indicates that DOTS telemetry data can be 4001 shared between DOTS clients and servers."; 4002 } 4004 grouping attack-mapping { 4005 description 4006 "A set of information used for sharing vendor attack mapping 4007 information with a peer."; 4008 list vendor { 4009 key "vendor-id"; 4010 description 4011 "Vendor attack mapping information of the client/server"; 4012 leaf vendor-id { 4013 type uint32; 4014 description 4015 "Vendor ID is a security vendor's Enterprise Number."; 4016 } 4017 list attack-mapping { 4018 key "attack-id"; 4019 description 4020 "Attack mapping details."; 4021 leaf attack-id { 4022 type uint32; 4023 description 4024 "Unique identifier assigned by the vendor for the attack."; 4025 } 4026 leaf attack-name { 4027 type string; 4028 mandatory true; 4029 description 4030 "Textual representation of attack description. Natural Language 4031 Processing techniques (e.g., word embedding) can possibly be used 4032 to map the attack description to an attack type."; 4033 } 4034 } 4035 } 4036 } 4038 augment "/ietf-data:dots-data/ietf-data:dots-client" { 4039 if-feature "dots-telemetry"; 4040 container vendor-mapping { 4041 description 4042 "Clients use this feature to share their vendor 4043 attack mapping information with DOTS servers."; 4044 uses attack-mapping; 4045 } 4046 } 4048 augment "/ietf-data:dots-data/ietf-data:capabilities" { 4049 if-feature "dots-telemetry"; 4050 leaf vendor-mapping-enabled { 4051 type boolean; 4052 config false; 4053 description 4054 "Indicates that the server supports sharing 4055 attack vendor mapping details with DOTS clients."; 4056 } 4057 } 4059 augment "/ietf-data:dots-data" { 4060 if-feature "dots-telemetry"; 4061 container vendor-mapping { 4062 config false; 4063 description 4064 "Includes the list of vendor attack mapping details 4065 that will be shared upon request with DOTS clients."; 4066 uses attack-mapping; 4067 } 4068 } 4069 } 4070 4072 10. YANG/JSON Mapping Parameters to CBOR 4074 All DOTS telemetry parameters in the payload of the DOTS signal 4075 channel MUST be mapped to CBOR types as shown in the following table: 4077 o Implementers may use the values in: https://github.com/boucadair/ 4078 draft-dots-telemetry/blob/master/mapping-table.txt 4080 +----------------------+-------------+------+---------------+--------+ 4081 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 4082 | | Type | Key | Type & | Type | 4083 | | | | Information | | 4084 +======================+=============+======+===============+========+ 4085 | tsid | uint32 |TBA1 | 0 unsigned | Number | 4086 | telemetry | container |TBA2 | 5 map | Object | 4087 | low-percentile | decimal64 |TBA3 | 6 tag 4 | | 4088 | | | | [-2, integer]| String | 4089 | mid-percentile | decimal64 |TBA4 | 6 tag 4 | | 4090 | | | | [-2, integer]| String | 4091 | high-percentile | decimal64 |TBA5 | 6 tag 4 | | 4092 | | | | [-2, integer]| String | 4093 | unit-config | list |TBA6 | 4 array | Array | 4094 | unit | enumeration |TBA7 | 0 unsigned | String | 4095 | unit-status | boolean |TBA8 | 7 bits 20 | False | 4096 | | | | 7 bits 21 | True | 4097 | total-pipe-capability| list |TBA9 | 4 array | Array | 4098 | link-id | string |TBA10 | 3 text string | String | 4099 | pre-or-ongoing- | list |TBA11 | 4 array | Array | 4100 | mitigation | | | | | 4101 | total-traffic-normal | list |TBA12 | 4 array | Array | 4102 | low-percentile-g | yang:gauge64|TBA13 | 0 unsigned | String | 4103 | mid-percentile-g | yang:gauge64|TBA14 | 0 unsigned | String | 4104 | high-percentile-g | yang:gauge64|TBA15 | 0 unsigned | String | 4105 | peak-g | yang:gauge64|TBA16 | 0 unsigned | String | 4106 | total-attack-traffic | list |TBA17 | 4 array | Array | 4107 | total-traffic | list |TBA18 | 4 array | Array | 4108 | total-connection- | | | | | 4109 | capacity | list |TBA19 | 4 array | Array | 4110 | connection | uint64 |TBA20 | 0 unsigned | String | 4111 | connection-client | uint64 |TBA21 | 0 unsigned | String | 4112 | embryonic | uint64 |TBA22 | 0 unsigned | String | 4113 | embryonic-client | uint64 |TBA23 | 0 unsigned | String | 4114 | connection-ps | uint64 |TBA24 | 0 unsigned | String | 4115 | connection-client-ps | uint64 |TBA25 | 0 unsigned | String | 4116 | request-ps | uint64 |TBA26 | 0 unsigned | String | 4117 | request-client-ps | uint64 |TBA27 | 0 unsigned | String | 4118 | partial-request-ps | uint64 |TBA28 | 0 unsigned | String | 4119 | partial-request- | | | | | 4120 | client-ps | uint64 |TBA29 | 0 unsigned | String | 4121 | total-attack- | | | | | 4122 | connection | container |TBA30 | 5 map | Object | 4123 | low-percentile-l | list |TBA31 | 4 array | Array | 4124 | mid-percentile-l | list |TBA32 | 4 array | Array | 4125 | high-percentile-l | list |TBA33 | 4 array | Array | 4126 | peak-l | list |TBA34 | 4 array | Array | 4127 | attack-detail | list |TBA35 | 4 array | Array | 4128 | id | uint32 |TBA36 | 0 unsigned | Number | 4129 | attack-id | uint32 |TBA37 | 0 unsigned | Number | 4130 | attack-name | string |TBA38 | 3 text string | String | 4131 | attack-severity | enumeration |TBA39 | 0 unsigned | String | 4132 | start-time | uint64 |TBA40 | 0 unsigned | String | 4133 | end-time | uint64 |TBA41 | 0 unsigned | String | 4134 | source-count | container |TBA42 | 5 map | Object | 4135 | top-talker | container |TBA43 | 5 map | Object | 4136 | spoofed-status | boolean |TBA44 | 7 bits 20 | False | 4137 | | | | 7 bits 21 | True | 4138 | low-percentile-c | container |TBA45 | 5 map | Object | 4139 | mid-percentile-c | container |TBA46 | 5 map | Object | 4140 | high-percentile-c | container |TBA47 | 5 map | Object | 4141 | peak-c | container |TBA48 | 5 map | Object | 4142 | baseline | container |TBA49 | 5 map | Object | 4143 | current-config | container |TBA50 | 5 map | Object | 4144 | max-config-values | container |TBA51 | 5 map | Object | 4145 | min-config-values | container |TBA52 | 5 map | Object | 4146 | supported-units | container |TBA53 | 5 map | Object | 4147 | server-originated- | boolean |TBA54 | 7 bits 20 | False | 4148 | telemetry | | | 7 bits 21 | True | 4149 | telemetry-notify- | uint32 |TBA55 | 0 unsigned | Number | 4150 | interval | | | | | 4151 | tmid | uint32 |TBA56 | 0 unsigned | Number | 4152 | measurement-interval | enumeration |TBA57 | 0 unsigned | String | 4153 | measurement-sample | enumeration |TBA58 | 0 unsigned | String | 4154 | talker | list |TBA59 | 4 array | Array | 4155 | source-prefix | inet: |TBA60 | 3 text string | String | 4156 | | ip-prefix | | | | 4157 | mid-list | leaf-list |TBA61 | 4 array | Array | 4158 | | uint32 | | 0 unsigned | Number | 4159 | source-port-range | list |TBA62 | 4 array | Array | 4160 | source-icmp-type- | list |TBA63 | 4 array | Array | 4161 | range | | | | | 4162 | lower-type | uint8 |TBA64 | 0 unsigned | Number | 4163 | upper-type | uint8 |TBA65 | 0 unsigned | Number | 4164 | target | container |TBA66 | 5 map | Object | 4165 | capacity | uint64 |TBA67 | 0 unsigned | String | 4166 | protocol | uint8 |TBA68 | 0 unsigned | Number | 4167 | total-traffic- | | | | | 4168 | normal-per-protocol | list |TBA69 | 4 array | Array | 4169 | total-traffic- | | | | | 4170 | normal-per-port | list |TBA70 | 4 array | Array | 4171 | total-connection- | | | | | 4172 | capacity-per-port | list |TBA71 | 4 array | Array | 4173 | total-traffic- | | | | | 4174 | -protocol | list |TBA72 | 4 array | Array | 4175 | total-traffic- port | list |TBA73 | 4 array | Array | 4176 | total-attack- | | | | | 4177 | traffic-protocol | list |TBA74 | 4 array | Array | 4178 | total-attack- | | | | | 4179 | traffic-port | list |TBA75 | 4 array | Array | 4180 | total-attack- | | | | | 4181 | connection-port | list |TBA76 | 4 array | Array | 4182 | port | inet: | | | | 4183 | | port-number|TBA77 | 0 unsigned | Number | 4184 | query-type | leaf-list |TBA78 | 4 array | Array | 4185 | | | | 0 unsigned | String | 4186 | vendor-id | uint32 |TBA79 | 0 unsigned | Number | 4187 | ietf-dots-telemetry: | | | | | 4188 | telemetry-setup | container |TBA80 | 5 map | Object | 4189 | ietf-dots-telemetry: | | | | | 4190 | total-traffic | list |TBA81 | 4 array | Array | 4191 | ietf-dots-telemetry: | | | | | 4192 | unit | enumeration |TBA82 | 0 unsigned | String | 4193 | ietf-dots-telemetry: | | | | | 4194 | low-percentile-g | yang:gauge64|TBA83 | 0 unsigned | String | 4195 | ietf-dots-telemetry: | | | | | 4196 | mid-percentile-g | yang:gauge64|TBA84 | 0 unsigned | String | 4197 | ietf-dots-telemetry: | | | | | 4198 | high-percentile-g | yang:gauge64|TBA85 | 0 unsigned | String | 4199 | ietf-dots-telemetry: | | | | | 4200 | peak-g | yang:gauge64|TBA86 | 0 unsigned | String | 4201 | ietf-dots-telemetry: | | | | | 4202 | total-attack-traffic | list |TBA87 | 4 array | Array | 4203 | ietf-dots-telemetry: | | | | | 4204 | total-attack- | | | | | 4205 | connection | container |TBA88 | 5 map | Object | 4206 | ietf-dots-telemetry: | | | | | 4207 | low-percentile-c | container |TBA89 | 5 map | Object | 4208 | ietf-dots-telemetry: | | | | | 4209 | mid-percentile-c | container |TBA90 | 5 map | Object | 4210 | ietf-dots-telemetry: | | | | | 4211 | high-percentile-c | container |TBA91 | 5 map | Object | 4212 | ietf-dots-telemetry: | | | | | 4213 | peak-c | container |TBA92 | 5 map | Object | 4214 | ietf-dots-telemetry: | | | | | 4215 | connection | uint64 |TBA93 | 0 unsigned | String | 4216 | ietf-dots-telemetry: | | | | | 4217 | embryonic | uint64 |TBA94 | 0 unsigned | String | 4218 | ietf-dots-telemetry: | | | | | 4219 | connection-ps | uint64 |TBA95 | 0 unsigned | String | 4220 | ietf-dots-telemetry: | | | | | 4221 | request-ps | uint64 |TBA96 | 0 unsigned | String | 4222 | ietf-dots-telemetry: | | | | | 4223 | partial-request-ps | uint64 |TBA97 | 0 unsigned | String | 4224 | ietf-dots-telemetry: | | | | | 4225 | attack-detail | list |TBA98 | 4 array | Array | 4226 | ietf-dots-telemetry: | | | | | 4227 | id | uint32 |TBA99 | 0 unsigned | Number | 4228 | ietf-dots-telemetry: | | | | | 4229 | attack-id | uint32 |TBA100| 0 unsigned | Number | 4230 | ietf-dots-telemetry: | | | | | 4231 | attack-name | string |TBA101| 3 text string | String | 4232 | ietf-dots-telemetry: | | | | | 4233 | attack-severity | enumeration |TBA102| 0 unsigned | String | 4234 | ietf-dots-telemetry: | | | | | 4235 | start-time | uint64 |TBA103| 0 unsigned | String | 4236 | ietf-dots-telemetry: | | | | | 4237 | end-time | uint64 |TBA104| 0 unsigned | String | 4238 | ietf-dots-telemetry: | | | | | 4239 | source-count | container |TBA105| 5 map | Object | 4240 | ietf-dots-telemetry: | | | | | 4241 | top-talker | container |TBA106| 5 map | Object | 4242 | ietf-dots-telemetry: | | | | | 4243 | spoofed-status | boolean |TBA107| 7 bits 20 | False | 4244 | | | | 7 bits 21 | True | 4245 | ietf-dots-telemetry: | | | | | 4246 | talker | list |TBA108| 4 array | Array | 4247 | ietf-dots-telemetry: | inet: |TBA109| 3 text string | String | 4248 | source-prefix | ip-prefix | | | | 4249 | ietf-dots-telemetry: | | | | | 4250 | source-port-range | list |TBA110| 4 array | Array | 4251 | ietf-dots-telemetry: | | | | | 4252 | lower-port | inet: | | | | 4253 | | port-number|TBA111| 0 unsigned | Number | 4254 | ietf-dots-telemetry: | | | | | 4255 | upper-port | inet: | | | | 4256 | | port-number|TBA112| 0 unsigned | Number | 4257 | ietf-dots-telemetry: | | | | | 4258 | source-icmp-type- | list |TBA113| 4 array | Array | 4259 | range | | | | | 4260 | ietf-dots-telemetry: | | | | | 4261 | lower-type | uint8 |TBA114| 0 unsigned | Number | 4262 | ietf-dots-telemetry: | | | | | 4263 | upper-type | uint8 |TBA115| 0 unsigned | Number | 4264 | ietf-dots-telemetry: | | | | | 4265 | telemetry | container |TBA116| 5 map | Object | 4266 | ietf-dots-telemetry: | | | | | 4267 | vendor-id | uint32 |TBA117| 0 unsigned | Number | 4268 +----------------------+-------------+------+---------------+--------+ 4270 11. IANA Considerationsr 4272 11.1. DOTS Signal Channel CBOR Key Values 4274 This specification registers the DOTS telemetry attributes in the 4275 IANA "DOTS Signal Channel CBOR Key Values" registry available at 4276 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 4277 cbor-key-values. 4279 The DOTS telemetry attributes defined in this specification are 4280 comprehension-optional parameters. 4282 o Note to the RFC Editor: CBOR keys are assigned from the 4283 32768-49151 range. 4285 +----------------------+-------+-------+------------+---------------+ 4286 | Parameter Name | CBOR | CBOR | Change | Specification | 4287 | | Key | Major | Controller | Document(s) | 4288 | | Value | Type | | | 4289 +======================+=======+=======+============+===============+ 4290 | tsid | TBA1 | 0 | IESG | [RFCXXXX] | 4291 | telemetry | TBA2 | 5 | IESG | [RFCXXXX] | 4292 | low-percentile | TBA3 | 6tag4 | IESG | [RFCXXXX] | 4293 | mid-percentile | TBA4 | 6tag4 | IESG | [RFCXXXX] | 4294 | high-percentile | TBA5 | 6tag4 | IESG | [RFCXXXX] | 4295 | unit-config | TBA6 | 4 | IESG | [RFCXXXX] | 4296 | unit | TBA7 | 0 | IESG | [RFCXXXX] | 4297 | unit-status | TBA8 | 7 | IESG | [RFCXXXX] | 4298 | total-pipe-capability| TBA9 | 4 | IESG | [RFCXXXX] | 4299 | link-id | TBA10 | 3 | IESG | [RFCXXXX] | 4300 | pre-or-ongoing- | TBA11 | 4 | IESG | [RFCXXXX] | 4301 | mitigation | | | | | 4302 | total-traffic-normal | TBA12 | 4 | IESG | [RFCXXXX] | 4303 | low-percentile-g | TBA13 | 0 | IESG | [RFCXXXX] | 4304 | mid-percentile-g | TBA14 | 0 | IESG | [RFCXXXX] | 4305 | high-percentile-g | TBA15 | 0 | IESG | [RFCXXXX] | 4306 | peak-g | TBA16 | 0 | IESG | [RFCXXXX] | 4307 | total-attack-traffic | TBA17 | 4 | IESG | [RFCXXXX] | 4308 | total-traffic | TBA18 | 4 | IESG | [RFCXXXX] | 4309 | total-connection- | TBA19 | 4 | IESG | [RFCXXXX] | 4310 | capacity | | | | | 4311 | connection | TBA20 | 0 | IESG | [RFCXXXX] | 4312 | connection-client | TBA21 | 0 | IESG | [RFCXXXX] | 4313 | embryonic | TBA22 | 0 | IESG | [RFCXXXX] | 4314 | embryonic-client | TBA23 | 0 | IESG | [RFCXXXX] | 4315 | connection-ps | TBA24 | 0 | IESG | [RFCXXXX] | 4316 | connection-client-ps | TBA25 | 0 | IESG | [RFCXXXX] | 4317 | request-ps | TBA26 | 0 | IESG | [RFCXXXX] | 4318 | request-client-ps | TBA27 | 0 | IESG | [RFCXXXX] | 4319 | partial-request-ps | TBA28 | 0 | IESG | [RFCXXXX] | 4320 | partial-request- | TBA29 | 0 | IESG | [RFCXXXX] | 4321 | client-ps | | | | | 4322 | total-attack- | TBA30 | 5 | IESG | [RFCXXXX] | 4323 | connection | | | | | 4324 | low-percentile-l | TBA31 | 4 | IESG | [RFCXXXX] | 4325 | mid-percentile-l | TBA32 | 4 | IESG | [RFCXXXX] | 4326 | high-percentile-l | TBA33 | 4 | IESG | [RFCXXXX] | 4327 | peak-l | TBA34 | 4 | IESG | [RFCXXXX] | 4328 | attack-detail | TBA35 | 4 | IESG | [RFCXXXX] | 4329 | id | TBA36 | 0 | IESG | [RFCXXXX] | 4330 | attack-id | TBA37 | 0 | IESG | [RFCXXXX] | 4331 | attack-name | TBA38 | 3 | IESG | [RFCXXXX] | 4332 | attack-severity | TBA39 | 0 | IESG | [RFCXXXX] | 4333 | start-time | TBA40 | 0 | IESG | [RFCXXXX] | 4334 | end-time | TBA41 | 0 | IESG | [RFCXXXX] | 4335 | source-count | TBA42 | 5 | IESG | [RFCXXXX] | 4336 | top-talker | TBA43 | 5 | IESG | [RFCXXXX] | 4337 | spoofed-status | TBA44 | 7 | IESG | [RFCXXXX] | 4338 | low-percentile-c | TBA45 | 5 | IESG | [RFCXXXX] | 4339 | mid-percentile-c | TBA46 | 5 | IESG | [RFCXXXX] | 4340 | high-percentile-c | TBA47 | 5 | IESG | [RFCXXXX] | 4341 | peak-c | TBA48 | 5 | IESG | [RFCXXXX] | 4342 | ietf-dots-signal-cha | TBA49 | 5 | IESG | [RFCXXXX] | 4343 | current-config | TBA50 | 5 | IESG | [RFCXXXX] | 4344 | max-config-value | TBA51 | 5 | IESG | [RFCXXXX] | 4345 | min-config-values | TBA52 | 5 | IESG | [RFCXXXX] | 4346 | supported-units | TBA55 | 5 | IESG | [RFCXXXX] | 4347 | server-originated- | TBA54 | 7 | IESG | [RFCXXXX] | 4348 | telemetry | | | | | 4349 | telemetry-notify- | TBA55 | 0 | IESG | [RFCXXXX] | 4350 | interval | | | | | 4351 | tmid | TBA56 | 0 | IESG | [RFCXXXX] | 4352 | measurement-interval | TBA57 | 0 | IESG | [RFCXXXX] | 4353 | measurement-sample | TBA58 | 0 | IESG | [RFCXXXX] | 4354 | talker | TBA59 | 0 | IESG | [RFCXXXX] | 4355 | source-prefix | TBA60 | 0 | IESG | [RFCXXXX] | 4356 | mid-list | TBA61 | 4 | IESG | [RFCXXXX] | 4357 | source-port-range | TBA62 | 4 | IESG | [RFCXXXX] | 4358 | source-icmp-type- | TBA63 | 4 | IESG | [RFCXXXX] | 4359 | range | | | | | 4360 | lower-type | TBA64 | 0 | IESG | [RFCXXXX] | 4361 | upper-type | TBA65 | 0 | IESG | [RFCXXXX] | 4362 | target | TBA66 | 5 | IESG | [RFCXXXX] | 4363 | capacity | TBA67 | 0 | IESG | [RFCXXXX] | 4364 | protocol | TBA68 | 0 | IESG | [RFCXXXX] | 4365 | total-traffic- | TBA69 | 4 | IESG | [RFCXXXX] | 4366 | normal-per-protocol | | | | | 4367 | total-traffic- | TBA70 | 4 | IESG | [RFCXXXX] | 4368 | normal-per-port | | | | | 4369 | total-connection- | TBA71 | 4 | IESG | [RFCXXXX] | 4370 | capacity-per-port | | | | | 4371 | total-traffic- | TBA72 | 4 | IESG | [RFCXXXX] | 4372 | -protocol | | | | | 4373 | total-traffic-port | TBA73 | 4 | IESG | [RFCXXXX] | 4374 | total-attack- | TBA74 | 4 | IESG | [RFCXXXX] | 4375 | traffic-protocol | | | | | 4376 | total-attack- | TBA75 | 4 | IESG | [RFCXXXX] | 4377 | traffic-port | | | | | 4378 | total-attack- | TBA76 | 4 | IESG | [RFCXXXX] | 4379 | connection-port | | | | | 4380 | port | TBA77 | 0 | IESG | [RFCXXXX] | 4381 | query-type | TBA78 | 4 | IESG | [RFCXXXX] | 4382 | vendor-id | TBA79 | 0 | IESG | [RFCXXXX] | 4383 | ietf-dots-telemetry: | TBA80 | 5 | IESG | [RFCXXXX] | 4384 | telemetry-setup | | | | | 4385 | ietf-dots-telemetry: | TBA81 | 0 | IESG | [RFCXXXX] | 4386 | total-traffic | | | | | 4387 | ietf-dots-telemetry: | TBA82 | 0 | IESG | [RFCXXXX] | 4388 | unit | | | | | 4389 | ietf-dots-telemetry: | TBA83 | 0 | IESG | [RFCXXXX] | 4390 | low-percentile-g | | | | | 4391 | ietf-dots-telemetry: | TBA84 | 0 | IESG | [RFCXXXX] | 4392 | mid-percentile-g | | | | | 4393 | ietf-dots-telemetry: | TBA85 | 0 | IESG | [RFCXXXX] | 4394 | high-percentile-g | | | | | 4395 | ietf-dots-telemetry: | TBA86 | 0 | IESG | [RFCXXXX] | 4396 | peak-g | | | | | 4397 | ietf-dots-telemetry: | TBA87 | 0 | IESG | [RFCXXXX] | 4398 | total-attack-traffic | | | | | 4399 | ietf-dots-telemetry: | TBA88 | 0 | IESG | [RFCXXXX] | 4400 | total-attack- | | | | | 4401 | connection | | | | | 4402 | ietf-dots-telemetry: | TBA89 | 0 | IESG | [RFCXXXX] | 4403 | low-percentile-c | | | | | 4404 | ietf-dots-telemetry: | TBA90 | 0 | IESG | [RFCXXXX] | 4405 | mid-percentile-c | | | | | 4406 | ietf-dots-telemetry: | TBA91 | 0 | IESG | [RFCXXXX] | 4407 | high-percentile-c | | | | | 4408 | ietf-dots-telemetry: | TBA92 | 0 | IESG | [RFCXXXX] | 4409 | peak-c | | | | | 4410 | ietf-dots-telemetry: | TBA93 | 0 | IESG | [RFCXXXX] | 4411 | connection | | | | | 4412 | ietf-dots-telemetry: | TBA94 | 0 | IESG | [RFCXXXX] | 4413 | embryonic | | | | | 4414 | ietf-dots-telemetry: | TBA95 | 0 | IESG | [RFCXXXX] | 4415 | connection-ps | | | | | 4416 | ietf-dots-telemetry: | TBA96 | 0 | IESG | [RFCXXXX] | 4417 | request-ps | | | | | 4418 | ietf-dots-telemetry: | TBA97 | 0 | IESG | [RFCXXXX] | 4419 | partial-request-ps | | | | | 4420 | ietf-dots-telemetry: | TBA98 | 4 | IESG | [RFCXXXX] | 4421 | attack-detail | | | | | 4422 | ietf-dots-telemetry: | TBA99 | 0 | IESG | [RFCXXXX] | 4423 | id | | | | | 4424 | ietf-dots-telemetry: | TBA100| 0 | IESG | [RFCXXXX] | 4425 | attack-id | | | | | 4426 | ietf-dots-telemetry: | TBA101| 0 | IESG | [RFCXXXX] | 4427 | attack-name | | | | | 4428 | ietf-dots-telemetry: | TBA102| 0 | IESG | [RFCXXXX] | 4429 | attack-severity | | | | | 4430 | ietf-dots-telemetry: | TBA103| 0 | IESG | [RFCXXXX] | 4431 | start-time | | | | | 4432 | ietf-dots-telemetry: | TBA104| 0 | IESG | [RFCXXXX] | 4433 | end-time | | | | | 4434 | ietf-dots-telemetry: | TBA105| 0 | IESG | [RFCXXXX] | 4435 | source-count | | | | | 4436 | ietf-dots-telemetry: | TBA106| 0 | IESG | [RFCXXXX] | 4437 | top-talker | | | | | 4438 | ietf-dots-telemetry: | TBA107| 0 | IESG | [RFCXXXX] | 4439 | spoofed-status | | | | | 4440 | ietf-dots-telemetry: | TBA108| 0 | IESG | [RFCXXXX] | 4441 | talker | | | | | 4442 | ietf-dots-telemetry: | TBA109| 0 | IESG | [RFCXXXX] | 4443 | source-prefix | | | | | 4444 | ietf-dots-telemetry: | | | | | 4445 | source-port-range | TBA110| 4 | IESG | [RFCXXXX] | 4446 | ietf-dots-telemetry: | | | | | 4447 | lower-port | TBA111| 0 | IESG | [RFCXXXX] | 4448 | ietf-dots-telemetry: | | | | | 4449 | upper-port | TBA112| 0 | IESG | [RFCXXXX] | 4450 | ietf-dots-telemetry: | | | | | 4451 | source-icmp-type- | TBA113| 4 | IESG | [RFCXXXX] | 4452 | range | | | | | 4453 | ietf-dots-telemetry: | | | | | 4454 | lower-type | TBA114| 0 | IESG | [RFCXXXX] | 4455 | ietf-dots-telemetry: | | | | | 4456 | upper-type | TBA115| 0 | IESG | [RFCXXXX] | 4457 | ietf-dots-telemetry: | TBA116| 5 | IESG | [RFCXXXX] | 4458 | telemetry | | | | | 4459 | ietf-dots-telemetry: | TBA117| 0 | IESG | [RFCXXXX] | 4460 | vendor-id | | | | | 4461 +----------------------+-------+-------+------------+---------------+ 4463 11.2. DOTS Signal Channel Conflict Cause Codes 4465 This specification requests IANA to assign a new code from the "DOTS 4466 Signal Channel Conflict Cause Codes" registry available at 4467 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 4468 conflict-cause-codes. 4470 +------+-------------------+------------------------+-------------+ 4471 | Code | Label | Description | Reference | 4472 +======+===================+========================+=============+ 4473 | TBA | overlapping-pipes | Overlapping pipe scope | [RFCXXXX] | 4474 +------+-------------------+------------------------+-------------+ 4476 11.3. DOTS Signal Telemetry YANG Module 4478 This document requests IANA to register the following URIs in the 4479 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4481 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4482 Registrant Contact: The IESG. 4483 XML: N/A; the requested URI is an XML namespace. 4485 URI: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4486 Registrant Contact: The IESG. 4487 XML: N/A; the requested URI is an XML namespace. 4489 This document requests IANA to register the following YANG modules in 4490 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4491 Parameters" registry. 4493 name: ietf-dots-telemetry 4494 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4495 maintained by IANA: N 4496 prefix: dots-telemetry 4497 reference: RFC XXXX 4499 name: ietf-dots-mapping 4500 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-mapping 4501 maintained by IANA: N 4502 prefix: dots-mapping 4503 reference: RFC XXXX 4505 12. Security Considerations 4507 12.1. DOTS Signal Channel Telemetry 4509 The security considerations for the DOTS signal channel protocol are 4510 discussed in Section 10 of [RFC8782]. The following discusses the 4511 security considerations that are specific to the DOTS signal channel 4512 extension defined in this document. 4514 The DOTS telemetry information includes DOTS client network topology, 4515 DOTS client domain pipe capacity, normal traffic baseline and 4516 connections capacity, and threat and mitigation information. Such 4517 information is sensitive; it MUST be protected at rest by the DOTS 4518 server domain to prevent data leakage. 4520 DOTS clients are typically trusted devices by the DOTS client domain. 4521 DOTS clients may be co-located on network security services (e.g., 4522 firewall) and a compromised security service potentially can do a lot 4523 more damage to the network. This assumption differs from the often 4524 held view that devices are untrusted, often referred to as the "zero- 4525 trust model". A compromised DOTS client can send fake DOTS telemetry 4526 data to a DOTS server to mislead the DOTS server. This attack can be 4527 prevented by monitoring and auditing DOTS clients to detect 4528 misbehavior and to deter misuse, and by only authorizing the DOTS 4529 client to convey the DOTS telemetry for specific target resources 4530 (e.g., an application server is authorized to exchange DOTS telemetry 4531 for its IP addresses but a DDoS mitigator can exchange DOTS telemetry 4532 for any target resource in the network). As a reminder, this is 4533 variation of dealing with compromised DOTS clients as discussed in 4534 Section 10 of [RFC8782]. 4536 DOTS servers must be capable of defending themselves against DoS 4537 attacks from compromised DOTS clients. The following non- 4538 comprehensive list of mitigation techniques can be used by a DOTS 4539 server to handle misbehaving DOTS clients: 4541 o The probing rate (defined in Section 4.5 of [RFC8782]) can be used 4542 to limit the average data rate to the DOTS server. 4544 o Rate-limiting DOTS telemetry, including those with new 'tmid' 4545 values, from the same DOTS client defends against DoS attacks that 4546 would result in varying the 'tmid' to exhaust DOTS server 4547 resources. Likewise, the DOTS server can enforce a quota and 4548 time-limit on the number of active pre-or-ongoing-mitigation 4549 telemetry data (identified by 'tmid') from the DOTS client. 4551 Note also that telemetry notification interval may be used to rate- 4552 limit the pre-or-ongoing-mitigation telemetry notifications received 4553 by a DOTS client domain. 4555 12.2. Vendor Attack Mapping 4557 The security considerations for the DOTS data channel protocol are 4558 discussed in Section 10 of [RFC8783]. The following discusses the 4559 security considerations that are specific to the DOTS data channel 4560 extension defined in this document. 4562 All data nodes defined in the YANG module specified in Section 9.2 4563 which can be created, modified, and deleted (i.e., config true, which 4564 is the default) are considered sensitive. Write operations to these 4565 data nodes without proper protection can have a negative effect on 4566 network operations. Appropriate security measures are recommended to 4567 prevent illegitimate users from invoking DOTS data channel primitives 4568 as discussed in [RFC8783]. Nevertheless, an attacker who can access 4569 a DOTS client is technically capable of undertaking various attacks, 4570 such as: 4572 o Communicating invalid attack mapping details to the server 4573 ('/ietf-data:dots-data/ietf-data:dots-client/dots- 4574 telemetry:vendor-mapping'), which will mislead the server when 4575 correlating attack details. 4577 Some of the readable data nodes in the YANG module specified in 4578 Section 9.2 may be considered sensitive. It is thus important to 4579 control read access to these data nodes. These are the data nodes 4580 and their sensitivity: 4582 o '/ietf-data:dots-data/ietf-data:dots-client/dots-telemetry:vendor- 4583 mapping' can be misused to infer the DDoS protection technology 4584 deployed in a DOTS client domain. 4586 o '/ietf-data:dots-data/dots-telemetry:vendor-mapping' can be used 4587 by a compromised DOTS client to leak the attack detection 4588 capabilities of the DOTS server. This is a variation of the 4589 compromised DOTS client attacks discussed in Section 12.1. 4591 13. Contributors 4593 The following individuals have contributed to this document: 4595 o Li Su, CMCC, Email: suli@chinamobile.com 4597 o Pan Wei, Huawei, Email: william.panwei@huawei.com 4599 14. Acknowledgements 4601 The authors would like to thank Flemming Andreasen, Liang Xia, and 4602 Kaname Nishizuka co-authors of [I-D.doron-dots-telemetry] and 4603 everyone who had contributed to that document. 4605 The authors would like to thank Kaname Nishizuka, Wei Pan, and Yuuhei 4606 Hayashi for comments and review. 4608 Special thanks to Jon Shallow and Kaname Nishizuka for their 4609 implementation and interoperability work. 4611 15. References 4613 15.1. Normative References 4615 [Enterprise-Numbers] 4616 "Private Enterprise Numbers", May 2020, 4617 . 4619 [I-D.ietf-dots-signal-call-home] 4620 Reddy.K, T., Boucadair, M., and J. Shallow, "Distributed 4621 Denial-of-Service Open Threat Signaling (DOTS) Signal 4622 Channel Call Home", draft-ietf-dots-signal-call-home-08 4623 (work in progress), March 2020. 4625 [I-D.ietf-dots-signal-filter-control] 4626 Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 4627 "Controlling Filtering Rules Using Distributed Denial-of- 4628 Service Open Threat Signaling (DOTS) Signal Channel", 4629 draft-ietf-dots-signal-filter-control-06 (work in 4630 progress), June 2020. 4632 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4633 Requirement Levels", BCP 14, RFC 2119, 4634 DOI 10.17487/RFC2119, March 1997, 4635 . 4637 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4638 DOI 10.17487/RFC3688, January 2004, 4639 . 4641 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4642 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4643 . 4645 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4646 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4647 October 2013, . 4649 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4650 Application Protocol (CoAP)", RFC 7641, 4651 DOI 10.17487/RFC7641, September 2015, 4652 . 4654 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4655 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4656 . 4658 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4659 the Constrained Application Protocol (CoAP)", RFC 7959, 4660 DOI 10.17487/RFC7959, August 2016, 4661 . 4663 [RFC7970] Danyliw, R., "The Incident Object Description Exchange 4664 Format Version 2", RFC 7970, DOI 10.17487/RFC7970, 4665 November 2016, . 4667 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 4668 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 4669 . 4671 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4672 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4673 May 2017, . 4675 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 4676 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 4677 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 4678 2018, . 4680 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 4681 Mortensen, A., and N. Teague, "Distributed Denial-of- 4682 Service Open Threat Signaling (DOTS) Signal Channel 4683 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 4684 . 4686 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 4687 Denial-of-Service Open Threat Signaling (DOTS) Data 4688 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 4689 May 2020, . 4691 15.2. Informative References 4693 [I-D.bosh-core-new-block] 4694 Boucadair, M. and J. Shallow, "Constrained Application 4695 Protocol (CoAP) Block-Wise Transfer Options for Faster 4696 Transmission", draft-bosh-core-new-block-04 (work in 4697 progress), June 2020. 4699 [I-D.doron-dots-telemetry] 4700 Doron, E., Reddy, T., Andreasen, F., Xia, L., and K. 4701 Nishizuka, "Distributed Denial-of-Service Open Threat 4702 Signaling (DOTS) Telemetry Specifications", draft-doron- 4703 dots-telemetry-00 (work in progress), October 2016. 4705 [I-D.ietf-dots-multihoming] 4706 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 4707 Deployment Considerations for Distributed-Denial-of- 4708 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 4709 multihoming-04 (work in progress), May 2020. 4711 [I-D.ietf-dots-use-cases] 4712 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 4713 L., and K. Nishizuka, "Use cases for DDoS Open Threat 4714 Signaling", draft-ietf-dots-use-cases-23 (work in 4715 progress), May 2020. 4717 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 4718 "Framework for IP Performance Metrics", RFC 2330, 4719 DOI 10.17487/RFC2330, May 1998, 4720 . 4722 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4723 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4724 . 4726 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4727 Threat Signaling (DOTS) Requirements", RFC 8612, 4728 DOI 10.17487/RFC8612, May 2019, 4729 . 4731 Authors' Addresses 4733 Mohamed Boucadair (editor) 4734 Orange 4735 Rennes 35000 4736 France 4738 Email: mohamed.boucadair@orange.com 4740 Tirumaleswar Reddy (editor) 4741 McAfee, Inc. 4742 Embassy Golf Link Business Park 4743 Bangalore, Karnataka 560071 4744 India 4746 Email: kondtir@gmail.com 4748 Ehud Doron 4749 Radware Ltd. 4750 Raoul Wallenberg Street 4751 Tel-Aviv 69710 4752 Israel 4754 Email: ehudd@radware.com 4755 Meiling Chen 4756 CMCC 4757 32, Xuanwumen West 4758 BeiJing, BeiJing 100053 4759 China 4761 Email: chenmeiling@chinamobile.com 4763 Jon Shallow 4764 United Kingdom 4766 Email: supjps-ietf@jpshallow.com