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