idnits 2.17.1 draft-ietf-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 14 instances of too long lines in the document, the longest one being 43 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 279 has weird spacing: '...er-port ine...' == Line 280 has weird spacing: '...er-port ine...' -- The document date (October 12, 2017) is 2388 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 (-41) exists of draft-ietf-dots-signal-channel-04 == Outdated reference: A later version (-21) exists of draft-ietf-netmod-acl-model-14 ** 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 (-06) exists of draft-ietf-netmod-yang-tree-diagrams-01 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) Summary: 5 errors (**), 0 flaws (~~), 8 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: April 15, 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 October 12, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-ietf-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 https://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 April 15, 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 (https://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 Module . . . . . . . . . . . . . . 6 67 3.1.1. Identifier Module Tree Structure . . . . . . . . . . 6 68 3.1.2. Identifier Model YANG Module . . . . . . . . . . . . 7 69 3.1.3. Filter Model YANG Module Tree Structure . . . . . . . 10 70 3.1.4. Filter Model YANG Module . . . . . . . . . . . . . . 11 71 3.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 13 72 3.2.1. Create Identifiers . . . . . . . . . . . . . . . . . 13 73 3.2.2. Delete Identifiers . . . . . . . . . . . . . . . . . 16 74 3.2.3. Retrieving Installed Identifiers . . . . . . . . . . 17 75 3.3. Filtering Rules . . . . . . . . . . . . . . . . . . . . . 19 76 3.3.1. Install Filtering Rules . . . . . . . . . . . . . . . 19 77 3.3.2. Remove Filtering Rules . . . . . . . . . . . . . . . 21 78 3.3.3. Retrieving Installed Filtering Rules . . . . . . . . 21 79 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 80 4.1. DOTS Data Channel JSON Attribute Mappings Registry . . . 22 81 4.2. Registration Template . . . . . . . . . . . . . . . . . . 22 82 4.3. Initial Registry Contents . . . . . . . . . . . . . . . . 23 83 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 24 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 24 85 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 25 86 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 87 8.1. Normative References . . . . . . . . . . . . . . . . . . 25 88 8.2. Informative References . . . . . . . . . . . . . . . . . 26 89 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 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) [I-D.ietf-dots-architecture] 101 defines two channels: signal and data channels (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 The terminology for describing YANG data modules is defined in 165 [RFC7950]. The meaning of the symbols in tree diagrams is defined in 166 [I-D.ietf-netmod-yang-tree-diagrams]. 168 For simplicity, all of the examples in this document use "/restconf" 169 as the discovered RESTCONF API root path. Many protocol header lines 170 and message-body text within examples throughout the document are 171 split into multiple lines for display purposes only. When a line 172 ends with backslash ('\') as the last character, the line is wrapped 173 for display purposes. It is to be considered to be joined to the 174 next line by deleting the backslash, the following line break, and 175 the leading whitespace of the next line. 177 3. DOTS Data Channel 179 The DOTS data channel is intended to be used for bulk data exchanges 180 between DOTS agents. Unlike the signal channel 181 [I-D.ietf-dots-signal-channel], which must operate nominally even 182 when confronted with signal degradation due to packets loss, the data 183 channel is not expected to be constructed to deal with DDoS attack 184 conditions. 186 As the primary function of the data channel is data exchange, a 187 reliable transport is required in order for DOTS agents to detect 188 data delivery success or failure. RESTCONF [RFC8040] over TLS 189 [RFC5246] over TCP is used for DOTS data channel (Figure 2). 190 RESTCONF uses HTTP methods to provide CRUD (create, read, update, 191 delete) operations on a conceptual datastore containing YANG data, 192 which is compatible with a server implementing NETCONF datastores. 194 The HTTP POST, PUT, PATCH, and DELETE methods are used to edit data 195 resources represented by DOTS data channel YANG data models. These 196 basic edit operations allow the DOTS data channel running 197 configuration to be altered by a DOTS client. 199 DOTS data channel configuration data and state data can be retrieved 200 with the GET method. HTTP status codes are used to report success or 201 failure for RESTCONF operations. 203 The DOTS client will perform the root resource discovery procedure 204 discussed in Section 3.1 of [RFC8040] to determine the root of the 205 RESTCONF API. After discovering the RESTCONF API root, the DOTS 206 client uses this value as the initial part of the path in the request 207 URI, in any subsequent request to the DOTS server. The DOTS server 208 may support retrieval of the YANG modules it supports (Section 3.7 in 209 [RFC8040]), for example, a DOTS client may use RESTCONF to retrieve 210 the company proprietary YANG modules supported by the DOTS server. 212 Note: This document uses RESTCONF, a protocol based on HTTP 213 [RFC7230], for configuring data defined in YANG version 1 214 [RFC6020] or YANG version 1.1 [RFC7950], using the datastore 215 concepts defined in the Network Configuration Protocol (NETCONF) 216 [RFC6241]. RESTCONF combines the simplicity of the HTTP protocol 217 with the predictability and automation potential of a schema- 218 driven API. RESTCONF offers a simple subset of NETCONF 219 functionality and provides a simplified interface using REST-like 220 API which addresses the needs of the DOTS data channel and hence 221 an optimal choice. 223 +--------------+ 224 | DOTS | 225 +--------------+ 226 | RESTCONF | 227 +--------------+ 228 | TLS | 229 +--------------+ 230 | TCP | 231 +--------------+ 232 | IP | 233 +--------------+ 235 Figure 2: Abstract Layering of DOTS data channel over RESTCONF over 236 TLS 238 JavaScript Object Notation (JSON) [RFC7159] payload is used to 239 propagate data channel specific payload messages that convey request 240 parameters and response information such as errors. This 241 specification uses the encoding rules defined in [RFC7951] for 242 representing DOTS data channel configuration data defined using YANG 243 (Section 3.1) as JSON text. 245 A DOTS client registers itself to its DOTS server(s) in order to set 246 up DOTS data channel related configuration data and receive state 247 data (i.e., non-configuration data) from the DOTS server(s). 249 A single DOTS data channel between DOTS agents can be used to 250 exchange multiple requests and multiple responses. To reduce DOTS 251 client and DOTS server workload, DOTS client SHOULD re-use the same 252 TLS session. While the communication to the DOTS server is 253 quiescent, the DOTS client MAY probe the server to ensure it has 254 maintained cryptographic state. Such probes can also keep alive 255 firewall and/or NAT bindings. A TLS heartbeat [RFC6520] verifies the 256 DOTS server still has TLS state by returning a TLS message. 258 3.1. DOTS Data Channel YANG Module 260 3.1.1. Identifier Module Tree Structure 262 This document defines a YANG module for creating identifiers, such as 263 names or aliases, for resources for which mitigation may be 264 requested. Such identifiers may be used in subsequent DOTS signal 265 channel exchanges to refer more efficiently to the resources under 266 attack. 268 This document defines the YANG module "ietf-dots-data-channel- 269 identifier", which has the following tree structure: 271 module: ietf-dots-data-channel-identifier 272 +--rw identifier 273 +--rw client-identifier* binary 274 +--rw alias* [alias-name] 275 +--rw alias-name string 276 +--rw target-ip* inet:ip-address 277 +--rw target-prefix* inet:ip-prefix 278 +--rw target-port-range* [lower-port upper-port] 279 | +--rw lower-port inet:port-number 280 | +--rw upper-port inet:port-number 281 +--rw target-protocol* uint8 282 +--rw fqdn* inet:domain-name 283 +--rw uri* inet:uri 285 This structure is aligned with Section 5.2.1 of 286 [I-D.ietf-dots-signal-channel]. 288 3.1.2. Identifier Model YANG Module 290 file "ietf-dots-data-channel-identifier@2017-10-12.yang" 292 module ietf-dots-data-channel-identifier { 293 yang-version 1.1; 294 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-data-channel-identifier"; 296 prefix "alias"; 298 import ietf-inet-types { 299 prefix "inet"; 300 } 302 organization "IETF DOTS Working Group"; 304 contact 305 "Konda, Tirumaleswar Reddy 306 Mohamed Boucadair 307 Kaname Nishizuka 308 Liang Xia 309 Prashanth Patil 310 Andrew Mortensen 311 Nik Teague "; 313 description 314 "This module contains YANG definition for configuring 315 identifiers for resources using DOTS data channel. 317 Copyright (c) 2017 IETF Trust and the persons identified as 318 authors of the code. All rights reserved. 320 Redistribution and use in source and binary forms, with or 321 without modification, is permitted pursuant to, and subject 322 to the license terms contained in, the Simplified BSD License 323 set forth in Section 4.c of the IETF Trust's Legal Provisions 324 Relating to IETF Documents 325 (http://trustee.ietf.org/license-info). 327 This version of this YANG module is part of RFC XXXX; see 328 the RFC itself for full legal notices."; 330 revision 2017-10-12 { 331 description "Fix nits and align the module with the signal 332 channel."; 333 reference 334 "-05"; 335 } 337 revision 2017-08-03 { 338 reference 339 "https://tools.ietf.org/html/draft-ietf-dots-data-channel"; 340 } 342 container identifier { 343 description "Top level container for identifiers"; 345 leaf-list client-identifier { 346 type binary; 347 description "A client identifier conveyed by a DOTS gateway 348 to a remote DOTS server."; 350 reference 351 "I-D.itef-dots-signal-channel"; 352 } 354 list alias { 355 key alias-name; 356 description "List of identifiers"; 358 leaf alias-name { 359 type string; 360 description "alias name"; 361 } 363 leaf-list target-ip { 364 type inet:ip-address; 365 description "IPv4 or IPv6 address identifying the target."; 366 } 367 leaf-list target-prefix { 368 type inet:ip-prefix; 369 description "IPv4 or IPv6 prefix identifying the target."; 370 } 372 list target-port-range { 373 key "lower-port upper-port"; 374 description 375 "Port range. When only lower-port is present, 376 it represents a single port."; 377 leaf lower-port { 378 type inet:port-number; 379 mandatory true; 380 description "Lower port number."; 381 } 382 leaf upper-port { 383 type inet:port-number; 384 must ". >= ../lower-port" { 385 error-message 386 "The upper-port must be greater than or 387 equal to lower-port"; 388 } 389 description "Upper port number."; 390 } 391 } 393 leaf-list target-protocol { 394 type uint8; 395 description "Identifies the target protocol number."; 397 reference 398 "https://www.iana.org/assignments/protocol-numbers/ 399 protocol-numbers.xhtml"; 400 } 402 leaf-list fqdn { 403 type inet:domain-name; 404 description "FQDN"; 405 } 407 leaf-list uri { 408 type inet:uri; 409 description "URI"; 410 } 411 } 412 } 413 } 414 416 3.1.3. Filter Model YANG Module Tree Structure 418 This document augments the "ietf-access-control-list" Access Control 419 List (ACL) YANG module [I-D.ietf-netmod-acl-model] for managing 420 filtering rules. ACL is explained in Section 1 of 421 [I-D.ietf-netmod-acl-model]. 423 Examples of ACL management include, but not limited to,: 425 o Black-list management, which enables a DOTS client to inform the 426 DOTS server about sources from which traffic should be suppressed. 428 o White-list management, which enables a DOTS client to inform the 429 DOTS server about sources from which traffic should always be 430 accepted. 432 o Filter management, which enables a DOTS client to request the 433 installation or removal of traffic filters, dropping or rate- 434 limiting unwanted traffic and permitting white-listed traffic. 436 This document defines the YANG module "ietf-dots-access-control-list" 437 to augment the "ietf-access-control-list" module to support filters 438 based on the client identifier (client-identifier), to support rate- 439 limit action (rate-limit), and to handle fragmented packets 440 (fragments). 442 Filtering fragments adds an additional layer of protection against a 443 DoS attack that uses only noninitial fragments. When there is only 444 Layer 3 information in the ACL entry and the fragments keyword is 445 present, for noninitial fragments matching the ACL entry, the deny or 446 permit action associated with the ACL entry will be enforced and for 447 initial or non-fragment matching the ACL entry, the next ACL entry 448 will be processed. When there is both Layer 3 and Layer 4 449 information in the ACL entry and the fragments keyword is present, 450 the ACL action is conservative for both permit and deny actions. The 451 actions are conservative to not accidentally deny a fragmented 452 portion of a flow because the fragments do not contain sufficient 453 information to match all of the filter attributes. In the deny 454 action case, instead of denying a non-initial fragment, the next ACL 455 entry is processed. In the permit case, it is assumed that the Layer 456 4 information in the non-initial fragment, if available, matches the 457 Layer 4 information in the ACL entry. 459 The "ietf-dots-access-control-list" module has the following 460 structure: 462 module: ietf-dots-access-control-list 463 augment /ietf-acl:access-lists: 464 +--rw client-identifier* binary 465 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ace/ietf-acl:actions/ietf-acl:packet-handling: 466 +--:(rate-limit) 467 +--rw rate-limit? decimal64 468 augment /ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ace: 469 +--rw fragments? empty 471 3.1.4. Filter Model YANG Module 473 file "ietf-dots-access-control-list@2017-10-12.yang" 475 module ietf-dots-access-control-list { 476 yang-version 1.1; 478 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-access-control-list"; 479 prefix "dots-acl"; 481 import ietf-access-control-list { 482 prefix "ietf-acl"; 483 } 485 organization "IETF DOTS Working Group"; 487 contact 488 "Konda, Tirumaleswar Reddy 489 Mohamed Boucadair 490 Kaname Nishizuka 491 Liang Xia 492 Prashanth Patil 493 Andrew Mortensen 494 Nik Teague "; 496 description 497 "This module contains YANG definition for configuring 498 filtering rules using DOTS data channel. 500 Copyright (c) 2017 IETF Trust and the persons identified as 501 authors of the code. All rights reserved. 503 Redistribution and use in source and binary forms, with or 504 without modification, is permitted pursuant to, and subject 505 to the license terms contained in, the Simplified BSD License 506 set forth in Section 4.c of the IETF Trust's Legal Provisions 507 Relating to IETF Documents 508 (http://trustee.ietf.org/license-info). 509 This version of this YANG module is part of RFC XXXX; see 510 the RFC itself for full legal notices."; 512 revision 2017-10-12 { 513 description "Fix nits and align the module with the signal 514 channel."; 515 reference 516 "-05"; 517 } 519 revision 2017-06-12 { 520 reference 521 "https://tools.ietf.org/html/draft-ietf-dots-data-channel"; 522 } 524 augment "/ietf-acl:access-lists" { 526 description "client-identifier parameter."; 528 leaf-list client-identifier { 529 type binary; 530 description "A client identifier conveyed by a DOTS gateway 531 to a remote DOTS server."; 532 } 533 } 535 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/" 536 + "ietf-acl:ace/ietf-acl:actions" { 538 description "rate-limit action"; 539 leaf rate-limit { 540 type decimal64 { 541 fraction-digits 2; 542 } 543 description "rate-limit action."; 544 } 545 } 547 augment "/ietf-acl:access-lists/ietf-acl:acl/ietf-acl:aces/ietf-acl:ace" { 549 description "Handle non-initial and initial fragments."; 551 leaf fragments { 552 type empty; 553 description "Handle fragments."; 554 } 555 } 556 } 557 559 3.2. Identifiers 561 3.2.1. Create Identifiers 563 A POST request is used to create identifiers, such as names or 564 aliases, for resources for which a mitigation may be requested. Such 565 identifiers may then be used in subsequent DOTS signal channel 566 exchanges to refer more efficiently to the resources under attack 567 (Figure 3). 569 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 570 Host: {host}:{port} 571 Content-Format: "application/yang.api+json" 572 { 573 "ietf-dots-data-channel-identifier:identifier": { 574 "client-identifier": "string", 575 "alias": [ 576 { 577 "alias-name": "string", 578 "target-ip": [ 579 "string" 580 ], 581 "target-prefix": [ 582 "string" 583 ], 584 "target-port-range": [ 585 { 586 "lower-port": integer, 587 "upper-port": integer 588 } 589 ], 590 "target-protocol": [ 591 integer 592 ], 593 "fqdn": [ 594 "string" 595 ], 596 "uri": [ 597 "string" 598 ] 599 } 600 ] 601 } 602 } 604 Figure 3: POST to create identifiers 606 The header parameters are described below: 608 client-identifer: This attribute has the same meaning, syntax and 609 processing rules as the 'client-identifier' attribute defined in 610 [I-D.ietf-dots-signal-channel]. This is an optional attribute. 612 alias-name: Name of the alias. This is a mandatory attribute. 614 target-ip: IP addresses are separated by commas. This is an 615 optional attribute. 617 target-prefix: Prefixes are separated by commas. This is an 618 optional attribute. 620 target-port-range: The port range, lower-port for lower port number 621 and upper-port for upper port number. For TCP, UDP, SCTP, or 622 DCCP: the range of ports (e.g., 80 to 8080). This is an optional 623 attribute. 625 target-protocol: Values are taken from the IANA protocol registry 626 [proto_numbers]. The value 0 has a special meaning for 'all 627 protocols'. This is an optional attribute. 629 fqdn: Fully Qualified Domain Name, is the full name of a system, 630 rather than just its hostname. For example, "venera" is a 631 hostname, and "venera.isi.edu" is an FQDN. This is an optional 632 attribute. 634 uri: Uniform Resource Identifier (URI). This is an optional 635 attribute. 637 In the POST request at least one of the attributes 'target-ip' or 638 'target-prefix' or 'fqdn' or 'uri' MUST be present. DOTS agents can 639 safely ignore Vendor-Specific parameters they don't understand. 641 Figure 4 shows a POST request to create alias called "https1" for 642 HTTP(S) servers with IP addresses 2001:db8:6401::1 and 643 2001:db8:6401::2 listening on port 443. 645 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 646 Host: www.example.com 647 Content-Format: "application/yang.api+json" 648 { 649 "ietf-dots-data-channel-identifier:identifier": { 650 "client-identifier": "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=", 651 "alias": [ 652 { 653 "alias-name": "Server1", 654 "target-protocol": [ 655 6 656 ], 657 "target-ip": [ 658 "2001:db8:6401::1", 659 "2001:db8:6401::2" 660 ], 661 "target-port-range": [ 662 { 663 "lower-port": 443 664 } 665 ] 666 } 667 ] 668 } 669 } 671 Figure 4: POST to create identifiers 673 The DOTS server indicates the result of processing the POST request 674 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 675 codes are some sort of invalid requests and 5xx codes are returned if 676 the DOTS server has erred or it is incapable of accepting the alias. 677 Response code 201 (Created) will be returned in the response if the 678 DOTS server has accepted the alias. If the request is missing one or 679 more mandatory attributes then 400 (Bad Request) will be returned in 680 the response or if the request contains invalid or unknown parameters 681 then 400 (Invalid query) will be returned in the response. The HTTP 682 response will include the JSON body received in the request. 684 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 685 create or modify the aliases in the DOTS server. 687 3.2.2. Delete Identifiers 689 A DELETE request is used to delete identifiers maintained by a DOTS 690 server (Figure 5). 692 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 693 /alias=Server1 HTTP/1.1 694 Host: {host}:{port} 696 Figure 5: DELETE identifier 698 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 699 resource identifier is encoded from left to right, starting with the 700 top-level data node, according to the 'api-path' rule defined in 701 Section 3.5.3.1 of [RFC8040]. The data node in the above path 702 expression is a YANG list node and MUST be encoded according to the 703 rules defined in Section 3.5.1 of [RFC8040]. 705 If the DOTS server does not find the alias name conveyed in the 706 DELETE request in its configuration data, then it responds with a 404 707 (Not Found) error response code. The DOTS server successfully 708 acknowledges a DOTS client's request to remove the identifier using 709 204 (No Content) in the response. 711 3.2.3. Retrieving Installed Identifiers 713 A GET request is used to retrieve the set of installed identifiers 714 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 715 to retrieve all the identifiers that were instantiated by the DOTS 716 client. The content parameter and its permitted values are defined 717 in Section 4.8.1 of [RFC8040]. 719 GET /restconf/data/ietf-dots-data-channel-identifier:identifier?\ 720 content=config HTTP/1.1 721 Host: {host}:{port} 722 Accept: application/yang-data+json 724 Figure 6: GET to retrieve all the installed identifiers 726 Figure 7 shows response for all identifiers on the DOTS server. 728 { 729 "ietf-dots-data-channel-identifier:identifier": { 730 "client-identifier": "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=", 731 "alias": [ 732 { 733 "alias-name": "Server1", 734 "traffic-protocol": [ 735 6 736 ], 737 "ip": [ 738 "2001:db8:6401::1", 739 "2001:db8:6401::2" 740 ], 741 "port-range": [ 742 { 743 "lower-port": 443 744 } 745 ] 746 }, 747 { 748 "alias-name": "Server2", 749 "traffic-protocol": [ 750 6 751 ], 752 "ip": [ 753 "2001:db8:6401::10", 754 "2001:db8:6401::20" 755 ], 756 "port-range": [ 757 { 758 "lower-port": 80 759 } 760 ] 761 } 762 ] 763 } 764 } 766 Figure 7: Response body 768 If the DOTS server does not find the alias name conveyed in the GET 769 request in its configuration data, then it responds with a 404 (Not 770 Found) error response code. 772 3.3. Filtering Rules 774 The DOTS server either receives the filtering rules directly from the 775 DOTS client or via a DOTS gateway. 777 If the DOTS client signals the filtering rules via a DOTS gateway, 778 then the DOTS gateway validates if the DOTS client is authorized to 779 signal the filtering rules and if the client is authorized propagates 780 the rules to the DOTS server. Likewise, the DOTS server validates if 781 the DOTS gateway is authorized to signal the filtering rules. To 782 create or purge filters, the DOTS client sends HTTP requests to its 783 DOTS gateway. The DOTS gateway validates the rules in the requests 784 and proxies the requests containing the filtering rules to a DOTS 785 server. When the DOTS gateway receives the associated HTTP response 786 from the DOTS server, it propagates the response back to the DOTS 787 client. 789 The following APIs define means for a DOTS client to configure 790 filtering rules on a DOTS server. 792 3.3.1. Install Filtering Rules 794 A POST request is used to push filtering rules to a DOTS server. 795 Figure 8 shows a POST request example to block traffic from 796 192.0.2.0/24, destined to 198.51.100.0/24. The ACL JSON 797 configuration for the filtering rule is generated using the ACL YANG 798 data model defined in [I-D.ietf-netmod-acl-model] and the ACL 799 configuration XML for the filtering rule is specified in Section 4.3 800 of [I-D.ietf-netmod-acl-model]. 802 POST /restconf/data/ietf-dots-access-control-list HTTP/1.1 803 Host: www.example.com 804 Content-Format: "application/yang.api+json" 805 { 806 "ietf-dots-access-control-list:access-lists": { 807 "client-identifier": "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=", 808 "acl": [ 809 { 810 "acl-name": "sample-ipv4-acl", 811 "acl-type": "ipv4-acl", 812 "aces": { 813 "ace": [ 814 { 815 "rule-name": "rule1", 816 "matches": { 817 "ipv4-acl": { 818 "source-ipv4-network": "192.0.2.0/24", 819 "destination-ipv4-network": "198.51.100.0/24" 820 } 821 }, 822 "actions": { 823 "deny": [null] 824 } 825 } 826 ] 827 } 828 } 829 ] 830 } 831 } 833 Figure 8: POST to install filterng rules 835 The header parameters defined in [I-D.ietf-netmod-acl-model] are 836 discussed below: 838 acl-name: The name of access-list. This is a mandatory attribute. 840 acl-type: Indicates the primary intended type of match criteria 841 (e.g. IPv4, IPv6). This is a mandatory attribute. 843 protocol: Internet Protocol numbers. This is an optional 844 attribute. 846 source-ipv4-network: The source IPv4 prefix. This is an optional 847 attribute. 849 destination-ipv4-network: The destination IPv4 prefix. This is an 850 optional attribute. 852 actions: "deny" or "permit" or "rate-limit". "permit" action is 853 used to white-list traffic. "deny" action is used to black-list 854 traffic. "rate-limit" action is used to rate-limit traffic, the 855 allowed traffic rate is represented in bytes per second indicated 856 in IEEE floating point format [IEEE.754.1985]. If actions 857 attribute is not specified in the request then the default action 858 is "deny". This is an optional attribute. 860 The DOTS server indicates the result of processing the POST request 861 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 862 codes are some sort of invalid requests and 5xx codes are returned if 863 the DOTS server has erred or it is incapable of configuring the 864 filtering rules. Response code 201 (Created) will be returned in the 865 response if the DOTS server has accepted the filtering rules. If the 866 request is missing one or more mandatory attributes then 400 (Bad 867 Request) will be returned in the response or if the request contains 868 invalid or unknown parameters then 400 (Invalid query) will be 869 returned in the response. 871 The DOTS client can use the PUT request to create or modify the 872 filtering rules in the DOTS server. 874 3.3.2. Remove Filtering Rules 876 A DELETE request is used to delete filtering rules from a DOTS server 877 (Figure 9). 879 DELETE /restconf/data/ietf-dots-access-control-list:access-lists/acl-name\ 880 =sample-ipv4-acl&acl-type=ipv4-acl HTTP/1.1 881 Host: {host}:{port} 883 Figure 9: DELETE to remove the filtering rules 885 If the DOTS server does not find the access list name and access list 886 type conveyed in the DELETE request in its configuration data, then 887 it responds with a 404 (Not Found) error response code. The DOTS 888 server successfully acknowledges a DOTS client's request to withdraw 889 the filtering rules using 204 (No Content) response code, and removes 890 the filtering rules as soon as possible. 892 3.3.3. Retrieving Installed Filtering Rules 894 The DOTS client periodically queries the DOTS server to check the 895 counters for installed filtering rules. A GET request is used to 896 retrieve filtering rules from a DOTS server. Figure 10 shows how to 897 retrieve all the filtering rules programmed by the DOTS client and 898 the number of matches for the installed filtering rules. 900 GET /restconf/data/ietf-dots-access-control-list:access-lists?content=all HTTP/1.1 901 Host: {host}:{port} 902 Accept: application/yang-data+json 904 Figure 10: GET to retrieve the configuration data and state data for 905 the filtering rules 907 If the DOTS server does not find the access list name and access list 908 type conveyed in the GET request in its configuration data, then it 909 responds with a 404 (Not Found) error response code. 911 4. IANA Considerations 913 This specification registers new parameters for the DOTS data channel 914 and establishes registries for mappings to JSON attributes. 916 4.1. DOTS Data Channel JSON Attribute Mappings Registry 918 A new registry will be requested from IANA, entitled "DOTS data 919 channel JSON attribute Mappings Registry". The registry is to be 920 created as Expert Review Required. 922 4.2. Registration Template 924 JSON Attribute: 925 JSON attribute name. 927 Description: 928 Brief description of the attribute. 930 Change Controller: 931 For Standards Track RFCs, list the "IESG". For others, give the 932 name of the responsible party. Other details (e.g., postal 933 address, email address, home page URI) may also be included. 935 Specification Document(s): 936 Reference to the document or documents that specify the parameter, 937 preferably including URIs that can be used to retrieve copies of 938 the documents. An indication of the relevant sections may also be 939 included but is not required. 941 4.3. Initial Registry Contents 943 o JSON Attribute: "client-identifier" 944 o Description: Client identifier. 945 o Change Controller: IESG 946 o Specification Document(s): this document 948 o JSON Attribute: "alias-name" 949 o Description: Name of alias. 950 o Change Controller: IESG 951 o Specification Document(s): this document 953 o JSON Attribute: "traffic-protocol" 954 o Description: Internet protocol numbers. 955 o Change Controller: IESG 956 o Specification Document(s): this document 958 o JSON Attribute: "port-range" 959 o Description: The port range, lower-port for lower port number and 960 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 961 the range of ports (e.g., 80 to 8080). 962 o Change Controller: IESG 963 o Specification Document(s): this document 965 o JSON Attribute: "lower-port" 966 o Description: Lower port number for port range. 967 o Change Controller: IESG 968 o Specification Document(s): this document 970 o JSON Attribute: "upper-port" 971 o Description: Upper port number for port range. 972 o Change Controller: IESG 973 o Specification Document(s): this document 975 o JSON Attribute: "ip" 976 o Description: IP address. 977 o Change Controller: IESG 978 o Specification Document(s): this document 980 o JSON Attribute: "prefix" 981 o Description: IP prefix 982 o Change Controller: IESG 983 o Specification Document(s): this document 985 o JSON Attribute: "fqdn" 986 o Description: Fully Qualified Domain Name, is the full name of a 987 system, rather than just its hostname. For example, "venera" is a 988 hostname, and "venera.isi.edu" is an FQDN. 990 o Change Controller: IESG 991 o Specification Document(s): this document 993 o JSON Attribute: "uri" 994 o Description: Uniform Resource Identifier (URI). 995 o Change Controller: IESG 996 o Specification Document(s): this document 998 5. Contributors 1000 The following individuals have contributed to this document: 1002 Dan Wing 1004 Email: dwing-ietf@fuggles.com 1006 6. Security Considerations 1008 Authenticated encryption MUST be used for data confidentiality and 1009 message integrity. TLS based on client certificate MUST be used for 1010 mutual authentication. The interaction between the DOTS agents 1011 requires Transport Layer Security (TLS) with a cipher suite offering 1012 confidentiality protection and the guidance given in [RFC7525] MUST 1013 be followed to avoid attacks on TLS. 1015 An attacker may be able to inject RST packets, bogus application 1016 segments, etc., regardless of whether TLS authentication is used. 1017 Because the application data is TLS protected, this will not result 1018 in the application receiving bogus data, but it will constitute a DoS 1019 on the connection. This attack can be countered by using TCP-AO 1020 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 1021 attacker will be rejected by the TCP-AO integrity check and therefore 1022 will never reach the TLS layer. 1024 In order to prevent leaking internal information outside a client- 1025 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 1026 the identity of internal DOTS clients (client-identifier) unless 1027 explicitly configured to do so. 1029 Special care should be taken in order to ensure that the activation 1030 of the proposed mechanism won't have an impact on the stability of 1031 the network (including connectivity and services delivered over that 1032 network). 1034 Involved functional elements in the cooperation system must establish 1035 exchange instructions and notification over a secure and 1036 authenticated channel. Adequate filters can be enforced to avoid 1037 that nodes outside a trusted domain can inject request such as 1038 deleting filtering rules. Nevertheless, attacks can be initiated 1039 from within the trusted domain if an entity has been corrupted. 1040 Adequate means to monitor trusted nodes should also be enabled. 1042 7. Acknowledgements 1044 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 1045 Doron, Russ White, Jon Shallow, and Gilbert Clark for the discussion 1046 and comments. 1048 8. References 1050 8.1. Normative References 1052 [I-D.ietf-dots-architecture] 1053 Mortensen, A., Andreasen, F., Reddy, T., 1054 christopher_gray3@cable.comcast.com, c., Compton, R., and 1055 N. Teague, "Distributed-Denial-of-Service Open Threat 1056 Signaling (DOTS) Architecture", draft-ietf-dots- 1057 architecture-04 (work in progress), July 2017. 1059 [I-D.ietf-dots-signal-channel] 1060 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 1061 Teague, "Distributed Denial-of-Service Open Threat 1062 Signaling (DOTS) Signal Channel", draft-ietf-dots-signal- 1063 channel-04 (work in progress), October 2017. 1065 [I-D.ietf-netmod-acl-model] 1066 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 1067 "Network Access Control List (ACL) YANG Data Model", 1068 draft-ietf-netmod-acl-model-14 (work in progress), October 1069 2017. 1071 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1072 Requirement Levels", BCP 14, RFC 2119, 1073 DOI 10.17487/RFC2119, March 1997, 1074 . 1076 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1077 (TLS) Protocol Version 1.2", RFC 5246, 1078 DOI 10.17487/RFC5246, August 2008, 1079 . 1081 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 1082 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 1083 June 2010, . 1085 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1086 Protocol (HTTP/1.1): Message Syntax and Routing", 1087 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1088 . 1090 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1091 "Recommendations for Secure Use of Transport Layer 1092 Security (TLS) and Datagram Transport Layer Security 1093 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1094 2015, . 1096 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1097 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1098 . 1100 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1101 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1102 . 1104 8.2. Informative References 1106 [I-D.ietf-dots-requirements] 1107 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 1108 Denial of Service (DDoS) Open Threat Signaling 1109 Requirements", draft-ietf-dots-requirements-06 (work in 1110 progress), July 2017. 1112 [I-D.ietf-netmod-yang-tree-diagrams] 1113 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1114 ietf-netmod-yang-tree-diagrams-01 (work in progress), June 1115 2017. 1117 [IEEE.754.1985] 1118 Institute of Electrical and Electronics Engineers, 1119 "Standard for Binary Floating-Point Arithmetic", August 1120 1985. 1122 [proto_numbers] 1123 "IANA, "Protocol Numbers"", 2011, 1124 . 1126 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1127 the Network Configuration Protocol (NETCONF)", RFC 6020, 1128 DOI 10.17487/RFC6020, October 2010, 1129 . 1131 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1132 and A. Bierman, Ed., "Network Configuration Protocol 1133 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1134 . 1136 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1137 Layer Security (TLS) and Datagram Transport Layer Security 1138 (DTLS) Heartbeat Extension", RFC 6520, 1139 DOI 10.17487/RFC6520, February 2012, 1140 . 1142 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1143 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1144 2014, . 1146 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1147 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1148 . 1150 Authors' Addresses 1152 Tirumaleswar Reddy 1153 McAfee, Inc. 1154 Embassy Golf Link Business Park 1155 Bangalore, Karnataka 560071 1156 India 1158 Email: kondtir@gmail.com 1160 Mohamed Boucadair 1161 Orange 1162 Rennes 35000 1163 France 1165 Email: mohamed.boucadair@orange.com 1167 Kaname Nishizuka 1168 NTT Communications 1169 GranPark 16F 3-4-1 Shibaura, Minato-ku 1170 Tokyo 108-8118 1171 Japan 1173 Email: kaname@nttv6.jp 1174 Liang Xia 1175 Huawei 1176 101 Software Avenue, Yuhuatai District 1177 Nanjing, Jiangsu 210012 1178 China 1180 Email: frank.xialiang@huawei.com 1182 Prashanth Patil 1183 Cisco Systems, Inc. 1185 Email: praspati@cisco.com 1187 Andrew Mortensen 1188 Arbor Networks, Inc. 1189 2727 S. State St 1190 Ann Arbor, MI 48104 1191 United States 1193 Email: amortensen@arbor.net 1195 Nik Teague 1196 Verisign, Inc. 1197 United States 1199 Email: nteague@verisign.com