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