idnits 2.17.1 draft-ietf-dots-telemetry-01.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 84 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 839 has weird spacing: '...apacity uin...' == Line 1130 has weird spacing: '...er-port ine...' == Line 1297 has weird spacing: '...er-port ine...' == Line 1352 has weird spacing: '...er-port ine...' == Line 1398 has weird spacing: '...er-port ine...' == (1 more instance...) -- The document date (January 31, 2020) is 1545 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 2960, but not defined -- Possible downref: Non-RFC (?) normative reference: ref. 'Enterprise-Numbers' == Outdated reference: A later version (-14) exists of draft-ietf-dots-signal-call-home-07 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-07) exists of draft-ietf-dots-signal-filter-control-02 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-20 Summary: 2 errors (**), 0 flaws (~~), 11 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: August 3, 2020 McAfee 6 E. Doron 7 Radware Ltd. 8 M. Chen 9 CMCC 10 January 31, 2020 12 Distributed Denial-of-Service Open Threat Signaling (DOTS) Telemetry 13 draft-ietf-dots-telemetry-01 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 August 3, 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. YANG Considerations . . . . . . . . . . . . . . . . . . . 10 72 4.7. A Note About Examples . . . . . . . . . . . . . . . . . . 10 73 5. Telemetry Operation Paths . . . . . . . . . . . . . . . . . . 10 74 6. DOTS Telemetry Setup and Configuration . . . . . . . . . . . 11 75 6.1. Telemetry Configuration . . . . . . . . . . . . . . . . . 12 76 6.1.1. Retrieve Current DOTS Telemetry Configuration . . . . 12 77 6.1.2. Convey DOTS Telemetry Configuration . . . . . . . . . 15 78 6.1.3. Retrieve Installed DOTS Telemetry Configuration . . . 18 79 6.1.4. Delete DOTS Telemetry Configuration . . . . . . . . . 19 80 6.2. Total Pipe Capacity . . . . . . . . . . . . . . . . . . . 19 81 6.2.1. Convey DOTS Client Domain Pipe Capacity . . . . . . . 20 82 6.2.2. Retrieve DOTS Client Domain Pipe Capacity . . . . . . 25 83 6.2.3. Delete DOTS Client Domain Pipe Capacity . . . . . . . 25 84 6.3. Telemetry Baseline . . . . . . . . . . . . . . . . . . . 26 85 6.3.1. Convey DOTS Client Domain Baseline Information . . . 29 86 6.3.2. Retrieve Normal Traffic Baseline . . . . . . . . . . 30 87 6.3.3. Retrieve Normal Traffic Baseline . . . . . . . . . . 30 88 6.4. Reset Installed Telemetry Setup and Configuration . . . . 31 89 6.5. Conflict with Other DOTS Clients of the Same Domain . . . 31 90 7. DOTS Telemetry from Clients to Servers . . . . . . . . . . . 31 91 7.1. Pre-mitigation DOTS Telemetry Attributes . . . . . . . . 32 92 7.1.1. Total Traffic . . . . . . . . . . . . . . . . . . . . 33 93 7.1.2. Total Attack Traffic . . . . . . . . . . . . . . . . 34 94 7.1.3. Total Attack Connections . . . . . . . . . . . . . . 35 95 7.1.4. Attack Details . . . . . . . . . . . . . . . . . . . 36 96 7.2. DOTS Client to Server Mitigation Efficacy DOTS Telemetry 97 Attributes . . . . . . . . . . . . . . . . . . . . . . . 39 98 7.3. Sample Examples . . . . . . . . . . . . . . . . . . . . . 40 99 7.3.1. Single Pre-Mitigation . . . . . . . . . . . . . . . . 40 100 7.3.2. Multiple Pre-Mitigations . . . . . . . . . . . . . . 40 101 7.3.3. Top-Talker of Targets . . . . . . . . . . . . . . . . 40 102 7.3.4. Top-Talker of Each Target . . . . . . . . . . . . . . 40 103 8. DOTS Telemetry from Servers to Clients . . . . . . . . . . . 40 104 8.1. DOTS Server to Client Mitigation Status DOTS Telemetry 105 Attributes . . . . . . . . . . . . . . . . . . . . . . . 40 106 8.1.1. Mitigation Status . . . . . . . . . . . . . . . . . . 42 107 8.2. DOTS Detector to Clients Detection Telemetry . . . . . . 43 108 9. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 43 109 10. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 63 110 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 65 111 11.1. DOTS Signal Channel CBOR Key Values . . . . . . . . . . 65 112 11.2. DOTS Signal Channel Conflict Cause Codes . . . . . . . . 66 113 11.3. DOTS Signal Telemetry YANG Module . . . . . . . . . . . 67 114 12. Security Considerations . . . . . . . . . . . . . . . . . . . 67 115 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 67 116 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 67 117 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 68 118 15.1. Normative References . . . . . . . . . . . . . . . . . . 68 119 15.2. Informative References . . . . . . . . . . . . . . . . . 69 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 122 1. Introduction 124 Distributed Denial of Service (DDoS) attacks have become more vicious 125 and sophisticated in almost all aspects of their maneuvers and 126 malevolent intentions. IT organizations and service providers are 127 facing DDoS attacks that fall into two broad categories: Network/ 128 Transport layer attacks and Application layer attacks: 130 o Network/Transport layer attacks target the victim's 131 infrastructure. These attacks are not necessarily aimed at taking 132 down the actual delivered services, but rather to eliminate 133 various network elements (routers, switches, firewalls, transit 134 links, and so on) from serving legitimate user traffic. 136 The main method of such attacks is to send a large volume or high 137 PPS of traffic toward the victim's infrastructure. Typically, 138 attack volumes may vary from a few 100 Mbps/PPS to 100s of Gbps or 139 even Tbps. Attacks are commonly carried out leveraging botnets 140 and attack reflectors for amplification attacks such as NTP 141 (Network Time Protocol), DNS (Domain Name System), SNMP (Simple 142 Network Management Protocol), or SSDP (Simple Service Discovery 143 Protoco). 145 o Application layer attacks target various applications. Typical 146 examples include attacks against HTTP/HTTPS, DNS, SIP (Session 147 Initiation Protocol), or SMTP (Simple Mail Transfer Protocol). 148 However, all valid applications with their port numbers open at 149 network edges can be attractive attack targets. 151 Application layer attacks are considered more complex and hard to 152 categorize, therefore harder to detect and mitigate efficiently. 154 To compound the problem, attackers also leverage multi-vectored 155 attacks. These attacks are assembled from dynamic attack vectors 156 (Network/Application) and tactics. As such, multiple attack vectors 157 formed by multiple attack types and volumes are launched 158 simultaneously towards a victim. Multi-vector attacks are harder to 159 detect and defend. Multiple and simultaneous mitigation techniques 160 are needed to defeat such attack campaigns. It is also common for 161 attackers to change attack vectors right after a successful 162 mitigation, burdening their opponents with changing their defense 163 methods. 165 The ultimate conclusion derived from these real scenarios is that 166 modern attacks detection and mitigation are most certainly 167 complicated and highly convoluted tasks. They demand a comprehensive 168 knowledge of the attack attributes, the targeted normal behavior/ 169 traffic patterns, as well as the attacker's on-going and past 170 actions. Even more challenging, retrieving all the analytics needed 171 for detecting these attacks is not simple to obtain with the 172 industry's current capabilities. 174 The DOTS signal channel protocol [I-D.ietf-dots-signal-channel] is 175 used to carry information about a network resource or a network (or a 176 part thereof) that is under a DDoS attack. Such information is sent 177 by a DOTS client to one or multiple DOTS servers so that appropriate 178 mitigation actions are undertaken on traffic deemed suspicious. 179 Various use cases are discussed in [I-D.ietf-dots-use-cases]. 181 Typically, DOTS clients can be integrated within a DDoS attack 182 detector, or network and security elements that have been actively 183 engaged with ongoing attacks. The DOTS client mitigation environment 184 determines that it is no longer possible or practical for it to 185 handle these attacks. This can be due to lack of resources or 186 security capabilities, as derived from the complexities and the 187 intensity of these attacks. In this circumstance, the DOTS client 188 has invaluable knowledge about the actual attacks that need to be 189 handled by the DOTS server. By enabling the DOTS client to share 190 this comprehensive knowledge of an ongoing attack under specific 191 circumstances, the DOTS server can drastically increase its abilities 192 to accomplish successful mitigation. While the attack is being 193 handled by the DOTS server associated mitigation resources, the DOTS 194 server has the knowledge about the ongoing attack mitigation. The 195 DOTS server can share this information with the DOTS client so that 196 the client can better assess and evaluate the actual mitigation 197 realized. 199 In some deployments, DOTS clients can send mitigation hints derived 200 from attack details to DOTS servers, with the full understanding that 201 the DOTS server may ignore mitigation hints, as described in 202 [RFC8612] (Gen-004). Mitigation hints will be transmitted across the 203 DOTS signal channel, as the data channel may not be functional during 204 an attack. How a DOTS server is handling normal and attack traffic 205 attributes, and mitigation hints is implementation-specific. 207 Both DOTS client and server can benefit this information by 208 presenting various information in relevant management, reporting, and 209 portal systems. 211 This document defines DOTS telemetry attributes the DOTS client can 212 convey to the DOTS server, and vice versa. The DOTS telemetry 213 attributes are not mandatory fields. Nevertheless, when DOTS 214 telemetry attributes are available to a DOTS agent, and absent any 215 policy, it can signal the attributes in order to optimize the overall 216 mitigation service provisioned using DOTS. Some of the DOTS 217 telemetry data is not shared during an attack time. 219 2. Terminology 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 223 "OPTIONAL" in this document are to be interpreted as described in BCP 224 14 [RFC2119][RFC8174] when, and only when, they appear in all 225 capitals, as shown here. 227 The reader should be familiar with the terms defined in [RFC8612]. 229 "DOTS Telemetry" is defined as the collection of attributes that are 230 used to characterize normal traffic baseline, attacks and their 231 mitigation measures, and any related information that may help in 232 enforcing countermeasures. The DOTS Telemetry is an optional set of 233 attributes that can be signaled in the DOTS signal channel protocol. 235 The meaning of the symbols in YANG tree diagrams is defined in 236 [RFC8340]. 238 3. DOTS Telemetry: Overview and Purpose 240 When signaling a mitigation request, it is most certainly beneficial 241 for the DOTS client to signal to the DOTS server any knowledge 242 regarding ongoing attacks. This can happen in cases where DOTS 243 clients are asking the DOTS server for support in defending against 244 attacks that they have already detected and/or mitigated. These 245 actions taken by DOTS clients are referred to as "signaling the DOTS 246 Telemetry". 248 If attacks are already detected and categorized by the DOTS client 249 domain, the DOTS server, and its associated mitigation services, can 250 proactively benefit this information and optimize the overall service 251 delivered. It is important to note that DOTS client and server 252 detection and mitigation approaches can be different, and can 253 potentially outcome different results and attack classifications. 254 The DDoS mitigation service treats the ongoing attack details from 255 the client as hints and cannot completely rely or trust the attack 256 details conveyed by the DOTS client. 258 A basic requirement of security operation teams is to be aware and 259 get visibility into the attacks they need to handle. The DOTS server 260 security operation teams benefit from the DOTS telemetry, especially 261 from the reports of ongoing attacks. Even if some mitigation can be 262 automated, operational teams can use the DOTS telemetry to be 263 prepared for attack mitigation and to assign the correct resources 264 (operation staff, networking and mitigation) for the specific 265 service. Similarly, security operation personnel at the DOTS client 266 side ask for feedback about their requests for protection. 267 Therefore, it is valuable for the DOTS server to share DOTS telemetry 268 with the DOTS client. 270 Thus mutual sharing of information is crucial for "closing the 271 mitigation loop" between the DOTS client and server. For the server 272 side team, it is important to realize that the same attacks that the 273 DOTS server's mitigation resources are seeing are those that the DOTS 274 client is asking to mitigate. For the DOTS client side team, it is 275 important to realize that the DOTS clients receive the required 276 service. For example: understanding that "I asked for mitigation of 277 two attacks and my DOTS server detects and mitigates only one...". 278 Cases of inconsistency in attack classification between DOTS client 279 and server can be high-lighted, and maybe handled, using the DOTS 280 telemetry attributes. 282 In addition, management and orchestration systems, at both DOTS 283 client and server sides, can potentially use DOTS telemetry as a 284 feedback to automate various control and management activities 285 derived from ongoing information signaled. 287 If the DOTS server's mitigation resources have the capabilities to 288 facilitate the DOTS telemetry, the DOTS server adopts its protection 289 strategy and activates the required countermeasures immediately 290 (automation enabled). The overall results of this adoption are 291 optimized attack mitigation decisions and actions. 293 The DOTS telemetry can also be used to tune the DDoS mitigators with 294 the correct state of the attack. During the last few years, DDoS 295 attack detection technologies have evolved from threshold-based 296 detection (that is, cases when all or specific parts of traffic cross 297 a pre-defined threshold for a certain period of time is considered as 298 an attack) to an "anomaly detection" approach. In anomaly detection, 299 the main idea is to maintain rigorous learning of "normal" behavior 300 and where an "anomaly" (or an attack) is identified and categorized 301 based on the knowledge about the normal behavior and a deviation from 302 this normal behavior. Machine learning approaches are used such that 303 the actual "traffic thresholds" are "automatically calculated" by 304 learning the protected entity normal traffic behavior during peace 305 time. The normal traffic characterization learned is referred to as 306 the "normal traffic baseline". An attack is detected when the 307 victim's actual traffic is deviating from this normal baseline. 309 In addition, subsequent activities toward mitigating an attack are 310 much more challenging. The ability to distinguish legitimate traffic 311 from attacker traffic on a per packet basis is complex. This 312 complexity originates from the fact that the packet itself may look 313 "legitimate" and no attack signature can be identified. The anomaly 314 can be identified only after detailed statistical analysis. DDoS 315 attack mitigators use the normal baseline during the mitigation of an 316 attack to identify and categorize the expected appearance of a 317 specific traffic pattern. Particularly the mitigators use the normal 318 baseline to recognize the "level of normality" needs to be achieved 319 during the various mitigation process. 321 Normal baseline calculation is performed based on continuous learning 322 of the normal behavior of the protected entities. The minimum 323 learning period varies from hours to days and even weeks, depending 324 on the protected application behavior. The baseline cannot be 325 learned during active attacks because attack conditions do not 326 characterize the protected entities' normal behavior. 328 If the DOTS client has calculated the normal baseline of its 329 protected entities, signaling this attribute to the DOTS server along 330 with the attack traffic levels is significantly valuable. The DOTS 331 server benefits from this telemetry by tuning its mitigation 332 resources with the DOTS client's normal baseline. The DOTS server 333 mitigators use the baseline to familiarize themselves with the attack 334 victim's normal behavior and target the baseline as the level of 335 normality they need to achieve. Consequently, the overall mitigation 336 performances obtained are dramatically improved in terms of time to 337 mitigate, accuracy, false-negative, false-positive, and other 338 measures. 340 Mitigation of attacks without having certain knowledge of normal 341 traffic can be inaccurate at best. This is especially true for 342 recursive signaling (see Section 3.2.3 in [I-D.ietf-dots-use-cases]). 343 In addition, the highly diverse types of use-cases where DOTS clients 344 are integrated also emphasize the need for knowledge of client 345 behavior. Consequently, common global thresholds for attack 346 detection practically cannot be realized. Each DOTS client can have 347 its own levels of traffic and normal behavior. Without facilitating 348 normal baseline signaling, it may be very difficult for DOTS servers 349 in some cases to detect and mitigate the attacks accurately: 351 It is important to emphasize that it is practically impossible for 352 the server's mitigators to calculate the normal baseline, in cases 353 they do not have any knowledge of the traffic beforehand. 355 In addition, baseline learning requires a period of time that 356 cannot be afforded during active attack. 358 Of course, this information can provided using out-of-band 359 mechanisms or manual configuration at the risk to maintain 360 inaccurate information as the network evolves and "normal" 361 patterns change. The use of a dynamic and collaborative means 362 between the DOTS client and server to identify and share key 363 parameters for the sake of efficient DDoS protect is valuable. 365 During a high volume attack, DOTS client pipes can be totally 366 saturated. The DOTS client asks the DOTS server to handle the attack 367 upstream so that DOTS client pipes return to a reasonable load level 368 (normal pattern, ideally). At this point, it is essential to ensure 369 that the mitigator does not overwhelm the DOTS client pipes by 370 sending back "clean traffic", or what it believes is "clean". This 371 can happen when the mitigator has not managed to detect and mitigate 372 all the attacks launched towards the client. In this case, it can be 373 valuable to clients to signal to server the "Total pipe capacity", 374 which is the level of traffic the DOTS client domain can absorb from 375 the upstream network. Dynamic updating of the condition of pipes 376 between DOTS agents while they are under a DDoS attack is essential. 377 For example, for cases of multiple DOTS clients share the same 378 physical connectivity pipes. It is important to note, that the term 379 "pipe" noted here does not necessary represent physical pipe, but 380 rather represents the current level of traffic client can observe 381 from server. The server should activate other mechanisms to ensure 382 it does not saturate the client's pipes unintentionally. The rate- 383 limit action defined in [I-D.ietf-dots-data-channel] is a reasonable 384 candidate to achieve this objective; the client can ask for the type 385 of traffic (such as ICMP, UDP, TCP port number 80) it prefers to 386 limit. The rate-limit action can be controlled via the signal- 387 channel [I-D.ietf-dots-signal-filter-control] even when the pipe is 388 overwhelmed. 390 To summarize: 392 Timely and effective signaling of up-to-date DOTS telemetry to all 393 elements involved in the mitigation process is essential and 394 absolutely improves the overall service effectiveness. Bi- 395 directional feedback between DOTS agents is required for the 396 increased awareness of each party, supporting superior and highly 397 efficient attack mitigation service. 399 4. Generic Considerations 401 4.1. DOTS Client Identification 403 Following the rules in [I-D.ietf-dots-signal-channel], a unique 404 identifier is generated by a DOTS client to prevent request 405 collisions. 407 4.2. DOTS Gateways 409 DOTS gateways may be located between DOTS clients and servers. The 410 considerations elaborated in [I-D.ietf-dots-signal-channel] must be 411 followed. In particular, 'cdid' attribute is used to unambiguously 412 identify a DOTS client domain. 414 4.3. Empty URI Paths 416 Uri-Path parameters with empty values MUST NOT be present in DOTS 417 telemetry requests. 419 4.4. Controlling Configuration Data 421 The DOTS server follows the same considerations discussed in 422 Section of 4.5.3 of [I-D.ietf-dots-signal-channel] for managing DOTS 423 telemetry configuration freshness and notification. Likewise, a DOTS 424 client may control the selection of configuration and non- 425 configuration data nodes when sending a GET request by means of the 426 'c' Uri-Query option and following the procedure specified in 427 Section of 4.4.2 of [I-D.ietf-dots-signal-channel]. These 428 considerations are not re-iterated in the following sections. 430 4.5. Block-wise Transfer 432 DOTS clients can use Block-wise transfer [RFC7959] with the 433 recommendation detailed in Section 4.4.2 of 434 [I-D.ietf-dots-signal-channel] to control the size of a response when 435 the data to be returned does not fit within a single datagram. 437 DOTS clients can also use Block1 Option in a PUT request (see 438 Section 2.5 of [RFC7959]). 440 o NOTE: Add more details. 442 4.6. YANG Considerations 444 Messages exchanged between DOTS agents are serialized using Concise 445 Binary Object Representation (CBOR). CBOR-encoded payloads are used 446 to carry signal channel-specific payload messages which convey 447 request parameters and response information such as errors 448 [I-D.ietf-dots-signal-channel]. 450 This document specifies a YANG module for representing DOTS telemetry 451 message types (Section 9). All parameters in the payload of the DOTS 452 signal channel are mapped to CBOR types as specified in Section 10. 454 4.7. A Note About Examples 456 Examples are provided for illustration purposes. The document does 457 not aim to provide a comprehensive list of message examples. 459 The authoritative reference for validating telemetry messages is the 460 YANG module (Section 9) and the mapping table established in 461 Section 10. 463 5. Telemetry Operation Paths 465 As discussed in [I-D.ietf-dots-signal-channel], each DOTS operation 466 is indicated by a path-suffix that indicates the intended operation. 467 The operation path is appended to the path-prefix to form the URI 468 used with a CoAP request to perform the desired DOTS operation. The 469 following telemetry path-suffixes are defined (Table 1): 471 +-----------------+----------------+-------------+ 472 | Operation | Operation Path | Details | 473 +-----------------+----------------+-------------+ 474 | Telemetry Setup | /tm-setup | Section 6 | 475 | Telemetry | /tm | Section 7.1 | 476 +-----------------+----------------+-------------+ 478 Table 1: DOTS Telemetry Operations 480 Consequently, the "ietf-dots-telemetry" YANG module defined in this 481 document augments the "ietf-dots-signal" with two new message types 482 called "telemetry-setup" and "telemetry". The tree structure of the 483 "telemetry-setup" message type is shown below (more details are 484 provided in the following sections about the exact structure of 485 "telemetry-setup" and "telemetry" message types). 487 augment /ietf-signal:dots-signal/ietf-signal:message-type: 488 +--:(telemetry-setup) {dots-telemetry}? 489 | ... 490 | +--rw (setup-type)? 491 | +--:(telemetry-config) 492 | | ... 493 | +--:(pipe) 494 | | ... 495 | +--:(baseline) 496 | ... 497 +--:(telemetry) {dots-telemetry}? 498 ... 500 Figure 1: New DOTS Message Types (YANG Tree Structure) 502 6. DOTS Telemetry Setup and Configuration 504 In reference to Figure 1, a DOTS telemetry setup message MUST include 505 only telemetry-related configuration parameters (Section 6.1) or 506 information about DOTS client domain pipe capacity (Section 6.2) or 507 telemetry traffic baseline (Section 6.3). As such, requests that 508 include a mix of telemetry configuration, pipe capacity, or traffic 509 baseline MUST be rejected by DOTS servers with a 4.00 (Bad Request). 511 A DOTS client can reset all installed DOTS telemetry setup and 512 configuration data following the considerations detailed in 513 Section 6.4. 515 A DOTS server may detect conflicts when processing requests related 516 to DOTS client domain pipe capacity or telemetry traffic baseline 517 with requests from other DOTS clients of the same DOTS client domain. 518 More details are included in Section 6.5. 520 DOTS telemetry setup and configuration request and response messages 521 are marked as Confirmable messages. 523 6.1. Telemetry Configuration 525 A DOTS client can negotiate with its server(s) a set of telemetry 526 configuration parameters to be used for telemetry. Such parameters 527 include: 529 o Percentile-related measurement parameters 531 o Measurement units 533 o Acceptable percentile values 535 o Telemetry notification interval 537 o Acceptable Server-initiated pre-mitigation telemetry 539 Section 11.3 of [RFC2330] includes more details about computing 540 percentiles. 542 6.1.1. Retrieve Current DOTS Telemetry Configuration 544 A GET request is used to obtain acceptable and current telemetry 545 configuration parameters on the DOTS server. This request may 546 include a 'cdid' Path-URI when the request is relayed by a DOTS 547 gateway. An example of such request is depicted in Figure 2. 549 Header: GET (Code=0.01) 550 Uri-Path: ".well-known" 551 Uri-Path: "dots" 552 Uri-Path: "tm-setup" 553 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 555 Figure 2: GET to Retrieve Current and Acceptable DOTS Telemetry 556 Configuration 558 Upon receipt of such request, the DOTS server replies with a 2.05 559 (Content) response that conveys the current and telemetry parameters 560 acceptable by the DOTS server. The tree structure of the response 561 message body is provided in Figure 3. Note that the response 562 includes also any pipe (Section 6.2) and baseline information 563 (Section 6.3) maintained by the DOTS server for this DOTS client. 565 DOTS servers that support the capability of sending pre-mitigation 566 telemetry information to DOTS clients (Section 8) sets 'server- 567 initiated-telemetry' under 'max-config-values' to 'true' ('false' is 568 used otherwise). If 'server-initiated-telemetry' is not present in a 569 response, this is equivalent to receiving a request with 'server- 570 initiated-telemetry'' set to 'false'. 572 augment /ietf-signal:dots-signal/ietf-signal:message-type: 573 +--:(telemetry-setup) {dots-telemetry}? 574 | +--rw telemetry* [cuid tsid] 575 | ... 576 | +--rw (setup-type)? 577 | +--:(telemetry-config) 578 | | +--rw current-config 579 | | | +--rw measurement-interval? interval 580 | | | +--rw measurement-sample? sample 581 | | | +--rw low-percentile? percentile 582 | | | +--rw mid-percentile? percentile 583 | | | +--rw high-percentile? percentile 584 | | | +--rw unit-config* [unit] 585 | | | | +--rw unit unit 586 | | | | +--rw unit-status? boolean 587 | | | +--rw server-initiated-telemetry? boolean 588 | | | +--rw telemetry-notify-interval? uint32 589 | | +--ro max-config-values 590 | | | +--ro measurement-interval? interval 591 | | | +--ro measurement-sample? sample 592 | | | +--ro low-percentile? percentile 593 | | | +--ro mid-percentile? percentile 594 | | | +--ro high-percentile? percentile 595 | | | +--ro server-initiated-telemetry? boolean 596 | | | +--ro telemetry-notify-interval? uint32 597 | | +--ro min-config-values 598 | | | +--ro measurement-interval? interval 599 | | | +--ro measurement-sample? sample 600 | | | +--ro low-percentile? percentile 601 | | | +--ro mid-percentile? percentile 602 | | | +--ro high-percentile? percentile 603 | | | +--ro telemetry-notify-interval? uint32 604 | | +--ro supported-units 605 | | +--ro unit-config* [unit] 606 | | +--ro unit unit 607 | | +--ro unit-status? boolean 608 | +--:(pipe) 609 | ... 610 | +--:(baseline) 611 | ... 612 +--:(telemetry) {dots-telemetry}? 613 +--rw pre-mitigation* [cuid id] 614 ... 616 Figure 3: Telemetry Configuration Tree Structure 618 6.1.2. Convey DOTS Telemetry Configuration 620 PUT request is used to convey the configuration parameters for the 621 telemetry data (e.g., low, mid, or high percentile values). For 622 example, a DOTS client may contact its DOTS server to change the 623 default percentile values used as baseline for telemetry data. 624 Figure 3 lists the attributes that can be set by a DOTS client in 625 such PUT request. An example of a DOTS client that modifies all 626 percentile reference values is shown in Figure 4. 628 Header: PUT (Code=0.03) 629 Uri-Path: ".well-known" 630 Uri-Path: "dots" 631 Uri-Path: "tm-setup" 632 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 633 Uri-Path: "tsid=123" 634 Content-Format: "application/dots+cbor" 636 { 637 "ietf-dots-signal-channel:telemetry-setup": { 638 "telemetry": [ 639 { 640 "current-config": { 641 "low-percentile": 5.00, 642 "mid-percentile": 65.00, 643 "high-percentile": 95.00 644 } 645 } 646 ] 647 } 648 } 650 Figure 4: PUT to Convey the DOTS Telemetry Configuration 652 'cuid' is a mandatory Uri-Path parameter for PUT requests. 654 The following additional Uri-Path parameter is defined: 656 tsid: Telemetry Setup Identifier is an identifier for the DOTS 657 telemetry setup and configuration data represented as an 658 integer. This identifier MUST be generated by DOTS clients. 659 'tsid' values MUST increase monotonically (when a new PUT is 660 generated by a DOTS client to convey new configuration 661 parameters for the telemetry). 663 This is a mandatory attribute. 665 At least one configurable attribute MUST be present in the PUT 666 request. 668 Attributes and Uri-Path parameters with empty values MUST NOT be 669 present in a request and render the entire request invalid. 671 The PUT request with a higher numeric 'tsid' value overrides the DOTS 672 telemetry configuration data installed by a PUT request with a lower 673 numeric 'tsid' value. To avoid maintaining a long list of 'tsid' 674 requests for requests carrying telemetry configuration data from a 675 DOTS client, the lower numeric 'tsid' MUST be automatically deleted 676 and no longer available at the DOTS server. 678 The DOTS server indicates the result of processing the PUT request 679 using the following response codes: 681 o If the request is missing a mandatory attribute, does not include 682 'cuid' or 'tsid' Uri-Path parameters, or contains one or more 683 invalid or unknown parameters, 4.00 (Bad Request) MUST be returned 684 in the response. 686 o If the DOTS server does not find the 'tsid' parameter value 687 conveyed in the PUT request in its configuration data and if the 688 DOTS server has accepted the configuration parameters, then a 689 response code 2.01 (Created) MUST be returned in the response. 691 o If the DOTS server finds the 'tsid' parameter value conveyed in 692 the PUT request in its configuration data and if the DOTS server 693 has accepted the updated configuration parameters, 2.04 (Changed) 694 MUST be returned in the response. 696 o If any of the enclosed configurable attribute values are not 697 acceptable to the DOTS server (Section 6.1.1), 4.22 (Unprocessable 698 Entity) MUST be returned in the response. 700 The DOTS client may re-try and send the PUT request with updated 701 attribute values acceptable to the DOTS server. 703 Setting 'low-percentile' to '0.00' indicates that the DOTS client is 704 not interested in receiving low-percentiles. Likewise, setting 'mid- 705 percentile' (or 'high-percentile') to the same value as 'low- 706 percentile' (or 'mid-percentile') indicates that the DOTS client is 707 not interested in receiving mid-percentiles (or high-percentiles). 708 For example, a DOTS client can send the request depicted in Figure 5 709 to inform the server that it is interested in receiving only high- 710 percentiles. This assumes that the client will only use that 711 percentile type when sharing telemetry data with the server. 713 Header: PUT (Code=0.03) 714 Uri-Path: ".well-known" 715 Uri-Path: "dots" 716 Uri-Path: "tm-setup" 717 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 718 Uri-Path: "tsid=569" 719 Content-Format: "application/dots+cbor" 721 { 722 "ietf-dots-signal-channel:telemetry-setup": { 723 "telemetry": [ 724 { 725 "current-config": { 726 "low-percentile": 0.00, 727 "mid-percentile": 0.00, 728 "high-percentile": 95.00 729 } 730 } 731 ] 732 } 733 } 735 Figure 5: PUT to Disable Low- and Mid-Percentiles 737 DOTS clients that are interested to receive pre-mitigation telemetry 738 information from a DOTS server (Section 8) MUST set 'server- 739 initiated-telemetry' to 'true'. If 'server-initiated-telemetry' is 740 not present in a PUT request, this is equivalent to receiving a 741 request with 'server-initiated-telemetry'' set to 'false'. An 742 example of a reques to enable pre-mitigation telemetry from DOTS 743 servers is shown in Figure 6. 745 Header: PUT (Code=0.03) 746 Uri-Path: ".well-known" 747 Uri-Path: "dots" 748 Uri-Path: "tm-setup" 749 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 750 Uri-Path: "tsid=569" 751 Content-Format: "application/dots+cbor" 753 { 754 "ietf-dots-signal-channel:telemetry-setup": { 755 "telemetry": [ 756 { 757 "current-config": { 758 "server-initiated-telemetry": true 759 } 760 } 761 ] 762 } 763 } 765 Figure 6: PUT to Enable Pre-mitigation Telemetry from the DOTS server 767 o Note 1: Consider adding examples where signaling link aggregates 768 is sufficient.? 770 o Note 2: Which target prefix to communicate in the baseline/pipe 771 depends on the location of the DOTS server. For example, if both 772 upstream networks exposes a DOTS server; only information related 773 to prefixes assigned by that upstream network to the DOTS client 774 domain will be signalled. Consider adding a reference to the DOTS 775 Multihoming draft. 777 6.1.3. Retrieve Installed DOTS Telemetry Configuration 779 A DOTS client may issue a GET message with 'tsid' Uri-Path parameter 780 to retrieve the current DOTS telemetry configuration. An example of 781 such request is depicted in Figure 7. 783 Header: GET (Code=0.01) 784 Uri-Path: ".well-known" 785 Uri-Path: "dots" 786 Uri-Path: "tm-setup" 787 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 788 Uri-Path: "tsid=123" 790 Figure 7: GET to Retrieve Current DOTS Telemetry Configuration 792 If the DOTS server does not find the 'tsid' Uri-Path value conveyed 793 in the GET request in its configuration data for the requesting DOTS 794 client, it MUST respond with a 4.04 (Not Found) error response code. 796 6.1.4. Delete DOTS Telemetry Configuration 798 A DELETE request is used to delete the installed DOTS telemetry 799 configuration data (Figure 8). 'cuid' and 'tsid' are mandatory Uri- 800 Path parameters for such DELETE requests. 802 Header: DELETE (Code=0.04) 803 Uri-Path: ".well-known" 804 Uri-Path: "dots" 805 Uri-Path: "tm-setup" 806 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 807 Uri-Path: "tsid=123" 809 Figure 8: Delete Telemetry Configuration 811 If the DELETE request does not include 'cuid' and 'tsid' parameters, 812 the DOTS server MUST reply with a 4.00 (Bad Request). 814 The DOTS server resets the DOTS telemetry configuration back to the 815 default values and acknowledges a DOTS client's request to remove the 816 DOTS telemetry configuration using 2.02 (Deleted) response code. A 817 2.02 (Deleted) Response Code is returned even if the 'tsid' parameter 818 value conveyed in the DELETE request does not exist in its 819 configuration data before the request. 821 6.2. Total Pipe Capacity 823 A DOTS client can communicate to its server(s) its DOTS client domain 824 pipe information. The tree structure of the pipe information is 825 shown in Figure 9. 827 augment /ietf-signal:dots-signal/ietf-signal:message-type: 828 +--:(telemetry-setup) {dots-telemetry}? 829 | +--rw telemetry* [cuid tsid] 830 | +--rw cuid string 831 | +--rw cdid? string 832 | +--rw tsid uint32 833 | +--rw (setup-type)? 834 | +--:(telemetry-config) 835 | | ... 836 | +--:(pipe) 837 | | +--rw total-pipe-capacity* [link-id unit] 838 | | +--rw link-id nt:link-id 839 | | +--rw capacity uint64 840 | | +--rw unit unit 841 | +--:(baseline) 842 | ... 843 +--:(telemetry) {dots-telemetry}? 844 +--rw pre-mitigation* [cuid id] 845 ... 847 Figure 9: Pipe Tree Structure 849 A DOTS client domain pipe is defined as a list of limits of 850 (incoming) traffic volume (total-pipe-capacity") that can be 851 forwarded over ingress interconnection links fo a DOTS client domain. 852 Each of these links is identified with a "link-id" [RFC8345]. 854 This limit can be expressed in packets per second (PPS) or kilo 855 packets per second (Kpps) and Bits per Second (BPS), and in kilobytes 856 per second or megabytes per second or gigabytes per second. The unit 857 used by a DOTS client when conveying pipe information is captured in 858 "unit" attribute. 860 6.2.1. Convey DOTS Client Domain Pipe Capacity 862 Similar considerations to those specified in Section 6.1.2 are 863 followed with one exception: 865 The relative order of two PUT requests carrying DOTS client domain 866 pipe attributes from a DOTS client is determined by comparing 867 their respective 'tsid' values. If such two requests have 868 overlapping "link-id" and "unit", the PUT request with higher 869 numeric 'tsid' value will override the request with a lower 870 numeric 'tsid' value. The overlapped lower numeric 'tsid' MUST be 871 automatically deleted and no longer. 873 DOTS clients SHOULD minimize the number of active "tsids" used for 874 pipe information. Typically, in order to avoid maintaining a long 875 list of "tsids" for pipe information, it is RECOMMENDED that DOTS 876 clients include in a request to update information related to a given 877 link, the information of other links (already communicated using a 878 lower 'tsid' value). Doing so, this update request will override 879 these existing requests and hence optimize the number of 'tsid" 880 request per DOTS client. 882 o Note: This assumes that all link information can fit in one single 883 message. 885 For example, a DOTS client managing a single homed domain (Figure 10) 886 can send a PUT request (shown in Figure 11) to communicate the 887 capacity of "link1" used to connected its ISP. 889 ,--,--,--. ,--,--,--. 890 ,-' `-. ,-' `-. 891 ( DOTS Client )=====( ISP#A ) 892 `-. Domain ,-' link1 `-. ,-' 893 `--'--'--' `--'--'--' 895 Figure 10: Single Homed DOTS Client Domain 897 Header: PUT (Code=0.03) 898 Uri-Path: ".well-known" 899 Uri-Path: "dots" 900 Uri-Path: "tm-setup" 901 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 902 Uri-Path: "tsid=457" 903 Content-Format: "application/dots+cbor" 905 { 906 "ietf-dots-signal-channel:telemetry-setup": { 907 "telemetry": [ 908 { 909 "total-pipe-capacity": [ 910 { 911 "link-id": "link1", 912 "capacity": 500, 913 "unit": "megabytes-ps" 914 } 915 ] 916 } 917 ] 918 } 919 } 921 Figure 11: Example of a PUT Request to Convey Pipe Information 922 (Single Homed) 924 Now consider that the DOTS client domain was upgraded to connect to 925 an additional ISP (ISP#B of Figure 12), the DOTS client can inform 926 the DOTS server about this update by sending the PUT request depicted 927 in Figure 13. This request includes also information related to 928 "link1" even if that link is not upgraded. Upon receipt of this 929 request, the DOTS server removes the request with "tsid=457" and 930 updates its configuration base to maintain two links (link#1 and 931 link#2). 933 ,--,--,--. 934 ,-' `-. 935 ( ISP#B ) 936 `-. ,-' 937 `--'--'--' 938 || 939 || link2 940 ,--,--,--. ,--,--,--. 941 ,-' `-. ,-' `-. 942 ( DOTS Client )=====( ISP#A ) 943 `-. Domain ,-' link1 `-. ,-' 944 `--'--'--' `--'--'--' 946 Figure 12: Multi-Homed DOTS Client Domain 948 Header: PUT (Code=0.03) 949 Uri-Path: ".well-known" 950 Uri-Path: "dots" 951 Uri-Path: "tm-setup" 952 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 953 Uri-Path: "tsid=458" 954 Content-Format: "application/dots+cbor" 956 { 957 "ietf-dots-signal-channel:telemetry-setup": { 958 "telemetry": [ 959 { 960 "total-pipe-capacity": [ 961 { 962 "link-id": "link1", 963 "capacity": 500, 964 "unit": "megabytes-ps" 965 }, 966 { 967 "link-id": "link2", 968 "capacity": 500, 969 "unit": "megabytes-ps" 970 } 971 ] 972 } 973 ] 974 } 975 } 977 Figure 13: Example of a PUT Request to Convey Pipe Information 978 (Multi-Homed) 980 A DOTS client can delete a link by sending a PUT request with the 981 capacity" attribute set to "0" if other links are still active for 982 the same DOTS client domain (see Section 6.2.3 for other delete 983 cases). For example, if a DOTS client domain re-homes (that is, it 984 changes it ISP), the DOTS client can inform the DOTS server about 985 this update (e.g., from the network configuration in Figure 10 to the 986 one shown in Figure 14) by sending the PUT request depicted in 987 Figure 15. Upon receipt of this request, the DOTS server removes 988 "link1" from its configuration bases for this DOTS client domain. 990 ,--,--,--. 991 ,-' `-. 992 ( ISP#B ) 993 `-. ,-' 994 `--'--'--' 995 || 996 || link2 997 ,--,--,--. 998 ,-' `-. 999 ( DOTS Client ) 1000 `-. Domain ,-' 1001 `--'--'--' 1003 Figure 14: Multi-Homed DOTS Client Domain 1005 Header: PUT (Code=0.03) 1006 Uri-Path: ".well-known" 1007 Uri-Path: "dots" 1008 Uri-Path: "tm-setup" 1009 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1010 Uri-Path: "tsid=459" 1011 Content-Format: "application/dots+cbor" 1013 { 1014 "ietf-dots-signal-channel:telemetry-setup": { 1015 "telemetry": [ 1016 { 1017 "total-pipe-capacity": [ 1018 { 1019 "link-id": "link1", 1020 "capacity": 0, 1021 "unit": "megabytes-ps" 1022 }, 1023 { 1024 "link-id": "link2", 1025 "capacity": 500, 1026 "unit": "megabytes-ps" 1027 } 1028 ] 1029 } 1030 ] 1031 } 1032 } 1034 Figure 15: Example of a PUT Request to Convey Pipe Information 1035 (Multi-Homed) 1037 6.2.2. Retrieve DOTS Client Domain Pipe Capacity 1039 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1040 specific installed DOTS client domain pipe related information. The 1041 that aim, the same procedure defined in (Section 6.1.3) is followed. 1043 To retrieve all pipe information bound to a DOTS client, the DOTS 1044 client proceeds as specified in Section 6.1.1. 1046 6.2.3. Delete DOTS Client Domain Pipe Capacity 1048 A DELETE request is used to delete the installed DOTS client domain 1049 pipe related information. The that aim, the same procedure defined 1050 in (Section 6.1.4) is followed. 1052 6.3. Telemetry Baseline 1054 A DOTS client can communicate to its server(s) its normal traffic 1055 baseline and total connections capacity: 1057 Total Traffic Normal Baseline: By default, the low percentile (10th 1058 percentile), mid percentile (50th percentile), high percentile 1059 (90th percentile), and peak values (100th percentile) of "Total 1060 traffic normal baselines" measured in packets per second (PPS) or 1061 kilo packets per second (Kpps) and Bits per Second (BPS), and 1062 kilobytes per second or megabytes per second or gigabytes per 1063 second. For example, 90th percentile says that 90% of the time, 1064 the total normal traffic is below the limit specified. 1066 The traffic normal baseline is represented for a target and is 1067 transport-protocol specific. 1069 If the DOTS client negotiated percentile values and units 1070 (Section 6.1), these negotiated values will be used instead of the 1071 default ones. 1073 Total Connections Capacity: If the target is subjected to resource 1074 consuming DDoS attack, the following optional attributes for the 1075 target per transport-protocol are useful to detect resource 1076 consuming DDoS attacks: 1078 * The maximum number of simultaneous connections that are allowed 1079 to the target. The threshold is transport-protocol specific 1080 because the target could support multiple protocols. 1082 * The maximum number of simultaneous connections that are allowed 1083 to the target per client. 1085 * The maximum number of simultaneous embryonic connections that 1086 are allowed to the target. The term "embryonic connection" 1087 refers to a connection whose connection handshake is not 1088 finished and embryonic connection is only possible in 1089 connection-oriented transport protocols like TCP or SCTP. 1091 * The maximum number of simultaneous embryonic connections that 1092 are allowed to the target per client. 1094 * The maximum number of connections allowed per second to the 1095 target. 1097 * The maximum number of connections allowed per second to the 1098 target per client. 1100 * The maximum number of requests allowed per second to the 1101 target. 1103 * The maximum number of requests allowed per second to the target 1104 per client. 1106 * The maximum number of partial requests allowed per second to 1107 the target. 1109 * The maximum number of partial requests allowed per second to 1110 the target per client. 1112 The tree structure of the baseline is shown in Figure 16. 1114 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1115 +--:(telemetry-setup) {dots-telemetry}? 1116 | +--rw telemetry* [cuid tsid] 1117 | +--rw cuid string 1118 | +--rw cdid? string 1119 | +--rw tsid uint32 1120 | +--rw (setup-type)? 1121 | +--:(telemetry-config) 1122 | | ... 1123 | +--:(pipe) 1124 | | ... 1125 | +--:(baseline) 1126 | +--rw baseline* [id] 1127 | +--rw id uint32 1128 | +--rw target-prefix* inet:ip-prefix 1129 | +--rw target-port-range* [lower-port] 1130 | | +--rw lower-port inet:port-number 1131 | | +--rw upper-port? inet:port-number 1132 | +--rw target-protocol* uint8 1133 | +--rw target-fqdn* inet:domain-name 1134 | +--rw target-uri* inet:uri 1135 | +--rw total-traffic-normal-baseline* [unit protocol] 1136 | | +--rw unit unit 1137 | | +--rw protocol uint8 1138 | | +--rw low-percentile-g? yang:gauge64 1139 | | +--rw mid-percentile-g? yang:gauge64 1140 | | +--rw high-percentile-g? yang:gauge64 1141 | | +--rw peak-g? yang:gauge64 1142 | +--rw total-connection-capacity* [protocol] 1143 | +--rw protocol uint8 1144 | +--rw connection? uint64 1145 | +--rw connection-client? uint64 1146 | +--rw embryonic? uint64 1147 | +--rw embryonic-client? uint64 1148 | +--rw connection-ps? uint64 1149 | +--rw connection-client-ps? uint64 1150 | +--rw request-ps? uint64 1151 | +--rw request-client-ps? uint64 1152 | +--rw partial-request-ps? uint64 1153 | +--rw partial-request-client-ps? uint6 1154 +--:(telemetry) {dots-telemetry}? 1155 +--rw pre-mitigation* [cuid id] 1156 ... 1158 Figure 16: Telemetry Baseline Tree Structure 1160 6.3.1. Convey DOTS Client Domain Baseline Information 1162 Similar considerations to those specified in Section 6.1.2 are 1163 followed with one exception: 1165 The relative order of two PUT requests carrying DOTS client domain 1166 baseline attributes from a DOTS client is determined by comparing 1167 their respective 'tsid' values. If such two requests have 1168 overlapping targets, the PUT request with higher numeric 'tsid' 1169 value will override the request with a lower numeric 'tsid' value. 1170 The overlapped lower numeric 'tsid' MUST be automatically deleted 1171 and no longer. 1173 Two PUT requests from a DOTS client have overlapping targets if there 1174 is a common IP address, IP prefix, FQDN, or URI. 1176 DOTS clients SHOULD minimize the number of active "tsids" used for 1177 baseline information. Typically, in order to avoid maintaining a 1178 long list of "tsids" for baseline information, it is RECOMMENDED that 1179 DOTS clients include in a request to update information related to a 1180 given target, the information of other targets (already communicated 1181 using a lower 'tsid' value) (assuming this fits within one single 1182 datagram). This update request will override these existing requests 1183 and hence optimize the number of 'tsid" request per DOTS client. 1185 If no target clause in included in the request, this is an indication 1186 that the baseline information applies for the DOTS client domain as a 1187 whole. 1189 An example of a PUT request to convey the baseline information is 1190 shown in Figure 17. 1192 Header: PUT (Code=0.03) 1193 Uri-Path: ".well-known" 1194 Uri-Path: "dots" 1195 Uri-Path: "tm-setup" 1196 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1197 Uri-Path: "tsid=126" 1198 Content-Format: "application/dots+cbor" 1200 { 1201 "ietf-dots-signal-channel:telemetry": { 1202 "baseline": { 1203 "id": 1, 1204 "target-prefix": [ 1205 "2001:db8:6401::1/128", 1206 "2001:db8:6401::2/128" 1207 ], 1208 "total-traffic-normal-baseline": { 1209 "unit": "megabytes-ps", 1210 "protocol": 6, 1211 "peak-g": "50" 1212 } 1213 } 1214 } 1215 } 1217 Figure 17: PUT to Convey the DOTS Traffic Baseline 1219 o Note: Add some multi-homing considerations in this section or in 1220 the multi-homing I-D. 1222 6.3.2. Retrieve Normal Traffic Baseline 1224 A GET request with 'tsid' Uri-Path parameter is used to retrieve a 1225 specific installed DOTS client domain baseline traffic information. 1226 The that aim, the same procedure defined in (Section 6.1.3) is 1227 followed. 1229 To retrieve all baseline information bound to a DOTS client, the DOTS 1230 client proceeds as specified in Section 6.1.1. 1232 6.3.3. Retrieve Normal Traffic Baseline 1234 A DELETE request is used to delete the installed DOTS client domain 1235 normal traffic baseline. The that aim, the same procedure defined in 1236 (Section 6.1.4) is followed. 1238 6.4. Reset Installed Telemetry Setup and Configuration 1240 Upon bootstrapping (or reboot or any other event that may alter the , 1241 a DOTS client MAY send a DELETE request to set the telemetry 1242 parameters to default values. Such a request does not include any 1243 'tsid'. An example of such request is depicted in Figure 18. 1245 Header: DELETE (Code=0.04) 1246 Uri-Path: ".well-known" 1247 Uri-Path: "dots" 1248 Uri-Path: "tm-setup" 1249 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1251 Figure 18: Delete Telemetry Configuration 1253 6.5. Conflict with Other DOTS Clients of the Same Domain 1255 A DOTS server may detect conflicts between requests to convey pipe 1256 and baseline information received from DOTS clients of the same DOTS 1257 client domain. 'conflict-information' is used to report the conflict 1258 to the DOTS client following similar conflict handling discussed in 1259 Section 4.4.1 of [I-D.ietf-dots-signal-channel]. The confict cause 1260 can be set to one of these values: 1262 1: Overlapping targets (already defined in 1263 [I-D.ietf-dots-signal-channel]). 1265 TBA: Overlapping pipe scope (see Section 11). 1267 7. DOTS Telemetry from Clients to Servers 1269 There are two broad types of DDoS attacks, one is bandwidth consuming 1270 attack, the other is target resource consuming attack. This section 1271 outlines the set of DOTS telemetry attributes (Section 7.1) that 1272 covers both the types of attacks. The ultimate objective of these 1273 attributes is to allow for the complete knowledge of attacks and the 1274 various particulars that can best characterize attacks. 1276 The description and motivation behind each attribute are presented in 1277 Section 3. DOTS telemetry attributes are optionally signaled and 1278 therefore MUST NOT be treated as mandatory fields in the DOTS signal 1279 channel protocol. 1281 The "ietf-dots-telemetry" YANG module (Section 9) augments the "ietf- 1282 dots-signal" with a new message type called "telemetry". The tree 1283 structure of the "telemetry" message type is shown Figure 19. 1285 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1286 +--:(telemetry-setup) {dots-telemetry}? 1287 | +--rw telemetry* [cuid tsid] 1288 | ... 1289 +--:(telemetry) {dots-telemetry}? 1290 +--rw pre-mitigation* [cuid id] 1291 +--rw cuid string 1292 +--rw cdid? string 1293 +--rw id uint32 1294 +--rw target 1295 | +--rw target-prefix* inet:ip-prefix 1296 | +--rw target-port-range* [lower-port] 1297 | | +--rw lower-port inet:port-number 1298 | | +--rw upper-port? inet:port-number 1299 | +--rw target-protocol* uint8 1300 | +--rw target-fqdn* inet:domain-name 1301 | +--rw target-uri* inet:uri 1302 +--rw total-traffic* [unit protocol] 1303 | ... 1304 +--rw total-attack-traffic* [unit protocol] 1305 | ... 1306 +--rw total-attack-connection 1307 | ... 1308 +--rw attack-detail 1309 ... 1311 Figure 19: Telemetry Message Type Tree Structure 1313 7.1. Pre-mitigation DOTS Telemetry Attributes 1315 The pre-mitigation telemetry attributes are indicated by the path- 1316 suffix '/tm'. The '/tm' is appended to the path-prefix to form the 1317 URI used with a CoAP request to signal the DOTS telemetry. The 1318 following pre-mitigation telemetry attributes can be signaled from 1319 DOTS clients to DOTS servers. 1321 o DISCUSSION NOTES: (1) Some telemetry can be communicated using 1322 DOTS data channel. (2) Evaluate the risk of fragmentation,. Some 1323 of the information is not specific to each mitigation request. (3) 1324 Should we define other configuration parameters to be controlled 1325 by a DOTS client, e.g., Indicate a favorite measurement unit? 1326 Indicate a minimum notification interval? 1328 7.1.1. Total Traffic 1330 By default, this attribute conveys the low percentile (10th 1331 percentile), mid percentile (50th percentile), high percentile (90th 1332 percentile) and peak values of total traffic during a DDoS attack 1333 measured in packets per second (PPS) or kilo packets per second 1334 (Kpps) and Bits per Second (BPS), and kilobytes per second or 1335 megabytes per second gigabytes per second. 1337 The total traffic is represented for a target and is transport- 1338 protocol specific. 1340 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1341 +--:(telemetry-setup) {dots-telemetry}? 1342 | +--rw telemetry* [cuid tsid] 1343 | ... 1344 +--:(telemetry) {dots-telemetry}? 1345 +--rw pre-mitigation* [cuid id] 1346 +--rw cuid string 1347 +--rw cdid? string 1348 +--rw id uint32 1349 +--rw target 1350 | +--rw target-prefix* inet:ip-prefix 1351 | +--rw target-port-range* [lower-port] 1352 | | +--rw lower-port inet:port-number 1353 | | +--rw upper-port? inet:port-number 1354 | +--rw target-protocol* uint8 1355 | +--rw target-fqdn* inet:domain-name 1356 | +--rw target-uri* inet:uri 1357 +--rw total-traffic* [unit protocol] 1358 | +--rw unit unit 1359 | +--rw protocol uint8 1360 | +--rw low-percentile-g? yang:gauge64 1361 | +--rw mid-percentile-g? yang:gauge64 1362 | +--rw high-percentile-g? yang:gauge64 1363 | +--rw peak-g? yang:gauge64 1364 +--rw total-attack-traffic* [unit protocol] 1365 | ... 1366 +--rw total-attack-connection 1367 | ... 1368 +--rw attack-detail 1369 ... 1371 Figure 20: Total Traffic Tree Structure 1373 7.1.2. Total Attack Traffic 1375 By default, this attribute conveys the total attack traffic can be 1376 identified by the DOTS client domain's DMS or DDoS Detector. The low 1377 percentile (10th percentile), mid percentile (50th percentile), high 1378 percentile (90th percentile) and peak values of total attack traffic 1379 measured in packets per second (PPS) or kilo packets per second 1380 (Kpps) and Bits per Second (BPS), and kilobytes per second or 1381 megabytes per second or gigabytes per second. 1383 The total attack traffic is represented for a target and is 1384 transport-protocol specific. 1386 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1387 +--:(telemetry-setup) {dots-telemetry}? 1388 | +--rw telemetry* [cuid tsid] 1389 | ... 1390 +--:(telemetry) {dots-telemetry}? 1391 +--rw pre-mitigation* [cuid id] 1392 +--rw cuid string 1393 +--rw cdid? string 1394 +--rw id uint32 1395 +--rw target 1396 | +--rw target-prefix* inet:ip-prefix 1397 | +--rw target-port-range* [lower-port] 1398 | | +--rw lower-port inet:port-number 1399 | | +--rw upper-port? inet:port-number 1400 | +--rw target-protocol* uint8 1401 | +--rw target-fqdn* inet:domain-name 1402 | +--rw target-uri* inet:uri 1403 +--rw total-traffic* [unit protocol] 1404 | ... 1405 +--rw total-attack-traffic* [unit protocol] 1406 | +--rw unit unit 1407 | +--rw protocol uint8 1408 | +--rw low-percentile-g? yang:gauge64 1409 | +--rw mid-percentile-g? yang:gauge64 1410 | +--rw high-percentile-g? yang:gauge64 1411 | +--rw peak-g? yang:gauge64 1412 +--rw total-attack-connection 1413 | ... 1414 +--rw attack-detail 1415 ... 1417 Figure 21: Total Attack Traffic Tree Structure 1419 7.1.3. Total Attack Connections 1421 If the target is subjected to resource consuming DDoS attack, the low 1422 percentile (10th percentile), mid percentile (50th percentile), high 1423 percentile (90th percentile) and peak values of following optional 1424 attributes for the target per transport-protocol are included to 1425 represent the attack characteristics: 1427 o The number of simultaneous attack connections to the target 1428 server. 1430 o The number of simultaneous embryonic connections to the target 1431 server. 1433 o The number of attack connections per second to the target server. 1435 o The number of attack requests to the target server. 1437 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1438 +--:(telemetry-setup) {dots-telemetry}? 1439 | +--rw telemetry* [cuid tsid] 1440 | ... 1441 +--:(telemetry) {dots-telemetry}? 1442 +--rw pre-mitigation* [cuid id] 1443 +--rw cuid string 1444 +--rw cdid? string 1445 +--rw id uint32 1446 +--rw target 1447 | +--rw target-prefix* inet:ip-prefix 1448 | +--rw target-port-range* [lower-port] 1449 | | +--rw lower-port inet:port-number 1450 | | +--rw upper-port? inet:port-number 1451 | +--rw target-protocol* uint8 1452 | +--rw target-fqdn* inet:domain-name 1453 | +--rw target-uri* inet:uri 1454 +--rw total-traffic* [unit protocol] 1455 | ... 1456 +--rw total-attack-traffic* [unit protocol] 1457 | ... 1458 +--rw total-attack-connection 1459 | +--rw low-percentile-l* [protocol] 1460 | | +--rw protocol uint8 1461 | | +--rw connection? yang:gauge64 1462 | | +--rw embryonic? yang:gauge64 1463 | | +--rw connection-ps? yang:gauge64 1464 | | +--rw request-ps? yang:gauge64 1465 | | +--rw partial-request-ps? yang:gauge64 1466 | +--rw mid-percentile-l* [protocol] 1467 | | +--rw protocol uint8 1468 | | +--rw connection? yang:gauge64 1469 | | +--rw embryonic? yang:gauge64 1470 | | +--rw connection-ps? yang:gauge64 1471 | | +--rw request-ps? yang:gauge64 1472 | | +--rw partial-request-ps? yang:gauge64 1473 | +--rw high-percentile-l* [protocol] 1474 | | +--rw protocol uint8 1475 | | +--rw connection? yang:gauge64 1476 | | +--rw embryonic? yang:gauge64 1477 | | +--rw connection-ps? yang:gauge64 1478 | | +--rw request-ps? yang:gauge64 1479 | | +--rw partial-request-ps? yang:gauge64 1480 | +--rw peak-l* [protocol] 1481 | +--rw protocol uint8 1482 | +--rw connection? yang:gauge64 1483 | +--rw embryonic? yang:gauge64 1484 | +--rw connection-ps? yang:gauge64 1485 | +--rw request-ps? yang:gauge64 1486 | +--rw partial-request-ps? yang:gauge64 1487 +--rw attack-detail 1488 ... 1490 Figure 22: Total Attack Connections Tree Structure 1492 7.1.4. Attack Details 1494 The attack details need to cover well-known and common attacks (such 1495 as a SYN Flood) along with new emerging or vendor-specific attacks. 1497 augment /ietf-signal:dots-signal/ietf-signal:message-type: 1498 +--:(telemetry-setup) {dots-telemetry}? 1499 | +--rw telemetry* [cuid tsid] 1500 | ... 1501 +--:(telemetry) {dots-telemetry}? 1502 +--rw pre-mitigation* [cuid id] 1503 +--rw cuid string 1504 +--rw cdid? string 1505 +--rw id uint32 1506 ... 1507 +--rw attack-detail 1508 +--rw id? uint32 1509 +--rw attack-id? string 1510 +--rw attack-name? string 1511 +--rw attack-severity? attack-severity 1512 +--rw start-time? uint64 1513 +--rw end-time? uint64 1514 +--rw source-count 1515 | +--rw low-percentile-g? yang:gauge64 1516 | +--rw mid-percentile-g? yang:gauge64 1517 | +--rw high-percentile-g? yang:gauge64 1518 | +--rw peak-g? yang:gauge64 1519 +--rw top-talker 1520 +--rw source-prefix* [source-prefix] 1521 +--rw spoofed-status? boolean 1522 +--rw source-prefix inet:ip-prefix 1523 +--rw total-attack-traffic* [unit] 1524 | +--rw unit unit 1525 | +--rw low-percentile-g? yang:gauge64 1526 | +--rw mid-percentile-g? yang:gauge64 1527 | +--rw high-percentile-g? yang:gauge64 1528 | +--rw peak-g? yang:gauge64 1529 +--rw total-attack-connection 1530 +--rw low-percentile-l* [protocol] 1531 | +--rw protocol uint8 1532 | +--rw connection? yang:gauge64 1533 | +--rw embryonic? yang:gauge64 1534 | +--rw connection-ps? yang:gauge64 1535 | +--rw request-ps? yang:gauge64 1536 | +--rw partial-request-ps? yang:gauge64 1537 +--rw mid-percentile-l* [protocol] 1538 | +--rw protocol uint8 1539 | +--rw connection? yang:gauge64 1540 | +--rw embryonic? yang:gauge64 1541 | +--rw connection-ps? yang:gauge64 1542 | +--rw request-ps? yang:gauge64 1543 | +--rw partial-request-ps? yang:gauge64 1544 +--rw high-percentile-l* [protocol] 1545 | +--rw protocol uint8 1546 | +--rw connection? yang:gauge64 1547 | +--rw embryonic? yang:gauge64 1548 | +--rw connection-ps? yang:gauge64 1549 | +--rw request-ps? yang:gauge64 1550 | +--rw partial-request-ps? yang:gauge64 1551 +--rw peak-l* [protocol] 1552 +--rw protocol uint8 1553 +--rw connection? yang:gauge64 1554 +--rw embryonic? yang:gauge64 1555 +--rw connection-ps? yang:gauge64 1556 +--rw request-ps? yang:gauge64 1557 +--rw partial-request-ps? yang:gauge64 1559 Attack Detail Tree Structure 1561 The following new fields describing the on-going attack are 1562 discussed: 1564 id: Vendor ID is a security vendor's Enterprise Number as registered 1565 with IANA [Enterprise-Numbers]. It is a four-byte integer value. 1567 This is a mandatory sub-attribute. 1569 attack-id: Unique identifier assigned by the vendor for the attack. 1571 This is a mandatory sub-attribute. 1573 attack-name: Textual representation of attack description. Natural 1574 Language Processing techniques (e.g., word embedding) can possibly 1575 be used to map the attack description to an attack type. Textual 1576 representation of attack solves two problems (a) avoids the need 1577 to create mapping tables manually between vendors (2) Avoids the 1578 need to standardize attack types which keep evolving. 1580 This is a mandatory sub-attribute 1582 attack-severity: Attack severity. Emergency (0), critical (1) and 1583 alert (2). 1585 This is an optional sub-attribute 1587 start-time: The time the attack started. The attack start time is 1588 expressed in seconds relative to 1970-01-01T00:00Z in UTC time 1589 (Section 2.4.1 of [RFC7049]). The CBOR encoding is modified so 1590 that the leading tag 1 (epoch-based date/time) MUST be omitted. 1592 This is a mandatory sub-attribute 1594 end-time: The time the attack-id attack ended. The attack 1595 end time is expressed in seconds relative to 1970-01-01T00:00Z in 1596 UTC time (Section 2.4.1 of [RFC7049]). The CBOR encoding is 1597 modified so that the leading tag 1 (epoch-based date/time) MUST be 1598 omitted. 1600 This is an optional sub-attribute 1602 The following existing fields are re-defined describing the on-going 1603 attack are discussed: 1605 o The target resource is identified using the attributes 'target- 1606 prefix', 'target-port-range', 'target-protocol', 'target- 1607 fqdn','target-uri', or 'alias-name' defined in the base DOTS 1608 signal channel protocol and at least one of the attributes 1609 'target-prefix', 'target-fqdn','target-uri', or 'alias-name' MUST 1610 be present in the attack details. 1612 A. If the target is subjected to bandwidth consuming attack, the 1613 attributes representing the low percentile (10th percentile), 1614 mid percentile (50th percentile), high percentile (90th 1615 percentile) and peak values of the attack-id attack traffic 1616 measured in packets per second (PPS) or kilo packets per 1617 second (Kpps) and Bits per Second (BPS), and kilobytes per 1618 second or megabytes per second or gigabytes per second are 1619 included. 1621 B. If the target is subjected to resource consuming DDoS attacks, 1622 the same attributes defined for Section 7.1.3 are applicable 1623 for representing the attack. 1625 This is an optional sub-attribute. 1627 o A count of sources involved in the attack targeting the victim and 1628 a list of top talkers among those sources. The top talkers are 1629 represented using the 'source-prefix' defined in 1630 [I-D.ietf-dots-signal-call-home]. If the top talkers are spoofed 1631 IP addresses (e.g., reflection attacks) or not. If the target is 1632 subjected to bandwidth consuming attack, the attack traffic from 1633 each of the top talkers represented in the low percentile (10th 1634 percentile), mid percentile (50th percentile), high percentile 1635 (90th percentile) and peak values of traffic measured in packets 1636 per second (PPS) or kilo packets per second (Kpps) and Bits per 1637 Second (BPS), and kilobytes per second or megabytes per second 1638 gigabytes per second. If the target is subjected to resource 1639 consuming DDoS attacks, the same attributes defined for 1640 Section 7.1.3 are applicable here for representing the attack per 1641 talker. This is an optional sub-attribute. 1643 7.2. DOTS Client to Server Mitigation Efficacy DOTS Telemetry 1644 Attributes 1646 The mitigation efficacy telemetry attributes can be signaled from the 1647 DOTS client to the DOTS server as part of the periodic mitigation 1648 efficacy updates to the server (Section 5.3.4 of 1649 [I-D.ietf-dots-signal-channel]). 1651 Total Attack Traffic: The low percentile (10th percentile), mid 1652 percentile (50th percentile), high percentile (90th percentile), 1653 and peak values of total attack traffic the DOTS client still sees 1654 during the active mitigation service measured in packets per 1655 second (PPS) or kilo packets per second (Kpps) and Bits per Second 1656 (BPS), and kilobytes per second or megabytes per second or 1657 gigabytes per second. See Figure 21. 1659 Attack Details: The overall attack details as observed from the 1660 DOTS client perspective during the active mitigation service. The 1661 same attributes defined in Section 7.1.4 are applicable here. 1663 7.3. Sample Examples 1665 7.3.1. Single Pre-Mitigation 1667 <<>> 1669 7.3.2. Multiple Pre-Mitigations 1671 <> 1673 7.3.3. Top-Talker of Targets 1675 <> 1679 <> 1682 7.3.4. Top-Talker of Each Target 1684 <> 1688 8. DOTS Telemetry from Servers to Clients 1690 8.1. DOTS Server to Client Mitigation Status DOTS Telemetry Attributes 1692 The mitigation status telemetry attributes can be signaled from the 1693 DOTS server to the DOTS client as part of the periodic mitigation 1694 status update (Section 5.3.3 of [I-D.ietf-dots-signal-channel]). In 1695 particular, DOTS clients can receive asynchronous notifications of 1696 the attack details from DOTS servers using the Observe option defined 1697 in [RFC7641]. 1699 The "ietf-dots-telemetry" YANG module augments the "mitigation-scope" 1700 type message defined in "ietf-dots-signal" with telemetry data as 1701 depicted in following tree structure: 1703 augment /ietf-signal:dots-signal/ietf-signal:message-type 1704 /ietf-signal:mitigation-scope/ietf-signal:scope: 1705 +--rw total-traffic* [unit protocol] {dots-telemetry}? 1706 | +--rw unit unit 1707 | +--rw protocol uint8 1708 | +--rw low-percentile-g? yang:gauge64 1709 | +--rw mid-percentile-g? yang:gauge64 1710 | +--rw high-percentile-g? yang:gauge64 1711 | +--rw peak-g? yang:gauge64 1712 +--rw total-attack-traffic* [unit] {dots-telemetry}? 1713 | +--rw unit unit 1714 | +--rw low-percentile-g? yang:gauge64 1715 | +--rw mid-percentile-g? yang:gauge64 1716 | +--rw high-percentile-g? yang:gauge64 1717 | +--rw peak-g? yang:gauge64 1718 +--rw total-attack-connection {dots-telemetry}? 1719 | +--rw low-percentile-c 1720 | | +--rw connection? yang:gauge64 1721 | | +--rw embryonic? yang:gauge64 1722 | | +--rw connection-ps? yang:gauge64 1723 | | +--rw request-ps? yang:gauge64 1724 | | +--rw partial-request-ps? yang:gauge64 1725 | +--rw mid-percentile-c 1726 | | +--rw connection? yang:gauge64 1727 | | +--rw embryonic? yang:gauge64 1728 | | +--rw connection-ps? yang:gauge64 1729 | | +--rw request-ps? yang:gauge64 1730 | | +--rw partial-request-ps? yang:gauge64 1731 | +--rw high-percentile-c 1732 | | +--rw connection? yang:gauge64 1733 | | +--rw embryonic? yang:gauge64 1734 | | +--rw connection-ps? yang:gauge64 1735 | | +--rw request-ps? yang:gauge64 1736 | | +--rw partial-request-ps? yang:gauge64 1737 | +--rw peak-c 1738 | +--rw connection? yang:gauge64 1739 | +--rw embryonic? yang:gauge64 1740 | +--rw connection-ps? yang:gauge64 1741 | +--rw request-ps? yang:gauge64 1742 | +--rw partial-request-ps? yang:gauge64 1743 +--rw attack-detail {dots-telemetry}? 1744 +--rw id? uint32 1745 +--rw attack-id? string 1746 +--rw attack-name? string 1747 +--rw attack-severity? attack-severity 1748 +--rw start-time? uint64 1749 +--rw end-time? uint64 1750 +--rw source-count 1751 | +--rw low-percentile-g? yang:gauge64 1752 | +--rw mid-percentile-g? yang:gauge64 1753 | +--rw high-percentile-g? yang:gauge64 1754 | +--rw peak-g? yang:gauge64 1755 +--rw top-talker 1756 +--rw source-prefix* [source-prefix] 1757 +--rw spoofed-status? boolean 1758 +--rw source-prefix inet:ip-prefix 1759 +--rw total-attack-traffic* [unit] 1760 | +--rw unit unit 1761 | +--rw low-percentile-g? yang:gauge64 1762 | +--rw mid-percentile-g? yang:gauge64 1763 | +--rw high-percentile-g? yang:gauge64 1764 | +--rw peak-g? yang:gauge64 1765 +--rw total-attack-connection 1766 +--rw low-percentile-c 1767 | +--rw connection? yang:gauge64 1768 | +--rw embryonic? yang:gauge64 1769 | +--rw connection-ps? yang:gauge64 1770 | +--rw request-ps? yang:gauge64 1771 | +--rw partial-request-ps? yang:gauge64 1772 +--rw mid-percentile-c 1773 | +--rw connection? yang:gauge64 1774 | +--rw embryonic? yang:gauge64 1775 | +--rw connection-ps? yang:gauge64 1776 | +--rw request-ps? yang:gauge64 1777 | +--rw partial-request-ps? yang:gauge64 1778 +--rw high-percentile-c 1779 | +--rw connection? yang:gauge64 1780 | +--rw embryonic? yang:gauge64 1781 | +--rw connection-ps? yang:gauge64 1782 | +--rw request-ps? yang:gauge64 1783 | +--rw partial-request-ps? yang:gauge64 1784 +--rw peak-c 1785 +--rw connection? yang:gauge64 1786 +--rw embryonic? yang:gauge64 1787 +--rw connection-ps? yang:gauge64 1788 +--rw request-ps? yang:gauge64 1789 +--rw partial-request-ps? yang:gauge64 1791 8.1.1. Mitigation Status 1793 As defined in [RFC8612], the actual mitigation activities can include 1794 several countermeasure mechanisms. The DOTS server SHOULD signal the 1795 current operational status to each relevant countermeasure. A list 1796 of attacks detected by each countermeasure. 1798 The same attributes defined for Section 7.1.4 are applicable for 1799 describing the attacks detected and mitigated. 1801 8.2. DOTS Detector to Clients Detection Telemetry 1803 The attack details can also be signaled from DOTS servers to DOTS 1804 clients. For example, the DOTS server co-located with a DDoS 1805 detector collects monitoring information from the target network, 1806 identifies DDoS attack using statistical analysis or deep learning 1807 techniques, and signals the attack details to the DOTS client. 1809 The DOTS client can use the attack details to decide whether to 1810 trigger a DOTS mitigation request or not. Furthermore, the security 1811 operation personnel at the DOTS client domain can use the attack 1812 details to determine the protection strategy and select the 1813 appropriate DOTS server for mitigating the attack. 1815 <> 1817 9. YANG Module 1819 This module uses types defined in [RFC6991]. 1821 file "ietf-dots-telemetry@2020-01-23.yang" 1822 module ietf-dots-telemetry { 1823 yang-version 1.1; 1824 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-telemetry"; 1825 prefix dots-telemetry; 1827 import ietf-dots-signal-channel { 1828 prefix ietf-signal; 1829 reference 1830 "RFC SSSS: Distributed Denial-of-Service Open Threat 1831 Signaling (DOTS) Signal Channel Specification"; 1832 } 1833 import ietf-dots-data-channel { 1834 prefix ietf-data; 1835 reference 1836 "RFC DDDD: Distributed Denial-of-Service Open Threat 1837 Signaling (DOTS) Data Channel Specification"; 1838 } 1839 import ietf-yang-types { 1840 prefix yang; 1841 reference 1842 "Section 3 of RFC 6991"; 1843 } 1844 import ietf-inet-types { 1845 prefix inet; 1846 reference 1847 "Section 4 of RFC 6991"; 1848 } 1849 import ietf-network-topology { 1850 prefix nt; 1851 reference 1852 "Section 6.2 of RFC 8345: A YANG Data Model for Network 1853 Topologies"; 1854 } 1856 organization 1857 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 1858 contact 1859 "WG Web: 1860 WG List: 1862 Author: Mohamed Boucadair 1863 1865 Author: Konda, Tirumaleswar Reddy 1866 "; 1867 description 1868 "This module contains YANG definitions for the signaling 1869 of DOTS telemetry exchanged between a DOTS client and 1870 a DOTS server, by means of the DOTS signal channel. 1872 Copyright (c) 2020 IETF Trust and the persons identified as 1873 authors of the code. All rights reserved. 1875 Redistribution and use in source and binary forms, with or 1876 without modification, is permitted pursuant to, and subject 1877 to the license terms contained in, the Simplified BSD License 1878 set forth in Section 4.c of the IETF Trust's Legal Provisions 1879 Relating to IETF Documents 1880 (http://trustee.ietf.org/license-info). 1882 This version of this YANG module is part of RFC XXXX; see 1883 the RFC itself for full legal notices."; 1885 revision 2020-01-23 { 1886 description 1887 "Initial revision."; 1888 reference 1889 "RFC XXXX: Distributed Denial-of-Service Open Threat 1890 Signaling (DOTS) Telemetry"; 1891 } 1893 feature dots-telemetry { 1894 description 1895 "This feature means that the DOTS signal channel is able 1896 to convey DOTS telemetry data between DOTS clients and 1897 servers."; 1898 } 1900 typedef attack-severity { 1901 type enumeration { 1902 enum emergency { 1903 value 1; 1904 description 1905 "The attack is severe: emergency."; 1906 } 1907 enum critical { 1908 value 2; 1909 description 1910 "The attack is critical."; 1911 } 1912 enum alert { 1913 value 3; 1914 description 1915 "This is an alert."; 1916 } 1917 } 1918 description 1919 "Enumeration for attack severity."; 1920 } 1922 typedef unit { 1923 type enumeration { 1924 enum pps { 1925 value 1; 1926 description 1927 "Packets per second (PPS)."; 1928 } 1929 enum kilo-pps { 1930 value 2; 1931 description 1932 "Kilo packets per second (Kpps)."; 1933 } 1934 enum bps { 1935 value 3; 1936 description 1937 "Bits per Second (BPS)."; 1938 } 1939 enum kilobytes-ps { 1940 value 4; 1941 description 1942 "Kilobytes per second."; 1943 } 1944 enum megabytes-ps { 1945 value 5; 1946 description 1947 "Megabytes per second."; 1948 } 1949 enum gigabytes-ps { 1950 value 6; 1951 description 1952 "Gigabytes per second."; 1953 } 1954 } 1955 description 1956 "Enumeration to indicate which unit is used."; 1957 } 1959 typedef interval { 1960 type enumeration { 1961 enum hour { 1962 value 1; 1963 description 1964 "Hour."; 1965 } 1966 enum day { 1967 value 2; 1968 description 1969 "Day."; 1970 } 1971 enum week { 1972 value 3; 1973 description 1974 "Week."; 1975 } 1976 enum month { 1977 value 4; 1978 description 1979 "Month."; 1980 } 1981 } 1982 description 1983 "Enumeration to indicate the overall measurement period."; 1984 } 1986 typedef sample { 1987 type enumeration { 1988 enum second { 1989 value 1; 1990 description 1991 "Second."; 1992 } 1993 enum 5-seconds { 1994 value 2; 1995 description 1996 "5 seconds."; 1997 } 1998 enum 30-seconds { 1999 value 3; 2000 description 2001 "30 seconds."; 2002 } 2003 enum minute { 2004 value 4; 2005 description 2006 "One minute."; 2007 } 2008 enum 5-minutes { 2009 value 5; 2010 description 2011 "5 minutes."; 2012 } 2013 enum 10-minutes { 2014 value 6; 2015 description 2016 "10 minutes."; 2017 } 2018 enum 30-minutes { 2019 value 7; 2020 description 2021 "30 minutes."; 2022 } 2023 enum hour { 2024 value 8; 2025 description 2026 "One hour."; 2027 } 2028 } 2029 description 2030 "Enumeration to indicate the measurement perdiod."; 2031 } 2033 typedef percentile { 2034 type decimal64 { 2035 fraction-digits 2; 2036 } 2037 description 2038 "The nth percentile of a set of data is the 2039 value at which n percent of the data is below it."; 2040 } 2041 grouping percentile-config { 2042 description 2043 "Configuration of low, mid, and high percentile values."; 2044 leaf measurement-interval { 2045 type interval; 2046 description 2047 "Defines the period on which percentiles are computed."; 2048 } 2049 leaf measurement-sample { 2050 type sample; 2051 description 2052 "Defines the time distribution for measuring 2053 values that are used to compute percentiles.."; 2054 } 2055 leaf low-percentile { 2056 type percentile; 2057 default "10.00"; 2058 description 2059 "Low percentile. If set to '0', this means low-percentiles 2060 are disabled."; 2061 } 2062 leaf mid-percentile { 2063 type percentile; 2064 must '. >= ../low-percentile' { 2065 error-message 2066 "The mid-percentile must be greater than 2067 or equal to the low-percentile."; 2068 } 2069 default "50.00"; 2070 description 2071 "Mid percentile. If set to the same value as low-percentiles, 2072 this means mid-percentiles are disabled."; 2073 } 2074 leaf high-percentile { 2075 type percentile; 2076 must '. >= ../mid-percentile' { 2077 error-message 2078 "The high-percentile must be greater than 2079 or equal to the mid-percentile."; 2080 } 2081 default "90.00"; 2082 description 2083 "High percentile. If set to the same value as mid-percentiles, 2084 this means high-percentiles are disabled."; 2085 } 2086 } 2088 grouping percentile { 2089 description 2090 "Generic grouping for percentile."; 2091 leaf low-percentile-g { 2092 type yang:gauge64; 2093 description 2094 "Low traffic."; 2095 } 2096 leaf mid-percentile-g { 2097 type yang:gauge64; 2098 description 2099 "Mid percentile."; 2100 } 2101 leaf high-percentile-g { 2102 type yang:gauge64; 2103 description 2104 "High percentile."; 2105 } 2106 leaf peak-g { 2107 type yang:gauge64; 2108 description 2109 "Peak"; 2110 } 2111 } 2113 grouping unit-config { 2114 description 2115 "Generic grouping for unit configuration."; 2116 list unit-config { 2117 key "unit"; 2118 description 2119 "Controls which units are allowed when sharing telemetry 2120 data."; 2121 leaf unit { 2122 type unit; 2123 description 2124 "The traffic can be measured in packets per 2125 second (PPS) or kilo packets per second (Kpps) and Bits per 2126 Second (BPS), and kilobytes per second or megabytes per second 2127 or gigabytes per second."; 2128 } 2129 leaf unit-status { 2130 type boolean; 2131 description 2132 "Enable/disable the use of the measurement unit."; 2133 } 2134 } 2135 } 2136 grouping traffic-unit { 2137 description 2138 "Grouping of traffic as a function of measurement unit."; 2139 leaf unit { 2140 type unit; 2141 description 2142 "The traffic can be measured in packets per 2143 second (PPS) or kilo packets per second (Kpps) and Bits per 2144 Second (BPS), and kilobytes per second or megabytes per second 2145 or gigabytes per second."; 2146 } 2147 uses percentile; 2148 } 2150 grouping traffic-unit-protocol { 2151 description 2152 "Grouping of traffic of a given transport protocol as 2153 a function of measurement unit."; 2154 leaf unit { 2155 type unit; 2156 description 2157 "The traffic can be measured in packets per 2158 second (PPS) or kilo packets per second (Kpps) and Bits per 2159 Second (BPS), and kilobytes per second or megabytes per second 2160 or gigabytes per second."; 2161 } 2162 leaf protocol { 2163 type uint8; 2164 description 2165 "The transport protocol. 2166 Values are taken from the IANA Protocol Numbers registry: 2167 . 2169 For example, this field contains 6 for TCP, 2170 17 for UDP, 33 for DCCP, or 132 for SCTP."; 2171 } 2172 uses percentile; 2173 } 2175 grouping total-connection-capacity { 2176 description 2177 "Total Connections Capacity. If the target is subjected 2178 to resource consuming DDoS attack, these attributes are 2179 useful to detect resource consuming DDoS attacks"; 2180 leaf connection { 2181 type uint64; 2182 description 2183 "The maximum number of simultaneous connections that 2184 are allowed to the target server. The threshold is 2185 transport-protocol specific because the target server 2186 could support multiple protocols."; 2187 } 2188 leaf connection-client { 2189 type uint64; 2190 description 2191 "The maximum number of simultaneous connections that 2192 are allowed to the target server per client."; 2193 } 2194 leaf embryonic { 2195 type uint64; 2196 description 2197 "The maximum number of simultaneous embryonic connections 2198 that are allowed to the target server. The term 'embryonic 2199 connection' refers to a connection whose connection handshake 2200 is not finished and embryonic connection is only possible in 2201 connection-oriented transport protocols like TCP or SCTP."; 2202 } 2203 leaf embryonic-client { 2204 type uint64; 2205 description 2206 "The maximum number of simultaneous embryonic connections 2207 that are allowed to the target server per client."; 2208 } 2209 leaf connection-ps { 2210 type uint64; 2211 description 2212 "The maximum number of connections allowed per second 2213 to the target server."; 2214 } 2215 leaf connection-client-ps { 2216 type uint64; 2217 description 2218 "The maximum number of connections allowed per second 2219 to the target server per client."; 2220 } 2221 leaf request-ps { 2222 type uint64; 2223 description 2224 "The maximum number of requests allowed per second 2225 to the target server."; 2226 } 2227 leaf request-client-ps { 2228 type uint64; 2229 description 2230 "The maximum number of requests allowed per second 2231 to the target server per client."; 2233 } 2234 leaf partial-request-ps { 2235 type uint64; 2236 description 2237 "The maximum number of partial requests allowed per 2238 second to the target server."; 2239 } 2240 leaf partial-request-client-ps { 2241 type uint64; 2242 description 2243 "The maximum number of partial requests allowed per 2244 second to the target server per client."; 2245 } 2246 } 2248 grouping connection { 2249 description 2250 "A set of attributes which represent the attack 2251 characteristics"; 2252 leaf connection { 2253 type yang:gauge64; 2254 description 2255 "The number of simultaneous attack connections to 2256 the target server."; 2257 } 2258 leaf embryonic { 2259 type yang:gauge64; 2260 description 2261 "The number of simultaneous embryonic connections to 2262 the target server."; 2263 } 2264 leaf connection-ps { 2265 type yang:gauge64; 2266 description 2267 "The number of attack connections per second to 2268 the target server."; 2269 } 2270 leaf request-ps { 2271 type yang:gauge64; 2272 description 2273 "The number of attack requests per second to 2274 the target server."; 2275 } 2276 leaf partial-request-ps { 2277 type yang:gauge64; 2278 description 2279 "The number of attack partial requests to 2280 the target server."; 2282 } 2283 } 2285 grouping connection-percentile { 2286 description 2287 "Total attack connections."; 2288 container low-percentile-c { 2289 description 2290 "Low percentile of attack connections."; 2291 uses connection; 2292 } 2293 container mid-percentile-c { 2294 description 2295 "Mid percentile of attack connections."; 2296 uses connection; 2297 } 2298 container high-percentile-c { 2299 description 2300 "High percentile of attack connections."; 2301 uses connection; 2302 } 2303 container peak-c { 2304 description 2305 "Peak attack connections."; 2306 uses connection; 2307 } 2308 } 2310 grouping connection-protocol-percentile { 2311 description 2312 "Total attack connections."; 2313 list low-percentile-l { 2314 key "protocol"; 2315 description 2316 "Low percentile of attack connections."; 2317 leaf protocol { 2318 type uint8; 2319 description 2320 "The transport protocol. 2321 Values are taken from the IANA Protocol Numbers registry: 2322 ."; 2323 } 2324 uses connection; 2325 } 2326 list mid-percentile-l { 2327 key "protocol"; 2328 description 2329 "Mid percentile of attack connections."; 2331 leaf protocol { 2332 type uint8; 2333 description 2334 "The transport protocol. 2335 Values are taken from the IANA Protocol Numbers registry: 2336 ."; 2337 } 2338 uses connection; 2339 } 2340 list high-percentile-l { 2341 key "protocol"; 2342 description 2343 "Highg percentile of attack connections."; 2344 leaf protocol { 2345 type uint8; 2346 description 2347 "The transport protocol. 2348 Values are taken from the IANA Protocol Numbers registry: 2349 ."; 2350 } 2351 uses connection; 2352 } 2353 list peak-l { 2354 key "protocol"; 2355 description 2356 "Peak attack connections."; 2357 leaf protocol { 2358 type uint8; 2359 description 2360 "The transport protocol. 2361 Values are taken from the IANA Protocol Numbers registry: 2362 ."; 2363 } 2364 uses connection; 2365 } 2366 } 2368 grouping attack-detail { 2369 description 2370 "Various information and details that describe the on-going 2371 attacks that needs to be mitigated by the DOTS server. 2372 The attack details need to cover well-known and common attacks 2373 (such as a SYN Flood) along with new emerging or vendor-specific 2374 attacks."; 2375 leaf id { 2376 type uint32; 2377 description 2378 "Vendor ID is a security vendor's Enterprise Number."; 2380 } 2381 leaf attack-id { 2382 type string; 2383 description 2384 "Unique identifier assigned by the vendor for the attack."; 2385 } 2386 leaf attack-name { 2387 type string; 2388 description 2389 "Textual representation of attack description. Natural Language 2390 Processing techniques (e.g., word embedding) can possibly be used 2391 to map the attack description to an attack type."; 2392 } 2393 leaf attack-severity { 2394 type attack-severity; 2395 description 2396 "Severity level of an attack"; 2397 } 2398 leaf start-time { 2399 type uint64; 2400 description 2401 "The time the attack started. Start time is represented in seconds 2402 relative to 1970-01-01T00:00:00Z in UTC time."; 2403 } 2404 leaf end-time { 2405 type uint64; 2406 description 2407 "The time the attack ended. End time is represented in seconds 2408 relative to 1970-01-01T00:00:00Z in UTC time."; 2409 } 2410 container source-count { 2411 description 2412 "Indicates the count of unique sources involved 2413 in the attack."; 2414 uses percentile; 2415 } 2416 } 2418 grouping top-talker-aggregate { 2419 description 2420 "Top attack sources."; 2421 list source-prefix { 2422 key "source-prefix"; 2423 description 2424 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2425 leaf spoofed-status { 2426 type boolean; 2427 description 2428 "Indicates whether this address is spoofed."; 2429 } 2430 leaf source-prefix { 2431 type inet:ip-prefix; 2432 description 2433 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2434 } 2435 list total-attack-traffic { 2436 key "unit"; 2437 description 2438 "Total attack traffic issued from this source."; 2439 uses traffic-unit; 2440 } 2441 container total-attack-connection { 2442 description 2443 "Total attack connections issued from this source."; 2444 uses connection-percentile; 2445 } 2446 } 2447 } 2449 grouping top-talker { 2450 description 2451 "Top attack sources."; 2452 list source-prefix { 2453 key "source-prefix"; 2454 description 2455 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2456 leaf spoofed-status { 2457 type boolean; 2458 description 2459 "Indicates whether this address is spoofed."; 2460 } 2461 leaf source-prefix { 2462 type inet:ip-prefix; 2463 description 2464 "IPv4 or IPv6 prefix identifying the attacker(s)."; 2465 } 2466 list total-attack-traffic { 2467 key "unit"; 2468 description 2469 "Total attack traffic issued from this source."; 2470 uses traffic-unit; 2471 } 2472 container total-attack-connection { 2473 description 2474 "Total attack connections issued from this source."; 2475 uses connection-protocol-percentile; 2477 } 2478 } 2479 } 2481 grouping baseline { 2482 description 2483 "Grouping for the telemetry baseline."; 2484 uses ietf-data:target; 2485 list total-traffic-normal-baseline { 2486 key "unit protocol"; 2487 description 2488 "Total traffic normal baselines."; 2489 uses traffic-unit-protocol; 2490 } 2491 list total-connection-capacity { 2492 key "protocol"; 2493 description 2494 "Total connection capacity."; 2495 leaf protocol { 2496 type uint8; 2497 description 2498 "The transport protocol. 2499 Values are taken from the IANA Protocol Numbers registry: 2500 ."; 2501 } 2502 uses total-connection-capacity; 2503 } 2504 } 2506 grouping pre-mitigation { 2507 description 2508 "Grouping for the telemetry data."; 2509 list total-traffic { 2510 key "unit protocol"; 2511 description 2512 "Total traffic."; 2513 uses traffic-unit-protocol; 2514 } 2515 list total-attack-traffic { 2516 key "unit protocol"; 2517 description 2518 "Total attack traffic per protocol."; 2519 uses traffic-unit-protocol; 2520 } 2521 container total-attack-connection { 2522 description 2523 "Total attack connections."; 2524 uses connection-protocol-percentile; 2526 } 2527 container attack-detail { 2528 description 2529 "Attack details."; 2530 uses attack-detail; 2531 container top-talker { 2532 description 2533 "Top attack sources."; 2534 uses top-talker; 2535 } 2536 } 2537 } 2539 augment "/ietf-signal:dots-signal/ietf-signal:message-type/" 2540 + "ietf-signal:mitigation-scope/ietf-signal:scope" { 2541 if-feature "dots-telemetry"; 2542 description 2543 "Extends mitigation scope with telemetry update data."; 2544 list total-traffic { 2545 key "unit protocol"; 2546 description 2547 "Total traffic."; 2548 uses traffic-unit-protocol; 2549 } 2550 list total-attack-traffic { 2551 key "unit"; 2552 description 2553 "Total attack traffic."; 2554 uses traffic-unit; 2555 } 2556 container total-attack-connection { 2557 description 2558 "Total attack connections."; 2559 uses connection-percentile; 2560 } 2561 container attack-detail { 2562 description 2563 "Atatck details"; 2564 uses attack-detail; 2565 container top-talker { 2566 description 2567 "Top attack sources."; 2568 uses top-talker-aggregate; 2569 } 2570 } 2571 } 2573 augment "/ietf-signal:dots-signal/ietf-signal:message-type" { 2574 if-feature "dots-telemetry"; 2575 description 2576 "Add a new choice to enclose telemetry data in DOTS 2577 signal channel."; 2578 case telemetry-setup { 2579 description 2580 "Indicates the message is about telemetry."; 2581 list telemetry { 2582 key "cuid tsid"; 2583 description 2584 "The telemetry data per DOTS client."; 2585 leaf cuid { 2586 type string; 2587 description 2588 "A unique identifier that is 2589 generated by a DOTS client to prevent 2590 request collisions. It is expected that the 2591 cuid will remain consistent throughout the 2592 lifetime of the DOTS client."; 2593 } 2594 leaf cdid { 2595 type string; 2596 description 2597 "The cdid should be included by a server-domain 2598 DOTS gateway to propagate the client domain 2599 identification information from the 2600 gateway's client-facing-side to the gateway's 2601 server-facing-side, and from the gateway's 2602 server-facing-side to the DOTS server. 2604 It may be used by the final DOTS server 2605 for policy enforcement purposes."; 2606 } 2607 leaf tsid { 2608 type uint32; 2609 description 2610 "An identifier for the DOTS telemetry setup 2611 data."; 2612 } 2613 choice setup-type { 2614 description 2615 "Can be a mitigation configuration, a pipe capacity, 2616 or baseline message."; 2617 case telemetry-config { 2618 description 2619 "Uses to set low, mid, and high percentile values."; 2620 container current-config { 2621 description 2622 "Current configuration values."; 2623 uses percentile-config; 2624 uses unit-config; 2625 leaf server-initiated-telemetry { 2626 type boolean; 2627 description 2628 "Used by a DOTS client to enable/disable whether it 2629 accepts pre-mitigation telemetry from the DOTS 2630 server."; 2631 } 2632 leaf telemetry-notify-interval { 2633 type uint32 { 2634 range "1 .. 3600"; 2635 } 2636 units "seconds"; 2637 description 2638 "Minimum number of seconds between successive 2639 telemetry notifications."; 2640 } 2641 } 2642 container max-config-values { 2643 description 2644 "Maximum acceptable configuration values."; 2645 config false; 2646 uses percentile-config; 2647 // Check if this is right place for indciating this capability 2648 leaf server-initiated-telemetry { 2649 type boolean; 2650 description 2651 "Indicates whether the DOTS server can be instructed 2652 to send pre-mitigation telemetry. If set to FALSE 2653 or the attribute is not present, this is an indication 2654 that the server does not support this capability."; 2655 } 2656 leaf telemetry-notify-interval { 2657 type uint32 { 2658 range "1 .. 3600"; 2659 } 2660 units "seconds"; 2661 description 2662 "Minimum number of seconds between successive 2663 telemetry notifications."; 2664 } 2665 } 2666 container min-config-values { 2667 description 2668 "Minimum acceptable configuration values."; 2669 config false; 2670 uses percentile-config; 2671 leaf telemetry-notify-interval { 2672 type uint32 { 2673 range "1 .. 3600"; 2674 } 2675 units "seconds"; 2676 description 2677 "Minimum number of seconds between successive 2678 telemetry notifications."; 2679 } 2680 } 2681 container supported-units { 2682 description 2683 "Supported units and default activation status."; 2684 config false; 2685 uses unit-config; 2686 } 2687 } 2688 case pipe { 2689 description 2690 "Total pipe capacity of a DOTS client domain"; 2691 list total-pipe-capacity { 2692 key "link-id unit"; 2693 description 2694 "Total pipe capacity of a DOTS client domain."; 2695 leaf link-id { 2696 type nt:link-id; 2697 description 2698 "Identifier of an interconnection link."; 2699 } 2700 leaf capacity { 2701 type uint64; 2702 mandatory true; 2703 description 2704 "Pipe capacity."; 2705 } 2706 leaf unit { 2707 type unit; 2708 description 2709 "The traffic can be measured in packets per 2710 second (PPS) or kilo packets per second (Kpps) and Bits per 2711 Second (BPS), and kilobytes per second or megabytes per second 2712 or gigabytes per second."; 2713 } 2714 } 2715 } 2716 case baseline { 2717 description 2718 "Traffic baseline information"; 2719 list baseline { 2720 key "id"; 2721 description 2722 "Traffic baseline information"; 2723 leaf id { 2724 type uint32; 2725 must '. >= 1'; 2726 description 2727 "A baseline entry identifier."; 2728 } 2729 uses baseline; 2730 } 2731 } 2732 } 2733 } 2734 } 2735 case telemetry { 2736 description 2737 "Indicates the message is about telemetry."; 2738 list pre-mitigation { 2739 key "cuid id"; 2740 description 2741 "Pre-mitigation telemetry per DOTS client."; 2742 leaf cuid { 2743 type string; 2744 description 2745 "A unique identifier that is 2746 generated by a DOTS client to prevent 2747 request collisions. It is expected that the 2748 cuid will remain consistent throughout the 2749 lifetime of the DOTS client."; 2750 } 2751 leaf cdid { 2752 type string; 2753 description 2754 "The cdid should be included by a server-domain 2755 DOTS gateway to propagate the client domain 2756 identification information from the 2757 gateway's client-facing-side to the gateway's 2758 server-facing-side, and from the gateway's 2759 server-facing-side to the DOTS server. 2761 It may be used by the final DOTS server 2762 for policy enforcement purposes."; 2763 } 2764 leaf id { 2765 type uint32; 2766 description 2767 "An identifier to uniquely demux telemetry data send using 2768 the same message."; 2769 } 2770 container target { 2771 description 2772 "Indicates the target."; 2773 uses ietf-data:target; 2774 } 2775 uses pre-mitigation; 2776 } 2777 } 2778 } 2779 } 2780 2782 10. YANG/JSON Mapping Parameters to CBOR 2784 All DOTS telemetry parameters in the payload of the DOTS signal 2785 channel MUST be mapped to CBOR types as shown in the following table: 2787 +----------------------+-------------+------+---------------+--------+ 2788 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 2789 | | Type | Key | Type & | Type | 2790 | | | | Information | | 2791 +----------------------+-------------+------+---------------+--------+ 2792 | ietf-dots-signal-cha | | | | | 2793 | nnel:telemetry | container |32776 | 5 map | Object | 2794 | tsid | uint32 |32777 | 0 unsigned | Number | 2795 | telemetry-config | container |32778 | 5 map | Object | 2796 | low-percentile | decimal64 |32779 | 6 tag 4 | | 2797 | | | | [-2, integer]| String | 2798 | mid-percentile | decimal64 |32780 | 6 tag 4 | | 2799 | | | | [-2, integer]| String | 2800 | high-percentile | decimal64 |32781 | 6 tag 4 | | 2801 | | | | [-2, integer]| String | 2802 | unit-config | list |32782 | 4 array | Array | 2803 | unit | enumeration |32783 | 0 unsigned | String | 2804 | unit-status | boolean |32784 | 7 bits 20 | False | 2805 | | | | 7 bits 21 | True | 2806 | total-pipe-capability| list |32785 | 4 array | Array | 2807 | pipe | uint64 |32786 | 0 unsigned | String | 2808 | pre-mitigation | list |32787 | 4 array | Array | 2809 | ietf-dots-signal-cha | | | | | 2810 | nnel:telemetry-setup | container |32888 | 5 map | Object | 2811 | total-traffic- | | | | | 2812 | normal-baseline | list |32789 | 4 array | Array | 2813 | low-percentile-g | yang:gauge64|32790 | 0 unsigned | String | 2814 | mid-percentile-g | yang:gauge64|32791 | 0 unsigned | String | 2815 | high-percentile-g | yang:gauge64|32792 | 0 unsigned | String | 2816 | peak-g | yang:gauge64|32793 | 0 unsigned | String | 2817 | total-attack-traffic | list |32794 | 4 array | Array | 2818 | total-traffic | list |32795 | 4 array | Array | 2819 | total-connection- | | | | | 2820 | capacity | list |32796 | 4 array | Array | 2821 | connection | uint64 |32797 | 0 unsigned | String | 2822 | connection-client | uint64 |32798 | 0 unsigned | String | 2823 | embryonic | uint64 |32799 | 0 unsigned | String | 2824 | embryonic-client | uint64 |32800 | 0 unsigned | String | 2825 | connection-ps | uint64 |32801 | 0 unsigned | String | 2826 | connection-client-ps | uint64 |32802 | 0 unsigned | String | 2827 | request-ps | uint64 |32803 | 0 unsigned | String | 2828 | request-client-ps | uint64 |32804 | 0 unsigned | String | 2829 | partial-request-ps | uint64 |32805 | 0 unsigned | String | 2830 | partial-request- | | | | | 2831 | client-ps | uint64 |32806 | 0 unsigned | String | 2832 | total-attack- | | | | | 2833 | connection | container |32807 | 5 map | Object | 2834 | low-percentile-l | list |32808 | 4 array | Array | 2835 | mid-percentile-l | list |32809 | 4 array | Array | 2836 | high-percentile-l | list |32810 | 4 array | Array | 2837 | peak-l | list |32811 | 4 array | Array | 2838 | attack-detail | container |32812 | 5 map | Object | 2839 | id | uint32 |32813 | 0 unsigned | Number | 2840 | attack-id | string |32814 | 3 text string | String | 2841 | attack-name | string |32815 | 3 text string | String | 2842 | attack-severity | enumeration |32816 | 0 unsigned | String | 2843 | start-time | uint64 |32817 | 0 unsigned | String | 2844 | end-time | uint64 |32819 | 0 unsigned | String | 2845 | source-count | container |32820 | 5 map | Object | 2846 | top-talker | container |32821 | 5 map | Object | 2847 | spoofed-status | boolean |32822 | 7 bits 20 | False | 2848 | | | | 7 bits 21 | True | 2849 | low-percentile-c | container |32823 | 5 map | Object | 2850 | mid-percentile-c | container |32824 | 5 map | Object | 2851 | high-percentile-c | container |32825 | 5 map | Object | 2852 | peak-c | container |32826 | 5 map | Object | 2853 | baseline | container |32827 | 5 map | Object | 2854 | current-config | container |32828 | 5 map | Object | 2855 | max-config-values | container |32829 | 5 map | Object | 2856 | min-config-values | container |32830 | 5 map | Object | 2857 | supported-units | container |32831 | 5 map | Object | 2858 | server-initiated- | boolean |32832 | 7 bits 20 | False | 2859 | telemetry | | | 7 bits 21 | True | 2860 | telemetry-notify- | uint32 |32833 | 0 unsigned | Number | 2861 | interval | | | | | 2862 +----------------------+-------------+------+---------------+--------+ 2864 11. IANA Considerations 2866 11.1. DOTS Signal Channel CBOR Key Values 2868 This specification registers the DOTS telemetry attributes in the 2869 IANA "DOTS Signal Channel CBOR Key Values" registry available at 2870 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 2871 cbor-key-values. 2873 The DOTS telemetry attributes defined in this specification are 2874 comprehension-optional parameters. 2876 o Note to the RFC Editor: (1) CBOR keys are assigned from the 2877 32768-49151 range. (2) Please assign the following suggested 2878 values. 2880 +----------------------+-------+-------+------------+---------------+ 2881 | Parameter Name | CBOR | CBOR | Change | Specification | 2882 | | Key | Major | Controller | Document(s) | 2883 | | Value | Type | | | 2884 +----------------------+-------+-------+------------+---------------+ 2885 | ietf-dots-signal-cha | 32776 | 5 | IESG | [RFCXXXX] | 2886 | nnel:telemetry | | | | | 2887 | tsid | 32777 | 0 | IESG | [RFCXXXX] | 2888 | telemetry-config | 32778 | 5 | IESG | [RFCXXXX] | 2889 | low-percentile | 32779 | 6tag4 | IESG | [RFCXXXX] | 2890 | mid-percentile | 32780 | 6tag4 | IESG | [RFCXXXX] | 2891 | high-percentile | 32781 | 6tag4 | IESG | [RFCXXXX] | 2892 | unit-config | 32782 | 4 | IESG | [RFCXXXX] | 2893 | unit | 32783 | 0 | IESG | [RFCXXXX] | 2894 | unit-status | 32784 | 7 | IESG | [RFCXXXX] | 2895 | total-pipe-capability| 32785 | 4 | IESG | [RFCXXXX] | 2896 | pipe | 32786 | 0 | IESG | [RFCXXXX] | 2897 | pre-mitigation | 32787 | 4 | IESG | [RFCXXXX] | 2898 | ietf-dots-signal-cha | 32788 | 5 | IESG | [RFCXXXX] | 2899 | nnel:telemetry | | | | | 2900 | total-traffic- | 32789 | 4 | IESG | [RFCXXXX] | 2901 | normal-baseline | | | | | 2902 | low-percentile-g | 32790 | 0 | IESG | [RFCXXXX] | 2903 | mid-percentile-g | 32791 | 0 | IESG | [RFCXXXX] | 2904 | high-percentile-g | 32792 | 0 | IESG | [RFCXXXX] | 2905 | peak-g | 32793 | 0 | IESG | [RFCXXXX] | 2906 | total-attack-traffic | 32794 | 4 | IESG | [RFCXXXX] | 2907 | total-traffic | 32795 | 4 | IESG | [RFCXXXX] | 2908 | total-connection- | 32796 | 4 | IESG | [RFCXXXX] | 2909 | capacity | | | | | 2910 | connection | 32797 | 0 | IESG | [RFCXXXX] | 2911 | connection-client | 32798 | 0 | IESG | [RFCXXXX] | 2912 | embryonic | 32799 | 0 | IESG | [RFCXXXX] | 2913 | embryonic-client | 32800 | 0 | IESG | [RFCXXXX] | 2914 | connection-ps | 32801 | 0 | IESG | [RFCXXXX] | 2915 | connection-client-ps | 32802 | 0 | IESG | [RFCXXXX] | 2916 | request-ps | 32803 | 0 | IESG | [RFCXXXX] | 2917 | request-client-ps | 32804 | 0 | IESG | [RFCXXXX] | 2918 | partial-request-ps | 32805 | 0 | IESG | [RFCXXXX] | 2919 | partial-request- | 32806 | 0 | IESG | [RFCXXXX] | 2920 | client-ps | | | | | 2921 | total-attack- | 32807 | 5 | IESG | [RFCXXXX] | 2922 | connection | | | | | 2923 | low-percentile-l | 32808 | 4 | IESG | [RFCXXXX] | 2924 | mid-percentile-l | 32809 | 4 | IESG | [RFCXXXX] | 2925 | high-percentile-l | 32810 | 4 | IESG | [RFCXXXX] | 2926 | peak-l | 32811 | 4 | IESG | [RFCXXXX] | 2927 | attack-detail | 32812 | 5 | IESG | [RFCXXXX] | 2928 | id | 32813 | 0 | IESG | [RFCXXXX] | 2929 | attack-id | 32814 | 3 | IESG | [RFCXXXX] | 2930 | attack-name | 32815 | 3 | IESG | [RFCXXXX] | 2931 | attack-severity | 32816 | 0 | IESG | [RFCXXXX] | 2932 | start-time | 32817 | 0 | IESG | [RFCXXXX] | 2933 | end-time | 32819 | 0 | IESG | [RFCXXXX] | 2934 | source-count | 32820 | 5 | IESG | [RFCXXXX] | 2935 | top-talker | 32821 | 5 | IESG | [RFCXXXX] | 2936 | spoofed-status | 32822 | 7 | IESG | [RFCXXXX] | 2937 | low-percentile-c | 32823 | 5 | IESG | [RFCXXXX] | 2938 | mid-percentile-c | 32824 | 5 | IESG | [RFCXXXX] | 2939 | high-percentile-c | 32825 | 5 | IESG | [RFCXXXX] | 2940 | peak-c | 32826 | 5 | IESG | [RFCXXXX] | 2941 | ietf-dots-signal-cha | 32827 | 5 | IESG | [RFCXXXX] | 2942 | current-config | 32828 | 5 | IESG | [RFCXXXX] | 2943 | max-config-value | 32829 | 5 | IESG | [RFCXXXX] | 2944 | min-config-values | 32830 | 5 | IESG | [RFCXXXX] | 2945 | supported-units | 32831 | 5 | IESG | [RFCXXXX] | 2946 | server-initiated- | 32832 | 7 | IESG | [RFCXXXX] | 2947 | telemetry | | | | | 2948 | telemetry-notify- | 32833 | 0 | IESG | [RFCXXXX] | 2949 | interval | | | | | 2950 +----------------------+-------+-------+------------+---------------+ 2952 11.2. DOTS Signal Channel Conflict Cause Codes 2954 This specification requests IANA to assign a new code from the "DOTS 2955 Signal Channel Conflict Cause Codes" registry available at 2956 https://www.iana.org/assignments/dots/dots.xhtml#dots-signal-channel- 2957 conflict-cause-codes. 2959 Code Label Description Reference 2960 TBA overlapping-pipes Overlapping pipe scope [RFCXXXX] 2962 11.3. DOTS Signal Telemetry YANG Module 2964 This document requests IANA to register the following URI in the "ns" 2965 subregistry within the "IETF XML Registry" [RFC3688]: 2967 URI: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 2968 Registrant Contact: The IESG. 2969 XML: N/A; the requested URI is an XML namespace. 2971 This document requests IANA to register the following YANG module in 2972 the "YANG Module Names" subregistry [RFC7950] within the "YANG 2973 Parameters" registry. 2975 name: ietf-dots-telemetry 2976 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-telemetry 2977 maintained by IANA: N 2978 prefix: dots-telemetry 2979 reference: RFC XXXX 2981 12. Security Considerations 2983 Security considerations in [I-D.ietf-dots-signal-channel] need to be 2984 taken into consideration. 2986 13. Contributors 2988 The following individuals have contributed to this document: 2990 o Li Su, CMCC, Email: suli@chinamobile.com 2992 o Jin Peng, CMCC, Email: pengjin@chinamobile.com 2994 o Pan Wei, Huawei, Email: william.panwei@huawei.com 2996 14. Acknowledgements 2998 The authors would like to thank Flemming Andreasen, Liang Xia, and 2999 Kaname Nishizuka co-authors of https://tools.ietf.org/html/draft- 3000 doron-dots-telemetry-00 draft and everyone who had contributed to 3001 that document. 3003 Authors would like to thank Kaname Nishizuka, Jon Shallow, Wei Pan 3004 and Yuuhei Hayashi for comments and review. 3006 15. References 3008 15.1. Normative References 3010 [Enterprise-Numbers] 3011 "Private Enterprise Numbers", 2005, . 3014 [I-D.ietf-dots-data-channel] 3015 Boucadair, M. and T. Reddy.K, "Distributed Denial-of- 3016 Service Open Threat Signaling (DOTS) Data Channel 3017 Specification", draft-ietf-dots-data-channel-31 (work in 3018 progress), July 2019. 3020 [I-D.ietf-dots-signal-call-home] 3021 Reddy.K, T., Boucadair, M., and J. Shallow, "Distributed 3022 Denial-of-Service Open Threat Signaling (DOTS) Signal 3023 Channel Call Home", draft-ietf-dots-signal-call-home-07 3024 (work in progress), November 2019. 3026 [I-D.ietf-dots-signal-channel] 3027 Reddy.K, T., Boucadair, M., Patil, P., Mortensen, A., and 3028 N. Teague, "Distributed Denial-of-Service Open Threat 3029 Signaling (DOTS) Signal Channel Specification", draft- 3030 ietf-dots-signal-channel-41 (work in progress), January 3031 2020. 3033 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3034 Requirement Levels", BCP 14, RFC 2119, 3035 DOI 10.17487/RFC2119, March 1997, 3036 . 3038 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3039 DOI 10.17487/RFC3688, January 2004, 3040 . 3042 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 3043 RFC 6991, DOI 10.17487/RFC6991, July 2013, 3044 . 3046 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3047 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3048 October 2013, . 3050 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3051 Application Protocol (CoAP)", RFC 7641, 3052 DOI 10.17487/RFC7641, September 2015, 3053 . 3055 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3056 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3057 . 3059 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 3060 the Constrained Application Protocol (CoAP)", RFC 7959, 3061 DOI 10.17487/RFC7959, August 2016, 3062 . 3064 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3065 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3066 May 2017, . 3068 15.2. Informative References 3070 [I-D.ietf-dots-signal-filter-control] 3071 Nishizuka, K., Boucadair, M., Reddy.K, T., and T. Nagata, 3072 "Controlling Filtering Rules Using Distributed Denial-of- 3073 Service Open Threat Signaling (DOTS) Signal Channel", 3074 draft-ietf-dots-signal-filter-control-02 (work in 3075 progress), September 2019. 3077 [I-D.ietf-dots-use-cases] 3078 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 3079 L., and K. Nishizuka, "Use cases for DDoS Open Threat 3080 Signaling", draft-ietf-dots-use-cases-20 (work in 3081 progress), September 2019. 3083 [RFC2330] Paxson, V., Almes, G., Mahdavi, J., and M. Mathis, 3084 "Framework for IP Performance Metrics", RFC 2330, 3085 DOI 10.17487/RFC2330, May 1998, 3086 . 3088 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 3089 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 3090 . 3092 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 3093 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 3094 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 3095 2018, . 3097 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 3098 Threat Signaling (DOTS) Requirements", RFC 8612, 3099 DOI 10.17487/RFC8612, May 2019, 3100 . 3102 Authors' Addresses 3104 Mohamed Boucadair (editor) 3105 Orange 3106 Rennes 35000 3107 France 3109 Email: mohamed.boucadair@orange.com 3111 Tirumaleswar Reddy (editor) 3112 McAfee, Inc. 3113 Embassy Golf Link Business Park 3114 Bangalore, Karnataka 560071 3115 India 3117 Email: kondtir@gmail.com 3119 Ehud Doron 3120 Radware Ltd. 3121 Raoul Wallenberg Street 3122 Tel-Aviv 69710 3123 Israel 3125 Email: ehudd@radware.com 3127 Meiling Chen 3128 CMCC 3129 32, Xuanwumen West 3130 BeiJing, BeiJing 100053 3131 China 3133 Email: chenmeiling@chinamobile.com