idnits 2.17.1 draft-ietf-dots-data-channel-29.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 448 has weird spacing: '...er-port ine...' == Line 533 has weird spacing: '...warding ide...' == Line 830 has weird spacing: '... icmp typ...' -- The document date (May 09, 2019) is 1785 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 2198 -- Looks like a reference, but probably isn't: '6' on line 2198 -- Looks like a reference, but probably isn't: '17' on line 2198 -- Looks like a reference, but probably isn't: '58' on line 2198 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-31 ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-13 == Outdated reference: A later version (-15) exists of draft-ietf-dots-server-discovery-02 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5575 (Obsoleted by RFC 8955) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 8 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: November 10, 2019 McAfee 6 May 09, 2019 8 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 9 Specification 10 draft-ietf-dots-data-channel-29 12 Abstract 14 The document specifies a Distributed Denial-of-Service Open Threat 15 Signaling (DOTS) data channel used for bulk exchange of data that 16 cannot easily or appropriately communicated through the DOTS signal 17 channel under attack conditions. 19 This is a companion document to the DOTS signal channel 20 specification. 22 Editorial Note (To be removed by RFC Editor) 24 Please update these statements within the document with the RFC 25 number to be assigned to this document: 27 o "This version of this YANG module is part of RFC XXXX;" 29 o "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 30 (DOTS) Data Channel Specification"; 32 o reference: RFC XXXX 34 Please update the "revision" date of the YANG module. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on November 10, 2019. 53 Copyright Notice 55 Copyright (c) 2019 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3. DOTS Data Channel . . . . . . . . . . . . . . . . . . . . . . 5 73 3.1. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 74 3.2. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 75 3.3. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 8 76 3.4. Detect and Prevent Infinite Loops . . . . . . . . . . . . 9 77 3.5. Stale Entries . . . . . . . . . . . . . . . . . . . . . . 9 78 4. DOTS Data Channel YANG Module . . . . . . . . . . . . . . . . 10 79 4.1. Generic Tree Structure . . . . . . . . . . . . . . . . . 10 80 4.2. Filtering Fields . . . . . . . . . . . . . . . . . . . . 13 81 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 20 82 5. Managing DOTS Clients . . . . . . . . . . . . . . . . . . . . 37 83 5.1. Registering DOTS Clients . . . . . . . . . . . . . . . . 37 84 5.2. Unregistering DOTS Clients . . . . . . . . . . . . . . . 40 85 6. Managing DOTS Aliases . . . . . . . . . . . . . . . . . . . . 40 86 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 41 87 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 45 88 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 47 89 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 47 90 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 47 91 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 49 92 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 52 93 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 59 94 8. Operational Considerations . . . . . . . . . . . . . . . . . 60 95 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 61 97 11. Contributing Authors . . . . . . . . . . . . . . . . . . . . 63 98 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 64 99 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 65 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 65 101 14.1. Normative References . . . . . . . . . . . . . . . . . . 65 102 14.2. Informative References . . . . . . . . . . . . . . . . . 67 103 Appendix A. Sample Examples: Filtering Fragments . . . . . . . . 68 104 Appendix B. Sample Examples: Filtering TCP Messages . . . . . . 71 105 B.1. Discard TCP Null Attack . . . . . . . . . . . . . . . . . 71 106 B.2. Rate-Limit SYN Flooding . . . . . . . . . . . . . . . . . 72 107 B.3. Rate-Limit ACK Flooding . . . . . . . . . . . . . . . . . 73 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 74 110 1. Introduction 112 A distributed denial-of-service (DDoS) attack is an attempt to make 113 machines or network resources unavailable to their intended users. 114 In most cases, sufficient scale can be achieved by compromising 115 enough end-hosts and using those infected hosts to perpetrate and 116 amplify the attack. The victim of such attack can be an application 117 server, a router, a firewall, an entire network, etc. 119 As discussed in [I-D.ietf-dots-requirements], the lack of a common 120 method to coordinate a real-time response among involved actors and 121 network domains inhibits the speed and effectiveness of DDoS attack 122 mitigation. From that standpoint, DDoS Open Threat Signaling (DOTS) 123 defines an architecture that allows a DOTS client to send requests to 124 a DOTS server for DDoS attack mitigation 125 [I-D.ietf-dots-architecture]. The DOTS approach is thus meant to 126 minimize the impact of DDoS attacks, thereby contributing to the 127 enforcement of more efficient defensive if not proactive security 128 strategies. To that aim, DOTS defines two channels: the signal and 129 the data channels (Figure 1). 131 +---------------+ +---------------+ 132 | | <------- Signal Channel ------> | | 133 | DOTS Client | | DOTS Server | 134 | | <======= Data Channel ======> | | 135 +---------------+ +---------------+ 137 Figure 1: DOTS Channels 139 The DOTS signal channel is used to carry information about a device 140 or a network (or a part thereof) that is under a DDoS attack. Such 141 information is sent by a DOTS client to an upstream DOTS server so 142 that appropriate mitigation actions are undertaken on traffic deemed 143 suspicious. The DOTS signal channel is further elaborated in 144 [I-D.ietf-dots-signal-channel]. 146 As for the DOTS data channel, it is used for infrequent bulk data 147 exchange between DOTS agents to significantly improve the 148 coordination of all the parties involved in the response to the 149 attack. Section 2 of [I-D.ietf-dots-architecture] mentions that the 150 DOTS data channel is used to perform the following tasks: 152 o Creating aliases for resources for which mitigation may be 153 requested. 155 A DOTS client may submit to its DOTS server a collection of 156 prefixes which it would like to refer to by an alias when 157 requesting mitigation. The DOTS server can respond to this 158 request with either a success or failure response (see Section 2 159 in [I-D.ietf-dots-architecture]). 161 Refer to Section 6 for more details. 163 o Policy management, which enables a DOTS client to request the 164 installation or withdrawal of traffic filters, dropping or rate- 165 limiting unwanted traffic, and permitting accept-listed traffic. 166 A DOTS client is entitled to instruct filtering rules only on IP 167 resources that belong to its domain. 169 Sample use cases for populating drop- or accept-list filtering 170 rules are detailed hereafter: 172 * If a network resource (DOTS client) is informed about a 173 potential DDoS attack from a set of IP addresses, the DOTS 174 client informs its servicing DOTS gateway of all suspect IP 175 addresses that need to be drop-listed for further 176 investigation. The DOTS client could also specify a list of 177 protocols and port numbers in the drop-list rule. 179 The DOTS gateway then propagates the drop-listed IP addresses 180 to a DOTS server which will undertake appropriate actions so 181 that traffic originated by these IP addresses to the target 182 network (specified by the DOTS client) is blocked. 184 * A network, that has partner sites from which only legitimate 185 traffic arrives, may want to ensure that the traffic from these 186 sites is not subjected to DDoS attack mitigation. The DOTS 187 client uses the DOTS data channel to convey the accept-listed 188 IP prefixes of the partner sites to its DOTS server. 190 The DOTS server uses this information to accept-list flows 191 originated by such IP prefixes and which reach the network. 193 Refer to Section 7 for more details. 195 2. Terminology 197 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 198 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 199 "OPTIONAL" in this document are to be interpreted as described in 200 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 201 as shown here. 203 The reader should be familiar with the terms defined in 204 [I-D.ietf-dots-requirements]. 206 The terminology for describing YANG modules is defined in [RFC7950]. 207 The meaning of the symbols in the tree diagrams is defined in 208 [RFC8340]. 210 This document generalizes the notion of Access Control List (ACL) so 211 that it is not device-specific [RFC8519]. As such, this document 212 defines an ACL as an ordered set of rules that is used to filter 213 traffic. Each rule is represented by an Access Control Entry (ACE). 214 ACLs communicated via the DOTS data channel are not bound to a device 215 interface. 217 For the sake of simplicity, all of the examples in this document use 218 "/restconf" as the discovered RESTCONF API root path. Many protocol 219 header lines and message-body text within examples throughout the 220 document are split into multiple lines for display purposes only. 221 When a line ends with backslash ('\') as the last character, the line 222 is wrapped for display purposes. It is to be considered to be joined 223 to the next line by deleting the backslash, the following line break, 224 and the leading whitespace of the next line. 226 3. DOTS Data Channel 228 3.1. Design Overview 230 Unlike the DOTS signal channel, which must remain operational even 231 when confronted with signal degradation due to packets loss, the DOTS 232 data channel is not expected to be fully operational at all times, 233 especially when a DDoS attack is underway. The requirements for a 234 DOTS data channel protocol are documented in 235 [I-D.ietf-dots-requirements]. 237 This specification does not require an order of DOTS signal and data 238 channel creations nor mandates a time interval between them. These 239 considerations are implementation- and deployment-specific. 241 As the primary function of the data channel is data exchange, a 242 reliable transport mode is required in order for DOTS agents to 243 detect data delivery success or failure. This document uses RESTCONF 244 [RFC8040] over TLS over TCP as the DOTS data channel protocol. The 245 abstract layering of DOTS data channel is shown in Figure 2. 247 +-------------------+ 248 | DOTS Data Channel | 249 +-------------------+ 250 | RESTCONF | 251 +-------------------+ 252 | TLS | 253 +-------------------+ 254 | TCP | 255 +-------------------+ 256 | IP | 257 +-------------------+ 259 Figure 2: Abstract Layering of DOTS Data Channel 261 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 262 resources represented by DOTS data channel YANG modules. These basic 263 edit operations allow the DOTS data channel running configuration to 264 be altered by a DOTS client. Rules for generating and processing 265 RESTCONF methods are defined in Section 4 of [RFC8040]. 267 DOTS data channel configuration information as well as state 268 information can be retrieved with the GET method. An HTTP status- 269 line is returned for each request to report success or failure for 270 RESTCONF operations (Section 5.4 of [RFC8040]). The "error-tag" 271 provides more information about encountered errors (Section 7 of 272 [RFC8040]). 274 DOTS clients perform the root resource discovery procedure discussed 275 in Section 3.1 of [RFC8040] to determine the root of the RESTCONF 276 API. After discovering the RESTCONF API root, a DOTS client uses 277 this value as the initial part of the path in the request URI in any 278 subsequent request to the DOTS server. The DOTS server may support 279 the retrieval of the YANG modules it supports (Section 3.7 in 280 [RFC8040]). For example, a DOTS client may use RESTCONF to retrieve 281 the vendor-specific YANG modules supported by its DOTS server. 283 JavaScript Object Notation (JSON) [RFC8259] payloads are used to 284 propagate the DOTS data-channel-specific payload messages that carry 285 request parameters and response information, such as errors. This 286 specification uses the encoding rules defined in [RFC7951] for 287 representing DOTS data channel configuration data using YANG 288 (Section 4) as JSON text. 290 A DOTS client registers itself to its DOTS server(s) in order to set 291 up DOTS data channel-related configuration data and receive state 292 data (i.e., non-configuration data) from the DOTS server(s) 293 (Section 5). Mutual authentication considerations are specified in 294 Section 8 of [I-D.ietf-dots-signal-channel]. The coupling of signal 295 and data channels is discussed in Section 4.4.1 of 296 [I-D.ietf-dots-signal-channel]. 298 A single DOTS data channel between DOTS agents can be used to 299 exchange multiple requests and multiple responses. To reduce DOTS 300 client and DOTS server workload, DOTS clients SHOULD re-use the same 301 TLS session. While the communication to the DOTS server is 302 quiescent, the DOTS client MAY probe the server to ensure it has 303 maintained cryptographic state. Such probes can also keep alive 304 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 305 that the DOTS server still has TLS state by returning a TLS message. 307 A DOTS server may detect conflicting filtering requests from distinct 308 DOTS clients which belong to the same domain. For example, a DOTS 309 client could request to drop-list a prefix by specifying the source 310 prefix, while another DOTS client could request to accept-list that 311 same source prefix, but both having the same destination prefix. 312 DOTS servers SHOULD support a configuration parameter to indicate the 313 behavior to follow when a conflict is detected (e.g., reject all, 314 reject the new request, notify an administrator for validation). 315 Section 7.2 specifies a default behavior when no instruction is 316 supplied to a DOTS server. 318 How a DOTS client synchronizes its configuration with the one 319 maintained by its DOTS server(s) is implementation-specific. For 320 example: 322 o a DOTS client can systematically send a GET message before and/or 323 after a configuration change request. 325 o a DOTS client can re-establish the disconnected DOTS session after 326 an attack is mitigated and sends a GET message before a 327 configuration change request. 329 NAT considerations for the DOTS data channel are similar to those 330 discussed in Section 3 of [I-D.ietf-dots-signal-channel]. 332 How filtering rules that are instantiated on a DOTS server are 333 translated into network configurations actions is out of scope of 334 this specification. 336 Some of the fields introduced in Section 4 are also discussed in 337 Sections 5, 6, and 7. These sections are authoritative for these 338 fields. 340 3.2. DOTS Server(s) Discovery 342 This document assumes that DOTS clients are provisioned with a way to 343 know how to reach their DOTS server(s), which could occur by a 344 variety of means (e.g., local configuration, or dynamic means such as 345 DHCP [I-D.ietf-dots-server-discovery]). The specification of such 346 means are out of scope of this document. 348 Likewise, it is out of scope of this document to specify the behavior 349 to be followed by a DOTS client to send DOTS requests when multiple 350 DOTS servers are provisioned (e.g., contact all DOTS servers, select 351 one DOTS server among the list). 353 3.3. DOTS Gateways 355 When a server-domain DOTS gateway is involved in DOTS data channel 356 exchanges, the same considerations for manipulating the 'cdid' 357 (client domain identifier) parameter specified in 358 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 359 reminder, 'cdid' is meant to assist the DOTS server to enforce some 360 policies (e.g., limit the number of filtering rules per DOTS client 361 or per DOTS client domain). A loop detect mechanism for DOTS 362 gateways is specified in Section 3.4. 364 If a DOTS gateway is involved, the DOTS gateway verifies that the 365 DOTS client is authorized to undertake a data channel action (e.g., 366 instantiate filtering rules). If the DOTS client is authorized, it 367 propagates the rules to the upstream DOTS server. Likewise, the DOTS 368 server verifies that the DOTS gateway is authorized to relay data 369 channel actions. For example, to create or purge filters, a DOTS 370 client sends its request to its DOTS gateway. The DOTS gateway 371 validates the rules in the request and proxies the requests 372 containing the filtering rules to its DOTS server. When the DOTS 373 gateway receives the associated response from the DOTS server, it 374 propagates the response back to the DOTS client. 376 3.4. Detect and Prevent Infinite Loops 378 In order to detect and prevent infinite loops, DOTS gateways MUST 379 support the procedure defined in Section 5.7.1 of [RFC7230]. In 380 particular, each intermediate DOTS gateway MUST check that none of 381 its own information (e.g., server names, literal IP addresses) is 382 present in the "Via" header field of a DOTS message it receives: 384 o If it detects that its own information is present in the "Via" 385 header field, the DOTS gateway MUST NOT forward the DOTS message. 386 Messages that cannot be forwarded because of a loop SHOULD be 387 logged with a "508 Loop Detected" status-line returned sent back 388 to the DOTS peer. The structure of the reported error is depicted 389 in Figure 3. 391 error-app-tag: loop-detected 392 error-tag: operation-failed 393 error-type: transport, application 394 error-info: : A copy of the Via header field when 395 the loop was detected. 396 Description: An infinite loop has been detected when forwarding 397 a requests via a proxy. 399 Figure 3: Loop Detected Error 401 It is RECOMMENDED that DOTS clients and gateways support methods 402 to alert administrators about loop errors so that appropriate 403 actions are undertaken. 405 o Otherwise, the DOTS agent MUST update or insert the "Via" header 406 by appending its own information. 408 Unless configured otherwise, DOTS gateways at the boundaries of a 409 DOTS client domain SHOULD remove the previous "Via" header field 410 information after checking for a loop before forwarding. This 411 behavior is required for topology hiding purposes but can also serve 412 to minimize potential conflicts that may arise if overlapping 413 information is used in distinct DOTS domains (e.g., private IPv4 414 addresses, non globally unique aliases). 416 3.5. Stale Entries 418 In order to avoid stale entries, a lifetime is associated with alias 419 and filtering entries created by DOTS clients. Also, DOTS servers 420 may track the inactivity timeout of DOTS clients to detect stale 421 entries. 423 4. DOTS Data Channel YANG Module 425 4.1. Generic Tree Structure 427 The DOTS data channel YANG module (ietf-dots-data-channel) provides a 428 method for DOTS clients to manage aliases for resources for which 429 mitigation may be requested. Such aliases may be used in subsequent 430 DOTS signal channel exchanges to refer more efficiently to the 431 resources under attack. 433 Note that the full module's tree has been split across several 434 figures to aid the exposition of the various sub-trees. 436 The tree structure for the DOTS alias is depicted in Figure 4. 438 module: ietf-dots-data-channel 439 +--rw dots-data 440 +--rw dots-client* [cuid] 441 | +--rw cuid string 442 | +--rw cdid? string 443 | +--rw aliases 444 | | +--rw alias* [name] 445 | | +--rw name string 446 | | +--rw target-prefix* inet:ip-prefix 447 | | +--rw target-port-range* [lower-port] 448 | | | +--rw lower-port inet:port-number 449 | | | +--rw upper-port? inet:port-number 450 | | +--rw target-protocol* uint8 451 | | +--rw target-fqdn* inet:domain-name 452 | | +--rw target-uri* inet:uri 453 | | +--ro pending-lifetime? int32 454 | +--rw acls 455 | ... 456 +--ro capabilities 457 ... 459 Figure 4: DOTS Alias Subtree 461 Also, the 'ietf-dots-data-channel' module provides a method for DOTS 462 clients to manage filtering rules. Examples of filtering management 463 in a DOTS context include, but not limited to: 465 o Drop-list management, which enables a DOTS client to inform a DOTS 466 server about sources from which traffic should be discarded. 468 o Accept-list management, which enables a DOTS client to inform a 469 DOTS server about sources from which traffic should always be 470 accepted. 472 o Policy management, which enables a DOTS client to request the 473 installation or withdrawal of traffic filters, dropping or rate- 474 limiting unwanted traffic and permitting accept-listed traffic. 476 The tree structure for the DOTS filtering entries is depicted in 477 Figure 5. 479 Investigations into the prospect of augmenting 'ietf-access-control- 480 list' to meet DOTS requirements concluded that such a design approach 481 did not support many of the DOTS requirements, e.g., 483 o Retrieve a filtering entry (or all entries) created by a DOTS 484 client. 486 o Delete a filtering entry that was instantiated by a DOTS client. 488 Accordingly, new DOTS filtering entries (i.e., Access Control List 489 (ACL)) are defined that mimic the structure specified in [RFC8519]. 490 Concretely, DOTS agents are assumed to manipulate an ordered list of 491 ACLs; each ACL contains a separately ordered list of Access Control 492 Entries (ACEs). Each ACE has a group of match and a group of action 493 criteria. 495 Once all the ACE entries have been iterated though with no match, 496 then all the following ACL's ACE entries are iterated through until 497 the first match at which point the specified action is applied. If 498 there is no match during 'idle' time (i.e., no mitigation is active), 499 then there is no further action to be taken against the packet. If 500 there is no match during active mitigation, then the packet will 501 still be scrubbed by the DDoS mitigator. 503 module: ietf-dots-data-channel 504 +--rw dots-data 505 +--rw dots-client* [cuid] 506 | +--rw cuid string 507 | +--rw cdid? string 508 | +--rw aliases 509 | | ... 510 | +--rw acls 511 | +--rw acl* [name] 512 | +--rw name string 513 | +--rw type? ietf-acl:acl-type 514 | +--rw activation-type? activation-type 515 | +--ro pending-lifetime? int32 516 | +--rw aces 517 | +--rw ace* [name] 518 | +--rw name string 519 | +--rw matches 520 | | +--rw (l3)? 521 | | | +--:(ipv4) 522 | | | | ... 523 | | | +--:(ipv6) 524 | | | ... 525 | | +--rw (l4)? 526 | | +--:(tcp) 527 | | | ... 528 | | +--:(udp) 529 | | | ... 530 | | +--:(icmp) 531 | | ... 532 | +--rw actions 533 | | +--rw forwarding identityref 534 | | +--rw rate-limit? decimal64 535 | +--ro statistics 536 | +--ro matched-packets? yang:counter64 537 | +--ro matched-octets? yang:counter64 538 +--ro capabilities 539 ... 541 Figure 5: DOTS ACLs Subtree 543 Filtering rules instructed by a DOTS client assumes a default 544 direction: the destination is the DOTS client domain. 546 DOTS forwarding actions can be 'accept' (i.e., accept matching 547 traffic) or 'drop' (i.e., drop matching traffic without sending any 548 ICMP error message). Accepted traffic can be subject to rate- 549 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 550 matching traffic and send an ICMP error message to the source) is not 551 supported in 'ietf-dots-data-channel' because it is not appropriate 552 in the context of DDoS mitigation. Generating ICMP messages to 553 notify drops when mitigating a DDoS attack will exacerbate the DDoS 554 attack. Furthermore, these ICMP messages will be used by an attacker 555 as an explicit signal that the traffic is being blocked. 557 4.2. Filtering Fields 559 The 'ietf-dots-data-channel' module reuses the packet fields module 560 'ietf-packet-fields' [RFC8519] which defines matching on fields in 561 the packet including IPv4, IPv6, and transport layer fields. The 562 'ietf-dots-data-channel' module can be augmented, for example, to 563 support additional protocol-specific matching fields. 565 This specification defines a new IPv4/IPv6 matching field called 566 'fragment' to efficiently handle fragment-related filtering rules. 567 Indeed, [RFC8519] does not support such capability for IPv6 but 568 offers a partial support for IPv4 by means of 'flags'. Nevertheless, 569 the use of 'flags' is problematic since it does not allow to define a 570 bitmask. For example, setting other bits not covered by the 'flags' 571 filtering clause in a packet will allow that packet to get through 572 (because it won't match the ACE). Sample examples to illustrate how 573 'fragment' can be used are provided in Appendix A. 575 Figure 6 shows the IPv4 match subtree. 577 module: ietf-dots-data-channel 578 +--rw dots-data 579 +--rw dots-client* [cuid] 580 | ... 581 | +--rw acls 582 | +--rw acl* [name] 583 | ... 584 | +--rw aces 585 | +--rw ace* [name] 586 | +--rw name string 587 | +--rw matches 588 | | +--rw (l3)? 589 | | | +--:(ipv4) 590 | | | | +--rw ipv4 591 | | | | +--rw dscp? inet:dscp 592 | | | | +--rw ecn? uint8 593 | | | | +--rw length? uint16 594 | | | | +--rw ttl? uint8 595 | | | | +--rw protocol? uint8 596 | | | | +--rw ihl? uint8 597 | | | | +--rw flags? bits 598 | | | | +--rw offset? uint16 599 | | | | +--rw identification? uint16 600 | | | | +--rw (destination-network)? 601 | | | | | +--:(destination-ipv4-network) 602 | | | | | +--rw destination-ipv4-network? 603 | | | | | inet:ipv4-prefix 604 | | | | +--rw (source-network)? 605 | | | | | +--:(source-ipv4-network) 606 | | | | | +--rw source-ipv4-network? 607 | | | | | inet:ipv4-prefix 608 | | | | +--rw fragment 609 | | | | +--rw operator? operator 610 | | | | +--rw type fragment-type 611 | | | +--:(ipv6) 612 | | | ... 613 | | +--rw (l4)? 614 | | ... 615 | +--rw actions 616 | | ... 617 | +--ro statistics 618 | ... 619 +--ro capabilities 620 ... 622 Figure 6: DOTS ACLs Subtree (IPv4 Match) 624 Figure 7 shows the IPv6 match subtree. 626 module: ietf-dots-data-channel 627 +--rw dots-data 628 +--rw dots-client* [cuid] 629 | ... 630 | +--rw acls 631 | +--rw acl* [name] 632 | ... 633 | +--rw aces 634 | +--rw ace* [name] 635 | +--rw name string 636 | +--rw matches 637 | | +--rw (l3)? 638 | | | +--:(ipv4) 639 | | | | ... 640 | | | +--:(ipv6) 641 | | | +--rw ipv6 642 | | | +--rw dscp? inet:dscp 643 | | | +--rw ecn? uint8 644 | | | +--rw length? uint16 645 | | | +--rw ttl? uint8 646 | | | +--rw protocol? uint8 647 | | | +--rw (destination-network)? 648 | | | | +--:(destination-ipv6-network) 649 | | | | +--rw destination-ipv6-network? 650 | | | | inet:ipv6-prefix 651 | | | +--rw (source-network)? 652 | | | | +--:(source-ipv6-network) 653 | | | | +--rw source-ipv6-network? 654 | | | | inet:ipv6-prefix 655 | | | +--rw flow-label? 656 | | | | inet:ipv6-flow-label 657 | | | +--rw fragment 658 | | | +--rw operator? operator 659 | | | +--rw type fragment-type 660 | | +--rw (l4)? 661 | | ... 662 | +--rw actions 663 | | ... 664 | +--ro statistics 665 | ... 666 +--ro capabilities 667 ... 669 Figure 7: DOTS ACLs Subtree (IPv6 Match) 671 Figure 8 shows the TCP match subtree. In addition to the fields 672 defined in [RFC8519], this specification defines a new TCP matching 673 field, called 'flags-bitmask', to efficiently handle TCP flags 674 filtering rules. Some examples are provided in Appendix B. 676 module: ietf-dots-data-channel 677 +--rw dots-data 678 +-rw dots-client* [cuid] 679 | ... 680 | +-rw acls 681 | +-rw acl* [name] 682 | ... 683 | +-rw aces 684 | +-rw ace* [name] 685 | +-rw name string 686 | +-rw matches 687 | | +-rw (l3)? 688 | | | ... 689 | | +-rw (l4)? 690 | | +-:(tcp) 691 | | | +-rw tcp 692 | | | +--rw sequence-number? uint32 693 | | | +--rw acknowledgement-number? uint32 694 | | | +--rw data-offset? uint8 695 | | | +--rw reserved? uint8 696 | | | +--rw flags? bits 697 | | | +--rw window-size? uint16 698 | | | +--rw urgent-pointer? uint16 699 | | | +--rw options? binary 700 | | | +--rw flags-bitmask 701 | | | | +--rw operator? operator 702 | | | | +--rw bitmask uint16 703 | | | +--rw (source-port)? 704 | | | | +--:(source-port-range-or-operator) 705 | | | | +--rw source-port-range-or-operator 706 | | | | +--rw (port-range-or-operator)? 707 | | | | +--:(range) 708 | | | | | +--rw lower-port 709 | | | | | | inet:port-number 710 | | | | | +--rw upper-port 711 | | | | | inet:port-number 712 | | | | +--:(operator) 713 | | | | +--rw operator? 714 | | | | | operator 715 | | | | +--rw port 716 | | | | inet:port-number 717 | | | +--rw (destination-port)? 718 | | | +--:(destination-port-range-or-operator) 719 | | | +--rw destination-port-range-or-operator 720 | | | +--rw (port-range-or-operator)? 721 | | | +--:(range) 722 | | | | +--rw lower-port 723 | | | | | inet:port-number 724 | | | | +--rw upper-port 725 | | | | inet:port-number 726 | | | +--:(operator) 727 | | | +--rw operator? 728 | | | | operator 729 | | | +--rw port 730 | | | inet:port-number 731 | | +-:(udp) 732 | | | ... 733 | | +-:(icmp) 734 | | ... 735 | +-rw actions 736 | | ... 737 | +-ro statistics 738 | ... 739 +-ro capabilities 740 ... 742 Figure 8: DOTS ACLs Subtree (TCP Match) 744 Figure 9 shows the UDP and ICMP match subtrees. The same structure 745 is used for both ICMP and ICMPv6. The indication whether an ACL is 746 about ICMP or ICMPv6 is governed by the 'l3' match or the ACL type. 748 module: ietf-dots-data-channel 749 +-rw dots-data 750 +-rw dots-client* [cuid] 751 | ... 752 | +-rw acls 753 | +-rw acl* [name] 754 | ... 755 | +-rw aces 756 | +-rw ace* [name] 757 | +--rw name string 758 | +--rw matches 759 | | +--rw (l3)? 760 | | | ... 761 | | +--rw (l4)? 762 | | +--:(tcp) 763 | | | ... 764 | | +--:(udp) 765 | | | +--rw udp 766 | | | +--rw length? uint16 767 | | | +--rw (source-port)? 768 | | | | +--:(source-port-range-or-operator) 769 | | | | +--rw source-port-range-or-operator 770 | | | | +--rw (port-range-or-operator)? 771 | | | | +--:(range) 772 | | | | | +--rw lower-port 773 | | | | | | inet:port-number 774 | | | | | +--rw upper-port 775 | | | | | inet:port-number 776 | | | | +--:(operator) 777 | | | | +--rw operator? 778 | | | | | operator 779 | | | | +--rw port 780 | | | | inet:port-number 781 | | | +--rw (destination-port)? 782 | | | +--:(destination-port-range-or-operator) 783 | | | +--rw destination-port-range-or-operator 784 | | | +--rw (port-range-or-operator)? 785 | | | +--:(range) 786 | | | | +--rw lower-port 787 | | | | | inet:port-number 788 | | | | +--rw upper-port 789 | | | | inet:port-number 790 | | | +--:(operator) 791 | | | +--rw operator? 792 | | | | operator 793 | | | +--rw port 794 | | | inet:port-number 795 | | +--:(icmp) 796 | | +--rw icmp 797 | | +--rw type? uint8 798 | | +--rw code? uint8 799 | | +--rw rest-of-header? binary 800 | +--rw actions 801 | | ... 802 | +--ro statistics 803 | ... 804 +-ro capabilities 805 ... 807 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 809 DOTS implementations MUST support the following matching criteria: 811 match based on the IP header (IPv4 and IPv6), match based on the 812 transport header (TCP, UDP, and ICMP), and any combination 813 thereof. The same matching fields are used for both ICMP and 814 ICMPv6. 816 The following match fields MUST be supported by DOTS implementations 817 (Table 1): 819 ACL Mandatory Fields 820 Match 821 ------- ------------------------------------------------------------- 822 ipv4 length, protocol, destination-ipv4-network, source- 823 ipv4-network, and fragment 824 ipv6 length, protocol, destination-ipv6-network, source- 825 ipv6-network, and fragment 826 tcp flags-bitmask, source-port-range-or-operator, and 827 destination-port-range-or-operator 828 udp length, source-port-range-or-operator, and destination-port- 829 range-or-operator 830 icmp type and code 832 Table 1: Mandatory DOTS Channel Match Fields 834 Implementations MAY support other filtering match fields and actions. 835 The 'ietf-dots-data-channel' provides a method for an implementation 836 to expose its filtering capabilities. The tree structure of the 837 'capabilities' is shown in Figure 10. DOTS clients that support both 838 'fragment' and 'flags' (or 'flags-bitmask' and 'flags') matching 839 fields MUST NOT set these fields in the same request. 841 module: ietf-dots-data-channel 842 +--rw dots-data 843 ... 844 +--ro capabilities 845 +--ro address-family* enumeration 846 +--ro forwarding-actions* identityref 847 +--ro rate-limit? boolean 848 +--ro transport-protocols* uint8 849 +--ro ipv4 850 | +--ro dscp? boolean 851 | +--ro ecn? boolean 852 | +--ro length? boolean 853 | +--ro ttl? boolean 854 | +--ro protocol? boolean 855 | +--ro ihl? boolean 856 | +--ro flags? boolean 857 | +--ro offset? boolean 858 | +--ro identification? boolean 859 | +--ro source-prefix? boolean 860 | +--ro destination-prefix? boolean 861 | +--ro fragment? boolean 862 +--ro ipv6 863 | +--ro dscp? boolean 864 | +--ro ecn? boolean 865 | +--ro length? boolean 866 | +--ro hoplimit? boolean 867 | +--ro protocol? boolean 868 | +--ro destination-prefix? boolean 869 | +--ro source-prefix? boolean 870 | +--ro flow-label? boolean 871 | +--ro fragment? boolean 872 +--ro tcp 873 | +--ro sequence-number? boolean 874 | +--ro acknowledgement-number? boolean 875 | +--ro data-offset? boolean 876 | +--ro reserved? boolean 877 | +--ro flags? boolean 878 | +--ro window-size? boolean 879 | +--ro urgent-pointer? boolean 880 | +--ro options? boolean 881 | +--ro flags-bitmask? boolean 882 | +--ro source-port? boolean 883 | +--ro destination-port? boolean 884 | +--ro port-range? boolean 885 +--ro udp 886 | +--ro length? boolean 887 | +--ro source-port? boolean 888 | +--ro destination-port? boolean 889 | +--ro port-range? boolean 890 +--ro icmp 891 +--ro type? boolean 892 +--ro code? boolean 893 +--ro rest-of-header? boolean 895 Figure 10: Filtering Capabilities Subtree 897 4.3. YANG Module 899 This module uses the common YANG types defined in [RFC6991] and types 900 defined in [RFC8519]. 902 file "ietf-dots-data-channel@2019-05-09.yang" 903 module ietf-dots-data-channel { 904 yang-version 1.1; 905 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 906 prefix data-channel; 908 import ietf-inet-types { 909 prefix inet; 910 reference "Section 4 of RFC 6991"; 911 } 912 import ietf-access-control-list { 913 prefix ietf-acl; 914 reference 915 "RFC 8519: YANG Data Model for Network Access 916 Control Lists (ACLs)"; 917 } 918 import ietf-packet-fields { 919 prefix packet-fields; 920 reference 921 "RFC 8519: YANG Data Model for Network Access 922 Control Lists (ACLs)"; 923 } 925 organization 926 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 927 contact 928 "WG Web: 929 WG List: 931 Editor: Mohamed Boucadair 932 934 Editor: Konda, Tirumaleswar Reddy 935 937 Author: Jon Shallow 938 940 Author: Kaname Nishizuka 941 943 Author: Liang Xia 944 946 Author: Prashanth Patil 947 949 Author: Andrew Mortensen 950 952 Author: Nik Teague 953 "; 954 description 955 "This module contains YANG definition for configuring 956 aliases for resources and filtering rules using DOTS 957 data channel. 959 Copyright (c) 2019 IETF Trust and the persons identified as 960 authors of the code. All rights reserved. 962 Redistribution and use in source and binary forms, with or 963 without modification, is permitted pursuant to, and subject 964 to the license terms contained in, the Simplified BSD License 965 set forth in Section 4.c of the IETF Trust's Legal Provisions 966 Relating to IETF Documents 967 (http://trustee.ietf.org/license-info). 969 This version of this YANG module is part of RFC XXXX; see 970 the RFC itself for full legal notices."; 972 revision 2019-05-09 { 973 description 974 "Initial revision."; 975 reference 976 "RFC XXXX: Distributed Denial-of-Service Open Threat 977 Signaling (DOTS) Data Channel Specification"; 978 } 980 typedef activation-type { 981 type enumeration { 982 enum "activate-when-mitigating" { 983 value 1; 984 description 985 "The Access Control List (ACL) is installed only when 986 a mitigation is active for the DOTS client."; 987 } 988 enum "immediate" { 989 value 2; 990 description 991 "The ACL is immediately activated."; 992 } 993 enum "deactivate" { 994 value 3; 995 description 996 "The ACL is maintained by the DOTS server, but it is 997 deactivated."; 998 } 999 } 1000 description 1001 "Indicates the activation type of an ACL."; 1002 } 1004 typedef operator { 1005 type bits { 1006 bit not { 1007 position 0; 1008 description 1009 "If set, logical negation of operation."; 1010 } 1011 bit match { 1012 position 1; 1013 description 1014 "Match bit. This is a bitwise match operation 1015 defined as '(data & value) == value'."; 1016 } 1017 bit any { 1018 position 3; 1019 description 1020 "Any bit. This is a match on any of the bits in 1021 bitmask. It evaluates to 'true' if any of the bits 1022 in the value mask are set in the data, 1023 i.e., '(data & value) != 0'."; 1024 } 1025 } 1026 description 1027 "Specifies how to apply the defined bitmask."; 1028 } 1030 grouping tcp-flags { 1031 leaf operator { 1032 type operator; 1033 default "match"; 1034 description 1035 "Specifies how to interpret the TCP flags."; 1036 } 1037 leaf bitmask { 1038 type uint16; 1039 mandatory true; 1040 description 1041 "The bitmask matches the last 4 bits of byte 12 1042 and byte 13 of the TCP header. For clarity, the 4 bits 1043 of byte 12 corresponding to the TCP data offset field 1044 are not included in any matching."; 1045 } 1046 description 1047 "Operations on TCP flags."; 1048 } 1050 typedef fragment-type { 1051 type bits { 1052 bit df { 1053 position 0; 1054 description 1055 "Don't fragment bit for IPv4. 1057 Must be set to 0 when it appears in an IPv6 filter."; 1058 } 1059 bit isf { 1060 position 1; 1061 description 1062 "Is a fragment."; 1063 } 1064 bit ff { 1065 position 2; 1066 description 1067 "First fragment."; 1068 } 1069 bit lf { 1070 position 3; 1071 description 1072 "Last fragment."; 1073 } 1074 } 1075 description 1076 "Different fragment types to match against."; 1077 } 1079 grouping target { 1080 description 1081 "Specifies the targets of the mitigation request."; 1082 leaf-list target-prefix { 1083 type inet:ip-prefix; 1084 description 1085 "IPv4 or IPv6 prefix identifying the target."; 1086 } 1087 list target-port-range { 1088 key "lower-port"; 1089 description 1090 "Port range. When only lower-port is 1091 present, it represents a single port number."; 1092 leaf lower-port { 1093 type inet:port-number; 1094 mandatory true; 1095 description 1096 "Lower port number of the port range."; 1097 } 1098 leaf upper-port { 1099 type inet:port-number; 1100 must '. >= ../lower-port' { 1101 error-message 1102 "The upper port number must be greater than 1103 or equal to the lower-port number."; 1104 } 1105 description 1106 "Upper port number of the port range."; 1107 } 1108 } 1109 leaf-list target-protocol { 1110 type uint8; 1111 description 1112 "Identifies the target protocol number. 1114 Values are taken from the IANA protocol registry: 1115 https://www.iana.org/assignments/protocol-numbers/ 1116 protocol-numbers.xhtml 1118 For example, 6 for TCP or 17 for UDP."; 1119 } 1120 leaf-list target-fqdn { 1121 type inet:domain-name; 1122 description 1123 "FQDN identifying the target."; 1124 } 1125 leaf-list target-uri { 1126 type inet:uri; 1127 description 1128 "URI identifying the target."; 1129 } 1130 } 1132 grouping fragment-fields { 1133 leaf operator { 1134 type operator; 1135 default "match"; 1136 description 1137 "Specifies how to interpret the fragment type."; 1138 } 1139 leaf type { 1140 type fragment-type; 1141 mandatory true; 1142 description 1143 "Indicates what fragment type to look for."; 1144 } 1145 description 1146 "Operations on fragment types."; 1147 } 1149 grouping aliases { 1150 description 1151 "Top level container for aliases."; 1152 list alias { 1153 key "name"; 1154 description 1155 "List of aliases."; 1156 leaf name { 1157 type string; 1158 description 1159 "The name of the alias."; 1160 } 1161 uses target; 1162 leaf pending-lifetime { 1163 type int32; 1164 units "minutes"; 1165 config false; 1166 description 1167 "Indicates the pending validity lifetime of the alias 1168 entry."; 1169 } 1170 } 1171 } 1173 grouping ports { 1174 choice source-port { 1175 container source-port-range-or-operator { 1176 uses packet-fields:port-range-or-operator; 1177 description 1178 "Source port definition."; 1179 } 1180 description 1181 "Choice of specifying the source port or referring to 1182 a group of source port numbers."; 1183 } 1184 choice destination-port { 1185 container destination-port-range-or-operator { 1186 uses packet-fields:port-range-or-operator; 1187 description 1188 "Destination port definition."; 1189 } 1190 description 1191 "Choice of specifying a destination port or referring 1192 to a group of destination port numbers."; 1193 } 1194 description 1195 "Choice of specifying a source or destination port numbers."; 1196 } 1198 grouping access-lists { 1199 description 1200 "Specifies the ordered set of Access Control Lists."; 1202 list acl { 1203 key "name"; 1204 ordered-by user; 1205 description 1206 "An ACL is an ordered list of Access Control Entries (ACE). 1207 Each ACE has a list of match criteria and a list of actions."; 1208 leaf name { 1209 type string { 1210 length "1..64"; 1211 } 1212 description 1213 "The name of the access list."; 1214 reference 1215 "RFC 8519: YANG Data Model for Network Access 1216 Control Lists (ACLs)"; 1217 } 1218 leaf type { 1219 type ietf-acl:acl-type; 1220 description 1221 "Type of access control list. Indicates the primary intended 1222 type of match criteria (e.g., IPv4, IPv6) used in the list 1223 instance."; 1224 reference 1225 "RFC 8519: YANG Data Model for Network Access 1226 Control Lists (ACLs)"; 1227 } 1228 leaf activation-type { 1229 type activation-type; 1230 default "activate-when-mitigating"; 1231 description 1232 "Indicates the activation type of an ACL. An ACL can be 1233 deactivated, installed immediately, or installed when 1234 a mitigation is active."; 1235 } 1236 leaf pending-lifetime { 1237 type int32; 1238 units "minutes"; 1239 config false; 1240 description 1241 "Indicates the pending validity lifetime of the ACL 1242 entry."; 1243 } 1244 container aces { 1245 description 1246 "The Access Control Entries container contains 1247 a list of ACEs."; 1248 list ace { 1249 key "name"; 1250 ordered-by user; 1251 description 1252 "List of access list entries."; 1253 leaf name { 1254 type string { 1255 length "1..64"; 1256 } 1257 description 1258 "A unique name identifying this ACE."; 1259 reference 1260 "RFC 8519: YANG Data Model for Network Access 1261 Control Lists (ACLs)"; 1262 } 1263 container matches { 1264 description 1265 "The rules in this set determine what fields will be 1266 matched upon before any action is taken on them. 1268 If no matches are defined in a particular container, 1269 then any packet will match that container. 1271 If no matches are specified at all in an ACE, then any 1272 packet will match the ACE."; 1273 reference 1274 "RFC 8519: YANG Data Model for Network Access 1275 Control Lists (ACLs)"; 1276 choice l3 { 1277 container ipv4 { 1278 when "derived-from(../../../../type, " 1279 + "'ietf-acl:ipv4-acl-type')"; 1280 uses packet-fields:acl-ip-header-fields; 1281 uses packet-fields:acl-ipv4-header-fields; 1282 container fragment { 1283 description 1284 "Indicates how to handle IPv4 fragments."; 1285 uses fragment-fields; 1286 } 1287 description 1288 "Rule set that matches IPv4 header."; 1289 } 1290 container ipv6 { 1291 when "derived-from(../../../../type, " 1292 + "'ietf-acl:ipv6-acl-type')"; 1293 uses packet-fields:acl-ip-header-fields; 1294 uses packet-fields:acl-ipv6-header-fields; 1295 container fragment { 1296 description 1297 "Indicates how to handle IPv6 fragments."; 1299 uses fragment-fields; 1300 } 1301 description 1302 "Rule set that matches IPv6 header."; 1303 } 1304 description 1305 "Either IPv4 or IPv6."; 1306 } 1307 choice l4 { 1308 container tcp { 1309 uses packet-fields:acl-tcp-header-fields; 1310 container flags-bitmask { 1311 description 1312 "Indicates how to handle TCP flags."; 1313 uses tcp-flags; 1314 } 1315 uses ports; 1316 description 1317 "Rule set that matches TCP header."; 1318 } 1319 container udp { 1320 uses packet-fields:acl-udp-header-fields; 1321 uses ports; 1322 description 1323 "Rule set that matches UDP header."; 1324 } 1325 container icmp { 1326 uses packet-fields:acl-icmp-header-fields; 1327 description 1328 "Rule set that matches ICMP/ICMPv6 header."; 1329 } 1330 description 1331 "Can be TCP, UDP, or ICMP/ICMPv6"; 1332 } 1333 } 1334 container actions { 1335 description 1336 "Definitions of action for this ACE."; 1337 leaf forwarding { 1338 type identityref { 1339 base ietf-acl:forwarding-action; 1340 } 1341 mandatory true; 1342 description 1343 "Specifies the forwarding action per ACE."; 1344 reference 1345 "RFC 8519: YANG Data Model for Network Access 1346 Control Lists (ACLs)"; 1348 } 1349 leaf rate-limit { 1350 when "../forwarding = 'ietf-acl:accept'" { 1351 description 1352 "Rate-limit is valid only when accept action is 1353 used."; 1354 } 1355 type decimal64 { 1356 fraction-digits 2; 1357 } 1358 units "bytes per second"; 1359 description 1360 "Specifies how to rate-limit the traffic."; 1361 } 1362 } 1363 container statistics { 1364 config false; 1365 description 1366 "Aggregate statistics."; 1367 uses ietf-acl:acl-counters; 1368 } 1369 } 1370 } 1371 } 1372 } 1374 container dots-data { 1375 description 1376 "Main container for DOTS data channel."; 1377 list dots-client { 1378 key "cuid"; 1379 description 1380 "List of DOTS clients."; 1381 leaf cuid { 1382 type string; 1383 description 1384 "A unique identifier that is generated by a DOTS client 1385 to prevent request collisions."; 1386 reference 1387 "RFC YYYY: Distributed Denial-of-Service Open Threat 1388 Signaling (DOTS) Signal Channel Specification"; 1389 } 1390 leaf cdid { 1391 type string; 1392 description 1393 "A client domain identifier conveyed by a 1394 server-domain DOTS gateway to a remote DOTS server."; 1395 reference 1396 "RFC YYYY: Distributed Denial-of-Service Open Threat 1397 Signaling (DOTS) Signal Channel Specification"; 1398 } 1399 container aliases { 1400 description 1401 "Set of aliases that are bound to a DOTS client."; 1402 uses aliases; 1403 } 1404 container acls { 1405 description 1406 "Access lists that are bound to a DOTS client."; 1407 uses access-lists; 1408 } 1409 } 1410 container capabilities { 1411 config false; 1412 description 1413 "Match capabilities"; 1414 leaf-list address-family { 1415 type enumeration { 1416 enum "ipv4" { 1417 description 1418 "IPv4 is supported."; 1419 } 1420 enum "ipv6" { 1421 description 1422 "IPv6 is supported."; 1423 } 1424 } 1425 description 1426 "Indicates the IP address families supported by 1427 the DOTS server."; 1428 } 1429 leaf-list forwarding-actions { 1430 type identityref { 1431 base ietf-acl:forwarding-action; 1432 } 1433 description 1434 "Supported forwarding action(s)."; 1435 } 1436 leaf rate-limit { 1437 type boolean; 1438 description 1439 "Support of rate-limit action."; 1440 } 1441 leaf-list transport-protocols { 1442 type uint8; 1443 description 1444 "Upper-layer protocol associated with a filtering rule. 1446 Values are taken from the IANA protocol registry: 1447 https://www.iana.org/assignments/protocol-numbers/ 1448 protocol-numbers.xhtml 1450 For example, this field contains 1 for ICMP, 6 for TCP 1451 17 for UDP, or 58 for ICMPv6."; 1452 } 1453 container ipv4 { 1454 description 1455 "Indicates IPv4 header fields that are supported to enforce 1456 ACLs."; 1457 leaf dscp { 1458 type boolean; 1459 description 1460 "Support of filtering based on Differentiated Services Code 1461 Point (DSCP)."; 1462 } 1463 leaf ecn { 1464 type boolean; 1465 description 1466 "Support of filtering based on Explicit Congestion 1467 Notification (ECN)."; 1468 } 1469 leaf length { 1470 type boolean; 1471 description 1472 "Support of filtering based on the Total Length."; 1473 } 1474 leaf ttl { 1475 type boolean; 1476 description 1477 "Support of filtering based on the Time to Live (TTL)."; 1478 } 1479 leaf protocol { 1480 type boolean; 1481 description 1482 "Support of filtering based on protocol field."; 1483 } 1484 leaf ihl { 1485 type boolean; 1486 description 1487 "Support of filtering based on the Internet Header 1488 Length (IHL)."; 1489 } 1490 leaf flags { 1491 type boolean; 1492 description 1493 "Support of filtering based on the 'flags'."; 1494 } 1495 leaf offset { 1496 type boolean; 1497 description 1498 "Support of filtering based on the 'offset'."; 1499 } 1500 leaf identification { 1501 type boolean; 1502 description 1503 "Support of filtering based on the 'identification'."; 1504 } 1505 leaf source-prefix { 1506 type boolean; 1507 description 1508 "Support of filtering based on the source prefix."; 1509 } 1510 leaf destination-prefix { 1511 type boolean; 1512 description 1513 "Support of filtering based on the destination prefix."; 1514 } 1515 leaf fragment { 1516 type boolean; 1517 description 1518 "Indicates the capability of a DOTS server to 1519 enforce filters on IPv4 fragments. That is, the match 1520 functionality based on the Layer 3 'fragment' clause 1521 is supported."; 1522 } 1523 } 1524 container ipv6 { 1525 description 1526 "Indicates IPv6 header fields that are supported to enforce 1527 ACLs."; 1528 leaf dscp { 1529 type boolean; 1530 description 1531 "Support of filtering based on DSCP."; 1532 } 1533 leaf ecn { 1534 type boolean; 1535 description 1536 "Support of filtering based on ECN."; 1537 } 1538 leaf length { 1539 type boolean; 1540 description 1541 "Support of filtering based on the Payload Length."; 1542 } 1543 leaf hoplimit { 1544 type boolean; 1545 description 1546 "Support of filtering based on the Hop Limit."; 1547 } 1548 leaf protocol { 1549 type boolean; 1550 description 1551 "Support of filtering based on the Next Header field."; 1552 } 1553 leaf destination-prefix { 1554 type boolean; 1555 description 1556 "Support of filtering based on the destination prefix."; 1557 } 1558 leaf source-prefix { 1559 type boolean; 1560 description 1561 "Support of filtering based on the source prefix."; 1562 } 1563 leaf flow-label { 1564 type boolean; 1565 description 1566 "Support of filtering based on the Flow label."; 1567 } 1568 leaf fragment { 1569 type boolean; 1570 description 1571 "Indicates the capability of a DOTS server to 1572 enforce filters on IPv6 fragments."; 1573 } 1574 } 1575 container tcp { 1576 description 1577 "Set of TCP fields that are supported by the DOTS server 1578 to enfoce filters."; 1579 leaf sequence-number { 1580 type boolean; 1581 description 1582 "Support of filtering based on the TCP sequence number."; 1583 } 1584 leaf acknowledgement-number { 1585 type boolean; 1586 description 1587 "Support of filtering based on the TCP acknowledgement 1588 number."; 1589 } 1590 leaf data-offset { 1591 type boolean; 1592 description 1593 "Support of filtering based on the TCP data-offset."; 1594 } 1595 leaf reserved { 1596 type boolean; 1597 description 1598 "Support of filtering based on the TCP reserved field."; 1599 } 1600 leaf flags { 1601 type boolean; 1602 description 1603 "Support of filtering, as defined in RFC 8519, based 1604 on the TCP flags."; 1605 } 1606 leaf window-size { 1607 type boolean; 1608 description 1609 "Support of filtering based on the TCP window size."; 1610 } 1611 leaf urgent-pointer { 1612 type boolean; 1613 description 1614 "Support of filtering based on the TCP urgent pointer."; 1615 } 1616 leaf options { 1617 type boolean; 1618 description 1619 "Support of filtering based on the TCP options."; 1620 } 1621 leaf flags-bitmask { 1622 type boolean; 1623 description 1624 "Support of filtering based on the TCP flags bitmask."; 1625 } 1626 leaf source-port { 1627 type boolean; 1628 description 1629 "Support of filtering based on the source port number."; 1630 } 1631 leaf destination-port { 1632 type boolean; 1633 description 1634 "Support of filtering based on the destination port 1635 number."; 1637 } 1638 leaf port-range { 1639 type boolean; 1640 description 1641 "Support of filtering based on a port range. 1643 This includes filtering based on a source port range, 1644 destination port range, or both. All operators 1645 (i.e, less than or equal to, greater than or equal to, 1646 equal to, and not equal to) are supported."; 1647 } 1648 } 1649 container udp { 1650 description 1651 "Set of UDP fields that are supported by the DOTS server 1652 to enforce filters."; 1653 leaf length { 1654 type boolean; 1655 description 1656 "Support of filtering based on the UDP length."; 1657 } 1658 leaf source-port { 1659 type boolean; 1660 description 1661 "Support of filtering based on the source port number."; 1662 } 1663 leaf destination-port { 1664 type boolean; 1665 description 1666 "Support of filtering based on the destination port 1667 number."; 1668 } 1669 leaf port-range { 1670 type boolean; 1671 description 1672 "Support of filtering based on a port range. 1674 This includes filtering based on a source port range, 1675 destination port range, or both. All operators 1676 (i.e, less than or equal, greater than or equal, equal to, 1677 and not equal to) are supported."; 1678 } 1679 } 1680 container icmp { 1681 description 1682 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1683 server to enforce filters."; 1684 leaf type { 1685 type boolean; 1686 description 1687 "Support of filtering based on the ICMP/ICMPv6 type."; 1688 } 1689 leaf code { 1690 type boolean; 1691 description 1692 "Support of filtering based on the ICMP/ICMPv6 code."; 1693 } 1694 leaf rest-of-header { 1695 type boolean; 1696 description 1697 "Support of filtering based on the ICMP four-bytes 1698 field / the ICMPv6 message body."; 1699 } 1700 } 1701 } 1702 } 1703 } 1704 1706 5. Managing DOTS Clients 1708 5.1. Registering DOTS Clients 1710 In order to make use of DOTS data channel, a DOTS client MUST 1711 register to its DOTS server(s) by creating a DOTS client ('dots- 1712 client') resource. To that aim, DOTS clients SHOULD send a POST 1713 request (shown in Figure 11). 1715 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1716 Host: {host}:{port} 1717 Content-Type: application/yang-data+json 1719 { 1720 "ietf-dots-data-channel:dots-client": [ 1721 { 1722 "cuid": "string" 1723 } 1724 ] 1725 } 1727 Figure 11: POST to Register Schema 1729 The 'cuid' (client unique identifier) parameter is described below: 1731 cuid: A globally unique identifier that is meant to prevent 1732 collisions among DOTS clients. This attribute has the same 1733 meaning, syntax, and processing rules as the 'cuid' attribute 1734 defined in [I-D.ietf-dots-signal-channel]. 1736 DOTS clients MUST use the same 'cuid' for both signal and data 1737 channels. 1739 This is a mandatory attribute. 1741 In deployments where server-domain DOTS gateways are enabled, 1742 identity information about the origin source client domain SHOULD be 1743 supplied to the DOTS server. That information is meant to assist the 1744 DOTS server to enforce some policies. These policies can be enforced 1745 per-client, per-client domain, or both. Figure 12 shows a schema 1746 example of a request relayed by a server-domain DOTS gateway. 1748 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1749 Host: {host}:{port} 1750 Content-Type: application/yang-data+json 1752 { 1753 "ietf-dots-data-channel:dots-client": [ 1754 { 1755 "cuid": "string", 1756 "cdid": "string" 1757 } 1758 ] 1759 } 1761 Figure 12: POST to Register Schema (via a Server-Domain DOTS Gateway) 1763 A server-domain DOTS gateway SHOULD add the following attribute: 1765 cdid: This attribute has the same meaning, syntax, and processing 1766 rules as the 'cdid' attribute defined in 1767 [I-D.ietf-dots-signal-channel]. 1769 In deployments where server-domain DOTS gateways are enabled, 1770 'cdid' does not need to be inserted when relaying DOTS methods to 1771 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1772 servers are responsible for maintaining the association between 1773 'cdid' and 'cuid' for policy enforcement purposes. 1775 This is an optional attribute. 1777 A request example to create a 'dots-client' resource is depicted in 1778 Figure 13. This request is relayed by a server-domain DOTS gateway 1779 as hinted by the presence of the 'cdid' attribute. 1781 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1782 Host: example.com 1783 Content-Type: application/yang-data+json 1785 { 1786 "ietf-dots-data-channel:dots-client": [ 1787 { 1788 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1789 "cdid": "7eeaf349529eb55ed50113" 1790 } 1791 ] 1792 } 1794 Figure 13: POST to Register (DOTS gateway) 1796 As a reminder, DOTS gateways may rewrite the 'cuid' used by peer DOTS 1797 clients (Section 4.4.1 of [I-D.ietf-dots-signal-channel]). 1799 DOTS servers can identify the DOTS client domain using the 'cdid' 1800 parameter or using the client's DNS name specified in the Subject 1801 Alternative Name extension's dNSName type in the client certificate 1802 [RFC6125]. 1804 DOTS servers MUST limit the number of 'dots-client' resources to be 1805 created by the same DOTS client to 1 per request. Requests with 1806 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1807 To that aim, the DOTS server MUST rely on the same procedure to 1808 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1809 [I-D.ietf-dots-signal-channel]. 1811 The DOTS server indicates the result of processing the POST request 1812 using status-line codes. Status codes in the range "2xx" codes are 1813 success, "4xx" codes are some sort of invalid requests and "5xx" 1814 codes are returned if the DOTS server has erred or is incapable of 1815 accepting the creation of the 'dots-client' resource. In particular, 1817 o "201 Created" status-line is returned in the response, if the DOTS 1818 server has accepted the request. 1820 o "400 Bad Request" status-line is returned by the DOTS server, if 1821 the request does not include a 'cuid' parameter. The error-tag 1822 "missing-attribute" is used in this case. 1824 o "409 Conflict" status-line is returned to the requesting DOTS 1825 client, if the data resource already exists. The error-tag 1826 "resource-denied" is used in this case. 1828 Once a DOTS client registers itself to a DOTS server, it can 1829 create/delete/retrieve aliases (Section 6) and filtering rules 1830 (Section 7). 1832 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1833 register a DOTS client within the DOTS server. An example is shown 1834 in Figure 14. 1836 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1837 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1838 Host: example.com 1839 Content-Type: application/yang-data+json 1841 { 1842 "ietf-dots-data-channel:dots-client": [ 1843 { 1844 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1845 } 1846 ] 1847 } 1849 Figure 14: PUT to Register 1851 The DOTS gateway that inserted a 'cdid' in a PUT request MUST strip 1852 the 'cdid' parameter in the corresponding response before forwarding 1853 the response to the DOTS client. 1855 5.2. Unregistering DOTS Clients 1857 A DOTS client de-registers from its DOTS server(s) by deleting the 1858 'cuid' resource(s). Resources bound to this DOTS client will be 1859 deleted by the DOTS server. An example of a de-register request is 1860 shown in Figure 15. 1862 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1863 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1864 Host: example.com 1866 Figure 15: De-register a DOTS Client 1868 6. Managing DOTS Aliases 1870 The following sub-sections define means for a DOTS client to create 1871 aliases (Section 6.1), retrieve one or a list of aliases 1872 (Section 6.2), and delete an alias (Section 6.3). 1874 6.1. Create Aliases 1876 A POST or PUT request is used by a DOTS client to create aliases, for 1877 resources for which a mitigation may be requested. Such aliases may 1878 be used in subsequent DOTS signal channel exchanges to refer more 1879 efficiently to the resources under attack. 1881 DOTS clients within the same domain can create different aliases for 1882 the same resource. 1884 The structure of POST requests used to create aliases is shown in 1885 Figure 16. 1887 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1888 /dots-client=cuid HTTP/1.1 1889 Host: {host}:{port} 1890 Content-Type: application/yang-data+json 1892 { 1893 "ietf-dots-data-channel:aliases": { 1894 "alias": [ 1895 { 1896 "name": "string", 1897 "target-prefix": [ 1898 "string" 1899 ], 1900 "target-port-range": [ 1901 { 1902 "lower-port": integer, 1903 "upper-port": integer 1904 } 1905 ], 1906 "target-protocol": [ 1907 integer 1908 ], 1909 "target-fqdn": [ 1910 "string" 1911 ], 1912 "target-uri": [ 1913 "string" 1914 ] 1915 } 1916 ] 1917 } 1918 } 1920 Figure 16: POST to Create Aliases (Request Schema) 1922 The parameters are described below: 1924 name: Name of the alias. 1926 This is a mandatory attribute. 1928 target-prefix: Prefixes are separated by commas. Prefixes are 1929 represented using Classless Inter-domain Routing (CIDR) notation 1930 [RFC4632]. As a reminder, the prefix length must be less than or 1931 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1933 The prefix list MUST NOT include broadcast, loopback, or multicast 1934 addresses. These addresses are considered as invalid values. In 1935 addition, the DOTS server MUST validate that these prefixes are 1936 within the scope of the DOTS client domain. Other validation 1937 checks may be supported by DOTS servers. 1939 This is an optional attribute. 1941 target-port-range: A range of port numbers. 1943 The port range is defined by two bounds, a lower port number 1944 (lower-port) and an upper port number (upper-port). The range is 1945 considered to include both the lower and upper bounds. 1947 When only 'lower-port' is present, it represents a single port 1948 number. 1950 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1951 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1952 [RFC4340], the range of port numbers can be, for example, 1953 1024-65535. 1955 This is an optional attribute. 1957 target-protocol: A list of protocols. Values are taken from the 1958 IANA protocol registry [proto_numbers]. 1960 If 'target-protocol' is not specified, then the request applies to 1961 any protocol. 1963 This is an optional attribute. 1965 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 1966 identifying resources under attack [RFC8499]. 1968 How a name is passed to an underlying name resolution library is 1969 implementation- and deployment-specific. Nevertheless, once the 1970 name is resolved into one or multiple IP addresses, DOTS servers 1971 MUST apply the same validation checks as those for 'target- 1972 prefix'. 1974 The use of FQDNs may be suboptimal because it does not guarantee 1975 that the DOTS server will resolve a name to the same IP addresses 1976 that the DOTS client does. 1978 This is an optional attribute. 1980 target-uri: A list of Uniform Resource Identifiers (URIs) 1981 [RFC3986]. 1983 The same validation checks used for 'target-fqdn' MUST be followed 1984 by DOTS servers to validate a target URI. 1986 This is an optional attribute. 1988 In POST or PUT requests, at least one of the 'target-prefix', 1989 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1990 agents can safely ignore Vendor-Specific parameters they don't 1991 understand. 1993 If more than one 'target-*' scope types (e.g., 'target-prefix' and 1994 'target-fqdn' or 'target-fqdn' and 'target-uri') are included in a 1995 POST or PUT request, the DOTS server binds all resulting IP 1996 addresses/prefixes to the same resource. 1998 Figure 17 shows a POST request to create an alias called "https1" for 1999 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 2000 listening on TCP port number 443. 2002 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2003 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2004 Host: www.example.com 2005 Content-Type: application/yang-data+json 2007 { 2008 "ietf-dots-data-channel:aliases": { 2009 "alias": [ 2010 { 2011 "name": "https1", 2012 "target-protocol": [ 2013 6 2014 ], 2015 "target-prefix": [ 2016 "2001:db8:6401::1/128", 2017 "2001:db8:6401::2/128" 2018 ], 2019 "target-port-range": [ 2020 { 2021 "lower-port": 443 2022 } 2023 ] 2024 } 2025 ] 2026 } 2027 } 2029 Figure 17: Example of a POST to Create an Alias 2031 "201 Created" status-line MUST be returned in the response if the 2032 DOTS server has accepted the alias. 2034 "409 Conflict" status-line MUST be returned to the requesting DOTS 2035 client, if the request is conflicting with an existing alias name. 2036 The error-tag "resource-denied" is used in this case. 2038 If the request is missing a mandatory attribute or it contains an 2039 invalid or unknown parameter, "400 Bad Request" status-line MUST be 2040 returned by the DOTS server. The error-tag is set to "missing- 2041 attribute", "invalid-value", or "unknown-element" as a function of 2042 the encountered error. 2044 If the request is received via a server-domain DOTS gateway, but the 2045 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2046 is expected to be supplied, the DOTS server MUST reply with "403 2047 Forbidden" status-line and the error-tag "access-denied". Upon 2048 receipt of this message, the DOTS client MUST register (Section 5). 2050 A DOTS client uses the PUT request to modify the aliases in the DOTS 2051 server. In particular, a DOTS client MUST update its alias entries 2052 upon change of the prefix indicated in the 'target-prefix'. 2054 A DOTS server MUST maintain an alias for at least 10080 minutes (1 2055 week). If no refresh request is seen from the DOTS client, the DOTS 2056 server removes expired entries. 2058 6.2. Retrieve Installed Aliases 2060 A GET request is used to retrieve one or all installed aliases by a 2061 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 2062 'name' is included in the request, this is an indication that the 2063 request is about retrieving all aliases instantiated by the DOTS 2064 client. 2066 Figure 18 shows an example to retrieve all the aliases that were 2067 instantiated by the requesting DOTS client. The "content" query 2068 parameter and its permitted values are defined in Section 4.8.1 of 2069 [RFC8040]. 2071 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2072 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2073 /aliases?content=all HTTP/1.1 2074 Host: example.com 2075 Accept: application/yang-data+json 2077 Figure 18: GET to Retrieve All Installed Aliases 2079 Figure 19 shows an example of the response message body that includes 2080 all the aliases that are maintained by the DOTS server for the DOTS 2081 client identified by the 'cuid' parameter. 2083 { 2084 "ietf-dots-data-channel:aliases": { 2085 "alias": [ 2086 { 2087 "name": "Server1", 2088 "target-protocol": [ 2089 6 2090 ], 2091 "target-prefix": [ 2092 "2001:db8:6401::1/128", 2093 "2001:db8:6401::2/128" 2094 ], 2095 "target-port-range": [ 2096 { 2097 "lower-port": 443 2098 } 2099 ], 2100 "pending-lifetime": 3596 2101 }, 2102 { 2103 "name": "Server2", 2104 "target-protocol": [ 2105 6 2106 ], 2107 "target-prefix": [ 2108 "2001:db8:6401::10/128", 2109 "2001:db8:6401::20/128" 2110 ], 2111 "target-port-range": [ 2112 { 2113 "lower-port": 80 2114 } 2115 ], 2116 "pending-lifetime": 9869 2117 } 2118 ] 2119 } 2120 } 2122 Figure 19: An Example of Response Body Listing All Installed Aliases 2124 Figure 20 shows an example of a GET request to retrieve the alias 2125 "Server2" that was instantiated by the DOTS client. 2127 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2128 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2129 /aliases/alias=Server2?content=all HTTP/1.1 2130 Host: example.com 2131 Accept: application/yang-data+json 2133 Figure 20: GET to Retrieve an Alias 2135 If an alias name ('name') is included in the request, but the DOTS 2136 server does not find that alias name for this DOTS client in its 2137 configuration data, it MUST respond with a "404 Not Found" status- 2138 line. 2140 6.3. Delete Aliases 2142 A DELETE request is used to delete an alias maintained by a DOTS 2143 server. 2145 If the DOTS server does not find the alias name, conveyed in the 2146 DELETE request, in its configuration data for this DOTS client, it 2147 MUST respond with a "404 Not Found" status-line. 2149 The DOTS server successfully acknowledges a DOTS client's request to 2150 remove the alias using "204 No Content" status-line in the response. 2152 Figure 21 shows an example of a request to delete an alias. 2154 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2155 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2156 /aliases/alias=Server1 HTTP/1.1 2157 Host: example.com 2159 Figure 21: Delete an Alias 2161 7. Managing DOTS Filtering Rules 2163 The following sub-sections define means for a DOTS client to retrieve 2164 DOTS filtering capabilities (Section 7.1), create filtering rules 2165 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2166 delete a filtering rule (Section 7.4). 2168 7.1. Retrieve DOTS Filtering Capabilities 2170 A DOTS client MAY send a GET request to retrieve the filtering 2171 capabilities supported by a DOTS server. Figure 22 shows an example 2172 of such request. 2174 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2175 /capabilities HTTP/1.1 2176 Host: example.com 2177 Accept: application/yang-data+json 2179 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2181 A DOTS client which issued a GET request to retrieve the filtering 2182 capabilities supported by its DOTS server, SHOULD NOT request for 2183 filtering actions that are not supported by that DOTS server. 2185 Figure 23 shows an example of a response body received from a DOTS 2186 server which supports: 2188 o IPv4, IPv6, TCP, UDP, ICMP, and ICMPv6 mandatory match criteria 2189 listed in Section 4.2. 2191 o 'accept', 'drop', and 'rate-limit' actions. 2193 { 2194 "ietf-dots-data-channel:capabilities": { 2195 "address-family": ["ipv4", "ipv6"], 2196 "forwarding-actions": ["drop", "accept"], 2197 "rate-limit": true, 2198 "transport-protocols": [1, 6, 17, 58], 2199 "ipv4": { 2200 "length": true, 2201 "protocol": true, 2202 "destination-prefix": true, 2203 "source-prefix": true, 2204 "fragment": true 2205 }, 2206 "ipv6": { 2207 "length": true, 2208 "protocol": true, 2209 "destination-prefix": true, 2210 "source-prefix": true, 2211 "fragment": true 2212 }, 2213 "tcp": { 2214 "flags-bitmask": true, 2215 "source-port": true, 2216 "destination-port": true, 2217 "port-range": true 2218 }, 2219 "udp": { 2220 "length": true, 2221 "source-port": true, 2222 "destination-port": true, 2223 "port-range": true 2224 }, 2225 "icmp": { 2226 "type": true, 2227 "code": true 2228 } 2229 } 2230 } 2232 Figure 23: Reply to a GET Request with Filtering Capabilities 2233 (Message Body) 2235 7.2. Install Filtering Rules 2237 A POST or PUT request is used by a DOTS client to communicate 2238 filtering rules to a DOTS server. 2240 Figure 24 shows a POST request example to block traffic from 2241 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2242 discussed in Appendix A. 2244 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2245 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2246 Host: example.com 2247 Content-Type: application/yang-data+json 2249 { 2250 "ietf-dots-data-channel:acls": { 2251 "acl": [ 2252 { 2253 "name": "sample-ipv4-acl", 2254 "type": "ipv4-acl-type", 2255 "activation-type": "activate-when-mitigating", 2256 "aces": { 2257 "ace": [ 2258 { 2259 "name": "rule1", 2260 "matches": { 2261 "ipv4": { 2262 "destination-ipv4-network": "198.51.100.0/24", 2263 "source-ipv4-network": "192.0.2.0/24" 2264 } 2265 }, 2266 "actions": { 2267 "forwarding": "drop" 2268 } 2269 } 2270 ] 2271 } 2272 } 2273 ] 2274 } 2275 } 2277 Figure 24: POST to Install Filtering Rules 2279 The meaning of these parameters is as follows: 2281 name: The name of the access list. 2283 This is a mandatory attribute. 2285 type: Indicates the primary intended type of match criteria (e.g., 2286 IPv4, IPv6). It is set to 'ipv4-acl-type' in the example of 2287 Figure 24. 2289 This is an optional attribute. 2291 activation-type: Indicates whether an ACL has to be activated 2292 (immediately or during mitigation time) or instantiated without 2293 being activated (deactivated). Deactivated ACLs can be activated 2294 using a variety of means such as manual configuration on a DOTS 2295 server or using the DOTS data channel. 2297 If this attribute is not provided, the DOTS server MUST use 2298 'activate-when-mitigating' as default value. 2300 When a mitigation is in progress, the DOTS server MUST only 2301 activate 'activate-when-mitigating' filters that are bound to the 2302 DOTS client that triggered the mitigation. 2304 This is an optional attribute. 2306 matches: Define criteria used to identify a flow on which to apply 2307 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2308 The detailed match parameters are specified in Section 4. 2310 In the example depicted in Figure 24, an IPv4 matching criteria is 2311 used. 2313 This is an optional attribute. 2315 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2316 MUST validate that these prefixes are within the scope of the DOTS 2317 client domain. Other validation checks may be supported by DOTS 2318 servers. If this attribute is not provided, the DOTS server 2319 enforces the ACL on any destination IP address that belong to the 2320 DOTS client domain. 2322 This is a mandatory attribute in requests with an 'activation- 2323 type' set to 'immediate'. 2325 source-ipv4-network: The source IPv4 prefix. 2327 This is an optional attribute. 2329 actions: Actions in the forwarding ACL category can be "drop" or 2330 "accept". The "accept" action is used to accept-list traffic. 2331 The "drop" action is used to drop-list traffic. 2333 Accepted traffic may be subject to "rate-limit"; the allowed 2334 traffic rate is represented in bytes per second. This unit is the 2335 same as the one used for "traffic-rate" in [RFC5575]. 2337 This is a mandatory attribute. 2339 The DOTS server indicates the result of processing the POST request 2340 using the status-line. Concretely, "201 Created" status-line MUST be 2341 returned in the response if the DOTS server has accepted the 2342 filtering rules. If the request is missing a mandatory attribute or 2343 contains an invalid or unknown parameter (e.g., a match field not 2344 supported by the DOTS server), "400 Bad Request" status-line MUST be 2345 returned by the DOTS server in the response. The error-tag is set to 2346 "missing-attribute", "invalid-value", or "unknown-element" as a 2347 function of the encountered error. 2349 If the request is received via a server-domain DOTS gateway, but the 2350 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2351 is expected to be supplied, the DOTS server MUST reply with "403 2352 Forbidden" status-line and the error-tag "access-denied". Upon 2353 receipt of this message, the DOTS client MUST register (Figure 11). 2355 If the request is conflicting with an existing filtering installed by 2356 another DOTS client of the domain, absent any local policy, the DOTS 2357 server returns "409 Conflict" status-line to the requesting DOTS 2358 client. The error-tag "resource-denied" is used in this case. 2360 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2361 to specify how an access control entry is inserted within an ACL and 2362 how an ACL is inserted within an ACL set. 2364 The DOTS client uses the PUT request to modify its filtering rules 2365 maintained by the DOTS server. In particular, a DOTS client MUST 2366 update its filtering entries upon change of the destination-prefix. 2367 How such change is detected is out of scope. 2369 A DOTS server MUST maintain a filtering rule for at least 10080 2370 minutes (1 week). If no refresh request is seen from the DOTS 2371 client, the DOTS server removes expired entries. Typically, a 2372 refresh request is a PUT request which echoes the content of a 2373 response to a GET request with all of the read-only parameters 2374 stripped out (e.g., pending-lifetime). 2376 7.3. Retrieve Installed Filtering Rules 2378 A DOTS client periodically queries its DOTS server to check the 2379 counters for installed filtering rules. A GET request is used to 2380 retrieve filtering rules from a DOTS server. In order to indicate 2381 which type of data is requested in a GET request, the DOTS client 2382 sets adequately the "content" query parameter. 2384 If the DOTS server does not find the access list name conveyed in the 2385 GET request in its configuration data for this DOTS client, it 2386 responds with a "404 Not Found" status-line. 2388 In order to illustrate the intended behavior, consider the example 2389 depicted in Figure 25. In reference to this example, the DOTS client 2390 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2392 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2393 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2394 /acl=test-acl-ipv6-udp HTTP/1.1 2395 Host: example.com 2396 Content-Type: application/yang-data+json 2398 { 2399 "ietf-dots-data-channel:acls": { 2400 "acl": [ 2401 { 2402 "name": "test-acl-ipv6-udp", 2403 "type": "ipv6-acl-type", 2404 "activation-type": "immediate", 2405 "aces": { 2406 "ace": [ 2407 { 2408 "name": "my-test-ace", 2409 "matches": { 2410 "ipv6": { 2411 "destination-ipv6-network": "2001:db8:6401::2/127", 2412 "source-ipv6-network": "2001:db8:1234::/96", 2413 "protocol": 17, 2414 "flow-label": 10000 2415 }, 2416 "udp": { 2417 "source-port": { 2418 "operator": "lte", 2419 "port": 80 2420 }, 2421 "destination-port": { 2422 "operator": "neq", 2423 "port": 1010 2424 } 2425 } 2426 }, 2427 "actions": { 2428 "forwarding": "accept" 2429 } 2430 } 2431 ] 2432 } 2433 } 2434 ] 2435 } 2436 } 2438 Figure 25: Example of a PUT Request to Create a Filtering 2440 The peer DOTS server follows the procedure specified in Section 7.2 2441 to process the request. We consider in the following that a positive 2442 response is sent back to the requesting DOTS client to confirm that 2443 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2444 server. 2446 The DOTS client can issue a GET request to retrieve all its filtering 2447 rules and the number of matches for the installed filtering rules as 2448 illustrated in Figure 26. The "content" query parameter is set to 2449 'all'. The message body of the response to this GET request is shown 2450 in Figure 27. 2452 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2453 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2454 /acls?content=all HTTP/1.1 2455 Host: example.com 2456 Accept: application/yang-data+json 2458 Figure 26: Retrieve the Configuration Data and State Data for the 2459 Filtering Rules (GET Request) 2461 { 2462 "ietf-dots-data-channel:acls": { 2463 "acl": [ 2464 { 2465 "name": "test-acl-ipv6-udp", 2466 "type": "ipv6-acl-type", 2467 "activation-type": "immediate", 2468 "pending-lifetime":9080, 2469 "aces": { 2470 "ace": [ 2471 { 2472 "name": "my-test-ace", 2473 "matches": { 2474 "ipv6": { 2475 "destination-ipv6-network": "2001:db8:6401::2/127", 2476 "source-ipv6-network": "2001:db8:1234::/96", 2477 "protocol": 17, 2478 "flow-label": 10000 2479 }, 2480 "udp": { 2481 "source-port": { 2482 "operator": "lte", 2483 "port": 80 2484 }, 2485 "destination-port": { 2486 "operator": "neq", 2487 "port": 1010 2488 } 2489 } 2490 }, 2491 "actions": { 2492 "forwarding": "accept" 2493 } 2494 } 2495 ] 2496 } 2497 } 2498 ] 2499 } 2500 } 2502 Figure 27: Retrieve the Configuration Data and State Data for the 2503 Filtering Rules (Response Message Body) 2505 Also, a DOTS client can issue a GET request to retrieve only 2506 configuration data related to an ACL as shown in Figure 28. It does 2507 so by setting the "content" query parameter to 'config'. 2509 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2510 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2511 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2512 Host: example.com 2513 Accept: application/yang-data+json 2515 Figure 28: Retrieve the Configuration Data for a Filtering Rule (GET 2516 Request) 2518 A response to this GET request is shown in Figure 29. 2520 { 2521 "ietf-dots-data-channel:acls": { 2522 "acl": [ 2523 { 2524 "name": "test-acl-ipv6-udp", 2525 "type": "ipv6-acl-type", 2526 "activation-type": "immediate", 2527 "aces": { 2528 "ace": [ 2529 { 2530 "name": "my-test-ace", 2531 "matches": { 2532 "ipv6": { 2533 "destination-ipv6-network": "2001:db8:6401::2/127", 2534 "source-ipv6-network": "2001:db8:1234::/96", 2535 "protocol": 17, 2536 "flow-label": 10000 2537 }, 2538 "udp": { 2539 "source-port": { 2540 "operator": "lte", 2541 "port": 80 2542 }, 2543 "destination-port": { 2544 "operator": "neq", 2545 "port": 1010 2546 } 2547 } 2548 }, 2549 "actions": { 2550 "forwarding": "accept" 2551 } 2552 } 2553 ] 2554 } 2555 } 2556 ] 2557 } 2558 } 2560 Figure 29: Retrieve the Configuration Data for a Filtering Rule 2561 (Response Message Body) 2563 A DOTS client can also issue a GET request with a "content" query 2564 parameter set to 'non-config' to exclusively retrieve non- 2565 configuration data bound to a given ACL as shown in Figure 30. A 2566 response to this GET request is shown in Figure 31. 2568 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2569 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2570 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2571 Host: example.com 2572 Accept: application/yang-data+json 2574 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule 2575 (GET Request) 2577 { 2578 "ietf-dots-data-channel:acls": { 2579 "acl": [ 2580 { 2581 "name": "test-acl-ipv6-udp", 2582 "pending-lifetime": 8000, 2583 "aces": { 2584 "ace": [ 2585 { 2586 "name": "my-test-ace" 2587 } 2588 ] 2589 } 2590 } 2591 ] 2592 } 2593 } 2595 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule 2596 (Response Message Body) 2598 7.4. Remove Filtering Rules 2600 A DELETE request is used by a DOTS client to delete filtering rules 2601 from a DOTS server. 2603 If the DOTS server does not find the access list name carried in the 2604 DELETE request in its configuration data for this DOTS client, it 2605 MUST respond with a "404 Not Found" status-line. The DOTS server 2606 successfully acknowledges a DOTS client's request to withdraw the 2607 filtering rules using "204 No Content" status-line, and removes the 2608 filtering rules accordingly. 2610 Figure 32 shows an example of a request to remove the IPv4 ACL 2611 "sample-ipv4-acl" created in Section 7.2. 2613 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2614 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2615 /acl=sample-ipv4-acl HTTP/1.1 2616 Host: example.com 2618 Figure 32: Remove a Filtering Rule (DELETE Request) 2620 Figure 33 shows an example of a response received from the DOTS 2621 server to confirm the deletion of "sample-ipv4-acl". 2623 HTTP/1.1 204 No Content 2624 Server: Apache 2625 Date: Fri, 27 Jul 2018 10:05:15 GMT 2626 Cache-Control: no-cache 2627 Content-Type: application/yang-data+json 2628 Content-Length: 0 2629 Connection: Keep-Alive 2631 Figure 33: Remove a Filtering Rule (Response) 2633 8. Operational Considerations 2635 The following operational considerations should be taken into 2636 account: 2638 o DOTS servers MUST NOT enable both DOTS data channel and direct 2639 configuration, to avoid race conditions and inconsistent 2640 configurations arising from simultaneous updates from multiple 2641 sources. 2643 o DOTS agents SHOULD enable the DOTS data channel to configure 2644 aliases and ACLs, and only use direct configuration as a stop-gap 2645 mechanism to test DOTS signal channel with aliases and ACLs. 2646 Further, direct configuration SHOULD only be used when the on-path 2647 DOTS agents are within the same domain. 2649 o If a DOTS server has enabled direct configuration, it can reject 2650 the DOTS data channel connection using hard ICMP error [RFC1122] 2651 or RST (Reset) bit in the TCP header or reject the RESTCONF 2652 request using an error response containing a "503 Service 2653 Unavailable" status-line. 2655 9. IANA Considerations 2657 This document requests IANA to register the following URI in the "ns" 2658 subregistry within the "IETF XML Registry" [RFC3688]: 2660 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2661 Registrant Contact: The IESG. 2662 XML: N/A; the requested URI is an XML namespace. 2664 This document requests IANA to register the following YANG module in 2665 the "YANG Module Names" subregistry [RFC7950] within the "YANG 2666 Parameters" registry. 2668 Name: ietf-dots-data-channel 2669 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2670 Prefix: data-channel 2671 Reference: RFC XXXX 2673 This module is not maintained by IANA. 2675 10. Security Considerations 2677 RESTCONF security considerations are discussed in [RFC8040]. In 2678 particular, DOTS agents MUST follow the security recommendations in 2679 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2680 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2681 [I-D.ietf-dots-signal-channel]. 2683 Authenticated encryption MUST be used for data confidentiality and 2684 message integrity. The interaction between the DOTS agents requires 2685 Transport Layer Security (TLS) with a cipher suite offering 2686 confidentiality protection and the guidance given in [RFC7525] MUST 2687 be followed to avoid attacks on TLS. 2689 The installation of drop- or accept-list rules using RESTCONF over 2690 TLS reveals the attacker IP addresses and legitimate IP addresses 2691 only to the DOTS server trusted by the DOTS client. The secure 2692 communication channel between DOTS agents provides privacy and 2693 prevents a network eavesdropper from directly gaining access to the 2694 drop- and accept-listed IP addresses. 2696 An attacker may be able to inject RST packets, bogus application 2697 segments, etc., regardless of whether TLS authentication is used. 2698 Because the application data is TLS protected, this will not result 2699 in the application receiving bogus data, but it will constitute a DoS 2700 on the connection. This attack can be countered by using TCP-AO 2701 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2702 attacker will be rejected by the TCP-AO integrity check and therefore 2703 will never reach the TLS layer. 2705 In order to prevent leaking internal information outside a client- 2706 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2707 internal DOTS clients (e.g., source IP address, client's hostname) 2708 unless explicitly configured to do so. 2710 DOTS servers MUST verify that requesting DOTS clients are entitled to 2711 enforce filtering rules on a given IP prefix. That is, only 2712 filtering rules on IP resources that belong to the DOTS client domain 2713 can be authorized by a DOTS server. The exact mechanism for the DOTS 2714 servers to validate that the target prefixes are within the scope of 2715 the DOTS client domain is deployment-specific. 2717 Rate-limiting DOTS requests, including those with new 'cuid' values, 2718 from the same DOTS client defends against DoS attacks that would 2719 result from varying the 'cuid' to exhaust DOTS server resources. 2720 Rate-limit policies SHOULD be enforced on DOTS gateways (if deployed) 2721 and DOTS servers. 2723 Applying resources quota per DOTS client and/or per DOTS client 2724 domain (e.g., limit the number of aliases and filters to be installed 2725 by DOTS clients) prevents DOTS server resources to be aggressively 2726 used by some DOTS clients and ensures, therefore, DDoS mitigation 2727 usage fairness. Additionally, DOTS servers may limit the number of 2728 DOTS clients that can be enabled per domain. 2730 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 2731 privacy enabling protocols (e.g., DNS over TLS [RFC7858] or DoH 2732 [RFC8484]) to prevent eavesdroppers from possibly identifying the 2733 target resources protected by the DDoS mitigation service, and means 2734 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 2735 [RFC4034]). 2737 The presence of DOTS gateways may lead to infinite forwarding loops, 2738 which is undesirable. To prevent and detect such loops, a mechanism 2739 is defined in Section 3.4. 2741 All data nodes defined in the YANG module which can be created, 2742 modified, and deleted (i.e., config true, which is the default) are 2743 considered sensitive. Write operations applied to these data nodes 2744 without proper protection can negatively affect network operations. 2745 This module reuses YANG structures from [RFC8519], and the security 2746 considerations for those nodes continue to apply for this usage. 2747 Appropriate security measures are recommended to prevent illegitimate 2748 users from invoking DOTS data channel primitives. Nevertheless, an 2749 attacker who can access a DOTS client is technically capable of 2750 launching various attacks, such as: 2752 o Setting an arbitrarily low rate-limit, which may prevent 2753 legitimate traffic from being forwarded (rate-limit). 2755 o Setting an arbitrarily high rate-limit, which may lead to the 2756 forwarding of illegitimate DDoS traffic (rate-limit). 2758 o Communicating invalid aliases to the server (alias), which will 2759 cause the failure of associating both data and signal channels. 2761 o Setting invalid ACL entries, which may prevent legitimate traffic 2762 from being forwarded. Likewise, invalid ACL entries may lead to 2763 forward DDoS traffic. 2765 11. Contributing Authors 2767 The following individuals co-authored this document: 2769 Kaname Nishizuka 2770 NTT Communications 2771 GranPark 16F 3-4-1 Shibaura, Minato-ku 2772 Tokyo 108-8118 2773 Japan 2775 Email: kaname@nttv6.jp 2777 Liang Xia 2778 Huawei 2779 101 Software Avenue, Yuhuatai District 2780 Nanjing, Jiangsu 210012 2781 China 2783 Email: frank.xialiang@huawei.com 2785 Prashanth Patil 2786 Cisco Systems, Inc. 2788 Email: praspati@cisco.com 2790 Andrew Mortensen 2791 Arbor Networks, Inc. 2792 2727 S. State St 2793 Ann Arbor, MI 48104 2794 United States 2796 Email: andrew.mortensen@netscout.com 2798 Nik Teague 2799 Verisign, Inc. 2800 United States 2802 Email: nteague@verisign.com 2804 12. Contributors 2806 The following individuals have contributed to this document: 2808 o Dan Wing, Email: dwing-ietf@fuggles.com 2810 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.com 2812 13. Acknowledgements 2814 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2815 Doron, Russ White, Gilbert Clark, Kathleen Moriarty, Nesredien 2816 Suleiman, Roni Even, and Brian Trammel for the discussion and 2817 comments. 2819 The authors would like to give special thanks to Kaname Nishizuka and 2820 Jon Shallow for their efforts in implementing the protocol and 2821 performing interop testing at IETF Hackathons. 2823 Many thanks to Ben Kaduk for the detailed AD review. 2825 Thanks to Martin Bjorklund for the guidance on RESTCONF. 2827 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 2828 Kuehlewind, and Warren Kumari for the review. 2830 14. References 2832 14.1. Normative References 2834 [I-D.ietf-dots-signal-channel] 2835 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 2836 Teague, "Distributed Denial-of-Service Open Threat 2837 Signaling (DOTS) Signal Channel Specification", draft- 2838 ietf-dots-signal-channel-31 (work in progress), March 2839 2019. 2841 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2842 Requirement Levels", BCP 14, RFC 2119, 2843 DOI 10.17487/RFC2119, March 1997, 2844 . 2846 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2847 DOI 10.17487/RFC3688, January 2004, 2848 . 2850 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2851 (CIDR): The Internet Address Assignment and Aggregation 2852 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2853 2006, . 2855 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2856 Verification of Domain-Based Application Service Identity 2857 within Internet Public Key Infrastructure Using X.509 2858 (PKIX) Certificates in the Context of Transport Layer 2859 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2860 2011, . 2862 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2863 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2864 . 2866 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2867 Protocol (HTTP/1.1): Message Syntax and Routing", 2868 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2869 . 2871 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2872 "Recommendations for Secure Use of Transport Layer 2873 Security (TLS) and Datagram Transport Layer Security 2874 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2875 2015, . 2877 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2878 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2879 . 2881 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2882 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2883 . 2885 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2886 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2887 . 2889 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2890 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2891 May 2017, . 2893 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2894 Interchange Format", STD 90, RFC 8259, 2895 DOI 10.17487/RFC8259, December 2017, 2896 . 2898 [RFC8519] Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, 2899 "YANG Data Model for Network Access Control Lists (ACLs)", 2900 RFC 8519, DOI 10.17487/RFC8519, March 2019, 2901 . 2903 14.2. Informative References 2905 [I-D.ietf-dots-architecture] 2906 Mortensen, A., K, R., Andreasen, F., Teague, N., and R. 2907 Compton, "Distributed-Denial-of-Service Open Threat 2908 Signaling (DOTS) Architecture", draft-ietf-dots- 2909 architecture-13 (work in progress), April 2019. 2911 [I-D.ietf-dots-requirements] 2912 Mortensen, A., K, R., and R. Moskowitz, "Distributed 2913 Denial of Service (DDoS) Open Threat Signaling 2914 Requirements", draft-ietf-dots-requirements-22 (work in 2915 progress), March 2019. 2917 [I-D.ietf-dots-server-discovery] 2918 Boucadair, M., K, R., and P. Patil, "Distributed-Denial- 2919 of-Service Open Threat Signaling (DOTS) Server Discovery", 2920 draft-ietf-dots-server-discovery-02 (work in progress), 2921 May 2019. 2923 [proto_numbers] 2924 "IANA, "Protocol Numbers"", 2011, 2925 . 2927 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2928 Communication Layers", STD 3, RFC 1122, 2929 DOI 10.17487/RFC1122, October 1989, 2930 . 2932 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2933 Resource Identifier (URI): Generic Syntax", STD 66, 2934 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2935 . 2937 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2938 Rose, "Resource Records for the DNS Security Extensions", 2939 RFC 4034, DOI 10.17487/RFC4034, March 2005, 2940 . 2942 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2943 Congestion Control Protocol (DCCP)", RFC 4340, 2944 DOI 10.17487/RFC4340, March 2006, 2945 . 2947 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2948 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2949 . 2951 [RFC5575] Marques, P., Sheth, N., Raszuk, R., Greene, B., Mauch, J., 2952 and D. McPherson, "Dissemination of Flow Specification 2953 Rules", RFC 5575, DOI 10.17487/RFC5575, August 2009, 2954 . 2956 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2957 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2958 June 2010, . 2960 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2961 Layer Security (TLS) and Datagram Transport Layer Security 2962 (DTLS) Heartbeat Extension", RFC 6520, 2963 DOI 10.17487/RFC6520, February 2012, 2964 . 2966 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 2967 and P. Hoffman, "Specification for DNS over Transport 2968 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 2969 2016, . 2971 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2972 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2973 . 2975 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 2976 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 2977 . 2979 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 2980 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 2981 January 2019, . 2983 Appendix A. Sample Examples: Filtering Fragments 2985 This specification strongly recommends the use of "fragment" for 2986 handling fragments. 2988 Figure 34 shows the content of the POST request to be issued by a 2989 DOTS client to its DOTS server to allow the traffic destined to 2990 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2991 packets. The following ACEs are defined (in this order): 2993 o "drop-all-fragments" ACE: discards all fragments. 2995 o "allow-dns-packets" ACE: accepts DNS packets destined to 2996 198.51.100.0/24. 2998 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2999 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 3000 Host: example.com 3001 Content-Type: application/yang-data+json 3003 { 3004 "ietf-dots-data-channel:acls": { 3005 "acl": [ 3006 { 3007 "name": "dns-fragments", 3008 "type": "ipv4-acl-type", 3009 "aces": { 3010 "ace": [ 3011 { 3012 "name": "drop-all-fragments", 3013 "matches": { 3014 "ipv4": { 3015 "fragment": { 3016 "operator": "match", 3017 "type": "isf" 3018 } 3019 } 3020 }, 3021 "actions": { 3022 "forwarding": "drop" 3023 } 3024 } 3025 ] 3026 "ace": [ 3027 { 3028 "name": "allow-dns-packets", 3029 "matches": { 3030 "ipv4": { 3031 "destination-ipv4-network": "198.51.100.0/24" 3032 } 3033 "udp": { 3034 "destination-port": { 3035 "operator": "eq", 3036 "port": 53 3037 } 3038 }, 3039 "actions": { 3040 "forwarding": "accept" 3041 } 3042 } 3043 ] 3044 } 3045 } 3046 ] 3048 } 3049 } 3051 Figure 34: Filtering IPv4 Fragmented Packets 3053 Figure 35 shows a POST request example issued by a DOTS client to its 3054 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 3055 port number 53, but to drop all fragmented packets. The following 3056 ACEs are defined (in this order): 3058 o "drop-all-fragments" ACE: discards all fragments (including atomic 3059 fragments). That is, IPv6 packets which include a Fragment header 3060 (44) are dropped. 3062 o "allow-dns-packets" ACE: accepts DNS packets destined to 3063 2001:db8::/32. 3065 POST /restconf/data/ietf-dots-data-channel:dots-data\ 3066 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 3067 Host: example.com 3068 Content-Type: application/yang-data+json 3070 { 3071 "ietf-dots-data-channel:acls": { 3072 "acl": [ 3073 { 3074 "name": "dns-fragments", 3075 "type": "ipv6-acl-type", 3076 "aces": { 3077 "ace": [ 3078 { 3079 "name": "drop-all-fragments", 3080 "matches": { 3081 "ipv6": { 3082 "fragment": { 3083 "operator": "match", 3084 "type": "isf" 3085 } 3086 } 3087 }, 3088 "actions": { 3089 "forwarding": "drop" 3090 } 3091 } 3092 ] 3093 "ace": [ 3094 { 3095 "name": "allow-dns-packets", 3096 "matches": { 3097 "ipv6": { 3098 "destination-ipv6-network": "2001:db8::/32" 3099 } 3100 "udp": { 3101 "destination-port": { 3102 "operator": "eq", 3103 "port": 53 3104 } 3105 } 3106 }, 3107 "actions": { 3108 "forwarding": "accept" 3109 } 3110 } 3111 ] 3112 } 3113 } 3114 ] 3115 } 3116 } 3118 Figure 35: Filtering IPv6 Fragmented Packets 3120 Appendix B. Sample Examples: Filtering TCP Messages 3122 This section provides sample examples to illustrate TCP-specific 3123 filtering based on the flag bits. These examples should not be 3124 interpreted as recommended filtering behaviors under specific DDoS 3125 attacks. 3127 B.1. Discard TCP Null Attack 3129 Figure 36 shows an example of a DOTS request sent by a DOTS client to 3130 install immediately a filter to discard incoming TCP messages having 3131 all flags unset. The bitmask can be set to 255 to check against the 3132 (CWR, ECE, URG, ACK, PSH, RST, SYN, FIN) flags. 3134 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3135 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3136 /acl=tcp-flags-example HTTP/1.1 3137 Host: example.com 3138 Content-Type: application/yang-data+json 3140 { 3141 "ietf-dots-data-channel:acls": { 3142 "acl": [{ 3143 "name": "tcp-flags-example", 3144 "activation-type": "immediate", 3145 "aces": { 3146 "ace": [{ 3147 "name": "null-attack", 3148 "matches": { 3149 "tcp": { 3150 "flags-bitmask": { 3151 "operator": "not any", 3152 "bitmask": 4095 3153 } 3154 } 3155 }, 3156 "actions": { 3157 "forwarding": "drop" 3158 } 3159 }] 3160 } 3161 }] 3162 } 3163 } 3165 Figure 36: Example of a DOTS Request to Deny TCP Null Attack Messages 3167 B.2. Rate-Limit SYN Flooding 3169 Figure 37 shows an ACL example to rate-limit incoming SYNs during a 3170 SYN-flood attack. 3172 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3173 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3174 /acl=tcp-flags-example HTTP/1.1 3175 Host: example.com 3176 Content-Type: application/yang-data+json 3178 { 3179 "ietf-dots-data-channel:acls": { 3180 "acl": [{ 3181 "name": "tcp-flags-example", 3182 "activation-type": "activate-when-mitigating", 3183 "aces": { 3184 "ace": [{ 3185 "name": "rate-limit-syn", 3186 "matches": { 3187 "tcp": { 3188 "flags-bitmask": { 3189 "operator": "match", 3190 "bitmask": 2 3191 } 3192 } 3193 }, 3194 "actions": { 3195 "forwarding": "accept", 3196 "rate-limit": "20.00" 3197 } 3198 }] 3199 } 3200 }] 3201 } 3202 } 3204 Figure 37: Example of DOTS Request to Rate-Limit Incoming TCP SYNs 3206 B.3. Rate-Limit ACK Flooding 3208 Figure 38 shows an ACL example to rate-limit incoming ACKs during an 3209 ACK-flood attack. 3211 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3212 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3213 /acl=tcp-flags-example HTTP/1.1 3214 Host: example.com 3215 Content-Type: application/yang-data+json 3217 { 3218 "ietf-dots-data-channel:acls": { 3219 "acl": [{ 3220 "name": "tcp-flags-example", 3221 "type": "ipv4-acl-type", 3222 "activation-type": "activate-when-mitigating", 3223 "aces": { 3224 "ace": [{ 3225 "name": "rate-limit-ack", 3226 "matches": { 3227 "tcp": { 3228 "flags-bitmask": { 3229 "operator": "match", 3230 "bitmask": 16 3231 } 3232 } 3233 }, 3234 "actions": { 3235 "forwarding": "accept", 3236 "rate-limit": "20.00" 3237 } 3238 }] 3239 } 3240 }] 3241 } 3242 } 3244 Figure 38: Example of DOTS Request to Rate-Limit Incoming TCP ACKs 3246 Authors' Addresses 3248 Mohamed Boucadair (editor) 3249 Orange 3250 Rennes 35000 3251 France 3253 Email: mohamed.boucadair@orange.com 3254 Tirumaleswar Reddy (editor) 3255 McAfee, Inc. 3256 Embassy Golf Link Business Park 3257 Bangalore, Karnataka 560071 3258 India 3260 Email: kondtir@gmail.com