idnits 2.17.1 draft-ietf-dots-data-channel-27.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 433 has weird spacing: '...er-port ine...' == Line 518 has weird spacing: '...warding ide...' == Line 816 has weird spacing: '... icmp typ...' -- The document date (February 22, 2019) is 1887 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 2171 -- Looks like a reference, but probably isn't: '6' on line 2171 -- Looks like a reference, but probably isn't: '17' on line 2171 -- Looks like a reference, but probably isn't: '58' on line 2171 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-28 ** 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-11 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-18 -- 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: 2 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: August 26, 2019 McAfee 6 February 22, 2019 8 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 9 Specification 10 draft-ietf-dots-data-channel-27 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 August 26, 2019. 53 Copyright Notice 55 Copyright (c) 2019 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 72 3. DOTS Data Channel . . . . . . . . . . . . . . . . . . . . . . 5 73 3.1. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 74 3.2. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 7 75 3.3. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 8 76 3.4. Detect and Prevent Infinite Loops . . . . . . . . . . . . 8 77 3.5. Stale Entries . . . . . . . . . . . . . . . . . . . . . . 9 78 4. DOTS Data Channel YANG Module . . . . . . . . . . . . . . . . 9 79 4.1. Generic Tree Structure . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . . . . 64 100 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 64 101 14.1. Normative References . . . . . . . . . . . . . . . . . . 64 102 14.2. Informative References . . . . . . . . . . . . . . . . . 65 103 Appendix A. Sample Examples: Filtering Fragments . . . . . . . . 67 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 70 106 1. Introduction 108 A distributed denial-of-service (DDoS) attack is an attempt to make 109 machines or network resources unavailable to their intended users. 110 In most cases, sufficient scale can be achieved by compromising 111 enough end-hosts and using those infected hosts to perpetrate and 112 amplify the attack. The victim of such attack can be an application 113 server, a router, a firewall, an entire network, etc. 115 As discussed in [I-D.ietf-dots-requirements], the lack of a common 116 method to coordinate a real-time response among involved actors and 117 network domains inhibits the speed and effectiveness of DDoS attack 118 mitigation. From that standpoint, DDoS Open Threat Signaling (DOTS) 119 defines an architecture that allows a DOTS client to send requests to 120 a DOTS server for DDoS attack mitigation 121 [I-D.ietf-dots-architecture]. The DOTS approach is thus meant to 122 minimize the impact of DDoS attacks, thereby contributing to the 123 enforcement of more efficient defensive if not proactive security 124 strategies. To that aim, DOTS defines two channels: the signal and 125 the data channels (Figure 1). 127 +---------------+ +---------------+ 128 | | <------- Signal Channel ------> | | 129 | DOTS Client | | DOTS Server | 130 | | <======= Data Channel ======> | | 131 +---------------+ +---------------+ 133 Figure 1: DOTS Channels 135 The DOTS signal channel is used to carry information about a device 136 or a network (or a part thereof) that is under a DDoS attack. Such 137 information is sent by a DOTS client to an upstream DOTS server so 138 that appropriate mitigation actions are undertaken on traffic deemed 139 suspicious. The DOTS signal channel is further elaborated in 140 [I-D.ietf-dots-signal-channel]. 142 As for the DOTS data channel, it is used for infrequent bulk data 143 exchange between DOTS agents to significantly improve the 144 coordination of all the parties involved in the response to the 145 attack. Section 2 of [I-D.ietf-dots-architecture] mentions that the 146 DOTS data channel is used to perform the following tasks: 148 o Creating aliases for resources for which mitigation may be 149 requested. 151 A DOTS client may submit to its DOTS server a collection of 152 prefixes which it would like to refer to by an alias when 153 requesting mitigation. The DOTS server can respond to this 154 request with either a success or failure response (see Section 2 155 in [I-D.ietf-dots-architecture]). 157 Refer to Section 6 for more details. 159 o Policy management, which enables a DOTS client to request the 160 installation or withdrawal of traffic filters, dropping or rate- 161 limiting unwanted traffic, and permitting accept-listed traffic. 162 A DOTS client is entitled to instruct filtering rules only on IP 163 resources that belong to its domain. 165 Sample use cases for populating drop- or accept-list filtering 166 rules are detailed hereafter: 168 * If a network resource (DOTS client) is informed about a 169 potential DDoS attack from a set of IP addresses, the DOTS 170 client informs its servicing DOTS gateway of all suspect IP 171 addresses that need to be drop-listed for further 172 investigation. The DOTS client could also specify a list of 173 protocols and port numbers in the drop-list rule. 175 The DOTS gateway then propagates the drop-listed IP addresses 176 to a DOTS server which will undertake appropriate actions so 177 that traffic originated by these IP addresses to the target 178 network (specified by the DOTS client) is blocked. 180 * A network, that has partner sites from which only legitimate 181 traffic arrives, may want to ensure that the traffic from these 182 sites is not subjected to DDoS attack mitigation. The DOTS 183 client uses the DOTS data channel to convey the accept-listed 184 IP prefixes of the partner sites to its DOTS server. 186 The DOTS server uses this information to accept-list flows 187 originated by such IP prefixes and which reach the network. 189 Refer to Section 7 for more details. 191 2. Terminology 193 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 195 "OPTIONAL" in this document are to be interpreted as described in 196 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, 197 as shown here. 199 The reader should be familiar with the terms defined in 200 [I-D.ietf-dots-requirements]. 202 The terminology for describing YANG modules is defined in [RFC7950]. 203 The meaning of the symbols in the tree diagrams is defined in 204 [RFC8340]. 206 This document generalizes the notion of Access Control List (ACL) so 207 that it is not device-specific [I-D.ietf-netmod-acl-model]. As such, 208 this document defines an ACL as an ordered set of rules that is used 209 to filter traffic. Each rule is represented by an Access Control 210 Entry (ACE). ACLs communicated via the DOTS data channel are not 211 bound to a device interface. 213 For the sake of simplicity, all of the examples in this document use 214 "/restconf" as the discovered RESTCONF API root path. Many protocol 215 header lines and message-body text within examples throughout the 216 document are split into multiple lines for display purposes only. 217 When a line ends with backslash ('\') as the last character, the line 218 is wrapped for display purposes. It is to be considered to be joined 219 to the next line by deleting the backslash, the following line break, 220 and the leading whitespace of the next line. 222 3. DOTS Data Channel 224 3.1. Design Overview 226 Unlike the DOTS signal channel, which must remain operational even 227 when confronted with signal degradation due to packets loss, the DOTS 228 data channel is not expected to be fully operational at all times, 229 especially when a DDoS attack is underway. The requirements for a 230 DOTS data channel protocol are documented in 231 [I-D.ietf-dots-requirements]. 233 This specification does not require an order of DOTS signal and data 234 channel creations nor mandates a time interval between them. These 235 considerations are implementation- and deployment-specific. 237 As the primary function of the data channel is data exchange, a 238 reliable transport mode is required in order for DOTS agents to 239 detect data delivery success or failure. This document uses RESTCONF 240 [RFC8040] over TLS over TCP as the DOTS data channel protocol. The 241 abstract layering of DOTS data channel is shown in Figure 2. 243 +-------------------+ 244 | DOTS Data Channel | 245 +-------------------+ 246 | RESTCONF | 247 +-------------------+ 248 | TLS | 249 +-------------------+ 250 | TCP | 251 +-------------------+ 252 | IP | 253 +-------------------+ 255 Figure 2: Abstract Layering of DOTS Data Channel 257 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 258 resources represented by DOTS data channel YANG modules. These basic 259 edit operations allow the DOTS data channel running configuration to 260 be altered by a DOTS client. Rules for generating and processing 261 RESTCONF methods are defined in Section 4 of [RFC8040]. 263 DOTS data channel configuration information as well as state 264 information can be retrieved with the GET method. An HTTP status- 265 line header field is returned for each request to report success or 266 failure for RESTCONF operations (Section 5.4 of [RFC8040]). The 267 "error-tag" provides more information about encountered errors 268 (Section 7 of [RFC8040]). 270 DOTS clients perform the root resource discovery procedure discussed 271 in Section 3.1 of [RFC8040] to determine the root of the RESTCONF 272 API. After discovering the RESTCONF API root, a DOTS client uses 273 this value as the initial part of the path in the request URI, in any 274 subsequent request to the DOTS server. The DOTS server may support 275 the retrieval of the YANG modules it supports (Section 3.7 in 276 [RFC8040]). For example, a DOTS client may use RESTCONF to retrieve 277 the vendor-specific YANG modules supported by its DOTS server. 279 JavaScript Object Notation (JSON) [RFC8259] payloads are used to 280 propagate the DOTS data-channel-specific payload messages that carry 281 request parameters and response information, such as errors. This 282 specification uses the encoding rules defined in [RFC7951] for 283 representing DOTS data channel configuration data using YANG 284 (Section 4) as JSON text. 286 A DOTS client registers itself to its DOTS server(s) in order to set 287 up DOTS data channel-related configuration data and receive state 288 data (i.e., non-configuration data) from the DOTS server(s) 289 (Section 5). Mutual authentication considerations are specified in 290 Section 8 of [I-D.ietf-dots-signal-channel]. The coupling of signal 291 and data channels is discussed in Section 4.4.1 of 292 [I-D.ietf-dots-signal-channel]. 294 A single DOTS data channel between DOTS agents can be used to 295 exchange multiple requests and multiple responses. To reduce DOTS 296 client and DOTS server workload, DOTS clients SHOULD re-use the same 297 TLS session. While the communication to the DOTS server is 298 quiescent, the DOTS client MAY probe the server to ensure it has 299 maintained cryptographic state. Such probes can also keep alive 300 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 301 that the DOTS server still has TLS state by returning a TLS message. 303 A DOTS server may detect conflicting filtering requests from distinct 304 DOTS clients which belong to the same domain. For example, a DOTS 305 client could request to drop-list a prefix by specifying the source 306 prefix, while another DOTS client could request to accept-list that 307 same source prefix, but both having the same destination prefix. 308 DOTS servers SHOULD support a configuration parameter to indicate the 309 behavior to follow when a conflict is detected (e.g., reject all, 310 reject the new request, notify an administrator for validation). 311 Section 7.2 specifies a default behavior when no instruction is 312 supplied to a DOTS server. 314 NAT considerations for the DOTS data channel are similar to those 315 discussed in Section 3 of [I-D.ietf-dots-signal-channel]. 317 How filtering rules that are instantiated on a DOTS server are 318 translated into network configurations actions is out of scope of 319 this specification. 321 Some of the fields introduced in Section 4 are also discussed in 322 Sections 5, 6, and 7. These sections are authoritative for these 323 fields. 325 3.2. DOTS Server(s) Discovery 327 This document assumes that DOTS clients are provisioned with a way to 328 know how to reach their DOTS server(s), which could occur by a 329 variety of means (e.g., local configuration, or dynamic means such as 330 DHCP). The specification of such means are out of scope of this 331 document. 333 Likewise, it is out of scope of this document to specify the behavior 334 to be followed by a DOTS client to send DOTS requests when multiple 335 DOTS servers are provisioned (e.g., contact all DOTS servers, select 336 one DOTS server among the list). 338 3.3. DOTS Gateways 340 When a server-domain DOTS gateway is involved in DOTS data channel 341 exchanges, the same considerations for manipulating the 'cdid' 342 (client domain identifier) parameter specified in 343 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 344 reminder, 'cdid' is meant to assist the DOTS server to enforce some 345 policies (e.g., limit the number of filtering rules per DOTS client 346 or per DOTS client domain). A loop detect mechanism for DOTS 347 gateways is specified in Section 3.4. 349 If a DOTS gateway is involved, the DOTS gateway verifies that the 350 DOTS client is authorized to undertake a data channel action (e.g., 351 instantiate filtering rules). If the DOTS client is authorized, it 352 propagates the rules to the upstream DOTS server. Likewise, the DOTS 353 server verifies that the DOTS gateway is authorized to relay data 354 channel actions. For example, to create or purge filters, a DOTS 355 client sends its request to its DOTS gateway. The DOTS gateway 356 validates the rules in the request and proxies the requests 357 containing the filtering rules to its DOTS server. When the DOTS 358 gateway receives the associated response from the DOTS server, it 359 propagates the response back to the DOTS client. 361 3.4. Detect and Prevent Infinite Loops 363 In order to detect and prevent infinite loops, DOTS gateways MUST 364 support the procedure defined in Section 5.7.1 of [RFC7230]. In 365 particular, each intermediate DOTS gateway MUST check that none of 366 its own information (e.g., server names, literal IP addresses) is 367 present in the "Via" header of a DOTS message it receives: 369 o If it detects that its own information is present in the "Via" 370 header, the DOTS gateway MUST NOT forward the DOTS message. 371 Messages that cannot be forwarded because of a loop SHOULD be 372 logged with a "508 Loop Detected" status-line returned sent back 373 to the DOTS peer. The structure of the reported error is depicted 374 in Figure 3. 376 error-app-tag: loop-detected 377 error-tag: operation-failed 378 error-type: transport, application 379 error-info: : A copy of the Via header when 380 the loop was detected. 381 Description: An infinite loop has been detected when forwarding 382 a requests via a proxy. 384 Figure 3: Loop Detected Error 386 It is RECOMMENDED that DOTS clients and gateways support means to 387 alert administrators about loop errors so that appropriate actions 388 are undertaken. 390 o Otherwise, the DOTS agent MUST update or insert the "Via" header 391 by appending its own information. 393 Unless configured otherwise, DOTS gateways at the boundaries of a 394 DOTS client domain SHOULD remove the previous "Via" header 395 information after checking for a loop before forwarding. This 396 behavior is required for topology hiding purposes but can also serve 397 to minimize potential conflicts that may arise if overlapping 398 information is used in distinct DOTS domains (e.g., private IPv4 399 addresses, non globally unique aliases). 401 3.5. Stale Entries 403 In order to avoid stale entries, a lifetime is associated with alias 404 and filtering entries created by DOTS clients. Also, DOTS servers 405 may track the inactivity timeout of DOTS clients to detect stale 406 entries. 408 4. DOTS Data Channel YANG Module 410 4.1. Generic Tree Structure 412 The DOTS data channel YANG module (ietf-dots-data-channel) provides a 413 method for DOTS clients to manage aliases for resources for which 414 mitigation may be requested. Such aliases may be used in subsequent 415 DOTS signal channel exchanges to refer more efficiently to the 416 resources under attack. 418 Note that the full module's tree has been split across several 419 figures to aid the exposition of the various sub-trees. 421 The tree structure for the DOTS alias is depicted in Figure 4. 423 module: ietf-dots-data-channel 424 +--rw dots-data 425 +--rw dots-client* [cuid] 426 | +--rw cuid string 427 | +--rw cdid? string 428 | +--rw aliases 429 | | +--rw alias* [name] 430 | | +--rw name string 431 | | +--rw target-prefix* inet:ip-prefix 432 | | +--rw target-port-range* [lower-port] 433 | | | +--rw lower-port inet:port-number 434 | | | +--rw upper-port? inet:port-number 435 | | +--rw target-protocol* uint8 436 | | +--rw target-fqdn* inet:domain-name 437 | | +--rw target-uri* inet:uri 438 | | +--ro pending-lifetime? int32 439 | +--rw acls 440 | ... 441 +--ro capabilities 442 ... 444 Figure 4: DOTS Alias Subtree 446 Also, the 'ietf-dots-data-channel' module provides a method for DOTS 447 clients to manage filtering rules. Examples of filtering management 448 in a DOTS context include, but not limited to: 450 o Drop-list management, which enables a DOTS client to inform a DOTS 451 server about sources from which traffic should be discarded. 453 o Accept-list management, which enables a DOTS client to inform a 454 DOTS server about sources from which traffic should always be 455 accepted. 457 o Policy management, which enables a DOTS client to request the 458 installation or withdrawal of traffic filters, dropping or rate- 459 limiting unwanted traffic and permitting accept-listed traffic. 461 The tree structure for the DOTS filtering entries is depicted in 462 Figure 5. 464 Investigations into the prospect of augmenting 'ietf-access-control- 465 list' to meet DOTS requirements concluded that such a design approach 466 did not support many of the DOTS requirements, e.g., 468 o Retrieve a filtering entry (or all entries) created by a DOTS 469 client. 471 o Delete a filtering entry that was instantiated by a DOTS client. 473 Accordingly, new DOTS filtering entries (i.e., Access Control List 474 (ACL)) are defined that mimic the structure specified in 475 [I-D.ietf-netmod-acl-model]. Concretely, DOTS agents are assumed to 476 manipulate an ordered list of ACLs; each ACL contains a separately 477 ordered list of Access Control Entries (ACEs). Each ACE has a group 478 of match and a group of action criteria. 480 Once all the ACE entries have been iterated though with no match, 481 then all the following ACL's ACE entries are iterated through until 482 the first match at which point the specified action is applied. If 483 there is no match during 'idle' time (i.e., no mitigation is active), 484 then there is no further action to be taken against the packet. If 485 there is no match during active mitigation, then the packet will 486 still be scrubbed by the DDoS mitigator. 488 module: ietf-dots-data-channel 489 +--rw dots-data 490 +--rw dots-client* [cuid] 491 | +--rw cuid string 492 | +--rw cdid? string 493 | +--rw aliases 494 | | ... 495 | +--rw acls 496 | +--rw acl* [name] 497 | +--rw name string 498 | +--rw type? ietf-acl:acl-type 499 | +--rw activation-type? activation-type 500 | +--ro pending-lifetime? int32 501 | +--rw aces 502 | +--rw ace* [name] 503 | +--rw name string 504 | +--rw matches 505 | | +--rw (l3)? 506 | | | +--:(ipv4) 507 | | | | ... 508 | | | +--:(ipv6) 509 | | | ... 510 | | +--rw (l4)? 511 | | +--:(tcp) 512 | | | ... 513 | | +--:(udp) 514 | | | ... 515 | | +--:(icmp) 516 | | ... 517 | +--rw actions 518 | | +--rw forwarding identityref 519 | | +--rw rate-limit? decimal64 520 | +--ro statistics 521 | +--ro matched-packets? yang:counter64 522 | +--ro matched-octets? yang:counter64 523 +--ro capabilities 524 ... 526 Figure 5: DOTS ACLs Subtree 528 Filtering rules instructed by a DOTS client assumes a default 529 direction: the destination is the DOTS client domain. 531 DOTS forwarding actions can be 'accept' (i.e., accept matching 532 traffic) or 'drop' (i.e., drop matching traffic without sending any 533 ICMP error message). Accepted traffic can be subject to rate- 534 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 535 matching traffic and send an ICMP error message to the source) is not 536 supported in 'ietf-dots-data-channel' because it is not appropriate 537 in the context of DDoS mitigation. Generating ICMP messages to 538 notify drops when mitigating a DDoS attack will exacerbate the DDoS 539 attack. Furthermore, these ICMP messages will be used by an attacker 540 as an explicit signal that the traffic is being blocked. 542 4.2. Filtering Fields 544 The 'ietf-dots-data-channel' module reuses the packet fields module 545 'ietf-packet-fields' [I-D.ietf-netmod-acl-model] which defines 546 matching on fields in the packet including IPv4, IPv6, and transport 547 layer fields. The 'ietf-dots-data-channel' module can be augmented, 548 for example, to support additional protocol-specific matching fields. 550 This specification defines a new IPv4/IPv6 matching field called 551 'fragment' to efficiently handle fragment-related filtering rules. 552 Indeed, [I-D.ietf-netmod-acl-model] does not support such capability 553 for IPv6 but offers a partial support for IPv4 by means of 'flags'. 554 Nevertheless, the use of 'flags' is problematic since it does not 555 allow to define a bitmask. For example, setting other bits not 556 covered by the 'flags' filtering clause in a packet will allow that 557 packet to get through (because it won't match the ACE). Sample 558 examples to illustrate how 'fragment' can be used are provided in 559 Appendix A. 561 Figure 6 shows the IPv4 match subtree. 563 module: ietf-dots-data-channel 564 +--rw dots-data 565 +--rw dots-client* [cuid] 566 | ... 567 | +--rw acls 568 | +--rw acl* [name] 569 | ... 570 | +--rw aces 571 | +--rw ace* [name] 572 | +--rw name string 573 | +--rw matches 574 | | +--rw (l3)? 575 | | | +--:(ipv4) 576 | | | | +--rw ipv4 577 | | | | +--rw dscp? inet:dscp 578 | | | | +--rw ecn? uint8 579 | | | | +--rw length? uint16 580 | | | | +--rw ttl? uint8 581 | | | | +--rw protocol? uint8 582 | | | | +--rw ihl? uint8 583 | | | | +--rw flags? bits 584 | | | | +--rw offset? uint16 585 | | | | +--rw identification? uint16 586 | | | | +--rw (destination-network)? 587 | | | | | +--:(destination-ipv4-network) 588 | | | | | +--rw destination-ipv4-network? 589 | | | | | inet:ipv4-prefix 590 | | | | +--rw (source-network)? 591 | | | | | +--:(source-ipv4-network) 592 | | | | | +--rw source-ipv4-network? 593 | | | | | inet:ipv4-prefix 594 | | | | +--rw fragment 595 | | | | +--rw operator? operator 596 | | | | +--rw type fragment-type 597 | | | +--:(ipv6) 598 | | | ... 599 | | +--rw (l4)? 600 | | ... 601 | +--rw actions 602 | | ... 603 | +--ro statistics 604 | ... 605 +--ro capabilities 606 ... 608 Figure 6: DOTS ACLs Subtree (IPv4 Match) 610 Figure 7 shows the IPv6 match subtree. 612 module: ietf-dots-data-channel 613 +--rw dots-data 614 +--rw dots-client* [cuid] 615 | ... 616 | +--rw acls 617 | +--rw acl* [name] 618 | ... 619 | +--rw aces 620 | +--rw ace* [name] 621 | +--rw name string 622 | +--rw matches 623 | | +--rw (l3)? 624 | | | +--:(ipv4) 625 | | | | ... 626 | | | +--:(ipv6) 627 | | | +--rw ipv6 628 | | | +--rw dscp? inet:dscp 629 | | | +--rw ecn? uint8 630 | | | +--rw length? uint16 631 | | | +--rw ttl? uint8 632 | | | +--rw protocol? uint8 633 | | | +--rw (destination-network)? 634 | | | | +--:(destination-ipv6-network) 635 | | | | +--rw destination-ipv6-network? 636 | | | | inet:ipv6-prefix 637 | | | +--rw (source-network)? 638 | | | | +--:(source-ipv6-network) 639 | | | | +--rw source-ipv6-network? 640 | | | | inet:ipv6-prefix 641 | | | +--rw flow-label? 642 | | | | inet:ipv6-flow-label 643 | | | +--rw fragment 644 | | | +--rw operator? operator 645 | | | +--rw type fragment-type 646 | | +--rw (l4)? 647 | | ... 648 | +--rw actions 649 | | ... 650 | +--ro statistics 651 | ... 652 +--ro capabilities 653 ... 655 Figure 7: DOTS ACLs Subtree (IPv6 Match) 657 Figure 8 shows the TCP match subtree. In addition to the fields 658 defined in [I-D.ietf-netmod-acl-model], this specification defines a 659 new TCP matching field, called 'flags-bitmask', to efficiently handle 660 TCP flags filtering rules. 662 module: ietf-dots-data-channel 663 +--rw dots-data 664 +-rw dots-client* [cuid] 665 | ... 666 | +-rw acls 667 | +-rw acl* [name] 668 | ... 669 | +-rw aces 670 | +-rw ace* [name] 671 | +-rw name string 672 | +-rw matches 673 | | +-rw (l3)? 674 | | | ... 675 | | +-rw (l4)? 676 | | +-:(tcp) 677 | | | +-rw tcp 678 | | | +--rw sequence-number? uint32 679 | | | +--rw acknowledgement-number? uint32 680 | | | +--rw data-offset? uint8 681 | | | +--rw reserved? uint8 682 | | | +--rw flags? bits 683 | | | +--rw window-size? uint16 684 | | | +--rw urgent-pointer? uint16 685 | | | +--rw options? binary 686 | | | +--rw flags-bitmask 687 | | | | +--rw operator? operator 688 | | | | +--rw bitmask uint16 689 | | | +--rw (source-port)? 690 | | | | +--:(source-port-range-or-operator) 691 | | | | +--rw source-port-range-or-operator 692 | | | | +--rw (port-range-or-operator)? 693 | | | | +--:(range) 694 | | | | | +--rw lower-port 695 | | | | | | inet:port-number 696 | | | | | +--rw upper-port 697 | | | | | inet:port-number 698 | | | | +--:(operator) 699 | | | | +--rw operator? 700 | | | | | operator 701 | | | | +--rw port 702 | | | | inet:port-number 703 | | | +--rw (destination-port)? 704 | | | +--:(destination-port-range-or-operator) 705 | | | +--rw destination-port-range-or-operator 706 | | | +--rw (port-range-or-operator)? 707 | | | +--:(range) 708 | | | | +--rw lower-port 709 | | | | | inet:port-number 710 | | | | +--rw upper-port 711 | | | | inet:port-number 712 | | | +--:(operator) 713 | | | +--rw operator? 714 | | | | operator 715 | | | +--rw port 716 | | | inet:port-number 717 | | +-:(udp) 718 | | | ... 719 | | +-:(icmp) 720 | | ... 721 | +-rw actions 722 | | ... 723 | +-ro statistics 724 | ... 725 +-ro capabilities 726 ... 728 Figure 8: DOTS ACLs Subtree (TCP Match) 730 Figure 9 shows the UDP and ICMP match subtrees. The same structure 731 is used for both ICMP and ICMPv6. The indication whether an ACL is 732 about ICMP or ICMPv6 is governed by the 'l3' match. 734 module: ietf-dots-data-channel 735 +-rw dots-data 736 +-rw dots-client* [cuid] 737 | ... 738 | +-rw acls 739 | +-rw acl* [name] 740 | ... 741 | +-rw aces 742 | +-rw ace* [name] 743 | +--rw name string 744 | +--rw matches 745 | | +--rw (l3)? 746 | | | ... 747 | | +--rw (l4)? 748 | | +--:(tcp) 749 | | | ... 750 | | +--:(udp) 751 | | | +--rw udp 752 | | | +--rw length? uint16 753 | | | +--rw (source-port)? 754 | | | | +--:(source-port-range-or-operator) 755 | | | | +--rw source-port-range-or-operator 756 | | | | +--rw (port-range-or-operator)? 757 | | | | +--:(range) 758 | | | | | +--rw lower-port 759 | | | | | | inet:port-number 760 | | | | | +--rw upper-port 761 | | | | | inet:port-number 762 | | | | +--:(operator) 763 | | | | +--rw operator? 764 | | | | | operator 765 | | | | +--rw port 766 | | | | inet:port-number 767 | | | +--rw (destination-port)? 768 | | | +--:(destination-port-range-or-operator) 769 | | | +--rw destination-port-range-or-operator 770 | | | +--rw (port-range-or-operator)? 771 | | | +--:(range) 772 | | | | +--rw lower-port 773 | | | | | inet:port-number 774 | | | | +--rw upper-port 775 | | | | inet:port-number 776 | | | +--:(operator) 777 | | | +--rw operator? 778 | | | | operator 779 | | | +--rw port 780 | | | inet:port-number 781 | | +--:(icmp) 782 | | +--rw icmp 783 | | +--rw type? uint8 784 | | +--rw code? uint8 785 | | +--rw rest-of-header? binary 786 | +--rw actions 787 | | ... 788 | +--ro statistics 789 | ... 790 +-ro capabilities 791 ... 793 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 795 DOTS implementations MUST support the following matching criteria: 797 match based on the IP header (IPv4 and IPv6), match based on the 798 transport header (TCP, UDP, and ICMP), and any combination 799 thereof. The same matching fields are used for both ICMP and 800 ICMPv6. 802 The following match fields MUST be supported by DOTS implementations 803 (Table 1): 805 ACL Mandatory Fields 806 Match 807 ------- ------------------------------------------------------------- 808 ipv4 length, protocol, destination-ipv4-network, source- 809 ipv4-network, and fragment 810 ipv6 length, protocol, destination-ipv6-network, source- 811 ipv6-network, and fragment 812 tcp flags-bitmask, source-port-range-or-operator, and 813 destination-port-range-or-operator 814 udp length, source-port-range-or-operator, and destination-port- 815 range-or-operator 816 icmp type and code 818 Table 1: Mandatory DOTS Channel Match Fields 820 Implementations MAY support other filtering match fields and actions. 821 The 'ietf-dots-data-channel' provides a method for an implementation 822 to expose its filtering capabilities. The tree structure of the 823 'capabilities' is shown in Figure 10. 825 module: ietf-dots-data-channel 826 +--rw dots-data 827 ... 828 +--ro capabilities 829 +--ro address-family* enumeration 830 +--ro forwarding-actions* identityref 831 +--ro rate-limit? boolean 832 +--ro transport-protocols* uint8 833 +--ro ipv4 834 | +--ro dscp? boolean 835 | +--ro ecn? boolean 836 | +--ro length? boolean 837 | +--ro ttl? boolean 838 | +--ro protocol? boolean 839 | +--ro ihl? boolean 840 | +--ro flags? boolean 841 | +--ro offset? boolean 842 | +--ro identification? boolean 843 | +--ro source-prefix? boolean 844 | +--ro destination-prefix? boolean 845 | +--ro fragment? boolean 846 +--ro ipv6 847 | +--ro dscp? boolean 848 | +--ro ecn? boolean 849 | +--ro length? boolean 850 | +--ro hoplimit? boolean 851 | +--ro protocol? boolean 852 | +--ro destination-prefix? boolean 853 | +--ro source-prefix? boolean 854 | +--ro flow-label? boolean 855 | +--ro fragment? boolean 856 +--ro tcp 857 | +--ro sequence-number? boolean 858 | +--ro acknowledgement-number? boolean 859 | +--ro data-offset? boolean 860 | +--ro reserved? boolean 861 | +--ro flags? boolean 862 | +--ro window-size? boolean 863 | +--ro urgent-pointer? boolean 864 | +--ro options? boolean 865 | +--ro flags-bitmask? boolean 866 | +--ro source-port? boolean 867 | +--ro destination-port? boolean 868 | +--ro port-range? boolean 869 +--ro udp 870 | +--ro length? boolean 871 | +--ro source-port? boolean 872 | +--ro destination-port? boolean 873 | +--ro port-range? boolean 874 +--ro icmp 875 +--ro type? boolean 876 +--ro code? boolean 877 +--ro rest-of-header? boolean 879 Figure 10: Filtering Capabilities Subtree 881 4.3. YANG Module 883 This module uses the common YANG types defined in [RFC6991] and types 884 defined in [I-D.ietf-netmod-acl-model]. 886 file "ietf-dots-data-channel@2019-02-14.yang" 887 module ietf-dots-data-channel { 888 yang-version 1.1; 889 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 890 prefix data-channel; 892 import ietf-inet-types { 893 prefix inet; 894 reference "Section 4 of RFC 6991"; 895 } 896 import ietf-access-control-list { 897 prefix ietf-acl; 898 reference 899 "RFC 8519: Network Access Control List (ACL) 900 YANG Data Model"; 901 } 902 import ietf-packet-fields { 903 prefix packet-fields; 904 reference 905 "RFC 8519: YANG Data Model for Network Access 906 Control Lists (ACLs)"; 907 } 909 organization 910 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 911 contact 912 "WG Web: 913 WG List: 915 Editor: Mohamed Boucadair 916 918 Editor: Konda, Tirumaleswar Reddy 919 921 Author: Jon Shallow 922 924 Author: Kaname Nishizuka 925 927 Author: Liang Xia 928 930 Author: Prashanth Patil 931 933 Author: Andrew Mortensen 934 936 Author: Nik Teague 937 "; 938 description 939 "This module contains YANG definition for configuring 940 aliases for resources and filtering rules using DOTS 941 data channel. 943 Copyright (c) 2019 IETF Trust and the persons identified as 944 authors of the code. All rights reserved. 946 Redistribution and use in source and binary forms, with or 947 without modification, is permitted pursuant to, and subject 948 to the license terms contained in, the Simplified BSD License 949 set forth in Section 4.c of the IETF Trust's Legal Provisions 950 Relating to IETF Documents 951 (http://trustee.ietf.org/license-info). 953 This version of this YANG module is part of RFC XXXX; see 954 the RFC itself for full legal notices."; 956 revision 2019-02-14 { 957 description 958 "Initial revision."; 959 reference 960 "RFC XXXX: Distributed Denial-of-Service Open Threat 961 Signaling (DOTS) Data Channel Specification"; 962 } 964 typedef activation-type { 965 type enumeration { 966 enum "activate-when-mitigating" { 967 value 1; 968 description 969 "The Access Control List (ACL) is installed only when 970 a mitigation is active for the DOTS client."; 971 } 972 enum "immediate" { 973 value 2; 974 description 975 "The ACL is immediately activated."; 976 } 977 enum "deactivate" { 978 value 3; 979 description 980 "The ACL is maintained by the DOTS server, but it is 981 deactivated."; 982 } 983 } 984 description 985 "Indicates the activation type of an ACL."; 986 } 988 typedef operator { 989 type bits { 990 bit not { 991 position 0; 992 description 993 "If set, logical negation of operation."; 995 } 996 bit match { 997 position 1; 998 description 999 "Match bit. If set, this is a bitwise match operation 1000 defined as '(data & value) == value'; if unset, (data & 1001 value) evaluates to TRUE if any of the bits in the value 1002 mask are set in the data , i.e., '(data & value) != 0'."; 1003 } 1004 } 1005 description 1006 "Specifies how to apply the defined bitmask."; 1007 } 1009 grouping tcp-flags { 1010 leaf operator { 1011 type operator; 1012 default "match"; 1013 description 1014 "Specifies how to interpret the TCP flags."; 1015 } 1016 leaf bitmask { 1017 type uint16; 1018 mandatory true; 1019 description 1020 "Bitmask values can be encoded as a 1- or 2-byte bitmask. 1021 When a single byte is specified, it matches byte 13 1022 of the TCP header, which contains bits 8 though 15 1023 of the 4th 32-bit word. When a 2-byte encoding is used, 1024 it matches bytes 12 and 13 of the TCP header with 1025 the bitmask fields corresponding to the TCP data offset 1026 field being ignored for purposes of matching."; 1027 } 1028 description 1029 "Operations on TCP flags."; 1030 } 1032 typedef fragment-type { 1033 type bits { 1034 bit df { 1035 position 0; 1036 description 1037 "Don't fragment bit for IPv4. 1038 Must be set to 0 when it appears in an IPv6 filter."; 1039 } 1040 bit isf { 1041 position 1; 1042 description 1043 "Is a fragment."; 1044 } 1045 bit ff { 1046 position 2; 1047 description 1048 "First fragment."; 1049 } 1050 bit lf { 1051 position 3; 1052 description 1053 "Last fragment."; 1054 } 1055 } 1056 description 1057 "Different fragment types to match against."; 1058 } 1060 grouping target { 1061 description 1062 "Specifies the targets of the mitigation request."; 1063 leaf-list target-prefix { 1064 type inet:ip-prefix; 1065 description 1066 "IPv4 or IPv6 prefix identifying the target."; 1067 } 1068 list target-port-range { 1069 key "lower-port"; 1070 description 1071 "Port range. When only lower-port is 1072 present, it represents a single port number."; 1073 leaf lower-port { 1074 type inet:port-number; 1075 mandatory true; 1076 description 1077 "Lower port number of the port range."; 1078 } 1079 leaf upper-port { 1080 type inet:port-number; 1081 must '. >= ../lower-port' { 1082 error-message 1083 "The upper port number must be greater than 1084 or equal to lower port number."; 1085 } 1086 description 1087 "Upper port number of the port range."; 1088 } 1089 } 1090 leaf-list target-protocol { 1091 type uint8; 1092 description 1093 "Identifies the target protocol number. 1095 Values are taken from the IANA protocol registry: 1096 https://www.iana.org/assignments/protocol-numbers/ 1097 protocol-numbers.xhtml 1099 For example, 6 for TCP or 17 for UDP."; 1100 } 1101 leaf-list target-fqdn { 1102 type inet:domain-name; 1103 description 1104 "FQDN identifying the target."; 1105 } 1106 leaf-list target-uri { 1107 type inet:uri; 1108 description 1109 "URI identifying the target."; 1110 } 1111 } 1113 grouping fragment-fields { 1114 leaf operator { 1115 type operator; 1116 default "match"; 1117 description 1118 "Specifies how to interpret the fragment type."; 1119 } 1120 leaf type { 1121 type fragment-type; 1122 mandatory true; 1123 description 1124 "Indicates what fragment type to look for."; 1125 } 1126 description 1127 "Operations on fragment types."; 1128 } 1130 grouping aliases { 1131 description 1132 "Top level container for aliases"; 1133 list alias { 1134 key "name"; 1135 description 1136 "List of aliases"; 1137 leaf name { 1138 type string; 1139 description 1140 "The name of the alias"; 1141 } 1142 uses target; 1143 leaf pending-lifetime { 1144 type int32; 1145 units "minutes"; 1146 config false; 1147 description 1148 "Indicates the pending validity lifetime of the alias 1149 entry."; 1150 } 1151 } 1152 } 1154 grouping ports { 1155 choice source-port { 1156 container source-port-range-or-operator { 1157 uses packet-fields:port-range-or-operator; 1158 description 1159 "Source port definition."; 1160 } 1161 description 1162 "Choice of specifying the source port or referring to 1163 a group of source port numbers."; 1164 } 1165 choice destination-port { 1166 container destination-port-range-or-operator { 1167 uses packet-fields:port-range-or-operator; 1168 description 1169 "Destination port definition."; 1170 } 1171 description 1172 "Choice of specifying a destination port or referring 1173 to a group of destination port numbers."; 1174 } 1175 description 1176 "Choice of specifying a source or destination port numbers."; 1177 } 1179 grouping access-lists { 1180 description 1181 "Specifies the ordered set of Access Control Lists."; 1182 list acl { 1183 key "name"; 1184 ordered-by user; 1185 description 1186 "An ACL is an ordered list of Access Control Entries (ACE). 1188 Each ACE has a list of match criteria and a list of actions."; 1189 leaf name { 1190 type string { 1191 length "1..64"; 1192 } 1193 description 1194 "The name of the access list."; 1195 reference 1196 "RFC 8519: YANG Data Model for Network Access 1197 Control Lists (ACLs)"; 1198 } 1199 leaf type { 1200 type ietf-acl:acl-type; 1201 description 1202 "Type of access control list. Indicates the primary intended 1203 type of match criteria (e.g., IPv4, IPv6) used in the list 1204 instance."; 1205 reference 1206 "RFC 8519: YANG Data Model for Network Access 1207 Control Lists (ACLs)"; 1208 } 1209 leaf activation-type { 1210 type activation-type; 1211 default "activate-when-mitigating"; 1212 description 1213 "Indicates the activation type of an ACL. An ACL can be 1214 deactivated, installed immediately, or installed when 1215 a mitigation is active."; 1216 } 1217 leaf pending-lifetime { 1218 type int32; 1219 units "minutes"; 1220 config false; 1221 description 1222 "Indicates the pending validity lifetime of the ACL 1223 entry."; 1224 } 1225 container aces { 1226 description 1227 "The Access Control Entries container contains 1228 a list of ACEs."; 1229 list ace { 1230 key "name"; 1231 ordered-by user; 1232 description 1233 "List of access list entries."; 1234 leaf name { 1235 type string { 1236 length "1..64"; 1237 } 1238 description 1239 "A unique name identifying this ACE."; 1240 reference 1241 "RFC 8519: YANG Data Model for Network Access 1242 Control Lists (ACLs)"; 1243 } 1244 container matches { 1245 description 1246 "The rules in this set determine what fields will be 1247 matched upon before any action is taken on them. 1249 If no matches are defined in a particular container, 1250 then any packet will match that container. 1252 If no matches are specified at all in an ACE, then any 1253 packet will match the ACE."; 1254 reference 1255 "RFC 8519: YANG Data Model for Network Access 1256 Control Lists (ACLs)"; 1257 choice l3 { 1258 container ipv4 { 1259 when "derived-from(../../../../type," 1260 + "'ietf-acl:ipv4-acl-type')"; 1261 uses packet-fields:acl-ip-header-fields; 1262 uses packet-fields:acl-ipv4-header-fields; 1263 container fragment { 1264 description 1265 "Indicates how to handle IPv4 fragments."; 1266 uses fragment-fields; 1267 } 1268 description 1269 "Rule set that matches IPv4 header."; 1270 } 1271 container ipv6 { 1272 when "derived-from(../../../../type," 1273 + "'ietf-acl:ipv6-acl-type')"; 1274 uses packet-fields:acl-ip-header-fields; 1275 uses packet-fields:acl-ipv6-header-fields; 1276 container fragment { 1277 description 1278 "Indicates how to handle IPv6 fragments."; 1279 uses fragment-fields; 1280 } 1281 description 1282 "Rule set that matches IPv6 header."; 1283 } 1284 description 1285 "Either IPv4 or IPv6."; 1286 } 1287 choice l4 { 1288 container tcp { 1289 uses packet-fields:acl-tcp-header-fields; 1290 container flags-bitmask { 1291 description 1292 "Indicates how to handle TCP flags."; 1293 uses tcp-flags; 1294 } 1295 uses ports; 1296 description 1297 "Rule set that matches TCP header."; 1298 } 1299 container udp { 1300 uses packet-fields:acl-udp-header-fields; 1301 uses ports; 1302 description 1303 "Rule set that matches UDP header."; 1304 } 1305 container icmp { 1306 uses packet-fields:acl-icmp-header-fields; 1307 description 1308 "Rule set that matches ICMP/ICMPv6 header."; 1309 } 1310 description 1311 "Can be TCP, UDP, or ICMP/ICMPv6"; 1312 } 1313 } 1314 container actions { 1315 description 1316 "Definitions of action for this ACE."; 1317 leaf forwarding { 1318 type identityref { 1319 base ietf-acl:forwarding-action; 1320 } 1321 mandatory true; 1322 description 1323 "Specifies the forwarding action per ACE."; 1324 reference 1325 "RFC 8519: YANG Data Model for Network Access 1326 Control Lists (ACLs)"; 1327 } 1328 leaf rate-limit { 1329 when "../forwarding = 'ietf-acl:accept'" { 1330 description 1331 "Rate-limit is valid only when accept action is 1332 used."; 1333 } 1334 type decimal64 { 1335 fraction-digits 2; 1336 } 1337 units "bytes per second"; 1338 description 1339 "Specifies how to rate-limit the traffic."; 1340 } 1341 } 1342 container statistics { 1343 config false; 1344 description 1345 "Aggregate statistics."; 1346 uses ietf-acl:acl-counters; 1347 } 1348 } 1349 } 1350 } 1351 } 1353 container dots-data { 1354 description 1355 "Main container for DOTS data channel."; 1356 list dots-client { 1357 key "cuid"; 1358 description 1359 "List of DOTS clients."; 1360 leaf cuid { 1361 type string; 1362 description 1363 "A unique identifier that is generated by a DOTS client 1364 to prevent request collisions."; 1365 reference 1366 "RFC YYYY: Distributed Denial-of-Service Open Threat 1367 Signaling (DOTS) Signal Channel Specification"; 1368 } 1369 leaf cdid { 1370 type string; 1371 description 1372 "A client domain identifier conveyed by a 1373 server-domain DOTS gateway to a remote DOTS server."; 1374 reference 1375 "RFC YYYY: Distributed Denial-of-Service Open Threat 1376 Signaling (DOTS) Signal Channel Specification"; 1377 } 1378 container aliases { 1379 description 1380 "Set of aliases that are bound to a DOTS client."; 1381 uses aliases; 1382 } 1383 container acls { 1384 description 1385 "Access lists that are bound to a DOTS client."; 1386 uses access-lists; 1387 } 1388 } 1389 container capabilities { 1390 config false; 1391 description 1392 "Match capabilities"; 1393 leaf-list address-family { 1394 type enumeration { 1395 enum "ipv4" { 1396 description 1397 "IPv4 is supported."; 1398 } 1399 enum "ipv6" { 1400 description 1401 "IPv6 is supported."; 1402 } 1403 } 1404 description 1405 "Indicates the IP address families supported by 1406 the DOTS server."; 1407 } 1408 leaf-list forwarding-actions { 1409 type identityref { 1410 base ietf-acl:forwarding-action; 1411 } 1412 description 1413 "Supported forwarding action(s)."; 1414 } 1415 leaf rate-limit { 1416 type boolean; 1417 description 1418 "Support of rate-limit action."; 1419 } 1420 leaf-list transport-protocols { 1421 type uint8; 1422 description 1423 "Upper-layer protocol associated with a filtering rule. 1425 Values are taken from the IANA protocol registry: 1426 https://www.iana.org/assignments/protocol-numbers/ 1427 protocol-numbers.xhtml 1428 For example, this field contains 1 for ICMP, 6 for TCP 1429 17 for UDP, or 58 for ICMPv6."; 1430 } 1431 container ipv4 { 1432 description 1433 "Indicates IPv4 header fields that are supported to enforce 1434 ACLs."; 1435 leaf dscp { 1436 type boolean; 1437 description 1438 "Support of filtering based on Differentiated Services Code 1439 Point (DSCP)."; 1440 } 1441 leaf ecn { 1442 type boolean; 1443 description 1444 "Support of filtering based on Explicit Congestion 1445 Notification (ECN)."; 1446 } 1447 leaf length { 1448 type boolean; 1449 description 1450 "Support of filtering based on the Total Length."; 1451 } 1452 leaf ttl { 1453 type boolean; 1454 description 1455 "Support of filtering based on the Time to Live (TTL)."; 1456 } 1457 leaf protocol { 1458 type boolean; 1459 description 1460 "Support of filtering based on protocol field."; 1461 } 1462 leaf ihl { 1463 type boolean; 1464 description 1465 "Support of filtering based on the Internet Header 1466 Length (IHL)."; 1467 } 1468 leaf flags { 1469 type boolean; 1470 description 1471 "Support of filtering based on the 'flags'"; 1472 } 1473 leaf offset { 1474 type boolean; 1475 description 1476 "Support of filtering based on the 'offset'."; 1477 } 1478 leaf identification { 1479 type boolean; 1480 description 1481 "Support of filtering based on the 'identification'."; 1482 } 1483 leaf source-prefix { 1484 type boolean; 1485 description 1486 "Support of filtering based on the source prefix."; 1487 } 1488 leaf destination-prefix { 1489 type boolean; 1490 description 1491 "Support of filtering based on the destination prefix."; 1492 } 1493 leaf fragment { 1494 type boolean; 1495 description 1496 "Indicates the capability of a DOTS server to 1497 enforce filters on IPv4 fragments. That is, the match 1498 functionality based on the layer 3 'fragment' clause 1499 is supported."; 1500 } 1501 } 1502 container ipv6 { 1503 description 1504 "Indicates IPv6 header fields that are supported to enforce 1505 ACLs."; 1506 leaf dscp { 1507 type boolean; 1508 description 1509 "Support of filtering based on DSCP."; 1510 } 1511 leaf ecn { 1512 type boolean; 1513 description 1514 "Support of filtering based on ECN."; 1515 } 1516 leaf length { 1517 type boolean; 1518 description 1519 "Support of filtering based on the Payload Length."; 1520 } 1521 leaf hoplimit { 1522 type boolean; 1523 description 1524 "Support of filtering based on the Hop Limit."; 1525 } 1526 leaf protocol { 1527 type boolean; 1528 description 1529 "Support of filtering based on the Next Header field."; 1530 } 1531 leaf destination-prefix { 1532 type boolean; 1533 description 1534 "Support of filtering based on the destination prefix."; 1535 } 1536 leaf source-prefix { 1537 type boolean; 1538 description 1539 "Support of filtering based on the source prefix."; 1540 } 1541 leaf flow-label { 1542 type boolean; 1543 description 1544 "Support of filtering based on the Flow label."; 1545 } 1546 leaf fragment { 1547 type boolean; 1548 description 1549 "Indicates the capability of a DOTS server to 1550 enforce filters on IPv6 fragments."; 1551 } 1552 } 1553 container tcp { 1554 description 1555 "Set of TCP fields that are supported by the DOTS server 1556 to enfoce filters."; 1557 leaf sequence-number { 1558 type boolean; 1559 description 1560 "Support of filtering based on the TCP sequence number."; 1561 } 1562 leaf acknowledgement-number { 1563 type boolean; 1564 description 1565 "Support of filtering based on the TCP acknowledgement 1566 number."; 1567 } 1568 leaf data-offset { 1569 type boolean; 1570 description 1571 "Support of filtering based on the TCP data-offset."; 1573 } 1574 leaf reserved { 1575 type boolean; 1576 description 1577 "Support of filtering based on the TCP reserved field."; 1578 } 1579 leaf flags { 1580 type boolean; 1581 description 1582 "Support of filtering, as defined in RFC 8519, based 1583 on the TCP flags."; 1584 } 1585 leaf window-size { 1586 type boolean; 1587 description 1588 "Support of filtering based on the TCP window size."; 1589 } 1590 leaf urgent-pointer { 1591 type boolean; 1592 description 1593 "Support of filtering based on the TCP urgent pointer."; 1594 } 1595 leaf options { 1596 type boolean; 1597 description 1598 "Support of filtering based on the TCP options."; 1599 } 1600 leaf flags-bitmask { 1601 type boolean; 1602 description 1603 "Support of filtering based on the TCP flags bitmask."; 1604 } 1605 leaf source-port { 1606 type boolean; 1607 description 1608 "Support of filtering based on the source port number."; 1609 } 1610 leaf destination-port { 1611 type boolean; 1612 description 1613 "Support of filtering based on the destination port 1614 number."; 1615 } 1616 leaf port-range { 1617 type boolean; 1618 description 1619 "Support of filtering based on a port range. 1621 This includes filtering based on a source port range, 1622 destination port range, or both. All operators 1623 (i.e, less than or equal, greater than or equal, equal to, 1624 and not equal to) are supported."; 1625 } 1626 } 1627 container udp { 1628 description 1629 "Set of UDP fields that are supported by the DOTS server 1630 to enforce filters."; 1631 leaf length { 1632 type boolean; 1633 description 1634 "Support of filtering based on the UDP length."; 1635 } 1636 leaf source-port { 1637 type boolean; 1638 description 1639 "Support of filtering based on the source port number."; 1640 } 1641 leaf destination-port { 1642 type boolean; 1643 description 1644 "Support of filtering based on the destination port 1645 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, greater than or equal, equal to, 1655 and not equal to) are supported."; 1656 } 1657 } 1658 container icmp { 1659 description 1660 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1661 server to enforce filters."; 1662 leaf type { 1663 type boolean; 1664 description 1665 "Support of filtering based on the ICMP/ICMPv6 type."; 1666 } 1667 leaf code { 1668 type boolean; 1669 description 1670 "Support of filtering based on the ICMP/ICMPv6 code."; 1671 } 1672 leaf rest-of-header { 1673 type boolean; 1674 description 1675 "Support of filtering based on the ICMP four-bytes 1676 field / the ICMPv6 message body."; 1677 } 1678 } 1679 } 1680 } 1681 } 1682 1684 5. Managing DOTS Clients 1686 5.1. Registering DOTS Clients 1688 In order to make use of DOTS data channel, a DOTS client MUST 1689 register to its DOTS server(s) by creating a DOTS client ('dots- 1690 client') resource. To that aim, DOTS clients SHOULD send a POST 1691 request (shown in Figure 11). 1693 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1694 Host: {host}:{port} 1695 Content-Type: application/yang-data+json 1696 { 1697 "ietf-dots-data-channel:dots-client": [ 1698 { 1699 "cuid": "string" 1700 } 1701 ] 1702 } 1704 Figure 11: POST to Register Schema 1706 The 'cuid' (client unique identifier) parameter is described below: 1708 cuid: A globally unique identifier that is meant to prevent 1709 collisions among DOTS clients. This attribute has the same 1710 meaning, syntax, and processing rules as the 'cuid' attribute 1711 defined in [I-D.ietf-dots-signal-channel]. 1713 DOTS clients MUST use the same 'cuid' for both signal and data 1714 channels. 1716 This is a mandatory attribute. 1718 In deployments where server-domain DOTS gateways are enabled, 1719 identity information about the origin source client domain SHOULD be 1720 supplied to the DOTS server. That information is meant to assist the 1721 DOTS server to enforce some policies. These policies can be enforced 1722 per-client, per-client domain, or both. Figure 12 shows a schema 1723 example of a request relayed by a server-domain DOTS gateway. 1725 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1726 Host: {host}:{port} 1727 Content-Type: application/yang-data+json 1728 { 1729 "ietf-dots-data-channel:dots-client": [ 1730 { 1731 "cuid": "string", 1732 "cdid": "string" 1733 } 1734 ] 1735 } 1737 Figure 12: POST to Register Schema (via a Server-Domain DOTS Gateway) 1739 A server-domain DOTS gateway SHOULD add the following attribute: 1741 cdid: This attribute has the same meaning, syntax, and processing 1742 rules as the 'cdid' attribute defined in 1743 [I-D.ietf-dots-signal-channel]. 1745 In deployments where server-domain DOTS gateways are enabled, 1746 'cdid' does not need to be inserted when relaying DOTS methods to 1747 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1748 servers are responsible for maintaining the association between 1749 'cdid' and 'cuid' for policy enforcement purposes. 1751 This is an optional attribute. 1753 A request example to create a 'dots-client' resource is depicted in 1754 Figure 13. This request is relayed by a server-domain DOTS gateway 1755 as hinted by the presence of the 'cdid' attribute. 1757 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1758 Host: example.com 1759 Content-Type: application/yang-data+json 1760 { 1761 "ietf-dots-data-channel:dots-client": [ 1762 { 1763 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1764 "cdid": "7eeaf349529eb55ed50113" 1765 } 1766 ] 1767 } 1769 Figure 13: POST to Register (DOTS gateway) 1771 As a reminder, DOTS gateways may rewrite the 'cuid' used by peer DOTS 1772 clients (Section 4.4.1 of [I-D.ietf-dots-signal-channel]). 1774 DOTS servers can identify the DOTS client domain using the 'cdid' 1775 parameter or using the client's DNS name specified in the Subject 1776 Alternative Name extension's dNSName type or SRV-ID in the client 1777 certificate. 1779 DOTS servers MUST limit the number of 'dots-client' resources to be 1780 created by the same DOTS client to 1 per request. Requests with 1781 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1782 To that aim, the DOTS server MUST rely on the same procedure to 1783 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1784 [I-D.ietf-dots-signal-channel]. 1786 The DOTS server indicates the result of processing the POST request 1787 using status-line codes. Status codes in the range "2xx" codes are 1788 success, "4xx" codes are some sort of invalid requests and "5xx" 1789 codes are returned if the DOTS server has erred or is incapable of 1790 accepting the creation of the 'dots-client' resource. In particular, 1792 o "201 Created" status-line is returned in the response, if the DOTS 1793 server has accepted the request. 1795 o "400 Bad Request" status-line is returned by the DOTS server, if 1796 the request does not include a 'cuid' parameter. The error-tag 1797 "missing-attribute" is used in this case. 1799 o "409 Conflict" status-line is returned to the requesting DOTS 1800 client, if the data resource already exists. The error-tag 1801 "resource-denied" is used in this case. 1803 Once a DOTS client registers itself to a DOTS server, it can 1804 create/delete/retrieve aliases (Section 6) and filtering rules 1805 (Section 7). 1807 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1808 register a DOTS client within the DOTS server. An example is shown 1809 in Figure 14. 1811 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1812 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1813 Host: example.com 1814 Content-Type: application/yang-data+json 1815 { 1816 "ietf-dots-data-channel:dots-client": [ 1817 { 1818 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1819 } 1820 ] 1821 } 1823 Figure 14: PUT to Register 1825 The DOTS gateway, that inserted a 'cdid' in a PUT request, MUST strip 1826 the 'cdid' parameter in the corresponding response before forwarding 1827 the response to the DOTS client. 1829 5.2. Unregistering DOTS Clients 1831 A DOTS client de-registers from its DOTS server(s) by deleting the 1832 'cuid' resource(s). Resources bound to this DOTS client will be 1833 deleted by the DOTS server. An example of a de-register request is 1834 shown in Figure 15. 1836 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1837 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1838 Host: example.com 1840 Figure 15: De-register a DOTS Client 1842 6. Managing DOTS Aliases 1844 The following sub-sections define means for a DOTS client to create 1845 aliases (Section 6.1), retrieve one or a list of aliases 1846 (Section 6.2), and delete an alias (Section 6.3). 1848 6.1. Create Aliases 1850 A POST or PUT request is used by a DOTS client to create aliases, for 1851 resources for which a mitigation may be requested. Such aliases may 1852 be used in subsequent DOTS signal channel exchanges to refer more 1853 efficiently to the resources under attack. 1855 DOTS clients within the same domain can create different aliases for 1856 the same resource. 1858 The structure of POST requests used to create aliases is shown in 1859 Figure 16. 1861 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1862 /dots-client=cuid HTTP/1.1 1863 Host: {host}:{port} 1864 Content-Type: application/yang-data+json 1865 { 1866 "ietf-dots-data-channel:aliases": { 1867 "alias": [ 1868 { 1869 "name": "string", 1870 "target-prefix": [ 1871 "string" 1872 ], 1873 "target-port-range": [ 1874 { 1875 "lower-port": integer, 1876 "upper-port": integer 1877 } 1878 ], 1879 "target-protocol": [ 1880 integer 1881 ], 1882 "target-fqdn": [ 1883 "string" 1884 ], 1885 "target-uri": [ 1886 "string" 1887 ] 1888 } 1889 ] 1890 } 1891 } 1893 Figure 16: POST to Create Aliases (Request Schema) 1895 The parameters are described below: 1897 name: Name of the alias. 1899 This is a mandatory attribute. 1901 target-prefix: Prefixes are separated by commas. Prefixes are 1902 represented using Classless Inter-domain Routing (CIDR) notation 1903 [RFC4632]. As a reminder, the prefix length must be less than or 1904 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1906 The prefix list MUST NOT include broadcast, loopback, or multicast 1907 addresses. These addresses are considered as invalid values. In 1908 addition, the DOTS server MUST validate that these prefixes are 1909 within the scope of the DOTS client's domain. Other validation 1910 checks may be supported by DOTS servers. 1912 This is an optional attribute. 1914 target-port-range: A range of port numbers. 1916 The port range is defined by two bounds, a lower port number 1917 (lower-port) and an upper port number (upper-port). The range is 1918 considered to include both the lower and upper bounds. 1920 When only 'lower-port' is present, it represents a single port 1921 number. 1923 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1924 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1925 [RFC4340], the range of port numbers can be, for example, 1926 1024-65535. 1928 This is an optional attribute. 1930 target-protocol: A list of protocols. Values are taken from the 1931 IANA protocol registry [proto_numbers]. 1933 If 'target-protocol' is not specified, then the request applies to 1934 any protocol. 1936 This is an optional attribute. 1938 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 1939 identifying resources under attack [RFC8499]. 1941 How a name is passed to an underlying name resolution library is 1942 implementation- and deployment-specific. Nevertheless, once the 1943 name is resolved into one or multiple IP addresses, DOTS servers 1944 MUST apply the same validation checks as those for 'target- 1945 prefix'. 1947 The use of FQDNs may be suboptimal because it does not guarantee 1948 that the DOTS server will resolve a name to the same IP addresses 1949 that the DOTS client does. 1951 This is an optional attribute. 1953 target-uri: A list of Uniform Resource Identifiers (URIs) 1954 [RFC3986]. 1956 The same validation checks used for 'target-fqdn' MUST be followed 1957 by DOTS servers to validate a target URI. 1959 This is an optional attribute. 1961 In POST or PUT requests, at least one of the 'target-prefix', 1962 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1963 agents can safely ignore Vendor-Specific parameters they don't 1964 understand. 1966 If more than one 'target-*' scope types (e.g., 'target-prefix' and 1967 'target-fqdn' or 'target-fqdn' and 'target-uri') are included in a 1968 POST or PUT request, the DOTS server binds all resulting IP 1969 addresses/prefixes to the same resource. 1971 Figure 17 shows a POST request to create an alias called "https1" for 1972 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1973 listening on TCP port number 443. 1975 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1976 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1977 Host: www.example.com 1978 Content-Type: application/yang-data+json 1979 { 1980 "ietf-dots-data-channel:aliases": { 1981 "alias": [ 1982 { 1983 "name": "https1", 1984 "target-protocol": [ 1985 6 1986 ], 1987 "target-prefix": [ 1988 "2001:db8:6401::1/128", 1989 "2001:db8:6401::2/128" 1990 ], 1991 "target-port-range": [ 1992 { 1993 "lower-port": 443 1994 } 1995 ] 1996 } 1997 ] 1998 } 1999 } 2001 Figure 17: Example of a POST to Create an Alias 2003 "201 Created" status-line MUST be returned in the response if the 2004 DOTS server has accepted the alias. 2006 "409 Conflict" status-line MUST be returned to the requesting DOTS 2007 client, if the request is conflicting with an existing alias name. 2008 The error-tag "resource-denied" is used in this case. 2010 If the request is missing a mandatory attribute or its contains an 2011 invalid or unknown parameter, "400 Bad Request" status-line MUST be 2012 returned by the DOTS server. The error-tag is set to "missing- 2013 attribute", "invalid-value", or "unknown-element" as a function of 2014 the encountered error. 2016 If the request is received via a server-domain DOTS gateway, but the 2017 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2018 is expected to be supplied, the DOTS server MUST reply with "403 2019 Forbidden" status-line and the error-tag "access-denied". Upon 2020 receipt of this message, the DOTS client MUST register (Section 5). 2022 A DOTS client uses the PUT request to modify the aliases in the DOTS 2023 server. In particular, a DOTS client MUST update its alias entries 2024 upon change of the prefix indicated in the 'target-prefix'. 2026 A DOTS server MUST maintain an alias for at least 10080 minutes (1 2027 week). If no refresh request is seen from the DOTS client, the DOTS 2028 server removes expired entries. 2030 6.2. Retrieve Installed Aliases 2032 A GET request is used to retrieve one or all installed aliases by a 2033 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 2034 'name' is included in the request, this is an indication that the 2035 request is about retrieving all aliases instantiated by the DOTS 2036 client. 2038 Figure 18 shows an example to retrieve all the aliases that were 2039 instantiated by the requesting DOTS client. The "content" query 2040 parameter and its permitted values are defined in Section 4.8.1 of 2041 [RFC8040]. 2043 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2044 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2045 /aliases?content=all HTTP/1.1 2046 Host: example.com 2047 Accept: application/yang-data+json 2049 Figure 18: GET to Retrieve All Installed Aliases 2051 Figure 19 shows an example of the response message body that includes 2052 all the aliases that are maintained by the DOTS server for the DOTS 2053 client identified by the 'cuid' parameter. 2055 { 2056 "ietf-dots-data-channel:aliases": { 2057 "alias": [ 2058 { 2059 "name": "Server1", 2060 "target-protocol": [ 2061 6 2062 ], 2063 "target-prefix": [ 2064 "2001:db8:6401::1/128", 2065 "2001:db8:6401::2/128" 2066 ], 2067 "target-port-range": [ 2068 { 2069 "lower-port": 443 2070 } 2071 ], 2072 "pending-lifetime": 3596 2073 }, 2074 { 2075 "name": "Server2", 2076 "target-protocol": [ 2077 6 2078 ], 2079 "target-prefix": [ 2080 "2001:db8:6401::10/128", 2081 "2001:db8:6401::20/128" 2082 ], 2083 "target-port-range": [ 2084 { 2085 "lower-port": 80 2086 } 2087 ], 2088 "pending-lifetime": 9869 2089 } 2090 ] 2091 } 2092 } 2094 Figure 19: An Example of Response Body Listing All Installed Aliases 2096 Figure 20 shows an example of a GET request to retrieve the alias 2097 "Server2" that was instantiated by the DOTS client. 2099 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2100 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2101 /aliases/alias=Server2?content=all HTTP/1.1 2102 Host: example.com 2103 Accept: application/yang-data+json 2105 Figure 20: GET to Retrieve an Alias 2107 If an alias name ('name') is included in the request, but the DOTS 2108 server does not find that alias name for this DOTS client in its 2109 configuration data, it MUST respond with a "404 Not Found" status- 2110 line. 2112 6.3. Delete Aliases 2114 A DELETE request is used to delete an alias maintained by a DOTS 2115 server. 2117 If the DOTS server does not find the alias name, conveyed in the 2118 DELETE request, in its configuration data for this DOTS client, it 2119 MUST respond with a "404 Not Found" status-line. 2121 The DOTS server successfully acknowledges a DOTS client's request to 2122 remove the alias using "204 No Content" status-line in the response. 2124 Figure 21 shows an example of a request to delete an alias. 2126 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2127 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2128 /aliases/alias=Server1 HTTP/1.1 2129 Host: example.com 2131 Figure 21: Delete an Alias 2133 7. Managing DOTS Filtering Rules 2135 The following sub-sections define means for a DOTS client to retrieve 2136 DOTS filtering capabilities (Section 7.1), create filtering rules 2137 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2138 delete a filtering rule (Section 7.4). 2140 7.1. Retrieve DOTS Filtering Capabilities 2142 A DOTS client MAY send a GET request to retrieve the filtering 2143 capabilities supported by a DOTS server. Figure 22 shows an example 2144 of such request. 2146 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2147 /capabilities HTTP/1.1 2148 Host: example.com 2149 Accept: application/yang-data+json 2151 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2153 A DOTS client which issued a GET request to retrieve the filtering 2154 capabilities supported by its DOTS server, SHOULD NOT request for 2155 filtering actions that are not supported by that DOTS server. 2157 Figure 23 shows an example of a response received from a DOTS server 2158 which supports: 2160 o IPv4, IPv6, TCP, UDP, ICMP, and ICMPv6 mandatory match criteria 2161 listed in Section 4.2. 2163 o 'accept', 'drop', and 'rate-limit' actions. 2165 Content-Type: application/yang-data+json 2166 { 2167 "ietf-dots-data-channel:capabilities": { 2168 "address-family": ["ipv4", "ipv6"], 2169 "forwarding-actions": ["drop", "accept"], 2170 "rate-limit": true, 2171 "transport-protocols": [1, 6, 17, 58], 2172 "ipv4": { 2173 "length": true, 2174 "protocol": true, 2175 "destination-prefix": true, 2176 "source-prefix": true, 2177 "fragment": true 2178 }, 2179 "ipv6": { 2180 "length": true, 2181 "protocol": true, 2182 "destination-prefix": true, 2183 "source-prefix": true, 2184 "fragment": true 2185 }, 2186 "tcp": { 2187 "flags-bitmask": true, 2188 "source-port": true, 2189 "destination-port": true, 2190 "port-range": true 2191 }, 2192 "udp": { 2193 "length": true, 2194 "source-port": true, 2195 "destination-port": true, 2196 "port-range": true 2197 }, 2198 "icmp": { 2199 "type": true, 2200 "code": true 2201 } 2202 } 2203 } 2205 Figure 23: Reply to a GET Request with Filtering Capabilities 2207 7.2. Install Filtering Rules 2209 A POST or PUT request is used by a DOTS client to communicate 2210 filtering rules to a DOTS server. 2212 Figure 24 shows a POST request example to block traffic from 2213 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2214 discussed in Appendix A. 2216 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2217 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2218 Host: example.com 2219 Content-Type: application/yang-data+json 2220 { 2221 "ietf-dots-data-channel:acls": { 2222 "acl": [ 2223 { 2224 "name": "sample-ipv4-acl", 2225 "type": "ipv4-acl-type", 2226 "activation-type": "activate-when-mitigating", 2227 "aces": { 2228 "ace": [ 2229 { 2230 "name": "rule1", 2231 "matches": { 2232 "ipv4": { 2233 "destination-ipv4-network": "198.51.100.0/24", 2234 "source-ipv4-network": "192.0.2.0/24" 2235 } 2236 }, 2237 "actions": { 2238 "forwarding": "drop" 2239 } 2240 } 2241 ] 2242 } 2243 } 2244 ] 2245 } 2246 } 2248 Figure 24: POST to Install Filtering Rules 2250 The meaning of these parameters is as follows: 2252 name: The name of the access list. 2254 This is a mandatory attribute. 2256 type: Indicates the primary intended type of match criteria (e.g., 2257 IPv4, IPv6). It is set to 'ipv4-acl-type' in the example of 2258 Figure 24. 2260 This is an optional attribute. 2262 activation-type: Indicates whether an ACL has to be activated 2263 (immediately or during mitigation time) or instantiated without 2264 being activated (deactivated). Deactivated ACLs can be activated 2265 using a variety of means such as manual configuration on a DOTS 2266 server or using the DOTS data channel. 2268 If this attribute is not provided, the DOTS server MUST use 2269 'activate-when-mitigating' as default value. 2271 When a mitigation is in progress, the DOTS server MUST only 2272 activate 'activate-when-mitigating' filters that are bound to the 2273 DOTS client that triggered the mitigation. 2275 This is an optional attribute. 2277 matches: Define criteria used to identify a flow on which to apply 2278 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2279 The detailed match parameters are specified in Section 4. 2281 In the example depicted in Figure 24, an IPv4 matching criteria is 2282 used. 2284 This is an optional attribute. 2286 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2287 MUST validate that these prefixes are within the scope of the DOTS 2288 client's domain. Other validation checks may be supported by DOTS 2289 servers. If this attribute is not provided, the DOTS server 2290 enforces the ACL on any destination IP address that belong to the 2291 DOTS client's domain. 2293 This is a mandatory attribute in requests with an 'activation- 2294 type' set to 'immediate'. 2296 source-ipv4-network: The source IPv4 prefix. 2298 This is an optional attribute. 2300 actions: Actions in the forwarding ACL category can be "drop" or 2301 "accept". The "accept" action is used to accept-list traffic. 2302 The "drop" action is used to drop-list traffic. 2304 Accepted traffic may be subject to "rate-limit"; the allowed 2305 traffic rate is represented in bytes per second. This unit is the 2306 same as the one used for "traffic-rate" in [RFC5575]. 2308 This is a mandatory attribute. 2310 The DOTS server indicates the result of processing the POST request 2311 using the status-line header. Concretely, "201 Created" status-line 2312 MUST be returned in the response if the DOTS server has accepted the 2313 filtering rules. If the request is missing a mandatory attribute or 2314 contains an invalid or unknown parameter (e.g., a match field not 2315 supported by the DOTS server), "400 Bad Request" status-line MUST be 2316 returned by the DOTS server in the response. The error-tag is set to 2317 "missing-attribute", "invalid-value", or "unknown-element" as a 2318 function of the encountered error. 2320 If the request is received via a server-domain DOTS gateway, but the 2321 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2322 is expected to be supplied, the DOTS server MUST reply with "403 2323 Forbidden" status-line and the error-tag "access-denied". Upon 2324 receipt of this message, the DOTS client MUST register (Figure 11). 2326 If the request is conflicting with an existing filtering installed by 2327 another DOTS client of the domain, absent any local policy, the DOTS 2328 server returns "409 Conflict" status-line to the requesting DOTS 2329 client. The error-tag "resource-denied" is used in this case. 2331 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2332 to specify how an access control entry is inserted within an ACL and 2333 how an ACL is inserted within an ACL set. 2335 The DOTS client uses the PUT request to modify its filtering rules 2336 maintained by the DOTS server. In particular, a DOTS client MUST 2337 update its filtering entries upon change of the destination-prefix. 2338 How such change is detected is out of scope. 2340 A DOTS server MUST maintain a filtering rule for at least 10080 2341 minutes (1 week). If no refresh request is seen from the DOTS 2342 client, the DOTS server removes expired entries. Typically, a 2343 refresh request is a PUT request which echoes the content of a 2344 response to a GET request with all of the read-only parameters 2345 stripped out (e.g., pending-lifetime). 2347 7.3. Retrieve Installed Filtering Rules 2349 A DOTS client periodically queries its DOTS server to check the 2350 counters for installed filtering rules. A GET request is used to 2351 retrieve filtering rules from a DOTS server. In order to indicate 2352 which type of data is requested in a GET request, the DOTS client 2353 sets adequately the "content" query parameter. 2355 If the DOTS server does not find the access list name conveyed in the 2356 GET request in its configuration data for this DOTS client, it 2357 responds with a "404 Not Found" status-line. 2359 In order to illustrate the intended behavior, consider the example 2360 depicted in Figure 25. In reference to this example, the DOTS client 2361 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2363 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2364 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2365 /acl=test-acl-ipv6-udp HTTP/1.1 2366 Host: example.com 2367 Content-Type: application/yang-data+json 2368 { 2369 "ietf-dots-data-channel:acls": { 2370 "acl": [ 2371 { 2372 "name": "test-acl-ipv6-udp", 2373 "type": "ipv6-acl-type", 2374 "activation-type": "immediate", 2375 "aces": { 2376 "ace": [ 2377 { 2378 "name": "my-test-ace", 2379 "matches": { 2380 "ipv6": { 2381 "destination-ipv6-network": "2001:db8:6401::2/127", 2382 "source-ipv6-network": "2001:db8:1234::/96", 2383 "protocol": 17, 2384 "flow-label": 10000 2385 }, 2386 "udp": { 2387 "source-port": { 2388 "operator": "lte", 2389 "port": 80 2390 }, 2391 "destination-port": { 2392 "operator": "neq", 2393 "port": 1010 2394 } 2395 } 2396 }, 2397 "actions": { 2398 "forwarding": "accept" 2399 } 2400 } 2401 ] 2402 } 2403 } 2404 ] 2405 } 2406 } 2408 Figure 25: Example of a PUT Request to Create a Filtering 2410 The peer DOTS server follows the procedure specified in Section 7.2 2411 to process the request. We consider in the following that a positive 2412 response is sent back to the requesting DOTS client to confirm that 2413 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2414 server. 2416 The DOTS client can issue a GET request to retrieve all its filtering 2417 rules and the number of matches for the installed filtering rules as 2418 illustrated in Figure 26. The "content" query parameter is set to 2419 'all'. The message body of the response to this GET request is shown 2420 in Figure 27. 2422 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2423 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2424 /acls?content=all HTTP/1.1 2425 Host: example.com 2426 Accept: application/yang-data+json 2428 Figure 26: Retrieve the Configuration Data and State Data for the 2429 Filtering Rules (GET Request) 2431 { 2432 "ietf-dots-data-channel:acls": { 2433 "acl": [ 2434 { 2435 "name": "test-acl-ipv6-udp", 2436 "type": "ipv6-acl-type", 2437 "activation-type": "immediate", 2438 "pending-lifetime":9080, 2439 "aces": { 2440 "ace": [ 2441 { 2442 "name": "my-test-ace", 2443 "matches": { 2444 "ipv6": { 2445 "destination-ipv6-network": "2001:db8:6401::2/127", 2446 "source-ipv6-network": "2001:db8:1234::/96", 2447 "protocol": 17, 2448 "flow-label": 10000 2449 }, 2450 "udp": { 2451 "source-port": { 2452 "operator": "lte", 2453 "port": 80 2454 }, 2455 "destination-port": { 2456 "operator": "neq", 2457 "port": 1010 2458 } 2459 } 2460 }, 2461 "actions": { 2462 "forwarding": "accept" 2463 } 2464 } 2465 ] 2466 } 2467 } 2468 ] 2469 } 2470 } 2472 Figure 27: Retrieve the Configuration Data and State Data for the 2473 Filtering Rules (Response Message Body) 2475 Also, a DOTS client can issue a GET request to retrieve only 2476 configuration data related to an ACL as shown in Figure 28. It does 2477 so by setting the "content" query parameter to 'config'. 2479 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2480 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2481 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2482 Host: example.com 2483 Accept: application/yang-data+json 2485 Figure 28: Retrieve the Configuration Data for a Filtering Rule (GET 2486 Request) 2488 A response to this GET request is shown in Figure 29. 2490 { 2491 "ietf-dots-data-channel:acls": { 2492 "acl": [ 2493 { 2494 "name": "test-acl-ipv6-udp", 2495 "type": "ipv6-acl-type", 2496 "activation-type": "immediate", 2497 "aces": { 2498 "ace": [ 2499 { 2500 "name": "my-test-ace", 2501 "matches": { 2502 "ipv6": { 2503 "destination-ipv6-network": "2001:db8:6401::2/127", 2504 "source-ipv6-network": "2001:db8:1234::/96", 2505 "protocol": 17, 2506 "flow-label": 10000 2507 }, 2508 "udp": { 2509 "source-port": { 2510 "operator": "lte", 2511 "port": 80 2512 }, 2513 "destination-port": { 2514 "operator": "neq", 2515 "port": 1010 2516 } 2517 } 2518 }, 2519 "actions": { 2520 "forwarding": "accept" 2521 } 2522 } 2523 ] 2524 } 2525 } 2526 ] 2527 } 2528 } 2530 Figure 29: Retrieve the Configuration Data for a Filtering Rule 2531 (Response Message Body) 2533 A DOTS client can also issue a GET request with a "content" query 2534 parameter set to 'non-config' to exclusively retrieve non- 2535 configuration data bound to a given ACL as shown in Figure 28. A 2536 response to this GET request is shown in Figure 31. 2538 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2539 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2540 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2541 Host: example.com 2542 Accept: application/yang-data+json 2544 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule 2545 (GET Request) 2547 { 2548 "ietf-dots-data-channel:acls": { 2549 "acl": [ 2550 { 2551 "name": "test-acl-ipv6-udp", 2552 "pending-lifetime": 8000, 2553 "aces": { 2554 "ace": [ 2555 { 2556 "name": "my-test-ace" 2557 } 2558 ] 2559 } 2560 } 2561 ] 2562 } 2563 } 2565 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule 2566 (Response Message Body) 2568 7.4. Remove Filtering Rules 2570 A DELETE request is used by a DOTS client to delete filtering rules 2571 from a DOTS server. 2573 If the DOTS server does not find the access list name carried in the 2574 DELETE request in its configuration data for this DOTS client, it 2575 MUST respond with a "404 Not Found" status-line. The DOTS server 2576 successfully acknowledges a DOTS client's request to withdraw the 2577 filtering rules using "204 No Content" status-line, and removes the 2578 filtering rules accordingly. 2580 Figure 32 shows an example of a request to remove the IPv4 ACL 2581 "sample-ipv4-acl" created in Section 7.2. 2583 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2584 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2585 /acl=sample-ipv4-acl HTTP/1.1 2586 Host: example.com 2588 Figure 32: Remove a Filtering Rule (DELETE Request) 2590 Figure 33 shows an example of a response received from the DOTS 2591 server to confirm the deletion of "sample-ipv4-acl". 2593 HTTP/1.1 204 No Content 2594 Server: Apache 2595 Date: Fri, 27 Jul 2018 10:05:15 GMT 2596 Cache-Control: no-cache 2597 Content-Type: application/yang-data+json 2598 Content-Length: 0 2599 Connection: Keep-Alive 2601 Figure 33: Remove a Filtering Rule (Response) 2603 8. Operational Considerations 2605 The following operational considerations should be taken into 2606 account: 2608 o DOTS servers MUST NOT enable both DOTS data channel and direct 2609 configuration, to avoid race conditions and inconsistent 2610 configurations arising from simultaneous updates from multiple 2611 sources. 2613 o DOTS agents SHOULD enable the DOTS data channel to configure 2614 aliases and ACLs, and only use direct configuration as a stop-gap 2615 mechanism to test DOTS signal channel with aliases and ACLs. 2616 Further, direct configuration SHOULD only be used when the on-path 2617 DOTS agents are within the same domain. 2619 o If a DOTS server has enabled direct configuration, it can reject 2620 the DOTS data channel connection using hard ICMP error [RFC1122] 2621 or RST (Reset) bit in the TCP header or reject the RESTCONF 2622 request using an error response containing a "503 Service 2623 Unavailable" status-line. 2625 9. IANA Considerations 2627 This document requests IANA to register the following URI in the "ns" 2628 subregistry within the "IETF XML Registry" [RFC3688]: 2630 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2631 Registrant Contact: The IESG. 2632 XML: N/A; the requested URI is an XML namespace. 2634 This document requests IANA to register the following YANG module in 2635 the "YANG Module Names" subregistry [RFC7950] within the "YANG 2636 Parameters" registry. 2638 name: ietf-dots-data-channel 2639 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2640 prefix: data-channel 2641 reference: RFC XXXX 2643 This module is not maintained by IANA. 2645 10. Security Considerations 2647 RESTCONF security considerations are discussed in [RFC8040]. In 2648 particular, DOTS agents MUST follow the security recommendations in 2649 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2650 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2651 [I-D.ietf-dots-signal-channel]. 2653 Authenticated encryption MUST be used for data confidentiality and 2654 message integrity. The interaction between the DOTS agents requires 2655 Transport Layer Security (TLS) with a cipher suite offering 2656 confidentiality protection and the guidance given in [RFC7525] MUST 2657 be followed to avoid attacks on TLS. 2659 The installation of drop- or accept-list rules using RESTCONF over 2660 TLS reveals the attacker IP addresses and legitimate IP addresses 2661 only to the DOTS server trusted by the DOTS client. The secure 2662 communication channel between DOTS agents provides privacy and 2663 prevents a network eavesdropper from directly gaining access to the 2664 drop- and accept-listed IP addresses. 2666 An attacker may be able to inject RST packets, bogus application 2667 segments, etc., regardless of whether TLS authentication is used. 2668 Because the application data is TLS protected, this will not result 2669 in the application receiving bogus data, but it will constitute a DoS 2670 on the connection. This attack can be countered by using TCP-AO 2671 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2672 attacker will be rejected by the TCP-AO integrity check and therefore 2673 will never reach the TLS layer. 2675 In order to prevent leaking internal information outside a client- 2676 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2677 internal DOTS clients (e.g., source IP address, client's hostname) 2678 unless explicitly configured to do so. 2680 DOTS servers MUST verify that requesting DOTS clients are entitled to 2681 enforce filtering rules on a given IP prefix. That is, only 2682 filtering rules on IP resources that belong to the DOTS client's 2683 domain can be authorized by a DOTS server. The exact mechanism for 2684 the DOTS servers to validate that the target prefixes are within the 2685 scope of the DOTS client's domain is deployment-specific. 2687 Rate-limiting DOTS requests, including those with new 'cuid' values, 2688 from the same DOTS client defends against DoS attacks that would 2689 result from varying the 'cuid' to exhaust DOTS server resources. 2690 Rate-limit policies SHOULD be enforced on DOTS gateways (if deployed) 2691 and DOTS servers. 2693 Applying resources quota per DOTS client and/or per DOTS client 2694 domain (e.g., limit the number of aliases and filters to be installed 2695 by DOTS clients) prevents DOTS server resources to be aggressively 2696 used by some DOTS clients and ensures, therefore, DDoS mitigation 2697 usage fairness. Additionally, DOTS servers may limit the number of 2698 DOTS clients that can be enabled per domain. 2700 The presence of DOTS gateways may lead to infinite forwarding loops, 2701 which is undesirable. To prevent and detect such loops, a mechanism 2702 is defined in Section 3.4. 2704 All data nodes defined in the YANG module which can be created, 2705 modified, and deleted (i.e., config true, which is the default) are 2706 considered sensitive. Write operations applied to these data nodes 2707 without proper protection can negatively affect network operations. 2708 This module reuses YANG structures from [I-D.ietf-netmod-acl-model], 2709 and the security considerations for those nodes continue to apply for 2710 this usage. Appropriate security measures are recommended to prevent 2711 illegitimate users from invoking DOTS data channel primitives. 2712 Nevertheless, an attacker who can access a DOTS client is technically 2713 capable of launching various attacks, such as: 2715 o Setting an arbitrarily low rate-limit, which may prevent 2716 legitimate traffic from being forwarded (rate-limit). 2718 o Setting an arbitrarily high rate-limit, which may lead to the 2719 forwarding of illegitimate DDoS traffic (rate-limit). 2721 o Communicating invalid aliases to the server (alias), which will 2722 cause the failure of associating both data and signal channels. 2724 o Setting invalid ACL entries, which may prevent legitimate traffic 2725 from being forwarded. Likewise, invalid ACL entries may lead to 2726 forward DDoS traffic. 2728 11. Contributing Authors 2730 The following individuals co-authored this document: 2732 Kaname Nishizuka 2733 NTT Communications 2734 GranPark 16F 3-4-1 Shibaura, Minato-ku 2735 Tokyo 108-8118 2736 Japan 2738 Email: kaname@nttv6.jp 2740 Liang Xia 2741 Huawei 2742 101 Software Avenue, Yuhuatai District 2743 Nanjing, Jiangsu 210012 2744 China 2746 Email: frank.xialiang@huawei.com 2748 Prashanth Patil 2749 Cisco Systems, Inc. 2751 Email: praspati@cisco.com 2753 Andrew Mortensen 2754 Arbor Networks, Inc. 2755 2727 S. State St 2756 Ann Arbor, MI 48104 2757 United States 2759 Email: andrew.mortensen@netscout.com 2761 Nik Teague 2762 Verisign, Inc. 2763 United States 2765 Email: nteague@verisign.com 2767 12. Contributors 2769 The following individuals have contributed to this document: 2771 o Dan Wing, Email: dwing-ietf@fuggles.com 2773 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.com 2775 13. Acknowledgements 2777 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2778 Doron, Russ White, Gilbert Clark, Kathleen Moriarty, and Nesredien 2779 Suleiman for the discussion and comments. 2781 The authors would like to give special thanks to Kaname Nishizuka and 2782 Jon Shallow for their efforts in implementing the protocol and 2783 performing interop testing at IETF Hackathons. 2785 Many thanks to Ben Kaduk for the detailed AD review. 2787 Thanks to Martin Bjorklund for the guidance on RESTCONF. 2789 14. References 2791 14.1. Normative References 2793 [I-D.ietf-dots-signal-channel] 2794 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 2795 Teague, "Distributed Denial-of-Service Open Threat 2796 Signaling (DOTS) Signal Channel Specification", draft- 2797 ietf-dots-signal-channel-28 (work in progress), January 2798 2019. 2800 [I-D.ietf-netmod-acl-model] 2801 Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, 2802 "Network Access Control List (ACL) YANG Data Model", 2803 draft-ietf-netmod-acl-model-21 (work in progress), 2804 November 2018. 2806 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2807 Requirement Levels", BCP 14, RFC 2119, 2808 DOI 10.17487/RFC2119, March 1997, 2809 . 2811 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2812 DOI 10.17487/RFC3688, January 2004, 2813 . 2815 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2816 (CIDR): The Internet Address Assignment and Aggregation 2817 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2818 2006, . 2820 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2821 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2822 . 2824 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2825 Protocol (HTTP/1.1): Message Syntax and Routing", 2826 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2827 . 2829 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2830 "Recommendations for Secure Use of Transport Layer 2831 Security (TLS) and Datagram Transport Layer Security 2832 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2833 2015, . 2835 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2836 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2837 . 2839 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2840 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2841 . 2843 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2844 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2845 . 2847 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2848 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2849 May 2017, . 2851 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2852 Interchange Format", STD 90, RFC 8259, 2853 DOI 10.17487/RFC8259, December 2017, 2854 . 2856 14.2. Informative References 2858 [I-D.ietf-dots-architecture] 2859 Mortensen, A., Andreasen, F., K, R., Teague, N., Compton, 2860 R., and c. christopher_gray3@cable.comcast.com, 2861 "Distributed-Denial-of-Service Open Threat Signaling 2862 (DOTS) Architecture", draft-ietf-dots-architecture-11 2863 (work in progress), February 2019. 2865 [I-D.ietf-dots-requirements] 2866 Mortensen, A., K, R., and R. Moskowitz, "Distributed 2867 Denial of Service (DDoS) Open Threat Signaling 2868 Requirements", draft-ietf-dots-requirements-18 (work in 2869 progress), February 2019. 2871 [proto_numbers] 2872 "IANA, "Protocol Numbers"", 2011, 2873 . 2875 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2876 Communication Layers", STD 3, RFC 1122, 2877 DOI 10.17487/RFC1122, October 1989, 2878 . 2880 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2881 Resource Identifier (URI): Generic Syntax", STD 66, 2882 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2883 . 2885 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2886 Congestion Control Protocol (DCCP)", RFC 4340, 2887 DOI 10.17487/RFC4340, March 2006, 2888 . 2890 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2891 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2892 . 2894 [RFC5575] Marques, P., Sheth, N., Raszuk, R., Greene, B., Mauch, J., 2895 and D. McPherson, "Dissemination of Flow Specification 2896 Rules", RFC 5575, DOI 10.17487/RFC5575, August 2009, 2897 . 2899 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2900 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2901 June 2010, . 2903 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2904 Layer Security (TLS) and Datagram Transport Layer Security 2905 (DTLS) Heartbeat Extension", RFC 6520, 2906 DOI 10.17487/RFC6520, February 2012, 2907 . 2909 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2910 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2911 . 2913 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 2914 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 2915 January 2019, . 2917 Appendix A. Sample Examples: Filtering Fragments 2919 This specification strongly recommends the use of "fragment" for 2920 handling fragments. 2922 Figure 34 shows the content of the POST request to be issued by a 2923 DOTS client to its DOTS server to allow the traffic destined to 2924 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2925 packets. The following ACEs are defined (in this order): 2927 o "drop-all-fragments" ACE: discards all fragments. 2929 o "allow-dns-packets" ACE: accepts DNS packets destined to 2930 198.51.100.0/24. 2932 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2933 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2934 Host: example.com 2935 Content-Type: application/yang-data+json 2936 { 2937 "ietf-dots-data-channel:acls": { 2938 "acl": [ 2939 { 2940 "name": "dns-fragments", 2941 "type": "ipv4-acl-type", 2942 "aces": { 2943 "ace": [ 2944 { 2945 "name": "drop-all-fragments", 2946 "matches": { 2947 "ipv4": { 2948 "fragment": { 2949 "operator": "match", 2950 "type": "isf" 2952 } 2953 } 2954 }, 2955 "actions": { 2956 "forwarding": "drop" 2957 } 2958 } 2959 ] 2960 "ace": [ 2961 { 2962 "name": "allow-dns-packets", 2963 "matches": { 2964 "ipv4": { 2965 "destination-ipv4-network": "198.51.100.0/24" 2966 } 2967 "udp": { 2968 "destination-port": { 2969 "operator": "eq", 2970 "port": 53 2971 } 2972 }, 2973 "actions": { 2974 "forwarding": "accept" 2975 } 2976 } 2977 ] 2978 } 2979 } 2980 ] 2981 } 2982 } 2984 Figure 34: Filtering IPv4 Fragmented Packets 2986 Figure 35 shows a POST request example issued by a DOTS client to its 2987 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 2988 port number 53, but to drop all fragmented packets. The following 2989 ACEs are defined (in this order): 2991 o "drop-all-fragments" ACE: discards all fragments (including atomic 2992 fragments). That is, IPv6 packets which include a Fragment header 2993 (44) are dropped. 2995 o "allow-dns-packets" ACE: accepts DNS packets destined to 2996 2001:db8::/32. 2998 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2999 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 3001 Host: example.com 3002 Content-Type: application/yang-data+json 3003 { 3004 "ietf-dots-data-channel:acls": { 3005 "acl": [ 3006 { 3007 "name": "dns-fragments", 3008 "type": "ipv6-acl-type", 3009 "aces": { 3010 "ace": [ 3011 { 3012 "name": "drop-all-fragments", 3013 "matches": { 3014 "ipv6": { 3015 "fragment": { 3016 "operator": "match", 3017 "type": "isf" 3018 } 3019 } 3020 }, 3021 "actions": { 3022 "forwarding": "drop" 3023 } 3024 } 3025 ] 3026 "ace": [ 3027 { 3028 "name": "allow-dns-packets", 3029 "matches": { 3030 "ipv6": { 3031 "destination-ipv6-network": "2001:db8::/32" 3032 } 3033 "udp": { 3034 "destination-port": { 3035 "operator": "eq", 3036 "port": 53 3037 } 3038 } 3039 }, 3040 "actions": { 3041 "forwarding": "accept" 3042 } 3043 } 3044 ] 3045 } 3046 } 3047 ] 3048 } 3050 } 3052 Figure 35: Filtering IPv6 Fragmented Packets 3054 Authors' Addresses 3056 Mohamed Boucadair (editor) 3057 Orange 3058 Rennes 35000 3059 France 3061 Email: mohamed.boucadair@orange.com 3063 Tirumaleswar Reddy (editor) 3064 McAfee, Inc. 3065 Embassy Golf Link Business Park 3066 Bangalore, Karnataka 560071 3067 India 3069 Email: kondtir@gmail.com