idnits 2.17.1 draft-ietf-dots-data-channel-03.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 13 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 (August 18, 2017) is 2441 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-04 ** 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-06 == Outdated reference: A later version (-41) exists of draft-ietf-dots-signal-channel-03 -- 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: February 19, 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 August 18, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-ietf-dots-data-channel-03 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 February 19, 2018. 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 target-ip* inet:ip-address 266 +--rw target-prefix* inet:ip-prefix 267 +--rw target-port-range* [lower-port upper-port] 268 | +--rw lower-port inet:port-number 269 | +--rw upper-port inet:port-number 270 +--rw target-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@2017-08-03.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 2017-08-03 { 293 reference 294 "https://tools.ietf.org/html/draft-ietf-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 target-ip { 307 type inet:ip-address; 308 description "IPv4 or IPv6 address identifyting the target."; 309 } 310 leaf-list target-prefix { 311 type inet:ip-prefix; 312 description "IPv4 or IPv6 prefix identifyting the target."; 313 } 314 list target-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 number."; 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 number."; 332 } 334 } 335 leaf-list target-protocol { 336 type uint8; 337 description "Identifies the target 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 non-initial fragment, if available, matches the Layer 4 information 390 in the ACL 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 "target-ip": [ 472 "string" 473 ], 474 "target-prefix": [ 475 "string" 476 ], 477 "target-port-range": [ 478 { 479 "lower-port": integer, 480 "upper-port": integer 481 } 482 ], 483 "target-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 target-ip: IP addresses are separated by commas. This is an 504 optional attribute. 506 target-prefix: Prefixes are separated by commas. This is an 507 optional attribute. 509 target-port-range: The port range, lower-port for lower port number 510 and upper-port for upper port number. For TCP, UDP, SCTP, or 511 DCCP: the range of ports (e.g., 80 to 8080). This is an optional 512 attribute. 514 target-protocol: Values are taken from the IANA protocol registry 515 [proto_numbers]. The value 0 has a special meaning for 'all 516 protocols'. This is an optional attribute. 518 fqdn: Fully Qualified Domain Name, is the full name of a system, 519 rather than just its hostname. For example, "venera" is a 520 hostname, and "venera.isi.edu" is an FQDN. This is an optional 521 attribute. 523 uri: Uniform Resource Identifier (URI). This is an optional 524 attribute. 526 In the POST request at least one of the attributes ip or prefix or 527 fqdn or uri MUST be present. DOTS agents can safely ignore Vendor- 528 Specific parameters they don't understand. 530 Figure 4 shows a POST request to create alias called "https1" for 531 HTTP(S) servers with IP addresses 2001:db8:6401::1 and 532 2001:db8:6401::2 listening on port 443. 534 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 535 Host: www.example.com 536 Content-Format: "application/yang.api+json" 537 { 538 "ietf-dots-data-channel-identifier:identifier": { 539 "alias": [ 540 { 541 "alias-name": "Server1", 542 "target-protocol": [ 543 6 544 ], 545 "target-ip": [ 546 "2001:db8:6401::1", 547 "2001:db8:6401::2" 548 ], 549 "target-port-range": [ 550 { 551 "lower-port": 443 552 } 553 ] 554 } 555 ] 556 } 557 } 559 Figure 4: POST to create identifiers 561 The DOTS server indicates the result of processing the POST request 562 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 563 codes are some sort of invalid requests and 5xx codes are returned if 564 the DOTS server has erred or it is incapable of accepting the alias. 565 Response code 201 (Created) will be returned in the response if the 566 DOTS server has accepted the alias. If the request is missing one or 567 more mandatory attributes then 400 (Bad Request) will be returned in 568 the response or if the request contains invalid or unknown parameters 569 then 400 (Invalid query) will be returned in the response. The HTTP 570 response will include the JSON body received in the request. 572 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 573 create or modify the aliases in the DOTS server. 575 3.2.2. Delete Identifiers 577 A DELETE request is used to delete identifiers maintained by a DOTS 578 server (Figure 5). 580 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 581 /alias=Server1 HTTP/1.1 582 Host: {host}:{port} 584 Figure 5: DELETE identifier 586 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 587 resource identifier is encoded from left to right, starting with the 588 top-level data node, according to the "api-path" rule defined in 589 Section 3.5.3.1 of [RFC8040]. The data node in the above path 590 expression is a YANG list node and MUST be encoded according to the 591 rules defined in Section 3.5.1 of [RFC8040]. 593 If the DOTS server does not find the alias name conveyed in the 594 DELETE request in its configuration data, then it responds with a 404 595 (Not Found) error response code. The DOTS server successfully 596 acknowledges a DOTS client's request to remove the identifier using 597 204 (No Content) in the response. 599 3.2.3. Retrieving Installed Identifiers 601 A GET request is used to retrieve the set of installed identifiers 602 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 603 to retrieve all the identifiers that were instantiated by the DOTS 604 client. The content parameter and its permitted values are defined 605 in Section 4.8.1 of [RFC8040]. 607 GET /restconf/data/ietf-dots-data-channel-identifier:identifier?\ 608 content=config HTTP/1.1 609 Host: {host}:{port} 610 Accept: application/yang-data+json 612 Figure 6: GET to retrieve all the installed identifiers 614 Figure 7 shows response for all identifiers on the DOTS server. 616 { 617 "ietf-dots-data-channel-identifier:identifier": [ 618 { 619 "alias": [ 620 { 621 "alias-name": "Server1", 622 "traffic-protocol": [ 623 6 624 ], 625 "ip": [ 626 "2001:db8:6401::1", 627 "2001:db8:6401::2" 628 ], 629 "port-range": [ 630 { 631 "lower-port": 443 632 } 633 ] 634 } 635 ] 636 }, 637 { 638 "alias": [ 639 { 640 "alias-name": "Server2", 641 "traffic-protocol": [ 642 6 643 ], 644 "ip": [ 645 "2001:db8:6401::10", 646 "2001:db8:6401::20" 647 ], 648 "port-range": [ 649 { 650 "lower-port": 80 651 } 652 ] 653 } 654 ] 655 } 656 ] 657 } 659 Figure 7: Response body 661 If the DOTS server does not find the alias name conveyed in the GET 662 request in its configuration data, then it responds with a 404 (Not 663 Found) error response code. 665 3.3. Filtering Rules 667 The DOTS server either receives the filtering rules directly from the 668 DOTS client or via the DOTS gateway. If the DOTS client signals the 669 filtering rules via the DOTS gateway then the DOTS gateway validates 670 if the DOTS client is authorized to signal the filtering rules and if 671 the client is authorized propagates the rules to the DOTS server. 672 Likewise, the DOTS server validates if the DOTS gateway is authorized 673 to signal the filtering rules. To create or purge filters, the DOTS 674 client sends HTTP requests to the DOTS gateway. The DOTS gateway 675 validates the rules in the requests and proxies the requests 676 containing the filtering rules to a DOTS server. When the DOTS 677 gateway receives the associated HTTP response from the DOTS server, 678 it propagates the response back to the DOTS client. 680 The following APIs define means for a DOTS client to configure 681 filtering rules on a DOTS server. 683 3.3.1. Install Filtering Rules 685 A POST request is used to push filtering rules to a DOTS server. 686 Figure 8 shows a POST request example to block traffic from 687 192.0.2.0/24, destined to 198.51.100.0/24. The ACL JSON 688 configuration for the filtering rule is generated using the ACL YANG 689 data model defined in [I-D.ietf-netmod-acl-model] and the ACL 690 configuration XML for the filtering rule is specified in Section 4.3 691 of [I-D.ietf-netmod-acl-model]. 693 POST /restconf/data/ietf-access-control-list HTTP/1.1 694 Host: www.example.com 695 Content-Format: "application/yang.api+json" 696 { 697 "ietf-access-control-list:access-lists": { 698 "acl": [ 699 { 700 "acl-name": "sample-ipv4-acl", 701 "acl-type": "ipv4", 702 "access-list-entries": { 703 "ace": [ 704 { 705 "rule-name": "rule1", 706 "matches": { 707 "source-ipv4-network": "192.0.2.0/24", 708 "destination-ipv4-network": "198.51.100.0/24" 709 }, 710 "actions": { 711 "deny": [null] 712 } 713 } 714 ] 715 } 716 } 717 ] 718 } 719 } 721 Figure 8: POST to install filterng rules 723 The header parameters defined in [I-D.ietf-netmod-acl-model] are 724 discussed below: 726 acl-name: The name of access-list. This is a mandatory attribute. 728 acl-type: Indicates the primary intended type of match criteria 729 (e.g. IPv4, IPv6). This is a mandatory attribute. 731 protocol: Internet Protocol numbers. This is an optional 732 attribute. 734 source-ipv4-network: The source IPv4 prefix. This is an optional 735 attribute. 737 destination-ipv4-network: The destination IPv4 prefix. This is an 738 optional attribute. 740 actions: "deny" or "permit" or "rate-limit". "permit" action is 741 used to white-list traffic. "deny" action is used to black-list 742 traffic. "rate-limit" action is used to rate-limit traffic, the 743 allowed traffic rate is represented in bytes per second indicated 744 in IEEE floating point format [IEEE.754.1985]. If actions 745 attribute is not specified in the request then the default action 746 is "deny". This is an optional attribute. 748 The DOTS server indicates the result of processing the POST request 749 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 750 codes are some sort of invalid requests and 5xx codes are returned if 751 the DOTS server has erred or it is incapable of configuring the 752 filtering rules. Response code 201 (Created) will be returned in the 753 response if the DOTS server has accepted the filtering rules. If the 754 request is missing one or more mandatory attributes then 400 (Bad 755 Request) will be returned in the response or if the request contains 756 invalid or unknown parameters then 400 (Invalid query) will be 757 returned in the response. 759 The DOTS client can use the PUT request to create or modify the 760 filtering rules in the DOTS server. 762 3.3.2. Remove Filtering Rules 764 A DELETE request is used to delete filtering rules from a DOTS server 765 (Figure 9). 767 DELETE /restconf/data/ietf-access-control-list:access-lists/acl-name\ 768 =sample-ipv4-acl&acl-type=ipv4 HTTP/1.1 769 Host: {host}:{port} 771 Figure 9: DELETE to remove the filtering rules 773 If the DOTS server does not find the access list name and access list 774 type conveyed in the DELETE request in its configuration data, then 775 it responds with a 404 (Not Found) error response code. The DOTS 776 server successfully acknowledges a DOTS client's request to withdraw 777 the filtering rules using 204 (No Content) response code, and removes 778 the filtering rules as soon as possible. 780 3.3.3. Retrieving Installed Filtering Rules 782 The DOTS client periodically queries the DOTS server to check the 783 counters for installed filtering rules. A GET request is used to 784 retrieve filtering rules from a DOTS server. Figure 10 shows how to 785 retrieve all the filtering rules programmed by the DOTS client and 786 the number of matches for the installed filtering rules. 788 GET /restconf/data/ietf-access-control-list:access-lists?content=all HTTP/1.1 789 Host: {host}:{port} 790 Accept: application/yang-data+json 792 Figure 10: GET to retrieve the configuration data and state data for 793 the filtering rules 795 If the DOTS server does not find the access list name and access list 796 type conveyed in the GET request in its configuration data, then it 797 responds with a 404 (Not Found) error response code. 799 4. IANA Considerations 801 This specification registers new parameters for the DOTS data channel 802 and establishes registries for mappings to JSON attributes. 804 4.1. DOTS Data Channel JSON Attribute Mappings Registry 806 A new registry will be requested from IANA, entitled "DOTS data 807 channel JSON attribute Mappings Registry". The registry is to be 808 created as Expert Review Required. 810 4.2. Registration Template 812 JSON Attribute: 813 JSON attribute name. 815 Description: 816 Brief description of the attribute. 818 Change Controller: 819 For Standards Track RFCs, list the "IESG". For others, give the 820 name of the responsible party. Other details (e.g., postal 821 address, email address, home page URI) may also be included. 823 Specification Document(s): 824 Reference to the document or documents that specify the parameter, 825 preferably including URIs that can be used to retrieve copies of 826 the documents. An indication of the relevant sections may also be 827 included but is not required. 829 4.3. Initial Registry Contents 831 o JSON Attribute: "alias-name" 832 o Description: Name of alias. 833 o Change Controller: IESG 834 o Specification Document(s): this document 835 o JSON Attribute: "traffic-protocol" 836 o Description: Internet protocol numbers. 837 o Change Controller: IESG 838 o Specification Document(s): this document 840 o JSON Attribute: "port-range" 841 o Description: The port range, lower-port for lower port number and 842 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 843 the range of ports (e.g., 80 to 8080). 844 o Change Controller: IESG 845 o Specification Document(s): this document 847 o JSON Attribute: "lower-port" 848 o Description: Lower port number for port range. 849 o Change Controller: IESG 850 o Specification Document(s): this document 852 o JSON Attribute: "upper-port" 853 o Description: Upper port number for port range. 854 o Change Controller: IESG 855 o Specification Document(s): this document 857 o JSON Attribute: "ip" 858 o Description: IP address. 859 o Change Controller: IESG 860 o Specification Document(s): this document 862 o JSON Attribute: "prefix" 863 o Description: IP prefix 864 o Change Controller: IESG 865 o Specification Document(s): this document 867 o JSON Attribute: "fqdn" 868 o Description: Fully Qualified Domain Name, is the full name of a 869 system, rather than just its hostname. For example, "venera" is a 870 hostname, and "venera.isi.edu" is an FQDN. 871 o Change Controller: IESG 872 o Specification Document(s): this document 874 o JSON Attribute: "uri" 875 o Description: Uniform Resource Identifier (URI). 876 o Change Controller: IESG 877 o Specification Document(s): this document 879 5. Contributors 881 The following individuals have contributed to this document: 883 Dan Wing 885 Email: dwing-ietf@fuggles.com 887 6. Security Considerations 889 Authenticated encryption MUST be used for data confidentiality and 890 message integrity. TLS based on client certificate MUST be used for 891 mutual authentication. The interaction between the DOTS agents 892 requires Transport Layer Security (TLS) with a cipher suite offering 893 confidentiality protection and the guidance given in [RFC7525] MUST 894 be followed to avoid attacks on TLS. 896 An attacker may be able to inject RST packets, bogus application 897 segments, etc., regardless of whether TLS authentication is used. 898 Because the application data is TLS protected, this will not result 899 in the application receiving bogus data, but it will constitute a DoS 900 on the connection. This attack can be countered by using TCP-AO 901 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 902 attacker will be rejected by the TCP-AO integrity check and therefore 903 will never reach the TLS layer. 905 Special care should be taken in order to ensure that the activation 906 of the proposed mechanism won't have an impact on the stability of 907 the network (including connectivity and services delivered over that 908 network). 910 Involved functional elements in the cooperation system must establish 911 exchange instructions and notification over a secure and 912 authenticated channel. Adequate filters can be enforced to avoid 913 that nodes outside a trusted domain can inject request such as 914 deleting filtering rules. Nevertheless, attacks can be initiated 915 from within the trusted domain if an entity has been corrupted. 916 Adequate means to monitor trusted nodes should also be enabled. 918 7. Acknowledgements 920 Thanks to Christian Jacquenet, Roland Dobbins, Andrew Mortensen, 921 Roman Danyliw, Ehud Doron, Russ White, Jon Shallow and Gilbert Clark 922 for the discussion and comments. 924 8. References 926 8.1. Normative References 928 [I-D.ietf-dots-architecture] 929 Mortensen, A., Andreasen, F., Reddy, T., 930 christopher_gray3@cable.comcast.com, c., Compton, R., and 931 N. Teague, "Distributed-Denial-of-Service Open Threat 932 Signaling (DOTS) Architecture", draft-ietf-dots- 933 architecture-04 (work in progress), July 2017. 935 [I-D.ietf-netmod-acl-model] 936 Bogdanovic, D., Jethanandani, M., Huang, L., Agarwal, S., 937 and D. Blair, "Network Access Control List (ACL) YANG Data 938 Model", draft-ietf-netmod-acl-model-11 (work in progress), 939 June 2017. 941 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 942 Requirement Levels", BCP 14, RFC 2119, 943 DOI 10.17487/RFC2119, March 1997, . 946 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 947 (TLS) Protocol Version 1.2", RFC 5246, 948 DOI 10.17487/RFC5246, August 2008, . 951 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 952 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 953 June 2010, . 955 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 956 Protocol (HTTP/1.1): Message Syntax and Routing", 957 RFC 7230, DOI 10.17487/RFC7230, June 2014, 958 . 960 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 961 "Recommendations for Secure Use of Transport Layer 962 Security (TLS) and Datagram Transport Layer Security 963 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 964 2015, . 966 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 967 RFC 7951, DOI 10.17487/RFC7951, August 2016, 968 . 970 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 971 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 972 . 974 8.2. Informative References 976 [I-D.ietf-dots-requirements] 977 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 978 Denial of Service (DDoS) Open Threat Signaling 979 Requirements", draft-ietf-dots-requirements-06 (work in 980 progress), July 2017. 982 [I-D.ietf-dots-signal-channel] 983 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 984 Teague, "Distributed Denial-of-Service Open Threat 985 Signaling (DOTS) Signal Channel", draft-ietf-dots-signal- 986 channel-03 (work in progress), August 2017. 988 [IEEE.754.1985] 989 Institute of Electrical and Electronics Engineers, 990 "Standard for Binary Floating-Point Arithmetic", August 991 1985. 993 [proto_numbers] 994 "IANA, "Protocol Numbers"", 2011, 995 . 997 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 998 the Network Configuration Protocol (NETCONF)", RFC 6020, 999 DOI 10.17487/RFC6020, October 2010, . 1002 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1003 and A. Bierman, Ed., "Network Configuration Protocol 1004 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1005 . 1007 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1008 Layer Security (TLS) and Datagram Transport Layer Security 1009 (DTLS) Heartbeat Extension", RFC 6520, 1010 DOI 10.17487/RFC6520, February 2012, . 1013 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1014 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1015 2014, . 1017 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1018 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1019 . 1021 Authors' Addresses 1023 Tirumaleswar Reddy 1024 McAfee, Inc. 1025 Embassy Golf Link Business Park 1026 Bangalore, Karnataka 560071 1027 India 1029 Email: kondtir@gmail.com 1031 Mohamed Boucadair 1032 Orange 1033 Rennes 35000 1034 France 1036 Email: mohamed.boucadair@orange.com 1038 Kaname Nishizuka 1039 NTT Communications 1040 GranPark 16F 3-4-1 Shibaura, Minato-ku 1041 Tokyo 108-8118 1042 Japan 1044 Email: kaname@nttv6.jp 1046 Liang Xia 1047 Huawei 1048 101 Software Avenue, Yuhuatai District 1049 Nanjing, Jiangsu 210012 1050 China 1052 Email: frank.xialiang@huawei.com 1054 Prashanth Patil 1055 Cisco Systems, Inc. 1057 Email: praspati@cisco.com 1058 Andrew Mortensen 1059 Arbor Networks, Inc. 1060 2727 S. State St 1061 Ann Arbor, MI 48104 1062 United States 1064 Email: amortensen@arbor.net 1066 Nik Teague 1067 Verisign, Inc. 1068 United States 1070 Email: nteague@verisign.com