idnits 2.17.1 draft-ietf-dots-data-channel-30.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 457 has weird spacing: '...er-port ine...' == Line 542 has weird spacing: '...warding ide...' == Line 839 has weird spacing: '... icmp typ...' -- The document date (July 03, 2019) is 1731 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 2207 -- Looks like a reference, but probably isn't: '6' on line 2207 -- Looks like a reference, but probably isn't: '17' on line 2207 -- Looks like a reference, but probably isn't: '58' on line 2207 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-34 ** 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 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5575 (Obsoleted by RFC 8955) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Intended status: Standards Track T. Reddy, Ed. 5 Expires: January 4, 2020 McAfee 6 July 03, 2019 8 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 9 Specification 10 draft-ietf-dots-data-channel-30 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 4, 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 . . . . . . . . . . . . . . . . . . . . . . 9 78 4. DOTS Data Channel YANG Module . . . . . . . . . . . . . . . . 10 79 4.1. Generic Tree Structure . . . . . . . . . . . . . . . . . 10 80 4.2. Filtering Fields . . . . . . . . . . . . . . . . . . . . 13 81 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 20 82 5. Managing DOTS Clients . . . . . . . . . . . . . . . . . . . . 37 83 5.1. Registering DOTS Clients . . . . . . . . . . . . . . . . 37 84 5.2. Unregistering DOTS Clients . . . . . . . . . . . . . . . 40 85 6. Managing DOTS Aliases . . . . . . . . . . . . . . . . . . . . 40 86 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 41 87 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 45 88 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 47 89 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 47 90 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 47 91 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 49 92 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 52 93 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 59 94 8. Operational Considerations . . . . . . . . . . . . . . . . . 60 95 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 96 10. Security Considerations . . . . . . . . . . . . . . . . . . . 61 97 11. Contributing Authors . . . . . . . . . . . . . . . . . . . . 63 98 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 64 99 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 65 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 65 101 14.1. Normative References . . . . . . . . . . . . . . . . . . 65 102 14.2. Informative References . . . . . . . . . . . . . . . . . 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]). 307 A single DOTS data channel between DOTS agents can be used to 308 exchange multiple requests and multiple responses. To reduce DOTS 309 client and DOTS server workload, DOTS clients SHOULD re-use the same 310 TLS session. While the communication to the DOTS server is 311 quiescent, the DOTS client MAY probe the server to ensure it has 312 maintained cryptographic state. Such probes can also keep alive 313 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 314 that the DOTS server still has TLS state by returning a TLS message. 316 A DOTS server may detect conflicting filtering requests from distinct 317 DOTS clients which belong to the same domain. For example, a DOTS 318 client could request to drop-list a prefix by specifying the source 319 prefix, while another DOTS client could request to accept-list that 320 same source prefix, but both having the same destination prefix. 321 DOTS servers SHOULD support a configuration parameter to indicate the 322 behavior to follow when a conflict is detected (e.g., reject all, 323 reject the new request, notify an administrator for validation). 324 Section 7.2 specifies a default behavior when no instruction is 325 supplied to a DOTS server. 327 How a DOTS client synchronizes its configuration with the one 328 maintained by its DOTS server(s) is implementation-specific. For 329 example: 331 o a DOTS client can systematically send a GET message before and/or 332 after a configuration change request. 334 o a DOTS client can re-establish the disconnected DOTS session after 335 an attack is mitigated and sends a GET message before a 336 configuration change request. 338 NAT considerations for the DOTS data channel are similar to those 339 discussed in Section 3 of [I-D.ietf-dots-signal-channel]. 341 How filtering rules that are instantiated on a DOTS server are 342 translated into network configurations actions is out of scope of 343 this specification. 345 Some of the fields introduced in Section 4 are also discussed in 346 Sections 5, 6, and 7. These sections are authoritative for these 347 fields. 349 3.2. DOTS Server(s) Discovery 351 This document assumes that DOTS clients are provisioned with a way to 352 know how to reach their DOTS server(s), which could occur by a 353 variety of means (e.g., local configuration, or dynamic means such as 354 DHCP [I-D.ietf-dots-server-discovery]). The specification of such 355 means are out of scope of this document. 357 Likewise, it is out of scope of this document to specify the behavior 358 to be followed by a DOTS client to send DOTS requests when multiple 359 DOTS servers are provisioned (e.g., contact all DOTS servers, select 360 one DOTS server among the list). 362 3.3. DOTS Gateways 364 When a server-domain DOTS gateway is involved in DOTS data channel 365 exchanges, the same considerations for manipulating the 'cdid' 366 (client domain identifier) parameter specified in 367 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 368 reminder, 'cdid' is meant to assist the DOTS server to enforce some 369 policies (e.g., limit the number of filtering rules per DOTS client 370 or per DOTS client domain). A loop detect mechanism for DOTS 371 gateways is specified in Section 3.4. 373 If a DOTS gateway is involved, the DOTS gateway verifies that the 374 DOTS client is authorized to undertake a data channel action (e.g., 375 instantiate filtering rules). If the DOTS client is authorized, it 376 propagates the rules to the upstream DOTS server. Likewise, the DOTS 377 server verifies that the DOTS gateway is authorized to relay data 378 channel actions. For example, to create or purge filters, a DOTS 379 client sends its request to its DOTS gateway. The DOTS gateway 380 validates the rules in the request and proxies the requests 381 containing the filtering rules to its DOTS server. When the DOTS 382 gateway receives the associated response from the DOTS server, it 383 propagates the response back to the DOTS client. 385 3.4. Detect and Prevent Infinite Loops 387 In order to detect and prevent infinite loops, DOTS gateways MUST 388 support the procedure defined in Section 5.7.1 of [RFC7230]. In 389 particular, each intermediate DOTS gateway MUST check that none of 390 its own information (e.g., server names, literal IP addresses) is 391 present in the "Via" header field of a DOTS message it receives: 393 o If it detects that its own information is present in the "Via" 394 header field, the DOTS gateway MUST NOT forward the DOTS message. 395 Messages that cannot be forwarded because of a loop SHOULD be 396 logged with a "508 Loop Detected" status-line returned sent back 397 to the DOTS peer. The structure of the reported error is depicted 398 in Figure 3. 400 error-app-tag: loop-detected 401 error-tag: operation-failed 402 error-type: transport, application 403 error-info: : A copy of the Via header field when 404 the loop was detected. 405 Description: An infinite loop has been detected when forwarding 406 a requests via a proxy. 408 Figure 3: Loop Detected Error 410 It is RECOMMENDED that DOTS clients and gateways support methods 411 to alert administrators about loop errors so that appropriate 412 actions are undertaken. 414 o Otherwise, the DOTS agent MUST update or insert the "Via" header 415 by appending its own information. 417 Unless configured otherwise, DOTS gateways at the boundaries of a 418 DOTS client domain SHOULD remove the previous "Via" header field 419 information after checking for a loop before forwarding. This 420 behavior is required for topology hiding purposes but can also serve 421 to minimize potential conflicts that may arise if overlapping 422 information is used in distinct DOTS domains (e.g., private IPv4 423 addresses, non globally unique aliases). 425 3.5. Stale Entries 427 In order to avoid stale entries, a lifetime is associated with alias 428 and filtering entries created by DOTS clients. Also, DOTS servers 429 may track the inactivity timeout of DOTS clients to detect stale 430 entries. 432 4. DOTS Data Channel YANG Module 434 4.1. Generic Tree Structure 436 The DOTS data channel YANG module (ietf-dots-data-channel) provides a 437 method for DOTS clients to manage aliases for resources for which 438 mitigation may be requested. Such aliases may be used in subsequent 439 DOTS signal channel exchanges to refer more efficiently to the 440 resources under attack. 442 Note that the full module's tree has been split across several 443 figures to aid the exposition of the various sub-trees. 445 The tree structure for the DOTS alias is depicted in Figure 4. 447 module: ietf-dots-data-channel 448 +--rw dots-data 449 +--rw dots-client* [cuid] 450 | +--rw cuid string 451 | +--rw cdid? string 452 | +--rw aliases 453 | | +--rw alias* [name] 454 | | +--rw name string 455 | | +--rw target-prefix* inet:ip-prefix 456 | | +--rw target-port-range* [lower-port] 457 | | | +--rw lower-port inet:port-number 458 | | | +--rw upper-port? inet:port-number 459 | | +--rw target-protocol* uint8 460 | | +--rw target-fqdn* inet:domain-name 461 | | +--rw target-uri* inet:uri 462 | | +--ro pending-lifetime? int32 463 | +--rw acls 464 | ... 465 +--ro capabilities 466 ... 468 Figure 4: DOTS Alias Subtree 470 Also, the 'ietf-dots-data-channel' module provides a method for DOTS 471 clients to manage filtering rules. Examples of filtering management 472 in a DOTS context include, but not limited to: 474 o Drop-list management, which enables a DOTS client to inform a DOTS 475 server about sources from which traffic should be discarded. 477 o Accept-list management, which enables a DOTS client to inform a 478 DOTS server about sources from which traffic should always be 479 accepted. 481 o Policy management, which enables a DOTS client to request the 482 installation or withdrawal of traffic filters, dropping or rate- 483 limiting unwanted traffic and permitting accept-listed traffic. 485 The tree structure for the DOTS filtering entries is depicted in 486 Figure 5. 488 Investigations into the prospect of augmenting 'ietf-access-control- 489 list' to meet DOTS requirements concluded that such a design approach 490 did not support many of the DOTS requirements, e.g., 492 o Retrieve a filtering entry (or all entries) created by a DOTS 493 client. 495 o Delete a filtering entry that was instantiated by a DOTS client. 497 Accordingly, new DOTS filtering entries (i.e., Access Control List 498 (ACL)) are defined that mimic the structure specified in [RFC8519]. 499 Concretely, DOTS agents are assumed to manipulate an ordered list of 500 ACLs; each ACL contains a separately ordered list of Access Control 501 Entries (ACEs). Each ACE has a group of match and a group of action 502 criteria. 504 Once all the ACE entries have been iterated though with no match, 505 then all the following ACL's ACE entries are iterated through until 506 the first match at which point the specified action is applied. If 507 there is no match during 'idle' time (i.e., no mitigation is active), 508 then there is no further action to be taken against the packet. If 509 there is no match during active mitigation, then the packet will 510 still be scrubbed by the DDoS mitigator. 512 module: ietf-dots-data-channel 513 +--rw dots-data 514 +--rw dots-client* [cuid] 515 | +--rw cuid string 516 | +--rw cdid? string 517 | +--rw aliases 518 | | ... 519 | +--rw acls 520 | +--rw acl* [name] 521 | +--rw name string 522 | +--rw type? ietf-acl:acl-type 523 | +--rw activation-type? activation-type 524 | +--ro pending-lifetime? int32 525 | +--rw aces 526 | +--rw ace* [name] 527 | +--rw name string 528 | +--rw matches 529 | | +--rw (l3)? 530 | | | +--:(ipv4) 531 | | | | ... 532 | | | +--:(ipv6) 533 | | | ... 534 | | +--rw (l4)? 535 | | +--:(tcp) 536 | | | ... 537 | | +--:(udp) 538 | | | ... 539 | | +--:(icmp) 540 | | ... 541 | +--rw actions 542 | | +--rw forwarding identityref 543 | | +--rw rate-limit? decimal64 544 | +--ro statistics 545 | +--ro matched-packets? yang:counter64 546 | +--ro matched-octets? yang:counter64 547 +--ro capabilities 548 ... 550 Figure 5: DOTS ACLs Subtree 552 Filtering rules instructed by a DOTS client assumes a default 553 direction: the destination is the DOTS client domain. 555 DOTS forwarding actions can be 'accept' (i.e., accept matching 556 traffic) or 'drop' (i.e., drop matching traffic without sending any 557 ICMP error message). Accepted traffic can be subject to rate- 558 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 559 matching traffic and send an ICMP error message to the source) is not 560 supported in 'ietf-dots-data-channel' because it is not appropriate 561 in the context of DDoS mitigation. Generating ICMP messages to 562 notify drops when mitigating a DDoS attack will exacerbate the DDoS 563 attack. Furthermore, these ICMP messages will be used by an attacker 564 as an explicit signal that the traffic is being blocked. 566 4.2. Filtering Fields 568 The 'ietf-dots-data-channel' module reuses the packet fields module 569 'ietf-packet-fields' [RFC8519] which defines matching on fields in 570 the packet including IPv4, IPv6, and transport layer fields. The 571 'ietf-dots-data-channel' module can be augmented, for example, to 572 support additional protocol-specific matching fields. 574 This specification defines a new IPv4/IPv6 matching field called 575 'fragment' to efficiently handle fragment-related filtering rules. 576 Indeed, [RFC8519] does not support such capability for IPv6 but 577 offers a partial support for IPv4 by means of 'flags'. Nevertheless, 578 the use of 'flags' is problematic since it does not allow to define a 579 bitmask. For example, setting other bits not covered by the 'flags' 580 filtering clause in a packet will allow that packet to get through 581 (because it won't match the ACE). Sample examples to illustrate how 582 'fragment' can be used are provided in Appendix A. 584 Figure 6 shows the IPv4 match subtree. 586 module: ietf-dots-data-channel 587 +--rw dots-data 588 +--rw dots-client* [cuid] 589 | ... 590 | +--rw acls 591 | +--rw acl* [name] 592 | ... 593 | +--rw aces 594 | +--rw ace* [name] 595 | +--rw name string 596 | +--rw matches 597 | | +--rw (l3)? 598 | | | +--:(ipv4) 599 | | | | +--rw ipv4 600 | | | | +--rw dscp? inet:dscp 601 | | | | +--rw ecn? uint8 602 | | | | +--rw length? uint16 603 | | | | +--rw ttl? uint8 604 | | | | +--rw protocol? uint8 605 | | | | +--rw ihl? uint8 606 | | | | +--rw flags? bits 607 | | | | +--rw offset? uint16 608 | | | | +--rw identification? uint16 609 | | | | +--rw (destination-network)? 610 | | | | | +--:(destination-ipv4-network) 611 | | | | | +--rw destination-ipv4-network? 612 | | | | | inet:ipv4-prefix 613 | | | | +--rw (source-network)? 614 | | | | | +--:(source-ipv4-network) 615 | | | | | +--rw source-ipv4-network? 616 | | | | | inet:ipv4-prefix 617 | | | | +--rw fragment 618 | | | | +--rw operator? operator 619 | | | | +--rw type fragment-type 620 | | | +--:(ipv6) 621 | | | ... 622 | | +--rw (l4)? 623 | | ... 624 | +--rw actions 625 | | ... 626 | +--ro statistics 627 | ... 628 +--ro capabilities 629 ... 631 Figure 6: DOTS ACLs Subtree (IPv4 Match) 633 Figure 7 shows the IPv6 match subtree. 635 module: ietf-dots-data-channel 636 +--rw dots-data 637 +--rw dots-client* [cuid] 638 | ... 639 | +--rw acls 640 | +--rw acl* [name] 641 | ... 642 | +--rw aces 643 | +--rw ace* [name] 644 | +--rw name string 645 | +--rw matches 646 | | +--rw (l3)? 647 | | | +--:(ipv4) 648 | | | | ... 649 | | | +--:(ipv6) 650 | | | +--rw ipv6 651 | | | +--rw dscp? inet:dscp 652 | | | +--rw ecn? uint8 653 | | | +--rw length? uint16 654 | | | +--rw ttl? uint8 655 | | | +--rw protocol? uint8 656 | | | +--rw (destination-network)? 657 | | | | +--:(destination-ipv6-network) 658 | | | | +--rw destination-ipv6-network? 659 | | | | inet:ipv6-prefix 660 | | | +--rw (source-network)? 661 | | | | +--:(source-ipv6-network) 662 | | | | +--rw source-ipv6-network? 663 | | | | inet:ipv6-prefix 664 | | | +--rw flow-label? 665 | | | | inet:ipv6-flow-label 666 | | | +--rw fragment 667 | | | +--rw operator? operator 668 | | | +--rw type fragment-type 669 | | +--rw (l4)? 670 | | ... 671 | +--rw actions 672 | | ... 673 | +--ro statistics 674 | ... 675 +--ro capabilities 676 ... 678 Figure 7: DOTS ACLs Subtree (IPv6 Match) 680 Figure 8 shows the TCP match subtree. In addition to the fields 681 defined in [RFC8519], this specification defines a new TCP matching 682 field, called 'flags-bitmask', to efficiently handle TCP flags 683 filtering rules. Some examples are provided in Appendix B. 685 module: ietf-dots-data-channel 686 +--rw dots-data 687 +-rw dots-client* [cuid] 688 | ... 689 | +-rw acls 690 | +-rw acl* [name] 691 | ... 692 | +-rw aces 693 | +-rw ace* [name] 694 | +-rw name string 695 | +-rw matches 696 | | +-rw (l3)? 697 | | | ... 698 | | +-rw (l4)? 699 | | +-:(tcp) 700 | | | +-rw tcp 701 | | | +--rw sequence-number? uint32 702 | | | +--rw acknowledgement-number? uint32 703 | | | +--rw data-offset? uint8 704 | | | +--rw reserved? uint8 705 | | | +--rw flags? bits 706 | | | +--rw window-size? uint16 707 | | | +--rw urgent-pointer? uint16 708 | | | +--rw options? binary 709 | | | +--rw flags-bitmask 710 | | | | +--rw operator? operator 711 | | | | +--rw bitmask uint16 712 | | | +--rw (source-port)? 713 | | | | +--:(source-port-range-or-operator) 714 | | | | +--rw source-port-range-or-operator 715 | | | | +--rw (port-range-or-operator)? 716 | | | | +--:(range) 717 | | | | | +--rw lower-port 718 | | | | | | inet:port-number 719 | | | | | +--rw upper-port 720 | | | | | inet:port-number 721 | | | | +--:(operator) 722 | | | | +--rw operator? 723 | | | | | operator 724 | | | | +--rw port 725 | | | | inet:port-number 726 | | | +--rw (destination-port)? 727 | | | +--:(destination-port-range-or-operator) 728 | | | +--rw destination-port-range-or-operator 729 | | | +--rw (port-range-or-operator)? 730 | | | +--:(range) 731 | | | | +--rw lower-port 732 | | | | | inet:port-number 733 | | | | +--rw upper-port 734 | | | | inet:port-number 735 | | | +--:(operator) 736 | | | +--rw operator? 737 | | | | operator 738 | | | +--rw port 739 | | | inet:port-number 740 | | +-:(udp) 741 | | | ... 742 | | +-:(icmp) 743 | | ... 744 | +-rw actions 745 | | ... 746 | +-ro statistics 747 | ... 748 +-ro capabilities 749 ... 751 Figure 8: DOTS ACLs Subtree (TCP Match) 753 Figure 9 shows the UDP and ICMP match subtrees. The same structure 754 is used for both ICMP and ICMPv6. The indication whether an ACL is 755 about ICMP or ICMPv6 is governed by the 'l3' match or the ACL type. 757 module: ietf-dots-data-channel 758 +-rw dots-data 759 +-rw dots-client* [cuid] 760 | ... 761 | +-rw acls 762 | +-rw acl* [name] 763 | ... 764 | +-rw aces 765 | +-rw ace* [name] 766 | +--rw name string 767 | +--rw matches 768 | | +--rw (l3)? 769 | | | ... 770 | | +--rw (l4)? 771 | | +--:(tcp) 772 | | | ... 773 | | +--:(udp) 774 | | | +--rw udp 775 | | | +--rw length? uint16 776 | | | +--rw (source-port)? 777 | | | | +--:(source-port-range-or-operator) 778 | | | | +--rw source-port-range-or-operator 779 | | | | +--rw (port-range-or-operator)? 780 | | | | +--:(range) 781 | | | | | +--rw lower-port 782 | | | | | | inet:port-number 783 | | | | | +--rw upper-port 784 | | | | | inet:port-number 785 | | | | +--:(operator) 786 | | | | +--rw operator? 787 | | | | | operator 788 | | | | +--rw port 789 | | | | inet:port-number 790 | | | +--rw (destination-port)? 791 | | | +--:(destination-port-range-or-operator) 792 | | | +--rw destination-port-range-or-operator 793 | | | +--rw (port-range-or-operator)? 794 | | | +--:(range) 795 | | | | +--rw lower-port 796 | | | | | inet:port-number 797 | | | | +--rw upper-port 798 | | | | inet:port-number 799 | | | +--:(operator) 800 | | | +--rw operator? 801 | | | | operator 802 | | | +--rw port 803 | | | inet:port-number 804 | | +--:(icmp) 805 | | +--rw icmp 806 | | +--rw type? uint8 807 | | +--rw code? uint8 808 | | +--rw rest-of-header? binary 809 | +--rw actions 810 | | ... 811 | +--ro statistics 812 | ... 813 +-ro capabilities 814 ... 816 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 818 DOTS implementations MUST support the following matching criteria: 820 match based on the IP header (IPv4 and IPv6), match based on the 821 transport header (TCP, UDP, and ICMP), and any combination 822 thereof. The same matching fields are used for both ICMP and 823 ICMPv6. 825 The following match fields MUST be supported by DOTS implementations 826 (Table 1): 828 ACL Mandatory Fields 829 Match 830 ------- ------------------------------------------------------------- 831 ipv4 length, protocol, destination-ipv4-network, source- 832 ipv4-network, and fragment 833 ipv6 length, protocol, destination-ipv6-network, source- 834 ipv6-network, and fragment 835 tcp flags-bitmask, source-port-range-or-operator, and 836 destination-port-range-or-operator 837 udp length, source-port-range-or-operator, and destination-port- 838 range-or-operator 839 icmp type and code 841 Table 1: Mandatory DOTS Channel Match Fields 843 Implementations MAY support other filtering match fields and actions. 844 The 'ietf-dots-data-channel' provides a method for an implementation 845 to expose its filtering capabilities. The tree structure of the 846 'capabilities' is shown in Figure 10. DOTS clients that support both 847 'fragment' and 'flags' (or 'flags-bitmask' and 'flags') matching 848 fields MUST NOT set these fields in the same request. 850 module: ietf-dots-data-channel 851 +--rw dots-data 852 ... 853 +--ro capabilities 854 +--ro address-family* enumeration 855 +--ro forwarding-actions* identityref 856 +--ro rate-limit? boolean 857 +--ro transport-protocols* uint8 858 +--ro ipv4 859 | +--ro dscp? boolean 860 | +--ro ecn? boolean 861 | +--ro length? boolean 862 | +--ro ttl? boolean 863 | +--ro protocol? boolean 864 | +--ro ihl? boolean 865 | +--ro flags? boolean 866 | +--ro offset? boolean 867 | +--ro identification? boolean 868 | +--ro source-prefix? boolean 869 | +--ro destination-prefix? boolean 870 | +--ro fragment? boolean 871 +--ro ipv6 872 | +--ro dscp? boolean 873 | +--ro ecn? boolean 874 | +--ro length? boolean 875 | +--ro hoplimit? boolean 876 | +--ro protocol? boolean 877 | +--ro destination-prefix? boolean 878 | +--ro source-prefix? boolean 879 | +--ro flow-label? boolean 880 | +--ro fragment? boolean 881 +--ro tcp 882 | +--ro sequence-number? boolean 883 | +--ro acknowledgement-number? boolean 884 | +--ro data-offset? boolean 885 | +--ro reserved? boolean 886 | +--ro flags? boolean 887 | +--ro window-size? boolean 888 | +--ro urgent-pointer? boolean 889 | +--ro options? boolean 890 | +--ro flags-bitmask? boolean 891 | +--ro source-port? boolean 892 | +--ro destination-port? boolean 893 | +--ro port-range? boolean 894 +--ro udp 895 | +--ro length? boolean 896 | +--ro source-port? boolean 897 | +--ro destination-port? boolean 898 | +--ro port-range? boolean 899 +--ro icmp 900 +--ro type? boolean 901 +--ro code? boolean 902 +--ro rest-of-header? boolean 904 Figure 10: Filtering Capabilities Subtree 906 4.3. YANG Module 908 This module uses the common YANG types defined in [RFC6991] and types 909 defined in [RFC8519]. 911 file "ietf-dots-data-channel@2019-05-09.yang" 912 module ietf-dots-data-channel { 913 yang-version 1.1; 914 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 915 prefix data-channel; 917 import ietf-inet-types { 918 prefix inet; 919 reference "Section 4 of RFC 6991"; 920 } 921 import ietf-access-control-list { 922 prefix ietf-acl; 923 reference 924 "RFC 8519: YANG Data Model for Network Access 925 Control Lists (ACLs)"; 926 } 927 import ietf-packet-fields { 928 prefix packet-fields; 929 reference 930 "RFC 8519: YANG Data Model for Network Access 931 Control Lists (ACLs)"; 932 } 934 organization 935 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 936 contact 937 "WG Web: 938 WG List: 940 Editor: Mohamed Boucadair 941 943 Editor: Konda, Tirumaleswar Reddy 944 946 Author: Jon Shallow 947 949 Author: Kaname Nishizuka 950 952 Author: Liang Xia 953 955 Author: Prashanth Patil 956 958 Author: Andrew Mortensen 959 961 Author: Nik Teague 962 "; 963 description 964 "This module contains YANG definition for configuring 965 aliases for resources and filtering rules using DOTS 966 data channel. 968 Copyright (c) 2019 IETF Trust and the persons identified as 969 authors of the code. All rights reserved. 971 Redistribution and use in source and binary forms, with or 972 without modification, is permitted pursuant to, and subject 973 to the license terms contained in, the Simplified BSD License 974 set forth in Section 4.c of the IETF Trust's Legal Provisions 975 Relating to IETF Documents 976 (http://trustee.ietf.org/license-info). 978 This version of this YANG module is part of RFC XXXX; see 979 the RFC itself for full legal notices."; 981 revision 2019-05-09 { 982 description 983 "Initial revision."; 984 reference 985 "RFC XXXX: Distributed Denial-of-Service Open Threat 986 Signaling (DOTS) Data Channel Specification"; 987 } 989 typedef activation-type { 990 type enumeration { 991 enum "activate-when-mitigating" { 992 value 1; 993 description 994 "The Access Control List (ACL) is installed only when 995 a mitigation is active for the DOTS client."; 996 } 997 enum "immediate" { 998 value 2; 999 description 1000 "The ACL is immediately activated."; 1001 } 1002 enum "deactivate" { 1003 value 3; 1004 description 1005 "The ACL is maintained by the DOTS server, but it is 1006 deactivated."; 1007 } 1008 } 1009 description 1010 "Indicates the activation type of an ACL."; 1011 } 1013 typedef operator { 1014 type bits { 1015 bit not { 1016 position 0; 1017 description 1018 "If set, logical negation of operation."; 1019 } 1020 bit match { 1021 position 1; 1022 description 1023 "Match bit. This is a bitwise match operation 1024 defined as '(data & value) == value'."; 1025 } 1026 bit any { 1027 position 3; 1028 description 1029 "Any bit. This is a match on any of the bits in 1030 bitmask. It evaluates to 'true' if any of the bits 1031 in the value mask are set in the data, 1032 i.e., '(data & value) != 0'."; 1033 } 1034 } 1035 description 1036 "Specifies how to apply the defined bitmask."; 1037 } 1039 grouping tcp-flags { 1040 leaf operator { 1041 type operator; 1042 default "match"; 1043 description 1044 "Specifies how to interpret the TCP flags."; 1045 } 1046 leaf bitmask { 1047 type uint16; 1048 mandatory true; 1049 description 1050 "The bitmask matches the last 4 bits of byte 12 1051 and byte 13 of the TCP header. For clarity, the 4 bits 1052 of byte 12 corresponding to the TCP data offset field 1053 are not included in any matching."; 1054 } 1055 description 1056 "Operations on TCP flags."; 1057 } 1059 typedef fragment-type { 1060 type bits { 1061 bit df { 1062 position 0; 1063 description 1064 "Don't fragment bit for IPv4. 1066 Must be set to 0 when it appears in an IPv6 filter."; 1067 } 1068 bit isf { 1069 position 1; 1070 description 1071 "Is a fragment."; 1072 } 1073 bit ff { 1074 position 2; 1075 description 1076 "First fragment."; 1077 } 1078 bit lf { 1079 position 3; 1080 description 1081 "Last fragment."; 1082 } 1083 } 1084 description 1085 "Different fragment types to match against."; 1086 } 1088 grouping target { 1089 description 1090 "Specifies the targets of the mitigation request."; 1091 leaf-list target-prefix { 1092 type inet:ip-prefix; 1093 description 1094 "IPv4 or IPv6 prefix identifying the target."; 1095 } 1096 list target-port-range { 1097 key "lower-port"; 1098 description 1099 "Port range. When only lower-port is 1100 present, it represents a single port number."; 1101 leaf lower-port { 1102 type inet:port-number; 1103 mandatory true; 1104 description 1105 "Lower port number of the port range."; 1106 } 1107 leaf upper-port { 1108 type inet:port-number; 1109 must '. >= ../lower-port' { 1110 error-message 1111 "The upper port number must be greater than 1112 or equal to the lower-port number."; 1113 } 1114 description 1115 "Upper port number of the port range."; 1116 } 1117 } 1118 leaf-list target-protocol { 1119 type uint8; 1120 description 1121 "Identifies the target protocol number. 1123 Values are taken from the IANA protocol registry: 1124 https://www.iana.org/assignments/protocol-numbers/ 1125 protocol-numbers.xhtml 1127 For example, 6 for TCP or 17 for UDP."; 1128 } 1129 leaf-list target-fqdn { 1130 type inet:domain-name; 1131 description 1132 "FQDN identifying the target."; 1133 } 1134 leaf-list target-uri { 1135 type inet:uri; 1136 description 1137 "URI identifying the target."; 1138 } 1139 } 1141 grouping fragment-fields { 1142 leaf operator { 1143 type operator; 1144 default "match"; 1145 description 1146 "Specifies how to interpret the fragment type."; 1147 } 1148 leaf type { 1149 type fragment-type; 1150 mandatory true; 1151 description 1152 "Indicates what fragment type to look for."; 1153 } 1154 description 1155 "Operations on fragment types."; 1156 } 1158 grouping aliases { 1159 description 1160 "Top level container for aliases."; 1161 list alias { 1162 key "name"; 1163 description 1164 "List of aliases."; 1165 leaf name { 1166 type string; 1167 description 1168 "The name of the alias."; 1169 } 1170 uses target; 1171 leaf pending-lifetime { 1172 type int32; 1173 units "minutes"; 1174 config false; 1175 description 1176 "Indicates the pending validity lifetime of the alias 1177 entry."; 1178 } 1179 } 1180 } 1182 grouping ports { 1183 choice source-port { 1184 container source-port-range-or-operator { 1185 uses packet-fields:port-range-or-operator; 1186 description 1187 "Source port definition."; 1188 } 1189 description 1190 "Choice of specifying the source port or referring to 1191 a group of source port numbers."; 1192 } 1193 choice destination-port { 1194 container destination-port-range-or-operator { 1195 uses packet-fields:port-range-or-operator; 1196 description 1197 "Destination port definition."; 1198 } 1199 description 1200 "Choice of specifying a destination port or referring 1201 to a group of destination port numbers."; 1202 } 1203 description 1204 "Choice of specifying a source or destination port numbers."; 1205 } 1207 grouping access-lists { 1208 description 1209 "Specifies the ordered set of Access Control Lists."; 1211 list acl { 1212 key "name"; 1213 ordered-by user; 1214 description 1215 "An ACL is an ordered list of Access Control Entries (ACE). 1216 Each ACE has a list of match criteria and a list of actions."; 1217 leaf name { 1218 type string { 1219 length "1..64"; 1220 } 1221 description 1222 "The name of the access list."; 1223 reference 1224 "RFC 8519: YANG Data Model for Network Access 1225 Control Lists (ACLs)"; 1226 } 1227 leaf type { 1228 type ietf-acl:acl-type; 1229 description 1230 "Type of access control list. Indicates the primary intended 1231 type of match criteria (e.g., IPv4, IPv6) used in the list 1232 instance."; 1233 reference 1234 "RFC 8519: YANG Data Model for Network Access 1235 Control Lists (ACLs)"; 1236 } 1237 leaf activation-type { 1238 type activation-type; 1239 default "activate-when-mitigating"; 1240 description 1241 "Indicates the activation type of an ACL. An ACL can be 1242 deactivated, installed immediately, or installed when 1243 a mitigation is active."; 1244 } 1245 leaf pending-lifetime { 1246 type int32; 1247 units "minutes"; 1248 config false; 1249 description 1250 "Indicates the pending validity lifetime of the ACL 1251 entry."; 1252 } 1253 container aces { 1254 description 1255 "The Access Control Entries container contains 1256 a list of ACEs."; 1257 list ace { 1258 key "name"; 1259 ordered-by user; 1260 description 1261 "List of access list entries."; 1262 leaf name { 1263 type string { 1264 length "1..64"; 1265 } 1266 description 1267 "A unique name identifying this ACE."; 1268 reference 1269 "RFC 8519: YANG Data Model for Network Access 1270 Control Lists (ACLs)"; 1271 } 1272 container matches { 1273 description 1274 "The rules in this set determine what fields will be 1275 matched upon before any action is taken on them. 1277 If no matches are defined in a particular container, 1278 then any packet will match that container. 1280 If no matches are specified at all in an ACE, then any 1281 packet will match the ACE."; 1282 reference 1283 "RFC 8519: YANG Data Model for Network Access 1284 Control Lists (ACLs)"; 1285 choice l3 { 1286 container ipv4 { 1287 when "derived-from(../../../../type, " 1288 + "'ietf-acl:ipv4-acl-type')"; 1289 uses packet-fields:acl-ip-header-fields; 1290 uses packet-fields:acl-ipv4-header-fields; 1291 container fragment { 1292 description 1293 "Indicates how to handle IPv4 fragments."; 1294 uses fragment-fields; 1295 } 1296 description 1297 "Rule set that matches IPv4 header."; 1298 } 1299 container ipv6 { 1300 when "derived-from(../../../../type, " 1301 + "'ietf-acl:ipv6-acl-type')"; 1302 uses packet-fields:acl-ip-header-fields; 1303 uses packet-fields:acl-ipv6-header-fields; 1304 container fragment { 1305 description 1306 "Indicates how to handle IPv6 fragments."; 1308 uses fragment-fields; 1309 } 1310 description 1311 "Rule set that matches IPv6 header."; 1312 } 1313 description 1314 "Either IPv4 or IPv6."; 1315 } 1316 choice l4 { 1317 container tcp { 1318 uses packet-fields:acl-tcp-header-fields; 1319 container flags-bitmask { 1320 description 1321 "Indicates how to handle TCP flags."; 1322 uses tcp-flags; 1323 } 1324 uses ports; 1325 description 1326 "Rule set that matches TCP header."; 1327 } 1328 container udp { 1329 uses packet-fields:acl-udp-header-fields; 1330 uses ports; 1331 description 1332 "Rule set that matches UDP header."; 1333 } 1334 container icmp { 1335 uses packet-fields:acl-icmp-header-fields; 1336 description 1337 "Rule set that matches ICMP/ICMPv6 header."; 1338 } 1339 description 1340 "Can be TCP, UDP, or ICMP/ICMPv6"; 1341 } 1342 } 1343 container actions { 1344 description 1345 "Definitions of action for this ACE."; 1346 leaf forwarding { 1347 type identityref { 1348 base ietf-acl:forwarding-action; 1349 } 1350 mandatory true; 1351 description 1352 "Specifies the forwarding action per ACE."; 1353 reference 1354 "RFC 8519: YANG Data Model for Network Access 1355 Control Lists (ACLs)"; 1357 } 1358 leaf rate-limit { 1359 when "../forwarding = 'ietf-acl:accept'" { 1360 description 1361 "Rate-limit is valid only when accept action is 1362 used."; 1363 } 1364 type decimal64 { 1365 fraction-digits 2; 1366 } 1367 units "bytes per second"; 1368 description 1369 "Specifies how to rate-limit the traffic."; 1370 } 1371 } 1372 container statistics { 1373 config false; 1374 description 1375 "Aggregate statistics."; 1376 uses ietf-acl:acl-counters; 1377 } 1378 } 1379 } 1380 } 1381 } 1383 container dots-data { 1384 description 1385 "Main container for DOTS data channel."; 1386 list dots-client { 1387 key "cuid"; 1388 description 1389 "List of DOTS clients."; 1390 leaf cuid { 1391 type string; 1392 description 1393 "A unique identifier that is generated by a DOTS client 1394 to prevent request collisions."; 1395 reference 1396 "RFC YYYY: Distributed Denial-of-Service Open Threat 1397 Signaling (DOTS) Signal Channel Specification"; 1398 } 1399 leaf cdid { 1400 type string; 1401 description 1402 "A client domain identifier conveyed by a 1403 server-domain DOTS gateway to a remote DOTS server."; 1404 reference 1405 "RFC YYYY: Distributed Denial-of-Service Open Threat 1406 Signaling (DOTS) Signal Channel Specification"; 1407 } 1408 container aliases { 1409 description 1410 "Set of aliases that are bound to a DOTS client."; 1411 uses aliases; 1412 } 1413 container acls { 1414 description 1415 "Access lists that are bound to a DOTS client."; 1416 uses access-lists; 1417 } 1418 } 1419 container capabilities { 1420 config false; 1421 description 1422 "Match capabilities"; 1423 leaf-list address-family { 1424 type enumeration { 1425 enum "ipv4" { 1426 description 1427 "IPv4 is supported."; 1428 } 1429 enum "ipv6" { 1430 description 1431 "IPv6 is supported."; 1432 } 1433 } 1434 description 1435 "Indicates the IP address families supported by 1436 the DOTS server."; 1437 } 1438 leaf-list forwarding-actions { 1439 type identityref { 1440 base ietf-acl:forwarding-action; 1441 } 1442 description 1443 "Supported forwarding action(s)."; 1444 } 1445 leaf rate-limit { 1446 type boolean; 1447 description 1448 "Support of rate-limit action."; 1449 } 1450 leaf-list transport-protocols { 1451 type uint8; 1452 description 1453 "Upper-layer protocol associated with a filtering rule. 1455 Values are taken from the IANA protocol registry: 1456 https://www.iana.org/assignments/protocol-numbers/ 1457 protocol-numbers.xhtml 1459 For example, this field contains 1 for ICMP, 6 for TCP 1460 17 for UDP, or 58 for ICMPv6."; 1461 } 1462 container ipv4 { 1463 description 1464 "Indicates IPv4 header fields that are supported to enforce 1465 ACLs."; 1466 leaf dscp { 1467 type boolean; 1468 description 1469 "Support of filtering based on Differentiated Services Code 1470 Point (DSCP)."; 1471 } 1472 leaf ecn { 1473 type boolean; 1474 description 1475 "Support of filtering based on Explicit Congestion 1476 Notification (ECN)."; 1477 } 1478 leaf length { 1479 type boolean; 1480 description 1481 "Support of filtering based on the Total Length."; 1482 } 1483 leaf ttl { 1484 type boolean; 1485 description 1486 "Support of filtering based on the Time to Live (TTL)."; 1487 } 1488 leaf protocol { 1489 type boolean; 1490 description 1491 "Support of filtering based on protocol field."; 1492 } 1493 leaf ihl { 1494 type boolean; 1495 description 1496 "Support of filtering based on the Internet Header 1497 Length (IHL)."; 1498 } 1499 leaf flags { 1500 type boolean; 1501 description 1502 "Support of filtering based on the 'flags'."; 1503 } 1504 leaf offset { 1505 type boolean; 1506 description 1507 "Support of filtering based on the 'offset'."; 1508 } 1509 leaf identification { 1510 type boolean; 1511 description 1512 "Support of filtering based on the 'identification'."; 1513 } 1514 leaf source-prefix { 1515 type boolean; 1516 description 1517 "Support of filtering based on the source prefix."; 1518 } 1519 leaf destination-prefix { 1520 type boolean; 1521 description 1522 "Support of filtering based on the destination prefix."; 1523 } 1524 leaf fragment { 1525 type boolean; 1526 description 1527 "Indicates the capability of a DOTS server to 1528 enforce filters on IPv4 fragments. That is, the match 1529 functionality based on the Layer 3 'fragment' clause 1530 is supported."; 1531 } 1532 } 1533 container ipv6 { 1534 description 1535 "Indicates IPv6 header fields that are supported to enforce 1536 ACLs."; 1537 leaf dscp { 1538 type boolean; 1539 description 1540 "Support of filtering based on DSCP."; 1541 } 1542 leaf ecn { 1543 type boolean; 1544 description 1545 "Support of filtering based on ECN."; 1546 } 1547 leaf length { 1548 type boolean; 1549 description 1550 "Support of filtering based on the Payload Length."; 1551 } 1552 leaf hoplimit { 1553 type boolean; 1554 description 1555 "Support of filtering based on the Hop Limit."; 1556 } 1557 leaf protocol { 1558 type boolean; 1559 description 1560 "Support of filtering based on the Next Header field."; 1561 } 1562 leaf destination-prefix { 1563 type boolean; 1564 description 1565 "Support of filtering based on the destination prefix."; 1566 } 1567 leaf source-prefix { 1568 type boolean; 1569 description 1570 "Support of filtering based on the source prefix."; 1571 } 1572 leaf flow-label { 1573 type boolean; 1574 description 1575 "Support of filtering based on the Flow label."; 1576 } 1577 leaf fragment { 1578 type boolean; 1579 description 1580 "Indicates the capability of a DOTS server to 1581 enforce filters on IPv6 fragments."; 1582 } 1583 } 1584 container tcp { 1585 description 1586 "Set of TCP fields that are supported by the DOTS server 1587 to enforce filters."; 1588 leaf sequence-number { 1589 type boolean; 1590 description 1591 "Support of filtering based on the TCP sequence number."; 1592 } 1593 leaf acknowledgement-number { 1594 type boolean; 1595 description 1596 "Support of filtering based on the TCP acknowledgement 1597 number."; 1598 } 1599 leaf data-offset { 1600 type boolean; 1601 description 1602 "Support of filtering based on the TCP data-offset."; 1603 } 1604 leaf reserved { 1605 type boolean; 1606 description 1607 "Support of filtering based on the TCP reserved field."; 1608 } 1609 leaf flags { 1610 type boolean; 1611 description 1612 "Support of filtering, as defined in RFC 8519, based 1613 on the TCP flags."; 1614 } 1615 leaf window-size { 1616 type boolean; 1617 description 1618 "Support of filtering based on the TCP window size."; 1619 } 1620 leaf urgent-pointer { 1621 type boolean; 1622 description 1623 "Support of filtering based on the TCP urgent pointer."; 1624 } 1625 leaf options { 1626 type boolean; 1627 description 1628 "Support of filtering based on the TCP options."; 1629 } 1630 leaf flags-bitmask { 1631 type boolean; 1632 description 1633 "Support of filtering based on the TCP flags bitmask."; 1634 } 1635 leaf source-port { 1636 type boolean; 1637 description 1638 "Support of filtering based on the source port number."; 1639 } 1640 leaf destination-port { 1641 type boolean; 1642 description 1643 "Support of filtering based on the destination port 1644 number."; 1646 } 1647 leaf port-range { 1648 type boolean; 1649 description 1650 "Support of filtering based on a port range. 1652 This includes filtering based on a source port range, 1653 destination port range, or both. All operators 1654 (i.e, less than or equal to, greater than or equal to, 1655 equal to, and not equal to) are supported."; 1656 } 1657 } 1658 container udp { 1659 description 1660 "Set of UDP fields that are supported by the DOTS server 1661 to enforce filters."; 1662 leaf length { 1663 type boolean; 1664 description 1665 "Support of filtering based on the UDP length."; 1666 } 1667 leaf source-port { 1668 type boolean; 1669 description 1670 "Support of filtering based on the source port number."; 1671 } 1672 leaf destination-port { 1673 type boolean; 1674 description 1675 "Support of filtering based on the destination port 1676 number."; 1677 } 1678 leaf port-range { 1679 type boolean; 1680 description 1681 "Support of filtering based on a port range. 1683 This includes filtering based on a source port range, 1684 destination port range, or both. All operators 1685 (i.e, less than or equal, greater than or equal, equal to, 1686 and not equal to) are supported."; 1687 } 1688 } 1689 container icmp { 1690 description 1691 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1692 server to enforce filters."; 1693 leaf type { 1694 type boolean; 1695 description 1696 "Support of filtering based on the ICMP/ICMPv6 type."; 1697 } 1698 leaf code { 1699 type boolean; 1700 description 1701 "Support of filtering based on the ICMP/ICMPv6 code."; 1702 } 1703 leaf rest-of-header { 1704 type boolean; 1705 description 1706 "Support of filtering based on the ICMP four-bytes 1707 field / the ICMPv6 message body."; 1708 } 1709 } 1710 } 1711 } 1712 } 1713 1715 5. Managing DOTS Clients 1717 5.1. Registering DOTS Clients 1719 In order to make use of DOTS data channel, a DOTS client MUST 1720 register to its DOTS server(s) by creating a DOTS client ('dots- 1721 client') resource. To that aim, DOTS clients SHOULD send a POST 1722 request (shown in Figure 11). 1724 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1725 Host: {host}:{port} 1726 Content-Type: application/yang-data+json 1728 { 1729 "ietf-dots-data-channel:dots-client": [ 1730 { 1731 "cuid": "string" 1732 } 1733 ] 1734 } 1736 Figure 11: POST to Register Schema 1738 The 'cuid' (client unique identifier) parameter is described below: 1740 cuid: A globally unique identifier that is meant to prevent 1741 collisions among DOTS clients. This attribute has the same 1742 meaning, syntax, and processing rules as the 'cuid' attribute 1743 defined in [I-D.ietf-dots-signal-channel]. 1745 DOTS clients MUST use the same 'cuid' for both signal and data 1746 channels. 1748 This is a mandatory attribute. 1750 In deployments where server-domain DOTS gateways are enabled, 1751 identity information about the origin source client domain SHOULD be 1752 supplied to the DOTS server. That information is meant to assist the 1753 DOTS server to enforce some policies. These policies can be enforced 1754 per-client, per-client domain, or both. Figure 12 shows a schema 1755 example of a request relayed by a server-domain DOTS gateway. 1757 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1758 Host: {host}:{port} 1759 Content-Type: application/yang-data+json 1761 { 1762 "ietf-dots-data-channel:dots-client": [ 1763 { 1764 "cuid": "string", 1765 "cdid": "string" 1766 } 1767 ] 1768 } 1770 Figure 12: POST to Register Schema (via a Server-Domain DOTS Gateway) 1772 A server-domain DOTS gateway SHOULD add the following attribute: 1774 cdid: This attribute has the same meaning, syntax, and processing 1775 rules as the 'cdid' attribute defined in 1776 [I-D.ietf-dots-signal-channel]. 1778 In deployments where server-domain DOTS gateways are enabled, 1779 'cdid' does not need to be inserted when relaying DOTS methods to 1780 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1781 servers are responsible for maintaining the association between 1782 'cdid' and 'cuid' for policy enforcement purposes. 1784 This is an optional attribute. 1786 A request example to create a 'dots-client' resource is depicted in 1787 Figure 13. This request is relayed by a server-domain DOTS gateway 1788 as hinted by the presence of the 'cdid' attribute. 1790 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1791 Host: example.com 1792 Content-Type: application/yang-data+json 1794 { 1795 "ietf-dots-data-channel:dots-client": [ 1796 { 1797 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1798 "cdid": "7eeaf349529eb55ed50113" 1799 } 1800 ] 1801 } 1803 Figure 13: POST to Register (DOTS gateway) 1805 As a reminder, DOTS gateways may rewrite the 'cuid' used by peer DOTS 1806 clients (Section 4.4.1 of [I-D.ietf-dots-signal-channel]). 1808 DOTS servers can identify the DOTS client domain using the 'cdid' 1809 parameter or using the client's DNS name specified in the Subject 1810 Alternative Name extension's dNSName type in the client certificate 1811 [RFC6125]. 1813 DOTS servers MUST limit the number of 'dots-client' resources to be 1814 created by the same DOTS client to 1 per request. Requests with 1815 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1816 To that aim, the DOTS server MUST rely on the same procedure to 1817 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1818 [I-D.ietf-dots-signal-channel]. 1820 The DOTS server indicates the result of processing the POST request 1821 using status-line codes. Status codes in the range "2xx" codes are 1822 success, "4xx" codes are some sort of invalid requests and "5xx" 1823 codes are returned if the DOTS server has erred or is incapable of 1824 accepting the creation of the 'dots-client' resource. In particular, 1826 o "201 Created" status-line is returned in the response, if the DOTS 1827 server has accepted the request. 1829 o "400 Bad Request" status-line is returned by the DOTS server, if 1830 the request does not include a 'cuid' parameter. The error-tag 1831 "missing-attribute" is used in this case. 1833 o "409 Conflict" status-line is returned to the requesting DOTS 1834 client, if the data resource already exists. The error-tag 1835 "resource-denied" is used in this case. 1837 Once a DOTS client registers itself to a DOTS server, it can 1838 create/delete/retrieve aliases (Section 6) and filtering rules 1839 (Section 7). 1841 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1842 register a DOTS client within the DOTS server. An example is shown 1843 in Figure 14. 1845 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1846 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1847 Host: example.com 1848 Content-Type: application/yang-data+json 1850 { 1851 "ietf-dots-data-channel:dots-client": [ 1852 { 1853 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1854 } 1855 ] 1856 } 1858 Figure 14: PUT to Register 1860 The DOTS gateway that inserted a 'cdid' in a PUT request MUST strip 1861 the 'cdid' parameter in the corresponding response before forwarding 1862 the response to the DOTS client. 1864 5.2. Unregistering DOTS Clients 1866 A DOTS client de-registers from its DOTS server(s) by deleting the 1867 'cuid' resource(s). Resources bound to this DOTS client will be 1868 deleted by the DOTS server. An example of a de-register request is 1869 shown in Figure 15. 1871 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1872 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1873 Host: example.com 1875 Figure 15: De-register a DOTS Client 1877 6. Managing DOTS Aliases 1879 The following sub-sections define means for a DOTS client to create 1880 aliases (Section 6.1), retrieve one or a list of aliases 1881 (Section 6.2), and delete an alias (Section 6.3). 1883 6.1. Create Aliases 1885 A POST or PUT request is used by a DOTS client to create aliases, for 1886 resources for which a mitigation may be requested. Such aliases may 1887 be used in subsequent DOTS signal channel exchanges to refer more 1888 efficiently to the resources under attack. 1890 DOTS clients within the same domain can create different aliases for 1891 the same resource. 1893 The structure of POST requests used to create aliases is shown in 1894 Figure 16. 1896 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1897 /dots-client=cuid HTTP/1.1 1898 Host: {host}:{port} 1899 Content-Type: application/yang-data+json 1901 { 1902 "ietf-dots-data-channel:aliases": { 1903 "alias": [ 1904 { 1905 "name": "string", 1906 "target-prefix": [ 1907 "string" 1908 ], 1909 "target-port-range": [ 1910 { 1911 "lower-port": integer, 1912 "upper-port": integer 1913 } 1914 ], 1915 "target-protocol": [ 1916 integer 1917 ], 1918 "target-fqdn": [ 1919 "string" 1920 ], 1921 "target-uri": [ 1922 "string" 1923 ] 1924 } 1925 ] 1926 } 1927 } 1929 Figure 16: POST to Create Aliases (Request Schema) 1931 The parameters are described below: 1933 name: Name of the alias. 1935 This is a mandatory attribute. 1937 target-prefix: Prefixes are separated by commas. Prefixes are 1938 represented using Classless Inter-domain Routing (CIDR) notation 1939 [RFC4632]. As a reminder, the prefix length must be less than or 1940 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1942 The prefix list MUST NOT include broadcast, loopback, or multicast 1943 addresses. These addresses are considered as invalid values. In 1944 addition, the DOTS server MUST validate that these prefixes are 1945 within the scope of the DOTS client domain. Other validation 1946 checks may be supported by DOTS servers. 1948 This is an optional attribute. 1950 target-port-range: A range of port numbers. 1952 The port range is defined by two bounds, a lower port number 1953 (lower-port) and an upper port number (upper-port). The range is 1954 considered to include both the lower and upper bounds. 1956 When only 'lower-port' is present, it represents a single port 1957 number. 1959 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1960 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1961 [RFC4340], the range of port numbers can be, for example, 1962 1024-65535. 1964 This is an optional attribute. 1966 target-protocol: A list of protocols. Values are taken from the 1967 IANA protocol registry [proto_numbers]. 1969 If 'target-protocol' is not specified, then the request applies to 1970 any protocol. 1972 This is an optional attribute. 1974 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 1975 identifying resources under attack [RFC8499]. 1977 How a name is passed to an underlying name resolution library is 1978 implementation- and deployment-specific. Nevertheless, once the 1979 name is resolved into one or multiple IP addresses, DOTS servers 1980 MUST apply the same validation checks as those for 'target- 1981 prefix'. 1983 The use of FQDNs may be suboptimal because it does not guarantee 1984 that the DOTS server will resolve a name to the same IP addresses 1985 that the DOTS client does. 1987 This is an optional attribute. 1989 target-uri: A list of Uniform Resource Identifiers (URIs) 1990 [RFC3986]. 1992 The same validation checks used for 'target-fqdn' MUST be followed 1993 by DOTS servers to validate a target URI. 1995 This is an optional attribute. 1997 In POST or PUT requests, at least one of the 'target-prefix', 1998 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1999 agents can safely ignore Vendor-Specific parameters they don't 2000 understand. 2002 If more than one 'target-*' scope types (e.g., 'target-prefix' and 2003 'target-fqdn' or 'target-fqdn' and 'target-uri') are included in a 2004 POST or PUT request, the DOTS server binds all resulting IP 2005 addresses/prefixes to the same resource. 2007 Figure 17 shows a POST request to create an alias called "https1" for 2008 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 2009 listening on TCP port number 443. 2011 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2012 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2013 Host: www.example.com 2014 Content-Type: application/yang-data+json 2016 { 2017 "ietf-dots-data-channel:aliases": { 2018 "alias": [ 2019 { 2020 "name": "https1", 2021 "target-protocol": [ 2022 6 2023 ], 2024 "target-prefix": [ 2025 "2001:db8:6401::1/128", 2026 "2001:db8:6401::2/128" 2027 ], 2028 "target-port-range": [ 2029 { 2030 "lower-port": 443 2031 } 2032 ] 2033 } 2034 ] 2035 } 2036 } 2038 Figure 17: Example of a POST to Create an Alias 2040 "201 Created" status-line MUST be returned in the response if the 2041 DOTS server has accepted the alias. 2043 "409 Conflict" status-line MUST be returned to the requesting DOTS 2044 client, if the request is conflicting with an existing alias name. 2045 The error-tag "resource-denied" is used in this case. 2047 If the request is missing a mandatory attribute or it contains an 2048 invalid or unknown parameter, "400 Bad Request" status-line MUST be 2049 returned by the DOTS server. The error-tag is set to "missing- 2050 attribute", "invalid-value", or "unknown-element" as a function of 2051 the encountered error. 2053 If the request is received via a server-domain DOTS gateway, but the 2054 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2055 is expected to be supplied, the DOTS server MUST reply with "403 2056 Forbidden" status-line and the error-tag "access-denied". Upon 2057 receipt of this message, the DOTS client MUST register (Section 5). 2059 A DOTS client uses the PUT request to modify the aliases in the DOTS 2060 server. In particular, a DOTS client MUST update its alias entries 2061 upon change of the prefix indicated in the 'target-prefix'. 2063 A DOTS server MUST maintain an alias for at least 10080 minutes (1 2064 week). If no refresh request is seen from the DOTS client, the DOTS 2065 server removes expired entries. 2067 6.2. Retrieve Installed Aliases 2069 A GET request is used to retrieve one or all installed aliases by a 2070 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 2071 'name' is included in the request, this is an indication that the 2072 request is about retrieving all aliases instantiated by the DOTS 2073 client. 2075 Figure 18 shows an example to retrieve all the aliases that were 2076 instantiated by the requesting DOTS client. The "content" query 2077 parameter and its permitted values are defined in Section 4.8.1 of 2078 [RFC8040]. 2080 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2081 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2082 /aliases?content=all HTTP/1.1 2083 Host: example.com 2084 Accept: application/yang-data+json 2086 Figure 18: GET to Retrieve All Installed Aliases 2088 Figure 19 shows an example of the response message body that includes 2089 all the aliases that are maintained by the DOTS server for the DOTS 2090 client identified by the 'cuid' parameter. 2092 { 2093 "ietf-dots-data-channel:aliases": { 2094 "alias": [ 2095 { 2096 "name": "Server1", 2097 "target-protocol": [ 2098 6 2099 ], 2100 "target-prefix": [ 2101 "2001:db8:6401::1/128", 2102 "2001:db8:6401::2/128" 2103 ], 2104 "target-port-range": [ 2105 { 2106 "lower-port": 443 2107 } 2108 ], 2109 "pending-lifetime": 3596 2110 }, 2111 { 2112 "name": "Server2", 2113 "target-protocol": [ 2114 6 2115 ], 2116 "target-prefix": [ 2117 "2001:db8:6401::10/128", 2118 "2001:db8:6401::20/128" 2119 ], 2120 "target-port-range": [ 2121 { 2122 "lower-port": 80 2123 } 2124 ], 2125 "pending-lifetime": 9869 2126 } 2127 ] 2128 } 2129 } 2131 Figure 19: An Example of Response Body Listing All Installed Aliases 2133 Figure 20 shows an example of a GET request to retrieve the alias 2134 "Server2" that was instantiated by the DOTS client. 2136 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2137 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2138 /aliases/alias=Server2?content=all HTTP/1.1 2139 Host: example.com 2140 Accept: application/yang-data+json 2142 Figure 20: GET to Retrieve an Alias 2144 If an alias name ('name') is included in the request, but the DOTS 2145 server does not find that alias name for this DOTS client in its 2146 configuration data, it MUST respond with a "404 Not Found" status- 2147 line. 2149 6.3. Delete Aliases 2151 A DELETE request is used to delete an alias maintained by a DOTS 2152 server. 2154 If the DOTS server does not find the alias name, conveyed in the 2155 DELETE request, in its configuration data for this DOTS client, it 2156 MUST respond with a "404 Not Found" status-line. 2158 The DOTS server successfully acknowledges a DOTS client's request to 2159 remove the alias using "204 No Content" status-line in the response. 2161 Figure 21 shows an example of a request to delete an alias. 2163 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2164 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2165 /aliases/alias=Server1 HTTP/1.1 2166 Host: example.com 2168 Figure 21: Delete an Alias 2170 7. Managing DOTS Filtering Rules 2172 The following sub-sections define means for a DOTS client to retrieve 2173 DOTS filtering capabilities (Section 7.1), create filtering rules 2174 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2175 delete a filtering rule (Section 7.4). 2177 7.1. Retrieve DOTS Filtering Capabilities 2179 A DOTS client MAY send a GET request to retrieve the filtering 2180 capabilities supported by a DOTS server. Figure 22 shows an example 2181 of such request. 2183 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2184 /capabilities HTTP/1.1 2185 Host: example.com 2186 Accept: application/yang-data+json 2188 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2190 A DOTS client which issued a GET request to retrieve the filtering 2191 capabilities supported by its DOTS server, SHOULD NOT request for 2192 filtering actions that are not supported by that DOTS server. 2194 Figure 23 shows an example of a response body received from a DOTS 2195 server which supports: 2197 o IPv4, IPv6, TCP, UDP, ICMP, and ICMPv6 mandatory match criteria 2198 listed in Section 4.2. 2200 o 'accept', 'drop', and 'rate-limit' actions. 2202 { 2203 "ietf-dots-data-channel:capabilities": { 2204 "address-family": ["ipv4", "ipv6"], 2205 "forwarding-actions": ["drop", "accept"], 2206 "rate-limit": true, 2207 "transport-protocols": [1, 6, 17, 58], 2208 "ipv4": { 2209 "length": true, 2210 "protocol": true, 2211 "destination-prefix": true, 2212 "source-prefix": true, 2213 "fragment": true 2214 }, 2215 "ipv6": { 2216 "length": true, 2217 "protocol": true, 2218 "destination-prefix": true, 2219 "source-prefix": true, 2220 "fragment": true 2221 }, 2222 "tcp": { 2223 "flags-bitmask": true, 2224 "source-port": true, 2225 "destination-port": true, 2226 "port-range": true 2227 }, 2228 "udp": { 2229 "length": true, 2230 "source-port": true, 2231 "destination-port": true, 2232 "port-range": true 2233 }, 2234 "icmp": { 2235 "type": true, 2236 "code": true 2237 } 2238 } 2239 } 2241 Figure 23: Reply to a GET Request with Filtering Capabilities 2242 (Message Body) 2244 7.2. Install Filtering Rules 2246 A POST or PUT request is used by a DOTS client to communicate 2247 filtering rules to a DOTS server. 2249 Figure 24 shows a POST request example to block traffic from 2250 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2251 discussed in Appendix A. 2253 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2254 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2255 Host: example.com 2256 Content-Type: application/yang-data+json 2258 { 2259 "ietf-dots-data-channel:acls": { 2260 "acl": [ 2261 { 2262 "name": "sample-ipv4-acl", 2263 "type": "ipv4-acl-type", 2264 "activation-type": "activate-when-mitigating", 2265 "aces": { 2266 "ace": [ 2267 { 2268 "name": "rule1", 2269 "matches": { 2270 "ipv4": { 2271 "destination-ipv4-network": "198.51.100.0/24", 2272 "source-ipv4-network": "192.0.2.0/24" 2273 } 2274 }, 2275 "actions": { 2276 "forwarding": "drop" 2277 } 2278 } 2279 ] 2280 } 2281 } 2282 ] 2283 } 2284 } 2286 Figure 24: POST to Install Filtering Rules 2288 The meaning of these parameters is as follows: 2290 name: The name of the access list. 2292 This is a mandatory attribute. 2294 type: Indicates the primary intended type of match criteria (e.g., 2295 IPv4, IPv6). It is set to 'ipv4-acl-type' in the example of 2296 Figure 24. 2298 This is an optional attribute. 2300 activation-type: Indicates whether an ACL has to be activated 2301 (immediately or during mitigation time) or instantiated without 2302 being activated (deactivated). Deactivated ACLs can be activated 2303 using a variety of means such as manual configuration on a DOTS 2304 server or using the DOTS data channel. 2306 If this attribute is not provided, the DOTS server MUST use 2307 'activate-when-mitigating' as default value. 2309 When a mitigation is in progress, the DOTS server MUST only 2310 activate 'activate-when-mitigating' filters that are bound to the 2311 DOTS client that triggered the mitigation. 2313 This is an optional attribute. 2315 matches: Define criteria used to identify a flow on which to apply 2316 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2317 The detailed match parameters are specified in Section 4. 2319 In the example depicted in Figure 24, an IPv4 matching criteria is 2320 used. 2322 This is an optional attribute. 2324 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2325 MUST validate that these prefixes are within the scope of the DOTS 2326 client domain. Other validation checks may be supported by DOTS 2327 servers. If this attribute is not provided, the DOTS server 2328 enforces the ACL on any destination IP address that belong to the 2329 DOTS client domain. 2331 This is a mandatory attribute in requests with an 'activation- 2332 type' set to 'immediate'. 2334 source-ipv4-network: The source IPv4 prefix. 2336 This is an optional attribute. 2338 actions: Actions in the forwarding ACL category can be "drop" or 2339 "accept". The "accept" action is used to accept-list traffic. 2340 The "drop" action is used to drop-list traffic. 2342 Accepted traffic may be subject to "rate-limit"; the allowed 2343 traffic rate is represented in bytes per second. This unit is the 2344 same as the one used for "traffic-rate" in [RFC5575]. 2346 This is a mandatory attribute. 2348 The DOTS server indicates the result of processing the POST request 2349 using the status-line. Concretely, "201 Created" status-line MUST be 2350 returned in the response if the DOTS server has accepted the 2351 filtering rules. If the request is missing a mandatory attribute or 2352 contains an invalid or unknown parameter (e.g., a match field not 2353 supported by the DOTS server), "400 Bad Request" status-line MUST be 2354 returned by the DOTS server in the response. The error-tag is set to 2355 "missing-attribute", "invalid-value", or "unknown-element" as a 2356 function of the encountered error. 2358 If the request is received via a server-domain DOTS gateway, but the 2359 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2360 is expected to be supplied, the DOTS server MUST reply with "403 2361 Forbidden" status-line and the error-tag "access-denied". Upon 2362 receipt of this message, the DOTS client MUST register (Figure 11). 2364 If the request is conflicting with an existing filtering installed by 2365 another DOTS client of the domain, absent any local policy, the DOTS 2366 server returns "409 Conflict" status-line to the requesting DOTS 2367 client. The error-tag "resource-denied" is used in this case. 2369 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2370 to specify how an access control entry is inserted within an ACL and 2371 how an ACL is inserted within an ACL set. 2373 The DOTS client uses the PUT request to modify its filtering rules 2374 maintained by the DOTS server. In particular, a DOTS client MUST 2375 update its filtering entries upon change of the destination-prefix. 2376 How such change is detected is out of scope. 2378 A DOTS server MUST maintain a filtering rule for at least 10080 2379 minutes (1 week). If no refresh request is seen from the DOTS 2380 client, the DOTS server removes expired entries. Typically, a 2381 refresh request is a PUT request which echoes the content of a 2382 response to a GET request with all of the read-only parameters 2383 stripped out (e.g., pending-lifetime). 2385 7.3. Retrieve Installed Filtering Rules 2387 A DOTS client periodically queries its DOTS server to check the 2388 counters for installed filtering rules. A GET request is used to 2389 retrieve filtering rules from a DOTS server. In order to indicate 2390 which type of data is requested in a GET request, the DOTS client 2391 sets adequately the "content" query parameter. 2393 If the DOTS server does not find the access list name conveyed in the 2394 GET request in its configuration data for this DOTS client, it 2395 responds with a "404 Not Found" status-line. 2397 In order to illustrate the intended behavior, consider the example 2398 depicted in Figure 25. In reference to this example, the DOTS client 2399 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2401 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2402 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2403 /acl=test-acl-ipv6-udp HTTP/1.1 2404 Host: example.com 2405 Content-Type: application/yang-data+json 2407 { 2408 "ietf-dots-data-channel:acls": { 2409 "acl": [ 2410 { 2411 "name": "test-acl-ipv6-udp", 2412 "type": "ipv6-acl-type", 2413 "activation-type": "immediate", 2414 "aces": { 2415 "ace": [ 2416 { 2417 "name": "my-test-ace", 2418 "matches": { 2419 "ipv6": { 2420 "destination-ipv6-network": "2001:db8:6401::2/127", 2421 "source-ipv6-network": "2001:db8:1234::/96", 2422 "protocol": 17, 2423 "flow-label": 10000 2424 }, 2425 "udp": { 2426 "source-port": { 2427 "operator": "lte", 2428 "port": 80 2429 }, 2430 "destination-port": { 2431 "operator": "neq", 2432 "port": 1010 2433 } 2434 } 2435 }, 2436 "actions": { 2437 "forwarding": "accept" 2438 } 2439 } 2440 ] 2441 } 2442 } 2443 ] 2444 } 2445 } 2447 Figure 25: Example of a PUT Request to Create a Filtering 2449 The peer DOTS server follows the procedure specified in Section 7.2 2450 to process the request. We consider in the following that a positive 2451 response is sent back to the requesting DOTS client to confirm that 2452 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2453 server. 2455 The DOTS client can issue a GET request to retrieve all its filtering 2456 rules and the number of matches for the installed filtering rules as 2457 illustrated in Figure 26. The "content" query parameter is set to 2458 'all'. The message body of the response to this GET request is shown 2459 in Figure 27. 2461 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2462 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2463 /acls?content=all HTTP/1.1 2464 Host: example.com 2465 Accept: application/yang-data+json 2467 Figure 26: Retrieve the Configuration Data and State Data for the 2468 Filtering Rules (GET Request) 2470 { 2471 "ietf-dots-data-channel:acls": { 2472 "acl": [ 2473 { 2474 "name": "test-acl-ipv6-udp", 2475 "type": "ipv6-acl-type", 2476 "activation-type": "immediate", 2477 "pending-lifetime":9080, 2478 "aces": { 2479 "ace": [ 2480 { 2481 "name": "my-test-ace", 2482 "matches": { 2483 "ipv6": { 2484 "destination-ipv6-network": "2001:db8:6401::2/127", 2485 "source-ipv6-network": "2001:db8:1234::/96", 2486 "protocol": 17, 2487 "flow-label": 10000 2488 }, 2489 "udp": { 2490 "source-port": { 2491 "operator": "lte", 2492 "port": 80 2493 }, 2494 "destination-port": { 2495 "operator": "neq", 2496 "port": 1010 2497 } 2498 } 2499 }, 2500 "actions": { 2501 "forwarding": "accept" 2502 } 2503 } 2504 ] 2505 } 2506 } 2507 ] 2508 } 2509 } 2511 Figure 27: Retrieve the Configuration Data and State Data for the 2512 Filtering Rules (Response Message Body) 2514 Also, a DOTS client can issue a GET request to retrieve only 2515 configuration data related to an ACL as shown in Figure 28. It does 2516 so by setting the "content" query parameter to 'config'. 2518 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2519 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2520 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2521 Host: example.com 2522 Accept: application/yang-data+json 2524 Figure 28: Retrieve the Configuration Data for a Filtering Rule (GET 2525 Request) 2527 A response to this GET request is shown in Figure 29. 2529 { 2530 "ietf-dots-data-channel:acls": { 2531 "acl": [ 2532 { 2533 "name": "test-acl-ipv6-udp", 2534 "type": "ipv6-acl-type", 2535 "activation-type": "immediate", 2536 "aces": { 2537 "ace": [ 2538 { 2539 "name": "my-test-ace", 2540 "matches": { 2541 "ipv6": { 2542 "destination-ipv6-network": "2001:db8:6401::2/127", 2543 "source-ipv6-network": "2001:db8:1234::/96", 2544 "protocol": 17, 2545 "flow-label": 10000 2546 }, 2547 "udp": { 2548 "source-port": { 2549 "operator": "lte", 2550 "port": 80 2551 }, 2552 "destination-port": { 2553 "operator": "neq", 2554 "port": 1010 2555 } 2556 } 2557 }, 2558 "actions": { 2559 "forwarding": "accept" 2560 } 2561 } 2562 ] 2563 } 2564 } 2565 ] 2566 } 2567 } 2569 Figure 29: Retrieve the Configuration Data for a Filtering Rule 2570 (Response Message Body) 2572 A DOTS client can also issue a GET request with a "content" query 2573 parameter set to 'non-config' to exclusively retrieve non- 2574 configuration data bound to a given ACL as shown in Figure 30. A 2575 response to this GET request is shown in Figure 31. 2577 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2578 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2579 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2580 Host: example.com 2581 Accept: application/yang-data+json 2583 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule 2584 (GET Request) 2586 { 2587 "ietf-dots-data-channel:acls": { 2588 "acl": [ 2589 { 2590 "name": "test-acl-ipv6-udp", 2591 "pending-lifetime": 8000, 2592 "aces": { 2593 "ace": [ 2594 { 2595 "name": "my-test-ace" 2596 } 2597 ] 2598 } 2599 } 2600 ] 2601 } 2602 } 2604 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule 2605 (Response Message Body) 2607 7.4. Remove Filtering Rules 2609 A DELETE request is used by a DOTS client to delete filtering rules 2610 from a DOTS server. 2612 If the DOTS server does not find the access list name carried in the 2613 DELETE request in its configuration data for this DOTS client, it 2614 MUST respond with a "404 Not Found" status-line. The DOTS server 2615 successfully acknowledges a DOTS client's request to withdraw the 2616 filtering rules using "204 No Content" status-line, and removes the 2617 filtering rules accordingly. 2619 Figure 32 shows an example of a request to remove the IPv4 ACL 2620 "sample-ipv4-acl" created in Section 7.2. 2622 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2623 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2624 /acl=sample-ipv4-acl HTTP/1.1 2625 Host: example.com 2627 Figure 32: Remove a Filtering Rule (DELETE Request) 2629 Figure 33 shows an example of a response received from the DOTS 2630 server to confirm the deletion of "sample-ipv4-acl". 2632 HTTP/1.1 204 No Content 2633 Server: Apache 2634 Date: Fri, 27 Jul 2018 10:05:15 GMT 2635 Cache-Control: no-cache 2636 Content-Type: application/yang-data+json 2637 Content-Length: 0 2638 Connection: Keep-Alive 2640 Figure 33: Remove a Filtering Rule (Response) 2642 8. Operational Considerations 2644 The following operational considerations should be taken into 2645 account: 2647 o DOTS servers MUST NOT enable both DOTS data channel and direct 2648 configuration, to avoid race conditions and inconsistent 2649 configurations arising from simultaneous updates from multiple 2650 sources. 2652 o DOTS agents SHOULD enable the DOTS data channel to configure 2653 aliases and ACLs, and only use direct configuration as a stop-gap 2654 mechanism to test DOTS signal channel with aliases and ACLs. 2655 Further, direct configuration SHOULD only be used when the on-path 2656 DOTS agents are within the same domain. 2658 o If a DOTS server has enabled direct configuration, it can reject 2659 the DOTS data channel connection using hard ICMP error [RFC1122] 2660 or RST (Reset) bit in the TCP header or reject the RESTCONF 2661 request using an error response containing a "503 Service 2662 Unavailable" status-line. 2664 9. IANA Considerations 2666 This document requests IANA to register the following URI in the "ns" 2667 subregistry within the "IETF XML Registry" [RFC3688]: 2669 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2670 Registrant Contact: The IESG. 2671 XML: N/A; the requested URI is an XML namespace. 2673 This document requests IANA to register the following YANG module in 2674 the "YANG Module Names" subregistry [RFC7950] within the "YANG 2675 Parameters" registry. 2677 Name: ietf-dots-data-channel 2678 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2679 Prefix: data-channel 2680 Reference: RFC XXXX 2682 This module is not maintained by IANA. 2684 10. Security Considerations 2686 RESTCONF security considerations are discussed in [RFC8040]. In 2687 particular, DOTS agents MUST follow the security recommendations in 2688 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2689 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2690 [I-D.ietf-dots-signal-channel]. 2692 Authenticated encryption MUST be used for data confidentiality and 2693 message integrity. The interaction between the DOTS agents requires 2694 Transport Layer Security (TLS) with a cipher suite offering 2695 confidentiality protection and the guidance given in [RFC7525] MUST 2696 be followed to avoid attacks on TLS. 2698 The installation of drop- or accept-list rules using RESTCONF over 2699 TLS reveals the attacker IP addresses and legitimate IP addresses 2700 only to the DOTS server trusted by the DOTS client. The secure 2701 communication channel between DOTS agents provides privacy and 2702 prevents a network eavesdropper from directly gaining access to the 2703 drop- and accept-listed IP addresses. 2705 An attacker may be able to inject RST packets, bogus application 2706 segments, etc., regardless of whether TLS authentication is used. 2707 Because the application data is TLS protected, this will not result 2708 in the application receiving bogus data, but it will constitute a DoS 2709 on the connection. This attack can be countered by using TCP-AO 2710 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2711 attacker will be rejected by the TCP-AO integrity check and therefore 2712 will never reach the TLS layer. 2714 In order to prevent leaking internal information outside a client- 2715 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2716 internal DOTS clients (e.g., source IP address, client's hostname) 2717 unless explicitly configured to do so. 2719 DOTS servers MUST verify that requesting DOTS clients are entitled to 2720 enforce filtering rules on a given IP prefix. That is, only 2721 filtering rules on IP resources that belong to the DOTS client domain 2722 can be authorized by a DOTS server. The exact mechanism for the DOTS 2723 servers to validate that the target prefixes are within the scope of 2724 the DOTS client domain is deployment-specific. 2726 Rate-limiting DOTS requests, including those with new 'cuid' values, 2727 from the same DOTS client defends against DoS attacks that would 2728 result from varying the 'cuid' to exhaust DOTS server resources. 2729 Rate-limit policies SHOULD be enforced on DOTS gateways (if deployed) 2730 and DOTS servers. 2732 Applying resources quota per DOTS client and/or per DOTS client 2733 domain (e.g., limit the number of aliases and filters to be installed 2734 by DOTS clients) prevents DOTS server resources to be aggressively 2735 used by some DOTS clients and ensures, therefore, DDoS mitigation 2736 usage fairness. Additionally, DOTS servers may limit the number of 2737 DOTS clients that can be enabled per domain. 2739 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 2740 privacy enabling protocols (e.g., DNS over TLS [RFC7858] or DoH 2741 [RFC8484]) to prevent eavesdroppers from possibly identifying the 2742 target resources protected by the DDoS mitigation service, and means 2743 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 2744 [RFC4034]). 2746 The presence of DOTS gateways may lead to infinite forwarding loops, 2747 which is undesirable. To prevent and detect such loops, a mechanism 2748 is defined in Section 3.4. 2750 All data nodes defined in the YANG module which can be created, 2751 modified, and deleted (i.e., config true, which is the default) are 2752 considered sensitive. Write operations applied to these data nodes 2753 without proper protection can negatively affect network operations. 2754 This module reuses YANG structures from [RFC8519], and the security 2755 considerations for those nodes continue to apply for this usage. 2756 Appropriate security measures are recommended to prevent illegitimate 2757 users from invoking DOTS data channel primitives. Nevertheless, an 2758 attacker who can access a DOTS client is technically capable of 2759 launching various attacks, such as: 2761 o Setting an arbitrarily low rate-limit, which may prevent 2762 legitimate traffic from being forwarded (rate-limit). 2764 o Setting an arbitrarily high rate-limit, which may lead to the 2765 forwarding of illegitimate DDoS traffic (rate-limit). 2767 o Communicating invalid aliases to the server (alias), which will 2768 cause the failure of associating both data and signal channels. 2770 o Setting invalid ACL entries, which may prevent legitimate traffic 2771 from being forwarded. Likewise, invalid ACL entries may lead to 2772 forward DDoS traffic. 2774 11. Contributing Authors 2776 The following individuals co-authored this document: 2778 Kaname Nishizuka 2779 NTT Communications 2780 GranPark 16F 3-4-1 Shibaura, Minato-ku 2781 Tokyo 108-8118 2782 Japan 2784 Email: kaname@nttv6.jp 2786 Liang Xia 2787 Huawei 2788 101 Software Avenue, Yuhuatai District 2789 Nanjing, Jiangsu 210012 2790 China 2792 Email: frank.xialiang@huawei.com 2794 Prashanth Patil 2795 Cisco Systems, Inc. 2797 Email: praspati@cisco.com 2799 Andrew Mortensen 2800 Arbor Networks, Inc. 2801 2727 S. State St 2802 Ann Arbor, MI 48104 2803 United States 2805 Email: andrew.mortensen@netscout.com 2807 Nik Teague 2808 Iron Mountain Data Centers 2809 United Kingdom 2811 Email: nteague@ironmountain.co.uk 2813 12. Contributors 2815 The following individuals have contributed to this document: 2817 o Dan Wing, Email: dwing-ietf@fuggles.com 2819 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.com 2821 13. Acknowledgements 2823 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2824 Doron, Russ White, Gilbert Clark, Kathleen Moriarty, Nesredien 2825 Suleiman, Roni Even, and Brian Trammel for the discussion and 2826 comments. 2828 The authors would like to give special thanks to Kaname Nishizuka and 2829 Jon Shallow for their efforts in implementing the protocol and 2830 performing interop testing at IETF Hackathons. 2832 Many thanks to Ben Kaduk for the detailed AD review. 2834 Thanks to Martin Bjorklund for the guidance on RESTCONF. 2836 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 2837 Kuehlewind, and Warren Kumari for the review. 2839 14. References 2841 14.1. Normative References 2843 [I-D.ietf-dots-signal-channel] 2844 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 2845 Teague, "Distributed Denial-of-Service Open Threat 2846 Signaling (DOTS) Signal Channel Specification", draft- 2847 ietf-dots-signal-channel-34 (work in progress), May 2019. 2849 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2850 Requirement Levels", BCP 14, RFC 2119, 2851 DOI 10.17487/RFC2119, March 1997, 2852 . 2854 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2855 DOI 10.17487/RFC3688, January 2004, 2856 . 2858 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2859 (CIDR): The Internet Address Assignment and Aggregation 2860 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2861 2006, . 2863 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2864 Verification of Domain-Based Application Service Identity 2865 within Internet Public Key Infrastructure Using X.509 2866 (PKIX) Certificates in the Context of Transport Layer 2867 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2868 2011, . 2870 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2871 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2872 . 2874 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2875 Protocol (HTTP/1.1): Message Syntax and Routing", 2876 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2877 . 2879 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2880 "Recommendations for Secure Use of Transport Layer 2881 Security (TLS) and Datagram Transport Layer Security 2882 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2883 2015, . 2885 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2886 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2887 . 2889 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2890 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2891 . 2893 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2894 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2895 . 2897 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2898 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2899 May 2017, . 2901 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2902 Interchange Format", STD 90, RFC 8259, 2903 DOI 10.17487/RFC8259, December 2017, 2904 . 2906 [RFC8519] Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, 2907 "YANG Data Model for Network Access Control Lists (ACLs)", 2908 RFC 8519, DOI 10.17487/RFC8519, March 2019, 2909 . 2911 14.2. Informative References 2913 [I-D.ietf-dots-architecture] 2914 Mortensen, A., K, R., Andreasen, F., Teague, N., and R. 2915 Compton, "Distributed-Denial-of-Service Open Threat 2916 Signaling (DOTS) Architecture", draft-ietf-dots- 2917 architecture-14 (work in progress), May 2019. 2919 [I-D.ietf-dots-server-discovery] 2920 Boucadair, M. and R. K, "Distributed-Denial-of-Service 2921 Open Threat Signaling (DOTS) Server Discovery", draft- 2922 ietf-dots-server-discovery-04 (work in progress), June 2923 2019. 2925 [proto_numbers] 2926 "IANA, "Protocol Numbers"", 2011, 2927 . 2929 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2930 Communication Layers", STD 3, RFC 1122, 2931 DOI 10.17487/RFC1122, October 1989, 2932 . 2934 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2935 Resource Identifier (URI): Generic Syntax", STD 66, 2936 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2937 . 2939 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 2940 Rose, "Resource Records for the DNS Security Extensions", 2941 RFC 4034, DOI 10.17487/RFC4034, March 2005, 2942 . 2944 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2945 Congestion Control Protocol (DCCP)", RFC 4340, 2946 DOI 10.17487/RFC4340, March 2006, 2947 . 2949 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2950 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2951 . 2953 [RFC5575] Marques, P., Sheth, N., Raszuk, R., Greene, B., Mauch, J., 2954 and D. McPherson, "Dissemination of Flow Specification 2955 Rules", RFC 5575, DOI 10.17487/RFC5575, August 2009, 2956 . 2958 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2959 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2960 June 2010, . 2962 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2963 Layer Security (TLS) and Datagram Transport Layer Security 2964 (DTLS) Heartbeat Extension", RFC 6520, 2965 DOI 10.17487/RFC6520, February 2012, 2966 . 2968 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 2969 and P. Hoffman, "Specification for DNS over Transport 2970 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 2971 2016, . 2973 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2974 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2975 . 2977 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 2978 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 2979 . 2981 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 2982 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 2983 January 2019, . 2985 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 2986 Threat Signaling (DOTS) Requirements", RFC 8612, 2987 DOI 10.17487/RFC8612, May 2019, 2988 . 2990 Appendix A. Sample Examples: Filtering Fragments 2992 This specification strongly recommends the use of "fragment" for 2993 handling fragments. 2995 Figure 34 shows the content of the POST request to be issued by a 2996 DOTS client to its DOTS server to allow the traffic destined to 2997 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2998 packets. The following ACEs are defined (in this order): 3000 o "drop-all-fragments" ACE: discards all fragments. 3002 o "allow-dns-packets" ACE: accepts DNS packets destined to 3003 198.51.100.0/24. 3005 POST /restconf/data/ietf-dots-data-channel:dots-data\ 3006 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 3007 Host: example.com 3008 Content-Type: application/yang-data+json 3010 { 3011 "ietf-dots-data-channel:acls": { 3012 "acl": [ 3013 { 3014 "name": "dns-fragments", 3015 "type": "ipv4-acl-type", 3016 "aces": { 3017 "ace": [ 3018 { 3019 "name": "drop-all-fragments", 3020 "matches": { 3021 "ipv4": { 3022 "fragment": { 3023 "operator": "match", 3024 "type": "isf" 3025 } 3026 } 3027 }, 3028 "actions": { 3029 "forwarding": "drop" 3030 } 3031 } 3032 ] 3033 "ace": [ 3034 { 3035 "name": "allow-dns-packets", 3036 "matches": { 3037 "ipv4": { 3038 "destination-ipv4-network": "198.51.100.0/24" 3039 } 3040 "udp": { 3041 "destination-port": { 3042 "operator": "eq", 3043 "port": 53 3044 } 3045 }, 3046 "actions": { 3047 "forwarding": "accept" 3048 } 3049 } 3050 ] 3051 } 3052 } 3053 ] 3054 } 3055 } 3057 Figure 34: Filtering IPv4 Fragmented Packets 3059 Figure 35 shows a POST request example issued by a DOTS client to its 3060 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 3061 port number 53, but to drop all fragmented packets. The following 3062 ACEs are defined (in this order): 3064 o "drop-all-fragments" ACE: discards all fragments (including atomic 3065 fragments). That is, IPv6 packets which include a Fragment header 3066 (44) are dropped. 3068 o "allow-dns-packets" ACE: accepts DNS packets destined to 3069 2001:db8::/32. 3071 POST /restconf/data/ietf-dots-data-channel:dots-data\ 3072 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 3073 Host: example.com 3074 Content-Type: application/yang-data+json 3076 { 3077 "ietf-dots-data-channel:acls": { 3078 "acl": [ 3079 { 3080 "name": "dns-fragments", 3081 "type": "ipv6-acl-type", 3082 "aces": { 3083 "ace": [ 3084 { 3085 "name": "drop-all-fragments", 3086 "matches": { 3087 "ipv6": { 3088 "fragment": { 3089 "operator": "match", 3090 "type": "isf" 3091 } 3092 } 3093 }, 3094 "actions": { 3095 "forwarding": "drop" 3096 } 3097 } 3098 ] 3099 "ace": [ 3100 { 3101 "name": "allow-dns-packets", 3102 "matches": { 3103 "ipv6": { 3104 "destination-ipv6-network": "2001:db8::/32" 3105 } 3106 "udp": { 3107 "destination-port": { 3108 "operator": "eq", 3109 "port": 53 3110 } 3111 } 3113 }, 3114 "actions": { 3115 "forwarding": "accept" 3116 } 3117 } 3118 ] 3119 } 3120 } 3121 ] 3122 } 3123 } 3125 Figure 35: Filtering IPv6 Fragmented Packets 3127 Appendix B. Sample Examples: Filtering TCP Messages 3129 This section provides sample examples to illustrate TCP-specific 3130 filtering based on the flag bits. These examples should not be 3131 interpreted as recommended filtering behaviors under specific DDoS 3132 attacks. 3134 B.1. Discard TCP Null Attack 3136 Figure 36 shows an example of a DOTS request sent by a DOTS client to 3137 install immediately a filter to discard incoming TCP messages having 3138 all flags unset. The bitmask can be set to 255 to check against the 3139 (CWR, ECE, URG, ACK, PSH, RST, SYN, FIN) flags. 3141 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3142 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3143 /acl=tcp-flags-example HTTP/1.1 3144 Host: example.com 3145 Content-Type: application/yang-data+json 3147 { 3148 "ietf-dots-data-channel:acls": { 3149 "acl": [{ 3150 "name": "tcp-flags-example", 3151 "activation-type": "immediate", 3152 "aces": { 3153 "ace": [{ 3154 "name": "null-attack", 3155 "matches": { 3156 "tcp": { 3157 "flags-bitmask": { 3158 "operator": "not any", 3159 "bitmask": 4095 3160 } 3161 } 3162 }, 3163 "actions": { 3164 "forwarding": "drop" 3165 } 3166 }] 3167 } 3168 }] 3169 } 3170 } 3172 Figure 36: Example of a DOTS Request to Deny TCP Null Attack Messages 3174 B.2. Rate-Limit SYN Flooding 3176 Figure 37 shows an ACL example to rate-limit incoming SYNs during a 3177 SYN-flood attack. 3179 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3180 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3181 /acl=tcp-flags-example HTTP/1.1 3182 Host: example.com 3183 Content-Type: application/yang-data+json 3185 { 3186 "ietf-dots-data-channel:acls": { 3187 "acl": [{ 3188 "name": "tcp-flags-example", 3189 "activation-type": "activate-when-mitigating", 3190 "aces": { 3191 "ace": [{ 3192 "name": "rate-limit-syn", 3193 "matches": { 3194 "tcp": { 3195 "flags-bitmask": { 3196 "operator": "match", 3197 "bitmask": 2 3198 } 3199 } 3200 }, 3201 "actions": { 3202 "forwarding": "accept", 3203 "rate-limit": "20.00" 3204 } 3205 }] 3206 } 3207 }] 3208 } 3209 } 3211 Figure 37: Example of DOTS Request to Rate-Limit Incoming TCP SYNs 3213 B.3. Rate-Limit ACK Flooding 3215 Figure 38 shows an ACL example to rate-limit incoming ACKs during an 3216 ACK-flood attack. 3218 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 3219 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 3220 /acl=tcp-flags-example HTTP/1.1 3221 Host: example.com 3222 Content-Type: application/yang-data+json 3224 { 3225 "ietf-dots-data-channel:acls": { 3226 "acl": [{ 3227 "name": "tcp-flags-example", 3228 "type": "ipv4-acl-type", 3229 "activation-type": "activate-when-mitigating", 3230 "aces": { 3231 "ace": [{ 3232 "name": "rate-limit-ack", 3233 "matches": { 3234 "tcp": { 3235 "flags-bitmask": { 3236 "operator": "match", 3237 "bitmask": 16 3238 } 3239 } 3240 }, 3241 "actions": { 3242 "forwarding": "accept", 3243 "rate-limit": "20.00" 3244 } 3245 }] 3246 } 3247 }] 3248 } 3249 } 3251 Figure 38: Example of DOTS Request to Rate-Limit Incoming TCP ACKs 3253 Authors' Addresses 3255 Mohamed Boucadair (editor) 3256 Orange 3257 Rennes 35000 3258 France 3260 Email: mohamed.boucadair@orange.com 3261 Tirumaleswar Reddy (editor) 3262 McAfee, Inc. 3263 Embassy Golf Link Business Park 3264 Bangalore, Karnataka 560071 3265 India 3267 Email: kondtir@gmail.com