idnits 2.17.1 draft-ietf-dots-telemetry-06.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 195 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 890 has weird spacing: '...apacity uin...' == Line 1226 has weird spacing: '...er-port ine...' == Line 1554 has weird spacing: '...er-port ine...' == Line 1863 has weird spacing: '...er-port ine...' == Line 1866 has weird spacing: '...er-type uin...' == (2 more instances...) -- The document date (April 7, 2020) is 1474 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) -- Looks like a reference, but probably isn't: '17' on line 2115 == Missing Reference: 'RFCXXXX' is mentioned on line 4017, but not defined == Unused Reference: 'I-D.ietf-dots-signal-call-home' is defined on line 4077, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'Enterprise-Numbers' == Outdated reference: A later version (-14) exists of draft-ietf-dots-signal-call-home-08 == Outdated reference: A later version (-07) exists of draft-ietf-dots-signal-filter-control-03 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-03 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-20 Summary: 2 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy, Ed. 5 Expires: October 9, 2020 McAfee 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 April 7, 2020 12 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 13 draft-ietf-dots-telemetry-06 15 Abstract 17 This document aims to enrich DOTS signal channel protocol with 18 various telemetry attributes allowing optimal DDoS attack mitigation. 19 It specifies the normal traffic baseline and attack traffic telemetry 20 attributes a DOTS client can convey to its DOTS server in the 21 mitigation request, the mitigation status telemetry attributes a DOTS 22 server can communicate to a DOTS client, and the mitigation efficacy 23 telemetry attributes a DOTS client can communicate to a DOTS server. 24 The telemetry attributes can assist the mitigator to choose the DDoS 25 mitigation techniques and perform optimal DDoS attack mitigation. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at https://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on October 9, 2020. 44 Copyright Notice 46 Copyright (c) 2020 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (https://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 3. DOTS Telemetry: Overview and Purpose . . . . . . . . . . . . 5 64 4. Generic Considerations . . . . . . . . . . . . . . . . . . . 9 65 4.1. DOTS Client Identification . . . . . . . . . . . . . . . 9 66 4.2. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 9 67 4.3. Empty URI Paths . . . . . . . . . . . . . . . . . . . . . 9 68 4.4. Controlling Configuration Data . . . . . . . . . . . . . 9 69 4.5. Block-wise Transfer . . . . . . . . . . . . . . . . . . . 10 70 4.6. DOTS Multi-homing Considerations . . . . . . . . . . . . 10 71 4.7. YANG Considerations . . . . . . . . . . . . . . . . . . . 10 72 4.8. A Note About Examples . . . . . . . . . . . . . . . . . . 11 73 5. Telemetry Operation Paths . . . . . . . . . . . . . . . . . . 11 74 6. DOTS Telemetry Setup Configuration . . . . . . . . . . . . . 12 75 6.1. Telemetry Configuration . . . . . . . . . . . . . . . . . 13 76 6.1.1. Retrieve Current DOTS Telemetry Configuration . . . . 13 77 6.1.2. Convey DOTS Telemetry Configuration . . . . . . . . . 16 78 6.1.3. Retrieve Installed DOTS Telemetry Configuration . . . 19 79 6.1.4. Delete DOTS Telemetry Configuration . . . . . . . . . 19 80 6.2. Total Pipe Capacity . . . . . . . . . . . . . . . . . . . 20 81 6.2.1. Convey DOTS Client Domain Pipe Capacity . . . . . . . 21 82 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity . 26 83 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity . . 26 84 6.3. Telemetry Baseline . . . . . . . . . . . . . . . . . . . 27 85 6.3.1. Convey DOTS Client Domain Baseline Information . . . 30 86 6.3.2. Retrieve Installed Normal Traffic Baseline . . . . . 33 87 6.3.3. Delete Installed Normal Traffic Baseline . . . . . . 33 88 6.4. Reset Installed Telemetry Setup . . . . . . . . . . . . . 33 89 6.5. Conflict with Other DOTS Clients of the Same Domain . . . 33 90 7. DOTS Pre-or-Ongoing Mitigation Telemetry . . . . . . . . . . 34 91 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes . . . 36 92 7.1.1. Target . . . . . . . . . . . . . . . . . . . . . . . 36 93 7.1.2. Total Traffic . . . . . . . . . . . . . . . . . . . . 38 94 7.1.3. Total Attack Traffic . . . . . . . . . . . . . . . . 39 95 7.1.4. Total Attack Connections . . . . . . . . . . . . . . 41 96 7.1.5. Attack Details . . . . . . . . . . . . . . . . . . . 42 98 7.2. From DOTS Clients to DOTS Servers . . . . . . . . . . . . 44 99 7.3. From DOTS Servers to DOTS Clients . . . . . . . . . . . . 47 100 8. DOTS Telemetry Mitigation Status Update . . . . . . . . . . . 51 101 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS 102 Telemetry Attributes . . . . . . . . . . . . . . . . . . 51 103 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 104 Attributes . . . . . . . . . . . . . . . . . . . . . . . 52 105 9. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 56 106 10. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 81 107 11. IANA Considerationsr . . . . . . . . . . . . . . . . . . . . 85 108 11.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 85 109 11.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 89 110 11.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 90 111 12. Security Considerations . . . . . . . . . . . . . . . . . . . 90 112 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 90 113 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 90 114 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 91 115 15.1. Normative References . . . . . . . . . . . . . . . . . . 91 116 15.2. Informative References . . . . . . . . . . . . . . . . . 92 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 93 119 1. Introduction 121 Distributed Denial of Service (DDoS) attacks have become more 122 sophisticated. IT organizations and service providers are facing 123 DDoS attacks that fall into two broad categories: 125 1. Network/Transport layer attacks target the victim's 126 infrastructure. These attacks are not necessarily aimed at 127 taking down the actual delivered services, but rather to 128 eliminate various network elements (routers, switches, firewalls, 129 transit links, and so on) from serving legitimate users traffic. 131 The main method of such attacks is to send a large volume or high 132 packet per second (pps) of traffic toward the victim's 133 infrastructure. Typically, attack volumes may vary from a few 134 100 Mbps to 100s of Gbps or even Tbps. Attacks are commonly 135 carried out leveraging botnets and attack reflectors for 136 amplification attacks such as NTP (Network Time Protocol), DNS 137 (Domain Name System), SNMP (Simple Network Management Protocol), 138 or SSDP (Simple Service Discovery Protocol). 140 2. Application layer attacks target various applications. Typical 141 examples include attacks against HTTP/HTTPS, DNS, SIP (Session 142 Initiation Protocol), or SMTP (Simple Mail Transfer Protocol). 143 However, all applications with their port numbers open at network 144 edges can be attractive attack targets. 146 Application layer attacks are considered more complex and hard to 147 categorize, therefore harder to detect and mitigate efficiently. 149 To compound the problem, attackers also leverage multi-vectored 150 attacks. These attacks are assembled from dynamic attack vectors 151 (Network/Application) and tactics. As such, multiple attack vectors 152 formed by multiple attack types and volumes are launched 153 simultaneously towards a victim. Multi-vector attacks are harder to 154 detect and defend. Multiple and simultaneous mitigation techniques 155 are needed to defeat such attack campaigns. It is also common for 156 attackers to change attack vectors right after a successful 157 mitigation, burdening their opponents with changing their defense 158 methods. 160 The ultimate conclusion derived from these real scenarios is that 161 modern attacks detection and mitigation are most certainly 162 complicated and highly convoluted tasks. They demand a comprehensive 163 knowledge of the attack attributes, the targeted normal behavior 164 (including, normal traffic patterns), as well as the attacker's on- 165 going and past actions. Even more challenging, retrieving all the 166 analytics needed for detecting these attacks is not simple to obtain 167 with the industry's current capabilities. 169 The DOTS signal channel protocol [I-D.ietf-dots-signal-channel] is 170 used to carry information about a network resource or a network (or a 171 part thereof) that is under a DDoS attack. Such information is sent 172 by a DOTS client to one or multiple DOTS servers so that appropriate 173 mitigation actions are undertaken on traffic deemed suspicious. 174 Various use cases are discussed in [I-D.ietf-dots-use-cases]. 176 Typically, DOTS clients can be integrated within a DDoS attack 177 detector, or network and security elements that have been actively 178 engaged with ongoing attacks. The DOTS client mitigation environment 179 determines that it is no longer possible or practical for it to 180 handle these attacks. This can be due to a lack of resources or 181 security capabilities, as derived from the complexities and the 182 intensity of these attacks. In this circumstance, the DOTS client 183 has invaluable knowledge about the actual attacks that need to be 184 handled by its DOTS server(s). By enabling the DOTS client to share 185 this comprehensive knowledge of an ongoing attack under specific 186 circumstances, the DOTS server can drastically increase its ability 187 to accomplish successful mitigation. While the attack is being 188 handled by the DOTS server associated mitigation resources, the DOTS 189 server has the knowledge about the ongoing attack mitigation. The 190 DOTS server can share this information with the DOTS client so that 191 the client can better assess and evaluate the actual mitigation 192 realized. 194 DOTS clients can send mitigation hints derived from attack details to 195 DOTS servers, with the full understanding that the DOTS server may 196 ignore mitigation hints, as described in [RFC8612] (Gen-004). 197 Mitigation hints will be transmitted across the DOTS signal channel, 198 as the data channel may not be functional during an attack. How a 199 DOTS server is handling normal and attack traffic attributes, and 200 mitigation hints is implementation-specific. 202 Both DOTS client and server can benefit this information by 203 presenting various information in relevant management, reporting, and 204 portal systems. 206 This document defines DOTS telemetry attributes that can be conveyed 207 by DOTS clients to DOTS servers, and vice versa. The DOTS telemetry 208 attributes are not mandatory fields. Nevertheless, when DOTS 209 telemetry attributes are available to a DOTS agent, and absent any 210 policy, it can signal the attributes in order to optimize the overall 211 mitigation service provisioned using DOTS. Some of the DOTS 212 telemetry data is not shared during an attack time. 214 2. Terminology 216 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 217 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 218 "OPTIONAL" in this document are to be interpreted as described in BCP 219 14 [RFC2119][RFC8174] when, and only when, they appear in all 220 capitals, as shown here. 222 The reader should be familiar with the terms defined in [RFC8612]. 224 "DOTS Telemetry" is defined as the collection of attributes that are 225 used to characterize normal traffic baseline, attacks and their 226 mitigation measures, and any related information that may help in 227 enforcing countermeasures. The DOTS Telemetry is an optional set of 228 attributes that can be signaled in the DOTS signal channel protocol. 230 The meaning of the symbols in YANG tree diagrams is defined in 231 [RFC8340]. 233 3. DOTS Telemetry: Overview and Purpose 235 When signaling a mitigation request, it is most certainly beneficial 236 for DOTS clients to signal to DOTS servers any knowledge regarding 237 ongoing attacks. This can happen in cases where DOTS clients are 238 asking DOTS servers for support in defending against attacks that 239 they have already detected and/or mitigated. These actions taken by 240 DOTS clients are referred to as "signaling the DOTS Telemetry". 242 If attacks are already detected and categorized within a DOTS client 243 domain, the DOTS server, and its associated mitigation services, can 244 proactively benefit this information and optimize the overall service 245 delivery. It is important to note that DOTS clients and servers 246 detection and mitigation approaches can be different, and can 247 potentially outcome different results and attack classifications. 248 The DDoS mitigation service treats the ongoing attack details 249 received from DOTS clients as hints and cannot completely rely or 250 trust the attack details conveyed by DOTS clients. 252 A basic requirement of security operation teams is to be aware and 253 get visibility into the attacks they need to handle. The DOTS server 254 security operation teams benefit from the DOTS telemetry, especially 255 from the reports of ongoing attacks. Even if some mitigation can be 256 automated, operational teams can use the DOTS telemetry to be 257 prepared for attack mitigation and to assign the correct resources 258 (operation staff, networking and mitigation) for the specific 259 service. Similarly, security operation personnel at the DOTS client 260 side ask for feedback about their requests for protection. 261 Therefore, it is valuable for DOTS servers to share DOTS telemetry 262 with DOTS clients. 264 Mutual sharing of information is thus crucial for "closing the 265 mitigation loop" between DOTS clients and servers. For the server 266 side team, it is important to realize that the same attacks that the 267 DOTS server's mitigation resources are seeing are those that a DOTS 268 client is asking to mitigate. For the DOTS client side team, it is 269 important to realize that the DOTS clients receive the required 270 service. For example, understanding that "I asked for mitigation of 271 two attacks and my DOTS server detects and mitigates only one...". 272 Cases of inconsistency in attack classification between DOTS clients 273 and servers can be highlighted, and maybe handled, using the DOTS 274 telemetry attributes. 276 In addition, management and orchestration systems, at both DOTS 277 client and server sides, can use DOTS telemetry as a feedback to 278 automate various control and management activities derived from 279 signaled telemetry information . 281 If the DOTS server's mitigation resources have the capabilities to 282 facilitate the DOTS telemetry, the DOTS server adapts its protection 283 strategy and activates the required countermeasures immediately 284 (automation enabled) for the sake of optimized attack mitigation 285 decisions and actions. 287 DOTS telemetry can also be used to tune the DDoS mitigators with the 288 correct state of an attack. During the last few years, DDoS attack 289 detection technologies have evolved from threshold-based detection 290 (that is, cases when all or specific parts of traffic cross a pre- 291 defined threshold for a certain period of time is considered as an 292 attack) to an "anomaly detection" approach. For the latter, it is 293 required to maintain rigorous learning of "normal" behavior and where 294 an "anomaly" (or an attack) is identified and categorized based on 295 the knowledge about the normal behavior and a deviation from this 296 normal behavior. Machine learning approaches are used such that the 297 actual traffic thresholds are automatically calculated by learning 298 the protected entity normal traffic behavior during idle time. The 299 normal traffic characterization learned is referred to as the "normal 300 traffic baseline". An attack is detected when the victim's actual 301 traffic is deviating from this normal baseline. 303 In addition, subsequent activities toward mitigating an attack are 304 much more challenging. The ability to distinguish legitimate traffic 305 from attacker traffic on a per packet basis is complex. For example, 306 a packet may look "legitimate" and no attack signature can be 307 identified. The anomaly can be identified only after detailed 308 statistical analysis. DDoS attack mitigators use the normal baseline 309 during the mitigation of an attack to identify and categorize the 310 expected appearance of a specific traffic pattern. Particularly, the 311 mitigators use the normal baseline to recognize the "level of 312 normality" needs to be achieved during the various mitigation 313 process. 315 Normal baseline calculation is performed based on continuous learning 316 of the normal behavior of the protected entities. The minimum 317 learning period varies from hours to days and even weeks, depending 318 on the protected application behavior. The baseline cannot be 319 learned during active attacks because attack conditions do not 320 characterize the protected entities' normal behavior. 322 If the DOTS client has calculated the normal baseline of its 323 protected entities, signaling such information to the DOTS server 324 along with the attack traffic levels is significantly valuable. The 325 DOTS server benefits from this telemetry by tuning its mitigation 326 resources with the DOTS client's normal baseline. The DOTS server 327 mitigators use the baseline to familiarize themselves with the attack 328 victim's normal behavior and target the baseline as the level of 329 normality they need to achieve. Fed with this inforamtion, the 330 overall mitigation performances is expected to be improved in terms 331 of time to mitigate, accuracy, false-negative, and false-positive. 333 Mitigation of attacks without having certain knowledge of normal 334 traffic can be inaccurate at best. This is especially true for 335 recursive signaling (see Section 3.2.3 in [I-D.ietf-dots-use-cases]). 336 In addition, the highly diverse types of use-cases where DOTS clients 337 are integrated also emphasize the need for knowledge of each DOTS 338 client domain behavior. Consequently, common global thresholds for 339 attack detection practically cannot be realized. Each DOTS client 340 domain can have its own levels of traffic and normal behavior. 341 Without facilitating normal baseline signaling, it may be very 342 difficult for DOTS servers in some cases to detect and mitigate the 343 attacks accurately: 345 It is important to emphasize that it is practically impossible for 346 the DOTS server's mitigators to calculate the normal baseline in 347 cases where they do not have any knowledge of the traffic 348 beforehand. 350 In addition, baseline learning requires a period of time that 351 cannot be afforded during active attack. 353 Of course, this information can provided using out-of-band 354 mechanisms or manual configuration at the risk to maintain 355 inaccurate information as the network evolves and "normal" 356 patterns change. The use of a dynamic and collaborative means 357 between the DOTS client and server to identify and share key 358 parameters for the sake of efficient DDoS protection is valuable. 360 During a high volume attack, DOTS client pipes can be totally 361 saturated. DOTS clients ask their DOTS servers to handle the attack 362 upstream so that DOTS client pipes return to a reasonable load level 363 (normal pattern, ideally). At this point, it is essential to ensure 364 that the mitigator does not overwhelm the DOTS client pipes by 365 sending back "clean traffic", or what it believes is "clean". This 366 can happen when the mitigator has not managed to detect and mitigate 367 all the attacks launched towards the DOTS client domain. In this 368 case, it can be valuable to DOTS clients to signal to DOTS servers 369 the "total pipe capacity", which is the level of traffic the DOTS 370 client domain can absorb from its upstream network. Dynamic updates 371 of the condition of pipes between DOTS agents while they are under a 372 DDoS attack is essential (e.g., where multiple DOTS clients share the 373 same physical connectivity pipes). It is important to note that the 374 term "pipe" noted here does not necessary represent physical pipe, 375 but rather represents the maximum level of traffic that the DOTS 376 client domain can receive. The DOTS server should activate other 377 mechanisms to ensure it does not allow the DOTS client domain's pipes 378 to be saturated unintentionally. The rate-limit action defined in 379 [I-D.ietf-dots-data-channel] is a reasonable candidate to achieve 380 this objective; the DOTS client can ask for the type(s) of traffic 381 (such as ICMP, UDP, TCP port number 80) it prefers to limit. The 382 rate-limit action can be controlled via the signal-channel 383 [I-D.ietf-dots-signal-filter-control] even when the pipe is 384 overwhelmed. 386 To summarize: 388 Timely and effective signaling of up-to-date DDoS telemetry to all 389 elements involved in the mitigation process is essential and 390 absolutely improves the overall DDoS mitigation service 391 effectiveness. Bi-directional feedback between DOTS agents is 392 required for an increased awareness of each party, supporting 393 superior and highly efficient attack mitigation service. 395 4. Generic Considerations 397 4.1. DOTS Client Identification 399 Following the rules in [I-D.ietf-dots-signal-channel], a unique 400 identifier is generated by a DOTS client to prevent request 401 collisions ('cuid'). 403 As a reminder, [I-D.ietf-dots-signal-channel] forbids 'cuid' to be 404 returned in a response message body. 406 4.2. DOTS Gateways 408 DOTS gateways may be located between DOTS clients and servers. The 409 considerations elaborated in [I-D.ietf-dots-signal-channel] must be 410 followed. In particular, 'cdid' attribute is used to unambiguously 411 identify a DOTS client domain. 413 As a reminder, [I-D.ietf-dots-signal-channel] forbids 'cdid' (if 414 present) to be returned in a response message body. 416 4.3. Empty URI Paths 418 Uri-Path parameters and attributes with empty values MUST NOT be 419 present in a request and render an entire message invalid. 421 4.4. Controlling Configuration Data 423 The DOTS server follows the same considerations discussed in 424 Section of 4.5.3 of [I-D.ietf-dots-signal-channel] for managing DOTS 425 telemetry configuration freshness and notification. Likewise, a DOTS 426 client may control the selection of configuration and non- 427 configuration data nodes when sending a GET request by means of the 428 'c' Uri-Query option and following the procedure specified in 429 Section of 4.4.2 of [I-D.ietf-dots-signal-channel]. These 430 considerations are not re-iterated in the following sections. 432 4.5. Block-wise Transfer 434 DOTS clients can use Block-wise transfer [RFC7959] with the 435 recommendation detailed in Section 4.4.2 of 436 [I-D.ietf-dots-signal-channel] to control the size of a response when 437 the data to be returned does not fit within a single datagram. 439 DOTS clients can also use Block1 Option in a PUT request (see 440 Section 2.5 of [RFC7959]) to initiate large transfers, but these 441 Block1 transfers will fail if the inbound "pipe" is running full, so 442 consideration needs to be made to try to fit this PUT into a single 443 transfer, or to separate out the PUT into several discrete PUTs where 444 each of them fits into a single packet. 446 4.6. DOTS Multi-homing Considerations 448 Multi-homed DOTS clients are assumed to follow the recommendations in 449 [I-D.ietf-dots-multihoming] to select which DOTS server to contact 450 and which IP prefixes to include in a telemetry message to a given 451 peer DOTS server. For example, if each upstream network exposes a 452 DOTS server and the DOTS client maintains DOTS channels with all of 453 them, only the information related to prefixes assigned by an 454 upstream network to the DOTS client domain will be signaled via the 455 DOTS channel established with the DOTS server of that upstream 456 network. Considerations related to whether (and how) a DOTS client 457 gleans some telemetry information (e.g., attack details) it receives 458 from a first DOTS server and share it with a second DOTS server are 459 implementation- and deployment-specific. 461 4.7. YANG Considerations 463 Messages exchanged between DOTS agents are serialized using Concise 464 Binary Object Representation (CBOR). CBOR-encoded payloads are used 465 to carry signal channel-specific payload messages which convey 466 request parameters and response information such as errors 467 [I-D.ietf-dots-signal-channel]. 469 This document specifies a YANG module for representing DOTS telemetry 470 message types (Section 9). All parameters in the payload of the DOTS 471 signal channel are mapped to CBOR types as specified in Section 10. 473 This YANG module is not intended to be used via NETCONF/ RESTCONF for 474 DOTS server management purposes; such module is out of the scope of 475 this document. It serves only to provide a data model and encoding, 476 but not a management data model. 478 DOTS servers are allowed to update the non-configurable 'ro' entities 479 in the responses. 481 The DOTS telemetry module (Section 9) uses "enumerations" rather than 482 "identities" to define units, samples, and intervals because 483 otherwise the namespace identifier "ietf-dots-telemetry" must be 484 included when a telemetry attribute is included (e.g., in a 485 mitigation efficacy update). The use of "identities" is thus 486 suboptimal from a message compactness standpoint. 488 4.8. A Note About Examples 490 Examples are provided for illustration purposes. The document does 491 not aim to provide a comprehensive list of message examples. 493 The authoritative reference for validating telemetry messages is the 494 YANG module (Section 9) and the mapping table established in 495 Section 10. 497 5. Telemetry Operation Paths 499 As discussed in [I-D.ietf-dots-signal-channel], each DOTS operation 500 is indicated by a path-suffix that indicates the intended operation. 501 The operation path is appended to the path-prefix to form the URI 502 used with a CoAP request to perform the desired DOTS operation. The 503 following telemetry path-suffixes are defined (Table 1): 505 +-----------------+----------------+-----------+ 506 | Operation | Operation Path | Details | 507 +-----------------+----------------+-----------+ 508 | Telemetry Setup | /tm-setup | Section 6 | 509 | Telemetry | /tm | Section 7 | 510 +-----------------+----------------+-----------+ 512 Table 1: DOTS Telemetry Operations 514 Consequently, the "ietf-dots-telemetry" YANG module defined in this 515 document (Section 9) augments the "ietf-dots-signal" with two new 516 message types called "telemetry-setup" and "telemetry". The tree 517 structure is shown in Figure 1 (more details are provided in the 518 following sections about the exact structure of "telemetry-setup" and 519 "telemetry" message types). 521 augment /ietf-signal:dots-signal/ietf-signal:message-type: 522 +--:(telemetry-setup) {dots-telemetry}? 523 | ... 524 | +--rw (setup-type)? 525 | +--:(telemetry-config) 526 | | ... 527 | +--:(pipe) 528 | | ... 529 | +--:(baseline) 530 | ... 531 +--:(telemetry) {dots-telemetry}? 532 ... 534 Figure 1: New DOTS Message Types (YANG Tree Structure) 536 6. DOTS Telemetry Setup Configuration 538 In reference to Figure 1, a DOTS telemetry setup message MUST include 539 only telemetry-related configuration parameters (Section 6.1) or 540 information about DOTS client domain pipe capacity (Section 6.2) or 541 telemetry traffic baseline (Section 6.3). As such, requests that 542 include a mix of telemetry configuration, pipe capacity, or traffic 543 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 545 A DOTS client can reset all installed DOTS telemetry setup 546 configuration data following the considerations detailed in 547 Section 6.4. 549 A DOTS server may detect conflicts when processing requests related 550 to DOTS client domain pipe capacity or telemetry traffic baseline 551 with requests from other DOTS clients of the same DOTS client domain. 552 More details are included in Section 6.5. 554 Telemetry setup configuration is bound to a DOTS client domain. DOTS 555 serves MUST NOT expect DOTS clients to send regular requests to 556 refresh the telemetry setup configuration. Any available telemetry 557 setup configuration has a validity timeout of the DOTS session with a 558 DOTS client domain. DOTS clients update their telemetry setup 559 configuration upon change of a parameter that may impact attack 560 mitigation. 562 DOTS telemetry setup configuration request and response messages are 563 marked as Confirmable messages. 565 6.1. Telemetry Configuration 567 A DOTS client can negotiate with its server(s) a set of telemetry 568 configuration parameters to be used for telemetry. Such parameters 569 include: 571 o Percentile-related measurement parameters 573 o Measurement units 575 o Acceptable percentile values 577 o Telemetry notification interval 579 o Acceptable Server-originated telemetry 581 Section 11.3 of [RFC2330] includes more details about computing 582 percentiles. 584 6.1.1. Retrieve Current DOTS Telemetry Configuration 586 A GET request is used to obtain acceptable and current telemetry 587 configuration parameters on the DOTS server. This request may 588 include a 'cdid' Path-URI when the request is relayed by a DOTS 589 gateway. An example of such request is depicted in Figure 2. 591 Header: GET (Code=0.01) 592 Uri-Path: ".well-known" 593 Uri-Path: "dots" 594 Uri-Path: "tm-setup" 595 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 597 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 598 Configuration 600 Upon receipt of such request, the DOTS server replies with a 2.05 601 (Content) response that conveys the current and telemetry parameters 602 acceptable by the DOTS server. The tree structure of the response 603 message body is provided in Figure 3. Note that the response also 604 includes any pipe (Section 6.2) and baseline information 605 (Section 6.3) maintained by the DOTS server for this DOTS client. 607 DOTS servers that support the capability of sending telemetry 608 information to DOTS clients prior or during a mitigation 609 (Section 8.2) sets 'server-originated-telemetry' under 'max-config- 610 values' to 'true' ('false' is used otherwise). If 'server- 611 originated-telemetry' is not present in a response, this is 612 equivalent to receiving a request with 'server-originated-telemetry'' 613 set to 'false'. 615 augment /ietf-signal:dots-signal/ietf-signal:message-type: 616 +--:(telemetry-setup) {dots-telemetry}? 617 | +--ro max-config-values 618 | | +--ro measurement-interval? interval 619 | | +--ro measurement-sample? sample 620 | | +--ro low-percentile? percentile 621 | | +--ro mid-percentile? percentile 622 | | +--ro high-percentile? percentile 623 | | +--ro server-originated-telemetry? boolean 624 | | +--ro telemetry-notify-interval? uint32 625 | +--ro min-config-values 626 | | +--ro measurement-interval? interval 627 | | +--ro measurement-sample? sample 628 | | +--ro low-percentile? percentile 629 | | +--ro mid-percentile? percentile 630 | | +--ro high-percentile? percentile 631 | | +--ro telemetry-notify-interval? uint32 632 | +--ro supported-units 633 | | +--ro unit-config* [unit] 634 | | +--ro unit unit-type 635 | | +--ro unit-status? boolean 636 | +--rw telemetry* [cuid tsid] 637 | +--rw cuid string 638 | +--rw cdid? string 639 | +--rw tsid uint32 640 | +--rw (setup-type)? 641 | +--:(telemetry-config) 642 | | +--rw current-config 643 | | +--rw measurement-interval? interval 644 | | +--rw measurement-sample? sample 645 | | +--rw low-percentile? percentile 646 | | +--rw mid-percentile? percentile 647 | | +--rw high-percentile? percentile 648 | | +--rw unit-config* [unit] 649 | | | +--rw unit unit-type 650 | | | +--rw unit-status? boolean 651 | | +--rw server-originated-telemetry? boolean 652 | | +--rw telemetry-notify-interval? uint32 653 | +--:(pipe) 654 | ... 655 | +--:(baseline) 656 | ... 657 +--:(telemetry) {dots-telemetry}? 658 +--rw pre-or-ongoing-mitigation* [cuid tmid] 659 ... 661 Figure 3: Telemetry Configuration Tree Structure 663 When both 'min-config-values' and 'max-config-values' attributes are 664 present, the values carried in 'max-config-values' attributes MUST be 665 greater or equal to their counterpart in 'min-config-values' 666 attributes. 668 6.1.2. Convey DOTS Telemetry Configuration 670 PUT request is used to convey the configuration parameters for the 671 telemetry data (e.g., low, mid, or high percentile values). For 672 example, a DOTS client may contact its DOTS server to change the 673 default percentile values used as baseline for telemetry data. 674 Figure 3 lists the attributes that can be set by a DOTS client in 675 such PUT request. An example of a DOTS client that modifies all 676 percentile reference values is shown in Figure 4. 678 Header: PUT (Code=0.03) 679 Uri-Path: ".well-known" 680 Uri-Path: "dots" 681 Uri-Path: "tm-setup" 682 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 683 Uri-Path: "tsid=123" 684 Content-Format: "application/dots+cbor" 686 { 687 "ietf-dots-telemetry:telemetry-setup": { 688 "telemetry": [ 689 { 690 "current-config": { 691 "low-percentile": "5.00", 692 "mid-percentile": "65.00", 693 "high-percentile": "95.00" 694 } 695 } 696 ] 697 } 698 } 700 Figure 4: PUT to Convey the DOTS Telemetry Configuration 702 'cuid' is a mandatory Uri-Path parameter for PUT requests. 704 The following additional Uri-Path parameter is defined: 706 tsid: Telemetry Setup Identifier is an identifier for the DOTS 707 telemetry setup configuration data represented as an integer. 708 This identifier MUST be generated by DOTS clients. 'tsid' 709 values MUST increase monotonically (when a new PUT is generated 710 by a DOTS client to convey new configuration parameters for the 711 telemetry). 713 This is a mandatory attribute. 715 'cuid' and 'tsid' MUST NOT appear in the PUT request message body. 717 At least one configurable attribute MUST be present in the PUT 718 request. 720 The PUT request with a higher numeric 'tsid' value overrides the DOTS 721 telemetry configuration data installed by a PUT request with a lower 722 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 723 requests for requests carrying telemetry configuration data from a 724 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 725 and no longer be available at the DOTS server. 727 The DOTS server indicates the result of processing the PUT request 728 using the following response codes: 730 o If the request is missing a mandatory attribute, does not include 731 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 732 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 733 in the response. 735 o If the DOTS server does not find the 'tsid' parameter value 736 conveyed in the PUT request in its configuration data and if the 737 DOTS server has accepted the configuration parameters, then a 738 response code 2.01 (Created) MUST be returned in the response. 740 o If the DOTS server finds the 'tsid' parameter value conveyed in 741 the PUT request in its configuration data and if the DOTS server 742 has accepted the updated configuration parameters, 2.04 (Changed) 743 MUST be returned in the response. 745 o If any of the enclosed configurable attribute values are not 746 acceptable to the DOTS server (Section 6.1.1), 4.22 (Unprocessable 747 Entity) MUST be returned in the response. 749 The DOTS client may re-try and send the PUT request with updated 750 attribute values acceptable to the DOTS server. 752 By default, low percentile (10th percentile), mid percentile (50th 753 percentile), high percentile (90th percentile), and peak (100th 754 percentile) values are used to represent telemetry data. 755 Nevertheless, a DOTS client can disable some percentile types (low, 756 mid, high). In particular, setting 'low-percentile' to '0.00' 757 indicates that the DOTS client is not interested in receiving low- 758 percentiles. Likewise, setting 'mid-percentile' (or 'high- 759 percentile') to the same value as 'low-percentile' (or 'mid- 760 percentile') indicates that the DOTS client is not interested in 761 receiving mid-percentiles (or high-percentiles). For example, a DOTS 762 client can send the request depicted in Figure 5 to inform the server 763 that it is interested in receiving only high-percentiles. This 764 assumes that the client will only use that percentile type when 765 sharing telemetry data with the server. 767 Header: PUT (Code=0.03) 768 Uri-Path: ".well-known" 769 Uri-Path: "dots" 770 Uri-Path: "tm-setup" 771 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 772 Uri-Path: "tsid=569" 773 Content-Format: "application/dots+cbor" 775 { 776 "ietf-dots-telemetry:telemetry-setup": { 777 "telemetry": [ 778 { 779 "current-config": { 780 "low-percentile": "0.00", 781 "mid-percentile": "0.00", 782 "high-percentile": "95.00" 783 } 784 } 785 ] 786 } 787 } 789 Figure 5: PUT to Disable Low- and Mid-Percentiles 791 DOTS clients can also configure the unit type(s) to be used for 792 traffic-related telemetry data. Typically, the supported unit types 793 are: packets per second, bits per second, and bytes per second. 795 DOTS clients that are interested to receive pre- or onoing mitigation 796 telemetry (pre-or-ongoing-mitigation) information from a DOTS server 797 (Section 8.2) MUST set 'server-originated-telemetry' to 'true'. If 798 'server-originated-telemetry' is not present in a PUT request, this 799 is equivalent to receiving a request with 'server-originated- 800 telemetry'' set to 'false'. An example of a request to enable pre- 801 or-ongoing-mitigation telemetry from DOTS servers is shown in 802 Figure 6. 804 Header: PUT (Code=0.03) 805 Uri-Path: ".well-known" 806 Uri-Path: "dots" 807 Uri-Path: "tm-setup" 808 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 809 Uri-Path: "tsid=569" 810 Content-Format: "application/dots+cbor" 812 { 813 "ietf-dots-telemetry:telemetry-setup": { 814 "telemetry": [ 815 { 816 "current-config": { 817 "server-originated-telemetry": true 818 } 819 } 820 ] 821 } 822 } 824 Figure 6: PUT to Enable Pre-or-ongoing-mitigation Telemetry from the 825 DOTS server 827 6.1.3. Retrieve Installed DOTS Telemetry Configuration 829 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 830 to retrieve the current DOTS telemetry configuration. An example of 831 such request is depicted in Figure 7. 833 Header: GET (Code=0.01) 834 Uri-Path: ".well-known" 835 Uri-Path: "dots" 836 Uri-Path: "tm-setup" 837 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 838 Uri-Path: "tsid=123" 840 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 842 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 843 in the GET request in its configuration data for the requesting DOTS 844 client, it MUST respond with a 4.04 (Not Found) error response code. 846 6.1.4. Delete DOTS Telemetry Configuration 848 A DELETE request is used to delete the installed DOTS telemetry 849 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 850 Path parameters for such DELETE requests. 852 Header: DELETE (Code=0.04) 853 Uri-Path: ".well-known" 854 Uri-Path: "dots" 855 Uri-Path: "tm-setup" 856 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 857 Uri-Path: "tsid=123" 859 Figure 8: Delete Telemetry Configuration 861 The DOTS server resets the DOTS telemetry configuration back to the 862 default values and acknowledges a DOTS client's request to remove the 863 DOTS telemetry configuration using 2.02 (Deleted) response code. A 864 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 865 value conveyed in the DELETE request does not exist in its 866 configuration data before the request. 868 Section 6.4 discusses the procedure to reset all DOTS telemetry setup 869 configuration. 871 6.2. Total Pipe Capacity 873 A DOTS client can communicate to its server(s) its DOTS client domain 874 pipe information. The tree structure of the pipe information is 875 shown in Figure 9. 877 augment /ietf-signal:dots-signal/ietf-signal:message-type: 878 +--:(telemetry-setup) {dots-telemetry}? 879 | ... 880 | +--rw telemetry* [cuid tsid] 881 | +--rw cuid string 882 | +--rw cdid? string 883 | +--rw tsid uint32 884 | +--rw (setup-type)? 885 | +--:(telemetry-config) 886 | | ... 887 | +--:(pipe) 888 | | +--rw total-pipe-capacity* [link-id unit] 889 | | +--rw link-id nt:link-id 890 | | +--rw capacity uint64 891 | | +--rw unit unit 892 | +--:(baseline) 893 | ... 894 +--:(telemetry) {dots-telemetry}? 895 +--rw pre-or-ongoing-mitigation* [cuid tmid] 896 ... 898 Figure 9: Pipe Tree Structure 900 A DOTS client domain pipe is defined as a list of limits of 901 (incoming) traffic volume (total-pipe-capacity") that can be 902 forwarded over ingress interconnection links of a DOTS client domain. 903 Each of these links is identified with a "link-id" [RFC8345]. 905 The unit used by a DOTS client when conveying pipe information is 906 captured in 'unit' attribute. 908 6.2.1. Convey DOTS Client Domain Pipe Capacity 910 Similar considerations to those specified in Section 6.1.2 are 911 followed with one exception: 913 The relative order of two PUT requests carrying DOTS client domain 914 pipe attributes from a DOTS client is determined by comparing 915 their respective 'tsid' values. If such two requests have 916 overlapping "link-id" and "unit", the PUT request with higher 917 numeric 'tsid' value will override the request with a lower 918 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 919 automatically deleted and no longer be available. 921 DOTS clients SHOULD minimize the number of active 'tsids' used for 922 pipe information. Typically, in order to avoid maintaining a long 923 list of 'tsids' for pipe information, it is RECOMMENDED that DOTS 924 clients include in any request to update information related to a 925 given link the information of other links (already communicated using 926 a lower 'tsid' value). Doing so, this update request will override 927 these existing requests and hence optimize the number of 'tsid' 928 request per DOTS client. 930 o Note: This assumes that all link information can fit in one single 931 message. 933 For example, a DOTS client managing a single homed domain (Figure 10) 934 can send a PUT request (shown in Figure 11) to communicate the 935 capacity of "link1" used to connect to its ISP. 937 ,--,--,--. ,--,--,--. 938 ,-' `-. ,-' `-. 939 ( DOTS Client )=====( ISP#A ) 940 `-. Domain ,-' link1 `-. ,-' 941 `--'--'--' `--'--'--' 943 Figure 10: Single Homed DOTS Client Domain 945 Header: PUT (Code=0.03) 946 Uri-Path: ".well-known" 947 Uri-Path: "dots" 948 Uri-Path: "tm-setup" 949 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 950 Uri-Path: "tsid=457" 951 Content-Format: "application/dots+cbor" 953 { 954 "ietf-dots-telemetry:telemetry-setup": { 955 "telemetry": [ 956 { 957 "total-pipe-capacity": [ 958 { 959 "link-id": "link1", 960 "capacity": "500", 961 "unit": "megabit-ps" 962 } 963 ] 964 } 965 ] 966 } 967 } 969 Figure 11: Example of a PUT Request to Convey Pipe Information 970 (Single Homed) 972 DOTS clients may be instructed to signal a link aggregate instead of 973 individual links. For example, a DOTS client managing a DOTS client 974 domain having two interconnection links with an upstream ISP 975 (Figure 12) can send a PUT request (shown in Figure 13) to 976 communicate the aggregate link capacity with its ISP. Signalling 977 individual or aggregate link capacity is deployment-specific. 979 ,--,--,--. ,--,--,--. 980 ,-' `-.===== ,-' `-. 981 ( DOTS Client ) ( ISP#C ) 982 `-. Domain ,-'====== `-. ,-' 983 `--'--'--' `--'--'--' 985 Figure 12: DOTS Client Domain with Two Interconnection Links 987 Header: PUT (Code=0.03) 988 Uri-Path: ".well-known" 989 Uri-Path: "dots" 990 Uri-Path: "tm-setup" 991 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 992 Uri-Path: "tsid=896" 993 Content-Format: "application/dots+cbor" 995 { 996 "ietf-dots-telemetry:telemetry-setup": { 997 "telemetry": [ 998 { 999 "total-pipe-capacity": [ 1000 { 1001 "link-id": "aggregate", 1002 "capacity": "700", 1003 "unit": "megabit-ps" 1004 } 1005 ] 1006 } 1007 ] 1008 } 1009 } 1011 Figure 13: Example of a PUT Request to Convey Pipe Information 1012 (Aggregated Link) 1014 Now consider that the DOTS client domain was upgraded to connect to 1015 an additional ISP (ISP#B of Figure 14), the DOTS client can inform a 1016 third-party DOTS server (that is, not hosted with ISP#A and ISP#B 1017 domains) about this update by sending the PUT request depicted in 1018 Figure 15. This request also includes information related to "link1" 1019 even if that link is not upgraded. Upon receipt of this request, the 1020 DOTS server removes the request with 'tsid=457' and updates its 1021 configuration base to maintain two links (link#1 and link#2). 1023 ,--,--,--. 1024 ,-' `-. 1025 ( ISP#B ) 1026 `-. ,-' 1027 `--'--'--' 1028 || 1029 || link2 1030 ,--,--,--. ,--,--,--. 1031 ,-' `-. ,-' `-. 1032 ( DOTS Client )=====( ISP#A ) 1033 `-. Domain ,-' link1 `-. ,-' 1034 `--'--'--' `--'--'--' 1036 Figure 14: Multi-Homed DOTS Client Domain 1038 Header: PUT (Code=0.03) 1039 Uri-Path: ".well-known" 1040 Uri-Path: "dots" 1041 Uri-Path: "tm-setup" 1042 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1043 Uri-Path: "tsid=458" 1044 Content-Format: "application/dots+cbor" 1046 { 1047 "ietf-dots-telemetry:telemetry-setup": { 1048 "telemetry": [ 1049 { 1050 "total-pipe-capacity": [ 1051 { 1052 "link-id": "link1", 1053 "capacity": "500", 1054 "unit": "megabit-ps" 1055 }, 1056 { 1057 "link-id": "link2", 1058 "capacity": "500", 1059 "unit": "megabit-ps" 1060 } 1061 ] 1062 } 1063 ] 1064 } 1065 } 1067 Figure 15: Example of a PUT Request to Convey Pipe Information 1068 (Multi-Homed) 1070 A DOTS client can delete a link by sending a PUT request with the 1071 'capacity' attribute set to "0" if other links are still active for 1072 the same DOTS client domain (see Section 6.2.3 for other delete 1073 cases). For example, if a DOTS client domain re-homes (that is, it 1074 changes its ISP), the DOTS client can inform its DOTS server about 1075 this update (e.g., from the network configuration in Figure 10 to the 1076 one shown in Figure 16) by sending the PUT request depicted in 1077 Figure 17. Upon receipt of this request, the DOTS server removes 1078 "link1" from its configuration bases for this DOTS client domain. 1080 ,--,--,--. 1081 ,-' `-. 1082 ( ISP#B ) 1083 `-. ,-' 1084 `--'--'--' 1085 || 1086 || link2 1087 ,--,--,--. 1088 ,-' `-. 1089 ( DOTS Client ) 1090 `-. Domain ,-' 1091 `--'--'--' 1093 Figure 16: Multi-Homed DOTS Client Domain 1095 Header: PUT (Code=0.03) 1096 Uri-Path: ".well-known" 1097 Uri-Path: "dots" 1098 Uri-Path: "tm-setup" 1099 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1100 Uri-Path: "tsid=459" 1101 Content-Format: "application/dots+cbor" 1103 { 1104 "ietf-dots-telemetry:telemetry-setup": { 1105 "telemetry": [ 1106 { 1107 "total-pipe-capacity": [ 1108 { 1109 "link-id": "link1", 1110 "capacity": "0", 1111 "unit": "megabit-ps" 1112 }, 1113 { 1114 "link-id": "link2", 1115 "capacity": "500", 1116 "unit": "megabit-ps" 1117 } 1118 ] 1119 } 1120 ] 1121 } 1122 } 1124 Figure 17: Example of a PUT Request to Convey Pipe Information 1125 (Multi-Homed) 1127 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity 1129 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1130 specific installed DOTS client domain pipe related information. The 1131 same procedure as defined in (Section 6.1.3) is followed. 1133 To retrieve all pipe information bound to a DOTS client, the DOTS 1134 client proceeds as specified in Section 6.1.1. 1136 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity 1138 A DELETE request is used to delete the installed DOTS client domain 1139 pipe related information. The same procedure as defined in 1140 (Section 6.1.4) is followed. 1142 6.3. Telemetry Baseline 1144 A DOTS client can communicate to its server(s) its normal traffic 1145 baseline and connections capacity: 1147 Total traffic normal baseline: The percentile values representing 1148 the total traffic normal baseline. It can be represented for a 1149 target using 'total-traffic-normal'. 1151 The traffic normal per protocol ('total-traffic-normal-per- 1152 protocol') baseline is represented for a target and is transport- 1153 protocol specific. 1155 The traffic normal per port number ('total-traffic-normal-per- 1156 port') baseline is represented for each port number bound to a 1157 target. 1159 If the DOTS client negotiated percentile values and units 1160 (Section 6.1), these negotiated values will be used instead of the 1161 default ones. 1163 Total connections capacity: If the target is subjected to resource 1164 consuming DDoS attacks, the following optional attributes for the 1165 target per transport-protocol are useful to detect resource 1166 consuming DDoS attacks: 1168 * The maximum number of simultaneous connections that are allowed 1169 to the target. 1171 * The maximum number of simultaneous connections that are allowed 1172 to the target per client. 1174 * The maximum number of simultaneous embryonic connections that 1175 are allowed to the target. The term "embryonic connection" 1176 refers to a connection whose connection handshake is not 1177 finished. Embryonic connection is only possible in connection- 1178 oriented transport protocols like TCP or SCTP. 1180 * The maximum number of simultaneous embryonic connections that 1181 are allowed to the target per client. 1183 * The maximum number of connections allowed per second to the 1184 target. 1186 * The maximum number of connections allowed per second to the 1187 target per client. 1189 * The maximum number of requests allowed per second to the 1190 target. 1192 * The maximum number of requests allowed per second to the target 1193 per client. 1195 * The maximum number of partial requests allowed per second to 1196 the target. Attacks relying upon partial requests create a 1197 connection with a target but do not send a complete request 1198 (e.g., HTTP request). 1200 * The maximum number of partial requests allowed per second to 1201 the target per client. 1203 The aggregate per transport protocol is captured in 'total- 1204 connection-capacity', while port-specific capabilities are 1205 represented using 'total-connection-capacity-per-port'. 1207 The tree structure of the baseline is shown in Figure 18. 1209 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1210 +--:(telemetry-setup) {dots-telemetry}? 1211 | ... 1212 | +--rw telemetry* [cuid tsid] 1213 | +--rw cuid string 1214 | +--rw cdid? string 1215 | +--rw tsid uint32 1216 | +--rw (setup-type)? 1217 | +--:(telemetry-config) 1218 | | ... 1219 | +--:(pipe) 1220 | | ... 1221 | +--:(baseline) 1222 | +--rw baseline* [id] 1223 | +--rw id uint32 1224 | +--rw target-prefix* inet:ip-prefix 1225 | +--rw target-port-range* [lower-port] 1226 | | +--rw lower-port inet:port-number 1227 | | +--rw upper-port? inet:port-number 1228 | +--rw target-protocol* uint8 1229 | +--rw target-fqdn* inet:domain-name 1230 | +--rw target-uri* inet:uri 1231 | +--rw alias-name* string 1232 | +--rw total-traffic-normal* [unit] 1233 | | +--rw unit unit 1234 | | +--rw low-percentile-g? yang:gauge64 1235 | | +--rw mid-percentile-g? yang:gauge64 1236 | | +--rw high-percentile-g? yang:gauge64 1237 | | +--rw peak-g? yang:gauge64 1238 | +--rw total-traffic-normal-per-protocol* [unit protocol] 1239 | | +--rw unit unit 1240 | | +--rw protocol uint8 1241 | | +--rw low-percentile-g? yang:gauge64 1242 | | +--rw mid-percentile-g? yang:gauge64 1243 | | +--rw high-percentile-g? yang:gauge64 1244 | | +--rw peak-g? yang:gauge64 1245 | +--rw total-traffic-normal-per-port* [unit port] 1246 | | +--rw port inet:port-number 1247 | | +--rw unit unit 1248 | | +--rw low-percentile-g? yang:gauge64 1249 | | +--rw mid-percentile-g? yang:gauge64 1250 | | +--rw high-percentile-g? yang:gauge64 1251 | | +--rw peak-g? yang:gauge64 1252 | +--rw total-connection-capacity* [protocol] 1253 | | +--rw protocol uint8 1254 | | +--rw connection? uint64 1255 | | +--rw connection-client? uint64 1256 | | +--rw embryonic? uint64 1257 | | +--rw embryonic-client? uint64 1258 | | +--rw connection-ps? uint64 1259 | | +--rw connection-client-ps? uint64 1260 | | +--rw request-ps? uint64 1261 | | +--rw request-client-ps? uint64 1262 | | +--rw partial-request-ps? uint64 1263 | | +--rw partial-request-client-ps? uint64 1264 | +--rw total-connection-capacity-per-port* [protocol port] 1265 | +--rw protocol uint8 1266 | +--rw port inet:port-number 1267 | +--rw connection? uint64 1268 | +--rw connection-client? uint64 1269 | +--rw embryonic? uint64 1270 | +--rw embryonic-client? uint64 1271 | +--rw connection-ps? uint64 1272 | +--rw connection-client-ps? uint64 1273 | +--rw request-ps? uint64 1274 | +--rw request-client-ps? uint64 1275 | +--rw partial-request-ps? uint64 1276 | +--rw partial-request-client-ps? uint64 1277 +--:(telemetry) {dots-telemetry}? 1278 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1279 ... 1281 Figure 18: Telemetry Baseline Tree Structure 1283 6.3.1. Convey DOTS Client Domain Baseline Information 1285 Similar considerations to those specified in Section 6.1.2 are 1286 followed with one exception: 1288 The relative order of two PUT requests carrying DOTS client domain 1289 baseline attributes from a DOTS client is determined by comparing 1290 their respective 'tsid' values. If such two requests have 1291 overlapping targets, the PUT request with higher numeric 'tsid' 1292 value will override the request with a lower numeric 'tsid' value. 1293 The overlapped lower numeric 'tsid' MUST be automatically deleted 1294 and no longer be available. 1296 Two PUT requests from a DOTS client have overlapping targets if there 1297 is a common IP address, IP prefix, FQDN, or URI. 1299 DOTS clients SHOULD minimize the number of active 'tsids' used for 1300 baseline information. Typically, in order to avoid maintaining a 1301 long list of 'tsids' for baseline information, it is RECOMMENDED that 1302 DOTS clients include in a request to update information related to a 1303 given target, the information of other targets (already communicated 1304 using a lower 'tsid' value) (assuming this fits within one single 1305 datagram). This update request will override these existing requests 1306 and hence optimize the number of 'tsid' request per DOTS client. 1308 If no target clause in included in the request, this is an indication 1309 that the baseline information applies for the DOTS client domain as a 1310 whole. 1312 An example of a PUT request to convey the baseline information is 1313 shown in Figure 19. 1315 Header: PUT (Code=0.03) 1316 Uri-Path: ".well-known" 1317 Uri-Path: "dots" 1318 Uri-Path: "tm-setup" 1319 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1320 Uri-Path: "tsid=126" 1321 Content-Format: "application/dots+cbor" 1323 { 1324 "ietf-dots-telemetry:telemetry": { 1325 { 1326 "ietf-dots-telemetry:telemetry-setup": { 1327 "telemetry": [ 1328 { 1329 "baseline": { 1330 "id": 1, 1331 "target-prefix": [ 1332 "2001:db8:6401::1/128", 1333 "2001:db8:6401::2/128" 1334 ], 1335 "total-traffic-normal": [{ 1336 "unit": "megabit-ps", 1337 "peak-g": "60" 1338 }] 1339 } 1340 } 1341 ] 1342 } 1343 } 1345 Figure 19: PUT to Convey the DOTS Traffic Baseline 1347 The DOTS client may share protocol-specific baseline information 1348 (e.g., TCP and UDP) as shown in Figure 19. 1350 Header: PUT (Code=0.03) 1351 Uri-Path: ".well-known" 1352 Uri-Path: "dots" 1353 Uri-Path: "tm-setup" 1354 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1355 Uri-Path: "tsid=128" 1356 Content-Format: "application/dots+cbor" 1358 { 1359 "ietf-dots-telemetry:telemetry": { 1360 { 1361 "ietf-dots-telemetry:telemetry-setup": { 1362 "telemetry": [ 1363 { 1364 "baseline": { 1365 "id": 1, 1366 "target-prefix": [ 1367 "2001:db8:6401::1/128", 1368 "2001:db8:6401::2/128" 1369 ], 1370 "total-traffic-normal-per-protocol": [ 1371 { 1372 "unit": "megabit-ps", 1373 "protocol": 6, 1374 "peak-g": "50" 1375 }, 1376 { 1377 "unit": "megabit-ps", 1378 "protocol": 17, 1379 "peak-g": "10" 1380 } 1381 ] 1382 } 1383 } 1384 ] 1385 } 1386 } 1388 Figure 20: PUT to Convey the DOTS Traffic Baseline (2) 1390 The traffic baseline information should be updated to reflect 1391 legitimate overloads (e.g., flash crowds) to prevent unnecessary 1392 mitigation. 1394 6.3.2. Retrieve Installed Normal Traffic Baseline 1396 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1397 specific installed DOTS client domain baseline traffic information. 1398 The same procedure as defined in (Section 6.1.3) is followed. 1400 To retrieve all baseline information bound to a DOTS client, the DOTS 1401 client proceeds as specified in Section 6.1.1. 1403 6.3.3. Delete Installed Normal Traffic Baseline 1405 A DELETE request is used to delete the installed DOTS client domain 1406 normal traffic baseline. The same procedure as defined in 1407 (Section 6.1.4) is followed. 1409 6.4. Reset Installed Telemetry Setup 1411 Upon bootstrapping (or reboot or any other event that may alter the 1412 DOTS client setup), a DOTS client MAY send a DELETE request to set 1413 the telemetry parameters to default values. Such a request does not 1414 include any 'tsid'. An example of such request is depicted in 1415 Figure 21. 1417 Header: DELETE (Code=0.04) 1418 Uri-Path: ".well-known" 1419 Uri-Path: "dots" 1420 Uri-Path: "tm-setup" 1421 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1423 Figure 21: Delete Telemetry Configuration 1425 6.5. Conflict with Other DOTS Clients of the Same Domain 1427 A DOTS server may detect conflicts between requests to convey pipe 1428 and baseline information received from DOTS clients of the same DOTS 1429 client domain. 'conflict-information' is used to report the conflict 1430 to the DOTS client following similar conflict handling discussed in 1431 Section 4.4.1 of [I-D.ietf-dots-signal-channel]. The conflict cause 1432 can be set to one of these values: 1434 1: Overlapping targets (already defined in 1435 [I-D.ietf-dots-signal-channel]). 1437 TBA: Overlapping pipe scope (see Section 11). 1439 7. DOTS Pre-or-Ongoing Mitigation Telemetry 1441 There are two broad types of DDoS attacks, one is bandwidth consuming 1442 attack, the other is target resource consuming attack. This section 1443 outlines the set of DOTS telemetry attributes (Section 7.1) that 1444 covers both the types of attacks. The ultimate objective of these 1445 attributes is to allow for the complete knowledge of attacks and the 1446 various particulars that can best characterize attacks. 1448 The "ietf-dots-telemetry" YANG module (Section 9) augments the "ietf- 1449 dots-signal" with a new message type called "telemetry". The tree 1450 structure of the "telemetry" message type is shown Figure 24. 1452 The pre-or-ongoing-mitigation telemetry attributes are indicated by 1453 the path-suffix '/tm'. The '/tm' is appended to the path-prefix to 1454 form the URI used with a CoAP request to signal the DOTS telemetry. 1455 Pre-or-ongoing-mitigation telemetry attributes specified in 1456 Section 7.1 can be signaled between DOTS agents. 1458 Pre-or-ongoing-mitigation telemetry attributes may be sent by a DOTS 1459 client or a DOTS server. 1461 DOTS agents SHOULD bind pre-or-ongoing-mitigation telemetry data with 1462 mitigation requests relying upon the target clause. In particular, a 1463 telemetry PUT request sent after a mitigation request may include a 1464 reference to that mitigation request ('mid-list') as shown in 1465 Figure 22. An example illustrating requests correlation by means of 1466 'target-prefix' is shown in Figure 23. 1468 When generating telemetry data to send to a peer, the DOTS agent must 1469 auto-scale so that appropriate unit(s) are used. 1471 +-----------+ +-----------+ 1472 |DOTS client| |DOTS server| 1473 +-----------+ +-----------+ 1474 | | 1475 |=========Mitigation Request (mid)=====================>| 1476 | | 1477 |================ Telemetry (mid-list{mid})============>| 1478 | | 1480 Figure 22: Example of Request Correlation using 'mid' 1482 +-----------+ +-----------+ 1483 |DOTS client| |DOTS server| 1484 +-----------+ +-----------+ 1485 | | 1486 |<=============== Telemetry (target-prefix)=============| 1487 | | 1488 |=========Mitigation Request (target-prefix)===========>| 1489 | | 1491 Figure 23: Example of Request Correlation using Target Prefix 1493 DOTS agents MUST NOT send pre-or-ongoing-mitigation telemetry 1494 messages to the same peer more frequently than once every 'telemetry- 1495 notify-interval' (Section 6.1). 1497 DOTS pre-or-ongoing-mitigation telemetry request and response 1498 messages MUST be marked as Non-Confirmable messages. 1500 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1501 +--:(telemetry-setup) {dots-telemetry}? 1502 | +--rw telemetry* [cuid tsid] 1503 | ... 1504 +--:(telemetry) {dots-telemetry}? 1505 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1506 +--rw cuid string 1507 +--rw cdid? string 1508 +--rw tmid uint32 1509 +--rw target 1510 | ... 1511 +--rw total-traffic* [unit] 1512 | ... 1513 +--rw total-traffic-protocol* [unit protocol] 1514 | ... 1515 +--rw total-traffic-port* [unit port] 1516 | ... 1517 +--rw total-attack-traffic* [unit] 1518 | ... 1519 +--rw total-attack-traffic-protocol* [unit protocol] 1520 | ... 1521 +--rw total-attack-traffic-port* [unit port] 1522 | ... 1523 +--rw total-attack-connection 1524 | ... 1525 +--rw total-attack-connection-port 1526 | ... 1527 +--rw attack-detail* [attack-id] 1528 ... 1530 Figure 24: Telemetry Message Type Tree Structure 1532 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes 1534 The description and motivation behind each attribute are presented in 1535 Section 3. DOTS telemetry attributes are optionally signaled and 1536 therefore MUST NOT be treated as mandatory fields in the DOTS signal 1537 channel protocol. 1539 7.1.1. Target 1541 A target resource (Figure 25) is identified using the attributes 1542 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1543 fqdn', 'target-uri', or 'alias-name' defined in the base DOTS signal 1544 channel protocol. 1546 +--:(telemetry) {dots-telemetry}? 1547 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1548 +--rw cuid string 1549 +--rw cdid? string 1550 +--rw tmid uint32 1551 +--rw target 1552 | +--rw target-prefix* inet:ip-prefix 1553 | +--rw target-port-range* [lower-port] 1554 | | +--rw lower-port inet:port-number 1555 | | +--rw upper-port? inet:port-number 1556 | +--rw target-protocol* uint8 1557 | +--rw target-fqdn* inet:domain-name 1558 | +--rw target-uri* inet:uri 1559 | +--rw alias-name* string 1560 | +--rw mid-list* uint32 1561 +--rw total-traffic* [unit] 1562 | ... 1563 +--rw total-traffic-protocol* [unit protocol] 1564 | ... 1565 +--rw total-traffic-port* [unit port] 1566 | ... 1567 +--rw total-attack-traffic* [unit] 1568 | ... 1569 +--rw total-attack-traffic-protocol* [unit protocol] 1570 | ... 1571 +--rw total-attack-traffic-port* [unit port] 1572 | ... 1573 +--rw total-attack-connection 1574 | ... 1575 +--rw total-attack-connection-port 1576 | ... 1577 +--rw attack-detail* [attack-id] 1578 ... 1580 Figure 25: Target Tree Structure 1582 At least one of the attributes 'target-prefix', 'target-fqdn', 1583 'target-uri', 'alias-name', or 'mid-list' MUST be present in the 1584 target definition. 1586 If the target is subjected to bandwidth consuming attack, the 1587 attributes representing the percentile values of the 'attack-id' 1588 attack traffic are included. 1590 If the target is subjected to resource consuming DDoS attacks, the 1591 same attributes defined for Section 7.1.4 are applicable for 1592 representing the attack. 1594 This is an optional sub-attribute. 1596 7.1.2. Total Traffic 1598 The 'total-traffic' attribute (Figure 26) conveys the percentile 1599 values of total traffic observed during a DDoS attack. More granular 1600 total traffic can be conveyed in 'total-traffic-protocol' and 'total- 1601 traffic-port'. 1603 The 'total-traffic-protocol' represents the total traffic for a 1604 target and is transport-protocol specific. 1606 The 'total-traffic-port' represents the total traffic for a target 1607 per port number. 1609 +--:(telemetry) {dots-telemetry}? 1610 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1611 +--rw cuid string 1612 +--rw cdid? string 1613 +--rw tmid uint32 1614 +--rw target 1615 | ... 1616 +--rw total-traffic* [unit] 1617 | +--rw unit unit 1618 | +--rw low-percentile-g? yang:gauge64 1619 | +--rw mid-percentile-g? yang:gauge64 1620 | +--rw high-percentile-g? yang:gauge64 1621 | +--rw peak-g? yang:gauge64 1622 +--rw total-traffic-protocol* [unit protocol] 1623 | +--rw protocol uint8 1624 | +--rw unit unit 1625 | +--rw low-percentile-g? yang:gauge64 1626 | +--rw mid-percentile-g? yang:gauge64 1627 | +--rw high-percentile-g? yang:gauge64 1628 | +--rw peak-g? yang:gauge64 1629 +--rw total-traffic-port* [unit port] 1630 | +--rw port inet:port-number 1631 | +--rw unit unit 1632 | +--rw low-percentile-g? yang:gauge64 1633 | +--rw mid-percentile-g? yang:gauge64 1634 | +--rw high-percentile-g? yang:gauge64 1635 | +--rw peak-g? yang:gauge64 1636 +--rw total-attack-traffic* [unit] 1637 | ... 1638 +--rw total-attack-traffic-protocol* [unit protocol] 1639 | ... 1640 +--rw total-attack-traffic-port* [unit port] 1641 | ... 1642 +--rw total-attack-connection 1643 | ... 1644 +--rw total-attack-connection-port 1645 | ... 1646 +--rw attack-detail* [attack-id] 1647 ... 1649 Figure 26: Total Traffic Tree Structure 1651 7.1.3. Total Attack Traffic 1653 The 'total-attack-traffic' attribute (Figure 27) conveys the total 1654 attack traffic identified by the DOTS client domain's DMS (or DDoS 1655 Detector). More granular total traffic can be conveyed in 'total- 1656 attack-traffic-protocol' and 'total-attack-traffic-port'. 1658 The 'total-attack-traffic-protocol' represents the total attack 1659 traffic for a target and is transport-protocol specific. 1661 The 'total-attack-traffic-port' represents the total attack traffic 1662 for a target per port number. 1664 +--:(telemetry) {dots-telemetry}? 1665 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1666 +--rw cuid string 1667 +--rw cdid? string 1668 +--rw tmid uint32 1669 +--rw target 1670 | ... 1671 +--rw total-traffic* [unit] 1672 | ... 1673 +--rw total-traffic-protocol* [unit protocol] 1674 | ... 1675 +--rw total-traffic-port* [unit port] 1676 | ... 1677 +--rw total-attack-traffic* [unit] 1678 | +--rw unit unit 1679 | +--rw low-percentile-g? yang:gauge64 1680 | +--rw mid-percentile-g? yang:gauge64 1681 | +--rw high-percentile-g? yang:gauge64 1682 | +--rw peak-g? yang:gauge64 1683 +--rw total-attack-traffic-protocol* [unit protocol] 1684 | +--rw protocol uint8 1685 | +--rw unit unit 1686 | +--rw low-percentile-g? yang:gauge64 1687 | +--rw mid-percentile-g? yang:gauge64 1688 | +--rw high-percentile-g? yang:gauge64 1689 | +--rw peak-g? yang:gauge64 1690 +--rw total-attack-traffic-port* [unit port] 1691 | +--rw port inet:port-number 1692 | +--rw unit unit 1693 | +--rw low-percentile-g? yang:gauge64 1694 | +--rw mid-percentile-g? yang:gauge64 1695 | +--rw high-percentile-g? yang:gauge64 1696 | +--rw peak-g? yang:gauge64 1697 +--rw total-attack-connection 1698 | ... 1699 +--rw total-attack-connection-port 1700 | ... 1701 +--rw attack-detail* [attack-id] 1702 ... 1704 Figure 27: Total Attack Traffic Tree Structure 1706 7.1.4. Total Attack Connections 1708 If the target is subjected to resource consuming DDoS attack, the 1709 'total-attack-connection' attribute is used to convey the percentile 1710 values of total attack connections. The following optional sub- 1711 attributes for the target per transport-protocol are included to 1712 represent the attack characteristics: 1714 o The number of simultaneous attack connections to the target. 1715 o The number of simultaneous embryonic connections to the target. 1716 o The number of attack connections per second to the target. 1717 o The number of attack requests to the target. 1719 The total attack connections per port number is represented using 1720 'total-attack-connection-port' attribute. 1722 +--:(telemetry) {dots-telemetry}? 1723 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1724 +--rw cuid string 1725 +--rw cdid? string 1726 +--rw tmid uint32 1727 +--rw target 1728 | ... 1729 +--rw total-attack-connection 1730 | +--rw low-percentile-l* [protocol] 1731 | | +--rw protocol uint8 1732 | | +--rw connection? yang:gauge64 1733 | | +--rw embryonic? yang:gauge64 1734 | | +--rw connection-ps? yang:gauge64 1735 | | +--rw request-ps? yang:gauge64 1736 | | +--rw partial-request-ps? yang:gauge64 1737 | +--rw mid-percentile-l* [protocol] 1738 | | +--rw protocol uint8 1739 | | +--rw connection? yang:gauge64 1740 | | +--rw embryonic? yang:gauge64 1741 | | +--rw connection-ps? yang:gauge64 1742 | | +--rw request-ps? yang:gauge64 1743 | | +--rw partial-request-ps? yang:gauge64 1744 | +--rw high-percentile-l* [protocol] 1745 | | +--rw protocol uint8 1746 | | +--rw connection? yang:gauge64 1747 | | +--rw embryonic? yang:gauge64 1748 | | +--rw connection-ps? yang:gauge64 1749 | | +--rw request-ps? yang:gauge64 1750 | | +--rw partial-request-ps? yang:gauge64 1751 | +--rw peak-l* [protocol] 1752 | +--rw protocol uint8 1753 | +--rw connection? yang:gauge64 1754 | +--rw embryonic? yang:gauge64 1755 | +--rw connection-ps? yang:gauge64 1756 | +--rw request-ps? yang:gauge64 1757 | +--rw partial-request-ps? yang:gauge64 1758 +--rw total-attack-connection-port 1759 | +--rw low-percentile-l* [protocol port] 1760 | | +--rw port inet:port-number 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 mid-percentile-l* [protocol port] 1768 | | +--rw port inet:port-number 1769 | | +--rw protocol uint8 1770 | | +--rw connection? yang:gauge64 1771 | | +--rw embryonic? yang:gauge64 1772 | | +--rw connection-ps? yang:gauge64 1773 | | +--rw request-ps? yang:gauge64 1774 | | +--rw partial-request-ps? yang:gauge64 1775 | +--rw high-percentile-l* [protocol port] 1776 | | +--rw port inet:port-number 1777 | | +--rw protocol uint8 1778 | | +--rw connection? yang:gauge64 1779 | | +--rw embryonic? yang:gauge64 1780 | | +--rw connection-ps? yang:gauge64 1781 | | +--rw request-ps? yang:gauge64 1782 | | +--rw partial-request-ps? yang:gauge64 1783 | +--rw peak-l* [protocol port] 1784 | +--rw port inet:port-number 1785 | +--rw protocol uint8 1786 | +--rw connection? yang:gauge64 1787 | +--rw embryonic? yang:gauge64 1788 | +--rw connection-ps? yang:gauge64 1789 | +--rw request-ps? yang:gauge64 1790 | +--rw partial-request-ps? yang:gauge64 1791 +--rw attack-detail* [attack-id] 1792 ... 1794 Figure 28: Total Attack Connections Tree Structure 1796 7.1.5. Attack Details 1798 This attribute (Figure 29) is used to signal a set of details 1799 characterizing an attack. The following sub-attributes describing 1800 the on-going attack can be signal as attack details. 1802 id: Vendor ID is a security vendor's Enterprise Number as registered 1803 with IANA [Enterprise-Numbers]. It is a four-byte integer value. 1805 attack-id: Unique identifier assigned for the attack. 1807 attack-name: Textual representation of attack description. Natural 1808 Language Processing techniques (e.g., word embedding) can possibly 1809 be used to map the attack description to an attack type. Textual 1810 representation of attack solves two problems: (a) avoids the need 1811 to create mapping tables manually between vendors and (2) avoids 1812 the need to standardize attack types which keep evolving. 1814 attack-severity: Attack severity. These values are supported: 1815 emergency (1), critical (2), and alert (3). 1817 start-time: The time the attack started. The attack's start time is 1818 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1819 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1820 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1822 end-time: The time the attack-id attack ended. The attack end time 1823 is expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1824 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1825 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1827 source-count: A count of sources involved in the attack targeting 1828 the victim. 1830 top-talkers: A list of top talkers among attack sources. The top 1831 talkers are represented using the 'source-prefix'. 1833 'spoofed-status' is used whether a top talker is a spoofed IP 1834 address (e.g., reflection attacks) or not. 1836 If the target is subjected to bandwidth consuming attack, the 1837 attack traffic from each of the top talkers is included ('total- 1838 attack-traffic', Section 7.1.3). 1840 If the target is subjected to resource consuming DDoS attacks, the 1841 same attributes defined for Section 7.1.4 are applicable for 1842 representing the attack per talker. 1844 +--:(telemetry) {dots-telemetry}? 1845 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1846 +--rw cuid string 1847 +--rw cdid? string 1848 +--rw tmid uint32 1849 +--rw target 1850 | ... 1851 +--rw attack-detail* [attack-id] 1852 +--rw id? uint32 1853 +--rw attack-id string 1854 +--rw attack-name? string 1855 +--rw attack-severity? attack-severity 1856 +--rw start-time? uint64 1857 +--rw end-time? uint64 1858 +--rw top-talker 1859 +--rw talker* [source-prefix] 1860 +--rw spoofed-status? boolean 1861 +--rw source-prefix inet:ip-prefix 1862 +--rw source-port-range* [lower-port] 1863 | +--rw lower-port inet:port-number 1864 | +--rw upper-port? inet:port-number 1865 +--rw source-icmp-type-range* [lower-type] 1866 | +--rw lower-type uint8 1867 | +--rw upper-type? uint8 1868 +--rw total-attack-traffic* [unit] 1869 | +--rw unit unit 1870 | +--rw low-percentile-g? yang:gauge64 1871 | +--rw mid-percentile-g? yang:gauge64 1872 | +--rw high-percentile-g? yang:gauge64 1873 | +--rw peak-g? yang:gauge64 1874 +--rw total-attack-connection 1875 +--rw low-percentile-l* [protocol] 1876 | ... 1877 +--rw mid-percentile-l* [protocol] 1878 | ... 1879 +--rw high-percentile-l* [protocol] 1880 | ... 1881 +--rw peak-l* [protocol] 1882 ... 1884 Figure 29: Attack Detail Tree Structure 1886 7.2. From DOTS Clients to DOTS Servers 1888 DOTS clients uses PUT request to signal pre-or-ongoing-mitigation 1889 telemetry to DOTS servers. An example of such request is shown in 1890 Figure 30. 1892 Header: PUT (Code=0.03) 1893 Uri-Path: ".well-known" 1894 Uri-Path: "dots" 1895 Uri-Path: "tm" 1896 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1897 Uri-Path: "tmid=123" 1898 Content-Format: "application/dots+cbor" 1900 { 1901 "ietf-dots-telemetry:telemetry": { 1902 "pre-or-ongoing-mitigation": { 1903 "target": { 1904 { 1905 "target-prefix": [ 1906 "2001:db8::1/128" 1907 ], 1908 "total-attack-traffic-protocol": [ 1909 { 1910 "protocol": 17, 1911 "unit": "megabit-ps", 1912 "mid-percentile-g": "900" 1913 } 1914 ], 1915 "attack-detail": [ 1916 { 1917 "attack-id": "an-id"; 1918 "start-time": "1957811234", 1919 "attack-severity": "emergency" 1920 } 1921 ] 1922 } 1923 } 1924 } 1925 } 1926 } 1928 Figure 30: PUT to Send Pre-or-Ongoing-Mitigation Telemetry 1930 'cuid' is a mandatory Uri-Path parameter for PUT requests. 1932 The following additional Uri-Path parameter is defined: 1934 tmid: Telemetry Identifier is an identifier for the DOTS pre-or- 1935 ongoing-mitigation telemetry data represented as an integer. 1936 This identifier MUST be generated by DOTS clients. 'tmid' values 1937 MUST increase monotonically (when a new PUT is generated by a 1938 DOTS client to convey pre-or-ongoing-mitigation telemetry). 1940 This is a mandatory attribute. 1942 'cuid' and 'tmid' MUST NOT appear in the PUT request message body. 1944 At least 'target' attribute and another pre-or-ongoing-mitigation 1945 attributes (Section 7.1) MUST be present in the PUT request. If only 1946 the 'target' attribute is present, this request is handled as per 1947 Section 7.3. 1949 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 1950 mitigation telemetry from a DOTS client is determined by comparing 1951 their respective 'tmid' values. If such two requests have 1952 overlapping 'target', the PUT request with higher numeric 'tmid' 1953 value will override the request with a lower numeric 'tmid' value. 1954 The overlapped lower numeric 'tmid' MUST be automatically deleted and 1955 no longer be available. 1957 The DOTS server indicates the result of processing a PUT request 1958 using CoAP response codes. The response code 2.04 (Changed) is 1959 returned if the DOTS server has accepted the pre-or-ongoing- 1960 mitigation telemetry. The error response code 5.03 (Service 1961 Unavailable) is returned if the DOTS server has erred. 5.03 uses Max- 1962 Age option to indicate the number of seconds after which to retry. 1964 How long a DOTS server maintains a 'tmid' as active or logs the 1965 enclosed telemetry information is implementation-specific. Note that 1966 if a 'tmid' is still active, then logging details are updated by the 1967 DOTS server as a function of the updates received from the peer DOTS 1968 client. 1970 A DOTS client that lost the state of its active 'tmids' or has to set 1971 'tmid' back to zero (e.g., crash or restart) MUST send a GET request 1972 to the DOTS server to retrieve the list of active 'tmid'. The DOTS 1973 client may then delete 'tmids' that should not be active anymore 1974 (Figure 31). Sending a DELETE with no 'tmid' indicates that all 1975 'tmids' must be deactivated (Figure 32). 1977 Header: DELETE (Code=0.04) 1978 Uri-Path: ".well-known" 1979 Uri-Path: "dots" 1980 Uri-Path: "tm" 1981 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1982 Uri-Path: "tmid=123" 1984 Figure 31: Delete a Pre-or-Ongoing-Mitigation Telemetry 1986 Header: DELETE (Code=0.04) 1987 Uri-Path: ".well-known" 1988 Uri-Path: "dots" 1989 Uri-Path: "tm" 1990 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1992 Figure 32: Delete All Pre-or-Ongoing-Mitigation Telemetry 1994 7.3. From DOTS Servers to DOTS Clients 1996 The pre-or-ongoing-mitigation (attack details, in particular) can 1997 also be signaled from DOTS servers to DOTS clients. For example, the 1998 DOTS server co-located with a DDoS detector collects monitoring 1999 information from the target network, identifies DDoS attack using 2000 statistical analysis or deep learning techniques, and signals the 2001 attack details to the DOTS client. 2003 The DOTS client can use the attack details to decide whether to 2004 trigger a DOTS mitigation request or not. Furthermore, the security 2005 operation personnel at the DOTS client domain can use the attack 2006 details to determine the protection strategy and select the 2007 appropriate DOTS server for mitigating the attack. 2009 In order to receive pre-or-ongoing-mitigation telemetry notifications 2010 from a DOTS server, a DOTS client MUST send a PUT (followed by a GET) 2011 with the target filter. An example of such PUT request is shown in 2012 Figure 33. In order to avoid maintaining a long list of such 2013 requests, it is RECOMMENDED that DOTS clients include all targets in 2014 the same request. DOTS servers may be instructed to restrict the 2015 number of pre-or-ongoing-mitigation requests per DOTS client domain. 2016 This request MUST be maintained active by the DOTS server until a 2017 delete request is received from the same DOTS client to clear this 2018 pre-or-ongoing-mitigation telemetry. 2020 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 2021 mitigation telemetry from a DOTS client is determined by comparing 2022 their respective 'tmid' values. If such two requests have 2023 overlapping 'target', the PUT request with higher numeric 'tmid' 2024 value will override the request with a lower numeric 'tmid' value. 2025 The overlapped lower numeric 'tmid' MUST be automatically deleted and 2026 no longer be available. 2028 Header: PUT (Code=0.03) 2029 Uri-Path: ".well-known" 2030 Uri-Path: "dots" 2031 Uri-Path: "tm" 2032 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2033 Uri-Path: "tmid=123" 2034 Content-Format: "application/dots+cbor" 2036 { 2037 "ietf-dots-telemetry:telemetry": { 2038 "pre-or-ongoing-mitigation": { 2039 "target": { 2040 { 2041 "target-prefix": [ 2042 "2001:db8::/32" 2043 ] 2044 } 2045 } 2046 } 2047 } 2048 } 2050 Figure 33: PUT to Request Pre-or-Ongoing-Mitigation Telemetry 2052 DOTS clients of the same domain can request to receive pre-or- 2053 ongoing-mitigation telemetry bound to the same target. 2055 The DOTS client conveys the Observe Option set to '0' in the GET 2056 request to receive asynchronous notifications carrying pre-or- 2057 ongoing-mitigation telemetry data from the DOTS server. The GET 2058 request specifies a 'tmid' (Figure 34) or not (Figure 35). 2060 Header: GET (Code=0.01) 2061 Uri-Path: ".well-known" 2062 Uri-Path: "dots" 2063 Uri-Path: "tm" 2064 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2065 Uri-Path: "tmid=123" 2066 Observe: 0 2068 Figure 34: GET to Subscribe to Telemetry Asynchronous Notifications 2069 for a Specific 'tmid' 2071 Header: GET (Code=0.01) 2072 Uri-Path: ".well-known" 2073 Uri-Path: "dots" 2074 Uri-Path: "tm" 2075 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2076 Observe: 0 2078 Figure 35: GET to Subscribe to Telemetry Asynchronous Notifications 2079 for All 'tmids' 2081 The DOTS client can filter out the asynchronous notifications from 2082 the DOTS server by indicating one or more Uri-Query options in its 2083 GET request. A Uri-Query option can include the following 2084 parameters: target-prefix, lower-port, upper-port, target-protocol, 2085 target-fqdn, target-uri, alias-name. An example of request to 2086 subscribe to asynchronous UDP telemetry notifications is shown in 2087 Figure 36. This filter will be applied for all 'tmids'. 2089 Header: GET (Code=0.01) 2090 Uri-Path: ".well-known" 2091 Uri-Path: "dots" 2092 Uri-Path: "tm" 2093 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2094 Uri-Query: "target-protocol=17" 2095 Observe: 0 2097 Figure 36: GET Request to Receive Telemetry Asynchronous 2098 Notifications Filtered using Uri-Query 2100 The DOTS server will send asynchronous notifications to the DOTS 2101 client when an attack event is detected following similar 2102 considerations as in Section 4.4.2.1 of 2103 [I-D.ietf-dots-signal-channel]. An example of a pre-or-ongoing- 2104 mitigation telemetry notification is shown in Figure 37. 2106 { 2107 "ietf-dots-telemetry:telemetry": { 2108 "pre-or-ongoing-mitigation": { 2109 "target": { 2110 { 2111 "tmid": 123, 2112 "target-prefix": [ 2113 "2001:db8::1/128" 2114 ], 2115 "target-protocol": [17], 2116 "total-attack-traffic": [ 2117 { 2118 "unit": "megabit-ps", 2119 "mid-percentile-g": "900" 2120 } 2121 ], 2122 "attack-detail": [ 2123 { 2124 "attack-id": "an-id", 2125 "start-time": "1957818434", 2126 "attack-severity": "emergency" 2127 } 2128 ] 2129 } 2130 } 2131 } 2132 } 2133 } 2135 Figure 37: Message Body of a Pre-or-Ongoing-Mitigation Telemetry 2136 Notification from the DOTS Server 2138 A DOTS server sends the aggregate data for a target using 'total- 2139 attack-traffic' attribute. It may includes more granular data when 2140 needed (that is, 'total-attack-traffic-protocol' and 'total-attack- 2141 traffic-port'). 2143 A DOTS server may aggregate pre-or-ongoing-mitigation data (e.g., 2144 'top-talkers') for all targets of a domain, or when justified, send 2145 specific information (e.g., 'top-talkers') per individual targets. 2147 The DOTS client may log pre-or-ongoing-mitigation telemetry data with 2148 an alert sent to an administrator or a network controller. The DOTS 2149 client may send a mitigation request if the attack cannot be handled 2150 locally. 2152 A DOTS client that is not interested to receive pre-or-ongoing- 2153 mitigation telemetry data for a target MUST send a delete request 2154 similar to the one depicted in Figure 31. 2156 8. DOTS Telemetry Mitigation Status Update 2158 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 2159 Attributes 2161 The mitigation efficacy telemetry attributes can be signaled from 2162 DOTS clients to DOTS servers as part of the periodic mitigation 2163 efficacy updates to the server (Section 5.3.4 of 2164 [I-D.ietf-dots-signal-channel]). 2166 Total Attack Traffic: The overall attack traffic as observed from 2167 the DOTS client perspective during an active mitigation. See 2168 Figure 27. 2170 Attack Details: The overall attack details as observed from the 2171 DOTS client perspective during an active mitigation. See 2172 Section 7.1.5. 2174 The "ietf-dots-telemetry" YANG module augments the "mitigation-scope" 2175 type message defined in "ietf-dots-signal" so that these attributes 2176 can be signalled by a DOTS client in a mitigation efficacy update 2177 (Figure 38). 2179 augment /ietf-signal:dots-signal/ietf-signal:message-type 2180 /ietf-signal:mitigation-scope/ietf-signal:scope: 2181 +--rw total-attack-traffic* [unit] {dots-telemetry}? 2182 | ... 2183 +--rw attack-detail* [attack-id] {dots-telemetry}? 2184 +--rw id? uint32 2185 +--rw attack-id string 2186 +--rw attack-name? string 2187 +--rw attack-severity? attack-severity 2188 +--rw start-time? uint64 2189 +--rw end-time? uint64 2190 +--rw source-count 2191 | ... 2192 +--rw top-talker 2193 ... 2195 Figure 38: Telemetry Efficacy Update Tree Structure 2197 In order to signal telemetry data in a mitigation efficacy update, it 2198 is RECOMMENDED that the DOTS client has already established a DOTS 2199 telemetry setup session with the server in 'idle' time. 2201 Header: PUT (Code=0.03) 2202 Uri-Path: ".well-known" 2203 Uri-Path: "dots" 2204 Uri-Path: "mitigate" 2205 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2206 Uri-Path: "mid=123" 2207 If-Match: 2208 Content-Format: "application/dots+cbor" 2210 { 2211 "ietf-dots-signal-channel:mitigation-scope": { 2212 "scope": [ 2213 { 2214 "alias-name": [ 2215 "https1", 2216 "https2" 2217 ], 2218 "attack-status": "under-attack", 2219 "ietf-dots-telemetry:total-attack-traffic": [ 2220 { 2221 "ietf-dots-telemetry:unit": "megabit-ps", 2222 "ietf-dots-telemetry:mid-percentile-g": "900" 2223 } 2224 ] 2225 } 2226 ] 2227 } 2228 } 2230 Figure 39: An Example of Mitigation Efficacy Update with Telemetry 2231 Attributes 2233 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 2234 Attributes 2236 The mitigation status telemetry attributes can be signaled from the 2237 DOTS server to the DOTS client as part of the periodic mitigation 2238 status update (Section 5.3.3 of [I-D.ietf-dots-signal-channel]). In 2239 particular, DOTS clients can receive asynchronous notifications of 2240 the attack details from DOTS servers using the Observe option defined 2241 in [RFC7641]. 2243 In order to make use of this feature, DOTS clients MUST establish a 2244 telemetry setup session with the DOTS server in 'idle' time and MUST 2245 set the 'server-originated-telemetry' attribute to 'true'. 2247 DOTS servers MUST NOT include telemetry attributes in mitigation 2248 status updates sent to DOTS clients for which 'server-originated- 2249 telemetry' attribute is set to 'false'. 2251 As defined in [RFC8612], the actual mitigation activities can include 2252 several countermeasure mechanisms. The DOTS server signals the 2253 current operational status to each relevant countermeasure. A list 2254 of attacks detected by each countermeasure MAY also be included. The 2255 same attributes defined for Section 7.1.5 are applicable for 2256 describing the attacks detected and mitigated. 2258 The "ietf-dots-telemetry" YANG module (Section 9) augments the 2259 "mitigation-scope" type message defined in "ietf-dots-signal" with 2260 telemetry data as depicted in following tree structure: 2262 augment /ietf-signal:dots-signal/ietf-signal:message-type 2263 /ietf-signal:mitigation-scope/ietf-signal:scope: 2264 +--ro total-traffic* [unit] {dots-telemetry}? 2265 | +--ro unit unit 2266 | +--ro low-percentile-g? yang:gauge64 2267 | +--ro mid-percentile-g? yang:gauge64 2268 | +--ro high-percentile-g? yang:gauge64 2269 | +--ro peak-g? yang:gauge64 2270 +--rw total-attack-traffic* [unit] {dots-telemetry}? 2271 | +--rw unit unit 2272 | +--rw low-percentile-g? yang:gauge64 2273 | +--rw mid-percentile-g? yang:gauge64 2274 | +--rw high-percentile-g? yang:gauge64 2275 | +--rw peak-g? yang:gauge64 2276 +--ro total-attack-connection {dots-telemetry}? 2277 | +--ro low-percentile-c 2278 | | +--ro connection? yang:gauge64 2279 | | +--ro embryonic? yang:gauge64 2280 | | +--ro connection-ps? yang:gauge64 2281 | | +--ro request-ps? yang:gauge64 2282 | | +--ro partial-request-ps? yang:gauge64 2283 | +--ro mid-percentile-c 2284 | | ... 2285 | +--ro high-percentile-c 2286 | | ... 2287 | +--ro peak-c 2288 | ... 2289 +--rw attack-detail* [attack-id] {dots-telemetry}? 2290 +--rw id? uint32 2291 +--rw attack-id string 2292 +--rw attack-name? string 2293 +--rw attack-severity? attack-severity 2294 +--rw start-time? uint64 2295 +--rw end-time? uint64 2296 +--rw source-count 2297 | +--rw low-percentile-g? yang:gauge64 2298 | +--rw mid-percentile-g? yang:gauge64 2299 | +--rw high-percentile-g? yang:gauge64 2300 | +--rw peak-g? yang:gauge64 2301 +--rw top-talker 2302 +--rw talker* [source-prefix] 2303 +--rw spoofed-status? boolean 2304 +--rw source-prefix inet:ip-prefix 2305 +--rw source-port-range* [lower-port] 2306 | +--rw lower-port inet:port-number 2307 | +--rw upper-port? inet:port-number 2308 +--rw source-icmp-type-range* [lower-type] 2309 | +--rw lower-type uint8 2310 | +--rw upper-type? uint8 2311 +--rw total-attack-traffic* [unit] 2312 | +--rw unit unit 2313 | +--rw low-percentile-g? yang:gauge64 2314 | +--rw mid-percentile-g? yang:gauge64 2315 | +--rw high-percentile-g? yang:gauge64 2316 | +--rw peak-g? yang:gauge64 2317 +--rw total-attack-connection 2318 +--rw low-percentile-c 2319 | +--rw connection? yang:gauge64 2320 | +--rw embryonic? yang:gauge64 2321 | +--rw connection-ps? yang:gauge64 2322 | +--rw request-ps? yang:gauge64 2323 | +--rw partial-request-ps? yang:gauge64 2324 +--rw mid-percentile-c 2325 | ... 2326 +--rw high-percentile-c 2327 | ... 2328 +--rw peak-c 2329 ... 2331 Figure 40 shows an example of an asynchronous notification of attack 2332 mitigation status from the DOTS server. This notification signals 2333 both the mid-percentile value of processed attack traffic and the 2334 peak percentile value of unique sources involved in the attack. 2336 { 2337 "ietf-dots-signal-channel:mitigation-scope": { 2338 "scope": [ 2339 { 2340 "mid": 12332, 2341 "mitigation-start": "1507818434", 2342 "alias-name": ["https1", "https2"], 2343 "lifetime": 1600, 2344 "status": "attack-successfully-mitigated", 2345 "bytes-dropped": "134334555", 2346 "bps-dropped": "43344", 2347 "pkts-dropped": "333334444", 2348 "pps-dropped": "432432", 2349 "ietf-dots-telemetry:total-attack-traffic": [ 2350 { 2351 "ietf-dots-telemetry:unit": "megabit-ps", 2352 "ietf-dots-telemetry:mid-percentile-g": "900" 2353 } 2354 ], 2355 "ietf-dots-telemetry::attack-detail": [ 2356 { 2357 "ietf-dots-telemetry:attack-id": "another-id", 2358 "ietf-dots-telemetry:source-count": { 2359 "ietf-dots-telemetry:peak-g": "10000" 2360 } 2361 } 2362 ] 2363 } 2364 ] 2365 } 2366 } 2368 Figure 40: Response Body of a Mitigation Status With Telemetry 2369 Attributes 2371 DOTS clients can filter out the asynchronous notifications from the 2372 DOTS server by indicating one or more Uri-Query options in its GET 2373 request. A Uri-Query option can include the following parameters: 2374 target-prefix, lower-port, upper-port, target-protocol, target-fqdn, 2375 target-uri, alias-name. An example of request to subscribe to 2376 asynchronous notifications bound to the "http1" alias is shown in 2377 Figure 41. 2379 Header: GET (Code=0.01) 2380 Uri-Path: ".well-known" 2381 Uri-Path: "dots" 2382 Uri-Path: "mitigate" 2383 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 2384 Uri-Path: "mid=12332" 2385 Uri-Query: "target-alias=https1" 2386 Observe: 0 2388 Figure 41: GET Request to Receive Asynchronous Notifications Filtered 2389 using Uri-Query 2391 If the target query does not match the target of the enclosed 'mid' 2392 as maintained by the DOTS server, the latter MUST respond with a 4.04 2393 (Not Found) error response code. The DOTS server MUST NOT add a new 2394 observe entry if this query overlaps with an existing one. 2396 9. YANG Module 2398 This module uses types defined in [RFC6991] and [RFC8345]. 2400 file "ietf-dots-telemetry@2020-04-03.yang" 2401 module ietf-dots-telemetry { 2402 yang-version 1.1; 2403 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 2404 prefix dots-telemetry; 2406 import ietf-dots-signal-channel { 2407 prefix ietf-signal; 2408 reference 2409 "RFC SSSS: Distributed Denial-of-Service Open Threat 2410 Signaling (DOTS) Signal Channel Specification"; 2411 } 2412 import ietf-dots-data-channel { 2413 prefix ietf-data; 2414 reference 2415 "RFC DDDD: Distributed Denial-of-Service Open Threat 2416 Signaling (DOTS) Data Channel Specification"; 2417 } 2418 import ietf-yang-types { 2419 prefix yang; 2420 reference 2421 "Section 3 of RFC 6991"; 2422 } 2423 import ietf-inet-types { 2424 prefix inet; 2425 reference 2426 "Section 4 of RFC 6991"; 2428 } 2429 import ietf-network-topology { 2430 prefix nt; 2431 reference 2432 "Section 6.2 of RFC 8345: A YANG Data Model for Network 2433 Topologies"; 2434 } 2436 organization 2437 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2438 contact 2439 "WG Web: 2440 WG List: 2442 Author: Mohamed Boucadair 2443 2445 Author: Konda, Tirumaleswar Reddy 2446 "; 2447 description 2448 "This module contains YANG definitions for the signaling 2449 of DOTS telemetry exchanged between a DOTS client and 2450 a DOTS server, by means of the DOTS signal channel. 2452 Copyright (c) 2020 IETF Trust and the persons identified as 2453 authors of the code. All rights reserved. 2455 Redistribution and use in source and binary forms, with or 2456 without modification, is permitted pursuant to, and subject 2457 to the license terms contained in, the Simplified BSD License 2458 set forth in Section 4.c of the IETF Trust's Legal Provisions 2459 Relating to IETF Documents 2460 (http://trustee.ietf.org/license-info). 2462 This version of this YANG module is part of RFC XXXX; see 2463 the RFC itself for full legal notices."; 2465 revision 2020-04-03 { 2466 description 2467 "Initial revision."; 2468 reference 2469 "RFC XXXX: Distributed Denial-of-Service Open Threat 2470 Signaling (DOTS) Telemetry"; 2471 } 2473 feature dots-telemetry { 2474 description 2475 "This feature means that the DOTS signal channel is able 2476 to convey DOTS telemetry data between DOTS clients and 2477 servers."; 2478 } 2480 typedef attack-severity { 2481 type enumeration { 2482 enum emergency { 2483 value 1; 2484 description 2485 "The attack is severe: emergency."; 2486 } 2487 enum critical { 2488 value 2; 2489 description 2490 "The attack is critical."; 2491 } 2492 enum alert { 2493 value 3; 2494 description 2495 "This is an alert."; 2496 } 2497 } 2498 description 2499 "Enumeration for attack severity."; 2500 } 2502 typedef unit-type { 2503 type enumeration { 2504 enum packet-ps { 2505 value 1; 2506 description 2507 "Packets per second (pps)."; 2508 } 2509 enum bit-ps { 2510 value 2; 2511 description 2512 "Bits per Second (bit/s)."; 2513 } 2514 enum byte-ps { 2515 value 3; 2516 description 2517 "Bytes per second (Byte/s)."; 2518 } 2519 } 2520 description 2521 "Enumeration to indicate which unit type is used."; 2522 } 2523 typedef unit { 2524 type enumeration { 2525 enum packet-ps { 2526 value 1; 2527 description 2528 "Packets per second (pps)."; 2529 } 2530 enum bit-ps { 2531 value 2; 2532 description 2533 "Bits per Second (bps)."; 2534 } 2535 enum byte-ps { 2536 value 3; 2537 description 2538 "Bytes per second (Bps)."; 2539 } 2540 enum kilopacket-ps { 2541 value 4; 2542 description 2543 "Kilo packets per second (kpps)."; 2544 } 2545 enum kilobit-ps { 2546 value 5; 2547 description 2548 "Kilobits per second (kbps)."; 2549 } 2550 enum kilobyte-ps { 2551 value 6; 2552 description 2553 "Kilobytes per second (kBps)."; 2554 } 2555 enum megapacket-ps { 2556 value 7; 2557 description 2558 "Mega packets per second (Mpps)."; 2559 } 2560 enum megabit-ps { 2561 value 8; 2562 description 2563 "Megabits per second (Mbps)."; 2564 } 2565 enum megabyte-ps { 2566 value 9; 2567 description 2568 "Megabytes per second (MBps)."; 2569 } 2570 enum gigapacket-ps { 2571 value 10; 2572 description 2573 "Giga packets per second (Gpps)."; 2574 } 2575 enum gigabit-ps { 2576 value 11; 2577 description 2578 "Gigabits per second (Gbps)."; 2579 } 2580 enum gigabyte-ps { 2581 value 12; 2582 description 2583 "Gigabytes per second (GBps)."; 2584 } 2585 enum terapacket-ps { 2586 value 13; 2587 description 2588 "Tera packets per second (Tpps)."; 2589 } 2590 enum terabit-ps { 2591 value 14; 2592 description 2593 "Terabits per second (Tbps)."; 2594 } 2595 enum terabyte-ps { 2596 value 15; 2597 description 2598 "Terabytes per second (TBps)."; 2599 } 2600 } 2601 description 2602 "Enumeration to indicate which unit is used."; 2603 } 2605 typedef interval { 2606 type enumeration { 2607 enum hour { 2608 value 1; 2609 description 2610 "Hour."; 2611 } 2612 enum day { 2613 value 2; 2614 description 2615 "Day."; 2616 } 2617 enum week { 2618 value 3; 2619 description 2620 "Week."; 2621 } 2622 enum month { 2623 value 4; 2624 description 2625 "Month."; 2626 } 2627 } 2628 description 2629 "Enumeration to indicate the overall measurement period."; 2630 } 2632 typedef sample { 2633 type enumeration { 2634 enum second { 2635 value 1; 2636 description 2637 "Second."; 2638 } 2639 enum 5-seconds { 2640 value 2; 2641 description 2642 "5 seconds."; 2643 } 2644 enum 30-seconds { 2645 value 3; 2646 description 2647 "30 seconds."; 2648 } 2649 enum minute { 2650 value 4; 2651 description 2652 "One minute."; 2653 } 2654 enum 5-minutes { 2655 value 5; 2656 description 2657 "5 minutes."; 2658 } 2659 enum 10-minutes { 2660 value 6; 2661 description 2662 "10 minutes."; 2663 } 2664 enum 30-minutes { 2665 value 7; 2666 description 2667 "30 minutes."; 2668 } 2669 enum hour { 2670 value 8; 2671 description 2672 "One hour."; 2673 } 2674 } 2675 description 2676 "Enumeration to indicate the measurement perdiod."; 2677 } 2679 typedef percentile { 2680 type decimal64 { 2681 fraction-digits 2; 2682 } 2683 description 2684 "The nth percentile of a set of data is the 2685 value at which n percent of the data is below it."; 2686 } 2688 grouping percentile-config { 2689 description 2690 "Configuration of low, mid, and high percentile values."; 2691 leaf measurement-interval { 2692 type interval; 2693 description 2694 "Defines the period on which percentiles are computed."; 2695 } 2696 leaf measurement-sample { 2697 type sample; 2698 description 2699 "Defines the time distribution for measuring 2700 values that are used to compute percentiles."; 2701 } 2702 leaf low-percentile { 2703 type percentile; 2704 default "10.00"; 2705 description 2706 "Low percentile. If set to '0', this means low-percentiles 2707 are disabled."; 2708 } 2709 leaf mid-percentile { 2710 type percentile; 2711 must '. >= ../low-percentile' { 2712 error-message 2713 "The mid-percentile must be greater than 2714 or equal to the low-percentile."; 2716 } 2717 default "50.00"; 2718 description 2719 "Mid percentile. If set to the same value as low-percentiles, 2720 this means mid-percentiles are disabled."; 2721 } 2722 leaf high-percentile { 2723 type percentile; 2724 must '. >= ../mid-percentile' { 2725 error-message 2726 "The high-percentile must be greater than 2727 or equal to the mid-percentile."; 2728 } 2729 default "90.00"; 2730 description 2731 "High percentile. If set to the same value as mid-percentiles, 2732 this means high-percentiles are disabled."; 2733 } 2734 } 2736 grouping percentile { 2737 description 2738 "Generic grouping for percentile."; 2739 leaf low-percentile-g { 2740 type yang:gauge64; 2741 description 2742 "Low traffic."; 2743 } 2744 leaf mid-percentile-g { 2745 type yang:gauge64; 2746 description 2747 "Mid percentile."; 2748 } 2749 leaf high-percentile-g { 2750 type yang:gauge64; 2751 description 2752 "High percentile."; 2753 } 2754 leaf peak-g { 2755 type yang:gauge64; 2756 description 2757 "Peak"; 2758 } 2759 } 2761 grouping unit-config { 2762 description 2763 "Generic grouping for unit configuration."; 2765 list unit-config { 2766 key "unit"; 2767 description 2768 "Controls which units are allowed when sharing telemetry 2769 data."; 2770 leaf unit { 2771 type unit-type; 2772 description 2773 "Can be packet-ps, bit-ps, or byte-ps."; 2774 } 2775 leaf unit-status { 2776 type boolean; 2777 description 2778 "Enable/disable the use of the measurement unit."; 2779 } 2780 } 2781 } 2783 grouping traffic-unit { 2784 description 2785 "Grouping of traffic as a function of measurement unit."; 2786 leaf unit { 2787 type unit; 2788 description 2789 "The traffic can be measured using unit types: packets 2790 per second (PPS), Bits per Second (BPS), and/or 2791 bytes per second. DOTS agents auto-scale to the appropriate 2792 units (e.g., megabit-ps, kilobit-ps)."; 2793 } 2794 uses percentile; 2795 } 2797 grouping traffic-unit-protocol { 2798 description 2799 "Grouping of traffic of a given transport protocol as 2800 a function of measurement unit."; 2801 leaf protocol { 2802 type uint8; 2803 description 2804 "The transport protocol. 2805 Values are taken from the IANA Protocol Numbers registry: 2806 . 2808 For example, this field contains 6 for TCP, 2809 17 for UDP, 33 for DCCP, or 132 for SCTP."; 2810 } 2811 uses traffic-unit; 2812 } 2813 grouping traffic-unit-port { 2814 description 2815 "Grouping of traffic bound to port number as 2816 a function of measurement unit."; 2817 leaf port { 2818 type inet:port-number; 2819 description 2820 "Port number."; 2821 } 2822 uses traffic-unit; 2823 } 2825 grouping total-connection-capacity { 2826 description 2827 "Total Connections Capacity. If the target is subjected 2828 to resource consuming DDoS attack, these attributes are 2829 useful to detect resource consuming DDoS attacks"; 2830 leaf connection { 2831 type uint64; 2832 description 2833 "The maximum number of simultaneous connections that 2834 are allowed to the target server. The threshold is 2835 transport-protocol specific because the target server 2836 could support multiple protocols."; 2837 } 2838 leaf connection-client { 2839 type uint64; 2840 description 2841 "The maximum number of simultaneous connections that 2842 are allowed to the target server per client."; 2843 } 2844 leaf embryonic { 2845 type uint64; 2846 description 2847 "The maximum number of simultaneous embryonic connections 2848 that are allowed to the target server. The term 'embryonic 2849 connection' refers to a connection whose connection handshake 2850 is not finished and embryonic connection is only possible in 2851 connection-oriented transport protocols like TCP or SCTP."; 2852 } 2853 leaf embryonic-client { 2854 type uint64; 2855 description 2856 "The maximum number of simultaneous embryonic connections 2857 that are allowed to the target server per client."; 2858 } 2859 leaf connection-ps { 2860 type uint64; 2861 description 2862 "The maximum number of connections allowed per second 2863 to the target server."; 2864 } 2865 leaf connection-client-ps { 2866 type uint64; 2867 description 2868 "The maximum number of connections allowed per second 2869 to the target server per client."; 2870 } 2871 leaf request-ps { 2872 type uint64; 2873 description 2874 "The maximum number of requests allowed per second 2875 to the target server."; 2876 } 2877 leaf request-client-ps { 2878 type uint64; 2879 description 2880 "The maximum number of requests allowed per second 2881 to the target server per client."; 2882 } 2883 leaf partial-request-ps { 2884 type uint64; 2885 description 2886 "The maximum number of partial requests allowed per 2887 second to the target server."; 2888 } 2889 leaf partial-request-client-ps { 2890 type uint64; 2891 description 2892 "The maximum number of partial requests allowed per 2893 second to the target server per client."; 2894 } 2895 } 2897 grouping total-connection-capacity-protocol { 2898 description 2899 "Total Connections Capacity per protocol. If the target is subjected 2900 to resource consuming DDoS attack, these attributes are 2901 useful to detect resource consuming DDoS attacks"; 2902 leaf protocol { 2903 type uint8; 2904 description 2905 "The transport protocol. 2906 Values are taken from the IANA Protocol Numbers registry: 2907 ."; 2908 } 2909 uses total-connection-capacity; 2910 } 2912 grouping connection { 2913 description 2914 "A set of attributes which represent the attack 2915 characteristics"; 2916 leaf connection { 2917 type yang:gauge64; 2918 description 2919 "The number of simultaneous attack connections to 2920 the target server."; 2921 } 2922 leaf embryonic { 2923 type yang:gauge64; 2924 description 2925 "The number of simultaneous embryonic connections to 2926 the target server."; 2927 } 2928 leaf connection-ps { 2929 type yang:gauge64; 2930 description 2931 "The number of attack connections per second to 2932 the target server."; 2933 } 2934 leaf request-ps { 2935 type yang:gauge64; 2936 description 2937 "The number of attack requests per second to 2938 the target server."; 2939 } 2940 leaf partial-request-ps { 2941 type yang:gauge64; 2942 description 2943 "The number of attack partial requests to 2944 the target server."; 2945 } 2946 } 2948 grouping connection-percentile { 2949 description 2950 "Total attack connections."; 2951 container low-percentile-c { 2952 description 2953 "Low percentile of attack connections."; 2954 uses connection; 2955 } 2956 container mid-percentile-c { 2957 description 2958 "Mid percentile of attack connections."; 2959 uses connection; 2960 } 2961 container high-percentile-c { 2962 description 2963 "High percentile of attack connections."; 2964 uses connection; 2965 } 2966 container peak-c { 2967 description 2968 "Peak attack connections."; 2969 uses connection; 2970 } 2971 } 2973 grouping connection-protocol { 2974 description 2975 "Total attack connections."; 2976 leaf protocol { 2977 type uint8; 2978 description 2979 "The transport protocol. 2980 Values are taken from the IANA Protocol Numbers registry: 2981 ."; 2982 } 2983 uses connection; 2984 } 2986 grouping connection-port { 2987 description 2988 "Total attack connections per port number."; 2989 leaf port { 2990 type inet:port-number; 2991 description 2992 "Port number."; 2993 } 2994 uses connection-protocol; 2995 } 2997 grouping connection-protocol-percentile { 2998 description 2999 "Total attack connections."; 3000 list low-percentile-l { 3001 key "protocol"; 3002 description 3003 "Low percentile of attack connections."; 3004 uses connection-protocol; 3006 } 3007 list mid-percentile-l { 3008 key "protocol"; 3009 description 3010 "Mid percentile of attack connections."; 3011 uses connection-protocol; 3012 } 3013 list high-percentile-l { 3014 key "protocol"; 3015 description 3016 "High percentile of attack connections."; 3017 uses connection-protocol; 3018 } 3019 list peak-l { 3020 key "protocol"; 3021 description 3022 "Peak attack connections."; 3023 uses connection-protocol; 3024 } 3025 } 3027 grouping connection-protocol-port-percentile { 3028 description 3029 "Total attack connections."; 3030 list low-percentile-l { 3031 key "protocol port"; 3032 description 3033 "Low percentile of attack connections."; 3034 uses connection-port; 3035 } 3036 list mid-percentile-l { 3037 key "protocol port"; 3038 description 3039 "Mid percentile of attack connections."; 3040 uses connection-port; 3041 } 3042 list high-percentile-l { 3043 key "protocol port"; 3044 description 3045 "High percentile of attack connections."; 3046 uses connection-port; 3047 } 3048 list peak-l { 3049 key "protocol port"; 3050 description 3051 "Peak attack connections."; 3052 uses connection-port; 3053 } 3055 } 3057 grouping attack-detail { 3058 description 3059 "Various information and details that describe the on-going 3060 attacks that needs to be mitigated by the DOTS server. 3061 The attack details need to cover well-known and common attacks 3062 (such as a SYN Flood) along with new emerging or vendor-specific 3063 attacks."; 3064 leaf id { 3065 type uint32; 3066 description 3067 "Vendor ID is a security vendor's Enterprise Number."; 3068 } 3069 leaf attack-id { 3070 type string; 3071 description 3072 "Unique identifier assigned by the vendor for the attack."; 3073 } 3074 leaf attack-name { 3075 type string; 3076 description 3077 "Textual representation of attack description. Natural Language 3078 Processing techniques (e.g., word embedding) can possibly be used 3079 to map the attack description to an attack type."; 3080 } 3081 leaf attack-severity { 3082 type attack-severity; 3083 description 3084 "Severity level of an attack"; 3085 } 3086 leaf start-time { 3087 type uint64; 3088 description 3089 "The time the attack started. Start time is represented in seconds 3090 relative to 1970-01-01T00:00:00Z in UTC time."; 3091 } 3092 leaf end-time { 3093 type uint64; 3094 description 3095 "The time the attack ended. End time is represented in seconds 3096 relative to 1970-01-01T00:00:00Z in UTC time."; 3097 } 3098 container source-count { 3099 description 3100 "Indicates the count of unique sources involved 3101 in the attack."; 3102 uses percentile; 3104 } 3105 } 3107 grouping top-talker-aggregate { 3108 description 3109 "Top attack sources."; 3110 list talker { 3111 key "source-prefix"; 3112 description 3113 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3114 leaf spoofed-status { 3115 type boolean; 3116 description 3117 "Indicates whether this address is spoofed."; 3118 } 3119 leaf source-prefix { 3120 type inet:ip-prefix; 3121 description 3122 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3123 } 3124 list source-port-range { 3125 key "lower-port"; 3126 description 3127 "Port range. When only lower-port is 3128 present, it represents a single port number."; 3129 leaf lower-port { 3130 type inet:port-number; 3131 mandatory true; 3132 description 3133 "Lower port number of the port range."; 3134 } 3135 leaf upper-port { 3136 type inet:port-number; 3137 must '. >= ../lower-port' { 3138 error-message 3139 "The upper port number must be greater than 3140 or equal to lower port number."; 3141 } 3142 description 3143 "Upper port number of the port range."; 3144 } 3145 } 3146 list source-icmp-type-range { 3147 key "lower-type"; 3148 description 3149 "ICMP type range. When only lower-type is 3150 present, it represents a single ICMP type."; 3151 leaf lower-type { 3152 type uint8; 3153 mandatory true; 3154 description 3155 "Lower ICMP type of the ICMP type range."; 3156 } 3157 leaf upper-type { 3158 type uint8; 3159 must '. >= ../lower-type' { 3160 error-message 3161 "The upper ICMP type must be greater than 3162 or equal to lower ICMP type."; 3163 } 3164 description 3165 "Upper type of the ICMP type range."; 3166 } 3167 } 3168 list total-attack-traffic { 3169 key "unit"; 3170 description 3171 "Total attack traffic issued from this source."; 3172 uses traffic-unit; 3173 } 3174 container total-attack-connection { 3175 description 3176 "Total attack connections issued from this source."; 3177 uses connection-percentile; 3178 } 3179 } 3180 } 3182 grouping top-talker { 3183 description 3184 "Top attack sources."; 3185 list talker { 3186 key "source-prefix"; 3187 description 3188 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3189 leaf spoofed-status { 3190 type boolean; 3191 description 3192 "Indicates whether this address is spoofed."; 3193 } 3194 leaf source-prefix { 3195 type inet:ip-prefix; 3196 description 3197 "IPv4 or IPv6 prefix identifying the attacker(s)."; 3198 } 3199 list source-port-range { 3200 key "lower-port"; 3201 description 3202 "Port range. When only lower-port is 3203 present, it represents a single port number."; 3204 leaf lower-port { 3205 type inet:port-number; 3206 mandatory true; 3207 description 3208 "Lower port number of the port range."; 3209 } 3210 leaf upper-port { 3211 type inet:port-number; 3212 must '. >= ../lower-port' { 3213 error-message 3214 "The upper port number must be greater than 3215 or equal to lower port number."; 3216 } 3217 description 3218 "Upper port number of the port range."; 3219 } 3220 } 3221 list source-icmp-type-range { 3222 key "lower-type"; 3223 description 3224 "ICMP type range. When only lower-type is 3225 present, it represents a single ICMP type."; 3226 leaf lower-type { 3227 type uint8; 3228 mandatory true; 3229 description 3230 "Lower ICMP type of the ICMP type range."; 3231 } 3232 leaf upper-type { 3233 type uint8; 3234 must '. >= ../lower-type' { 3235 error-message 3236 "The upper ICMP type must be greater than 3237 or equal to lower ICMP type."; 3238 } 3239 description 3240 "Upper type of the ICMP type range."; 3241 } 3242 } 3243 list total-attack-traffic { 3244 key "unit"; 3245 description 3246 "Total attack traffic issued from this source."; 3247 uses traffic-unit; 3249 } 3250 container total-attack-connection { 3251 description 3252 "Total attack connections issued from this source."; 3253 uses connection-protocol-percentile; 3254 } 3255 } 3256 } 3258 grouping baseline { 3259 description 3260 "Grouping for the telemetry baseline."; 3261 uses ietf-data:target; 3262 leaf-list alias-name { 3263 type string; 3264 description 3265 "An alias name that points to a resource."; 3266 } 3267 list total-traffic-normal { 3268 key "unit"; 3269 description 3270 "Total traffic normal baselines."; 3271 uses traffic-unit; 3272 } 3273 list total-traffic-normal-per-protocol { 3274 key "unit protocol"; 3275 description 3276 "Total traffic normal baselines per protocol."; 3277 uses traffic-unit-protocol; 3278 } 3279 list total-traffic-normal-per-port { 3280 key "unit port"; 3281 description 3282 "Total traffic normal baselines per port number."; 3283 uses traffic-unit-port; 3284 } 3285 list total-connection-capacity { 3286 key "protocol"; 3287 description 3288 "Total connection capacity."; 3289 uses total-connection-capacity-protocol; 3290 } 3291 list total-connection-capacity-per-port { 3292 key "protocol port"; 3293 description 3294 "Total connection capacity per port number."; 3295 leaf port { 3296 type inet:port-number; 3297 description 3298 "The target port number."; 3299 } 3300 uses total-connection-capacity-protocol; 3301 } 3302 } 3304 grouping pre-or-ongoing-mitigation { 3305 description 3306 "Grouping for the telemetry data."; 3307 list total-traffic { 3308 key "unit"; 3309 description 3310 "Total traffic."; 3311 uses traffic-unit; 3312 } 3313 list total-traffic-protocol { 3314 key "unit protocol"; 3315 description 3316 "Total traffic."; 3317 uses traffic-unit-protocol; 3318 } 3319 list total-traffic-port { 3320 key "unit port"; 3321 description 3322 "Total traffic per port."; 3323 uses traffic-unit-port; 3324 } 3325 list total-attack-traffic { 3326 key "unit"; 3327 description 3328 "Total attack traffic."; 3329 uses traffic-unit-protocol; 3330 } 3331 list total-attack-traffic-protocol { 3332 key "unit protocol"; 3333 description 3334 "Total attack traffic per protocol."; 3335 uses traffic-unit-protocol; 3336 } 3337 list total-attack-traffic-port { 3338 key "unit port"; 3339 description 3340 "Total attack traffic per port."; 3341 uses traffic-unit-port; 3342 } 3343 container total-attack-connection { 3344 description 3345 "Total attack connections."; 3346 uses connection-protocol-percentile; 3347 } 3348 container total-attack-connection-port { 3349 description 3350 "Total attack connections."; 3351 uses connection-protocol-port-percentile; 3352 } 3353 list attack-detail { 3354 key "attack-id"; 3355 description 3356 "Attack details."; 3357 uses attack-detail; 3358 container top-talker { 3359 description 3360 "Top attack sources."; 3361 uses top-talker; 3362 } 3363 } 3364 } 3366 augment "/ietf-signal:dots-signal/ietf-signal:message-type/" 3367 + "ietf-signal:mitigation-scope/ietf-signal:scope" { 3368 if-feature "dots-telemetry"; 3369 description 3370 "Extends mitigation scope with telemetry update data."; 3371 list total-traffic { 3372 key "unit"; 3373 config false; 3374 description 3375 "Total traffic."; 3376 uses traffic-unit; 3377 } 3378 list total-attack-traffic { 3379 key "unit"; 3380 description 3381 "Total attack traffic."; 3382 uses traffic-unit; 3383 } 3384 container total-attack-connection { 3385 config false; 3386 description 3387 "Total attack connections."; 3388 uses connection-percentile; 3389 } 3390 list attack-detail { 3391 key "attack-id"; 3392 description 3393 "Atatck details"; 3394 uses attack-detail; 3395 container top-talker { 3396 description 3397 "Top attack sources."; 3398 uses top-talker-aggregate; 3399 } 3400 } 3401 } 3403 augment "/ietf-signal:dots-signal/ietf-signal:message-type" { 3404 if-feature "dots-telemetry"; 3405 description 3406 "Add a new choice to enclose telemetry data in DOTS 3407 signal channel."; 3408 case telemetry-setup { 3409 description 3410 "Indicates the message is about telemetry."; 3411 container max-config-values { 3412 config false; 3413 description 3414 "Maximum acceptable configuration values."; 3415 uses percentile-config; 3416 leaf server-originated-telemetry { 3417 type boolean; 3418 description 3419 "Indicates whether the DOTS server can be instructed 3420 to send pre-or-ongoing-mitigation telemetry. If set to FALSE 3421 or the attribute is not present, this is an indication 3422 that the server does not support this capability."; 3423 } 3424 leaf telemetry-notify-interval { 3425 type uint32 { 3426 range "1 .. 3600"; 3427 } 3428 must '. >= ../../min-config-values/telemetry-notify-interval' { 3429 error-message 3430 "The value must be greater than or equal 3431 to the telemetry-notify-interval in the min-config-values"; 3432 } 3433 units "seconds"; 3434 description 3435 "Minimum number of seconds between successive 3436 telemetry notifications."; 3437 } 3438 } 3439 container min-config-values { 3440 config false; 3441 description 3442 "Minimum acceptable configuration values."; 3443 uses percentile-config; 3444 leaf telemetry-notify-interval { 3445 type uint32 { 3446 range "1 .. 3600"; 3447 } 3448 units "seconds"; 3449 description 3450 "Minimum number of seconds between successive 3451 telemetry notifications."; 3452 } 3453 } 3454 container supported-units { 3455 config false; 3456 description 3457 "Supported units and default activation status."; 3458 uses unit-config; 3459 } 3460 list telemetry { 3461 key "cuid tsid"; 3462 description 3463 "The telemetry data per DOTS client."; 3464 leaf cuid { 3465 type string; 3466 description 3467 "A unique identifier that is 3468 generated by a DOTS client to prevent 3469 request collisions. It is expected that the 3470 cuid will remain consistent throughout the 3471 lifetime of the DOTS client."; 3472 } 3473 leaf cdid { 3474 type string; 3475 description 3476 "The cdid should be included by a server-domain 3477 DOTS gateway to propagate the client domain 3478 identification information from the 3479 gateway's client-facing-side to the gateway's 3480 server-facing-side, and from the gateway's 3481 server-facing-side to the DOTS server. 3483 It may be used by the final DOTS server 3484 for policy enforcement purposes."; 3485 } 3486 leaf tsid { 3487 type uint32; 3488 description 3489 "An identifier for the DOTS telemetry setup 3490 data."; 3491 } 3492 choice setup-type { 3493 description 3494 "Can be a mitigation configuration, a pipe capacity, 3495 or baseline message."; 3496 case telemetry-config { 3497 description 3498 "Uses to set low, mid, and high percentile values."; 3499 container current-config { 3500 description 3501 "Current configuration values."; 3502 uses percentile-config; 3503 uses unit-config; 3504 leaf server-originated-telemetry { 3505 type boolean; 3506 description 3507 "Used by a DOTS client to enable/disable whether it 3508 accepts pre-or-ongoing-mitigation telemetry from 3509 the DOTS server."; 3510 } 3511 leaf telemetry-notify-interval { 3512 type uint32 { 3513 range "1 .. 3600"; 3514 } 3515 units "seconds"; 3516 description 3517 "Minimum number of seconds between successive 3518 telemetry notifications."; 3519 } 3520 } 3521 } 3522 case pipe { 3523 description 3524 "Total pipe capacity of a DOTS client domain"; 3525 list total-pipe-capacity { 3526 key "link-id unit"; 3527 description 3528 "Total pipe capacity of a DOTS client domain."; 3529 leaf link-id { 3530 type nt:link-id; 3531 description 3532 "Identifier of an interconnection link."; 3533 } 3534 leaf capacity { 3535 type uint64; 3536 mandatory true; 3537 description 3538 "Pipe capacity."; 3539 } 3540 leaf unit { 3541 type unit; 3542 description 3543 "The traffic can be measured using unit types: packets 3544 per second (PPS), Bits per Second (BPS), and/or 3545 bytes per second. DOTS agents auto-scale to the 3546 appropriate units (e.g., megabit-ps, kilobit-ps)."; 3547 } 3548 } 3549 } 3550 case baseline { 3551 description 3552 "Traffic baseline information"; 3553 list baseline { 3554 key "id"; 3555 description 3556 "Traffic baseline information"; 3557 leaf id { 3558 type uint32; 3559 must '. >= 1'; 3560 description 3561 "A baseline entry identifier."; 3562 } 3563 uses baseline; 3564 } 3565 } 3566 } 3567 } 3568 } 3569 case telemetry { 3570 description 3571 "Indicates the message is about telemetry."; 3572 list pre-or-ongoing-mitigation { 3573 key "cuid tmid"; 3574 description 3575 "Pre-or-ongoing-mitigation telemetry per DOTS client."; 3576 leaf cuid { 3577 type string; 3578 description 3579 "A unique identifier that is 3580 generated by a DOTS client to prevent 3581 request collisions. It is expected that the 3582 cuid will remain consistent throughout the 3583 lifetime of the DOTS client."; 3584 } 3585 leaf cdid { 3586 type string; 3587 description 3588 "The cdid should be included by a server-domain 3589 DOTS gateway to propagate the client domain 3590 identification information from the 3591 gateway's client-facing-side to the gateway's 3592 server-facing-side, and from the gateway's 3593 server-facing-side to the DOTS server. 3595 It may be used by the final DOTS server 3596 for policy enforcement purposes."; 3597 } 3598 leaf tmid { 3599 type uint32; 3600 description 3601 "An identifier to uniquely demux telemetry data sent 3602 using the same message."; 3603 } 3604 container target { 3605 description 3606 "Indicates the target."; 3607 uses ietf-data:target; 3608 leaf-list alias-name { 3609 type string; 3610 description 3611 "An alias name that points to a resource."; 3612 } 3613 leaf-list mid-list { 3614 type uint32; 3615 description 3616 "Reference a list of associated mitigation requests."; 3617 } 3618 } 3619 uses pre-or-ongoing-mitigation; 3620 } 3621 } 3622 } 3623 } 3624 3626 10. YANG/JSON Mapping Parameters to CBOR 3628 All DOTS telemetry parameters in the payload of the DOTS signal 3629 channel MUST be mapped to CBOR types as shown in the following table: 3631 o Implementers may use the values in: https://github.com/boucadair/ 3632 draft-dots-telemetry/blob/master/mapping-table.txt 3634 +----------------------+-------------+------+---------------+--------+ 3635 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 3636 | | Type | Key | Type & | Type | 3637 | | | | Information | | 3638 +----------------------+-------------+------+---------------+--------+ 3639 | tsid | uint32 |TBA1 | 0 unsigned | Number | 3640 | telemetry | container |TBA2 | 5 map | Object | 3641 | low-percentile | decimal64 |TBA3 | 6 tag 4 | | 3642 | | | | [-2, integer]| String | 3643 | mid-percentile | decimal64 |TBA4 | 6 tag 4 | | 3644 | | | | [-2, integer]| String | 3645 | high-percentile | decimal64 |TBA5 | 6 tag 4 | | 3646 | | | | [-2, integer]| String | 3647 | unit-config | list |TBA6 | 4 array | Array | 3648 | unit | enumeration |TBA7 | 0 unsigned | String | 3649 | unit-status | boolean |TBA8 | 7 bits 20 | False | 3650 | | | | 7 bits 21 | True | 3651 | total-pipe-capability| list |TBA9 | 4 array | Array | 3652 | link-id | string |TBA10 | 3 text string | String | 3653 | pre-or-ongoing- | list |TBA11 | 4 array | Array | 3654 | mitigation | | | | | 3655 | total-traffic-normal | list |TBA12 | 4 array | Array | 3656 | low-percentile-g | yang:gauge64|TBA13 | 0 unsigned | String | 3657 | mid-percentile-g | yang:gauge64|TBA14 | 0 unsigned | String | 3658 | high-percentile-g | yang:gauge64|TBA15 | 0 unsigned | String | 3659 | peak-g | yang:gauge64|TBA16 | 0 unsigned | String | 3660 | total-attack-traffic | list |TBA17 | 4 array | Array | 3661 | total-traffic | list |TBA18 | 4 array | Array | 3662 | total-connection- | | | | | 3663 | capacity | list |TBA19 | 4 array | Array | 3664 | connection | uint64 |TBA20 | 0 unsigned | String | 3665 | connection-client | uint64 |TBA21 | 0 unsigned | String | 3666 | embryonic | uint64 |TBA22 | 0 unsigned | String | 3667 | embryonic-client | uint64 |TBA23 | 0 unsigned | String | 3668 | connection-ps | uint64 |TBA24 | 0 unsigned | String | 3669 | connection-client-ps | uint64 |TBA25 | 0 unsigned | String | 3670 | request-ps | uint64 |TBA26 | 0 unsigned | String | 3671 | request-client-ps | uint64 |TBA27 | 0 unsigned | String | 3672 | partial-request-ps | uint64 |TBA28 | 0 unsigned | String | 3673 | partial-request- | | | | | 3674 | client-ps | uint64 |TBA29 | 0 unsigned | String | 3675 | total-attack- | | | | | 3676 | connection | container |TBA30 | 5 map | Object | 3677 | low-percentile-l | list |TBA31 | 4 array | Array | 3678 | mid-percentile-l | list |TBA32 | 4 array | Array | 3679 | high-percentile-l | list |TBA33 | 4 array | Array | 3680 | peak-l | list |TBA34 | 4 array | Array | 3681 | attack-detail | list |TBA35 | 4 array | Array | 3682 | id | uint32 |TBA36 | 0 unsigned | Number | 3683 | attack-id | string |TBA37 | 3 text string | String | 3684 | attack-name | string |TBA38 | 3 text string | String | 3685 | attack-severity | enumeration |TBA39 | 0 unsigned | String | 3686 | start-time | uint64 |TBA40 | 0 unsigned | String | 3687 | end-time | uint64 |TBA41 | 0 unsigned | String | 3688 | source-count | container |TBA42 | 5 map | Object | 3689 | top-talker | container |TBA43 | 5 map | Object | 3690 | spoofed-status | boolean |TBA44 | 7 bits 20 | False | 3691 | | | | 7 bits 21 | True | 3692 | low-percentile-c | container |TBA45 | 5 map | Object | 3693 | mid-percentile-c | container |TBA46 | 5 map | Object | 3694 | high-percentile-c | container |TBA47 | 5 map | Object | 3695 | peak-c | container |TBA48 | 5 map | Object | 3696 | baseline | container |TBA49 | 5 map | Object | 3697 | current-config | container |TBA50 | 5 map | Object | 3698 | max-config-values | container |TBA51 | 5 map | Object | 3699 | min-config-values | container |TBA52 | 5 map | Object | 3700 | supported-units | container |TBA53 | 5 map | Object | 3701 | server-originated- | boolean |TBA54 | 7 bits 20 | False | 3702 | telemetry | | | 7 bits 21 | True | 3703 | telemetry-notify- | uint32 |TBA55 | 0 unsigned | Number | 3704 | interval | | | | | 3705 | tmid | uint32 |TBA56 | 0 unsigned | Number | 3706 | measurement-interval | enumeration |TBA57 | 0 unsigned | String | 3707 | measurement-sample | enumeration |TBA58 | 0 unsigned | String | 3708 | talker | list |TBA59 | 4 array | Array | 3709 | source-prefix | inet: |TBA60 | 3 text string | String | 3710 | | ip-prefix | | | | 3711 | mid-list | leaf-list |TBA61 | 4 array | Array | 3712 | | uint32 | | 0 unsigned | Number | 3713 | source-port-range | list |TBA62 | 4 array | Array | 3714 | source-icmp-type- | list |TBA63 | 4 array | Array | 3715 | range | | | | | 3716 | lower-type | uint8 |TBA64 | 0 unsigned | Number | 3717 | upper-type | uint8 |TBA65 | 0 unsigned | Number | 3718 | target | container |TBA66 | 5 map | Object | 3719 | capacity | uint64 |TBA67 | 0 unsigned | String | 3720 | protocol | uint8 |TBA68 | 0 unsigned | Number | 3721 | total-traffic- | | | | | 3722 | normal-per-protocol | list |TBA69 | 4 array | Array | 3723 | total-traffic- | | | | | 3724 | normal-per-port | list |TBA70 | 4 array | Array | 3725 | total-connection- | | | | | 3726 | capacity-per-port | list |TBA71 | 4 array | Array | 3727 | total-traffic- | | | | | 3728 | -protocol | list |TBA72 | 4 array | Array | 3729 | total-traffic- port | list |TBA73 | 4 array | Array | 3730 | total-attack- | | | | | 3731 | traffic-protocol | list |TBA74 | 4 array | Array | 3732 | total-attack- | | | | | 3733 | traffic-port | list |TBA75 | 4 array | Array | 3734 | total-attack- | | | | | 3735 | connection-port | list |TBA76 | 4 array | Array | 3736 | port | inet: | | | | 3737 | | port-number|TBA77 | 0 unsigned | Number | 3738 | ietf-dots-telemetry: | | | | | 3739 | telemetry-setup | container |TBA80 | 5 map | Object | 3740 | ietf-dots-telemetry: | | | | | 3741 | total-traffic | list |TBA81 | 4 array | Array | 3742 | ietf-dots-telemetry: | | | | | 3743 | unit | enumeration |TBA82 | 0 unsigned | String | 3744 | ietf-dots-telemetry: | | | | | 3745 | low-percentile-g | yang:gauge64|TBA83 | 0 unsigned | String | 3746 | ietf-dots-telemetry: | | | | | 3747 | mid-percentile-g | yang:gauge64|TBA84 | 0 unsigned | String | 3748 | ietf-dots-telemetry: | | | | | 3749 | high-percentile-g | yang:gauge64|TBA85 | 0 unsigned | String | 3750 | ietf-dots-telemetry: | | | | | 3751 | peak-g | yang:gauge64|TBA86 | 0 unsigned | String | 3752 | ietf-dots-telemetry: | | | | | 3753 | total-attack-traffic | list |TBA87 | 4 array | Array | 3754 | ietf-dots-telemetry: | | | | | 3755 | total-attack- | | | | | 3756 | connection | container |TBA88 | 5 map | Object | 3757 | ietf-dots-telemetry: | | | | | 3758 | low-percentile-c | container |TBA89 | 5 map | Object | 3759 | ietf-dots-telemetry: | | | | | 3760 | mid-percentile-c | container |TBA90 | 5 map | Object | 3761 | ietf-dots-telemetry: | | | | | 3762 | high-percentile-c | container |TBA91 | 5 map | Object | 3763 | ietf-dots-telemetry: | | | | | 3764 | peak-c | container |TBA92 | 5 map | Object | 3765 | ietf-dots-telemetry: | | | | | 3766 | connection | uint64 |TBA93 | 0 unsigned | String | 3767 | ietf-dots-telemetry: | | | | | 3768 | embryonic | uint64 |TBA94 | 0 unsigned | String | 3769 | ietf-dots-telemetry: | | | | | 3770 | connection-ps | uint64 |TBA95 | 0 unsigned | String | 3771 | ietf-dots-telemetry: | | | | | 3772 | request-ps | uint64 |TBA96 | 0 unsigned | String | 3773 | ietf-dots-telemetry: | | | | | 3774 | partial-request-ps | uint64 |TBA97 | 0 unsigned | String | 3775 | ietf-dots-telemetry: | | | | | 3776 | attack-detail | list |TBA98 | 4 array | Array | 3777 | ietf-dots-telemetry: | | | | | 3778 | id | uint32 |TBA99 | 0 unsigned | Number | 3779 | ietf-dots-telemetry: | | | | | 3780 | attack-id | string |TBA100| 3 text string | String | 3781 | ietf-dots-telemetry: | | | | | 3782 | attack-name | string |TBA101| 3 text string | String | 3783 | ietf-dots-telemetry: | | | | | 3784 | attack-severity | enumeration |TBA102| 0 unsigned | String | 3785 | ietf-dots-telemetry: | | | | | 3786 | start-time | uint64 |TBA103| 0 unsigned | String | 3787 | ietf-dots-telemetry: | | | | | 3788 | end-time | uint64 |TBA104| 0 unsigned | String | 3789 | ietf-dots-telemetry: | | | | | 3790 | source-count | container |TBA105| 5 map | Object | 3791 | ietf-dots-telemetry: | | | | | 3792 | top-talker | container |TBA106| 5 map | Object | 3793 | ietf-dots-telemetry: | | | | | 3794 | spoofed-status | boolean |TBA107| 7 bits 20 | False | 3795 | | | | 7 bits 21 | True | 3796 | ietf-dots-telemetry: | | | | | 3797 | talker | list |TBA108| 4 array | Array | 3798 | ietf-dots-telemetry: | inet: |TBA109| 3 text string | String | 3799 | source-prefix | ip-prefix | | | | 3800 | ietf-dots-telemetry: | | | | | 3801 | source-port-range | list |TBA110| 4 array | Array | 3802 | ietf-dots-telemetry: | | | | | 3803 | lower-port | inet: | | | | 3804 | | port-number|TBA111| 0 unsigned | Number | 3805 | ietf-dots-telemetry: | | | | | 3806 | upper-port | inet: | | | | 3807 | | port-number|TBA112| 0 unsigned | Number | 3808 | ietf-dots-telemetry: | | | | | 3809 | source-icmp-type- | list |TBA113| 4 array | Array | 3810 | range | | | | | 3811 | ietf-dots-telemetry: | | | | | 3812 | lower-type | uint8 |TBA114| 0 unsigned | Number | 3813 | ietf-dots-telemetry: | | | | | 3814 | upper-type | uint8 |TBA115| 0 unsigned | Number | 3815 | ietf-dots-telemetry: | | | | | 3816 | telemetry | container |TBA116| 5 map | Object | 3817 +----------------------+-------------+------+---------------+--------+ 3819 11. IANA Considerationsr 3821 11.1. DOTS Signal Channel CBOR Key Values 3823 This specification registers the DOTS telemetry attributes in the 3824 IANA "DOTS Signal Channel CBOR Key Values" registry available at 3825 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 3826 cbor-key-values. 3828 The DOTS telemetry attributes defined in this specification are 3829 comprehension-optional parameters. 3831 o Note to the RFC Editor: (1) CBOR keys are assigned from the 3832 32768-49151 range. (2) Please assign the following suggested 3833 values. 3835 +----------------------+-------+-------+------------+---------------+ 3836 | Parameter Name | CBOR | CBOR | Change | Specification | 3837 | | Key | Major | Controller | Document(s) | 3838 | | Value | Type | | | 3839 +----------------------+-------+-------+------------+---------------+ 3840 | tsid | TBA1 | 0 | IESG | [RFCXXXX] | 3841 | telemetry | TBA2 | 5 | IESG | [RFCXXXX] | 3842 | low-percentile | TBA3 | 6tag4 | IESG | [RFCXXXX] | 3843 | mid-percentile | TBA4 | 6tag4 | IESG | [RFCXXXX] | 3844 | high-percentile | TBA5 | 6tag4 | IESG | [RFCXXXX] | 3845 | unit-config | TBA6 | 4 | IESG | [RFCXXXX] | 3846 | unit | TBA7 | 0 | IESG | [RFCXXXX] | 3847 | unit-status | TBA8 | 7 | IESG | [RFCXXXX] | 3848 | total-pipe-capability| TBA9 | 4 | IESG | [RFCXXXX] | 3849 | link-id | TBA10 | 3 | IESG | [RFCXXXX] | 3850 | pre-or-ongoing- | TBA11 | 4 | IESG | [RFCXXXX] | 3851 | mitigation | | | | | 3852 | total-traffic-normal | TBA12 | 4 | IESG | [RFCXXXX] | 3853 | low-percentile-g | TBA13 | 0 | IESG | [RFCXXXX] | 3854 | mid-percentile-g | TBA14 | 0 | IESG | [RFCXXXX] | 3855 | high-percentile-g | TBA15 | 0 | IESG | [RFCXXXX] | 3856 | peak-g | TBA16 | 0 | IESG | [RFCXXXX] | 3857 | total-attack-traffic | TBA17 | 4 | IESG | [RFCXXXX] | 3858 | total-traffic | TBA18 | 4 | IESG | [RFCXXXX] | 3859 | total-connection- | TBA19 | 4 | IESG | [RFCXXXX] | 3860 | capacity | | | | | 3861 | connection | TBA20 | 0 | IESG | [RFCXXXX] | 3862 | connection-client | TBA21 | 0 | IESG | [RFCXXXX] | 3863 | embryonic | TBA22 | 0 | IESG | [RFCXXXX] | 3864 | embryonic-client | TBA23 | 0 | IESG | [RFCXXXX] | 3865 | connection-ps | TBA24 | 0 | IESG | [RFCXXXX] | 3866 | connection-client-ps | TBA25 | 0 | IESG | [RFCXXXX] | 3867 | request-ps | TBA26 | 0 | IESG | [RFCXXXX] | 3868 | request-client-ps | TBA27 | 0 | IESG | [RFCXXXX] | 3869 | partial-request-ps | TBA28 | 0 | IESG | [RFCXXXX] | 3870 | partial-request- | TBA29 | 0 | IESG | [RFCXXXX] | 3871 | client-ps | | | | | 3872 | total-attack- | TBA30 | 5 | IESG | [RFCXXXX] | 3873 | connection | | | | | 3874 | low-percentile-l | TBA31 | 4 | IESG | [RFCXXXX] | 3875 | mid-percentile-l | TBA32 | 4 | IESG | [RFCXXXX] | 3876 | high-percentile-l | TBA33 | 4 | IESG | [RFCXXXX] | 3877 | peak-l | TBA34 | 4 | IESG | [RFCXXXX] | 3878 | attack-detail | TBA35 | 4 | IESG | [RFCXXXX] | 3879 | id | TBA36 | 0 | IESG | [RFCXXXX] | 3880 | attack-id | TBA37 | 3 | IESG | [RFCXXXX] | 3881 | attack-name | TBA38 | 3 | IESG | [RFCXXXX] | 3882 | attack-severity | TBA39 | 0 | IESG | [RFCXXXX] | 3883 | start-time | TBA40 | 0 | IESG | [RFCXXXX] | 3884 | end-time | TBA41 | 0 | IESG | [RFCXXXX] | 3885 | source-count | TBA42 | 5 | IESG | [RFCXXXX] | 3886 | top-talker | TBA43 | 5 | IESG | [RFCXXXX] | 3887 | spoofed-status | TBA44 | 7 | IESG | [RFCXXXX] | 3888 | low-percentile-c | TBA45 | 5 | IESG | [RFCXXXX] | 3889 | mid-percentile-c | TBA46 | 5 | IESG | [RFCXXXX] | 3890 | high-percentile-c | TBA47 | 5 | IESG | [RFCXXXX] | 3891 | peak-c | TBA48 | 5 | IESG | [RFCXXXX] | 3892 | ietf-dots-signal-cha | TBA49 | 5 | IESG | [RFCXXXX] | 3893 | current-config | TBA50 | 5 | IESG | [RFCXXXX] | 3894 | max-config-value | TBA51 | 5 | IESG | [RFCXXXX] | 3895 | min-config-values | TBA52 | 5 | IESG | [RFCXXXX] | 3896 | supported-units | TBA55 | 5 | IESG | [RFCXXXX] | 3897 | server-originated- | TBA54 | 7 | IESG | [RFCXXXX] | 3898 | telemetry | | | | | 3899 | telemetry-notify- | TBA55 | 0 | IESG | [RFCXXXX] | 3900 | interval | | | | | 3901 | tmid | TBA56 | 0 | IESG | [RFCXXXX] | 3902 | measurement-interval | TBA57 | 0 | IESG | [RFCXXXX] | 3903 | measurement-sample | TBA58 | 0 | IESG | [RFCXXXX] | 3904 | talker | TBA59 | 0 | IESG | [RFCXXXX] | 3905 | source-prefix | TBA60 | 0 | IESG | [RFCXXXX] | 3906 | mid-list | TBA61 | 4 | IESG | [RFCXXXX] | 3907 | source-port-range | TBA62 | 4 | IESG | [RFCXXXX] | 3908 | source-icmp-type- | TBA63 | 4 | IESG | [RFCXXXX] | 3909 | range | | | | | 3910 | lower-type | TBA64 | 0 | IESG | [RFCXXXX] | 3911 | upper-type | TBA65 | 0 | IESG | [RFCXXXX] | 3912 | target | TBA66 | 5 | IESG | [RFCXXXX] | 3913 | capacity | TBA67 | 0 | IESG | [RFCXXXX] | 3914 | protocol | TBA68 | 0 | IESG | [RFCXXXX] | 3915 | total-traffic- | TBA69 | 4 | IESG | [RFCXXXX] | 3916 | normal-per-protocol | | | | | 3917 | total-traffic- | TBA70 | 4 | IESG | [RFCXXXX] | 3918 | normal-per-port | | | | | 3919 | total-connection- | TBA71 | 4 | IESG | [RFCXXXX] | 3920 | capacity-per-port | | | | | 3921 | total-traffic- | TBA72 | 4 | IESG | [RFCXXXX] | 3922 | -protocol | | | | | 3923 | total-traffic-port | TBA73 | 4 | IESG | [RFCXXXX] | 3924 | total-attack- | TBA74 | 4 | IESG | [RFCXXXX] | 3925 | traffic-protocol | | | | | 3926 | total-attack- | TBA75 | 4 | IESG | [RFCXXXX] | 3927 | traffic-port | | | | | 3928 | total-attack- | TBA76 | 4 | IESG | [RFCXXXX] | 3929 | connection-port | | | | | 3930 | port | TBA77 | 0 | IESG | [RFCXXXX] | 3931 | ietf-dots-telemetry: | TBA80 | 5 | IESG | [RFCXXXX] | 3932 | telemetry-setup | | | | | 3933 | ietf-dots-telemetry: | TBA81 | 0 | IESG | [RFCXXXX] | 3934 | total-traffic | | | | | 3935 | ietf-dots-telemetry: | TBA82 | 0 | IESG | [RFCXXXX] | 3936 | unit | | | | | 3937 | ietf-dots-telemetry: | TBA83 | 0 | IESG | [RFCXXXX] | 3938 | low-percentile-g | | | | | 3939 | ietf-dots-telemetry: | TBA84 | 0 | IESG | [RFCXXXX] | 3940 | mid-percentile-g | | | | | 3941 | ietf-dots-telemetry: | TBA85 | 0 | IESG | [RFCXXXX] | 3942 | high-percentile-g | | | | | 3943 | ietf-dots-telemetry: | TBA86 | 0 | IESG | [RFCXXXX] | 3944 | peak-g | | | | | 3945 | ietf-dots-telemetry: | TBA87 | 0 | IESG | [RFCXXXX] | 3946 | total-attack-traffic | | | | | 3947 | ietf-dots-telemetry: | TBA88 | 0 | IESG | [RFCXXXX] | 3948 | total-attack- | | | | | 3949 | connection | | | | | 3950 | ietf-dots-telemetry: | TBA89 | 0 | IESG | [RFCXXXX] | 3951 | low-percentile-c | | | | | 3952 | ietf-dots-telemetry: | TBA90 | 0 | IESG | [RFCXXXX] | 3953 | mid-percentile-c | | | | | 3954 | ietf-dots-telemetry: | TBA91 | 0 | IESG | [RFCXXXX] | 3955 | high-percentile-c | | | | | 3956 | ietf-dots-telemetry: | TBA92 | 0 | IESG | [RFCXXXX] | 3957 | peak-c | | | | | 3958 | ietf-dots-telemetry: | TBA93 | 0 | IESG | [RFCXXXX] | 3959 | connection | | | | | 3960 | ietf-dots-telemetry: | TBA94 | 0 | IESG | [RFCXXXX] | 3961 | embryonic | | | | | 3962 | ietf-dots-telemetry: | TBA95 | 0 | IESG | [RFCXXXX] | 3963 | connection-ps | | | | | 3964 | ietf-dots-telemetry: | TBA96 | 0 | IESG | [RFCXXXX] | 3965 | request-ps | | | | | 3966 | ietf-dots-telemetry: | TBA97 | 0 | IESG | [RFCXXXX] | 3967 | partial-request-ps | | | | | 3968 | ietf-dots-telemetry: | TBA98 | 4 | IESG | [RFCXXXX] | 3969 | attack-detail | | | | | 3970 | ietf-dots-telemetry: | TBA99 | 0 | IESG | [RFCXXXX] | 3971 | id | | | | | 3972 | ietf-dots-telemetry: | TBA100| 0 | IESG | [RFCXXXX] | 3973 | attack-id | | | | | 3974 | ietf-dots-telemetry: | TBA101| 0 | IESG | [RFCXXXX] | 3975 | attack-name | | | | | 3976 | ietf-dots-telemetry: | TBA102| 0 | IESG | [RFCXXXX] | 3977 | attack-severity | | | | | 3978 | ietf-dots-telemetry: | TBA103| 0 | IESG | [RFCXXXX] | 3979 | start-time | | | | | 3980 | ietf-dots-telemetry: | TBA104| 0 | IESG | [RFCXXXX] | 3981 | end-time | | | | | 3982 | ietf-dots-telemetry: | TBA105| 0 | IESG | [RFCXXXX] | 3983 | source-count | | | | | 3984 | ietf-dots-telemetry: | TBA106| 0 | IESG | [RFCXXXX] | 3985 | top-talker | | | | | 3986 | ietf-dots-telemetry: | TBA107| 0 | IESG | [RFCXXXX] | 3987 | spoofed-status | | | | | 3988 | ietf-dots-telemetry: | TBA108| 0 | IESG | [RFCXXXX] | 3989 | talker | | | | | 3990 | ietf-dots-telemetry: | TBA109| 0 | IESG | [RFCXXXX] | 3991 | source-prefix | | | | | 3992 | ietf-dots-telemetry: | | | | | 3993 | source-port-range | TBA110| 4 | IESG | [RFCXXXX] | 3994 | ietf-dots-telemetry: | | | | | 3995 | lower-port | TBA111| 0 | IESG | [RFCXXXX] | 3996 | ietf-dots-telemetry: | | | | | 3997 | upper-port | TBA112| 0 | IESG | [RFCXXXX] | 3998 | ietf-dots-telemetry: | | | | | 3999 | source-icmp-type- | TBA113| 4 | IESG | [RFCXXXX] | 4000 | range | | | | | 4001 | ietf-dots-telemetry: | | | | | 4002 | lower-type | TBA114| 0 | IESG | [RFCXXXX] | 4003 | ietf-dots-telemetry: | | | | | 4004 | upper-type | TBA115| 0 | IESG | [RFCXXXX] | 4005 | ietf-dots-telemetry: | TBA116| 5 | IESG | [RFCXXXX] | 4006 | telemetry | | | | | 4007 +----------------------+-------+-------+------------+---------------+ 4009 11.2. DOTS Signal Channel Conflict Cause Codes 4011 This specification requests IANA to assign a new code from the "DOTS 4012 Signal Channel Conflict Cause Codes" registry available at 4013 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 4014 conflict-cause-codes. 4016 Code Label Description Reference 4017 TBA overlapping-pipes Overlapping pipe scope [RFCXXXX] 4019 11.3. DOTS Signal Telemetry YANG Module 4021 This document requests IANA to register the following URI in the "ns" 4022 subregistry within the "IETF XML Registry" [RFC3688]: 4024 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4025 Registrant Contact: The IESG. 4026 XML: N/A; the requested URI is an XML namespace. 4028 This document requests IANA to register the following YANG module in 4029 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4030 Parameters" registry. 4032 name: ietf-dots-telemetry 4033 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 4034 maintained by IANA: N 4035 prefix: dots-telemetry 4036 reference: RFC XXXX 4038 12. Security Considerations 4040 Security considerations in [I-D.ietf-dots-signal-channel] need to be 4041 taken into consideration. 4043 13. Contributors 4045 The following individuals have contributed to this document: 4047 o Li Su, CMCC, Email: suli@chinamobile.com 4049 o Jin Peng, CMCC, Email: pengjin@chinamobile.com 4051 o Pan Wei, Huawei, Email: william.panwei@huawei.com 4053 14. Acknowledgements 4055 The authors would like to thank Flemming Andreasen, Liang Xia, and 4056 Kaname Nishizuka co-authors of https://tools.ietf.org/html/draft- 4057 doron-dots-telemetry-00 draft and everyone who had contributed to 4058 that document. 4060 The authors would like to thank Kaname Nishizuka, Jon Shallow, Wei 4061 Pan and Yuuhei Hayashi for comments and review. 4063 15. References 4065 15.1. Normative References 4067 [Enterprise-Numbers] 4068 "Private Enterprise Numbers", 2005, . 4071 [I-D.ietf-dots-data-channel] 4072 Boucadair, M. and T. Reddy.K, "Distributed Denial-of- 4073 Service Open Threat Signaling (DOTS) Data Channel 4074 Specification", draft-ietf-dots-data-channel-31 (work in 4075 progress), July 2019. 4077 [I-D.ietf-dots-signal-call-home] 4078 Reddy.K, T., Boucadair, M., and J. Shallow, "Distributed 4079 Denial-of-Service Open Threat Signaling (DOTS) Signal 4080 Channel Call Home", draft-ietf-dots-signal-call-home-08 4081 (work in progress), March 2020. 4083 [I-D.ietf-dots-signal-channel] 4084 Reddy.K, T., Boucadair, M., Patil, P., Mortensen, A., and 4085 N. Teague, "Distributed Denial-of-Service Open Threat 4086 Signaling (DOTS) Signal Channel Specification", draft- 4087 ietf-dots-signal-channel-41 (work in progress), January 4088 2020. 4090 [I-D.ietf-dots-signal-filter-control] 4091 Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 4092 "Controlling Filtering Rules Using Distributed Denial-of- 4093 Service Open Threat Signaling (DOTS) Signal Channel", 4094 draft-ietf-dots-signal-filter-control-03 (work in 4095 progress), March 2020. 4097 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4098 Requirement Levels", BCP 14, RFC 2119, 4099 DOI 10.17487/RFC2119, March 1997, 4100 . 4102 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4103 DOI 10.17487/RFC3688, January 2004, 4104 . 4106 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4107 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4108 . 4110 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4111 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4112 October 2013, . 4114 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4115 Application Protocol (CoAP)", RFC 7641, 4116 DOI 10.17487/RFC7641, September 2015, 4117 . 4119 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4120 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4121 . 4123 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4124 the Constrained Application Protocol (CoAP)", RFC 7959, 4125 DOI 10.17487/RFC7959, August 2016, 4126 . 4128 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4129 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4130 May 2017, . 4132 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 4133 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 4134 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 4135 2018, . 4137 15.2. Informative References 4139 [I-D.ietf-dots-multihoming] 4140 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 4141 Deployment Considerations for Distributed-Denial-of- 4142 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 4143 multihoming-03 (work in progress), January 2020. 4145 [I-D.ietf-dots-use-cases] 4146 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 4147 L., and K. Nishizuka, "Use cases for DDoS Open Threat 4148 Signaling", draft-ietf-dots-use-cases-20 (work in 4149 progress), September 2019. 4151 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 4152 "Framework for IP Performance Metrics", RFC 2330, 4153 DOI 10.17487/RFC2330, May 1998, 4154 . 4156 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4157 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4158 . 4160 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4161 Threat Signaling (DOTS) Requirements", RFC 8612, 4162 DOI 10.17487/RFC8612, May 2019, 4163 . 4165 Authors' Addresses 4167 Mohamed Boucadair (editor) 4168 Orange 4169 Rennes 35000 4170 France 4172 Email: mohamed.boucadair@orange.com 4174 Tirumaleswar Reddy (editor) 4175 McAfee, Inc. 4176 Embassy Golf Link Business Park 4177 Bangalore, Karnataka 560071 4178 India 4180 Email: kondtir@gmail.com 4182 Ehud Doron 4183 Radware Ltd. 4184 Raoul Wallenberg Street 4185 Tel-Aviv 69710 4186 Israel 4188 Email: ehudd@radware.com 4190 Meiling Chen 4191 CMCC 4192 32, Xuanwumen West 4193 BeiJing, BeiJing 100053 4194 China 4196 Email: chenmeiling@chinamobile.com