idnits 2.17.1 draft-ietf-dots-signal-channel-09.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 is 1 instance of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([RFCXXXX]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1638 has weird spacing: '...er-port ine...' == Line 1639 has weird spacing: '...er-port ine...' -- The document date (November 27, 2017) is 2342 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) == Missing Reference: 'RFCXXXX' is mentioned on line 2196, but not defined == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-10 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6234 ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-01 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-05 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-05 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-08 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-07 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-09 == Outdated reference: A later version (-06) exists of draft-ietf-netmod-yang-tree-diagrams-02 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-21 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5077 (Obsoleted by RFC 8446) -- Obsolete informational reference (is this intentional?): RFC 6555 (Obsoleted by RFC 8305) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 8 errors (**), 0 flaws (~~), 14 warnings (==), 5 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 31, 2018 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 November 27, 2017 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel 16 draft-ietf-dots-signal-channel-09 18 Abstract 20 This document specifies the DOTS signal channel, a protocol for 21 signaling the need for protection against Distributed Denial-of- 22 Service (DDoS) attacks to a server capable of enabling network 23 traffic mitigation on behalf of the requesting client. 25 A companion document defines the DOTS data channel, a separate 26 reliable communication layer for DOTS management and configuration. 28 Editorial Note (To be removed by RFC Editor) 30 Please update these statements with the RFC number to be assigned to 31 this document: 33 o "This version of this YANG module is part of RFC XXXX;" 35 o "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 36 (DOTS) Signal Channel"; 38 o "| 3.00 | Alternate server | [RFCXXXX] |" 40 o reference: RFC XXXX 42 Status of This Memo 44 This Internet-Draft is submitted in full conformance with the 45 provisions of BCP 78 and BCP 79. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at https://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on May 31, 2018. 59 Copyright Notice 61 Copyright (c) 2017 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (https://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. Code Components extracted from this document must 70 include Simplified BSD License text as described in Section 4.e of 71 the Trust Legal Provisions and are provided without warranty as 72 described in the Simplified BSD License. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 77 2. Notational Conventions and Terminology . . . . . . . . . . . 5 78 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 5 79 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 7 80 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 7 81 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 7 82 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 8 83 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 9 84 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 10 85 4.4.2. Withdraw a Mitigation . . . . . . . . . . . . . . . . 18 86 4.4.3. Retrieve Information Related to a Mitigation . . . . 19 87 4.4.4. Efficacy Update from DOTS Clients . . . . . . . . . . 25 88 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 27 89 4.5.1. Discover Configuration Parameters . . . . . . . . . . 28 90 4.5.2. Convey DOTS Signal Channel Session Configuration . . 30 91 4.5.3. Delete DOTS Signal Channel Session Configuration . . 34 92 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 35 93 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 36 94 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 37 95 5.1. Mitigation Request YANG Module Tree Structure . . . . . . 37 96 5.2. Mitigation Request YANG Module . . . . . . . . . . . . . 38 97 5.3. Session Configuration YANG Module Tree Structure . . . . 41 98 5.4. Session Configuration YANG Module . . . . . . . . . . . . 41 99 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 44 100 7. (D)TLS Protocol Profile and Performance Considerations . . . 45 101 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 46 102 7.2. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 47 103 8. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . . . 48 104 9. Mutual Authentication of DOTS Agents & Authorization of DOTS 105 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 106 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50 107 10.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . 50 108 10.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . 50 109 10.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 50 110 10.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 51 111 10.4.1. Registration Template . . . . . . . . . . . . . . . 51 112 10.4.2. Initial Registry Contents . . . . . . . . . . . . . 51 113 10.5. YANG Modules . . . . . . . . . . . . . . . . . . . . . . 56 114 11. Implementation Status . . . . . . . . . . . . . . . . . . . . 56 115 11.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 57 116 12. Security Considerations . . . . . . . . . . . . . . . . . . . 57 117 13. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 58 118 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 58 119 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 59 120 15.1. Normative References . . . . . . . . . . . . . . . . . . 59 121 15.2. Informative References . . . . . . . . . . . . . . . . . 60 122 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 63 124 1. Introduction 126 A distributed denial-of-service (DDoS) attack is an attempt to make 127 machines or network resources unavailable to their intended users. 128 In most cases, sufficient scale can be achieved by compromising 129 enough end-hosts and using those infected hosts to perpetrate and 130 amplify the attack. The victim in this attack can be an application 131 server, a host, a router, a firewall, or an entire network. 133 Network applications have finite resources like CPU cycles, number of 134 processes or threads they can create and use, maximum number of 135 simultaneous connections it can handle, limited resources of the 136 control plane, etc. When processing network traffic, such 137 applications are supposed to use these resources to offer the 138 intended task in the most efficient fashion. However, a DDoS 139 attacker may be able to prevent an application from performing its 140 intended task by causing the application to exhaust the finite supply 141 of a specific resource. 143 TCP DDoS SYN-flood, for example, is a memory-exhaustion attack on the 144 victim and ACK-flood is a CPU exhaustion attack on the victim 146 [RFC4987]. Attacks on the link are carried out by sending enough 147 traffic such that the link becomes excessively congested, and 148 legitimate traffic suffers high packet loss. Stateful firewalls can 149 also be attacked by sending traffic that causes the firewall to hold 150 excessive state. The firewall then runs out of memory, and can no 151 longer instantiate the state required to pass legitimate flows. 152 Other possible DDoS attacks are discussed in [RFC4732]. 154 In many cases, it may not be possible for network administrators to 155 determine the causes of an attack, but instead just realize that 156 certain resources seem to be under attack. This document defines a 157 lightweight protocol permitting a DOTS client to request mitigation 158 from one or more DOTS servers for protection against detected, 159 suspected, or anticipated attacks. This protocol enables cooperation 160 between DOTS agents to permit a highly-automated network defense that 161 is robust, reliable and secure. 163 An example of network diagram showing a deployment of DOTS agents is 164 shown in Figure 1. In this example, the DOTS server is operating on 165 the access network. 167 Network 168 Resource CPE router Access network __________ 169 +-----------+ +--------------+ +-------------+ / \ 170 | |____| |_______| |___ | Internet | 171 |DOTS client| | DOTS gateway | | DOTS server | | | 172 | | | | | | | | 173 +-----------+ +--------------+ +-------------+ \__________/ 175 Figure 1: Sample DOTS Deployment (1) 177 The DOTS server can also be running on the Internet, as depicted in 178 Figure 2. 180 Network DDoS mitigation 181 Resource CPE router __________ service 182 +-----------+ +-------------+ / \ +-------------+ 183 | |____| |_______| |___ | | 184 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 185 | | | | | | | | 186 +-----------+ +-------------+ \__________/ +-------------+ 188 Figure 2: Sample DOTS Deployment (2) 190 In typical deployments, the DOTS client belongs to a different 191 administrative domain than the DOTS server. For example, the DOTS 192 client is a firewall protecting services owned and operated by an 193 domain, while the DOTS server is owned and operated by a different 194 domain providing DDoS mitigation services. That domain providing 195 DDoS mitigation service might, or might not, also provide Internet 196 access service to the website operator. 198 The DOTS server may (not) be co-located with the DOTS mitigator. In 199 typical deployments, the DOTS server belongs to the same 200 administrative domain as the mitigator. The DOTS client can 201 communicate directly with the DOTS server or indirectly via a DOTS 202 gateway. 204 The document adheres to the DOTS architecture 205 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 206 channel protocol are obtained from [I-D.ietf-dots-requirements]. 207 This document satisfies all the use cases discussed in 208 [I-D.ietf-dots-use-cases]. 210 This document focuses on the DOTS signal channel. This is a 211 companion document to the DOTS data channel specification 212 [I-D.ietf-dots-data-channel] that defines a configuration and bulk 213 data exchange mechanism supporting the DOTS signal channel. 215 2. Notational Conventions and Terminology 217 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 218 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 219 "OPTIONAL" in this document are to be interpreted as described in 220 [RFC2119]. 222 (D)TLS: For brevity this term is used for statements that apply to 223 both Transport Layer Security [RFC5246] and Datagram Transport Layer 224 Security [RFC6347]. Specific terms will be used for any statement 225 that applies to either protocol alone. 227 The reader should be familiar with the terms defined in 228 [I-D.ietf-dots-architecture]. 230 The meaning of the symbols in YANG tree diagrams is defined in 231 [I-D.ietf-netmod-yang-tree-diagrams]. 233 3. Design Overview 235 The DOTS signal channel is built on top of the Constrained 236 Application Protocol (CoAP) [RFC7252], a lightweight protocol 237 originally designed for constrained devices and networks. CoAP's 238 expectation of packet loss, support for asynchronous non-confirmable 239 messaging, congestion control, small message overhead limiting the 240 need for fragmentation, use of minimal resources, and support for 241 (D)TLS make it a good foundation on which to build the DOTS signaling 242 mechanism. 244 The DOTS signal channel is layered on existing standards (Figure 3). 246 +--------------+ 247 | DOTS | 248 +--------------+ 249 | CoAP | 250 +--------------+ 251 | TLS | DTLS | 252 +--------------+ 253 | TCP | UDP | 254 +--------------+ 255 | IP | 256 +--------------+ 258 Figure 3: Abstract Layering of DOTS signal channel over CoAP over 259 (D)TLS 261 By default, DOTS signal channel MUST run over port number TBD as 262 defined in Section 10.1, for both UDP and TCP, unless the DOTS server 263 has mutual agreement with its DOTS clients to use a port other than 264 TBD for DOTS signal channel, or DOTS clients supports means to 265 dynamically discover the ports used by their DOTS servers. In order 266 to use a distinct port number (vs. TBD), DOTS clients and servers 267 should support a configurable parameter to supply the port number to 268 use. 270 The signal channel is initiated by the DOTS client (Section 4.4). 271 Once the signal channel is established, the DOTS agents periodically 272 send heartbeats to keep the channel active (Section 4.7). At any 273 time, the DOTS client may send a mitigation request message to a DOTS 274 server over the active channel. While mitigation is active, due to 275 the higher likelihood of packet loss during a DDoS attack, the DOTS 276 server periodically sends status messages to the client, including 277 basic mitigation feedback details. Mitigation remains active until 278 the DOTS client explicitly terminates mitigation, or the mitigation 279 lifetime expires. 281 DOTS signaling can happen with DTLS [RFC6347] over UDP and TLS 282 [RFC5246] over TCP. Likewise, requests may be sent using IPv4 or 283 IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS 284 signal channel is specified in Section 4.3. 286 Messages exchanged between DOTS clients and servers are serialized 287 using Concise Binary Object Representation (CBOR) [RFC7049], CBOR is 288 a binary encoding designed for small code and message size. CBOR 289 encoded payloads are used to convey signal channel specific payload 290 messages that convey request parameters and response information such 291 as errors. This specification uses the encoding rules defined in 292 [I-D.ietf-core-yang-cbor] for representing mitigation scope and DOTS 293 signal channel session configuration data defined using YANG 294 (Section 5) as CBOR data. 296 In order to prevent fragmentation, DOTS agents must follow the 297 recommendations in Section 4.6 of [RFC7252]. Refer to Section 7.2 298 for more details. 300 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 301 payload included in CoAP responses with 2.xx and 3.xx Response Codes 302 MUST be of content type "application/cbor" (Section 5.5.1 of 303 [RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes 304 MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The 305 Diagnostic Payload may contain additional information to aid 306 troubleshooting. 308 4. DOTS Signal Channel: Messages & Behaviors 310 4.1. DOTS Server(s) Discovery 312 This document assumes that DOTS clients are provisioned with the 313 reachability information of their DOTS server(s) using a variety of 314 means (e.g., local configuration, or dynamic means such as DHCP). 315 These means are out of scope of this document. 317 Likewise, it is out of scope of this document to specify the behavior 318 to follow by a DOTS client to place its requests (e.g., contact all 319 servers, select one server among the list) when multiple DOTS servers 320 are provisioned. 322 4.2. CoAP URIs 324 The DOTS server MUST support the use of the path-prefix of "/.well- 325 known/" as defined in [RFC5785] and the registered name of "dots". 326 Each DOTS operation is indicated by a path-suffix that indicates the 327 intended operation. 329 +-----------------------+----------------+-------------+ 330 | Operation | Operation path | Details | 331 +-----------------------+----------------+-------------+ 332 | Mitigation | /v1/mitigate | Section 4.4 | 333 +-----------------------+----------------+-------------+ 334 | Session configuration | /v1/config | Section 4.5 | 335 +-----------------------+----------------+-------------+ 337 Table 1: Operations and their corresponding URIs 339 4.3. Happy Eyeballs for DOTS Signal Channel 341 DOTS signaling can happen with DTLS over UDP and TLS over TCP. A 342 DOTS client can use DNS to determine the IP address(es) of a DOTS 343 server or a DOTS client may be provided with the list of DOTS server 344 IP addresses. The DOTS client MUST know a DOTS server's domain name; 345 hard-coding the domain name of the DOTS server into software is NOT 346 RECOMMENDED in case the domain name is not valid or needs to change 347 for legal or other reasons. The DOTS client performs A and/or AAAA 348 record lookup of the domain name and the result will be a list of IP 349 addresses, each of which can be used to contact the DOTS server using 350 UDP and TCP. 352 If an IPv4 path to reach a DOTS server is found, but the DOTS 353 server's IPv6 path is not working, a dual-stack DOTS client can 354 experience a significant connection delay compared to an IPv4-only 355 DOTS client. The other problem is that if a middlebox between the 356 DOTS client and DOTS server is configured to block UDP, the DOTS 357 client will fail to establish a DTLS session with the DOTS server and 358 will, then, have to fall back to TLS over TCP incurring significant 359 connection delays. [I-D.ietf-dots-requirements] discusses that DOTS 360 client and server will have to support both connectionless and 361 connection-oriented protocols. 363 To overcome these connection setup problems, the DOTS client can try 364 connecting to the DOTS server using both IPv6 and IPv4, and try both 365 DTLS over UDP and TLS over TCP in a fashion similar to the Happy 366 Eyeballs mechanism [RFC6555]. These connection attempts are 367 performed by the DOTS client when its initializes, and the client 368 uses that information for its subsequent alert to the DOTS server. 369 In order of preference (most preferred first), it is UDP over IPv6, 370 UDP over IPv4, TCP over IPv6, and finally TCP over IPv4, which 371 adheres to address preference order [RFC6724] and the DOTS preference 372 that UDP be used over TCP (to avoid TCP's head of line blocking). 374 DOTS client DOTS server 375 | | 376 |--DTLS ClientHello, IPv6 ---->X | 377 |--TCP SYN, IPv6-------------->X | 378 |--DTLS ClientHello, IPv4 ---->X | 379 |--TCP SYN, IPv4----------------------------------------->| 380 |--DTLS ClientHello, IPv6 ---->X | 381 |--TCP SYN, IPv6-------------->X | 382 |<-TCP SYNACK---------------------------------------------| 383 |--DTLS ClientHello, IPv4 ---->X | 384 |--TCP ACK----------------------------------------------->| 385 |<------------Establish TLS Session---------------------->| 386 |----------------DOTS signal----------------------------->| 387 | | 389 Figure 4: DOTS Happy Eyeballs 391 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 392 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 393 this example, it is assumed that the IPv6 path is broken and UDP is 394 dropped by a middlebox but has little impact to the DOTS client 395 because there is no long delay before using IPv4 and TCP. The DOTS 396 client repeats the mechanism to discover if DOTS signaling with DTLS 397 over UDP becomes available from the DOTS server, so the DOTS client 398 can migrate the DOTS signal channel from TCP to UDP, but such probing 399 SHOULD NOT be done more frequently than every 24 hours and MUST NOT 400 be done more frequently than every 5 minutes. 402 4.4. DOTS Mitigation Methods 404 The following methods are used by a DOTS client to request, withdraw, 405 or retrieve the status of mitigation requests: 407 PUT: DOTS clients use the PUT method to request mitigation from a 408 DOTS server (Section 4.4.1). During active mitigation, DOTS 409 clients may use PUT requests to convey mitigation efficacy updates 410 to the DOTS server (Section 4.4.4). 412 DELETE: DOTS clients use the DELETE method to withdraw a request for 413 mitigation from the DOTS server (Section 4.4.2). 415 GET: DOTS clients may use the GET method to subscribe to DOTS server 416 status messages, or to retrieve the list of existing mitigations 417 (Section 4.4.3). 419 Mitigation request and response messages are marked as Non- 420 confirmable messages. DOTS agents SHOULD follow the data 421 transmission guidelines discussed in Section 3.1.3 of [RFC8085] and 422 control transmission behavior by not sending on average more than one 423 UDP datagram per RTT to the peer DOTS agent. 425 Requests marked by the DOTS client as Non-confirmable messages are 426 sent at regular intervals until a response is received from the DOTS 427 server. If the DOTS client cannot maintain an RTT estimate, it 428 SHOULD NOT send more than one Non-confirmable request every 3 429 seconds, and SHOULD use an even less aggressive rate when possible 430 (case 2 in Section 3.1.3 of [RFC8085]). 432 4.4.1. Request Mitigation 434 When a DOTS client requires mitigation for any reason, the DOTS 435 client uses CoAP PUT method to send a mitigation request to the DOTS 436 server(s) (Figure 5, illustrated in JSON diagnostic notation). If 437 this DOTS client is entitled to solicit the DOTS service, the DOTS 438 server can enable mitigation on behalf of the DOTS client by 439 communicating the DOTS client's request to the mitigator and relaying 440 selected mitigator feedback to the requesting DOTS client. 442 Header: PUT (Code=0.03) 443 Uri-Host: "host" 444 Uri-Path: ".well-known" 445 Uri-Path: "dots" 446 Uri-Path: "version" 447 Uri-Path: "mitigate" 448 Content-Type: "application/cbor" 449 { 450 "mitigation-scope": { 451 "client-identifier": [ 452 "string" 453 ], 454 "scope": [ 455 { 456 "mitigation-id": integer, 457 "target-ip": [ 458 "string" 459 ], 460 "target-prefix": [ 461 "string" 462 ], 463 "target-port-range": [ 464 { 465 "lower-port": integer, 466 "upper-port": integer 467 } 468 ], 469 "target-protocol": [ 470 integer 471 ], 472 "fqdn": [ 473 "string" 474 ], 475 "uri": [ 476 "string" 477 ], 478 "alias-name": [ 479 "string" 480 ], 481 "lifetime": integer 482 } 483 ] 484 } 485 } 487 Figure 5: PUT to convey DOTS signals 489 The parameters are described below: 491 client-identifier: The client identifier MAY be conveyed by the DOTS 492 gateway to propagate the DOTS client identity from the gateway's 493 client-side to the gateway's server-side, and from the gateway's 494 server-side to the DOTS server. This allows the final DOTS server 495 to accept mitigation requests with scopes which the DOTS client is 496 authorized to manage. 498 The 'client-identifier' value MUST be assigned by the DOTS gateway 499 in a manner that ensures that there is no probability that the 500 same value will be assigned to a different DOTS client. The DOTS 501 gateway MUST obscure potentially sensitive DOTS client identity 502 information. The client-identifier attribute SHOULD NOT to be 503 generated and included by the DOTS client. 505 This is an optional attribute. 507 mitigation-id: Identifier for the mitigation request represented 508 using an integer. This identifier MUST be unique for each 509 mitigation request bound to the DOTS client, i.e., the mitigation- 510 id parameter value in the mitigation request needs to be unique 511 relative to the mitigation-id parameter values of active 512 mitigation requests conveyed from the DOTS client to the DOTS 513 server. This identifier MUST be generated by the DOTS client. 514 This document does not make any assumption about how this 515 identifier is generated. This is a mandatory attribute. 517 target-ip: A list of IP addresses under attack. This is an optional 518 attribute. 520 target-prefix: A list of prefixes under attack. Prefixes are 521 represented using CIDR notation [RFC4632]. This is an optional 522 attribute. 524 target-port-range: A list of ports under attack. The port range, 525 lower-port for lower port number and upper-port for upper port 526 number. When only lower-port is present, it represents a single 527 port. For TCP, UDP, Stream Control Transmission Protocol (SCTP) 528 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 529 [RFC4340]: the range of ports (e.g., 1024-65535). This is an 530 optional attribute. 532 target-protocol: A list of protocols under attack. Values are taken 533 from the IANA protocol registry [proto_numbers]. The value 0 has 534 a special meaning for 'all protocols'. This is an optional 535 attribute. 537 fqdn: A list of Fully Qualified Domain Names. Fully Qualified 538 Domain Name (FQDN) is the full name of a system, rather than just 539 its hostname. For example, "venera" is a hostname, and 540 "venera.isi.edu" is an FQDN. This is an optional attribute. 542 uri: A list of Uniform Resource Identifiers (URI). This is an 543 optional attribute. 545 alias-name: A list of aliases. Aliases can be created using the 546 DOTS data channel (Section 3.1.1 of [I-D.ietf-dots-data-channel]) 547 or direct configuration, or other means and then used in 548 subsequent signal channel exchanges to refer more efficiently to 549 the resources under attack. This is an optional attribute. 551 lifetime: Lifetime of the mitigation request in seconds. The 552 RECOMMENDED lifetime of a mitigation request is 3600 seconds (60 553 minutes) -- this value was chosen to be long enough so that 554 refreshing is not typically a burden on the DOTS client, while 555 expiring the request where the client has unexpectedly quit in a 556 timely manner. 558 A lifetime of negative one (-1) indicates indefinite lifetime for 559 the mitigation request. A lifetime of 0 in the request is an 560 invalid value. 562 DOTS clients MUST include this parameter in their mitigation 563 requests. Upon the expiry of this lifetime, and if the request is 564 not refreshed, the mitigation request is removed. The request can 565 be refreshed by sending the same request again. The server MAY 566 refuse indefinite lifetime, for policy reasons; the granted 567 lifetime value is returned in the response. DOTS clients MUST be 568 prepared to not be granted mitigations with indefinite lifetimes. 569 The server MUST always indicate the actual lifetime in the 570 response and the remaining lifetime in status messages sent to the 571 client. This is a mandatory attribute. 573 The CBOR key values for the parameters are defined in Section 6. 574 Section 10 defines how the CBOR key values can be allocated to 575 standards bodies and vendors. 577 FQDN and URI mitigation scopes may be thought of as a form of scope 578 alias, in which the addresses to which the domain name or URI resolve 579 represent the full scope of the mitigation. 581 In the PUT request at least one of the attributes 'target-ip' or 582 'target-prefix' or 'fqdn' or 'uri 'or 'alias-name' MUST be present. 583 If the attribute value is empty, then the attribute MUST NOT be 584 present in the request. DOTS agents can safely ignore Vendor- 585 Specific parameters they don't understand. 587 The relative order of two mitigation requests from a DOTS client is 588 determined by comparing their respective 'mitigation-id' values. If 589 two mitigation requests have overlapping mitigation scopes, the 590 mitigation request with higher numeric 'mitigation-id' value will 591 override the mitigation request with a lower numeric 'mitigation-id' 592 value. Two mitigation-ids from a DOTS client are overlapping if 593 there is a common IP address, IP prefix, FQDN, URI, or alias-name. 594 To avoid maintaining a long list of overlapping mitigation requests 595 from a DOTS client and avoid error-prone provisioning of mitigation 596 requests from a DOTS client, the overlapped lower numeric 597 'mitigation-id' MUST be automatically deleted and no longer available 598 at the DOTS server. 600 The Uri-Path option carries a major and minor version nomenclature to 601 manage versioning and DOTS signal channel in this specification uses 602 v1 major version. 604 If the DOTS client is using the certificate provisioned by the 605 Enrollment over Secure Transport (EST) server [RFC7030] in the DOTS 606 gateway-domain to authenticate itself to the DOTS gateway, then the 607 'client-identifier' value can be the output of a cryptographic hash 608 algorithm whose input is the DER-encoded ASN.1 representation of the 609 Subject Public Key Info (SPKI) of an X.509 certificate. In this 610 version of the specification, the cryptographic hash algorithm used 611 is SHA-256 [RFC6234]. The output of the cryptographic hash algorithm 612 is truncated to 16 bytes; truncation is done by stripping off the 613 final 16 bytes. The truncated output is base64url encoded. If the 614 'client-identifier' value is already present in the mitigation 615 request received from the DOTS client, the DOTS gateway MAY compute 616 the 'client-identifier' value, as discussed above, and add the 617 computed 'client-identifier' value to the end of the 'client- 618 identifier' list. The DOTS server MUST NOT use the 'client- 619 identifier' for the DOTS client authentication process. 621 In both DOTS signal and data channel sessions, the DOTS client MUST 622 authenticate itself to the DOTS server (Section 9). The DOTS server 623 may use the algorithm in Section 7 of [RFC7589] to derive the DOTS 624 client identity or username from the client certificate. The DOTS 625 client identity allows the DOTS server to accept mitigation requests 626 with scopes which the DOTS client is authorized to manage. The DOTS 627 server couples the DOTS signal and data channel sessions using the 628 DOTS client identity and the 'client-identifier' parameter value, so 629 the DOTS server can validate whether the aliases conveyed in the 630 mitigation request were indeed created by the same DOTS client using 631 the DOTS data channel session. If the aliases were not created by 632 the DOTS client, the DOTS server returns 4.00 (Bad Request) in the 633 response. 635 The DOTS server couples the DOTS signal channel sessions using the 636 DOTS client identity and the 'client-identifier' parameter value, and 637 the DOTS server uses 'mitigation-id' parameter value to detect 638 duplicate mitigation requests. If the mitigation request contains 639 both alias-name and other parameters identifying the target resources 640 (such as, 'target-ip', 'target-prefix', 'target-port-range', 'fqdn', 641 or 'uri'), then the DOTS server appends the parameter values in 642 'alias-name' with the corresponding parameter values in 'target-ip', 643 'target-prefix', 'target-port-range', 'fqdn', or 'uri'. 645 Figure 6 shows a PUT request example to signal that ports 80, 8080, 646 and 443 on the servers 2001:db8:6401::1 and 2001:db8:6401::2 are 647 being attacked (illustrated in JSON diagnostic notation). 649 Header: PUT (Code=0.03) 650 Uri-Host: "www.example.com" 651 Uri-Path: ".well-known" 652 Uri-Path: "dots" 653 Uri-Path: "v1" 654 Uri-Path: "mitigate" 655 Content-Format: "application/cbor" 656 { 657 "mitigation-scope": { 658 "client-identifier": [ 659 "dz6pHjaADkaFTbjr0JGBpw" 660 ], 661 "scope": [ 662 { 663 "mitigation-id": 12332, 664 "target-ip": [ 665 "2001:db8:6401::1", 666 "2001:db8:6401::2" 667 ], 668 "target-port-range": [ 669 { 670 "lower-port": 80 671 }, 672 { 673 "lower-port": 443 674 }, 675 { 676 "lower-port": 8080 677 } 678 ], 679 "target-protocol": [ 680 6 681 ] 682 } 684 ] 685 } 686 } 688 The CBOR encoding format is shown below: 690 A1 # map(1) 691 01 # unsigned(1) 692 A2 # map(2) 693 18 20 # unsigned(32) 694 81 # array(1) 695 76 # text(22) 696 647A3670486A6141446B614654626A72304A47427077 # "dz6pHjaADkaFTbjr0JGBpw" 697 02 # unsigned(2) 698 81 # array(1) 699 A4 # map(4) 700 03 # unsigned(3) 701 19 302C # unsigned(12332) 702 04 # unsigned(4) 703 82 # array(2) 704 70 # text(16) 705 323030313A6462383A363430313A3A31 # "2001:db8:6401::1" 706 70 # text(16) 707 323030313A6462383A363430313A3A32 # "2001:db8:6401::2" 708 05 # unsigned(5) 709 83 # array(3) 710 A1 # map(1) 711 06 # unsigned(6) 712 18 50 # unsigned(80) 713 A1 # map(1) 714 06 # unsigned(6) 715 19 01BB # unsigned(443) 716 A1 # map(1) 717 06 # unsigned(6) 718 19 1F90 # unsigned(8080) 719 08 # unsigned(8) 720 81 # array(1) 721 06 # unsigned(6) 723 Figure 6: PUT for DOTS signal 725 The DOTS server indicates the result of processing the PUT request 726 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 727 codes are some sort of invalid requests (client errors). COAP 5.xx 728 codes are returned if the DOTS server has erred or is currently 729 unavailable to provide mitigation in response to the mitigation 730 request from the DOTS client. 732 Figure 7 shows an example of a PUT request that is successfully 733 processed (i.e., CoAP 2.xx response codes). 735 { 736 "mitigation-scope": { 737 "client-identifier": [ 738 "string" 739 ], 740 "scope": [ 741 { 742 "mitigation-id": integer, 743 "lifetime": integer 744 } 745 ] 746 } 747 } 749 Figure 7: 2.xx response body 751 If the DOTS server does not find the 'mitigation-id' parameter value 752 conveyed in the PUT request in its configuration data, then the 753 server MAY accept the mitigation request by sending back a 2.01 754 (Created) response to the DOTS client; the DOTS server will 755 consequently try to mitigate the attack. 757 If the DOTS server finds the 'mitigation-id' parameter value conveyed 758 in the PUT request in its configuration data, then the server MAY 759 update the mitigation request, and a 2.04 (Changed) response is 760 returned to indicate a successful update of the mitigation request. 762 If the request is missing one or more mandatory attributes, then 4.00 763 (Bad Request) will be returned in the response or if the request 764 contains invalid or unknown parameters then 4.02 (Invalid query) is 765 returned in the response. 767 For a mitigation request to continue beyond the initial negotiated 768 lifetime, the DOTS client need to refresh the current mitigation 769 request by sending a new PUT request. The PUT request MUST use the 770 same 'mitigation-id' value, and MUST repeat all the other parameters 771 as sent in the original mitigation request apart from a possible 772 change to the lifetime parameter value. 774 A DOTS gateway MUST update the 'client-identifier' list in the 775 response to remove the 'client-identifier' value it had added in the 776 corresponding request before forwarding the response to the DOTS 777 client. 779 4.4.2. Withdraw a Mitigation 781 A DELETE request is used to withdraw a DOTS mitigation request from a 782 DOTS server (Figure 8). 784 Header: DELETE (Code=0.04) 785 Uri-Host: "host" 786 Uri-Path: ".well-known" 787 Uri-Path: "dots" 788 Uri-Path: "version" 789 Uri-Path: "mitigate" 790 Content-Format: "application/cbor" 791 { 792 "mitigation-scope": { 793 "client-identifier": [ 794 "string" 795 ], 796 "scope": [ 797 { 798 "mitigation-id": integer 799 } 800 ] 801 } 802 } 804 Figure 8: Withdraw DOTS signal 806 The DOTS server immediately acknowledges a DOTS client's request to 807 withdraw the DOTS signal using 2.02 (Deleted) response code with no 808 response payload. A 2.02 (Deleted) Response Code is returned even if 809 the 'mitigation-id' parameter value conveyed in the DELETE request 810 does not exist in its configuration data before the request. 812 If the DOTS server finds the 'mitigation-id' parameter value conveyed 813 in the DELETE request in its configuration data, then to protect 814 against route or DNS flapping caused by a client rapidly toggling 815 mitigation, and to dampen the effect of oscillating attacks, DOTS 816 servers MAY allow mitigation to continue for a limited period after 817 acknowledging a DOTS client's withdrawal of a mitigation request. 818 During this period, the DOTS server status messages SHOULD indicate 819 that mitigation is active but terminating. The initial active-but- 820 terminating period SHOULD be sufficiently long to absorb latency 821 incurred by route propagation. The active-but-terminating period 822 SHOULD be set by default to 120 seconds. If the client requests 823 mitigation again before the initial active-but-terminating period 824 elapses, the DOTS server MAY exponentially increase the active-but- 825 terminating period up to a maximum of 300 seconds (5 minutes). After 826 the active-but-terminating period elapses, the DOTS server MUST treat 827 the mitigation as terminated, as the DOTS client is no longer 828 responsible for the mitigation. For example, if there is a financial 829 relationship between the DOTS client and server domains, the DOTS 830 client ceases incurring cost at this point. 832 4.4.3. Retrieve Information Related to a Mitigation 834 A GET request is used to retrieve information (including status) of a 835 DOTS mitigation from a DOTS server (Figure 9). If the DOTS server 836 does not find the 'mitigation-id' parameter value conveyed in the GET 837 request in its configuration data, then it responds with a 4.04 (Not 838 Found) error response code. The 'c' (content) parameter and its 839 permitted values defined in [I-D.ietf-core-comi] can be used to 840 retrieve non-configuration data (attack mitigation status) or 841 configuration data or both. The DOTS server SHOULD support this 842 optional filtering capability but can safely ignore it if not 843 supported. 845 The examples depicted in Figure 9 assume the default of "c=a". 847 1) To retrieve all DOTS signals signaled by the DOTS client. 849 Header: GET (Code=0.01) 850 Uri-Host: "host" 851 Uri-Path: ".well-known" 852 Uri-Path: "dots" 853 Uri-Path: "version" 854 Uri-Path: "mitigate" 855 Observe : 0 856 { 857 "mitigation-scope": { 858 "client-identifier": [ 859 "string" 860 ] 861 } 862 } 864 2) To retrieve a specific DOTS signal signaled by the DOTS client. 865 The configuration data in the response will be formatted in the 866 same order it was processed at the DOTS server. 868 Header: GET (Code=0.01) 869 Uri-Host: "host" 870 Uri-Path: ".well-known" 871 Uri-Path: "dots" 872 Uri-Path: "version" 873 Uri-Path: "mitigate" 874 Observe : 0 875 Content-Format: "application/cbor" 876 { 877 "mitigation-scope": { 878 "client-identifier": [ 879 "string" 880 ], 881 "scope": [ 882 { 883 "mitigation-id": integer 884 } 885 ] 886 } 887 } 889 Figure 9: GET to retrieve the rules 891 Figure 10 shows a response example of all the active mitigation 892 requests associated with the DOTS client on the DOTS server and the 893 mitigation status of each mitigation request. 895 { 896 "mitigation-scope": { 897 "scope": [ 898 { 899 "mitigation-id": 12332, 900 "mitigation-start": 1507818434.00, 901 "target-protocol": [ 902 17 903 ], 904 "lifetime":1800, 905 "status":2, 906 "bytes-dropped": 134334555, 907 "bps-dropped": 43344, 908 "pkts-dropped": 333334444, 909 "pps-dropped": 432432 910 }, 911 { 912 "mitigation-id": 12333, 913 "mitigation-start": 1507818393.00, 914 "target-protocol": [ 915 6 916 ], 917 "lifetime":1800, 918 "status":3 919 "bytes-dropped": 0, 920 "bps-dropped": 0, 921 "pkts-dropped": 0, 922 "pps-dropped": 0 923 } 924 ] 925 } 926 } 928 Figure 10: Response body 930 The mitigation status parameters are described below. 932 lifetime: The remaining lifetime of the mitigation request in 933 seconds. 935 mitigation-start: Mitigation start time is represented in seconds 936 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 937 [RFC7049]). The encoding is modified so that the leading tag 1 938 (epoch-based date/time) MUST be omitted. 940 bytes-dropped: The total dropped byte count for the mitigation 941 request since the attack mitigation is triggered. The count wraps 942 around when it reaches the maximum value of unsigned integer. 943 This is an optional attribute. 945 bps-dropped: The average dropped bytes per second for the mitigation 946 request since the attack mitigation is triggered. This SHOULD be 947 a five-minute average. This is an optional attribute. 949 pkts-dropped: The total dropped packet count for the mitigation 950 request since the attack mitigation is triggered. This is an 951 optional attribute. 953 pps-dropped: The average dropped packets per second for the 954 mitigation request since the attack mitigation is triggered. This 955 SHOULD be a five-minute average. This is an optional attribute. 957 status: Status of attack mitigation. The 'status' parameter is a 958 mandatory attribute. 960 The various possible values of 'status' parameter are explained in 961 Table 2. 963 +-----------+-------------------------------------------------------+ 964 | Parameter | Description | 965 | value | | 966 +-----------+-------------------------------------------------------+ 967 | 1 | Attack mitigation is in progress (e.g., changing the | 968 | | network path to re-route the inbound traffic to DOTS | 969 | | mitigator). | 970 +-----------+-------------------------------------------------------+ 971 | 2 | Attack is successfully mitigated (e.g., traffic is | 972 | | redirected to a DDOS mitigator and attack traffic is | 973 | | dropped). | 974 +-----------+-------------------------------------------------------+ 975 | 3 | Attack has stopped and the DOTS client an withdraw | 976 | | the mitigation request. | 977 +-----------+-------------------------------------------------------+ 978 | 4 | Attack has exceeded the mitigation provider | 979 | | capability. | 980 +-----------+-------------------------------------------------------+ 981 | 5 | DOTS client has withdrawn the mitigation request and | 982 | | the mitigation is active but terminating. | 983 +-----------+-------------------------------------------------------+ 985 Table 2: Values of 'status' parameter 987 The observe option defined in [RFC7641] extends the CoAP core 988 protocol with a mechanism for a CoAP client to "observe" a resource 989 on a CoAP server: the client retrieves a representation of the 990 resource and requests this representation be updated by the server as 991 long as the client is interested in the resource. A DOTS client 992 conveys the observe option set to '0' in the GET request to receive 993 unsolicited notifications of attack mitigation status from the DOTS 994 server. Unidirectional notifications within the bidirectional signal 995 channel allows unsolicited message delivery, enabling asynchronous 996 notifications between the agents. Due to the higher likelihood of 997 packet loss during a DDoS attack, DOTS server periodically sends 998 attack mitigation status to the DOTS client and also notifies the 999 DOTS client whenever the status of the attack mitigation changes. If 1000 the DOTS server cannot maintain a RTT estimate, it SHOULD NOT send 1001 more than one unsolicited notification every 3 seconds, and SHOULD 1002 use an even less aggressive rate when possible (case 2 in 1003 Section 3.1.3 of [RFC8085]). 1005 A DOTS client that is no longer interested in receiving notifications 1006 from the DOTS server can simply "forget" the observation. When the 1007 DOTS server then sends the next notification, the DOTS client will 1008 not recognize the token in the message and thus will return a Reset 1009 message. This causes the DOTS server to remove the associated entry. 1010 Alternatively, the DOTS client can explicitly deregister by issuing a 1011 GET request that has the Token field set to the token of the 1012 observation to be cancelled and includes an Observe Option with the 1013 value set to '1' (deregister). 1015 Figure 11 shows an example of a DOTS client requesting a DOTS server 1016 to send notifications related a given mitigation request. 1018 DOTS Client DOTS Server 1019 | | 1020 | GET / | 1021 | Token: 0x4a | Registration 1022 | Observe: 0 | 1023 +------------------------------>| 1024 | | 1025 | 2.05 Content | 1026 | Token: 0x4a | Notification of 1027 | Observe: 12 | the current state 1028 | status: "mitigation | 1029 | in progress" | 1030 |<------------------------------+ 1031 | 2.05 Content | 1032 | Token: 0x4a | Notification upon 1033 | Observe: 44 | a state change 1034 | status: "mitigation | 1035 | complete" | 1036 |<------------------------------+ 1037 | 2.05 Content | 1038 | Token: 0x4a | Notification upon 1039 | Observe: 60 | a state change 1040 | status: "attack stopped" | 1041 |<------------------------------+ 1042 | | 1044 Figure 11: Notifications of attack mitigation status 1046 4.4.3.1. Mitigation Status 1048 The DOTS client can send the GET request at frequent intervals 1049 without the Observe option to retrieve the configuration data of the 1050 mitigation request and non-configuration data (i.e., the attack 1051 status). The frequency of polling the DOTS server to get the 1052 mitigation status should follow the transmission guidelines given in 1053 Section 3.1.3 of [RFC8085]. If the DOTS server has been able to 1054 mitigate the attack and the attack has stopped, the DOTS server 1055 indicates as such in the status, and the DOTS client recalls the 1056 mitigation request by issuing a DELETE for the mitigation-id. 1058 A DOTS client should react to the status of the attack from the DOTS 1059 server and not the fact that it has recognized, using its own means, 1060 that the attack has been mitigated. This ensures that the DOTS 1061 client does not recall a mitigation request in a premature fashion 1062 because it is possible that the DOTS client does not sense the DDOS 1063 attack on its resources but the DOTS server could be actively 1064 mitigating the attack and the attack is not completely averted. 1066 4.4.4. Efficacy Update from DOTS Clients 1068 While DDoS mitigation is active, due to the likelihood of packet 1069 loss, a DOTS client MAY periodically transmit DOTS mitigation 1070 efficacy updates to the relevant DOTS server. A PUT request 1071 (Figure 12) is used to convey the mitigation efficacy update to the 1072 DOTS server. 1074 The PUT request MUST include all the parameters used in the PUT 1075 request to convey the DOTS signal (Section 4.4.1) unchanged apart 1076 from the lifetime parameter value. If this is not the case, the DOTS 1077 server MUST reject the request with a 4.02 error response code. 1079 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1080 value is used to make the PUT request conditional on the current 1081 existence of the mitigation request. If UDP is used as transport, 1082 CoAP requests may arrive out-of-order. For example, the DOTS client 1083 may send a PUT request to convey an efficacy update to the DOTS 1084 server followed by a DELETE request to withdraw the mitigation 1085 request, but the DELETE request arrives at the DOTS server before the 1086 PUT request. To handle out-of-order delivery of requests, if an If- 1087 Match option is present in the PUT request and the 'mitigation-id' in 1088 the request matches a mitigation request from that DOTS client, then 1089 the request is processed. If no match is found, the PUT request is 1090 silently ignored. 1092 Header: PUT (Code=0.03) 1093 Uri-Host: "host" 1094 Uri-Path: ".well-known" 1095 Uri-Path: "dots" 1096 Uri-Path: "version" 1097 Uri-Path: "mitigate" 1098 Content-Format: "application/cbor" 1099 { 1100 "mitigation-scope": { 1101 "client-identifier": [ 1102 "string" 1103 ], 1104 "scope": [ 1105 { 1106 "mitigation-id": integer, 1107 "target-ip": [ 1108 "string" 1109 ], 1110 "target-port-range": [ 1111 { 1112 "lower-port": integer, 1113 "upper-port": integer 1114 } 1115 ], 1116 "target-protocol": [ 1117 integer 1118 ], 1119 "fqdn": [ 1120 "string" 1121 ], 1122 "uri": [ 1123 "string" 1124 ], 1125 "alias-name": [ 1126 "string" 1127 ], 1128 "lifetime": integer, 1129 "attack-status": integer 1130 } 1131 ] 1132 } 1133 } 1135 Figure 12: Efficacy Update 1137 The 'attack-status' parameter is a mandatory attribute when doing a 1138 efficacy update. The various possible values contained in the 1139 'attack-status' parameter are described in Table 3. 1141 +-----------+-------------------------------------------------------+ 1142 | Parameter | Description | 1143 | value | | 1144 +-----------+-------------------------------------------------------+ 1145 | 1 | The DOTS client determines that it is still under | 1146 | | attack. | 1147 +-----------+-------------------------------------------------------+ 1148 | 2 | The DOTS client determines that the attack is | 1149 | | successfully mitigated (e.g., attack traffic is not | 1150 | | seen). | 1151 +-----------+-------------------------------------------------------+ 1153 Table 3: Values of 'attack-status' parameter 1155 The DOTS server indicates the result of processing a PUT request 1156 using CoAP response codes. The response code 2.04 (Changed) is 1157 returned if the DOTS server has accepted the mitigation efficacy 1158 update. The error response code 5.03 (Service Unavailable) is 1159 returned if the DOTS server has erred or is incapable of performing 1160 the mitigation. 1162 4.5. DOTS Signal Channel Session Configuration 1164 The DOTS client can negotiate, configure, and retrieve the DOTS 1165 signal channel session behavior. The DOTS signal channel can be 1166 used, for example, to configure the following: 1168 a. Heartbeat interval: DOTS agents regularly send heartbeats (CoAP 1169 Ping/Pong) to each other after mutual authentication in order to 1170 keep the DOTS signal channel open, heartbeat messages are 1171 exchanged between the DOTS agents every heartbeat-interval 1172 seconds to detect the current status of the DOTS signal channel 1173 session. 1175 b. Missing heartbeats allowed: This variable indicates the maximum 1176 number of consecutive heartbeat messages for which a DOTS agent 1177 did not receive a response before concluding that the session is 1178 disconnected or defunct. 1180 c. Acceptable signal loss ratio: Maximum retransmissions, 1181 retransmission timeout value and other message transmission 1182 parameters for the DOTS signal channel. 1184 Reliability is provided to requests and responses by marking them as 1185 Confirmable (CON) messages. DOTS signal channel session 1186 configuration requests and responses are marked as Confirmable (CON) 1187 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1188 message is retransmitted using a default timeout and exponential 1189 back-off between retransmissions, until the DOTS server sends an 1190 Acknowledgement message (ACK) with the same Message ID conveyed from 1191 the DOTS client. Message transmission parameters are defined in 1192 Section 4.8 of [RFC7252]. Reliability is provided to the responses 1193 by marking them as Confirmable (CON) messages. The DOTS server can 1194 either piggyback the response in the acknowledgement message or if 1195 the DOTS server is not able to respond immediately to a request 1196 carried in a Confirmable message, it simply responds with an Empty 1197 Acknowledgement message so that the DOTS client can stop 1198 retransmitting the request. Empty Acknowledgement message is 1199 explained in Section 2.2 of [RFC7252]. When the response is ready, 1200 the server sends it in a new Confirmable message which then in turn 1201 needs to be acknowledged by the DOTS client (see Sections 5.2.1 and 1202 5.2.2 of [RFC7252]). Requests and responses exchanged between DOTS 1203 agents during peacetime are marked as Confirmable messages. 1205 Implementation Note: A DOTS client that receives a response in a CON 1206 message may want to clean up the message state right after sending 1207 the ACK. If that ACK is lost and the DOTS server retransmits the 1208 CON, the DOTS client may no longer have any state to which to 1209 correlate this response, making the retransmission an unexpected 1210 message; the DOTS client will send a Reset message so it does not 1211 receive any more retransmissions. This behavior is normal and not an 1212 indication of an error (see Section 5.3.2 of [RFC7252] for more 1213 details). 1215 4.5.1. Discover Configuration Parameters 1217 A GET request is used to obtain acceptable and current configuration 1218 parameters on the DOTS server for DOTS signal channel session 1219 configuration. Figure 13 shows how to obtain acceptable 1220 configuration parameters for the DOTS server. 1222 Header: GET (Code=0.01) 1223 Uri-Host: "host" 1224 Uri-Path: ".well-known" 1225 Uri-Path: "dots" 1226 Uri-Path: "version" 1227 Uri-Path: "config" 1229 Figure 13: GET to retrieve configuration 1231 The DOTS server in the 2.05 (Content) response conveys the current, 1232 minimum and maximum attribute values acceptable by the DOTS server. 1234 Content-Format: "application/cbor" 1235 { 1236 "heartbeat-interval": { 1237 "CurrentValue": integer, 1238 "MinValue": integer, 1239 "MaxValue" : integer, 1240 }, 1241 "missing-hb-allowed": { 1242 "CurrentValue": integer, 1243 "MinValue": integer, 1244 "MaxValue" : integer, 1245 }, 1246 "max-retransmit": { 1247 "CurrentValue": integer, 1248 "MinValue": integer, 1249 "MaxValue" : integer, 1250 }, 1251 "ack-timeout": { 1252 "CurrentValue": integer, 1253 "MinValue": integer, 1254 "MaxValue" : integer, 1255 }, 1256 "ack-random-factor": { 1257 "CurrentValue": number, 1258 "MinValue": number, 1259 "MaxValue" : number, 1260 }, 1261 "trigger-mitigation": { 1262 "CurrentValue": boolean, 1263 } 1264 } 1266 Figure 14: GET response body 1268 Figure 15 shows an example of acceptable and current configuration 1269 parameters on the DOTS server for DOTS signal channel session 1270 configuration. 1272 Content-Format: "application/cbor" 1273 { 1274 "heartbeat-interval": { 1275 "CurrentValue": 30, 1276 "MinValue": 15, 1277 "MaxValue" : 240, 1278 }, 1279 "missing-hb-allowed": { 1280 "CurrentValue": 5, 1281 "MinValue": 3, 1282 "MaxValue" : 9, 1283 }, 1284 "max-retransmit": { 1285 "CurrentValue": 3, 1286 "MinValue": 2, 1287 "MaxValue" : 15, 1288 }, 1289 "ack-timeout": { 1290 "CurrentValue": 2, 1291 "MinValue": 1, 1292 "MaxValue" : 30, 1293 }, 1294 "ack-random-factor": { 1295 "CurrentValue": 1.5, 1296 "MinValue": 1.1, 1297 "MaxValue" : 4.0, 1298 }, 1299 "trigger-mitigation": { 1300 "CurrentValue": true, 1301 } 1302 } 1304 Figure 15: Configuration response body 1306 4.5.2. Convey DOTS Signal Channel Session Configuration 1308 A PUT request is used to convey the configuration parameters for the 1309 signal channel (e.g., heartbeat interval, maximum retransmissions). 1310 Message transmission parameters for CoAP are defined in Section 4.8 1311 of [RFC7252]. The RECOMMENDED values of transmission parameter 1312 values are ack_timeout (2 seconds), max-retransmit (3), ack-random- 1313 factor (1.5). In addition to those parameters, the RECOMMENDED 1314 specific DOTS transmission parameter values are heartbeat-interval 1315 (30 seconds) and missing-hb-allowed (5). 1317 Note: heartbeat-interval should be tweaked to also assist DOTS 1318 messages for NAT traversal (SIG-010 of 1319 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1320 messages must not be sent more frequently than once every 15 1321 seconds and should use longer intervals when possible. 1322 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1323 minutes or longer, but experience shows that sending packets every 1324 15 to 30 seconds is necessary to prevent the majority of 1325 middleboxes from losing state for UDP flows. From that 1326 standpoint, this specification recommends a minimum heartbeat- 1327 interval of 15 seconds and a maximum heartbeat-interval of 240 1328 seconds. The recommended value of 30 seconds is selected to 1329 anticipate the expiry of NAT state. 1331 A heartbeat-interval of 30 second may be seen as too chatty in 1332 some deployments. For such deployments, DOTS agents may negotiate 1333 longer heartbeat-interval values to avoid overloading the network 1334 with too frequent keepalives. 1336 When a confirmable "CoAP ping" is sent, and if there is no response, 1337 the "CoAP ping" will get retransmitted max-retransmit number of times 1338 by the CoAP layer using an initial timeout set to a random duration 1339 between ack_timeout and (ack-timeout*ack-random-factor) and 1340 exponential back-off between retransmissions. By choosing the 1341 recommended transmission parameters, the "CoAP ping" will timeout 1342 after 45 seconds. If the DOTS agent does not receive any response 1343 from the peer DOTS agent for missing-hb-allowed number of consecutive 1344 "CoAP ping" confirmable messages, then it concludes that the DOTS 1345 signal channel session is disconnected. A DOTS client MUST NOT 1346 transmit a "CoAP ping" while waiting for the previous "CoAP ping" 1347 response from the same DOTS server. 1349 If the DOTS agent wishes to change the default values of message 1350 transmission parameters, then it should follow the guidance given in 1351 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1352 values for message transmission parameters and default values for 1353 non-negotiated message transmission parameters. 1355 The signal channel session configuration is applicable to a single 1356 DOTS signal channel session between the DOTS agents. 1358 Header: PUT (Code=0.03) 1359 Uri-Host: "host" 1360 Uri-Path: ".well-known" 1361 Uri-Path: "dots" 1362 Uri-Path: "version" 1363 Uri-Path: "config" 1364 Content-Format: "application/cbor" 1365 { 1366 "signal-config": { 1367 "session-id": integer, 1368 "heartbeat-interval": integer, 1369 "missing-hb-allowed": integer, 1370 "max-retransmit": integer, 1371 "ack-timeout": integer, 1372 "ack-random-factor": number 1373 "trigger-mitigation": boolean 1374 } 1375 } 1377 Figure 16: PUT to convey the DOTS signal channel session 1378 configuration data. 1380 The parameters are described below: 1382 session-id: Identifier for the DOTS signal channel session 1383 configuration data represented as an integer. This identifier 1384 MUST be generated by the DOTS client. This document does not make 1385 any assumption about how this identifier is generated. This is a 1386 mandatory attribute. 1388 heartbeat-interval: Time interval in seconds between two 1389 consecutive heartbeat messages. This is an optional attribute. 1391 missing-hb-allowed: Maximum number of consecutive heartbeat 1392 messages for which the DOTS agent did not receive a response 1393 before concluding that the session is disconnected. This is an 1394 optional attribute. 1396 max-retransmit: Maximum number of retransmissions for a message 1397 (referred to as MAX_RETRANSMIT parameter in CoAP). This is an 1398 optional attribute. 1400 ack-timeout: Timeout value in seconds used to calculate the initial 1401 retransmission timeout value (referred to as ACK_TIMEOUT parameter 1402 in CoAP). This is an optional attribute. 1404 ack-random-factor: Random factor used to influence the timing of 1405 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1406 CoAP). This is an optional attribute. 1408 trigger-mitigation: If the parameter value is set to 'false', then 1409 DDoS mitigation is triggered only when the DOTS signal channel 1410 session is lost. Automated mitigation on loss of signal is 1411 discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. If 1412 the DOTS client ceases to respond to heartbeat messages, then the 1413 DOTS server can detect that the DOTS session is lost. The default 1414 value of the parameter is 'true'. This is an optional attribute. 1416 In the PUT request at least one of the attributes heartbeat-interval, 1417 missing-hb-allowed, max-retransmit, ack-timeout, ack-random-factor, 1418 and trigger-mitigation MUST be present. The PUT request with higher 1419 numeric session-id value over-rides the DOTS signal channel session 1420 configuration data installed by a PUT request with a lower numeric 1421 session-id value. 1423 Figure 17 shows a PUT request example to convey the configuration 1424 parameters for the DOTS signal channel. 1426 Header: PUT (Code=0.03) 1427 Uri-Host: "www.example.com" 1428 Uri-Path: ".well-known" 1429 Uri-Path: "dots" 1430 Uri-Path: "v1" 1431 Uri-Path: "config" 1432 Content-Format: "application/cbor" 1433 { 1434 "signal-config": { 1435 "session-id": 1234534333242, 1436 "heartbeat-interval": 91, 1437 "missing-hb-allowed": 3, 1438 "max-retransmit": 7, 1439 "ack-timeout": 5, 1440 "ack-random-factor": 1.5, 1441 "trigger-mitigation": false 1442 } 1443 } 1445 Figure 17: PUT to convey the configuration parameters 1447 The DOTS server indicates the result of processing the PUT request 1448 using CoAP response codes: 1450 o If the DOTS server finds the 'session-id' parameter value conveyed 1451 in the PUT request in its configuration data and if the DOTS 1452 server has accepted the updated configuration parameters, then 1453 2.04 (Changed) code is returned in the response. 1455 o If the DOTS server does not find the 'session-id' parameter value 1456 conveyed in the PUT request in its configuration data and if the 1457 DOTS server has accepted the configuration parameters, then a 1458 response code 2.01 (Created) is returned in the response. 1460 o If the request is missing one or more mandatory attributes, then 1461 4.00 (Bad Request) is returned in the response. 1463 o If the request contains one or more invalid or unknown parameters, 1464 then 4.02 (Invalid query) code is returned in the response. 1466 o Response code 4.22 (Unprocessable Entity) is returned in the 1467 response, if any of the heartbeat-interval, missing-hb-allowed, 1468 max-retransmit, target-protocol, ack-timeout, and ack-random- 1469 factor attribute values are not acceptable to the DOTS server. 1470 Upon receipt of the 4.22 error response code, the DOTS client 1471 should request the maximum and minimum attribute values acceptable 1472 to the DOTS server (Section 4.5.1). The DOTS client may re-try 1473 and send the PUT request with updated attribute values acceptable 1474 to the DOTS server. 1476 4.5.3. Delete DOTS Signal Channel Session Configuration 1478 A DELETE request is used to delete the installed DOTS signal channel 1479 session configuration data (Figure 18). 1481 Header: DELETE (Code=0.04) 1482 Uri-Host: "host" 1483 Uri-Path: ".well-known" 1484 Uri-Path: "dots" 1485 Uri-Path: "version" 1486 Uri-Path: "config" 1487 Content-Format: "application/cbor" 1489 Figure 18: DELETE configuration 1491 The DOTS server resets the DOTS signal channel session configuration 1492 back to the default values and acknowledges a DOTS client's request 1493 to remove the DOTS signal channel session configuration using 2.02 1494 (Deleted) response code. 1496 4.6. Redirected Signaling 1498 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 1499 [I-D.ietf-dots-architecture]. 1501 If a DOTS server wants to redirect a DOTS client to an alternative 1502 DOTS server for a signal session, then the response code 3.00 1503 (alternate server) will be returned in the response to the client. 1504 The DOTS server can return the error response code 3.00 in response 1505 to a PUT request from the DOTS client or convey the error response 1506 code 3.00 in a unidirectional notification response from the DOTS 1507 server. 1509 The DOTS server in the error response conveys the alternate DOTS 1510 server FQDN, and the alternate DOTS server IP addresses and time to 1511 live values in the CBOR body. 1513 { 1514 "alt-server": "string", 1515 "alt-server-record": [ 1516 { 1517 "addr": "string", 1518 "ttl" : integer, 1519 } 1520 ] 1521 } 1523 Figure 19: Error response body 1525 The parameters are described below: 1527 alt-server: FQDN of an alternate DOTS server. 1529 addr: IP address of an alternate DOTS server. 1531 ttl: Time to live (TTL) represented as an integer number of seconds. 1533 Figure 20 shows a 3.00 response example to convey the DOTS alternate 1534 server www.example-alt.com, its IP addresses 2001:db8:6401::1 and 1535 2001:db8:6401::2, and TTL values 3600 and 1800. 1537 { 1539 "alt-server": "www.example-alt.com", 1540 "alt-server-record": [ 1541 { 1542 "ttl" : 3600, 1543 "addr": "2001:db8:6401::1" 1544 }, 1545 { 1546 "ttl" : 1800, 1547 "addr": "2001:db8:6401::2" 1548 } 1549 ] 1550 } 1552 Figure 20: Example of error response body 1554 When the DOTS client receives 3.00 response, it considers the current 1555 request as having failed, but SHOULD try the request with the 1556 alternate DOTS server. During a DDOS attack, the DNS server may be 1557 subjected to DDOS attack, alternate DOTS server IP addresses conveyed 1558 in the 3.00 response help the DOTS client to skip DNS lookup of the 1559 alternate DOTS server and can try to establish UDP or TCP session 1560 with the alternate DOTS server IP addresses. The DOTS client SHOULD 1561 implement DNS64 function to handle the scenario where IPv6-only DOTS 1562 client communicates with IPv4-only alternate DOTS server. 1564 4.7. Heartbeat Mechanism 1566 To provide a metric of signal health and distinguish an 'idle' signal 1567 channel from a 'disconnected' or 'defunct' session, the DOTS agent 1568 sends a heartbeat over the signal channel to maintain its half of the 1569 channel. The DOTS agent similarly expects a heartbeat from its peer 1570 DOTS agent, and may consider a session terminated in the extended 1571 absence of a peer agent heartbeat. 1573 While the communication between the DOTS agents is quiescent, the 1574 DOTS client will probe the DOTS server to ensure it has maintained 1575 cryptographic state and vice versa. Such probes can also keep alive 1576 firewall and/or NAT bindings. This probing reduces the frequency of 1577 establishing a new handshake when a DOTS signal needs to be conveyed 1578 to the DOTS server. 1580 In case of a volumetric DDoS attack saturating the incoming link to 1581 the DOTS client, all traffic from the DOTS server to the DOTS client 1582 will likely be dropped, although the DOTS server receives heartbeat 1583 requests and DOTS messages from the DOTS client. In this scenario, 1584 the DOTS agents MUST behave differently to handle message 1585 transmission and DOTS session liveliness during link saturation: 1587 o The DOTS client MUST NOT consider the DOTS session terminated even 1588 after maximum "missing-hb-allowed" threshold is reached. The DOTS 1589 client SHOULD continue to use the current DOTS session, and send 1590 heartbeat requests over the current DOTS session, so the DOTS 1591 server knows the DOTS client has not disconnected the DOTS 1592 session. After the maximum "missing-hb-allowed" threshold is 1593 reached, the DOTS client SHOULD try (D)TLS session resumption. 1594 The DOTS client SHOULD send mitigation requests over the current 1595 DOTS session, and in parallel, try (D)TLS session resumption or 1596 0-RTT mode in DTLS 1.3 to piggyback the mitigation request in the 1597 ClientHello message. Once the link is no longer statured, if 1598 traffic from the DOTS server reaches the DOTS client over the 1599 current DOTS session, the DOTS client can stop (D)TLS session 1600 resumption or if (D)TLS session resumption is successful then 1601 disconnect the current DOTS session. 1603 o If the DOTS server does not receive any traffic from the peer DOTS 1604 client, then the DOTS server sends heartbeat requests to the DOTS 1605 client and after maximum "missing-hb-allowed" threshold is 1606 reached, the DOTS server concludes the session is disconnected. 1608 In DOTS over UDP, heartbeat messages may be exchanged between the 1609 DOTS agents using the "COAP ping" mechanism defined in Section 4.2 of 1610 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 1611 message and the peer DOTS agent will respond by sending an Reset 1612 message. 1614 In DOTS over TCP, heartbeat messages can be exchanged between the 1615 DOTS agents using the Ping and Pong messages specified in Section 4.4 1616 of [I-D.ietf-core-coap-tcp-tls]. That is, the DOTS agent sends a 1617 Ping message and the peer DOTS agent would respond by sending a 1618 single Pong message. 1620 5. DOTS Signal Channel YANG Modules 1622 This document defines YANG [RFC7950] modules for mitigation scope and 1623 DOTS signal channel session configuration data. 1625 5.1. Mitigation Request YANG Module Tree Structure 1627 This document defines the YANG module "ietf-dots-signal" 1628 (Section 5.2), which has the following tree structure: 1630 module: ietf-dots-signal 1631 +--rw mitigation-scope 1632 +--rw client-identifier* binary 1633 +--rw scope* [mitigation-id] 1634 +--rw mitigation-id int32 1635 +--rw target-ip* inet:ip-address 1636 +--rw target-prefix* inet:ip-prefix 1637 +--rw target-port-range* [lower-port upper-port] 1638 | +--rw lower-port inet:port-number 1639 | +--rw upper-port inet:port-number 1640 +--rw target-protocol* uint8 1641 +--rw fqdn* inet:domain-name 1642 +--rw uri* inet:uri 1643 +--rw alias-name* string 1644 +--rw lifetime? int32 1646 5.2. Mitigation Request YANG Module 1648 file "ietf-dots-signal@2017-11-27.yang" 1650 module ietf-dots-signal { 1651 yang-version 1.1; 1652 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal"; 1653 prefix "signal"; 1655 import ietf-inet-types { 1656 prefix "inet"; 1657 } 1659 organization "IETF DOTS Working Group"; 1661 contact 1662 "Konda, Tirumaleswar Reddy 1663 Mohamed Boucadair 1664 Prashanth Patil 1665 Andrew Mortensen 1666 Nik Teague "; 1668 description 1669 "This module contains YANG definition for DOTS 1670 signal sent by the DOTS client to the DOTS server. 1672 Copyright (c) 2017 IETF Trust and the persons identified as 1673 authors of the code. All rights reserved. 1675 Redistribution and use in source and binary forms, with or 1676 without modification, is permitted pursuant to, and subject 1677 to the license terms contained in, the Simplified BSD License 1678 set forth in Section 4.c of the IETF Trust's Legal Provisions 1679 Relating to IETF Documents 1680 (http://trustee.ietf.org/license-info). 1682 This version of this YANG module is part of RFC XXXX; see 1683 the RFC itself for full legal notices."; 1685 revision 2017-11-27 { 1686 description 1687 "Initial revision."; 1688 reference 1689 "RFC XXXX: A Distributed Denial-of-Service Open Threat 1690 Signaling (DOTS) Signal Channel"; 1691 } 1693 container mitigation-scope { 1694 description 1695 "Specifies the scope of the mitigation request."; 1697 leaf-list client-identifier { 1698 type binary; 1699 description 1700 "The client identifier may be conveyed by 1701 the DOTS gateway to propagate the DOTS client 1702 identity from the gateway's client-side to the 1703 gateway's server-side, and from the gateway's 1704 server-side to the DOTS server. 1706 It allows the final DOTS server to accept 1707 mitigation requests with scopes which the DOTS 1708 client is authorized to manage."; 1709 } 1711 list scope { 1712 key mitigation-id; 1713 description 1714 "The scope of the request."; 1716 leaf mitigation-id { 1717 type int32; 1718 description 1719 "Mitigation request identifier. 1721 This identifier must be unique for each mitigation 1722 request bound to the DOTS client."; 1723 } 1725 leaf-list target-ip { 1726 type inet:ip-address; 1727 description 1728 "IPv4 or IPv6 address identifying the target."; 1729 } 1731 leaf-list target-prefix { 1732 type inet:ip-prefix; 1733 description 1734 "IPv4 or IPv6 prefix identifying the target."; 1735 } 1737 list target-port-range { 1738 key "lower-port upper-port"; 1740 description 1741 "Port range. When only lower-port is 1742 present, it represents a single port."; 1744 leaf lower-port { 1745 type inet:port-number; 1746 mandatory true; 1747 description "Lower port number."; 1748 } 1750 leaf upper-port { 1751 type inet:port-number; 1752 must ". >= ../lower-port" { 1753 error-message 1754 "The upper port number must be greater than 1755 or equal to lower port number."; 1756 } 1757 description "Upper port number."; 1758 } 1759 } 1761 leaf-list target-protocol { 1762 type uint8; 1763 description 1764 "Identifies the target protocol number. 1766 The value '0' means 'all protocols'. 1768 Values are taken from the IANA protocol registry: 1769 https://www.iana.org/assignments/protocol-numbers/ 1770 protocol-numbers.xhtml 1772 For example, 6 for a TCP or 17 for UDP."; 1773 } 1774 leaf-list fqdn { 1775 type inet:domain-name; 1776 description "FQDN"; 1777 } 1779 leaf-list uri { 1780 type inet:uri; 1781 description "URI"; 1782 } 1784 leaf-list alias-name { 1785 type string; 1786 description "alias name"; 1787 } 1789 leaf lifetime { 1790 type int32; 1791 units "seconds"; 1792 default 3600; 1793 description 1794 "Indicates the lifetime of the mitigation request."; 1795 } 1796 } 1797 } 1798 } 1799 1801 5.3. Session Configuration YANG Module Tree Structure 1803 This document defines the YANG module "ietf-dots-signal-config" 1804 (Section 5.4), which has the following structure: 1806 module: ietf-dots-signal-config 1807 +--rw signal-config 1808 +--rw session-id? int32 1809 +--rw heartbeat-interval? int16 1810 +--rw missing-hb-allowed? int16 1811 +--rw max-retransmit? int16 1812 +--rw ack-timeout? int16 1813 +--rw ack-random-factor? decimal64 1814 +--rw trigger-mitigation? boolean 1816 5.4. Session Configuration YANG Module 1818 file "ietf-dots-signal-config@2017-11-27.yang" 1820 module ietf-dots-signal-config { 1821 yang-version 1.1; 1822 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-config"; 1823 prefix "config"; 1825 organization "IETF DOTS Working Group"; 1827 contact 1828 "Konda, Tirumaleswar Reddy 1829 Mohamed Boucadair 1830 Prashanth Patil 1831 Andrew Mortensen 1832 Nik Teague "; 1834 description 1835 "This module contains YANG definition for DOTS 1836 signal channel session configuration. 1838 Copyright (c) 2017 IETF Trust and the persons identified as 1839 authors of the code. All rights reserved. 1841 Redistribution and use in source and binary forms, with or 1842 without modification, is permitted pursuant to, and subject 1843 to the license terms contained in, the Simplified BSD License 1844 set forth in Section 4.c of the IETF Trust's Legal Provisions 1845 Relating to IETF Documents 1846 (http://trustee.ietf.org/license-info). 1848 This version of this YANG module is part of RFC XXXX; see 1849 the RFC itself for full legal notices."; 1851 revision 2017-11-27 { 1852 description 1853 "Initial revision."; 1854 reference 1855 "RFC XXXX: A Distributed Denial-of-Service Open Threat 1856 Signaling (DOTS) Signal Channel"; 1857 } 1859 container signal-config { 1860 description 1861 "DOTS signal channel session configuration."; 1863 leaf session-id { 1864 type int32; 1865 description 1866 "An identifier for the DOTS signal channel 1867 session configuration data."; 1868 } 1869 leaf heartbeat-interval { 1870 type int16; 1871 units "seconds"; 1872 default 30; 1873 description 1874 "DOTS agents regularly send heartbeats to each other 1875 after mutual authentication in order to keep 1876 the DOTS signal channel open."; 1877 } 1879 leaf missing-hb-allowed { 1880 type int16; 1881 default 5; 1882 description 1883 "Maximum number of missing heartbeats allowed."; 1884 } 1886 leaf max-retransmit { 1887 type int16; 1888 default 3; 1889 description 1890 "Maximum number of retransmissions of a 1891 Confirmable message."; 1892 } 1894 leaf ack-timeout { 1895 type int16; 1896 units "seconds"; 1897 default 2; 1898 description 1899 "Initial retransmission timeout value."; 1900 } 1902 leaf ack-random-factor { 1903 type decimal64 { 1904 fraction-digits 2; 1905 } 1906 default 1.5; 1907 description 1908 "Random factor used to influence the timing of 1909 retransmissions."; 1910 } 1911 leaf trigger-mitigation { 1912 type boolean; 1913 default true; 1914 description 1915 "If false, then mitigation is triggered 1916 only when the DOTS server channel session is lost"; 1918 } 1919 } 1920 } 1921 1923 6. Mapping Parameters to CBOR 1925 All parameters in the payload in the DOTS signal channel MUST be 1926 mapped to CBOR types as shown in Table 4 and are given an integer key 1927 to save space. The recipient of the payload MAY reject the 1928 information if it is not suitably mapped. 1930 /--------------------+---------------------+--------------------------\ 1931 | Parameter name | CBOR key | CBOR major type of value | 1932 +--------------------+---------------------+--------------------------+ 1933 | mitigation-scope | 1 | 5 (map) | 1934 | scope | 2 | 5 (map) | 1935 | mitigation-id | 3 | 0 (unsigned) | 1936 | target-ip | 4 | 4 (array) | 1937 | target-port-range | 5 | 4 | 1938 | lower-port | 6 | 0 | 1939 | upper-port | 7 | 0 | 1940 | target-protocol | 8 | 4 | 1941 | fqdn | 9 | 4 | 1942 | uri | 10 | 4 | 1943 | alias-name | 11 | 4 | 1944 | lifetime | 12 | 0 | 1945 | attack-status | 13 | 0 | 1946 | signal-config | 14 | 5 | 1947 | heartbeat-interval | 15 | 0 | 1948 | max-retransmit | 16 | 0 | 1949 | ack-timeout | 17 | 0 | 1950 | ack-random-factor | 18 | 7 | 1951 | MinValue | 19 | 0 | 1952 | MaxValue | 20 | 0 | 1953 | status | 21 | 0 | 1954 | bytes-dropped | 22 | 0 | 1955 | bps-dropped | 23 | 0 | 1956 | pkts-dropped | 24 | 0 | 1957 | pps-dropped | 25 | 0 | 1958 | session-id | 26 | 0 | 1959 | trigger-mitigation | 27 | 7 (simple types) | 1960 | missing-hb-allowed | 28 | 0 | 1961 | CurrentValue | 29 | 0 | 1962 | mitigation-start | 30 | 7 (floating-point) | 1963 | target-prefix | 31 | 4 (array) | 1964 | client-identifier | 32 | 2 (byte string) | 1965 | alt-server | 33 | 2 | 1966 | alt-server-record | 34 | 4 | 1967 | addr | 35 | 2 | 1968 | ttl | 36 | 0 | 1969 \--------------------+---------------------+--------------------------/ 1970 Table 4: CBOR mappings used in DOTS signal channel message 1972 7. (D)TLS Protocol Profile and Performance Considerations 1973 7.1. (D)TLS Protocol Profile 1975 This section defines the (D)TLS protocol profile of DOTS signal 1976 channel over (D)TLS and DOTS data channel over TLS. 1978 There are known attacks on (D)TLS, such as machine-in-the-middle and 1979 protocol downgrade. These are general attacks on (D)TLS and not 1980 specific to DOTS over (D)TLS; please refer to the (D)TLS RFCs for 1981 discussion of these security issues. DOTS agents MUST adhere to the 1982 (D)TLS implementation recommendations and security considerations of 1983 [RFC7525] except with respect to (D)TLS version. Since encryption of 1984 DOTS using (D)TLS is virtually a green-field deployment DOTS agents 1985 MUST implement only (D)TLS 1.2 or later. 1987 When a DOTS client is configured with a domain name of the DOTS 1988 server, and connects to its configured DOTS server, the server may 1989 present it with a PKIX certificate. In order to ensure proper 1990 authentication, DOTS client MUST verify the entire certification path 1991 per [RFC5280]. The DOTS client additionaly uses [RFC6125] validation 1992 techniques to compare the domain name to the certificate provided. 1994 A key challenge to deploying DOTS is provisioning DOTS clients, 1995 including the distribution of keying material to DOTS clients to make 1996 possible the required mutual authentication of DOTS agents. EST 1997 defines a method of certificate enrollment by which domains operating 1998 DOTS servers may provision DOTS clients with all necessary 1999 cryptographic keying material, including a private key and 2000 certificate with which to authenticate itself. One deployment option 2001 is DOTS clients to behave as EST clients for certificate enrollment 2002 from an EST server provisioned by the mitigation provider. This 2003 document does not specify which EST mechanism the DOTS client uses to 2004 achieve initial enrollment. 2006 Implementations compliant with this profile MUST implement all of the 2007 following items: 2009 o DTLS record replay detection (Section 3.3 of [RFC6347]) to protect 2010 against replay attacks. 2012 o (D)TLS session resumption without server-side state [RFC5077] to 2013 resume session and convey the DOTS signal. 2015 o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduce 2016 the size of the ServerHello, and can be used by DOTS agents that 2017 cannot obtain certificates (e.g., DOTS clients and DOTS gateways 2018 on private networks). 2020 Implementations compliant with this profile SHOULD implement all of 2021 the following items to reduce the delay required to deliver a DOTS 2022 signal: 2024 o TLS False Start [RFC7918] which reduces round-trips by allowing 2025 the TLS second flight of messages (ChangeCipherSpec) to also 2026 contain the DOTS signal. 2028 o Cached Information Extension [RFC7924] which avoids transmitting 2029 the server's certificate and certificate chain if the client has 2030 cached that information from a previous TLS handshake. 2032 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 2033 convey DOTS signal. 2035 7.2. MTU and Fragmentation 2037 To avoid DOTS signal message fragmentation and the consequently 2038 decreased probability of message delivery, DOTS agents MUST ensure 2039 that the DTLS record MUST fit within a single datagram. If the path 2040 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 2041 be assumed. The length of the URL MUST NOT exceed 256 bytes. If UDP 2042 is used to convey the DOTS signal messages then the DOTS client must 2043 consider the amount of record expansion expected by the DTLS 2044 processing when calculating the size of CoAP message that fits within 2045 the path MTU. Path MTU MUST be greater than or equal to [CoAP 2046 message size + DTLS overhead of 13 octets + authentication overhead 2047 of the negotiated DTLS cipher suite + block padding (Section 4.1.1.1 2048 of [RFC6347]). If the request size exceeds the path MTU then the 2049 DOTS client MUST split the DOTS signal into separate messages, for 2050 example the list of addresses in the 'target-ip' parameter could be 2051 split into multiple lists and each list conveyed in a new PUT 2052 request. 2054 Implementation Note: DOTS choice of message size parameters works 2055 well with IPv6 and with most of today's IPv4 paths. However, with 2056 IPv4, it is harder to absolutely ensure that there is no IP 2057 fragmentation. If IPv4 support on unusual networks is a 2058 consideration and path MTU is unknown, implementations may want to 2059 limit themselves to more conservative IPv4 datagram sizes such as 576 2060 bytes, as per [RFC0791] IP packets up to 576 bytes should never need 2061 to be fragmented, thus sending a maximum of 500 bytes of DOTS signal 2062 over a UDP datagram will generally avoid IP fragmentation. 2064 8. (D)TLS 1.3 Considerations 2066 TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements 2067 for connection establishment over TLS 1.2. The DTLS 1.3 protocol 2068 [I-D.rescorla-tls-dtls13] is based on the TLS 1.3 protocol and 2069 provides equivalent security guarantees. (D)TLS 1.3 provides two 2070 basic handshake modes of interest to DOTS signal channel: 2072 o Absent packet loss, a full handshake in which the DOTS client is 2073 able to send the DOTS signal message after one round trip and the 2074 DOTS server immediately after receiving the first DOTS signal 2075 message from the client. 2077 o 0-RTT mode in which the DOTS client can authenticate itself and 2078 send DOTS signal message on its first flight, thus reducing 2079 handshake latency. 0-RTT only works if the DOTS client has 2080 previously communicated with that DOTS server, which is very 2081 likely with the DOTS signal channel. The DOTS client SHOULD 2082 establish a (D)TLS session with the DOTS server during peacetime 2083 and share a PSK. During DDOS attack, the DOTS client can use the 2084 (D)TLS session to convey the DOTS signal message and if there is 2085 no response from the server after multiple re-tries then the DOTS 2086 client can resume the (D)TLS session in 0-RTT mode using PSK. A 2087 simplified TLS 1.3 handshake with 0-RTT DOTS signal message 2088 exchange is shown in Figure 21. 2090 DOTS Client DOTS Server 2092 ClientHello 2093 (Finished) 2094 (0-RTT DOTS signal message) 2095 (end_of_early_data) --------> 2096 ServerHello 2097 {EncryptedExtensions} 2098 {ServerConfiguration} 2099 {Certificate} 2100 {CertificateVerify} 2101 {Finished} 2102 <-------- [DOTS signal message] 2103 {Finished} --------> 2105 [DOTS signal message] <-------> [DOTS signal message] 2107 Figure 21: TLS 1.3 handshake with 0-RTT 2109 9. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 2111 (D)TLS based on client certificate can be used for mutual 2112 authentication between DOTS agents. If a DOTS gateway is involved, 2113 DOTS clients and DOTS gateway MUST perform mutual authentication; 2114 only authorized DOTS clients are allowed to send DOTS signals to a 2115 DOTS gateway. DOTS gateway and DOTS server MUST perform mutual 2116 authentication; DOTS server only allows DOTS signals from authorized 2117 DOTS gateway, creating a two-link chain of transitive authentication 2118 between the DOTS client and the DOTS server. 2120 +-----------------------------------------------+ 2121 | example.com domain +---------+ | 2122 | | AAA | | 2123 | +---------------+ | Server | | 2124 | | Application | +------+--+ | 2125 | | server +<-----------------+ ^ | 2126 | | (DOTS client) | | | | 2127 | +---------------+ | | | 2128 | V V | example.net domain 2129 | +-----+----+--+ | +---------------+ 2130 | +--------------+ | | | | | 2131 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 2132 | | (DOTS client)| | Gateway | | | Server | 2133 | +--------------+ | | | | | 2134 | +----+--------+ | +---------------+ 2135 | ^ | 2136 | | | 2137 | +----------------+ | | 2138 | | DDOS detector | | | 2139 | | (DOTS client) +<---------------+ | 2140 | +----------------+ | 2141 +-----------------------------------------------+ 2143 Figure 22: Example of Authentication and Authorization of DOTS Agents 2145 In the example depicted in Figure 22, the DOTS gateway and DOTS 2146 clients within the 'example.com' domain mutually authenticate with 2147 each other. After the DOTS gateway validates the identity of a DOTS 2148 client, it communicates with the AAA server in the 'example.com' 2149 domain to determine if the DOTS client is authorized to request DDOS 2150 mitigation. If the DOTS client is not authorized, a 4.01 2151 (Unauthorized) is returned in the response to the DOTS client. In 2152 this example, the DOTS gateway only allows the application server and 2153 DDOS detector to request DDOS mitigation, but does not permit the 2154 user of type 'guest' to request DDOS mitigation. 2156 Also, DOTS gateway and DOTS server located in different domains MUST 2157 perform mutual authentication (e.g., using certificates). A DOTS 2158 server will only allow a DOTS gateway with a certificate for a 2159 particular domain to request mitigation for that domain. In 2160 reference to Figure 22, the DOTS server only allows the DOTS gateway 2161 to request mitigation for 'example.com' domain and not for other 2162 domains. 2164 10. IANA Considerations 2166 This specification registers a default port, new URI suffix in the 2167 Well-Known URIs registry, new CoAP response code, new parameters for 2168 DOTS signal channel and establishes registries for mappings to CBOR. 2170 10.1. DOTS Signal Channel UDP and TCP Port Number 2172 IANA has assigned the port number TBD to the DOTS signal channel 2173 protocol, for both UDP and TCP. 2175 10.2. Well-Known 'dots' URI 2177 This memo registers the 'dots' well-known URI in the Well-Known URIs 2178 registry as defined by [RFC5785]. 2180 URI suffix: dots 2182 Change controller: IETF 2184 Specification document(s): This RFC 2186 Related information: None 2188 10.3. CoAP Response Code 2190 The following entry is added to the "CoAP Response Codes" sub- 2191 registry: 2193 +------+-------------------+-----------+ 2194 | Code | Description | Reference | 2195 +------+-------------------+-----------+ 2196 | 3.00 | Alternate server | [RFCXXXX] | 2197 +------+-------------------+-----------+ 2199 Table 4: CoAP Response Code 2201 10.4. DOTS Signal Channel CBOR Mappings Registry 2203 A new registry will be requested from IANA, entitled "DOTS signal 2204 channel CBOR Mappings Registry". The registry is to be created as 2205 Expert Review Required. 2207 10.4.1. Registration Template 2209 Parameter name: 2210 Parameter names (e.g., "target_ip") in the DOTS signal channel. 2212 CBOR Key Value: 2213 Key value for the parameter. The key value MUST be an integer in 2214 the range of 1 to 65536. The key values in the range of 32768 to 2215 65536 are assigned for Vendor-Specific parameters. 2217 CBOR Major Type: 2218 CBOR Major type and optional tag for the claim. 2220 Change Controller: 2221 For Standards Track RFCs, list the "IESG". For others, give the 2222 name of the responsible party. Other details (e.g., postal 2223 address, email address, home page URI) may also be included. 2225 Specification Document(s): 2226 Reference to the document or documents that specify the parameter, 2227 preferably including URIs that can be used to retrieve copies of 2228 the documents. An indication of the relevant sections may also be 2229 included but is not required. 2231 10.4.2. Initial Registry Contents 2233 o Parameter Name: "mitigation-scope" 2234 o CBOR Key Value: 1 2235 o CBOR Major Type: 5 2236 o Change Controller: IESG 2237 o Specification Document(s): this document 2239 o Parameter Name: "scope" 2240 o CBOR Key Value: 2 2241 o CBOR Major Type: 5 2242 o Change Controller: IESG 2243 o Specification Document(s): this document 2245 o Parameter Name: "mitigation-id" 2246 o CBOR Key Value: 3 2247 o CBOR Major Type: 0 2248 o Change Controller: IESG 2249 o Specification Document(s): this document 2251 o Parameter Name:target-ip 2252 o CBOR Key Value: 4 2253 o CBOR Major Type: 4 2254 o Change Controller: IESG 2255 o Specification Document(s): this document 2257 o Parameter Name: target-port-range 2258 o CBOR Key Value: 5 2259 o CBOR Major Type: 4 2260 o Change Controller: IESG 2261 o Specification Document(s): this document 2263 o Parameter Name: "lower-port" 2264 o CBOR Key Value: 6 2265 o CBOR Major Type: 0 2266 o Change Controller: IESG 2267 o Specification Document(s): this document 2269 o Parameter Name: "upper-port" 2270 o CBOR Key Value: 7 2271 o CBOR Major Type: 0 2272 o Change Controller: IESG 2273 o Specification Document(s): this document 2275 o Parameter Name: target-protocol 2276 o CBOR Key Value: 8 2277 o CBOR Major Type: 4 2278 o Change Controller: IESG 2279 o Specification Document(s): this document 2281 o Parameter Name: "fqdn" 2282 o CBOR Key Value: 9 2283 o CBOR Major Type: 4 2284 o Change Controller: IESG 2285 o Specification Document(s): this document 2287 o Parameter Name: "uri" 2288 o CBOR Key Value: 10 2289 o CBOR Major Type: 4 2290 o Change Controller: IESG 2291 o Specification Document(s): this document 2293 o Parameter Name: alias-name 2294 o CBOR Key Value: 11 2295 o CBOR Major Type: 4 2296 o Change Controller: IESG 2297 o Specification Document(s): this document 2299 o Parameter Name: "lifetime" 2300 o CBOR Key Value: 12 2301 o CBOR Major Type: 0 2302 o Change Controller: IESG 2303 o Specification Document(s): this document 2305 o Parameter Name: attack-status 2306 o CBOR Key Value: 13 2307 o CBOR Major Type: 0 2308 o Change Controller: IESG 2309 o Specification Document(s): this document 2311 o Parameter Name: signal-config 2312 o CBOR Key Value: 14 2313 o CBOR Major Type: 5 2314 o Change Controller: IESG 2315 o Specification Document(s): this document 2317 o Parameter Name: heartbeat-interval 2318 o CBOR Key Value: 15 2319 o CBOR Major Type: 0 2320 o Change Controller: IESG 2321 o Specification Document(s): this document 2323 o Parameter Name: max-retransmit 2324 o CBOR Key Value: 16 2325 o CBOR Major Type: 0 2326 o Change Controller: IESG 2327 o Specification Document(s): this document 2329 o Parameter Name: ack-timeout 2330 o CBOR Key Value: 17 2331 o CBOR Major Type: 0 2332 o Change Controller: IESG 2333 o Specification Document(s): this document 2335 o Parameter Name: ack-random-factor 2336 o CBOR Key Value: 18 2337 o CBOR Major Type: 7 2338 o Change Controller: IESG 2339 o Specification Document(s): this document 2341 o Parameter Name: MinValue 2342 o CBOR Key Value: 19 2343 o CBOR Major Type: 0 2344 o Change Controller: IESG 2345 o Specification Document(s): this document 2347 o Parameter Name: MaxValue 2348 o CBOR Key Value: 20 2349 o CBOR Major Type: 0 2350 o Change Controller: IESG 2351 o Specification Document(s): this document 2353 o Parameter Name: status 2354 o CBOR Key Value: 21 2355 o CBOR Major Type: 0 2356 o Change Controller: IESG 2357 o Specification Document(s): this document 2359 o Parameter Name: bytes-dropped 2360 o CBOR Key Value: 22 2361 o CBOR Major Type: 0 2362 o Change Controller: IESG 2363 o Specification Document(s): this document 2365 o Parameter Name: bps-dropped 2366 o CBOR Key Value: 23 2367 o CBOR Major Type: 0 2368 o Change Controller: IESG 2369 o Specification Document(s): this document 2371 o Parameter Name: pkts-dropped 2372 o CBOR Key Value: 24 2373 o CBOR Major Type: 0 2374 o Change Controller: IESG 2375 o Specification Document(s): this document 2377 o Parameter Name: pps-dropped 2378 o CBOR Key Value: 25 2379 o CBOR Major Type: 0 2380 o Change Controller: IESG 2381 o Specification Document(s): this document 2383 o Parameter Name: session-id 2384 o CBOR Key Value: 26 2385 o CBOR Major Type: 0 2386 o Change Controller: IESG 2387 o Specification Document(s): this document 2389 o Parameter Name: trigger-mitigation 2390 o CBOR Key Value: 27 2391 o CBOR Major Type: 7 2392 o Change Controller: IESG 2393 o Specification Document(s): this document 2395 o Parameter Name: missing-hb-allowed 2396 o CBOR Key Value: 28 2397 o CBOR Major Type: 0 2398 o Change Controller: IESG 2399 o Specification Document(s): this document 2401 o Parameter Name: CurrentValue 2402 o CBOR Key Value: 29 2403 o CBOR Major Type: 0 2404 o Change Controller: IESG 2405 o Specification Document(s): this document 2407 o Parameter Name:mitigation-start 2408 o CBOR Key Value: 30 2409 o CBOR Major Type: 7 2410 o Change Controller: IESG 2411 o Specification Document(s): this document 2413 o Parameter Name:target-prefix 2414 o CBOR Key Value: 31 2415 o CBOR Major Type: 4 2416 o Change Controller: IESG 2417 o Specification Document(s): this document 2419 o Parameter Name:client-identifier 2420 o CBOR Key Value: 32 2421 o CBOR Major Type: 2 2422 o Change Controller: IESG 2423 o Specification Document(s): this document 2425 o Parameter Name:alt-server 2426 o CBOR Key Value: 33 2427 o CBOR Major Type: 2 2428 o Change Controller: IESG 2429 o Specification Document(s): this document 2431 o Parameter Name:alt-server-record 2432 o CBOR Key Value: 34 2433 o CBOR Major Type: 4 2434 o Change Controller: IESG 2435 o Specification Document(s): this document 2437 o Parameter Name:addr 2438 o CBOR Key Value: 35 2439 o CBOR Major Type: 2 2440 o Change Controller: IESG 2441 o Specification Document(s): this document 2443 o Parameter Name:ttl 2444 o CBOR Key Value: 36 2445 o CBOR Major Type: 0 2446 o Change Controller: IESG 2447 o Specification Document(s): this document 2449 10.5. YANG Modules 2451 This document requests IANA to register the following URIs in the 2452 "IETF XML Registry" [RFC3688]: 2454 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal 2455 Registrant Contact: The IESG. 2456 XML: N/A; the requested URI is an XML namespace. 2458 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-config 2459 Registrant Contact: The IESG. 2460 XML: N/A; the requested URI is an XML namespace. 2462 This document requests IANA to register the following YANG modules in 2463 the "YANG Module Names" registry [RFC7950]. 2465 name: ietf-signal 2466 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal 2467 prefix: signal 2468 reference: RFC XXXX 2470 name: ietf-dots-signal-config 2471 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-config 2472 prefix: config 2473 reference: RFC XXXX 2475 11. Implementation Status 2477 [Note to RFC Editor: Please remove this section and reference to 2478 [RFC7942] prior to publication.] 2480 This section records the status of known implementations of the 2481 protocol defined by this specification at the time of posting of this 2482 Internet-Draft, and is based on a proposal described in [RFC7942]. 2483 The description of implementations in this section is intended to 2484 assist the IETF in its decision processes in progressing drafts to 2485 RFCs. Please note that the listing of any individual implementation 2486 here does not imply endorsement by the IETF. Furthermore, no effort 2487 has been spent to verify the information presented here that was 2488 supplied by IETF contributors. This is not intended as, and must not 2489 be construed to be, a catalog of available implementations or their 2490 features. Readers are advised to note that other implementations may 2491 exist. 2493 According to [RFC7942], "this will allow reviewers and working groups 2494 to assign due consideration to documents that have the benefit of 2495 running code, which may serve as evidence of valuable experimentation 2496 and feedback that have made the implemented protocols more mature. 2497 It is up to the individual working groups to use this information as 2498 they see fit". 2500 11.1. nttdots 2502 Organization: NTT Communication is developing a DOTS client and 2503 DOTS server software based on DOTS signal channel specified in 2504 this draft. It will be open-sourced. 2505 Description: Early implementation of DOTS protocol. It is aimed to 2506 implement a full DOTS protocol spec in accordance with maturing of 2507 DOTS protocol itself. 2508 Implementation: https://github.com/nttdots/go-dots 2509 Level of maturity: It is a early implementation of DOTS protocol. 2510 Messaging between DOTS clients and DOTS servers has been tested. 2511 Level of maturity will increase in accordance with maturing of 2512 DOTS protocol itself. 2513 Coverage: Capability of DOTS client: sending DOTS messages to the 2514 DOTS server in CoAP over DTLS as dots-signal. Capability of DOTS 2515 server: receiving dots-signal, validating received dots-signal, 2516 starting mitigation by handing over the dots-signal to DDOS 2517 mitigator. 2518 Licensing: It will be open-sourced with BSD 3-clause license. 2519 Implementation experience: It is implemented in Go-lang. Core 2520 specification of signaling is mature to be implemented, however, 2521 finding good libraries(like DTLS, CoAP) is rather difficult. 2522 Contact: Kaname Nishizuka 2524 12. Security Considerations 2526 Authenticated encryption MUST be used for data confidentiality and 2527 message integrity. (D)TLS based on client certificate MUST be used 2528 for mutual authentication. The interaction between the DOTS agents 2529 requires Datagram Transport Layer Security (DTLS) and Transport Layer 2530 Security (TLS) with a cipher suite offering confidentiality 2531 protection and the guidance given in [RFC7525] MUST be followed to 2532 avoid attacks on (D)TLS. 2534 A single DOTS signal channel between DOTS agents can be used to 2535 exchange multiple DOTS signal messages. To reduce DOTS client and 2536 DOTS server workload, DOTS client SHOULD re-use the (D)TLS session. 2538 If TCP is used between DOTS agents, an attacker may be able to inject 2539 RST packets, bogus application segments, etc., regardless of whether 2540 TLS authentication is used. Because the application data is TLS 2541 protected, this will not result in the application receiving bogus 2542 data, but it will constitute a DoS on the connection. This attack 2543 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 2544 any bogus packets injected by an attacker will be rejected by the 2545 TCP-AO integrity check and therefore will never reach the TLS layer. 2547 In order to prevent leaking internal information outside a client- 2548 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 2549 the identity of internal DOTS clients (client-identifier) unless 2550 explicitly configured to do so. 2552 Special care should be taken in order to ensure that the activation 2553 of the proposed mechanism won't have an impact on the stability of 2554 the network (including connectivity and services delivered over that 2555 network). 2557 Involved functional elements in the cooperation system must establish 2558 exchange instructions and notification over a secure and 2559 authenticated channel. Adequate filters can be enforced to avoid 2560 that nodes outside a trusted domain can inject request such as 2561 deleting filtering rules. Nevertheless, attacks can be initiated 2562 from within the trusted domain if an entity has been corrupted. 2563 Adequate means to monitor trusted nodes should also be enabled. 2565 13. Contributors 2567 The following individuals have contributed to this document: 2569 Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email: 2570 mgeller@cisco.com 2572 Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States 2573 Email: rgm@htt-consult.com 2575 Dan Wing Email: dwing-ietf@fuggles.com 2577 14. Acknowledgements 2579 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 2580 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 2581 Xia, Jon Shallow, and Gilbert Clark for the discussion and comments. 2583 15. References 2585 15.1. Normative References 2587 [I-D.ietf-core-coap-tcp-tls] 2588 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 2589 Silverajan, B., and B. Raymor, "CoAP (Constrained 2590 Application Protocol) over TCP, TLS, and WebSockets", 2591 draft-ietf-core-coap-tcp-tls-10 (work in progress), 2592 October 2017. 2594 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2595 Requirement Levels", BCP 14, RFC 2119, 2596 DOI 10.17487/RFC2119, March 1997, 2597 . 2599 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 2600 DOI 10.17487/RFC3688, January 2004, 2601 . 2603 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 2604 Ciphersuites for Transport Layer Security (TLS)", 2605 RFC 4279, DOI 10.17487/RFC4279, December 2005, 2606 . 2608 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2609 (TLS) Protocol Version 1.2", RFC 5246, 2610 DOI 10.17487/RFC5246, August 2008, 2611 . 2613 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2614 Housley, R., and W. Polk, "Internet X.509 Public Key 2615 Infrastructure Certificate and Certificate Revocation List 2616 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 2617 . 2619 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 2620 Uniform Resource Identifiers (URIs)", RFC 5785, 2621 DOI 10.17487/RFC5785, April 2010, 2622 . 2624 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 2625 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 2626 June 2010, . 2628 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2629 Verification of Domain-Based Application Service Identity 2630 within Internet Public Key Infrastructure Using X.509 2631 (PKIX) Certificates in the Context of Transport Layer 2632 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2633 2011, . 2635 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 2636 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 2637 DOI 10.17487/RFC6234, May 2011, 2638 . 2640 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 2641 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 2642 January 2012, . 2644 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 2645 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 2646 Transport Layer Security (TLS) and Datagram Transport 2647 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 2648 June 2014, . 2650 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 2651 Application Protocol (CoAP)", RFC 7252, 2652 DOI 10.17487/RFC7252, June 2014, 2653 . 2655 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 2656 "Recommendations for Secure Use of Transport Layer 2657 Security (TLS) and Datagram Transport Layer Security 2658 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2659 2015, . 2661 [RFC7641] Hartke, K., "Observing Resources in the Constrained 2662 Application Protocol (CoAP)", RFC 7641, 2663 DOI 10.17487/RFC7641, September 2015, 2664 . 2666 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 2667 RFC 7950, DOI 10.17487/RFC7950, August 2016, 2668 . 2670 15.2. Informative References 2672 [I-D.ietf-core-comi] 2673 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 2674 Management Interface", draft-ietf-core-comi-01 (work in 2675 progress), July 2017. 2677 [I-D.ietf-core-yang-cbor] 2678 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 2679 Minaburo, "CBOR Encoding of Data Modeled with YANG", 2680 draft-ietf-core-yang-cbor-05 (work in progress), August 2681 2017. 2683 [I-D.ietf-dots-architecture] 2684 Mortensen, A., Andreasen, F., Reddy, T., 2685 christopher_gray3@cable.comcast.com, c., Compton, R., and 2686 N. Teague, "Distributed-Denial-of-Service Open Threat 2687 Signaling (DOTS) Architecture", draft-ietf-dots- 2688 architecture-05 (work in progress), October 2017. 2690 [I-D.ietf-dots-data-channel] 2691 Reddy, T., Boucadair, M., Nishizuka, K., Xia, L., Patil, 2692 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 2693 Service Open Threat Signaling (DOTS) Data Channel", draft- 2694 ietf-dots-data-channel-08 (work in progress), November 2695 2017. 2697 [I-D.ietf-dots-requirements] 2698 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 2699 Denial of Service (DDoS) Open Threat Signaling 2700 Requirements", draft-ietf-dots-requirements-07 (work in 2701 progress), October 2017. 2703 [I-D.ietf-dots-use-cases] 2704 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 2705 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 2706 Open Threat Signaling", draft-ietf-dots-use-cases-09 (work 2707 in progress), November 2017. 2709 [I-D.ietf-netmod-yang-tree-diagrams] 2710 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 2711 ietf-netmod-yang-tree-diagrams-02 (work in progress), 2712 October 2017. 2714 [I-D.ietf-tls-tls13] 2715 Rescorla, E., "The Transport Layer Security (TLS) Protocol 2716 Version 1.3", draft-ietf-tls-tls13-21 (work in progress), 2717 July 2017. 2719 [I-D.rescorla-tls-dtls13] 2720 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 2721 Datagram Transport Layer Security (DTLS) Protocol Version 2722 1.3", draft-rescorla-tls-dtls13-01 (work in progress), 2723 March 2017. 2725 [proto_numbers] 2726 "IANA, "Protocol Numbers"", 2011, 2727 . 2729 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 2730 DOI 10.17487/RFC0791, September 1981, 2731 . 2733 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 2734 Congestion Control Protocol (DCCP)", RFC 4340, 2735 DOI 10.17487/RFC4340, March 2006, 2736 . 2738 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 2739 (CIDR): The Internet Address Assignment and Aggregation 2740 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 2741 2006, . 2743 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 2744 Denial-of-Service Considerations", RFC 4732, 2745 DOI 10.17487/RFC4732, December 2006, 2746 . 2748 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 2749 Translation (NAT) Behavioral Requirements for Unicast 2750 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 2751 2007, . 2753 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 2754 RFC 4960, DOI 10.17487/RFC4960, September 2007, 2755 . 2757 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 2758 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 2759 . 2761 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 2762 "Transport Layer Security (TLS) Session Resumption without 2763 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 2764 January 2008, . 2766 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 2767 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 2768 2012, . 2770 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 2771 "Default Address Selection for Internet Protocol Version 6 2772 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 2773 . 2775 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 2776 "Enrollment over Secure Transport", RFC 7030, 2777 DOI 10.17487/RFC7030, October 2013, 2778 . 2780 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 2781 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 2782 October 2013, . 2784 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 2785 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 2786 . 2788 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 2789 NETCONF Protocol over Transport Layer Security (TLS) with 2790 Mutual X.509 Authentication", RFC 7589, 2791 DOI 10.17487/RFC7589, June 2015, 2792 . 2794 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 2795 Layer Security (TLS) False Start", RFC 7918, 2796 DOI 10.17487/RFC7918, August 2016, 2797 . 2799 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 2800 (TLS) Cached Information Extension", RFC 7924, 2801 DOI 10.17487/RFC7924, July 2016, 2802 . 2804 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 2805 Code: The Implementation Status Section", BCP 205, 2806 RFC 7942, DOI 10.17487/RFC7942, July 2016, 2807 . 2809 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 2810 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 2811 March 2017, . 2813 Authors' Addresses 2814 Tirumaleswar Reddy 2815 McAfee, Inc. 2816 Embassy Golf Link Business Park 2817 Bangalore, Karnataka 560071 2818 India 2820 Email: kondtir@gmail.com 2822 Mohamed Boucadair 2823 Orange 2824 Rennes 35000 2825 France 2827 Email: mohamed.boucadair@orange.com 2829 Prashanth Patil 2830 Cisco Systems, Inc. 2832 Email: praspati@cisco.com 2834 Andrew Mortensen 2835 Arbor Networks, Inc. 2836 2727 S. State St 2837 Ann Arbor, MI 48104 2838 United States 2840 Email: amortensen@arbor.net 2842 Nik Teague 2843 Verisign, Inc. 2844 United States 2846 Email: nteague@verisign.com