idnits 2.17.1 draft-ietf-dots-data-channel-14.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 23 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 458 has weird spacing: '...er-port ine...' == Line 459 has weird spacing: '...er-port ine...' == Line 541 has weird spacing: '...warding ide...' == Line 858 has weird spacing: '... icmp typ...' -- The document date (March 29, 2018) is 2220 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 2009 -- Looks like a reference, but probably isn't: '6' on line 2009 -- Looks like a reference, but probably isn't: '17' on line 2009 -- Looks like a reference, but probably isn't: '58' on line 2009 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-18 == 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) -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 5 errors (**), 0 flaws (~~), 9 warnings (==), 8 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: September 30, 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 March 29, 2018 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 Specification 20 draft-ietf-dots-data-channel-14 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 September 30, 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 . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . 38 107 6.1. Create Aliases . . . . . . . . . . . . . . . . . . . . . 38 108 6.2. Retrieve Installed Aliases . . . . . . . . . . . . . . . 42 109 6.3. Delete Aliases . . . . . . . . . . . . . . . . . . . . . 44 110 7. Managing DOTS Filtering Rules . . . . . . . . . . . . . . . . 44 111 7.1. Retrieve DOTS Filtering Capabilities . . . . . . . . . . 44 112 7.2. Install Filtering Rules . . . . . . . . . . . . . . . . . 46 113 7.3. Retrieve Installed Filtering Rules . . . . . . . . . . . 49 114 7.4. Remove Filtering Rules . . . . . . . . . . . . . . . . . 50 115 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 116 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 51 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 51 118 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 52 119 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 52 120 12.1. Normative References . . . . . . . . . . . . . . . . . . 52 121 12.2. Informative References . . . . . . . . . . . . . . . . . 54 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 124 1. Introduction 126 A distributed denial-of-service (DDoS) attack is an attempt to make 127 machines or network resources unavailable to their intended users. 128 In most cases, sufficient scale can be achieved by compromising 129 enough end-hosts and using those infected hosts to perpetrate and 130 amplify the attack. The victim of such attack can be an application 131 server, a router, a firewall, an entire network, etc. 133 As discussed in [I-D.ietf-dots-requirements], the lack of a common 134 method to coordinate a real-time response among involved actors and 135 network domains inhibits the speed and effectiveness of DDoS attack 136 mitigation. From that standpoint, DDoS Open Threat Signaling (DOTS) 137 defines an architecture that allows a DOTS client to send requests to 138 a DOTS server for DDoS attack mitigation 139 [I-D.ietf-dots-architecture]. The DOTS approach is thus meant to 140 minimize the impact of DDoS attacks, thereby contributing to the 141 enforcement of more efficient defensive if not proactive security 142 strategies. To that aim, DOTS defines two channels: the signal and 143 the data channels (Figure 1). 145 +---------------+ +---------------+ 146 | | <------- Signal Channel ------> | | 147 | DOTS Client | | DOTS Server | 148 | | <======= Data Channel ======> | | 149 +---------------+ +---------------+ 151 Figure 1: DOTS Channels 153 The DOTS signal channel is used to carry information about a device 154 or a network (or a part thereof) that is under a DDoS attack. Such 155 information is sent by a DOTS client to an upstream DOTS server so 156 that appropriate mitigation actions are undertaken on traffic deemed 157 suspicious. The DOTS signal channel is further elaborated in 158 [I-D.ietf-dots-signal-channel]. 160 As for the DOTS data channel, it is used for infrequent bulk data 161 exchange between DOTS agents to significantly improve the 162 coordination of all the parties involved in the response to the 163 attack. Section 2 of [I-D.ietf-dots-architecture] mentions that the 164 DOTS data channel is used to perform the following tasks: 166 o Creating aliases for resources for which mitigation may be 167 requested. 169 A DOTS client may submit to its DOTS server a collection of 170 prefixes which it would like to refer to by an alias when 171 requesting mitigation. The DOTS server can respond to this 172 request with either a success or failure response (see Section 2 173 in [I-D.ietf-dots-architecture]). 175 Refer to Section 6 for more details. 177 o Filter management, which enables a DOTS client to request the 178 installation or withdrawal of traffic filters, dropping or rate- 179 limiting unwanted traffic, and permitting white-listed traffic. A 180 DOTS client is entitled to instruct filtering rules only on IP 181 resources that belong to its domain. 183 Sample use cases for populating black- or white-list filtering 184 rules are detailed hereafter: 186 * If a network resource (DOTS client) detects a potential DDoS 187 attack from a set of IP addresses, the DOTS client informs its 188 servicing DOTS gateway of all suspect IP addresses that need to 189 be blocked or black-listed for further investigation. The DOTS 190 client could also specify a list of protocols and port numbers 191 in the black-list rule. 193 The DOTS gateway then propagates the black-listed IP addresses 194 to a DOTS server which will undertake appropriate actions so 195 that traffic originated by these IP addresses to the target 196 network (specified by the DOTS client) is blocked. 198 * A network, that has partner sites from which only legitimate 199 traffic arrives, may want to ensure that the traffic from these 200 sites is not subjected to DDoS attack mitigation. The DOTS 201 client uses the DOTS data channel to convey the white-listed IP 202 prefixes of the partner sites to its DOTS server. 204 The DOTS server uses this information to white-list flows 205 originated by such IP prefixes and which reach the network. 207 Refer to Section 7 for more details. 209 2. Terminology 211 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 212 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 213 document are to be interpreted as described in [RFC2119]. 215 The reader should be familiar with the terms defined in 216 [I-D.ietf-dots-requirements]. 218 The terminology for describing YANG data modules is defined in 219 [RFC7950]. The meaning of the symbols in tree diagrams is defined in 220 [RFC8340]. 222 This document generalizes the notion of Access Control List (ACL) so 223 that it is not device-specific [I-D.ietf-netmod-acl-model]. As such, 224 this document defines an ACL as an ordered set of rules that is used 225 to filter traffic. Each rule is represented by an Access Control 226 Entry (ACE). ACLs communicated via the DOTS data channel are not 227 bound to a device interface. 229 For the sake of simplicity, all of the examples in this document use 230 "/restconf" as the discovered RESTCONF API root path. Many protocol 231 header lines and message-body text within examples throughout the 232 document are split into multiple lines for display purposes only. 233 When a line ends with backslash ('\') as the last character, the line 234 is wrapped for display purposes. It is to be considered to be joined 235 to the next line by deleting the backslash, the following line break, 236 and the leading whitespace of the next line. 238 3. DOTS Data Channel 240 3.1. Design Overview 242 Unlike the DOTS signal channel, which must remain operational even 243 when confronted with signal degradation due to packets loss, the DOTS 244 data channel is not expected to be fully operational at all times, 245 especially when a DDoS attack is underway. The requirements for a 246 DOTS data channel protocol are documented in 247 [I-D.ietf-dots-requirements]. 249 This specification does not require an order of DOTS signal and data 250 channel creations nor mandates a time interval between them. These 251 considerations are implementation- and deployment-specific. 253 As the primary function of the data channel is data exchange, a 254 reliable transport mode is required in order for DOTS agents to 255 detect data delivery success or failure. This document uses RESTCONF 256 [RFC8040] over TLS [RFC5246] over TCP as the DOTS data channel 257 protocol. The abstract layering of DOTS data channel is shown in 258 Figure 2. 260 +-------------------+ 261 | DOTS Data Channel | 262 +-------------------+ 263 | RESTCONF | 264 +-------------------+ 265 | TLS | 266 +-------------------+ 267 | TCP | 268 +-------------------+ 269 | IP | 270 +-------------------+ 272 Figure 2: Abstract Layering of DOTS Data Channel 274 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 275 resources represented by DOTS data channel YANG data modules. These 276 basic edit operations allow the DOTS data channel running 277 configuration to be altered by a DOTS client. 279 DOTS data channel configuration information as well as state 280 information can be retrieved with the GET method. An HTTP status- 281 line header field is returned for each request to report success or 282 failure for RESTCONF operations (Section 5.4 of [RFC8040]). The 283 "error-tag" provides more information about encountered errors 284 (Section 7 of [RFC8040]). 286 DOTS clients perform the root resource discovery procedure discussed 287 in Section 3.1 of [RFC8040] to determine the root of the RESTCONF 288 API. After discovering the RESTCONF API root, a DOTS client uses 289 this value as the initial part of the path in the request URI, in any 290 subsequent request to the DOTS server. The DOTS server may support 291 the retrieval of the YANG modules it supports (Section 3.7 in 292 [RFC8040]). For example, a DOTS client may use RESTCONF to retrieve 293 the vendor-specific YANG modules supported by its DOTS server. 295 JavaScript Object Notation (JSON) [RFC7159] payload is used to 296 propagate the DOTS data channel specific payload messages that carry 297 request parameters and response information, such as errors. This 298 specification uses the encoding rules defined in [RFC7951] for 299 representing DOTS data channel configuration data using YANG 300 (Section 4) as JSON text. 302 A DOTS client registers itself to its DOTS server(s) in order to set 303 up DOTS data channel-related configuration data and receive state 304 data (i.e., non-configuration data) from the DOTS server(s) 305 (Section 5). Mutual authentication and coupling of signal and data 306 channels are specified in [I-D.ietf-dots-signal-channel]. 308 A single DOTS data channel between DOTS agents can be used to 309 exchange multiple requests and multiple responses. To reduce DOTS 310 client and DOTS server workload, DOTS clients SHOULD re-use the same 311 TLS session. While the communication to the DOTS server is 312 quiescent, the DOTS client MAY probe the server to ensure it has 313 maintained cryptographic state. Such probes can also keep alive 314 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies 315 that the DOTS server still has TLS state by returning a TLS message. 317 How filtering rules instantiated on a DOTS server are translated into 318 network configurations actions is out of scope. 320 3.2. DOTS Server(s) Discovery 322 This document assumes that DOTS clients are provisioned with the 323 reachability information of their DOTS server(s) using a variety of 324 means (e.g., local configuration, or dynamic means such as DHCP). 325 The specification of such means are out of scope of this document. 327 Likewise, it is out of scope of this document to specify the behavior 328 to follow by a DOTS client to place its requests (e.g., contact all 329 servers, select one server among the list) when multiple DOTS servers 330 are provisioned. 332 3.3. NAT Considerations 334 In deployments where one or more translators (e.g., NAT44, NAT64, 335 NPTv6) are enabled between the client's network and the DOTS server, 336 DOTS data channel messages forwarded to a DOTS server must not 337 include internal IP addresses/prefixes and/or port numbers; external 338 addresses/prefixes and/or port numbers as assigned by the translator 339 MUST be used instead. This document does not make any recommendation 340 about possible translator discovery mechanisms. The following are 341 some (non-exhaustive) deployment examples that may be considered: 343 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 344 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 345 external addresses/prefixes and/or port numbers. Information 346 retrieved by means of PCP or STUN will be used to feed the DOTS 347 data channel messages that will be sent to a DOTS server. 349 o A DOTS gateway may be co-located with the translator. The DOTS 350 gateway will need to update the DOTS messages, based upon the 351 local translator's binding table. 353 3.4. DOTS Gateways 355 When a server-domain DOTS gateway is involved in DOTS data channel 356 exchanges, the same considerations for manipulating the 'cdid' 357 (client domain identifier) parameter specified in 358 [I-D.ietf-dots-signal-channel] MUST be followed by DOTS agents. As a 359 reminder, 'cdid' is meant to assist the DOTS server to enforce some 360 policies (e.g., limit the number of filtering rules per DOTS client 361 or per DOTS client domain). A loop detect mechanism for DOTS 362 gateways is specified in Section 3.5. 364 If a DOTS gateway is involved, the DOTS gateway verifies that the 365 DOTS client is authorized to undertake a data channel action (e.g., 366 instantiate filtering rules). If the DOTS client is authorized, it 367 propagates the rules to the upstream DOTS server. Likewise, the DOTS 368 server verifies that the DOTS gateway is authorized to relay data 369 channel actions. For example, to create or purge filters, a DOTS 370 client sends its request to its DOTS gateway. The DOTS gateway 371 validates the rules in the request and proxies the requests 372 containing the filtering rules to its DOTS server. When the DOTS 373 gateway receives the associated response from the DOTS server, it 374 propagates the response back to the DOTS client. 376 A DOTS server may detect conflicting filtering requests from distinct 377 DOTS clients which belong to the same domain. For example, a DOTS 378 client could request to blacklist a prefix by specifying the source 379 prefix, while another DOTS client could request to whitelist that 380 same source prefix, but both having the same destination prefix. It 381 is out of scope of this specification to recommend the behavior to 382 follow for handling conflicting requests (e.g., reject all, reject 383 the new request, notify an administrator for validation). DOTS 384 servers SHOULD support a configuration parameter to indicate the 385 behavior to follow when a conflict is detected. Section 7.2 386 specifies the behavior when no instruction is supplied to a DOTS 387 server. 389 3.5. Detect and Prevent Infinite Loops 391 In order to detect and prevent infinite loops, DOTS gateways MUST 392 support the procedure defined in Section 5.7.1 of [RFC7230]. In 393 particular, each intermediate DOTS gateway MUST check that none of 394 its own information (e.g., server names, literal IP addresses) is 395 present in the "Via" header of a DOTS message it receives: 397 o If it detects that its own information is present in the "Via" 398 header, the DOTS gateway MUST NOT forward the DOTS message. 399 Messages that cannot be forwarded because of a loop SHOULD be 400 logged with a "508 Loop Detected" status-line returned sent back 401 to the DOTS peer. The structure of the reported error is depicted 402 in Figure 3. 404 error-tag: loop-detected 405 error-type: transport, application 406 error-severity: error 407 error-info: : A copy of the Via header when 408 the loop was detected. 409 Description: An infinite loop has been detected when forwarding 410 a requests via a proxy. 412 Figure 3: Loop Detected Error 414 It is RECOMMENDED that DOTS clients and gateways support means to 415 alert administrators about loop errors so that appropriate actions 416 are undertaken. 418 o Otherwise, the DOTS agent MUST update or insert the "Via" header 419 by appending its own information. 421 Unless configured otherwise, DOTS gateways at the boundaries of a 422 DOTS client domain SHOULD remove the previous "Via" header 423 information after checking for a loop before forwarding. This 424 behavior is required for topology hiding purposes but also to 425 minimizing potential conflicts that may arise if overlapping 426 information is used in distinct DOTS domains (e.g., private IPv4 427 addresses, non globally unique aliases). 429 3.6. Stale Entries 431 In order to avoid stale entries, a lifetime is associated with alias 432 and filtering entries created by DOTS clients. Also, DOTS servers 433 may track the inactivity timeout of DOTS clients to detect stale 434 entries. 436 4. DOTS Data Channel YANG Module 438 4.1. Tree Structure 440 The DOTS data channel YANG module (ietf-dots-data-channel) allows a 441 DOTS client to manage aliases for resources for which mitigation may 442 be requested. Such aliases may be used in subsequent DOTS signal 443 channel exchanges to refer more efficiently to the resources under 444 attack. 446 The tree structure for the DOTS alias is depicted in Figure 4. 448 module: ietf-dots-data-channel 449 +--rw dots-data 450 +--rw dots-client* [cuid] 451 | +--rw cuid string 452 | +--rw cdid? string 453 | +--rw aliases 454 | | +--rw alias* [name] 455 | | +--rw name string 456 | | +--rw target-prefix* inet:ip-prefix 457 | | +--rw target-port-range* [lower-port upper-port] 458 | | | +--rw lower-port inet:port-number 459 | | | +--rw upper-port inet:port-number 460 | | +--rw target-protocol* uint8 461 | | +--rw target-fqdn* inet:domain-name 462 | | +--rw target-uri* inet:uri 463 | | +--ro pending-lifetime? int32 464 | +--rw acls 465 | ... 466 +--ro capabilities 467 ... 469 Figure 4: DOTS Alias Subtree 471 Also, the 'ietf-dots-data-channel' module allows DOTS clients to 472 manage filtering rules. Examples of filtering management in a DOTS 473 context include, but not limited to: 475 o Black-list management, which enables a DOTS client to inform a 476 DOTS server about sources from which traffic should be discarded. 478 o White-list management, which enables a DOTS client to inform a 479 DOTS server about sources from which traffic should always be 480 accepted. 482 o Filter management, which enables a DOTS client to request the 483 installation or withdrawal of traffic filters, dropping or rate- 484 limiting unwanted traffic and permitting white-listed traffic. 486 The tree structure for the DOTS filtering entries is depicted in 487 Figure 5. 489 Early versions of this document investigated to what extent 490 augmenting 'ietf-access-control-list' meet DOTS requirements, but 491 that design approach was abandoned because it does not support 492 meeting many of DOTS requirements, e.g., 494 o Retrieve a filtering entry (or all entries) created by a DOTS 495 client. 497 o Delete a filtering entry that was instantiated by a DOTS client. 499 DOTS filtering entries (i.e., Access Control List (ACL)) mimic the 500 structure specified in [I-D.ietf-netmod-acl-model]. Concretely, DOTS 501 agents are assumed to manipulate an ordered list of ACLs; each ACL 502 contains a separately ordered list of Access Control Entries (ACEs). 503 Each ACE has a group of match and a group of action criteria. 505 Once all the ACE entries have been iterated though with no match, 506 then all the following ACL's ACE entries are iterated through until 507 the first match at which point the specified action is applied. If 508 there is no match, then there is no action to be taken against the 509 packet. 511 module: ietf-dots-data-channel 512 +--rw dots-data 513 +--rw dots-client* [cuid] 514 | +--rw cuid string 515 | +--rw cdid? string 516 | +--rw aliases 517 | | ... 518 | +--rw acls 519 | +--rw acl* [name] 520 | +--rw name string 521 | +--rw type? ietf-acl:acl-type 522 | +--rw activation-type? enumeration 523 | +--ro pending-lifetime? int32 524 | +--rw aces 525 | +--rw ace* [name] 526 | +--rw name string 527 | +--rw matches 528 | | +--rw (l3)? 529 | | | +--:(ipv4) 530 | | | ... 531 | | | +--:(ipv6) 532 | | | ... 533 | | +--rw (l4)? 534 | | +--:(tcp) 535 | | | ... 536 | | +--:(udp) 537 | | | ... 538 | | +--:(icmp) 539 | | ... 540 | +--rw actions 541 | | +--rw forwarding identityref 542 | | +--rw rate-limit? decimal64 543 | +--ro statistics 544 | +--ro matched-packets? yang:counter64 545 | +--ro matched-octets? yang:counter64 546 +--ro capabilities 547 ... 549 Figure 5: DOTS ACLs Subtree 551 Filtering rules instructed by a DOTS client assumes a default 552 direction: the destination is the DOTS client domain. 554 DOTS forwarding actions can be 'accept' (i.e., accept matching 555 traffic) or 'drop' (i.e., drop matching traffic without sending any 556 ICMP error message). Accepted traffic can be subject to rate 557 limiting 'rate-limit'. Note that 'reject' action (i.e., drop 558 matching traffic and send an ICMP error message to the source) is not 559 supported in 'ietf-dots-data-channel' because it is not appropriate 560 in the context of DDoS mitigation. Generating ICMP messages to 561 notify drops when mitigating a DDoS attack will exacerbate the DDoS 562 attack. Furthermore, these ICMP messages will be used by an attacker 563 as an explicit signal that the traffic is being blocked. 565 This document supports fragment filtering which adds an additional 566 layer of protection against a DoS attack that uses non-initial 567 fragments only. When there is only layer 3 information in the ACL 568 entry and the fragments keyword is present, for non-initial fragments 569 matching the ACE entry, the 'deny' or 'accept' action associated with 570 the ACE entry will be enforced. For initial or non-fragment matching 571 the ACE entry, the next ACE entry will be processed. When there is 572 both layer 3 and layer 4 information in the ACE entry and the 573 fragments keyword is present, the ACE action is conservative for both 574 'accept' and 'deny' actions. The actions are conservative to not 575 accidentally deny a fragmented portion of a flow because the 576 fragments do not contain sufficient information to match all of the 577 filter attributes. In the 'deny' action case, instead of denying a 578 non-initial fragment, the next ACE entry is processed. In the 579 'accept' case, it is assumed that the layer 4 information in the non- 580 initial fragment, if available, matches the layer 4 information in 581 the ACE entry. 583 4.2. Filtering Fields 585 The 'ietf-dots-data-channel' module reuses the packet fields module 586 'ietf-packet-fields' [I-D.ietf-netmod-acl-model] which defines 587 matching on fields in the packet including IPv4, IPv6, and transport 588 layer fields. 590 Figure 6 shows the IPv4 match subtree. 592 module: ietf-dots-data-channel 593 +--rw dots-data 594 +--rw dots-client* [cuid] 595 | ... 596 | +--rw acls 597 | +--rw acl* [name] 598 | ... 599 | +--rw aces 600 | +--rw ace* [name] 601 | +--rw name string 602 | +--rw matches 603 | | +--rw (l3)? 604 | | | +--:(ipv4) 605 | | | | +--rw ipv4 606 | | | | +--rw dscp? 607 | | | | | inet:dscp 608 | | | | +--rw ecn? 609 | | | | | uint8 610 | | | | +--rw length? 611 | | | | | uint16 612 | | | | +--rw ttl? 613 | | | | | uint8 614 | | | | +--rw protocol? 615 | | | | | uint8 616 | | | | +--rw ihl? 617 | | | | | uint8 618 | | | | +--rw flags? 619 | | | | | bits 620 | | | | +--rw offset? 621 | | | | | uint16 622 | | | | +--rw identification? 623 | | | | | uint16 624 | | | | +--rw (destination-network)? 625 | | | | | +--:(destination-ipv4-network) 626 | | | | | +--rw destination-ipv4-network? 627 | | | | | inet:ipv4-prefix 628 | | | | +--rw (source-network)? 629 | | | | | +--:(source-ipv4-network) 630 | | | | | +--rw source-ipv4-network? 631 | | | | | inet:ipv4-prefix 632 | | | | +--rw v4-fragments? 633 | | | | empty 634 | | | +--:(ipv6) 635 | | | ... 636 | | +--rw (l4)? 637 | | ... 638 | +--rw actions 639 | | ... 640 | +--ro statistics 641 | ... 642 +--ro capabilities 643 ... 645 Figure 6: DOTS ACLs Subtree (IPv4 Match) 647 Figure 7 shows the IPv6 match subtree. 649 module: ietf-dots-data-channel 650 +--rw dots-data 651 +--rw dots-client* [cuid] 652 | ... 653 | +--rw acls 654 | +--rw acl* [name] 655 | ... 656 | +--rw aces 657 | +--rw ace* [name] 658 | +--rw name string 659 | +--rw matches 660 | | +--rw (l3)? 661 | | | +--:(ipv4) 662 | | | | ... 663 | | | +--:(ipv6) 664 | | | +--rw ipv6 665 | | | +--rw dscp? 666 | | | | inet:dscp 667 | | | +--rw ecn? 668 | | | | uint8 669 | | | +--rw length? 670 | | | | uint16 671 | | | +--rw ttl? 672 | | | | uint8 673 | | | +--rw protocol? 674 | | | | uint8 675 | | | +--rw (destination-network)? 676 | | | | +--:(destination-ipv6-network) 677 | | | | +--rw destination-ipv6-network? 678 | | | | inet:ipv6-prefix 679 | | | +--rw (source-network)? 680 | | | | +--:(source-ipv6-network) 681 | | | | +--rw source-ipv6-network? 682 | | | | inet:ipv6-prefix 683 | | | +--rw flow-label? 684 | | | | inet:ipv6-flow-label 685 | | | +--rw v6-fragments? 686 | | | empty 687 | | +--rw (l4)? 688 | | ... 689 | +--rw actions 690 | | ... 691 | +--ro statistics 692 | ... 693 +--ro capabilities 694 ... 696 Figure 7: DOTS ACLs Subtree (IPv6 Match) 698 Figure 8 shows the TCP match subtree. 700 module: ietf-dots-data-channel 701 +--rw dots-data 702 +--rw dots-client* [cuid] 703 | ... 704 | +--rw acls 705 | +--rw acl* [name] 706 | ... 707 | +--rw aces 708 | +--rw ace* [name] 709 | +--rw name string 710 | +--rw matches 711 | | +--rw (l3)? 712 | | | ... 713 | | +--rw (l4)? 714 | | +--:(tcp) 715 | | | +--rw tcp 716 | | | +--rw sequence-number? 717 | | | | uint32 718 | | | +--rw acknowledgement-number? 719 | | | | uint32 720 | | | +--rw data-offset? 721 | | | | uint8 722 | | | +--rw reserved? 723 | | | | uint8 724 | | | +--rw flags? 725 | | | | bits 726 | | | +--rw window-size? 727 | | | | uint16 728 | | | +--rw urgent-pointer? 729 | | | | uint16 730 | | | +--rw options? 731 | | | | uint32 732 | | | +--rw (source-port)? 733 | | | | +--:(source-port-range-or-operator) 734 | | | | +--rw source-port-range-or-operator 735 | | | | +--rw (port-range-or-operator)? 736 | | | | +--:(range) 737 | | | | | +--rw lower-port 738 | | | | | | inet:port-number 739 | | | | | +--rw upper-port 740 | | | | | inet:port-number 741 | | | | +--:(operator) 742 | | | | +--rw operator? 743 | | | | | operator 744 | | | | +--rw port 745 | | | | inet:port-number 746 | | | +--rw (destination-port)? 747 | | | +--:(destination-port-range-or-operator) 748 | | | +--rw destination-port-range-or-operator 749 | | | +--rw (port-range-or-operator)? 750 | | | +--:(range) 751 | | | | +--rw lower-port 752 | | | | | inet:port-number 753 | | | | +--rw upper-port 754 | | | | inet:port-number 755 | | | +--:(operator) 756 | | | +--rw operator? 757 | | | | operator 758 | | | +--rw port 759 | | | inet:port-number 760 | | +--:(udp) 761 | | | ... 762 | | +--:(icmp) 763 | | ... 764 | +--rw actions 765 | | ... 766 | +--ro statistics 767 | ... 768 +--ro capabilities 769 ... 771 Figure 8: DOTS ACLs Subtree (TCP Match) 773 Figure 9 shows the UDP and ICMP match subtree. 775 module: ietf-dots-data-channel 776 +--rw dots-data 777 +--rw dots-client* [cuid] 778 | ... 779 | +--rw acls 780 | +--rw acl* [name] 781 | ... 782 | +--rw aces 783 | +--rw ace* [name] 784 | +--rw name string 785 | +--rw matches 786 | | +--rw (l3)? 787 | | | ... 788 | | +--rw (l4)? 789 | | +--:(tcp) 790 | | | ... 791 | | +--:(udp) 792 | | | +--rw udp 793 | | | +--rw length? 794 | | | | uint16 795 | | | +--rw (source-port)? 796 | | | | +--:(source-port-range-or-operator) 797 | | | | +--rw source-port-range-or-operator 798 | | | | +--rw (port-range-or-operator)? 799 | | | | +--:(range) 800 | | | | | +--rw lower-port 801 | | | | | | inet:port-number 802 | | | | | +--rw upper-port 803 | | | | | inet:port-number 804 | | | | +--:(operator) 805 | | | | +--rw operator? 806 | | | | | operator 807 | | | | +--rw port 808 | | | | inet:port-number 809 | | | +--rw (destination-port)? 810 | | | +--:(destination-port-range-or-operator) 811 | | | +--rw destination-port-range-or-operator 812 | | | +--rw (port-range-or-operator)? 813 | | | +--:(range) 814 | | | | +--rw lower-port 815 | | | | | inet:port-number 816 | | | | +--rw upper-port 817 | | | | inet:port-number 818 | | | +--:(operator) 819 | | | +--rw operator? 820 | | | | operator 821 | | | +--rw port 822 | | | inet:port-number 823 | | +--:(icmp) 824 | | +--rw icmp 825 | | +--rw type? uint8 826 | | +--rw code? uint8 827 | | +--rw rest-of-header? uint32 828 | +--rw actions 829 | | ... 830 | +--ro statistics 831 | ... 832 +--ro capabilities 833 ... 835 Figure 9: DOTS ACLs Subtree (UDP and ICMP Match) 837 DOTS implementations MUST support the following matching criteria: 839 match based on the IP header (IPv4 and IPv6), match based on the 840 transport header (TCP, UDP, and ICMP), and any combination 841 thereof. The same matching fields are used for both ICMP and 842 ICMPv6. 844 The following match fields MUST be supported by DOTS implementations 845 (Table 1): 847 ACL Mandatory Fields 848 Match 849 ------- ------------------------------------------------------------- 850 ipv4 length, protocol, destination-ipv4-network, source- 851 ipv4-network, and v4-fragments 852 ipv6 length, protocol, destination-ipv6-network, source- 853 ipv6-network, and v6-fragments 854 tcp flags, source-port-range-or-operator, and destination-port- 855 range-or-operator 856 udp length, source-port-range-or-operator, and destination-port- 857 range-or-operator 858 icmp type and code 860 Table 1: Mandatory DOTS Channel Match Fields 862 Implementations MAY support other filtering match fields and actions. 863 The 'ietf-dots-data-channel' allows an implementation to expose its 864 filtering capabilities. The tree structure of the 'capabilities' is 865 shown in Figure 10. 867 module: ietf-dots-data-channel 868 +--rw dots-data 869 ... 870 +--ro capabilities 871 +--ro address-family* enumeration 872 +--ro forwarding-actions* identityref 873 +--ro rate-limit? boolean 874 +--ro fragment* enumeration 875 +--ro transport-protocols* uint8 876 +--ro ipv4 877 | +--ro dscp? boolean 878 | +--ro ecn? boolean 879 | +--ro length? boolean 880 | +--ro ttl? boolean 881 | +--ro protocol? boolean 882 | +--ro ihl? boolean 883 | +--ro flags? boolean 884 | +--ro offset? boolean 885 | +--ro identification? boolean 886 | +--ro source-prefix? boolean 887 | +--ro destination-prefix? boolean 888 +--ro ipv6 889 | +--ro dscp? boolean 890 | +--ro ecn? boolean 891 | +--ro flow-label? boolean 892 | +--ro length? boolean 893 | +--ro protocol? boolean 894 | +--ro hoplimit? boolean 895 | +--ro source-prefix? boolean 896 | +--ro destination-prefix? boolean 897 +--ro tcp 898 | +--ro sequence-number? boolean 899 | +--ro acknowledgement-number? boolean 900 | +--ro data-offset? boolean 901 | +--ro reserved? boolean 902 | +--ro flags? boolean 903 | +--ro window-size? boolean 904 | +--ro urgent-pointer? boolean 905 | +--ro options? boolean 906 | +--ro source-port? boolean 907 | +--ro destination-port? boolean 908 | +--ro port-range? boolean 909 +--ro udp 910 | +--ro length? boolean 911 | +--ro source-port? boolean 912 | +--ro destination-port? boolean 913 | +--ro port-range? boolean 914 +--ro icmp 915 +--ro type? boolean 916 +--ro code? boolean 917 +--ro rest-of-header? boolean 919 Figure 10: Filtering Capabilities Sub-Tree 921 4.3. YANG Module 923 file "ietf-dots-data-channel@2018-03-16.yang" 925 module ietf-dots-data-channel { 926 yang-version 1.1; 927 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel"; 928 prefix data-channel; 930 import ietf-access-control-list { 931 prefix ietf-acl; 932 } 933 import ietf-packet-fields { 934 prefix packet-fields; 935 } 936 import ietf-dots-signal-channel { 937 prefix dots-signal; 938 } 940 organization 941 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 942 contact 943 "WG Web: 944 WG List: 946 Editor: Konda, Tirumaleswar Reddy 947 949 Editor: Mohamed Boucadair 950 952 Author: Kaname Nishizuka 953 955 Author: Liang Xia 956 958 Author: Prashanth Patil 959 961 Author: Andrew Mortensen 962 964 Author: Nik Teague 965 967 Author: Jon Shallow 968 "; 969 description 970 "This module contains YANG definition for configuring 971 aliases for resources and filtering rules using DOTS 972 data channel. 974 Copyright (c) 2018 IETF Trust and the persons identified as 975 authors of the code. All rights reserved. 977 Redistribution and use in source and binary forms, with or 978 without modification, is permitted pursuant to, and subject 979 to the license terms contained in, the Simplified BSD License 980 set forth in Section 4.c of the IETF Trust's Legal Provisions 981 Relating to IETF Documents 982 (http://trustee.ietf.org/license-info). 984 This version of this YANG module is part of RFC XXXX; see 985 the RFC itself for full legal notices."; 987 revision 2018-03-16 { 988 description 989 "Initial revision."; 990 reference 991 "RFC XXXX: Distributed Denial-of-Service Open Threat 992 Signaling (DOTS) Data Channel Specification"; 993 } 995 grouping aliases { 996 description 997 "Top level container for aliases"; 998 list alias { 999 key "name"; 1000 description 1001 "List of aliases"; 1002 leaf name { 1003 type string; 1004 description 1005 "The name of the alias"; 1006 } 1007 uses dots-signal:target; 1008 leaf pending-lifetime { 1009 type int32; 1010 units "minutes"; 1011 config false; 1012 description 1013 "Indicates the pending validity lifetime of the alias 1014 entry."; 1015 } 1016 } 1017 } 1019 grouping ports { 1020 choice source-port { 1021 container source-port-range-or-operator { 1022 uses packet-fields:port-range-or-operator; 1023 description 1024 "Source port definition."; 1025 } 1026 description 1027 "Choice of specifying the source port or referring to 1028 a group of source ports."; 1029 } 1030 choice destination-port { 1031 container destination-port-range-or-operator { 1032 uses packet-fields:port-range-or-operator; 1033 description 1034 "Destination port definition."; 1035 } 1036 description 1037 "Choice of specifying a destination port or referring 1038 to a group of destination ports."; 1039 } 1040 description 1041 "Choice of specifying a source or destination ports."; 1042 } 1044 grouping access-lists { 1045 description 1046 "Specifies the ordered set of Access Control Lists."; 1047 list acl { 1048 key "name"; 1049 ordered-by user; 1050 description 1051 "An Access Control List (ACL) is an ordered list of 1052 Access Control Entries (ACE). Each Access Control Entry 1053 has a list of match criteria and a list of actions."; 1054 leaf name { 1055 type string { 1056 length "1..64"; 1057 } 1058 description 1059 "The name of the access list."; 1060 reference 1061 "RFC ZZZZ: Network Access Control List (ACL) 1062 YANG Data Model"; 1063 } 1064 leaf type { 1065 type ietf-acl:acl-type; 1066 description 1067 "Type of access control list. Indicates the primary intended 1068 type of match criteria (e.g., IPv4, IPv6) used in the list 1069 instance."; 1070 reference 1071 "RFC ZZZZ: Network Access Control List (ACL) 1072 YANG Data Model"; 1073 } 1074 leaf activation-type { 1075 type enumeration { 1076 enum "activate-when-mitigating" { 1077 value 1; 1078 description 1079 "The ACL is installed only when a mitigation is active. 1080 The ACL is specific to this DOTS client."; 1082 } 1083 enum "immediate" { 1084 value 2; 1085 description 1086 "The ACL is immediately activated."; 1087 } 1088 } 1089 description 1090 "Indicates whether an ACL is to be installed immediately 1091 or when a mitigation is active."; 1092 } 1093 leaf pending-lifetime { 1094 type int32; 1095 units "minutes"; 1096 config false; 1097 description 1098 "Indicates the pending validity lifetime of the alias 1099 entry."; 1100 } 1101 container aces { 1102 description 1103 "The Access Control Entries container contains 1104 a list of ACEs."; 1105 list ace { 1106 key "name"; 1107 ordered-by user; 1108 description 1109 "List of access list entries."; 1110 leaf name { 1111 type string { 1112 length "1..64"; 1113 } 1114 description 1115 "A unique name identifying this Access List 1116 Entry (ACE)."; 1117 reference 1118 "RFC ZZZZ: Network Access Control List (ACL) 1119 YANG Data Model"; 1120 } 1121 container matches { 1122 description 1123 "The rules in this set determine what fields will be 1124 matched upon before any action is taken on them. 1126 If no matches are defined in a particular container, 1127 then any packet will match that container. 1129 If no matches are specified at all in an ACE, then any 1130 packet will match the ACE."; 1131 reference 1132 "RFC ZZZZ: Network Access Control List (ACL) 1133 YANG Data Model"; 1135 choice l3 { 1136 container ipv4 { 1137 when "derived-from(../../../../type," + 1138 "'ietf-acl:ipv4-acl-type')"; 1139 uses packet-fields:acl-ip-header-fields; 1140 uses packet-fields:acl-ipv4-header-fields; 1141 leaf v4-fragments { 1142 type empty; 1143 description 1144 "Handle IPv4 fragments."; 1145 } 1146 description 1147 "Rule set that matches IPv4 header."; 1148 } 1149 container ipv6 { 1150 when "derived-from(../../../../type," + 1151 "'ietf-acl:ipv6-acl-type')"; 1152 uses packet-fields:acl-ip-header-fields; 1153 uses packet-fields:acl-ipv6-header-fields; 1154 leaf v6-fragments { 1155 type empty; 1156 description 1157 "Handle IPv6 fragments."; 1158 } 1159 description 1160 "Rule set that matches IPv6 header."; 1161 } 1162 description 1163 "Either IPv4 or IPv6."; 1164 } 1165 choice l4 { 1166 container tcp { 1167 uses packet-fields:acl-tcp-header-fields; 1168 uses ports; 1169 description 1170 "Rule set that matches TCP header."; 1171 } 1172 container udp { 1173 uses packet-fields:acl-udp-header-fields; 1174 uses ports; 1175 description 1176 "Rule set that matches UDP header."; 1177 } 1178 container icmp { 1179 uses packet-fields:acl-icmp-header-fields; 1180 description 1181 "Rule set that matches ICMP/ICMPv6 header."; 1182 } 1183 description 1184 "Can be TCP, UDP, or ICMP/ICMPv6"; 1185 } 1186 } 1187 container actions { 1188 description 1189 "Definitions of action for this ACE."; 1190 leaf forwarding { 1191 type identityref { 1192 base ietf-acl:forwarding-action; 1193 } 1194 mandatory true; 1195 description 1196 "Specifies the forwarding action per ACE."; 1197 reference 1198 "RFC ZZZZ: Network Access Control List (ACL) 1199 YANG Data Model"; 1200 } 1201 leaf rate-limit { 1202 when "../forwarding = 'ietf-acl:accept'" { 1203 description 1204 "rate-limit valid only when accept action is used"; 1205 } 1206 type decimal64 { 1207 fraction-digits 2; 1208 } 1209 description 1210 "rate-limit traffic"; 1211 } 1212 } 1213 container statistics { 1214 config false; 1215 description 1216 "Aggregate statistics."; 1217 uses ietf-acl:acl-counters; 1218 } 1219 } 1220 } 1221 } 1222 } 1224 container dots-data { 1225 description 1226 "Main container for DOTS data channel."; 1227 list dots-client { 1228 key "cuid"; 1229 description 1230 "List of DOTS clients."; 1231 leaf cuid { 1232 type string; 1233 description 1234 "A unique identifier that is randomly generated by 1235 a DOTS client to prevent request collisions."; 1236 reference 1237 "RFC YYYY: Distributed Denial-of-Service Open Threat 1238 Signaling (DOTS) Signal Channel Specification"; 1239 } 1240 leaf cdid { 1241 type string; 1242 description 1243 "A client domain identifier conveyed by a 1244 server-domain DOTS gateway to a remote DOTS server."; 1245 reference 1246 "RFC YYYY: Distributed Denial-of-Service Open Threat 1247 Signaling (DOTS) Signal Channel Specification"; 1248 } 1249 container aliases { 1250 description 1251 "Set of aliases that are bound to a DOTS client."; 1252 uses aliases; 1253 } 1254 container acls { 1255 description 1256 "Access lists that are bound to a DOTS client."; 1257 uses access-lists; 1258 } 1259 } 1260 container capabilities { 1261 config false; 1262 description 1263 "Match capabilities"; 1264 leaf-list address-family { 1265 type enumeration { 1266 enum "ipv4" { 1267 description 1268 "IPv4 is supported."; 1269 } 1270 enum "ipv6" { 1271 description 1272 "IPv6 is supported."; 1273 } 1275 } 1276 description 1277 "Indicates the IP address families supported by 1278 the DOTS server."; 1279 } 1280 leaf-list forwarding-actions { 1281 type identityref { 1282 base ietf-acl:forwarding-action; 1283 } 1284 description 1285 "Supported forwarding action(s)."; 1286 } 1287 leaf rate-limit { 1288 type boolean; 1289 description 1290 "Support of rate-limit action."; 1291 } 1292 leaf-list fragment { 1293 type enumeration { 1294 enum "unsupported" { 1295 description 1296 "No fragment support."; 1297 } 1298 enum "v4-fragment" { 1299 description 1300 "Filtering IPv4 fragments is supported."; 1301 } 1302 enum "v6-fragment" { 1303 description 1304 "Filtering IPv4 fragments is supported."; 1305 } 1306 } 1307 description 1308 "Indicates the capability of a DOTS server to 1309 enforce filters on fragments."; 1310 } 1311 leaf-list transport-protocols { 1312 type uint8; 1313 description 1314 "Upper-layer protocol associated with this mapping. 1316 Values are taken from the IANA protocol registry: 1317 https://www.iana.org/assignments/protocol-numbers/ 1318 protocol-numbers.xhtml 1320 For example, this field contains 6 (TCP) for a TCP 1321 mapping or 17 (UDP) for a UDP mapping."; 1322 } 1323 container ipv4 { 1324 description 1325 "Indicates IPv4 header fields that are supported to enforce 1326 ACLs."; 1327 leaf dscp { 1328 type boolean; 1329 description 1330 "Support of filtering based on DSCP."; 1331 } 1332 leaf ecn { 1333 type boolean; 1334 description 1335 "Support of filtering based on ECN."; 1336 } 1337 leaf length { 1338 type boolean; 1339 description 1340 "Support of filtering based on the Total Length."; 1341 } 1342 leaf ttl { 1343 type boolean; 1344 description 1345 "Support of filtering based on the TTL."; 1346 } 1347 leaf protocol { 1348 type boolean; 1349 description 1350 "Support of filtering based on protocol field."; 1351 } 1352 leaf ihl { 1353 type boolean; 1354 description 1355 "Support of filtering based on the Internet Header 1356 Length (IHL)."; 1357 } 1358 leaf flags { 1359 type boolean; 1360 description 1361 "Support of filtering based on the flags."; 1362 } 1363 leaf offset { 1364 type boolean; 1365 description 1366 "Support of filtering based on the fragment offset."; 1367 } 1368 leaf identification { 1369 type boolean; 1370 description 1371 "Support of filtering based on the fragment 1372 identification."; 1373 } 1374 leaf source-prefix { 1375 type boolean; 1376 description 1377 "Support of filtering based on the source prefix."; 1378 } 1379 leaf destination-prefix { 1380 type boolean; 1381 description 1382 "Support of filtering based on the destination prefix."; 1383 } 1384 } 1385 container ipv6 { 1386 description 1387 "Indicates IPv6 header fields that are supported to enforce 1388 ACLs."; 1389 leaf dscp { 1390 type boolean; 1391 description 1392 "Support of filtering based on DSCP."; 1393 } 1394 leaf ecn { 1395 type boolean; 1396 description 1397 "Support of filtering based on ECN."; 1398 } 1399 leaf flow-label { 1400 type boolean; 1401 description 1402 "Support of filtering based on the Flow label."; 1403 } 1404 leaf length { 1405 type boolean; 1406 description 1407 "Support of filtering based on the Payload Length."; 1408 } 1409 leaf protocol { 1410 type boolean; 1411 description 1412 "Support of filtering based on the Next Header field."; 1413 } 1414 leaf hoplimit { 1415 type boolean; 1416 description 1417 "Support of filtering based on the Hop Limit."; 1418 } 1419 leaf source-prefix { 1420 type boolean; 1421 description 1422 "Support of filtering based on the source prefix."; 1423 } 1424 leaf destination-prefix { 1425 type boolean; 1426 description 1427 "Support of filtering based on the destination prefix."; 1428 } 1429 } 1430 container tcp { 1431 description 1432 "Set of TCP fields that are supported by the DOTS server 1433 to enfoce filters."; 1434 leaf sequence-number { 1435 type boolean; 1436 description 1437 "Support of filtering based on the TCP sequence number."; 1438 } 1439 leaf acknowledgement-number { 1440 type boolean; 1441 description 1442 "Support of filtering based on the TCP acknowledgement 1443 number."; 1444 } 1445 leaf data-offset { 1446 type boolean; 1447 description 1448 "Support of filtering based on the TCP data-offset."; 1449 } 1450 leaf reserved { 1451 type boolean; 1452 description 1453 "Support of filtering based on the TCP reserved field."; 1454 } 1455 leaf flags { 1456 type boolean; 1457 description 1458 "Support of filtering based on the TCP flags."; 1459 } 1460 leaf window-size { 1461 type boolean; 1462 description 1463 "Support of filtering based on the TCP window size."; 1464 } 1465 leaf urgent-pointer { 1466 type boolean; 1467 description 1468 "Support of filtering based on the TCP urgent pointer."; 1469 } 1470 leaf options { 1471 type boolean; 1472 description 1473 "Support of filtering based on the TCP options."; 1474 } 1475 leaf source-port { 1476 type boolean; 1477 description 1478 "Support of filtering based on the source port number."; 1479 } 1480 leaf destination-port { 1481 type boolean; 1482 description 1483 "Support of filtering based on the destination port 1484 number."; 1485 } 1486 leaf port-range { 1487 type boolean; 1488 description 1489 "Support of filtering based on a port range."; 1490 } 1491 } 1492 container udp { 1493 description 1494 "Set of UDP fields that are supported by the DOTS server 1495 to enforce filters."; 1496 leaf length { 1497 type boolean; 1498 description 1499 "Support of filtering based on the UDP length."; 1500 } 1501 leaf source-port { 1502 type boolean; 1503 description 1504 "Support of filtering based on the source port number."; 1505 } 1506 leaf destination-port { 1507 type boolean; 1508 description 1509 "Support of filtering based on the destination port 1510 number."; 1511 } 1512 leaf port-range { 1513 type boolean; 1514 description 1515 "Support of filtering based on a port range."; 1516 } 1517 } 1518 container icmp { 1519 description 1520 "Set of ICMP/ICMPv6 fields that are supported by the DOTS server 1521 to enforce filters."; 1522 leaf type { 1523 type boolean; 1524 description 1525 "Support of filtering based on the ICMP/ICMPv6 type."; 1526 } 1527 leaf code { 1528 type boolean; 1529 description 1530 "Support of filtering based on the ICMP/ICMPv6 code."; 1531 } 1532 leaf rest-of-header { 1533 type boolean; 1534 description 1535 "Support of filtering based on the ICMP four-bytes 1536 field."; 1537 } 1538 } 1539 } 1540 } 1541 } 1542 1544 5. Managing DOTS Clients 1546 5.1. Registering DOTS Clients 1548 In order to make use of DOTS data channel, a DOTS client MUST 1549 register to its DOTS server(s) by creating a DOTS client ('dots- 1550 client') resource. To that aim, DOTS clients SHOULD send a POST 1551 request (shown in Figure 11). 1553 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1554 Host: {host}:{port} 1555 Content-Type: application/yang-data+json 1556 { 1557 "ietf-dots-data-channel:dots-client": [ 1558 { 1559 "cuid": "string" 1560 } 1561 ] 1562 } 1564 Figure 11: POST to Register 1566 The 'cuid' (client unique identifier) parameter is described below: 1568 cuid: A globally unique identifier that is meant to prevent 1569 collisions among DOTS clients. This attribute has the same 1570 meaning, syntax, and processing rules as the 'cuid' attribute 1571 defined in [I-D.ietf-dots-signal-channel]. 1573 DOTS clients MUST use the same 'cuid' for both signal and data 1574 channels. 1576 This is a mandatory attribute. 1578 In deployments where server-domain DOTS gateways are enabled, 1579 identity information about the origin source client domain SHOULD be 1580 supplied to the DOTS server. That information is meant to assist the 1581 DOTS server to enforce some policies. These policies can be enforced 1582 per-client, per-client domain, or both. Figure 12 shows an example 1583 of a request relayed by a server-domain DOTS gateway. 1585 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1586 Host: {host}:{port} 1587 Content-Type: application/yang-data+json 1588 { 1589 "ietf-dots-data-channel:dots-client": [ 1590 { 1591 "cuid": "string", 1592 "cdid": "string" 1593 } 1594 ] 1595 } 1597 Figure 12: POST to Register (DOTS Gateway) 1599 A server-domain DOTS gateway SHOULD add the following attribute: 1601 cdid: This attribute has the same meaning, syntax, and processing 1602 rules as the 'cdid' attribute defined in 1603 [I-D.ietf-dots-signal-channel]. 1605 In deployments where server-domain DOTS gateways are enabled, 1606 'cdid' does not need to be inserted when relaying DOTS methods to 1607 manage aliases (Section 6) or filtering rules (Section 7). DOTS 1608 servers are responsible for maintaining the association between 1609 'cdid' and 'cuid' for policy enforcement purposes. 1611 This is an optional attribute. 1613 A request example to create a 'dots-client' resource is depicted in 1614 Figure 13. This request is relayed by a server-domain DOTS gateway 1615 as hinted by the presence of the 'cdid' attribute. 1617 POST /restconf/data/ietf-dots-data-channel:dots-data HTTP/1.1 1618 Host: {host}:{port} 1619 Content-Type: application/yang-data+json 1620 { 1621 "ietf-dots-data-channel:dots-client": [ 1622 { 1623 "cuid": "dz6pHjaADkaFTbjr0JGBpw", 1624 "cdid": "7eeaf349529eb55ed50113" 1625 } 1626 ] 1627 } 1629 Figure 13: POST to Register (DOTS gateway) 1631 DOTS servers MUST limit the number of 'dots-client' resources to be 1632 created by the same DOTS client to 1 per request. Requests with 1633 multiple 'dots-client' resources MUST be rejected by DOTS servers. 1634 To that aim, the DOTS server MUST rely on the same procedure to 1635 unambiguously identify a DOTS client as discussed in Section 4.4.1 of 1636 [I-D.ietf-dots-signal-channel]. 1638 The DOTS server indicates the result of processing the POST request 1639 using status-line codes. Status codes in the range "2xx" codes are 1640 success, "4xx" codes are some sort of invalid requests and "5xx" 1641 codes are returned if the DOTS server has erred or is incapable of 1642 accepting the creation of the 'dots-client' resource. In particular, 1644 o "201 Created" status-line is returned in the response, if the DOTS 1645 server has accepted the request. 1647 o "400 Bad Request" status-line is returned by the DOTS server, if 1648 the request does not include a 'cuid' parameter. The error-tag 1649 "missing-attribute" is used in this case. 1651 o "409 Conflict" status-line is returned to the requesting DOTS 1652 client, if the data resource already exists. The error-tag 1653 "resource-denied" is used in this case. 1655 Once a DOTS client registers itself to a DOTS server, it can 1656 create/delete/retrieve aliases (Section 6) and filtering rules 1657 (Section 7). 1659 A DOTS client MAY use the PUT request (Section 4.5 in [RFC8040]) to 1660 register a DOTS client within the DOTS server. An example is shown 1661 in Figure 14. 1663 PUT /restconf/data/ietf-dots-data-channel:dots-data\ 1664 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1665 Host: {host}:{port} 1666 Content-Type: application/yang-data+json 1667 { 1668 "ietf-dots-data-channel:dots-client": [ 1669 { 1670 "cuid": "dz6pHjaADkaFTbjr0JGBpw" 1671 } 1672 ] 1673 } 1675 Figure 14: PUT to Register 1677 The DOTS gateway that inserted a 'cdid' in a PUT request, MUST strip 1678 the 'cdid' parameter in the corresponding response before forwarding 1679 the response to the DOTS client. 1681 5.2. Uregistering DOTS Clients 1683 A DOTS client de-registers from its DOTS server by deleting the 1684 'cuid' resource. Resources bound to this DOTS client will be deleted 1685 by the DOTS server. An example of de-register request is shown in 1686 Figure 15. 1688 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1689 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1690 Host: {host}:{port} 1692 Figure 15: De-register a DOTS Client 1694 6. Managing DOTS Aliases 1696 The following sub-sections define means for a DOTS client to create 1697 aliases (Section 6.1), retrieve one or a list of aliases 1698 (Section 6.2), and delete an alias (Section 6.3). 1700 6.1. Create Aliases 1702 A POST or PUT request is used by a DOTS client to create aliases, for 1703 resources for which a mitigation may be requested. Such aliases may 1704 be used in subsequent DOTS signal channel exchanges to refer more 1705 efficiently to the resources under attack. 1707 DOTS clients within the same domain can create different aliases for 1708 the same resource. 1710 The structure of POST requests used to create aliases is shown in 1711 Figure 16. 1713 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1714 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1715 Host: {host}:{port} 1716 Content-Type: application/yang-data+json 1717 { 1718 "ietf-dots-data-channel:aliases": { 1719 "alias": [ 1720 { 1721 "name": "string", 1722 "target-prefix": [ 1723 "string" 1724 ], 1725 "target-port-range": [ 1726 { 1727 "lower-port": integer, 1728 "upper-port": integer 1729 } 1730 ], 1731 "target-protocol": [ 1732 integer 1733 ], 1734 "target-fqdn": [ 1735 "string" 1736 ], 1737 "target-uri": [ 1738 "string" 1739 ] 1740 } 1741 ] 1742 } 1743 } 1745 Figure 16: POST to Create Aliases 1747 The parameters are described below: 1749 name: Name of the alias. 1751 This is a mandatory attribute. 1753 target-prefix: Prefixes are separated by commas. Prefixes are 1754 represented using Classless Inter-domain Routing (CIDR) notation 1755 [RFC4632]. As a reminder, the prefix length must be less than or 1756 equal to 32 (resp. 128) for IPv4 (resp. IPv6). 1758 The prefix list MUST NOT include broadcast, loopback, or multicast 1759 addresses. These addresses are considered as invalid values. In 1760 addition, the DOTS server MUST validate that these prefixes are 1761 within the scope of the DOTS client's domain. Other validation 1762 checks may be supported by DOTS servers. 1764 This is an optional attribute. 1766 target-port-range: A range of port numbers. 1768 The port range is defined by two bounds, a lower port number 1769 (lower-port) and an upper port number (upper-port). 1771 When only 'lower-port' is present, it represents a single port 1772 number. 1774 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 1775 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 1776 [RFC4340], the range of port numbers can be, for example, 1777 1024-65535. 1779 This is an optional attribute. 1781 target-protocol: A list of protocols. Values are taken from the 1782 IANA protocol registry [proto_numbers]. 1784 The value '0' has a special meaning for 'all protocols'. 1786 This is an optional attribute. 1788 target-fqdn: A list of Fully Qualified Domain Names (FQDNs). An 1789 FQDN is the full name of a resource, rather than just its 1790 hostname. For example, "venera" is a hostname, and 1791 "venera.isi.edu" is an FQDN [RFC1983]. 1793 How a name is passed to an underlying name resolution library is 1794 implementation- and deployment-specific. Nevertheless, once the 1795 name is resolved into one or multiple IP addresses, DOTS servers 1796 MUST apply the same validation checks as those for 'target- 1797 prefix'. 1799 This is an optional attribute. 1801 target-uri: A list of Uniform Resource Identifiers (URIs) 1802 [RFC3986]. 1804 The same validation checks used for 'target-fqdn' MUST be followed 1805 by DOTS servers to validate a target URI. 1807 This is an optional attribute. 1809 In POST requests, at least one of the 'target-prefix', 'target-fqdn', 1810 or 'target-uri' attributes MUST be present. DOTS agents can safely 1811 ignore Vendor-Specific parameters they don't understand. 1813 Figure 17 shows a POST request to create an alias called "https1" for 1814 HTTPS servers with IP addresses 2001:db8:6401::1 and 2001:db8:6401::2 1815 listening on port number 443. 1817 POST /restconf/data/ietf-dots-data-channel:dots-data\ 1818 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 1819 Host: www.example.com 1820 Content-Type: application/yang-data+json 1821 { 1822 "ietf-dots-data-channel:aliases": { 1823 "alias": [ 1824 { 1825 "name": "https1", 1826 "target-protocol": [ 1827 6 1828 ], 1829 "target-prefix": [ 1830 "2001:db8:6401::1/128", 1831 "2001:db8:6401::2/128" 1832 ], 1833 "target-port-range": [ 1834 { 1835 "lower-port": 443 1836 } 1837 ] 1838 } 1839 ] 1840 } 1841 } 1843 Figure 17: Example of a POST to Create an Alias 1845 "201 Created" status-line MUST be returned in the response if the 1846 DOTS server has accepted the alias. 1848 "409 Conflict" status-line MUST be returned to the requesting DOTS 1849 client, if the request is conflicting with an existing alias name. 1850 The error-tag "resource-denied" is used in this case. 1852 If the request is missing a mandatory attribute or its contains an 1853 invalid or unknown parameter, "400 Bad Request" status-line MUST be 1854 returned by the DOTS server. The error-tag is set to "missing- 1855 attribute", "invalid-value", or "unknown-element" as a function of 1856 the encountered error. 1858 If the request is received via a server-domain DOTS gateway, but the 1859 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 1860 is expected to be supplied, the DOTS server MUST reply with "403 1861 Forbidden" status-line and the error-tag "access-denied". Upon 1862 receipt of this message, the DOTS client MUST register (Section 5). 1864 A DOTS client uses the PUT request to modify the aliases in the DOTS 1865 server. In particular, a DOTS client MUST update its alias entries 1866 upon change of the prefix indicated in the 'target-prefix'. 1868 A DOTS server MUST maintain an alias for at least 10080 minutes (1 1869 week). If no refresh request is seen from the DOTS client, the DOTS 1870 server removes expired entries. 1872 6.2. Retrieve Installed Aliases 1874 GET request is used to retrieve one or all installed aliases by a 1875 DOTS client from a DOTS server (Section 3.3.1 in [RFC8040]). If no 1876 'name' is included in the request, this is an indication that the 1877 request is about retrieving all aliases instantiated by the DOTS 1878 client. 1880 Figure 18 shows an example to retrieve all the aliases that were 1881 instantiated by the requesting DOTS client. The 'content' parameter 1882 and its permitted values are defined in Section 4.8.1 of [RFC8040]. 1884 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1885 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1886 /aliases?content=config HTTP/1.1 1887 Host: {host}:{port} 1888 Accept: application/yang-data+json 1890 Figure 18: GET to Retrieve All Installed Aliases 1892 Figure 19 shows an example of the response message body that includes 1893 all the aliases that are maintained by the DOTS server for the DOTS 1894 client identified by the 'cuid' parameter. 1896 { 1897 "ietf-dots-data-channel:aliases": { 1898 "alias": [ 1899 { 1900 "name": "Server1", 1901 "traffic-protocol": [ 1902 6 1903 ], 1904 "target-prefix": [ 1905 "2001:db8:6401::1/128", 1906 "2001:db8:6401::2/128" 1907 ], 1908 "target-port-range": [ 1909 { 1910 "lower-port": 443 1911 } 1912 ], 1913 "pending-lifetime": 3596 1914 }, 1915 { 1916 "name": "Server2", 1917 "target-protocol": [ 1918 6 1919 ], 1920 "target-prefix": [ 1921 "2001:db8:6401::10/128", 1922 "2001:db8:6401::20/128" 1923 ], 1924 "target-port-range": [ 1925 { 1926 "lower-port": 80 1927 } 1928 ], 1929 "pending-lifetime": 9869 1930 } 1931 ] 1932 } 1933 } 1935 Figure 19: An Example of Response Body 1937 Figure 20 shows an example of a GET request to retrieve the alias 1938 "Server2" that was instantiated by the DOTS client. 1940 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1941 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1942 /aliases/alias=Server2?content=config HTTP/1.1 1943 Host: {host}:{port} 1944 Accept: application/yang-data+json 1946 Figure 20: GET to Retrieve an Alias 1948 If an alias name ('name') is included in the request, but the DOTS 1949 server does not find that alias name for this DOTS client in its 1950 configuration data, it MUST respond with a "404 Not Found" status- 1951 line. 1953 6.3. Delete Aliases 1955 DELETE request is used to delete an alias maintained by a DOTS 1956 server. 1958 If the DOTS server does not find the alias name, conveyed in the 1959 DELETE request, in its configuration data for this DOTS client, it 1960 MUST respond with a "404 Not Found" status-line. 1962 The DOTS server successfully acknowledges a DOTS client's request to 1963 remove the alias using "204 No Content" status-line in the response. 1965 Figure 21 shows an example of a request to delete an alias. 1967 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 1968 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 1969 /aliases/alias=Server1 HTTP/1.1 1970 Host: {host}:{port} 1972 Figure 21: Delete an Alias 1974 7. Managing DOTS Filtering Rules 1976 The following sub-sections define means for a DOTS client to retrieve 1977 DOTS filtering capabilities (Section 7.1), create filtering rules 1978 (Section 7.2), retrieve active filtering rules (Section 7.3), and 1979 delete a filtering rule (Section 7.4). 1981 7.1. Retrieve DOTS Filtering Capabilities 1983 A DOTS client MAY send a GET request to retrieve the filtering 1984 capabilities supported by a DOTS server. Figure 22 shows an example 1985 of such request. 1987 GET /restconf/data/ietf-dots-data-channel:dots-data\ 1988 /capabilities HTTP/1.1 1989 Host: {host}:{port} 1990 Accept: application/yang-data+json 1992 Figure 22: GET to Retrieve the Capabilities of a DOTS Server 1994 A DOTS client which issued a GET request to retrieve the filtering 1995 capabilities supported by its, SHOULD NOT request for filtering 1996 actions that are not supported by that DOTS server. 1998 Figure 23 shows an example of a response received from a DOTS server 1999 which only supports the mandatory filtering criteria listed in 2000 Section 4.1. 2002 Content-Type: application/yang-data+json 2003 { 2004 "ietf-dots-data-channel:capabilities": { 2005 "address-family": ["ipv4", "ipv6"], 2006 "forwarding-actions": ["drop", "accept"], 2007 "rate-limit": "true", 2008 "fragment": ["v4-fragment", "v6-fragment"], 2009 "transport-protocols": [1, 6, 17, 58], 2010 "ipv4": { 2011 "length": "true", 2012 "protocol": "true", 2013 "destination-prefix": "true", 2014 "source-prefix": "true" 2015 }, 2016 "ipv6": { 2017 "length": "true", 2018 "protocol": "true", 2019 "destination-prefix": "true", 2020 "source-prefix": "true" 2021 }, 2022 "tcp": { 2023 "flags": "true", 2024 "source-port": "true", 2025 "destination-port": "true", 2026 "port-range": "true" 2027 }, 2028 "udp": { 2029 "length": "true", 2030 "source-port": "true", 2031 "destination-port": "true", 2032 "port-range": "true" 2033 }, 2034 "icmp": { 2035 "type": "true", 2036 "code": "true" 2037 } 2038 } 2039 } 2041 Figure 23: Reply to a GET Response with Filtering Capabilities 2043 7.2. Install Filtering Rules 2045 A POST or PUT request is used by a DOTS client to communicate 2046 filtering rules to a DOTS server. 2048 Figure 24 shows a POST request example to block traffic from 2049 192.0.2.0/24 and destined to 198.51.100.0/24. 2051 POST /restconf/data/ietf-dots-data-channel:dots-data\ 2052 /dots-client=dz6pHjaADkaFTbjr0JGBpw HTTP/1.1 2053 Host: {host}:{port} 2054 Content-Type: application/yang-data+json 2055 { 2056 "ietf-dots-data-channel:acls": { 2057 "acl": [ 2058 { 2059 "name": "sample-ipv4-acl", 2060 "type": "ipv4-acl-type", 2061 "activation-type": "activate-when-mitigating", 2062 "aces": { 2063 "ace": [ 2064 { 2065 "name": "rule1", 2066 "matches": { 2067 "ipv4": { 2068 "destination-ipv4-network": "198.51.100.0/24", 2069 "source-ipv4-network": "192.0.2.0/24" 2070 } 2071 }, 2072 "actions": { 2073 "forwarding": "drop" 2074 } 2075 } 2076 ] 2077 } 2078 } 2079 ] 2080 } 2081 } 2083 Figure 24: POST to Install Filtering Rules 2085 The meaning of these parameters is as follows: 2087 name: The name of the access list. 2089 This is a mandatory attribute. 2091 type: Indicates the primary intended type of match criteria (e.g., 2092 IPv4, IPv6). It is set to 'ipv4-acl-type' in this example. 2094 This is an optional attribute. 2096 activation-type: Indicates whether an ACL has to be installed 2097 immediately or during mitigation time. If this attribute is not 2098 provided, the DOTS server MUST use 'activate-when-mitigating' as 2099 default value. Filters that are activated only when a mitigation 2100 is in progress MUST be bound to the DOTS client which created the 2101 filtering rule. 2103 This is an optional attribute. 2105 matches: Define criteria used to identify a flow on which to apply 2106 the rule. It can be "l3" (IPv4, IPv6) or "l4" (TCP, UDP, ..). 2107 The detailed match parameters are specified in Section 4. 2109 In this example, an IPv4 matching criteria is used. 2111 This is an optional attribute. 2113 destination-ipv4-network: The destination IPv4 prefix. DOTS servers 2114 MUST validate that these prefixes are within the scope of the DOTS 2115 client's domain. Other validation checks may be supported by DOTS 2116 servers. If this attribute is not provided, the DOTS server 2117 enforces the ACL on any destination IP address that belong to the 2118 DOTS client's domain. 2120 This is a mandatory attribute in requests with an 'activation- 2121 type' set to 'immediate'. 2123 source-ipv4-network: The source IPv4 prefix. 2125 This is an optional attribute. 2127 actions: Actions in the forwarding ACL category can be "drop" or 2128 "accept". The "accept" action is used to white-list traffic. The 2129 "drop" action is used to black-list traffic. 2131 Accepted traffic may be subject to "rate-limit"; the allowed 2132 traffic rate is represented in bytes per second indicated in IEEE 2133 floating point format [IEEE.754.1985]. 2135 This is a mandatory attribute. 2137 The DOTS server indicates the result of processing the POST request 2138 using the status-line header. Concretely, "201 Created" status-line 2139 MUST be returned in the response if the DOTS server has accepted the 2140 filtering rules. If the request is missing a mandatory attribute or 2141 contains an invalid or unknown parameter (e.g., a match field not 2142 supported by the DOTS server), "400 Bad Request" status-line MUST be 2143 returned by the DOTS server in the response. The error-tag is set to 2144 "missing-attribute", "invalid-value", or "unknown-element" as a 2145 function of the encountered error. 2147 If the request is received via a server-domain DOTS gateway, but the 2148 DOTS server does not maintain a 'cdid' for this 'cuid' while a 'cdid' 2149 is expected to be supplied, the DOTS server MUST reply with "403 2150 Forbidden" status-line and the error-tag "access-denied". Upon 2151 receipt of this message, the DOTS client MUST register (Figure 11). 2153 If the request is conflicting with an existing filtering installed by 2154 another DOTS client of the domain, the DOTS server returns "409 2155 Conflict" status-line to the requesting DOTS client. The error-tag 2156 "resource-denied" is used in this case. 2158 The "insert" query parameter (Section 4.8.5 of [RFC8040]) MAY be used 2159 to specify how an access control entry is inserted within an ACL and 2160 how an ACL is inserted within an ACL set. 2162 The DOTS client uses the PUT request to modify its filtering rules 2163 maintained by the DOTS server. In particular, a DOTS client MUST 2164 update its filtering entries upon change of the destination-prefix. 2165 How such change is detected is out of scope. 2167 A DOTS server MUST maintain a filtering rule for at least 10080 2168 minutes (1 week). If no refresh request is seen from the DOTS 2169 client, the DOTS server removes expired entries. 2171 7.3. Retrieve Installed Filtering Rules 2173 The DOTS client periodically queries the DOTS server to check the 2174 counters for installed filtering rules. GET request is used to 2175 retrieve filtering rules from a DOTS server. 2177 If the DOTS server does not find the access list name conveyed in the 2178 GET request in its configuration data for this DOTS client, it 2179 responds with a "404 Not Found" status-line. 2181 Figure 25 shows how to retrieve all the filtering rules that were 2182 instantiated by the DOTS client and the number of matches for the 2183 installed filtering rules. 2185 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2186 /dots-client=dz6pHjaADkaFTbjr0JGBpw\ 2187 /acls?content=all HTTP/1.1 2188 Host: {host}:{port} 2189 Accept: application/yang-data+json 2191 Figure 25: GET to Retrieve the Configuration Data and State Data for 2192 the Filtering Rules 2194 Figure 26 shows how to retrieve "sample-ipv6-acl" filtering rule 2195 instantiated by the DOTS client, having 2196 "cuid=dz6pHjaADkaFTbjr0JGBpw", and the number of matches for the 2197 installed filtering rules. 2199 GET /restconf/data/ietf-dots-data-channel:dots-data\ 2200 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2201 /acl=sample-ipv6-acl?content=all HTTP/1.1 2202 Host: {host}:{port} 2203 Accept: application/yang-data+json 2205 Figure 26: GET to Retrieve the Configuration Data and State Data for 2206 a Filtering Rule 2208 7.4. Remove Filtering Rules 2210 DELETE request is used by a DOTS client to delete filtering rules 2211 from a DOTS server. 2213 If the DOTS server does not find the access list name carried in the 2214 DELETE request in its configuration data for this DOTS client, it 2215 MUST respond with a "404 Not Found" status-line. The DOTS server 2216 successfully acknowledges a DOTS client's request to withdraw the 2217 filtering rules using "204 No Content" status-line, and removes the 2218 filtering rules accordingly. 2220 Figure 27 shows an example of a request to remove the IPv4 ACL named 2221 "sample-ipv4-acl". 2223 DELETE /restconf/data/ietf-dots-data-channel:dots-data\ 2224 /dots-client=dz6pHjaADkaFTbjr0JGBpw/acls\ 2225 /acl=sample-ipv4-acl HTTP/1.1 2226 Host: {host}:{port} 2228 Figure 27: DELETE to Remove a Filtering Rule 2230 8. IANA Considerations 2232 This document requests IANA to register the following URI in the 2233 "IETF XML Registry" [RFC3688]: 2235 URI: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2236 Registrant Contact: The IESG. 2237 XML: N/A; the requested URI is an XML namespace. 2239 This document requests IANA to register the following YANG module in 2240 the "YANG Module Names" registry [RFC7950]. 2242 name: ietf-dots-data-channel 2243 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-data-channel 2244 prefix: data-channel 2245 reference: RFC XXXX 2247 9. Contributors 2249 The following individuals have contributed to this document: 2251 o Dan Wing, Email: dwing-ietf@fuggles.com 2253 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 2255 10. Security Considerations 2257 RESTCONF security considerations are discussed in [RFC8040]. In 2258 particular, DOTS agents MUST follow the security recommendations in 2259 Sections 2 and 12 of [RFC8040]. Also, DOTS agents MUST support the 2260 mutual authentication TLS profile discussed in Sections 7.1 and 8 of 2261 [I-D.ietf-dots-signal-channel]. YANG ACL-specific security 2262 considerations are discussed in [I-D.ietf-netmod-acl-model]. 2264 Authenticated encryption MUST be used for data confidentiality and 2265 message integrity. The interaction between the DOTS agents requires 2266 Transport Layer Security (TLS) with a cipher suite offering 2267 confidentiality protection and the guidance given in [RFC7525] MUST 2268 be followed to avoid attacks on TLS. 2270 An attacker may be able to inject RST packets, bogus application 2271 segments, etc., regardless of whether TLS authentication is used. 2272 Because the application data is TLS protected, this will not result 2273 in the application receiving bogus data, but it will constitute a DoS 2274 on the connection. This attack can be countered by using TCP-AO 2275 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 2276 attacker will be rejected by the TCP-AO integrity check and therefore 2277 will never reach the TLS layer. 2279 In order to prevent leaking internal information outside a client- 2280 domain, client-side DOTS gateways SHOULD NOT reveal the identity of 2281 internal DOTS clients (e.g., source IP address, client's hostname) 2282 unless explicitly configured to do so. 2284 DOTS servers MUST verify that requesting DOTS clients are entitled to 2285 enforce filtering rules on a given IP prefix. That is, only 2286 filtering rules on IP resources that belong to the DOTS client's 2287 domain MUST be authorized by a DOTS server. The exact mechanism for 2288 the DOTS servers to validate that the target prefixes are within the 2289 scope of the DOTS client's domain is deployment-specific. 2291 Rate-limiting DOTS requests, including those with new 'cuid' values, 2292 from the same DOTS client defends against DoS attacks that would 2293 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 2294 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 2295 DOTS servers. 2297 Applying resources quota per DOTS client and/or per DOTS client 2298 domain (e.g., limit the number of aliases and filters to be install 2299 by DOTS clients) prevents DOTS server resources to be aggressively 2300 used by some DOTS clients and ensures, therefore, DDoS mitigation 2301 usage fairness. Additionally, DOTS servers may limit the number of 2302 DOTS clients that can be enabled per domain. 2304 All data nodes defined in the YANG module which can be created, 2305 modified, and deleted (i.e., config true, which is the default) are 2306 considered sensitive. Write operations applied to these data nodes 2307 without proper protection can negatively affect network operations. 2308 Appropriate security measures are recommended to prevent illegitimate 2309 users from invoking DOTS data channel primitives. Nevertheless, an 2310 attacker who can access a DOTS client is technically capable of 2311 launching various attacks, such as: 2313 o Set an arbitrarily low rate-limit, which may prevent legitimate 2314 traffic from being forwarded (rate-limit). 2316 o Set an arbitrarily high rate-limit, which may lead to the 2317 forwarding of illegitimate DDoS traffic (rate-limit). 2319 o Communicate invalid aliases to the server (alias), which will 2320 cause the failure of associating both data and signal channels. 2322 o Set invalid ACL entries, which may prevent legitimate traffic from 2323 being forwarded. Likewise, invalid ACL entries may lead to 2324 forward DDoS traffic. 2326 11. Acknowledgements 2328 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 2329 Doron, Russ White, Gilbert Clark, and Nesredien Suleiman for the 2330 discussion and comments. 2332 12. References 2334 12.1. Normative References 2336 [I-D.ietf-dots-signal-channel] 2337 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 2338 Teague, "Distributed Denial-of-Service Open Threat 2339 Signaling (DOTS) Signal Channel Specification", draft- 2340 ietf-dots-signal-channel-18 (work in progress), March 2341 2018. 2343 [I-D.ietf-netmod-acl-model] 2344 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 2345 "Network Access Control List (ACL) YANG Data Model", 2346 draft-ietf-netmod-acl-model-18 (work in progress), March 2347 2018. 2349 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2350 Requirement Levels", BCP 14, RFC 2119, 2351 DOI 10.17487/RFC2119, March 1997, 2352 . 2354 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2355 DOI 10.17487/RFC3688, January 2004, 2356 . 2358 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2359 (CIDR): The Internet Address Assignment and Aggregation 2360 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2361 2006, . 2363 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2364 (TLS) Protocol Version 1.2", RFC 5246, 2365 DOI 10.17487/RFC5246, August 2008, 2366 . 2368 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 2369 Protocol (HTTP/1.1): Message Syntax and Routing", 2370 RFC 7230, DOI 10.17487/RFC7230, June 2014, 2371 . 2373 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2374 "Recommendations for Secure Use of Transport Layer 2375 Security (TLS) and Datagram Transport Layer Security 2376 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2377 2015, . 2379 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 2380 RFC 7951, DOI 10.17487/RFC7951, August 2016, 2381 . 2383 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 2384 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 2385 . 2387 12.2. Informative References 2389 [I-D.ietf-dots-architecture] 2390 Mortensen, A., Andreasen, F., Reddy, T., 2391 christopher_gray3@cable.comcast.com, c., Compton, R., and 2392 N. Teague, "Distributed-Denial-of-Service Open Threat 2393 Signaling (DOTS) Architecture", draft-ietf-dots- 2394 architecture-06 (work in progress), March 2018. 2396 [I-D.ietf-dots-requirements] 2397 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 2398 Denial of Service (DDoS) Open Threat Signaling 2399 Requirements", draft-ietf-dots-requirements-14 (work in 2400 progress), February 2018. 2402 [IEEE.754.1985] 2403 Institute of Electrical and Electronics Engineers, 2404 "Standard for Binary Floating-Point Arithmetic", August 2405 1985. 2407 [proto_numbers] 2408 "IANA, "Protocol Numbers"", 2011, 2409 . 2411 [RFC1983] Malkin, G., Ed., "Internet Users' Glossary", FYI 18, 2412 RFC 1983, DOI 10.17487/RFC1983, August 1996, 2413 . 2415 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2416 Resource Identifier (URI): Generic Syntax", STD 66, 2417 RFC 3986, DOI 10.17487/RFC3986, January 2005, 2418 . 2420 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2421 Congestion Control Protocol (DCCP)", RFC 4340, 2422 DOI 10.17487/RFC4340, March 2006, 2423 . 2425 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2426 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2427 . 2429 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 2430 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 2431 DOI 10.17487/RFC5389, October 2008, 2432 . 2434 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2435 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2436 June 2010, . 2438 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 2439 Layer Security (TLS) and Datagram Transport Layer Security 2440 (DTLS) Heartbeat Extension", RFC 6520, 2441 DOI 10.17487/RFC6520, February 2012, 2442 . 2444 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 2445 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 2446 DOI 10.17487/RFC6887, April 2013, 2447 . 2449 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 2450 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2451 2014, . 2453 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2454 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2455 . 2457 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 2458 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 2459 . 2461 Authors' Addresses 2463 Tirumaleswar Reddy (editor) 2464 McAfee, Inc. 2465 Embassy Golf Link Business Park 2466 Bangalore, Karnataka 560071 2467 India 2469 Email: kondtir@gmail.com 2470 Mohamed Boucadair (editor) 2471 Orange 2472 Rennes 35000 2473 France 2475 Email: mohamed.boucadair@orange.com 2477 Kaname Nishizuka 2478 NTT Communications 2479 GranPark 16F 3-4-1 Shibaura, Minato-ku 2480 Tokyo 108-8118 2481 Japan 2483 Email: kaname@nttv6.jp 2485 Liang Xia 2486 Huawei 2487 101 Software Avenue, Yuhuatai District 2488 Nanjing, Jiangsu 210012 2489 China 2491 Email: frank.xialiang@huawei.com 2493 Prashanth Patil 2494 Cisco Systems, Inc. 2496 Email: praspati@cisco.com 2498 Andrew Mortensen 2499 Arbor Networks, Inc. 2500 2727 S. State St 2501 Ann Arbor, MI 48104 2502 United States 2504 Email: amortensen@arbor.net 2506 Nik Teague 2507 Verisign, Inc. 2508 United States 2510 Email: nteague@verisign.com