idnits 2.17.1 draft-ietf-dots-signal-filter-control-07.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 : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFCXXXX]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 25, 2020) is 1394 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 1017, but not defined ** Obsolete normative reference: RFC 8782 (Obsoleted by RFC 9132) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS K. Nishizuka 3 Internet-Draft NTT Communications 4 Intended status: Standards Track M. Boucadair 5 Expires: December 27, 2020 Orange 6 T. Reddy 7 McAfee 8 T. Nagata 9 Lepidum 10 June 25, 2020 12 Controlling Filtering Rules Using Distributed Denial-of-Service Open 13 Threat Signaling (DOTS) Signal Channel 14 draft-ietf-dots-signal-filter-control-07 16 Abstract 18 This document specifies an extension to the Distributed Denial-of- 19 Service Open Threat Signaling (DOTS) signal channel protocol so that 20 DOTS clients can control their filtering rules when an attack 21 mitigation is active. 23 Particularly, this extension allows a DOTS client to activate or de- 24 activate existing filtering rules during a DDoS attack. The 25 characterization of these filtering rules is conveyed by a DOTS 26 client during an idle time (i.e., no mitigation is active) by means 27 of the DOTS data channel protocol. 29 Editorial Note (To be removed by RFC Editor) 31 Please update these statements within the document with the RFC 32 number to be assigned to this document: 34 o "This version of this YANG module is part of RFC XXXX;" 36 o "RFC XXXX: Controlling Filtering Rules Using Distributed Denial- 37 of-Service Open Threat Signaling (DOTS) Signal Channel"; 39 o reference: RFC XXXX 41 o [RFCXXXX] 43 Please update the "revision" date of the YANG module. 45 Status of This Memo 47 This Internet-Draft is submitted in full conformance with the 48 provisions of BCP 78 and BCP 79. 50 Internet-Drafts are working documents of the Internet Engineering 51 Task Force (IETF). Note that other groups may also distribute 52 working documents as Internet-Drafts. The list of current Internet- 53 Drafts is at https://datatracker.ietf.org/drafts/current/. 55 Internet-Drafts are draft documents valid for a maximum of six months 56 and may be updated, replaced, or obsoleted by other documents at any 57 time. It is inappropriate to use Internet-Drafts as reference 58 material or to cite them other than as "work in progress." 60 This Internet-Draft will expire on December 27, 2020. 62 Copyright Notice 64 Copyright (c) 2020 IETF Trust and the persons identified as the 65 document authors. All rights reserved. 67 This document is subject to BCP 78 and the IETF Trust's Legal 68 Provisions Relating to IETF Documents 69 (https://trustee.ietf.org/license-info) in effect on the date of 70 publication of this document. Please review these documents 71 carefully, as they describe your rights and restrictions with respect 72 to this document. Code Components extracted from this document must 73 include Simplified BSD License text as described in Section 4.e of 74 the Trust Legal Provisions and are provided without warranty as 75 described in the Simplified BSD License. 77 Table of Contents 79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 80 1.1. The Problem . . . . . . . . . . . . . . . . . . . . . . . 3 81 1.2. Controlling Filtering Rules Using DOTS Signal Channel . . 4 82 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 83 3. Controlling Filtering Rules of a DOTS Client . . . . . . . . 5 84 3.1. Binding DOTS Data and Signal Channels . . . . . . . . . . 5 85 3.2. DOTS Signal Channel Extension . . . . . . . . . . . . . . 6 86 3.2.1. Parameters and Behaviors . . . . . . . . . . . . . . 6 87 3.2.2. DOTS Signal Filtering Control Module . . . . . . . . 9 88 3.2.2.1. Tree Structure . . . . . . . . . . . . . . . . . 10 89 3.2.2.2. YANG Module . . . . . . . . . . . . . . . . . . . 10 90 4. Some Examples . . . . . . . . . . . . . . . . . . . . . . . . 12 91 4.1. Conflict Handling . . . . . . . . . . . . . . . . . . . . 12 92 4.2. On-Demand Activation of an Accept-List Filter . . . . . . 17 93 4.3. DOTS Servers/Mitigators Lacking Capacity . . . . . . . . 18 94 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 95 5.1. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 22 96 5.2. DOTS Signal Filtering Control YANG Module . . . . . . . . 23 97 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 98 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 24 99 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 100 8.1. Normative References . . . . . . . . . . . . . . . . . . 24 101 8.2. Informative References . . . . . . . . . . . . . . . . . 25 102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 104 1. Introduction 106 1.1. The Problem 108 In the Distributed Denial-of-Service Open Threat Signaling (DOTS) 109 architecture [I-D.ietf-dots-architecture], DOTS clients and servers 110 communicate using both a signal channel protocol [RFC8782] and a data 111 channel protocol [RFC8783]. 113 The DOTS data channel protocol [RFC8783] is used for bulk data 114 exchange between DOTS agents to improve the coordination of parties 115 involved in the response to a Distributed Denial-of-Service (DDoS) 116 attack. Filter management is one of its tasks which enables a DOTS 117 client to retrieve the filtering capabilities of a DOTS server and to 118 manage filtering rules. Typically, these filtering rules are used 119 for dropping or rate-limiting unwanted traffic, and permitting 120 accept-listed traffic. 122 The DOTS signal channel protocol [RFC8782] is designed to be 123 resilient under extremely hostile network conditions and provides 124 continued contact between DOTS agents even as DDoS attack traffic 125 saturates the link. The DOTS signal channel can be established 126 between two DOTS agents prior to or during an attack. At any time, 127 the DOTS client may send mitigation requests (as per Section 4.4 of 128 [RFC8782]) to a DOTS server over the active signal channel. While 129 mitigation is active, the DOTS server periodically sends status 130 messages to the DOTS client, including basic mitigation feedback 131 details. In case of a massive DDoS attack that saturates the 132 incoming link(s) to the DOTS client, all traffic from the DOTS server 133 to the DOTS client will likely be dropped. However, the DOTS server 134 may still receive DOTS messages sent from the DOTS client over the 135 signalling channel thanks to the heartbeat requests keeping the 136 channel active (as described in Section 4.7 of [RFC8782]). 138 Unlike the DOTS signal channel protocol, the DOTS data channel 139 protocol is not expected to deal with attack conditions. As such, an 140 issue that might be encountered in some deployments is when filters 141 installed by means of the DOTS data channel protocol may not function 142 as expected during DDoS attacks or, worse, exacerbate an ongoing DDoS 143 attack. In such conditions the DOTS data channel protocol cannot be 144 used to change these filters, which may complicate DDoS mitigation 145 operations [Interop]. 147 A typical case is a conflict between filtering rules installed by a 148 DOTS client and the mitigation actions of a DDoS mitigator. 149 Consider, for instance, a DOTS client that configures during 'idle' 150 time (i.e., no mitigation is active) some filtering rules using the 151 DOTS data channel protocol to permit traffic from accept-listed 152 sources. However, during a volumetric DDoS attack the DDoS mitigator 153 identifies the source addresses/prefixes in the accept-listed 154 filtering rules are attacking the target. For example, an attacker 155 can spoof the IP addresses of accept-listed sources to generate 156 attack traffic or the attacker can compromise the accept-listed 157 sources and program them to launch a DDoS attack. 159 [RFC8782] is designed so that the DDoS server notifies the above 160 conflict to the DOTS client (that is, 'conflict-cause' parameter set 161 to 2 (Conflicts with an existing accept list)), but the DOTS client 162 may not be able to withdraw the accept-list rules during the attack 163 period due to the high-volume attack traffic saturating the inbound 164 link to the DOTS client domain. In other words, the DOTS client 165 cannot use the DOTS data channel protocol to withdraw the accept-list 166 filters when a DDoS attack is in progress. 168 1.2. Controlling Filtering Rules Using DOTS Signal Channel 170 This specification addresses the problems discussed in Section 1.1 by 171 adding a capability for managing filtering rules using the DOTS 172 signal channel protocol, which enables a DOTS client to request the 173 activation (or deactivation) of filtering rules during a DDoS attack. 174 Note that creating these filtering rules is still the responsibility 175 of the DOTS data channel [RFC8783]. 177 The DOTS signal channel protocol is designed to enable a DOTS client 178 to contact a DOTS server for help even under severe network 179 congestion conditions. Therefore, extending the DOTS signal channel 180 protocol to manage the filtering rules during an attack will enhance 181 the protection capability offered by DOTS protocols. 183 Note: The experiment at the IETF103 hackathon [Interop] showed 184 that even when the inbound link is saturated by DDoS attack 185 traffic, the DOTS client can signal mitigation requests using the 186 DOTS signal channel over the saturated link. 188 Conflicts that are induced by filters installed by other DOTS clients 189 of the same domain are not discussed in this specification. 191 An augmentation to the DOTS signal channel YANG module is defined in 192 Section 3.2.2. 194 Sample examples are provided in Section 4, in particular: 196 o Section 4.1 illustrates how the filter control extension is used 197 when conflicts with Access Control Lists (ACLs) are detected and 198 reported by a DOTS server. 200 o Section 4.2 shows how a DOTS client can instruct a DOTS server to 201 safely forward some specific traffic in 'attack' time. 203 o Section 4.3 shows how a DOTS client can react if the DDoS traffic 204 is still being forwarded to the DOTS client domain even if 205 mitigation requests were sent to a DOTS server. 207 The JavaScript Object Notation (JSON) encoding of YANG-modeled data 208 [RFC7951] is used to illustrate the examples. 210 2. Terminology 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 214 "OPTIONAL" in this document are to be interpreted as described in BCP 215 14 [RFC2119] [RFC8174] when, and only when, they appear in all 216 capitals, as shown here. 218 The reader should be familiar with the terms defined in [RFC8612]. 220 The terminology for describing YANG modules is defined in [RFC7950]. 221 The meaning of the symbols in the tree diagram is defined in 222 [RFC8340]. 224 3. Controlling Filtering Rules of a DOTS Client 226 3.1. Binding DOTS Data and Signal Channels 228 The filtering rules eventually managed using the DOTS signal channel 229 protocol are created a priori by the same DOTS client using the DOTS 230 data channel protocol. Managing conflicts with filters installed by 231 other DOTS clients of the same domain is out of scope. 233 As discussed in Section 4.4.1 of [RFC8782], a DOTS client must use 234 the same 'cuid' for both the DOTS signal and data channels. This 235 requirement is meant to facilitate binding DOTS channels used by the 236 same DOTS client. 238 The DOTS signal and data channels from a DOTS client may or may not 239 use the same DOTS server. Nevertheless, the scope of the mitigation 240 request, alias, and filtering rules are not restricted to the DOTS 241 server but to the DOTS server domain. To that aim, DOTS servers 242 within a domain are assumed to have a mechanism to coordinate the 243 mitigation requests, aliases, and filtering rules to coordinate their 244 decisions for better mitigation operation efficiency. The exact 245 details about such mechanism is out of the scope of this document. 247 A filtering rule controlled by the DOTS signal channel is identified 248 by its ACL name (Section 4.3 of [RFC8782]). Note that an ACL name 249 unambiguously identifies an ACL bound to a DOTS client, but the same 250 name may be used by distinct DOTS clients. 252 The activation or deactivation of an ACL by the DOTS signal channel 253 overrides the 'activation-type' (defined in Section 4.3 of [RFC8783]) 254 a priori conveyed with the filtering rules using the DOTS data 255 channel protocol. 257 Once the attack is mitigated, the DOTS client may use the data 258 channel to control the 'activation-type' (e.g., revert to a default 259 value) of some of the filtering rules controlled by the DOTS signal 260 channel or delete some of these filters. This behavior is deployment 261 specific. 263 3.2. DOTS Signal Channel Extension 265 3.2.1. Parameters and Behaviors 267 This specification extends the mitigation request defined in 268 Section 4.4.1 of [RFC8782] to convey the intended control of 269 configured filtering rules. Concretely, the DOTS client conveys 270 'acl-list' attribute with the following sub-attributes in the CBOR 271 body of a mitigation request (see the YANG structure in 272 Section 3.2.2.1): 274 acl-name: A name of an access list defined using the DOTS data 275 channel (Section 4.3 of [RFC8783]) that is associated with the 276 DOTS client. 278 As a reminder, an ACL is an ordered list of Access Control Entries 279 (ACE). Each ACE has a list of match criteria and a list of 280 actions [RFC8783]. The list of configured ACLs can be retrieved 281 using the DOTS data channel during 'idle' time. 283 This is a mandatory attribute when 'acl-list' is included. 285 activation-type: Indicates the activation type of an ACL overriding 286 the existing 'activation-type' installed by the DOTS client using 287 the DOTS data channel. 289 As a reminder, this attribute can be set to 'deactivate', 290 'immediate', or 'activate-when-mitigating' as defined in 291 [RFC8783]. 293 Note that both 'immediate' and 'activate-when-mitigating' have an 294 immediate effect when a mitigation request is being processed by 295 the DOTS server. 297 This is an optional attribute. 299 By default, ACL-related operations are achieved using the DOTS data 300 channel protocol when no attack is ongoing. DOTS clients MUST NOT 301 use the filtering control over DOTS signal channel in 'idle' time; 302 such requests MUST be discarded by DOTS servers with 4.00 (Bad 303 Request). 305 During an attack time, DOTS clients may include 'acl-list', 'acl- 306 name', and 'activation-type' attributes in a mitigation request. 307 This request may be the initial mitigation request for a given 308 mitigation scope or a new one overriding an existing request. In 309 both cases, a new 'mid' MUST be used. Nevertheless, it is NOT 310 RECOMMENDED to include ACL attributes in an initial mitigation 311 request for a given mitigation scope or in a mitigation request 312 adjusting the mitigation scope. This recommendation is meant to 313 avoid delaying attack mitigations because of failures to process ACL 314 attributes. 316 As the attack evolves, DOTS clients can adjust the 'activation-type' 317 of an ACL conveyed in a mitigation request or control other filters 318 as necessary. This can be achieved by sending a PUT request with a 319 new 'mid' value. 321 It is RECOMMENDED for a DOTS client to subscribe to asynchronous 322 notifications of the attack mitigation, as detailed in 323 Section 4.4.2.1 of [RFC8782]. If not, the polling mechanism in 324 Section 4.4.2.2 of [RFC8782] has to be followed by the DOTS client. 326 A DOTS client relies on the information received from the DOTS server 327 and/or local information to the DOTS client domain to trigger a 328 filter control request. Only filters that are pertinent for an 329 ongoing mitigation should be controlled by a DOTS client using the 330 DOTS signal channel. 332 'acl-list', 'acl-name', and 'activation-type' are defined as 333 comprehension-required parameters. Following the rules in Section 6 334 of [RFC8782], if the DOTS server does not understand the 'acl-list' 335 or 'acl-name' or 'activation-type' attributes, it responds with a 336 "4.00 (Bad Request)" error response code. 338 If the DOTS server does not find the ACL name ('acl-name') conveyed 339 in the mitigation request for this DOTS client, it MUST respond with 340 4.04 (Not Found) error response code. 342 If the DOTS server finds the ACL name for this DOTS client, and 343 assuming the request passed the validation checks in Section 4.4.1 of 344 [RFC8782], the DOTS server MUST proceed with the 'activation-type' 345 update. The update is immediately enforced by the DOTS server and 346 will be maintained as the new activation type for the ACL name even 347 after the termination of the mitigation request. In addition, the 348 DOTS server MUST update the lifetime of the corresponding ACL similar 349 to the update when a refresh request is received using the DOTS data 350 channel (Section 7.2 of [RFC8783]). If, for some reason, the DOTS 351 server fails to apply the filter update, it MUST respond with 5.03 352 (Service Unavailable) error response code and include the failed ACL 353 update in the diagnostic payload of the response (an example is shown 354 in Figure 1). Else, the DOTS server replies with the appropriate 355 response code defined in Section 4.4.1 of [RFC8782]. 357 { 358 "ietf-dots-signal-channel:mitigation-scope": { 359 "scope": [ 360 { 361 "mid": 123, 362 "ietf-dots-signal-control:acl-list": [ 363 { 364 "acl-name": "an-accept-list", 365 "activation-type": "deactivate" 366 } 367 ] 368 } 369 ] 370 } 371 } 373 Figure 1: Example of a Diagnostic Payload Including Failed ACL Update 375 The JSON/YANG mappings for DOTS filter control attributes are shown 376 in Table 1. As a reminder, the mapping for 'acl-name' is defined in 377 Table 5 of [RFC8782]. 379 +-------------------+------------+--------+---------------+--------+ 380 | Parameter Name | YANG | CBOR | CBOR Major | JSON | 381 | | Type | Key | Type & | Type | 382 | | | | Information | | 383 +===================+============+========+===============+========+ 384 | activation-type | enumeration| TBA1 | 0 unsigned | String | 385 +-------------------+------------+--------+---------------+--------+ 386 | ietf-dots-signal- | | | | | 387 | control:acl-list | list | TBA2 | 4 array | Array | 388 +-------------------+------------+--------+---------------+--------+ 389 | acl-name | leafref | 23 | 3 text string | String | 390 +-------------------+------------+--------+---------------+--------+ 391 Table 1: JSON/YANG Mapping to CBOR for Filter Control Attributes 393 If the DOTS client receives a 5.03 (Service Unavailable) with a 394 diagnostic payload indicating a failed ACL update as a response to an 395 initial mitigation or a mitigation with adjusted scope, the DOTS 396 client MUST immediately send a new request which repeats all the 397 parameters as sent in the failed mitigation request but without 398 including the ACL attributes. After the expiry of Max-Age returned 399 in the 5.03 (Service Unavailable) response, the DOTS client retries 400 with a new mitigation request (i.e., a new 'mid') that repeats all 401 the parameters as sent in the failed mitigation request (i.e., the 402 one including the ACL attributes). 404 If, during an active mitigation, the 'activation-type' is changed at 405 the DOTS server (e.g., as a result of an external action) for an ACL 406 bound to a DOTS client, the DOTS server notifies that DOTS client of 407 the change by including the corresponding ACL parameters in an 408 asynchronous notification (the DOTS client is observing the active 409 mitigation) or in a response to a polling request (Section 4.4.2.2 of 410 [RFC8782]). 412 If the DOTS signal and data channels of a DOTS client are not 413 established with the same DOTS server of a DOTS server domain, the 414 above request processing operations are undertaken using the 415 coordination mechanism discussed in Section 3.1. 417 This specification does not require any modification to the efficacy 418 update and the withdrawal procedures defined in [RFC8782]. In 419 particular, ACL-related clauses are not included in a PUT request 420 used to send an efficacy update and DELETE requests. 422 3.2.2. DOTS Signal Filtering Control Module 423 3.2.2.1. Tree Structure 425 This document augments the "ietf-dots-signal-channel" YANG module 426 defined in [RFC8782] for managing filtering rules. 428 This document defines the YANG module "ietf-dots-signal-control", 429 which has the following tree structure: 431 module: ietf-dots-signal-control 432 augment /ietf-signal:dots-signal/ietf-signal:message-type 433 /ietf-signal:mitigation-scope/ietf-signal:scope: 434 +--rw acl-list* [acl-name] {control-filtering}? 435 +--rw acl-name 436 | -> /ietf-data:dots-data/dots-client/acls/acl/name 437 +--rw activation-type? ietf-data:activation-type 439 3.2.2.2. YANG Module 441 This YANG module is not intended to be used via NETCONF/RESTCONF for 442 DOTS server management purposes; such module is out of the scope of 443 this document. It serves only to provide a data model and encoding, 444 but not a management data model. 446 This module uses types defined in [RFC8783]. 448 file "ietf-dots-signal-control@2019-05-13.yang" 450 module ietf-dots-signal-control { 451 yang-version 1.1; 452 namespace 453 "urn:ietf:params:xml:ns:yang:ietf-dots-signal-control"; 454 prefix dots-control; 456 import ietf-dots-signal-channel { 457 prefix ietf-signal; 458 reference 459 "RFC 8782: Distributed Denial-of-Service Open Threat 460 Signaling (DOTS) Signal Channel Specification"; 461 } 462 import ietf-dots-data-channel { 463 prefix ietf-data; 464 reference 465 "RFC 8783: Distributed Denial-of-Service Open Threat 466 Signaling (DOTS) Data Channel Specification"; 467 } 469 organization 470 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 471 contact 472 "WG Web: 473 WG List: 475 Author: Kaname Nishizuka 476 478 Author: Mohamed Boucadair 479 481 Author: Konda, Tirumaleswar Reddy 482 484 Author: Takahiko Nagata 485 "; 487 description 488 "This module contains YANG definition for the signaling 489 messages exchanged between a DOTS client and a DOTS server 490 to control, by means of the DOTS signal channel, filtering 491 rules configured using the DOTS data channel. 493 Copyright (c) 2020 IETF Trust and the persons identified as 494 authors of the code. All rights reserved. 496 Redistribution and use in source and binary forms, with or 497 without modification, is permitted pursuant to, and subject 498 to the license terms contained in, the Simplified BSD License 499 set forth in Section 4.c of the IETF Trust's Legal Provisions 500 Relating to IETF Documents 501 (http://trustee.ietf.org/license-info). 503 This version of this YANG module is part of RFC XXXX; see 504 the RFC itself for full legal notices."; 506 revision 2019-05-13 { 507 description 508 "Initial revision."; 509 reference 510 "RFC XXXX: Controlling Filtering Rules Using Distributed 511 Denial-of-Service Open Threat Signaling (DOTS) 512 Signal Channel"; 513 } 515 feature control-filtering { 516 description 517 "This feature means that the DOTS signal channel is able 518 to manage the filtering rules created by the same DOTS 519 client using the DOTS data channel."; 520 } 522 augment "/ietf-signal:dots-signal/ietf-signal:message-type" 523 + "/ietf-signal:mitigation-scope/ietf-signal:scope" { 524 if-feature control-filtering; 526 description "ACL name and activation type."; 528 list acl-list { 529 key "acl-name"; 530 description 531 "List of ACLs as defined using the DOTS data 532 channel. ACLs bound to a DOTS client are uniquely 533 identified by a name."; 534 leaf acl-name { 535 type leafref { 536 path "/ietf-data:dots-data/ietf-data:dots-client" 537 + "/ietf-data:acls/ietf-data:acl/ietf-data:name"; 538 } 539 description 540 "Reference to the ACL name bound to a DOTS client."; 541 } 542 leaf activation-type { 543 type ietf-data:activation-type; 544 default "activate-when-mitigating"; 545 description 546 "Sets the activation type of an ACL."; 547 } 548 } 549 } 550 } 551 553 4. Some Examples 555 This section provides some examples to illustrate the behavior 556 specified in Section 3.2.1. These examples are provided for 557 illustration purposes; they should not be considered as deployment 558 recommendations. 560 4.1. Conflict Handling 562 Let's consider a DOTS client which contacts its DOTS server during 563 'idle' time to install an accept-list allowing for UDP traffic issued 564 from 2001:db8:1234::/48 with a destination port number 443 to be 565 forwarded to 2001:db8:6401::2/127. It does so by sending, for 566 example, a PUT request shown in Figure 2. 568 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 569 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 570 /acl=an-accept-list HTTP/1.1 571 Host: example.com 572 Content-Type: application/yang-data+json 574 { 575 "ietf-dots-data-channel:acls": { 576 "acl": [ 577 { 578 "name": "an-accept-list", 579 "type": "ipv6-acl-type", 580 "activation-type": "activate-when-mitigating", 581 "aces": { 582 "ace": [ 583 { 584 "name": "test-ace-ipv6-udp", 585 "matches": { 586 "ipv6": { 587 "destination-ipv6-network": "2001:db8:6401::2/127", 588 "source-ipv6-network": "2001:db8:1234::/48" 589 }, 590 "udp": { 591 "destination-port-range-or-operator": { 592 "operator": "eq", 593 "port": 443 594 } 595 } 596 }, 597 "actions": { 598 "forwarding": "accept" 599 } 600 } 601 ] 602 } 603 } 604 ] 605 } 606 } 608 Figure 2: DOTS Data Channel Request to Create a Filter 610 Sometime later, consider that a DDoS attack is detected by the DOTS 611 client on 2001:db8:6401::2/127. Consequently, the DOTS client sends 612 a mitigation request to its DOTS server as shown in Figure 3. 614 Header: PUT (Code=0.03) 615 Uri-Path: ".well-known" 616 Uri-Path: "dots" 617 Uri-Path: "mitigate" 618 Uri-Path: "cuid=paL8p4Zqo4SLv64TLPXrxA" 619 Uri-Path: "mid=123" 620 Content-Format: "application/dots+cbor" 622 { 623 "ietf-dots-signal-channel:mitigation-scope": { 624 "scope": [ 625 { 626 "target-prefix": [ 627 "2001:db8:6401::2/127" 628 ], 629 "target-protocol": [ 630 17 631 ], 632 "lifetime": 3600 633 } 634 ] 635 } 636 } 638 Figure 3: DOTS Signal Channel Mitigation Request 640 The DOTS server accepts immediately the request by replying with 2.01 641 (Created) (Figure 4 depicts the message body of the response). 643 { 644 "ietf-dots-signal-channel:mitigation-scope": { 645 "scope": [ 646 { 647 "mid": 123, 648 "lifetime": 3600 649 } 650 ] 651 } 652 } 654 Figure 4: Status Response (Message Body) 656 Assuming the DOTS client subscribed to asynchronous notifications, 657 when the DOTS server concludes that some of the attack sources belong 658 to 2001:db8:1234::/48, it sends a notification message with 'status' 659 code set to '1 (Attack mitigation is in progress)' and 'conflict- 660 cause' set to '2' (conflict-with-acceptlist) to the DOTS client to 661 indicate that this mitigation request is in progress, but a conflict 662 is detected. 664 Upon receipt of the notification message from the DOTS server, the 665 DOTS client sends a PUT request to deactivate the "an-accept-list" 666 ACL as shown in Figure 5. 668 The DOTS client can also decide to send a PUT request to deactivate 669 the "an-accept-list" ACL, if suspect traffic is received from an 670 accept-listed source (2001:db8:1234::/48). The structure of that PUT 671 is the same as the one shown in Figure 5. 673 Header: PUT (Code=0.03) 674 Uri-Path: ".well-known" 675 Uri-Path: "dots" 676 Uri-Path: "mitigate" 677 Uri-Path: "cuid=paL8p4Zqo4SLv64TLPXrxA" 678 Uri-Path: "mid=124" 679 Content-Format: "application/dots+cbor" 681 { 682 "ietf-dots-signal-channel:mitigation-scope": { 683 "scope": [ 684 { 685 "target-prefix": [ 686 "2001:db8:6401::2/127" 687 ], 688 "target-protocol": [ 689 17 690 ], 691 "ietf-dots-signal-control:acl-list": [ 692 { 693 "acl-name": "an-accept-list", 694 "activation-type": "deactivate" 695 } 696 ], 697 "lifetime": 3600 698 } 699 ] 700 } 701 } 703 Figure 5: PUT for Deactivating a Conflicting Filter 705 Then, the DOTS server deactivates "an-accept-list" ACL and replies 706 with 2.04 (Changed) response to the DOTS client to confirm the 707 successful operation. The message body is similar to the one 708 depicted in Figure 4. 710 Once the attack is mitigated, the DOTS client may use the data 711 channel to retrieve its ACLs maintained by the DOTS server. As shown 712 in Figure 6, the activation type is set to 'deactivate' as set by the 713 DOTS signal channel (Figure 5) instead of the type initially set 714 using the DOTS data channel (Figure 2). 716 { 717 "ietf-dots-data-channel:acls": { 718 "acl": [ 719 { 720 "name": "an-accept-list", 721 "type": "ipv6-acl-type", 722 "activation-type": "deactivate", 723 "pending-lifetime": 10021, 724 "aces": { 725 "ace": [ 726 { 727 "name": "test-ace-ipv6-udp", 728 "matches": { 729 "ipv6": { 730 "destination-ipv6-network": "2001:db8:6401::2/127", 731 "source-ipv6-network": "2001:db8:1234::/48" 732 }, 733 "udp": { 734 "destination-port-range-or-operator": { 735 "operator": "eq", 736 "port": 443 737 } 738 } 739 }, 740 "actions": { 741 "forwarding": "accept" 742 } 743 } 744 ] 745 } 746 } 747 ] 748 } 749 } 751 Figure 6: DOTS Data Channel GET Response after Mitigation (Message 752 Body) 754 4.2. On-Demand Activation of an Accept-List Filter 756 Let's consider a DOTS client which contacts its DOTS server during 757 'idle' time to install an accept-list allowing for UDP traffic issued 758 from 2001:db8:1234::/48 to be forwarded to 2001:db8:6401::2/127. It 759 does so by sending, for example, a PUT request shown in Figure 7. 760 The DOTS server installs this filter with a "deactivated" state. 762 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 763 /dots-client=ioiuLoZqo4SLv64TLPXrxA/acls\ 764 /acl=my-accept-list HTTP/1.1 765 Host: example.com 766 Content-Type: application/yang-data+json 768 { 769 "ietf-dots-data-channel:acls": { 770 "acl": [ 771 { 772 "name": "my-accept-list", 773 "type": "ipv6-acl-type", 774 "activation-type": "deactivate", 775 "aces": { 776 "ace": [ 777 { 778 "name": "an-ace", 779 "matches": { 780 "ipv6": { 781 "destination-ipv6-network": "2001:db8:6401::2/127", 782 "source-ipv6-network": "2001:db8:1234::/48", 783 "protocol": 17 784 } 785 }, 786 "actions": { 787 "forwarding": "accept" 788 } 789 } 790 ] 791 } 792 } 793 ] 794 } 795 } 797 Figure 7: DOTS Data Channel Request to Create an Accept-List Filter 799 Sometime later, consider that a UDP DDoS attack is detected by the 800 DOTS client on 2001:db8:6401::2/127 but the DOTS client wants to let 801 the traffic from 2001:db8:1234::/48 to be accept-listed to the DOTS 802 client domain. Consequently, the DOTS client sends a mitigation 803 request to its DOTS server as shown in Figure 8. 805 Header: PUT (Code=0.03) 806 Uri-Path: ".well-known" 807 Uri-Path: "dots" 808 Uri-Path: "mitigate" 809 Uri-Path: "cuid=ioiuLoZqo4SLv64TLPXrxA" 810 Uri-Path: "mid=4879" 811 Content-Format: "application/dots+cbor" 813 { 814 "ietf-dots-signal-channel:mitigation-scope": { 815 "scope": [ 816 { 817 "target-prefix": [ 818 "2001:db8:6401::2/127" 819 ], 820 "target-protocol": [ 821 17 822 ], 823 "ietf-dots-signal-control:acl-list": [ 824 { 825 "acl-name": "my-accept-list", 826 "activation-type": "immediate" 827 } 828 ], 829 "lifetime": 3600 830 } 831 ] 832 } 833 } 835 Figure 8: DOTS Signal Channel Mitigation Request with a Filter 836 Control 838 The DOTS server activates "my-accept-list" ACL and replies with 2.01 839 (Created) response to the DOTS client to confirm the successful 840 operation. 842 4.3. DOTS Servers/Mitigators Lacking Capacity 844 This section describes a scenario in which a DOTS client activates a 845 drop-list or a rate-limit filter during an attack. 847 Consider a DOTS client that contacts its DOTS server during 'idle' 848 time to install an accept-list that rate-limits all (or a part 849 thereof) traffic to be forwarded to 2001:db8:123::/48 as a last 850 resort countermeasure whenever required. Installing the accept-list 851 can be done by sending, for example, the PUT request shown in 852 Figure 9. The DOTS server installs this filter with a "deactivated" 853 state. 855 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 856 /dots-client=OopPisZqo4SLv64TLPXrxA/acls\ 857 /acl=my-ratelimit-list HTTP/1.1 858 Host: example.com 859 Content-Type: application/yang-data+json 861 { 862 "ietf-dots-data-channel:acls": { 863 "acl": [ 864 { 865 "name": "my-ratelimit-list", 866 "type": "ipv6-acl-type", 867 "activation-type": "deactivate", 868 "aces": { 869 "ace": [ 870 { 871 "name": "my-ace", 872 "matches": { 873 "ipv6": { 874 "destination-ipv6-network": "2001:db8:123::/48" 875 } 876 }, 877 "actions": { 878 "forwarding": "accept", 879 "rate-limit": "20000.00" 880 } 881 } 882 ] 883 } 884 } 885 ] 886 } 887 } 889 Figure 9: DOTS Data Channel Request to Create a Rate-Limit Filter 891 Consider now that a DDoS attack is detected by the DOTS client on 892 2001:db8:123::/48. Consequently, the DOTS client sends a mitigation 893 request to its DOTS server (Figure 10). 895 Header: PUT (Code=0.03) 896 Uri-Path: ".well-known" 897 Uri-Path: "dots" 898 Uri-Path: "mitigate" 899 Uri-Path: "cuid=OopPisZqo4SLv64TLPXrxA" 900 Uri-Path: "mid=85" 901 Content-Format: "application/dots+cbor" 903 { 904 "ietf-dots-signal-channel:mitigation-scope": { 905 "scope": [ 906 { 907 "target-prefix": [ 908 "2001:db8:123::/48" 909 ], 910 "lifetime": 3600 911 } 912 ] 913 } 914 } 916 Figure 10: DOTS Signal Channel Mitigation Request 918 For some reason (e.g., the DOTS server, or the mitigator, is lacking 919 a capability or capacity), the DOTS client is still receiving attack 920 traffic which saturates available links. To soften the problem, the 921 DOTS client decides to activate the filter that rate-limits the 922 traffic destined to the DOTS client domain. To that aim, the DOTS 923 client sends the mitigation request to its DOTS server shown in 924 Figure 11. 926 Header: PUT (Code=0.03) 927 Uri-Path: ".well-known" 928 Uri-Path: "dots" 929 Uri-Path: "mitigate" 930 Uri-Path: "cuid=OopPisZqo4SLv64TLPXrxA" 931 Uri-Path: "mid=86" 932 Content-Format: "application/dots+cbor" 934 { 935 "ietf-dots-signal-channel:mitigation-scope": { 936 "scope": [ 937 { 938 "target-prefix": [ 939 "2001:db8:123::/48" 940 ], 941 "ietf-dots-signal-control:acl-list": [ 942 { 943 "acl-name": "my-ratelimit-list", 944 "activation-type": "immediate" 945 } 946 ], 947 "lifetime": 3600 948 } 949 ] 950 } 951 } 953 Figure 11: DOTS Signal Channel Mitigation Request to Activate a Rate- 954 Limit Filter 956 Then, the DOTS server activates "my-ratelimit-list" ACL and replies 957 with 2.04 (Changed) response to the DOTS client to confirm the 958 successful operation. 960 As the attack mitigation evolves, the DOTS client may decide to 961 deactivate the rate-limit policy (e.g., upon receipt of notification 962 status change from 'attack-exceeded-capability' to 'attack- 963 mitigation-in-progress'). Based on the mitigation status conveyed by 964 the DOTS server, the DOTS client can de-activate the rate-limit 965 action. It does so by sending the request shown in Figure 12. 967 Header: PUT (Code=0.03) 968 Uri-Path: ".well-known" 969 Uri-Path: "dots" 970 Uri-Path: "mitigate" 971 Uri-Path: "cuid=OopPisZqo4SLv64TLPXrxA" 972 Uri-Path: "mid=87" 973 Content-Format: "application/dots+cbor" 975 { 976 "ietf-dots-signal-channel:mitigation-scope": { 977 "scope": [ 978 { 979 "target-prefix": [ 980 "2001:db8:123::/48" 981 ], 982 "ietf-dots-signal-control:acl-list": [ 983 { 984 "acl-name": "my-ratelimit-list", 985 "activation-type": "deactivate" 986 } 987 ], 988 "lifetime": 3600 989 } 990 ] 991 } 992 } 994 Figure 12: DOTS Signal Channel Mitigation Request to Deactivate a 995 Rate-Limit Filter 997 5. IANA Considerations 999 5.1. DOTS Signal Channel CBOR Mappings Registry 1001 This specification registers the following parameters in the IANA 1002 "DOTS Signal Channel CBOR Key Values" registry [Key-Map]. 1004 o Note to the RFC Editor: Please delete (TBA1-TBA2) once the CBOR 1005 keys are assigned from the 1-16383 range. Please update Table 1 1006 accordingly. 1008 +--------------------+--------+-------+------------+---------------+ 1009 | Parameter Name | CBOR | CBOR | Change | Specification | 1010 | | Key | Major | Controller | Document(s) | 1011 | | Value | Type | | | 1012 +====================+========+=======+============+===============+ 1013 | activation-type | 52 | | | | 1014 | | (TBA1) | 0 | IESG | [RFCXXXX] | 1015 +--------------------+--------+-------+------------+---------------+ 1016 | ietf-dots-signal- | 53 | | | | 1017 | control:acl-list | (TBA2) | 4 | IESG | [RFCXXXX] | 1018 +--------------------+--------+-------+------------+---------------+ 1020 5.2. DOTS Signal Filtering Control YANG Module 1022 This document requests IANA to register the following URI in the "ns" 1023 subregistry within the "IETF XML Registry" [RFC3688]: 1025 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-control 1026 Registrant Contact: The IESG. 1027 XML: N/A; the requested URI is an XML namespace. 1029 This document requests IANA to register the following YANG module in 1030 the "YANG Module Names" subregistry [RFC7950] within the "YANG 1031 Parameters" registry. 1033 Name: ietf-dots-signal-control 1034 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-control 1035 Maintained by IANA: N 1036 Prefix: dots-control 1037 Reference: RFC XXXX 1039 6. Security Considerations 1041 The security considerations for the DOTS signal channel protocol are 1042 discussed in Section 10 of [RFC8782], while those for the DOTS data 1043 channel protocol are discussed in Section 10 of [RFC8783]. The 1044 following discusses the security considerations that are specific to 1045 the DOTS signal channel extension defined in this document. 1047 This specification does not allow to create new filtering rules, 1048 which is the responsibility of the DOTS data channel. DOTS client 1049 domains should be adequately prepared prior to an attack, e.g., by 1050 creating filters that will be activated on demand when an attack is 1051 detected. 1053 A DOTS client is entitled to access only the resources it creates. 1054 In particular, a DOTS client can not tweak filtering rules created by 1055 other DOTS clients of the same DOTS client domain. As a reminder, 1056 DOTS servers must associate filtering rules with the DOTS client that 1057 created these resources. Failure to ensure such association by a 1058 DOTS server will have severe impact on DOTS client domains. 1060 A compromised DOTS client can use the filtering control capability to 1061 exacerbate an ongoing attack. Likewise, such a compromised DOTS 1062 client may abstain from reacting to an ACL conflict notification 1063 received from the DOTS server during attacks. These are not new 1064 attack vectors, but variations of threats discussed in [RFC8782] and 1065 [RFC8783]. DOTS operators should carefully monitor and audit DOTS 1066 agents to detect misbehaviors and to deter misuses. 1068 7. Acknowledgements 1070 Many thanks to Wei Pan, Xia Liang, Jon Shallow, Dan Wing, Christer 1071 Holmberg, Shawn Emery, Tim Chown, Murray Kucherawy, Roman Danyliw, 1072 Erik Kline, and Eric Vyncke for the comments. 1074 Thanks to Benjamin Kaduk for the AD review. 1076 8. References 1078 8.1. Normative References 1080 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1081 Requirement Levels", BCP 14, RFC 2119, 1082 DOI 10.17487/RFC2119, March 1997, 1083 . 1085 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1086 DOI 10.17487/RFC3688, January 2004, 1087 . 1089 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1090 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1091 . 1093 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1094 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1095 May 2017, . 1097 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 1098 Mortensen, A., and N. Teague, "Distributed Denial-of- 1099 Service Open Threat Signaling (DOTS) Signal Channel 1100 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 1101 . 1103 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 1104 Denial-of-Service Open Threat Signaling (DOTS) Data 1105 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 1106 May 2020, . 1108 8.2. Informative References 1110 [I-D.ietf-dots-architecture] 1111 Mortensen, A., Reddy.K, T., Andreasen, F., Teague, N., and 1112 R. Compton, "Distributed-Denial-of-Service Open Threat 1113 Signaling (DOTS) Architecture", draft-ietf-dots- 1114 architecture-18 (work in progress), March 2020. 1116 [Interop] Nishizuka, K., Shallow, J., and L. Xia , "DOTS Interop 1117 test report, IETF 103 Hackathon", November 2018, 1118 . 1122 [Key-Map] IANA, "DOTS Signal Channel CBOR Key Values", 1123 . 1126 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1127 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1128 . 1130 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1131 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1132 . 1134 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 1135 Threat Signaling (DOTS) Requirements", RFC 8612, 1136 DOI 10.17487/RFC8612, May 2019, 1137 . 1139 Authors' Addresses 1140 Kaname Nishizuka 1141 NTT Communications 1142 GranPark 16F 3-4-1 Shibaura, Minato-ku 1143 Tokyo 108-8118 1144 Japan 1146 Email: kaname@nttv6.jp 1148 Mohamed Boucadair 1149 Orange 1150 Rennes 35000 1151 France 1153 Email: mohamed.boucadair@orange.com 1155 Tirumaleswar Reddy 1156 McAfee, Inc. 1157 Embassy Golf Link Business Park 1158 Bangalore, Karnataka 560071 1159 India 1161 Email: kondtir@gmail.com 1163 Takahiko Nagata 1164 Lepidum 1165 Japan 1167 Email: nagata@lepidum.co.jp