idnits 2.17.1 draft-reddy-dots-data-channel-05.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 4 instances of too long lines in the document, the longest one being 8 characters in excess of 72. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 267 has weird spacing: '...er-port ine...' == Line 268 has weird spacing: '...er-port ine...' -- The document date (March 10, 2017) is 2602 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) == Missing Reference: 'RFC7230' is mentioned on line 204, but not defined ** Obsolete undefined reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) == Missing Reference: 'RFC7950' is mentioned on line 205, but not defined == Missing Reference: 'RFC6241' is mentioned on line 206, but not defined == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-01 ** Downref: Normative reference to an Informational draft: draft-ietf-dots-architecture (ref. 'I-D.ietf-dots-architecture') == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-09 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-03 == Outdated reference: A later version (-10) exists of draft-reddy-dots-signal-channel-09 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 5 errors (**), 0 flaws (~~), 12 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy 3 Internet-Draft Cisco 4 Intended status: Standards Track M. Boucadair 5 Expires: September 11, 2017 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 10, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-reddy-dots-data-channel-05 21 Abstract 23 The document specifies a Distributed Denial-of-Service Open Threat 24 Signaling (DOTS) data channel used for bulk exchange of data not 25 easily or appropriately communicated through the DOTS signal channel 26 under attack conditions. This is a companion document to the DOTS 27 signal channel specification. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on September 11, 2017. 46 Copyright Notice 48 Copyright (c) 2017 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Notational Conventions and Terminology . . . . . . . . . . . 4 65 3. DOTS Data Channel . . . . . . . . . . . . . . . . . . . . . . 4 66 3.1. DOTS Data Channel YANG Model . . . . . . . . . . . . . . 6 67 3.1.1. Identifier Model structure . . . . . . . . . . . . . 6 68 3.1.2. Identifier Model . . . . . . . . . . . . . . . . . . 6 69 3.1.3. Filter Model and structure . . . . . . . . . . . . . 8 70 3.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 8 71 3.2.1. Create Identifiers . . . . . . . . . . . . . . . . . 8 72 3.2.2. Delete Identifiers . . . . . . . . . . . . . . . . . 11 73 3.2.3. Retrieving Installed Identifiers . . . . . . . . . . 11 74 3.3. Filtering Rules . . . . . . . . . . . . . . . . . . . . . 14 75 3.3.1. Install Filtering Rules . . . . . . . . . . . . . . . 14 76 3.3.2. Remove Filtering Rules . . . . . . . . . . . . . . . 16 77 3.3.3. Retrieving Installed Filtering Rules . . . . . . . . 16 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 79 4.1. DOTS Data Channel JSON Attribute Mappings Registry . . . 17 80 4.2. Registration Template . . . . . . . . . . . . . . . . . . 17 81 4.3. Initial Registry Contents . . . . . . . . . . . . . . . . 17 82 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 19 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 84 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 19 85 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 86 8.1. Normative References . . . . . . . . . . . . . . . . . . 20 87 8.2. Informative References . . . . . . . . . . . . . . . . . 20 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 90 1. Introduction 92 A distributed denial-of-service (DDoS) attack is an attempt to make 93 machines or network resources unavailable to their intended users. 94 In most cases, sufficient scale can be achieved by compromising 95 enough end-hosts and using those infected hosts to perpetrate and 96 amplify the attack. The victim in this attack can be an application 97 server, a client, a router, a firewall, or an entire network. 99 DDoS Open Threat Signaling (DOTS) defines two channels: signal and 100 data channels [I-D.ietf-dots-architecture] (Figure 1). The DOTS 101 signal channel used to convey that a network is under a DDOS attack 102 to an upstream DOTS server so that appropriate mitigation actions are 103 undertaken on the suspect traffic is further elaborated in 104 [I-D.reddy-dots-signal-channel]. The DOTS data channel is used for 105 infrequent bulk data exchange between DOTS agents in the aim to 106 significantly augment attack response coordination. 108 +---------------+ +---------------+ 109 | | <------- Signal Channel ------> | | 110 | DOTS Client | | DOTS Server | 111 | | <======= Data Channel ======> | | 112 +---------------+ +---------------+ 114 Figure 1: DOTS Channels 116 Section 2 of [I-D.ietf-dots-architecture] identifies that the DOTS 117 data channel is used to perform the tasks listed below: 119 o Filter management, which enables a DOTS client to install or 120 remove traffic filters, dropping or rate-limiting unwanted traffic 121 and permitting white-listed traffic. Sample use cases for 122 populating black- or white-list filtering rules are detailed 123 hereafter: 125 A. If a network resource (DOTS client) detects a potential DDoS 126 attack from a set of IP addresses, the DOTS client informs its 127 servicing router (DOTS gateway) of all suspect IP addresses 128 that need to be blocked or black-listed for further 129 investigation. The DOTS client could also specify a list of 130 protocols and ports in the black-list rule. That DOTS gateway 131 in-turn propagates the black-listed IP addresses to the DOTS 132 server which will undertake appropriate action so that traffic 133 from these IP addresses to the target network (specified by 134 the DOTS client) is blocked. 135 B. An enterprise network has partner sites from which only 136 legitimate traffic arrives and the enterprise network wants to 137 ensure that the traffic from these sites is not penalized 138 during DDOS attacks. The DOTS client uses DOTS data channel 139 to convey the white-listed IP addresses or prefixes of the 140 partner sites to its DOTS server. The DOTS server uses this 141 information to white-list flows from such IP addresses or 142 prefixes reaching the enterprise network. 143 o Creating identifiers, such as names or aliases, for resources for 144 which mitigation may be requested: 146 A. The DOTS client may submit to the DOTS server a collection of 147 prefixes it wants to refer to by alias when requesting 148 mitigation, to which the server would respond with a success 149 status and the new prefix group alias, or an error status and 150 message in the event the DOTS client's data channel request 151 failed (see requirement OP-006 in [I-D.ietf-dots-requirements] 152 and Section 2 in [I-D.ietf-dots-architecture]). 154 2. Notational Conventions and Terminology 156 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 157 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 158 document are to be interpreted as described in [RFC2119]. 160 The reader should be familiar with the terms defined in 161 [I-D.ietf-dots-architecture]. 163 For simplicity, all of the examples in this document use "/restconf" 164 as the discovered RESTCONF API root path. Many protocol header lines 165 and message-body text within examples throughout the document are 166 split into multiple lines for display purposes only. When a line 167 ends with backslash ('\') as the last character, the line is wrapped 168 for display purposes. It is to be considered to be joined to the 169 next line by deleting the backslash, the following line break, and 170 the leading whitespace of the next line. 172 3. DOTS Data Channel 174 The DOTS data channel is intended to be used for bulk data exchanges 175 between DOTS agents. Unlike the signal channel, which must operate 176 nominally even when confronted with despite signal degradation due to 177 packet loss, the data channel is not expected to be constructed to 178 deal with attack conditions. 180 As the primary function of the data channel is data exchange, a 181 reliable transport is required in order for DOTS agents to detect 182 data delivery success or failure. RESTCONF [RFC8040] over TLS 183 [RFC5246] over TCP is used for DOTS data channel (Figure 2). 184 RESTCONF uses HTTP methods to provide CRUD operations on a conceptual 185 datastore containing YANG-defined data, which is compatible with a 186 server which implements NETCONF datastores. The HTTP POST, PUT, 187 PATCH, and DELETE methods are used to edit data resources represented 188 by DOTS data channel YANG data models. These basic edit operations 189 allow the DOTS data channel running configuration to be altered by a 190 DOTS client. DOTS data channel configuration data and state data can 191 be retrieved with the GET method. HTTP status codes are used to 192 report success or failure for RESTCONF operations. The DOTS client 193 will perform the root resource discovery procedure discussed in 194 Section 3.1 of [RFC8040] to determine the root of the RESTCONF API. 195 After discovering the RESTCONF API root, the DOTS client MUST use 196 this value as the initial part of the path in the request URI, in any 197 subsequent request to the DOTS server. The DOTS server can 198 optionally support retrieval of the YANG modules it supports 199 (Section 3.7 in [RFC8040]), for example, DOTS client can use RESTCONF 200 to retreive the company proprietary YANG model supported by the DOTS 201 server. 203 Note: This document uses RESTCONF, a protocol based on HTTP 204 [RFC7230], for configuring data defined in YANG version 1 [RFC6020] 205 or YANG version 1.1 [RFC7950], using the datastore concepts defined 206 in the Network Configuration Protocol (NETCONF) [RFC6241]. RESTCONF 207 combines the simplicity of the HTTP protocol with the predictability 208 and automation potential of a schema-driven API. RESTCONF offers a 209 simple subset of NETCONF functionality and provides a simplified 210 interface using REST-like API which addresses the needs of the DOTS 211 data channel and hence an optimal choice. 213 +--------------+ 214 | DOTS | 215 +--------------+ 216 | RESTCONF | 217 +--------------+ 218 | TLS | 219 +--------------+ 220 | TCP | 221 +--------------+ 222 | IP | 223 +--------------+ 225 Figure 2: Abstract Layering of DOTS data channel over RESTCONF over 226 TLS 228 JavaScript Object Notation (JSON) [RFC7159] payload is used to 229 propogate data channel specific payload messages that convey request 230 parameters and response information such as errors. This 231 specification uses the encoding rules defined in [RFC7951] for 232 representing DOTS data channel configuration data defined using YANG 233 (Section 3.1) as JSON text. 235 A DOTS client registers itself to its DOTS server(s) in order to set 236 up DOTS data channel related configuration data on the DOTS server 237 and receive state data (i.e., non-configuration data) from the DOTS 238 server. A single DOTS data channel between DOTS agents can be used 239 to exchange multiple requests and multiple responses. To reduce DOTS 240 client and DOTS server workload, DOTS client SHOULD re-use the TLS 241 session. While the communication to the DOTS server is quiescent, 242 the DOTS client MAY probe the server to ensure it has maintained 243 cryptographic state. Such probes can also keep alive firewall or NAT 244 bindings. A TLS heartbeat [RFC6520] verifies the DOTS server still 245 has TLS state by returning a TLS message. 247 3.1. DOTS Data Channel YANG Model 249 3.1.1. Identifier Model structure 251 This document defines a YANG [RFC6020] data model for creating 252 identifers, such as names or aliases, for resources for which 253 mitigation may be requested. Such identifiers may then be used in 254 subsequent DOTS signal channel exchanges to refer more efficiently to 255 the resources under attack. 257 This document defines the YANG module "ietf-dots-data-channel- 258 identifier", which has the following structure: 260 module: ietf-dots-data-channel-identifier 261 +--rw identifier 262 +--rw alias* [alias-name] 263 +--rw alias-name string 264 +--rw ip* inet:ip-address 265 +--rw prefix* inet:ip-prefix 266 +--rw port-range* [lower-port upper-port] 267 | +--rw lower-port inet:port-number 268 | +--rw upper-port inet:port-number 269 +--rw traffic-protocol* uint8 270 +--rw FQDN* inet:domain-name 271 +--rw URI* inet:uri 272 +--rw E.164* string 274 3.1.2. Identifier Model 276 file "ietf-dots-data-channel-identifier@2016-11-28.yang" 278 module ietf-dots-data-channel-identifier { 279 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel-identifier"; 280 prefix "alias"; 281 import ietf-inet-types { 282 prefix "inet"; 284 } 285 organization "Cisco Systems, Inc."; 286 contact "Tirumaleswar Reddy "; 288 description 289 "This module contains YANG definition for 290 configuring identifiers for resources using DOTS data channel"; 292 revision 2016-11-28 { 293 reference 294 "https://tools.ietf.org/html/draft-reddy-dots-data-channel"; 295 } 297 container identifier { 298 description "top level container for identifiers"; 299 list alias { 300 key alias-name; 301 description "list of identifiers"; 302 leaf alias-name { 303 type string; 304 description "alias name"; 305 } 306 leaf-list ip { 307 type inet:ip-address; 308 description "IP address"; 309 } 310 leaf-list prefix { 311 type inet:ip-prefix; 312 description "prefix"; 313 } 314 list port-range { 315 key "lower-port upper-port"; 316 description "Port range. When only lower-port is present, 317 it represents a single port."; 318 leaf lower-port { 319 type inet:port-number; 320 mandatory true; 321 description "lower port"; 322 } 323 leaf upper-port { 324 type inet:port-number; 325 must ". >= ../lower-port" { 326 error-message 327 "The upper-port must be greater than or 328 equal to lower-port"; 329 } 330 description "upper port"; 331 } 333 } 334 leaf-list traffic-protocol { 335 type uint8; 336 description "Internet Protocol number"; 337 } 338 leaf-list FQDN { 339 type inet:domain-name; 340 description "FQDN"; 341 } 342 leaf-list URI { 343 type inet:uri; 344 description "URI"; 345 } 346 leaf-list E.164 { 347 type string; 348 description "E.164 number"; 349 } 350 } 351 } 352 } 353 355 3.1.3. Filter Model and structure 357 This document uses the Access Control List (ACL) YANG data model 358 [I-D.ietf-netmod-acl-model] for the configuration of filtering rules. 359 ACL is explained in Section 1 of [I-D.ietf-netmod-acl-model]. 361 Examples of such configuration include: 363 o Black-list management, which enables a DOTS client to inform the 364 DOTS server about sources from which traffic should be suppressed. 365 o White-list management, which enables a DOTS client to inform the 366 DOTS server about sources from which traffic should always be 367 accepted. 368 o Filter management, which enables a DOTS client to install or 369 remove traffic filters, dropping or rate-limiting unwanted traffic 370 and permitting white-listed traffic. 372 3.2. Identifiers 374 3.2.1. Create Identifiers 376 A POST request is used to create identifiers, such as names or 377 aliases, for resources for which a mitigation may be requested. Such 378 identifiers may then be used in subsequent DOTS signal channel 379 exchanges to refer more efficiently to the resources under attack 380 (Figure 3). 382 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 383 Host: {host}:{port} 384 Content-Format: "application/yang.api+json" 385 { 386 "ietf-dots-data-channel-identifier:identifier": { 387 "alias": [ 388 { 389 "alias-name": "string", 390 "ip": [ 391 "string" 392 ], 393 "prefix": [ 394 "string" 395 ], 396 "port-range": [ 397 { 398 "lower-port": integer, 399 "upper-port": integer 400 } 401 ], 402 "traffic-protocol": [ 403 integer 404 ], 405 "FQDN": [ 406 "string" 407 ], 408 "URI": [ 409 "string" 410 ], 411 "E.164": [ 412 "string" 413 ] 414 } 415 ] 416 } 417 } 419 Figure 3: POST to create identifiers 421 The header parameters are described below: 423 alias-name: Name of the alias. This is a mandatory attribute. 424 traffic-protocol: Internet Protocol numbers. This is an optional 425 attribute. 426 port-range: The port range, lower-port for lower port number and 427 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 429 the range of ports (e.g., 80 to 8080). This is an optional 430 attribute. 431 ip: IP addresses are separated by commas. This is an optional 432 attribute. 433 prefix: Prefixes are separated by commas. This is an optional 434 attribute. 435 FQDN: Fully Qualified Domain Name, is the full name of a system, 436 rather than just its hostname. For example, "venera" is a 437 hostname, and "venera.isi.edu" is an FQDN. This is an optional 438 attribute. 439 URI: Uniform Resource Identifier (URI). This is an optional 440 attribute. 441 E.164: E.164 number. This is an optional attribute. 443 In the POST request at least one of the attributes ip or prefix or 444 FQDN or URI MUST be present. DOTS agents can safely ignore Vendor- 445 Specific parameters they don't understand. 447 Figure 4 shows a POST request to create alias called "https1" for 448 HTTP(S) servers with IP addresses 2002:db8:6401::1 and 449 2002:db8:6401::2 listening on port 443. 451 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 452 Host: www.example.com 453 Content-Format: "application/yang.api+json" 454 { 455 "ietf-dots-data-channel-identifier:identifier": { 456 "alias": [ 457 { 458 "alias-name": "Server1", 459 "traffic-protocol": [ 460 6 461 ], 462 "ip": [ 463 "2002:db8:6401::1", 464 "2002:db8:6401::2" 465 ], 466 "port-range": [ 467 { 468 "lower-port": 443 469 } 470 ] 471 } 472 ] 473 } 474 } 476 Figure 4: POST to create identifiers 478 The DOTS server indicates the result of processing the POST request 479 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 480 codes are some sort of invalid requests and 5xx codes are returned if 481 the DOTS server has erred or it is incapable of accepting the alias. 482 Response code 201 (Created) will be returned in the response if the 483 DOTS server has accepted the alias. If the request is missing one or 484 more mandatory attributes then 400 (Bad Request) will be returned in 485 the response or if the request contains invalid or unknown parameters 486 then 400 (Invalid query) will be returned in the response. The HTTP 487 response will include the JSON body received in the request. 489 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 490 create or modify the aliases in the DOTS server. 492 3.2.2. Delete Identifiers 494 A DELETE request is used to delete identifiers maintained by a DOTS 495 server (Figure 5). 497 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 498 /alias=Server1 HTTP/1.1 499 Host: {host}:{port} 501 Figure 5: DELETE identifier 503 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 504 resource identifier is encoded from left to right, starting with the 505 top-level data node, according to the "api-path" rule defined in 506 Section 3.5.3.1 of [RFC8040]. The data node in the above path 507 expression is a YANG list node and MUST be encoded according to the 508 rules defined in Section 3.5.1 of [RFC8040]. 510 If the DOTS server does not find the alias name conveyed in the 511 DELETE request in its configuration data, then it responds with a 404 512 (Not Found) error response code. The DOTS server successfully 513 acknowledges a DOTS client's request to remove the identifier using 514 204 (No Content) in the response. 516 3.2.3. Retrieving Installed Identifiers 518 A GET request is used to retrieve the set of installed identifiers 519 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 520 to retrieve all the identifiers that were instantiated by the DOTS 521 client. The content parameter and its permitted values are defined 522 in Section 4.8.1 of [RFC8040]. 524 GET /restconf/data/ietf-dots-data-channel-identifier:identifier?\ 525 content=config HTTP/1.1 526 Host: {host}:{port} 527 Accept: application/yang-data+json 529 Figure 6: GET to retrieve all the installed identifiers 531 Figure 7 shows response for all identifiers on the DOTS server. 533 { 534 "ietf-dots-data-channel-identifier:identifier": [ 535 { 536 "alias": [ 537 { 538 "alias-name": "Server1", 539 "traffic-protocol": [ 540 6 541 ], 542 "ip": [ 543 "2002:db8:6401::1", 544 "2002:db8:6401::2" 545 ], 546 "port-range": [ 547 { 548 "lower-port": 443 549 } 550 ] 551 } 552 ] 553 }, 554 { 555 "alias": [ 556 { 557 "alias-name": "Server2", 558 "traffic-protocol": [ 559 6 560 ], 561 "ip": [ 562 "2002:db8:6401::10", 563 "2002:db8:6401::20" 564 ], 565 "port-range": [ 566 { 567 "lower-port": 80 568 } 569 ] 570 } 571 ] 572 } 573 ] 574 } 576 Figure 7: Response body 578 If the DOTS server does not find the alias name conveyed in the GET 579 request in its configuration data, then it responds with a 404 (Not 580 Found) error response code. 582 3.3. Filtering Rules 584 The DOTS server either receives the filtering rules directly from the 585 DOTS client or via the DOTS gateway. If the DOTS client signals the 586 filtering rules via the DOTS gateway then the DOTS gateway validates 587 if the DOTS client is authorized to signal the filtering rules and if 588 the client is authorized propagates the rules to the DOTS server. 589 Likewise, the DOTS server validates if the DOTS gateway is authorized 590 to signal the filtering rules. To create or purge filters, the DOTS 591 client sends HTTP requests to the DOTS gateway. The DOTS gateway 592 validates the rules in the requests and proxies the requests 593 containing the filtering rules to a DOTS server. When the DOTS 594 gateway receives the associated HTTP response from the DOTS server, 595 it propagates the response back to the DOTS client. 597 The following APIs define means for a DOTS client to configure 598 filtering rules on a DOTS server. 600 3.3.1. Install Filtering Rules 602 A POST request is used to push filtering rules to a DOTS server. 603 Figure 8 shows a POST request example to block traffic from 604 10.10.10.1/24, destined to 11.11.11.1/24. The ACL JSON configuration 605 for the filtering rule is generated using the ACL YANG data model 606 defined in [I-D.ietf-netmod-acl-model] and the ACL configuration XML 607 for the filtering rule is specified in Section 4.3 of 608 [I-D.ietf-netmod-acl-model]. This specification updates the ACL YANG 609 data model defined in [I-D.ietf-netmod-acl-model] to support rate- 610 limit action. 612 POST /restconf/data/ietf-access-control-list HTTP/1.1 613 Host: www.example.com 614 Content-Format: "application/yang.api+json" 615 { 616 "ietf-access-control-list:access-lists": { 617 "acl": [ 618 { 619 "acl-name": "sample-ipv4-acl", 620 "acl-type": "ipv4", 621 "access-list-entries": { 622 "ace": [ 623 { 624 "rule-name": "rule1", 625 "matches": { 626 "source-ipv4-network": "10.10.10.1/24", 627 "destination-ipv4-network": "11.11.11.1/24" 628 }, 629 "actions": { 630 "deny": [null] 631 } 632 } 633 ] 634 } 635 } 636 ] 637 } 638 } 640 Figure 8: POST to install filterng rules 642 The header parameters defined in [I-D.ietf-netmod-acl-model] are 643 discussed below: 645 acl-name: The name of access-list. This is a mandatory attribute. 646 acl-type: Indicates the primary intended type of match criteria 647 (e.g. IPv4, IPv6). This is a mandatory attribute. 648 protocol: Internet Protocol numbers. This is an optional 649 attribute. 650 source-ipv4-network: The source IPv4 prefix. This is an optional 651 attribute. 652 destination-ipv4-network: The destination IPv4 prefix. This is an 653 optional attribute. 654 actions: "deny" or "permit" or "rate-limit". "permit" action is 655 used to white-list traffic. "deny" action is used to black-list 656 traffic. "rate-limit" action is used to rate-limit traffic, the 657 allowed traffic rate is represented in bytes per second indicated 658 in IEEE floating point format [IEEE.754.1985]. If actions 659 attribute is not specified in the request then the default action 660 is "deny". This is an optional attribute. 662 The DOTS server indicates the result of processing the POST request 663 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 664 codes are some sort of invalid requests and 5xx codes are returned if 665 the DOTS server has erred or it is incapable of configuring the 666 filtering rules. Response code 201 (Created) will be returned in the 667 response if the DOTS server has accepted the filtering rules. If the 668 request is missing one or more mandatory attributes then 400 (Bad 669 Request) will be returned in the response or if the request contains 670 invalid or unknown parameters then 400 (Invalid query) will be 671 returned in the response. 673 The DOTS client can use the PUT request to create or modify the 674 filtering rules in the DOTS server. 676 3.3.2. Remove Filtering Rules 678 A DELETE request is used to delete filtering rules from a DOTS server 679 (Figure 9). 681 DELETE /restconf/data/ietf-access-control-list:access-lists/acl-name\ 682 =sample-ipv4-acl&acl-type=ipv4 HTTP/1.1 683 Host: {host}:{port} 685 Figure 9: DELETE to remove the filtering rules 687 If the DOTS server does not find the access list name and access list 688 type conveyed in the DELETE request in its configuration data, then 689 it responds with a 404 (Not Found) error response code. The DOTS 690 server successfully acknowledges a DOTS client's request to withdraw 691 the filtering rules using 204 (No Content) response code, and removes 692 the filtering rules as soon as possible. 694 3.3.3. Retrieving Installed Filtering Rules 696 The DOTS client periodically queries the DOTS server to check the 697 counters for installed filtering rules. A GET request is used to 698 retrieve filtering rules from a DOTS server. Figure 10 shows how to 699 retrieve all the filtering rules programmed by the DOTS client and 700 the number of matches for the installed filtering rules. 702 GET /restconf/data/ietf-access-control-list:access-lists?content=all HTTP/1.1 703 Host: {host}:{port} 704 Accept: application/yang-data+json 706 Figure 10: GET to retrieve the configuration data and state data for 707 the filtering rules 709 If the DOTS server does not find the access list name and access list 710 type conveyed in the GET request in its configuration data, then it 711 responds with a 404 (Not Found) error response code. 713 4. IANA Considerations 715 This specification registers new parameters for the DOTS data channel 716 and establishes registries for mappings to JSON attributes. 718 4.1. DOTS Data Channel JSON Attribute Mappings Registry 720 A new registry will be requested from IANA, entitled "DOTS data 721 channel JSON attribute Mappings Registry". The registry is to be 722 created as Expert Review Required. 724 4.2. Registration Template 726 JSON Attribute: 727 JSON attribute name. 728 Description: 729 Brief description of the attribute. 730 Change Controller: 731 For Standards Track RFCs, list the "IESG". For others, give the 732 name of the responsible party. Other details (e.g., postal 733 address, email address, home page URI) may also be included. 734 Specification Document(s): 735 Reference to the document or documents that specify the parameter, 736 preferably including URIs that can be used to retrieve copies of 737 the documents. An indication of the relevant sections may also be 738 included but is not required. 740 4.3. Initial Registry Contents 742 o JSON Attribute: "alias-name" 743 o Description: Name of alias. 744 o Change Controller: IESG 745 o Specification Document(s): this document 747 o JSON Attribute: "traffic-protocol" 748 o Description: Internet protocol numbers. 749 o Change Controller: IESG 750 o Specification Document(s): this document 752 o JSON Attribute: "port-range" 753 o Description: The port range, lower-port for lower port number and 754 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 755 the range of ports (e.g., 80 to 8080). 756 o Change Controller: IESG 757 o Specification Document(s): this document 759 o JSON Attribute: "lower-port" 760 o Description: Lower port number for port range. 761 o Change Controller: IESG 762 o Specification Document(s): this document 764 o JSON Attribute: "upper-port" 765 o Description: Upper port number for port range. 766 o Change Controller: IESG 767 o Specification Document(s): this document 769 o JSON Attribute: "ip" 770 o Description: IP address. 771 o Change Controller: IESG 772 o Specification Document(s): this document 774 o JSON Attribute: "prefix" 775 o Description: IP prefix 776 o Change Controller: IESG 777 o Specification Document(s): this document 779 o JSON Attribute: "FQDN" 780 o Description: Fully Qualified Domain Name, is the full name of a 781 system, rather than just its hostname. For example, "venera" is a 782 hostname, and "venera.isi.edu" is an FQDN. 783 o Change Controller: IESG 784 o Specification Document(s): this document 786 o JSON Attribute: "URI" 787 o Description: Uniform Resource Identifier (URI). 788 o Change Controller: IESG 789 o Specification Document(s): this document 791 o JSON Attribute: "E.164" 792 o Description: E.164 number. 793 o Change Controller: IESG 794 o Specification Document(s): this document 796 5. Contributors 798 The following individuals have contributed to this document: 800 Dan Wing Email: dwing-ietf@fuggles.com 802 6. Security Considerations 804 Authenticated encryption MUST be used for data confidentiality and 805 message integrity. TLS based on client certificate MUST be used for 806 mutual authentication. The interaction between the DOTS agents 807 requires Transport Layer Security (TLS) with a cipher suite offering 808 confidentiality protection and the guidance given in [RFC7525] MUST 809 be followed to avoid attacks on TLS. 811 An attacker may be able to inject RST packets, bogus application 812 segments, etc., regardless of whether TLS authentication is used. 813 Because the application data is TLS protected, this will not result 814 in the application receiving bogus data, but it will constitute a DoS 815 on the connection. This attack can be countered by using TCP-AO 816 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 817 attacker will be rejected by the TCP-AO integrity check and therefore 818 will never reach the TLS layer. 820 Special care should be taken in order to ensure that the activation 821 of the proposed mechanism won't have an impact on the stability of 822 the network (including connectivity and services delivered over that 823 network). 825 Involved functional elements in the cooperation system must establish 826 exchange instructions and notification over a secure and 827 authenticated channel. Adequate filters can be enforced to avoid 828 that nodes outside a trusted domain can inject request such as 829 deleting filtering rules. Nevertheless, attacks can be initiated 830 from within the trusted domain if an entity has been corrupted. 831 Adequate means to monitor trusted nodes should also be enabled. 833 7. Acknowledgements 835 Thanks to Christian Jacquenet, Roland Dobbins, Andrew Mortensen, 836 Roman Danyliw, Ehud Doron and Gilbert Clark for the discussion and 837 comments. 839 8. References 840 8.1. Normative References 842 [I-D.ietf-dots-architecture] 843 Mortensen, A., Andreasen, F., Reddy, T., 844 christopher_gray3@cable.comcast.com, c., Compton, R., and 845 N. Teague, "Distributed-Denial-of-Service Open Threat 846 Signaling (DOTS) Architecture", draft-ietf-dots- 847 architecture-01 (work in progress), October 2016. 849 [I-D.ietf-netmod-acl-model] 850 Bogdanovic, D., Koushik, K., Huang, L., and D. Blair, 851 "Network Access Control List (ACL) YANG Data Model", 852 draft-ietf-netmod-acl-model-09 (work in progress), October 853 2016. 855 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 856 Requirement Levels", BCP 14, RFC 2119, 857 DOI 10.17487/RFC2119, March 1997, 858 . 860 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 861 (TLS) Protocol Version 1.2", RFC 5246, 862 DOI 10.17487/RFC5246, August 2008, 863 . 865 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 866 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 867 June 2010, . 869 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 870 "Recommendations for Secure Use of Transport Layer 871 Security (TLS) and Datagram Transport Layer Security 872 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 873 2015, . 875 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 876 RFC 7951, DOI 10.17487/RFC7951, August 2016, 877 . 879 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 880 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 881 . 883 8.2. Informative References 885 [I-D.ietf-dots-requirements] 886 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 887 Denial of Service (DDoS) Open Threat Signaling 888 Requirements", draft-ietf-dots-requirements-03 (work in 889 progress), October 2016. 891 [I-D.reddy-dots-signal-channel] 892 Reddy, T., Boucadair, M., and P. Patil, "Distributed 893 Denial-of-Service Open Threat Signaling (DOTS) Signal 894 Channel", draft-reddy-dots-signal-channel-09 (work in 895 progress), March 2017. 897 [IEEE.754.1985] 898 Institute of Electrical and Electronics Engineers, 899 "Standard for Binary Floating-Point Arithmetic", August 900 1985. 902 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 903 the Network Configuration Protocol (NETCONF)", RFC 6020, 904 DOI 10.17487/RFC6020, October 2010, 905 . 907 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 908 Layer Security (TLS) and Datagram Transport Layer Security 909 (DTLS) Heartbeat Extension", RFC 6520, 910 DOI 10.17487/RFC6520, February 2012, 911 . 913 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 914 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 915 2014, . 917 Authors' Addresses 919 Tirumaleswar Reddy 920 Cisco Systems, Inc. 921 Cessna Business Park, Varthur Hobli 922 Sarjapur Marathalli Outer Ring Road 923 Bangalore, Karnataka 560103 924 India 926 Email: tireddy@cisco.com 927 Mohamed Boucadair 928 Orange 929 Rennes 35000 930 France 932 Email: mohamed.boucadair@orange.com 934 Kaname Nishizuka 935 NTT Communications 936 GranPark 16F 3-4-1 Shibaura, Minato-ku 937 Tokyo 108-8118 938 Japan 940 Email: kaname@nttv6.jp 942 Liang Xia 943 Huawei 944 101 Software Avenue, Yuhuatai District 945 Nanjing, Jiangsu 210012 946 China 948 Email: frank.xialiang@huawei.com 950 Prashanth Patil 951 Cisco Systems, Inc. 953 Email: praspati@cisco.com 955 Andrew Mortensen 956 Arbor Networks, Inc. 957 2727 S. State St 958 Ann Arbor, MI 48104 959 United States 961 Email: amortensen@arbor.net 963 Nik Teague 964 Verisign, Inc. 965 United States 967 Email: nteague@verisign.com