idnits 2.17.1 draft-ietf-dots-data-channel-07.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 (November 12, 2017) is 2356 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-06 == 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-07 == 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: May 16, 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 November 12, 2017 18 Distributed Denial-of-Service Open Threat Signaling (DOTS) Data Channel 19 draft-ietf-dots-data-channel-07 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 May 16, 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 . . . . . . . . 22 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 "dz6pHjaADkaFTbjr0JGBpw", 654 "iAYmCNPmrYoKoqzgFMiobw" 655 ], 656 "alias": [ 657 { 658 "alias-name": "Server1", 659 "target-protocol": [ 660 6 661 ], 662 "target-ip": [ 663 "2001:db8:6401::1", 664 "2001:db8:6401::2" 665 ], 666 "target-port-range": [ 667 { 668 "lower-port": 443 669 } 670 ] 671 } 672 ] 673 } 674 } 676 Figure 4: POST to create identifiers 678 The DOTS server indicates the result of processing the POST request 679 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 680 codes are some sort of invalid requests and 5xx codes are returned if 681 the DOTS server has erred or it is incapable of accepting the alias. 682 Response code 201 (Created) will be returned in the response if the 683 DOTS server has accepted the alias. If the request is missing one or 684 more mandatory attributes then 400 (Bad Request) will be returned in 685 the response or if the request contains invalid or unknown parameters 686 then 400 (Invalid query) will be returned in the response. The HTTP 687 response will include the JSON body received in the request. 689 The DOTS client can use the PUT request (Section 4.5 in [RFC8040]) to 690 create or modify the aliases in the DOTS server. 692 3.2.2. Delete Identifiers 694 A DELETE request is used to delete identifiers maintained by a DOTS 695 server (Figure 5). 697 DELETE /restconf/data/ietf-dots-data-channel-identifier:identifier\ 698 /client-identifier=dz6pHjaADkaFTbjr0JGBpw,iAYmCNPmrYoKoqzgFMiobw\ 699 /alias-name=Server1 HTTP/1.1 700 Host: {host}:{port} 702 Figure 5: DELETE identifier 704 In RESTCONF, URI-encoded path expressions are used. A RESTCONF data 705 resource identifier is encoded from left to right, starting with the 706 top-level data node, according to the 'api-path' rule defined in 707 Section 3.5.3.1 of [RFC8040]. The data node in the above path 708 expression is a YANG list node and MUST be encoded according to the 709 rules defined in Section 3.5.1 of [RFC8040]. 711 If the DOTS server does not find the alias name conveyed in the 712 DELETE request in its configuration data, then it responds with a 404 713 (Not Found) error response code. The DOTS server successfully 714 acknowledges a DOTS client's request to remove the identifier using 715 204 (No Content) in the response. 717 3.2.3. Retrieving Installed Identifiers 719 A GET request is used to retrieve the set of installed identifiers 720 from a DOTS server (Section 3.3.1 in [RFC8040]). Figure 6 shows how 721 to retrieve all the identifiers that were instantiated by the DOTS 722 client. The content parameter and its permitted values are defined 723 in Section 4.8.1 of [RFC8040]. 725 GET /restconf/data/ietf-dots-data-channel-identifier:identifier\ 726 /client-identifier=dz6pHjaADkaFTbjr0JGBpw,iAYmCNPmrYoKoqzgFMiobw?\ 727 content=config HTTP/1.1 728 Host: {host}:{port} 729 Accept: application/yang-data+json 731 Figure 6: GET to retrieve all the installed identifiers 733 Figure 7 shows response for all identifiers on the DOTS server. 735 { 736 "ietf-dots-data-channel-identifier:identifier": { 737 "client-identifier": [ 738 "dz6pHjaADkaFTbjr0JGBpw", 739 "iAYmCNPmrYoKoqzgFMiobw" 740 ], 741 "alias": [ 742 { 743 "alias-name": "Server1", 744 "traffic-protocol": [ 745 6 746 ], 747 "ip": [ 748 "2001:db8:6401::1", 749 "2001:db8:6401::2" 750 ], 751 "port-range": [ 752 { 753 "lower-port": 443 754 } 755 ] 756 }, 757 { 758 "alias-name": "Server2", 759 "traffic-protocol": [ 760 6 761 ], 762 "ip": [ 763 "2001:db8:6401::10", 764 "2001:db8:6401::20" 765 ], 766 "port-range": [ 767 { 768 "lower-port": 80 769 } 770 ] 771 } 772 ] 773 } 774 } 776 Figure 7: Response body 778 If the DOTS server does not find the alias name conveyed in the GET 779 request in its configuration data, then it responds with a 404 (Not 780 Found) error response code. 782 3.3. Filtering Rules 784 The DOTS server either receives the filtering rules directly from the 785 DOTS client or via a DOTS gateway. 787 If the DOTS client signals the filtering rules via a DOTS gateway, 788 then the DOTS gateway validates if the DOTS client is authorized to 789 signal the filtering rules and if the client is authorized propagates 790 the rules to the DOTS server. Likewise, the DOTS server validates if 791 the DOTS gateway is authorized to signal the filtering rules. To 792 create or purge filters, the DOTS client sends HTTP requests to its 793 DOTS gateway. The DOTS gateway validates the rules in the requests 794 and proxies the requests containing the filtering rules to a DOTS 795 server. When the DOTS gateway receives the associated HTTP response 796 from the DOTS server, it propagates the response back to the DOTS 797 client. 799 The following APIs define means for a DOTS client to configure 800 filtering rules on a DOTS server. 802 3.3.1. Install Filtering Rules 804 A POST request is used to push filtering rules to a DOTS server. 805 Figure 8 shows a POST request example to block traffic from 806 192.0.2.0/24, destined to 198.51.100.0/24. The ACL JSON 807 configuration for the filtering rule is generated using the ACL YANG 808 data model defined in [I-D.ietf-netmod-acl-model] and the ACL 809 configuration XML for the filtering rule is specified in Section 4.3 810 of [I-D.ietf-netmod-acl-model]. 812 POST /restconf/data/ietf-dots-access-control-list HTTP/1.1 813 Host: www.example.com 814 Content-Format: "application/yang.api+json" 815 { 816 "ietf-dots-access-control-list:access-lists": { 817 "client-identifier": [ 818 "dz6pHjaADkaFTbjr0JGBpw", 819 "iAYmCNPmrYoKoqzgFMiobw" 820 ], 821 "acl": [ 822 { 823 "acl-name": "sample-ipv4-acl", 824 "acl-type": "ipv4-acl", 825 "aces": { 826 "ace": [ 827 { 828 "rule-name": "rule1", 829 "matches": { 830 "ipv4-acl": { 831 "source-ipv4-network": "192.0.2.0/24", 832 "destination-ipv4-network": "198.51.100.0/24" 833 } 834 }, 835 "actions": { 836 "deny": [null] 837 } 838 } 839 ] 840 } 841 } 842 ] 843 } 844 } 846 Figure 8: POST to install filterng rules 848 The header parameters defined in [I-D.ietf-netmod-acl-model] are 849 discussed below: 851 acl-name: The name of access-list. This is a mandatory attribute. 853 acl-type: Indicates the primary intended type of match criteria 854 (e.g. IPv4, IPv6). This is a mandatory attribute. 856 protocol: Internet Protocol numbers. This is an optional 857 attribute. 859 source-ipv4-network: The source IPv4 prefix. This is an optional 860 attribute. 862 destination-ipv4-network: The destination IPv4 prefix. This is an 863 optional attribute. 865 actions: "deny" or "permit" or "rate-limit". "permit" action is 866 used to white-list traffic. "deny" action is used to black-list 867 traffic. "rate-limit" action is used to rate-limit traffic, the 868 allowed traffic rate is represented in bytes per second indicated 869 in IEEE floating point format [IEEE.754.1985]. If actions 870 attribute is not specified in the request then the default action 871 is "deny". This is an optional attribute. 873 The DOTS server indicates the result of processing the POST request 874 using HTTP response codes. HTTP 2xx codes are success, HTTP 4xx 875 codes are some sort of invalid requests and 5xx codes are returned if 876 the DOTS server has erred or it is incapable of configuring the 877 filtering rules. Response code 201 (Created) will be returned in the 878 response if the DOTS server has accepted the filtering rules. If the 879 request is missing one or more mandatory attributes then 400 (Bad 880 Request) will be returned in the response or if the request contains 881 invalid or unknown parameters then 400 (Invalid query) will be 882 returned in the response. 884 The DOTS client can use the PUT request to create or modify the 885 filtering rules in the DOTS server. 887 3.3.2. Remove Filtering Rules 889 A DELETE request is used to delete filtering rules from a DOTS server 890 (Figure 9). 892 DELETE /restconf/data/ietf-dots-access-control-list:access-lists\ 893 /client-identifier=dz6pHjaADkaFTbjr0JGBpw,iAYmCNPmrYoKoqzgFMiobw\ 894 /acl-name=sample-ipv4-acl&acl-type=ipv4-acl HTTP/1.1 895 Host: {host}:{port} 897 Figure 9: DELETE to remove the filtering rules 899 If the DOTS server does not find the access list name and access list 900 type conveyed in the DELETE request in its configuration data, then 901 it responds with a 404 (Not Found) error response code. The DOTS 902 server successfully acknowledges a DOTS client's request to withdraw 903 the filtering rules using 204 (No Content) response code, and removes 904 the filtering rules as soon as possible. 906 3.3.3. Retrieving Installed Filtering Rules 908 The DOTS client periodically queries the DOTS server to check the 909 counters for installed filtering rules. A GET request is used to 910 retrieve filtering rules from a DOTS server. Figure 10 shows how to 911 retrieve all the filtering rules programmed by the DOTS client and 912 the number of matches for the installed filtering rules. 914 GET /restconf/data/ietf-dots-access-control-list:access-lists\ 915 /client-identifier=dz6pHjaADkaFTbjr0JGBpw,iAYmCNPmrYoKoqzgFMiobw?\ 916 content=all HTTP/1.1 917 Host: {host}:{port} 918 Accept: application/yang-data+json 920 Figure 10: GET to retrieve the configuration data and state data for 921 the filtering rules 923 If the DOTS server does not find the access list name and access list 924 type conveyed in the GET request in its configuration data, then it 925 responds with a 404 (Not Found) error response code. 927 4. IANA Considerations 929 This specification registers new parameters for the DOTS data channel 930 and establishes registries for mappings to JSON attributes. 932 4.1. DOTS Data Channel JSON Attribute Mappings Registry 934 A new registry will be requested from IANA, entitled "DOTS data 935 channel JSON attribute Mappings Registry". The registry is to be 936 created as Expert Review Required. 938 4.2. Registration Template 940 JSON Attribute: 941 JSON attribute name. 943 Description: 944 Brief description of the attribute. 946 Change Controller: 947 For Standards Track RFCs, list the "IESG". For others, give the 948 name of the responsible party. Other details (e.g., postal 949 address, email address, home page URI) may also be included. 951 Specification Document(s): 952 Reference to the document or documents that specify the parameter, 953 preferably including URIs that can be used to retrieve copies of 954 the documents. An indication of the relevant sections may also be 955 included but is not required. 957 4.3. Initial Registry Contents 959 o JSON Attribute: "client-identifier" 960 o Description: Client identifier. 961 o Change Controller: IESG 962 o Specification Document(s): this document 964 o JSON Attribute: "alias-name" 965 o Description: Name of alias. 966 o Change Controller: IESG 967 o Specification Document(s): this document 969 o JSON Attribute: "traffic-protocol" 970 o Description: Internet protocol numbers. 971 o Change Controller: IESG 972 o Specification Document(s): this document 974 o JSON Attribute: "port-range" 975 o Description: The port range, lower-port for lower port number and 976 upper-port for upper port number. For TCP, UDP, SCTP, or DCCP: 977 the range of ports (e.g., 80 to 8080). 978 o Change Controller: IESG 979 o Specification Document(s): this document 981 o JSON Attribute: "lower-port" 982 o Description: Lower port number for port range. 983 o Change Controller: IESG 984 o Specification Document(s): this document 986 o JSON Attribute: "upper-port" 987 o Description: Upper port number for port range. 988 o Change Controller: IESG 989 o Specification Document(s): this document 991 o JSON Attribute: "ip" 992 o Description: IP address. 993 o Change Controller: IESG 994 o Specification Document(s): this document 996 o JSON Attribute: "prefix" 997 o Description: IP prefix 998 o Change Controller: IESG 999 o Specification Document(s): this document 1001 o JSON Attribute: "fqdn" 1002 o Description: Fully Qualified Domain Name, is the full name of a 1003 system, rather than just its hostname. For example, "venera" is a 1004 hostname, and "venera.isi.edu" is an FQDN. 1005 o Change Controller: IESG 1006 o Specification Document(s): this document 1008 o JSON Attribute: "uri" 1009 o Description: Uniform Resource Identifier (URI). 1010 o Change Controller: IESG 1011 o Specification Document(s): this document 1013 5. Contributors 1015 The following individuals have contributed to this document: 1017 Dan Wing 1019 Email: dwing-ietf@fuggles.com 1021 6. Security Considerations 1023 Authenticated encryption MUST be used for data confidentiality and 1024 message integrity. TLS based on client certificate MUST be used for 1025 mutual authentication. The interaction between the DOTS agents 1026 requires Transport Layer Security (TLS) with a cipher suite offering 1027 confidentiality protection and the guidance given in [RFC7525] MUST 1028 be followed to avoid attacks on TLS. 1030 An attacker may be able to inject RST packets, bogus application 1031 segments, etc., regardless of whether TLS authentication is used. 1032 Because the application data is TLS protected, this will not result 1033 in the application receiving bogus data, but it will constitute a DoS 1034 on the connection. This attack can be countered by using TCP-AO 1035 [RFC5925]. If TCP-AO is used, then any bogus packets injected by an 1036 attacker will be rejected by the TCP-AO integrity check and therefore 1037 will never reach the TLS layer. 1039 In order to prevent leaking internal information outside a client- 1040 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 1041 the identity of internal DOTS clients (client-identifier) unless 1042 explicitly configured to do so. 1044 Special care should be taken in order to ensure that the activation 1045 of the proposed mechanism won't have an impact on the stability of 1046 the network (including connectivity and services delivered over that 1047 network). 1049 Involved functional elements in the cooperation system must establish 1050 exchange instructions and notification over a secure and 1051 authenticated channel. Adequate filters can be enforced to avoid 1052 that nodes outside a trusted domain can inject request such as 1053 deleting filtering rules. Nevertheless, attacks can be initiated 1054 from within the trusted domain if an entity has been corrupted. 1055 Adequate means to monitor trusted nodes should also be enabled. 1057 7. Acknowledgements 1059 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Ehud 1060 Doron, Russ White, Jon Shallow, and Gilbert Clark for the discussion 1061 and comments. 1063 8. References 1065 8.1. Normative References 1067 [I-D.ietf-dots-architecture] 1068 Mortensen, A., Andreasen, F., Reddy, T., 1069 christopher_gray3@cable.comcast.com, c., Compton, R., and 1070 N. Teague, "Distributed-Denial-of-Service Open Threat 1071 Signaling (DOTS) Architecture", draft-ietf-dots- 1072 architecture-05 (work in progress), October 2017. 1074 [I-D.ietf-dots-signal-channel] 1075 Reddy, T., Boucadair, M., Patil, P., Mortensen, A., and N. 1076 Teague, "Distributed Denial-of-Service Open Threat 1077 Signaling (DOTS) Signal Channel", draft-ietf-dots-signal- 1078 channel-06 (work in progress), October 2017. 1080 [I-D.ietf-netmod-acl-model] 1081 Jethanandani, M., Huang, L., Agarwal, S., and D. Blair, 1082 "Network Access Control List (ACL) YANG Data Model", 1083 draft-ietf-netmod-acl-model-14 (work in progress), October 1084 2017. 1086 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1087 Requirement Levels", BCP 14, RFC 2119, 1088 DOI 10.17487/RFC2119, March 1997, 1089 . 1091 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1092 (TLS) Protocol Version 1.2", RFC 5246, 1093 DOI 10.17487/RFC5246, August 2008, 1094 . 1096 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 1097 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 1098 June 2010, . 1100 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1101 Protocol (HTTP/1.1): Message Syntax and Routing", 1102 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1103 . 1105 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1106 "Recommendations for Secure Use of Transport Layer 1107 Security (TLS) and Datagram Transport Layer Security 1108 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 1109 2015, . 1111 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1112 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1113 . 1115 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1116 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1117 . 1119 8.2. Informative References 1121 [I-D.ietf-dots-requirements] 1122 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 1123 Denial of Service (DDoS) Open Threat Signaling 1124 Requirements", draft-ietf-dots-requirements-07 (work in 1125 progress), October 2017. 1127 [I-D.ietf-netmod-yang-tree-diagrams] 1128 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 1129 ietf-netmod-yang-tree-diagrams-02 (work in progress), 1130 October 2017. 1132 [IEEE.754.1985] 1133 Institute of Electrical and Electronics Engineers, 1134 "Standard for Binary Floating-Point Arithmetic", August 1135 1985. 1137 [proto_numbers] 1138 "IANA, "Protocol Numbers"", 2011, 1139 . 1141 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1142 the Network Configuration Protocol (NETCONF)", RFC 6020, 1143 DOI 10.17487/RFC6020, October 2010, 1144 . 1146 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1147 and A. Bierman, Ed., "Network Configuration Protocol 1148 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1149 . 1151 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 1152 Layer Security (TLS) and Datagram Transport Layer Security 1153 (DTLS) Heartbeat Extension", RFC 6520, 1154 DOI 10.17487/RFC6520, February 2012, 1155 . 1157 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1158 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1159 2014, . 1161 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1162 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1163 . 1165 Authors' Addresses 1167 Tirumaleswar Reddy 1168 McAfee, Inc. 1169 Embassy Golf Link Business Park 1170 Bangalore, Karnataka 560071 1171 India 1173 Email: kondtir@gmail.com 1175 Mohamed Boucadair 1176 Orange 1177 Rennes 35000 1178 France 1180 Email: mohamed.boucadair@orange.com 1181 Kaname Nishizuka 1182 NTT Communications 1183 GranPark 16F 3-4-1 Shibaura, Minato-ku 1184 Tokyo 108-8118 1185 Japan 1187 Email: kaname@nttv6.jp 1189 Liang Xia 1190 Huawei 1191 101 Software Avenue, Yuhuatai District 1192 Nanjing, Jiangsu 210012 1193 China 1195 Email: frank.xialiang@huawei.com 1197 Prashanth Patil 1198 Cisco Systems, Inc. 1200 Email: praspati@cisco.com 1202 Andrew Mortensen 1203 Arbor Networks, Inc. 1204 2727 S. State St 1205 Ann Arbor, MI 48104 1206 United States 1208 Email: amortensen@arbor.net 1210 Nik Teague 1211 Verisign, Inc. 1212 United States 1214 Email: nteague@verisign.com