idnits 2.17.1 draft-ietf-dots-data-channel-06.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 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 27, 2017) is 2366 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-05 ** 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-05 == 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-02 -- 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 30, 2018 Orange 6 K. Nishizuka 7 NTT Communications 8 L. Xia 9 Huawei 10 P. Patil 11 Cisco 12 A. Mortensen 13 Arbor Networks, Inc. 14 N. Teague 15 Verisign, Inc. 16 October 27, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-ietf-dots-data-channel-06 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 30, 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 . . . . . . . . . . . . . . . . . 17 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": [ 575 "string" 576 ], 577 "alias": [ 578 { 579 "alias-name": "string", 580 "target-ip": [ 581 "string" 582 ], 583 "target-prefix": [ 584 "string" 585 ], 586 "target-port-range": [ 587 { 588 "lower-port": integer, 589 "upper-port": integer 590 } 591 ], 592 "target-protocol": [ 593 integer 594 ], 595 "fqdn": [ 596 "string" 597 ], 598 "uri": [ 599 "string" 600 ] 601 } 602 ] 603 } 604 } 606 Figure 3: POST to create identifiers 608 The header parameters are described below: 610 client-identifer: This attribute has the same meaning, syntax and 611 processing rules as the 'client-identifier' attribute defined in 612 [I-D.ietf-dots-signal-channel]. This is an optional attribute. 614 alias-name: Name of the alias. This is a mandatory attribute. 616 target-ip: IP addresses are separated by commas. This is an 617 optional attribute. 619 target-prefix: Prefixes are separated by commas. This is an 620 optional attribute. 622 target-port-range: The port range, lower-port for lower port number 623 and upper-port for upper port number. For TCP, UDP, SCTP, or 624 DCCP: the range of ports (e.g., 80 to 8080). This is an optional 625 attribute. 627 target-protocol: Values are taken from the IANA protocol registry 628 [proto_numbers]. The value 0 has a special meaning for 'all 629 protocols'. This is an optional attribute. 631 fqdn: Fully Qualified Domain Name, is the full name of a system, 632 rather than just its hostname. For example, "venera" is a 633 hostname, and "venera.isi.edu" is an FQDN. This is an optional 634 attribute. 636 uri: Uniform Resource Identifier (URI). This is an optional 637 attribute. 639 In the POST request at least one of the attributes 'target-ip' or 640 'target-prefix' or 'fqdn' or 'uri' MUST be present. DOTS agents can 641 safely ignore Vendor-Specific parameters they don't understand. 643 Figure 4 shows a POST request to create alias called "https1" for 644 HTTP(S) servers with IP addresses 2001:db8:6401::1 and 645 2001:db8:6401::2 listening on port 443. 647 POST /restconf/data/ietf-dots-data-channel-identifier HTTP/1.1 648 Host: www.example.com 649 Content-Format: "application/yang.api+json" 650 { 651 "ietf-dots-data-channel-identifier:identifier": { 652 "client-identifier": [ 653 "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=" 654 ], 655 "alias": [ 656 { 657 "alias-name": "Server1", 658 "target-protocol": [ 659 6 660 ], 661 "target-ip": [ 662 "2001:db8:6401::1", 663 "2001:db8:6401::2" 664 ], 665 "target-port-range": [ 666 { 667 "lower-port": 443 668 } 669 ] 670 } 671 ] 672 } 673 } 675 Figure 4: POST to create identifiers 677 The DOTS server indicates the result of processing the POST request 678 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 679 codes are some sort of invalid requests and 5xx codes are returned if 680 the DOTS server has erred or it is incapable of accepting the alias. 681 Response code 201 (Created) will be returned in the response if the 682 DOTS server has accepted the alias. If the request is missing one or 683 more mandatory attributes then 400 (Bad Request) will be returned in 684 the response or if the request contains invalid or unknown parameters 685 then 400 (Invalid query) will be returned in the response. The HTTP 686 response will include the JSON body received in the request. 688 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 689 create or modify the aliases in the DOTS server. 691 3.2.2. Delete Identifiers 693 A DELETE request is used to delete identifiers maintained by a DOTS 694 server (Figure 5). 696 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 697 /alias=Server1 HTTP/1.1 698 Host: {host}:{port} 700 Figure 5: DELETE identifier 702 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 703 resource identifier is encoded from left to right, starting with the 704 top-level data node, according to the 'api-path' rule defined in 705 Section 3.5.3.1 of [RFC8040]. The data node in the above path 706 expression is a YANG list node and MUST be encoded according to the 707 rules defined in Section 3.5.1 of [RFC8040]. 709 If the DOTS server does not find the alias name conveyed in the 710 DELETE request in its configuration data, then it responds with a 404 711 (Not Found) error response code. The DOTS server successfully 712 acknowledges a DOTS client's request to remove the identifier using 713 204 (No Content) in the response. 715 3.2.3. Retrieving Installed Identifiers 717 A GET request is used to retrieve the set of installed identifiers 718 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 719 to retrieve all the identifiers that were instantiated by the DOTS 720 client. The content parameter and its permitted values are defined 721 in Section 4.8.1 of [RFC8040]. 723 GET /restconf/data/ietf-dots-data-channel-identifier:identifier?\ 724 content=config HTTP/1.1 725 Host: {host}:{port} 726 Accept: application/yang-data+json 728 Figure 6: GET to retrieve all the installed identifiers 730 Figure 7 shows response for all identifiers on the DOTS server. 732 { 733 "ietf-dots-data-channel-identifier:identifier": { 734 "client-identifier": [ 735 "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=" 736 ], 737 "alias": [ 738 { 739 "alias-name": "Server1", 740 "traffic-protocol": [ 741 6 742 ], 743 "ip": [ 744 "2001:db8:6401::1", 745 "2001:db8:6401::2" 746 ], 747 "port-range": [ 748 { 749 "lower-port": 443 750 } 751 ] 752 }, 753 { 754 "alias-name": "Server2", 755 "traffic-protocol": [ 756 6 757 ], 758 "ip": [ 759 "2001:db8:6401::10", 760 "2001:db8:6401::20" 761 ], 762 "port-range": [ 763 { 764 "lower-port": 80 765 } 766 ] 767 } 768 ] 769 } 770 } 772 Figure 7: Response body 774 If the DOTS server does not find the alias name conveyed in the GET 775 request in its configuration data, then it responds with a 404 (Not 776 Found) error response code. 778 3.3. Filtering Rules 780 The DOTS server either receives the filtering rules directly from the 781 DOTS client or via a DOTS gateway. 783 If the DOTS client signals the filtering rules via a DOTS gateway, 784 then the DOTS gateway validates if the DOTS client is authorized to 785 signal the filtering rules and if the client is authorized propagates 786 the rules to the DOTS server. Likewise, the DOTS server validates if 787 the DOTS gateway is authorized to signal the filtering rules. To 788 create or purge filters, the DOTS client sends HTTP requests to its 789 DOTS gateway. The DOTS gateway validates the rules in the requests 790 and proxies the requests containing the filtering rules to a DOTS 791 server. When the DOTS gateway receives the associated HTTP response 792 from the DOTS server, it propagates the response back to the DOTS 793 client. 795 The following APIs define means for a DOTS client to configure 796 filtering rules on a DOTS server. 798 3.3.1. Install Filtering Rules 800 A POST request is used to push filtering rules to a DOTS server. 801 Figure 8 shows a POST request example to block traffic from 802 192.0.2.0/24, destined to 198.51.100.0/24. The ACL JSON 803 configuration for the filtering rule is generated using the ACL YANG 804 data model defined in [I-D.ietf-netmod-acl-model] and the ACL 805 configuration XML for the filtering rule is specified in Section 4.3 806 of [I-D.ietf-netmod-acl-model]. 808 POST /restconf/data/ietf-dots-access-control-list HTTP/1.1 809 Host: www.example.com 810 Content-Format: "application/yang.api+json" 811 { 812 "ietf-dots-access-control-list:access-lists": { 813 "client-identifier": [ 814 "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=" 815 ], 816 "acl": [ 817 { 818 "acl-name": "sample-ipv4-acl", 819 "acl-type": "ipv4-acl", 820 "aces": { 821 "ace": [ 822 { 823 "rule-name": "rule1", 824 "matches": { 825 "ipv4-acl": { 826 "source-ipv4-network": "192.0.2.0/24", 827 "destination-ipv4-network": "198.51.100.0/24" 828 } 829 }, 830 "actions": { 831 "deny": [null] 832 } 833 } 834 ] 835 } 836 } 837 ] 838 } 839 } 841 Figure 8: POST to install filterng rules 843 The header parameters defined in [I-D.ietf-netmod-acl-model] are 844 discussed below: 846 acl-name: The name of access-list. This is a mandatory attribute. 848 acl-type: Indicates the primary intended type of match criteria 849 (e.g. IPv4, IPv6). This is a mandatory attribute. 851 protocol: Internet Protocol numbers. This is an optional 852 attribute. 854 source-ipv4-network: The source IPv4 prefix. This is an optional 855 attribute. 857 destination-ipv4-network: The destination IPv4 prefix. This is an 858 optional attribute. 860 actions: "deny" or "permit" or "rate-limit". "permit" action is 861 used to white-list traffic. "deny" action is used to black-list 862 traffic. "rate-limit" action is used to rate-limit traffic, the 863 allowed traffic rate is represented in bytes per second indicated 864 in IEEE floating point format [IEEE.754.1985]. If actions 865 attribute is not specified in the request then the default action 866 is "deny". This is an optional attribute. 868 The DOTS server indicates the result of processing the POST request 869 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 870 codes are some sort of invalid requests and 5xx codes are returned if 871 the DOTS server has erred or it is incapable of configuring the 872 filtering rules. Response code 201 (Created) will be returned in the 873 response if the DOTS server has accepted the filtering rules. If the 874 request is missing one or more mandatory attributes then 400 (Bad 875 Request) will be returned in the response or if the request contains 876 invalid or unknown parameters then 400 (Invalid query) will be 877 returned in the response. 879 The DOTS client can use the PUT request to create or modify the 880 filtering rules in the DOTS server. 882 3.3.2. Remove Filtering Rules 884 A DELETE request is used to delete filtering rules from a DOTS server 885 (Figure 9). 887 DELETE /restconf/data/ietf-dots-access-control-list:access-lists/acl-name\ 888 =sample-ipv4-acl&acl-type=ipv4-acl HTTP/1.1 889 Host: {host}:{port} 891 Figure 9: DELETE to remove the filtering rules 893 If the DOTS server does not find the access list name and access list 894 type conveyed in the DELETE request in its configuration data, then 895 it responds with a 404 (Not Found) error response code. The DOTS 896 server successfully acknowledges a DOTS client's request to withdraw 897 the filtering rules using 204 (No Content) response code, and removes 898 the filtering rules as soon as possible. 900 3.3.3. Retrieving Installed Filtering Rules 902 The DOTS client periodically queries the DOTS server to check the 903 counters for installed filtering rules. A GET request is used to 904 retrieve filtering rules from a DOTS server. Figure 10 shows how to 905 retrieve all the filtering rules programmed by the DOTS client and 906 the number of matches for the installed filtering rules. 908 GET /restconf/data/ietf-dots-access-control-list:access-lists?content=all HTTP/1.1 909 Host: {host}:{port} 910 Accept: application/yang-data+json 912 Figure 10: GET to retrieve the configuration data and state data for 913 the filtering rules 915 If the DOTS server does not find the access list name and access list 916 type conveyed in the GET request in its configuration data, then it 917 responds with a 404 (Not Found) error response code. 919 4. IANA Considerations 921 This specification registers new parameters for the DOTS data channel 922 and establishes registries for mappings to JSON attributes. 924 4.1. DOTS Data Channel JSON Attribute Mappings Registry 926 A new registry will be requested from IANA, entitled "DOTS data 927 channel JSON attribute Mappings Registry". The registry is to be 928 created as Expert Review Required. 930 4.2. Registration Template 932 JSON Attribute: 933 JSON attribute name. 935 Description: 936 Brief description of the attribute. 938 Change Controller: 939 For Standards Track RFCs, list the "IESG". For others, give the 940 name of the responsible party. Other details (e.g., postal 941 address, email address, home page URI) may also be included. 943 Specification Document(s): 944 Reference to the document or documents that specify the parameter, 945 preferably including URIs that can be used to retrieve copies of 946 the documents. An indication of the relevant sections may also be 947 included but is not required. 949 4.3. Initial Registry Contents 951 o JSON Attribute: "client-identifier" 952 o Description: Client identifier. 953 o Change Controller: IESG 954 o Specification Document(s): this document 956 o JSON Attribute: "alias-name" 957 o Description: Name of alias. 958 o Change Controller: IESG 959 o Specification Document(s): this document 961 o JSON Attribute: "traffic-protocol" 962 o Description: Internet protocol numbers. 963 o Change Controller: IESG 964 o Specification Document(s): this document 966 o JSON Attribute: "port-range" 967 o Description: The port range, lower-port for lower port number and 968 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 969 the range of ports (e.g., 80 to 8080). 970 o Change Controller: IESG 971 o Specification Document(s): this document 973 o JSON Attribute: "lower-port" 974 o Description: Lower port number for port range. 975 o Change Controller: IESG 976 o Specification Document(s): this document 978 o JSON Attribute: "upper-port" 979 o Description: Upper port number for port range. 980 o Change Controller: IESG 981 o Specification Document(s): this document 983 o JSON Attribute: "ip" 984 o Description: IP address. 985 o Change Controller: IESG 986 o Specification Document(s): this document 988 o JSON Attribute: "prefix" 989 o Description: IP prefix 990 o Change Controller: IESG 991 o Specification Document(s): this document 993 o JSON Attribute: "fqdn" 994 o Description: Fully Qualified Domain Name, is the full name of a 995 system, rather than just its hostname. For example, "venera" is a 996 hostname, and "venera.isi.edu" is an FQDN. 998 o Change Controller: IESG 999 o Specification Document(s): this document 1001 o JSON Attribute: "uri" 1002 o Description: Uniform Resource Identifier (URI). 1003 o Change Controller: IESG 1004 o Specification Document(s): this document 1006 5. Contributors 1008 The following individuals have contributed to this document: 1010 Dan Wing 1012 Email: dwing-ietf@fuggles.com 1014 6. Security Considerations 1016 Authenticated encryption MUST be used for data confidentiality and 1017 message integrity. TLS based on client certificate MUST be used for 1018 mutual authentication. The interaction between the DOTS agents 1019 requires Transport Layer Security (TLS) with a cipher suite offering 1020 confidentiality protection and the guidance given in [RFC7525] MUST 1021 be followed to avoid attacks on TLS. 1023 An attacker may be able to inject RST packets, bogus application 1024 segments, etc., regardless of whether TLS authentication is used. 1025 Because the application data is TLS protected, this will not result 1026 in the application receiving bogus data, but it will constitute a DoS 1027 on the connection. This attack can be countered by using TCP-AO 1028 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 1029 attacker will be rejected by the TCP-AO integrity check and therefore 1030 will never reach the TLS layer. 1032 In order to prevent leaking internal information outside a client- 1033 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 1034 the identity of internal DOTS clients (client-identifier) unless 1035 explicitly configured to do so. 1037 Special care should be taken in order to ensure that the activation 1038 of the proposed mechanism won't have an impact on the stability of 1039 the network (including connectivity and services delivered over that 1040 network). 1042 Involved functional elements in the cooperation system must establish 1043 exchange instructions and notification over a secure and 1044 authenticated channel. Adequate filters can be enforced to avoid 1045 that nodes outside a trusted domain can inject request such as 1046 deleting filtering rules. Nevertheless, attacks can be initiated 1047 from within the trusted domain if an entity has been corrupted. 1048 Adequate means to monitor trusted nodes should also be enabled. 1050 7. Acknowledgements 1052 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 1053 Doron, Russ White, Jon Shallow, and Gilbert Clark for the discussion 1054 and comments. 1056 8. References 1058 8.1. Normative References 1060 [I-D.ietf-dots-architecture] 1061 Mortensen, A., Andreasen, F., Reddy, T., 1062 christopher_gray3@cable.comcast.com, c., Compton, R., and 1063 N. Teague, "Distributed-Denial-of-Service Open Threat 1064 Signaling (DOTS) Architecture", draft-ietf-dots- 1065 architecture-05 (work in progress), October 2017. 1067 [I-D.ietf-dots-signal-channel] 1068 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 1069 Teague, "Distributed Denial-of-Service Open Threat 1070 Signaling (DOTS) Signal Channel", draft-ietf-dots-signal- 1071 channel-05 (work in progress), October 2017. 1073 [I-D.ietf-netmod-acl-model] 1074 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 1075 "Network Access Control List (ACL) YANG Data Model", 1076 draft-ietf-netmod-acl-model-14 (work in progress), October 1077 2017. 1079 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1080 Requirement Levels", BCP 14, RFC 2119, 1081 DOI 10.17487/RFC2119, March 1997, 1082 . 1084 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1085 (TLS) Protocol Version 1.2", RFC 5246, 1086 DOI 10.17487/RFC5246, August 2008, 1087 . 1089 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 1090 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 1091 June 2010, . 1093 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1094 Protocol (HTTP/1.1): Message Syntax and Routing", 1095 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1096 . 1098 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1099 "Recommendations for Secure Use of Transport Layer 1100 Security (TLS) and Datagram Transport Layer Security 1101 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1102 2015, . 1104 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1105 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1106 . 1108 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1109 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1110 . 1112 8.2. Informative References 1114 [I-D.ietf-dots-requirements] 1115 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 1116 Denial of Service (DDoS) Open Threat Signaling 1117 Requirements", draft-ietf-dots-requirements-06 (work in 1118 progress), July 2017. 1120 [I-D.ietf-netmod-yang-tree-diagrams] 1121 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1122 ietf-netmod-yang-tree-diagrams-02 (work in progress), 1123 October 2017. 1125 [IEEE.754.1985] 1126 Institute of Electrical and Electronics Engineers, 1127 "Standard for Binary Floating-Point Arithmetic", August 1128 1985. 1130 [proto_numbers] 1131 "IANA, "Protocol Numbers"", 2011, 1132 . 1134 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1135 the Network Configuration Protocol (NETCONF)", RFC 6020, 1136 DOI 10.17487/RFC6020, October 2010, 1137 . 1139 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1140 and A. Bierman, Ed., "Network Configuration Protocol 1141 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1142 . 1144 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1145 Layer Security (TLS) and Datagram Transport Layer Security 1146 (DTLS) Heartbeat Extension", RFC 6520, 1147 DOI 10.17487/RFC6520, February 2012, 1148 . 1150 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1151 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1152 2014, . 1154 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1155 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1156 . 1158 Authors' Addresses 1160 Tirumaleswar Reddy 1161 McAfee, Inc. 1162 Embassy Golf Link Business Park 1163 Bangalore, Karnataka 560071 1164 India 1166 Email: kondtir@gmail.com 1168 Mohamed Boucadair 1169 Orange 1170 Rennes 35000 1171 France 1173 Email: mohamed.boucadair@orange.com 1175 Kaname Nishizuka 1176 NTT Communications 1177 GranPark 16F 3-4-1 Shibaura, Minato-ku 1178 Tokyo 108-8118 1179 Japan 1181 Email: kaname@nttv6.jp 1182 Liang Xia 1183 Huawei 1184 101 Software Avenue, Yuhuatai District 1185 Nanjing, Jiangsu 210012 1186 China 1188 Email: frank.xialiang@huawei.com 1190 Prashanth Patil 1191 Cisco Systems, Inc. 1193 Email: praspati@cisco.com 1195 Andrew Mortensen 1196 Arbor Networks, Inc. 1197 2727 S. State St 1198 Ann Arbor, MI 48104 1199 United States 1201 Email: amortensen@arbor.net 1203 Nik Teague 1204 Verisign, Inc. 1205 United States 1207 Email: nteague@verisign.com