idnits 2.17.1 draft-ietf-dots-data-channel-02.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 10 instances of too long lines in the document, the longest one being 63 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 268 has weird spacing: '...er-port ine...' == Line 269 has weird spacing: '...er-port ine...' -- The document date (June 22, 2017) is 2500 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) == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-03 ** 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-11 ** 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 (-22) exists of draft-ietf-dots-requirements-05 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-02 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 5 errors (**), 0 flaws (~~), 7 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair 5 Expires: December 24, 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 June 22, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-ietf-dots-data-channel-02 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 December 24, 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 structure . . . . . . . . . . . . . . . 8 70 3.1.4. Filter Model . . . . . . . . . . . . . . . . . . . . 9 71 3.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 11 72 3.2.1. Create Identifiers . . . . . . . . . . . . . . . . . 11 73 3.2.2. Delete Identifiers . . . . . . . . . . . . . . . . . 13 74 3.2.3. Retrieving Installed Identifiers . . . . . . . . . . 14 75 3.3. Filtering Rules . . . . . . . . . . . . . . . . . . . . . 16 76 3.3.1. Install Filtering Rules . . . . . . . . . . . . . . . 16 77 3.3.2. Remove Filtering Rules . . . . . . . . . . . . . . . 18 78 3.3.3. Retrieving Installed Filtering Rules . . . . . . . . 18 79 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 80 4.1. DOTS Data Channel JSON Attribute Mappings Registry . . . 19 81 4.2. Registration Template . . . . . . . . . . . . . . . . . . 19 82 4.3. Initial Registry Contents . . . . . . . . . . . . . . . . 19 83 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 21 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 85 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 86 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 87 8.1. Normative References . . . . . . . . . . . . . . . . . . 22 88 8.2. Informative References . . . . . . . . . . . . . . . . . 23 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 91 1. Introduction 93 A distributed denial-of-service (DDoS) attack is an attempt to make 94 machines or network resources unavailable to their intended users. 95 In most cases, sufficient scale can be achieved by compromising 96 enough end-hosts and using those infected hosts to perpetrate and 97 amplify the attack. The victim in this attack can be an application 98 server, a client, a router, a firewall, or an entire network. 100 DDoS Open Threat Signaling (DOTS) defines two channels: signal and 101 data channels [I-D.ietf-dots-architecture] (Figure 1). The DOTS 102 signal channel used to convey that a network is under a DDOS attack 103 to an upstream DOTS server so that appropriate mitigation actions are 104 undertaken on the suspect traffic is further elaborated in 105 [I-D.ietf-dots-signal-channel]. The DOTS data channel is used for 106 infrequent bulk data exchange between DOTS agents in the aim to 107 significantly augment attack response coordination. 109 +---------------+ +---------------+ 110 | | <------- Signal Channel ------> | | 111 | DOTS Client | | DOTS Server | 112 | | <======= Data Channel ======> | | 113 +---------------+ +---------------+ 115 Figure 1: DOTS Channels 117 Section 2 of [I-D.ietf-dots-architecture] identifies that the DOTS 118 data channel is used to perform the tasks listed below: 120 o Filter management, which enables a DOTS client to request the 121 installation or removal of traffic filters, dropping or rate- 122 limiting unwanted traffic and permitting white-listed traffic. 123 Sample use cases for populating black- or white-list filtering 124 rules are detailed hereafter: 126 A. If a network resource (DOTS client) detects a potential DDoS 127 attack from a set of IP addresses, the DOTS client informs its 128 servicing router (DOTS gateway) of all suspect IP addresses 129 that need to be blocked or black-listed for further 130 investigation. The DOTS client could also specify a list of 131 protocols and ports in the black-list rule. That DOTS gateway 132 in-turn propagates the black-listed IP addresses to the DOTS 133 server which will undertake appropriate action so that traffic 134 from these IP addresses to the target network (specified by 135 the DOTS client) is blocked. 137 B. A network has partner sites from which only legitimate traffic 138 arrives and the network wants to ensure that the traffic from 139 these sites is not penalized during DDOS attacks. The DOTS 140 client uses the DOTS data channel to convey the white-listed 141 IP addresses or prefixes of the partner sites to its DOTS 142 server. The DOTS server uses this information to white-list 143 flows from such IP addresses or prefixes reaching the network. 145 o Creating identifiers, such as names or aliases, for resources for 146 which mitigation may be requested: 148 A. The DOTS client may submit to the DOTS server a collection of 149 prefixes which it would like to refer to by alias when 150 requesting mitigation. The server can respond to this request 151 with either with a success or failure response (see 152 requirement OP-006 in [I-D.ietf-dots-requirements] and 153 Section 2 in [I-D.ietf-dots-architecture]). 155 2. Notational Conventions and Terminology 157 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 158 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 159 document are to be interpreted as described in [RFC2119]. 161 The reader should be familiar with the terms defined in 162 [I-D.ietf-dots-architecture]. 164 For simplicity, all of the examples in this document use "/restconf" 165 as the discovered RESTCONF API root path. Many protocol header lines 166 and message-body text within examples throughout the document are 167 split into multiple lines for display purposes only. When a line 168 ends with backslash ('\') as the last character, the line is wrapped 169 for display purposes. It is to be considered to be joined to the 170 next line by deleting the backslash, the following line break, and 171 the leading whitespace of the next line. 173 3. DOTS Data Channel 175 The DOTS data channel is intended to be used for bulk data exchanges 176 between DOTS agents. Unlike the signal channel, which must operate 177 nominally even when confronted with signal degradation due to packet 178 loss, the data channel is not expected to be constructed to deal with 179 DDoS attack conditions. 181 As the primary function of the data channel is data exchange, a 182 reliable transport is required in order for DOTS agents to detect 183 data delivery success or failure. RESTCONF [RFC8040] over TLS 184 [RFC5246] over TCP is used for DOTS data channel (Figure 2). 185 RESTCONF uses HTTP methods to provide CRUD operations on a conceptual 186 datastore containing YANG-defined data, which is compatible with a 187 server which implements NETCONF datastores. The HTTP POST, PUT, 188 PATCH, and DELETE methods are used to edit data resources represented 189 by DOTS data channel YANG data models. These basic edit operations 190 allow the DOTS data channel running configuration to be altered by a 191 DOTS client. DOTS data channel configuration data and state data can 192 be retrieved with the GET method. HTTP status codes are used to 193 report success or failure for RESTCONF operations. The DOTS client 194 will perform the root resource discovery procedure discussed in 195 Section 3.1 of [RFC8040] to determine the root of the RESTCONF API. 196 After discovering the RESTCONF API root, the DOTS client MUST use 197 this value as the initial part of the path in the request URI, in any 198 subsequent request to the DOTS server. The DOTS server can 199 optionally support retrieval of the YANG modules it supports 200 (Section 3.7 in [RFC8040]), for example, DOTS client can use RESTCONF 201 to retrieve the company proprietary YANG model supported by the DOTS 202 server. 204 Note: This document uses RESTCONF, a protocol based on HTTP 205 [RFC7230], for configuring data defined in YANG version 1 [RFC6020] 206 or YANG version 1.1 [RFC7950], using the datastore concepts defined 207 in the Network Configuration Protocol (NETCONF) [RFC6241]. RESTCONF 208 combines the simplicity of the HTTP protocol with the predictability 209 and automation potential of a schema-driven API. RESTCONF offers a 210 simple subset of NETCONF functionality and provides a simplified 211 interface using REST-like API which addresses the needs of the DOTS 212 data channel and hence an optimal choice. 214 +--------------+ 215 | DOTS | 216 +--------------+ 217 | RESTCONF | 218 +--------------+ 219 | TLS | 220 +--------------+ 221 | TCP | 222 +--------------+ 223 | IP | 224 +--------------+ 226 Figure 2: Abstract Layering of DOTS data channel over RESTCONF over 227 TLS 229 JavaScript Object Notation (JSON) [RFC7159] payload is used to 230 propagate data channel specific payload messages that convey request 231 parameters and response information such as errors. This 232 specification uses the encoding rules defined in [RFC7951] for 233 representing DOTS data channel configuration data defined using YANG 234 (Section 3.1) as JSON text. 236 A DOTS client registers itself to its DOTS server(s) in order to set 237 up DOTS data channel related configuration data on the DOTS server 238 and receive state data (i.e., non-configuration data) from the DOTS 239 server. A single DOTS data channel between DOTS agents can be used 240 to exchange multiple requests and multiple responses. To reduce DOTS 241 client and DOTS server workload, DOTS client SHOULD re-use the TLS 242 session. While the communication to the DOTS server is quiescent, 243 the DOTS client MAY probe the server to ensure it has maintained 244 cryptographic state. Such probes can also keep alive firewall or NAT 245 bindings. A TLS heartbeat [RFC6520] verifies the DOTS server still 246 has TLS state by returning a TLS message. 248 3.1. DOTS Data Channel YANG Model 250 3.1.1. Identifier Model structure 252 This document defines a YANG [RFC6020] data model for creating 253 identifiers, such as names or aliases, for resources for which 254 mitigation may be requested. Such identifiers may then be used in 255 subsequent DOTS signal channel exchanges to refer more efficiently to 256 the resources under attack. 258 This document defines the YANG module "ietf-dots-data-channel- 259 identifier", which has the following structure: 261 module: ietf-dots-data-channel-identifier 262 +--rw identifier 263 +--rw alias* [alias-name] 264 +--rw alias-name string 265 +--rw ip* inet:ip-address 266 +--rw prefix* inet:ip-prefix 267 +--rw port-range* [lower-port upper-port] 268 | +--rw lower-port inet:port-number 269 | +--rw upper-port inet:port-number 270 +--rw traffic-protocol* uint8 271 +--rw fqdn* inet:domain-name 272 +--rw uri* inet:uri 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"; 283 } 285 organization "McAfee, Inc."; 286 contact "Konda, 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 317 "Port range. When only lower-port is present, 318 it represents a single port."; 319 leaf lower-port { 320 type inet:port-number; 321 mandatory true; 322 description "lower port"; 323 } 324 leaf upper-port { 325 type inet:port-number; 326 must ". >= ../lower-port" { 327 error-message 328 "The upper-port must be greater than or 329 equal to lower-port"; 330 } 331 description "upper port"; 332 } 334 } 335 leaf-list traffic-protocol { 336 type uint8; 337 description "Internet Protocol number"; 338 } 339 leaf-list fqdn { 340 type inet:domain-name; 341 description "FQDN"; 342 } 343 leaf-list uri { 344 type inet:uri; 345 description "URI"; 346 } 347 } 348 } 349 } 350 352 3.1.3. Filter Model structure 354 This document extends the "ietf-access-control-list" Access Control 355 List (ACL) YANG data model [I-D.ietf-netmod-acl-model] for the 356 configuration of filtering rules. ACL is explained in Section 1 of 357 [I-D.ietf-netmod-acl-model]. 359 Examples of such configuration include: 361 o Black-list management, which enables a DOTS client to inform the 362 DOTS server about sources from which traffic should be suppressed. 364 o White-list management, which enables a DOTS client to inform the 365 DOTS server about sources from which traffic should always be 366 accepted. 368 o Filter management, which enables a DOTS client to request the 369 installation or removal of traffic filters, dropping or rate- 370 limiting unwanted traffic and permitting white-listed traffic. 372 This document defines the YANG module "ietf-dots-access-control-list" 373 to extend the "ietf-access-control-list" module to handle fragmented 374 packets and to support rate-limit action. Filtering fragments adds 375 an additional layer of protection against a denial-of-service (DoS) 376 attack that uses only noninitial fragments. When there is only Layer 377 3 information in the ACL entry and the fragments keyword is present, 378 for noninitial fragments matching the ACL entry, the deny or permit 379 action associated with the ACL entry will be enforced and for initial 380 or non-fragment matching the ACL entry, the the next ACL entry will 381 be processed. When there is both Layer 3 and Layer 4 information in 382 the ACL entry and the fragments keyword is present, the ACL action is 383 conservative for both permit and deny actions. The actions are 384 conservative to not accidentally deny a fragmented portion of a flow 385 because the fragments do not contain sufficient information to match 386 all of the filter attributes. In the deny action case, instead of 387 denying a non-initial fragment, the next ACL entry is processed. In 388 the permit case, it is assumed that the Layer 4 information in the 389 packet, if available, matches the Layer 4 information in the ACL 390 entry. 392 The "ietf-dots-access-control-list" module has the following 393 structure: 395 module: ietf-dots-access-control-list 396 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:actions/ietf-acl:packet-handling: 397 +--:(rate-limit) 398 +--rw rate-limit? decimal64 399 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace: 400 +--rw fragments? empty 402 3.1.4. Filter Model 404 This YANG module augments the "ietf-access-control-list" YANG data 405 model defined in [I-D.ietf-netmod-acl-model]. 407 file "ietf-dots-access-control-list@2017-06-12.yang" 409 module ietf-dots-access-control-list { 410 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-access-control-list"; 411 prefix "dots-acl"; 412 import ietf-access-control-list { 413 prefix "ietf-acl"; 414 } 415 organization "McAfee, Inc."; 416 contact "Konda, Tirumaleswar Reddy "; 418 description 419 "This module contains YANG definition for 420 configuring filtering rules using DOTS data channel"; 422 revision 2017-06-12 { 423 reference 424 "https://tools.ietf.org/html/draft-ietf-dots-data-channel"; 425 } 427 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace/ietf-acl:actions/ietf-acl:packet-handling" { 429 description "rate-limit action"; 431 case rate-limit { 432 leaf rate-limit { 433 type decimal64 { 434 fraction-digits 2; 435 } 436 description "rate-limit action."; 437 } 438 } 439 } 441 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:access-list-entries/ietf-acl:ace" { 443 description "handle non-intial and initial fragments"; 445 leaf fragments { 446 type empty; 447 description "handle fragments."; 448 } 449 } 450 } 451 453 3.2. Identifiers 455 3.2.1. Create Identifiers 457 A POST request is used to create identifiers, such as names or 458 aliases, for resources for which a mitigation may be requested. Such 459 identifiers may then be used in subsequent DOTS signal channel 460 exchanges to refer more efficiently to the resources under attack 461 (Figure 3). 463 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 464 Host: {host}:{port} 465 Content-Format: "application/yang.api+json" 466 { 467 "ietf-dots-data-channel-identifier:identifier": { 468 "alias": [ 469 { 470 "alias-name": "string", 471 "ip": [ 472 "string" 473 ], 474 "prefix": [ 475 "string" 476 ], 477 "port-range": [ 478 { 479 "lower-port": integer, 480 "upper-port": integer 481 } 482 ], 483 "traffic-protocol": [ 484 integer 485 ], 486 "fqdn": [ 487 "string" 488 ], 489 "uri": [ 490 "string" 491 ] 492 } 493 ] 494 } 495 } 497 Figure 3: POST to create identifiers 499 The header parameters are described below: 501 alias-name: Name of the alias. This is a mandatory attribute. 503 traffic-protocol: Internet Protocol numbers. This is an optional 504 attribute. 506 port-range: The port range, lower-port for lower port number and 507 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 508 the range of ports (e.g., 80 to 8080). This is an optional 509 attribute. 511 ip: IP addresses are separated by commas. This is an optional 512 attribute. 514 prefix: Prefixes are separated by commas. This is an optional 515 attribute. 517 fqdn: Fully Qualified Domain Name, is the full name of a system, 518 rather than just its hostname. For example, "venera" is a 519 hostname, and "venera.isi.edu" is an FQDN. This is an optional 520 attribute. 522 uri: Uniform Resource Identifier (URI). This is an optional 523 attribute. 525 In the POST request at least one of the attributes ip or prefix or 526 fqdn or uri MUST be present. DOTS agents can safely ignore Vendor- 527 Specific parameters they don't understand. 529 Figure 4 shows a POST request to create alias called "https1" for 530 HTTP(S) servers with IP addresses 2001:db8:6401::1 and 531 2001:db8:6401::2 listening on port 443. 533 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 534 Host: www.example.com 535 Content-Format: "application/yang.api+json" 536 { 537 "ietf-dots-data-channel-identifier:identifier": { 538 "alias": [ 539 { 540 "alias-name": "Server1", 541 "traffic-protocol": [ 542 6 543 ], 544 "ip": [ 545 "2001:db8:6401::1", 546 "2001:db8:6401::2" 547 ], 548 "port-range": [ 549 { 550 "lower-port": 443 551 } 552 ] 553 } 554 ] 555 } 556 } 558 Figure 4: POST to create identifiers 560 The DOTS server indicates the result of processing the POST request 561 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 562 codes are some sort of invalid requests and 5xx codes are returned if 563 the DOTS server has erred or it is incapable of accepting the alias. 564 Response code 201 (Created) will be returned in the response if the 565 DOTS server has accepted the alias. If the request is missing one or 566 more mandatory attributes then 400 (Bad Request) will be returned in 567 the response or if the request contains invalid or unknown parameters 568 then 400 (Invalid query) will be returned in the response. The HTTP 569 response will include the JSON body received in the request. 571 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 572 create or modify the aliases in the DOTS server. 574 3.2.2. Delete Identifiers 576 A DELETE request is used to delete identifiers maintained by a DOTS 577 server (Figure 5). 579 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 580 /alias=Server1 HTTP/1.1 581 Host: {host}:{port} 583 Figure 5: DELETE identifier 585 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 586 resource identifier is encoded from left to right, starting with the 587 top-level data node, according to the "api-path" rule defined in 588 Section 3.5.3.1 of [RFC8040]. The data node in the above path 589 expression is a YANG list node and MUST be encoded according to the 590 rules defined in Section 3.5.1 of [RFC8040]. 592 If the DOTS server does not find the alias name conveyed in the 593 DELETE request in its configuration data, then it responds with a 404 594 (Not Found) error response code. The DOTS server successfully 595 acknowledges a DOTS client's request to remove the identifier using 596 204 (No Content) in the response. 598 3.2.3. Retrieving Installed Identifiers 600 A GET request is used to retrieve the set of installed identifiers 601 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 602 to retrieve all the identifiers that were instantiated by the DOTS 603 client. The content parameter and its permitted values are defined 604 in Section 4.8.1 of [RFC8040]. 606 GET /restconf/data/ietf-dots-data-channel-identifier:identifier?\ 607 content=config HTTP/1.1 608 Host: {host}:{port} 609 Accept: application/yang-data+json 611 Figure 6: GET to retrieve all the installed identifiers 613 Figure 7 shows response for all identifiers on the DOTS server. 615 { 616 "ietf-dots-data-channel-identifier:identifier": [ 617 { 618 "alias": [ 619 { 620 "alias-name": "Server1", 621 "traffic-protocol": [ 622 6 623 ], 624 "ip": [ 625 "2001:db8:6401::1", 626 "2001:db8:6401::2" 627 ], 628 "port-range": [ 629 { 630 "lower-port": 443 631 } 632 ] 633 } 634 ] 635 }, 636 { 637 "alias": [ 638 { 639 "alias-name": "Server2", 640 "traffic-protocol": [ 641 6 642 ], 643 "ip": [ 644 "2001:db8:6401::10", 645 "2001:db8:6401::20" 646 ], 647 "port-range": [ 648 { 649 "lower-port": 80 650 } 651 ] 652 } 653 ] 654 } 655 ] 656 } 658 Figure 7: Response body 660 If the DOTS server does not find the alias name conveyed in the GET 661 request in its configuration data, then it responds with a 404 (Not 662 Found) error response code. 664 3.3. Filtering Rules 666 The DOTS server either receives the filtering rules directly from the 667 DOTS client or via the DOTS gateway. If the DOTS client signals the 668 filtering rules via the DOTS gateway then the DOTS gateway validates 669 if the DOTS client is authorized to signal the filtering rules and if 670 the client is authorized propagates the rules to the DOTS server. 671 Likewise, the DOTS server validates if the DOTS gateway is authorized 672 to signal the filtering rules. To create or purge filters, the DOTS 673 client sends HTTP requests to the DOTS gateway. The DOTS gateway 674 validates the rules in the requests and proxies the requests 675 containing the filtering rules to a DOTS server. When the DOTS 676 gateway receives the associated HTTP response from the DOTS server, 677 it propagates the response back to the DOTS client. 679 The following APIs define means for a DOTS client to configure 680 filtering rules on a DOTS server. 682 3.3.1. Install Filtering Rules 684 A POST request is used to push filtering rules to a DOTS server. 685 Figure 8 shows a POST request example to block traffic from 686 192.0.2.0/24, destined to 198.51.100.0/24. The ACL JSON 687 configuration for the filtering rule is generated using the ACL YANG 688 data model defined in [I-D.ietf-netmod-acl-model] and the ACL 689 configuration XML for the filtering rule is specified in Section 4.3 690 of [I-D.ietf-netmod-acl-model]. 692 POST /restconf/data/ietf-access-control-list HTTP/1.1 693 Host: www.example.com 694 Content-Format: "application/yang.api+json" 695 { 696 "ietf-access-control-list:access-lists": { 697 "acl": [ 698 { 699 "acl-name": "sample-ipv4-acl", 700 "acl-type": "ipv4", 701 "access-list-entries": { 702 "ace": [ 703 { 704 "rule-name": "rule1", 705 "matches": { 706 "source-ipv4-network": "192.0.2.0/24", 707 "destination-ipv4-network": "198.51.100.0/24" 708 }, 709 "actions": { 710 "deny": [null] 711 } 712 } 713 ] 714 } 715 } 716 ] 717 } 718 } 720 Figure 8: POST to install filterng rules 722 The header parameters defined in [I-D.ietf-netmod-acl-model] are 723 discussed below: 725 acl-name: The name of access-list. This is a mandatory attribute. 727 acl-type: Indicates the primary intended type of match criteria 728 (e.g. IPv4, IPv6). This is a mandatory attribute. 730 protocol: Internet Protocol numbers. This is an optional 731 attribute. 733 source-ipv4-network: The source IPv4 prefix. This is an optional 734 attribute. 736 destination-ipv4-network: The destination IPv4 prefix. This is an 737 optional attribute. 739 actions: "deny" or "permit" or "rate-limit". "permit" action is 740 used to white-list traffic. "deny" action is used to black-list 741 traffic. "rate-limit" action is used to rate-limit traffic, the 742 allowed traffic rate is represented in bytes per second indicated 743 in IEEE floating point format [IEEE.754.1985]. If actions 744 attribute is not specified in the request then the default action 745 is "deny". This is an optional attribute. 747 The DOTS server indicates the result of processing the POST request 748 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 749 codes are some sort of invalid requests and 5xx codes are returned if 750 the DOTS server has erred or it is incapable of configuring the 751 filtering rules. Response code 201 (Created) will be returned in the 752 response if the DOTS server has accepted the filtering rules. If the 753 request is missing one or more mandatory attributes then 400 (Bad 754 Request) will be returned in the response or if the request contains 755 invalid or unknown parameters then 400 (Invalid query) will be 756 returned in the response. 758 The DOTS client can use the PUT request to create or modify the 759 filtering rules in the DOTS server. 761 3.3.2. Remove Filtering Rules 763 A DELETE request is used to delete filtering rules from a DOTS server 764 (Figure 9). 766 DELETE /restconf/data/ietf-access-control-list:access-lists/acl-name\ 767 =sample-ipv4-acl&acl-type=ipv4 HTTP/1.1 768 Host: {host}:{port} 770 Figure 9: DELETE to remove the filtering rules 772 If the DOTS server does not find the access list name and access list 773 type conveyed in the DELETE request in its configuration data, then 774 it responds with a 404 (Not Found) error response code. The DOTS 775 server successfully acknowledges a DOTS client's request to withdraw 776 the filtering rules using 204 (No Content) response code, and removes 777 the filtering rules as soon as possible. 779 3.3.3. Retrieving Installed Filtering Rules 781 The DOTS client periodically queries the DOTS server to check the 782 counters for installed filtering rules. A GET request is used to 783 retrieve filtering rules from a DOTS server. Figure 10 shows how to 784 retrieve all the filtering rules programmed by the DOTS client and 785 the number of matches for the installed filtering rules. 787 GET /restconf/data/ietf-access-control-list:access-lists?content=all HTTP/1.1 788 Host: {host}:{port} 789 Accept: application/yang-data+json 791 Figure 10: GET to retrieve the configuration data and state data for 792 the filtering rules 794 If the DOTS server does not find the access list name and access list 795 type conveyed in the GET request in its configuration data, then it 796 responds with a 404 (Not Found) error response code. 798 4. IANA Considerations 800 This specification registers new parameters for the DOTS data channel 801 and establishes registries for mappings to JSON attributes. 803 4.1. DOTS Data Channel JSON Attribute Mappings Registry 805 A new registry will be requested from IANA, entitled "DOTS data 806 channel JSON attribute Mappings Registry". The registry is to be 807 created as Expert Review Required. 809 4.2. Registration Template 811 JSON Attribute: 812 JSON attribute name. 814 Description: 815 Brief description of the attribute. 817 Change Controller: 818 For Standards Track RFCs, list the "IESG". For others, give the 819 name of the responsible party. Other details (e.g., postal 820 address, email address, home page URI) may also be included. 822 Specification Document(s): 823 Reference to the document or documents that specify the parameter, 824 preferably including URIs that can be used to retrieve copies of 825 the documents. An indication of the relevant sections may also be 826 included but is not required. 828 4.3. Initial Registry Contents 830 o JSON Attribute: "alias-name" 831 o Description: Name of alias. 832 o Change Controller: IESG 833 o Specification Document(s): this document 834 o JSON Attribute: "traffic-protocol" 835 o Description: Internet protocol numbers. 836 o Change Controller: IESG 837 o Specification Document(s): this document 839 o JSON Attribute: "port-range" 840 o Description: The port range, lower-port for lower port number and 841 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 842 the range of ports (e.g., 80 to 8080). 843 o Change Controller: IESG 844 o Specification Document(s): this document 846 o JSON Attribute: "lower-port" 847 o Description: Lower port number for port range. 848 o Change Controller: IESG 849 o Specification Document(s): this document 851 o JSON Attribute: "upper-port" 852 o Description: Upper port number for port range. 853 o Change Controller: IESG 854 o Specification Document(s): this document 856 o JSON Attribute: "ip" 857 o Description: IP address. 858 o Change Controller: IESG 859 o Specification Document(s): this document 861 o JSON Attribute: "prefix" 862 o Description: IP prefix 863 o Change Controller: IESG 864 o Specification Document(s): this document 866 o JSON Attribute: "fqdn" 867 o Description: Fully Qualified Domain Name, is the full name of a 868 system, rather than just its hostname. For example, "venera" is a 869 hostname, and "venera.isi.edu" is an FQDN. 870 o Change Controller: IESG 871 o Specification Document(s): this document 873 o JSON Attribute: "uri" 874 o Description: Uniform Resource Identifier (URI). 875 o Change Controller: IESG 876 o Specification Document(s): this document 878 5. Contributors 880 The following individuals have contributed to this document: 882 Dan Wing 884 Email: dwing-ietf@fuggles.com 886 6. Security Considerations 888 Authenticated encryption MUST be used for data confidentiality and 889 message integrity. TLS based on client certificate MUST be used for 890 mutual authentication. The interaction between the DOTS agents 891 requires Transport Layer Security (TLS) with a cipher suite offering 892 confidentiality protection and the guidance given in [RFC7525] MUST 893 be followed to avoid attacks on TLS. 895 An attacker may be able to inject RST packets, bogus application 896 segments, etc., regardless of whether TLS authentication is used. 897 Because the application data is TLS protected, this will not result 898 in the application receiving bogus data, but it will constitute a DoS 899 on the connection. This attack can be countered by using TCP-AO 900 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 901 attacker will be rejected by the TCP-AO integrity check and therefore 902 will never reach the TLS layer. 904 Special care should be taken in order to ensure that the activation 905 of the proposed mechanism won't have an impact on the stability of 906 the network (including connectivity and services delivered over that 907 network). 909 Involved functional elements in the cooperation system must establish 910 exchange instructions and notification over a secure and 911 authenticated channel. Adequate filters can be enforced to avoid 912 that nodes outside a trusted domain can inject request such as 913 deleting filtering rules. Nevertheless, attacks can be initiated 914 from within the trusted domain if an entity has been corrupted. 915 Adequate means to monitor trusted nodes should also be enabled. 917 7. Acknowledgements 919 Thanks to Christian Jacquenet, Roland Dobbins, Andrew Mortensen, 920 Roman Danyliw, Ehud Doron, Russ White and Gilbert Clark for the 921 discussion and comments. 923 8. References 925 8.1. Normative References 927 [I-D.ietf-dots-architecture] 928 Mortensen, A., Andreasen, F., Reddy, T., 929 christopher_gray3@cable.comcast.com, c., Compton, R., and 930 N. Teague, "Distributed-Denial-of-Service Open Threat 931 Signaling (DOTS) Architecture", draft-ietf-dots- 932 architecture-03 (work in progress), June 2017. 934 [I-D.ietf-netmod-acl-model] 935 Bogdanovic, D., Jethanandani, M., Huang, L., Agarwal, S., 936 and D. Blair, "Network Access Control List (ACL) YANG Data 937 Model", draft-ietf-netmod-acl-model-11 (work in progress), 938 June 2017. 940 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 941 Requirement Levels", BCP 14, RFC 2119, 942 DOI 10.17487/RFC2119, March 1997, 943 . 945 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 946 (TLS) Protocol Version 1.2", RFC 5246, 947 DOI 10.17487/RFC5246, August 2008, 948 . 950 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 951 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 952 June 2010, . 954 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 955 Protocol (HTTP/1.1): Message Syntax and Routing", 956 RFC 7230, DOI 10.17487/RFC7230, June 2014, 957 . 959 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 960 "Recommendations for Secure Use of Transport Layer 961 Security (TLS) and Datagram Transport Layer Security 962 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 963 2015, . 965 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 966 RFC 7951, DOI 10.17487/RFC7951, August 2016, 967 . 969 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 970 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 971 . 973 8.2. Informative References 975 [I-D.ietf-dots-requirements] 976 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 977 Denial of Service (DDoS) Open Threat Signaling 978 Requirements", draft-ietf-dots-requirements-05 (work in 979 progress), June 2017. 981 [I-D.ietf-dots-signal-channel] 982 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 983 Teague, "Distributed Denial-of-Service Open Threat 984 Signaling (DOTS) Signal Channel", draft-ietf-dots-signal- 985 channel-02 (work in progress), June 2017. 987 [IEEE.754.1985] 988 Institute of Electrical and Electronics Engineers, 989 "Standard for Binary Floating-Point Arithmetic", August 990 1985. 992 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 993 the Network Configuration Protocol (NETCONF)", RFC 6020, 994 DOI 10.17487/RFC6020, October 2010, 995 . 997 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 998 and A. Bierman, Ed., "Network Configuration Protocol 999 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1000 . 1002 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1003 Layer Security (TLS) and Datagram Transport Layer Security 1004 (DTLS) Heartbeat Extension", RFC 6520, 1005 DOI 10.17487/RFC6520, February 2012, 1006 . 1008 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1009 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1010 2014, . 1012 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1013 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1014 . 1016 Authors' Addresses 1018 Tirumaleswar Reddy 1019 McAfee, Inc. 1020 Embassy Golf Link Business Park 1021 Bangalore, Karnataka 560071 1022 India 1024 Email: kondtir@gmail.com 1026 Mohamed Boucadair 1027 Orange 1028 Rennes 35000 1029 France 1031 Email: mohamed.boucadair@orange.com 1033 Kaname Nishizuka 1034 NTT Communications 1035 GranPark 16F 3-4-1 Shibaura, Minato-ku 1036 Tokyo 108-8118 1037 Japan 1039 Email: kaname@nttv6.jp 1041 Liang Xia 1042 Huawei 1043 101 Software Avenue, Yuhuatai District 1044 Nanjing, Jiangsu 210012 1045 China 1047 Email: frank.xialiang@huawei.com 1049 Prashanth Patil 1050 Cisco Systems, Inc. 1052 Email: praspati@cisco.com 1053 Andrew Mortensen 1054 Arbor Networks, Inc. 1055 2727 S. State St 1056 Ann Arbor, MI 48104 1057 United States 1059 Email: amortensen@arbor.net 1061 Nik Teague 1062 Verisign, Inc. 1063 United States 1065 Email: nteague@verisign.com