idnits 2.17.1 draft-ietf-dots-data-channel-23.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 : ---------------------------------------------------------------------------- ** 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 459 has weird spacing: '...er-port ine...' == Line 460 has weird spacing: '...er-port ine...' == Line 542 has weird spacing: '...warding ide...' == Line 837 has weird spacing: '... icmp typ...' -- The document date (November 20, 2018) is 1977 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 2097 -- Looks like a reference, but probably isn't: '6' on line 2097 -- Looks like a reference, but probably isn't: '17' on line 2097 -- Looks like a reference, but probably isn't: '58' on line 2097 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-25 ** 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-16 -- 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: 3 errors (**), 0 flaws (~~), 8 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: May 24, 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 November 20, 2018 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 Specification 20 draft-ietf-dots-data-channel-23 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 May 24, 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. Generic 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. Unregistering DOTS Clients . . . . . . . . . . . . . . . 39 106 6. Managing DOTS Aliases . . . . . . . . . . . . . . . . . . . . 40 107 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 40 108 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 44 109 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 46 110 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 46 111 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 46 112 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 48 113 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 51 114 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 58 115 8. Operational Considerations . . . . . . . . . . . . . . . . . 59 116 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 59 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 60 118 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 62 119 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 62 120 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 121 13.1. Normative References . . . . . . . . . . . . . . . . . . 62 122 13.2. Informative References . . . . . . . . . . . . . . . . . 63 123 Appendix A. Sample Examples: Filtering Fragments . . . . . . . . 65 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67 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 Policy 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 accept-listed traffic. 183 A DOTS client is entitled to instruct filtering rules only on IP 184 resources that belong to its domain. 186 Sample use cases for populating drop- or accept-list filtering 187 rules are detailed hereafter: 189 * If a network resource (DOTS client) detects a potential DDoS 190 attack from a set of IP addresses, the DOTS client informs its 191 servicing DOTS gateway of all suspect IP addresses that need to 192 be drop- or accept-listed for further investigation. The DOTS 193 client could also specify a list of protocols and port numbers 194 in the drop-list rule. 196 The DOTS gateway then propagates the drop-listed IP addresses 197 to a DOTS server which will undertake appropriate actions so 198 that traffic originated by these IP addresses to the target 199 network (specified by the DOTS client) is blocked. 201 * A network, that has partner sites from which only legitimate 202 traffic arrives, may want to ensure that the traffic from these 203 sites is not subjected to DDoS attack mitigation. The DOTS 204 client uses the DOTS data channel to convey the accept-listed 205 IP prefixes of the partner sites to its DOTS server. 207 The DOTS server uses this information to accept-list flows 208 originated by such IP prefixes and which reach the network. 210 Refer to Section 7 for more details. 212 2. Terminology 214 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 215 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 216 document are to be interpreted as described in [RFC2119]. 218 The reader should be familiar with the terms defined in 219 [I-D.ietf-dots-requirements]. 221 The terminology for describing YANG modules is defined in [RFC7950]. 222 The meaning of the symbols in tree diagrams is defined in [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 over TCP as the DOTS data channel protocol. The 259 abstract layering of DOTS data channel is shown in Figure 2. 261 +-------------------+ 262 | DOTS Data Channel | 263 +-------------------+ 264 | RESTCONF | 265 +-------------------+ 266 | TLS | 267 +-------------------+ 268 | TCP | 269 +-------------------+ 270 | IP | 271 +-------------------+ 273 Figure 2: Abstract Layering of DOTS Data Channel 275 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 276 resources represented by DOTS data channel YANG modules. These basic 277 edit operations allow the DOTS data channel running configuration to 278 be altered by a DOTS client. 280 DOTS data channel configuration information as well as state 281 information can be retrieved with the GET method. An HTTP status- 282 line header field is returned for each request to report success or 283 failure for RESTCONF operations (Section 5.4 of [RFC8040]). The 284 "error-tag" provides more information about encountered errors 285 (Section 7 of [RFC8040]). 287 DOTS clients perform the root resource discovery procedure discussed 288 in Section 3.1 of [RFC8040] to determine the root of the RESTCONF 289 API. After discovering the RESTCONF API root, a DOTS client uses 290 this value as the initial part of the path in the request URI, in any 291 subsequent request to the DOTS server. The DOTS server may support 292 the retrieval of the YANG modules it supports (Section 3.7 in 293 [RFC8040]). For example, a DOTS client may use RESTCONF to retrieve 294 the vendor-specific YANG modules supported by its DOTS server. 296 JavaScript Object Notation (JSON) [RFC8259] payload is used to 297 propagate the DOTS data channel specific payload messages that carry 298 request parameters and response information, such as errors. This 299 specification uses the encoding rules defined in [RFC7951] for 300 representing DOTS data channel configuration data using YANG 301 (Section 4) as JSON text. 303 A DOTS client registers itself to its DOTS server(s) in order to set 304 up DOTS data channel-related configuration data and receive state 305 data (i.e., non-configuration data) from the DOTS server(s) 306 (Section 5). Mutual authentication and coupling of signal and data 307 channels are specified in [I-D.ietf-dots-signal-channel]. 309 A single DOTS data channel between DOTS agents can be used to 310 exchange multiple requests and multiple responses. To reduce DOTS 311 client and DOTS server workload, DOTS clients SHOULD re-use the same 312 TLS session. While the communication to the DOTS server is 313 quiescent, the DOTS client MAY probe the server to ensure it has 314 maintained cryptographic state. Such probes can also keep alive 315 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 316 that the DOTS server still has TLS state by returning a TLS message. 318 A DOTS server may detect conflicting filtering requests from distinct 319 DOTS clients which belong to the same domain. For example, a DOTS 320 client could request to drop-list a prefix by specifying the source 321 prefix, while another DOTS client could request to accept-list that 322 same source prefix, but both having the same destination prefix. It 323 is out of scope of this specification to recommend the behavior to 324 follow for handling conflicting requests (e.g., reject all, reject 325 the new request, notify an administrator for validation). DOTS 326 servers SHOULD support a configuration parameter to indicate the 327 behavior to follow when a conflict is detected. Section 7.2 328 specifies the behavior when no instruction is supplied to a DOTS 329 server. 331 How filtering rules instantiated on a DOTS server are translated into 332 network configurations actions is out of scope. 334 3.2. DOTS Server(s) Discovery 336 This document assumes that DOTS clients are provisioned with the 337 reachability information of their DOTS server(s) using a variety of 338 means (e.g., local configuration, or dynamic means such as DHCP). 339 The specification of such means are out of scope of this document. 341 Likewise, it is out of scope of this document to specify the behavior 342 to be followed by a DOTS client to send DOTS requests when multiple 343 DOTS servers are provisioned (e.g., contact all DOTS servers, select 344 one DOTS server among the list). 346 3.3. NAT Considerations 348 In deployments where one or more translators (e.g., NAT44, NAT64, 349 NPTv6) are enabled between the client's network and the DOTS server, 350 DOTS data channel messages forwarded to a DOTS server MUST NOT 351 include internal IP addresses/prefixes and/or port numbers; external 352 addresses/prefixes and/or port numbers as assigned by the translator 353 MUST be used instead. This document does not make any recommendation 354 about possible translator discovery mechanisms. The following are 355 some (non-exhaustive) deployment examples that may be considered: 357 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 358 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 359 external addresses/prefixes and/or port numbers. Information 360 retrieved by means of PCP or STUN will be used to feed the DOTS 361 data channel messages that will be sent to a DOTS server. 363 o A DOTS gateway may be co-located with the translator. The DOTS 364 gateway will need to update the DOTS messages, based upon the 365 local translator's binding table. 367 3.4. DOTS Gateways 369 When a server-domain DOTS gateway is involved in DOTS data channel 370 exchanges, the same considerations for manipulating the 'cdid' 371 (client domain identifier) parameter specified in 372 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 373 reminder, 'cdid' is meant to assist the DOTS server to enforce some 374 policies (e.g., limit the number of filtering rules per DOTS client 375 or per DOTS client domain). A loop detect mechanism for DOTS 376 gateways is specified in Section 3.5. 378 If a DOTS gateway is involved, the DOTS gateway verifies that the 379 DOTS client is authorized to undertake a data channel action (e.g., 380 instantiate filtering rules). If the DOTS client is authorized, it 381 propagates the rules to the upstream DOTS server. Likewise, the DOTS 382 server verifies that the DOTS gateway is authorized to relay data 383 channel actions. For example, to create or purge filters, a DOTS 384 client sends its request to its DOTS gateway. The DOTS gateway 385 validates the rules in the request and proxies the requests 386 containing the filtering rules to its DOTS server. When the DOTS 387 gateway receives the associated response from the DOTS server, it 388 propagates the response back to the DOTS client. 390 3.5. Detect and Prevent Infinite Loops 392 In order to detect and prevent infinite loops, DOTS gateways MUST 393 support the procedure defined in Section 5.7.1 of [RFC7230]. In 394 particular, each intermediate DOTS gateway MUST check that none of 395 its own information (e.g., server names, literal IP addresses) is 396 present in the "Via" header of a DOTS message it receives: 398 o If it detects that its own information is present in the "Via" 399 header, the DOTS gateway MUST NOT forward the DOTS message. 400 Messages that cannot be forwarded because of a loop SHOULD be 401 logged with a "508 Loop Detected" status-line returned sent back 402 to the DOTS peer. The structure of the reported error is depicted 403 in Figure 3. 405 error-tag: loop-detected 406 error-type: transport, application 407 error-severity: error 408 error-info: : A copy of the Via header when 409 the loop was detected. 410 Description: An infinite loop has been detected when forwarding 411 a requests via a proxy. 413 Figure 3: Loop Detected Error 415 It is RECOMMENDED that DOTS clients and gateways support means to 416 alert administrators about loop errors so that appropriate actions 417 are undertaken. 419 o Otherwise, the DOTS agent MUST update or insert the "Via" header 420 by appending its own information. 422 Unless configured otherwise, DOTS gateways at the boundaries of a 423 DOTS client domain SHOULD remove the previous "Via" header 424 information after checking for a loop before forwarding. This 425 behavior is required for topology hiding purposes but also to 426 minimize potential conflicts that may arise if overlapping 427 information is used in distinct DOTS domains (e.g., private IPv4 428 addresses, non globally unique aliases). 430 3.6. Stale Entries 432 In order to avoid stale entries, a lifetime is associated with alias 433 and filtering entries created by DOTS clients. Also, DOTS servers 434 may track the inactivity timeout of DOTS clients to detect stale 435 entries. 437 4. DOTS Data Channel YANG Module 439 4.1. Generic Tree Structure 441 The DOTS data channel YANG module (ietf-dots-data-channel) provides a 442 method for DOTS clients to manage aliases for resources for which 443 mitigation may be requested. Such aliases may be used in subsequent 444 DOTS signal channel exchanges to refer more efficiently to the 445 resources under attack. 447 The tree structure for the DOTS alias is depicted in Figure 4. 449 module: ietf-dots-data-channel 450 +--rw dots-data 451 +--rw dots-client* [cuid] 452 | +--rw cuid string 453 | +--rw cdid? string 454 | +--rw aliases 455 | | +--rw alias* [name] 456 | | +--rw name string 457 | | +--rw target-prefix* inet:ip-prefix 458 | | +--rw target-port-range* [lower-port upper-port] 459 | | | +--rw lower-port inet:port-number 460 | | | +--rw upper-port inet:port-number 461 | | +--rw target-protocol* uint8 462 | | +--rw target-fqdn* inet:domain-name 463 | | +--rw target-uri* inet:uri 464 | | +--ro pending-lifetime? int32 465 | +--rw acls 466 | ... 467 +--ro capabilities 468 ... 470 Figure 4: DOTS Alias Subtree 472 Also, the 'ietf-dots-data-channel' module provides a method for DOTS 473 clients to manage filtering rules. Examples of filtering management 474 in a DOTS context include, but not limited to: 476 o Drop-list management, which enables a DOTS client to inform a DOTS 477 server about sources from which traffic should be discarded. 479 o Accept-list management, which enables a DOTS client to inform a 480 DOTS server about sources from which traffic should always be 481 accepted. 483 o Policy management, which enables a DOTS client to request the 484 installation or withdrawal of traffic filters, dropping or rate- 485 limiting unwanted traffic and permitting accept-listed traffic. 487 The tree structure for the DOTS filtering entries is depicted in 488 Figure 5. 490 Early versions of this document investigated to what extent 491 augmenting 'ietf-access-control-list' meet DOTS requirements, but 492 that design approach was abandoned because it does not support 493 meeting many of DOTS requirements, e.g., 495 o Retrieve a filtering entry (or all entries) created by a DOTS 496 client. 498 o Delete a filtering entry that was instantiated by a DOTS client. 500 DOTS filtering entries (i.e., Access Control List (ACL)) mimic the 501 structure specified in [I-D.ietf-netmod-acl-model]. Concretely, DOTS 502 agents are assumed to manipulate an ordered list of ACLs; each ACL 503 contains a separately ordered list of Access Control Entries (ACEs). 504 Each ACE has a group of match and a group of action criteria. 506 Once all the ACE entries have been iterated though with no match, 507 then all the following ACL's ACE entries are iterated through until 508 the first match at which point the specified action is applied. If 509 there is no match, then there is no action to be taken against the 510 packet. 512 module: ietf-dots-data-channel 513 +--rw dots-data 514 +--rw dots-client* [cuid] 515 | +--rw cuid string 516 | +--rw cdid? string 517 | +--rw aliases 518 | | ... 519 | +--rw acls 520 | +--rw acl* [name] 521 | +--rw name string 522 | +--rw type? ietf-acl:acl-type 523 | +--rw activation-type? enumeration 524 | +--ro pending-lifetime? int32 525 | +--rw aces 526 | +--rw ace* [name] 527 | +--rw name string 528 | +--rw matches 529 | | +--rw (l3)? 530 | | | +--:(ipv4) 531 | | | | ... 532 | | | +--:(ipv6) 533 | | | ... 534 | | +--rw (l4)? 535 | | +--:(tcp) 536 | | | ... 537 | | +--:(udp) 538 | | | ... 539 | | +--:(icmp) 540 | | ... 541 | +--rw actions 542 | | +--rw forwarding identityref 543 | | +--rw rate-limit? decimal64 544 | +--ro statistics 545 | +--ro matched-packets? yang:counter64 546 | +--ro matched-octets? yang:counter64 547 +--ro capabilities 548 ... 550 Figure 5: DOTS ACLs Subtree 552 Filtering rules instructed by a DOTS client assumes a default 553 direction: the destination is the DOTS client domain. 555 DOTS forwarding actions can be 'accept' (i.e., accept matching 556 traffic) or 'drop' (i.e., drop matching traffic without sending any 557 ICMP error message). Accepted traffic can be subject to rate 558 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 559 matching traffic and send an ICMP error message to the source) is not 560 supported in 'ietf-dots-data-channel' because it is not appropriate 561 in the context of DDoS mitigation. Generating ICMP messages to 562 notify drops when mitigating a DDoS attack will exacerbate the DDoS 563 attack. Furthermore, these ICMP messages will be used by an attacker 564 as an explicit signal that the traffic is being blocked. 566 4.2. Filtering Fields 568 The 'ietf-dots-data-channel' module reuses the packet fields module 569 'ietf-packet-fields' [I-D.ietf-netmod-acl-model] which defines 570 matching on fields in the packet including IPv4, IPv6, and transport 571 layer fields. 573 This specification defines a new IPv4/IPv6 matching field called 574 'fragment' to efficiently handle fragment-related filtering rules. 575 Indeed, [I-D.ietf-netmod-acl-model] does not support such capability 576 for IPv6 but offers a partial support for IPv4 by means of 'flags'. 577 Nevertheless, the use of 'flags' is problematic since it does not 578 allow to define a bitmask. For example, setting other bits not 579 covered by the 'flags' filtering clause in a packet will allow that 580 packet to get through (because it won't match the ACE). Sample 581 examples to illustrate how 'fragment' can be used are provided in 582 Appendix A. 584 Figure 6 shows the IPv4 match subtree. 586 module: ietf-dots-data-channel 587 +--rw dots-data 588 +--rw dots-client* [cuid] 589 | ... 590 | +--rw acls 591 | +--rw acl* [name] 592 | ... 593 | +--rw aces 594 | +--rw ace* [name] 595 | +--rw name string 596 | +--rw matches 597 | | +--rw (l3)? 598 | | | +--:(ipv4) 599 | | | | +--rw ipv4 600 | | | | +--rw dscp? inet:dscp 601 | | | | +--rw ecn? uint8 602 | | | | +--rw length? uint16 603 | | | | +--rw ttl? uint8 604 | | | | +--rw protocol? uint8 605 | | | | +--rw ihl? uint8 606 | | | | +--rw flags? bits 607 | | | | +--rw offset? uint16 608 | | | | +--rw identification? uint16 609 | | | | +--rw (destination-network)? 610 | | | | | +--:(destination-ipv4-network) 611 | | | | | +--rw destination-ipv4-network? 612 | | | | | inet:ipv4-prefix 613 | | | | +--rw (source-network)? 614 | | | | | +--:(source-ipv4-network) 615 | | | | | +--rw source-ipv4-network? 616 | | | | | inet:ipv4-prefix 617 | | | | +--rw fragment 618 | | | | +--rw operator? operator 619 | | | | +--rw type fragment-type 620 | | | +--:(ipv6) 621 | | | ... 622 | | +--rw (l4)? 623 | | ... 624 | +--rw actions 625 | | ... 626 | +--ro statistics 627 | ... 628 +--ro capabilities 629 ... 631 Figure 6: DOTS ACLs Subtree (IPv4 Match) 633 Figure 7 shows the IPv6 match subtree. 635 module: ietf-dots-data-channel 636 +--rw dots-data 637 +--rw dots-client* [cuid] 638 | ... 639 | +--rw acls 640 | +--rw acl* [name] 641 | ... 642 | +--rw aces 643 | +--rw ace* [name] 644 | +--rw name string 645 | +--rw matches 646 | | +--rw (l3)? 647 | | | +--:(ipv4) 648 | | | | ... 649 | | | +--:(ipv6) 650 | | | +--rw ipv6 651 | | | +--rw dscp? inet:dscp 652 | | | +--rw ecn? uint8 653 | | | +--rw length? uint16 654 | | | +--rw ttl? uint8 655 | | | +--rw protocol? uint8 656 | | | +--rw (destination-network)? 657 | | | | +--:(destination-ipv6-network) 658 | | | | +--rw destination-ipv6-network? 659 | | | | inet:ipv6-prefix 660 | | | +--rw (source-network)? 661 | | | | +--:(source-ipv6-network) 662 | | | | +--rw source-ipv6-network? 663 | | | | inet:ipv6-prefix 664 | | | +--rw flow-label? 665 | | | | inet:ipv6-flow-label 666 | | | +--rw fragment 667 | | | +--rw operator? operator 668 | | | +--rw type fragment-type 669 | | +--rw (l4)? 670 | | ... 671 | +--rw actions 672 | | ... 673 | +--ro statistics 674 | ... 675 +--ro capabilities 676 ... 678 Figure 7: DOTS ACLs Subtree (IPv6 Match) 680 Figure 8 shows the TCP match subtree. In addition to the fields 681 defined in [I-D.ietf-netmod-acl-model], this specification defines a 682 new TCP matching field, called 'flags-bitmask', to efficiently handle 683 TCP flags filtering rules. 685 module: ietf-dots-data-channel 686 +--rw dots-data 687 +-rw dots-client* [cuid] 688 | ... 689 | +-rw acls 690 | +-rw acl* [name] 691 | ... 692 | +-rw aces 693 | +-rw ace* [name] 694 | +-rw name string 695 | +-rw matches 696 | | +-rw (l3)? 697 | | | ... 698 | | +-rw (l4)? 699 | | +-:(tcp) 700 | | | +-rw tcp 701 | | | +--rw sequence-number? uint32 702 | | | +--rw acknowledgement-number? uint32 703 | | | +--rw data-offset? uint8 704 | | | +--rw reserved? uint8 705 | | | +--rw flags? bits 706 | | | +--rw window-size? uint16 707 | | | +--rw urgent-pointer? uint16 708 | | | +--rw options? binary 709 | | | +--rw flags-bitmask 710 | | | | +--rw operator? operator 711 | | | | +--rw bitmask uint16 712 | | | +--rw (source-port)? 713 | | | | +--:(source-port-range-or-operator) 714 | | | | +--rw source-port-range-or-operator 715 | | | | +--rw (port-range-or-operator)? 716 | | | | +--:(range) 717 | | | | | +--rw lower-port 718 | | | | | | inet:port-number 719 | | | | | +--rw upper-port 720 | | | | | inet:port-number 721 | | | | +--:(operator) 722 | | | | +--rw operator? 723 | | | | | operator 724 | | | | +--rw port 725 | | | | inet:port-number 726 | | | +--rw (destination-port)? 727 | | | +--:(destination-port-range-or-operator) 728 | | | +--rw destination-port-range-or-operator 729 | | | +--rw (port-range-or-operator)? 730 | | | +--:(range) 731 | | | | +--rw lower-port 732 | | | | | inet:port-number 733 | | | | +--rw upper-port 734 | | | | inet:port-number 735 | | | +--:(operator) 736 | | | +--rw operator? 737 | | | | operator 738 | | | +--rw port 739 | | | inet:port-number 740 | | +-:(udp) 741 | | | ... 742 | | +-:(icmp) 743 | | ... 744 | +-rw actions 745 | | ... 746 | +-ro statistics 747 | ... 748 +-ro capabilities 749 ... 751 Figure 8: DOTS ACLs Subtree (TCP Match) 753 Figure 9 shows the UDP and ICMP match subtrees. 755 module: ietf-dots-data-channel 756 +-rw dots-data 757 +-rw dots-client* [cuid] 758 | ... 759 | +-rw acls 760 | +-rw acl* [name] 761 | ... 762 | +-rw aces 763 | +-rw ace* [name] 764 | +--rw name string 765 | +--rw matches 766 | | +--rw (l3)? 767 | | | ... 768 | | +--rw (l4)? 769 | | +--:(tcp) 770 | | | ... 771 | | +--:(udp) 772 | | | +--rw udp 773 | | | +--rw length? uint16 774 | | | +--rw (source-port)? 775 | | | | +--:(source-port-range-or-operator) 776 | | | | +--rw source-port-range-or-operator 777 | | | | +--rw (port-range-or-operator)? 778 | | | | +--:(range) 779 | | | | | +--rw lower-port 780 | | | | | | inet:port-number 781 | | | | | +--rw upper-port 782 | | | | | inet:port-number 783 | | | | +--:(operator) 784 | | | | +--rw operator? 785 | | | | | operator 786 | | | | +--rw port 787 | | | | inet:port-number 788 | | | +--rw (destination-port)? 789 | | | +--:(destination-port-range-or-operator) 790 | | | +--rw destination-port-range-or-operator 791 | | | +--rw (port-range-or-operator)? 792 | | | +--:(range) 793 | | | | +--rw lower-port 794 | | | | | inet:port-number 795 | | | | +--rw upper-port 796 | | | | inet:port-number 797 | | | +--:(operator) 798 | | | +--rw operator? 799 | | | | operator 800 | | | +--rw port 801 | | | inet:port-number 802 | | +--:(icmp) 803 | | +--rw icmp 804 | | +--rw type? uint8 805 | | +--rw code? uint8 806 | | +--rw rest-of-header? binary 807 | +--rw actions 808 | | ... 809 | +--ro statistics 810 | ... 811 +-ro capabilities 812 ... 814 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 816 DOTS implementations MUST support the following matching criteria: 818 match based on the IP header (IPv4 and IPv6), match based on the 819 transport header (TCP, UDP, and ICMP), and any combination 820 thereof. The same matching fields are used for both ICMP and 821 ICMPv6. 823 The following match fields MUST be supported by DOTS implementations 824 (Table 1): 826 ACL Mandatory Fields 827 Match 828 ------- ------------------------------------------------------------- 829 ipv4 length, protocol, destination-ipv4-network, source- 830 ipv4-network, and fragment 831 ipv6 length, protocol, destination-ipv6-network, source- 832 ipv6-network, and fragment 833 tcp flags-bitmask, source-port-range-or-operator, and 834 destination-port-range-or-operator 835 udp length, source-port-range-or-operator, and destination-port- 836 range-or-operator 837 icmp type and code 839 Table 1: Mandatory DOTS Channel Match Fields 841 Implementations MAY support other filtering match fields and actions. 842 The 'ietf-dots-data-channel' provides a method for an implementation 843 to expose its filtering capabilities. The tree structure of the 844 'capabilities' is shown in Figure 10. 846 module: ietf-dots-data-channel 847 +--rw dots-data 848 ... 849 +--ro capabilities 850 +--ro address-family* enumeration 851 +--ro forwarding-actions* identityref 852 +--ro rate-limit? boolean 853 +--ro transport-protocols* uint8 854 +--ro ipv4 855 | +--ro dscp? boolean 856 | +--ro ecn? boolean 857 | +--ro length? boolean 858 | +--ro ttl? boolean 859 | +--ro protocol? boolean 860 | +--ro ihl? boolean 861 | +--ro flags? boolean 862 | +--ro offset? boolean 863 | +--ro identification? boolean 864 | +--ro source-prefix? boolean 865 | +--ro destination-prefix? boolean 866 | +--ro fragment? boolean 867 +--ro ipv6 868 | +--ro dscp? boolean 869 | +--ro ecn? boolean 870 | +--ro flow-label? boolean 871 | +--ro length? boolean 872 | +--ro protocol? boolean 873 | +--ro hoplimit? boolean 874 | +--ro source-prefix? boolean 875 | +--ro destination-prefix? boolean 876 | +--ro fragment? boolean 877 +--ro tcp 878 | +--ro sequence-number? boolean 879 | +--ro acknowledgement-number? boolean 880 | +--ro data-offset? boolean 881 | +--ro reserved? boolean 882 | +--ro flags? boolean 883 | +--ro flags-bitmask? boolean 884 | +--ro window-size? boolean 885 | +--ro urgent-pointer? boolean 886 | +--ro options? boolean 887 | +--ro source-port? boolean 888 | +--ro destination-port? boolean 889 | +--ro port-range? boolean 890 +--ro udp 891 | +--ro length? boolean 892 | +--ro source-port? boolean 893 | +--ro destination-port? boolean 894 | +--ro port-range? boolean 895 +--ro icmp 896 +--ro type? boolean 897 +--ro code? boolean 898 +--ro rest-of-header? boolean 900 Figure 10: Filtering Capabilities Subtree 902 4.3. YANG Module 904 file "ietf-dots-data-channel@2018-11-20.yang" 906 module ietf-dots-data-channel { 907 yang-version 1.1; 908 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 909 prefix data-channel; 911 import ietf-access-control-list { 912 prefix ietf-acl; 913 reference 914 "RFC ZZZZ: Network Access Control List (ACL) 915 YANG Data Model"; 916 } 917 import ietf-packet-fields { 918 prefix packet-fields; 919 reference 920 "RFC ZZZZ: Network Access Control List (ACL) 921 YANG Data Model"; 923 } 924 import ietf-dots-signal-channel { 925 prefix dots-signal; 926 reference 927 "RFC YYYY: Distributed Denial-of-Service Open Threat 928 Signaling (DOTS) Signal Channel Specification"; 929 } 931 organization 932 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 933 contact 934 "WG Web: 935 WG List: 937 Editor: Mohamed Boucadair 938 940 Editor: Konda, Tirumaleswar Reddy 941 943 Author: Jon Shallow 944 946 Author: Kaname Nishizuka 947 949 Author: Liang Xia 950 952 Author: Prashanth Patil 953 955 Author: Andrew Mortensen 956 958 Author: Nik Teague 959 "; 960 description 961 "This module contains YANG definition for configuring 962 aliases for resources and filtering rules using DOTS 963 data channel. 965 Copyright (c) 2018 IETF Trust and the persons identified as 966 authors of the code. All rights reserved. 968 Redistribution and use in source and binary forms, with or 969 without modification, is permitted pursuant to, and subject 970 to the license terms contained in, the Simplified BSD License 971 set forth in Section 4.c of the IETF Trust's Legal Provisions 972 Relating to IETF Documents 973 (http://trustee.ietf.org/license-info). 975 This version of this YANG module is part of RFC XXXX; see 976 the RFC itself for full legal notices."; 978 revision 2018-11-20 { 979 description 980 "Initial revision."; 981 reference 982 "RFC XXXX: Distributed Denial-of-Service Open Threat 983 Signaling (DOTS) Data Channel Specification"; 984 } 986 typedef operator { 987 type bits { 988 bit not { 989 position 0; 990 description 991 "If set, logical negation of operation."; 992 } 993 bit match { 994 position 1; 995 description 996 "Match bit. If set, this is a bitwise match operation 997 defined as '(data & value) == value'; if unset, (data & 998 value) evaluates to TRUE if any of the bits in the value 999 mask are set in the data."; 1000 } 1001 } 1002 description 1003 "How to apply the defined bitmask."; 1004 } 1006 grouping tcp-flags { 1007 leaf operator { 1008 type operator; 1009 default match; 1010 description 1011 "How to interpret the TCP flags."; 1012 } 1013 leaf bitmask { 1014 type uint16; 1015 mandatory true; 1016 description 1017 "Bitmask values can be encoded as a 1- or 2-byte bitmask. 1018 When a single byte is specified, it matches byte 13 1019 of the TCP header, which contains bits 8 though 15 1020 of the 4th 32-bit word. When a 2-byte encoding is used, 1021 it matches bytes 12 and 13 of the TCP header with 1022 the data offset field having a 'don't care' value."; 1023 } 1024 description 1025 "Operations on TCP flags."; 1026 } 1028 typedef fragment-type { 1029 type bits { 1030 bit df { 1031 position 0; 1032 description 1033 "Don't fragment bit for IPv4. 1034 This bit must be set to 0 for IPv6."; 1035 } 1036 bit isf { 1037 position 1; 1038 description 1039 "Is a fragment."; 1040 } 1041 bit ff { 1042 position 2; 1043 description 1044 "First fragment."; 1045 } 1046 bit lf { 1047 position 3; 1048 description 1049 "Last fragment."; 1050 } 1051 } 1052 description 1053 "Different fragment types to match against."; 1054 } 1056 grouping fragment-fields { 1057 leaf operator { 1058 type operator; 1059 default match; 1060 description 1061 "How to interpret the fragment type."; 1062 } 1063 leaf type { 1064 type fragment-type; 1065 mandatory true; 1066 description 1067 "What fragment type to look for."; 1068 } 1069 description 1070 "Operations on fragment types."; 1071 } 1073 grouping aliases { 1074 description 1075 "Top level container for aliases"; 1076 list alias { 1077 key "name"; 1078 description 1079 "List of aliases"; 1080 leaf name { 1081 type string; 1082 description 1083 "The name of the alias"; 1084 } 1085 uses dots-signal:target; 1086 leaf pending-lifetime { 1087 type int32; 1088 units "minutes"; 1089 config false; 1090 description 1091 "Indicates the pending validity lifetime of the alias 1092 entry."; 1093 } 1094 } 1095 } 1097 grouping ports { 1098 choice source-port { 1099 container source-port-range-or-operator { 1100 uses packet-fields:port-range-or-operator; 1101 description 1102 "Source port definition."; 1103 } 1104 description 1105 "Choice of specifying the source port or referring to 1106 a group of source ports."; 1107 } 1108 choice destination-port { 1109 container destination-port-range-or-operator { 1110 uses packet-fields:port-range-or-operator; 1111 description 1112 "Destination port definition."; 1113 } 1114 description 1115 "Choice of specifying a destination port or referring 1116 to a group of destination ports."; 1117 } 1118 description 1119 "Choice of specifying a source or destination ports."; 1120 } 1122 grouping access-lists { 1123 description 1124 "Specifies the ordered set of Access Control Lists."; 1125 list acl { 1126 key "name"; 1127 ordered-by user; 1128 description 1129 "An Access Control List (ACL) is an ordered list of 1130 Access Control Entries (ACE). Each Access Control Entry 1131 has a list of match criteria and a list of actions."; 1132 leaf name { 1133 type string { 1134 length "1..64"; 1135 } 1136 description 1137 "The name of the access list."; 1138 reference 1139 "RFC ZZZZ: Network Access Control List (ACL) 1140 YANG Data Model"; 1141 } 1142 leaf type { 1143 type ietf-acl:acl-type; 1144 description 1145 "Type of access control list. Indicates the primary intended 1146 type of match criteria (e.g., IPv4, IPv6) used in the list 1147 instance."; 1148 reference 1149 "RFC ZZZZ: Network Access Control List (ACL) 1150 YANG Data Model"; 1151 } 1152 leaf activation-type { 1153 type enumeration { 1154 enum "activate-when-mitigating" { 1155 value 1; 1156 description 1157 "The ACL is installed only when a mitigation is active. 1158 The ACL is specific to this DOTS client."; 1159 } 1160 enum "immediate" { 1161 value 2; 1162 description 1163 "The ACL is immediately activated."; 1164 } 1165 enum "deactivate" { 1166 value 3; 1167 description 1168 "The ACL is maintained by the server, but it is 1169 deactivated."; 1170 } 1171 } 1172 description 1173 "Indicates whether an ACL is to be installed immediately 1174 or when a mitigation is active."; 1175 } 1176 leaf pending-lifetime { 1177 type int32; 1178 units "minutes"; 1179 config false; 1180 description 1181 "Indicates the pending validity lifetime of the alias 1182 entry."; 1183 } 1184 container aces { 1185 description 1186 "The Access Control Entries container contains 1187 a list of ACEs."; 1188 list ace { 1189 key "name"; 1190 ordered-by user; 1191 description 1192 "List of access list entries."; 1193 leaf name { 1194 type string { 1195 length "1..64"; 1196 } 1197 description 1198 "A unique name identifying this Access List 1199 Entry (ACE)."; 1200 reference 1201 "RFC ZZZZ: Network Access Control List (ACL) 1202 YANG Data Model"; 1203 } 1204 container matches { 1205 description 1206 "The rules in this set determine what fields will be 1207 matched upon before any action is taken on them. 1209 If no matches are defined in a particular container, 1210 then any packet will match that container. 1212 If no matches are specified at all in an ACE, then any 1213 packet will match the ACE."; 1214 reference 1215 "RFC ZZZZ: Network Access Control List (ACL) 1216 YANG Data Model"; 1218 choice l3 { 1219 container ipv4 { 1220 when "derived-from(../../../../type," + 1221 "'ietf-acl:ipv4-acl-type')"; 1222 uses packet-fields:acl-ip-header-fields; 1223 uses packet-fields:acl-ipv4-header-fields; 1224 container fragment { 1225 description 1226 "Indicates how to handle IPv4 fragments."; 1227 uses fragment-fields; 1228 } 1229 description 1230 "Rule set that matches IPv4 header."; 1231 } 1232 container ipv6 { 1233 when "derived-from(../../../../type," + 1234 "'ietf-acl:ipv6-acl-type')"; 1235 uses packet-fields:acl-ip-header-fields; 1236 uses packet-fields:acl-ipv6-header-fields; 1237 container fragment { 1238 description 1239 "Indicates how to handle IPv6 fragments."; 1240 uses fragment-fields; 1241 } 1242 description 1243 "Rule set that matches IPv6 header."; 1244 } 1245 description 1246 "Either IPv4 or IPv6."; 1247 } 1248 choice l4 { 1249 container tcp { 1250 uses packet-fields:acl-tcp-header-fields; 1251 container flags-bitmask { 1252 description 1253 "Indicates how to handle TCP flags."; 1254 uses tcp-flags; 1255 } 1256 uses ports; 1257 description 1258 "Rule set that matches TCP header."; 1259 } 1260 container udp { 1261 uses packet-fields:acl-udp-header-fields; 1262 uses ports; 1263 description 1264 "Rule set that matches UDP header."; 1265 } 1266 container icmp { 1267 uses packet-fields:acl-icmp-header-fields; 1268 description 1269 "Rule set that matches ICMP/ICMPv6 header."; 1270 } 1271 description 1272 "Can be TCP, UDP, or ICMP/ICMPv6"; 1273 } 1274 } 1275 container actions { 1276 description 1277 "Definitions of action for this ACE."; 1278 leaf forwarding { 1279 type identityref { 1280 base ietf-acl:forwarding-action; 1281 } 1282 mandatory true; 1283 description 1284 "Specifies the forwarding action per ACE."; 1285 reference 1286 "RFC ZZZZ: Network Access Control List (ACL) 1287 YANG Data Model"; 1288 } 1289 leaf rate-limit { 1290 when "../forwarding = 'ietf-acl:accept'" { 1291 description 1292 "rate-limit valid only when accept action is used"; 1293 } 1294 type decimal64 { 1295 fraction-digits 2; 1296 } 1297 description 1298 "rate-limit traffic"; 1299 } 1300 } 1301 container statistics { 1302 config false; 1303 description 1304 "Aggregate statistics."; 1305 uses ietf-acl:acl-counters; 1306 } 1307 } 1309 } 1310 } 1311 } 1313 container dots-data { 1314 description 1315 "Main container for DOTS data channel."; 1316 list dots-client { 1317 key "cuid"; 1318 description 1319 "List of DOTS clients."; 1320 leaf cuid { 1321 type string; 1322 description 1323 "A unique identifier that is randomly generated by 1324 a DOTS client to prevent request collisions."; 1325 reference 1326 "RFC YYYY: Distributed Denial-of-Service Open Threat 1327 Signaling (DOTS) Signal Channel Specification"; 1328 } 1329 leaf cdid { 1330 type string; 1331 description 1332 "A client domain identifier conveyed by a 1333 server-domain DOTS gateway to a remote DOTS server."; 1334 reference 1335 "RFC YYYY: Distributed Denial-of-Service Open Threat 1336 Signaling (DOTS) Signal Channel Specification"; 1337 } 1338 container aliases { 1339 description 1340 "Set of aliases that are bound to a DOTS client."; 1341 uses aliases; 1342 } 1343 container acls { 1344 description 1345 "Access lists that are bound to a DOTS client."; 1346 uses access-lists; 1347 } 1348 } 1349 container capabilities { 1350 config false; 1351 description 1352 "Match capabilities"; 1353 leaf-list address-family { 1354 type enumeration { 1355 enum "ipv4" { 1356 description 1357 "IPv4 is supported."; 1358 } 1359 enum "ipv6" { 1360 description 1361 "IPv6 is supported."; 1362 } 1363 } 1364 description 1365 "Indicates the IP address families supported by 1366 the DOTS server."; 1367 } 1368 leaf-list forwarding-actions { 1369 type identityref { 1370 base ietf-acl:forwarding-action; 1371 } 1372 description 1373 "Supported forwarding action(s)."; 1374 } 1375 leaf rate-limit { 1376 type boolean; 1377 description 1378 "Support of rate-limit action."; 1379 } 1380 leaf-list transport-protocols { 1381 type uint8; 1382 description 1383 "Upper-layer protocol associated with a filtering rule. 1385 Values are taken from the IANA protocol registry: 1386 https://www.iana.org/assignments/protocol-numbers/ 1387 protocol-numbers.xhtml 1389 For example, this field contains 1 for ICMP, 6 for TCP 1390 17 for UDP, or 58 for ICMPv6."; 1391 } 1392 container ipv4 { 1393 description 1394 "Indicates IPv4 header fields that are supported to enforce 1395 ACLs."; 1396 leaf dscp { 1397 type boolean; 1398 description 1399 "Support of filtering based on DSCP."; 1400 } 1401 leaf ecn { 1402 type boolean; 1403 description 1404 "Support of filtering based on ECN."; 1406 } 1407 leaf length { 1408 type boolean; 1409 description 1410 "Support of filtering based on the Total Length."; 1411 } 1412 leaf ttl { 1413 type boolean; 1414 description 1415 "Support of filtering based on the TTL."; 1416 } 1417 leaf protocol { 1418 type boolean; 1419 description 1420 "Support of filtering based on protocol field."; 1421 } 1422 leaf ihl { 1423 type boolean; 1424 description 1425 "Support of filtering based on the Internet Header 1426 Length (IHL)."; 1427 } 1428 leaf flags { 1429 type boolean; 1430 description 1431 "Support of filtering based on the 'flags'"; 1432 } 1433 leaf offset { 1434 type boolean; 1435 description 1436 "Support of filtering based on the 'offset'."; 1437 } 1438 leaf identification { 1439 type boolean; 1440 description 1441 "Support of filtering based on the 'identification'."; 1442 } 1443 leaf source-prefix { 1444 type boolean; 1445 description 1446 "Support of filtering based on the source prefix."; 1447 } 1448 leaf destination-prefix { 1449 type boolean; 1450 description 1451 "Support of filtering based on the destination prefix."; 1452 } 1453 leaf fragment { 1454 type boolean; 1455 description 1456 "Indicates the capability of a DOTS server to 1457 enforce filters on IPv4 fragments. That is 'fragment' 1458 clause is supported."; 1459 } 1460 } 1461 container ipv6 { 1462 description 1463 "Indicates IPv6 header fields that are supported to enforce 1464 ACLs."; 1465 leaf dscp { 1466 type boolean; 1467 description 1468 "Support of filtering based on DSCP."; 1469 } 1470 leaf ecn { 1471 type boolean; 1472 description 1473 "Support of filtering based on ECN."; 1474 } 1475 leaf flow-label { 1476 type boolean; 1477 description 1478 "Support of filtering based on the Flow label."; 1479 } 1480 leaf length { 1481 type boolean; 1482 description 1483 "Support of filtering based on the Payload Length."; 1484 } 1485 leaf protocol { 1486 type boolean; 1487 description 1488 "Support of filtering based on the Next Header field."; 1489 } 1490 leaf hoplimit { 1491 type boolean; 1492 description 1493 "Support of filtering based on the Hop Limit."; 1494 } 1495 leaf source-prefix { 1496 type boolean; 1497 description 1498 "Support of filtering based on the source prefix."; 1499 } 1500 leaf destination-prefix { 1501 type boolean; 1502 description 1503 "Support of filtering based on the destination prefix."; 1504 } 1505 leaf fragment { 1506 type boolean; 1507 description 1508 "Indicates the capability of a DOTS server to 1509 enforce filters on IPv6 fragments."; 1510 } 1511 } 1512 container tcp { 1513 description 1514 "Set of TCP fields that are supported by the DOTS server 1515 to enfoce filters."; 1516 leaf sequence-number { 1517 type boolean; 1518 description 1519 "Support of filtering based on the TCP sequence number."; 1520 } 1521 leaf acknowledgement-number { 1522 type boolean; 1523 description 1524 "Support of filtering based on the TCP acknowledgement 1525 number."; 1526 } 1527 leaf data-offset { 1528 type boolean; 1529 description 1530 "Support of filtering based on the TCP data-offset."; 1531 } 1532 leaf reserved { 1533 type boolean; 1534 description 1535 "Support of filtering based on the TCP reserved field."; 1536 } 1537 leaf flags { 1538 type boolean; 1539 description 1540 "Support of filtering, as defined in RFC ZZZZ, based 1541 on the TCP flags."; 1542 } 1543 leaf flags-bitmask { 1544 type boolean; 1545 description 1546 "Support of filtering based on the TCP flags bitmask."; 1547 } 1548 leaf window-size { 1549 type boolean; 1550 description 1551 "Support of filtering based on the TCP window size."; 1552 } 1553 leaf urgent-pointer { 1554 type boolean; 1555 description 1556 "Support of filtering based on the TCP urgent pointer."; 1557 } 1558 leaf options { 1559 type boolean; 1560 description 1561 "Support of filtering based on the TCP options."; 1562 } 1563 leaf source-port { 1564 type boolean; 1565 description 1566 "Support of filtering based on the source port number."; 1567 } 1568 leaf destination-port { 1569 type boolean; 1570 description 1571 "Support of filtering based on the destination port 1572 number."; 1573 } 1574 leaf port-range { 1575 type boolean; 1576 description 1577 "Support of filtering based on a port range."; 1578 } 1579 } 1580 container udp { 1581 description 1582 "Set of UDP fields that are supported by the DOTS server 1583 to enforce filters."; 1584 leaf length { 1585 type boolean; 1586 description 1587 "Support of filtering based on the UDP length."; 1588 } 1589 leaf source-port { 1590 type boolean; 1591 description 1592 "Support of filtering based on the source port number."; 1593 } 1594 leaf destination-port { 1595 type boolean; 1596 description 1597 "Support of filtering based on the destination port 1598 number."; 1599 } 1600 leaf port-range { 1601 type boolean; 1602 description 1603 "Support of filtering based on a port range."; 1604 } 1605 } 1606 container icmp { 1607 description 1608 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1609 server to enforce filters."; 1610 leaf type { 1611 type boolean; 1612 description 1613 "Support of filtering based on the ICMP/ICMPv6 type."; 1614 } 1615 leaf code { 1616 type boolean; 1617 description 1618 "Support of filtering based on the ICMP/ICMPv6 code."; 1619 } 1620 leaf rest-of-header { 1621 type boolean; 1622 description 1623 "Support of filtering based on the ICMP four-bytes 1624 field."; 1625 } 1626 } 1627 } 1628 } 1629 } 1630 1632 5. Managing DOTS Clients 1634 5.1. Registering DOTS Clients 1636 In order to make use of DOTS data channel, a DOTS client MUST 1637 register to its DOTS server(s) by creating a DOTS client ('dots- 1638 client') resource. To that aim, DOTS clients SHOULD send a POST 1639 request (shown in Figure 11). 1641 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1642 Host: {host}:{port} 1643 Content-Type: application/yang-data+json 1644 { 1645 "ietf-dots-data-channel:dots-client": [ 1646 { 1647 "cuid": "string" 1648 } 1649 ] 1650 } 1652 Figure 11: POST to Register 1654 The 'cuid' (client unique identifier) parameter is described below: 1656 cuid: A globally unique identifier that is meant to prevent 1657 collisions among DOTS clients. This attribute has the same 1658 meaning, syntax, and processing rules as the 'cuid' attribute 1659 defined in [I-D.ietf-dots-signal-channel]. 1661 DOTS clients MUST use the same 'cuid' for both signal and data 1662 channels. 1664 This is a mandatory attribute. 1666 In deployments where server-domain DOTS gateways are enabled, 1667 identity information about the origin source client domain SHOULD be 1668 supplied to the DOTS server. That information is meant to assist the 1669 DOTS server to enforce some policies. These policies can be enforced 1670 per-client, per-client domain, or both. Figure 12 shows an example 1671 of a request relayed by a server-domain DOTS gateway. 1673 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1674 Host: {host}:{port} 1675 Content-Type: application/yang-data+json 1676 { 1677 "ietf-dots-data-channel:dots-client": [ 1678 { 1679 "cuid": "string", 1680 "cdid": "string" 1681 } 1682 ] 1683 } 1685 Figure 12: POST to Register (via a Server-Domain DOTS Gateway) 1687 A server-domain DOTS gateway SHOULD add the following attribute: 1689 cdid: This attribute has the same meaning, syntax, and processing 1690 rules as the 'cdid' attribute defined in 1691 [I-D.ietf-dots-signal-channel]. 1693 In deployments where server-domain DOTS gateways are enabled, 1694 'cdid' does not need to be inserted when relaying DOTS methods to 1695 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1696 servers are responsible for maintaining the association between 1697 'cdid' and 'cuid' for policy enforcement purposes. 1699 This is an optional attribute. 1701 A request example to create a 'dots-client' resource is depicted in 1702 Figure 13. This request is relayed by a server-domain DOTS gateway 1703 as hinted by the presence of the 'cdid' attribute. 1705 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1706 Host: {host}:{port} 1707 Content-Type: application/yang-data+json 1708 { 1709 "ietf-dots-data-channel:dots-client": [ 1710 { 1711 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1712 "cdid": "7eeaf349529eb55ed50113" 1713 } 1714 ] 1715 } 1717 Figure 13: POST to Register (DOTS gateway) 1719 DOTS servers MUST limit the number of 'dots-client' resources to be 1720 created by the same DOTS client to 1 per request. Requests with 1721 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1722 To that aim, the DOTS server MUST rely on the same procedure to 1723 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1724 [I-D.ietf-dots-signal-channel]. 1726 The DOTS server indicates the result of processing the POST request 1727 using status-line codes. Status codes in the range "2xx" codes are 1728 success, "4xx" codes are some sort of invalid requests and "5xx" 1729 codes are returned if the DOTS server has erred or is incapable of 1730 accepting the creation of the 'dots-client' resource. In particular, 1732 o "201 Created" status-line is returned in the response, if the DOTS 1733 server has accepted the request. 1735 o "400 Bad Request" status-line is returned by the DOTS server, if 1736 the request does not include a 'cuid' parameter. The error-tag 1737 "missing-attribute" is used in this case. 1739 o "409 Conflict" status-line is returned to the requesting DOTS 1740 client, if the data resource already exists. The error-tag 1741 "resource-denied" is used in this case. 1743 Once a DOTS client registers itself to a DOTS server, it can 1744 create/delete/retrieve aliases (Section 6) and filtering rules 1745 (Section 7). 1747 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1748 register a DOTS client within the DOTS server. An example is shown 1749 in Figure 14. 1751 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1752 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1753 Host: {host}:{port} 1754 Content-Type: application/yang-data+json 1755 { 1756 "ietf-dots-data-channel:dots-client": [ 1757 { 1758 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1759 } 1760 ] 1761 } 1763 Figure 14: PUT to Register 1765 The DOTS gateway, that inserted a 'cdid' in a PUT request, MUST strip 1766 the 'cdid' parameter in the corresponding response before forwarding 1767 the response to the DOTS client. 1769 5.2. Unregistering DOTS Clients 1771 A DOTS client de-registers from its DOTS server(s) by deleting the 1772 'cuid' resource(s). Resources bound to this DOTS client will be 1773 deleted by the DOTS server. An example of a de-register request is 1774 shown in Figure 15. 1776 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1777 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1778 Host: {host}:{port} 1780 Figure 15: De-register a DOTS Client 1782 6. Managing DOTS Aliases 1784 The following sub-sections define means for a DOTS client to create 1785 aliases (Section 6.1), retrieve one or a list of aliases 1786 (Section 6.2), and delete an alias (Section 6.3). 1788 6.1. Create Aliases 1790 A POST or PUT request is used by a DOTS client to create aliases, for 1791 resources for which a mitigation may be requested. Such aliases may 1792 be used in subsequent DOTS signal channel exchanges to refer more 1793 efficiently to the resources under attack. 1795 DOTS clients within the same domain can create different aliases for 1796 the same resource. 1798 The structure of POST requests used to create aliases is shown in 1799 Figure 16. 1801 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1802 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1803 Host: {host}:{port} 1804 Content-Type: application/yang-data+json 1805 { 1806 "ietf-dots-data-channel:aliases": { 1807 "alias": [ 1808 { 1809 "name": "string", 1810 "target-prefix": [ 1811 "string" 1812 ], 1813 "target-port-range": [ 1814 { 1815 "lower-port": integer, 1816 "upper-port": integer 1817 } 1818 ], 1819 "target-protocol": [ 1820 integer 1821 ], 1822 "target-fqdn": [ 1823 "string" 1824 ], 1825 "target-uri": [ 1826 "string" 1827 ] 1828 } 1829 ] 1830 } 1831 } 1833 Figure 16: POST to Create Aliases 1835 The parameters are described below: 1837 name: Name of the alias. 1839 This is a mandatory attribute. 1841 target-prefix: Prefixes are separated by commas. Prefixes are 1842 represented using Classless Inter-domain Routing (CIDR) notation 1843 [RFC4632]. As a reminder, the prefix length must be less than or 1844 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1846 The prefix list MUST NOT include broadcast, loopback, or multicast 1847 addresses. These addresses are considered as invalid values. In 1848 addition, the DOTS server MUST validate that these prefixes are 1849 within the scope of the DOTS client's domain. Other validation 1850 checks may be supported by DOTS servers. 1852 This is an optional attribute. 1854 target-port-range: A range of port numbers. 1856 The port range is defined by two bounds, a lower port number 1857 (lower-port) and an upper port number (upper-port). 1859 When only 'lower-port' is present, it represents a single port 1860 number. 1862 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1863 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1864 [RFC4340], the range of port numbers can be, for example, 1865 1024-65535. 1867 This is an optional attribute. 1869 target-protocol: A list of protocols. Values are taken from the 1870 IANA protocol registry [proto_numbers]. 1872 The value '0' has a special meaning for 'all protocols'. 1874 This is an optional attribute. 1876 target-fqdn: A list of Fully Qualified Domain Names (FQDNs). An 1877 FQDN is the full name of a resource, rather than just its 1878 hostname. For example, "venera" is a hostname, and 1879 "venera.isi.edu" is an FQDN [RFC1983]. 1881 How a name is passed to an underlying name resolution library is 1882 implementation- and deployment-specific. Nevertheless, once the 1883 name is resolved into one or multiple IP addresses, DOTS servers 1884 MUST apply the same validation checks as those for 'target- 1885 prefix'. 1887 This is an optional attribute. 1889 target-uri: A list of Uniform Resource Identifiers (URIs) 1890 [RFC3986]. 1892 The same validation checks used for 'target-fqdn' MUST be followed 1893 by DOTS servers to validate a target URI. 1895 This is an optional attribute. 1897 In POST or PUT requests, at least one of the 'target-prefix', 1898 'target-fqdn', or 'target-uri' attributes MUST be present. DOTS 1899 agents can safely ignore Vendor-Specific parameters they don't 1900 understand. 1902 Figure 17 shows a POST request to create an alias called "https1" for 1903 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1904 listening on port number 443. 1906 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1907 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1908 Host: www.example.com 1909 Content-Type: application/yang-data+json 1910 { 1911 "ietf-dots-data-channel:aliases": { 1912 "alias": [ 1913 { 1914 "name": "https1", 1915 "target-protocol": [ 1916 6 1917 ], 1918 "target-prefix": [ 1919 "2001:db8:6401::1/128", 1920 "2001:db8:6401::2/128" 1921 ], 1922 "target-port-range": [ 1923 { 1924 "lower-port": 443 1925 } 1926 ] 1927 } 1928 ] 1929 } 1930 } 1932 Figure 17: Example of a POST to Create an Alias 1934 "201 Created" status-line MUST be returned in the response if the 1935 DOTS server has accepted the alias. 1937 "409 Conflict" status-line MUST be returned to the requesting DOTS 1938 client, if the request is conflicting with an existing alias name. 1939 The error-tag "resource-denied" is used in this case. 1941 If the request is missing a mandatory attribute or its contains an 1942 invalid or unknown parameter, "400 Bad Request" status-line MUST be 1943 returned by the DOTS server. The error-tag is set to "missing- 1944 attribute", "invalid-value", or "unknown-element" as a function of 1945 the encountered error. 1947 If the request is received via a server-domain DOTS gateway, but the 1948 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 1949 is expected to be supplied, the DOTS server MUST reply with "403 1950 Forbidden" status-line and the error-tag "access-denied". Upon 1951 receipt of this message, the DOTS client MUST register (Section 5). 1953 A DOTS client uses the PUT request to modify the aliases in the DOTS 1954 server. In particular, a DOTS client MUST update its alias entries 1955 upon change of the prefix indicated in the 'target-prefix'. 1957 A DOTS server MUST maintain an alias for at least 10080 minutes (1 1958 week). If no refresh request is seen from the DOTS client, the DOTS 1959 server removes expired entries. 1961 6.2. Retrieve Installed Aliases 1963 GET request is used to retrieve one or all installed aliases by a 1964 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 1965 'name' is included in the request, this is an indication that the 1966 request is about retrieving all aliases instantiated by the DOTS 1967 client. 1969 Figure 18 shows an example to retrieve all the aliases that were 1970 instantiated by the requesting DOTS client. The 'content' parameter 1971 and its permitted values are defined in Section 4.8.1 of [RFC8040]. 1973 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1974 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1975 /aliases?content=all HTTP/1.1 1976 Host: {host}:{port} 1977 Accept: application/yang-data+json 1979 Figure 18: GET to Retrieve All Installed Aliases 1981 Figure 19 shows an example of the response message body that includes 1982 all the aliases that are maintained by the DOTS server for the DOTS 1983 client identified by the 'cuid' parameter. 1985 { 1986 "ietf-dots-data-channel:aliases": { 1987 "alias": [ 1988 { 1989 "name": "Server1", 1990 "target-protocol": [ 1991 6 1992 ], 1993 "target-prefix": [ 1994 "2001:db8:6401::1/128", 1995 "2001:db8:6401::2/128" 1996 ], 1997 "target-port-range": [ 1998 { 1999 "lower-port": 443 2000 } 2001 ], 2002 "pending-lifetime": 3596 2003 }, 2004 { 2005 "name": "Server2", 2006 "target-protocol": [ 2007 6 2008 ], 2009 "target-prefix": [ 2010 "2001:db8:6401::10/128", 2011 "2001:db8:6401::20/128" 2012 ], 2013 "target-port-range": [ 2014 { 2015 "lower-port": 80 2016 } 2017 ], 2018 "pending-lifetime": 9869 2019 } 2020 ] 2021 } 2022 } 2024 Figure 19: An Example of Response Body Listing All Installed Aliases 2026 Figure 20 shows an example of a GET request to retrieve the alias 2027 "Server2" that was instantiated by the DOTS client. 2029 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2030 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2031 /aliases/alias=Server2?content=all HTTP/1.1 2032 Host: {host}:{port} 2033 Accept: application/yang-data+json 2035 Figure 20: GET to Retrieve an Alias 2037 If an alias name ('name') is included in the request, but the DOTS 2038 server does not find that alias name for this DOTS client in its 2039 configuration data, it MUST respond with a "404 Not Found" status- 2040 line. 2042 6.3. Delete Aliases 2044 DELETE request is used to delete an alias maintained by a DOTS 2045 server. 2047 If the DOTS server does not find the alias name, conveyed in the 2048 DELETE request, in its configuration data for this DOTS client, it 2049 MUST respond with a "404 Not Found" status-line. 2051 The DOTS server successfully acknowledges a DOTS client's request to 2052 remove the alias using "204 No Content" status-line in the response. 2054 Figure 21 shows an example of a request to delete an alias. 2056 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2057 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2058 /aliases/alias=Server1 HTTP/1.1 2059 Host: {host}:{port} 2061 Figure 21: Delete an Alias 2063 7. Managing DOTS Filtering Rules 2065 The following sub-sections define means for a DOTS client to retrieve 2066 DOTS filtering capabilities (Section 7.1), create filtering rules 2067 (Section 7.2), retrieve active filtering rules (Section 7.3), and 2068 delete a filtering rule (Section 7.4). 2070 7.1. Retrieve DOTS Filtering Capabilities 2072 A DOTS client MAY send a GET request to retrieve the filtering 2073 capabilities supported by a DOTS server. Figure 22 shows an example 2074 of such request. 2076 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2077 /capabilities HTTP/1.1 2078 Host: {host}:{port} 2079 Accept: application/yang-data+json 2081 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 2083 A DOTS client which issued a GET request to retrieve the filtering 2084 capabilities supported by its DOTS server, SHOULD NOT request for 2085 filtering actions that are not supported by that DOTS server. 2087 Figure 23 shows an example of a response received from a DOTS server 2088 which only supports the mandatory filtering criteria listed in 2089 Section 4.1. 2091 Content-Type: application/yang-data+json 2092 { 2093 "ietf-dots-data-channel:capabilities": { 2094 "address-family": ["ipv4", "ipv6"], 2095 "forwarding-actions": ["drop", "accept"], 2096 "rate-limit": true, 2097 "transport-protocols": [1, 6, 17, 58], 2098 "ipv4": { 2099 "length": true, 2100 "protocol": true, 2101 "destination-prefix": true, 2102 "source-prefix": true, 2103 "fragment": true 2104 }, 2105 "ipv6": { 2106 "length": true, 2107 "protocol": true, 2108 "destination-prefix": true, 2109 "source-prefix": true, 2110 "fragment": true 2111 }, 2112 "tcp": { 2113 "flags-bitmask": true, 2114 "source-port": true, 2115 "destination-port": true, 2116 "port-range": true 2117 }, 2118 "udp": { 2119 "length": true, 2120 "source-port": true, 2121 "destination-port": true, 2122 "port-range": true 2123 }, 2124 "icmp": { 2125 "type": true, 2126 "code": true 2127 } 2128 } 2129 } 2131 Figure 23: Reply to a GET Request with Filtering Capabilities 2133 7.2. Install Filtering Rules 2135 A POST or PUT request is used by a DOTS client to communicate 2136 filtering rules to a DOTS server. 2138 Figure 24 shows a POST request example to block traffic from 2139 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2140 discussed in Appendix A. 2142 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2143 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2144 Host: {host}:{port} 2145 Content-Type: application/yang-data+json 2146 { 2147 "ietf-dots-data-channel:acls": { 2148 "acl": [ 2149 { 2150 "name": "sample-ipv4-acl", 2151 "type": "ipv4-acl-type", 2152 "activation-type": "activate-when-mitigating", 2153 "aces": { 2154 "ace": [ 2155 { 2156 "name": "rule1", 2157 "matches": { 2158 "ipv4": { 2159 "destination-ipv4-network": "198.51.100.0/24", 2160 "source-ipv4-network": "192.0.2.0/24" 2161 } 2162 }, 2163 "actions": { 2164 "forwarding": "drop" 2165 } 2166 } 2167 ] 2168 } 2169 } 2170 ] 2171 } 2172 } 2174 Figure 24: POST to Install Filtering Rules 2176 The meaning of these parameters is as follows: 2178 name: The name of the access list. 2180 This is a mandatory attribute. 2182 type: Indicates the primary intended type of match criteria (e.g., 2183 IPv4, IPv6). It is set to 'ipv4-acl-type' in the example of 2184 Figure 24. 2186 This is an optional attribute. 2188 activation-type: Indicates whether an ACL has to be activated 2189 (immediately or during mitigation time) or instantiated without 2190 being activated (deactivated). Deactivated ACLs can be activated 2191 using a variety of means such as manual configuration on a DOTS 2192 server or using the DOTS data channel. 2194 If this attribute is not provided, the DOTS server MUST use 2195 'activate-when-mitigating' as default value. 2197 Filters that are activated only when a mitigation is in progress 2198 MUST be bound to the DOTS client which created the filtering rule. 2200 This is an optional attribute. 2202 matches: Define criteria used to identify a flow on which to apply 2203 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2204 The detailed match parameters are specified in Section 4. 2206 In the example depicted in Figure 24, an IPv4 matching criteria is 2207 used. 2209 This is an optional attribute. 2211 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2212 MUST validate that these prefixes are within the scope of the DOTS 2213 client's domain. Other validation checks may be supported by DOTS 2214 servers. If this attribute is not provided, the DOTS server 2215 enforces the ACL on any destination IP address that belong to the 2216 DOTS client's domain. 2218 This is a mandatory attribute in requests with an 'activation- 2219 type' set to 'immediate'. 2221 source-ipv4-network: The source IPv4 prefix. 2223 This is an optional attribute. 2225 actions: Actions in the forwarding ACL category can be "drop" or 2226 "accept". The "accept" action is used to accept-list traffic. 2227 The "drop" action is used to drop-list traffic. 2229 Accepted traffic may be subject to "rate-limit"; the allowed 2230 traffic rate is represented in bytes per second indicated in IEEE 2231 floating point format [IEEE.754.1985]. 2233 This is a mandatory attribute. 2235 The DOTS server indicates the result of processing the POST request 2236 using the status-line header. Concretely, "201 Created" status-line 2237 MUST be returned in the response if the DOTS server has accepted the 2238 filtering rules. If the request is missing a mandatory attribute or 2239 contains an invalid or unknown parameter (e.g., a match field not 2240 supported by the DOTS server), "400 Bad Request" status-line MUST be 2241 returned by the DOTS server in the response. The error-tag is set to 2242 "missing-attribute", "invalid-value", or "unknown-element" as a 2243 function of the encountered error. 2245 If the request is received via a server-domain DOTS gateway, but the 2246 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2247 is expected to be supplied, the DOTS server MUST reply with "403 2248 Forbidden" status-line and the error-tag "access-denied". Upon 2249 receipt of this message, the DOTS client MUST register (Figure 11). 2251 If the request is conflicting with an existing filtering installed by 2252 another DOTS client of the domain, the DOTS server returns "409 2253 Conflict" status-line to the requesting DOTS client. The error-tag 2254 "resource-denied" is used in this case. 2256 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2257 to specify how an access control entry is inserted within an ACL and 2258 how an ACL is inserted within an ACL set. 2260 The DOTS client uses the PUT request to modify its filtering rules 2261 maintained by the DOTS server. In particular, a DOTS client MUST 2262 update its filtering entries upon change of the destination-prefix. 2263 How such change is detected is out of scope. 2265 A DOTS server MUST maintain a filtering rule for at least 10080 2266 minutes (1 week). If no refresh request is seen from the DOTS 2267 client, the DOTS server removes expired entries. Typically, a 2268 refresh request is a PUT request which echoes the content of a 2269 response to a GET request with all of the read-only parameters 2270 stripped out (e.g. pending-lifetime). 2272 7.3. Retrieve Installed Filtering Rules 2274 A DOTS client periodically queries its DOTS server to check the 2275 counters for installed filtering rules. GET request is used to 2276 retrieve filtering rules from a DOTS server. In order to indicate 2277 which type of data is requested in a GET request, the DOTS client 2278 sets adequately the 'content' parameter. 2280 If the DOTS server does not find the access list name conveyed in the 2281 GET request in its configuration data for this DOTS client, it 2282 responds with a "404 Not Found" status-line. 2284 In order to illustrate the intended behavior, consider the example 2285 depicted in Figure 25. In reference to this example, the DOTS client 2286 requests the creation of an immediate ACL called "test-acl-ipv6-udp". 2288 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 2289 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2290 /acl=test-acl-ipv6-udp HTTP/1.1 2291 Host: {host}:{port} 2292 Content-Type: application/yang-data+json 2293 { 2294 "ietf-dots-data-channel:acls": { 2295 "acl": [ 2296 { 2297 "name": "test-acl-ipv6-udp", 2298 "type": "ipv6-acl-type", 2299 "activation-type": "immediate", 2300 "aces": { 2301 "ace": [ 2302 { 2303 "name": "test-ace-ipv6-udp", 2304 "matches": { 2305 "ipv6": { 2306 "destination-ipv6-network": "2001:db8:6401::2/127", 2307 "source-ipv6-network": "2001:db8:1234::/96", 2308 "protocol": 17, 2309 "flow-label": 10000 2310 }, 2311 "udp": { 2312 "source-port": { 2313 "operator": "lte", 2314 "port": 80 2315 }, 2316 "destination-port": { 2317 "operator": "neq", 2318 "port": 1010 2319 } 2320 } 2321 }, 2322 "actions": { 2323 "forwarding": "accept" 2324 } 2325 } 2326 ] 2327 } 2328 } 2329 ] 2330 } 2331 } 2333 Figure 25: Example of a PUT Request to Create a Filtering 2335 The peer DOTS server follows the procedure specified in Section 7.2 2336 to process the request. We consider in the following that a positive 2337 response is sent back to the requesting DOTS client to confirm that 2338 the "test-acl-ipv6-udp" ACL is successfully installed by the DOTS 2339 server. 2341 The DOTS client can issue a GET request to retrieve all its filtering 2342 rules and the number of matches for the installed filtering rules as 2343 illustrated in Figure 26. 'content' parameter is set to 'all'. The 2344 message body of the response to this GET request is shown in 2345 Figure 27. 2347 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2348 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2349 /acls?content=all HTTP/1.1 2350 Host: {host}:{port} 2351 Accept: application/yang-data+json 2353 Figure 26: Retrieve the Configuration Data and State Data for the 2354 Filtering Rules (GET Request) 2356 { 2357 "ietf-dots-data-channel:acls": { 2358 "acl": [ 2359 { 2360 "name": "test-acl-ipv6-udp", 2361 "type": "ipv6-acl-type", 2362 "activation-type": "immediate", 2363 "pending-lifetime":9080, 2364 "aces": { 2365 "ace": [ 2366 { 2367 "name": "test-ace-ipv6-udp", 2368 "matches": { 2369 "ipv6": { 2370 "destination-ipv6-network": "2001:db8:6401::2/127", 2371 "source-ipv6-network": "2001:db8:1234::/96", 2372 "protocol": 17, 2373 "flow-label": 10000 2374 }, 2375 "udp": { 2376 "source-port": { 2377 "operator": "lte", 2378 "port": 80 2379 }, 2380 "destination-port": { 2381 "operator": "neq", 2382 "port": 1010 2383 } 2384 } 2385 }, 2386 "actions": { 2387 "forwarding": "accept" 2388 } 2389 } 2390 ] 2391 } 2392 } 2393 ] 2394 } 2395 } 2397 Figure 27: Retrieve the Configuration Data and State Data for the 2398 Filtering Rules (Response Message Body) 2400 Also, a DOTS client can issue a GET request to retrieve only 2401 configuration data related to an ACL as shown in Figure 28. It does 2402 so by setting 'content' parameter to 'config'. 2404 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2405 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2406 /acl=test-acl-ipv6-udp?content=config HTTP/1.1 2407 Host: {host}:{port} 2408 Accept: application/yang-data+json 2410 Figure 28: Retrieve the Configuration Data for a Filtering Rule (GET 2411 Request) 2413 A response to this GET request is shown in Figure 29. 2415 { 2416 "ietf-dots-data-channel:acls": { 2417 "acl": [ 2418 { 2419 "name": "test-acl-ipv6-udp", 2420 "type": "ipv6-acl-type", 2421 "activation-type": "immediate", 2422 "aces": { 2423 "ace": [ 2424 { 2425 "name": "test-ace-ipv6-udp", 2426 "matches": { 2427 "ipv6": { 2428 "destination-ipv6-network": "2001:db8:6401::2/127", 2429 "source-ipv6-network": "2001:db8:1234::/96", 2430 "protocol": 17, 2431 "flow-label": 10000 2432 }, 2433 "udp": { 2434 "source-port": { 2435 "operator": "lte", 2436 "port": 80 2437 }, 2438 "destination-port": { 2439 "operator": "neq", 2440 "port": 1010 2441 } 2442 } 2443 }, 2444 "actions": { 2445 "forwarding": "accept" 2446 } 2447 } 2448 ] 2449 } 2450 } 2451 ] 2452 } 2453 } 2455 Figure 29: Retrieve the Configuration Data for a Filtering Rule 2456 (Response Message Body) 2458 A DOTS client can also issue a GET request with 'content' parameter 2459 to 'non-config' to exclusively retrieve non-configuration data bound 2460 to a given ACL as shown in Figure 28. A response to this GET request 2461 is shown in Figure 31. 2463 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2464 /dots-client=paL8p4Zqo4SLv64TLPXrxA/acls\ 2465 /acl=test-acl-ipv6-udp?content=non-config HTTP/1.1 2466 Host: {host}:{port} 2467 Accept: application/yang-data+json 2469 Figure 30: Retrieve the Non-Configuration Data for a Filtering Rule 2470 (GET Request) 2472 { 2473 "ietf-dots-data-channel:acls": { 2474 "acl": [ 2475 { 2476 "name": "test-acl-ipv6-udp", 2477 "pending-lifetime": 8000, 2478 "aces": { 2479 "ace": [ 2480 { 2481 "name": "test-ace-ipv6-udp" 2482 } 2483 ] 2484 } 2485 } 2486 ] 2487 } 2488 } 2490 Figure 31: Retrieve the Non-Configuration Data for a Filtering Rule 2491 (Response Message Body) 2493 7.4. Remove Filtering Rules 2495 DELETE request is used by a DOTS client to delete filtering rules 2496 from a DOTS server. 2498 If the DOTS server does not find the access list name carried in the 2499 DELETE request in its configuration data for this DOTS client, it 2500 MUST respond with a "404 Not Found" status-line. The DOTS server 2501 successfully acknowledges a DOTS client's request to withdraw the 2502 filtering rules using "204 No Content" status-line, and removes the 2503 filtering rules accordingly. 2505 Figure 32 shows an example of a request to remove the IPv4 ACL 2506 "sample-ipv4-acl" created in Section 7.2. 2508 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2509 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2510 /acl=sample-ipv4-acl HTTP/1.1 2511 Host: {host}:{port} 2513 Figure 32: Remove a Filtering Rule (DELETE Request) 2515 Figure 33 shows an example of a response received from the DOTS 2516 server to confirm the deletion of "sample-ipv4-acl". 2518 HTTP/1.1 204 No Content 2519 Server: Apache 2520 Date: Fri, 27 Jul 2018 10:05:15 GMT 2521 Cache-Control: no-cache 2522 Content-Type: application/yang-data+json 2523 Content-Length: 0 2524 Connection: Keep-Alive 2526 Figure 33: Remove a Filtering Rule (Response) 2528 8. Operational Considerations 2530 The following operational considerations should be taken into 2531 account: 2533 o DOTS server MUST NOT enable both DOTS data channel and direct 2534 configuration to avoid race conditions and inconsistent 2535 configurations arising from simultaneous updates from multiple 2536 sources. 2538 o DOTS agents SHOULD enable DOTS data channel to configure aliases 2539 and ACLs, and only use direct configuration as a stop-gap 2540 mechanism to test DOTS signal channel with aliases and ACLs. 2541 Further, direct configuration SHOULD only be used when the on-path 2542 DOTS agents are within the same domain. 2544 o If the DOTS server has enabled direct configuration, it can reject 2545 the DOTS data channel connection using hard ICMP error [RFC1122] 2546 or RST (Reset) bit in the TCP header or reject the RESTCONF 2547 request using an error response containing a "503 Service 2548 Unavailable" status-line. 2550 9. IANA Considerations 2552 This document requests IANA to register the following URI in the 2553 "IETF XML Registry" [RFC3688]: 2555 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2556 Registrant Contact: The IESG. 2557 XML: N/A; the requested URI is an XML namespace. 2559 This document requests IANA to register the following YANG module in 2560 the "YANG Module Names" registry [RFC7950]. 2562 name: ietf-dots-data-channel 2563 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2564 prefix: data-channel 2565 reference: RFC XXXX 2567 10. Security Considerations 2569 RESTCONF security considerations are discussed in [RFC8040]. In 2570 particular, DOTS agents MUST follow the security recommendations in 2571 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2572 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2573 [I-D.ietf-dots-signal-channel]. YANG ACL-specific security 2574 considerations are discussed in [I-D.ietf-netmod-acl-model]. 2576 Authenticated encryption MUST be used for data confidentiality and 2577 message integrity. The interaction between the DOTS agents requires 2578 Transport Layer Security (TLS) with a cipher suite offering 2579 confidentiality protection and the guidance given in [RFC7525] MUST 2580 be followed to avoid attacks on TLS. 2582 The installation of drop- or accept-list rules using RESTCONF over 2583 TLS reveals the attacker IP addresses and legitimate IP addresses 2584 only to the DOTS server trusted by the DOTS client. The secure 2585 communication channel between DOTS agents provides privacy and 2586 prevents a network eavesdropper from gaining access to the drop- and 2587 accept-listed IP addresses. 2589 An attacker may be able to inject RST packets, bogus application 2590 segments, etc., regardless of whether TLS authentication is used. 2591 Because the application data is TLS protected, this will not result 2592 in the application receiving bogus data, but it will constitute a DoS 2593 on the connection. This attack can be countered by using TCP-AO 2594 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2595 attacker will be rejected by the TCP-AO integrity check and therefore 2596 will never reach the TLS layer. 2598 In order to prevent leaking internal information outside a client- 2599 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2600 internal DOTS clients (e.g., source IP address, client's hostname) 2601 unless explicitly configured to do so. 2603 DOTS servers MUST verify that requesting DOTS clients are entitled to 2604 enforce filtering rules on a given IP prefix. That is, only 2605 filtering rules on IP resources that belong to the DOTS client's 2606 domain MUST be authorized by a DOTS server. The exact mechanism for 2607 the DOTS servers to validate that the target prefixes are within the 2608 scope of the DOTS client's domain is deployment-specific. 2610 Rate-limiting DOTS requests, including those with new 'cuid' values, 2611 from the same DOTS client defends against DoS attacks that would 2612 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 2613 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 2614 DOTS servers. 2616 Applying resources quota per DOTS client and/or per DOTS client 2617 domain (e.g., limit the number of aliases and filters to be install 2618 by DOTS clients) prevents DOTS server resources to be aggressively 2619 used by some DOTS clients and ensures, therefore, DDoS mitigation 2620 usage fairness. Additionally, DOTS servers may limit the number of 2621 DOTS clients that can be enabled per domain. 2623 The presence of DOTS gateways may lead to infinite forwarding loops, 2624 which is undesirable. To prevent and detect such loops, a mechanism 2625 is defined in Section 3.5. 2627 All data nodes defined in the YANG module which can be created, 2628 modified, and deleted (i.e., config true, which is the default) are 2629 considered sensitive. Write operations applied to these data nodes 2630 without proper protection can negatively affect network operations. 2631 Appropriate security measures are recommended to prevent illegitimate 2632 users from invoking DOTS data channel primitives. Nevertheless, an 2633 attacker who can access a DOTS client is technically capable of 2634 launching various attacks, such as: 2636 o Set an arbitrarily low rate-limit, which may prevent legitimate 2637 traffic from being forwarded (rate-limit). 2639 o Set an arbitrarily high rate-limit, which may lead to the 2640 forwarding of illegitimate DDoS traffic (rate-limit). 2642 o Communicate invalid aliases to the server (alias), which will 2643 cause the failure of associating both data and signal channels. 2645 o Set invalid ACL entries, which may prevent legitimate traffic from 2646 being forwarded. Likewise, invalid ACL entries may lead to 2647 forward DDoS traffic. 2649 11. Contributors 2651 The following individuals have contributed to this document: 2653 o Dan Wing, Email: dwing-ietf@fuggles.com 2655 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.com 2657 12. Acknowledgements 2659 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2660 Doron, Russ White, Gilbert Clark, Kathleen Moriarty, and Nesredien 2661 Suleiman for the discussion and comments. 2663 13. References 2665 13.1. Normative References 2667 [I-D.ietf-dots-signal-channel] 2668 K, R., Boucadair, M., Patil, P., Mortensen, A., and N. 2669 Teague, "Distributed Denial-of-Service Open Threat 2670 Signaling (DOTS) Signal Channel Specification", draft- 2671 ietf-dots-signal-channel-25 (work in progress), September 2672 2018. 2674 [I-D.ietf-netmod-acl-model] 2675 Jethanandani, M., Agarwal, S., Huang, L., and D. Blair, 2676 "Network Access Control List (ACL) YANG Data Model", 2677 draft-ietf-netmod-acl-model-21 (work in progress), 2678 November 2018. 2680 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2681 Requirement Levels", BCP 14, RFC 2119, 2682 DOI 10.17487/RFC2119, March 1997, 2683 . 2685 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2686 DOI 10.17487/RFC3688, January 2004, 2687 . 2689 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2690 (CIDR): The Internet Address Assignment and Aggregation 2691 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2692 2006, . 2694 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2695 Protocol (HTTP/1.1): Message Syntax and Routing", 2696 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2697 . 2699 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2700 "Recommendations for Secure Use of Transport Layer 2701 Security (TLS) and Datagram Transport Layer Security 2702 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2703 2015, . 2705 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2706 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2707 . 2709 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2710 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2711 . 2713 13.2. Informative References 2715 [I-D.ietf-dots-architecture] 2716 Mortensen, A., Andreasen, F., K, R., Compton, R., and N. 2717 Teague, "Distributed-Denial-of-Service Open Threat 2718 Signaling (DOTS) Architecture", draft-ietf-dots- 2719 architecture-07 (work in progress), September 2018. 2721 [I-D.ietf-dots-requirements] 2722 Mortensen, A., Moskowitz, R., and R. K, "Distributed 2723 Denial of Service (DDoS) Open Threat Signaling 2724 Requirements", draft-ietf-dots-requirements-16 (work in 2725 progress), October 2018. 2727 [IEEE.754.1985] 2728 Institute of Electrical and Electronics Engineers, 2729 "Standard for Binary Floating-Point Arithmetic", August 2730 1985. 2732 [proto_numbers] 2733 "IANA, "Protocol Numbers"", 2011, 2734 . 2736 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 2737 Communication Layers", STD 3, RFC 1122, 2738 DOI 10.17487/RFC1122, October 1989, 2739 . 2741 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 2742 RFC 1983, DOI 10.17487/RFC1983, August 1996, 2743 . 2745 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2746 Resource Identifier (URI): Generic Syntax", STD 66, 2747 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2748 . 2750 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2751 Congestion Control Protocol (DCCP)", RFC 4340, 2752 DOI 10.17487/RFC4340, March 2006, 2753 . 2755 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2756 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2757 . 2759 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2760 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2761 DOI 10.17487/RFC5389, October 2008, 2762 . 2764 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2765 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2766 June 2010, . 2768 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2769 Layer Security (TLS) and Datagram Transport Layer Security 2770 (DTLS) Heartbeat Extension", RFC 6520, 2771 DOI 10.17487/RFC6520, February 2012, 2772 . 2774 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 2775 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 2776 DOI 10.17487/RFC6887, April 2013, 2777 . 2779 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2780 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2781 . 2783 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2784 Interchange Format", STD 90, RFC 8259, 2785 DOI 10.17487/RFC8259, December 2017, 2786 . 2788 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2789 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2790 . 2792 Appendix A. Sample Examples: Filtering Fragments 2794 This specification strongly recommends the use of "fragment" for 2795 handling fragments. 2797 Figure 34 shows the content of the POST request to be issued by a 2798 DOTS client to its DOTS server to allow the traffic destined to 2799 198.51.100.0/24 and UDP port number 53, but to drop all fragmented 2800 packets. The following ACEs are defined (in this order): 2802 o "drop-all-fragments" ACE: discards all fragments. 2804 o "allow-dns-packets" ACE: accepts DNS packets destined to 2805 198.51.100.0/24. 2807 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2808 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2809 Host: {host}:{port} 2810 Content-Type: application/yang-data+json 2811 { 2812 "ietf-dots-data-channel:acls": { 2813 "acl": [ 2814 { 2815 "name": "dns-fragments", 2816 "type": "ipv4-acl-type", 2817 "aces": { 2818 "ace": [ 2819 { 2820 "name": "drop-all-fragments", 2821 "matches": { 2822 "ipv4": { 2823 "fragment": { 2824 "operator": "match", 2825 "type": "isf" 2826 } 2827 } 2828 }, 2829 "actions": { 2830 "forwarding": "drop" 2831 } 2832 } 2833 ] 2834 "ace": [ 2835 { 2836 "name": "allow-dns-packets", 2837 "matches": { 2838 "ipv4": { 2839 "destination-ipv4-network": "198.51.100.0/24" 2840 } 2841 "udp": { 2842 "destination-port": { 2843 "operator": "eq", 2844 "port": 53 2845 } 2846 }, 2847 "actions": { 2848 "forwarding": "accept" 2849 } 2850 } 2851 ] 2852 } 2853 } 2854 ] 2855 } 2856 } 2858 Figure 34: Filtering IPv4 Fragmented Packets (Recommended) 2860 Figure 35 shows a POST request example issued by a DOTS client to its 2861 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 2862 port number 53, but to drop all fragmented packets. The following 2863 ACEs are defined (in this order): 2865 o "drop-all-fragments" ACE: discards all fragments (including atomic 2866 fragments). That is, IPv6 packets which include a Fragment header 2867 (44) are dropped. 2869 o "allow-dns-packets" ACE: accepts DNS packets destined to 2870 2001:db8::/32. 2872 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2873 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2874 Host: {host}:{port} 2875 Content-Type: application/yang-data+json 2876 { 2877 "ietf-dots-data-channel:acls": { 2878 "acl": [ 2879 { 2880 "name": "dns-fragments", 2881 "type": "ipv6-acl-type", 2882 "aces": { 2883 "ace": [ 2884 { 2885 "name": "drop-all-fragments", 2886 "matches": { 2887 "ipv6": { 2888 "fragment": { 2889 "operator": "match", 2890 "type": "isf" 2891 } 2892 } 2893 }, 2894 "actions": { 2895 "forwarding": "drop" 2896 } 2897 } 2898 ] 2899 "ace": [ 2900 { 2901 "name": "allow-dns-packets", 2902 "matches": { 2903 "ipv6": { 2904 "destination-ipv6-network": "2001:db8::/32" 2905 } 2906 "udp": { 2907 "destination-port": { 2908 "operator": "eq", 2909 "port": 53 2910 } 2911 } 2912 }, 2913 "actions": { 2914 "forwarding": "accept" 2915 } 2916 } 2917 ] 2918 } 2919 } 2920 ] 2921 } 2922 } 2924 Figure 35: Filtering IPv6 Fragmented Packets 2926 Authors' Addresses 2927 Mohamed Boucadair (editor) 2928 Orange 2929 Rennes 35000 2930 France 2932 Email: mohamed.boucadair@orange.com 2934 Tirumaleswar Reddy (editor) 2935 McAfee, Inc. 2936 Embassy Golf Link Business Park 2937 Bangalore, Karnataka 560071 2938 India 2940 Email: kondtir@gmail.com 2942 Kaname Nishizuka 2943 NTT Communications 2944 GranPark 16F 3-4-1 Shibaura, Minato-ku 2945 Tokyo 108-8118 2946 Japan 2948 Email: kaname@nttv6.jp 2950 Liang Xia 2951 Huawei 2952 101 Software Avenue, Yuhuatai District 2953 Nanjing, Jiangsu 210012 2954 China 2956 Email: frank.xialiang@huawei.com 2958 Prashanth Patil 2959 Cisco Systems, Inc. 2961 Email: praspati@cisco.com 2963 Andrew Mortensen 2964 Arbor Networks, Inc. 2965 2727 S. State St 2966 Ann Arbor, MI 48104 2967 United States 2969 Email: amortensen@arbor.net 2970 Nik Teague 2971 Verisign, Inc. 2972 United States 2974 Email: nteague@verisign.com