idnits 2.17.1 draft-ietf-dots-telemetry-05.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 175 instances of too long lines in the document, the longest one being 8 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 868 has weird spacing: '...apacity uin...' == Line 1186 has weird spacing: '...er-port ine...' == Line 1431 has weird spacing: '...er-port ine...' == Line 1661 has weird spacing: '...er-port ine...' == Line 1664 has weird spacing: '...er-type uin...' == (2 more instances...) -- The document date (March 27, 2020) is 1484 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 3579, but not defined == Unused Reference: 'I-D.ietf-dots-signal-call-home' is defined on line 3639, 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 (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy, Ed. 5 Expires: September 28, 2020 McAfee 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 March 27, 2020 12 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 13 draft-ietf-dots-telemetry-05 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 September 28, 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 . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . 12 76 6.1.1. Retrieve Current DOTS Telemetry Configuration . . . . 12 77 6.1.2. Convey DOTS Telemetry Configuration . . . . . . . . . 15 78 6.1.3. Retrieve Installed DOTS Telemetry Configuration . . . 18 79 6.1.4. Delete DOTS Telemetry Configuration . . . . . . . . . 18 80 6.2. Total Pipe Capacity . . . . . . . . . . . . . . . . . . . 19 81 6.2.1. Convey DOTS Client Domain Pipe Capacity . . . . . . . 20 82 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity . 25 83 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity . . 25 84 6.3. Telemetry Baseline . . . . . . . . . . . . . . . . . . . 26 85 6.3.1. Convey DOTS Client Domain Baseline Information . . . 28 86 6.3.2. Retrieve Installed Normal Traffic Baseline . . . . . 29 87 6.3.3. Delete Installed Normal Traffic Baseline . . . . . . 29 88 6.4. Reset Installed Telemetry Setup . . . . . . . . . . . . . 30 89 6.5. Conflict with Other DOTS Clients of the Same Domain . . . 30 90 7. DOTS Pre-or-Ongoing Mitigation Telemetry . . . . . . . . . . 30 91 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes . . . 32 92 7.1.1. Target . . . . . . . . . . . . . . . . . . . . . . . 32 93 7.1.2. Total Traffic . . . . . . . . . . . . . . . . . . . . 33 94 7.1.3. Total Attack Traffic . . . . . . . . . . . . . . . . 34 95 7.1.4. Total Attack Connections . . . . . . . . . . . . . . 35 96 7.1.5. Attack Details . . . . . . . . . . . . . . . . . . . 37 98 7.2. From DOTS Clients to DOTS Servers . . . . . . . . . . . . 39 99 7.3. From DOTS Servers to DOTS Clients . . . . . . . . . . . . 40 100 8. DOTS Telemetry Mitigation Status Update . . . . . . . . . . . 43 101 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS 102 Telemetry Attributes . . . . . . . . . . . . . . . . . . 43 103 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 104 Attributes . . . . . . . . . . . . . . . . . . . . . . . 45 105 9. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 48 106 10. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 72 107 11. IANA Considerationsr . . . . . . . . . . . . . . . . . . . . 75 108 11.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 75 109 11.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 79 110 11.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 79 111 12. Security Considerations . . . . . . . . . . . . . . . . . . . 79 112 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 80 113 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 80 114 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 115 15.1. Normative References . . . . . . . . . . . . . . . . . . 80 116 15.2. Informative References . . . . . . . . . . . . . . . . . 81 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 119 1. Introduction 121 Distributed Denial of Service (DDoS) attacks have become more vicious 122 and sophisticated in almost all aspects of their maneuvers and 123 malevolent intentions. IT organizations and service providers are 124 facing DDoS attacks that fall into two broad categories: Network/ 125 Transport layer attacks and Application layer attacks: 127 o Network/Transport layer attacks target the victim's 128 infrastructure. These attacks are not necessarily aimed at taking 129 down the actual delivered services, but rather to eliminate 130 various network elements (routers, switches, firewalls, transit 131 links, and so on) from serving legitimate user traffic. 133 The main method of such attacks is to send a large volume or high 134 packet per second (PPS) of traffic toward the victim's 135 infrastructure. Typically, attack volumes may vary from a few 100 136 Mbps/PPS to 100s of Gbps or even Tbps. Attacks are commonly 137 carried out leveraging botnets and attack reflectors for 138 amplification attacks such as NTP (Network Time Protocol), DNS 139 (Domain Name System), SNMP (Simple Network Management Protocol), 140 or SSDP (Simple Service Discovery Protoco). 142 o Application layer attacks target various applications. Typical 143 examples include attacks against HTTP/HTTPS, DNS, SIP (Session 144 Initiation Protocol), or SMTP (Simple Mail Transfer Protocol). 146 However, all valid applications with their port numbers open at 147 network edges can be attractive attack targets. 149 Application layer attacks are considered more complex and hard to 150 categorize, therefore harder to detect and mitigate efficiently. 152 To compound the problem, attackers also leverage multi-vectored 153 attacks. These attacks are assembled from dynamic attack vectors 154 (Network/Application) and tactics. As such, multiple attack vectors 155 formed by multiple attack types and volumes are launched 156 simultaneously towards a victim. Multi-vector attacks are harder to 157 detect and defend. Multiple and simultaneous mitigation techniques 158 are needed to defeat such attack campaigns. It is also common for 159 attackers to change attack vectors right after a successful 160 mitigation, burdening their opponents with changing their defense 161 methods. 163 The ultimate conclusion derived from these real scenarios is that 164 modern attacks detection and mitigation are most certainly 165 complicated and highly convoluted tasks. They demand a comprehensive 166 knowledge of the attack attributes, the targeted normal behavior/ 167 traffic patterns, as well as the attacker's on-going and past 168 actions. Even more challenging, retrieving all the analytics needed 169 for detecting these attacks is not simple to obtain with the 170 industry's current capabilities. 172 The DOTS signal channel protocol [I-D.ietf-dots-signal-channel] is 173 used to carry information about a network resource or a network (or a 174 part thereof) that is under a DDoS attack. Such information is sent 175 by a DOTS client to one or multiple DOTS servers so that appropriate 176 mitigation actions are undertaken on traffic deemed suspicious. 177 Various use cases are discussed in [I-D.ietf-dots-use-cases]. 179 Typically, DOTS clients can be integrated within a DDoS attack 180 detector, or network and security elements that have been actively 181 engaged with ongoing attacks. The DOTS client mitigation environment 182 determines that it is no longer possible or practical for it to 183 handle these attacks. This can be due to lack of resources or 184 security capabilities, as derived from the complexities and the 185 intensity of these attacks. In this circumstance, the DOTS client 186 has invaluable knowledge about the actual attacks that need to be 187 handled by its DOTS server(s). By enabling the DOTS client to share 188 this comprehensive knowledge of an ongoing attack under specific 189 circumstances, the DOTS server can drastically increase its ability 190 to accomplish successful mitigation. While the attack is being 191 handled by the DOTS server associated mitigation resources, the DOTS 192 server has the knowledge about the ongoing attack mitigation. The 193 DOTS server can share this information with the DOTS client so that 194 the client can better assess and evaluate the actual mitigation 195 realized. 197 In some deployments, DOTS clients can send mitigation hints derived 198 from attack details to DOTS servers, with the full understanding that 199 the DOTS server may ignore mitigation hints, as described in 200 [RFC8612] (Gen-004). Mitigation hints will be transmitted across the 201 DOTS signal channel, as the data channel may not be functional during 202 an attack. How a DOTS server is handling normal and attack traffic 203 attributes, and mitigation hints is implementation-specific. 205 Both DOTS client and server can benefit this information by 206 presenting various information in relevant management, reporting, and 207 portal systems. 209 This document defines DOTS telemetry attributes the DOTS client can 210 convey to the DOTS server, and vice versa. The DOTS telemetry 211 attributes are not mandatory fields. Nevertheless, when DOTS 212 telemetry attributes are available to a DOTS agent, and absent any 213 policy, it can signal the attributes in order to optimize the overall 214 mitigation service provisioned using DOTS. Some of the DOTS 215 telemetry data is not shared during an attack time. 217 2. Terminology 219 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 220 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 221 "OPTIONAL" in this document are to be interpreted as described in BCP 222 14 [RFC2119][RFC8174] when, and only when, they appear in all 223 capitals, as shown here. 225 The reader should be familiar with the terms defined in [RFC8612]. 227 "DOTS Telemetry" is defined as the collection of attributes that are 228 used to characterize normal traffic baseline, attacks and their 229 mitigation measures, and any related information that may help in 230 enforcing countermeasures. The DOTS Telemetry is an optional set of 231 attributes that can be signaled in the DOTS signal channel protocol. 233 The meaning of the symbols in YANG tree diagrams is defined in 234 [RFC8340]. 236 3. DOTS Telemetry: Overview and Purpose 238 When signaling a mitigation request, it is most certainly beneficial 239 for the DOTS client to signal to the DOTS server any knowledge 240 regarding ongoing attacks. This can happen in cases where DOTS 241 clients are asking the DOTS server for support in defending against 242 attacks that they have already detected and/or mitigated. These 243 actions taken by DOTS clients are referred to as "signaling the DOTS 244 Telemetry". 246 If attacks are already detected and categorized by the DOTS client 247 domain, the DOTS server, and its associated mitigation services, can 248 proactively benefit this information and optimize the overall service 249 delivered. It is important to note that DOTS client and server 250 detection and mitigation approaches can be different, and can 251 potentially outcome different results and attack classifications. 252 The DDoS mitigation service treats the ongoing attack details from 253 the client as hints and cannot completely rely or trust the attack 254 details conveyed by the DOTS client. 256 A basic requirement of security operation teams is to be aware and 257 get visibility into the attacks they need to handle. The DOTS server 258 security operation teams benefit from the DOTS telemetry, especially 259 from the reports of ongoing attacks. Even if some mitigation can be 260 automated, operational teams can use the DOTS telemetry to be 261 prepared for attack mitigation and to assign the correct resources 262 (operation staff, networking and mitigation) for the specific 263 service. Similarly, security operation personnel at the DOTS client 264 side ask for feedback about their requests for protection. 265 Therefore, it is valuable for the DOTS server to share DOTS telemetry 266 with the DOTS client. 268 Thus mutual sharing of information is crucial for "closing the 269 mitigation loop" between the DOTS client and server. For the server 270 side team, it is important to realize that the same attacks that the 271 DOTS server's mitigation resources are seeing are those that the DOTS 272 client is asking to mitigate. For the DOTS client side team, it is 273 important to realize that the DOTS clients receive the required 274 service. For example, understanding that "I asked for mitigation of 275 two attacks and my DOTS server detects and mitigates only one...". 276 Cases of inconsistency in attack classification between DOTS client 277 and server can be high-lighted, and maybe handled, using the DOTS 278 telemetry attributes. 280 In addition, management and orchestration systems, at both DOTS 281 client and server sides, can potentially use DOTS telemetry as a 282 feedback to automate various control and management activities 283 derived from ongoing information signaled. 285 If the DOTS server's mitigation resources have the capabilities to 286 facilitate the DOTS telemetry, the DOTS server adopts its protection 287 strategy and activates the required countermeasures immediately 288 (automation enabled). The overall results of this adoption are 289 optimized attack mitigation decisions and actions. 291 The DOTS telemetry can also be used to tune the DDoS mitigators with 292 the correct state of the attack. During the last few years, DDoS 293 attack detection technologies have evolved from threshold-based 294 detection (that is, cases when all or specific parts of traffic cross 295 a pre-defined threshold for a certain period of time is considered as 296 an attack) to an "anomaly detection" approach. In anomaly detection, 297 the main idea is to maintain rigorous learning of "normal" behavior 298 and where an "anomaly" (or an attack) is identified and categorized 299 based on the knowledge about the normal behavior and a deviation from 300 this normal behavior. Machine learning approaches are used such that 301 the actual "traffic thresholds" are "automatically calculated" by 302 learning the protected entity normal traffic behavior during peace 303 time. The normal traffic characterization learned is referred to as 304 the "normal traffic baseline". An attack is detected when the 305 victim's actual traffic is deviating from this normal baseline. 307 In addition, subsequent activities toward mitigating an attack are 308 much more challenging. The ability to distinguish legitimate traffic 309 from attacker traffic on a per packet basis is complex. This 310 complexity originates from the fact that the packet itself may look 311 "legitimate" and no attack signature can be identified. The anomaly 312 can be identified only after detailed statistical analysis. DDoS 313 attack mitigators use the normal baseline during the mitigation of an 314 attack to identify and categorize the expected appearance of a 315 specific traffic pattern. Particularly the mitigators use the normal 316 baseline to recognize the "level of normality" needs to be achieved 317 during the various mitigation process. 319 Normal baseline calculation is performed based on continuous learning 320 of the normal behavior of the protected entities. The minimum 321 learning period varies from hours to days and even weeks, depending 322 on the protected application behavior. The baseline cannot be 323 learned during active attacks because attack conditions do not 324 characterize the protected entities' normal behavior. 326 If the DOTS client has calculated the normal baseline of its 327 protected entities, signaling this attribute to the DOTS server along 328 with the attack traffic levels is significantly valuable. The DOTS 329 server benefits from this telemetry by tuning its mitigation 330 resources with the DOTS client's normal baseline. The DOTS server 331 mitigators use the baseline to familiarize themselves with the attack 332 victim's normal behavior and target the baseline as the level of 333 normality they need to achieve. Consequently, the overall mitigation 334 performances obtained are dramatically improved in terms of time to 335 mitigate, accuracy, false-negative, false-positive, and other 336 measures. 338 Mitigation of attacks without having certain knowledge of normal 339 traffic can be inaccurate at best. This is especially true for 340 recursive signaling (see Section 3.2.3 in [I-D.ietf-dots-use-cases]). 341 In addition, the highly diverse types of use-cases where DOTS clients 342 are integrated also emphasize the need for knowledge of client 343 behavior. Consequently, common global thresholds for attack 344 detection practically cannot be realized. Each DOTS client can have 345 its own levels of traffic and normal behavior. Without facilitating 346 normal baseline signaling, it may be very difficult for DOTS servers 347 in some cases to detect and mitigate the attacks accurately: 349 It is important to emphasize that it is practically impossible for 350 the server's mitigators to calculate the normal baseline in cases 351 where they do not have any knowledge of the traffic beforehand. 353 In addition, baseline learning requires a period of time that 354 cannot be afforded during active attack. 356 Of course, this information can provided using out-of-band 357 mechanisms or manual configuration at the risk to maintain 358 inaccurate information as the network evolves and "normal" 359 patterns change. The use of a dynamic and collaborative means 360 between the DOTS client and server to identify and share key 361 parameters for the sake of efficient DDoS protection is valuable. 363 During a high volume attack, DOTS client pipes can be totally 364 saturated. The DOTS client asks the DOTS server to handle the attack 365 upstream so that DOTS client pipes return to a reasonable load level 366 (normal pattern, ideally). At this point, it is essential to ensure 367 that the mitigator does not overwhelm the DOTS client pipes by 368 sending back "clean traffic", or what it believes is "clean". This 369 can happen when the mitigator has not managed to detect and mitigate 370 all the attacks launched towards the client. In this case, it can be 371 valuable to clients to signal to server the "Total pipe capacity", 372 which is the level of traffic the DOTS client domain can absorb from 373 the upstream network. Dynamic updates of the condition of pipes 374 between DOTS agents while they are under a DDoS attack is essential. 375 For example, where multiple DOTS clients share the same physical 376 connectivity pipes. It is important to note, that the term "pipe" 377 noted here does not necessary represent physical pipe, but rather 378 represents the maximum level of traffic that the DOTS client domain 379 can receive. The DOTS server should activate other mechanisms to 380 ensure it does not allow the client's pipes to be saturated 381 unintentionally. The rate-limit action defined in 382 [I-D.ietf-dots-data-channel] is a reasonable candidate to achieve 383 this objective; the client can ask for the type of traffic (such as 384 ICMP, UDP, TCP port number 80) it prefers to limit. The rate-limit 385 action can be controlled via the signal-channel 387 [I-D.ietf-dots-signal-filter-control] even when the pipe is 388 overwhelmed. 390 To summarize: 392 Timely and effective signaling of up-to-date DOTS telemetry to all 393 elements involved in the mitigation process is essential and 394 absolutely improves the overall service effectiveness. Bi- 395 directional feedback between DOTS agents is required for the 396 increased awareness of each party, supporting superior and highly 397 efficient attack mitigation service. 399 4. Generic Considerations 401 4.1. DOTS Client Identification 403 Following the rules in [I-D.ietf-dots-signal-channel], a unique 404 identifier is generated by a DOTS client to prevent request 405 collisions ('cuid'). 407 4.2. DOTS Gateways 409 DOTS gateways may be located between DOTS clients and servers. The 410 considerations elaborated in [I-D.ietf-dots-signal-channel] must be 411 followed. In particular, 'cdid' attribute is used to unambiguously 412 identify a DOTS client domain. 414 4.3. Empty URI Paths 416 Uri-Path parameters and attributes with empty values MUST NOT be 417 present in a request and render an entire message invalid. 419 4.4. Controlling Configuration Data 421 The DOTS server follows the same considerations discussed in 422 Section of 4.5.3 of [I-D.ietf-dots-signal-channel] for managing DOTS 423 telemetry configuration freshness and notification. Likewise, a DOTS 424 client may control the selection of configuration and non- 425 configuration data nodes when sending a GET request by means of the 426 'c' Uri-Query option and following the procedure specified in 427 Section of 4.4.2 of [I-D.ietf-dots-signal-channel]. These 428 considerations are not re-iterated in the following sections. 430 4.5. Block-wise Transfer 432 DOTS clients can use Block-wise transfer [RFC7959] with the 433 recommendation detailed in Section 4.4.2 of 435 [I-D.ietf-dots-signal-channel] to control the size of a response when 436 the data to be returned does not fit within a single datagram. 438 DOTS clients can also use Block1 Option in a PUT request (see 439 Section 2.5 of [RFC7959]) to initiate large transfers, but these 440 Block1 transfers will fail if the inbound "pipe" is running full, so 441 consideration needs to be made to try to fit this PUT into a single 442 transfer, or to separate out the PUT into several discrete PUTs where 443 each of them fits into a single packet. 445 4.6. DOTS Multi-homing Considerations 447 Multi-homed DOTS clients are assumed to follow the recommendations in 448 [I-D.ietf-dots-multihoming] to select which DOTS server to contact 449 and which IP prefixes to include in a telemetry message to a given 450 peer DOTS server. For example, if each upstream network exposes a 451 DOTS server and the DOTS client maintains DOTS channels with all of 452 them, only the information related to prefixes assigned by an 453 upstream network to the DOTS client domain will be signaled via the 454 DOTS channel established with the DOTS server of that upstream 455 network. Considerations related to whether (and how) a DOTS client 456 gleans some telemetry information (e.g., attack details) it receives 457 from a first DOTS server and share it with a second DOTS server are 458 implementation- and deployment-specific. 460 4.7. YANG Considerations 462 Messages exchanged between DOTS agents are serialized using Concise 463 Binary Object Representation (CBOR). CBOR-encoded payloads are used 464 to carry signal channel-specific payload messages which convey 465 request parameters and response information such as errors 466 [I-D.ietf-dots-signal-channel]. 468 This document specifies a YANG module for representing DOTS telemetry 469 message types (Section 9). All parameters in the payload of the DOTS 470 signal channel are mapped to CBOR types as specified in Section 10. 472 The DOTS telemetry module (Section 9) uses "enumerations" rather than 473 "identities" to define units, samples, and intervals because 474 otherwise the namespace identifier "ietf-dots-telemetry" must be 475 included when a telemetry attribute is included (e.g., in a 476 mitigation efficacy update). The use of "identities" is thus 477 suboptimal from a message compactness standpoint. 479 4.8. A Note About Examples 481 Examples are provided for illustration purposes. The document does 482 not aim to provide a comprehensive list of message examples. 484 The authoritative reference for validating telemetry messages is the 485 YANG module (Section 9) and the mapping table established in 486 Section 10. 488 5. Telemetry Operation Paths 490 As discussed in [I-D.ietf-dots-signal-channel], each DOTS operation 491 is indicated by a path-suffix that indicates the intended operation. 492 The operation path is appended to the path-prefix to form the URI 493 used with a CoAP request to perform the desired DOTS operation. The 494 following telemetry path-suffixes are defined (Table 1): 496 +-----------------+----------------+-----------+ 497 | Operation | Operation Path | Details | 498 +-----------------+----------------+-----------+ 499 | Telemetry Setup | /tm-setup | Section 6 | 500 | Telemetry | /tm | Section 7 | 501 +-----------------+----------------+-----------+ 503 Table 1: DOTS Telemetry Operations 505 Consequently, the "ietf-dots-telemetry" YANG module defined in this 506 document (Section 9) augments the "ietf-dots-signal" with two new 507 message types called "telemetry-setup" and "telemetry". The tree 508 structure is shown in Figure 1 (more details are provided in the 509 following sections about the exact structure of "telemetry-setup" and 510 "telemetry" message types). 512 augment /ietf-signal:dots-signal/ietf-signal:message-type: 513 +--:(telemetry-setup) {dots-telemetry}? 514 | ... 515 | +--rw (setup-type)? 516 | +--:(telemetry-config) 517 | | ... 518 | +--:(pipe) 519 | | ... 520 | +--:(baseline) 521 | ... 522 +--:(telemetry) {dots-telemetry}? 523 ... 525 Figure 1: New DOTS Message Types (YANG Tree Structure) 527 6. DOTS Telemetry Setup Configuration 529 In reference to Figure 1, a DOTS telemetry setup message MUST include 530 only telemetry-related configuration parameters (Section 6.1) or 531 information about DOTS client domain pipe capacity (Section 6.2) or 532 telemetry traffic baseline (Section 6.3). As such, requests that 533 include a mix of telemetry configuration, pipe capacity, or traffic 534 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 536 A DOTS client can reset all installed DOTS telemetry setup 537 configuration data following the considerations detailed in 538 Section 6.4. 540 A DOTS server may detect conflicts when processing requests related 541 to DOTS client domain pipe capacity or telemetry traffic baseline 542 with requests from other DOTS clients of the same DOTS client domain. 543 More details are included in Section 6.5. 545 DOTS telemetry setup configuration request and response messages are 546 marked as Confirmable messages. 548 6.1. Telemetry Configuration 550 A DOTS client can negotiate with its server(s) a set of telemetry 551 configuration parameters to be used for telemetry. Such parameters 552 include: 554 o Percentile-related measurement parameters 556 o Measurement units 558 o Acceptable percentile values 560 o Telemetry notification interval 562 o Acceptable Server-originated telemetry 564 Section 11.3 of [RFC2330] includes more details about computing 565 percentiles. 567 6.1.1. Retrieve Current DOTS Telemetry Configuration 569 A GET request is used to obtain acceptable and current telemetry 570 configuration parameters on the DOTS server. This request may 571 include a 'cdid' Path-URI when the request is relayed by a DOTS 572 gateway. An example of such request is depicted in Figure 2. 574 Header: GET (Code=0.01) 575 Uri-Path: ".well-known" 576 Uri-Path: "dots" 577 Uri-Path: "tm-setup" 578 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 580 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 581 Configuration 583 Upon receipt of such request, the DOTS server replies with a 2.05 584 (Content) response that conveys the current and telemetry parameters 585 acceptable by the DOTS server. The tree structure of the response 586 message body is provided in Figure 3. Note that the response also 587 includes any pipe (Section 6.2) and baseline information 588 (Section 6.3) maintained by the DOTS server for this DOTS client. 590 DOTS servers that support the capability of sending telemetry 591 information to DOTS clients prior or during a mitigation 592 (Section 8.2) sets 'server-originated-telemetry' under 'max-config- 593 values' to 'true' ('false' is used otherwise). If 'server- 594 originated-telemetry' is not present in a response, this is 595 equivalent to receiving a request with 'server-originated-telemetry'' 596 set to 'false'. 598 augment /ietf-signal:dots-signal/ietf-signal:message-type: 599 +--:(telemetry-setup) {dots-telemetry}? 600 | +--rw telemetry* [cuid tsid] 601 | ... 602 | +--rw (setup-type)? 603 | +--:(telemetry-config) 604 | | +--rw current-config 605 | | | +--rw measurement-interval? interval 606 | | | +--rw measurement-sample? sample 607 | | | +--rw low-percentile? percentile 608 | | | +--rw mid-percentile? percentile 609 | | | +--rw high-percentile? percentile 610 | | | +--rw unit-config* [unit] 611 | | | | +--rw unit unit 612 | | | | +--rw unit-status? boolean 613 | | | +--rw server-originated-telemetry? boolean 614 | | | +--rw telemetry-notify-interval? uint32 615 | | +--ro max-config-values 616 | | | +--ro measurement-interval? interval 617 | | | +--ro measurement-sample? sample 618 | | | +--ro low-percentile? percentile 619 | | | +--ro mid-percentile? percentile 620 | | | +--ro high-percentile? percentile 621 | | | +--ro server-originated-telemetry? boolean 622 | | | +--ro telemetry-notify-interval? uint32 623 | | +--ro min-config-values 624 | | | +--ro measurement-interval? interval 625 | | | +--ro measurement-sample? sample 626 | | | +--ro low-percentile? percentile 627 | | | +--ro mid-percentile? percentile 628 | | | +--ro high-percentile? percentile 629 | | | +--ro telemetry-notify-interval? uint32 630 | | +--ro supported-units 631 | | +--ro unit-config* [unit] 632 | | +--ro unit unit 633 | | +--ro unit-status? boolean 634 | +--:(pipe) 635 | ... 636 | +--:(baseline) 637 | ... 638 +--:(telemetry) {dots-telemetry}? 639 +--rw pre-or-ongoing-mitigation* [cuid tmid] 640 ... 642 Figure 3: Telemetry Configuration Tree Structure 644 When both 'min-config-values' and 'max-config-values' attributes are 645 present, the values carried in 'max-config-values' attributes MUST be 646 greater or equal to their counterpart in 'min-config-values' 647 attributes. 649 6.1.2. Convey DOTS Telemetry Configuration 651 PUT request is used to convey the configuration parameters for the 652 telemetry data (e.g., low, mid, or high percentile values). For 653 example, a DOTS client may contact its DOTS server to change the 654 default percentile values used as baseline for telemetry data. 655 Figure 3 lists the attributes that can be set by a DOTS client in 656 such PUT request. An example of a DOTS client that modifies all 657 percentile reference values is shown in Figure 4. 659 Header: PUT (Code=0.03) 660 Uri-Path: ".well-known" 661 Uri-Path: "dots" 662 Uri-Path: "tm-setup" 663 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 664 Uri-Path: "tsid=123" 665 Content-Format: "application/dots+cbor" 667 { 668 "ietf-dots-telemetry:telemetry-setup": { 669 "telemetry": [ 670 { 671 "current-config": { 672 "low-percentile": "5.00", 673 "mid-percentile": "65.00", 674 "high-percentile": "95.00" 675 } 676 } 677 ] 678 } 679 } 681 Figure 4: PUT to Convey the DOTS Telemetry Configuration 683 'cuid' is a mandatory Uri-Path parameter for PUT requests. 685 The following additional Uri-Path parameter is defined: 687 tsid: Telemetry Setup Identifier is an identifier for the DOTS 688 telemetry setup configuration data represented as an integer. 689 This identifier MUST be generated by DOTS clients. 'tsid' 690 values MUST increase monotonically (when a new PUT is generated 691 by a DOTS client to convey new configuration parameters for the 692 telemetry). 694 This is a mandatory attribute. 696 At least one configurable attribute MUST be present in the PUT 697 request. 699 The PUT request with a higher numeric 'tsid' value overrides the DOTS 700 telemetry configuration data installed by a PUT request with a lower 701 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 702 requests for requests carrying telemetry configuration data from a 703 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 704 and no longer be available at the DOTS server. 706 The DOTS server indicates the result of processing the PUT request 707 using the following response codes: 709 o If the request is missing a mandatory attribute, does not include 710 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 711 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 712 in the response. 714 o If the DOTS server does not find the 'tsid' parameter value 715 conveyed in the PUT request in its configuration data and if the 716 DOTS server has accepted the configuration parameters, then a 717 response code 2.01 (Created) MUST be returned in the response. 719 o If the DOTS server finds the 'tsid' parameter value conveyed in 720 the PUT request in its configuration data and if the DOTS server 721 has accepted the updated configuration parameters, 2.04 (Changed) 722 MUST be returned in the response. 724 o If any of the enclosed configurable attribute values are not 725 acceptable to the DOTS server (Section 6.1.1), 4.22 (Unprocessable 726 Entity) MUST be returned in the response. 728 The DOTS client may re-try and send the PUT request with updated 729 attribute values acceptable to the DOTS server. 731 By default, low percentile (10th percentile), mid percentile (50th 732 percentile), high percentile (90th percentile), and peak (100th 733 percentile) values are used to represent telemetry data. 734 Nevertheless, a DOTS client can disable some percentile types (low, 735 mid, high). In particular, setting 'low-percentile' to '0.00' 736 indicates that the DOTS client is not interested in receiving low- 737 percentiles. Likewise, setting 'mid-percentile' (or 'high- 738 percentile') to the same value as 'low-percentile' (or 'mid- 739 percentile') indicates that the DOTS client is not interested in 740 receiving mid-percentiles (or high-percentiles). For example, a DOTS 741 client can send the request depicted in Figure 5 to inform the server 742 that it is interested in receiving only high-percentiles. This 743 assumes that the client will only use that percentile type when 744 sharing telemetry data with the server. 746 Header: PUT (Code=0.03) 747 Uri-Path: ".well-known" 748 Uri-Path: "dots" 749 Uri-Path: "tm-setup" 750 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 751 Uri-Path: "tsid=569" 752 Content-Format: "application/dots+cbor" 754 { 755 "ietf-dots-telemetry:telemetry-setup": { 756 "telemetry": [ 757 { 758 "current-config": { 759 "low-percentile": "0.00", 760 "mid-percentile": "0.00", 761 "high-percentile": "95.00" 762 } 763 } 764 ] 765 } 766 } 768 Figure 5: PUT to Disable Low- and Mid-Percentiles 770 DOTS clients can also configure the unit type(s) to be used for 771 traffic-related telemetry data. Typically, the supported unit types 772 are: packets per second, bits per second, and bytes per second. 774 DOTS clients that are interested to receive pre- or onoing mitigation 775 telemetry (pre-or-ongoing-mitigation) information from a DOTS server 776 (Section 8.2) MUST set 'server-originated-telemetry' to 'true'. If 777 'server-originated-telemetry' is not present in a PUT request, this 778 is equivalent to receiving a request with 'server-originated- 779 telemetry'' set to 'false'. An example of a request to enable pre- 780 or-ongoing-mitigation telemetry from DOTS servers is shown in 781 Figure 6. 783 Header: PUT (Code=0.03) 784 Uri-Path: ".well-known" 785 Uri-Path: "dots" 786 Uri-Path: "tm-setup" 787 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 788 Uri-Path: "tsid=569" 789 Content-Format: "application/dots+cbor" 791 { 792 "ietf-dots-telemetry:telemetry-setup": { 793 "telemetry": [ 794 { 795 "current-config": { 796 "server-originated-telemetry": true 797 } 798 } 799 ] 800 } 801 } 803 Figure 6: PUT to Enable Pre-or-ongoing-mitigation Telemetry from the 804 DOTS server 806 6.1.3. Retrieve Installed DOTS Telemetry Configuration 808 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 809 to retrieve the current DOTS telemetry configuration. An example of 810 such request is depicted in Figure 7. 812 Header: GET (Code=0.01) 813 Uri-Path: ".well-known" 814 Uri-Path: "dots" 815 Uri-Path: "tm-setup" 816 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 817 Uri-Path: "tsid=123" 819 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 821 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 822 in the GET request in its configuration data for the requesting DOTS 823 client, it MUST respond with a 4.04 (Not Found) error response code. 825 6.1.4. Delete DOTS Telemetry Configuration 827 A DELETE request is used to delete the installed DOTS telemetry 828 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 829 Path parameters for such DELETE requests. 831 Header: DELETE (Code=0.04) 832 Uri-Path: ".well-known" 833 Uri-Path: "dots" 834 Uri-Path: "tm-setup" 835 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 836 Uri-Path: "tsid=123" 838 Figure 8: Delete Telemetry Configuration 840 The DOTS server resets the DOTS telemetry configuration back to the 841 default values and acknowledges a DOTS client's request to remove the 842 DOTS telemetry configuration using 2.02 (Deleted) response code. A 843 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 844 value conveyed in the DELETE request does not exist in its 845 configuration data before the request. 847 Section 6.4 discusses the procedure to reset all DOTS telemetry setup 848 configuration. 850 6.2. Total Pipe Capacity 852 A DOTS client can communicate to its server(s) its DOTS client domain 853 pipe information. The tree structure of the pipe information is 854 shown in Figure 9. 856 augment /ietf-signal:dots-signal/ietf-signal:message-type: 857 +--:(telemetry-setup) {dots-telemetry}? 858 | +--rw telemetry* [cuid tsid] 859 | +--rw cuid string 860 | +--rw cdid? string 861 | +--rw tsid uint32 862 | +--rw (setup-type)? 863 | +--:(telemetry-config) 864 | | ... 865 | +--:(pipe) 866 | | +--rw total-pipe-capacity* [link-id unit] 867 | | +--rw link-id nt:link-id 868 | | +--rw capacity uint64 869 | | +--rw unit unit 870 | +--:(baseline) 871 | ... 872 +--:(telemetry) {dots-telemetry}? 873 +--rw pre-or-ongoing-mitigation* [cuid tmid] 874 ... 876 Figure 9: Pipe Tree Structure 878 A DOTS client domain pipe is defined as a list of limits of 879 (incoming) traffic volume (total-pipe-capacity") that can be 880 forwarded over ingress interconnection links of a DOTS client domain. 881 Each of these links is identified with a "link-id" [RFC8345]. 883 The unit used by a DOTS client when conveying pipe information is 884 captured in 'unit' attribute. 886 6.2.1. Convey DOTS Client Domain Pipe Capacity 888 Similar considerations to those specified in Section 6.1.2 are 889 followed with one exception: 891 The relative order of two PUT requests carrying DOTS client domain 892 pipe attributes from a DOTS client is determined by comparing 893 their respective 'tsid' values. If such two requests have 894 overlapping "link-id" and "unit", the PUT request with higher 895 numeric 'tsid' value will override the request with a lower 896 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 897 automatically deleted and no longer be available. 899 DOTS clients SHOULD minimize the number of active 'tsids' used for 900 pipe information. Typically, in order to avoid maintaining a long 901 list of 'tsids' for pipe information, it is RECOMMENDED that DOTS 902 clients include in any request to update information related to a 903 given link the information of other links (already communicated using 904 a lower 'tsid' value). Doing so, this update request will override 905 these existing requests and hence optimize the number of 'tsid' 906 request per DOTS client. 908 o Note: This assumes that all link information can fit in one single 909 message. 911 For example, a DOTS client managing a single homed domain (Figure 10) 912 can send a PUT request (shown in Figure 11) to communicate the 913 capacity of "link1" used to connect to its ISP. 915 ,--,--,--. ,--,--,--. 916 ,-' `-. ,-' `-. 917 ( DOTS Client )=====( ISP#A ) 918 `-. Domain ,-' link1 `-. ,-' 919 `--'--'--' `--'--'--' 921 Figure 10: Single Homed DOTS Client Domain 923 Header: PUT (Code=0.03) 924 Uri-Path: ".well-known" 925 Uri-Path: "dots" 926 Uri-Path: "tm-setup" 927 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 928 Uri-Path: "tsid=457" 929 Content-Format: "application/dots+cbor" 931 { 932 "ietf-dots-telemetry:telemetry-setup": { 933 "telemetry": [ 934 { 935 "total-pipe-capacity": [ 936 { 937 "link-id": "link1", 938 "capacity": "500", 939 "unit": "megabit-ps" 940 } 941 ] 942 } 943 ] 944 } 945 } 947 Figure 11: Example of a PUT Request to Convey Pipe Information 948 (Single Homed) 950 DOTS clients may be instructed to signal a link aggregate instead of 951 individual links. For example, a DOTS client managing a DOTS client 952 domain having two interconnection links with an upstream ISP 953 (Figure 12) can send a PUT request (shown in Figure 13) to 954 communicate the aggregate link capacity with its ISP. Signalling 955 individual or aggregate link capacity is deployment-specific. 957 ,--,--,--. ,--,--,--. 958 ,-' `-.===== ,-' `-. 959 ( DOTS Client ) ( ISP#C ) 960 `-. Domain ,-'====== `-. ,-' 961 `--'--'--' `--'--'--' 963 Figure 12: DOTS Client Domain with Two Interconnection Links 965 Header: PUT (Code=0.03) 966 Uri-Path: ".well-known" 967 Uri-Path: "dots" 968 Uri-Path: "tm-setup" 969 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 970 Uri-Path: "tsid=896" 971 Content-Format: "application/dots+cbor" 973 { 974 "ietf-dots-telemetry:telemetry-setup": { 975 "telemetry": [ 976 { 977 "total-pipe-capacity": [ 978 { 979 "link-id": "aggregate", 980 "capacity": "700", 981 "unit": "megabit-ps" 982 } 983 ] 984 } 985 ] 986 } 987 } 989 Figure 13: Example of a PUT Request to Convey Pipe Information 990 (Aggregated Link) 992 Now consider that the DOTS client domain was upgraded to connect to 993 an additional ISP (ISP#B of Figure 14), the DOTS client can inform a 994 third-party DOTS server (that is, not hosted with ISP#A and ISP#B 995 domains) about this update by sending the PUT request depicted in 996 Figure 15. This request also includes information related to "link1" 997 even if that link is not upgraded. Upon receipt of this request, the 998 DOTS server removes the request with 'tsid=457' and updates its 999 configuration base to maintain two links (link#1 and link#2). 1001 ,--,--,--. 1002 ,-' `-. 1003 ( ISP#B ) 1004 `-. ,-' 1005 `--'--'--' 1006 || 1007 || link2 1008 ,--,--,--. ,--,--,--. 1009 ,-' `-. ,-' `-. 1010 ( DOTS Client )=====( ISP#A ) 1011 `-. Domain ,-' link1 `-. ,-' 1012 `--'--'--' `--'--'--' 1014 Figure 14: Multi-Homed DOTS Client Domain 1016 Header: PUT (Code=0.03) 1017 Uri-Path: ".well-known" 1018 Uri-Path: "dots" 1019 Uri-Path: "tm-setup" 1020 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1021 Uri-Path: "tsid=458" 1022 Content-Format: "application/dots+cbor" 1024 { 1025 "ietf-dots-telemetry:telemetry-setup": { 1026 "telemetry": [ 1027 { 1028 "total-pipe-capacity": [ 1029 { 1030 "link-id": "link1", 1031 "capacity": "500", 1032 "unit": "megabit-ps" 1033 }, 1034 { 1035 "link-id": "link2", 1036 "capacity": "500", 1037 "unit": "megabit-ps" 1038 } 1039 ] 1040 } 1041 ] 1042 } 1043 } 1045 Figure 15: Example of a PUT Request to Convey Pipe Information 1046 (Multi-Homed) 1048 A DOTS client can delete a link by sending a PUT request with the 1049 'capacity' attribute set to "0" if other links are still active for 1050 the same DOTS client domain (see Section 6.2.3 for other delete 1051 cases). For example, if a DOTS client domain re-homes (that is, it 1052 changes its ISP), the DOTS client can inform its DOTS server about 1053 this update (e.g., from the network configuration in Figure 10 to the 1054 one shown in Figure 16) by sending the PUT request depicted in 1055 Figure 17. Upon receipt of this request, the DOTS server removes 1056 "link1" from its configuration bases for this DOTS client domain. 1058 ,--,--,--. 1059 ,-' `-. 1060 ( ISP#B ) 1061 `-. ,-' 1062 `--'--'--' 1063 || 1064 || link2 1065 ,--,--,--. 1066 ,-' `-. 1067 ( DOTS Client ) 1068 `-. Domain ,-' 1069 `--'--'--' 1071 Figure 16: Multi-Homed DOTS Client Domain 1073 Header: PUT (Code=0.03) 1074 Uri-Path: ".well-known" 1075 Uri-Path: "dots" 1076 Uri-Path: "tm-setup" 1077 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1078 Uri-Path: "tsid=459" 1079 Content-Format: "application/dots+cbor" 1081 { 1082 "ietf-dots-telemetry:telemetry-setup": { 1083 "telemetry": [ 1084 { 1085 "total-pipe-capacity": [ 1086 { 1087 "link-id": "link1", 1088 "capacity": "0", 1089 "unit": "megabit-ps" 1090 }, 1091 { 1092 "link-id": "link2", 1093 "capacity": "500", 1094 "unit": "megabit-ps" 1095 } 1096 ] 1097 } 1098 ] 1099 } 1100 } 1102 Figure 17: Example of a PUT Request to Convey Pipe Information 1103 (Multi-Homed) 1105 6.2.2. Retrieve Installed DOTS Client Domain Pipe Capacity 1107 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1108 specific installed DOTS client domain pipe related information. The 1109 same procedure as defined in (Section 6.1.3) is followed. 1111 To retrieve all pipe information bound to a DOTS client, the DOTS 1112 client proceeds as specified in Section 6.1.1. 1114 6.2.3. Delete Installed DOTS Client Domain Pipe Capacity 1116 A DELETE request is used to delete the installed DOTS client domain 1117 pipe related information. The same procedure as defined in 1118 (Section 6.1.4) is followed. 1120 6.3. Telemetry Baseline 1122 A DOTS client can communicate to its server(s) its normal traffic 1123 baseline and total connections capacity: 1125 Total Traffic Normal Baseline: The percentile values representing 1126 the total traffic normal baseline. 1128 The traffic normal baseline is represented for a target and is 1129 transport-protocol specific. 1131 If the DOTS client negotiated percentile values and units 1132 (Section 6.1), these negotiated values will be used instead of the 1133 default ones. 1135 Total Connections Capacity: If the target is subjected to resource 1136 consuming DDoS attacks, the following optional attributes for the 1137 target per transport-protocol are useful to detect resource 1138 consuming DDoS attacks: 1140 Total Connections Capacity: 1142 * The maximum number of simultaneous connections that are allowed 1143 to the target. 1144 * The maximum number of simultaneous connections that are allowed 1145 to the target per client. 1146 * The maximum number of simultaneous embryonic connections that 1147 are allowed to the target. The term "embryonic connection" 1148 refers to a connection whose connection handshake is not 1149 finished and embryonic connection is only possible in 1150 connection-oriented transport protocols like TCP or SCTP. 1151 * The maximum number of simultaneous embryonic connections that 1152 are allowed to the target per client. 1153 * The maximum number of connections allowed per second to the 1154 target. 1155 * The maximum number of connections allowed per second to the 1156 target per client. 1157 * The maximum number of requests allowed per second to the 1158 target. 1159 * The maximum number of requests allowed per second to the target 1160 per client. 1161 * The maximum number of partial requests allowed per second to 1162 the target. 1163 * The maximum number of partial requests allowed per second to 1164 the target per client. 1166 The threshold is transport-protocol. 1168 The tree structure of the baseline is shown in Figure 18. 1170 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1171 +--:(telemetry-setup) {dots-telemetry}? 1172 | +--rw telemetry* [cuid tsid] 1173 | +--rw cuid string 1174 | +--rw cdid? string 1175 | +--rw tsid uint32 1176 | +--rw (setup-type)? 1177 | +--:(telemetry-config) 1178 | | ... 1179 | +--:(pipe) 1180 | | ... 1181 | +--:(baseline) 1182 | +--rw baseline* [id] 1183 | +--rw id uint32 1184 | +--rw target-prefix* inet:ip-prefix 1185 | +--rw target-port-range* [lower-port] 1186 | | +--rw lower-port inet:port-number 1187 | | +--rw upper-port? inet:port-number 1188 | +--rw target-protocol* uint8 1189 | +--rw target-fqdn* inet:domain-name 1190 | +--rw target-uri* inet:uri 1191 | +--rw total-traffic-normal-baseline* [unit protocol] 1192 | | +--rw unit unit 1193 | | +--rw protocol uint8 1194 | | +--rw low-percentile-g? yang:gauge64 1195 | | +--rw mid-percentile-g? yang:gauge64 1196 | | +--rw high-percentile-g? yang:gauge64 1197 | | +--rw peak-g? yang:gauge64 1198 | +--rw total-connection-capacity* [protocol] 1199 | +--rw protocol uint8 1200 | +--rw connection? uint64 1201 | +--rw connection-client? uint64 1202 | +--rw embryonic? uint64 1203 | +--rw embryonic-client? uint64 1204 | +--rw connection-ps? uint64 1205 | +--rw connection-client-ps? uint64 1206 | +--rw request-ps? uint64 1207 | +--rw request-client-ps? uint64 1208 | +--rw partial-request-ps? uint64 1209 | +--rw partial-request-client-ps? uint64 1210 +--:(telemetry) {dots-telemetry}? 1211 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1212 ... 1214 Figure 18: Telemetry Baseline Tree Structure 1216 6.3.1. Convey DOTS Client Domain Baseline Information 1218 Similar considerations to those specified in Section 6.1.2 are 1219 followed with one exception: 1221 The relative order of two PUT requests carrying DOTS client domain 1222 baseline attributes from a DOTS client is determined by comparing 1223 their respective 'tsid' values. If such two requests have 1224 overlapping targets, the PUT request with higher numeric 'tsid' 1225 value will override the request with a lower numeric 'tsid' value. 1226 The overlapped lower numeric 'tsid' MUST be automatically deleted 1227 and no longer be available. 1229 Two PUT requests from a DOTS client have overlapping targets if there 1230 is a common IP address, IP prefix, FQDN, or URI. 1232 DOTS clients SHOULD minimize the number of active 'tsids' used for 1233 baseline information. Typically, in order to avoid maintaining a 1234 long list of 'tsids' for baseline information, it is RECOMMENDED that 1235 DOTS clients include in a request to update information related to a 1236 given target, the information of other targets (already communicated 1237 using a lower 'tsid' value) (assuming this fits within one single 1238 datagram). This update request will override these existing requests 1239 and hence optimize the number of 'tsid' request per DOTS client. 1241 If no target clause in included in the request, this is an indication 1242 that the baseline information applies for the DOTS client domain as a 1243 whole. 1245 An example of a PUT request to convey the baseline information is 1246 shown in Figure 19. 1248 Header: PUT (Code=0.03) 1249 Uri-Path: ".well-known" 1250 Uri-Path: "dots" 1251 Uri-Path: "tm-setup" 1252 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1253 Uri-Path: "tsid=126" 1254 Content-Format: "application/dots+cbor" 1256 { 1257 "ietf-dots-telemetry:telemetry": { 1258 { 1259 "ietf-dots-telemetry:telemetry-setup": { 1260 "telemetry": [ 1261 { 1262 "baseline": { 1263 "id": 1, 1264 "target-prefix": [ 1265 "2001:db8:6401::1/128", 1266 "2001:db8:6401::2/128" 1267 ], 1268 "total-traffic-normal-baseline": { 1269 "unit": "megabit-ps", 1270 "protocol": 6, 1271 "peak-g": "50" 1272 } 1273 } 1274 } 1275 ] 1276 } 1277 } 1279 Figure 19: PUT to Convey the DOTS Traffic Baseline 1281 6.3.2. Retrieve Installed Normal Traffic Baseline 1283 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1284 specific installed DOTS client domain baseline traffic information. 1285 The same procedure as defined in (Section 6.1.3) is followed. 1287 To retrieve all baseline information bound to a DOTS client, the DOTS 1288 client proceeds as specified in Section 6.1.1. 1290 6.3.3. Delete Installed Normal Traffic Baseline 1292 A DELETE request is used to delete the installed DOTS client domain 1293 normal traffic baseline. The same procedure as defined in 1294 (Section 6.1.4) is followed. 1296 6.4. Reset Installed Telemetry Setup 1298 Upon bootstrapping (or reboot or any other event that may alter the 1299 DOTS client setup), a DOTS client MAY send a DELETE request to set 1300 the telemetry parameters to default values. Such a request does not 1301 include any 'tsid'. An example of such request is depicted in 1302 Figure 20. 1304 Header: DELETE (Code=0.04) 1305 Uri-Path: ".well-known" 1306 Uri-Path: "dots" 1307 Uri-Path: "tm-setup" 1308 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1310 Figure 20: Delete Telemetry Configuration 1312 6.5. Conflict with Other DOTS Clients of the Same Domain 1314 A DOTS server may detect conflicts between requests to convey pipe 1315 and baseline information received from DOTS clients of the same DOTS 1316 client domain. 'conflict-information' is used to report the conflict 1317 to the DOTS client following similar conflict handling discussed in 1318 Section 4.4.1 of [I-D.ietf-dots-signal-channel]. The conflict cause 1319 can be set to one of these values: 1321 1: Overlapping targets (already defined in 1322 [I-D.ietf-dots-signal-channel]). 1324 TBA: Overlapping pipe scope (see Section 11). 1326 7. DOTS Pre-or-Ongoing Mitigation Telemetry 1328 There are two broad types of DDoS attacks, one is bandwidth consuming 1329 attack, the other is target resource consuming attack. This section 1330 outlines the set of DOTS telemetry attributes (Section 7.1) that 1331 covers both the types of attacks. The ultimate objective of these 1332 attributes is to allow for the complete knowledge of attacks and the 1333 various particulars that can best characterize attacks. 1335 The "ietf-dots-telemetry" YANG module (Section 9) augments the "ietf- 1336 dots-signal" with a new message type called "telemetry". The tree 1337 structure of the "telemetry" message type is shown Figure 23. 1339 The pre-or-ongoing-mitigation telemetry attributes are indicated by 1340 the path-suffix '/tm'. The '/tm' is appended to the path-prefix to 1341 form the URI used with a CoAP request to signal the DOTS telemetry. 1342 Pre-or-ongoing-mitigation telemetry attributes specified in 1343 Section 7.1 can be signaled between DOTS agents. 1345 Pre-or-ongoing-mitigation telemetry attributes may be sent by a DOTS 1346 client or a DOTS server. 1348 DOTS agents SHOULD bind pre-or-ongoing-mitigation telemetry data with 1349 mitigation requests relying upon the target clause. In particular, a 1350 telemetry PUT request sent after a mitigation request may include a 1351 reference to that mitigation request ('mid-list') as shown in 1352 Figure 21. An example illustrating requests correlation by means of 1353 'target-prefix' is shown in Figure 22. 1355 When generating telemetry data to send to a peer, the DOTS agent must 1356 auto-scale so that appropriate unit(s) are used. 1358 +-----------+ +-----------+ 1359 |DOTS client| |DOTS server| 1360 +-----------+ +-----------+ 1361 | | 1362 |=========Mitigation Request (mid)=====================>| 1363 | | 1364 |================ Telemetry (mid-list{mid})============>| 1365 | | 1367 Figure 21: Example of Request Correlation using 'mid' 1369 +-----------+ +-----------+ 1370 |DOTS client| |DOTS server| 1371 +-----------+ +-----------+ 1372 | | 1373 |<=============== Telemetry (target-prefix)=============| 1374 | | 1375 |=========Mitigation Request (target-prefix)===========>| 1376 | | 1378 Figure 22: Example of Request Correlation using Target Prefix 1380 DOTS agents MUST NOT send pre-or-ongoing-mitigation telemetry 1381 messages to the same peer more frequently than once every 'telemetry- 1382 notify-interval' (Section 6.1). 1384 DOTS pre-or-ongoing-mitigation telemetry request and response 1385 messages MUST be marked as Non-Confirmable messages. 1387 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1388 +--:(telemetry-setup) {dots-telemetry}? 1389 | +--rw telemetry* [cuid tsid] 1390 | ... 1391 +--:(telemetry) {dots-telemetry}? 1392 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1393 +--rw cuid string 1394 +--rw cdid? string 1395 +--rw tmid uint32 1396 +--rw target 1397 | ... 1398 +--rw total-traffic* [unit protocol] 1399 | ... 1400 +--rw total-attack-traffic* [unit protocol] 1401 | ... 1402 +--rw total-attack-connection 1403 | ... 1404 +--rw attack-detail 1405 ... 1407 Figure 23: Telemetry Message Type Tree Structure 1409 7.1. Pre-or-Ongoing-Mitigation DOTS Telemetry Attributes 1411 The description and motivation behind each attribute are presented in 1412 Section 3. DOTS telemetry attributes are optionally signaled and 1413 therefore MUST NOT be treated as mandatory fields in the DOTS signal 1414 channel protocol. 1416 7.1.1. Target 1418 A target resource (Figure 24) is identified using the attributes 1419 'target-prefix', 'target-port-range', 'target-protocol', 'target- 1420 fqdn', 'target-uri', or 'alias-name' defined in the base DOTS signal 1421 channel protocol. 1423 +--:(telemetry) {dots-telemetry}? 1424 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1425 +--rw cuid string 1426 +--rw cdid? string 1427 +--rw tmid uint32 1428 +--rw target 1429 | +--rw target-prefix* inet:ip-prefix 1430 | +--rw target-port-range* [lower-port] 1431 | | +--rw lower-port inet:port-number 1432 | | +--rw upper-port? inet:port-number 1433 | +--rw target-protocol* uint8 1434 | +--rw target-fqdn* inet:domain-name 1435 | +--rw target-uri* inet:uri 1436 | +--rw alias-name* string 1437 | +--rw mid-list* uint32 1438 +--rw total-traffic* [unit protocol] 1439 | ... 1440 +--rw total-attack-traffic* [unit protocol] 1441 | ... 1442 +--rw total-attack-connection 1443 | ... 1444 +--rw attack-detail 1445 ... 1447 Figure 24: Target Tree Structure 1449 At least one of the attributes 'target-prefix', 'target-fqdn', 1450 'target-uri', 'alias-name', or 'mid-list' MUST be present in the 1451 target definition. 1453 If the target is subjected to bandwidth consuming attack, the 1454 attributes representing the percentile values of the 'attack-id' 1455 attack traffic are included. 1457 If the target is subjected to resource consuming DDoS attacks, the 1458 same attributes defined for Section 7.1.4 are applicable for 1459 representing the attack. 1461 This is an optional sub-attribute. 1463 7.1.2. Total Traffic 1465 This attribute (Figure 25) conveys the percentile values of total 1466 traffic observed during a DDoS attack. 1468 The total traffic is represented for a target and is transport- 1469 protocol specific. 1471 +--:(telemetry) {dots-telemetry}? 1472 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1473 +--rw cuid string 1474 +--rw cdid? string 1475 +--rw tmid uint32 1476 +--rw target 1477 | ... 1478 +--rw total-traffic* [unit protocol] 1479 | +--rw unit unit 1480 | +--rw protocol uint8 1481 | +--rw low-percentile-g? yang:gauge64 1482 | +--rw mid-percentile-g? yang:gauge64 1483 | +--rw high-percentile-g? yang:gauge64 1484 | +--rw peak-g? yang:gauge64 1485 +--rw total-attack-traffic* [unit protocol] 1486 | ... 1487 +--rw total-attack-connection 1488 | ... 1489 +--rw attack-detail 1490 ... 1492 Figure 25: Total Traffic Tree Structure 1494 7.1.3. Total Attack Traffic 1496 This attribute (Figure 26) conveys the total attack traffic 1497 identified by the DOTS client domain's DMS (or DDoS Detector). 1499 The total attack traffic is represented for a target and is 1500 transport-protocol specific. 1502 +--:(telemetry) {dots-telemetry}? 1503 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1504 +--rw cuid string 1505 +--rw cdid? string 1506 +--rw tmid uint32 1507 +--rw target 1508 | ... 1509 +--rw total-traffic* [unit protocol] 1510 | ... 1511 +--rw total-attack-traffic* [unit protocol] 1512 | +--rw unit unit 1513 | +--rw protocol uint8 1514 | +--rw low-percentile-g? yang:gauge64 1515 | +--rw mid-percentile-g? yang:gauge64 1516 | +--rw high-percentile-g? yang:gauge64 1517 | +--rw peak-g? yang:gauge64 1518 +--rw total-attack-connection 1519 | ... 1520 +--rw attack-detail 1521 ... 1523 Figure 26: Total Attack Traffic Tree Structure 1525 7.1.4. Total Attack Connections 1527 If the target is subjected to resource consuming DDoS attack, this 1528 attribute is used to convey the percentile values of total attack 1529 connections. The following optional sub-attributes for the target 1530 per transport-protocol are included to represent the attack 1531 characteristics: 1533 o The number of simultaneous attack connections to the target. 1534 o The number of simultaneous embryonic connections to the target. 1535 o The number of attack connections per second to the target. 1536 o The number of attack requests to the target. 1538 +--:(telemetry) {dots-telemetry}? 1539 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1540 +--rw cuid string 1541 +--rw cdid? string 1542 +--rw tmid uint32 1543 +--rw target 1544 | ... 1545 +--rw total-traffic* [unit protocol] 1546 | ... 1547 +--rw total-attack-traffic* [unit protocol] 1548 | ... 1549 +--rw total-attack-connection 1550 | +--rw low-percentile-l* [protocol] 1551 | | +--rw protocol uint8 1552 | | +--rw connection? yang:gauge64 1553 | | +--rw embryonic? yang:gauge64 1554 | | +--rw connection-ps? yang:gauge64 1555 | | +--rw request-ps? yang:gauge64 1556 | | +--rw partial-request-ps? yang:gauge64 1557 | +--rw mid-percentile-l* [protocol] 1558 | | +--rw protocol uint8 1559 | | +--rw connection? yang:gauge64 1560 | | +--rw embryonic? yang:gauge64 1561 | | +--rw connection-ps? yang:gauge64 1562 | | +--rw request-ps? yang:gauge64 1563 | | +--rw partial-request-ps? yang:gauge64 1564 | +--rw high-percentile-l* [protocol] 1565 | | +--rw protocol uint8 1566 | | +--rw connection? yang:gauge64 1567 | | +--rw embryonic? yang:gauge64 1568 | | +--rw connection-ps? yang:gauge64 1569 | | +--rw request-ps? yang:gauge64 1570 | | +--rw partial-request-ps? yang:gauge64 1571 | +--rw peak-l* [protocol] 1572 | +--rw protocol uint8 1573 | +--rw connection? yang:gauge64 1574 | +--rw embryonic? yang:gauge64 1575 | +--rw connection-ps? yang:gauge64 1576 | +--rw request-ps? yang:gauge64 1577 | +--rw partial-request-ps? yang:gauge64 1578 +--rw attack-detail 1579 ... 1581 Figure 27: Total Attack Connections Tree Structure 1583 7.1.5. Attack Details 1585 This attribute (Figure 28) is used to signal a set of details 1586 characterizing an attack. The following optional sub-attributes 1587 describing the on-going attack can be signal as attack details. 1589 id: Vendor ID is a security vendor's Enterprise Number as registered 1590 with IANA [Enterprise-Numbers]. It is a four-byte integer value. 1592 attack-id: Unique identifier assigned by the vendor for the attack. 1594 attack-name: Textual representation of attack description. Natural 1595 Language Processing techniques (e.g., word embedding) can possibly 1596 be used to map the attack description to an attack type. Textual 1597 representation of attack solves two problems: (a) avoids the need 1598 to create mapping tables manually between vendors and (2) avoids 1599 the need to standardize attack types which keep evolving. 1601 attack-severity: Attack severity. These values are supported: 1602 Emergency (1), critical (2), and alert (3). 1604 start-time: The time the attack started. The attack's start time is 1605 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1606 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1607 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1609 end-time: The time the attack-id attack ended. The attack end time 1610 is expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1611 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1612 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1614 source-count: A count of sources involved in the attack targeting 1615 the victim. 1617 top-talkers: A list of top talkers among attack sources. The top 1618 talkers are represented using the 'source-prefix'. 1620 'spoofed-status' is used whether a top talker is a spoofed IP 1621 address (e.g., reflection attacks) or not. 1623 If the target is subjected to bandwidth consuming attack, the 1624 attack traffic from each of the top talkers is included ('total- 1625 attack-traffic', Section 7.1.3). 1627 If the target is subjected to resource consuming DDoS attacks, the 1628 same attributes defined for Section 7.1.4 are applicable for 1629 representing the attack per talker. 1631 +--:(telemetry) {dots-telemetry}? 1632 +--rw pre-or-ongoing-mitigation* [cuid tmid] 1633 +--rw cuid string 1634 +--rw cdid? string 1635 +--rw tmid uint32 1636 +--rw target 1637 | ... 1638 +--rw total-traffic* [unit protocol] 1639 | ... 1640 +--rw total-attack-traffic* [unit protocol] 1641 | ... 1642 +--rw total-attack-connection 1643 | ... 1644 +--rw attack-detail 1645 +--rw id? uint32 1646 +--rw attack-id? string 1647 +--rw attack-name? string 1648 +--rw attack-severity? attack-severity 1649 +--rw start-time? uint64 1650 +--rw end-time? uint64 1651 +--rw source-count 1652 | +--rw low-percentile-g? yang:gauge64 1653 | +--rw mid-percentile-g? yang:gauge64 1654 | +--rw high-percentile-g? yang:gauge64 1655 | +--rw peak-g? yang:gauge64 1656 +--rw top-talker 1657 +--rw talker* [source-prefix] 1658 +--rw spoofed-status? boolean 1659 +--rw source-prefix inet:ip-prefix 1660 +--rw source-port-range* [lower-port] 1661 | +--rw lower-port inet:port-number 1662 | +--rw upper-port? inet:port-number 1663 +--rw source-icmp-type-range* [lower-type] 1664 | +--rw lower-type uint8 1665 | +--rw upper-type? uint8 1666 +--rw total-attack-traffic* [unit] 1667 | +--rw unit unit 1668 | +--rw low-percentile-g? yang:gauge64 1669 | +--rw mid-percentile-g? yang:gauge64 1670 | +--rw high-percentile-g? yang:gauge64 1671 | +--rw peak-g? yang:gauge64 1672 +--rw total-attack-connection 1673 +--rw low-percentile-l* [protocol] 1674 | ... 1675 +--rw mid-percentile-l* [protocol] 1676 | ... 1677 +--rw high-percentile-l* [protocol] 1678 | ... 1680 +--rw peak-l* [protocol] 1681 ... 1683 Figure 28: Attack Detail Tree Structure 1685 7.2. From DOTS Clients to DOTS Servers 1687 DOTS clients uses PUT request to signal pre-or-ongoing-mitigation 1688 telemetry to DOTS servers. An example of such request is shown in 1689 Figure 29. 1691 Header: PUT (Code=0.03) 1692 Uri-Path: ".well-known" 1693 Uri-Path: "dots" 1694 Uri-Path: "tm" 1695 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1696 Uri-Path: "tmid=123" 1697 Content-Format: "application/dots+cbor" 1699 { 1700 "ietf-dots-telemetry:telemetry": { 1701 "pre-or-ongoing-mitigation": { 1702 "target": { 1703 { 1704 "target-prefix": [ 1705 "2001:db8::1/128" 1706 ] 1707 "total-attack-traffic": [ 1708 { 1709 "protocol": 17, 1710 "unit": "megabit-ps", 1711 "mid-percentile-g": "900" 1712 } 1713 ], 1714 "attack-detail": { 1715 "start-time": "1957811234", 1716 "attack-severity": "emergency" 1717 } 1718 } 1719 } 1720 } 1721 } 1722 } 1724 Figure 29: PUT to Send Pre-or-Ongoing-Mitigation Telemetry 1726 'cuid' is a mandatory Uri-Path parameter for PUT requests. 1728 The following additional Uri-Path parameter is defined: 1730 tmid: Telemetry Identifier is an identifier for the DOTS pre-or- 1731 ongoing-mitigation telemetry data represented as an integer. 1732 This identifier MUST be generated by DOTS clients. 'tsid' values 1733 MUST increase monotonically (when a new PUT is generated by a 1734 DOTS client to convey pre-or-ongoing-mitigation telemetry). 1736 This is a mandatory attribute. 1738 At least 'target' attribute and another pre-or-ongoing-mitigation 1739 attributes (Section 7.1) MUST be present in the PUT request. If only 1740 the 'target' attribute is present, this request is handled as per 1741 Section 7.3. 1743 The relative order of two PUT requests carrying DOTS pre-or-ongoing- 1744 mitigation telemetry from a DOTS client is determined by comparing 1745 their respective 'tmid' values. If such two requests have 1746 overlapping 'target', the PUT request with higher numeric 'tmid' 1747 value will override the request with a lower numeric 'tmid' value. 1748 The overlapped lower numeric 'tmid' MUST be automatically deleted and 1749 no longer be available. 1751 The DOTS server indicates the result of processing a PUT request 1752 using CoAP response codes. The response code 2.04 (Changed) is 1753 returned if the DOTS server has accepted the pre-or-ongoing- 1754 mitigation telemetry. The error response code 5.03 (Service 1755 Unavailable) is returned if the DOTS server has erred. 5.03 uses Max- 1756 Age option to indicate the number of seconds after which to retry. 1758 How long a DOTS server maintains a 'tmid' as active or logs the 1759 enclosed telemetry information is implementation-specific. Note that 1760 if a 'tmid' is still active, then logging details are updated by the 1761 DOTS server as a function of the updates received from the peer DOTS 1762 client. 1764 A DOTS client that lost the state of its active 'tmids' or has to set 1765 'tmid' back to zero (e.g., crash or restart) MUST send a GET request 1766 to the DOTS server to retrieve the list of active 'tmid'. The DOTS 1767 client may then delete 'tmids' that should not be active anymore. 1769 7.3. From DOTS Servers to DOTS Clients 1771 The pre-or-ongoing-mitigation (attack details, in particular) can 1772 also be signaled from DOTS servers to DOTS clients. For example, the 1773 DOTS server co-located with a DDoS detector collects monitoring 1774 information from the target network, identifies DDoS attack using 1775 statistical analysis or deep learning techniques, and signals the 1776 attack details to the DOTS client. 1778 The DOTS client can use the attack details to decide whether to 1779 trigger a DOTS mitigation request or not. Furthermore, the security 1780 operation personnel at the DOTS client domain can use the attack 1781 details to determine the protection strategy and select the 1782 appropriate DOTS server for mitigating the attack. 1784 In order to receive pre-or-ongoing-mitigation telemetry notifications 1785 from a DOTS server, a DOTS client MUST send a PUT (followed by a GET) 1786 with the target filter. An example of such PUT request is shown in 1787 Figure 30. In order to avoid maintaining a long list of such 1788 requests, it is RECOMMENDED that DOTS clients include all targets in 1789 the same request. DOTS servers may be instructed to restrict the 1790 number of pre-or-ongoing-mitigation requests per DOTS client domain. 1792 Header: PUT (Code=0.03) 1793 Uri-Path: ".well-known" 1794 Uri-Path: "dots" 1795 Uri-Path: "tm" 1796 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1797 Uri-Path: "tmid=123" 1798 Content-Format: "application/dots+cbor" 1800 { 1801 "ietf-dots-telemetry:telemetry": { 1802 "pre-or-ongoing-mitigation": { 1803 "target": { 1804 { 1805 "target-prefix": [ 1806 "2001:db8::/32" 1807 ] 1808 } 1809 } 1810 } 1811 } 1812 } 1814 Figure 30: PUT to Request Pre-or-Ongoing-Mitigation Telemetry 1816 DOTS clients of the same domain can request to receive pre-or- 1817 ongoing-mitigation telemetry bound to the same target. 1819 The DOTS client conveys the Observe Option set to '0' in the GET 1820 request to receive asynchronous notifications carrying pre-or- 1821 ongoing-mitigation telemetry data from the DOTS server. The GET 1822 request specify a 'tmid' (Figure 31) or not (Figure 32). 1824 Header: GET (Code=0.01) 1825 Uri-Path: ".well-known" 1826 Uri-Path: "dots" 1827 Uri-Path: "tm" 1828 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1829 Uri-Path: "tmid=123" 1830 Observe: 0 1832 Figure 31: GET to Subscribe to Telemetry Asynchronous Notifications 1833 for a Specific 'tmid' 1835 Header: GET (Code=0.01) 1836 Uri-Path: ".well-known" 1837 Uri-Path: "dots" 1838 Uri-Path: "tm" 1839 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1840 Observe: 0 1842 Figure 32: GET to Subscribe to Telemetry Asynchronous Notifications 1843 for All 'tmids' 1845 The DOTS server will send asynchronous notifications to the DOTS 1846 client when an event if following similar considerations as in 1847 Section 4.4.2.1 of [I-D.ietf-dots-signal-channel]. An example of a 1848 pre-or-ongoing-mitigation telemetry notification is shown in 1849 Figure 33. 1851 { 1852 "ietf-dots-telemetry:telemetry": { 1853 "pre-or-ongoing-mitigation": { 1854 "target": { 1855 { 1856 "tmid": 123, 1857 "target-prefix": [ 1858 "2001:db8::1/128" 1859 ] 1860 "total-attack-traffic": [ 1861 { 1862 "protocol": 17, 1863 "unit": "megabit-ps", 1864 "mid-percentile-g": "900" 1865 } 1866 ], 1867 "attack-detail": { 1868 "start-time": "1957818434", 1869 "attack-severity": "emergency" 1870 } 1871 } 1872 } 1873 } 1874 } 1875 } 1877 Figure 33: Message Body of a Pre-or-Ongoing-Mitigation Telemetry 1878 Notification from the DOTS Server 1880 A DOTS server may aggregate pre-or-ongoing-mitigation data (e.g., 1881 'top-talkers') for all targets of a domain, or when justified, send 1882 specific information (e.g., 'top-talkers') per individual targets. 1884 The DOTS client may log pre-or-ongoing-mitigation telemetry data with 1885 an alert sent to an administrator or a network controller. The DOTS 1886 client may send a mitigation request if the attack cannot be handled 1887 locally. 1889 8. DOTS Telemetry Mitigation Status Update 1891 8.1. DOTS Clients to Servers Mitigation Efficacy DOTS Telemetry 1892 Attributes 1894 The mitigation efficacy telemetry attributes can be signaled from 1895 DOTS clients to DOTS servers as part of the periodic mitigation 1896 efficacy updates to the server (Section 5.3.4 of 1897 [I-D.ietf-dots-signal-channel]). 1899 Total Attack Traffic: The overall attack traffic as observed from 1900 the DOTS client perspective during an active mitigation. See 1901 Figure 26. 1903 Attack Details: The overall attack details as observed from the 1904 DOTS client perspective during an active mitigation. See 1905 Section 7.1.5. 1907 The "ietf-dots-telemetry" YANG module augments the "mitigation-scope" 1908 type message defined in "ietf-dots-signal" so that these attributes 1909 can be signalled by a DOTS client in a mitigation efficacy update 1910 (Figure 34). 1912 augment /ietf-signal:dots-signal/ietf-signal:message-type 1913 /ietf-signal:mitigation-scope/ietf-signal:scope: 1914 +--rw total-attack-traffic* [unit] {dots-telemetry}? 1915 | ... 1916 +--rw attack-detail {dots-telemetry}? 1917 +--rw id? uint32 1918 +--rw attack-id? string 1919 +--rw attack-name? string 1920 +--rw attack-severity? attack-severity 1921 +--rw start-time? uint64 1922 +--rw end-time? uint64 1923 +--rw source-count 1924 | ... 1925 +--rw top-talker 1926 ... 1928 Figure 34: Telemetry Efficacy Update Tree Structure 1930 In order to signal telemetry data in a mitigation efficacy update, it 1931 is RECOMMENDED that the DOTS client has already established a DOTS 1932 telemetry setup session with the server in 'idle' time. 1934 Header: PUT (Code=0.03) 1935 Uri-Path: ".well-known" 1936 Uri-Path: "dots" 1937 Uri-Path: "mitigate" 1938 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1939 Uri-Path: "mid=123" 1940 If-Match: 1941 Content-Format: "application/dots+cbor" 1943 { 1944 "ietf-dots-signal-channel:mitigation-scope": { 1945 "scope": [ 1946 { 1947 "alias-name": [ 1948 "myserver" 1949 ], 1950 "attack-status": "under-attack", 1951 "ietf-dots-telemetry:total-attack-traffic": [ 1952 { 1953 "ietf-dots-telemetry:unit": "megabit-ps", 1954 "ietf-dots-telemetry:mid-percentile-g": "900" 1955 } 1956 ] 1957 } 1958 ] 1959 } 1960 } 1962 Figure 35: An Example of Mitigation Efficacy Update with Telemetry 1963 Attributes 1965 8.2. DOTS Servers to Clients Mitigation Status DOTS Telemetry 1966 Attributes 1968 The mitigation status telemetry attributes can be signaled from the 1969 DOTS server to the DOTS client as part of the periodic mitigation 1970 status update (Section 5.3.3 of [I-D.ietf-dots-signal-channel]). In 1971 particular, DOTS clients can receive asynchronous notifications of 1972 the attack details from DOTS servers using the Observe option defined 1973 in [RFC7641]. 1975 In order to make use of this feature, DOTS clients MUST establish a 1976 telemetry setup session with the DOTS server in 'idle' time and MUST 1977 set the 'server-originated-telemetry' attribute to 'true'. 1979 DOTS servers MUST NOT include telemetry attributes in mitigation 1980 status updates sent to DOTS clients for which 'server-originated- 1981 telemetry' attribute is set to 'false'. 1983 As defined in [RFC8612], the actual mitigation activities can include 1984 several countermeasure mechanisms. The DOTS server signals the 1985 current operational status to each relevant countermeasure. A list 1986 of attacks detected by each countermeasure MAY also be included. The 1987 same attributes defined for Section 7.1.5 are applicable for 1988 describing the attacks detected and mitigated. 1990 The "ietf-dots-telemetry" YANG module (Section 9) augments the 1991 "mitigation-scope" type message defined in "ietf-dots-signal" with 1992 telemetry data as depicted in following tree structure: 1994 augment /ietf-signal:dots-signal/ietf-signal:message-type 1995 /ietf-signal:mitigation-scope/ietf-signal:scope: 1996 +--ro total-traffic* [unit protocol] {dots-telemetry}? 1997 | +--ro unit unit 1998 | +--ro protocol uint8 1999 | +--ro low-percentile-g? yang:gauge64 2000 | +--ro mid-percentile-g? yang:gauge64 2001 | +--ro high-percentile-g? yang:gauge64 2002 | +--ro peak-g? yang:gauge64 2003 +--rw total-attack-traffic* [unit] {dots-telemetry}? 2004 | +--rw unit unit 2005 | +--rw low-percentile-g? yang:gauge64 2006 | +--rw mid-percentile-g? yang:gauge64 2007 | +--rw high-percentile-g? yang:gauge64 2008 | +--rw peak-g? yang:gauge64 2009 +--ro total-attack-connection {dots-telemetry}? 2010 | +--ro low-percentile-c 2011 | | +--ro connection? yang:gauge64 2012 | | +--ro embryonic? yang:gauge64 2013 | | +--ro connection-ps? yang:gauge64 2014 | | +--ro request-ps? yang:gauge64 2015 | | +--ro partial-request-ps? yang:gauge64 2016 | +--ro mid-percentile-c 2017 | | ... 2018 | +--ro high-percentile-c 2019 | | ... 2020 | +--ro peak-c 2021 | ... 2022 +--rw attack-detail {dots-telemetry}? 2023 +--rw id? uint32 2024 +--rw attack-id? string 2025 +--rw attack-name? string 2026 +--rw attack-severity? attack-severity 2027 +--rw start-time? uint64 2028 +--rw end-time? uint64 2029 +--rw source-count 2030 | +--rw low-percentile-g? yang:gauge64 2031 | +--rw mid-percentile-g? yang:gauge64 2032 | +--rw high-percentile-g? yang:gauge64 2033 | +--rw peak-g? yang:gauge64 2034 +--rw top-talker 2035 +--rw talker* [source-prefix] 2036 +--rw spoofed-status? boolean 2037 +--rw source-prefix inet:ip-prefix 2038 +--rw source-port-range* [lower-port] 2039 | +--rw lower-port inet:port-number 2040 | +--rw upper-port? inet:port-number 2041 +--rw source-icmp-type-range* [lower-type] 2042 | +--rw lower-type uint8 2043 | +--rw upper-type? uint8 2044 +--rw total-attack-traffic* [unit] 2045 | +--rw unit unit 2046 | +--rw low-percentile-g? yang:gauge64 2047 | +--rw mid-percentile-g? yang:gauge64 2048 | +--rw high-percentile-g? yang:gauge64 2049 | +--rw peak-g? yang:gauge64 2050 +--rw total-attack-connection 2051 +--rw low-percentile-c 2052 | +--rw connection? yang:gauge64 2053 | +--rw embryonic? yang:gauge64 2054 | +--rw connection-ps? yang:gauge64 2055 | +--rw request-ps? yang:gauge64 2056 | +--rw partial-request-ps? yang:gauge64 2057 +--rw mid-percentile-c 2058 | ... 2059 +--rw high-percentile-c 2060 | ... 2061 +--rw peak-c 2062 ... 2064 Figure 36 shows an example of an asynchronous notification of attack 2065 mitigation status from the DOTS server. This notification signals 2066 both the mid-percentile value of processed attack traffic and the 2067 peak percentile value of unique sources involved in the attack. 2069 { 2070 "ietf-dots-signal-channel:mitigation-scope": { 2071 "scope": [ 2072 { 2073 "mid": 12332, 2074 "mitigation-start": "1507818434", 2075 "alias-name": [ 2076 "myserver" 2077 ], 2078 "lifetime": 1600, 2079 "status": "attack-successfully-mitigated", 2080 "bytes-dropped": "134334555", 2081 "bps-dropped": "43344", 2082 "pkts-dropped": "333334444", 2083 "pps-dropped": "432432", 2084 "ietf-dots-telemetry:total-attack-traffic": [ 2085 { 2086 "ietf-dots-telemetry:unit": "megabit-ps", 2087 "ietf-dots-telemetry:mid-percentile-g": "900" 2088 } 2089 ], 2090 "ietf-dots-telemetry::attack-detail": { 2091 "ietf-dots-telemetry:source-count": { 2092 "ietf-dots-telemetry:peak-g": "10000" 2093 } 2094 } 2095 } 2096 ] 2097 } 2098 } 2100 Figure 36: Response Body of a Mitigation Status With Telemetry 2101 Attributes 2103 9. YANG Module 2105 This module uses types defined in [RFC6991] and [RFC8345]. 2107 file "ietf-dots-telemetry@2020-03-27.yang" 2108 module ietf-dots-telemetry { 2109 yang-version 1.1; 2110 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 2111 prefix dots-telemetry; 2113 import ietf-dots-signal-channel { 2114 prefix ietf-signal; 2115 reference 2116 "RFC SSSS: Distributed Denial-of-Service Open Threat 2117 Signaling (DOTS) Signal Channel Specification"; 2118 } 2119 import ietf-dots-data-channel { 2120 prefix ietf-data; 2121 reference 2122 "RFC DDDD: Distributed Denial-of-Service Open Threat 2123 Signaling (DOTS) Data Channel Specification"; 2124 } 2125 import ietf-yang-types { 2126 prefix yang; 2127 reference 2128 "Section 3 of RFC 6991"; 2129 } 2130 import ietf-inet-types { 2131 prefix inet; 2132 reference 2133 "Section 4 of RFC 6991"; 2134 } 2135 import ietf-network-topology { 2136 prefix nt; 2137 reference 2138 "Section 6.2 of RFC 8345: A YANG Data Model for Network 2139 Topologies"; 2140 } 2142 organization 2143 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2144 contact 2145 "WG Web: 2146 WG List: 2148 Author: Mohamed Boucadair 2149 2151 Author: Konda, Tirumaleswar Reddy 2152 "; 2153 description 2154 "This module contains YANG definitions for the signaling 2155 of DOTS telemetry exchanged between a DOTS client and 2156 a DOTS server, by means of the DOTS signal channel. 2158 Copyright (c) 2020 IETF Trust and the persons identified as 2159 authors of the code. All rights reserved. 2161 Redistribution and use in source and binary forms, with or 2162 without modification, is permitted pursuant to, and subject 2163 to the license terms contained in, the Simplified BSD License 2164 set forth in Section 4.c of the IETF Trust's Legal Provisions 2165 Relating to IETF Documents 2166 (http://trustee.ietf.org/license-info). 2168 This version of this YANG module is part of RFC XXXX; see 2169 the RFC itself for full legal notices."; 2171 revision 2020-03-27 { 2172 description 2173 "Initial revision."; 2174 reference 2175 "RFC XXXX: Distributed Denial-of-Service Open Threat 2176 Signaling (DOTS) Telemetry"; 2177 } 2179 feature dots-telemetry { 2180 description 2181 "This feature means that the DOTS signal channel is able 2182 to convey DOTS telemetry data between DOTS clients and 2183 servers."; 2184 } 2186 typedef attack-severity { 2187 type enumeration { 2188 enum emergency { 2189 value 1; 2190 description 2191 "The attack is severe: emergency."; 2192 } 2193 enum critical { 2194 value 2; 2195 description 2196 "The attack is critical."; 2197 } 2198 enum alert { 2199 value 3; 2200 description 2201 "This is an alert."; 2202 } 2203 } 2204 description 2205 "Enumeration for attack severity."; 2206 } 2208 typedef unit-type { 2209 type enumeration { 2210 enum packet-ps { 2211 value 1; 2212 description 2213 "Packets per second (PPS)."; 2214 } 2215 enum bit-ps { 2216 value 3; 2217 description 2218 "Bit per Second (BPS)."; 2219 } 2220 enum byte-ps { 2221 value 4; 2222 description 2223 "Kilobyte per second."; 2224 } 2225 } 2226 description 2227 "Enumeration to indicate which unit type is used."; 2228 } 2230 typedef unit { 2231 type enumeration { 2232 enum packet-ps { 2233 value 1; 2234 description 2235 "Packets per second (PPS)."; 2236 } 2237 enum kilopacket-ps { 2238 value 2; 2239 description 2240 "Kilo packets per second (Kpps)."; 2241 } 2242 enum bit-ps { 2243 value 3; 2244 description 2245 "Bit per Second (BPS)."; 2246 } 2247 enum byte-ps { 2248 value 4; 2249 description 2250 "Kilobyte per second."; 2251 } 2252 enum kilobyte-ps { 2253 value 5; 2254 description 2255 "Kilobyte per second."; 2256 } 2257 enum megabit-ps { 2258 value 6; 2259 description 2260 "Megabit per second."; 2262 } 2263 enum megabyte-ps { 2264 value 7; 2265 description 2266 "Megabyte per second."; 2267 } 2268 enum gigabit-ps { 2269 value 8; 2270 description 2271 "Gigabit per second."; 2272 } 2273 enum gigabyte-ps { 2274 value 9; 2275 description 2276 "Gigabyte per second."; 2277 } 2278 enum terabit-ps { 2279 value 10; 2280 description 2281 "Terabit per second."; 2282 } 2283 enum terabyte-ps { 2284 value 11; 2285 description 2286 "Terabyte per second."; 2287 } 2288 } 2289 description 2290 "Enumeration to indicate which unit is used."; 2291 } 2293 typedef interval { 2294 type enumeration { 2295 enum hour { 2296 value 1; 2297 description 2298 "Hour."; 2299 } 2300 enum day { 2301 value 2; 2302 description 2303 "Day."; 2304 } 2305 enum week { 2306 value 3; 2307 description 2308 "Week."; 2309 } 2310 enum month { 2311 value 4; 2312 description 2313 "Month."; 2314 } 2315 } 2316 description 2317 "Enumeration to indicate the overall measurement period."; 2318 } 2320 typedef sample { 2321 type enumeration { 2322 enum second { 2323 value 1; 2324 description 2325 "Second."; 2326 } 2327 enum 5-seconds { 2328 value 2; 2329 description 2330 "5 seconds."; 2331 } 2332 enum 30-seconds { 2333 value 3; 2334 description 2335 "30 seconds."; 2336 } 2337 enum minute { 2338 value 4; 2339 description 2340 "One minute."; 2341 } 2342 enum 5-minutes { 2343 value 5; 2344 description 2345 "5 minutes."; 2346 } 2347 enum 10-minutes { 2348 value 6; 2349 description 2350 "10 minutes."; 2351 } 2352 enum 30-minutes { 2353 value 7; 2354 description 2355 "30 minutes."; 2356 } 2357 enum hour { 2358 value 8; 2359 description 2360 "One hour."; 2361 } 2362 } 2363 description 2364 "Enumeration to indicate the measurement perdiod."; 2365 } 2367 typedef percentile { 2368 type decimal64 { 2369 fraction-digits 2; 2370 } 2371 description 2372 "The nth percentile of a set of data is the 2373 value at which n percent of the data is below it."; 2374 } 2376 grouping percentile-config { 2377 description 2378 "Configuration of low, mid, and high percentile values."; 2379 leaf measurement-interval { 2380 type interval; 2381 description 2382 "Defines the period on which percentiles are computed."; 2383 } 2384 leaf measurement-sample { 2385 type sample; 2386 description 2387 "Defines the time distribution for measuring 2388 values that are used to compute percentiles.."; 2389 } 2390 leaf low-percentile { 2391 type percentile; 2392 default "10.00"; 2393 description 2394 "Low percentile. If set to '0', this means low-percentiles 2395 are disabled."; 2396 } 2397 leaf mid-percentile { 2398 type percentile; 2399 must '. >= ../low-percentile' { 2400 error-message 2401 "The mid-percentile must be greater than 2402 or equal to the low-percentile."; 2403 } 2404 default "50.00"; 2405 description 2406 "Mid percentile. If set to the same value as low-percentiles, 2407 this means mid-percentiles are disabled."; 2408 } 2409 leaf high-percentile { 2410 type percentile; 2411 must '. >= ../mid-percentile' { 2412 error-message 2413 "The high-percentile must be greater than 2414 or equal to the mid-percentile."; 2415 } 2416 default "90.00"; 2417 description 2418 "High percentile. If set to the same value as mid-percentiles, 2419 this means high-percentiles are disabled."; 2420 } 2421 } 2423 grouping percentile { 2424 description 2425 "Generic grouping for percentile."; 2426 leaf low-percentile-g { 2427 type yang:gauge64; 2428 description 2429 "Low traffic."; 2430 } 2431 leaf mid-percentile-g { 2432 type yang:gauge64; 2433 description 2434 "Mid percentile."; 2435 } 2436 leaf high-percentile-g { 2437 type yang:gauge64; 2438 description 2439 "High percentile."; 2440 } 2441 leaf peak-g { 2442 type yang:gauge64; 2443 description 2444 "Peak"; 2445 } 2446 } 2448 grouping unit-config { 2449 description 2450 "Generic grouping for unit configuration."; 2451 list unit-config { 2452 key "unit"; 2453 description 2454 "Controls which units are allowed when sharing telemetry 2455 data."; 2456 leaf unit { 2457 type unit-type; 2458 description 2459 "Can be pps, bit/ps, or byte/ps"; 2460 } 2461 leaf unit-status { 2462 type boolean; 2463 description 2464 "Enable/disable the use of the measurement unit."; 2465 } 2466 } 2467 } 2469 grouping traffic-unit { 2470 description 2471 "Grouping of traffic as a function of measurement unit."; 2472 leaf unit { 2473 type unit; 2474 description 2475 "The traffic can be measured using unit types: packets 2476 per second (PPS), Bits per Second (BPS), and/or 2477 bytes per second. DOTS agents auto-scale to the appropriate 2478 units (e.g., megabit-ps, kilobit-ps)."; 2479 } 2480 uses percentile; 2481 } 2483 grouping traffic-unit-protocol { 2484 description 2485 "Grouping of traffic of a given transport protocol as 2486 a function of measurement unit."; 2487 leaf unit { 2488 type unit; 2489 description 2490 "The traffic can be measured using unit types: packets 2491 per second (PPS), Bits per Second (BPS), and/or 2492 bytes per second. DOTS agents auto-scale to the appropriate 2493 units (e.g., megabit-ps, kilobit-ps)."; 2494 } 2495 leaf protocol { 2496 type uint8; 2497 description 2498 "The transport protocol. 2499 Values are taken from the IANA Protocol Numbers registry: 2500 . 2502 For example, this field contains 6 for TCP, 2503 17 for UDP, 33 for DCCP, or 132 for SCTP."; 2504 } 2505 uses percentile; 2506 } 2508 grouping total-connection-capacity { 2509 description 2510 "Total Connections Capacity. If the target is subjected 2511 to resource consuming DDoS attack, these attributes are 2512 useful to detect resource consuming DDoS attacks"; 2513 leaf connection { 2514 type uint64; 2515 description 2516 "The maximum number of simultaneous connections that 2517 are allowed to the target server. The threshold is 2518 transport-protocol specific because the target server 2519 could support multiple protocols."; 2520 } 2521 leaf connection-client { 2522 type uint64; 2523 description 2524 "The maximum number of simultaneous connections that 2525 are allowed to the target server per client."; 2526 } 2527 leaf embryonic { 2528 type uint64; 2529 description 2530 "The maximum number of simultaneous embryonic connections 2531 that are allowed to the target server. The term 'embryonic 2532 connection' refers to a connection whose connection handshake 2533 is not finished and embryonic connection is only possible in 2534 connection-oriented transport protocols like TCP or SCTP."; 2535 } 2536 leaf embryonic-client { 2537 type uint64; 2538 description 2539 "The maximum number of simultaneous embryonic connections 2540 that are allowed to the target server per client."; 2541 } 2542 leaf connection-ps { 2543 type uint64; 2544 description 2545 "The maximum number of connections allowed per second 2546 to the target server."; 2547 } 2548 leaf connection-client-ps { 2549 type uint64; 2550 description 2551 "The maximum number of connections allowed per second 2552 to the target server per client."; 2553 } 2554 leaf request-ps { 2555 type uint64; 2556 description 2557 "The maximum number of requests allowed per second 2558 to the target server."; 2559 } 2560 leaf request-client-ps { 2561 type uint64; 2562 description 2563 "The maximum number of requests allowed per second 2564 to the target server per client."; 2565 } 2566 leaf partial-request-ps { 2567 type uint64; 2568 description 2569 "The maximum number of partial requests allowed per 2570 second to the target server."; 2571 } 2572 leaf partial-request-client-ps { 2573 type uint64; 2574 description 2575 "The maximum number of partial requests allowed per 2576 second to the target server per client."; 2577 } 2578 } 2580 grouping connection { 2581 description 2582 "A set of attributes which represent the attack 2583 characteristics"; 2584 leaf connection { 2585 type yang:gauge64; 2586 description 2587 "The number of simultaneous attack connections to 2588 the target server."; 2589 } 2590 leaf embryonic { 2591 type yang:gauge64; 2592 description 2593 "The number of simultaneous embryonic connections to 2594 the target server."; 2595 } 2596 leaf connection-ps { 2597 type yang:gauge64; 2598 description 2599 "The number of attack connections per second to 2600 the target server."; 2601 } 2602 leaf request-ps { 2603 type yang:gauge64; 2604 description 2605 "The number of attack requests per second to 2606 the target server."; 2607 } 2608 leaf partial-request-ps { 2609 type yang:gauge64; 2610 description 2611 "The number of attack partial requests to 2612 the target server."; 2613 } 2614 } 2616 grouping connection-percentile { 2617 description 2618 "Total attack connections."; 2619 container low-percentile-c { 2620 description 2621 "Low percentile of attack connections."; 2622 uses connection; 2623 } 2624 container mid-percentile-c { 2625 description 2626 "Mid percentile of attack connections."; 2627 uses connection; 2628 } 2629 container high-percentile-c { 2630 description 2631 "High percentile of attack connections."; 2632 uses connection; 2633 } 2634 container peak-c { 2635 description 2636 "Peak attack connections."; 2637 uses connection; 2638 } 2639 } 2641 grouping connection-protocol-percentile { 2642 description 2643 "Total attack connections."; 2644 list low-percentile-l { 2645 key "protocol"; 2646 description 2647 "Low percentile of attack connections."; 2648 leaf protocol { 2649 type uint8; 2650 description 2651 "The transport protocol. 2652 Values are taken from the IANA Protocol Numbers registry: 2653 ."; 2654 } 2655 uses connection; 2656 } 2657 list mid-percentile-l { 2658 key "protocol"; 2659 description 2660 "Mid percentile of attack connections."; 2661 leaf protocol { 2662 type uint8; 2663 description 2664 "The transport protocol. 2665 Values are taken from the IANA Protocol Numbers registry: 2666 ."; 2667 } 2668 uses connection; 2669 } 2670 list high-percentile-l { 2671 key "protocol"; 2672 description 2673 "High percentile of attack connections."; 2674 leaf protocol { 2675 type uint8; 2676 description 2677 "The transport protocol. 2678 Values are taken from the IANA Protocol Numbers registry: 2679 ."; 2680 } 2681 uses connection; 2682 } 2683 list peak-l { 2684 key "protocol"; 2685 description 2686 "Peak attack connections."; 2687 leaf protocol { 2688 type uint8; 2689 description 2690 "The transport protocol. 2691 Values are taken from the IANA Protocol Numbers registry: 2692 ."; 2693 } 2694 uses connection; 2695 } 2696 } 2698 grouping attack-detail { 2699 description 2700 "Various information and details that describe the on-going 2701 attacks that needs to be mitigated by the DOTS server. 2702 The attack details need to cover well-known and common attacks 2703 (such as a SYN Flood) along with new emerging or vendor-specific 2704 attacks."; 2705 leaf id { 2706 type uint32; 2707 description 2708 "Vendor ID is a security vendor's Enterprise Number."; 2709 } 2710 leaf attack-id { 2711 type string; 2712 description 2713 "Unique identifier assigned by the vendor for the attack."; 2714 } 2715 leaf attack-name { 2716 type string; 2717 description 2718 "Textual representation of attack description. Natural Language 2719 Processing techniques (e.g., word embedding) can possibly be used 2720 to map the attack description to an attack type."; 2721 } 2722 leaf attack-severity { 2723 type attack-severity; 2724 description 2725 "Severity level of an attack"; 2726 } 2727 leaf start-time { 2728 type uint64; 2729 description 2730 "The time the attack started. Start time is represented in seconds 2731 relative to 1970-01-01T00:00:00Z in UTC time."; 2732 } 2733 leaf end-time { 2734 type uint64; 2735 description 2736 "The time the attack ended. End time is represented in seconds 2737 relative to 1970-01-01T00:00:00Z in UTC time."; 2738 } 2739 container source-count { 2740 description 2741 "Indicates the count of unique sources involved 2742 in the attack."; 2743 uses percentile; 2744 } 2745 } 2747 grouping top-talker-aggregate { 2748 description 2749 "Top attack sources."; 2750 list talker { 2751 key "source-prefix"; 2752 description 2753 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2754 leaf spoofed-status { 2755 type boolean; 2756 description 2757 "Indicates whether this address is spoofed."; 2758 } 2759 leaf source-prefix { 2760 type inet:ip-prefix; 2761 description 2762 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2763 } 2764 list source-port-range { 2765 key "lower-port"; 2766 description 2767 "Port range. When only lower-port is 2768 present, it represents a single port number."; 2769 leaf lower-port { 2770 type inet:port-number; 2771 mandatory true; 2772 description 2773 "Lower port number of the port range."; 2774 } 2775 leaf upper-port { 2776 type inet:port-number; 2777 must ". >= ../lower-port" { 2778 error-message 2779 "The upper port number must be greater than 2780 or equal to lower port number."; 2781 } 2782 description 2783 "Upper port number of the port range."; 2784 } 2785 } 2786 list source-icmp-type-range { 2787 key "lower-type"; 2788 description 2789 "ICMP type range. When only lower-type is 2790 present, it represents a single ICMP type."; 2791 leaf lower-type { 2792 type uint8; 2793 mandatory true; 2794 description 2795 "Lower ICMP type of the ICMP type range."; 2796 } 2797 leaf upper-type { 2798 type uint8; 2799 must ". >= ../lower-type" { 2800 error-message 2801 "The upper ICMP type must be greater than 2802 or equal to lower ICMP type."; 2803 } 2804 description 2805 "Upper type of the ICMP type range."; 2806 } 2807 } 2808 list total-attack-traffic { 2809 key "unit"; 2810 description 2811 "Total attack traffic issued from this source."; 2812 uses traffic-unit; 2813 } 2814 container total-attack-connection { 2815 description 2816 "Total attack connections issued from this source."; 2817 uses connection-percentile; 2818 } 2819 } 2820 } 2822 grouping top-talker { 2823 description 2824 "Top attack sources."; 2825 list talker { 2826 key "source-prefix"; 2827 description 2828 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2829 leaf spoofed-status { 2830 type boolean; 2831 description 2832 "Indicates whether this address is spoofed."; 2833 } 2834 leaf source-prefix { 2835 type inet:ip-prefix; 2836 description 2837 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2839 } 2840 list source-port-range { 2841 key "lower-port"; 2842 description 2843 "Port range. When only lower-port is 2844 present, it represents a single port number."; 2845 leaf lower-port { 2846 type inet:port-number; 2847 mandatory true; 2848 description 2849 "Lower port number of the port range."; 2850 } 2851 leaf upper-port { 2852 type inet:port-number; 2853 must ". >= ../lower-port" { 2854 error-message 2855 "The upper port number must be greater than 2856 or equal to lower port number."; 2857 } 2858 description 2859 "Upper port number of the port range."; 2860 } 2861 } 2862 list source-icmp-type-range { 2863 key "lower-type"; 2864 description 2865 "ICMP type range. When only lower-type is 2866 present, it represents a single ICMP type."; 2867 leaf lower-type { 2868 type uint8; 2869 mandatory true; 2870 description 2871 "Lower ICMP type of the ICMP type range."; 2872 } 2873 leaf upper-type { 2874 type uint8; 2875 must ". >= ../lower-type" { 2876 error-message 2877 "The upper ICMP type must be greater than 2878 or equal to lower ICMP type."; 2879 } 2880 description 2881 "Upper type of the ICMP type range."; 2882 } 2883 } 2884 list total-attack-traffic { 2885 key "unit"; 2886 description 2887 "Total attack traffic issued from this source."; 2888 uses traffic-unit; 2889 } 2890 container total-attack-connection { 2891 description 2892 "Total attack connections issued from this source."; 2893 uses connection-protocol-percentile; 2894 } 2895 } 2896 } 2898 grouping baseline { 2899 description 2900 "Grouping for the telemetry baseline."; 2901 uses ietf-data:target; 2902 leaf-list alias-name { 2903 type string; 2904 description 2905 "An alias name that points to a resource."; 2906 } 2907 list total-traffic-normal-baseline { 2908 key "unit protocol"; 2909 description 2910 "Total traffic normal baselines."; 2911 uses traffic-unit-protocol; 2912 } 2913 list total-connection-capacity { 2914 key "protocol"; 2915 description 2916 "Total connection capacity."; 2917 leaf protocol { 2918 type uint8; 2919 description 2920 "The transport protocol. 2921 Values are taken from the IANA Protocol Numbers registry: 2922 ."; 2923 } 2924 uses total-connection-capacity; 2925 } 2926 } 2928 grouping pre-or-ongoing-mitigation { 2929 description 2930 "Grouping for the telemetry data."; 2931 list total-traffic { 2932 key "unit protocol"; 2933 description 2934 "Total traffic."; 2936 uses traffic-unit-protocol; 2937 } 2938 list total-attack-traffic { 2939 key "unit protocol"; 2940 description 2941 "Total attack traffic per protocol."; 2942 uses traffic-unit-protocol; 2943 } 2944 container total-attack-connection { 2945 description 2946 "Total attack connections."; 2947 uses connection-protocol-percentile; 2948 } 2949 container attack-detail { 2950 description 2951 "Attack details."; 2952 uses attack-detail; 2953 container top-talker { 2954 description 2955 "Top attack sources."; 2956 uses top-talker; 2957 } 2958 } 2959 } 2961 augment "/ietf-signal:dots-signal/ietf-signal:message-type/" 2962 + "ietf-signal:mitigation-scope/ietf-signal:scope" { 2963 if-feature "dots-telemetry"; 2964 description 2965 "Extends mitigation scope with telemetry update data."; 2966 list total-traffic { 2967 key "unit protocol"; 2968 config false; 2969 description 2970 "Total traffic."; 2971 uses traffic-unit-protocol; 2972 } 2973 list total-attack-traffic { 2974 key "unit"; 2975 description 2976 "Total attack traffic."; 2977 uses traffic-unit; 2978 } 2979 container total-attack-connection { 2980 config false; 2981 description 2982 "Total attack connections."; 2983 uses connection-percentile; 2985 } 2986 container attack-detail { 2987 description 2988 "Atatck details"; 2989 uses attack-detail; 2990 container top-talker { 2991 description 2992 "Top attack sources."; 2993 uses top-talker-aggregate; 2994 } 2995 } 2996 } 2998 augment "/ietf-signal:dots-signal/ietf-signal:message-type" { 2999 if-feature "dots-telemetry"; 3000 description 3001 "Add a new choice to enclose telemetry data in DOTS 3002 signal channel."; 3003 case telemetry-setup { 3004 description 3005 "Indicates the message is about telemetry."; 3006 list telemetry { 3007 key "cuid tsid"; 3008 description 3009 "The telemetry data per DOTS client."; 3010 leaf cuid { 3011 type string; 3012 description 3013 "A unique identifier that is 3014 generated by a DOTS client to prevent 3015 request collisions. It is expected that the 3016 cuid will remain consistent throughout the 3017 lifetime of the DOTS client."; 3018 } 3019 leaf cdid { 3020 type string; 3021 description 3022 "The cdid should be included by a server-domain 3023 DOTS gateway to propagate the client domain 3024 identification information from the 3025 gateway's client-facing-side to the gateway's 3026 server-facing-side, and from the gateway's 3027 server-facing-side to the DOTS server. 3029 It may be used by the final DOTS server 3030 for policy enforcement purposes."; 3031 } 3032 leaf tsid { 3033 type uint32; 3034 description 3035 "An identifier for the DOTS telemetry setup 3036 data."; 3037 } 3038 choice setup-type { 3039 description 3040 "Can be a mitigation configuration, a pipe capacity, 3041 or baseline message."; 3042 case telemetry-config { 3043 description 3044 "Uses to set low, mid, and high percentile values."; 3045 container current-config { 3046 description 3047 "Current configuration values."; 3048 uses percentile-config; 3049 uses unit-config; 3050 leaf server-originated-telemetry { 3051 type boolean; 3052 description 3053 "Used by a DOTS client to enable/disable whether it 3054 accepts pre-or-ongoing-mitigation telemetry from 3055 the DOTS server."; 3056 } 3057 leaf telemetry-notify-interval { 3058 type uint32 { 3059 range "1 .. 3600"; 3060 } 3061 units "seconds"; 3062 description 3063 "Minimum number of seconds between successive 3064 telemetry notifications."; 3065 } 3066 } 3067 container max-config-values { 3068 config false; 3069 description 3070 "Maximum acceptable configuration values."; 3071 uses percentile-config; 3072 // Check if this is right place for indciating this capability 3073 leaf server-originated-telemetry { 3074 type boolean; 3075 description 3076 "Indicates whether the DOTS server can be instructed 3077 to send pre-or-ongoing-mitigation telemetry. If set to FALSE 3078 or the attribute is not present, this is an indication 3079 that the server does not support this capability."; 3080 } 3081 leaf telemetry-notify-interval { 3082 type uint32 { 3083 range "1 .. 3600"; 3084 } 3085 must '. >= ../../min-config-values/telemetry-notify-interval' { 3086 error-message 3087 "The value must be greater than or equal 3088 to the telemetry-notify-interval in the min-config-values"; 3089 } 3090 units "seconds"; 3091 description 3092 "Minimum number of seconds between successive 3093 telemetry notifications."; 3094 } 3095 } 3096 container min-config-values { 3097 config false; 3098 description 3099 "Minimum acceptable configuration values."; 3100 uses percentile-config; 3101 leaf telemetry-notify-interval { 3102 type uint32 { 3103 range "1 .. 3600"; 3104 } 3105 units "seconds"; 3106 description 3107 "Minimum number of seconds between successive 3108 telemetry notifications."; 3109 } 3110 } 3111 container supported-units { 3112 config false; 3113 description 3114 "Supported units and default activation status."; 3115 uses unit-config; 3116 } 3117 } 3118 case pipe { 3119 description 3120 "Total pipe capacity of a DOTS client domain"; 3121 list total-pipe-capacity { 3122 key "link-id unit"; 3123 description 3124 "Total pipe capacity of a DOTS client domain."; 3125 leaf link-id { 3126 type nt:link-id; 3127 description 3128 "Identifier of an interconnection link."; 3130 } 3131 leaf capacity { 3132 type uint64; 3133 mandatory true; 3134 description 3135 "Pipe capacity."; 3136 } 3137 leaf unit { 3138 type unit; 3139 description 3140 "The traffic can be measured using unit types: packets 3141 per second (PPS), Bits per Second (BPS), and/or 3142 bytes per second. DOTS agents auto-scale to the 3143 appropriate units (e.g., megabit-ps, kilobit-ps)."; 3144 } 3145 } 3146 } 3147 case baseline { 3148 description 3149 "Traffic baseline information"; 3150 list baseline { 3151 key "id"; 3152 description 3153 "Traffic baseline information"; 3154 leaf id { 3155 type uint32; 3156 must '. >= 1'; 3157 description 3158 "A baseline entry identifier."; 3159 } 3160 uses baseline; 3161 } 3162 } 3163 } 3164 } 3165 } 3166 case telemetry { 3167 description 3168 "Indicates the message is about telemetry."; 3169 list pre-or-ongoing-mitigation { 3170 key "cuid tmid"; 3171 description 3172 "Pre-or-ongoing-mitigation telemetry per DOTS client."; 3173 leaf cuid { 3174 type string; 3175 description 3176 "A unique identifier that is 3177 generated by a DOTS client to prevent 3178 request collisions. It is expected that the 3179 cuid will remain consistent throughout the 3180 lifetime of the DOTS client."; 3181 } 3182 leaf cdid { 3183 type string; 3184 description 3185 "The cdid should be included by a server-domain 3186 DOTS gateway to propagate the client domain 3187 identification information from the 3188 gateway's client-facing-side to the gateway's 3189 server-facing-side, and from the gateway's 3190 server-facing-side to the DOTS server. 3192 It may be used by the final DOTS server 3193 for policy enforcement purposes."; 3194 } 3195 leaf tmid { 3196 type uint32; 3197 description 3198 "An identifier to uniquely demux telemetry data send using 3199 the same message."; 3200 } 3201 container target { 3202 description 3203 "Indicates the target."; 3204 uses ietf-data:target; 3205 leaf-list alias-name { 3206 type string; 3207 description 3208 "An alias name that points to a resource."; 3209 } 3210 leaf-list mid-list { 3211 type uint32; 3212 description 3213 "Reference a list of associated mitigation requests."; 3214 } 3215 } 3216 uses pre-or-ongoing-mitigation; 3217 } 3218 } 3219 } 3220 } 3221 3222 10. YANG/JSON Mapping Parameters to CBOR 3224 All DOTS telemetry parameters in the payload of the DOTS signal 3225 channel MUST be mapped to CBOR types as shown in the following table: 3227 o Implementers may use the values in: https://github.com/boucadair/ 3228 draft-dots-telemetry/blob/master/mapping-table.txt 3230 +----------------------+-------------+------+---------------+--------+ 3231 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 3232 | | Type | Key | Type & | Type | 3233 | | | | Information | | 3234 +----------------------+-------------+------+---------------+--------+ 3235 | tsid | uint32 |TBA1 | 0 unsigned | Number | 3236 | telemetry | container |TBA2 | 5 map | Object | 3237 | low-percentile | decimal64 |TBA3 | 6 tag 4 | | 3238 | | | | [-2, integer]| String | 3239 | mid-percentile | decimal64 |TBA4 | 6 tag 4 | | 3240 | | | | [-2, integer]| String | 3241 | high-percentile | decimal64 |TBA5 | 6 tag 4 | | 3242 | | | | [-2, integer]| String | 3243 | unit-config | list |TBA6 | 4 array | Array | 3244 | unit | enumeration |TBA7 | 0 unsigned | String | 3245 | unit-status | boolean |TBA8 | 7 bits 20 | False | 3246 | | | | 7 bits 21 | True | 3247 | total-pipe-capability| list |TBA9 | 4 array | Array | 3248 | link-id | string |TBA10 | 3 text string | String | 3249 | pre-or-ongoing- | list |TBA11 | 4 array | Array | 3250 | mitigation | | | | | 3251 | total-traffic- | | | | | 3252 | normal-baseline | list |TBA12 | 4 array | Array | 3253 | low-percentile-g | yang:gauge64|TBA13 | 0 unsigned | String | 3254 | mid-percentile-g | yang:gauge64|TBA14 | 0 unsigned | String | 3255 | high-percentile-g | yang:gauge64|TBA15 | 0 unsigned | String | 3256 | peak-g | yang:gauge64|TBA16 | 0 unsigned | String | 3257 | total-attack-traffic | list |TBA17 | 4 array | Array | 3258 | total-traffic | list |TBA18 | 4 array | Array | 3259 | total-connection- | | | | | 3260 | capacity | list |TBA19 | 4 array | Array | 3261 | connection | uint64 |TBA20 | 0 unsigned | String | 3262 | connection-client | uint64 |TBA21 | 0 unsigned | String | 3263 | embryonic | uint64 |TBA22 | 0 unsigned | String | 3264 | embryonic-client | uint64 |TBA23 | 0 unsigned | String | 3265 | connection-ps | uint64 |TBA24 | 0 unsigned | String | 3266 | connection-client-ps | uint64 |TBA25 | 0 unsigned | String | 3267 | request-ps | uint64 |TBA26 | 0 unsigned | String | 3268 | request-client-ps | uint64 |TBA27 | 0 unsigned | String | 3269 | partial-request-ps | uint64 |TBA28 | 0 unsigned | String | 3270 | partial-request- | | | | | 3271 | client-ps | uint64 |TBA29 | 0 unsigned | String | 3272 | total-attack- | | | | | 3273 | connection | container |TBA30 | 5 map | Object | 3274 | low-percentile-l | list |TBA31 | 4 array | Array | 3275 | mid-percentile-l | list |TBA32 | 4 array | Array | 3276 | high-percentile-l | list |TBA33 | 4 array | Array | 3277 | peak-l | list |TBA34 | 4 array | Array | 3278 | attack-detail | container |TBA35 | 5 map | Object | 3279 | id | uint32 |TBA36 | 0 unsigned | Number | 3280 | attack-id | string |TBA37 | 3 text string | String | 3281 | attack-name | string |TBA38 | 3 text string | String | 3282 | attack-severity | enumeration |TBA39 | 0 unsigned | String | 3283 | start-time | uint64 |TBA40 | 0 unsigned | String | 3284 | end-time | uint64 |TBA41 | 0 unsigned | String | 3285 | source-count | container |TBA42 | 5 map | Object | 3286 | top-talker | container |TBA43 | 5 map | Object | 3287 | spoofed-status | boolean |TBA44 | 7 bits 20 | False | 3288 | | | | 7 bits 21 | True | 3289 | low-percentile-c | container |TBA45 | 5 map | Object | 3290 | mid-percentile-c | container |TBA46 | 5 map | Object | 3291 | high-percentile-c | container |TBA47 | 5 map | Object | 3292 | peak-c | container |TBA48 | 5 map | Object | 3293 | baseline | container |TBA49 | 5 map | Object | 3294 | current-config | container |TBA50 | 5 map | Object | 3295 | max-config-values | container |TBA51 | 5 map | Object | 3296 | min-config-values | container |TBA52 | 5 map | Object | 3297 | supported-units | container |TBA53 | 5 map | Object | 3298 | server-originated- | boolean |TBA54 | 7 bits 20 | False | 3299 | telemetry | | | 7 bits 21 | True | 3300 | telemetry-notify- | uint32 |TBA55 | 0 unsigned | Number | 3301 | interval | | | | | 3302 | tmid | uint32 |TBA56 | 0 unsigned | Number | 3303 | measurement-interval | identityref |TBA57 | 0 unsigned | String | 3304 | measurement-sample | identityref |TBA58 | 0 unsigned | String | 3305 | talker | list |TBA59 | 4 array | Array | 3306 | source-prefix | inet: |TBA60 | 3 text string | String | 3307 | | ip-prefix | | | | 3308 | mid-list | leaf-list |TBA61 | 4 array | Array | 3309 | | uint32 | | 0 unsigned | Number | 3310 | source-port-range | list |TBA62 | 4 array | Array | 3311 | source-icmp-type- | list |TBA63 | 4 array | Array | 3312 | range | | | | | 3313 | lower-type | uint8 |TBA64 | 0 unsigned | Number | 3314 | upper-type | uint8 |TBA65 | 0 unsigned | Number | 3315 | target | container |TBA66 | 5 map | Object | 3316 | capacity | uint64 |TBA67 | 0 unsigned | String | 3317 | ietf-dots-telemetry: | | | | | 3318 | telemetry-setup | container |TBA70 | 5 map | Object | 3319 | ietf-dots-telemetry: | | | | | 3320 | total-traffic | list |TBA71 | 4 array | Array | 3321 | ietf-dots-telemetry: | | | | | 3322 | unit | enumeration |TBA72 | 0 unsigned | String | 3323 | ietf-dots-telemetry: | | | | | 3324 | low-percentile-g | yang:gauge64|TBA73 | 0 unsigned | String | 3325 | ietf-dots-telemetry: | | | | | 3326 | mid-percentile-g | yang:gauge64|TBA74 | 0 unsigned | String | 3327 | ietf-dots-telemetry: | | | | | 3328 | high-percentile-g | yang:gauge64|TBA75 | 0 unsigned | String | 3329 | ietf-dots-telemetry: | | | | | 3330 | peak-g | yang:gauge64|TBA76 | 0 unsigned | String | 3331 | ietf-dots-telemetry: | | | | | 3332 | total-attack-traffic | list |TBA77 | 4 array | Array | 3333 | ietf-dots-telemetry: | | | | | 3334 | total-attack- | | | | | 3335 | connection | container |TBA78 | 5 map | Object | 3336 | ietf-dots-telemetry: | | | | | 3337 | low-percentile-c | container |TBA79 | 5 map | Object | 3338 | ietf-dots-telemetry: | | | | | 3339 | mid-percentile-c | container |TBA80 | 5 map | Object | 3340 | ietf-dots-telemetry: | | | | | 3341 | high-percentile-c | container |TBA81 | 5 map | Object | 3342 | ietf-dots-telemetry: | | | | | 3343 | peak-c | container |TBA82 | 5 map | Object | 3344 | ietf-dots-telemetry: | | | | | 3345 | connection | uint64 |TBA83 | 0 unsigned | String | 3346 | ietf-dots-telemetry: | | | | | 3347 | embryonic | uint64 |TBA84 | 0 unsigned | String | 3348 | ietf-dots-telemetry: | | | | | 3349 | connection-ps | uint64 |TBA85 | 0 unsigned | String | 3350 | ietf-dots-telemetry: | | | | | 3351 | request-ps | uint64 |TBA86 | 0 unsigned | String | 3352 | ietf-dots-telemetry: | | | | | 3353 | partial-request-ps | uint64 |TBA87 | 0 unsigned | String | 3354 | ietf-dots-telemetry: | | | | | 3355 | attack-detail | container |TBA88 | 5 map | Object | 3356 | ietf-dots-telemetry: | | | | | 3357 | id | uint32 |TBA89 | 0 unsigned | Number | 3358 | ietf-dots-telemetry: | | | | | 3359 | attack-id | string |TBA90 | 3 text string | String | 3360 | ietf-dots-telemetry: | | | | | 3361 | attack-name | string |TBA91 | 3 text string | String | 3362 | ietf-dots-telemetry: | | | | | 3363 | attack-severity | enumeration |TBA92 | 0 unsigned | String | 3364 | ietf-dots-telemetry: | | | | | 3365 | start-time | uint64 |TBA93 | 0 unsigned | String | 3366 | ietf-dots-telemetry: | | | | | 3367 | end-time | uint64 |TBA94 | 0 unsigned | String | 3368 | ietf-dots-telemetry: | | | | | 3369 | source-count | container |TBA95 | 5 map | Object | 3370 | ietf-dots-telemetry: | | | | | 3371 | top-talker | container |TBA96 | 5 map | Object | 3372 | ietf-dots-telemetry: | | | | | 3373 | spoofed-status | boolean |TBA97 | 7 bits 20 | False | 3374 | | | | 7 bits 21 | True | 3375 | ietf-dots-telemetry: | | | | | 3376 | talker | list |TBA98 | 4 array | Array | 3377 | ietf-dots-telemetry: | inet: |TBA99 | 3 text string | String | 3378 | source-prefix | ip-prefix | | | | 3379 | ietf-dots-telemetry: | | | | | 3380 | source-port-range | list |TBA100| 4 array | Array | 3381 | ietf-dots-telemetry: | | | | | 3382 | lower-port | inet: | | | | 3383 | | port-number|TBA101| 0 unsigned | Number | 3384 | ietf-dots-telemetry: | | | | | 3385 | upper-port | inet: | | | | 3386 | | port-number|TBA102| 0 unsigned | Number | 3387 | ietf-dots-telemetry: | | | | | 3388 | source-icmp-type- | list |TBA103| 4 array | Array | 3389 | range | | | | | 3390 | ietf-dots-telemetry: | | | | | 3391 | lower-type | uint8 |TBA104| 0 unsigned | Number | 3392 | ietf-dots-telemetry: | | | | | 3393 | upper-type | uint8 |TBA105| 0 unsigned | Number | 3394 | ietf-dots-telemetry: | | | | | 3395 | telemetry | container |TBA106| 5 map | Object | 3396 +----------------------+-------------+------+---------------+--------+ 3398 11. IANA Considerationsr 3400 11.1. DOTS Signal Channel CBOR Key Values 3402 This specification registers the DOTS telemetry attributes in the 3403 IANA "DOTS Signal Channel CBOR Key Values" registry available at 3404 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 3405 cbor-key-values. 3407 The DOTS telemetry attributes defined in this specification are 3408 comprehension-optional parameters. 3410 o Note to the RFC Editor: (1) CBOR keys are assigned from the 3411 32768-49151 range. (2) Please assign the following suggested 3412 values. 3414 +----------------------+-------+-------+------------+---------------+ 3415 | Parameter Name | CBOR | CBOR | Change | Specification | 3416 | | Key | Major | Controller | Document(s) | 3417 | | Value | Type | | | 3418 +----------------------+-------+-------+------------+---------------+ 3419 | tsid | TBA1 | 0 | IESG | [RFCXXXX] | 3420 | telemetry | TBA2 | 5 | IESG | [RFCXXXX] | 3421 | low-percentile | TBA3 | 6tag4 | IESG | [RFCXXXX] | 3422 | mid-percentile | TBA4 | 6tag4 | IESG | [RFCXXXX] | 3423 | high-percentile | TBA5 | 6tag4 | IESG | [RFCXXXX] | 3424 | unit-config | TBA6 | 4 | IESG | [RFCXXXX] | 3425 | unit | TBA7 | 0 | IESG | [RFCXXXX] | 3426 | unit-status | TBA8 | 7 | IESG | [RFCXXXX] | 3427 | total-pipe-capability| TBA9 | 4 | IESG | [RFCXXXX] | 3428 | link-id | TBA10 | 3 | IESG | [RFCXXXX] | 3429 | pre-or-ongoing- | TBA11 | 4 | IESG | [RFCXXXX] | 3430 | mitigation | | | | | 3431 | total-traffic- | TBA12 | 4 | IESG | [RFCXXXX] | 3432 | normal-baseline | | | | | 3433 | low-percentile-g | TBA13 | 0 | IESG | [RFCXXXX] | 3434 | mid-percentile-g | TBA14 | 0 | IESG | [RFCXXXX] | 3435 | high-percentile-g | TBA15 | 0 | IESG | [RFCXXXX] | 3436 | peak-g | TBA16 | 0 | IESG | [RFCXXXX] | 3437 | total-attack-traffic | TBA17 | 4 | IESG | [RFCXXXX] | 3438 | total-traffic | TBA18 | 4 | IESG | [RFCXXXX] | 3439 | total-connection- | TBA19 | 4 | IESG | [RFCXXXX] | 3440 | capacity | | | | | 3441 | connection | TBA20 | 0 | IESG | [RFCXXXX] | 3442 | connection-client | TBA21 | 0 | IESG | [RFCXXXX] | 3443 | embryonic | TBA22 | 0 | IESG | [RFCXXXX] | 3444 | embryonic-client | TBA23 | 0 | IESG | [RFCXXXX] | 3445 | connection-ps | TBA24 | 0 | IESG | [RFCXXXX] | 3446 | connection-client-ps | TBA25 | 0 | IESG | [RFCXXXX] | 3447 | request-ps | TBA26 | 0 | IESG | [RFCXXXX] | 3448 | request-client-ps | TBA27 | 0 | IESG | [RFCXXXX] | 3449 | partial-request-ps | TBA28 | 0 | IESG | [RFCXXXX] | 3450 | partial-request- | TBA29 | 0 | IESG | [RFCXXXX] | 3451 | client-ps | | | | | 3452 | total-attack- | TBA30 | 5 | IESG | [RFCXXXX] | 3453 | connection | | | | | 3454 | low-percentile-l | TBA31 | 4 | IESG | [RFCXXXX] | 3455 | mid-percentile-l | TBA32 | 4 | IESG | [RFCXXXX] | 3456 | high-percentile-l | TBA33 | 4 | IESG | [RFCXXXX] | 3457 | peak-l | TBA34 | 4 | IESG | [RFCXXXX] | 3458 | attack-detail | TBA35 | 5 | IESG | [RFCXXXX] | 3459 | id | TBA36 | 0 | IESG | [RFCXXXX] | 3460 | attack-id | TBA37 | 3 | IESG | [RFCXXXX] | 3461 | attack-name | TBA38 | 3 | IESG | [RFCXXXX] | 3462 | attack-severity | TBA39 | 0 | IESG | [RFCXXXX] | 3463 | start-time | TBA40 | 0 | IESG | [RFCXXXX] | 3464 | end-time | TBA41 | 0 | IESG | [RFCXXXX] | 3465 | source-count | TBA42 | 5 | IESG | [RFCXXXX] | 3466 | top-talker | TBA43 | 5 | IESG | [RFCXXXX] | 3467 | spoofed-status | TBA44 | 7 | IESG | [RFCXXXX] | 3468 | low-percentile-c | TBA45 | 5 | IESG | [RFCXXXX] | 3469 | mid-percentile-c | TBA46 | 5 | IESG | [RFCXXXX] | 3470 | high-percentile-c | TBA47 | 5 | IESG | [RFCXXXX] | 3471 | peak-c | TBA48 | 5 | IESG | [RFCXXXX] | 3472 | ietf-dots-signal-cha | TBA49 | 5 | IESG | [RFCXXXX] | 3473 | current-config | TBA50 | 5 | IESG | [RFCXXXX] | 3474 | max-config-value | TBA51 | 5 | IESG | [RFCXXXX] | 3475 | min-config-values | TBA52 | 5 | IESG | [RFCXXXX] | 3476 | supported-units | TBA55 | 5 | IESG | [RFCXXXX] | 3477 | server-originated- | TBA54 | 7 | IESG | [RFCXXXX] | 3478 | telemetry | | | | | 3479 | telemetry-notify- | TBA55 | 0 | IESG | [RFCXXXX] | 3480 | interval | | | | | 3481 | tmid | TBA56 | 0 | IESG | [RFCXXXX] | 3482 | measurement-interval | TBA57 | 0 | IESG | [RFCXXXX] | 3483 | measurement-sample | TBA58 | 0 | IESG | [RFCXXXX] | 3484 | talker | TBA59 | 0 | IESG | [RFCXXXX] | 3485 | source-prefix | TBA60 | 0 | IESG | [RFCXXXX] | 3486 | mid-list | TBA61 | 4 | IESG | [RFCXXXX] | 3487 | source-port-range | TBA62 | 4 | IESG | [RFCXXXX] | 3488 | source-icmp-type- | TBA63 | 4 | IESG | [RFCXXXX] | 3489 | lower-type | TBA64 | 0 | IESG | [RFCXXXX] | 3490 | upper-type | TBA65 | 0 | IESG | [RFCXXXX] | 3491 | target | TBA66 | 5 | IESG | [RFCXXXX] | 3492 | capacity | TBA67 | 0 | IESG | [RFCXXXX] | 3493 | ietf-dots-telemetry: | TBA70 | 5 | IESG | [RFCXXXX] | 3494 | telemetry-setup | | | | | 3495 | ietf-dots-telemetry: | TBA71 | 0 | IESG | [RFCXXXX] | 3496 | total-traffic | | | | | 3497 | ietf-dots-telemetry: | TBA72 | 0 | IESG | [RFCXXXX] | 3498 | unit | | | | | 3499 | ietf-dots-telemetry: | TBA73 | 0 | IESG | [RFCXXXX] | 3500 | low-percentile-g | | | | | 3501 | ietf-dots-telemetry: | TBA74 | 0 | IESG | [RFCXXXX] | 3502 | mid-percentile-g | | | | | 3503 | ietf-dots-telemetry: | TBA75 | 0 | IESG | [RFCXXXX] | 3504 | high-percentile-g | | | | | 3505 | ietf-dots-telemetry: | TBA76 | 0 | IESG | [RFCXXXX] | 3506 | peak-g | | | | | 3507 | ietf-dots-telemetry: | TBA77 | 0 | IESG | [RFCXXXX] | 3508 | total-attack-traffic | | | | | 3509 | ietf-dots-telemetry: | TBA78 | 0 | IESG | [RFCXXXX] | 3510 | total-attack- | | | | | 3511 | connection | | | | | 3512 | ietf-dots-telemetry: | TBA79 | 0 | IESG | [RFCXXXX] | 3513 | low-percentile-c | | | | | 3514 | ietf-dots-telemetry: | TBA80 | 0 | IESG | [RFCXXXX] | 3515 | mid-percentile-c | | | | | 3516 | ietf-dots-telemetry: | TBA71 | 0 | IESG | [RFCXXXX] | 3517 | high-percentile-c | | | | | 3518 | ietf-dots-telemetry: | TBA82 | 0 | IESG | [RFCXXXX] | 3519 | peak-c | | | | | 3520 | ietf-dots-telemetry: | TBA83 | 0 | IESG | [RFCXXXX] | 3521 | connection | | | | | 3522 | ietf-dots-telemetry: | TBA84 | 0 | IESG | [RFCXXXX] | 3523 | embryonic | | | | | 3524 | ietf-dots-telemetry: | TBA85 | 0 | IESG | [RFCXXXX] | 3525 | connection-ps | | | | | 3526 | ietf-dots-telemetry: | TBA86 | 0 | IESG | [RFCXXXX] | 3527 | request-ps | | | | | 3528 | ietf-dots-telemetry: | TBA87 | 0 | IESG | [RFCXXXX] | 3529 | partial-request-ps | | | | | 3530 | ietf-dots-telemetry: | TBA88 | 0 | IESG | [RFCXXXX] | 3531 | attack-detail | | | | | 3532 | ietf-dots-telemetry: | TBA89 | 0 | IESG | [RFCXXXX] | 3533 | id | | | | | 3534 | ietf-dots-telemetry: | TBA90 | 0 | IESG | [RFCXXXX] | 3535 | attack-id | | | | | 3536 | ietf-dots-telemetry: | TBA91 | 0 | IESG | [RFCXXXX] | 3537 | attack-name | | | | | 3538 | ietf-dots-telemetry: | TBA92 | 0 | IESG | [RFCXXXX] | 3539 | attack-severity | | | | | 3540 | ietf-dots-telemetry: | TBA93 | 0 | IESG | [RFCXXXX] | 3541 | start-time | | | | | 3542 | ietf-dots-telemetry: | TBA94 | 0 | IESG | [RFCXXXX] | 3543 | end-time | | | | | 3544 | ietf-dots-telemetry: | TBA95 | 0 | IESG | [RFCXXXX] | 3545 | source-count | | | | | 3546 | ietf-dots-telemetry: | TBA96 | 0 | IESG | [RFCXXXX] | 3547 | top-talker | | | | | 3548 | ietf-dots-telemetry: | TBA97 | 0 | IESG | [RFCXXXX] | 3549 | spoofed-status | | | | | 3550 | ietf-dots-telemetry: | TBA98 | 0 | IESG | [RFCXXXX] | 3551 | talker | | | | | 3552 | ietf-dots-telemetry: | TBA99 | 0 | IESG | [RFCXXXX] | 3553 | source-prefix | | | | | 3554 | ietf-dots-telemetry: | | | | | 3555 | source-port-range | TBA100| 4 | IESG | [RFCXXXX] | 3556 | ietf-dots-telemetry: | | | | | 3557 | lower-port | TBA101| 0 | IESG | [RFCXXXX] | 3558 | ietf-dots-telemetry: | | | | | 3559 | upper-port | TBA102| 0 | IESG | [RFCXXXX] | 3560 | ietf-dots-telemetry: | | | | | 3561 | source-icmp-type- | TBA103| 4 | IESG | [RFCXXXX] | 3562 | range | | | | | 3563 | ietf-dots-telemetry: | | | | | 3564 | lower-type | TBA104| 0 | IESG | [RFCXXXX] | 3565 | ietf-dots-telemetry: | | | | | 3566 | upper-type | TBA105| 0 | IESG | [RFCXXXX] | 3567 | ietf-dots-telemetry: | TBA106| 5 | IESG | [RFCXXXX] | 3568 | telemetry | | | | | 3569 +----------------------+-------+-------+------------+---------------+ 3571 11.2. DOTS Signal Channel Conflict Cause Codes 3573 This specification requests IANA to assign a new code from the "DOTS 3574 Signal Channel Conflict Cause Codes" registry available at 3575 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 3576 conflict-cause-codes. 3578 Code Label Description Reference 3579 TBA overlapping-pipes Overlapping pipe scope [RFCXXXX] 3581 11.3. DOTS Signal Telemetry YANG Module 3583 This document requests IANA to register the following URI in the "ns" 3584 subregistry within the "IETF XML Registry" [RFC3688]: 3586 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 3587 Registrant Contact: The IESG. 3588 XML: N/A; the requested URI is an XML namespace. 3590 This document requests IANA to register the following YANG module in 3591 the "YANG Module Names" subregistry [RFC7950] within the "YANG 3592 Parameters" registry. 3594 name: ietf-dots-telemetry 3595 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 3596 maintained by IANA: N 3597 prefix: dots-telemetry 3598 reference: RFC XXXX 3600 12. Security Considerations 3602 Security considerations in [I-D.ietf-dots-signal-channel] need to be 3603 taken into consideration. 3605 13. Contributors 3607 The following individuals have contributed to this document: 3609 o Li Su, CMCC, Email: suli@chinamobile.com 3611 o Jin Peng, CMCC, Email: pengjin@chinamobile.com 3613 o Pan Wei, Huawei, Email: william.panwei@huawei.com 3615 14. Acknowledgements 3617 The authors would like to thank Flemming Andreasen, Liang Xia, and 3618 Kaname Nishizuka co-authors of https://tools.ietf.org/html/draft- 3619 doron-dots-telemetry-00 draft and everyone who had contributed to 3620 that document. 3622 Authors would like to thank Kaname Nishizuka, Jon Shallow, Wei Pan 3623 and Yuuhei Hayashi for comments and review. 3625 15. References 3627 15.1. Normative References 3629 [Enterprise-Numbers] 3630 "Private Enterprise Numbers", 2005, . 3633 [I-D.ietf-dots-data-channel] 3634 Boucadair, M. and T. Reddy.K, "Distributed Denial-of- 3635 Service Open Threat Signaling (DOTS) Data Channel 3636 Specification", draft-ietf-dots-data-channel-31 (work in 3637 progress), July 2019. 3639 [I-D.ietf-dots-signal-call-home] 3640 Reddy.K, T., Boucadair, M., and J. Shallow, "Distributed 3641 Denial-of-Service Open Threat Signaling (DOTS) Signal 3642 Channel Call Home", draft-ietf-dots-signal-call-home-08 3643 (work in progress), March 2020. 3645 [I-D.ietf-dots-signal-channel] 3646 Reddy.K, T., Boucadair, M., Patil, P., Mortensen, A., and 3647 N. Teague, "Distributed Denial-of-Service Open Threat 3648 Signaling (DOTS) Signal Channel Specification", draft- 3649 ietf-dots-signal-channel-41 (work in progress), January 3650 2020. 3652 [I-D.ietf-dots-signal-filter-control] 3653 Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 3654 "Controlling Filtering Rules Using Distributed Denial-of- 3655 Service Open Threat Signaling (DOTS) Signal Channel", 3656 draft-ietf-dots-signal-filter-control-03 (work in 3657 progress), March 2020. 3659 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3660 Requirement Levels", BCP 14, RFC 2119, 3661 DOI 10.17487/RFC2119, March 1997, 3662 . 3664 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3665 DOI 10.17487/RFC3688, January 2004, 3666 . 3668 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3669 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3670 . 3672 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3673 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3674 October 2013, . 3676 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3677 Application Protocol (CoAP)", RFC 7641, 3678 DOI 10.17487/RFC7641, September 2015, 3679 . 3681 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3682 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3683 . 3685 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 3686 the Constrained Application Protocol (CoAP)", RFC 7959, 3687 DOI 10.17487/RFC7959, August 2016, 3688 . 3690 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3691 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3692 May 2017, . 3694 15.2. Informative References 3696 [I-D.ietf-dots-multihoming] 3697 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 3698 Deployment Considerations for Distributed-Denial-of- 3699 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 3700 multihoming-03 (work in progress), January 2020. 3702 [I-D.ietf-dots-use-cases] 3703 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 3704 L., and K. Nishizuka, "Use cases for DDoS Open Threat 3705 Signaling", draft-ietf-dots-use-cases-20 (work in 3706 progress), September 2019. 3708 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 3709 "Framework for IP Performance Metrics", RFC 2330, 3710 DOI 10.17487/RFC2330, May 1998, 3711 . 3713 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3714 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3715 . 3717 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 3718 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 3719 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 3720 2018, . 3722 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 3723 Threat Signaling (DOTS) Requirements", RFC 8612, 3724 DOI 10.17487/RFC8612, May 2019, 3725 . 3727 Authors' Addresses 3729 Mohamed Boucadair (editor) 3730 Orange 3731 Rennes 35000 3732 France 3734 Email: mohamed.boucadair@orange.com 3736 Tirumaleswar Reddy (editor) 3737 McAfee, Inc. 3738 Embassy Golf Link Business Park 3739 Bangalore, Karnataka 560071 3740 India 3742 Email: kondtir@gmail.com 3743 Ehud Doron 3744 Radware Ltd. 3745 Raoul Wallenberg Street 3746 Tel-Aviv 69710 3747 Israel 3749 Email: ehudd@radware.com 3751 Meiling Chen 3752 CMCC 3753 32, Xuanwumen West 3754 BeiJing, BeiJing 100053 3755 China 3757 Email: chenmeiling@chinamobile.com