idnits 2.17.1 draft-ietf-dots-data-channel-20.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 : ---------------------------------------------------------------------------- ** There are 22 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([I-D.ietf-netmod-acl-model], [I-D.ietf-dots-signal-channel]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 460 has weird spacing: '...er-port ine...' == Line 461 has weird spacing: '...er-port ine...' == Line 543 has weird spacing: '...warding ide...' == Line 838 has weird spacing: '... icmp typ...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o DOTS server MUST not enable both DOTS data channel and direct configuration to avoid race conditions and inconsistent configurations arising from simultaneous updates from multiple sources. -- The document date (September 9, 2018) is 2056 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 2083 -- Looks like a reference, but probably isn't: '6' on line 2083 -- Looks like a reference, but probably isn't: '17' on line 2083 -- Looks like a reference, but probably isn't: '58' on line 2083 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-25 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-19 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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-07 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-15 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 5 errors (**), 0 flaws (~~), 10 warnings (==), 7 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: March 13, 2019 McAfee 6 K. Nishizuka 7 NTT Communications 8 L. Xia 9 Huawei 10 P. Patil 11 Cisco 12 A. Mortensen 13 Arbor Networks, Inc. 14 N. Teague 15 Verisign, Inc. 16 September 9, 2018 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 Specification 20 draft-ietf-dots-data-channel-20 22 Abstract 24 The document specifies a Distributed Denial-of-Service Open Threat 25 Signaling (DOTS) data channel used for bulk exchange of data that 26 cannot easily or appropriately communicated through the DOTS signal 27 channel under attack conditions. 29 This is a companion document to the DOTS signal channel 30 specification. 32 Editorial Note (To be removed by RFC Editor) 34 Please update these statements within the document with the RFC 35 number to be assigned to this document: 37 o "This version of this YANG module is part of RFC XXXX;" 39 o "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 40 (DOTS) Data Channel Specification"; 42 o reference: RFC XXXX 44 Please update these statements with the RFC number to be assigned to 45 the following documents: 47 o "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 48 (DOTS) Signal Channel Specification" (used to be 49 [I-D.ietf-dots-signal-channel]) 51 o "RFC ZZZZ: Network Access Control List (ACL) YANG Data Model" 52 (used to be [I-D.ietf-netmod-acl-model]) 54 Please update the "revision" date of the YANG module. 56 Status of This Memo 58 This Internet-Draft is submitted in full conformance with the 59 provisions of BCP 78 and BCP 79. 61 Internet-Drafts are working documents of the Internet Engineering 62 Task Force (IETF). Note that other groups may also distribute 63 working documents as Internet-Drafts. The list of current Internet- 64 Drafts is at https://datatracker.ietf.org/drafts/current/. 66 Internet-Drafts are draft documents valid for a maximum of six months 67 and may be updated, replaced, or obsoleted by other documents at any 68 time. It is inappropriate to use Internet-Drafts as reference 69 material or to cite them other than as "work in progress." 71 This Internet-Draft will expire on March 13, 2019. 73 Copyright Notice 75 Copyright (c) 2018 IETF Trust and the persons identified as the 76 document authors. All rights reserved. 78 This document is subject to BCP 78 and the IETF Trust's Legal 79 Provisions Relating to IETF Documents 80 (https://trustee.ietf.org/license-info) in effect on the date of 81 publication of this document. Please review these documents 82 carefully, as they describe your rights and restrictions with respect 83 to this document. Code Components extracted from this document must 84 include Simplified BSD License text as described in Section 4.e of 85 the Trust Legal Provisions and are provided without warranty as 86 described in the Simplified BSD License. 88 Table of Contents 90 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 91 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 92 3. DOTS Data Channel . . . . . . . . . . . . . . . . . . . . . . 6 93 3.1. Design Overview . . . . . . . . . . . . . . . . . . . . . 6 94 3.2. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 95 3.3. NAT Considerations . . . . . . . . . . . . . . . . . . . 8 96 3.4. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 8 97 3.5. Detect and Prevent Infinite Loops . . . . . . . . . . . . 9 98 3.6. Stale Entries . . . . . . . . . . . . . . . . . . . . . . 10 99 4. DOTS Data Channel YANG Module . . . . . . . . . . . . . . . . 10 100 4.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 10 101 4.2. Filtering Fields . . . . . . . . . . . . . . . . . . . . 14 102 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 21 103 5. Managing DOTS Clients . . . . . . . . . . . . . . . . . . . . 36 104 5.1. Registering DOTS Clients . . . . . . . . . . . . . . . . 36 105 5.2. Uregistering DOTS Clients . . . . . . . . . . . . . . . . 39 106 6. Managing DOTS Aliases . . . . . . . . . . . . . . . . . . . . 39 107 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 39 108 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 43 109 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 45 110 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 45 111 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 45 112 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 47 113 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 50 114 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 56 115 8. Operational Considerations . . . . . . . . . . . . . . . . . 57 116 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 58 118 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 60 119 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 60 120 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 121 13.1. Normative References . . . . . . . . . . . . . . . . . . 60 122 13.2. Informative References . . . . . . . . . . . . . . . . . 61 123 Appendix A. Sample Examples: Filtering Fragments . . . . . . . . 63 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 66 126 1. Introduction 128 A distributed denial-of-service (DDoS) attack is an attempt to make 129 machines or network resources unavailable to their intended users. 130 In most cases, sufficient scale can be achieved by compromising 131 enough end-hosts and using those infected hosts to perpetrate and 132 amplify the attack. The victim of such attack can be an application 133 server, a router, a firewall, an entire network, etc. 135 As discussed in [I-D.ietf-dots-requirements], the lack of a common 136 method to coordinate a real-time response among involved actors and 137 network domains inhibits the speed and effectiveness of DDoS attack 138 mitigation. From that standpoint, DDoS Open Threat Signaling (DOTS) 139 defines an architecture that allows a DOTS client to send requests to 140 a DOTS server for DDoS attack mitigation 141 [I-D.ietf-dots-architecture]. The DOTS approach is thus meant to 142 minimize the impact of DDoS attacks, thereby contributing to the 143 enforcement of more efficient defensive if not proactive security 144 strategies. To that aim, DOTS defines two channels: the signal and 145 the data channels (Figure 1). 147 +---------------+ +---------------+ 148 | | <------- Signal Channel ------> | | 149 | DOTS Client | | DOTS Server | 150 | | <======= Data Channel ======> | | 151 +---------------+ +---------------+ 153 Figure 1: DOTS Channels 155 The DOTS signal channel is used to carry information about a device 156 or a network (or a part thereof) that is under a DDoS attack. Such 157 information is sent by a DOTS client to an upstream DOTS server so 158 that appropriate mitigation actions are undertaken on traffic deemed 159 suspicious. The DOTS signal channel is further elaborated in 160 [I-D.ietf-dots-signal-channel]. 162 As for the DOTS data channel, it is used for infrequent bulk data 163 exchange between DOTS agents to significantly improve the 164 coordination of all the parties involved in the response to the 165 attack. Section 2 of [I-D.ietf-dots-architecture] mentions that the 166 DOTS data channel is used to perform the following tasks: 168 o Creating aliases for resources for which mitigation may be 169 requested. 171 A DOTS client may submit to its DOTS server a collection of 172 prefixes which it would like to refer to by an alias when 173 requesting mitigation. The DOTS server can respond to this 174 request with either a success or failure response (see Section 2 175 in [I-D.ietf-dots-architecture]). 177 Refer to Section 6 for more details. 179 o Filter management, which enables a DOTS client to request the 180 installation or withdrawal of traffic filters, dropping or rate- 181 limiting unwanted traffic, and permitting white-listed traffic. A 182 DOTS client is entitled to instruct filtering rules only on IP 183 resources that belong to its domain. 185 Sample use cases for populating black- or white-list filtering 186 rules are detailed hereafter: 188 * If a network resource (DOTS client) detects a potential DDoS 189 attack from a set of IP addresses, the DOTS client informs its 190 servicing DOTS gateway of all suspect IP addresses that need to 191 be blocked or black-listed for further investigation. The DOTS 192 client could also specify a list of protocols and port numbers 193 in the black-list rule. 195 The DOTS gateway then propagates the black-listed IP addresses 196 to a DOTS server which will undertake appropriate actions so 197 that traffic originated by these IP addresses to the target 198 network (specified by the DOTS client) is blocked. 200 * A network, that has partner sites from which only legitimate 201 traffic arrives, may want to ensure that the traffic from these 202 sites is not subjected to DDoS attack mitigation. The DOTS 203 client uses the DOTS data channel to convey the white-listed IP 204 prefixes of the partner sites to its DOTS server. 206 The DOTS server uses this information to white-list flows 207 originated by such IP prefixes and which reach the network. 209 Refer to Section 7 for more details. 211 2. Terminology 213 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 214 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 215 document are to be interpreted as described in [RFC2119]. 217 The reader should be familiar with the terms defined in 218 [I-D.ietf-dots-requirements]. 220 The terminology for describing YANG data modules is defined in 221 [RFC7950]. The meaning of the symbols in tree diagrams is defined in 222 [RFC8340]. 224 This document generalizes the notion of Access Control List (ACL) so 225 that it is not device-specific [I-D.ietf-netmod-acl-model]. As such, 226 this document defines an ACL as an ordered set of rules that is used 227 to filter traffic. Each rule is represented by an Access Control 228 Entry (ACE). ACLs communicated via the DOTS data channel are not 229 bound to a device interface. 231 For the sake of simplicity, all of the examples in this document use 232 "/restconf" as the discovered RESTCONF API root path. Many protocol 233 header lines and message-body text within examples throughout the 234 document are split into multiple lines for display purposes only. 235 When a line ends with backslash ('\') as the last character, the line 236 is wrapped for display purposes. It is to be considered to be joined 237 to the next line by deleting the backslash, the following line break, 238 and the leading whitespace of the next line. 240 3. DOTS Data Channel 242 3.1. Design Overview 244 Unlike the DOTS signal channel, which must remain operational even 245 when confronted with signal degradation due to packets loss, the DOTS 246 data channel is not expected to be fully operational at all times, 247 especially when a DDoS attack is underway. The requirements for a 248 DOTS data channel protocol are documented in 249 [I-D.ietf-dots-requirements]. 251 This specification does not require an order of DOTS signal and data 252 channel creations nor mandates a time interval between them. These 253 considerations are implementation- and deployment-specific. 255 As the primary function of the data channel is data exchange, a 256 reliable transport mode is required in order for DOTS agents to 257 detect data delivery success or failure. This document uses RESTCONF 258 [RFC8040] over TLS [RFC5246] over TCP as the DOTS data channel 259 protocol. The abstract layering of DOTS data channel is shown in 260 Figure 2. 262 +-------------------+ 263 | DOTS Data Channel | 264 +-------------------+ 265 | RESTCONF | 266 +-------------------+ 267 | TLS | 268 +-------------------+ 269 | TCP | 270 +-------------------+ 271 | IP | 272 +-------------------+ 274 Figure 2: Abstract Layering of DOTS Data Channel 276 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 277 resources represented by DOTS data channel YANG data modules. These 278 basic edit operations allow the DOTS data channel running 279 configuration to be altered by a DOTS client. 281 DOTS data channel configuration information as well as state 282 information can be retrieved with the GET method. An HTTP status- 283 line header field is returned for each request to report success or 284 failure for RESTCONF operations (Section 5.4 of [RFC8040]). The 285 "error-tag" provides more information about encountered errors 286 (Section 7 of [RFC8040]). 288 DOTS clients perform the root resource discovery procedure discussed 289 in Section 3.1 of [RFC8040] to determine the root of the RESTCONF 290 API. After discovering the RESTCONF API root, a DOTS client uses 291 this value as the initial part of the path in the request URI, in any 292 subsequent request to the DOTS server. The DOTS server may support 293 the retrieval of the YANG modules it supports (Section 3.7 in 294 [RFC8040]). For example, a DOTS client may use RESTCONF to retrieve 295 the vendor-specific YANG modules supported by its DOTS server. 297 JavaScript Object Notation (JSON) [RFC8259] payload is used to 298 propagate the DOTS data channel specific payload messages that carry 299 request parameters and response information, such as errors. This 300 specification uses the encoding rules defined in [RFC7951] for 301 representing DOTS data channel configuration data using YANG 302 (Section 4) as JSON text. 304 A DOTS client registers itself to its DOTS server(s) in order to set 305 up DOTS data channel-related configuration data and receive state 306 data (i.e., non-configuration data) from the DOTS server(s) 307 (Section 5). Mutual authentication and coupling of signal and data 308 channels are specified in [I-D.ietf-dots-signal-channel]. 310 A single DOTS data channel between DOTS agents can be used to 311 exchange multiple requests and multiple responses. To reduce DOTS 312 client and DOTS server workload, DOTS clients SHOULD re-use the same 313 TLS session. While the communication to the DOTS server is 314 quiescent, the DOTS client MAY probe the server to ensure it has 315 maintained cryptographic state. Such probes can also keep alive 316 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 317 that the DOTS server still has TLS state by returning a TLS message. 319 A DOTS server may detect conflicting filtering requests from distinct 320 DOTS clients which belong to the same domain. For example, a DOTS 321 client could request to blacklist a prefix by specifying the source 322 prefix, while another DOTS client could request to whitelist that 323 same source prefix, but both having the same destination prefix. It 324 is out of scope of this specification to recommend the behavior to 325 follow for handling conflicting requests (e.g., reject all, reject 326 the new request, notify an administrator for validation). DOTS 327 servers SHOULD support a configuration parameter to indicate the 328 behavior to follow when a conflict is detected. Section 7.2 329 specifies the behavior when no instruction is supplied to a DOTS 330 server. 332 How filtering rules instantiated on a DOTS server are translated into 333 network configurations actions is out of scope. 335 3.2. DOTS Server(s) Discovery 337 This document assumes that DOTS clients are provisioned with the 338 reachability information of their DOTS server(s) using a variety of 339 means (e.g., local configuration, or dynamic means such as DHCP). 340 The specification of such means are out of scope of this document. 342 Likewise, it is out of scope of this document to specify the behavior 343 to be followed by a DOTS client to send DOTS requests when multiple 344 DOTS servers are provisioned (e.g., contact all DOTS servers, select 345 one DOTS server among the list). 347 3.3. NAT Considerations 349 In deployments where one or more translators (e.g., NAT44, NAT64, 350 NPTv6) are enabled between the client's network and the DOTS server, 351 DOTS data channel messages forwarded to a DOTS server MUST NOT 352 include internal IP addresses/prefixes and/or port numbers; external 353 addresses/prefixes and/or port numbers as assigned by the translator 354 MUST be used instead. This document does not make any recommendation 355 about possible translator discovery mechanisms. The following are 356 some (non-exhaustive) deployment examples that may be considered: 358 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 359 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 360 external addresses/prefixes and/or port numbers. Information 361 retrieved by means of PCP or STUN will be used to feed the DOTS 362 data channel messages that will be sent to a DOTS server. 364 o A DOTS gateway may be co-located with the translator. The DOTS 365 gateway will need to update the DOTS messages, based upon the 366 local translator's binding table. 368 3.4. DOTS Gateways 370 When a server-domain DOTS gateway is involved in DOTS data channel 371 exchanges, the same considerations for manipulating the 'cdid' 372 (client domain identifier) parameter specified in 373 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 374 reminder, 'cdid' is meant to assist the DOTS server to enforce some 375 policies (e.g., limit the number of filtering rules per DOTS client 376 or per DOTS client domain). A loop detect mechanism for DOTS 377 gateways is specified in Section 3.5. 379 If a DOTS gateway is involved, the DOTS gateway verifies that the 380 DOTS client is authorized to undertake a data channel action (e.g., 381 instantiate filtering rules). If the DOTS client is authorized, it 382 propagates the rules to the upstream DOTS server. Likewise, the DOTS 383 server verifies that the DOTS gateway is authorized to relay data 384 channel actions. For example, to create or purge filters, a DOTS 385 client sends its request to its DOTS gateway. The DOTS gateway 386 validates the rules in the request and proxies the requests 387 containing the filtering rules to its DOTS server. When the DOTS 388 gateway receives the associated response from the DOTS server, it 389 propagates the response back to the DOTS client. 391 3.5. Detect and Prevent Infinite Loops 393 In order to detect and prevent infinite loops, DOTS gateways MUST 394 support the procedure defined in Section 5.7.1 of [RFC7230]. In 395 particular, each intermediate DOTS gateway MUST check that none of 396 its own information (e.g., server names, literal IP addresses) is 397 present in the "Via" header of a DOTS message it receives: 399 o If it detects that its own information is present in the "Via" 400 header, the DOTS gateway MUST NOT forward the DOTS message. 401 Messages that cannot be forwarded because of a loop SHOULD be 402 logged with a "508 Loop Detected" status-line returned sent back 403 to the DOTS peer. The structure of the reported error is depicted 404 in Figure 3. 406 error-tag: loop-detected 407 error-type: transport, application 408 error-severity: error 409 error-info: : A copy of the Via header when 410 the loop was detected. 411 Description: An infinite loop has been detected when forwarding 412 a requests via a proxy. 414 Figure 3: Loop Detected Error 416 It is RECOMMENDED that DOTS clients and gateways support means to 417 alert administrators about loop errors so that appropriate actions 418 are undertaken. 420 o Otherwise, the DOTS agent MUST update or insert the "Via" header 421 by appending its own information. 423 Unless configured otherwise, DOTS gateways at the boundaries of a 424 DOTS client domain SHOULD remove the previous "Via" header 425 information after checking for a loop before forwarding. This 426 behavior is required for topology hiding purposes but also to 427 minimize potential conflicts that may arise if overlapping 428 information is used in distinct DOTS domains (e.g., private IPv4 429 addresses, non globally unique aliases). 431 3.6. Stale Entries 433 In order to avoid stale entries, a lifetime is associated with alias 434 and filtering entries created by DOTS clients. Also, DOTS servers 435 may track the inactivity timeout of DOTS clients to detect stale 436 entries. 438 4. DOTS Data Channel YANG Module 440 4.1. Tree Structure 442 The DOTS data channel YANG module (ietf-dots-data-channel) allows a 443 DOTS client to manage aliases for resources for which mitigation may 444 be requested. Such aliases may be used in subsequent DOTS signal 445 channel exchanges to refer more efficiently to the resources under 446 attack. 448 The tree structure for the DOTS alias is depicted in Figure 4. 450 module: ietf-dots-data-channel 451 +--rw dots-data 452 +--rw dots-client* [cuid] 453 | +--rw cuid string 454 | +--rw cdid? string 455 | +--rw aliases 456 | | +--rw alias* [name] 457 | | +--rw name string 458 | | +--rw target-prefix* inet:ip-prefix 459 | | +--rw target-port-range* [lower-port upper-port] 460 | | | +--rw lower-port inet:port-number 461 | | | +--rw upper-port inet:port-number 462 | | +--rw target-protocol* uint8 463 | | +--rw target-fqdn* inet:domain-name 464 | | +--rw target-uri* inet:uri 465 | | +--ro pending-lifetime? int32 466 | +--rw acls 467 | ... 468 +--ro capabilities 469 ... 471 Figure 4: DOTS Alias Subtree 473 Also, the 'ietf-dots-data-channel' module allows DOTS clients to 474 manage filtering rules. Examples of filtering management in a DOTS 475 context include, but not limited to: 477 o Black-list management, which enables a DOTS client to inform a 478 DOTS server about sources from which traffic should be discarded. 480 o White-list management, which enables a DOTS client to inform a 481 DOTS server about sources from which traffic should always be 482 accepted. 484 o Filter management, which enables a DOTS client to request the 485 installation or withdrawal of traffic filters, dropping or rate- 486 limiting unwanted traffic and permitting white-listed traffic. 488 The tree structure for the DOTS filtering entries is depicted in 489 Figure 5. 491 Early versions of this document investigated to what extent 492 augmenting 'ietf-access-control-list' meet DOTS requirements, but 493 that design approach was abandoned because it does not support 494 meeting many of DOTS requirements, e.g., 496 o Retrieve a filtering entry (or all entries) created by a DOTS 497 client. 499 o Delete a filtering entry that was instantiated by a DOTS client. 501 DOTS filtering entries (i.e., Access Control List (ACL)) mimic the 502 structure specified in [I-D.ietf-netmod-acl-model]. Concretely, DOTS 503 agents are assumed to manipulate an ordered list of ACLs; each ACL 504 contains a separately ordered list of Access Control Entries (ACEs). 505 Each ACE has a group of match and a group of action criteria. 507 Once all the ACE entries have been iterated though with no match, 508 then all the following ACL's ACE entries are iterated through until 509 the first match at which point the specified action is applied. If 510 there is no match, then there is no action to be taken against the 511 packet. 513 module: ietf-dots-data-channel 514 +--rw dots-data 515 +--rw dots-client* [cuid] 516 | +--rw cuid string 517 | +--rw cdid? string 518 | +--rw aliases 519 | | ... 520 | +--rw acls 521 | +--rw acl* [name] 522 | +--rw name string 523 | +--rw type? ietf-acl:acl-type 524 | +--rw activation-type? enumeration 525 | +--ro pending-lifetime? int32 526 | +--rw aces 527 | +--rw ace* [name] 528 | +--rw name string 529 | +--rw matches 530 | | +--rw (l3)? 531 | | | +--:(ipv4) 532 | | | | ... 533 | | | +--:(ipv6) 534 | | | ... 535 | | +--rw (l4)? 536 | | +--:(tcp) 537 | | | ... 538 | | +--:(udp) 539 | | | ... 540 | | +--:(icmp) 541 | | ... 542 | +--rw actions 543 | | +--rw forwarding identityref 544 | | +--rw rate-limit? decimal64 545 | +--ro statistics 546 | +--ro matched-packets? yang:counter64 547 | +--ro matched-octets? yang:counter64 548 +--ro capabilities 549 ... 551 Figure 5: DOTS ACLs Subtree 553 Filtering rules instructed by a DOTS client assumes a default 554 direction: the destination is the DOTS client domain. 556 DOTS forwarding actions can be 'accept' (i.e., accept matching 557 traffic) or 'drop' (i.e., drop matching traffic without sending any 558 ICMP error message). Accepted traffic can be subject to rate 559 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 560 matching traffic and send an ICMP error message to the source) is not 561 supported in 'ietf-dots-data-channel' because it is not appropriate 562 in the context of DDoS mitigation. Generating ICMP messages to 563 notify drops when mitigating a DDoS attack will exacerbate the DDoS 564 attack. Furthermore, these ICMP messages will be used by an attacker 565 as an explicit signal that the traffic is being blocked. 567 4.2. Filtering Fields 569 The 'ietf-dots-data-channel' module reuses the packet fields module 570 'ietf-packet-fields' [I-D.ietf-netmod-acl-model] which defines 571 matching on fields in the packet including IPv4, IPv6, and transport 572 layer fields. 574 This specification defines a new IPv4/IPv6 matching field called 575 'fragment' to efficiently handle fragment-related filtering rules. 576 Indeed, [I-D.ietf-netmod-acl-model] does not support such capability 577 for IPv6 but offers a partial support for IPv4 by means of 'flags'. 578 Nevertheless, the use of 'flags' is problematic since it does not 579 allow to define a bitmask. For example, setting other bits not 580 covered by the 'flags' filtering clause in a packet will allow that 581 packet to get through (because it won't match the ACE). Sample 582 examples to illustrate how 'fragment' can be used are provided in 583 Appendix A. 585 Figure 6 shows the IPv4 match subtree. 587 module: ietf-dots-data-channel 588 +--rw dots-data 589 +--rw dots-client* [cuid] 590 | ... 591 | +--rw acls 592 | +--rw acl* [name] 593 | ... 594 | +--rw aces 595 | +--rw ace* [name] 596 | +--rw name string 597 | +--rw matches 598 | | +--rw (l3)? 599 | | | +--:(ipv4) 600 | | | | +--rw ipv4 601 | | | | +--rw dscp? inet:dscp 602 | | | | +--rw ecn? uint8 603 | | | | +--rw length? uint16 604 | | | | +--rw ttl? uint8 605 | | | | +--rw protocol? uint8 606 | | | | +--rw ihl? uint8 607 | | | | +--rw flags? bits 608 | | | | +--rw offset? uint16 609 | | | | +--rw identification? uint16 610 | | | | +--rw (destination-network)? 611 | | | | | +--:(destination-ipv4-network) 612 | | | | | +--rw destination-ipv4-network? 613 | | | | | inet:ipv4-prefix 614 | | | | +--rw (source-network)? 615 | | | | | +--:(source-ipv4-network) 616 | | | | | +--rw source-ipv4-network? 617 | | | | | inet:ipv4-prefix 618 | | | | +--rw fragment 619 | | | | +--rw operator? operator 620 | | | | +--rw type fragment-type 621 | | | +--:(ipv6) 622 | | | ... 623 | | +--rw (l4)? 624 | | ... 625 | +--rw actions 626 | | ... 627 | +--ro statistics 628 | ... 629 +--ro capabilities 630 ... 632 Figure 6: DOTS ACLs Subtree (IPv4 Match) 634 Figure 7 shows the IPv6 match subtree. 636 module: ietf-dots-data-channel 637 +--rw dots-data 638 +--rw dots-client* [cuid] 639 | ... 640 | +--rw acls 641 | +--rw acl* [name] 642 | ... 643 | +--rw aces 644 | +--rw ace* [name] 645 | +--rw name string 646 | +--rw matches 647 | | +--rw (l3)? 648 | | | +--:(ipv4) 649 | | | | ... 650 | | | +--:(ipv6) 651 | | | +--rw ipv6 652 | | | +--rw dscp? inet:dscp 653 | | | +--rw ecn? uint8 654 | | | +--rw length? uint16 655 | | | +--rw ttl? uint8 656 | | | +--rw protocol? uint8 657 | | | +--rw (destination-network)? 658 | | | | +--:(destination-ipv6-network) 659 | | | | +--rw destination-ipv6-network? 660 | | | | inet:ipv6-prefix 661 | | | +--rw (source-network)? 662 | | | | +--:(source-ipv6-network) 663 | | | | +--rw source-ipv6-network? 664 | | | | inet:ipv6-prefix 665 | | | +--rw flow-label? 666 | | | | inet:ipv6-flow-label 667 | | | +--rw fragment 668 | | | +--rw operator? operator 669 | | | +--rw type fragment-type 670 | | +--rw (l4)? 671 | | ... 672 | +--rw actions 673 | | ... 674 | +--ro statistics 675 | ... 676 +--ro capabilities 677 ... 679 Figure 7: DOTS ACLs Subtree (IPv6 Match) 681 Figure 8 shows the TCP match subtree. In addition to the fields 682 defined in [I-D.ietf-netmod-acl-model], this specification defines a 683 new TCP matching field, called 'flags-bitmask', to efficiently handle 684 TCP flags filtering rules. 686 module: ietf-dots-data-channel 687 +--rw dots-data 688 +--rw dots-client* [cuid] 689 | ... 690 | +--rw acls 691 | +--rw acl* [name] 692 | ... 693 | +--rw aces 694 | +--rw ace* [name] 695 | +--rw name string 696 | +--rw matches 697 | | +--rw (l3)? 698 | | | ... 699 | | +--rw (l4)? 700 | | +--:(tcp) 701 | | | +--rw tcp 702 | | | +--rw sequence-number? uint32 703 | | | +--rw acknowledgement-number? uint32 704 | | | +--rw data-offset? uint8 705 | | | +--rw reserved? uint8 706 | | | +--rw flags? bits 707 | | | +--rw window-size? uint16 708 | | | +--rw urgent-pointer? uint16 709 | | | +--rw options? uint32 710 | | | +--rw flags-bitmask 711 | | | | +--rw operator? operator 712 | | | | +--rw bitmask uint16 713 | | | +--rw (source-port)? 714 | | | | +--:(source-port-range-or-operator) 715 | | | | +--rw source-port-range-or-operator 716 | | | | +--rw (port-range-or-operator)? 717 | | | | +--:(range) 718 | | | | | +--rw lower-port 719 | | | | | | inet:port-number 720 | | | | | +--rw upper-port 721 | | | | | inet:port-number 722 | | | | +--:(operator) 723 | | | | +--rw operator? 724 | | | | | operator 725 | | | | +--rw port 726 | | | | inet:port-number 727 | | | +--rw (destination-port)? 728 | | | +--:(destination-port-range-or-operator) 729 | | | +--rw destination-port-range-or-operator 730 | | | +--rw (port-range-or-operator)? 731 | | | +--:(range) 732 | | | | +--rw lower-port 733 | | | | | inet:port-number 734 | | | | +--rw upper-port 735 | | | | inet:port-number 736 | | | +--:(operator) 737 | | | +--rw operator? 738 | | | | operator 739 | | | +--rw port 740 | | | inet:port-number 741 | | +--:(udp) 742 | | | ... 743 | | +--:(icmp) 744 | | ... 745 | +--rw actions 746 | | ... 747 | +--ro statistics 748 | ... 749 +--ro capabilities 750 ... 752 Figure 8: DOTS ACLs Subtree (TCP Match) 754 Figure 9 shows the UDP and ICMP match subtree. 756 module: ietf-dots-data-channel 757 +--rw dots-data 758 +--rw dots-client* [cuid] 759 | ... 760 | +--rw acls 761 | +--rw acl* [name] 762 | ... 763 | +--rw aces 764 | +--rw ace* [name] 765 | +--rw name string 766 | +--rw matches 767 | | +--rw (l3)? 768 | | | ... 769 | | +--rw (l4)? 770 | | +--:(tcp) 771 | | | ... 772 | | +--:(udp) 773 | | | +--rw udp 774 | | | +--rw length? uint16 775 | | | +--rw (source-port)? 776 | | | | +--:(source-port-range-or-operator) 777 | | | | +--rw source-port-range-or-operator 778 | | | | +--rw (port-range-or-operator)? 779 | | | | +--:(range) 780 | | | | | +--rw lower-port 781 | | | | | | inet:port-number 782 | | | | | +--rw upper-port 783 | | | | | inet:port-number 784 | | | | +--:(operator) 785 | | | | +--rw operator? 786 | | | | | operator 787 | | | | +--rw port 788 | | | | inet:port-number 789 | | | +--rw (destination-port)? 790 | | | +--:(destination-port-range-or-operator) 791 | | | +--rw destination-port-range-or-operator 792 | | | +--rw (port-range-or-operator)? 793 | | | +--:(range) 794 | | | | +--rw lower-port 795 | | | | | inet:port-number 796 | | | | +--rw upper-port 797 | | | | inet:port-number 798 | | | +--:(operator) 799 | | | +--rw operator? 800 | | | | operator 801 | | | +--rw port 802 | | | inet:port-number 803 | | +--:(icmp) 804 | | +--rw icmp 805 | | +--rw type? uint8 806 | | +--rw code? uint8 807 | | +--rw rest-of-header? uint32 808 | +--rw actions 809 | | ... 810 | +--ro statistics 811 | ... 812 +--ro capabilities 813 ... 815 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 817 DOTS implementations MUST support the following matching criteria: 819 match based on the IP header (IPv4 and IPv6), match based on the 820 transport header (TCP, UDP, and ICMP), and any combination 821 thereof. The same matching fields are used for both ICMP and 822 ICMPv6. 824 The following match fields MUST be supported by DOTS implementations 825 (Table 1): 827 ACL Mandatory Fields 828 Match 829 ------- ------------------------------------------------------------- 830 ipv4 length, protocol, destination-ipv4-network, source- 831 ipv4-network, and fragment 832 ipv6 length, protocol, destination-ipv6-network, source- 833 ipv6-network, and fragment 834 tcp flags-bitmask, source-port-range-or-operator, and 835 destination-port-range-or-operator 836 udp length, source-port-range-or-operator, and destination-port- 837 range-or-operator 838 icmp type and code 840 Table 1: Mandatory DOTS Channel Match Fields 842 Implementations MAY support other filtering match fields and actions. 843 The 'ietf-dots-data-channel' allows an implementation to expose its 844 filtering capabilities. The tree structure of the 'capabilities' is 845 shown in Figure 10. 847 module: ietf-dots-data-channel 848 +--rw dots-data 849 ... 850 +--ro capabilities 851 +--ro address-family* enumeration 852 +--ro forwarding-actions* identityref 853 +--ro rate-limit? boolean 854 +--ro transport-protocols* uint8 855 +--ro ipv4 856 | +--ro dscp? boolean 857 | +--ro ecn? boolean 858 | +--ro length? boolean 859 | +--ro ttl? boolean 860 | +--ro protocol? boolean 861 | +--ro ihl? boolean 862 | +--ro flags? boolean 863 | +--ro offset? boolean 864 | +--ro identification? boolean 865 | +--ro source-prefix? boolean 866 | +--ro destination-prefix? boolean 867 | +--ro fragment? boolean 868 +--ro ipv6 869 | +--ro dscp? boolean 870 | +--ro ecn? boolean 871 | +--ro flow-label? boolean 872 | +--ro length? boolean 873 | +--ro protocol? boolean 874 | +--ro hoplimit? boolean 875 | +--ro source-prefix? boolean 876 | +--ro destination-prefix? boolean 877 | +--ro fragment? boolean 878 +--ro tcp 879 | +--ro sequence-number? boolean 880 | +--ro acknowledgement-number? boolean 881 | +--ro data-offset? boolean 882 | +--ro reserved? boolean 883 | +--ro flags? boolean 884 | +--ro flags-bitmask? boolean 885 | +--ro window-size? boolean 886 | +--ro urgent-pointer? boolean 887 | +--ro options? boolean 888 | +--ro source-port? boolean 889 | +--ro destination-port? boolean 890 | +--ro port-range? boolean 891 +--ro udp 892 | +--ro length? boolean 893 | +--ro source-port? boolean 894 | +--ro destination-port? boolean 895 | +--ro port-range? boolean 896 +--ro icmp 897 +--ro type? boolean 898 +--ro code? boolean 899 +--ro rest-of-header? boolean 901 Figure 10: Filtering Capabilities Sub-Tree 903 4.3. YANG Module 905 file "ietf-dots-data-channel@2018-07-25.yang" 907 module ietf-dots-data-channel { 908 yang-version 1.1; 909 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 910 prefix data-channel; 912 import ietf-access-control-list { 913 prefix ietf-acl; 914 } 915 import ietf-packet-fields { 916 prefix packet-fields; 917 } 918 import ietf-dots-signal-channel { 919 prefix dots-signal; 920 } 922 organization 923 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 924 contact 925 "WG Web: 926 WG List: 928 Editor: Mohamed Boucadair 929 931 Editor: Konda, Tirumaleswar Reddy 932 934 Author: Jon Shallow 935 937 Author: Kaname Nishizuka 938 940 Author: Liang Xia 941 943 Author: Prashanth Patil 944 946 Author: Andrew Mortensen 947 949 Author: Nik Teague 950 "; 951 description 952 "This module contains YANG definition for configuring 953 aliases for resources and filtering rules using DOTS 954 data channel. 956 Copyright (c) 2018 IETF Trust and the persons identified as 957 authors of the code. All rights reserved. 959 Redistribution and use in source and binary forms, with or 960 without modification, is permitted pursuant to, and subject 961 to the license terms contained in, the Simplified BSD License 962 set forth in Section 4.c of the IETF Trust's Legal Provisions 963 Relating to IETF Documents 964 (http://trustee.ietf.org/license-info). 966 This version of this YANG module is part of RFC XXXX; see 967 the RFC itself for full legal notices."; 969 revision 2018-07-25 { 970 description 971 "Initial revision."; 972 reference 973 "RFC XXXX: Distributed Denial-of-Service Open Threat 974 Signaling (DOTS) Data Channel Specification"; 975 } 977 typedef operator { 978 type bits { 979 bit not { 980 position 0; 981 description 982 "If set, logical negation of operation."; 983 } 984 bit match { 985 position 1; 986 description 987 "Match bit. If set, this is a bitwise match operation 988 defined as '(data & value) == value'; if unset, (data & 989 value) evaluates to TRUE if any of the bits in the value 990 mask are set in the data."; 991 } 992 } 993 description 994 "How to apply the defined bitmask."; 995 } 997 grouping tcp-flags { 998 leaf operator { 999 type operator; 1000 default match; 1001 description 1002 "How to interpret the TCP flags."; 1003 } 1004 leaf bitmask { 1005 type uint16; 1006 mandatory true; 1007 description 1008 "Bitmask values can be encoded as a 1- or 2-byte bitmask. 1009 When a single byte is specified, it matches byte 13 1010 of the TCP header, which contains bits 8 though 15 1011 of the 4th 32-bit word. When a 2-byte encoding is used, 1012 it matches bytes 12 and 13 of the TCP header with 1013 the data offset field having a 'don't care' value."; 1014 } 1015 description 1016 "Operations on TCP flags."; 1017 } 1018 typedef fragment-type { 1019 type bits { 1020 bit df { 1021 position 0; 1022 description 1023 "Don't fragment bit for IPv4. 1024 This bit must be set to 0 for IPv6."; 1025 } 1026 bit isf { 1027 position 1; 1028 description 1029 "Is a fragment."; 1030 } 1031 bit ff { 1032 position 2; 1033 description 1034 "First fragment."; 1035 } 1036 bit lf { 1037 position 3; 1038 description 1039 "Last fragment."; 1040 } 1041 } 1042 description 1043 "Different fragment types to match against."; 1044 } 1046 grouping fragment-fields { 1047 leaf operator { 1048 type operator; 1049 default match; 1050 description 1051 "How to interpret the fragment type."; 1052 } 1053 leaf type { 1054 type fragment-type; 1055 mandatory true; 1056 description 1057 "What fragment type to look for."; 1058 } 1059 description 1060 "Operations on fragment types."; 1061 } 1063 grouping aliases { 1064 description 1065 "Top level container for aliases"; 1067 list alias { 1068 key "name"; 1069 description 1070 "List of aliases"; 1071 leaf name { 1072 type string; 1073 description 1074 "The name of the alias"; 1075 } 1076 uses dots-signal:target; 1077 leaf pending-lifetime { 1078 type int32; 1079 units "minutes"; 1080 config false; 1081 description 1082 "Indicates the pending validity lifetime of the alias 1083 entry."; 1084 } 1085 } 1086 } 1088 grouping ports { 1089 choice source-port { 1090 container source-port-range-or-operator { 1091 uses packet-fields:port-range-or-operator; 1092 description 1093 "Source port definition."; 1094 } 1095 description 1096 "Choice of specifying the source port or referring to 1097 a group of source ports."; 1098 } 1099 choice destination-port { 1100 container destination-port-range-or-operator { 1101 uses packet-fields:port-range-or-operator; 1102 description 1103 "Destination port definition."; 1104 } 1105 description 1106 "Choice of specifying a destination port or referring 1107 to a group of destination ports."; 1108 } 1109 description 1110 "Choice of specifying a source or destination ports."; 1111 } 1113 grouping access-lists { 1114 description 1115 "Specifies the ordered set of Access Control Lists."; 1116 list acl { 1117 key "name"; 1118 ordered-by user; 1119 description 1120 "An Access Control List (ACL) is an ordered list of 1121 Access Control Entries (ACE). Each Access Control Entry 1122 has a list of match criteria and a list of actions."; 1123 leaf name { 1124 type string { 1125 length "1..64"; 1126 } 1127 description 1128 "The name of the access list."; 1129 reference 1130 "RFC ZZZZ: Network Access Control List (ACL) 1131 YANG Data Model"; 1132 } 1133 leaf type { 1134 type ietf-acl:acl-type; 1135 description 1136 "Type of access control list. Indicates the primary intended 1137 type of match criteria (e.g., IPv4, IPv6) used in the list 1138 instance."; 1139 reference 1140 "RFC ZZZZ: Network Access Control List (ACL) 1141 YANG Data Model"; 1142 } 1143 leaf activation-type { 1144 type enumeration { 1145 enum "activate-when-mitigating" { 1146 value 1; 1147 description 1148 "The ACL is installed only when a mitigation is active. 1149 The ACL is specific to this DOTS client."; 1150 } 1151 enum "immediate" { 1152 value 2; 1153 description 1154 "The ACL is immediately activated."; 1155 } 1156 } 1157 description 1158 "Indicates whether an ACL is to be installed immediately 1159 or when a mitigation is active."; 1160 } 1161 leaf pending-lifetime { 1162 type int32; 1163 units "minutes"; 1164 config false; 1165 description 1166 "Indicates the pending validity lifetime of the alias 1167 entry."; 1168 } 1169 container aces { 1170 description 1171 "The Access Control Entries container contains 1172 a list of ACEs."; 1173 list ace { 1174 key "name"; 1175 ordered-by user; 1176 description 1177 "List of access list entries."; 1178 leaf name { 1179 type string { 1180 length "1..64"; 1181 } 1182 description 1183 "A unique name identifying this Access List 1184 Entry (ACE)."; 1185 reference 1186 "RFC ZZZZ: Network Access Control List (ACL) 1187 YANG Data Model"; 1188 } 1189 container matches { 1190 description 1191 "The rules in this set determine what fields will be 1192 matched upon before any action is taken on them. 1194 If no matches are defined in a particular container, 1195 then any packet will match that container. 1197 If no matches are specified at all in an ACE, then any 1198 packet will match the ACE."; 1199 reference 1200 "RFC ZZZZ: Network Access Control List (ACL) 1201 YANG Data Model"; 1203 choice l3 { 1204 container ipv4 { 1205 when "derived-from(../../../../type," + 1206 "'ietf-acl:ipv4-acl-type')"; 1207 uses packet-fields:acl-ip-header-fields; 1208 uses packet-fields:acl-ipv4-header-fields; 1209 container fragment { 1210 description 1211 "Indicates how to handle IPv4 fragments."; 1212 uses fragment-fields; 1213 } 1214 description 1215 "Rule set that matches IPv4 header."; 1216 } 1217 container ipv6 { 1218 when "derived-from(../../../../type," + 1219 "'ietf-acl:ipv6-acl-type')"; 1220 uses packet-fields:acl-ip-header-fields; 1221 uses packet-fields:acl-ipv6-header-fields; 1222 container fragment { 1223 description 1224 "Indicates how to handle IPv6 fragments."; 1225 uses fragment-fields; 1226 } 1227 description 1228 "Rule set that matches IPv6 header."; 1229 } 1230 description 1231 "Either IPv4 or IPv6."; 1232 } 1233 choice l4 { 1234 container tcp { 1235 uses packet-fields:acl-tcp-header-fields; 1236 container flags-bitmask { 1237 description 1238 "Indicates how to handle TCP flags."; 1239 uses tcp-flags; 1240 } 1241 uses ports; 1242 description 1243 "Rule set that matches TCP header."; 1244 } 1245 container udp { 1246 uses packet-fields:acl-udp-header-fields; 1247 uses ports; 1248 description 1249 "Rule set that matches UDP header."; 1250 } 1251 container icmp { 1252 uses packet-fields:acl-icmp-header-fields; 1253 description 1254 "Rule set that matches ICMP/ICMPv6 header."; 1255 } 1256 description 1257 "Can be TCP, UDP, or ICMP/ICMPv6"; 1258 } 1260 } 1261 container actions { 1262 description 1263 "Definitions of action for this ACE."; 1264 leaf forwarding { 1265 type identityref { 1266 base ietf-acl:forwarding-action; 1267 } 1268 mandatory true; 1269 description 1270 "Specifies the forwarding action per ACE."; 1271 reference 1272 "RFC ZZZZ: Network Access Control List (ACL) 1273 YANG Data Model"; 1274 } 1275 leaf rate-limit { 1276 when "../forwarding = 'ietf-acl:accept'" { 1277 description 1278 "rate-limit valid only when accept action is used"; 1279 } 1280 type decimal64 { 1281 fraction-digits 2; 1282 } 1283 description 1284 "rate-limit traffic"; 1285 } 1286 } 1287 container statistics { 1288 config false; 1289 description 1290 "Aggregate statistics."; 1291 uses ietf-acl:acl-counters; 1292 } 1293 } 1294 } 1295 } 1296 } 1298 container dots-data { 1299 description 1300 "Main container for DOTS data channel."; 1301 list dots-client { 1302 key "cuid"; 1303 description 1304 "List of DOTS clients."; 1305 leaf cuid { 1306 type string; 1307 description 1308 "A unique identifier that is randomly generated by 1309 a DOTS client to prevent request collisions."; 1310 reference 1311 "RFC YYYY: Distributed Denial-of-Service Open Threat 1312 Signaling (DOTS) Signal Channel Specification"; 1313 } 1314 leaf cdid { 1315 type string; 1316 description 1317 "A client domain identifier conveyed by a 1318 server-domain DOTS gateway to a remote DOTS server."; 1319 reference 1320 "RFC YYYY: Distributed Denial-of-Service Open Threat 1321 Signaling (DOTS) Signal Channel Specification"; 1322 } 1323 container aliases { 1324 description 1325 "Set of aliases that are bound to a DOTS client."; 1326 uses aliases; 1327 } 1328 container acls { 1329 description 1330 "Access lists that are bound to a DOTS client."; 1331 uses access-lists; 1332 } 1333 } 1334 container capabilities { 1335 config false; 1336 description 1337 "Match capabilities"; 1338 leaf-list address-family { 1339 type enumeration { 1340 enum "ipv4" { 1341 description 1342 "IPv4 is supported."; 1343 } 1344 enum "ipv6" { 1345 description 1346 "IPv6 is supported."; 1347 } 1348 } 1349 description 1350 "Indicates the IP address families supported by 1351 the DOTS server."; 1352 } 1353 leaf-list forwarding-actions { 1354 type identityref { 1355 base ietf-acl:forwarding-action; 1357 } 1358 description 1359 "Supported forwarding action(s)."; 1360 } 1361 leaf rate-limit { 1362 type boolean; 1363 description 1364 "Support of rate-limit action."; 1365 } 1366 leaf-list transport-protocols { 1367 type uint8; 1368 description 1369 "Upper-layer protocol associated with this mapping. 1371 Values are taken from the IANA protocol registry: 1372 https://www.iana.org/assignments/protocol-numbers/ 1373 protocol-numbers.xhtml 1375 For example, this field contains 6 (TCP) for a TCP 1376 mapping or 17 (UDP) for a UDP mapping."; 1377 } 1378 container ipv4 { 1379 description 1380 "Indicates IPv4 header fields that are supported to enforce 1381 ACLs."; 1382 leaf dscp { 1383 type boolean; 1384 description 1385 "Support of filtering based on DSCP."; 1386 } 1387 leaf ecn { 1388 type boolean; 1389 description 1390 "Support of filtering based on ECN."; 1391 } 1392 leaf length { 1393 type boolean; 1394 description 1395 "Support of filtering based on the Total Length."; 1396 } 1397 leaf ttl { 1398 type boolean; 1399 description 1400 "Support of filtering based on the TTL."; 1401 } 1402 leaf protocol { 1403 type boolean; 1404 description 1405 "Support of filtering based on protocol field."; 1406 } 1407 leaf ihl { 1408 type boolean; 1409 description 1410 "Support of filtering based on the Internet Header 1411 Length (IHL)."; 1412 } 1413 leaf flags { 1414 type boolean; 1415 description 1416 "Support of filtering based on the 'flags'"; 1417 } 1418 leaf offset { 1419 type boolean; 1420 description 1421 "Support of filtering based on the 'offset'."; 1422 } 1423 leaf identification { 1424 type boolean; 1425 description 1426 "Support of filtering based on the 'identification'."; 1427 } 1428 leaf source-prefix { 1429 type boolean; 1430 description 1431 "Support of filtering based on the source prefix."; 1432 } 1433 leaf destination-prefix { 1434 type boolean; 1435 description 1436 "Support of filtering based on the destination prefix."; 1437 } 1438 leaf fragment { 1439 type boolean; 1440 description 1441 "Indicates the capability of a DOTS server to 1442 enforce filters on IPv4 fragments. That is 'fragment' 1443 clause is supported."; 1444 } 1445 } 1446 container ipv6 { 1447 description 1448 "Indicates IPv6 header fields that are supported to enforce 1449 ACLs."; 1450 leaf dscp { 1451 type boolean; 1452 description 1453 "Support of filtering based on DSCP."; 1454 } 1455 leaf ecn { 1456 type boolean; 1457 description 1458 "Support of filtering based on ECN."; 1459 } 1460 leaf flow-label { 1461 type boolean; 1462 description 1463 "Support of filtering based on the Flow label."; 1464 } 1465 leaf length { 1466 type boolean; 1467 description 1468 "Support of filtering based on the Payload Length."; 1469 } 1470 leaf protocol { 1471 type boolean; 1472 description 1473 "Support of filtering based on the Next Header field."; 1474 } 1475 leaf hoplimit { 1476 type boolean; 1477 description 1478 "Support of filtering based on the Hop Limit."; 1479 } 1480 leaf source-prefix { 1481 type boolean; 1482 description 1483 "Support of filtering based on the source prefix."; 1484 } 1485 leaf destination-prefix { 1486 type boolean; 1487 description 1488 "Support of filtering based on the destination prefix."; 1489 } 1490 leaf fragment { 1491 type boolean; 1492 description 1493 "Indicates the capability of a DOTS server to 1494 enforce filters on IPv6 fragments."; 1495 } 1496 } 1497 container tcp { 1498 description 1499 "Set of TCP fields that are supported by the DOTS server 1500 to enfoce filters."; 1502 leaf sequence-number { 1503 type boolean; 1504 description 1505 "Support of filtering based on the TCP sequence number."; 1506 } 1507 leaf acknowledgement-number { 1508 type boolean; 1509 description 1510 "Support of filtering based on the TCP acknowledgement 1511 number."; 1512 } 1513 leaf data-offset { 1514 type boolean; 1515 description 1516 "Support of filtering based on the TCP data-offset."; 1517 } 1518 leaf reserved { 1519 type boolean; 1520 description 1521 "Support of filtering based on the TCP reserved field."; 1522 } 1523 leaf flags { 1524 type boolean; 1525 description 1526 "Support of filtering, as defined in RFC ZZZZ, based 1527 on the TCP flags."; 1528 } 1529 leaf flags-bitmask { 1530 type boolean; 1531 description 1532 "Support of filtering based on the TCP flags bitmask."; 1533 } 1534 leaf window-size { 1535 type boolean; 1536 description 1537 "Support of filtering based on the TCP window size."; 1538 } 1539 leaf urgent-pointer { 1540 type boolean; 1541 description 1542 "Support of filtering based on the TCP urgent pointer."; 1543 } 1544 leaf options { 1545 type boolean; 1546 description 1547 "Support of filtering based on the TCP options."; 1548 } 1549 leaf source-port { 1550 type boolean; 1551 description 1552 "Support of filtering based on the source port number."; 1553 } 1554 leaf destination-port { 1555 type boolean; 1556 description 1557 "Support of filtering based on the destination port 1558 number."; 1559 } 1560 leaf port-range { 1561 type boolean; 1562 description 1563 "Support of filtering based on a port range."; 1564 } 1565 } 1566 container udp { 1567 description 1568 "Set of UDP fields that are supported by the DOTS server 1569 to enforce filters."; 1570 leaf length { 1571 type boolean; 1572 description 1573 "Support of filtering based on the UDP length."; 1574 } 1575 leaf source-port { 1576 type boolean; 1577 description 1578 "Support of filtering based on the source port number."; 1579 } 1580 leaf destination-port { 1581 type boolean; 1582 description 1583 "Support of filtering based on the destination port 1584 number."; 1585 } 1586 leaf port-range { 1587 type boolean; 1588 description 1589 "Support of filtering based on a port range."; 1590 } 1591 } 1592 container icmp { 1593 description 1594 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1595 server to enforce filters."; 1596 leaf type { 1597 type boolean; 1598 description 1599 "Support of filtering based on the ICMP/ICMPv6 type."; 1600 } 1601 leaf code { 1602 type boolean; 1603 description 1604 "Support of filtering based on the ICMP/ICMPv6 code."; 1605 } 1606 leaf rest-of-header { 1607 type boolean; 1608 description 1609 "Support of filtering based on the ICMP four-bytes 1610 field."; 1611 } 1612 } 1613 } 1614 } 1615 } 1616 1618 5. Managing DOTS Clients 1620 5.1. Registering DOTS Clients 1622 In order to make use of DOTS data channel, a DOTS client MUST 1623 register to its DOTS server(s) by creating a DOTS client ('dots- 1624 client') resource. To that aim, DOTS clients SHOULD send a POST 1625 request (shown in Figure 11). 1627 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1628 Host: {host}:{port} 1629 Content-Type: application/yang-data+json 1630 { 1631 "ietf-dots-data-channel:dots-client": [ 1632 { 1633 "cuid": "string" 1634 } 1635 ] 1636 } 1638 Figure 11: POST to Register 1640 The 'cuid' (client unique identifier) parameter is described below: 1642 cuid: A globally unique identifier that is meant to prevent 1643 collisions among DOTS clients. This attribute has the same 1644 meaning, syntax, and processing rules as the 'cuid' attribute 1645 defined in [I-D.ietf-dots-signal-channel]. 1647 DOTS clients MUST use the same 'cuid' for both signal and data 1648 channels. 1650 This is a mandatory attribute. 1652 In deployments where server-domain DOTS gateways are enabled, 1653 identity information about the origin source client domain SHOULD be 1654 supplied to the DOTS server. That information is meant to assist the 1655 DOTS server to enforce some policies. These policies can be enforced 1656 per-client, per-client domain, or both. Figure 12 shows an example 1657 of a request relayed by a server-domain DOTS gateway. 1659 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1660 Host: {host}:{port} 1661 Content-Type: application/yang-data+json 1662 { 1663 "ietf-dots-data-channel:dots-client": [ 1664 { 1665 "cuid": "string", 1666 "cdid": "string" 1667 } 1668 ] 1669 } 1671 Figure 12: POST to Register (DOTS Gateway) 1673 A server-domain DOTS gateway SHOULD add the following attribute: 1675 cdid: This attribute has the same meaning, syntax, and processing 1676 rules as the 'cdid' attribute defined in 1677 [I-D.ietf-dots-signal-channel]. 1679 In deployments where server-domain DOTS gateways are enabled, 1680 'cdid' does not need to be inserted when relaying DOTS methods to 1681 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1682 servers are responsible for maintaining the association between 1683 'cdid' and 'cuid' for policy enforcement purposes. 1685 This is an optional attribute. 1687 A request example to create a 'dots-client' resource is depicted in 1688 Figure 13. This request is relayed by a server-domain DOTS gateway 1689 as hinted by the presence of the 'cdid' attribute. 1691 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1692 Host: {host}:{port} 1693 Content-Type: application/yang-data+json 1694 { 1695 "ietf-dots-data-channel:dots-client": [ 1696 { 1697 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1698 "cdid": "7eeaf349529eb55ed50113" 1699 } 1700 ] 1701 } 1703 Figure 13: POST to Register (DOTS gateway) 1705 DOTS servers MUST limit the number of 'dots-client' resources to be 1706 created by the same DOTS client to 1 per request. Requests with 1707 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1708 To that aim, the DOTS server MUST rely on the same procedure to 1709 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1710 [I-D.ietf-dots-signal-channel]. 1712 The DOTS server indicates the result of processing the POST request 1713 using status-line codes. Status codes in the range "2xx" codes are 1714 success, "4xx" codes are some sort of invalid requests and "5xx" 1715 codes are returned if the DOTS server has erred or is incapable of 1716 accepting the creation of the 'dots-client' resource. In particular, 1718 o "201 Created" status-line is returned in the response, if the DOTS 1719 server has accepted the request. 1721 o "400 Bad Request" status-line is returned by the DOTS server, if 1722 the request does not include a 'cuid' parameter. The error-tag 1723 "missing-attribute" is used in this case. 1725 o "409 Conflict" status-line is returned to the requesting DOTS 1726 client, if the data resource already exists. The error-tag 1727 "resource-denied" is used in this case. 1729 Once a DOTS client registers itself to a DOTS server, it can 1730 create/delete/retrieve aliases (Section 6) and filtering rules 1731 (Section 7). 1733 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1734 register a DOTS client within the DOTS server. An example is shown 1735 in Figure 14. 1737 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1738 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1739 Host: {host}:{port} 1740 Content-Type: application/yang-data+json 1741 { 1742 "ietf-dots-data-channel:dots-client": [ 1743 { 1744 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1745 } 1746 ] 1747 } 1749 Figure 14: PUT to Register 1751 The DOTS gateway that inserted a 'cdid' in a PUT request, MUST strip 1752 the 'cdid' parameter in the corresponding response before forwarding 1753 the response to the DOTS client. 1755 5.2. Uregistering DOTS Clients 1757 A DOTS client de-registers from its DOTS server by deleting the 1758 'cuid' resource. Resources bound to this DOTS client will be deleted 1759 by the DOTS server. An example of de-register request is shown in 1760 Figure 15. 1762 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1763 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1764 Host: {host}:{port} 1766 Figure 15: De-register a DOTS Client 1768 6. Managing DOTS Aliases 1770 The following sub-sections define means for a DOTS client to create 1771 aliases (Section 6.1), retrieve one or a list of aliases 1772 (Section 6.2), and delete an alias (Section 6.3). 1774 6.1. Create Aliases 1776 A POST or PUT request is used by a DOTS client to create aliases, for 1777 resources for which a mitigation may be requested. Such aliases may 1778 be used in subsequent DOTS signal channel exchanges to refer more 1779 efficiently to the resources under attack. 1781 DOTS clients within the same domain can create different aliases for 1782 the same resource. 1784 The structure of POST requests used to create aliases is shown in 1785 Figure 16. 1787 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1788 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1789 Host: {host}:{port} 1790 Content-Type: application/yang-data+json 1791 { 1792 "ietf-dots-data-channel:aliases": { 1793 "alias": [ 1794 { 1795 "name": "string", 1796 "target-prefix": [ 1797 "string" 1798 ], 1799 "target-port-range": [ 1800 { 1801 "lower-port": integer, 1802 "upper-port": integer 1803 } 1804 ], 1805 "target-protocol": [ 1806 integer 1807 ], 1808 "target-fqdn": [ 1809 "string" 1810 ], 1811 "target-uri": [ 1812 "string" 1813 ] 1814 } 1815 ] 1816 } 1817 } 1819 Figure 16: POST to Create Aliases 1821 The parameters are described below: 1823 name: Name of the alias. 1825 This is a mandatory attribute. 1827 target-prefix: Prefixes are separated by commas. Prefixes are 1828 represented using Classless Inter-domain Routing (CIDR) notation 1829 [RFC4632]. As a reminder, the prefix length must be less than or 1830 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1832 The prefix list MUST NOT include broadcast, loopback, or multicast 1833 addresses. These addresses are considered as invalid values. In 1834 addition, the DOTS server MUST validate that these prefixes are 1835 within the scope of the DOTS client's domain. Other validation 1836 checks may be supported by DOTS servers. 1838 This is an optional attribute. 1840 target-port-range: A range of port numbers. 1842 The port range is defined by two bounds, a lower port number 1843 (lower-port) and an upper port number (upper-port). 1845 When only 'lower-port' is present, it represents a single port 1846 number. 1848 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1849 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1850 [RFC4340], the range of port numbers can be, for example, 1851 1024-65535. 1853 This is an optional attribute. 1855 target-protocol: A list of protocols. Values are taken from the 1856 IANA protocol registry [proto_numbers]. 1858 The value '0' has a special meaning for 'all protocols'. 1860 This is an optional attribute. 1862 target-fqdn: A list of Fully Qualified Domain Names (FQDNs). An 1863 FQDN is the full name of a resource, rather than just its 1864 hostname. For example, "venera" is a hostname, and 1865 "venera.isi.edu" is an FQDN [RFC1983]. 1867 How a name is passed to an underlying name resolution library is 1868 implementation- and deployment-specific. Nevertheless, once the 1869 name is resolved into one or multiple IP addresses, DOTS servers 1870 MUST apply the same validation checks as those for 'target- 1871 prefix'. 1873 This is an optional attribute. 1875 target-uri: A list of Uniform Resource Identifiers (URIs) 1876 [RFC3986]. 1878 The same validation checks used for 'target-fqdn' MUST be followed 1879 by DOTS servers to validate a target URI. 1881 This is an optional attribute. 1883 In POST or PUT requests, at least one of the 'target-prefix', 1884 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1885 agents can safely ignore Vendor-Specific parameters they don't 1886 understand. 1888 Figure 17 shows a POST request to create an alias called "https1" for 1889 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1890 listening on port number 443. 1892 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1893 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1894 Host: www.example.com 1895 Content-Type: application/yang-data+json 1896 { 1897 "ietf-dots-data-channel:aliases": { 1898 "alias": [ 1899 { 1900 "name": "https1", 1901 "target-protocol": [ 1902 6 1903 ], 1904 "target-prefix": [ 1905 "2001:db8:6401::1/128", 1906 "2001:db8:6401::2/128" 1907 ], 1908 "target-port-range": [ 1909 { 1910 "lower-port": 443 1911 } 1912 ] 1913 } 1914 ] 1915 } 1916 } 1918 Figure 17: Example of a POST to Create an Alias 1920 "201 Created" status-line MUST be returned in the response if the 1921 DOTS server has accepted the alias. 1923 "409 Conflict" status-line MUST be returned to the requesting DOTS 1924 client, if the request is conflicting with an existing alias name. 1925 The error-tag "resource-denied" is used in this case. 1927 If the request is missing a mandatory attribute or its contains an 1928 invalid or unknown parameter, "400 Bad Request" status-line MUST be 1929 returned by the DOTS server. The error-tag is set to "missing- 1930 attribute", "invalid-value", or "unknown-element" as a function of 1931 the encountered error. 1933 If the request is received via a server-domain DOTS gateway, but the 1934 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 1935 is expected to be supplied, the DOTS server MUST reply with "403 1936 Forbidden" status-line and the error-tag "access-denied". Upon 1937 receipt of this message, the DOTS client MUST register (Section 5). 1939 A DOTS client uses the PUT request to modify the aliases in the DOTS 1940 server. In particular, a DOTS client MUST update its alias entries 1941 upon change of the prefix indicated in the 'target-prefix'. 1943 A DOTS server MUST maintain an alias for at least 10080 minutes (1 1944 week). If no refresh request is seen from the DOTS client, the DOTS 1945 server removes expired entries. 1947 6.2. Retrieve Installed Aliases 1949 GET request is used to retrieve one or all installed aliases by a 1950 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 1951 'name' is included in the request, this is an indication that the 1952 request is about retrieving all aliases instantiated by the DOTS 1953 client. 1955 Figure 18 shows an example to retrieve all the aliases that were 1956 instantiated by the requesting DOTS client. The 'content' parameter 1957 and its permitted values are defined in Section 4.8.1 of [RFC8040]. 1959 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1960 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1961 /aliases?content=all HTTP/1.1 1962 Host: {host}:{port} 1963 Accept: application/yang-data+json 1965 Figure 18: GET to Retrieve All Installed Aliases 1967 Figure 19 shows an example of the response message body that includes 1968 all the aliases that are maintained by the DOTS server for the DOTS 1969 client identified by the 'cuid' parameter. 1971 { 1972 "ietf-dots-data-channel:aliases": { 1973 "alias": [ 1974 { 1975 "name": "Server1", 1976 "target-protocol": [ 1977 6 1978 ], 1979 "target-prefix": [ 1980 "2001:db8:6401::1/128", 1981 "2001:db8:6401::2/128" 1982 ], 1983 "target-port-range": [ 1984 { 1985 "lower-port": 443 1986 } 1987 ], 1988 "pending-lifetime": 3596 1989 }, 1990 { 1991 "name": "Server2", 1992 "target-protocol": [ 1993 6 1994 ], 1995 "target-prefix": [ 1996 "2001:db8:6401::10/128", 1997 "2001:db8:6401::20/128" 1998 ], 1999 "target-port-range": [ 2000 { 2001 "lower-port": 80 2002 } 2003 ], 2004 "pending-lifetime": 9869 2005 } 2006 ] 2007 } 2008 } 2010 Figure 19: An Example of Response Body 2012 Figure 20 shows an example of a GET request to retrieve the alias 2013 "Server2" that was instantiated by the DOTS client. 2015 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2016 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2017 /aliases/alias=Server2?content=all HTTP/1.1 2018 Host: {host}:{port} 2019 Accept: application/yang-data+json 2021 Figure 20: GET to Retrieve an Alias 2023 If an alias name ('name') is included in the request, but the DOTS 2024 server does not find that alias name for this DOTS client in its 2025 configuration data, it MUST respond with a "404 Not Found" status- 2026 line. 2028 6.3. Delete Aliases 2030 DELETE request is used to delete an alias maintained by a DOTS 2031 server. 2033 If the DOTS server does not find the alias name, conveyed in the 2034 DELETE request, in its configuration data for this DOTS client, it 2035 MUST respond with a "404 Not Found" status-line. 2037 The DOTS server successfully acknowledges a DOTS client's request to 2038 remove the alias using "204 No Content" status-line in the response. 2040 Figure 21 shows an example of a request to delete an alias. 2042 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2043 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2044 /aliases/alias=Server1 HTTP/1.1 2045 Host: {host}:{port} 2047 Figure 21: Delete an Alias 2049 7. Managing DOTS Filtering Rules 2051 The following sub-sections define means for a DOTS client to retrieve 2052 DOTS filtering capabilities (Section 7.1), create filtering rules 2053 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2054 delete a filtering rule (Section 7.4). 2056 7.1. Retrieve DOTS Filtering Capabilities 2058 A DOTS client MAY send a GET request to retrieve the filtering 2059 capabilities supported by a DOTS server. Figure 22 shows an example 2060 of such request. 2062 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2063 /capabilities HTTP/1.1 2064 Host: {host}:{port} 2065 Accept: application/yang-data+json 2067 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2069 A DOTS client which issued a GET request to retrieve the filtering 2070 capabilities supported by its DOTS server, SHOULD NOT request for 2071 filtering actions that are not supported by that DOTS server. 2073 Figure 23 shows an example of a response received from a DOTS server 2074 which only supports the mandatory filtering criteria listed in 2075 Section 4.1. 2077 Content-Type: application/yang-data+json 2078 { 2079 "ietf-dots-data-channel:capabilities": { 2080 "address-family": ["ipv4", "ipv6"], 2081 "forwarding-actions": ["drop", "accept"], 2082 "rate-limit": true, 2083 "transport-protocols": [1, 6, 17, 58], 2084 "ipv4": { 2085 "length": true, 2086 "protocol": true, 2087 "destination-prefix": true, 2088 "source-prefix": true, 2089 "fragment": true 2090 }, 2091 "ipv6": { 2092 "length": true, 2093 "protocol": true, 2094 "destination-prefix": true, 2095 "source-prefix": true, 2096 "fragment": true 2097 }, 2098 "tcp": { 2099 "flags-bitmask": true, 2100 "source-port": true, 2101 "destination-port": true, 2102 "port-range": true 2103 }, 2104 "udp": { 2105 "length": true, 2106 "source-port": true, 2107 "destination-port": true, 2108 "port-range": true 2109 }, 2110 "icmp": { 2111 "type": true, 2112 "code": true 2113 } 2114 } 2115 } 2117 Figure 23: Reply to a GET Response with Filtering Capabilities 2119 7.2. Install Filtering Rules 2121 A POST or PUT request is used by a DOTS client to communicate 2122 filtering rules to a DOTS server. 2124 Figure 24 shows a POST request example to block traffic from 2125 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2126 discussed in Appendix A. 2128 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2129 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2130 Host: {host}:{port} 2131 Content-Type: application/yang-data+json 2132 { 2133 "ietf-dots-data-channel:acls": { 2134 "acl": [ 2135 { 2136 "name": "sample-ipv4-acl", 2137 "type": "ipv4-acl-type", 2138 "activation-type": "activate-when-mitigating", 2139 "aces": { 2140 "ace": [ 2141 { 2142 "name": "rule1", 2143 "matches": { 2144 "ipv4": { 2145 "destination-ipv4-network": "198.51.100.0/24", 2146 "source-ipv4-network": "192.0.2.0/24" 2147 } 2148 }, 2149 "actions": { 2150 "forwarding": "drop" 2151 } 2152 } 2153 ] 2154 } 2155 } 2156 ] 2157 } 2158 } 2160 Figure 24: POST to Install Filtering Rules 2162 The meaning of these parameters is as follows: 2164 name: The name of the access list. 2166 This is a mandatory attribute. 2168 type: Indicates the primary intended type of match criteria (e.g., 2169 IPv4, IPv6). It is set to 'ipv4-acl-type' in this example. 2171 This is an optional attribute. 2173 activation-type: Indicates whether an ACL has to be installed 2174 immediately or during mitigation time. If this attribute is not 2175 provided, the DOTS server MUST use 'activate-when-mitigating' as 2176 default value. Filters that are activated only when a mitigation 2177 is in progress MUST be bound to the DOTS client which created the 2178 filtering rule. 2180 This is an optional attribute. 2182 matches: Define criteria used to identify a flow on which to apply 2183 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2184 The detailed match parameters are specified in Section 4. 2186 In this example, an IPv4 matching criteria is used. 2188 This is an optional attribute. 2190 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2191 MUST validate that these prefixes are within the scope of the DOTS 2192 client's domain. Other validation checks may be supported by DOTS 2193 servers. If this attribute is not provided, the DOTS server 2194 enforces the ACL on any destination IP address that belong to the 2195 DOTS client's domain. 2197 This is a mandatory attribute in requests with an 'activation- 2198 type' set to 'immediate'. 2200 source-ipv4-network: The source IPv4 prefix. 2202 This is an optional attribute. 2204 actions: Actions in the forwarding ACL category can be "drop" or 2205 "accept". The "accept" action is used to white-list traffic. The 2206 "drop" action is used to black-list traffic. 2208 Accepted traffic may be subject to "rate-limit"; the allowed 2209 traffic rate is represented in bytes per second indicated in IEEE 2210 floating point format [IEEE.754.1985]. 2212 This is a mandatory attribute. 2214 The DOTS server indicates the result of processing the POST request 2215 using the status-line header. Concretely, "201 Created" status-line 2216 MUST be returned in the response if the DOTS server has accepted the 2217 filtering rules. If the request is missing a mandatory attribute or 2218 contains an invalid or unknown parameter (e.g., a match field not 2219 supported by the DOTS server), "400 Bad Request" status-line MUST be 2220 returned by the DOTS server in the response. The error-tag is set to 2221 "missing-attribute", "invalid-value", or "unknown-element" as a 2222 function of the encountered error. 2224 If the request is received via a server-domain DOTS gateway, but the 2225 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2226 is expected to be supplied, the DOTS server MUST reply with "403 2227 Forbidden" status-line and the error-tag "access-denied". Upon 2228 receipt of this message, the DOTS client MUST register (Figure 11). 2230 If the request is conflicting with an existing filtering installed by 2231 another DOTS client of the domain, the DOTS server returns "409 2232 Conflict" status-line to the requesting DOTS client. The error-tag 2233 "resource-denied" is used in this case. 2235 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2236 to specify how an access control entry is inserted within an ACL and 2237 how an ACL is inserted within an ACL set. 2239 The DOTS client uses the PUT request to modify its filtering rules 2240 maintained by the DOTS server. In particular, a DOTS client MUST 2241 update its filtering entries upon change of the destination-prefix. 2242 How such change is detected is out of scope. 2244 A DOTS server MUST maintain a filtering rule for at least 10080 2245 minutes (1 week). If no refresh request is seen from the DOTS 2246 client, the DOTS server removes expired entries. Typically, a 2247 refresh request is a PUT request which echoes the content of a 2248 response to a GET request with all of the read-only parameters 2249 stripped out (e.g. pending-lifetime). 2251 7.3. Retrieve Installed Filtering Rules 2253 The DOTS client periodically queries the DOTS server to check the 2254 counters for installed filtering rules. GET request is used to 2255 retrieve filtering rules from a DOTS server. In order to indicate 2256 which type of data is requested in a GET request, the DOTS client 2257 sets adequately the 'content' parameter. 2259 If the DOTS server does not find the access list name conveyed in the 2260 GET request in its configuration data for this DOTS client, it 2261 responds with a "404 Not Found" status-line. 2263 In order to illustrate the intended behavior, consider the example 2264 depicted in Figure 25. In reference to this example, the DOTS client 2265 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2267 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2268 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2269 /acl=test-acl-ipv6-udp HTTP/1.1 2270 Host: {host}:{port} 2271 Content-Type: application/yang-data+json 2272 { 2273 "ietf-dots-data-channel:acls": { 2274 "acl": [ 2275 { 2276 "name": "test-acl-ipv6-udp", 2277 "type": "ipv6-acl-type", 2278 "activation-type": "immediate", 2279 "aces": { 2280 "ace": [ 2281 { 2282 "name": "test-ace-ipv6-udp", 2283 "matches": { 2284 "ipv6": { 2285 "destination-ipv6-network": "2001:db8:6401::2/127", 2286 "source-ipv6-network": "2001:db8:1234::/96", 2287 "protocol": 17, 2288 "flow-label": 10000 2289 }, 2290 "udp": { 2291 "source-port": { 2292 "operator": "lte", 2293 "port": 80 2294 }, 2295 "destination-port": { 2296 "operator": "neq", 2297 "port": 1010 2298 } 2299 } 2300 }, 2301 "actions": { 2302 "forwarding": "accept" 2303 } 2304 } 2305 ] 2306 } 2307 } 2308 ] 2309 } 2310 } 2312 Figure 25: Example of a PUT Request to Create a Filtering 2314 The peer DOTS server follows the procedure specified in Section 7.2 2315 to process the request. We consider in the following that a positive 2316 response is sent back to the requesting DOTS client to confirm that 2317 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2318 server. 2320 The DOTS client can issue a GET request to retrieve all its filtering 2321 rules and the number of matches for the installed filtering rules as 2322 illustrated in Figure 26. 'content' parameter is set to 'all'. The 2323 message body of the response to this GET request is shown in 2324 Figure 27. 2326 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2327 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2328 /acls?content=all HTTP/1.1 2329 Host: {host}:{port} 2330 Accept: application/yang-data+json 2332 Figure 26: Retrieve the Configuration Data and State Data for the 2333 Filtering Rules: GET Request 2335 { 2336 "ietf-dots-data-channel:acls": { 2337 "acl": [ 2338 { 2339 "name": "test-acl-ipv6-udp", 2340 "type": "ipv6-acl-type", 2341 "activation-type": "immediate", 2342 "pending-lifetime":9080, 2343 "aces": { 2344 "ace": [ 2345 { 2346 "name": "test-ace-ipv6-udp", 2347 "matches": { 2348 "ipv6": { 2349 "destination-ipv6-network": "2001:db8:6401::2/127", 2350 "source-ipv6-network": "2001:db8:1234::/96", 2351 "protocol": 17, 2352 "flow-label": 10000 2353 }, 2354 "udp": { 2355 "source-port": { 2356 "operator": "lte", 2357 "port": 80 2358 }, 2359 "destination-port": { 2360 "operator": "neq", 2361 "port": 1010 2362 } 2363 } 2364 }, 2365 "actions": { 2366 "forwarding": "accept" 2367 } 2368 } 2369 ] 2370 } 2371 } 2372 ] 2373 } 2374 } 2376 Figure 27: Retrieve the Configuration Data and State Data for the 2377 Filtering Rules: Response 2379 Also, a DOTS client can issue a GET request to retrieve only 2380 configuration data related to an ACL as shown in Figure 28. It does 2381 so by setting 'content' parameter to 'config'. 2383 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2384 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2385 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2386 Host: {host}:{port} 2387 Accept: application/yang-data+json 2389 Figure 28: Retrieve the Configuration Data for a Filtering Rule: GET 2390 Request 2392 A response to this GET request is shown in Figure 29. 2394 { 2395 "ietf-dots-data-channel:acls": { 2396 "acl": [ 2397 { 2398 "name": "test-acl-ipv6-udp", 2399 "type": "ipv6-acl-type", 2400 "activation-type": "immediate", 2401 "aces": { 2402 "ace": [ 2403 { 2404 "name": "test-ace-ipv6-udp", 2405 "matches": { 2406 "ipv6": { 2407 "destination-ipv6-network": "2001:db8:6401::2/127", 2408 "source-ipv6-network": "2001:db8:1234::/96", 2409 "protocol": 17, 2410 "flow-label": 10000 2411 }, 2412 "udp": { 2413 "source-port": { 2414 "operator": "lte", 2415 "port": 80 2416 }, 2417 "destination-port": { 2418 "operator": "neq", 2419 "port": 1010 2420 } 2421 } 2422 }, 2423 "actions": { 2424 "forwarding": "accept" 2425 } 2426 } 2427 ] 2428 } 2429 } 2430 ] 2431 } 2432 } 2434 Figure 29: Retrieve the Configuration Data for a Filtering Rule: 2435 Response 2437 A DOTS client can also issue a GET request with 'content' parameter 2438 to 'non-config' to exclusively retrieve non-configuration data bound 2439 to a given ACL as shown in Figure 28. A response to this GET request 2440 is shown in Figure 31. 2442 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2443 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2444 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2445 Host: {host}:{port} 2446 Accept: application/yang-data+json 2448 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule: 2449 GET Request 2451 { 2452 "ietf-dots-data-channel:acls": { 2453 "acl": [ 2454 { 2455 "name": "test-acl-ipv6-udp", 2456 "pending-lifetime": 8000, 2457 "aces": { 2458 "ace": [ 2459 { 2460 "name": "test-ace-ipv6-udp" 2461 } 2462 ] 2463 } 2464 } 2465 ] 2466 } 2467 } 2469 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule: 2470 GET Request 2472 7.4. Remove Filtering Rules 2474 DELETE request is used by a DOTS client to delete filtering rules 2475 from a DOTS server. 2477 If the DOTS server does not find the access list name carried in the 2478 DELETE request in its configuration data for this DOTS client, it 2479 MUST respond with a "404 Not Found" status-line. The DOTS server 2480 successfully acknowledges a DOTS client's request to withdraw the 2481 filtering rules using "204 No Content" status-line, and removes the 2482 filtering rules accordingly. 2484 Figure 32 shows an example of a request to remove the IPv4 ACL 2485 "sample-ipv4-acl" created in Section 7.2. 2487 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2488 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2489 /acl=sample-ipv4-acl HTTP/1.1 2490 Host: {host}:{port} 2492 Figure 32: Remove a Filtering Rule: DELETE Request 2494 Figure 33 shows an example of a response received from the server to 2495 confirm the deletion of "sample-ipv4-acl". 2497 HTTP/1.1 204 No Content 2498 Server: Apache 2499 Date: Fri, 27 Jul 2018 10:05:15 GMT 2500 Cache-Control: no-cache 2501 Content-Type: application/yang-data+json 2502 Content-Length: 0 2503 Connection: Keep-Alive 2505 Figure 33: Remove a Filtering Rule: Response 2507 8. Operational Considerations 2509 The following operational considerations should be taken into 2510 account: 2512 o DOTS server MUST not enable both DOTS data channel and direct 2513 configuration to avoid race conditions and inconsistent 2514 configurations arising from simultaneous updates from multiple 2515 sources. 2517 o DOTS agents SHOULD enable DOTS data channel to configure aliases 2518 and ACL's, and only use direct configuration as a stop-gap 2519 mechanism to test DOTS signal channel with aliases and ACL's. 2520 Further, direct configuration SHOULD only be used when the on-path 2521 DOTS agents are within the same domain. 2523 o If the DOTS server has enabled direct configuration, it can reject 2524 the DOTS data channel connection using hard ICMP error [RFC1122] 2525 or RST (Reset) bit in the TCP header or reject the RESTCONF 2526 request using an error response containing a "503 Service 2527 Unavailable" status-line. 2529 9. IANA Considerations 2531 This document requests IANA to register the following URI in the 2532 "IETF XML Registry" [RFC3688]: 2534 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2535 Registrant Contact: The IESG. 2536 XML: N/A; the requested URI is an XML namespace. 2538 This document requests IANA to register the following YANG module in 2539 the "YANG Module Names" registry [RFC7950]. 2541 name: ietf-dots-data-channel 2542 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2543 prefix: data-channel 2544 reference: RFC XXXX 2546 10. Security Considerations 2548 RESTCONF security considerations are discussed in [RFC8040]. In 2549 particular, DOTS agents MUST follow the security recommendations in 2550 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2551 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2552 [I-D.ietf-dots-signal-channel]. YANG ACL-specific security 2553 considerations are discussed in [I-D.ietf-netmod-acl-model]. 2555 Authenticated encryption MUST be used for data confidentiality and 2556 message integrity. The interaction between the DOTS agents requires 2557 Transport Layer Security (TLS) with a cipher suite offering 2558 confidentiality protection and the guidance given in [RFC7525] MUST 2559 be followed to avoid attacks on TLS. 2561 The installation of black-list and white-list rules using RESTCONF 2562 over TLS reveal the attacker IP addresses and legitimate IP addresses 2563 only to the DOTS server trusted by the DOTS client. The secure 2564 communication channel between DOTS agents provides privacy and 2565 prevents a network eavesdropper from gaining access to the black- 2566 listed and white-listed IP addresses. 2568 An attacker may be able to inject RST packets, bogus application 2569 segments, etc., regardless of whether TLS authentication is used. 2570 Because the application data is TLS protected, this will not result 2571 in the application receiving bogus data, but it will constitute a DoS 2572 on the connection. This attack can be countered by using TCP-AO 2573 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2574 attacker will be rejected by the TCP-AO integrity check and therefore 2575 will never reach the TLS layer. 2577 In order to prevent leaking internal information outside a client- 2578 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2579 internal DOTS clients (e.g., source IP address, client's hostname) 2580 unless explicitly configured to do so. 2582 DOTS servers MUST verify that requesting DOTS clients are entitled to 2583 enforce filtering rules on a given IP prefix. That is, only 2584 filtering rules on IP resources that belong to the DOTS client's 2585 domain MUST be authorized by a DOTS server. The exact mechanism for 2586 the DOTS servers to validate that the target prefixes are within the 2587 scope of the DOTS client's domain is deployment-specific. 2589 Rate-limiting DOTS requests, including those with new 'cuid' values, 2590 from the same DOTS client defends against DoS attacks that would 2591 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 2592 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 2593 DOTS servers. 2595 Applying resources quota per DOTS client and/or per DOTS client 2596 domain (e.g., limit the number of aliases and filters to be install 2597 by DOTS clients) prevents DOTS server resources to be aggressively 2598 used by some DOTS clients and ensures, therefore, DDoS mitigation 2599 usage fairness. Additionally, DOTS servers may limit the number of 2600 DOTS clients that can be enabled per domain. 2602 The presence of DOTS gateways may lead to infinite forwarding loops, 2603 which is undesirable. To prevent and detect such loops, a mechanism 2604 is defined in Section 3.5. 2606 All data nodes defined in the YANG module which can be created, 2607 modified, and deleted (i.e., config true, which is the default) are 2608 considered sensitive. Write operations applied to these data nodes 2609 without proper protection can negatively affect network operations. 2610 Appropriate security measures are recommended to prevent illegitimate 2611 users from invoking DOTS data channel primitives. Nevertheless, an 2612 attacker who can access a DOTS client is technically capable of 2613 launching various attacks, such as: 2615 o Set an arbitrarily low rate-limit, which may prevent legitimate 2616 traffic from being forwarded (rate-limit). 2618 o Set an arbitrarily high rate-limit, which may lead to the 2619 forwarding of illegitimate DDoS traffic (rate-limit). 2621 o Communicate invalid aliases to the server (alias), which will 2622 cause the failure of associating both data and signal channels. 2624 o Set invalid ACL entries, which may prevent legitimate traffic from 2625 being forwarded. Likewise, invalid ACL entries may lead to 2626 forward DDoS traffic. 2628 11. Contributors 2630 The following individuals have contributed to this document: 2632 o Dan Wing, Email: dwing-ietf@fuggles.com 2634 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 2636 12. Acknowledgements 2638 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2639 Doron, Russ White, Gilbert Clark, Kathleen Moriarty and Nesredien 2640 Suleiman for the discussion and comments. 2642 13. References 2644 13.1. Normative References 2646 [I-D.ietf-dots-signal-channel] 2647 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 2648 Teague, "Distributed Denial-of-Service Open Threat 2649 Signaling (DOTS) Signal Channel Specification", draft- 2650 ietf-dots-signal-channel-25 (work in progress), September 2651 2018. 2653 [I-D.ietf-netmod-acl-model] 2654 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 2655 "Network Access Control List (ACL) YANG Data Model", 2656 draft-ietf-netmod-acl-model-19 (work in progress), April 2657 2018. 2659 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2660 Requirement Levels", BCP 14, RFC 2119, 2661 DOI 10.17487/RFC2119, March 1997, 2662 . 2664 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2665 DOI 10.17487/RFC3688, January 2004, 2666 . 2668 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2669 (CIDR): The Internet Address Assignment and Aggregation 2670 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2671 2006, . 2673 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2674 (TLS) Protocol Version 1.2", RFC 5246, 2675 DOI 10.17487/RFC5246, August 2008, 2676 . 2678 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2679 Protocol (HTTP/1.1): Message Syntax and Routing", 2680 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2681 . 2683 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2684 "Recommendations for Secure Use of Transport Layer 2685 Security (TLS) and Datagram Transport Layer Security 2686 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2687 2015, . 2689 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2690 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2691 . 2693 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2694 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2695 . 2697 13.2. Informative References 2699 [I-D.ietf-dots-architecture] 2700 Mortensen, A., Andreasen, F., Reddy, T., 2701 christopher_gray3@cable.comcast.com, c., Compton, R., and 2702 N. Teague, "Distributed-Denial-of-Service Open Threat 2703 Signaling (DOTS) Architecture", draft-ietf-dots- 2704 architecture-07 (work in progress), September 2018. 2706 [I-D.ietf-dots-requirements] 2707 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 2708 Denial of Service (DDoS) Open Threat Signaling 2709 Requirements", draft-ietf-dots-requirements-15 (work in 2710 progress), August 2018. 2712 [IEEE.754.1985] 2713 Institute of Electrical and Electronics Engineers, 2714 "Standard for Binary Floating-Point Arithmetic", August 2715 1985. 2717 [proto_numbers] 2718 "IANA, "Protocol Numbers"", 2011, 2719 . 2721 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2722 Communication Layers", STD 3, RFC 1122, 2723 DOI 10.17487/RFC1122, October 1989, 2724 . 2726 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 2727 RFC 1983, DOI 10.17487/RFC1983, August 1996, 2728 . 2730 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2731 Resource Identifier (URI): Generic Syntax", STD 66, 2732 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2733 . 2735 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2736 Congestion Control Protocol (DCCP)", RFC 4340, 2737 DOI 10.17487/RFC4340, March 2006, 2738 . 2740 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2741 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2742 . 2744 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2745 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2746 DOI 10.17487/RFC5389, October 2008, 2747 . 2749 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2750 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2751 June 2010, . 2753 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2754 Layer Security (TLS) and Datagram Transport Layer Security 2755 (DTLS) Heartbeat Extension", RFC 6520, 2756 DOI 10.17487/RFC6520, February 2012, 2757 . 2759 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 2760 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 2761 DOI 10.17487/RFC6887, April 2013, 2762 . 2764 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2765 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2766 . 2768 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2769 Interchange Format", STD 90, RFC 8259, 2770 DOI 10.17487/RFC8259, December 2017, 2771 . 2773 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2774 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2775 . 2777 Appendix A. Sample Examples: Filtering Fragments 2779 This specification strongly recommends the use of "fragment" for 2780 handling fragments. 2782 Figure 34 shows the content of the POST request to be issued by a 2783 DOTS client to its DOTS server to allow the traffic destined to 2784 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2785 packets. The following ACEs are defined (in this order): 2787 o "drop-all-fragments" ACE: discards all fragments. 2789 o "allow-dns-packets" ACE: accepts DNS packets destined to 2790 198.51.100.0/24. 2792 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2793 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2794 Host: {host}:{port} 2795 Content-Type: application/yang-data+json 2796 { 2797 "ietf-dots-data-channel:acls": { 2798 "acl": [ 2799 { 2800 "name": "dns-fragments", 2801 "type": "ipv4-acl-type", 2802 "aces": { 2803 "ace": [ 2804 { 2805 "name": "drop-all-fragments", 2806 "matches": { 2807 "ipv4": { 2808 "fragment": { 2809 "operator": "match", 2810 "type": "isf" 2811 } 2812 } 2813 }, 2814 "actions": { 2815 "forwarding": "drop" 2817 } 2818 } 2819 ] 2820 "ace": [ 2821 { 2822 "name": "allow-dns-packets", 2823 "matches": { 2824 "ipv4": { 2825 "destination-ipv4-network": "198.51.100.0/24" 2826 } 2827 "udp": { 2828 "destination-port": { 2829 "operator": "eq", 2830 "port": 53 2831 } 2832 }, 2833 "actions": { 2834 "forwarding": "accept" 2835 } 2836 } 2837 ] 2838 } 2839 } 2840 ] 2841 } 2842 } 2844 Figure 34: Filtering IPv4 Fragmented Packets (Recommended) 2846 Figure 35 shows a POST request example issued by a DOTS client to its 2847 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 2848 port number 53, but to drop all fragmented packets. The following 2849 ACEs are defined (in this order): 2851 o "drop-all-fragments" ACE: discards all fragments (including atomic 2852 fragments). That is, IPv6 packets which include a Fragment header 2853 (44) are dropped. 2855 o "allow-dns-packets" ACE: accepts DNS packets destined to 2856 2001:db8::/32. 2858 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2859 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2860 Host: {host}:{port} 2861 Content-Type: application/yang-data+json 2862 { 2863 "ietf-dots-data-channel:acls": { 2864 "acl": [ 2865 { 2866 "name": "dns-fragments", 2867 "type": "ipv6-acl-type", 2868 "aces": { 2869 "ace": [ 2870 { 2871 "name": "drop-all-fragments", 2872 "matches": { 2873 "ipv6": { 2874 "fragment": { 2875 "operator": "match", 2876 "type": "isf" 2877 } 2878 } 2879 }, 2880 "actions": { 2881 "forwarding": "drop" 2882 } 2883 } 2884 ] 2885 "ace": [ 2886 { 2887 "name": "allow-dns-packets", 2888 "matches": { 2889 "ipv6": { 2890 "destination-ipv6-network": "2001:db8::/32" 2891 } 2892 "udp": { 2893 "destination-port": { 2894 "operator": "eq", 2895 "port": 53 2896 } 2897 } 2898 }, 2899 "actions": { 2900 "forwarding": "accept" 2901 } 2902 } 2903 ] 2904 } 2905 } 2906 ] 2907 } 2908 } 2910 Figure 35: Filtering IPv6 Fragmented Packets 2912 Authors' Addresses 2914 Mohamed Boucadair (editor) 2915 Orange 2916 Rennes 35000 2917 France 2919 Email: mohamed.boucadair@orange.com 2921 Tirumaleswar Reddy (editor) 2922 McAfee, Inc. 2923 Embassy Golf Link Business Park 2924 Bangalore, Karnataka 560071 2925 India 2927 Email: kondtir@gmail.com 2929 Kaname Nishizuka 2930 NTT Communications 2931 GranPark 16F 3-4-1 Shibaura, Minato-ku 2932 Tokyo 108-8118 2933 Japan 2935 Email: kaname@nttv6.jp 2937 Liang Xia 2938 Huawei 2939 101 Software Avenue, Yuhuatai District 2940 Nanjing, Jiangsu 210012 2941 China 2943 Email: frank.xialiang@huawei.com 2945 Prashanth Patil 2946 Cisco Systems, Inc. 2948 Email: praspati@cisco.com 2949 Andrew Mortensen 2950 Arbor Networks, Inc. 2951 2727 S. State St 2952 Ann Arbor, MI 48104 2953 United States 2955 Email: amortensen@arbor.net 2957 Nik Teague 2958 Verisign, Inc. 2959 United States 2961 Email: nteague@verisign.com