idnits 2.17.1 draft-ietf-dots-signal-channel-14.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 5 instances of too long lines in the document, the longest one being 11 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2081 has weird spacing: '...er-port ine...' == Line 2082 has weird spacing: '...er-port ine...' == Line 2097 has weird spacing: '...er-port ine...' == Line 2098 has weird spacing: '...er-port ine...' -- The document date (December 18, 2017) is 2292 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 3095, 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-02 == 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-10 == Outdated reference: A later version (-22) exists of draft-ietf-dots-requirements-08 == 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 (-43) exists of draft-ietf-tls-dtls13-22 == Outdated reference: A later version (-28) exists of draft-ietf-tls-tls13-22 -- 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 5389 (Obsoleted by RFC 8489) -- 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 (~~), 16 warnings (==), 6 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: June 21, 2018 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 December 18, 2017 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel 16 draft-ietf-dots-signal-channel-14 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 27 purposes. 29 Editorial Note (To be removed by RFC Editor) 31 Please update these statements with the RFC number to be assigned to 32 this document: 34 o "This version of this YANG module is part of RFC XXXX;" 36 o "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 37 (DOTS) Signal Channel"; 39 o "| 3.00 | Alternate server | [RFCXXXX] |" 41 o reference: RFC XXXX 43 o This RFC 45 Please update TBD statements with the port number to be assigned to 46 DOTS Signal Channel Protocol. 48 Status of This Memo 50 This Internet-Draft is submitted in full conformance with the 51 provisions of BCP 78 and BCP 79. 53 Internet-Drafts are working documents of the Internet Engineering 54 Task Force (IETF). Note that other groups may also distribute 55 working documents as Internet-Drafts. The list of current Internet- 56 Drafts is at https://datatracker.ietf.org/drafts/current/. 58 Internet-Drafts are draft documents valid for a maximum of six months 59 and may be updated, replaced, or obsoleted by other documents at any 60 time. It is inappropriate to use Internet-Drafts as reference 61 material or to cite them other than as "work in progress." 63 This Internet-Draft will expire on June 21, 2018. 65 Copyright Notice 67 Copyright (c) 2017 IETF Trust and the persons identified as the 68 document authors. All rights reserved. 70 This document is subject to BCP 78 and the IETF Trust's Legal 71 Provisions Relating to IETF Documents 72 (https://trustee.ietf.org/license-info) in effect on the date of 73 publication of this document. Please review these documents 74 carefully, as they describe your rights and restrictions with respect 75 to this document. Code Components extracted from this document must 76 include Simplified BSD License text as described in Section 4.e of 77 the Trust Legal Provisions and are provided without warranty as 78 described in the Simplified BSD License. 80 Table of Contents 82 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 83 2. Notational Conventions and Terminology . . . . . . . . . . . 5 84 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 85 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 8 86 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 8 87 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 8 88 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 9 89 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 10 90 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 11 91 4.4.2. Retrieve Information Related to a Mitigation . . . . 20 92 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 28 93 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 30 94 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 32 95 4.5.1. Discover Configuration Parameters . . . . . . . . . . 33 96 4.5.2. Convey DOTS Signal Channel Session Configuration . . 37 97 4.5.3. Delete DOTS Signal Channel Session Configuration . . 43 98 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 44 99 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 45 100 5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . . . 47 101 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 47 102 5.2. YANG Module . . . . . . . . . . . . . . . . . . . . . . . 49 103 6. Mapping Parameters to CBOR . . . . . . . . . . . . . . . . . 62 104 7. (D)TLS Protocol Profile and Performance Considerations . . . 63 105 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 63 106 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 64 107 7.3. MTU and Fragmentation . . . . . . . . . . . . . . . . . . 65 108 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 109 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 110 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 68 111 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 68 112 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 68 113 9.3. CoAP Response Code . . . . . . . . . . . . . . . . . . . 68 114 9.4. DOTS Signal Channel CBOR Mappings Registry . . . . . . . 69 115 9.4.1. Registration Template . . . . . . . . . . . . . . . . 69 116 9.4.2. Initial Registry Contents . . . . . . . . . . . . . . 69 117 9.5. DOTS Signal Channel YANG Module . . . . . . . . . . . . . 75 118 10. Implementation Status . . . . . . . . . . . . . . . . . . . . 75 119 10.1. nttdots . . . . . . . . . . . . . . . . . . . . . . . . 76 120 11. Security Considerations . . . . . . . . . . . . . . . . . . . 76 121 12. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 77 122 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 77 123 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 78 124 14.1. Normative References . . . . . . . . . . . . . . . . . . 78 125 14.2. Informative References . . . . . . . . . . . . . . . . . 80 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 84 128 1. Introduction 130 A distributed denial-of-service (DDoS) attack is an attempt to make 131 machines or network resources unavailable to their intended users. 132 In most cases, sufficient scale can be achieved by compromising 133 enough end-hosts and using those infected hosts to perpetrate and 134 amplify the attack. The victim in this attack can be an application 135 server, a host, a router, a firewall, or an entire network. 137 Network applications have finite resources like CPU cycles, the 138 number of processes or threads they can create and use, the maximum 139 number of simultaneous connections it can handle, the limited 140 resources of the control plane, etc. When processing network 141 traffic, such applications are supposed to use these resources to 142 offer the intended task in the most efficient manner. However, a 143 DDoS attacker may be able to prevent an application from performing 144 its intended task by making the application exhaust its finite 145 resources. 147 TCP DDoS SYN-flood, for example, is a memory-exhausting attack while 148 ACK-flood is a CPU-exhausting attack [RFC4987]. Attacks on the link 149 are carried out by sending enough traffic so that the link becomes 150 congested, thereby likely causing packet loss for legitimate traffic. 151 Stateful firewalls can also be attacked by sending traffic that 152 causes the firewall to maintain an excessive number of states that 153 may jeopardize the firewall's operation overall, besides like 154 performance impacts. The firewall then runs out of memory, and can 155 no longer instantiate the states required to process legitimate 156 flows. Other possible DDoS attacks are discussed in [RFC4732]. 158 In many cases, it may not be possible for network administrators to 159 determine the cause(s) of an attack. They may instead just realize 160 that certain resources seem to be under attack. This document 161 defines a lightweight protocol that allows a DOTS client to request 162 mitigation from one or more DOTS servers for protection against 163 detected, suspected, or anticipated attacks. This protocol enables 164 cooperation between DOTS agents to permit a highly-automated network 165 defense that is robust, reliable, and secure. 167 An example of a network diagram that illustrates a deployment of DOTS 168 agents is shown in Figure 1. In this example, a DOTS server is 169 operating on the access network. A DOTS client is located on the LAN 170 (Local Area Network), while a DOTS gateway is embedded in the CPE 171 (Customer Premises Equipment). 173 Network 174 Resource CPE router Access network __________ 175 +-----------+ +--------------+ +-------------+ / \ 176 | |___| |____| |___ | Internet | 177 |DOTS client| | DOTS gateway | | DOTS server | | | 178 | | | | | | | | 179 +-----------+ +--------------+ +-------------+ \__________/ 181 Figure 1: Sample DOTS Deployment (1) 183 DOTS servers can also be reachable over the Internet, as depicted in 184 Figure 2. 186 Network DDoS mitigation 187 Resource CPE router __________ service 188 +-----------+ +-------------+ / \ +-------------+ 189 | |___| |____| |___ | | 190 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 191 | | | | | | | | 192 +-----------+ +-------------+ \__________/ +-------------+ 194 Figure 2: Sample DOTS Deployment (2) 196 In typical deployments, the DOTS client belongs to a different 197 administrative domain than the DOTS server. For example, the DOTS 198 client is embedded in a firewall protecting services owned and 199 operated by a domain, while the DOTS server is owned and operated by 200 a different domain providing DDoS mitigation services. The latter 201 might or might not provide connectivity services to the network 202 hosting the DOTS client. 204 The DOTS server may (not) be co-located with the DOTS mitigator. In 205 typical deployments, the DOTS server belongs to the same 206 administrative domain as the mitigator. The DOTS client can 207 communicate directly with a DOTS server or indirectly via a DOTS 208 gateway. 210 The document adheres to the DOTS architecture 211 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 212 channel protocol are documented in [I-D.ietf-dots-requirements]. 213 This document satisfies all the use cases discussed in 214 [I-D.ietf-dots-use-cases]. 216 This document focuses on the DOTS signal channel. This is a 217 companion document of the DOTS data channel specification 218 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 219 data exchange mechanism supporting the DOTS signal channel. 221 2. Notational Conventions and Terminology 223 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 224 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 225 "OPTIONAL" in this document are to be interpreted as described in 226 [RFC2119]. 228 (D)TLS is used for statements that apply to both Transport Layer 229 Security [RFC5246] and Datagram Transport Layer Security [RFC6347]. 230 Specific terms are used for any statement that applies to either 231 protocol alone. 233 The reader should be familiar with the terms defined in 234 [I-D.ietf-dots-architecture]. 236 The meaning of the symbols in YANG tree diagrams is defined in 237 [I-D.ietf-netmod-yang-tree-diagrams]. 239 3. Design Overview 241 The DOTS signal channel is built on top of the Constrained 242 Application Protocol (CoAP) [RFC7252], a lightweight protocol 243 originally designed for constrained devices and networks. The many 244 features of CoAP (expectation of packet loss, support for 245 asynchronous non-confirmable messaging, congestion control, small 246 message overhead limiting the need for fragmentation, use of minimal 247 resources, and support for (D)TLS) makes it a good candidate to build 248 the DOTS signaling mechanism from. 250 The DOTS signal channel is layered on existing standards (Figure 3). 252 +---------------------+ 253 | DOTS Signal Channel | 254 +---------------------+ 255 | CoAP | 256 +----------+----------+ 257 | TLS | DTLS | 258 +----------+----------+ 259 | TCP | UDP | 260 +----------+----------+ 261 | IP | 262 +---------------------+ 264 Figure 3: Abstract Layering of DOTS signal channel over CoAP over 265 (D)TLS 267 By default, a DOTS signal channel MUST run over port number TBD as 268 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 269 has a mutual agreement with its DOTS clients to use a different port 270 number. DOTS clients may alternatively support means to dynamically 271 discover the ports used by their DOTS servers. In order to use a 272 distinct port number (as opposed to TBD), DOTS clients and servers 273 should support a configurable parameter to supply the port number to 274 use. The rationale for not using the default port number 5684 275 ((D)TLS CoAP) is to allow for differentiated behaviors in 276 environments where both a DOTS gateway and an IoT gateway (e.g., 277 Figure 3 of [RFC7452]) are present. 279 The signal channel is initiated by the DOTS client (Section 4.4). 280 Once the signal channel is established, the DOTS agents periodically 281 send heartbeats to keep the channel active (Section 4.7). At any 282 time, the DOTS client may send a mitigation request message to a DOTS 283 server over the active channel. While mitigation is active because 284 of the higher likelihood of packet loss during a DDoS attack, the 285 DOTS server periodically sends status messages to the client, 286 including basic mitigation feedback details. Mitigation remains 287 active until the DOTS client explicitly terminates mitigation, or the 288 mitigation lifetime expires. 290 DOTS signaling can happen with DTLS [RFC6347] over UDP and TLS 291 [RFC5246] over TCP. Likewise, DOTS requests may be sent using IPv4 292 or IPv6 transfer capabilities. A Happy Eyeballs procedure for DOTS 293 signal channel is specified in Section 4.3. 295 Messages exchanged between DOTS agents are serialized using Concise 296 Binary Object Representation (CBOR) [RFC7049], CBOR is a binary 297 encoding scheme designed for small code and message size. CBOR- 298 encoded payloads are used to carry signal channel-specific payload 299 messages which convey request parameters and response information 300 such as errors. In order to allow the use of the same data models, 301 [RFC7951] specifies the JSON encoding of YANG-modeled data. A 302 similar effort for CBOR is defined in [I-D.ietf-core-yang-cbor]. All 303 parameters in the payload of the DOTS signal channel are mapped to 304 CBOR types as specified in Section 6. 306 From that standpoint, this document specifies a YANG data model for 307 representing mitigation scopes and DOTS signal channel session 308 configuration data (Section 5). Representing these data as CBOR data 309 is assumed to follow the rules in [I-D.ietf-core-yang-cbor] or those 310 in [RFC7951] combined with JSON/CBOR conversion rules in [RFC7049]. . 312 In order to prevent fragmentation, DOTS agents must follow the 313 recommendations documented in Section 4.6 of [RFC7252]. Refer to 314 Section 7.3 for more details. 316 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 317 payload included in CoAP responses with 2.xx and 3.xx Response Codes 318 MUST be of content type "application/cbor" (Section 5.5.1 of 319 [RFC7252]). CoAP responses with 4.xx and 5.xx error Response Codes 320 MUST include a diagnostic payload (Section 5.5.2 of [RFC7252]). The 321 Diagnostic Payload may contain additional information to aid 322 troubleshooting. 324 In deployments where multiple DOTS clients are enabled in a network 325 (owned and operated by the same entity), the DOTS server may detect 326 conflicting mitigation requests from these clients. This document 327 does not aim to specify a comprehensive list of conditions under 328 which a DOTS server will characterize two mitigation requests from 329 distinct DOTS clients as conflicting, nor recommend a DOTS server 330 behavior for processing conflicting mitigation requests. Those 331 considerations are implementation- and deployment-specific. 332 Nevertheless, the document specifies the mechanisms to notify DOTS 333 clients when conflicts occur, including the conflict cause 334 (Section 4.4). 336 In deployments where one or more translators (e.g., Traditional NAT 337 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 338 enabled between the client's network and the DOTS server, DOTS signal 339 channel messages forwarded to a DOTS server must not include internal 340 IP addresses/prefixes and/or port numbers; external addresses/ 341 prefixes and/or port numbers as assigned by the translator must be 342 used instead. This document does not make any recommendation about 343 possible translator discovery mechanisms. The following are some 344 (non-exhaustive) deployment examples that may be considered: 346 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 347 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 348 external addresses/prefixes and/or port numbers. Information 349 retrieved by means of PCP or STUN will be used to feed the DOTS 350 signal channel messages that will be sent to a DOTS server. 352 o A DOTS gateway may be co-located with the translator. The DOTS 353 gateway will need to update the DOTS messages, based upon the 354 local translator's binding table. 356 4. DOTS Signal Channel: Messages & Behaviors 358 4.1. DOTS Server(s) Discovery 360 This document assumes that DOTS clients are provisioned with the 361 reachability information of their DOTS server(s) using a variety of 362 means (e.g., local configuration, or dynamic means such as DHCP). 363 These means are out of scope of this document. 365 Likewise, it is out of scope of this document to specify the behavior 366 of a DOTS client when it sends requests (e.g., contact all servers, 367 select one server among the list) when multiple DOTS servers are 368 provisioned. 370 4.2. CoAP URIs 372 The DOTS server MUST support the use of the path-prefix of "/.well- 373 known/" as defined in [RFC5785] and the registered name of "dots". 374 Each DOTS operation is indicated by a path-suffix that indicates the 375 intended operation. The operation path (Table 1) is appended to the 376 path-prefix to form the URI used with a CoAP request to perform the 377 desired DOTS operation. 379 +-----------------------+----------------+-------------+ 380 | Operation | Operation path | Details | 381 +-----------------------+----------------+-------------+ 382 | Mitigation | /v1/mitigate | Section 4.4 | 383 +-----------------------+----------------+-------------+ 384 | Session configuration | /v1/config | Section 4.5 | 385 +-----------------------+----------------+-------------+ 387 Table 1: Operations and their corresponding URIs 389 4.3. Happy Eyeballs for DOTS Signal Channel 391 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 392 support both connectionless and connection-oriented protocols. As 393 such, the DOTS signal channel is designed to operate with DTLS over 394 UDP and TLS over TCP. Further, a DOTS client may acquire a list of 395 IPv4 and IPv6 addresses (Section 4.1), each of which can be used to 396 contact the DOTS server using UDP and TCP. The following specifies 397 the procedure to follow to select the address family and the 398 transport protocol for sending DOTS signal channel messages. 400 Such procedure is needed to avoid experiencing long connection 401 delays. For example, if an IPv4 path to reach a DOTS server is 402 found, but the DOTS server's IPv6 path is not working, a dual-stack 403 DOTS client may experience a significant connection delay compared to 404 an IPv4-only DOTS client. The other problem is that if a middlebox 405 between the DOTS client and DOTS server is configured to block UDP 406 traffic, the DOTS client will fail to establish a DTLS session with 407 the DOTS server and, as a consequence, will have to fall back to TLS 408 over TCP, thereby incurring significant connection delays. 410 To overcome these connection setup problems, the DOTS client attempts 411 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 412 both DTLS over UDP and TLS over TCP in a manner similar to the Happy 413 Eyeballs mechanism [RFC6555]. These connection attempts are 414 performed by the DOTS client when it initializes. The results of the 415 Happy Eyeballs procedure are used by the DOTS client for sending its 416 subsequent messages to the DOTS server. 418 The order of preference of DOTS signal channel address family and 419 transport protocol (most preferred first) is: UDP over IPv6, UDP over 420 IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres 421 to the address preference order specified in [RFC6724] and the DOTS 422 signal channel preference which privileges the use of UDP over TCP 423 (to avoid TCP's head of line blocking). 425 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 426 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 427 this example, it is assumed that the IPv6 path is broken and UDP 428 traffic is dropped by a middlebox but has little impact to the DOTS 429 client because there is no long delay before using IPv4 and TCP. The 430 DOTS client repeats the mechanism to discover whether DOTS signal 431 channel messages with DTLS over UDP becomes available from the DOTS 432 server, so the DOTS client can migrate the DOTS signal channel from 433 TCP to UDP. Such probing SHOULD NOT be done more frequently than 434 every 24 hours and MUST NOT be done more frequently than every 5 435 minutes. 437 +-----------+ +-----------+ 438 |DOTS client| |DOTS server| 439 +-----------+ +-----------+ 440 | | 441 |--DTLS ClientHello, IPv6 ---->X | 442 |--TCP SYN, IPv6-------------->X | 443 |--DTLS ClientHello, IPv4 ---->X | 444 |--TCP SYN, IPv4--------------------------------------->| 445 |--DTLS ClientHello, IPv6 ---->X | 446 |--TCP SYN, IPv6-------------->X | 447 |<-TCP SYNACK-------------------------------------------| 448 |--DTLS ClientHello, IPv4 ---->X | 449 |--TCP ACK--------------------------------------------->| 450 |<------------Establish TLS Session-------------------->| 451 |----------------DOTS signal--------------------------->| 452 | | 454 Figure 4: DOTS Happy Eyeballs 456 4.4. DOTS Mitigation Methods 458 The following methods are used by a DOTS client to request, withdraw, 459 or retrieve the status of mitigation requests: 461 PUT: DOTS clients use the PUT method to request mitigation from a 462 DOTS server (Section 4.4.1). During active mitigation, DOTS 463 clients may use PUT requests to carry mitigation efficacy 464 updates to the DOTS server (Section 4.4.3). 466 GET: DOTS clients may use the GET method to subscribe to DOTS 467 server status messages, or to retrieve the list of its 468 mitigations maintained by a DOTS server (Section 4.4.2). 470 DELETE: DOTS clients use the DELETE method to withdraw a request for 471 mitigation from a DOTS server (Section 4.4.4). 473 Mitigation request and response messages are marked as Non- 474 confirmable messages (Section 2.2 of [RFC7252]). 476 DOTS agents SHOULD follow the data transmission guidelines discussed 477 in Section 3.1.3 of [RFC8085] and control transmission behavior by 478 not sending more than one UDP datagram per RTT to the peer DOTS agent 479 on average. 481 Requests marked by the DOTS client as Non-confirmable messages are 482 sent at regular intervals until a response is received from the DOTS 483 server. If the DOTS client cannot maintain an RTT estimate, it 484 SHOULD NOT send more than one Non-confirmable request every 3 485 seconds, and SHOULD use an even less aggressive rate whenever 486 possible (case 2 in Section 3.1.3 of [RFC8085]). 488 4.4.1. Request Mitigation 490 When a DOTS client requires mitigation for some reason, the DOTS 491 client uses the CoAP PUT method to send a mitigation request to its 492 DOTS server(s) (Figure 5, illustrated in JSON diagnostic notation). 494 If this DOTS client is entitled to solicit the DOTS service, the DOTS 495 server can enable mitigation on behalf of the DOTS client by 496 communicating the DOTS client's request to the mitigator and relaying 497 selected mitigator feedback to the requesting DOTS client. 499 Header: PUT (Code=0.03) 500 Uri-Host: "host" 501 Uri-Path: ".well-known" 502 Uri-Path: "dots" 503 Uri-Path: "version" 504 Uri-Path: "mitigate" 505 Content-Type: "application/cbor" 506 { 507 "mitigation-scope": { 508 "client-identifier": [ 509 "string" 510 ], 511 "scope": [ 512 { 513 "mitigation-id": integer, 514 "target-prefix": [ 515 "string" 516 ], 517 "target-port-range": [ 518 { 519 "lower-port": integer, 520 "upper-port": integer 521 } 522 ], 523 "target-protocol": [ 524 integer 525 ], 526 "target-fqdn": [ 527 "string" 528 ], 529 "target-uri": [ 530 "string" 531 ], 532 "alias-name": [ 533 "string" 534 ], 535 "lifetime": integer 536 } 537 ] 538 } 539 } 541 Figure 5: PUT to convey DOTS mitigation requests 543 The parameters are described below: 545 client-identifier: The client identifier MAY be conveyed by a 546 server-side DOTS gateway to propagate the DOTS client identity 547 from the gateway's client-side to the gateway's server-side, and 548 from the gateway's server-side to the DOTS server. 'client- 549 identifier' MAY be used by the final DOTS server for policy 550 enforcement purposes. 552 The 'client-identifier' value MUST be assigned by the server-side 553 DOTS gateway in a manner that ensures that there is zero 554 probability that the same value will be assigned to a different 555 DOTS client. The server-side DOTS gateway MUST conceal 556 potentially sensitive DOTS client identity information. 558 If aggregating DOTS mitigation requests received from multiple 559 DOTS clients is enabled, the server-side DOTS gateway has to 560 include a list of 'client-identifier' values; each value is 561 pointing to a unique DOTS client that is in the aggregated list. 562 It is out of scope of this document to specify how aggregation is 563 implemented by a DOTS gateway. 565 The client-identifier attribute MUST NOT be generated and included 566 by DOTS clients. 568 DOTS servers MUST ignore client-identifier attributes that are 569 directly supplied by source DOTS clients. This implies that first 570 server-side DOTS gateways MUST strip client-identifier attributes 571 supplied by DOTS clients. DOTS servers MAY support a 572 configuration parameter to identify DOTS gateways that are trusted 573 to supply client-identifier attributes. 575 This is an optional attribute. 577 mitigation-id: Identifier for the mitigation request represented 578 with an integer. This identifier MUST be unique for each 579 mitigation request bound to the DOTS client, i.e., the 580 'mitigation-id' parameter value in the mitigation request needs to 581 be unique relative to the 'mitigation-id' parameter values of 582 active mitigation requests conveyed from the DOTS client to the 583 DOTS server. This identifier MUST be generated by the DOTS 584 client. This document does not make any assumption about how this 585 identifier is generated. 587 This is a mandatory attribute. 589 target-prefix: A list of prefixes identifying resources under 590 attack. Prefixes are represented using Classless Inter-Domain 591 Routing (CIDR) notation [RFC4632]. 592 As a reminder, the prefix length must be less than or equal to 32 593 (resp. 128) for IPv4 (resp. IPv6). 595 This is an optional attribute. 597 target-port-range: A list of port numbers bound to resources under 598 attack. 600 The port range is defined by two bounds, a lower port number 601 (lower-port) and an upper port number (upper-port). When only 602 'lower-port' is present, it represents a single port number. For 603 TCP, UDP, Stream Control Transmission Protocol (SCTP) [RFC4960], 604 or Datagram Congestion Control Protocol (DCCP) [RFC4340], the 605 range of ports can be, for example, 1024-65535. 607 This is an optional attribute. 609 target-protocol: A list of protocols involved in an attack. Values 610 are taken from the IANA protocol registry [proto_numbers]. 612 The value '0' has a special meaning for 'all protocols'. 614 This is an optional attribute. 616 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 617 identifying resources under attack. An FQDN is the full name of a 618 resource, rather than just its hostname. For example, "venera" is 619 a hostname, and "venera.isi.edu" is an FQDN. 621 This is an optional attribute. 623 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 624 identifying resources under attack. 626 This is an optional attribute. 628 alias-name: A list of aliases of resources for which the mitigation 629 is requested. Aliases can be created using the DOTS data channel 630 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 631 configuration, or other means. An alias is used in subsequent 632 signal channel exchanges to refer more efficiently to the 633 resources under attack. 635 This is an optional attribute. 637 lifetime: Lifetime of the mitigation request in seconds. The 638 RECOMMENDED lifetime of a mitigation request is 3600 seconds (60 639 minutes) -- this value was chosen to be long enough so that 640 refreshing is not typically a burden on the DOTS client, while 641 expiring the request where the client has unexpectedly quit in a 642 timely manner. DOTS clients MUST include this parameter in their 643 mitigation requests. Upon the expiry of this lifetime, and if the 644 request is not refreshed, the mitigation request is removed. The 645 request can be refreshed by sending the same request again. 647 A lifetime of 0 in a mitigation request is an invalid value. 649 A lifetime of negative one (-1) indicates indefinite lifetime for 650 the mitigation request. The DOTS server MAY refuse indefinite 651 lifetime, for policy reasons; the granted lifetime value is 652 returned in the response. DOTS clients MUST be prepared to not be 653 granted mitigations with indefinite lifetimes. 655 The DOTS server MUST always indicate the actual lifetime in the 656 response and the remaining lifetime in status messages sent to the 657 DOTS client. 659 This is a mandatory attribute. 661 Because of the complexity to handle partial failure cases, this 662 specification does not allow for including multiple mitigation 663 requests in the same PUT request. Concretely, a DOTS client MUST NOT 664 include multiple 'scope' parameters in the same PUT request. 666 The CBOR key values for the parameters are defined in Section 6. 667 Section 9 defines how the CBOR key values can be allocated to 668 standard bodies and vendors. 670 FQDN and URI mitigation scopes may be thought of as a form of scope 671 alias, in which the addresses to which the domain name or URI resolve 672 represent the full scope of the mitigation. 674 In the PUT request at least one of the attributes 'target-prefix' or 675 'target-fqdn' or 'target-uri 'or 'alias-name' MUST be present. 676 Attributes with emty values MUST NOT be present in a request. 678 The relative order of two mitigation requests from a DOTS client is 679 determined by comparing their respective 'mitigation-id' values. If 680 two mitigation requests have overlapping mitigation scopes, the 681 mitigation request with the highest numeric 'mitigation-id' value 682 will override the other mitigation request. Two mitigation-ids from 683 a DOTS client are overlapping if there is a common IP address, IP 684 prefix, FQDN, URI, or alias-name. To avoid maintaining a long list 685 of overlapping mitigation requests from a DOTS client and avoid 686 error-prone provisioning of mitigation requests from a DOTS client, 687 the overlapped lower numeric 'mitigation-id' MUST be automatically 688 deleted and no longer available at the DOTS server. 690 The Uri-Path option carries a major and minor version nomenclature to 691 manage versioning and DOTS signal channel in this specification uses 692 v1 major version. 694 Figure 6 shows a PUT request example to signal that ports 80, 8080, 695 and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 servers are 696 under attack (illustrated in JSON diagnostic notation). 698 Header: PUT (Code=0.03) 699 Uri-Host: "www.example.com" 700 Uri-Path: ".well-known" 701 Uri-Path: "dots" 702 Uri-Path: "v1" 703 Uri-Path: "mitigate" 704 Content-Format: "application/cbor" 705 { 706 "mitigation-scope": { 707 "client-identifier": [ 708 "dz6pHjaADkaFTbjr0JGBpw" 709 ], 710 "scope": [ 711 { 712 "mitigation-id": 12332, 713 "target-prefix": [ 714 "2001:db8:6401::1/128", 715 "2001:db8:6401::2/128" 716 ], 717 "target-port-range": [ 718 { 719 "lower-port": 80 720 }, 721 { 722 "lower-port": 443 723 }, 724 { 725 "lower-port": 8080 726 } 727 ], 728 "target-protocol": [ 729 6 730 ] 731 } 732 ] 733 } 734 } 736 Figure 6: PUT for DOTS signal 738 The corresponding CBOR encoding format is shown in Figure 7. 740 A1 # map(1) 741 01 # unsigned(1) 742 A2 # map(2) 743 18 20 # unsigned(32) 744 81 # array(1) 745 76 # text(22) 746 647A3670486A6141446B614654626A72304A47427077 # "dz6pHjaADkaFTbjr0JGBpw" 747 02 # unsigned(2) 748 81 # array(1) 749 A4 # map(4) 750 03 # unsigned(3) 751 19 302C # unsigned(12332) 752 04 # unsigned(4) 753 82 # array(2) 754 74 # text(20) 755 323030313A6462383A363430313A3A312F313238 # "2001:db8:6401::1/128" 756 74 # text(20) 757 323030313A6462383A363430313A3A322F313238 # "2001:db8:6401::2/128" 758 05 # unsigned(5) 759 83 # array(3) 760 A1 # map(1) 761 06 # unsigned(6) 762 18 50 # unsigned(80) 763 A1 # map(1) 764 06 # unsigned(6) 765 19 01BB # unsigned(443) 766 A1 # map(1) 767 06 # unsigned(6) 768 19 1F90 # unsigned(8080) 769 08 # unsigned(8) 770 81 # array(1) 771 06 # unsigned(6) 773 Figure 7: PUT for DOTS signal (CBOR) 775 If the DOTS client is using the certificate provisioned by the 776 Enrollment over Secure Transport (EST) server [RFC7030] in the DOTS 777 gateway-domain to authenticate itself to the DOTS gateway, then the 778 'client-identifier' value can be the output of a cryptographic hash 779 algorithm whose input is the DER-encoded ASN.1 representation of the 780 Subject Public Key Info (SPKI) of an X.509 certificate. 782 In this version of the specification, the cryptographic hash 783 algorithm used is SHA-256 [RFC6234]. The output of the cryptographic 784 hash algorithm is truncated to 16 bytes; truncation is done by 785 stripping off the final 16 bytes. The truncated output is base64url 786 encoded. 788 In both DOTS signal and data channel sessions, the DOTS client MUST 789 authenticate itself to the DOTS server (Section 8). The DOTS server 790 may use the algorithm presented in Section 7 of [RFC7589] to derive 791 the DOTS client identity or username from the client certificate. 792 The DOTS client identity allows the DOTS server to accept mitigation 793 requests with scopes that the DOTS client is authorized to manage. 794 The DOTS server couples the DOTS signal and data channel sessions 795 using the DOTS client identity and the 'client-identifier' parameter 796 value, so the DOTS server can validate whether the aliases conveyed 797 in the mitigation request were indeed created by the same DOTS client 798 using the DOTS data channel session. If the aliases were not created 799 by the DOTS client, the DOTS server returns 4.00 (Bad Request) in the 800 response. 802 The DOTS server couples the DOTS signal channel sessions using the 803 DOTS client identity and the 'client-identifier' parameter value, and 804 the DOTS server uses 'mitigation-id' parameter value to detect 805 duplicate mitigation requests. If the mitigation request contains 806 the alias-name and other parameters identifying the target resources 807 (such as, 'target-prefix', 'target-port-range', 'target-fqdn', or 808 'target-uri'), then the DOTS server appends the parameter values in 809 'alias-name' with the corresponding parameter values in 'target- 810 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 812 The DOTS server indicates the result of processing the PUT request 813 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 814 codes are some sort of invalid requests (client errors). COAP 5.xx 815 codes are returned if the DOTS server has erred or is currently 816 unavailable to provide mitigation in response to the mitigation 817 request from the DOTS client. 819 Figure 8 shows an example of a PUT request that is successfully 820 processed (i.e., CoAP 2.xx response codes). 822 { 823 "mitigation-scope": { 824 "client-identifier": [ 825 "string" 826 ], 827 "scope": [ 828 { 829 "mitigation-id": 12332, 830 "lifetime": 3600 831 } 832 ] 833 } 834 } 836 Figure 8: 2.xx response body 838 If the request is missing one or more mandatory attributes, or 839 includes multiple 'scope' parameters, or contains invalid or unknown 840 parameters, the DOTS server MUST reply with 4.00 (Bad Request). DOTS 841 agents can safely ignore Vendor-Specific parameters they don't 842 understand. 844 A DOTS server that receives a mitigation request with a lifetime set 845 to '0' MUST reply with a 4.00 (Bad Request). 847 If the DOTS server does not find the 'mitigation-id' parameter value 848 conveyed in the PUT request in its configuration data, it MAY accept 849 the mitigation request by sending back a 2.01 (Created) response to 850 the DOTS client; the DOTS server will consequently try to mitigate 851 the attack. 853 If the DOTS server finds the 'mitigation-id' parameter value conveyed 854 in the PUT request in its configuration data, it MAY update the 855 mitigation request, and a 2.04 (Changed) response is returned to 856 indicate a successful update of the mitigation request. 858 If the request is conflicting with an existing mitigation request 859 from a different DOTS client, and the DOTS server decides to maintain 860 the conflicting mitigation request, the DOTS server returns 4.09 861 (Conflict) [RFC8132] to the requesting DOTS client. The response 862 includes enough information for a DOTS client to recognize the source 863 of the conflict (refer to 'conflict-information' specified in 864 Section 4.4.2). 866 For a mitigation request to continue beyond the initial negotiated 867 lifetime, the DOTS client has to refresh the current mitigation 868 request by sending a new PUT request. This PUT request MUST use the 869 same 'mitigation-id' value, and MUST repeat all the other parameters 870 as sent in the original mitigation request apart from a possible 871 change to the lifetime parameter value. 873 The DOTS gateway, which inserted a 'client-identifier' attribute in a 874 request, MUST strip the 'client-identifier' parameter in the 875 corresponding response before forwarding the response to the DOTS 876 client. 878 4.4.2. Retrieve Information Related to a Mitigation 880 A GET request is used by a DOTS client to retrieve information 881 (including status) of DOTS mitigations from a DOTS server. 883 The same considerations for manipulating 'client-identifier' 884 parameter by a DOTS gateway specified in Section 4.4.1 MUST be 885 followed for GET requests. 887 If the DOTS server does not find the 'mitigation-id' parameter value 888 conveyed in the GET request in its configuration data for the 889 requesting DOTS client or the one identified by 'client-identifier', 890 it MUST respond with a 4.04 (Not Found) error response code. 891 Likewise, the same error MUST be returned as a response to a request 892 to retrieve all mitigation records of a given DOTS client if the DOTS 893 server does not find any mitigation record for that DOTS client or 894 the one identified by 'client-identifier'. 896 The 'c' (content) parameter and its permitted values defined in 897 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 898 (attack mitigation status) or configuration data or both. The DOTS 899 server may support this optional filtering capability. It can safely 900 ignore it if not supported. 902 The following examples illustrate how a DOTS client retrieves active 903 mitigation requests from a DOTS server. In particular: 905 o Figure 9 shows the example of a GET request to retrieve all DOTS 906 mitigation requests signaled by a DOTS client. 908 o Figure 10 shows the example of a GET request to retrieve a 909 specific DOTS mitigation request signaled by a DOTS client. The 910 configuration data to be reported in the response is formatted in 911 the same order it was processed by the DOTS server. 913 These two examples assume the default of "c=a"; that is, the DOTS 914 client asks for all data to be reported by the DOTS server. 916 Header: GET (Code=0.01) 917 Uri-Host: "host" 918 Uri-Path: ".well-known" 919 Uri-Path: "dots" 920 Uri-Path: "version" 921 Uri-Path: "mitigate" 922 Observe : 0 923 { 924 "mitigation-scope": { 925 "client-identifier": [ 926 "dz6pHjaADkaFTbjr0JGBpw" 927 ] 928 } 929 } 931 Figure 9: GET to retrieve all DOTS mitigation requests 933 Header: GET (Code=0.01) 934 Uri-Host: "host" 935 Uri-Path: ".well-known" 936 Uri-Path: "dots" 937 Uri-Path: "version" 938 Uri-Path: "mitigate" 939 Observe : 0 940 Content-Format: "application/cbor" 941 { 942 "mitigation-scope": { 943 "client-identifier": [ 944 "dz6pHjaADkaFTbjr0JGBpw" 945 ], 946 "scope": [ 947 { 948 "mitigation-id": 12332 949 } 950 ] 951 } 952 } 954 Figure 10: GET to retrieve a specific DOTS mitigation request 956 Figure 11 shows a response example of all active mitigation requests 957 associated with the DOTS client on the DOTS server and the mitigation 958 status of each mitigation request. 960 { 961 "mitigation-scope": { 962 "scope": [ 963 { 964 "mitigation-id": 12332, 965 "mitigation-start": 1507818434.00, 966 "target-protocol": [ 967 17 968 ], 969 "lifetime": 1800, 970 "status": 2, 971 "bytes-dropped": 134334555, 972 "bps-dropped": 43344, 973 "pkts-dropped": 333334444, 974 "pps-dropped": 432432 975 }, 976 { 977 "mitigation-id": 12333, 978 "mitigation-start": 1507818393.00, 979 "target-protocol": [ 980 6 981 ], 982 "lifetime": 1800, 983 "status": 3, 984 "bytes-dropped": 0, 985 "bps-dropped": 0, 986 "pkts-dropped": 0, 987 "pps-dropped": 0 988 } 989 ] 990 } 991 } 993 Figure 11: Response body 995 The mitigation status parameters are described below: 997 mitigation-start: Mitigation start time is expressed in seconds 998 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 999 [RFC7049]). The encoding is modified so that the leading tag 1 1000 (epoch-based date/time) MUST be omitted. 1002 This is a mandatory attribute. 1004 lifetime: The remaining lifetime of the mitigation request, in 1005 seconds. 1007 This is a mandatory attribute. 1009 status: Status of attack mitigation. The various possible values of 1010 'status' parameter are explained in Table 2. 1012 This is a mandatory attribute. 1014 conflict-information: Indicates that a mitigation request is 1015 conflicting with another mitigation request(s) from other DOTS 1016 client(s). This optional attribute has the following structure: 1018 conflict-status: Indicates the status of a conflicting mitigation 1019 request. The following values are defined: 1021 1: DOTS server has detected conflicting mitigation requests 1022 from different DOTS clients. This mitigation request is 1023 currently inactive until the conflicts are resolved. 1024 Another mitigation request is active. 1026 2: DOTS server has detected conflicting mitigation requests 1027 from different DOTS clients. This mitigation request is 1028 currently active. 1030 3: DOTS server has detected conflicting mitigation requests 1031 from different DOTS clients. All conflicting mitigation 1032 requests are inactive. 1034 conflict-cause: Indicates the cause of the conflict. The 1035 following values are defined: 1037 1: Overlapping targets. 'conflict-scope' provides more details 1038 about the conflicting target clauses. 1040 2: Conflicts with an existing white list. This code is 1041 returned when the DDoS mitigation detects source addresses/ 1042 prefixes in the white-listed ACLs are attacking the target. 1044 conflict-scope Indicates the conflict scope. It may include a 1045 list of IP addresses, a list of prefixes, a list of port 1046 numbers, a list of target protocols, a list of FQDNs, a list of 1047 URIs, a list of alias-names, or references to conflicting ACLs. 1049 retry-timer Indicates, in seconds, the time after which the DOTS 1050 client may re-issue the same request. The DOTS server returns 1051 'retry-timer' only to DOTS client(s) for which a mitigation 1052 request is deactivated. Any retransmission of the same 1053 mitigation request before the expiry of this timer is likely to 1054 be rejected by the DOTS server for the same reasons. 1056 The retry-timer SHOULD be equal to the lifetime of the active 1057 mitigation request resulting in the deactivation of the 1058 conflicting mitigation request. The lifetime of the 1059 deactivated mitigation request will be updated to (retry-timer 1060 + 45 seconds), so the DOTS client can refresh the deactivated 1061 mitigation request after retry-timer seconds before expiry of 1062 lifetime and check if the conflict is resolved. 1064 bytes-dropped: The total dropped byte count for the mitigation 1065 request since the attack mitigation is triggered. The count wraps 1066 around when it reaches the maximum value of unsigned integer. 1068 This is an optional attribute. 1070 bps-dropped: The average number of dropped bytes per second for the 1071 mitigation request since the attack mitigation is triggered. This 1072 SHOULD be a five-minute average. 1074 This is an optional attribute. 1076 pkts-dropped: The total number of dropped packet count for the 1077 mitigation request since the attack mitigation is triggered. 1079 This is an optional attribute. 1081 pps-dropped: The average number of dropped packets per second for 1082 the mitigation request since the attack mitigation is triggered. 1083 This SHOULD be a five-minute average. 1085 This is an optional attribute. 1087 +-----------+-------------------------------------------------------+ 1088 | Parameter | Description | 1089 | value | | 1090 +-----------+-------------------------------------------------------+ 1091 | 1 | Attack mitigation is in progress (e.g., changing the | 1092 | | network path to re-route the inbound traffic to DOTS | 1093 | | mitigator). | 1094 +-----------+-------------------------------------------------------+ 1095 | 2 | Attack is successfully mitigated (e.g., traffic is | 1096 | | redirected to a DDOS mitigator and attack traffic is | 1097 | | dropped). | 1098 +-----------+-------------------------------------------------------+ 1099 | 3 | Attack has stopped and the DOTS client can withdraw | 1100 | | the mitigation request. | 1101 +-----------+-------------------------------------------------------+ 1102 | 4 | Attack has exceeded the mitigation provider | 1103 | | capability. | 1104 +-----------+-------------------------------------------------------+ 1105 | 5 | DOTS client has withdrawn the mitigation request and | 1106 | | the mitigation is active but terminating. | 1107 +-----------+-------------------------------------------------------+ 1108 | 6 | Attack mitigation is now terminated. | 1109 +-----------+-------------------------------------------------------+ 1110 | 7 | Attack mitigation is withdrawn. | 1111 +-----------+-------------------------------------------------------+ 1112 | 8 | Attack mitigation is rejected. | 1113 +-----------+-------------------------------------------------------+ 1115 Table 2: Values of 'status' parameter 1117 The observe option defined in [RFC7641] extends the CoAP core 1118 protocol with a mechanism for a CoAP client to "observe" a resource 1119 on a CoAP server: The client retrieves a representation of the 1120 resource and requests this representation be updated by the server as 1121 long as the client is interested in the resource. A DOTS client 1122 conveys the observe option set to '0' in the GET request to receive 1123 unsolicited notifications of attack mitigation status from the DOTS 1124 server. 1126 Unidirectional notifications within the bidirectional signal channel 1127 allows unsolicited message delivery, enabling asynchronous 1128 notifications between the agents. Due to the higher likelihood of 1129 packet loss during a DDoS attack, the DOTS server periodically sends 1130 attack mitigation status to the DOTS client and also notifies the 1131 DOTS client whenever the status of the attack mitigation changes. If 1132 the DOTS server cannot maintain a RTT estimate, it SHOULD NOT send 1133 more than one unsolicited notification every 3 seconds, and SHOULD 1134 use an even less aggressive rate whenever possible (case 2 in 1135 Section 3.1.3 of [RFC8085]). 1137 When conflicting requests are detected, the DOTS server enforces the 1138 corresponding policy (e.g., accept all requests, reject all requests, 1139 accept only one request but reject all the others, ...). It is 1140 assumed that this policy is supplied by the DOTS server administrator 1141 or it is a default behavior of the DOTS server implementation. Then, 1142 the DOTS server sends notification message(s) to the DOTS client(s) 1143 at the origin of the conflict. A conflict notification message 1144 includes information about the conflict cause, scope, and the status 1145 of the mitigation request(s). For example, 1147 o A notification message with status code set to '8 (Attack 1148 mitigation is rejected)' and 'conflict-status' set to '1' is sent 1149 to a DOTS client to indicate that this mitigation request is 1150 rejected because a conflict is detected. 1152 o A notification message with status code set to '7 (Attack 1153 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1154 to a DOTS client to indicate that an active mitigation request is 1155 deactivated because a conflict is detected. 1157 o A notification message with status code set to '1 (Attack 1158 mitigation is in progress)' and 'conflict-status' set to '2' is 1159 sent to a DOTS client to indicate that this mitigation request is 1160 in progress, but a conflict is detected. 1162 Upon receipt of a conflict notification message indicating that a 1163 mitigation request is deactivated because of a conflict, a DOTS 1164 client MUST NOT resend the same mitigation request before the expiry 1165 of 'retry-timer'. It is also recommended that DOTS clients support 1166 means to alert administrators about mitigation conflicts. 1168 A DOTS client that is no longer interested in receiving notifications 1169 from the DOTS server can simply "forget" the observation. When the 1170 DOTS server sends the next notification, the DOTS client will not 1171 recognize the token in the message and thus will return a Reset 1172 message. This causes the DOTS server to remove the associated entry. 1173 Alternatively, the DOTS client can explicitly deregister itself by 1174 issuing a GET request that has the Token field set to the token of 1175 the observation to be cancelled and includes an Observe Option with 1176 the value set to '1' (deregister). 1178 Figure 12 shows an example of a DOTS client requesting a DOTS server 1179 to send notifications related to a given mitigation request. 1181 DOTS Client DOTS Server 1182 | | 1183 | GET / | 1184 | Token: 0x4a | Registration 1185 | Observe: 0 | 1186 +------------------------------>| 1187 | | 1188 | 2.05 Content | 1189 | Token: 0x4a | Notification of 1190 | Observe: 12 | the current state 1191 | status: "mitigation | 1192 | in progress" | 1193 |<------------------------------+ 1194 | 2.05 Content | 1195 | Token: 0x4a | Notification upon 1196 | Observe: 44 | a state change 1197 | status: "mitigation | 1198 | complete" | 1199 |<------------------------------+ 1200 | 2.05 Content | 1201 | Token: 0x4a | Notification upon 1202 | Observe: 60 | a state change 1203 | status: "attack stopped" | 1204 |<------------------------------+ 1205 | | 1207 Figure 12: Notifications of attack mitigation status 1209 4.4.2.1. Mitigation Status 1211 The DOTS client can send the GET request at frequent intervals 1212 without the Observe option to retrieve the configuration data of the 1213 mitigation request and non-configuration data (i.e., the attack 1214 status). The frequency of polling the DOTS server to get the 1215 mitigation status should follow the transmission guidelines given in 1216 Section 3.1.3 of [RFC8085]. If the DOTS server has been able to 1217 mitigate the attack and the attack has stopped, the DOTS server 1218 indicates as such in the status, and the DOTS client recalls the 1219 mitigation request by issuing a DELETE request for the mitigation-id. 1221 A DOTS client SHOULD react to the status of the attack as per the 1222 information sent by the DOTS server rather than acknowledging by 1223 itself, using its own means, that the attack has been mitigated. 1224 This ensures that the DOTS client does not recall a mitigation 1225 request prematurely because it is possible that the DOTS client does 1226 not sense the DDOS attack on its resources but the DOTS server could 1227 be actively mitigating the attack and the attack is not completely 1228 averted. 1230 4.4.3. Efficacy Update from DOTS Clients 1232 While DDoS mitigation is active, due to the likelihood of packet 1233 loss, a DOTS client MAY periodically transmit DOTS mitigation 1234 efficacy updates to the relevant DOTS server. A PUT request is used 1235 to convey the mitigation efficacy update to the DOTS server. 1237 The PUT request MUST include all the parameters used in the PUT 1238 request to carry the DOTS mitigation request (Section 4.4.1) 1239 unchanged apart from the lifetime parameter value. If this is not 1240 the case, the DOTS server MUST reject the request with a 4.00 (Bad 1241 Request). 1243 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1244 value is used to make the PUT request conditional on the current 1245 existence of the mitigation request. If UDP is used as transport, 1246 CoAP requests may arrive out-of-order. For example, the DOTS client 1247 may send a PUT request to convey an efficacy update to the DOTS 1248 server followed by a DELETE request to withdraw the mitigation 1249 request, but the DELETE request arrives at the DOTS server before the 1250 PUT request. To handle out-of-order delivery of requests, if an If- 1251 Match option is present in the PUT request and the 'mitigation-id' in 1252 the request matches a mitigation request from that DOTS client, then 1253 the request is processed. If no match is found, the PUT request is 1254 silently ignored. 1256 An example of an efficacy update message, which includes an If-Match 1257 option with an empty value, is depicted in Figure 13. 1259 Header: PUT (Code=0.03) 1260 Uri-Host: "host" 1261 Uri-Path: ".well-known" 1262 Uri-Path: "dots" 1263 Uri-Path: "version" 1264 Uri-Path: "mitigate" 1265 Content-Format: "application/cbor" 1266 If-Match: 1267 { 1268 "mitigation-scope": { 1269 "client-identifier": [ 1270 "string" 1271 ], 1272 "scope": [ 1273 { 1274 "mitigation-id": integer, 1275 "target-prefix": [ 1276 "string" 1277 ], 1278 "target-port-range": [ 1279 { 1280 "lower-port": integer, 1281 "upper-port": integer 1282 } 1283 ], 1284 "target-protocol": [ 1285 integer 1286 ], 1287 "target-fqdn": [ 1288 "string" 1289 ], 1290 "target-uri": [ 1291 "string" 1292 ], 1293 "alias-name": [ 1294 "string" 1295 ], 1296 "lifetime": integer, 1297 "attack-status": integer 1298 } 1299 ] 1300 } 1301 } 1303 Figure 13: Efficacy Update 1305 The 'attack-status' parameter is a mandatory attribute when 1306 performing an efficacy update. The various possible values contained 1307 in the 'attack-status' parameter are described in Table 3. 1309 +-----------+-------------------------------------------------------+ 1310 | Parameter | Description | 1311 | value | | 1312 +-----------+-------------------------------------------------------+ 1313 | 1 | The DOTS client determines that it is still under | 1314 | | attack. | 1315 +-----------+-------------------------------------------------------+ 1316 | 2 | The DOTS client determines that the attack is | 1317 | | successfully mitigated (e.g., attack traffic is not | 1318 | | seen). | 1319 +-----------+-------------------------------------------------------+ 1321 Table 3: Values of 'attack-status' parameter 1323 The DOTS server indicates the result of processing a PUT request 1324 using CoAP response codes. The response code 2.04 (Changed) is 1325 returned if the DOTS server has accepted the mitigation efficacy 1326 update. The error response code 5.03 (Service Unavailable) is 1327 returned if the DOTS server has erred or is incapable of performing 1328 the mitigation. 1330 4.4.4. Withdraw a Mitigation 1332 A DELETE request is used to withdraw a DOTS mitigation request from a 1333 DOTS server (Figure 14). 1335 The same considerations for manipulating 'client-identifier' 1336 parameter by a DOTS gateway, as specified in Section 4.4.1, MUST be 1337 followed for DELETE requests. 1339 Header: DELETE (Code=0.04) 1340 Uri-Host: "host" 1341 Uri-Path: ".well-known" 1342 Uri-Path: "dots" 1343 Uri-Path: "version" 1344 Uri-Path: "mitigate" 1345 Content-Format: "application/cbor" 1346 { 1347 "mitigation-scope": { 1348 "client-identifier": [ 1349 "string" 1350 ], 1351 "scope": [ 1352 { 1353 "mitigation-id": integer 1354 } 1355 ] 1356 } 1357 } 1359 Figure 14: Withdraw DOTS signal 1361 If the request does not include a 'mitigation-id' parameter, the DOTS 1362 server MUST reply with a 4.00 (Bad Request). 1364 Once the request is validated, the DOTS server immediately 1365 acknowledges a DOTS client's request to withdraw the DOTS signal 1366 using 2.02 (Deleted) response code with no response payload. A 2.02 1367 (Deleted) Response Code is returned even if the 'mitigation-id' 1368 parameter value conveyed in the DELETE request does not exist in its 1369 configuration data before the request. 1371 If the DOTS server finds the 'mitigation-id' parameter value conveyed 1372 in the DELETE request in its configuration data for the DOTS client, 1373 then to protect against route or DNS flapping caused by a DOTS client 1374 rapidly removing a mitigation, and to dampen the effect of 1375 oscillating attacks, the DOTS server MAY allow mitigation to continue 1376 for a limited period after acknowledging a DOTS client's withdrawal 1377 of a mitigation request. During this period, the DOTS server status 1378 messages SHOULD indicate that mitigation is active but terminating 1379 (Section 4.4.2). 1381 The initial active-but-terminating period SHOULD be sufficiently long 1382 to absorb latency incurred by route propagation. The active-but- 1383 terminating period SHOULD be set by default to 120 seconds. If the 1384 client requests mitigation again before the initial active-but- 1385 terminating period elapses, the DOTS server MAY exponentially 1386 increase the active-but- terminating period up to a maximum of 300 1387 seconds (5 minutes). 1389 After the active-but-terminating period elapses, the DOTS server MUST 1390 treat the mitigation as terminated, as the DOTS client is no longer 1391 responsible for the mitigation. For example, if there is a financial 1392 relationship between the DOTS client and server domains, the DOTS 1393 client stops incurring cost at this point. 1395 4.5. DOTS Signal Channel Session Configuration 1397 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1398 channel session behavior. The DOTS signal channel can be used, for 1399 example, to configure the following: 1401 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1402 send heartbeats (CoAP Ping/Pong) to each other after mutual 1403 authentication is successfully completed in order to keep the 1404 DOTS signal channel open. Heartbeat messages are exchanged 1405 between DOTS agents every 'heartbeat-interval' seconds to detect 1406 the current status of the DOTS signal channel session. 1408 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1409 indicates the maximum number of consecutive heartbeat messages 1410 for which a DOTS agent did not receive a response before 1411 concluding that the session is disconnected or defunct. 1413 c. Acceptable signal loss ratio: Maximum retransmissions, 1414 retransmission timeout value, and other message transmission 1415 parameters for the DOTS signal channel. 1417 The same or distinct configuration sets may be used during attack 1418 ('attack-time-config') and peace times ('peace-time-config'). This 1419 is particularly useful for DOTS servers that might want to reduce 1420 heartbeat frequency or cease heartbeat exchanges when an active DOTS 1421 client has not requested mitigation. If distinct configuration are 1422 used, DOTS agents MUST follow the appropriate configuration set as a 1423 function of the mitigation activity (e.g., if no mitigation request 1424 is active, 'peace-time-config'-related values must be followed). 1425 Additionally, DOTS agents MUST automatically switch to the other 1426 configuration upon a change in the mitigation activity (e.g., if an 1427 attack mitigation is launched after a peacetime, the DOTS agent 1428 switches from 'peace-time-config' to 'attack-time-config'-related 1429 values). 1431 Requests and responses are deemed reliable by marking them as 1432 Confirmable (CON) messages. DOTS signal channel session 1433 configuration requests and responses are marked as Confirmable 1434 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1435 message is retransmitted using a default timeout and exponential 1436 back-off between retransmissions, until the DOTS server sends an 1437 Acknowledgement message (ACK) with the same Message ID conveyed from 1438 the DOTS client. 1440 Message transmission parameters are defined in Section 4.8 of 1441 [RFC7252]. The DOTS server can either piggyback the response in the 1442 acknowledgement message or, if the DOTS server cannot respond 1443 immediately to a request carried in a Confirmable message, it simply 1444 responds with an Empty Acknowledgement message so that the DOTS 1445 client can stop retransmitting the request. Empty Acknowledgement 1446 message is explained in Section 2.2 of [RFC7252]. When the response 1447 is ready, the server sends it in a new Confirmable message which in 1448 turn needs to be acknowledged by the DOTS client (see Sections 5.2.1 1449 and 5.2.2 of [RFC7252]). Requests and responses exchanged between 1450 DOTS agents during peacetime are marked as Confirmable messages. 1452 Implementation Note: A DOTS client that receives a response in a 1453 CON message may want to clean up the message state right after 1454 sending the ACK. If that ACK is lost and the DOTS server 1455 retransmits the CON, the DOTS client may no longer have any state 1456 that would help it correlate this response, thereby unexpecting 1457 the retransmission message. The DOTS client will send a Reset 1458 message so it does not receive any more retransmissions. This 1459 behavior is normal and not an indication of an error (see 1460 Section 5.3.2 of [RFC7252] for more details). 1462 4.5.1. Discover Configuration Parameters 1464 A GET request is used to obtain acceptable (e.g., minimum and maximum 1465 values) and current configuration parameters on the DOTS server for 1466 DOTS signal channel session configuration. 1468 Figure 15 shows how to obtain acceptable configuration parameters for 1469 the DOTS server. 1471 Header: GET (Code=0.01) 1472 Uri-Host: "host" 1473 Uri-Path: ".well-known" 1474 Uri-Path: "dots" 1475 Uri-Path: "version" 1476 Uri-Path: "config" 1478 Figure 15: GET to retrieve configuration 1480 The DOTS server in the 2.05 (Content) response conveys the current, 1481 minimum, and maximum attribute values acceptable by the DOTS server 1482 (Figure 16). 1484 Content-Format: "application/cbor" 1485 { 1486 "attack-time-config": { 1487 "heartbeat-interval": { 1488 "current-value": integer, 1489 "min-value": integer, 1490 "max-value": integer 1491 }, 1492 "missing-hb-allowed": { 1493 "current-value": integer, 1494 "min-value": integer, 1495 "max-value": integer 1496 }, 1497 "max-retransmit": { 1498 "current-value": integer, 1499 "min-value": integer, 1500 "max-value": integer 1501 }, 1502 "ack-timeout": { 1503 "current-value": integer, 1504 "min-value": integer, 1505 "max-value": integer 1506 }, 1507 "ack-random-factor": { 1508 "current-value": number, 1509 "min-value": number, 1510 "max-value": number 1511 } 1512 }, 1513 "peace-time-config": { 1514 "heartbeat-interval": { 1515 "current-value": integer, 1516 "min-value": integer, 1517 "max-value": integer 1518 }, 1519 "missing-hb-allowed": { 1520 "current-value": integer, 1521 "min-value": integer, 1522 "max-value": integer 1523 }, 1524 "max-retransmit": { 1525 "current-value": integer, 1526 "min-value": integer, 1527 "max-value": integer 1529 }, 1530 "ack-timeout": { 1531 "current-value": integer, 1532 "min-value": integer, 1533 "max-value": integer 1534 }, 1535 "ack-random-factor": { 1536 "current-value": number, 1537 "min-value": number, 1538 "max-value": number 1539 } 1540 }, 1541 "trigger-mitigation": { 1542 "current-value": boolean 1543 }, 1544 "config-interval": { 1545 "current-value": integer, 1546 "min-value": integer, 1547 "max-value": integer 1548 } 1549 } 1551 Figure 16: GET response body 1553 Figure 17 shows an example of acceptable and current configuration 1554 parameters on a DOTS server for DOTS signal channel session 1555 configuration. The same acceptable configuration is used during 1556 attack and peace times. 1558 Content-Format: "application/cbor" 1559 { 1560 "attack-time-config": { 1561 "heartbeat-interval": { 1562 "current-value": 30, 1563 "min-value": 15, 1564 "max-value": 240 1565 }, 1566 "missing-hb-allowed": { 1567 "current-value": 5, 1568 "min-value": 3, 1569 "max-value": 9 1570 }, 1571 "max-retransmit": { 1572 "current-value": 3, 1573 "min-value": 2, 1574 "max-value": 15 1575 }, 1576 "ack-timeout": { 1577 "current-value": 2, 1578 "min-value": 1, 1579 "max-value": 30 1580 }, 1581 "ack-random-factor": { 1582 "current-value": 1.5, 1583 "min-value": 1.1, 1584 "max-value": 4.0 1585 } 1586 }, 1587 "peace-time-config": { 1588 "heartbeat-interval": { 1589 "current-value": 30, 1590 "min-value": 15, 1591 "max-value": 240 1592 }, 1593 "missing-hb-allowed": { 1594 "current-value": 5, 1595 "min-value": 3, 1596 "max-value": 9 1597 }, 1598 "max-retransmit": { 1599 "current-value": 3, 1600 "min-value": 2, 1601 "max-value": 15 1602 }, 1603 "ack-timeout": { 1604 "current-value": 2, 1605 "min-value": 1, 1606 "max-value": 30 1607 }, 1608 "ack-random-factor": { 1609 "current-value": 1.5, 1610 "min-value": 1.1, 1611 "max-value": 4.0 1612 } 1613 }, 1614 "trigger-mitigation": { 1615 "current-value": true 1616 }, 1617 "config-interval": { 1618 "current-value": 1439, 1619 "min-value": 0, 1620 "max-value": 65535 1621 } 1622 } 1624 Figure 17: Configuration response body 1626 4.5.2. Convey DOTS Signal Channel Session Configuration 1628 A PUT request is used to convey the configuration parameters for the 1629 signal channel (e.g., heartbeat interval, maximum retransmissions). 1630 Message transmission parameters for CoAP are defined in Section 4.8 1631 of [RFC7252]. The RECOMMENDED values of transmission parameter 1632 values are ack-timeout (2 seconds), max-retransmit (3), ack-random- 1633 factor (1.5). In addition to those parameters, the RECOMMENDED 1634 specific DOTS transmission parameter values are 'heartbeat-interval' 1635 (30 seconds) and 'missing-hb-allowed' (5). 1637 Note: heartbeat-interval should be tweaked to also assist DOTS 1638 messages for NAT traversal (SIG-010 of 1639 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 1640 messages must not be sent more frequently than once every 15 1641 seconds and should use longer intervals when possible. 1642 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 1643 minutes or longer, but experience shows that sending packets every 1644 15 to 30 seconds is necessary to prevent the majority of 1645 middleboxes from losing state for UDP flows. From that 1646 standpoint, this specification recommends a minimum heartbeat- 1647 interval of 15 seconds and a maximum heartbeat-interval of 240 1648 seconds. The recommended value of 30 seconds is selected to 1649 anticipate the expiry of NAT state. 1651 A heartbeat-interval of 30 seconds may be seen as too chatty in 1652 some deployments. For such deployments, DOTS agents may negotiate 1653 longer heartbeat-interval values to prevent any network overload 1654 with too frequent keepalives. 1656 When a confirmable "CoAP Ping" is sent, and if there is no response, 1657 the "CoAP Ping" is retransmitted max-retransmit number of times by 1658 the CoAP layer using an initial timeout set to a random duration 1659 between ack-timeout and (ack-timeout*ack-random-factor) and 1660 exponential back-off between retransmissions. By choosing the 1661 recommended transmission parameters, the "CoAP Ping" will timeout 1662 after 45 seconds. If the DOTS agent does not receive any response 1663 from the peer DOTS agent for 'missing-hb-allowed' number of 1664 consecutive "CoAP Ping" confirmable messages, it concludes that the 1665 DOTS signal channel session is disconnected. A DOTS client MUST NOT 1666 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 1667 response from the same DOTS server. 1669 If the DOTS agent wishes to change the default values of message 1670 transmission parameters, then it should follow the guidance given in 1671 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 1672 values for message transmission parameters and default values for 1673 non-negotiated message transmission parameters. 1675 The signal channel session configuration is applicable to a single 1676 DOTS signal channel session between the DOTS agents. 1678 Header: PUT (Code=0.03) 1679 Uri-Host: "host" 1680 Uri-Path: ".well-known" 1681 Uri-Path: "dots" 1682 Uri-Path: "version" 1683 Uri-Path: "config" 1684 Content-Format: "application/cbor" 1685 { 1686 "signal-config": { 1687 "session-id": integer, 1688 "attack-time-config": { 1689 "heartbeat-interval": { 1690 "current-value": integer 1691 }, 1692 "missing-hb-allowed": { 1693 "current-value": integer 1694 }, 1695 "max-retransmit": { 1696 "current-value": integer 1697 }, 1698 "ack-timeout": { 1699 "current-value": integer 1700 }, 1701 "ack-random-factor": { 1702 "current-value": number 1703 } 1704 }, 1705 "peace-time-config": { 1706 "heartbeat-interval": { 1707 "current-value": integer 1708 }, 1709 "missing-hb-allowed": { 1710 "current-value": integer 1711 }, 1712 "max-retransmit": { 1713 "current-value": integer 1714 }, 1715 "ack-timeout": { 1716 "current-value": integer 1717 }, 1718 "ack-random-factor": { 1719 "current-value": number 1720 } 1721 }, 1722 "trigger-mitigation": boolean, 1723 "config-interval": integer 1724 } 1725 } 1727 Figure 18: PUT to convey the DOTS signal channel session 1728 configuration data. 1730 The parameters in Figure 18 are described below: 1732 session-id: Identifier for the DOTS signal channel session 1733 configuration data represented as an integer. This identifier 1734 MUST be generated by the DOTS client. This document does not make 1735 any assumption about how this identifier is generated. 1737 This is a mandatory attribute. 1739 attack-time-config: Set of configuration parameters to use when an 1740 attack is active. The following parameters may be included: 1742 heartbeat-interval: Time interval in seconds between two 1743 consecutive heartbeat messages. 1745 '0' is used to disable the heartbeat mechanism. 1747 This is an optional attribute. 1749 missing-hb-allowed: Maximum number of consecutive heartbeat 1750 messages for which the DOTS agent did not receive a response 1751 before concluding that the session is disconnected. 1753 This is an optional attribute. 1755 max-retransmit: Maximum number of retransmissions for a message 1756 (referred to as MAX_RETRANSMIT parameter in CoAP). 1758 This is an optional attribute. 1760 ack-timeout: Timeout value in seconds used to calculate the 1761 initial retransmission timeout value (referred to as 1762 ACK_TIMEOUT parameter in CoAP). 1764 This is an optional attribute. 1766 ack-random-factor: Random factor used to influence the timing of 1767 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1768 CoAP). 1770 This is an optional attribute. 1772 peace-time-config: Set of configuration parameters to use during 1773 peacetime. This attribute has the same structure as 'attack-time- 1774 config'. 1776 trigger-mitigation: If the parameter value is set to 'false', then 1777 DDoS mitigation is triggered only when the DOTS signal channel 1778 session is lost. Automated mitigation on loss of signal is 1779 discussed in Section 3.3.3 of [I-D.ietf-dots-architecture]. 1781 If the DOTS client ceases to respond to heartbeat messages, the 1782 DOTS server can detect that the DOTS session is lost. 1784 The default value of the parameter is 'true'. 1786 This is an optional attribute. 1788 config-interval: This parameter is returned to indicate the time 1789 interval expressed in minutes, which a DOTS agent must wait for 1790 before re-contacting its peer in order to retrieve the signal 1791 channel configuration data. 1793 '0' is used to disable this refresh mechanism. 1795 If a non-null value of 'config-interval' is received by a DOTS 1796 agent, it has to issue a PUT request to refresh the configuration 1797 parameters for the signal channel before the expiry of 'config- 1798 interval'. When a DDoS attack is active, refresh requests MUST 1799 NOT be sent by DOTS clients and the DOTS server MUST NOT terminate 1800 the (D)TLS session after the expiry of 'config-interval'. 1802 This mechanism allows to update the configuration data if a change 1803 occurs at the DOTS server side. For example, the new 1804 configuration may instruct a DOTS client to cease heartbeats or 1805 reduce heartbeat frequency. 1807 If this parameter is not returned, this is equivalent to receiving 1808 a 'config-interval' value set to '0'. 1810 If a DOTS server detects that a misbehaving DOTS client does not 1811 contact the DOTS server after the expiry of 'config-interval', in 1812 order to retrieve the signal channel configuration data, it MAY 1813 terminate the (D)TLS session. A (D)TLS session is terminated by 1814 the receipt of an authenticated message that closes the connection 1815 (e.g., a fatal alert (Section 7.2 of [RFC5246])). 1817 This is an optional attribute. 1819 At least one of the attributes 'heartbeat-interval', 'missing-hb- 1820 allowed', 'max-retransmit', 'ack-timeout', 'ack-random-factor', and 1821 'trigger-mitigation' MUST be present in the PUT request. The PUT 1822 request with a higher numeric 'session-id' value overrides the DOTS 1823 signal channel session configuration data installed by a PUT request 1824 with a lower numeric 'session-id' value. 1826 Figure 19 shows a PUT request example to convey the configuration 1827 parameters for the DOTS signal channel. In this example, heartbeat 1828 mechanism is disabled during peacetime, while the heartbeat interval 1829 is set to '91' when an attack is active. 1831 Header: PUT (Code=0.03) 1832 Uri-Host: "www.example.com" 1833 Uri-Path: ".well-known" 1834 Uri-Path: "dots" 1835 Uri-Path: "v1" 1836 Uri-Path: "config" 1837 Content-Format: "application/cbor" 1838 { 1839 "signal-config": { 1840 "session-id": 1234534333242, 1841 "attack-time-config": { 1842 "heartbeat-interval": { 1843 "current-value": 91 1844 }, 1845 "missing-hb-allowed": { 1846 "current-value": 3 1847 }, 1848 "max-retransmit": { 1849 "current-value": 7 1850 }, 1851 "ack-timeout": { 1852 "current-value": 5 1853 }, 1854 "ack-random-factor": { 1855 "current-value": 1.5 1856 } 1857 }, 1858 "peace-time-config": { 1859 "heartbeat-interval": { 1860 "current-value": 0 1861 }, 1862 "max-retransmit": { 1863 "current-value": 7 1864 }, 1865 "ack-timeout": { 1866 "current-value": 5 1867 }, 1868 "ack-random-factor": { 1869 "current-value": 1.5 1870 } 1871 }, 1872 "trigger-mitigation": false 1873 } 1874 } 1876 Figure 19: PUT to convey the configuration parameters 1878 The DOTS server indicates the result of processing the PUT request 1879 using CoAP response codes: 1881 o If the DOTS server finds the 'session-id' parameter value conveyed 1882 in the PUT request in its configuration data and if the DOTS 1883 server has accepted the updated configuration parameters, then 1884 2.04 (Changed) code is returned in the response. 1886 o If the DOTS server does not find the 'session-id' parameter value 1887 conveyed in the PUT request in its configuration data and if the 1888 DOTS server has accepted the configuration parameters, then a 1889 response code 2.01 (Created) is returned in the response. 1891 o If the request is missing one or more mandatory attributes or it 1892 contains one or more invalid or unknown parameters, 4.00 (Bad 1893 Request) is returned in the response. 1895 o Response code 4.22 (Unprocessable Entity) is returned in the 1896 response, if any of the 'heartbeat-interval', 'missing-hb- 1897 allowed', 'max-retransmit', 'target-protocol', 'ack-timeout', and 1898 'ack-random-factor' attribute values are not acceptable to the 1899 DOTS server. Upon receipt of the 4.22 error response code, the 1900 DOTS client should request the maximum and minimum attribute 1901 values acceptable to the DOTS server (Section 4.5.1). 1903 The DOTS client may re-try and send the PUT request with updated 1904 attribute values acceptable to the DOTS server. 1906 4.5.3. Delete DOTS Signal Channel Session Configuration 1908 A DELETE request is used to delete the installed DOTS signal channel 1909 session configuration data (Figure 20). 1911 Header: DELETE (Code=0.04) 1912 Uri-Host: "host" 1913 Uri-Path: ".well-known" 1914 Uri-Path: "dots" 1915 Uri-Path: "version" 1916 Uri-Path: "config" 1917 Content-Format: "application/cbor" 1919 Figure 20: DELETE configuration 1921 The DOTS server resets the DOTS signal channel session configuration 1922 back to the default values and acknowledges a DOTS client's request 1923 to remove the DOTS signal channel session configuration using 2.02 1924 (Deleted) response code. 1926 4.6. Redirected Signaling 1928 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 1929 [I-D.ietf-dots-architecture]. 1931 If a DOTS server wants to redirect a DOTS client to an alternative 1932 DOTS server for a signal session, then the response code 3.00 1933 (alternate server) will be returned in the response to the client. 1935 The DOTS server can return the error response code 3.00 in response 1936 to a PUT request from the DOTS client or convey the error response 1937 code 3.00 in a unidirectional notification response from the DOTS 1938 server. 1940 The DOTS server in the error response conveys the alternate DOTS 1941 server's FQDN, and the alternate DOTS server's IP address(es) and 1942 time to live values in the CBOR body (Figure 21). 1944 { 1945 "alt-server": "string", 1946 "alt-server-record": [ 1947 { 1948 "addr": "string", 1949 "ttl" : integer 1950 } 1951 ] 1952 } 1954 Figure 21: Error response body 1956 The parameters are described below: 1958 alt-server: FQDN of an alternate DOTS server. 1960 addr: IP address of an alternate DOTS server. 1962 ttl: Time to live (TTL) represented as an integer number of seconds. 1964 Figure 22 shows a 3.00 response example to convey the DOTS alternate 1965 server 'alt-server.example', its IP addresses 2001:db8:6401::1 and 1966 2001:db8:6401::2, and TTL values 3600 and 1800. 1968 { 1969 "alt-server": "alt-server.example", 1970 "alt-server-record": [ 1971 { 1972 "ttl" : 3600, 1973 "addr": "2001:db8:6401::1" 1974 }, 1975 { 1976 "ttl" : 1800, 1977 "addr": "2001:db8:6401::2" 1978 } 1979 ] 1980 } 1982 Figure 22: Example of error response body 1984 When the DOTS client receives 3.00 response, it considers the current 1985 request as failed, but SHOULD try re-sending the request to the 1986 alternate DOTS server. During a DDOS attack, the DNS server may be 1987 the target of another DDoS attack, alternate DOTS server's IP 1988 addresses conveyed in the 3.00 response help the DOTS client skip DNS 1989 lookup of the alternate DOTS server. The DOTS client can then try to 1990 establish a UDP or a TCP session with the alternate DOTS server. The 1991 DOTS client SHOULD implement a DNS64 function to handle the scenario 1992 where an IPv6-only DOTS client communicates with an IPv4-only 1993 alternate DOTS server. 1995 4.7. Heartbeat Mechanism 1997 To provide an indication of signal health and distinguish an 'idle' 1998 signal channel from a 'disconnected' or 'defunct' session, the DOTS 1999 agent sends a heartbeat over the signal channel to maintain its half 2000 of the channel. The DOTS agent similarly expects a heartbeat from 2001 its peer DOTS agent, and may consider a session terminated in the 2002 prolonged absence of a peer agent heartbeat. 2004 While the communication between the DOTS agents is quiescent, the 2005 DOTS client will probe the DOTS server to ensure it has maintained 2006 cryptographic state and vice versa. Such probes can also keep 2007 firewalls and/or stateful translators bindings alive. This probing 2008 reduces the frequency of establishing a new handshake when a DOTS 2009 signal needs to be conveyed to the DOTS server. 2011 In order to avoid complications due to the presence of some stateful 2012 translators and firewalls (e.g., discard an incoming packet because 2013 no matching state is found), DOTS servers MAY trigger their heartbeat 2014 requests immediately after receiving heartbeat probes from peer DOTS 2015 clients. 2017 In case of a massive DDoS attack that saturates the incoming link(s) 2018 to the DOTS client, all traffic from the DOTS server to the DOTS 2019 client will likely be dropped, although the DOTS server receives 2020 heartbeat requests in addition to DOTS messages sent by the DOTS 2021 client. In this scenario, the DOTS agents MUST behave differently to 2022 handle message transmission and DOTS session liveliness during link 2023 saturation: 2025 o The DOTS client MUST NOT consider the DOTS session terminated even 2026 after a maximum 'missing-hb-allowed' threshold is reached. The 2027 DOTS client SHOULD keep on using the current DOTS session to send 2028 heartbeat requests over it, so that the DOTS server knows the DOTS 2029 client has not disconnected the DOTS session. 2031 After the maximum 'missing-hb-allowed' threshold is reached, the 2032 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2033 client SHOULD send mitigation requests over the current DOTS 2034 session, and in parallel, for example, try to resume the (D)TLS 2035 session or use 0-RTT mode in DTLS 1.3 to piggyback the mitigation 2036 request in the ClientHello message. 2038 As soon as the link is no longer saturated, if traffic from the 2039 DOTS server reaches the DOTS client over the current DOTS session, 2040 the DOTS client can stop (D)TLS session resumption or if (D)TLS 2041 session resumption is successful then disconnect the current DOTS 2042 session. 2044 o If the DOTS server does not receive any traffic from the peer DOTS 2045 client, then the DOTS server sends heartbeat requests to the DOTS 2046 client and after maximum 'missing-hb-allowed' threshold is 2047 reached, the DOTS server concludes the session is disconnected. 2049 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2050 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2051 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2052 message and the peer DOTS agent will respond by sending a Reset 2053 message. 2055 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2056 DOTS agents using the Ping and Pong messages specified in Section 4.4 2057 of [I-D.ietf-core-coap-tcp-tls]. That is, the DOTS agent sends a 2058 Ping message and the peer DOTS agent would respond by sending a 2059 single Pong message. 2061 5. DOTS Signal Channel YANG Module 2063 This document defines a YANG [RFC7950] module for mitigation scope 2064 and DOTS signal channel session configuration data. 2066 5.1. Tree Structure 2068 This document defines the YANG module "ietf-dots-signal" 2069 (Section 5.2), which has the following tree structure. A DOTS signal 2070 message can either be a mitigation or a configuration message. 2072 module: ietf-dots-signal 2073 +--rw dots-signal 2074 +--rw (message-type)? 2075 +--:(mitigation-scope) 2076 | +--rw client-identifier* binary 2077 | +--rw scope* [mitigation-id] 2078 | +--rw mitigation-id int32 2079 | +--rw target-prefix* inet:ip-prefix 2080 | +--rw target-port-range* [lower-port upper-port] 2081 | | +--rw lower-port inet:port-number 2082 | | +--rw upper-port inet:port-number 2083 | +--rw target-protocol* uint8 2084 | +--rw target-fqdn* inet:domain-name 2085 | +--rw target-uri* inet:uri 2086 | +--rw alias-name* string 2087 | +--rw lifetime? int32 2088 | +--rw mitigation-start? int64 2089 | +--ro status? enumeration 2090 | +--ro conflict-information 2091 | | +--ro conflict-status? enumeration 2092 | | +--ro conflict-cause? enumeration 2093 | | +--ro retry-timer? int32 2094 | | +--ro conflict-scope 2095 | | +--ro target-prefix* inet:ip-prefix 2096 | | +--ro target-port-range* [lower-port upper-port] 2097 | | | +--ro lower-port inet:port-number 2098 | | | +--ro upper-port inet:port-number 2099 | | +--ro target-protocol* uint8 2100 | | +--ro target-fqdn* inet:domain-name 2101 | | +--ro target-uri* inet:uri 2102 | | +--ro alias-name* string 2103 | | +--ro acl-list* [acl-name acl-type] 2104 | | +--ro acl-name -> /ietf-acl:access-lists/acl/acl-name 2105 | | +--ro acl-type -> /ietf-acl:access-lists/acl/acl-type 2106 | +--ro pkts-dropped? yang:zero-based-counter64 2107 | +--ro bps-dropped? yang:zero-based-counter64 2108 | +--ro bytes-dropped? yang:zero-based-counter64 2109 | +--ro pps-dropped? yang:zero-based-counter64 2110 +--:(configuration) 2111 +--rw session-id int32 2112 +--rw attack-time-config 2113 | +--rw heartbeat-interval 2114 | | +--rw max-value? int16 2115 | | +--rw min-value? int16 2116 | | +--rw current-value? int16 2117 | +--rw missing-hb-allowed 2118 | | +--rw max-value? int16 2119 | | +--rw min-value? int16 2120 | | +--rw current-value? int16 2121 | +--rw max-retransmit 2122 | | +--rw max-value? int16 2123 | | +--rw min-value? int16 2124 | | +--rw current-value? int16 2125 | +--rw ack-timeout 2126 | | +--rw max-value? int16 2127 | | +--rw min-value? int16 2128 | | +--rw current-value? int16 2129 | +--rw ack-random-factor 2130 | +--rw max-value? decimal64 2131 | +--rw min-value? decimal64 2132 | +--rw current-value? decimal64 2133 +--rw peace-time-config 2134 | +--rw heartbeat-interval 2135 | | +--rw max-value? int16 2136 | | +--rw min-value? int16 2137 | | +--rw current-value? int16 2138 | +--rw missing-hb-allowed 2139 | | +--rw max-value? int16 2140 | | +--rw min-value? int16 2141 | | +--rw current-value? int16 2142 | +--rw max-retransmit 2143 | | +--rw max-value? int16 2144 | | +--rw min-value? int16 2145 | | +--rw current-value? int16 2146 | +--rw ack-timeout 2147 | | +--rw max-value? int16 2148 | | +--rw min-value? int16 2149 | | +--rw current-value? int16 2150 | +--rw ack-random-factor 2151 | +--rw max-value? decimal64 2152 | +--rw min-value? decimal64 2153 | +--rw current-value? decimal64 2154 +--rw trigger-mitigation? boolean 2155 +--rw config-interval? int32 2157 5.2. YANG Module 2159 file "ietf-dots-signal@2017-12-19.yang" 2161 module ietf-dots-signal { 2162 yang-version 1.1; 2163 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal"; 2164 prefix "signal"; 2166 import ietf-inet-types {prefix "inet";} 2167 import ietf-yang-types {prefix yang;} 2168 import ietf-access-control-list {prefix "ietf-acl";} 2170 organization "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2172 contact 2173 "Konda, Tirumaleswar Reddy 2174 Mohamed Boucadair 2175 Prashanth Patil 2176 Andrew Mortensen 2177 Nik Teague "; 2179 description 2180 "This module contains YANG definition for the signaling 2181 messages exchanged between a DOTS client and a DOTS server. 2183 Copyright (c) 2017 IETF Trust and the persons identified as 2184 authors of the code. All rights reserved. 2186 Redistribution and use in source and binary forms, with or 2187 without modification, is permitted pursuant to, and subject 2188 to the license terms contained in, the Simplified BSD License 2189 set forth in Section 4.c of the IETF Trust's Legal Provisions 2190 Relating to IETF Documents 2191 (http://trustee.ietf.org/license-info). 2193 This version of this YANG module is part of RFC XXXX; see 2194 the RFC itself for full legal notices."; 2196 revision 2017-12-19 { 2197 description 2198 "Initial revision."; 2199 reference 2200 "RFC XXXX: Distributed Denial-of-Service Open Threat 2201 Signaling (DOTS) Signal Channel"; 2202 } 2204 grouping target { 2205 description 2206 "Specifies the scope of the mitigation request."; 2208 leaf-list target-prefix { 2209 type inet:ip-prefix; 2210 description 2211 "IPv4 or IPv6 prefix identifying the target."; 2212 } 2214 list target-port-range { 2215 key "lower-port upper-port"; 2217 description 2218 "Port range. When only lower-port is 2219 present, it represents a single port."; 2221 leaf lower-port { 2222 type inet:port-number; 2223 mandatory true; 2224 description "Lower port number."; 2225 } 2227 leaf upper-port { 2228 type inet:port-number; 2229 must ". >= ../lower-port" { 2230 error-message 2231 "The upper port number must be greater than 2232 or equal to lower port number."; 2233 } 2234 description "Upper port number."; 2235 } 2236 } 2238 leaf-list target-protocol { 2239 type uint8; 2240 description 2241 "Identifies the target protocol number. 2243 The value '0' means 'all protocols'. 2245 Values are taken from the IANA protocol registry: 2246 https://www.iana.org/assignments/protocol-numbers/ 2247 protocol-numbers.xhtml 2249 For example, 6 for TCP or 17 for UDP."; 2250 } 2252 leaf-list target-fqdn { 2253 type inet:domain-name; 2254 description "FQDN identifying the target."; 2255 } 2257 leaf-list target-uri { 2258 type inet:uri; 2259 description "URI identifying the target."; 2260 } 2262 leaf-list alias-name { 2263 type string; 2264 description "alias name"; 2265 } 2266 } 2268 grouping mitigation-scope { 2269 description 2270 "Specifies the scope of the mitigation request."; 2272 leaf-list client-identifier { 2273 type binary; 2274 description 2275 "The client identifier may be conveyed by 2276 the DOTS gateway to propagate the DOTS client 2277 identification information from the gateway's 2278 client-side to the gateway's server-side, 2279 and from the gateway's server-side to the DOTS 2280 server. 2282 It may be used by the final DOTS server 2283 for policy enforcement purposes."; 2284 } 2286 list scope { 2287 key mitigation-id; 2288 description 2289 "The scope of the request."; 2291 leaf mitigation-id { 2292 type int32; 2293 description 2294 "Mitigation request identifier. 2296 This identifier must be unique for each mitigation 2297 request bound to the DOTS client."; 2298 } 2300 uses target; 2301 leaf lifetime { 2302 type int32; 2303 units "seconds"; 2304 default 3600; 2305 description 2306 "Indicates the lifetime of the mitigation request."; 2307 reference 2308 "RFC XXXX: Distributed Denial-of-Service Open Threat 2309 Signaling (DOTS) Signal Channel"; 2310 } 2312 leaf mitigation-start { 2313 type int64; 2314 units "seconds"; 2315 description 2316 "Mitigation start time is represented in seconds 2317 relative to 1970-01-01T00:00Z in UTC time."; 2318 } 2320 leaf status { 2321 type enumeration { 2322 enum "attack-mitigation-in-progress" { 2323 value 1; 2324 description 2325 "Attack mitigation is in progress (e.g., changing 2326 the network path to re-route the inbound traffic 2327 to DOTS mitigator)."; 2328 } 2330 enum "attack-successfully-mitigated" { 2331 value 2; 2332 description 2333 "Attack is successfully mitigated (e.g., traffic 2334 is redirected to a DDOS mitigator and attack 2335 traffic is dropped or blackholed)."; 2336 } 2338 enum "attack-stopped" { 2339 value 3; 2340 description 2341 "Attack has stopped and the DOTS client can 2342 withdraw the mitigation request."; 2343 } 2345 enum "attack-exceeded-capability" { 2346 value 4; 2347 description 2348 "Attack has exceeded the mitigation provider 2349 capability."; 2350 } 2352 enum "dots-client-withdrawn-mitigation" { 2353 value 5; 2354 description 2355 "DOTS client has withdrawn the mitigation 2356 request and the mitigation is active but 2357 terminating."; 2358 } 2360 enum "attack-mitigation-terminated" { 2361 value 6; 2362 description 2363 "Attack mitigation is now terminated."; 2364 } 2366 enum "attack-mitigation-withdrawn" { 2367 value 7; 2368 description 2369 "Attack mitigation is withdrawn."; 2370 } 2372 enum "attack-mitigation-rejected" { 2373 value 8; 2374 description 2375 "Attack mitigation is rejected."; 2376 } 2377 } 2378 config false; 2379 description 2380 "Indicates the status of a mitigation request. 2381 It must be included in responses only."; 2382 } 2384 container conflict-information { 2385 config false; 2386 description 2387 "Indicates that a conflict is detected. 2388 Must only be used for responses."; 2390 leaf conflict-status { 2391 type enumeration { 2392 enum "request-inactive-other-active" { 2393 value 1; 2394 description 2395 "DOTS Server has detected conflicting mitigation 2396 requests from different DOTS clients. 2398 This mitigation request is currently inactive 2399 until the conflicts are resolved. Another 2400 mitigation request is active."; 2401 } 2403 enum "request-active" { 2404 value 2; 2405 description 2406 "DOTS Server has detected conflicting mitigation 2407 requests from different DOTS clients. 2408 This mitigation request is currently active."; 2409 } 2411 enum "all-requests-inactive" { 2412 value 3; 2413 description 2414 "DOTS Server has detected conflicting mitigation 2415 requests from different DOTS clients. All 2416 conflicting mitigation requests are inactive."; 2417 } 2418 } 2419 description 2420 "Indicates the conflict status. 2421 It must be included in responses only."; 2422 } 2424 leaf conflict-cause { 2425 type enumeration { 2426 enum "overlapping-targets" { 2427 value 1; 2428 description 2429 "Overlapping targets. conflict-scope provides 2430 more details about the exact conflict."; 2431 } 2433 enum "conflict-with-whitelist" { 2434 value 2; 2435 description 2436 "Conflicts with an existing white list. 2438 This code is returned when the DDoS mitigation 2439 detects that some of the source addresses/prefixes 2440 listed in the white list ACLs are actually 2441 attacking the target."; 2442 } 2443 } 2444 description 2445 "Indicates the cause of the conflict. 2447 It must be included in responses only."; 2448 } 2450 leaf retry-timer { 2451 type int32; 2452 units "seconds"; 2453 description 2454 "The DOTS client must not re-send the 2455 same request before the expiry of this timer. 2456 It must be included in responses, only."; 2457 } 2459 container conflict-scope { 2460 description 2461 "Provides more information about the conflict scope."; 2463 uses target { 2464 when "../conflict-cause = 'overlapping-targets'"; 2465 } 2467 list acl-list { 2468 when "../../conflict-cause = 'conflict-with-whitelist'"; 2469 key "acl-name acl-type"; 2470 description 2471 "List of conflicting ACLs"; 2473 leaf acl-name { 2474 type leafref { 2475 path "/ietf-acl:access-lists/ietf-acl:acl" + 2476 "/ietf-acl:acl-name"; 2477 } 2478 description 2479 "Reference to the conflicting ACL name bound to 2480 a DOTS client."; 2481 } 2483 leaf acl-type { 2484 type leafref { 2485 path "/ietf-acl:access-lists/ietf-acl:acl" + 2486 "/ietf-acl:acl-type"; 2487 } 2488 description 2489 "Reference to the conflicting ACL type bound to 2490 a DOTS client."; 2491 } 2492 } 2493 } 2494 } 2495 leaf pkts-dropped { 2496 type yang:zero-based-counter64; 2497 config false; 2498 description 2499 "Number of dropped packets"; 2500 } 2502 leaf bps-dropped { 2503 type yang:zero-based-counter64; 2504 config false; 2505 description 2506 "The average number of dropped bytes per second for 2507 the mitigation request since the attack 2508 mitigation is triggered."; 2509 } 2511 leaf bytes-dropped { 2512 type yang:zero-based-counter64; 2513 units 'bytes'; 2514 config false; 2515 description 2516 "Counter for dropped packets; in bytes."; 2517 } 2519 leaf pps-dropped { 2520 type yang:zero-based-counter64; 2521 config false; 2522 description 2523 "The average number of dropped packets per second 2524 for the mitigation request since the attack 2525 mitigation is triggered."; 2526 } 2527 } 2528 } 2530 grouping config-parameters { 2531 description 2532 "Subset of DOTS signal channel session configuration."; 2534 container heartbeat-interval { 2535 description 2536 "DOTS agents regularly send heartbeats to each other 2537 after mutual authentication is successfully 2538 completed in order to keep the DOTS signal channel 2539 open."; 2541 leaf max-value { 2542 type int16; 2543 units "seconds"; 2544 description 2545 "Maximum acceptable value."; 2546 reference 2547 "RFC XXXX: Distributed Denial-of-Service Open Threat 2548 Signaling (DOTS) Signal Channel"; 2549 } 2551 leaf min-value { 2552 type int16; 2553 units "seconds"; 2554 description 2555 "Minimum acceptable value."; 2556 reference 2557 "RFC XXXX: Distributed Denial-of-Service Open Threat 2558 Signaling (DOTS) Signal Channel"; 2559 } 2560 leaf current-value { 2561 type int16; 2562 units "seconds"; 2563 default 30; 2564 description 2565 "Current value. 2567 '0' means that heartbeat mechanism is deactivated."; 2568 reference 2569 "RFC XXXX: Distributed Denial-of-Service Open Threat 2570 Signaling (DOTS) Signal Channel"; 2571 } 2572 } 2574 container missing-hb-allowed { 2575 description 2576 "Maximum number of missing heartbeats allowed."; 2578 leaf max-value { 2579 type int16; 2580 description 2581 "Maximum acceptable value."; 2582 reference 2583 "RFC XXXX: Distributed Denial-of-Service Open Threat 2584 Signaling (DOTS) Signal Channel"; 2585 } 2587 leaf min-value { 2588 type int16; 2589 description 2590 "Minimum acceptable value."; 2592 reference 2593 "RFC XXXX: Distributed Denial-of-Service Open Threat 2594 Signaling (DOTS) Signal Channel"; 2595 } 2596 leaf current-value { 2597 type int16; 2598 default 5; 2599 description 2600 "Current value."; 2601 reference 2602 "RFC XXXX: Distributed Denial-of-Service Open Threat 2603 Signaling (DOTS) Signal Channel"; 2604 } 2605 } 2607 container max-retransmit { 2608 description 2609 "Maximum number of retransmissions of a Confirmable 2610 message."; 2612 leaf max-value { 2613 type int16; 2614 description 2615 "Maximum acceptable value."; 2616 reference 2617 "Section 4.8 of RFC 7552."; 2618 } 2620 leaf min-value { 2621 type int16; 2622 description 2623 "Minimum acceptable value."; 2624 reference 2625 "Section 4.8 of RFC 7552."; 2626 } 2627 leaf current-value { 2628 type int16; 2629 default 3; 2630 description 2631 "Current value."; 2632 reference 2633 "RFC XXXX: Distributed Denial-of-Service Open Threat 2634 Signaling (DOTS) Signal Channel"; 2635 } 2636 } 2638 container ack-timeout { 2639 description 2640 "Initial retransmission timeout value."; 2642 leaf max-value { 2643 type int16; 2644 units "seconds"; 2645 description 2646 "Maximum value."; 2647 reference 2648 "Section 4.8 of RFC 7552."; 2649 } 2651 leaf min-value { 2652 type int16; 2653 units "seconds"; 2654 description 2655 "Minimum value."; 2656 reference 2657 "Section 4.8 of RFC 7552."; 2658 } 2659 leaf current-value { 2660 type int16; 2661 units "seconds"; 2662 default 2; 2663 description 2664 "Current value."; 2665 reference 2666 "Section 4.8 of RFC 7552."; 2667 } 2668 } 2670 container ack-random-factor { 2671 description 2672 "Random factor used to influence the timing of 2673 retransmissions."; 2675 leaf max-value { 2676 type decimal64 { 2677 fraction-digits 2; 2678 } 2679 description 2680 "Maximum acceptable value."; 2681 reference 2682 "Section 4.8 of RFC 7552."; 2683 } 2685 leaf min-value { 2686 type decimal64 { 2687 fraction-digits 2; 2689 } 2690 description 2691 "Minimum acceptable value."; 2692 reference 2693 "Section 4.8 of RFC 7552."; 2694 } 2695 leaf current-value { 2696 type decimal64 { 2697 fraction-digits 2; 2698 } 2699 default 1.5; 2700 description 2701 "Current value."; 2702 reference 2703 "Section 4.8 of RFC 7552."; 2704 } 2705 } 2706 } 2708 grouping signal-config { 2709 description 2710 "DOTS signal channel session configuration."; 2712 leaf session-id { 2713 type int32; 2714 mandatory true; 2715 description 2716 "An identifier for the DOTS signal channel 2717 session configuration data."; 2718 } 2720 container attack-time-config { 2721 description 2722 "Configuration paramaters to use when an attack is active."; 2723 uses config-parameters; 2724 } 2726 container peace-time-config { 2727 description 2728 "Configuration paramaters to use in peacetime."; 2729 uses config-parameters; 2730 } 2732 leaf trigger-mitigation { 2733 type boolean; 2734 default true; 2735 description 2736 "If false, then mitigation is triggered 2737 only when the DOTS server channel session is lost"; 2738 reference 2739 "RFC XXXX: Distributed Denial-of-Service Open Threat 2740 Signaling (DOTS) Signal Channel"; 2741 } 2743 leaf config-interval { 2744 type int32; 2745 units "minutes"; 2746 description 2747 "This parameter is returned by a DOTS server to 2748 a requesting DOTS client to indicate the time interval 2749 after which the DOTS client must contact the DOTS 2750 server in order to retrieve the signal channel 2751 configuration data. 2753 This mechanism allows the update of the configuration 2754 data if a change occurs. 2756 For example, the new configuration may instruct 2757 a DOTS client to cease heartbeats or reduce 2758 heartbeat frequency. 2760 '0' is used to disable this refresh mechanism."; 2761 } 2762 } 2764 container dots-signal { 2765 description 2766 "Main container for DOTS signal message. 2767 A DOTS signal message can be a mitigation message or 2768 a configuration message."; 2770 choice message-type { 2771 description 2772 "Either a mitigation or a configuration message."; 2774 case mitigation-scope { 2775 description 2776 "Mitigation scope of a mitigation message."; 2777 uses mitigation-scope; 2778 } 2780 case configuration { 2781 description 2782 "Configuration message."; 2783 uses signal-config; 2784 } 2786 } 2787 } 2788 } 2789 2791 6. Mapping Parameters to CBOR 2793 All parameters in the payload of the DOTS signal channel MUST be 2794 mapped to CBOR types as shown in Table 4 and are assigned an integer 2795 key to save space. The recipient of the payload MAY reject the 2796 information if it is not suitably mapped. 2798 /----------------------+----------------+--------------------------\ 2799 | Parameter name | CBOR key | CBOR major type of value | 2800 +----------------------+----------------+--------------------------+ 2801 | mitigation-scope | 1 | 5 (map) | 2802 | scope | 2 | 5 (map) | 2803 | mitigation-id | 3 | 0 (unsigned) | 2804 | acl-list | 4 | 4 | 2805 | target-port-range | 5 | 4 | 2806 | lower-port | 6 | 0 | 2807 | upper-port | 7 | 0 | 2808 | target-protocol | 8 | 4 | 2809 | target-fqdn | 9 | 4 | 2810 | target-uri | 10 | 4 | 2811 | alias-name | 11 | 4 | 2812 | lifetime | 12 | 0 | 2813 | attack-status | 13 | 0 | 2814 | signal-config | 14 | 5 | 2815 | heartbeat-interval | 15 | 5 (map) | 2816 | max-retransmit | 16 | 5 (map) | 2817 | ack-timeout | 17 | 5 (map) | 2818 | ack-random-factor | 18 | 5 (map) | 2819 | min-value | 19 | 0 | 2820 | max-value | 20 | 0 | 2821 | status | 21 | 0 | 2822 | conflict-information | 22 | 5 (map) | 2823 | conflict-status | 23 | 0 | 2824 | conflict-cause | 24 | 0 | 2825 | retry-timer | 25 | 0 | 2826 | bytes-dropped | 26 | 0 | 2827 | bps-dropped | 27 | 0 | 2828 | pkts-dropped | 28 | 0 | 2829 | pps-dropped | 29 | 0 | 2830 | session-id | 30 | 0 | 2831 | trigger-mitigation | 31 | 7 (simple types) | 2832 | missing-hb-allowed | 32 | 5 (map) | 2833 | current-value | 33 | 0 | 2834 | mitigation-start | 34 | 7 (floating-point) | 2835 | target-prefix | 35 | 4 (array) | 2836 | client-identifier | 36 | 2 (byte string) | 2837 | alt-server | 37 | 2 | 2838 | alt-server-record | 38 | 4 | 2839 | addr | 39 | 2 | 2840 | ttl | 40 | 0 | 2841 | conflict-scope | 41 | 5 (map) | 2842 | acl-name | 42 | 3 | 2843 | acl-type | 43 | 3 | 2844 | config-interval | 44 | 0 | 2845 | attack-time-config | 45 | 5 (map) | 2846 | peace-time-config | 46 | 5 (map) | 2847 \----------------------+----------------+--------------------------/ 2848 Table 4: CBOR mappings used in DOTS signal channel message 2850 7. (D)TLS Protocol Profile and Performance Considerations 2852 7.1. (D)TLS Protocol Profile 2854 This section defines the (D)TLS protocol profile of DOTS signal 2855 channel over (D)TLS and DOTS data channel over TLS. 2857 There are known attacks on (D)TLS, such as man-in-the-middle and 2858 protocol downgrade attacks. These are general attacks on (D)TLS and, 2859 as such, they are not specific to DOTS over (D)TLS; refer to the 2860 (D)TLS RFCs for discussion of these security issues. DOTS agents 2861 MUST adhere to the (D)TLS implementation recommendations and security 2862 considerations of [RFC7525] except with respect to (D)TLS version. 2863 Since DOTS signal channel encryption relies upon (D)TLS is virtually 2864 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 2865 or later. 2867 When a DOTS client is configured with a domain name of the DOTS 2868 server, and connects to its configured DOTS server, the server may 2869 present it with a PKIX certificate. In order to ensure proper 2870 authentication, a DOTS client MUST verify the entire certification 2871 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 2872 validation techniques to compare the domain name with the certificate 2873 provided. 2875 A key challenge to deploying DOTS is the provisioning of DOTS 2876 clients, including the distribution of keying material to DOTS 2877 clients to enable the required mutual authentication of DOTS agents. 2878 EST defines a method of certificate enrollment by which domains 2879 operating DOTS servers may provide DOTS clients with all the 2880 necessary cryptographic keying material, including a private key and 2881 a certificate to authenticate themselves. One deployment option is 2882 DOTS clients behave as EST clients for certificate enrollment from an 2883 EST server provisioned by the mitigation provider. This document 2884 does not specify which EST mechanism the DOTS client uses to achieve 2885 initial enrollment. 2887 Implementations compliant with this profile MUST implement all of the 2888 following items: 2890 o DTLS record replay detection (Section 3.3 of [RFC6347]) to protect 2891 against replay attacks. 2893 o (D)TLS session resumption without server-side state [RFC5077] to 2894 resume session and convey the DOTS signal. 2896 o Raw public keys [RFC7250] or PSK handshake [RFC4279] which reduces 2897 the size of the ServerHello, and can be used by DOTS agents that 2898 cannot obtain certificates. 2900 Implementations compliant with this profile SHOULD implement all of 2901 the following items to reduce the delay required to deliver a DOTS 2902 signal channel message: 2904 o TLS False Start [RFC7918] which reduces round-trips by allowing 2905 the TLS second flight of messages (ChangeCipherSpec) to also 2906 contain the DOTS signal. 2908 o Cached Information Extension [RFC7924] which avoids transmitting 2909 the server's certificate and certificate chain if the client has 2910 cached that information from a previous TLS handshake. 2912 o TCP Fast Open [RFC7413] can reduce the number of round-trips to 2913 convey DOTS signal channel message. 2915 7.2. (D)TLS 1.3 Considerations 2917 TLS 1.3 [I-D.ietf-tls-tls13] provides critical latency improvements 2918 for connection establishment over TLS 1.2. The DTLS 1.3 protocol 2919 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 2920 equivalent security guarantees. (D)TLS 1.3 provides two basic 2921 handshake modes the DOTS signal channel can take advantage of: 2923 o A full handshake mode in which a DOTS client can send a DOTS 2924 mitigation request message after one round trip and the DOTS 2925 server immediately responds with a DOTS mitigation response. This 2926 assumes no packet loss is experienced. 2928 o 0-RTT mode in which the DOTS client can authenticate itself and 2929 send DOTS mitigation request messages in the first message, thus 2930 reducing handshake latency. 0-RTT only works if the DOTS client 2931 has previously communicated with that DOTS server, which is very 2932 likely with the DOTS signal channel. 2934 The DOTS client has to establish a (D)TLS session with the DOTS 2935 server during peacetime and share a PSK. 2937 During a DDoS attack, the DOTS client can use the (D)TLS session 2938 to convey the DOTS mitigation request message and, if there is no 2939 response from the server after multiple retries, the DOTS client 2940 can resume the (D)TLS session in 0-RTT mode using PSK. 2942 Section 8 of [I-D.ietf-tls-tls13] discusses some mechanisms to 2943 implement to limit the impact of replay attacks on 0-RTT data. If 2944 TLS1.3 is used, DOTS servers must implement one of these 2945 mechanisms. 2947 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 2948 message exchange is shown in Figure 23. 2950 DOTS Client DOTS Server 2952 ClientHello 2953 (Finished) 2954 (0-RTT DOTS signal message) 2955 (end_of_early_data) --------> 2956 ServerHello 2957 {EncryptedExtensions} 2958 {ServerConfiguration} 2959 {Certificate} 2960 {CertificateVerify} 2961 {Finished} 2962 <-------- [DOTS signal message] 2963 {Finished} --------> 2965 [DOTS signal message] <-------> [DOTS signal message] 2967 Figure 23: TLS 1.3 handshake with 0-RTT 2969 7.3. MTU and Fragmentation 2971 To avoid DOTS signal message fragmentation and the subsequent 2972 decreased probability of message delivery, DOTS agents MUST ensure 2973 that the DTLS record MUST fit within a single datagram. If the path 2974 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 2975 be assumed. The length of the URL MUST NOT exceed 256 bytes. If UDP 2976 is used to convey the DOTS signal messages then the DOTS client must 2977 consider the amount of record expansion expected by the DTLS 2978 processing when calculating the size of CoAP message that fits within 2979 the path MTU. Path MTU MUST be greater than or equal to [CoAP 2980 message size + DTLS overhead of 13 octets + authentication overhead 2981 of the negotiated DTLS cipher suite + block padding (Section 4.1.1.1 2982 of [RFC6347]). If the request size exceeds the path MTU then the 2983 DOTS client MUST split the DOTS signal into separate messages, for 2984 example the list of addresses in the 'target-prefix' parameter could 2985 be split into multiple lists and each list conveyed in a new PUT 2986 request. 2988 Implementation Note: DOTS choice of message size parameters works 2989 well with IPv6 and with most of today's IPv4 paths. However, with 2990 IPv4, it is harder to reliably ensure that there is no IP 2991 fragmentation. If IPv4 path MTU is unknown, implementations may want 2992 to limit themselves to more conservative IPv4 datagram sizes such as 2993 576 bytes, as per [RFC0791]. IP packets whose size does not exceed 2994 576 bytes should never need to be fragmented: therefore, sending a 2995 maximum of 500 bytes of DOTS signal over a UDP datagram will 2996 generally avoid IP fragmentation. 2998 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3000 (D)TLS based upon client certificate can be used for mutual 3001 authentication between DOTS agents. If a DOTS gateway is involved, 3002 DOTS clients and DOTS gateways MUST perform mutual authentication; 3003 only authorized DOTS clients are allowed to send DOTS signals to a 3004 DOTS gateway. The DOTS gateway and the DOTS server MUST perform 3005 mutual authentication; a DOTS server only allows DOTS signal channel 3006 messages from an authorized DOTS gateway, thereby creating a two-link 3007 chain of transitive authentication between the DOTS client and the 3008 DOTS server. 3010 +-----------------------------------------------+ 3011 | example.com domain +---------+ | 3012 | | AAA | | 3013 | +---------------+ | Server | | 3014 | | Application | +------+--+ | 3015 | | server +<-----------------+ ^ | 3016 | | (DOTS client) | | | | 3017 | +---------------+ | | | 3018 | V V | example.net domain 3019 | +-----+----+--+ | +---------------+ 3020 | +--------------+ | | | | | 3021 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3022 | | (DOTS client)| | Gateway | | | Server | 3023 | +--------------+ | | | | | 3024 | +----+--------+ | +---------------+ 3025 | ^ | 3026 | | | 3027 | +----------------+ | | 3028 | | DDOS detector | | | 3029 | | (DOTS client) +<---------------+ | 3030 | +----------------+ | 3031 +-----------------------------------------------+ 3033 Figure 24: Example of Authentication and Authorization of DOTS Agents 3035 In the example depicted in Figure 24, the DOTS gateway and DOTS 3036 clients within the 'example.com' domain mutually authenticate with 3037 each other. After the DOTS gateway validates the identity of a DOTS 3038 client, it communicates with the AAA server in the 'example.com' 3039 domain to determine if the DOTS client is authorized to request DDoS 3040 mitigation. If the DOTS client is not authorized, a 4.01 3041 (Unauthorized) is returned in the response to the DOTS client. In 3042 this example, the DOTS gateway only allows the application server and 3043 DDoS attack detector to request DDOS mitigation, but does not permit 3044 the user of type 'guest' to request DDoS mitigation. 3046 Also, DOTS gateways and servers located in different domains MUST 3047 perform mutual authentication (e.g., using certificates). A DOTS 3048 server will only allow a DOTS gateway with a certificate for a 3049 particular domain to request mitigation for that domain. In 3050 reference to Figure 24, the DOTS server only allows the DOTS gateway 3051 to request mitigation for 'example.com' domain and not for other 3052 domains. 3054 9. IANA Considerations 3056 This specification registers a service port (Section 9.1), an URI 3057 suffix in the Well-Known URIs registry (Section 9.2), a CoAP response 3058 code (Section 9.3), a YANG module (Section 9.5). It also creates a 3059 registry for mappings to CBOR (Section 9.4). 3061 9.1. DOTS Signal Channel UDP and TCP Port Number 3063 IANA is requested to assign the port number TBD to the DOTS signal 3064 channel protocol for both UDP and TCP from the "Service Name and 3065 Transport Protocol Port Number Registry" available at 3066 https://www.iana.org/assignments/service-names-port-numbers/service- 3067 names-port-numbers.xhtml. 3069 The assignment of port number 4646 is strongly suggested, as 4646 is 3070 the ASCII decimal value for ".." (DOTS). 3072 9.2. Well-Known 'dots' URI 3074 This document requests IANA to register the 'dots' well-known URI in 3075 the Well-Known URIs registry (https://www.iana.org/assignments/well- 3076 known-uris/well-known-uris.xhtml) as defined by [RFC5785]. 3078 URI suffix: dots 3080 Change controller: IETF 3082 Specification document(s): This RFC 3084 Related information: None 3086 9.3. CoAP Response Code 3088 IANA is requested to add the following entry to the "CoAP Response 3089 Codes" sub-registry available at https://www.iana.org/assignments/ 3090 core-parameters/core-parameters.xhtml#response-codes: 3092 +------+------------------+-----------+ 3093 | Code | Description | Reference | 3094 +------+------------------+-----------+ 3095 | 3.00 | Alternate server | [RFCXXXX] | 3096 +------+------------------+-----------+ 3098 Table 4: CoAP Response Code 3100 9.4. DOTS Signal Channel CBOR Mappings Registry 3102 The document requests IANA to create a new registry, entitled "DOTS 3103 Signal Channel CBOR Mappings Registry". The structure of this 3104 registry is provided in Section 9.4.1. 3106 The registry is initially populated with the values in Section 9.4.2. 3108 Values from that registry MUST be assigned via Expert Review 3109 [RFC8126]. 3111 9.4.1. Registration Template 3113 Parameter name: 3114 Parameter name as used in the DOTS signal channel. 3116 CBOR Key Value: 3117 Key value for the parameter. The key value MUST be an integer in 3118 the 1-65536 range. The key values in the 32758-65536 range are 3119 assigned to Vendor-Specific parameters. 3121 CBOR Major Type: 3122 CBOR Major type and optional tag for the claim. 3124 Change Controller: 3125 For Standards Track RFCs, list the "IESG". For others, give the 3126 name of the responsible party. Other details (e.g., postal 3127 address, email address, home page URI) may also be included. 3129 Specification Document(s): 3130 Reference to the document or documents that specify the parameter, 3131 preferably including URIs that can be used to retrieve copies of 3132 the documents. An indication of the relevant sections may also be 3133 included but is not required. 3135 9.4.2. Initial Registry Contents 3137 o Parameter Name: mitigation-scope 3138 o CBOR Key Value: 1 3139 o CBOR Major Type: 5 3140 o Change Controller: IESG 3141 o Specification Document(s): this document 3143 o Parameter Name: scope 3144 o CBOR Key Value: 2 3145 o CBOR Major Type: 5 3146 o Change Controller: IESG 3147 o Specification Document(s): this document 3148 o Parameter Name: mitigation-id 3149 o CBOR Key Value: 3 3150 o CBOR Major Type: 0 3151 o Change Controller: IESG 3152 o Specification Document(s): this document 3154 o Parameter Name: acl-list 3155 o CBOR Key Value: 4 3156 o CBOR Major Type: 4 3157 o Change Controller: IESG 3158 o Specification Document(s): this document 3160 o Parameter Name: target-port-range 3161 o CBOR Key Value: 5 3162 o CBOR Major Type: 4 3163 o Change Controller: IESG 3164 o Specification Document(s): this document 3166 o Parameter Name: lower-port 3167 o CBOR Key Value: 6 3168 o CBOR Major Type: 0 3169 o Change Controller: IESG 3170 o Specification Document(s): this document 3172 o Parameter Name: upper-port 3173 o CBOR Key Value: 7 3174 o CBOR Major Type: 0 3175 o Change Controller: IESG 3176 o Specification Document(s): this document 3178 o Parameter Name: target-protocol 3179 o CBOR Key Value: 8 3180 o CBOR Major Type: 4 3181 o Change Controller: IESG 3182 o Specification Document(s): this document 3184 o Parameter Name: target-fqdn 3185 o CBOR Key Value: 9 3186 o CBOR Major Type: 4 3187 o Change Controller: IESG 3188 o Specification Document(s): this document 3190 o Parameter Name: target-uri 3191 o CBOR Key Value: 10 3192 o CBOR Major Type: 4 3193 o Change Controller: IESG 3194 o Specification Document(s): this document 3195 o Parameter Name: alias-name 3196 o CBOR Key Value: 11 3197 o CBOR Major Type: 4 3198 o Change Controller: IESG 3199 o Specification Document(s): this document 3201 o Parameter Name: lifetime 3202 o CBOR Key Value: 12 3203 o CBOR Major Type: 0 3204 o Change Controller: IESG 3205 o Specification Document(s): this document 3207 o Parameter Name: attack-status 3208 o CBOR Key Value: 13 3209 o CBOR Major Type: 0 3210 o Change Controller: IESG 3211 o Specification Document(s): this document 3213 o Parameter Name: signal-config 3214 o CBOR Key Value: 14 3215 o CBOR Major Type: 5 3216 o Change Controller: IESG 3217 o Specification Document(s): this document 3219 o Parameter Name: heartbeat-interval 3220 o CBOR Key Value: 15 3221 o CBOR Major Type: 5 3222 o Change Controller: IESG 3223 o Specification Document(s): this document 3225 o Parameter Name: max-retransmit 3226 o CBOR Key Value: 16 3227 o CBOR Major Type: 5 3228 o Change Controller: IESG 3229 o Specification Document(s): this document 3231 o Parameter Name: ack-timeout 3232 o CBOR Key Value: 17 3233 o CBOR Major Type: 5 3234 o Change Controller: IESG 3235 o Specification Document(s): this document 3237 o Parameter Name: ack-random-factor 3238 o CBOR Key Value: 18 3239 o CBOR Major Type: 5 3240 o Change Controller: IESG 3241 o Specification Document(s): this document 3242 o Parameter Name: min-value 3243 o CBOR Key Value: 19 3244 o CBOR Major Type: 0 3245 o Change Controller: IESG 3246 o Specification Document(s): this document 3248 o Parameter Name: max-value 3249 o CBOR Key Value: 20 3250 o CBOR Major Type: 0 3251 o Change Controller: IESG 3252 o Specification Document(s): this document 3254 o Parameter Name: status 3255 o CBOR Key Value: 21 3256 o CBOR Major Type: 0 3257 o Change Controller: IESG 3258 o Specification Document(s): this document 3260 o Parameter Name: conflict-information 3261 o CBOR Key Value: 22 3262 o CBOR Major Type: 5 3263 o Change Controller: IESG 3264 o Specification Document(s): this document 3266 o Parameter Name: conflict-status 3267 o CBOR Key Value: 23 3268 o CBOR Major Type: 0 3269 o Change Controller: IESG 3270 o Specification Document(s): this document 3272 o Parameter Name: conflict-cause 3273 o CBOR Key Value: 24 3274 o CBOR Major Type: 0 3275 o Change Controller: IESG 3276 o Specification Document(s): this document 3278 o Parameter Name: retry-timer 3279 o CBOR Key Value: 25 3280 o CBOR Major Type: 0 3281 o Change Controller: IESG 3282 o Specification Document(s): this document 3284 o Parameter Name: bytes-dropped 3285 o CBOR Key Value: 26 3286 o CBOR Major Type: 0 3287 o Change Controller: IESG 3288 o Specification Document(s): this document 3289 o Parameter Name: bps-dropped 3290 o CBOR Key Value: 27 3291 o CBOR Major Type: 0 3292 o Change Controller: IESG 3293 o Specification Document(s): this document 3295 o Parameter Name: pkts-dropped 3296 o CBOR Key Value: 28 3297 o CBOR Major Type: 0 3298 o Change Controller: IESG 3299 o Specification Document(s): this document 3301 o Parameter Name: pps-dropped 3302 o CBOR Key Value: 29 3303 o CBOR Major Type: 0 3304 o Change Controller: IESG 3305 o Specification Document(s): this document 3307 o Parameter Name: session-id 3308 o CBOR Key Value: 30 3309 o CBOR Major Type: 0 3310 o Change Controller: IESG 3311 o Specification Document(s): this document 3313 o Parameter Name: trigger-mitigation 3314 o CBOR Key Value: 31 3315 o CBOR Major Type: 7 3316 o Change Controller: IESG 3317 o Specification Document(s): this document 3319 o Parameter Name: missing-hb-allowed 3320 o CBOR Key Value: 32 3321 o CBOR Major Type: 5 3322 o Change Controller: IESG 3323 o Specification Document(s): this document 3325 o Parameter Name: current-value 3326 o CBOR Key Value: 33 3327 o CBOR Major Type: 0 3328 o Change Controller: IESG 3329 o Specification Document(s): this document 3331 o Parameter Name: mitigation-start 3332 o CBOR Key Value: 34 3333 o CBOR Major Type: 7 3334 o Change Controller: IESG 3335 o Specification Document(s): this document 3336 o Parameter Name: target-prefix 3337 o CBOR Key Value: 35 3338 o CBOR Major Type: 4 3339 o Change Controller: IESG 3340 o Specification Document(s): this document 3342 o Parameter Name: client-identifier 3343 o CBOR Key Value: 36 3344 o CBOR Major Type: 2 3345 o Change Controller: IESG 3346 o Specification Document(s): this document 3348 o Parameter Name: alt-server 3349 o CBOR Key Value: 37 3350 o CBOR Major Type: 2 3351 o Change Controller: IESG 3352 o Specification Document(s): this document 3354 o Parameter Name: alt-server-record 3355 o CBOR Key Value: 38 3356 o CBOR Major Type: 4 3357 o Change Controller: IESG 3358 o Specification Document(s): this document 3360 o Parameter Name: addr 3361 o CBOR Key Value: 39 3362 o CBOR Major Type: 2 3363 o Change Controller: IESG 3364 o Specification Document(s): this document 3366 o Parameter Name: ttl 3367 o CBOR Key Value: 40 3368 o CBOR Major Type: 0 3369 o Change Controller: IESG 3370 o Specification Document(s): this document 3372 o Parameter Name: conflict-scope 3373 o CBOR Key Value: 41 3374 o CBOR Major Type: 5 3375 o Change Controller: IESG 3376 o Specification Document(s): this document 3378 o Parameter Name: acl-name 3379 o CBOR Key Value: 42 3380 o CBOR Major Type: 3 3381 o Change Controller: IESG 3382 o Specification Document(s): this document 3383 o Parameter Name: acl-type 3384 o CBOR Key Value: 43 3385 o CBOR Major Type: 3 3386 o Change Controller: IESG 3387 o Specification Document(s): this document 3389 o Parameter Name: config-interval 3390 o CBOR Key Value: 44 3391 o CBOR Major Type: 0 3392 o Change Controller: IESG 3393 o Specification Document(s): this document 3395 o Parameter Name: attack-time-config 3396 o CBOR Key Value: 45 3397 o CBOR Major Type: 5 3398 o Change Controller: IESG 3399 o Specification Document(s): this document 3401 o Parameter Name: peace-time-config 3402 o CBOR Key Value: 46 3403 o CBOR Major Type: 5 3404 o Change Controller: IESG 3405 o Specification Document(s): this document 3407 9.5. DOTS Signal Channel YANG Module 3409 This document requests IANA to register the following URI in the 3410 "IETF XML Registry" [RFC3688]: 3412 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal 3413 Registrant Contact: The IESG. 3414 XML: N/A; the requested URI is an XML namespace. 3416 This document requests IANA to register the following YANG module in 3417 the "YANG Module Names" registry [RFC7950]. 3419 name: ietf-signal 3420 namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal 3421 prefix: signal 3422 reference: RFC XXXX 3424 10. Implementation Status 3426 [Note to RFC Editor: Please remove this section and reference to 3427 [RFC7942] prior to publication.] 3429 This section records the status of known implementations of the 3430 protocol defined by this specification at the time of posting this 3431 Internet-Draft, and is based upon a proposal described in [RFC7942]. 3432 The description of implementations in this section is intended to 3433 assist the IETF in its decision-making process when progressing 3434 drafts to RFCs. Please note that the listing of any individual 3435 implementation here does not imply endorsement by the IETF. 3436 Furthermore, no effort has been spent to verify the information 3437 presented here, and which was provided by individuals. This is not 3438 intended as, and must not be construed to be, a catalog of available 3439 implementations or features. Readers are advised to note that other 3440 implementations may exist. 3442 According to [RFC7942], "this will allow reviewers and working groups 3443 to assign due consideration to documents that have the benefit of 3444 running code, which may serve as evidence of valuable experimentation 3445 and feedback that have made the implemented protocols more mature. 3446 It is up to the individual working groups to use this information as 3447 they see fit". 3449 10.1. nttdots 3451 Organization: NTT Communication is developing a DOTS client and 3452 DOTS server software based on DOTS signal channel specified in 3453 this draft. It will be open-sourced. 3454 Description: Early implementation of DOTS protocol. It is aimed to 3455 implement a full DOTS protocol specification in accordance with 3456 the nurturing DOTS protocol. 3457 Implementation: https://github.com/nttdots/go-dots 3458 Level of maturity: It is an early implementation of the DOTS 3459 protocol. Messaging between DOTS clients and DOTS servers has 3460 been tested. Level of maturity will increase in accordance with 3461 the nurturing DOTS protocol. 3462 Coverage: Capability of DOTS client: sending DOTS messages to the 3463 DOTS server in CoAP over DTLS as dots-signal. Capability of DOTS 3464 server: receiving dots-signal, validating received dots-signal, 3465 starting mitigation by handing over the dots-signal to DDOS 3466 mitigator. 3467 Licensing: It will be open-sourced with BSD 3-clause license. 3468 Implementation experience: It is implemented in Go-lang. Core 3469 specification of signaling is mature to be implemented, however, 3470 finding good libraries(like DTLS, CoAP) is rather difficult. 3471 Contact: Kaname Nishizuka 3473 11. Security Considerations 3475 Authenticated encryption MUST be used for data confidentiality and 3476 message integrity. The interaction between the DOTS agents requires 3477 Datagram Transport Layer Security (DTLS) and Transport Layer Security 3478 (TLS) with a cipher suite offering confidentiality protection and the 3479 guidance given in [RFC7525] MUST be followed to avoid attacks on 3480 (D)TLS. The (D)TLS protocol profile for DOTS signal channel is 3481 specified in Section 7. 3483 A single DOTS signal channel between DOTS agents can be used to 3484 exchange multiple DOTS signal messages. To reduce DOTS client and 3485 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 3487 If TCP is used between DOTS agents, an attacker may be able to inject 3488 RST packets, bogus application segments, etc., regardless of whether 3489 TLS authentication is used. Because the application data is TLS 3490 protected, this will not result in the application receiving bogus 3491 data, but it will constitute a DoS on the connection. This attack 3492 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 3493 any bogus packets injected by an attacker will be rejected by the 3494 TCP-AO integrity check and therefore will never reach the TLS layer. 3496 In order to prevent leaking internal information outside a client- 3497 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 3498 the identification information that pertains to internal DOTS clients 3499 (client-identifier) unless explicitly configured to do so. 3501 Special care should be taken in order to ensure that the activation 3502 of the proposed mechanism will not impact the stability of the 3503 network (including connectivity and services delivered over that 3504 network). 3506 12. Contributors 3508 The following individuals have contributed to this document: 3510 Mike Geller Cisco Systems, Inc. 3250 Florida 33309 USA Email: 3511 mgeller@cisco.com 3513 Robert Moskowitz HTT Consulting Oak Park, MI 42837 United States 3514 Email: rgm@htt-consult.com 3516 Dan Wing Email: dwing-ietf@fuggles.com 3518 13. Acknowledgements 3520 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 3521 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 3522 Xia, Gilbert Clark, and Nesredien Suleiman for the discussion and 3523 comments. 3525 Special thanks to Jon Shallow for the careful reviews and inputs that 3526 enhanced this specification. 3528 14. References 3530 14.1. Normative References 3532 [I-D.ietf-core-coap-tcp-tls] 3533 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 3534 Silverajan, B., and B. Raymor, "CoAP (Constrained 3535 Application Protocol) over TCP, TLS, and WebSockets", 3536 draft-ietf-core-coap-tcp-tls-10 (work in progress), 3537 October 2017. 3539 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3540 Requirement Levels", BCP 14, RFC 2119, 3541 DOI 10.17487/RFC2119, March 1997, 3542 . 3544 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3545 DOI 10.17487/RFC3688, January 2004, 3546 . 3548 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 3549 Ciphersuites for Transport Layer Security (TLS)", 3550 RFC 4279, DOI 10.17487/RFC4279, December 2005, 3551 . 3553 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3554 (TLS) Protocol Version 1.2", RFC 5246, 3555 DOI 10.17487/RFC5246, August 2008, 3556 . 3558 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 3559 Housley, R., and W. Polk, "Internet X.509 Public Key 3560 Infrastructure Certificate and Certificate Revocation List 3561 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 3562 . 3564 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 3565 Uniform Resource Identifiers (URIs)", RFC 5785, 3566 DOI 10.17487/RFC5785, April 2010, 3567 . 3569 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 3570 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 3571 June 2010, . 3573 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 3574 Verification of Domain-Based Application Service Identity 3575 within Internet Public Key Infrastructure Using X.509 3576 (PKIX) Certificates in the Context of Transport Layer 3577 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 3578 2011, . 3580 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 3581 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 3582 DOI 10.17487/RFC6234, May 2011, 3583 . 3585 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 3586 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 3587 January 2012, . 3589 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 3590 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 3591 Transport Layer Security (TLS) and Datagram Transport 3592 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 3593 June 2014, . 3595 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 3596 Application Protocol (CoAP)", RFC 7252, 3597 DOI 10.17487/RFC7252, June 2014, 3598 . 3600 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 3601 "Recommendations for Secure Use of Transport Layer 3602 Security (TLS) and Datagram Transport Layer Security 3603 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 3604 2015, . 3606 [RFC7641] Hartke, K., "Observing Resources in the Constrained 3607 Application Protocol (CoAP)", RFC 7641, 3608 DOI 10.17487/RFC7641, September 2015, 3609 . 3611 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 3612 RFC 7950, DOI 10.17487/RFC7950, August 2016, 3613 . 3615 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 3616 Writing an IANA Considerations Section in RFCs", BCP 26, 3617 RFC 8126, DOI 10.17487/RFC8126, June 2017, 3618 . 3620 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 3621 FETCH Methods for the Constrained Application Protocol 3622 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 3623 . 3625 14.2. Informative References 3627 [I-D.ietf-core-comi] 3628 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 3629 Management Interface", draft-ietf-core-comi-02 (work in 3630 progress), December 2017. 3632 [I-D.ietf-core-yang-cbor] 3633 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 3634 Minaburo, "CBOR Encoding of Data Modeled with YANG", 3635 draft-ietf-core-yang-cbor-05 (work in progress), August 3636 2017. 3638 [I-D.ietf-dots-architecture] 3639 Mortensen, A., Andreasen, F., Reddy, T., 3640 christopher_gray3@cable.comcast.com, c., Compton, R., and 3641 N. Teague, "Distributed-Denial-of-Service Open Threat 3642 Signaling (DOTS) Architecture", draft-ietf-dots- 3643 architecture-05 (work in progress), October 2017. 3645 [I-D.ietf-dots-data-channel] 3646 Reddy, T., Boucadair, M., Nishizuka, K., Xia, L., Patil, 3647 P., Mortensen, A., and N. Teague, "Distributed Denial-of- 3648 Service Open Threat Signaling (DOTS) Data Channel", draft- 3649 ietf-dots-data-channel-10 (work in progress), December 3650 2017. 3652 [I-D.ietf-dots-requirements] 3653 Mortensen, A., Moskowitz, R., and T. Reddy, "Distributed 3654 Denial of Service (DDoS) Open Threat Signaling 3655 Requirements", draft-ietf-dots-requirements-08 (work in 3656 progress), December 2017. 3658 [I-D.ietf-dots-use-cases] 3659 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 3660 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 3661 Open Threat Signaling", draft-ietf-dots-use-cases-09 (work 3662 in progress), November 2017. 3664 [I-D.ietf-netmod-yang-tree-diagrams] 3665 Bjorklund, M. and L. Berger, "YANG Tree Diagrams", draft- 3666 ietf-netmod-yang-tree-diagrams-02 (work in progress), 3667 October 2017. 3669 [I-D.ietf-tls-dtls13] 3670 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 3671 Datagram Transport Layer Security (DTLS) Protocol Version 3672 1.3", draft-ietf-tls-dtls13-22 (work in progress), 3673 November 2017. 3675 [I-D.ietf-tls-tls13] 3676 Rescorla, E., "The Transport Layer Security (TLS) Protocol 3677 Version 1.3", draft-ietf-tls-tls13-22 (work in progress), 3678 November 2017. 3680 [proto_numbers] 3681 "IANA, "Protocol Numbers"", 2011, 3682 . 3684 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 3685 DOI 10.17487/RFC0791, September 1981, 3686 . 3688 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 3689 Address Translator (Traditional NAT)", RFC 3022, 3690 DOI 10.17487/RFC3022, January 2001, 3691 . 3693 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 3694 Resource Identifier (URI): Generic Syntax", STD 66, 3695 RFC 3986, DOI 10.17487/RFC3986, January 2005, 3696 . 3698 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 3699 Congestion Control Protocol (DCCP)", RFC 4340, 3700 DOI 10.17487/RFC4340, March 2006, 3701 . 3703 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 3704 (CIDR): The Internet Address Assignment and Aggregation 3705 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 3706 2006, . 3708 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 3709 Denial-of-Service Considerations", RFC 4732, 3710 DOI 10.17487/RFC4732, December 2006, 3711 . 3713 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 3714 Translation (NAT) Behavioral Requirements for Unicast 3715 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 3716 2007, . 3718 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 3719 RFC 4960, DOI 10.17487/RFC4960, September 2007, 3720 . 3722 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 3723 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 3724 . 3726 [RFC5077] Salowey, J., Zhou, H., Eronen, P., and H. Tschofenig, 3727 "Transport Layer Security (TLS) Session Resumption without 3728 Server-Side State", RFC 5077, DOI 10.17487/RFC5077, 3729 January 2008, . 3731 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 3732 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 3733 DOI 10.17487/RFC5389, October 2008, 3734 . 3736 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 3737 NAT64: Network Address and Protocol Translation from IPv6 3738 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 3739 April 2011, . 3741 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 3742 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 3743 . 3745 [RFC6555] Wing, D. and A. Yourtchenko, "Happy Eyeballs: Success with 3746 Dual-Stack Hosts", RFC 6555, DOI 10.17487/RFC6555, April 3747 2012, . 3749 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 3750 "Default Address Selection for Internet Protocol Version 6 3751 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 3752 . 3754 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 3755 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 3756 DOI 10.17487/RFC6887, April 2013, 3757 . 3759 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 3760 A., and H. Ashida, "Common Requirements for Carrier-Grade 3761 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 3762 April 2013, . 3764 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 3765 "Enrollment over Secure Transport", RFC 7030, 3766 DOI 10.17487/RFC7030, October 2013, 3767 . 3769 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 3770 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 3771 October 2013, . 3773 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 3774 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 3775 . 3777 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 3778 "Architectural Considerations in Smart Object Networking", 3779 RFC 7452, DOI 10.17487/RFC7452, March 2015, 3780 . 3782 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 3783 NETCONF Protocol over Transport Layer Security (TLS) with 3784 Mutual X.509 Authentication", RFC 7589, 3785 DOI 10.17487/RFC7589, June 2015, 3786 . 3788 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 3789 Layer Security (TLS) False Start", RFC 7918, 3790 DOI 10.17487/RFC7918, August 2016, 3791 . 3793 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 3794 (TLS) Cached Information Extension", RFC 7924, 3795 DOI 10.17487/RFC7924, July 2016, 3796 . 3798 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 3799 Code: The Implementation Status Section", BCP 205, 3800 RFC 7942, DOI 10.17487/RFC7942, July 2016, 3801 . 3803 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 3804 RFC 7951, DOI 10.17487/RFC7951, August 2016, 3805 . 3807 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 3808 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 3809 March 2017, . 3811 Authors' Addresses 3813 Tirumaleswar Reddy 3814 McAfee, Inc. 3815 Embassy Golf Link Business Park 3816 Bangalore, Karnataka 560071 3817 India 3819 Email: kondtir@gmail.com 3821 Mohamed Boucadair 3822 Orange 3823 Rennes 35000 3824 France 3826 Email: mohamed.boucadair@orange.com 3828 Prashanth Patil 3829 Cisco Systems, Inc. 3831 Email: praspati@cisco.com 3833 Andrew Mortensen 3834 Arbor Networks, Inc. 3835 2727 S. State St 3836 Ann Arbor, MI 48104 3837 United States 3839 Email: amortensen@arbor.net 3841 Nik Teague 3842 Verisign, Inc. 3843 United States 3845 Email: nteague@verisign.com