idnits 2.17.1 draft-ietf-dots-data-channel-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 22 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([I-D.ietf-netmod-acl-model], [I-D.ietf-dots-signal-channel]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 459 has weird spacing: '...er-port ine...' == Line 460 has weird spacing: '...er-port ine...' == Line 542 has weird spacing: '...warding ide...' -- The document date (April 18, 2018) is 2199 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 1967 -- Looks like a reference, but probably isn't: '6' on line 1967 -- Looks like a reference, but probably isn't: '17' on line 1967 -- Looks like a reference, but probably isn't: '58' on line 1967 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-19 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-18 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-06 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-14 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 5 errors (**), 0 flaws (~~), 8 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy, Ed. 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair, Ed. 5 Expires: October 20, 2018 Orange 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 April 18, 2018 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 Specification 20 draft-ietf-dots-data-channel-15 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 with the RFC number to be assigned to 35 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 October 20, 2018. 73 Copyright Notice 75 Copyright (c) 2018 IETF Trust and the persons identified as the 76 document authors. All rights reserved. 78 This document is subject to BCP 78 and the IETF Trust's Legal 79 Provisions Relating to IETF Documents 80 (https://trustee.ietf.org/license-info) in effect on the date of 81 publication of this document. Please review these documents 82 carefully, as they describe your rights and restrictions with respect 83 to this document. Code Components extracted from this document must 84 include Simplified BSD License text as described in Section 4.e of 85 the Trust Legal Provisions and are provided without warranty as 86 described in the Simplified BSD License. 88 Table of Contents 90 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 91 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 92 3. DOTS Data Channel . . . . . . . . . . . . . . . . . . . . . . 6 93 3.1. Design Overview . . . . . . . . . . . . . . . . . . . . . 6 94 3.2. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 95 3.3. NAT Considerations . . . . . . . . . . . . . . . . . . . 8 96 3.4. DOTS Gateways . . . . . . . . . . . . . . . . . . . . . . 8 97 3.5. Detect and Prevent Infinite Loops . . . . . . . . . . . . 9 98 3.6. Stale Entries . . . . . . . . . . . . . . . . . . . . . . 10 99 4. DOTS Data Channel YANG Module . . . . . . . . . . . . . . . . 10 100 4.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 10 101 4.2. Filtering Fields . . . . . . . . . . . . . . . . . . . . 14 102 4.3. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 21 103 5. Managing DOTS Clients . . . . . . . . . . . . . . . . . . . . 34 104 5.1. Registering DOTS Clients . . . . . . . . . . . . . . . . 34 105 5.2. Uregistering DOTS Clients . . . . . . . . . . . . . . . . 37 106 6. Managing DOTS Aliases . . . . . . . . . . . . . . . . . . . . 37 107 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 37 108 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 41 109 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 43 110 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 43 111 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 43 112 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 45 113 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 48 114 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 49 115 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 116 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 50 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 50 118 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 52 119 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 120 12.1. Normative References . . . . . . . . . . . . . . . . . . 52 121 12.2. Informative References . . . . . . . . . . . . . . . . . 53 122 Appendix A. Sample Examples: Filtering Fragments . . . . . . . . 54 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58 125 1. Introduction 127 A distributed denial-of-service (DDoS) attack is an attempt to make 128 machines or network resources unavailable to their intended users. 129 In most cases, sufficient scale can be achieved by compromising 130 enough end-hosts and using those infected hosts to perpetrate and 131 amplify the attack. The victim of such attack can be an application 132 server, a router, a firewall, an entire network, etc. 134 As discussed in [I-D.ietf-dots-requirements], the lack of a common 135 method to coordinate a real-time response among involved actors and 136 network domains inhibits the speed and effectiveness of DDoS attack 137 mitigation. From that standpoint, DDoS Open Threat Signaling (DOTS) 138 defines an architecture that allows a DOTS client to send requests to 139 a DOTS server for DDoS attack mitigation 140 [I-D.ietf-dots-architecture]. The DOTS approach is thus meant to 141 minimize the impact of DDoS attacks, thereby contributing to the 142 enforcement of more efficient defensive if not proactive security 143 strategies. To that aim, DOTS defines two channels: the signal and 144 the data channels (Figure 1). 146 +---------------+ +---------------+ 147 | | <------- Signal Channel ------> | | 148 | DOTS Client | | DOTS Server | 149 | | <======= Data Channel ======> | | 150 +---------------+ +---------------+ 152 Figure 1: DOTS Channels 154 The DOTS signal channel is used to carry information about a device 155 or a network (or a part thereof) that is under a DDoS attack. Such 156 information is sent by a DOTS client to an upstream DOTS server so 157 that appropriate mitigation actions are undertaken on traffic deemed 158 suspicious. The DOTS signal channel is further elaborated in 159 [I-D.ietf-dots-signal-channel]. 161 As for the DOTS data channel, it is used for infrequent bulk data 162 exchange between DOTS agents to significantly improve the 163 coordination of all the parties involved in the response to the 164 attack. Section 2 of [I-D.ietf-dots-architecture] mentions that the 165 DOTS data channel is used to perform the following tasks: 167 o Creating aliases for resources for which mitigation may be 168 requested. 170 A DOTS client may submit to its DOTS server a collection of 171 prefixes which it would like to refer to by an alias when 172 requesting mitigation. The DOTS server can respond to this 173 request with either a success or failure response (see Section 2 174 in [I-D.ietf-dots-architecture]). 176 Refer to Section 6 for more details. 178 o Filter management, which enables a DOTS client to request the 179 installation or withdrawal of traffic filters, dropping or rate- 180 limiting unwanted traffic, and permitting white-listed traffic. A 181 DOTS client is entitled to instruct filtering rules only on IP 182 resources that belong to its domain. 184 Sample use cases for populating black- or white-list filtering 185 rules are detailed hereafter: 187 * If a network resource (DOTS client) detects a potential DDoS 188 attack from a set of IP addresses, the DOTS client informs its 189 servicing DOTS gateway of all suspect IP addresses that need to 190 be blocked or black-listed for further investigation. The DOTS 191 client could also specify a list of protocols and port numbers 192 in the black-list rule. 194 The DOTS gateway then propagates the black-listed IP addresses 195 to a DOTS server which will undertake appropriate actions so 196 that traffic originated by these IP addresses to the target 197 network (specified by the DOTS client) is blocked. 199 * A network, that has partner sites from which only legitimate 200 traffic arrives, may want to ensure that the traffic from these 201 sites is not subjected to DDoS attack mitigation. The DOTS 202 client uses the DOTS data channel to convey the white-listed IP 203 prefixes of the partner sites to its DOTS server. 205 The DOTS server uses this information to white-list flows 206 originated by such IP prefixes and which reach the network. 208 Refer to Section 7 for more details. 210 2. Terminology 212 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 213 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 214 document are to be interpreted as described in [RFC2119]. 216 The reader should be familiar with the terms defined in 217 [I-D.ietf-dots-requirements]. 219 The terminology for describing YANG data modules is defined in 220 [RFC7950]. The meaning of the symbols in tree diagrams is defined in 221 [RFC8340]. 223 This document generalizes the notion of Access Control List (ACL) so 224 that it is not device-specific [I-D.ietf-netmod-acl-model]. As such, 225 this document defines an ACL as an ordered set of rules that is used 226 to filter traffic. Each rule is represented by an Access Control 227 Entry (ACE). ACLs communicated via the DOTS data channel are not 228 bound to a device interface. 230 For the sake of simplicity, all of the examples in this document use 231 "/restconf" as the discovered RESTCONF API root path. Many protocol 232 header lines and message-body text within examples throughout the 233 document are split into multiple lines for display purposes only. 234 When a line ends with backslash ('\') as the last character, the line 235 is wrapped for display purposes. It is to be considered to be joined 236 to the next line by deleting the backslash, the following line break, 237 and the leading whitespace of the next line. 239 3. DOTS Data Channel 241 3.1. Design Overview 243 Unlike the DOTS signal channel, which must remain operational even 244 when confronted with signal degradation due to packets loss, the DOTS 245 data channel is not expected to be fully operational at all times, 246 especially when a DDoS attack is underway. The requirements for a 247 DOTS data channel protocol are documented in 248 [I-D.ietf-dots-requirements]. 250 This specification does not require an order of DOTS signal and data 251 channel creations nor mandates a time interval between them. These 252 considerations are implementation- and deployment-specific. 254 As the primary function of the data channel is data exchange, a 255 reliable transport mode is required in order for DOTS agents to 256 detect data delivery success or failure. This document uses RESTCONF 257 [RFC8040] over TLS [RFC5246] over TCP as the DOTS data channel 258 protocol. The abstract layering of DOTS data channel is shown in 259 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 data modules. These 277 basic edit operations allow the DOTS data channel running 278 configuration to 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 blacklist a prefix by specifying the source 321 prefix, while another DOTS client could request to whitelist 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 follow by a DOTS client to place its requests (e.g., contact all 343 servers, select one server among the list) when multiple DOTS servers 344 are provisioned. 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 minimizing 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. Tree Structure 441 The DOTS data channel YANG module (ietf-dots-data-channel) allows a 442 DOTS client to manage aliases for resources for which mitigation may 443 be requested. Such aliases may be used in subsequent DOTS signal 444 channel exchanges to refer more efficiently to the resources under 445 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 allows DOTS clients to 473 manage filtering rules. Examples of filtering management in a DOTS 474 context include, but not limited to: 476 o Black-list management, which enables a DOTS client to inform a 477 DOTS server about sources from which traffic should be discarded. 479 o White-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 Filter 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 white-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 Figure 6 shows the IPv4 match subtree. 575 module: ietf-dots-data-channel 576 +--rw dots-data 577 +--rw dots-client* [cuid] 578 | ... 579 | +--rw acls 580 | +--rw acl* [name] 581 | ... 582 | +--rw aces 583 | +--rw ace* [name] 584 | +--rw name string 585 | +--rw matches 586 | | +--rw (l3)? 587 | | | +--:(ipv4) 588 | | | | +--rw ipv4 589 | | | | +--rw dscp? inet:dscp 590 | | | | +--rw ecn? uint8 591 | | | | +--rw length? uint16 592 | | | | +--rw ttl? uint8 593 | | | | +--rw protocol? uint8 594 | | | | +--rw ihl? uint8 595 | | | | +--rw flags? bits 596 | | | | +--rw offset? uint16 597 | | | | +--rw identification? uint16 598 | | | | +--rw (destination-network)? 599 | | | | | +--:(destination-ipv4-network) 600 | | | | | +--rw destination-ipv4-network? 601 | | | | | inet:ipv4-prefix 602 | | | | +--rw (source-network)? 603 | | | | +--:(source-ipv4-network) 604 | | | | +--rw source-ipv4-network? 605 | | | | inet:ipv4-prefix 606 | | | +--:(ipv6) 607 | | | ... 608 | | +--rw (l4)? 609 | | ... 610 | +--rw actions 611 | | ... 612 | +--ro statistics 613 | ... 614 +--ro capabilities 615 ... 617 Figure 6: DOTS ACLs Subtree (IPv4 Match) 619 Figure 7 shows the IPv6 match subtree. 621 module: ietf-dots-data-channel 622 +--rw dots-data 623 +--rw dots-client* [cuid] 624 | ... 625 | +--rw acls 626 | +--rw acl* [name] 627 | ... 628 | +--rw aces 629 | +--rw ace* [name] 630 | +--rw name string 631 | +--rw matches 632 | | +--rw (l3)? 633 | | | +--:(ipv4) 634 | | | | ... 635 | | | +--:(ipv6) 636 | | | +--rw ipv6 637 | | | +--rw dscp? inet:dscp 638 | | | +--rw ecn? uint8 639 | | | +--rw length? uint16 640 | | | +--rw ttl? uint8 641 | | | +--rw protocol? uint8 642 | | | +--rw (destination-network)? 643 | | | | +--:(destination-ipv6-network) 644 | | | | +--rw destination-ipv6-network? 645 | | | | inet:ipv6-prefix 646 | | | +--rw (source-network)? 647 | | | | +--:(source-ipv6-network) 648 | | | | +--rw source-ipv6-network? 649 | | | | inet:ipv6-prefix 650 | | | +--rw flow-label? 651 | | | | inet:ipv6-flow-label 652 | | | +--rw fragment? empty 653 | | +--rw (l4)? 654 | | ... 655 | +--rw actions 656 | | ... 657 | +--ro statistics 658 | ... 659 +--ro capabilities 660 ... 662 Figure 7: DOTS ACLs Subtree (IPv6 Match) 664 Figure 8 shows the TCP match subtree. 666 module: ietf-dots-data-channel 667 +--rw dots-data 668 +--rw dots-client* [cuid] 669 | ... 670 | +--rw acls 671 | +--rw acl* [name] 672 | ... 673 | +--rw aces 674 | +--rw ace* [name] 675 | +--rw name string 676 | +--rw matches 677 | | +--rw (l3)? 678 | | | ... 679 | | +--rw (l4)? 680 | | +--:(tcp) 681 | | | +--rw tcp 682 | | | +--rw sequence-number? uint32 683 | | | +--rw acknowledgement-number? uint32 684 | | | +--rw data-offset? uint8 685 | | | +--rw reserved? uint8 686 | | | +--rw flags? bits 687 | | | +--rw window-size? uint16 688 | | | +--rw urgent-pointer? uint16 689 | | | +--rw options? uint32 690 | | | +--rw (source-port)? 691 | | | | +--:(source-port-range-or-operator) 692 | | | | +--rw source-port-range-or-operator 693 | | | | +--rw (port-range-or-operator)? 694 | | | | +--:(range) 695 | | | | | +--rw lower-port 696 | | | | | | inet:port-number 697 | | | | | +--rw upper-port 698 | | | | | inet:port-number 699 | | | | +--:(operator) 700 | | | | +--rw operator? 701 | | | | | operator 702 | | | | +--rw port 703 | | | | inet:port-number 704 | | | +--rw (destination-port)? 705 | | | +--:(destination-port-range-or-operator) 706 | | | +--rw destination-port-range-or-operator 707 | | | +--rw (port-range-or-operator)? 708 | | | +--:(range) 709 | | | | +--rw lower-port 710 | | | | | inet:port-number 711 | | | | +--rw upper-port 712 | | | | inet:port-number 713 | | | +--:(operator) 714 | | | +--rw operator? 715 | | | | operator 716 | | | +--rw port 717 | | | inet:port-number 718 | | +--:(udp) 719 | | | ... 720 | | +--:(icmp) 721 | | ... 722 | +--rw actions 723 | | ... 724 | +--ro statistics 725 | ... 726 +--ro capabilities 727 ... 729 Figure 8: DOTS ACLs Subtree (TCP Match) 731 Figure 9 shows the UDP and ICMP match subtree. 733 module: ietf-dots-data-channel 734 +--rw dots-data 735 +--rw dots-client* [cuid] 736 | ... 737 | +--rw acls 738 | +--rw acl* [name] 739 | ... 740 | +--rw aces 741 | +--rw ace* [name] 742 | +--rw name string 743 | +--rw matches 744 | | +--rw (l3)? 745 | | | ... 746 | | +--rw (l4)? 747 | | +--:(tcp) 748 | | | ... 749 | | +--:(udp) 750 | | | +--rw udp 751 | | | +--rw length? uint16 752 | | | +--rw (source-port)? 753 | | | | +--:(source-port-range-or-operator) 754 | | | | +--rw source-port-range-or-operator 755 | | | | +--rw (port-range-or-operator)? 756 | | | | +--:(range) 757 | | | | | +--rw lower-port 758 | | | | | | inet:port-number 759 | | | | | +--rw upper-port 760 | | | | | inet:port-number 761 | | | | +--:(operator) 762 | | | | +--rw operator? 763 | | | | | operator 764 | | | | +--rw port 765 | | | | inet:port-number 766 | | | +--rw (destination-port)? 767 | | | +--:(destination-port-range-or-operator) 768 | | | +--rw destination-port-range-or-operator 769 | | | +--rw (port-range-or-operator)? 770 | | | +--:(range) 771 | | | | +--rw lower-port 772 | | | | | inet:port-number 773 | | | | +--rw upper-port 774 | | | | inet:port-number 775 | | | +--:(operator) 776 | | | +--rw operator? 777 | | | | operator 778 | | | +--rw port 779 | | | inet:port-number 780 | | +--:(icmp) 781 | | +--rw icmp 782 | | +--rw type? uint8 783 | | +--rw code? uint8 784 | | +--rw rest-of-header? uint32 785 | +--rw actions 786 | | ... 787 | +--ro statistics 788 | ... 789 +--ro capabilities 790 ... 792 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 794 DOTS implementations MUST support the following matching criteria: 796 match based on the IP header (IPv4 and IPv6), match based on the 797 transport header (TCP, UDP, and ICMP), and any combination 798 thereof. The same matching fields are used for both ICMP and 799 ICMPv6. 801 The following match fields MUST be supported by DOTS implementations 802 (Table 1): 804 ACL Mandatory Fields 805 Match 806 -------- ------------------------------------------------------------ 807 ipv4 length, protocol, flags, destination-ipv4-network, and 808 source-ipv4-network 809 ipv6 length, protocol, destination-ipv6-network, source- 810 ipv6-network, and fragment 811 tcp flags, source-port-range-or-operator, and destination-port- 812 range-or-operator 813 udp length, source-port-range-or-operator, and destination-port- 814 range-or-operator 815 icmp type and code 817 Table 1: Mandatory DOTS Channel Match Fields 819 Implementations MAY support other filtering match fields and actions. 820 The 'ietf-dots-data-channel' allows an implementation to expose its 821 filtering capabilities. The tree structure of the 'capabilities' is 822 shown in Figure 10. 824 module: ietf-dots-data-channel 825 +--rw dots-data 826 ... 827 +--ro capabilities 828 +--ro address-family* enumeration 829 +--ro forwarding-actions* identityref 830 +--ro rate-limit? boolean 831 +--ro fragment* enumeration 832 +--ro transport-protocols* uint8 833 +--ro ipv4 834 | +--ro dscp? boolean 835 | +--ro ecn? boolean 836 | +--ro length? boolean 837 | +--ro ttl? boolean 838 | +--ro protocol? boolean 839 | +--ro ihl? boolean 840 | +--ro flags? boolean 841 | +--ro offset? boolean 842 | +--ro identification? boolean 843 | +--ro source-prefix? boolean 844 | +--ro destination-prefix? boolean 845 +--ro ipv6 846 | +--ro dscp? boolean 847 | +--ro ecn? boolean 848 | +--ro flow-label? boolean 849 | +--ro length? boolean 850 | +--ro protocol? boolean 851 | +--ro hoplimit? boolean 852 | +--ro source-prefix? boolean 853 | +--ro destination-prefix? boolean 854 +--ro tcp 855 | +--ro sequence-number? boolean 856 | +--ro acknowledgement-number? boolean 857 | +--ro data-offset? boolean 858 | +--ro reserved? boolean 859 | +--ro flags? boolean 860 | +--ro window-size? boolean 861 | +--ro urgent-pointer? boolean 862 | +--ro options? boolean 863 | +--ro source-port? boolean 864 | +--ro destination-port? boolean 865 | +--ro port-range? boolean 866 +--ro udp 867 | +--ro length? boolean 868 | +--ro source-port? boolean 869 | +--ro destination-port? boolean 870 | +--ro port-range? boolean 871 +--ro icmp 872 +--ro type? boolean 873 +--ro code? boolean 874 +--ro rest-of-header? boolean 876 Figure 10: Filtering Capabilities Sub-Tree 878 4.3. YANG Module 880 file "ietf-dots-data-channel@2018-04-16.yang" 882 module ietf-dots-data-channel { 883 yang-version 1.1; 884 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 885 prefix data-channel; 887 import ietf-access-control-list { 888 prefix ietf-acl; 889 } 890 import ietf-packet-fields { 891 prefix packet-fields; 892 } 893 import ietf-dots-signal-channel { 894 prefix dots-signal; 895 } 897 organization 898 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 899 contact 900 "WG Web: 901 WG List: 903 Editor: Konda, Tirumaleswar Reddy 904 906 Editor: Mohamed Boucadair 907 909 Author: Kaname Nishizuka 910 912 Author: Liang Xia 913 915 Author: Prashanth Patil 916 918 Author: Andrew Mortensen 919 921 Author: Nik Teague 922 924 Author: Jon Shallow 925 "; 926 description 927 "This module contains YANG definition for configuring 928 aliases for resources and filtering rules using DOTS 929 data channel. 931 Copyright (c) 2018 IETF Trust and the persons identified as 932 authors of the code. All rights reserved. 934 Redistribution and use in source and binary forms, with or 935 without modification, is permitted pursuant to, and subject 936 to the license terms contained in, the Simplified BSD License 937 set forth in Section 4.c of the IETF Trust's Legal Provisions 938 Relating to IETF Documents 939 (http://trustee.ietf.org/license-info). 941 This version of this YANG module is part of RFC XXXX; see 942 the RFC itself for full legal notices."; 944 revision 2018-04-16 { 945 description 946 "Initial revision."; 947 reference 948 "RFC XXXX: Distributed Denial-of-Service Open Threat 949 Signaling (DOTS) Data Channel Specification"; 950 } 952 grouping aliases { 953 description 954 "Top level container for aliases"; 955 list alias { 956 key "name"; 957 description 958 "List of aliases"; 959 leaf name { 960 type string; 961 description 962 "The name of the alias"; 963 } 964 uses dots-signal:target; 965 leaf pending-lifetime { 966 type int32; 967 units "minutes"; 968 config false; 969 description 970 "Indicates the pending validity lifetime of the alias 971 entry."; 972 } 973 } 974 } 976 grouping ports { 977 choice source-port { 978 container source-port-range-or-operator { 979 uses packet-fields:port-range-or-operator; 980 description 981 "Source port definition."; 982 } 983 description 984 "Choice of specifying the source port or referring to 985 a group of source ports."; 986 } 987 choice destination-port { 988 container destination-port-range-or-operator { 989 uses packet-fields:port-range-or-operator; 990 description 991 "Destination port definition."; 992 } 993 description 994 "Choice of specifying a destination port or referring 995 to a group of destination ports."; 997 } 998 description 999 "Choice of specifying a source or destination ports."; 1000 } 1002 grouping access-lists { 1003 description 1004 "Specifies the ordered set of Access Control Lists."; 1005 list acl { 1006 key "name"; 1007 ordered-by user; 1008 description 1009 "An Access Control List (ACL) is an ordered list of 1010 Access Control Entries (ACE). Each Access Control Entry 1011 has a list of match criteria and a list of actions."; 1012 leaf name { 1013 type string { 1014 length "1..64"; 1015 } 1016 description 1017 "The name of the access list."; 1018 reference 1019 "RFC ZZZZ: Network Access Control List (ACL) 1020 YANG Data Model"; 1021 } 1022 leaf type { 1023 type ietf-acl:acl-type; 1024 description 1025 "Type of access control list. Indicates the primary intended 1026 type of match criteria (e.g., IPv4, IPv6) used in the list 1027 instance."; 1028 reference 1029 "RFC ZZZZ: Network Access Control List (ACL) 1030 YANG Data Model"; 1031 } 1032 leaf activation-type { 1033 type enumeration { 1034 enum "activate-when-mitigating" { 1035 value 1; 1036 description 1037 "The ACL is installed only when a mitigation is active. 1038 The ACL is specific to this DOTS client."; 1039 } 1040 enum "immediate" { 1041 value 2; 1042 description 1043 "The ACL is immediately activated."; 1044 } 1046 } 1047 description 1048 "Indicates whether an ACL is to be installed immediately 1049 or when a mitigation is active."; 1050 } 1051 leaf pending-lifetime { 1052 type int32; 1053 units "minutes"; 1054 config false; 1055 description 1056 "Indicates the pending validity lifetime of the alias 1057 entry."; 1058 } 1059 container aces { 1060 description 1061 "The Access Control Entries container contains 1062 a list of ACEs."; 1063 list ace { 1064 key "name"; 1065 ordered-by user; 1066 description 1067 "List of access list entries."; 1068 leaf name { 1069 type string { 1070 length "1..64"; 1071 } 1072 description 1073 "A unique name identifying this Access List 1074 Entry (ACE)."; 1075 reference 1076 "RFC ZZZZ: Network Access Control List (ACL) 1077 YANG Data Model"; 1078 } 1079 container matches { 1080 description 1081 "The rules in this set determine what fields will be 1082 matched upon before any action is taken on them. 1084 If no matches are defined in a particular container, 1085 then any packet will match that container. 1087 If no matches are specified at all in an ACE, then any 1088 packet will match the ACE."; 1089 reference 1090 "RFC ZZZZ: Network Access Control List (ACL) 1091 YANG Data Model"; 1093 choice l3 { 1094 container ipv4 { 1095 when "derived-from(../../../../type," + 1096 "'ietf-acl:ipv4-acl-type')"; 1097 uses packet-fields:acl-ip-header-fields; 1098 uses packet-fields:acl-ipv4-header-fields; 1099 description 1100 "Rule set that matches IPv4 header."; 1101 } 1102 container ipv6 { 1103 when "derived-from(../../../../type," + 1104 "'ietf-acl:ipv6-acl-type')"; 1105 uses packet-fields:acl-ip-header-fields; 1106 uses packet-fields:acl-ipv6-header-fields; 1107 leaf fragment { 1108 type empty; 1109 description 1110 "Handle IPv6 fragments. When this keyword 1111 is present, the match is about assessing 1112 whether a packet is a fragment (that is, 1113 a Fragment header is present)."; 1114 } 1115 description 1116 "Rule set that matches IPv6 header."; 1117 } 1118 description 1119 "Either IPv4 or IPv6."; 1120 } 1121 choice l4 { 1122 container tcp { 1123 uses packet-fields:acl-tcp-header-fields; 1124 uses ports; 1125 description 1126 "Rule set that matches TCP header."; 1127 } 1128 container udp { 1129 uses packet-fields:acl-udp-header-fields; 1130 uses ports; 1131 description 1132 "Rule set that matches UDP header."; 1133 } 1134 container icmp { 1135 uses packet-fields:acl-icmp-header-fields; 1136 description 1137 "Rule set that matches ICMP/ICMPv6 header."; 1138 } 1139 description 1140 "Can be TCP, UDP, or ICMP/ICMPv6"; 1141 } 1143 } 1144 container actions { 1145 description 1146 "Definitions of action for this ACE."; 1147 leaf forwarding { 1148 type identityref { 1149 base ietf-acl:forwarding-action; 1150 } 1151 mandatory true; 1152 description 1153 "Specifies the forwarding action per ACE."; 1154 reference 1155 "RFC ZZZZ: Network Access Control List (ACL) 1156 YANG Data Model"; 1157 } 1158 leaf rate-limit { 1159 when "../forwarding = 'ietf-acl:accept'" { 1160 description 1161 "rate-limit valid only when accept action is used"; 1162 } 1163 type decimal64 { 1164 fraction-digits 2; 1165 } 1166 description 1167 "rate-limit traffic"; 1168 } 1169 } 1170 container statistics { 1171 config false; 1172 description 1173 "Aggregate statistics."; 1174 uses ietf-acl:acl-counters; 1175 } 1176 } 1177 } 1178 } 1179 } 1181 container dots-data { 1182 description 1183 "Main container for DOTS data channel."; 1184 list dots-client { 1185 key "cuid"; 1186 description 1187 "List of DOTS clients."; 1188 leaf cuid { 1189 type string; 1190 description 1191 "A unique identifier that is randomly generated by 1192 a DOTS client to prevent request collisions."; 1193 reference 1194 "RFC YYYY: Distributed Denial-of-Service Open Threat 1195 Signaling (DOTS) Signal Channel Specification"; 1196 } 1197 leaf cdid { 1198 type string; 1199 description 1200 "A client domain identifier conveyed by a 1201 server-domain DOTS gateway to a remote DOTS server."; 1202 reference 1203 "RFC YYYY: Distributed Denial-of-Service Open Threat 1204 Signaling (DOTS) Signal Channel Specification"; 1205 } 1206 container aliases { 1207 description 1208 "Set of aliases that are bound to a DOTS client."; 1209 uses aliases; 1210 } 1211 container acls { 1212 description 1213 "Access lists that are bound to a DOTS client."; 1214 uses access-lists; 1215 } 1216 } 1217 container capabilities { 1218 config false; 1219 description 1220 "Match capabilities"; 1221 leaf-list address-family { 1222 type enumeration { 1223 enum "ipv4" { 1224 description 1225 "IPv4 is supported."; 1226 } 1227 enum "ipv6" { 1228 description 1229 "IPv6 is supported."; 1230 } 1231 } 1232 description 1233 "Indicates the IP address families supported by 1234 the DOTS server."; 1235 } 1236 leaf-list forwarding-actions { 1237 type identityref { 1238 base ietf-acl:forwarding-action; 1240 } 1241 description 1242 "Supported forwarding action(s)."; 1243 } 1244 leaf rate-limit { 1245 type boolean; 1246 description 1247 "Support of rate-limit action."; 1248 } 1249 leaf-list fragment { 1250 type enumeration { 1251 enum "unsupported" { 1252 description 1253 "No fragment support."; 1254 } 1255 enum "v4-fragment" { 1256 description 1257 "Filtering IPv4 fragments is supported."; 1258 } 1259 enum "v6-fragment" { 1260 description 1261 "Filtering IPv6 fragments is supported."; 1262 } 1263 } 1264 description 1265 "Indicates the capability of a DOTS server to 1266 enforce filters on fragments."; 1267 } 1268 leaf-list transport-protocols { 1269 type uint8; 1270 description 1271 "Upper-layer protocol associated with this mapping. 1273 Values are taken from the IANA protocol registry: 1274 https://www.iana.org/assignments/protocol-numbers/ 1275 protocol-numbers.xhtml 1277 For example, this field contains 6 (TCP) for a TCP 1278 mapping or 17 (UDP) for a UDP mapping."; 1279 } 1280 container ipv4 { 1281 description 1282 "Indicates IPv4 header fields that are supported to enforce 1283 ACLs."; 1284 leaf dscp { 1285 type boolean; 1286 description 1287 "Support of filtering based on DSCP."; 1289 } 1290 leaf ecn { 1291 type boolean; 1292 description 1293 "Support of filtering based on ECN."; 1294 } 1295 leaf length { 1296 type boolean; 1297 description 1298 "Support of filtering based on the Total Length."; 1299 } 1300 leaf ttl { 1301 type boolean; 1302 description 1303 "Support of filtering based on the TTL."; 1304 } 1305 leaf protocol { 1306 type boolean; 1307 description 1308 "Support of filtering based on protocol field."; 1309 } 1310 leaf ihl { 1311 type boolean; 1312 description 1313 "Support of filtering based on the Internet Header 1314 Length (IHL)."; 1315 } 1316 leaf flags { 1317 type boolean; 1318 description 1319 "Support of filtering based on the flags."; 1320 } 1321 leaf offset { 1322 type boolean; 1323 description 1324 "Support of filtering based on the fragment offset."; 1325 } 1326 leaf identification { 1327 type boolean; 1328 description 1329 "Support of filtering based on the fragment 1330 identification."; 1331 } 1332 leaf source-prefix { 1333 type boolean; 1334 description 1335 "Support of filtering based on the source prefix."; 1336 } 1337 leaf destination-prefix { 1338 type boolean; 1339 description 1340 "Support of filtering based on the destination prefix."; 1341 } 1342 } 1343 container ipv6 { 1344 description 1345 "Indicates IPv6 header fields that are supported to enforce 1346 ACLs."; 1347 leaf dscp { 1348 type boolean; 1349 description 1350 "Support of filtering based on DSCP."; 1351 } 1352 leaf ecn { 1353 type boolean; 1354 description 1355 "Support of filtering based on ECN."; 1356 } 1357 leaf flow-label { 1358 type boolean; 1359 description 1360 "Support of filtering based on the Flow label."; 1361 } 1362 leaf length { 1363 type boolean; 1364 description 1365 "Support of filtering based on the Payload Length."; 1366 } 1367 leaf protocol { 1368 type boolean; 1369 description 1370 "Support of filtering based on the Next Header field."; 1371 } 1372 leaf hoplimit { 1373 type boolean; 1374 description 1375 "Support of filtering based on the Hop Limit."; 1376 } 1377 leaf source-prefix { 1378 type boolean; 1379 description 1380 "Support of filtering based on the source prefix."; 1381 } 1382 leaf destination-prefix { 1383 type boolean; 1384 description 1385 "Support of filtering based on the destination prefix."; 1386 } 1387 } 1388 container tcp { 1389 description 1390 "Set of TCP fields that are supported by the DOTS server 1391 to enfoce filters."; 1392 leaf sequence-number { 1393 type boolean; 1394 description 1395 "Support of filtering based on the TCP sequence number."; 1396 } 1397 leaf acknowledgement-number { 1398 type boolean; 1399 description 1400 "Support of filtering based on the TCP acknowledgement 1401 number."; 1402 } 1403 leaf data-offset { 1404 type boolean; 1405 description 1406 "Support of filtering based on the TCP data-offset."; 1407 } 1408 leaf reserved { 1409 type boolean; 1410 description 1411 "Support of filtering based on the TCP reserved field."; 1412 } 1413 leaf flags { 1414 type boolean; 1415 description 1416 "Support of filtering based on the TCP flags."; 1417 } 1418 leaf window-size { 1419 type boolean; 1420 description 1421 "Support of filtering based on the TCP window size."; 1422 } 1423 leaf urgent-pointer { 1424 type boolean; 1425 description 1426 "Support of filtering based on the TCP urgent pointer."; 1427 } 1428 leaf options { 1429 type boolean; 1430 description 1431 "Support of filtering based on the TCP options."; 1432 } 1433 leaf source-port { 1434 type boolean; 1435 description 1436 "Support of filtering based on the source port number."; 1437 } 1438 leaf destination-port { 1439 type boolean; 1440 description 1441 "Support of filtering based on the destination port 1442 number."; 1443 } 1444 leaf port-range { 1445 type boolean; 1446 description 1447 "Support of filtering based on a port range."; 1448 } 1449 } 1450 container udp { 1451 description 1452 "Set of UDP fields that are supported by the DOTS server 1453 to enforce filters."; 1454 leaf length { 1455 type boolean; 1456 description 1457 "Support of filtering based on the UDP length."; 1458 } 1459 leaf source-port { 1460 type boolean; 1461 description 1462 "Support of filtering based on the source port number."; 1463 } 1464 leaf destination-port { 1465 type boolean; 1466 description 1467 "Support of filtering based on the destination port 1468 number."; 1469 } 1470 leaf port-range { 1471 type boolean; 1472 description 1473 "Support of filtering based on a port range."; 1474 } 1475 } 1476 container icmp { 1477 description 1478 "Set of ICMP/ICMPv6 fields that are supported by the DOTS 1479 server to enforce filters."; 1480 leaf type { 1481 type boolean; 1482 description 1483 "Support of filtering based on the ICMP/ICMPv6 type."; 1484 } 1485 leaf code { 1486 type boolean; 1487 description 1488 "Support of filtering based on the ICMP/ICMPv6 code."; 1489 } 1490 leaf rest-of-header { 1491 type boolean; 1492 description 1493 "Support of filtering based on the ICMP four-bytes 1494 field."; 1495 } 1496 } 1497 } 1498 } 1499 } 1500 1502 5. Managing DOTS Clients 1504 5.1. Registering DOTS Clients 1506 In order to make use of DOTS data channel, a DOTS client MUST 1507 register to its DOTS server(s) by creating a DOTS client ('dots- 1508 client') resource. To that aim, DOTS clients SHOULD send a POST 1509 request (shown in Figure 11). 1511 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1512 Host: {host}:{port} 1513 Content-Type: application/yang-data+json 1514 { 1515 "ietf-dots-data-channel:dots-client": [ 1516 { 1517 "cuid": "string" 1518 } 1519 ] 1520 } 1522 Figure 11: POST to Register 1524 The 'cuid' (client unique identifier) parameter is described below: 1526 cuid: A globally unique identifier that is meant to prevent 1527 collisions among DOTS clients. This attribute has the same 1528 meaning, syntax, and processing rules as the 'cuid' attribute 1529 defined in [I-D.ietf-dots-signal-channel]. 1531 DOTS clients MUST use the same 'cuid' for both signal and data 1532 channels. 1534 This is a mandatory attribute. 1536 In deployments where server-domain DOTS gateways are enabled, 1537 identity information about the origin source client domain SHOULD be 1538 supplied to the DOTS server. That information is meant to assist the 1539 DOTS server to enforce some policies. These policies can be enforced 1540 per-client, per-client domain, or both. Figure 12 shows an example 1541 of a request relayed by a server-domain DOTS gateway. 1543 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1544 Host: {host}:{port} 1545 Content-Type: application/yang-data+json 1546 { 1547 "ietf-dots-data-channel:dots-client": [ 1548 { 1549 "cuid": "string", 1550 "cdid": "string" 1551 } 1552 ] 1553 } 1555 Figure 12: POST to Register (DOTS Gateway) 1557 A server-domain DOTS gateway SHOULD add the following attribute: 1559 cdid: This attribute has the same meaning, syntax, and processing 1560 rules as the 'cdid' attribute defined in 1561 [I-D.ietf-dots-signal-channel]. 1563 In deployments where server-domain DOTS gateways are enabled, 1564 'cdid' does not need to be inserted when relaying DOTS methods to 1565 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1566 servers are responsible for maintaining the association between 1567 'cdid' and 'cuid' for policy enforcement purposes. 1569 This is an optional attribute. 1571 A request example to create a 'dots-client' resource is depicted in 1572 Figure 13. This request is relayed by a server-domain DOTS gateway 1573 as hinted by the presence of the 'cdid' attribute. 1575 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1576 Host: {host}:{port} 1577 Content-Type: application/yang-data+json 1578 { 1579 "ietf-dots-data-channel:dots-client": [ 1580 { 1581 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1582 "cdid": "7eeaf349529eb55ed50113" 1583 } 1584 ] 1585 } 1587 Figure 13: POST to Register (DOTS gateway) 1589 DOTS servers MUST limit the number of 'dots-client' resources to be 1590 created by the same DOTS client to 1 per request. Requests with 1591 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1592 To that aim, the DOTS server MUST rely on the same procedure to 1593 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1594 [I-D.ietf-dots-signal-channel]. 1596 The DOTS server indicates the result of processing the POST request 1597 using status-line codes. Status codes in the range "2xx" codes are 1598 success, "4xx" codes are some sort of invalid requests and "5xx" 1599 codes are returned if the DOTS server has erred or is incapable of 1600 accepting the creation of the 'dots-client' resource. In particular, 1602 o "201 Created" status-line is returned in the response, if the DOTS 1603 server has accepted the request. 1605 o "400 Bad Request" status-line is returned by the DOTS server, if 1606 the request does not include a 'cuid' parameter. The error-tag 1607 "missing-attribute" is used in this case. 1609 o "409 Conflict" status-line is returned to the requesting DOTS 1610 client, if the data resource already exists. The error-tag 1611 "resource-denied" is used in this case. 1613 Once a DOTS client registers itself to a DOTS server, it can 1614 create/delete/retrieve aliases (Section 6) and filtering rules 1615 (Section 7). 1617 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1618 register a DOTS client within the DOTS server. An example is shown 1619 in Figure 14. 1621 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1622 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1623 Host: {host}:{port} 1624 Content-Type: application/yang-data+json 1625 { 1626 "ietf-dots-data-channel:dots-client": [ 1627 { 1628 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1629 } 1630 ] 1631 } 1633 Figure 14: PUT to Register 1635 The DOTS gateway that inserted a 'cdid' in a PUT request, MUST strip 1636 the 'cdid' parameter in the corresponding response before forwarding 1637 the response to the DOTS client. 1639 5.2. Uregistering DOTS Clients 1641 A DOTS client de-registers from its DOTS server by deleting the 1642 'cuid' resource. Resources bound to this DOTS client will be deleted 1643 by the DOTS server. An example of de-register request is shown in 1644 Figure 15. 1646 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1647 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1648 Host: {host}:{port} 1650 Figure 15: De-register a DOTS Client 1652 6. Managing DOTS Aliases 1654 The following sub-sections define means for a DOTS client to create 1655 aliases (Section 6.1), retrieve one or a list of aliases 1656 (Section 6.2), and delete an alias (Section 6.3). 1658 6.1. Create Aliases 1660 A POST or PUT request is used by a DOTS client to create aliases, for 1661 resources for which a mitigation may be requested. Such aliases may 1662 be used in subsequent DOTS signal channel exchanges to refer more 1663 efficiently to the resources under attack. 1665 DOTS clients within the same domain can create different aliases for 1666 the same resource. 1668 The structure of POST requests used to create aliases is shown in 1669 Figure 16. 1671 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1672 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1673 Host: {host}:{port} 1674 Content-Type: application/yang-data+json 1675 { 1676 "ietf-dots-data-channel:aliases": { 1677 "alias": [ 1678 { 1679 "name": "string", 1680 "target-prefix": [ 1681 "string" 1682 ], 1683 "target-port-range": [ 1684 { 1685 "lower-port": integer, 1686 "upper-port": integer 1687 } 1688 ], 1689 "target-protocol": [ 1690 integer 1691 ], 1692 "target-fqdn": [ 1693 "string" 1694 ], 1695 "target-uri": [ 1696 "string" 1697 ] 1698 } 1699 ] 1700 } 1701 } 1703 Figure 16: POST to Create Aliases 1705 The parameters are described below: 1707 name: Name of the alias. 1709 This is a mandatory attribute. 1711 target-prefix: Prefixes are separated by commas. Prefixes are 1712 represented using Classless Inter-domain Routing (CIDR) notation 1713 [RFC4632]. As a reminder, the prefix length must be less than or 1714 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1716 The prefix list MUST NOT include broadcast, loopback, or multicast 1717 addresses. These addresses are considered as invalid values. In 1718 addition, the DOTS server MUST validate that these prefixes are 1719 within the scope of the DOTS client's domain. Other validation 1720 checks may be supported by DOTS servers. 1722 This is an optional attribute. 1724 target-port-range: A range of port numbers. 1726 The port range is defined by two bounds, a lower port number 1727 (lower-port) and an upper port number (upper-port). 1729 When only 'lower-port' is present, it represents a single port 1730 number. 1732 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1733 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1734 [RFC4340], the range of port numbers can be, for example, 1735 1024-65535. 1737 This is an optional attribute. 1739 target-protocol: A list of protocols. Values are taken from the 1740 IANA protocol registry [proto_numbers]. 1742 The value '0' has a special meaning for 'all protocols'. 1744 This is an optional attribute. 1746 target-fqdn: A list of Fully Qualified Domain Names (FQDNs). An 1747 FQDN is the full name of a resource, rather than just its 1748 hostname. For example, "venera" is a hostname, and 1749 "venera.isi.edu" is an FQDN [RFC1983]. 1751 How a name is passed to an underlying name resolution library is 1752 implementation- and deployment-specific. Nevertheless, once the 1753 name is resolved into one or multiple IP addresses, DOTS servers 1754 MUST apply the same validation checks as those for 'target- 1755 prefix'. 1757 This is an optional attribute. 1759 target-uri: A list of Uniform Resource Identifiers (URIs) 1760 [RFC3986]. 1762 The same validation checks used for 'target-fqdn' MUST be followed 1763 by DOTS servers to validate a target URI. 1765 This is an optional attribute. 1767 In POST requests, at least one of the 'target-prefix', 'target-fqdn', 1768 or 'target-uri' attributes MUST be present. DOTS agents can safely 1769 ignore Vendor-Specific parameters they don't understand. 1771 Figure 17 shows a POST request to create an alias called "https1" for 1772 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1773 listening on port number 443. 1775 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1776 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1777 Host: www.example.com 1778 Content-Type: application/yang-data+json 1779 { 1780 "ietf-dots-data-channel:aliases": { 1781 "alias": [ 1782 { 1783 "name": "https1", 1784 "target-protocol": [ 1785 6 1786 ], 1787 "target-prefix": [ 1788 "2001:db8:6401::1/128", 1789 "2001:db8:6401::2/128" 1790 ], 1791 "target-port-range": [ 1792 { 1793 "lower-port": 443 1794 } 1795 ] 1796 } 1797 ] 1798 } 1799 } 1801 Figure 17: Example of a POST to Create an Alias 1803 "201 Created" status-line MUST be returned in the response if the 1804 DOTS server has accepted the alias. 1806 "409 Conflict" status-line MUST be returned to the requesting DOTS 1807 client, if the request is conflicting with an existing alias name. 1808 The error-tag "resource-denied" is used in this case. 1810 If the request is missing a mandatory attribute or its contains an 1811 invalid or unknown parameter, "400 Bad Request" status-line MUST be 1812 returned by the DOTS server. The error-tag is set to "missing- 1813 attribute", "invalid-value", or "unknown-element" as a function of 1814 the encountered error. 1816 If the request is received via a server-domain DOTS gateway, but the 1817 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 1818 is expected to be supplied, the DOTS server MUST reply with "403 1819 Forbidden" status-line and the error-tag "access-denied". Upon 1820 receipt of this message, the DOTS client MUST register (Section 5). 1822 A DOTS client uses the PUT request to modify the aliases in the DOTS 1823 server. In particular, a DOTS client MUST update its alias entries 1824 upon change of the prefix indicated in the 'target-prefix'. 1826 A DOTS server MUST maintain an alias for at least 10080 minutes (1 1827 week). If no refresh request is seen from the DOTS client, the DOTS 1828 server removes expired entries. 1830 6.2. Retrieve Installed Aliases 1832 GET request is used to retrieve one or all installed aliases by a 1833 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 1834 'name' is included in the request, this is an indication that the 1835 request is about retrieving all aliases instantiated by the DOTS 1836 client. 1838 Figure 18 shows an example to retrieve all the aliases that were 1839 instantiated by the requesting DOTS client. The 'content' parameter 1840 and its permitted values are defined in Section 4.8.1 of [RFC8040]. 1842 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1843 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1844 /aliases?content=config HTTP/1.1 1845 Host: {host}:{port} 1846 Accept: application/yang-data+json 1848 Figure 18: GET to Retrieve All Installed Aliases 1850 Figure 19 shows an example of the response message body that includes 1851 all the aliases that are maintained by the DOTS server for the DOTS 1852 client identified by the 'cuid' parameter. 1854 { 1855 "ietf-dots-data-channel:aliases": { 1856 "alias": [ 1857 { 1858 "name": "Server1", 1859 "traffic-protocol": [ 1860 6 1861 ], 1862 "target-prefix": [ 1863 "2001:db8:6401::1/128", 1864 "2001:db8:6401::2/128" 1865 ], 1866 "target-port-range": [ 1867 { 1868 "lower-port": 443 1869 } 1870 ], 1871 "pending-lifetime": 3596 1872 }, 1873 { 1874 "name": "Server2", 1875 "target-protocol": [ 1876 6 1877 ], 1878 "target-prefix": [ 1879 "2001:db8:6401::10/128", 1880 "2001:db8:6401::20/128" 1881 ], 1882 "target-port-range": [ 1883 { 1884 "lower-port": 80 1885 } 1886 ], 1887 "pending-lifetime": 9869 1888 } 1889 ] 1890 } 1891 } 1893 Figure 19: An Example of Response Body 1895 Figure 20 shows an example of a GET request to retrieve the alias 1896 "Server2" that was instantiated by the DOTS client. 1898 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1899 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1900 /aliases/alias=Server2?content=config HTTP/1.1 1901 Host: {host}:{port} 1902 Accept: application/yang-data+json 1904 Figure 20: GET to Retrieve an Alias 1906 If an alias name ('name') is included in the request, but the DOTS 1907 server does not find that alias name for this DOTS client in its 1908 configuration data, it MUST respond with a "404 Not Found" status- 1909 line. 1911 6.3. Delete Aliases 1913 DELETE request is used to delete an alias maintained by a DOTS 1914 server. 1916 If the DOTS server does not find the alias name, conveyed in the 1917 DELETE request, in its configuration data for this DOTS client, it 1918 MUST respond with a "404 Not Found" status-line. 1920 The DOTS server successfully acknowledges a DOTS client's request to 1921 remove the alias using "204 No Content" status-line in the response. 1923 Figure 21 shows an example of a request to delete an alias. 1925 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1926 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1927 /aliases/alias=Server1 HTTP/1.1 1928 Host: {host}:{port} 1930 Figure 21: Delete an Alias 1932 7. Managing DOTS Filtering Rules 1934 The following sub-sections define means for a DOTS client to retrieve 1935 DOTS filtering capabilities (Section 7.1), create filtering rules 1936 (Section 7.2), retrieve active filtering rules (Section 7.3), and 1937 delete a filtering rule (Section 7.4). 1939 7.1. Retrieve DOTS Filtering Capabilities 1941 A DOTS client MAY send a GET request to retrieve the filtering 1942 capabilities supported by a DOTS server. Figure 22 shows an example 1943 of such request. 1945 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1946 /capabilities HTTP/1.1 1947 Host: {host}:{port} 1948 Accept: application/yang-data+json 1950 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 1952 A DOTS client which issued a GET request to retrieve the filtering 1953 capabilities supported by its, SHOULD NOT request for filtering 1954 actions that are not supported by that DOTS server. 1956 Figure 23 shows an example of a response received from a DOTS server 1957 which only supports the mandatory filtering criteria listed in 1958 Section 4.1. 1960 Content-Type: application/yang-data+json 1961 { 1962 "ietf-dots-data-channel:capabilities": { 1963 "address-family": ["ipv4", "ipv6"], 1964 "forwarding-actions": ["drop", "accept"], 1965 "rate-limit": "true", 1966 "fragment": ["v4-fragment", "v6-fragment"], 1967 "transport-protocols": [1, 6, 17, 58], 1968 "ipv4": { 1969 "length": "true", 1970 "protocol": "true", 1971 "destination-prefix": "true", 1972 "source-prefix": "true" 1973 }, 1974 "ipv6": { 1975 "length": "true", 1976 "protocol": "true", 1977 "destination-prefix": "true", 1978 "source-prefix": "true" 1979 }, 1980 "tcp": { 1981 "flags": "true", 1982 "source-port": "true", 1983 "destination-port": "true", 1984 "port-range": "true" 1985 }, 1986 "udp": { 1987 "length": "true", 1988 "source-port": "true", 1989 "destination-port": "true", 1990 "port-range": "true" 1991 }, 1992 "icmp": { 1993 "type": "true", 1994 "code": "true" 1995 } 1996 } 1997 } 1999 Figure 23: Reply to a GET Response with Filtering Capabilities 2001 7.2. Install Filtering Rules 2003 A POST or PUT request is used by a DOTS client to communicate 2004 filtering rules to a DOTS server. 2006 Figure 24 shows a POST request example to block traffic from 2007 192.0.2.0/24 and destined to 198.51.100.0/24. Other examples are 2008 discussed in Appendix A. 2010 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2011 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2012 Host: {host}:{port} 2013 Content-Type: application/yang-data+json 2014 { 2015 "ietf-dots-data-channel:acls": { 2016 "acl": [ 2017 { 2018 "name": "sample-ipv4-acl", 2019 "type": "ipv4-acl-type", 2020 "activation-type": "activate-when-mitigating", 2021 "aces": { 2022 "ace": [ 2023 { 2024 "name": "rule1", 2025 "matches": { 2026 "ipv4": { 2027 "destination-ipv4-network": "198.51.100.0/24", 2028 "source-ipv4-network": "192.0.2.0/24" 2029 } 2030 }, 2031 "actions": { 2032 "forwarding": "drop" 2033 } 2034 } 2035 ] 2036 } 2037 } 2038 ] 2039 } 2040 } 2042 Figure 24: POST to Install Filtering Rules 2044 The meaning of these parameters is as follows: 2046 name: The name of the access list. 2048 This is a mandatory attribute. 2050 type: Indicates the primary intended type of match criteria (e.g., 2051 IPv4, IPv6). It is set to 'ipv4-acl-type' in this example. 2053 This is an optional attribute. 2055 activation-type: Indicates whether an ACL has to be installed 2056 immediately or during mitigation time. If this attribute is not 2057 provided, the DOTS server MUST use 'activate-when-mitigating' as 2058 default value. Filters that are activated only when a mitigation 2059 is in progress MUST be bound to the DOTS client which created the 2060 filtering rule. 2062 This is an optional attribute. 2064 matches: Define criteria used to identify a flow on which to apply 2065 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2066 The detailed match parameters are specified in Section 4. 2068 In this example, an IPv4 matching criteria is used. 2070 This is an optional attribute. 2072 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2073 MUST validate that these prefixes are within the scope of the DOTS 2074 client's domain. Other validation checks may be supported by DOTS 2075 servers. If this attribute is not provided, the DOTS server 2076 enforces the ACL on any destination IP address that belong to the 2077 DOTS client's domain. 2079 This is a mandatory attribute in requests with an 'activation- 2080 type' set to 'immediate'. 2082 source-ipv4-network: The source IPv4 prefix. 2084 This is an optional attribute. 2086 actions: Actions in the forwarding ACL category can be "drop" or 2087 "accept". The "accept" action is used to white-list traffic. The 2088 "drop" action is used to black-list traffic. 2090 Accepted traffic may be subject to "rate-limit"; the allowed 2091 traffic rate is represented in bytes per second indicated in IEEE 2092 floating point format [IEEE.754.1985]. 2094 This is a mandatory attribute. 2096 The DOTS server indicates the result of processing the POST request 2097 using the status-line header. Concretely, "201 Created" status-line 2098 MUST be returned in the response if the DOTS server has accepted the 2099 filtering rules. If the request is missing a mandatory attribute or 2100 contains an invalid or unknown parameter (e.g., a match field not 2101 supported by the DOTS server), "400 Bad Request" status-line MUST be 2102 returned by the DOTS server in the response. The error-tag is set to 2103 "missing-attribute", "invalid-value", or "unknown-element" as a 2104 function of the encountered error. 2106 If the request is received via a server-domain DOTS gateway, but the 2107 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2108 is expected to be supplied, the DOTS server MUST reply with "403 2109 Forbidden" status-line and the error-tag "access-denied". Upon 2110 receipt of this message, the DOTS client MUST register (Figure 11). 2112 If the request is conflicting with an existing filtering installed by 2113 another DOTS client of the domain, the DOTS server returns "409 2114 Conflict" status-line to the requesting DOTS client. The error-tag 2115 "resource-denied" is used in this case. 2117 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2118 to specify how an access control entry is inserted within an ACL and 2119 how an ACL is inserted within an ACL set. 2121 The DOTS client uses the PUT request to modify its filtering rules 2122 maintained by the DOTS server. In particular, a DOTS client MUST 2123 update its filtering entries upon change of the destination-prefix. 2124 How such change is detected is out of scope. 2126 A DOTS server MUST maintain a filtering rule for at least 10080 2127 minutes (1 week). If no refresh request is seen from the DOTS 2128 client, the DOTS server removes expired entries. 2130 7.3. Retrieve Installed Filtering Rules 2132 The DOTS client periodically queries the DOTS server to check the 2133 counters for installed filtering rules. GET request is used to 2134 retrieve filtering rules from a DOTS server. 2136 If the DOTS server does not find the access list name conveyed in the 2137 GET request in its configuration data for this DOTS client, it 2138 responds with a "404 Not Found" status-line. 2140 Figure 25 shows how to retrieve all the filtering rules that were 2141 instantiated by the DOTS client and the number of matches for the 2142 installed filtering rules. 2144 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2145 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2146 /acls?content=all HTTP/1.1 2147 Host: {host}:{port} 2148 Accept: application/yang-data+json 2150 Figure 25: GET to Retrieve the Configuration Data and State Data for 2151 the Filtering Rules 2153 Figure 26 shows how to retrieve "sample-ipv6-acl" filtering rule 2154 instantiated by the DOTS client, having 2155 "cuid=dz6pHjaADkaFTbjr0JGBpw", and the number of matches for the 2156 installed filtering rules. 2158 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2159 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2160 /acl=sample-ipv6-acl?content=all HTTP/1.1 2161 Host: {host}:{port} 2162 Accept: application/yang-data+json 2164 Figure 26: GET to Retrieve the Configuration Data and State Data for 2165 a Filtering Rule 2167 7.4. Remove Filtering Rules 2169 DELETE request is used by a DOTS client to delete filtering rules 2170 from a DOTS server. 2172 If the DOTS server does not find the access list name carried in the 2173 DELETE request in its configuration data for this DOTS client, it 2174 MUST respond with a "404 Not Found" status-line. The DOTS server 2175 successfully acknowledges a DOTS client's request to withdraw the 2176 filtering rules using "204 No Content" status-line, and removes the 2177 filtering rules accordingly. 2179 Figure 27 shows an example of a request to remove the IPv4 ACL named 2180 "sample-ipv4-acl". 2182 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2183 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2184 /acl=sample-ipv4-acl HTTP/1.1 2185 Host: {host}:{port} 2187 Figure 27: DELETE to Remove a Filtering Rule 2189 8. IANA Considerations 2191 This document requests IANA to register the following URI in the 2192 "IETF XML Registry" [RFC3688]: 2194 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2195 Registrant Contact: The IESG. 2196 XML: N/A; the requested URI is an XML namespace. 2198 This document requests IANA to register the following YANG module in 2199 the "YANG Module Names" registry [RFC7950]. 2201 name: ietf-dots-data-channel 2202 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2203 prefix: data-channel 2204 reference: RFC XXXX 2206 9. Contributors 2208 The following individuals have contributed to this document: 2210 o Dan Wing, Email: dwing-ietf@fuggles.com 2212 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 2214 10. Security Considerations 2216 RESTCONF security considerations are discussed in [RFC8040]. In 2217 particular, DOTS agents MUST follow the security recommendations in 2218 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2219 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2220 [I-D.ietf-dots-signal-channel]. YANG ACL-specific security 2221 considerations are discussed in [I-D.ietf-netmod-acl-model]. 2223 Authenticated encryption MUST be used for data confidentiality and 2224 message integrity. The interaction between the DOTS agents requires 2225 Transport Layer Security (TLS) with a cipher suite offering 2226 confidentiality protection and the guidance given in [RFC7525] MUST 2227 be followed to avoid attacks on TLS. 2229 An attacker may be able to inject RST packets, bogus application 2230 segments, etc., regardless of whether TLS authentication is used. 2231 Because the application data is TLS protected, this will not result 2232 in the application receiving bogus data, but it will constitute a DoS 2233 on the connection. This attack can be countered by using TCP-AO 2234 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2235 attacker will be rejected by the TCP-AO integrity check and therefore 2236 will never reach the TLS layer. 2238 In order to prevent leaking internal information outside a client- 2239 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2240 internal DOTS clients (e.g., source IP address, client's hostname) 2241 unless explicitly configured to do so. 2243 DOTS servers MUST verify that requesting DOTS clients are entitled to 2244 enforce filtering rules on a given IP prefix. That is, only 2245 filtering rules on IP resources that belong to the DOTS client's 2246 domain MUST be authorized by a DOTS server. The exact mechanism for 2247 the DOTS servers to validate that the target prefixes are within the 2248 scope of the DOTS client's domain is deployment-specific. 2250 Rate-limiting DOTS requests, including those with new 'cuid' values, 2251 from the same DOTS client defends against DoS attacks that would 2252 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 2253 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 2254 DOTS servers. 2256 Applying resources quota per DOTS client and/or per DOTS client 2257 domain (e.g., limit the number of aliases and filters to be install 2258 by DOTS clients) prevents DOTS server resources to be aggressively 2259 used by some DOTS clients and ensures, therefore, DDoS mitigation 2260 usage fairness. Additionally, DOTS servers may limit the number of 2261 DOTS clients that can be enabled per domain. 2263 All data nodes defined in the YANG module which can be created, 2264 modified, and deleted (i.e., config true, which is the default) are 2265 considered sensitive. Write operations applied to these data nodes 2266 without proper protection can negatively affect network operations. 2267 Appropriate security measures are recommended to prevent illegitimate 2268 users from invoking DOTS data channel primitives. Nevertheless, an 2269 attacker who can access a DOTS client is technically capable of 2270 launching various attacks, such as: 2272 o Set an arbitrarily low rate-limit, which may prevent legitimate 2273 traffic from being forwarded (rate-limit). 2275 o Set an arbitrarily high rate-limit, which may lead to the 2276 forwarding of illegitimate DDoS traffic (rate-limit). 2278 o Communicate invalid aliases to the server (alias), which will 2279 cause the failure of associating both data and signal channels. 2281 o Set invalid ACL entries, which may prevent legitimate traffic from 2282 being forwarded. Likewise, invalid ACL entries may lead to 2283 forward DDoS traffic. 2285 11. Acknowledgements 2287 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2288 Doron, Russ White, Gilbert Clark, and Nesredien Suleiman for the 2289 discussion and comments. 2291 12. References 2293 12.1. Normative References 2295 [I-D.ietf-dots-signal-channel] 2296 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 2297 Teague, "Distributed Denial-of-Service Open Threat 2298 Signaling (DOTS) Signal Channel Specification", draft- 2299 ietf-dots-signal-channel-19 (work in progress), April 2300 2018. 2302 [I-D.ietf-netmod-acl-model] 2303 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 2304 "Network Access Control List (ACL) YANG Data Model", 2305 draft-ietf-netmod-acl-model-18 (work in progress), March 2306 2018. 2308 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2309 Requirement Levels", BCP 14, RFC 2119, 2310 DOI 10.17487/RFC2119, March 1997, 2311 . 2313 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2314 DOI 10.17487/RFC3688, January 2004, 2315 . 2317 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2318 (CIDR): The Internet Address Assignment and Aggregation 2319 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2320 2006, . 2322 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2323 (TLS) Protocol Version 1.2", RFC 5246, 2324 DOI 10.17487/RFC5246, August 2008, 2325 . 2327 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2328 Protocol (HTTP/1.1): Message Syntax and Routing", 2329 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2330 . 2332 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2333 "Recommendations for Secure Use of Transport Layer 2334 Security (TLS) and Datagram Transport Layer Security 2335 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2336 2015, . 2338 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2339 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2340 . 2342 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2343 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2344 . 2346 12.2. Informative References 2348 [I-D.ietf-dots-architecture] 2349 Mortensen, A., Andreasen, F., Reddy, T., 2350 christopher_gray3@cable.comcast.com, c., Compton, R., and 2351 N. Teague, "Distributed-Denial-of-Service Open Threat 2352 Signaling (DOTS) Architecture", draft-ietf-dots- 2353 architecture-06 (work in progress), March 2018. 2355 [I-D.ietf-dots-requirements] 2356 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 2357 Denial of Service (DDoS) Open Threat Signaling 2358 Requirements", draft-ietf-dots-requirements-14 (work in 2359 progress), February 2018. 2361 [IEEE.754.1985] 2362 Institute of Electrical and Electronics Engineers, 2363 "Standard for Binary Floating-Point Arithmetic", August 2364 1985. 2366 [proto_numbers] 2367 "IANA, "Protocol Numbers"", 2011, 2368 . 2370 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 2371 RFC 1983, DOI 10.17487/RFC1983, August 1996, 2372 . 2374 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2375 Resource Identifier (URI): Generic Syntax", STD 66, 2376 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2377 . 2379 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2380 Congestion Control Protocol (DCCP)", RFC 4340, 2381 DOI 10.17487/RFC4340, March 2006, 2382 . 2384 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2385 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2386 . 2388 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2389 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2390 DOI 10.17487/RFC5389, October 2008, 2391 . 2393 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2394 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2395 June 2010, . 2397 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2398 Layer Security (TLS) and Datagram Transport Layer Security 2399 (DTLS) Heartbeat Extension", RFC 6520, 2400 DOI 10.17487/RFC6520, February 2012, 2401 . 2403 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 2404 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 2405 DOI 10.17487/RFC6887, April 2013, 2406 . 2408 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2409 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2410 . 2412 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2413 Interchange Format", STD 90, RFC 8259, 2414 DOI 10.17487/RFC8259, December 2017, 2415 . 2417 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2418 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2419 . 2421 Appendix A. Sample Examples: Filtering Fragments 2423 Figure 28 shows a POST request example issued by a DOTS client to its 2424 DOTS server to allow the traffic destined to 198.51.100.0/24 and UDP 2425 port number 53, but to drop all fragmented packets. The following 2426 ACEs are defined (in this order): 2428 o "drop-all-except-last-fragment" ACE: discards all fragments, 2429 except the last fragment. 2431 o "allow-dns-packets" ACE: accepts DNS packets destined to 2432 198.51.100.0/24. 2434 o "drop-last-fragment" ACE: drops the last fragment. 2436 The ACEs order is important to appropriately enforce the intended 2437 filtering policy. For example, if the ACEs order is "allow-dns- 2438 packets" ACE, "drop-all-except-last-fragment" ACE, and then "drop- 2439 last-fragment" ACE, the first fragment won't be dropped because it 2440 includes both L3 and L4 information and will therefore match the 2441 "allow-dns-packets" ACE. 2443 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2444 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2445 Host: {host}:{port} 2446 Content-Type: application/yang-data+json 2447 { 2448 "ietf-dots-data-channel:acls": { 2449 "acl": [ 2450 { 2451 "name": "dns-fragments", 2452 "type": "ipv4-acl-type", 2453 "aces": { 2454 "ace": [ 2455 { 2456 "name": "drop-all-except-last-fragment", 2457 "matches": { 2458 "ipv4": { 2459 "flags": { 2460 "more": 1 2461 } 2462 } 2463 }, 2464 "actions": { 2465 "forwarding": "drop" 2466 } 2467 } 2468 ] 2469 "ace": [ 2470 { 2471 "name": "allow-dns-packets", 2472 "matches": { 2473 "ipv4": { 2474 "destination-ipv4-network": "198.51.100.0/24" 2475 } 2476 "udp": { 2477 "destination-port": { 2478 "operator": "eq", 2479 "port": 53 2480 } 2481 }, 2482 "actions": { 2483 "forwarding": "accept" 2484 } 2485 } 2486 ] 2487 "ace": [ 2488 { 2489 "name": "drop-last-fragment", 2490 "matches": { 2491 "ipv4": { 2492 "flags": { 2493 "more": 0 2494 } 2495 } 2496 }, 2497 "actions": { 2498 "forwarding": "drop" 2499 } 2500 } 2501 ] 2502 } 2503 } 2504 ] 2505 } 2506 } 2508 Figure 28: Filtering IPv4 Fragmented Packets 2510 Figure 29 shows a POST request example issued by a DOTS client to its 2511 DOTS server to allow the traffic destined to 2001:db8::/32 and UDP 2512 port number 53, but to drop all fragmented packets. The following 2513 ACEs are defined (in this order): 2515 o "drop-all-fragments" ACE: discards all fragments (including atomic 2516 fragments). That is, IPv6 packets which include a Fragment header 2517 (44) are dropped. 2519 o "allow-dns-packets" ACE: accepts DNS packets destined to 2520 2001:db8::/32. 2522 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2523 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2525 Host: {host}:{port} 2526 Content-Type: application/yang-data+json 2527 { 2528 "ietf-dots-data-channel:acls": { 2529 "acl": [ 2530 { 2531 "name": "dns-fragments", 2532 "type": "ipv6-acl-type", 2533 "aces": { 2534 "ace": [ 2535 { 2536 "name": "drop-all-fragments", 2537 "matches": { 2538 "ipv6": { 2539 "fragment" 2540 } 2541 }, 2542 "actions": { 2543 "forwarding": "drop" 2544 } 2545 } 2546 ] 2547 "ace": [ 2548 { 2549 "name": "allow-dns-packets", 2550 "matches": { 2551 "ipv6": { 2552 "destination-ipv6-network": "2001:db8::/32" 2553 } 2554 "udp": { 2555 "destination-port": { 2556 "operator": "eq", 2557 "port": 53 2558 } 2559 } 2560 }, 2561 "actions": { 2562 "forwarding": "accept" 2563 } 2564 } 2565 ] 2566 } 2567 } 2568 ] 2569 } 2570 } 2572 Figure 29: Filtering IPv6 Fragmented Packets 2574 Authors' Addresses 2576 Tirumaleswar Reddy (editor) 2577 McAfee, Inc. 2578 Embassy Golf Link Business Park 2579 Bangalore, Karnataka 560071 2580 India 2582 Email: kondtir@gmail.com 2584 Mohamed Boucadair (editor) 2585 Orange 2586 Rennes 35000 2587 France 2589 Email: mohamed.boucadair@orange.com 2591 Kaname Nishizuka 2592 NTT Communications 2593 GranPark 16F 3-4-1 Shibaura, Minato-ku 2594 Tokyo 108-8118 2595 Japan 2597 Email: kaname@nttv6.jp 2599 Liang Xia 2600 Huawei 2601 101 Software Avenue, Yuhuatai District 2602 Nanjing, Jiangsu 210012 2603 China 2605 Email: frank.xialiang@huawei.com 2607 Prashanth Patil 2608 Cisco Systems, Inc. 2610 Email: praspati@cisco.com 2611 Andrew Mortensen 2612 Arbor Networks, Inc. 2613 2727 S. State St 2614 Ann Arbor, MI 48104 2615 United States 2617 Email: amortensen@arbor.net 2619 Nik Teague 2620 Verisign, Inc. 2621 United States 2623 Email: nteague@verisign.com