idnits 2.17.1 draft-ietf-dots-data-channel-26.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 434 has weird spacing: '...er-port ine...' == Line 519 has weird spacing: '...warding ide...' == Line 817 has weird spacing: '... icmp typ...' -- The document date (February 18, 2019) is 1891 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 2172 -- Looks like a reference, but probably isn't: '6' on line 2172 -- Looks like a reference, but probably isn't: '17' on line 2172 -- Looks like a reference, but probably isn't: '58' on line 2172 == 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 22, 2019 McAfee 6 February 18, 2019 8 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 9 Specification 10 draft-ietf-dots-data-channel-26 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 22, 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 . . . . . . . . . . . . . . . . . . . . . . . 69 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-severity: error 380 error-info: : A copy of the Via header when 381 the loop was detected. 382 Description: An infinite loop has been detected when forwarding 383 a requests via a proxy. 385 Figure 3: Loop Detected Error 387 It is RECOMMENDED that DOTS clients and gateways support means to 388 alert administrators about loop errors so that appropriate actions 389 are undertaken. 391 o Otherwise, the DOTS agent MUST update or insert the "Via" header 392 by appending its own information. 394 Unless configured otherwise, DOTS gateways at the boundaries of a 395 DOTS client domain SHOULD remove the previous "Via" header 396 information after checking for a loop before forwarding. This 397 behavior is required for topology hiding purposes but can also serve 398 to minimize potential conflicts that may arise if overlapping 399 information is used in distinct DOTS domains (e.g., private IPv4 400 addresses, non globally unique aliases). 402 3.5. Stale Entries 404 In order to avoid stale entries, a lifetime is associated with alias 405 and filtering entries created by DOTS clients. Also, DOTS servers 406 may track the inactivity timeout of DOTS clients to detect stale 407 entries. 409 4. DOTS Data Channel YANG Module 411 4.1. Generic Tree Structure 413 The DOTS data channel YANG module (ietf-dots-data-channel) provides a 414 method for DOTS clients to manage aliases for resources for which 415 mitigation may be requested. Such aliases may be used in subsequent 416 DOTS signal channel exchanges to refer more efficiently to the 417 resources under attack. 419 Note that the full module's tree has been split across several 420 figures to aid the exposition of the various sub-trees. 422 The tree structure for the DOTS alias is depicted in Figure 4. 424 module: ietf-dots-data-channel 425 +--rw dots-data 426 +--rw dots-client* [cuid] 427 | +--rw cuid string 428 | +--rw cdid? string 429 | +--rw aliases 430 | | +--rw alias* [name] 431 | | +--rw name string 432 | | +--rw target-prefix* inet:ip-prefix 433 | | +--rw target-port-range* [lower-port] 434 | | | +--rw lower-port inet:port-number 435 | | | +--rw upper-port? inet:port-number 436 | | +--rw target-protocol* uint8 437 | | +--rw target-fqdn* inet:domain-name 438 | | +--rw target-uri* inet:uri 439 | | +--ro pending-lifetime? int32 440 | +--rw acls 441 | ... 442 +--ro capabilities 443 ... 445 Figure 4: DOTS Alias Subtree 447 Also, the 'ietf-dots-data-channel' module provides a method for DOTS 448 clients to manage filtering rules. Examples of filtering management 449 in a DOTS context include, but not limited to: 451 o Drop-list management, which enables a DOTS client to inform a DOTS 452 server about sources from which traffic should be discarded. 454 o Accept-list management, which enables a DOTS client to inform a 455 DOTS server about sources from which traffic should always be 456 accepted. 458 o Policy management, which enables a DOTS client to request the 459 installation or withdrawal of traffic filters, dropping or rate- 460 limiting unwanted traffic and permitting accept-listed traffic. 462 The tree structure for the DOTS filtering entries is depicted in 463 Figure 5. 465 Investigations into the prospect of augmenting 'ietf-access-control- 466 list' to meet DOTS requirements concluded that such a design approach 467 did not support many of the DOTS requirements, e.g., 469 o Retrieve a filtering entry (or all entries) created by a DOTS 470 client. 472 o Delete a filtering entry that was instantiated by a DOTS client. 474 Accordingly, new DOTS filtering entries (i.e., Access Control List 475 (ACL)) are defined that mimic the structure specified in 476 [I-D.ietf-netmod-acl-model]. Concretely, DOTS agents are assumed to 477 manipulate an ordered list of ACLs; each ACL contains a separately 478 ordered list of Access Control Entries (ACEs). Each ACE has a group 479 of match and a group of action criteria. 481 Once all the ACE entries have been iterated though with no match, 482 then all the following ACL's ACE entries are iterated through until 483 the first match at which point the specified action is applied. If 484 there is no match during peace time, then there is no further action 485 to be taken against the packet. If there is no match during active 486 mitigation, then the packet will still be scrubbed by the DDoS 487 mitigator. 489 module: ietf-dots-data-channel 490 +--rw dots-data 491 +--rw dots-client* [cuid] 492 | +--rw cuid string 493 | +--rw cdid? string 494 | +--rw aliases 495 | | ... 496 | +--rw acls 497 | +--rw acl* [name] 498 | +--rw name string 499 | +--rw type? ietf-acl:acl-type 500 | +--rw activation-type? activation-type 501 | +--ro pending-lifetime? int32 502 | +--rw aces 503 | +--rw ace* [name] 504 | +--rw name string 505 | +--rw matches 506 | | +--rw (l3)? 507 | | | +--:(ipv4) 508 | | | | ... 509 | | | +--:(ipv6) 510 | | | ... 511 | | +--rw (l4)? 512 | | +--:(tcp) 513 | | | ... 514 | | +--:(udp) 515 | | | ... 516 | | +--:(icmp) 517 | | ... 518 | +--rw actions 519 | | +--rw forwarding identityref 520 | | +--rw rate-limit? decimal64 521 | +--ro statistics 522 | +--ro matched-packets? yang:counter64 523 | +--ro matched-octets? yang:counter64 524 +--ro capabilities 525 ... 527 Figure 5: DOTS ACLs Subtree 529 Filtering rules instructed by a DOTS client assumes a default 530 direction: the destination is the DOTS client domain. 532 DOTS forwarding actions can be 'accept' (i.e., accept matching 533 traffic) or 'drop' (i.e., drop matching traffic without sending any 534 ICMP error message). Accepted traffic can be subject to rate- 535 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 536 matching traffic and send an ICMP error message to the source) is not 537 supported in 'ietf-dots-data-channel' because it is not appropriate 538 in the context of DDoS mitigation. Generating ICMP messages to 539 notify drops when mitigating a DDoS attack will exacerbate the DDoS 540 attack. Furthermore, these ICMP messages will be used by an attacker 541 as an explicit signal that the traffic is being blocked. 543 4.2. Filtering Fields 545 The 'ietf-dots-data-channel' module reuses the packet fields module 546 'ietf-packet-fields' [I-D.ietf-netmod-acl-model] which defines 547 matching on fields in the packet including IPv4, IPv6, and transport 548 layer fields. The 'ietf-dots-data-channel' module can be augmented, 549 for example, to support additional protocol-specific matching fields. 551 This specification defines a new IPv4/IPv6 matching field called 552 'fragment' to efficiently handle fragment-related filtering rules. 553 Indeed, [I-D.ietf-netmod-acl-model] does not support such capability 554 for IPv6 but offers a partial support for IPv4 by means of 'flags'. 555 Nevertheless, the use of 'flags' is problematic since it does not 556 allow to define a bitmask. For example, setting other bits not 557 covered by the 'flags' filtering clause in a packet will allow that 558 packet to get through (because it won't match the ACE). Sample 559 examples to illustrate how 'fragment' can be used are provided in 560 Appendix A. 562 Figure 6 shows the IPv4 match subtree. 564 module: ietf-dots-data-channel 565 +--rw dots-data 566 +--rw dots-client* [cuid] 567 | ... 568 | +--rw acls 569 | +--rw acl* [name] 570 | ... 571 | +--rw aces 572 | +--rw ace* [name] 573 | +--rw name string 574 | +--rw matches 575 | | +--rw (l3)? 576 | | | +--:(ipv4) 577 | | | | +--rw ipv4 578 | | | | +--rw dscp? inet:dscp 579 | | | | +--rw ecn? uint8 580 | | | | +--rw length? uint16 581 | | | | +--rw ttl? uint8 582 | | | | +--rw protocol? uint8 583 | | | | +--rw ihl? uint8 584 | | | | +--rw flags? bits 585 | | | | +--rw offset? uint16 586 | | | | +--rw identification? uint16 587 | | | | +--rw (destination-network)? 588 | | | | | +--:(destination-ipv4-network) 589 | | | | | +--rw destination-ipv4-network? 590 | | | | | inet:ipv4-prefix 591 | | | | +--rw (source-network)? 592 | | | | | +--:(source-ipv4-network) 593 | | | | | +--rw source-ipv4-network? 594 | | | | | inet:ipv4-prefix 595 | | | | +--rw fragment 596 | | | | +--rw operator? operator 597 | | | | +--rw type fragment-type 598 | | | +--:(ipv6) 599 | | | ... 600 | | +--rw (l4)? 601 | | ... 602 | +--rw actions 603 | | ... 604 | +--ro statistics 605 | ... 606 +--ro capabilities 607 ... 609 Figure 6: DOTS ACLs Subtree (IPv4 Match) 611 Figure 7 shows the IPv6 match subtree. 613 module: ietf-dots-data-channel 614 +--rw dots-data 615 +--rw dots-client* [cuid] 616 | ... 617 | +--rw acls 618 | +--rw acl* [name] 619 | ... 620 | +--rw aces 621 | +--rw ace* [name] 622 | +--rw name string 623 | +--rw matches 624 | | +--rw (l3)? 625 | | | +--:(ipv4) 626 | | | | ... 627 | | | +--:(ipv6) 628 | | | +--rw ipv6 629 | | | +--rw dscp? inet:dscp 630 | | | +--rw ecn? uint8 631 | | | +--rw length? uint16 632 | | | +--rw ttl? uint8 633 | | | +--rw protocol? uint8 634 | | | +--rw (destination-network)? 635 | | | | +--:(destination-ipv6-network) 636 | | | | +--rw destination-ipv6-network? 637 | | | | inet:ipv6-prefix 638 | | | +--rw (source-network)? 639 | | | | +--:(source-ipv6-network) 640 | | | | +--rw source-ipv6-network? 641 | | | | inet:ipv6-prefix 642 | | | +--rw flow-label? 643 | | | | inet:ipv6-flow-label 644 | | | +--rw fragment 645 | | | +--rw operator? operator 646 | | | +--rw type fragment-type 647 | | +--rw (l4)? 648 | | ... 649 | +--rw actions 650 | | ... 651 | +--ro statistics 652 | ... 653 +--ro capabilities 654 ... 656 Figure 7: DOTS ACLs Subtree (IPv6 Match) 658 Figure 8 shows the TCP match subtree. In addition to the fields 659 defined in [I-D.ietf-netmod-acl-model], this specification defines a 660 new TCP matching field, called 'flags-bitmask', to efficiently handle 661 TCP flags filtering rules. 663 module: ietf-dots-data-channel 664 +--rw dots-data 665 +-rw dots-client* [cuid] 666 | ... 667 | +-rw acls 668 | +-rw acl* [name] 669 | ... 670 | +-rw aces 671 | +-rw ace* [name] 672 | +-rw name string 673 | +-rw matches 674 | | +-rw (l3)? 675 | | | ... 676 | | +-rw (l4)? 677 | | +-:(tcp) 678 | | | +-rw tcp 679 | | | +--rw sequence-number? uint32 680 | | | +--rw acknowledgement-number? uint32 681 | | | +--rw data-offset? uint8 682 | | | +--rw reserved? uint8 683 | | | +--rw flags? bits 684 | | | +--rw window-size? uint16 685 | | | +--rw urgent-pointer? uint16 686 | | | +--rw options? binary 687 | | | +--rw flags-bitmask 688 | | | | +--rw operator? operator 689 | | | | +--rw bitmask uint16 690 | | | +--rw (source-port)? 691 | | | | +--:(source-port-range-or-operator) 692 | | | | +--rw source-port-range-or-operator 693 | | | | +--rw (port-range-or-operator)? 694 | | | | +--:(range) 695 | | | | | +--rw lower-port 696 | | | | | | inet:port-number 697 | | | | | +--rw upper-port 698 | | | | | inet:port-number 699 | | | | +--:(operator) 700 | | | | +--rw operator? 701 | | | | | operator 702 | | | | +--rw port 703 | | | | inet:port-number 704 | | | +--rw (destination-port)? 705 | | | +--:(destination-port-range-or-operator) 706 | | | +--rw destination-port-range-or-operator 707 | | | +--rw (port-range-or-operator)? 708 | | | +--:(range) 709 | | | | +--rw lower-port 710 | | | | | inet:port-number 711 | | | | +--rw upper-port 712 | | | | inet:port-number 713 | | | +--:(operator) 714 | | | +--rw operator? 715 | | | | operator 716 | | | +--rw port 717 | | | inet:port-number 718 | | +-:(udp) 719 | | | ... 720 | | +-:(icmp) 721 | | ... 722 | +-rw actions 723 | | ... 724 | +-ro statistics 725 | ... 726 +-ro capabilities 727 ... 729 Figure 8: DOTS ACLs Subtree (TCP Match) 731 Figure 9 shows the UDP and ICMP match subtrees. The same structure 732 is used for both ICMP and ICMPv6. The indication whether an ACL is 733 about ICMP or ICMPv6 is governed by the 'l3' match. 735 module: ietf-dots-data-channel 736 +-rw dots-data 737 +-rw dots-client* [cuid] 738 | ... 739 | +-rw acls 740 | +-rw acl* [name] 741 | ... 742 | +-rw aces 743 | +-rw ace* [name] 744 | +--rw name string 745 | +--rw matches 746 | | +--rw (l3)? 747 | | | ... 748 | | +--rw (l4)? 749 | | +--:(tcp) 750 | | | ... 751 | | +--:(udp) 752 | | | +--rw udp 753 | | | +--rw length? uint16 754 | | | +--rw (source-port)? 755 | | | | +--:(source-port-range-or-operator) 756 | | | | +--rw source-port-range-or-operator 757 | | | | +--rw (port-range-or-operator)? 758 | | | | +--:(range) 759 | | | | | +--rw lower-port 760 | | | | | | inet:port-number 761 | | | | | +--rw upper-port 762 | | | | | inet:port-number 763 | | | | +--:(operator) 764 | | | | +--rw operator? 765 | | | | | operator 766 | | | | +--rw port 767 | | | | inet:port-number 768 | | | +--rw (destination-port)? 769 | | | +--:(destination-port-range-or-operator) 770 | | | +--rw destination-port-range-or-operator 771 | | | +--rw (port-range-or-operator)? 772 | | | +--:(range) 773 | | | | +--rw lower-port 774 | | | | | inet:port-number 775 | | | | +--rw upper-port 776 | | | | inet:port-number 777 | | | +--:(operator) 778 | | | +--rw operator? 779 | | | | operator 780 | | | +--rw port 781 | | | inet:port-number 782 | | +--:(icmp) 783 | | +--rw icmp 784 | | +--rw type? uint8 785 | | +--rw code? uint8 786 | | +--rw rest-of-header? binary 787 | +--rw actions 788 | | ... 789 | +--ro statistics 790 | ... 791 +-ro capabilities 792 ... 794 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 796 DOTS implementations MUST support the following matching criteria: 798 match based on the IP header (IPv4 and IPv6), match based on the 799 transport header (TCP, UDP, and ICMP), and any combination 800 thereof. The same matching fields are used for both ICMP and 801 ICMPv6. 803 The following match fields MUST be supported by DOTS implementations 804 (Table 1): 806 ACL Mandatory Fields 807 Match 808 ------- ------------------------------------------------------------- 809 ipv4 length, protocol, destination-ipv4-network, source- 810 ipv4-network, and fragment 811 ipv6 length, protocol, destination-ipv6-network, source- 812 ipv6-network, and fragment 813 tcp flags-bitmask, source-port-range-or-operator, and 814 destination-port-range-or-operator 815 udp length, source-port-range-or-operator, and destination-port- 816 range-or-operator 817 icmp type and code 819 Table 1: Mandatory DOTS Channel Match Fields 821 Implementations MAY support other filtering match fields and actions. 822 The 'ietf-dots-data-channel' provides a method for an implementation 823 to expose its filtering capabilities. The tree structure of the 824 'capabilities' is shown in Figure 10. 826 module: ietf-dots-data-channel 827 +--rw dots-data 828 ... 829 +--ro capabilities 830 +--ro address-family* enumeration 831 +--ro forwarding-actions* identityref 832 +--ro rate-limit? boolean 833 +--ro transport-protocols* uint8 834 +--ro ipv4 835 | +--ro dscp? boolean 836 | +--ro ecn? boolean 837 | +--ro length? boolean 838 | +--ro ttl? boolean 839 | +--ro protocol? boolean 840 | +--ro ihl? boolean 841 | +--ro flags? boolean 842 | +--ro offset? boolean 843 | +--ro identification? boolean 844 | +--ro source-prefix? boolean 845 | +--ro destination-prefix? boolean 846 | +--ro fragment? boolean 847 +--ro ipv6 848 | +--ro dscp? boolean 849 | +--ro ecn? boolean 850 | +--ro length? boolean 851 | +--ro hoplimit? boolean 852 | +--ro protocol? boolean 853 | +--ro destination-prefix? boolean 854 | +--ro source-prefix? boolean 855 | +--ro flow-label? boolean 856 | +--ro fragment? boolean 857 +--ro tcp 858 | +--ro sequence-number? boolean 859 | +--ro acknowledgement-number? boolean 860 | +--ro data-offset? boolean 861 | +--ro reserved? boolean 862 | +--ro flags? boolean 863 | +--ro window-size? boolean 864 | +--ro urgent-pointer? boolean 865 | +--ro options? boolean 866 | +--ro flags-bitmask? boolean 867 | +--ro source-port? boolean 868 | +--ro destination-port? boolean 869 | +--ro port-range? boolean 870 +--ro udp 871 | +--ro length? boolean 872 | +--ro source-port? boolean 873 | +--ro destination-port? boolean 874 | +--ro port-range? boolean 875 +--ro icmp 876 +--ro type? boolean 877 +--ro code? boolean 878 +--ro rest-of-header? boolean 880 Figure 10: Filtering Capabilities Subtree 882 4.3. YANG Module 884 This module uses the common YANG types defined in [RFC6991] and types 885 defined in [I-D.ietf-netmod-acl-model]. 887 file "ietf-dots-data-channel@2019-02-14.yang" 888 module ietf-dots-data-channel { 889 yang-version 1.1; 890 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 891 prefix data-channel; 893 import ietf-inet-types { 894 prefix inet; 895 reference "Section 4 of RFC 6991"; 896 } 897 import ietf-access-control-list { 898 prefix ietf-acl; 899 reference 900 "RFC 8519: Network Access Control List (ACL) 901 YANG Data Model"; 902 } 903 import ietf-packet-fields { 904 prefix packet-fields; 905 reference 906 "RFC 8519: YANG Data Model for Network Access 907 Control Lists (ACLs)"; 908 } 910 organization 911 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 912 contact 913 "WG Web: 914 WG List: 916 Editor: Mohamed Boucadair 917 919 Editor: Konda, Tirumaleswar Reddy 920 922 Author: Jon Shallow 923 925 Author: Kaname Nishizuka 926 928 Author: Liang Xia 929 931 Author: Prashanth Patil 932 934 Author: Andrew Mortensen 935 937 Author: Nik Teague 938 "; 939 description 940 "This module contains YANG definition for configuring 941 aliases for resources and filtering rules using DOTS 942 data channel. 944 Copyright (c) 2019 IETF Trust and the persons identified as 945 authors of the code. All rights reserved. 947 Redistribution and use in source and binary forms, with or 948 without modification, is permitted pursuant to, and subject 949 to the license terms contained in, the Simplified BSD License 950 set forth in Section 4.c of the IETF Trust's Legal Provisions 951 Relating to IETF Documents 952 (http://trustee.ietf.org/license-info). 954 This version of this YANG module is part of RFC XXXX; see 955 the RFC itself for full legal notices."; 957 revision 2019-02-14 { 958 description 959 "Initial revision."; 960 reference 961 "RFC XXXX: Distributed Denial-of-Service Open Threat 962 Signaling (DOTS) Data Channel Specification"; 963 } 965 typedef activation-type { 966 type enumeration { 967 enum "activate-when-mitigating" { 968 value 1; 969 description 970 "The Access Control List (ACL) is installed only when 971 a mitigation is active for the DOTS client."; 972 } 973 enum "immediate" { 974 value 2; 975 description 976 "The ACL is immediately activated."; 977 } 978 enum "deactivate" { 979 value 3; 980 description 981 "The ACL is maintained by the DOTS server, but it is 982 deactivated."; 983 } 984 } 985 description 986 "Indicates the activation type of an ACL."; 987 } 989 typedef operator { 990 type bits { 991 bit not { 992 position 0; 993 description 994 "If set, logical negation of operation."; 996 } 997 bit match { 998 position 1; 999 description 1000 "Match bit. If set, this is a bitwise match operation 1001 defined as '(data & value) == value'; if unset, (data & 1002 value) evaluates to TRUE if any of the bits in the value 1003 mask are set in the data , i.e., '(data & value) != 0'."; 1004 } 1005 } 1006 description 1007 "Specifies how to apply the defined bitmask."; 1008 } 1010 grouping tcp-flags { 1011 leaf operator { 1012 type operator; 1013 default "match"; 1014 description 1015 "Specifies how to interpret the TCP flags."; 1016 } 1017 leaf bitmask { 1018 type uint16; 1019 mandatory true; 1020 description 1021 "Bitmask values can be encoded as a 1- or 2-byte bitmask. 1022 When a single byte is specified, it matches byte 13 1023 of the TCP header, which contains bits 8 though 15 1024 of the 4th 32-bit word. When a 2-byte encoding is used, 1025 it matches bytes 12 and 13 of the TCP header with 1026 the bitmask fields corresponding to the TCP data offset 1027 field being ignored for purposes of matching."; 1028 } 1029 description 1030 "Operations on TCP flags."; 1031 } 1033 typedef fragment-type { 1034 type bits { 1035 bit df { 1036 position 0; 1037 description 1038 "Don't fragment bit for IPv4. 1039 Must be set to 0 when it appears in an IPv6 filter."; 1040 } 1041 bit isf { 1042 position 1; 1043 description 1044 "Is a fragment."; 1045 } 1046 bit ff { 1047 position 2; 1048 description 1049 "First fragment."; 1050 } 1051 bit lf { 1052 position 3; 1053 description 1054 "Last fragment."; 1055 } 1056 } 1057 description 1058 "Different fragment types to match against."; 1059 } 1061 grouping target { 1062 description 1063 "Specifies the targets of the mitigation request."; 1064 leaf-list target-prefix { 1065 type inet:ip-prefix; 1066 description 1067 "IPv4 or IPv6 prefix identifying the target."; 1068 } 1069 list target-port-range { 1070 key "lower-port"; 1071 description 1072 "Port range. When only lower-port is 1073 present, it represents a single port number."; 1074 leaf lower-port { 1075 type inet:port-number; 1076 mandatory true; 1077 description 1078 "Lower port number of the port range."; 1079 } 1080 leaf upper-port { 1081 type inet:port-number; 1082 must '. >= ../lower-port' { 1083 error-message 1084 "The upper port number must be greater than 1085 or equal to lower port number."; 1086 } 1087 description 1088 "Upper port number of the port range."; 1089 } 1090 } 1091 leaf-list target-protocol { 1092 type uint8; 1093 description 1094 "Identifies the target protocol number. 1096 Values are taken from the IANA protocol registry: 1097 https://www.iana.org/assignments/protocol-numbers/ 1098 protocol-numbers.xhtml 1100 For example, 6 for TCP or 17 for UDP."; 1101 } 1102 leaf-list target-fqdn { 1103 type inet:domain-name; 1104 description 1105 "FQDN identifying the target."; 1106 } 1107 leaf-list target-uri { 1108 type inet:uri; 1109 description 1110 "URI identifying the target."; 1111 } 1112 } 1114 grouping fragment-fields { 1115 leaf operator { 1116 type operator; 1117 default "match"; 1118 description 1119 "Specifies how to interpret the fragment type."; 1120 } 1121 leaf type { 1122 type fragment-type; 1123 mandatory true; 1124 description 1125 "Indicates what fragment type to look for."; 1126 } 1127 description 1128 "Operations on fragment types."; 1129 } 1131 grouping aliases { 1132 description 1133 "Top level container for aliases"; 1134 list alias { 1135 key "name"; 1136 description 1137 "List of aliases"; 1138 leaf name { 1139 type string; 1140 description 1141 "The name of the alias"; 1142 } 1143 uses target; 1144 leaf pending-lifetime { 1145 type int32; 1146 units "minutes"; 1147 config false; 1148 description 1149 "Indicates the pending validity lifetime of the alias 1150 entry."; 1151 } 1152 } 1153 } 1155 grouping ports { 1156 choice source-port { 1157 container source-port-range-or-operator { 1158 uses packet-fields:port-range-or-operator; 1159 description 1160 "Source port definition."; 1161 } 1162 description 1163 "Choice of specifying the source port or referring to 1164 a group of source port numbers."; 1165 } 1166 choice destination-port { 1167 container destination-port-range-or-operator { 1168 uses packet-fields:port-range-or-operator; 1169 description 1170 "Destination port definition."; 1171 } 1172 description 1173 "Choice of specifying a destination port or referring 1174 to a group of destination port numbers."; 1175 } 1176 description 1177 "Choice of specifying a source or destination port numbers."; 1178 } 1180 grouping access-lists { 1181 description 1182 "Specifies the ordered set of Access Control Lists."; 1183 list acl { 1184 key "name"; 1185 ordered-by user; 1186 description 1187 "An ACL is an ordered list of Access Control Entries (ACE). 1189 Each ACE has a list of match criteria and a list of actions."; 1190 leaf name { 1191 type string { 1192 length "1..64"; 1193 } 1194 description 1195 "The name of the access list."; 1196 reference 1197 "RFC 8519: YANG Data Model for Network Access 1198 Control Lists (ACLs)"; 1199 } 1200 leaf type { 1201 type ietf-acl:acl-type; 1202 description 1203 "Type of access control list. Indicates the primary intended 1204 type of match criteria (e.g., IPv4, IPv6) used in the list 1205 instance."; 1206 reference 1207 "RFC 8519: YANG Data Model for Network Access 1208 Control Lists (ACLs)"; 1209 } 1210 leaf activation-type { 1211 type activation-type; 1212 default "activate-when-mitigating"; 1213 description 1214 "Indicates the activation type of an ACL. An ACL can be 1215 deactivated, installed immediately, or installed when 1216 a mitigation is active."; 1217 } 1218 leaf pending-lifetime { 1219 type int32; 1220 units "minutes"; 1221 config false; 1222 description 1223 "Indicates the pending validity lifetime of the ACL 1224 entry."; 1225 } 1226 container aces { 1227 description 1228 "The Access Control Entries container contains 1229 a list of ACEs."; 1230 list ace { 1231 key "name"; 1232 ordered-by user; 1233 description 1234 "List of access list entries."; 1235 leaf name { 1236 type string { 1237 length "1..64"; 1238 } 1239 description 1240 "A unique name identifying this ACE."; 1241 reference 1242 "RFC 8519: YANG Data Model for Network Access 1243 Control Lists (ACLs)"; 1244 } 1245 container matches { 1246 description 1247 "The rules in this set determine what fields will be 1248 matched upon before any action is taken on them. 1250 If no matches are defined in a particular container, 1251 then any packet will match that container. 1253 If no matches are specified at all in an ACE, then any 1254 packet will match the ACE."; 1255 reference 1256 "RFC 8519: YANG Data Model for Network Access 1257 Control Lists (ACLs)"; 1258 choice l3 { 1259 container ipv4 { 1260 when "derived-from(../../../../type," 1261 + "'ietf-acl:ipv4-acl-type')"; 1262 uses packet-fields:acl-ip-header-fields; 1263 uses packet-fields:acl-ipv4-header-fields; 1264 container fragment { 1265 description 1266 "Indicates how to handle IPv4 fragments."; 1267 uses fragment-fields; 1268 } 1269 description 1270 "Rule set that matches IPv4 header."; 1271 } 1272 container ipv6 { 1273 when "derived-from(../../../../type," 1274 + "'ietf-acl:ipv6-acl-type')"; 1275 uses packet-fields:acl-ip-header-fields; 1276 uses packet-fields:acl-ipv6-header-fields; 1277 container fragment { 1278 description 1279 "Indicates how to handle IPv6 fragments."; 1280 uses fragment-fields; 1281 } 1282 description 1283 "Rule set that matches IPv6 header."; 1284 } 1285 description 1286 "Either IPv4 or IPv6."; 1287 } 1288 choice l4 { 1289 container tcp { 1290 uses packet-fields:acl-tcp-header-fields; 1291 container flags-bitmask { 1292 description 1293 "Indicates how to handle TCP flags."; 1294 uses tcp-flags; 1295 } 1296 uses ports; 1297 description 1298 "Rule set that matches TCP header."; 1299 } 1300 container udp { 1301 uses packet-fields:acl-udp-header-fields; 1302 uses ports; 1303 description 1304 "Rule set that matches UDP header."; 1305 } 1306 container icmp { 1307 uses packet-fields:acl-icmp-header-fields; 1308 description 1309 "Rule set that matches ICMP/ICMPv6 header."; 1310 } 1311 description 1312 "Can be TCP, UDP, or ICMP/ICMPv6"; 1313 } 1314 } 1315 container actions { 1316 description 1317 "Definitions of action for this ACE."; 1318 leaf forwarding { 1319 type identityref { 1320 base ietf-acl:forwarding-action; 1321 } 1322 mandatory true; 1323 description 1324 "Specifies the forwarding action per ACE."; 1325 reference 1326 "RFC 8519: YANG Data Model for Network Access 1327 Control Lists (ACLs)"; 1328 } 1329 leaf rate-limit { 1330 when "../forwarding = 'ietf-acl:accept'" { 1331 description 1332 "Rate-limit is valid only when accept action is 1333 used."; 1334 } 1335 type decimal64 { 1336 fraction-digits 2; 1337 } 1338 units "bytes per second"; 1339 description 1340 "Specifies how to rate-limit the traffic."; 1341 } 1342 } 1343 container statistics { 1344 config false; 1345 description 1346 "Aggregate statistics."; 1347 uses ietf-acl:acl-counters; 1348 } 1349 } 1350 } 1351 } 1352 } 1354 container dots-data { 1355 description 1356 "Main container for DOTS data channel."; 1357 list dots-client { 1358 key "cuid"; 1359 description 1360 "List of DOTS clients."; 1361 leaf cuid { 1362 type string; 1363 description 1364 "A unique identifier that is generated by a DOTS client 1365 to prevent request collisions."; 1366 reference 1367 "RFC YYYY: Distributed Denial-of-Service Open Threat 1368 Signaling (DOTS) Signal Channel Specification"; 1369 } 1370 leaf cdid { 1371 type string; 1372 description 1373 "A client domain identifier conveyed by a 1374 server-domain DOTS gateway to a remote DOTS server."; 1375 reference 1376 "RFC YYYY: Distributed Denial-of-Service Open Threat 1377 Signaling (DOTS) Signal Channel Specification"; 1378 } 1379 container aliases { 1380 description 1381 "Set of aliases that are bound to a DOTS client."; 1382 uses aliases; 1383 } 1384 container acls { 1385 description 1386 "Access lists that are bound to a DOTS client."; 1387 uses access-lists; 1388 } 1389 } 1390 container capabilities { 1391 config false; 1392 description 1393 "Match capabilities"; 1394 leaf-list address-family { 1395 type enumeration { 1396 enum "ipv4" { 1397 description 1398 "IPv4 is supported."; 1399 } 1400 enum "ipv6" { 1401 description 1402 "IPv6 is supported."; 1403 } 1404 } 1405 description 1406 "Indicates the IP address families supported by 1407 the DOTS server."; 1408 } 1409 leaf-list forwarding-actions { 1410 type identityref { 1411 base ietf-acl:forwarding-action; 1412 } 1413 description 1414 "Supported forwarding action(s)."; 1415 } 1416 leaf rate-limit { 1417 type boolean; 1418 description 1419 "Support of rate-limit action."; 1420 } 1421 leaf-list transport-protocols { 1422 type uint8; 1423 description 1424 "Upper-layer protocol associated with a filtering rule. 1426 Values are taken from the IANA protocol registry: 1427 https://www.iana.org/assignments/protocol-numbers/ 1428 protocol-numbers.xhtml 1429 For example, this field contains 1 for ICMP, 6 for TCP 1430 17 for UDP, or 58 for ICMPv6."; 1431 } 1432 container ipv4 { 1433 description 1434 "Indicates IPv4 header fields that are supported to enforce 1435 ACLs."; 1436 leaf dscp { 1437 type boolean; 1438 description 1439 "Support of filtering based on Differentiated Services Code 1440 Point (DSCP)."; 1441 } 1442 leaf ecn { 1443 type boolean; 1444 description 1445 "Support of filtering based on Explicit Congestion 1446 Notification (ECN)."; 1447 } 1448 leaf length { 1449 type boolean; 1450 description 1451 "Support of filtering based on the Total Length."; 1452 } 1453 leaf ttl { 1454 type boolean; 1455 description 1456 "Support of filtering based on the Time to Live (TTL)."; 1457 } 1458 leaf protocol { 1459 type boolean; 1460 description 1461 "Support of filtering based on protocol field."; 1462 } 1463 leaf ihl { 1464 type boolean; 1465 description 1466 "Support of filtering based on the Internet Header 1467 Length (IHL)."; 1468 } 1469 leaf flags { 1470 type boolean; 1471 description 1472 "Support of filtering based on the 'flags'"; 1473 } 1474 leaf offset { 1475 type boolean; 1476 description 1477 "Support of filtering based on the 'offset'."; 1478 } 1479 leaf identification { 1480 type boolean; 1481 description 1482 "Support of filtering based on the 'identification'."; 1483 } 1484 leaf source-prefix { 1485 type boolean; 1486 description 1487 "Support of filtering based on the source prefix."; 1488 } 1489 leaf destination-prefix { 1490 type boolean; 1491 description 1492 "Support of filtering based on the destination prefix."; 1493 } 1494 leaf fragment { 1495 type boolean; 1496 description 1497 "Indicates the capability of a DOTS server to 1498 enforce filters on IPv4 fragments. That is, the match 1499 functionality based on the layer 3 'fragment' clause 1500 is supported."; 1501 } 1502 } 1503 container ipv6 { 1504 description 1505 "Indicates IPv6 header fields that are supported to enforce 1506 ACLs."; 1507 leaf dscp { 1508 type boolean; 1509 description 1510 "Support of filtering based on DSCP."; 1511 } 1512 leaf ecn { 1513 type boolean; 1514 description 1515 "Support of filtering based on ECN."; 1516 } 1517 leaf length { 1518 type boolean; 1519 description 1520 "Support of filtering based on the Payload Length."; 1521 } 1522 leaf hoplimit { 1523 type boolean; 1524 description 1525 "Support of filtering based on the Hop Limit."; 1526 } 1527 leaf protocol { 1528 type boolean; 1529 description 1530 "Support of filtering based on the Next Header field."; 1531 } 1532 leaf destination-prefix { 1533 type boolean; 1534 description 1535 "Support of filtering based on the destination prefix."; 1536 } 1537 leaf source-prefix { 1538 type boolean; 1539 description 1540 "Support of filtering based on the source prefix."; 1541 } 1542 leaf flow-label { 1543 type boolean; 1544 description 1545 "Support of filtering based on the Flow label."; 1546 } 1547 leaf fragment { 1548 type boolean; 1549 description 1550 "Indicates the capability of a DOTS server to 1551 enforce filters on IPv6 fragments."; 1552 } 1553 } 1554 container tcp { 1555 description 1556 "Set of TCP fields that are supported by the DOTS server 1557 to enfoce filters."; 1558 leaf sequence-number { 1559 type boolean; 1560 description 1561 "Support of filtering based on the TCP sequence number."; 1562 } 1563 leaf acknowledgement-number { 1564 type boolean; 1565 description 1566 "Support of filtering based on the TCP acknowledgement 1567 number."; 1568 } 1569 leaf data-offset { 1570 type boolean; 1571 description 1572 "Support of filtering based on the TCP data-offset."; 1574 } 1575 leaf reserved { 1576 type boolean; 1577 description 1578 "Support of filtering based on the TCP reserved field."; 1579 } 1580 leaf flags { 1581 type boolean; 1582 description 1583 "Support of filtering, as defined in RFC 8519, based 1584 on the TCP flags."; 1585 } 1586 leaf window-size { 1587 type boolean; 1588 description 1589 "Support of filtering based on the TCP window size."; 1590 } 1591 leaf urgent-pointer { 1592 type boolean; 1593 description 1594 "Support of filtering based on the TCP urgent pointer."; 1595 } 1596 leaf options { 1597 type boolean; 1598 description 1599 "Support of filtering based on the TCP options."; 1600 } 1601 leaf flags-bitmask { 1602 type boolean; 1603 description 1604 "Support of filtering based on the TCP flags bitmask."; 1605 } 1606 leaf source-port { 1607 type boolean; 1608 description 1609 "Support of filtering based on the source port number."; 1610 } 1611 leaf destination-port { 1612 type boolean; 1613 description 1614 "Support of filtering based on the destination port 1615 number."; 1616 } 1617 leaf port-range { 1618 type boolean; 1619 description 1620 "Support of filtering based on a port range. 1622 This includes filtering based on a source port range, 1623 destination port range, or both. All operators 1624 (i.e, less than or equal, greater than or equal, equal to, 1625 and not equal to) are supported."; 1626 } 1627 } 1628 container udp { 1629 description 1630 "Set of UDP fields that are supported by the DOTS server 1631 to enforce filters."; 1632 leaf length { 1633 type boolean; 1634 description 1635 "Support of filtering based on the UDP length."; 1636 } 1637 leaf source-port { 1638 type boolean; 1639 description 1640 "Support of filtering based on the source port number."; 1641 } 1642 leaf destination-port { 1643 type boolean; 1644 description 1645 "Support of filtering based on the destination port 1646 number."; 1647 } 1648 leaf port-range { 1649 type boolean; 1650 description 1651 "Support of filtering based on a port range. 1653 This includes filtering based on a source port range, 1654 destination port range, or both. All operators 1655 (i.e, less than or equal, greater than or equal, equal to, 1656 and not equal to) are supported."; 1657 } 1658 } 1659 container icmp { 1660 description 1661 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1662 server to enforce filters."; 1663 leaf type { 1664 type boolean; 1665 description 1666 "Support of filtering based on the ICMP/ICMPv6 type."; 1667 } 1668 leaf code { 1669 type boolean; 1670 description 1671 "Support of filtering based on the ICMP/ICMPv6 code."; 1672 } 1673 leaf rest-of-header { 1674 type boolean; 1675 description 1676 "Support of filtering based on the ICMP four-bytes 1677 field / the ICMPv6 message body."; 1678 } 1679 } 1680 } 1681 } 1682 } 1683 1685 5. Managing DOTS Clients 1687 5.1. Registering DOTS Clients 1689 In order to make use of DOTS data channel, a DOTS client MUST 1690 register to its DOTS server(s) by creating a DOTS client ('dots- 1691 client') resource. To that aim, DOTS clients SHOULD send a POST 1692 request (shown in Figure 11). 1694 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1695 Host: {host}:{port} 1696 Content-Type: application/yang-data+json 1697 { 1698 "ietf-dots-data-channel:dots-client": [ 1699 { 1700 "cuid": "string" 1701 } 1702 ] 1703 } 1705 Figure 11: POST to Register Schema 1707 The 'cuid' (client unique identifier) parameter is described below: 1709 cuid: A globally unique identifier that is meant to prevent 1710 collisions among DOTS clients. This attribute has the same 1711 meaning, syntax, and processing rules as the 'cuid' attribute 1712 defined in [I-D.ietf-dots-signal-channel]. 1714 DOTS clients MUST use the same 'cuid' for both signal and data 1715 channels. 1717 This is a mandatory attribute. 1719 In deployments where server-domain DOTS gateways are enabled, 1720 identity information about the origin source client domain SHOULD be 1721 supplied to the DOTS server. That information is meant to assist the 1722 DOTS server to enforce some policies. These policies can be enforced 1723 per-client, per-client domain, or both. Figure 12 shows a schema 1724 example of a request relayed by a server-domain DOTS gateway. 1726 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1727 Host: {host}:{port} 1728 Content-Type: application/yang-data+json 1729 { 1730 "ietf-dots-data-channel:dots-client": [ 1731 { 1732 "cuid": "string", 1733 "cdid": "string" 1734 } 1735 ] 1736 } 1738 Figure 12: POST to Register Schema (via a Server-Domain DOTS Gateway) 1740 A server-domain DOTS gateway SHOULD add the following attribute: 1742 cdid: This attribute has the same meaning, syntax, and processing 1743 rules as the 'cdid' attribute defined in 1744 [I-D.ietf-dots-signal-channel]. 1746 In deployments where server-domain DOTS gateways are enabled, 1747 'cdid' does not need to be inserted when relaying DOTS methods to 1748 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1749 servers are responsible for maintaining the association between 1750 'cdid' and 'cuid' for policy enforcement purposes. 1752 This is an optional attribute. 1754 A request example to create a 'dots-client' resource is depicted in 1755 Figure 13. This request is relayed by a server-domain DOTS gateway 1756 as hinted by the presence of the 'cdid' attribute. 1758 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1759 Host: example.com 1760 Content-Type: application/yang-data+json 1761 { 1762 "ietf-dots-data-channel:dots-client": [ 1763 { 1764 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1765 "cdid": "7eeaf349529eb55ed50113" 1766 } 1767 ] 1768 } 1770 Figure 13: POST to Register (DOTS gateway) 1772 As a reminder, DOTS gateways may rewrite the 'cuid' used by peer DOTS 1773 clients (Section 4.4.1 of [I-D.ietf-dots-signal-channel]). 1775 DOTS servers can identify the DOTS client domain using the 'cdid' 1776 parameter or using the client's DNS name specified in the Subject 1777 Alternative Name extension's dNSName type or SRV-ID in the client 1778 certificate. 1780 DOTS servers MUST limit the number of 'dots-client' resources to be 1781 created by the same DOTS client to 1 per request. Requests with 1782 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1783 To that aim, the DOTS server MUST rely on the same procedure to 1784 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1785 [I-D.ietf-dots-signal-channel]. 1787 The DOTS server indicates the result of processing the POST request 1788 using status-line codes. Status codes in the range "2xx" codes are 1789 success, "4xx" codes are some sort of invalid requests and "5xx" 1790 codes are returned if the DOTS server has erred or is incapable of 1791 accepting the creation of the 'dots-client' resource. In particular, 1793 o "201 Created" status-line is returned in the response, if the DOTS 1794 server has accepted the request. 1796 o "400 Bad Request" status-line is returned by the DOTS server, if 1797 the request does not include a 'cuid' parameter. The error-tag 1798 "missing-attribute" is used in this case. 1800 o "409 Conflict" status-line is returned to the requesting DOTS 1801 client, if the data resource already exists. The error-tag 1802 "resource-denied" is used in this case. 1804 Once a DOTS client registers itself to a DOTS server, it can 1805 create/delete/retrieve aliases (Section 6) and filtering rules 1806 (Section 7). 1808 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1809 register a DOTS client within the DOTS server. An example is shown 1810 in Figure 14. 1812 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1813 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1814 Host: example.com 1815 Content-Type: application/yang-data+json 1816 { 1817 "ietf-dots-data-channel:dots-client": [ 1818 { 1819 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1820 } 1821 ] 1822 } 1824 Figure 14: PUT to Register 1826 The DOTS gateway, that inserted a 'cdid' in a PUT request, MUST strip 1827 the 'cdid' parameter in the corresponding response before forwarding 1828 the response to the DOTS client. 1830 5.2. Unregistering DOTS Clients 1832 A DOTS client de-registers from its DOTS server(s) by deleting the 1833 'cuid' resource(s). Resources bound to this DOTS client will be 1834 deleted by the DOTS server. An example of a de-register request is 1835 shown in Figure 15. 1837 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1838 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1839 Host: example.com 1841 Figure 15: De-register a DOTS Client 1843 6. Managing DOTS Aliases 1845 The following sub-sections define means for a DOTS client to create 1846 aliases (Section 6.1), retrieve one or a list of aliases 1847 (Section 6.2), and delete an alias (Section 6.3). 1849 6.1. Create Aliases 1851 A POST or PUT request is used by a DOTS client to create aliases, for 1852 resources for which a mitigation may be requested. Such aliases may 1853 be used in subsequent DOTS signal channel exchanges to refer more 1854 efficiently to the resources under attack. 1856 DOTS clients within the same domain can create different aliases for 1857 the same resource. 1859 The structure of POST requests used to create aliases is shown in 1860 Figure 16. 1862 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1863 /dots-client=cuid HTTP/1.1 1864 Host: {host}:{port} 1865 Content-Type: application/yang-data+json 1866 { 1867 "ietf-dots-data-channel:aliases": { 1868 "alias": [ 1869 { 1870 "name": "string", 1871 "target-prefix": [ 1872 "string" 1873 ], 1874 "target-port-range": [ 1875 { 1876 "lower-port": integer, 1877 "upper-port": integer 1878 } 1879 ], 1880 "target-protocol": [ 1881 integer 1882 ], 1883 "target-fqdn": [ 1884 "string" 1885 ], 1886 "target-uri": [ 1887 "string" 1888 ] 1889 } 1890 ] 1891 } 1892 } 1894 Figure 16: POST to Create Aliases (Request Schema) 1896 The parameters are described below: 1898 name: Name of the alias. 1900 This is a mandatory attribute. 1902 target-prefix: Prefixes are separated by commas. Prefixes are 1903 represented using Classless Inter-domain Routing (CIDR) notation 1904 [RFC4632]. As a reminder, the prefix length must be less than or 1905 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1907 The prefix list MUST NOT include broadcast, loopback, or multicast 1908 addresses. These addresses are considered as invalid values. In 1909 addition, the DOTS server MUST validate that these prefixes are 1910 within the scope of the DOTS client's domain. Other validation 1911 checks may be supported by DOTS servers. 1913 This is an optional attribute. 1915 target-port-range: A range of port numbers. 1917 The port range is defined by two bounds, a lower port number 1918 (lower-port) and an upper port number (upper-port). The range is 1919 considered to include both the lower and upper bounds. 1921 When only 'lower-port' is present, it represents a single port 1922 number. 1924 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1925 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1926 [RFC4340], the range of port numbers can be, for example, 1927 1024-65535. 1929 This is an optional attribute. 1931 target-protocol: A list of protocols. Values are taken from the 1932 IANA protocol registry [proto_numbers]. 1934 If 'target-protocol' is not specified, then the request applies to 1935 any protocol. 1937 This is an optional attribute. 1939 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 1940 identifying resources under attack [RFC8499]. 1942 How a name is passed to an underlying name resolution library is 1943 implementation- and deployment-specific. Nevertheless, once the 1944 name is resolved into one or multiple IP addresses, DOTS servers 1945 MUST apply the same validation checks as those for 'target- 1946 prefix'. 1948 The use of FQDNs may be suboptimal because it does not guarantee 1949 that the DOTS server will resolve a name to the same IP addresses 1950 that the DOTS client does. 1952 This is an optional attribute. 1954 target-uri: A list of Uniform Resource Identifiers (URIs) 1955 [RFC3986]. 1957 The same validation checks used for 'target-fqdn' MUST be followed 1958 by DOTS servers to validate a target URI. 1960 This is an optional attribute. 1962 In POST or PUT requests, at least one of the 'target-prefix', 1963 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1964 agents can safely ignore Vendor-Specific parameters they don't 1965 understand. 1967 If more than one 'target-*' scope types (e.g., 'target-prefix' and 1968 'target-fqdn' or 'target-fqdn' and 'target-uri') are included in a 1969 POST or PUT request, the DOTS server binds all resulting IP 1970 addresses/prefixes to the same resource. 1972 Figure 17 shows a POST request to create an alias called "https1" for 1973 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1974 listening on TCP port number 443. 1976 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1977 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1978 Host: www.example.com 1979 Content-Type: application/yang-data+json 1980 { 1981 "ietf-dots-data-channel:aliases": { 1982 "alias": [ 1983 { 1984 "name": "https1", 1985 "target-protocol": [ 1986 6 1987 ], 1988 "target-prefix": [ 1989 "2001:db8:6401::1/128", 1990 "2001:db8:6401::2/128" 1991 ], 1992 "target-port-range": [ 1993 { 1994 "lower-port": 443 1995 } 1996 ] 1997 } 1998 ] 1999 } 2000 } 2002 Figure 17: Example of a POST to Create an Alias 2004 "201 Created" status-line MUST be returned in the response if the 2005 DOTS server has accepted the alias. 2007 "409 Conflict" status-line MUST be returned to the requesting DOTS 2008 client, if the request is conflicting with an existing alias name. 2009 The error-tag "resource-denied" is used in this case. 2011 If the request is missing a mandatory attribute or its contains an 2012 invalid or unknown parameter, "400 Bad Request" status-line MUST be 2013 returned by the DOTS server. The error-tag is set to "missing- 2014 attribute", "invalid-value", or "unknown-element" as a function of 2015 the encountered error. 2017 If the request is received via a server-domain DOTS gateway, but the 2018 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2019 is expected to be supplied, the DOTS server MUST reply with "403 2020 Forbidden" status-line and the error-tag "access-denied". Upon 2021 receipt of this message, the DOTS client MUST register (Section 5). 2023 A DOTS client uses the PUT request to modify the aliases in the DOTS 2024 server. In particular, a DOTS client MUST update its alias entries 2025 upon change of the prefix indicated in the 'target-prefix'. 2027 A DOTS server MUST maintain an alias for at least 10080 minutes (1 2028 week). If no refresh request is seen from the DOTS client, the DOTS 2029 server removes expired entries. 2031 6.2. Retrieve Installed Aliases 2033 A GET request is used to retrieve one or all installed aliases by a 2034 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 2035 'name' is included in the request, this is an indication that the 2036 request is about retrieving all aliases instantiated by the DOTS 2037 client. 2039 Figure 18 shows an example to retrieve all the aliases that were 2040 instantiated by the requesting DOTS client. The "content" query 2041 parameter and its permitted values are defined in Section 4.8.1 of 2042 [RFC8040]. 2044 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2045 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2046 /aliases?content=all HTTP/1.1 2047 Host: example.com 2048 Accept: application/yang-data+json 2050 Figure 18: GET to Retrieve All Installed Aliases 2052 Figure 19 shows an example of the response message body that includes 2053 all the aliases that are maintained by the DOTS server for the DOTS 2054 client identified by the 'cuid' parameter. 2056 { 2057 "ietf-dots-data-channel:aliases": { 2058 "alias": [ 2059 { 2060 "name": "Server1", 2061 "target-protocol": [ 2062 6 2063 ], 2064 "target-prefix": [ 2065 "2001:db8:6401::1/128", 2066 "2001:db8:6401::2/128" 2067 ], 2068 "target-port-range": [ 2069 { 2070 "lower-port": 443 2071 } 2072 ], 2073 "pending-lifetime": 3596 2074 }, 2075 { 2076 "name": "Server2", 2077 "target-protocol": [ 2078 6 2079 ], 2080 "target-prefix": [ 2081 "2001:db8:6401::10/128", 2082 "2001:db8:6401::20/128" 2083 ], 2084 "target-port-range": [ 2085 { 2086 "lower-port": 80 2087 } 2088 ], 2089 "pending-lifetime": 9869 2090 } 2091 ] 2092 } 2093 } 2095 Figure 19: An Example of Response Body Listing All Installed Aliases 2097 Figure 20 shows an example of a GET request to retrieve the alias 2098 "Server2" that was instantiated by the DOTS client. 2100 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2101 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2102 /aliases/alias=Server2?content=all HTTP/1.1 2103 Host: example.com 2104 Accept: application/yang-data+json 2106 Figure 20: GET to Retrieve an Alias 2108 If an alias name ('name') is included in the request, but the DOTS 2109 server does not find that alias name for this DOTS client in its 2110 configuration data, it MUST respond with a "404 Not Found" status- 2111 line. 2113 6.3. Delete Aliases 2115 A DELETE request is used to delete an alias maintained by a DOTS 2116 server. 2118 If the DOTS server does not find the alias name, conveyed in the 2119 DELETE request, in its configuration data for this DOTS client, it 2120 MUST respond with a "404 Not Found" status-line. 2122 The DOTS server successfully acknowledges a DOTS client's request to 2123 remove the alias using "204 No Content" status-line in the response. 2125 Figure 21 shows an example of a request to delete an alias. 2127 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2128 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2129 /aliases/alias=Server1 HTTP/1.1 2130 Host: example.com 2132 Figure 21: Delete an Alias 2134 7. Managing DOTS Filtering Rules 2136 The following sub-sections define means for a DOTS client to retrieve 2137 DOTS filtering capabilities (Section 7.1), create filtering rules 2138 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2139 delete a filtering rule (Section 7.4). 2141 7.1. Retrieve DOTS Filtering Capabilities 2143 A DOTS client MAY send a GET request to retrieve the filtering 2144 capabilities supported by a DOTS server. Figure 22 shows an example 2145 of such request. 2147 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2148 /capabilities HTTP/1.1 2149 Host: example.com 2150 Accept: application/yang-data+json 2152 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2154 A DOTS client which issued a GET request to retrieve the filtering 2155 capabilities supported by its DOTS server, SHOULD NOT request for 2156 filtering actions that are not supported by that DOTS server. 2158 Figure 23 shows an example of a response received from a DOTS server 2159 which supports: 2161 o IPv4, IPv6, TCP, UDP, ICMP, and ICMPv6 mandatory match criteria 2162 listed in Section 4.2. 2164 o 'accept', 'drop', and 'rate-limit' actions. 2166 Content-Type: application/yang-data+json 2167 { 2168 "ietf-dots-data-channel:capabilities": { 2169 "address-family": ["ipv4", "ipv6"], 2170 "forwarding-actions": ["drop", "accept"], 2171 "rate-limit": true, 2172 "transport-protocols": [1, 6, 17, 58], 2173 "ipv4": { 2174 "length": true, 2175 "protocol": true, 2176 "destination-prefix": true, 2177 "source-prefix": true, 2178 "fragment": true 2179 }, 2180 "ipv6": { 2181 "length": true, 2182 "protocol": true, 2183 "destination-prefix": true, 2184 "source-prefix": true, 2185 "fragment": true 2186 }, 2187 "tcp": { 2188 "flags-bitmask": true, 2189 "source-port": true, 2190 "destination-port": true, 2191 "port-range": true 2192 }, 2193 "udp": { 2194 "length": true, 2195 "source-port": true, 2196 "destination-port": true, 2197 "port-range": true 2198 }, 2199 "icmp": { 2200 "type": true, 2201 "code": true 2202 } 2203 } 2204 } 2206 Figure 23: Reply to a GET Request with Filtering Capabilities 2208 7.2. Install Filtering Rules 2210 A POST or PUT request is used by a DOTS client to communicate 2211 filtering rules to a DOTS server. 2213 Figure 24 shows a POST request example to block traffic from 2214 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2215 discussed in Appendix A. 2217 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2218 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2219 Host: example.com 2220 Content-Type: application/yang-data+json 2221 { 2222 "ietf-dots-data-channel:acls": { 2223 "acl": [ 2224 { 2225 "name": "sample-ipv4-acl", 2226 "type": "ipv4-acl-type", 2227 "activation-type": "activate-when-mitigating", 2228 "aces": { 2229 "ace": [ 2230 { 2231 "name": "rule1", 2232 "matches": { 2233 "ipv4": { 2234 "destination-ipv4-network": "198.51.100.0/24", 2235 "source-ipv4-network": "192.0.2.0/24" 2236 } 2237 }, 2238 "actions": { 2239 "forwarding": "drop" 2240 } 2241 } 2242 ] 2243 } 2244 } 2245 ] 2246 } 2247 } 2249 Figure 24: POST to Install Filtering Rules 2251 The meaning of these parameters is as follows: 2253 name: The name of the access list. 2255 This is a mandatory attribute. 2257 type: Indicates the primary intended type of match criteria (e.g., 2258 IPv4, IPv6). It is set to 'ipv4-acl-type' in the example of 2259 Figure 24. 2261 This is an optional attribute. 2263 activation-type: Indicates whether an ACL has to be activated 2264 (immediately or during mitigation time) or instantiated without 2265 being activated (deactivated). Deactivated ACLs can be activated 2266 using a variety of means such as manual configuration on a DOTS 2267 server or using the DOTS data channel. 2269 If this attribute is not provided, the DOTS server MUST use 2270 'activate-when-mitigating' as default value. 2272 When a mitigation is in progress, the DOTS server MUST only 2273 activate 'activate-when-mitigating' filters that are bound to the 2274 DOTS client that triggered the mitigation. 2276 This is an optional attribute. 2278 matches: Define criteria used to identify a flow on which to apply 2279 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2280 The detailed match parameters are specified in Section 4. 2282 In the example depicted in Figure 24, an IPv4 matching criteria is 2283 used. 2285 This is an optional attribute. 2287 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2288 MUST validate that these prefixes are within the scope of the DOTS 2289 client's domain. Other validation checks may be supported by DOTS 2290 servers. If this attribute is not provided, the DOTS server 2291 enforces the ACL on any destination IP address that belong to the 2292 DOTS client's domain. 2294 This is a mandatory attribute in requests with an 'activation- 2295 type' set to 'immediate'. 2297 source-ipv4-network: The source IPv4 prefix. 2299 This is an optional attribute. 2301 actions: Actions in the forwarding ACL category can be "drop" or 2302 "accept". The "accept" action is used to accept-list traffic. 2303 The "drop" action is used to drop-list traffic. 2305 Accepted traffic may be subject to "rate-limit"; the allowed 2306 traffic rate is represented in bytes per second. This unit is the 2307 same as the one used for "traffic-rate" in [RFC5575]. 2309 This is a mandatory attribute. 2311 The DOTS server indicates the result of processing the POST request 2312 using the status-line header. Concretely, "201 Created" status-line 2313 MUST be returned in the response if the DOTS server has accepted the 2314 filtering rules. If the request is missing a mandatory attribute or 2315 contains an invalid or unknown parameter (e.g., a match field not 2316 supported by the DOTS server), "400 Bad Request" status-line MUST be 2317 returned by the DOTS server in the response. The error-tag is set to 2318 "missing-attribute", "invalid-value", or "unknown-element" as a 2319 function of the encountered error. 2321 If the request is received via a server-domain DOTS gateway, but the 2322 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2323 is expected to be supplied, the DOTS server MUST reply with "403 2324 Forbidden" status-line and the error-tag "access-denied". Upon 2325 receipt of this message, the DOTS client MUST register (Figure 11). 2327 If the request is conflicting with an existing filtering installed by 2328 another DOTS client of the domain, absent any local policy, the DOTS 2329 server returns "409 Conflict" status-line to the requesting DOTS 2330 client. The error-tag "resource-denied" is used in this case. 2332 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2333 to specify how an access control entry is inserted within an ACL and 2334 how an ACL is inserted within an ACL set. 2336 The DOTS client uses the PUT request to modify its filtering rules 2337 maintained by the DOTS server. In particular, a DOTS client MUST 2338 update its filtering entries upon change of the destination-prefix. 2339 How such change is detected is out of scope. 2341 A DOTS server MUST maintain a filtering rule for at least 10080 2342 minutes (1 week). If no refresh request is seen from the DOTS 2343 client, the DOTS server removes expired entries. Typically, a 2344 refresh request is a PUT request which echoes the content of a 2345 response to a GET request with all of the read-only parameters 2346 stripped out (e.g., pending-lifetime). 2348 7.3. Retrieve Installed Filtering Rules 2350 A DOTS client periodically queries its DOTS server to check the 2351 counters for installed filtering rules. A GET request is used to 2352 retrieve filtering rules from a DOTS server. In order to indicate 2353 which type of data is requested in a GET request, the DOTS client 2354 sets adequately the "content" query parameter. 2356 If the DOTS server does not find the access list name conveyed in the 2357 GET request in its configuration data for this DOTS client, it 2358 responds with a "404 Not Found" status-line. 2360 In order to illustrate the intended behavior, consider the example 2361 depicted in Figure 25. In reference to this example, the DOTS client 2362 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2364 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2365 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2366 /acl=test-acl-ipv6-udp HTTP/1.1 2367 Host: example.com 2368 Content-Type: application/yang-data+json 2369 { 2370 "ietf-dots-data-channel:acls": { 2371 "acl": [ 2372 { 2373 "name": "test-acl-ipv6-udp", 2374 "type": "ipv6-acl-type", 2375 "activation-type": "immediate", 2376 "aces": { 2377 "ace": [ 2378 { 2379 "name": "my-test-ace", 2380 "matches": { 2381 "ipv6": { 2382 "destination-ipv6-network": "2001:db8:6401::2/127", 2383 "source-ipv6-network": "2001:db8:1234::/96", 2384 "protocol": 17, 2385 "flow-label": 10000 2386 }, 2387 "udp": { 2388 "source-port": { 2389 "operator": "lte", 2390 "port": 80 2391 }, 2392 "destination-port": { 2393 "operator": "neq", 2394 "port": 1010 2395 } 2396 } 2397 }, 2398 "actions": { 2399 "forwarding": "accept" 2400 } 2401 } 2402 ] 2403 } 2404 } 2405 ] 2406 } 2407 } 2409 Figure 25: Example of a PUT Request to Create a Filtering 2411 The peer DOTS server follows the procedure specified in Section 7.2 2412 to process the request. We consider in the following that a positive 2413 response is sent back to the requesting DOTS client to confirm that 2414 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2415 server. 2417 The DOTS client can issue a GET request to retrieve all its filtering 2418 rules and the number of matches for the installed filtering rules as 2419 illustrated in Figure 26. The "content" query parameter is set to 2420 'all'. The message body of the response to this GET request is shown 2421 in Figure 27. 2423 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2424 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2425 /acls?content=all HTTP/1.1 2426 Host: example.com 2427 Accept: application/yang-data+json 2429 Figure 26: Retrieve the Configuration Data and State Data for the 2430 Filtering Rules (GET Request) 2432 { 2433 "ietf-dots-data-channel:acls": { 2434 "acl": [ 2435 { 2436 "name": "test-acl-ipv6-udp", 2437 "type": "ipv6-acl-type", 2438 "activation-type": "immediate", 2439 "pending-lifetime":9080, 2440 "aces": { 2441 "ace": [ 2442 { 2443 "name": "my-test-ace", 2444 "matches": { 2445 "ipv6": { 2446 "destination-ipv6-network": "2001:db8:6401::2/127", 2447 "source-ipv6-network": "2001:db8:1234::/96", 2448 "protocol": 17, 2449 "flow-label": 10000 2450 }, 2451 "udp": { 2452 "source-port": { 2453 "operator": "lte", 2454 "port": 80 2455 }, 2456 "destination-port": { 2457 "operator": "neq", 2458 "port": 1010 2459 } 2460 } 2461 }, 2462 "actions": { 2463 "forwarding": "accept" 2464 } 2465 } 2466 ] 2467 } 2468 } 2469 ] 2470 } 2471 } 2473 Figure 27: Retrieve the Configuration Data and State Data for the 2474 Filtering Rules (Response Message Body) 2476 Also, a DOTS client can issue a GET request to retrieve only 2477 configuration data related to an ACL as shown in Figure 28. It does 2478 so by setting the "content" query parameter to 'config'. 2480 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2481 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2482 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2483 Host: example.com 2484 Accept: application/yang-data+json 2486 Figure 28: Retrieve the Configuration Data for a Filtering Rule (GET 2487 Request) 2489 A response to this GET request is shown in Figure 29. 2491 { 2492 "ietf-dots-data-channel:acls": { 2493 "acl": [ 2494 { 2495 "name": "test-acl-ipv6-udp", 2496 "type": "ipv6-acl-type", 2497 "activation-type": "immediate", 2498 "aces": { 2499 "ace": [ 2500 { 2501 "name": "my-test-ace", 2502 "matches": { 2503 "ipv6": { 2504 "destination-ipv6-network": "2001:db8:6401::2/127", 2505 "source-ipv6-network": "2001:db8:1234::/96", 2506 "protocol": 17, 2507 "flow-label": 10000 2508 }, 2509 "udp": { 2510 "source-port": { 2511 "operator": "lte", 2512 "port": 80 2513 }, 2514 "destination-port": { 2515 "operator": "neq", 2516 "port": 1010 2517 } 2518 } 2519 }, 2520 "actions": { 2521 "forwarding": "accept" 2522 } 2523 } 2524 ] 2525 } 2526 } 2527 ] 2528 } 2529 } 2531 Figure 29: Retrieve the Configuration Data for a Filtering Rule 2532 (Response Message Body) 2534 A DOTS client can also issue a GET request with a "content" query 2535 parameter set to 'non-config' to exclusively retrieve non- 2536 configuration data bound to a given ACL as shown in Figure 28. A 2537 response to this GET request is shown in Figure 31. 2539 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2540 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2541 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2542 Host: example.com 2543 Accept: application/yang-data+json 2545 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule 2546 (GET Request) 2548 { 2549 "ietf-dots-data-channel:acls": { 2550 "acl": [ 2551 { 2552 "name": "test-acl-ipv6-udp", 2553 "pending-lifetime": 8000, 2554 "aces": { 2555 "ace": [ 2556 { 2557 "name": "my-test-ace" 2558 } 2559 ] 2560 } 2561 } 2562 ] 2563 } 2564 } 2566 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule 2567 (Response Message Body) 2569 7.4. Remove Filtering Rules 2571 A DELETE request is used by a DOTS client to delete filtering rules 2572 from a DOTS server. 2574 If the DOTS server does not find the access list name carried in the 2575 DELETE request in its configuration data for this DOTS client, it 2576 MUST respond with a "404 Not Found" status-line. The DOTS server 2577 successfully acknowledges a DOTS client's request to withdraw the 2578 filtering rules using "204 No Content" status-line, and removes the 2579 filtering rules accordingly. 2581 Figure 32 shows an example of a request to remove the IPv4 ACL 2582 "sample-ipv4-acl" created in Section 7.2. 2584 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2585 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2586 /acl=sample-ipv4-acl HTTP/1.1 2587 Host: example.com 2589 Figure 32: Remove a Filtering Rule (DELETE Request) 2591 Figure 33 shows an example of a response received from the DOTS 2592 server to confirm the deletion of "sample-ipv4-acl". 2594 HTTP/1.1 204 No Content 2595 Server: Apache 2596 Date: Fri, 27 Jul 2018 10:05:15 GMT 2597 Cache-Control: no-cache 2598 Content-Type: application/yang-data+json 2599 Content-Length: 0 2600 Connection: Keep-Alive 2602 Figure 33: Remove a Filtering Rule (Response) 2604 8. Operational Considerations 2606 The following operational considerations should be taken into 2607 account: 2609 o DOTS servers MUST NOT enable both DOTS data channel and direct 2610 configuration, to avoid race conditions and inconsistent 2611 configurations arising from simultaneous updates from multiple 2612 sources. 2614 o DOTS agents SHOULD enable the DOTS data channel to configure 2615 aliases and ACLs, and only use direct configuration as a stop-gap 2616 mechanism to test DOTS signal channel with aliases and ACLs. 2617 Further, direct configuration SHOULD only be used when the on-path 2618 DOTS agents are within the same domain. 2620 o If a DOTS server has enabled direct configuration, it can reject 2621 the DOTS data channel connection using hard ICMP error [RFC1122] 2622 or RST (Reset) bit in the TCP header or reject the RESTCONF 2623 request using an error response containing a "503 Service 2624 Unavailable" status-line. 2626 9. IANA Considerations 2628 This document requests IANA to register the following URI in the "ns" 2629 subregistry within the "IETF XML Registry" [RFC3688]: 2631 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2632 Registrant Contact: The IESG. 2633 XML: N/A; the requested URI is an XML namespace. 2635 This document requests IANA to register the following YANG module in 2636 the "YANG Module Names" subregistry [RFC7950] within the "YANG 2637 Parameters" registry. 2639 name: ietf-dots-data-channel 2640 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2641 prefix: data-channel 2642 reference: RFC XXXX 2644 This module is not maintained by IANA. 2646 10. Security Considerations 2648 RESTCONF security considerations are discussed in [RFC8040]. In 2649 particular, DOTS agents MUST follow the security recommendations in 2650 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2651 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2652 [I-D.ietf-dots-signal-channel]. 2654 Authenticated encryption MUST be used for data confidentiality and 2655 message integrity. The interaction between the DOTS agents requires 2656 Transport Layer Security (TLS) with a cipher suite offering 2657 confidentiality protection and the guidance given in [RFC7525] MUST 2658 be followed to avoid attacks on TLS. 2660 The installation of drop- or accept-list rules using RESTCONF over 2661 TLS reveals the attacker IP addresses and legitimate IP addresses 2662 only to the DOTS server trusted by the DOTS client. The secure 2663 communication channel between DOTS agents provides privacy and 2664 prevents a network eavesdropper from directly gaining access to the 2665 drop- and accept-listed IP addresses. 2667 An attacker may be able to inject RST packets, bogus application 2668 segments, etc., regardless of whether TLS authentication is used. 2669 Because the application data is TLS protected, this will not result 2670 in the application receiving bogus data, but it will constitute a DoS 2671 on the connection. This attack can be countered by using TCP-AO 2672 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2673 attacker will be rejected by the TCP-AO integrity check and therefore 2674 will never reach the TLS layer. 2676 In order to prevent leaking internal information outside a client- 2677 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2678 internal DOTS clients (e.g., source IP address, client's hostname) 2679 unless explicitly configured to do so. 2681 DOTS servers MUST verify that requesting DOTS clients are entitled to 2682 enforce filtering rules on a given IP prefix. That is, only 2683 filtering rules on IP resources that belong to the DOTS client's 2684 domain can be authorized by a DOTS server. The exact mechanism for 2685 the DOTS servers to validate that the target prefixes are within the 2686 scope of the DOTS client's domain is deployment-specific. 2688 Rate-limiting DOTS requests, including those with new 'cuid' values, 2689 from the same DOTS client defends against DoS attacks that would 2690 result from varying the 'cuid' to exhaust DOTS server resources. 2691 Rate-limit policies SHOULD be enforced on DOTS gateways (if deployed) 2692 and DOTS servers. 2694 Applying resources quota per DOTS client and/or per DOTS client 2695 domain (e.g., limit the number of aliases and filters to be installed 2696 by DOTS clients) prevents DOTS server resources to be aggressively 2697 used by some DOTS clients and ensures, therefore, DDoS mitigation 2698 usage fairness. Additionally, DOTS servers may limit the number of 2699 DOTS clients that can be enabled per domain. 2701 The presence of DOTS gateways may lead to infinite forwarding loops, 2702 which is undesirable. To prevent and detect such loops, a mechanism 2703 is defined in Section 3.4. 2705 All data nodes defined in the YANG module which can be created, 2706 modified, and deleted (i.e., config true, which is the default) are 2707 considered sensitive. Write operations applied to these data nodes 2708 without proper protection can negatively affect network operations. 2709 This module reuses YANG structures from [I-D.ietf-netmod-acl-model], 2710 and the security considerations for those nodes continue to apply for 2711 this usage. Appropriate security measures are recommended to prevent 2712 illegitimate users from invoking DOTS data channel primitives. 2713 Nevertheless, an attacker who can access a DOTS client is technically 2714 capable of launching various attacks, such as: 2716 o Setting an arbitrarily low rate-limit, which may prevent 2717 legitimate traffic from being forwarded (rate-limit). 2719 o Setting an arbitrarily high rate-limit, which may lead to the 2720 forwarding of illegitimate DDoS traffic (rate-limit). 2722 o Communicating invalid aliases to the server (alias), which will 2723 cause the failure of associating both data and signal channels. 2725 o Setting invalid ACL entries, which may prevent legitimate traffic 2726 from being forwarded. Likewise, invalid ACL entries may lead to 2727 forward DDoS traffic. 2729 11. Contributing Authors 2731 The following individuals co-authored this document: 2733 Kaname Nishizuka 2734 NTT Communications 2735 GranPark 16F 3-4-1 Shibaura, Minato-ku 2736 Tokyo 108-8118 2737 Japan 2739 Email: kaname@nttv6.jp 2741 Liang Xia 2742 Huawei 2743 101 Software Avenue, Yuhuatai District 2744 Nanjing, Jiangsu 210012 2745 China 2747 Email: frank.xialiang@huawei.com 2749 Prashanth Patil 2750 Cisco Systems, Inc. 2752 Email: praspati@cisco.com 2754 Andrew Mortensen 2755 Arbor Networks, Inc. 2756 2727 S. State St 2757 Ann Arbor, MI 48104 2758 United States 2760 Email: andrew.mortensen@netscout.com 2762 Nik Teague 2763 Verisign, Inc. 2764 United States 2766 Email: nteague@verisign.com 2768 12. Contributors 2770 The following individuals have contributed to this document: 2772 o Dan Wing, Email: dwing-ietf@fuggles.com 2774 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.com 2776 13. Acknowledgements 2778 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2779 Doron, Russ White, Gilbert Clark, Kathleen Moriarty, and Nesredien 2780 Suleiman for the discussion and comments. 2782 Many thanks to Ben Kaduk for the detailed AD review. 2784 Thanks to Martin Bjorklund for the guidance on RESTCONF. 2786 14. References 2788 14.1. Normative References 2790 [I-D.ietf-dots-signal-channel] 2791 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 2792 Teague, "Distributed Denial-of-Service Open Threat 2793 Signaling (DOTS) Signal Channel Specification", draft- 2794 ietf-dots-signal-channel-28 (work in progress), January 2795 2019. 2797 [I-D.ietf-netmod-acl-model] 2798 Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, 2799 "Network Access Control List (ACL) YANG Data Model", 2800 draft-ietf-netmod-acl-model-21 (work in progress), 2801 November 2018. 2803 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2804 Requirement Levels", BCP 14, RFC 2119, 2805 DOI 10.17487/RFC2119, March 1997, 2806 . 2808 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2809 DOI 10.17487/RFC3688, January 2004, 2810 . 2812 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2813 (CIDR): The Internet Address Assignment and Aggregation 2814 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2815 2006, . 2817 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 2818 RFC 6991, DOI 10.17487/RFC6991, July 2013, 2819 . 2821 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2822 Protocol (HTTP/1.1): Message Syntax and Routing", 2823 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2824 . 2826 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2827 "Recommendations for Secure Use of Transport Layer 2828 Security (TLS) and Datagram Transport Layer Security 2829 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2830 2015, . 2832 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2833 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2834 . 2836 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2837 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2838 . 2840 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2841 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2842 . 2844 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2845 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2846 May 2017, . 2848 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2849 Interchange Format", STD 90, RFC 8259, 2850 DOI 10.17487/RFC8259, December 2017, 2851 . 2853 14.2. Informative References 2855 [I-D.ietf-dots-architecture] 2856 Mortensen, A., Andreasen, F., K, R., Teague, N., Compton, 2857 R., and c. christopher_gray3@cable.comcast.com, 2858 "Distributed-Denial-of-Service Open Threat Signaling 2859 (DOTS) Architecture", draft-ietf-dots-architecture-11 2860 (work in progress), February 2019. 2862 [I-D.ietf-dots-requirements] 2863 Mortensen, A., K, R., and R. Moskowitz, "Distributed 2864 Denial of Service (DDoS) Open Threat Signaling 2865 Requirements", draft-ietf-dots-requirements-18 (work in 2866 progress), February 2019. 2868 [proto_numbers] 2869 "IANA, "Protocol Numbers"", 2011, 2870 . 2872 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2873 Communication Layers", STD 3, RFC 1122, 2874 DOI 10.17487/RFC1122, October 1989, 2875 . 2877 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2878 Resource Identifier (URI): Generic Syntax", STD 66, 2879 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2880 . 2882 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2883 Congestion Control Protocol (DCCP)", RFC 4340, 2884 DOI 10.17487/RFC4340, March 2006, 2885 . 2887 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2888 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2889 . 2891 [RFC5575] Marques, P., Sheth, N., Raszuk, R., Greene, B., Mauch, J., 2892 and D. McPherson, "Dissemination of Flow Specification 2893 Rules", RFC 5575, DOI 10.17487/RFC5575, August 2009, 2894 . 2896 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2897 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2898 June 2010, . 2900 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2901 Layer Security (TLS) and Datagram Transport Layer Security 2902 (DTLS) Heartbeat Extension", RFC 6520, 2903 DOI 10.17487/RFC6520, February 2012, 2904 . 2906 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2907 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2908 . 2910 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 2911 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 2912 January 2019, . 2914 Appendix A. Sample Examples: Filtering Fragments 2916 This specification strongly recommends the use of "fragment" for 2917 handling fragments. 2919 Figure 34 shows the content of the POST request to be issued by a 2920 DOTS client to its DOTS server to allow the traffic destined to 2921 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2922 packets. The following ACEs are defined (in this order): 2924 o "drop-all-fragments" ACE: discards all fragments. 2926 o "allow-dns-packets" ACE: accepts DNS packets destined to 2927 198.51.100.0/24. 2929 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2930 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2931 Host: example.com 2932 Content-Type: application/yang-data+json 2933 { 2934 "ietf-dots-data-channel:acls": { 2935 "acl": [ 2936 { 2937 "name": "dns-fragments", 2938 "type": "ipv4-acl-type", 2939 "aces": { 2940 "ace": [ 2941 { 2942 "name": "drop-all-fragments", 2943 "matches": { 2944 "ipv4": { 2945 "fragment": { 2946 "operator": "match", 2947 "type": "isf" 2948 } 2949 } 2950 }, 2951 "actions": { 2952 "forwarding": "drop" 2953 } 2954 } 2955 ] 2956 "ace": [ 2957 { 2958 "name": "allow-dns-packets", 2959 "matches": { 2960 "ipv4": { 2961 "destination-ipv4-network": "198.51.100.0/24" 2962 } 2963 "udp": { 2964 "destination-port": { 2965 "operator": "eq", 2966 "port": 53 2967 } 2968 }, 2969 "actions": { 2970 "forwarding": "accept" 2971 } 2972 } 2973 ] 2974 } 2975 } 2976 ] 2977 } 2978 } 2980 Figure 34: Filtering IPv4 Fragmented Packets 2982 Figure 35 shows a POST request example issued by a DOTS client to its 2983 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 2984 port number 53, but to drop all fragmented packets. The following 2985 ACEs are defined (in this order): 2987 o "drop-all-fragments" ACE: discards all fragments (including atomic 2988 fragments). That is, IPv6 packets which include a Fragment header 2989 (44) are dropped. 2991 o "allow-dns-packets" ACE: accepts DNS packets destined to 2992 2001:db8::/32. 2994 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2995 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2996 Host: example.com 2997 Content-Type: application/yang-data+json 2998 { 2999 "ietf-dots-data-channel:acls": { 3000 "acl": [ 3001 { 3002 "name": "dns-fragments", 3003 "type": "ipv6-acl-type", 3004 "aces": { 3005 "ace": [ 3006 { 3007 "name": "drop-all-fragments", 3008 "matches": { 3009 "ipv6": { 3010 "fragment": { 3011 "operator": "match", 3012 "type": "isf" 3013 } 3014 } 3015 }, 3016 "actions": { 3017 "forwarding": "drop" 3018 } 3019 } 3020 ] 3021 "ace": [ 3022 { 3023 "name": "allow-dns-packets", 3024 "matches": { 3025 "ipv6": { 3026 "destination-ipv6-network": "2001:db8::/32" 3027 } 3028 "udp": { 3029 "destination-port": { 3030 "operator": "eq", 3031 "port": 53 3032 } 3033 } 3034 }, 3035 "actions": { 3036 "forwarding": "accept" 3037 } 3038 } 3039 ] 3040 } 3041 } 3042 ] 3043 } 3044 } 3046 Figure 35: Filtering IPv6 Fragmented Packets 3048 Authors' Addresses 3049 Mohamed Boucadair (editor) 3050 Orange 3051 Rennes 35000 3052 France 3054 Email: mohamed.boucadair@orange.com 3056 Tirumaleswar Reddy (editor) 3057 McAfee, Inc. 3058 Embassy Golf Link Business Park 3059 Bangalore, Karnataka 560071 3060 India 3062 Email: kondtir@gmail.com