idnits 2.17.1 draft-ietf-dots-signal-channel-41.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 : ---------------------------------------------------------------------------- ** 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 2701 has weird spacing: '...er-port ine...' -- The document date (January 6, 2020) is 1572 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 4395, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-08 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-11 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-14 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-02 == Outdated reference: A later version (-15) exists of draft-ietf-dots-server-discovery-06 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-20 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-34 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) Summary: 7 errors (**), 0 flaws (~~), 10 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy, Ed. 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair, Ed. 5 Expires: July 9, 2020 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Iron Mountain Data Centers 12 January 6, 2020 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-41 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 within the document with the RFC 32 number to be assigned to 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 Specification"; 39 o "| [RFCXXXX] |" 41 o reference: RFC XXXX 43 Please update this statement with the RFC number to be assigned to 44 the following documents: 46 o "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 47 (DOTS) Data Channel Specification (used to be I-D.ietf-dots-data- 48 channel) 50 Please update TBD/TBD1/TBD2 statements with the assignments made by 51 IANA to DOTS Signal Channel Protocol. 53 Also, please update the "revision" date of the YANG modules. 55 Status of This Memo 57 This Internet-Draft is submitted in full conformance with the 58 provisions of BCP 78 and BCP 79. 60 Internet-Drafts are working documents of the Internet Engineering 61 Task Force (IETF). Note that other groups may also distribute 62 working documents as Internet-Drafts. The list of current Internet- 63 Drafts is at https://datatracker.ietf.org/drafts/current/. 65 Internet-Drafts are draft documents valid for a maximum of six months 66 and may be updated, replaced, or obsoleted by other documents at any 67 time. It is inappropriate to use Internet-Drafts as reference 68 material or to cite them other than as "work in progress." 70 This Internet-Draft will expire on July 9, 2020. 72 Copyright Notice 74 Copyright (c) 2020 IETF Trust and the persons identified as the 75 document authors. All rights reserved. 77 This document is subject to BCP 78 and the IETF Trust's Legal 78 Provisions Relating to IETF Documents 79 (https://trustee.ietf.org/license-info) in effect on the date of 80 publication of this document. Please review these documents 81 carefully, as they describe your rights and restrictions with respect 82 to this document. Code Components extracted from this document must 83 include Simplified BSD License text as described in Section 4.e of 84 the Trust Legal Provisions and are provided without warranty as 85 described in the Simplified BSD License. 87 Table of Contents 89 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 90 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 91 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 92 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 10 93 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 10 94 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 10 95 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 10 96 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 12 97 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 13 98 4.4.2. Retrieve Information Related to a Mitigation . . . . 29 99 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 34 100 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 37 101 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 38 102 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 40 103 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 41 104 4.5.1. Discover Configuration Parameters . . . . . . . . . . 43 105 4.5.2. Convey DOTS Signal Channel Session Configuration . . 48 106 4.5.3. Configuration Freshness and Notifications . . . . . . 53 107 4.5.4. Delete DOTS Signal Channel Session Configuration . . 54 108 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 55 109 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 57 110 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 60 111 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 60 112 5.2. IANA DOTS Signal Channel YANG Module . . . . . . . . . . 62 113 5.3. IETF DOTS Signal Channel YANG Module . . . . . . . . . . 66 114 6. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 77 115 7. (D)TLS Protocol Profile and Performance Considerations . . . 79 116 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 79 117 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 81 118 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 83 119 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 120 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 121 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 86 122 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 86 123 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 86 124 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 86 125 9.4. CoAP Content-Formats Registration . . . . . . . . . . . . 87 126 9.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . . 87 127 9.6. DOTS Signal Channel Protocol Registry . . . . . . . . . . 88 128 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry . . 88 129 9.6.1.1. Registration Template . . . . . . . . . . . . . . 88 130 9.6.1.2. Initial Sub-Registry Content . . . . . . . . . . 89 131 9.6.2. Status Codes Sub-Registry . . . . . . . . . . . . . . 91 132 9.6.3. Conflict Status Codes Sub-Registry . . . . . . . . . 92 133 9.6.4. Conflict Cause Codes Sub-Registry . . . . . . . . . . 94 134 9.6.5. Attack Status Codes Sub-Registry . . . . . . . . . . 94 135 9.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 95 136 10. Security Considerations . . . . . . . . . . . . . . . . . . . 96 137 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 98 138 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 99 139 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 99 140 13.1. Normative References . . . . . . . . . . . . . . . . . . 99 141 13.2. Informative References . . . . . . . . . . . . . . . . . 102 142 Appendix A. CUID Generation . . . . . . . . . . . . . . . . . . 107 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 107 145 1. Introduction 147 A distributed denial-of-service (DDoS) attack is a distributed 148 attempt to make machines or network resources unavailable to their 149 intended users. In most cases, sufficient scale for an effective 150 attack can be achieved by compromising enough end-hosts and using 151 those infected hosts to perpetrate and amplify the attack. The 152 victim in this attack can be an application server, a host, a router, 153 a firewall, or an entire network. 155 Network applications have finite resources like CPU cycles, the 156 number of processes or threads they can create and use, the maximum 157 number of simultaneous connections they can handle, the limited 158 resources of the control plane, etc. When processing network 159 traffic, such applications are supposed to use these resources to 160 provide the intended functionality in the most efficient manner. 161 However, a DDoS attacker may be able to prevent an application from 162 performing its intended task by making the application exhaust its 163 finite resources. 165 A TCP DDoS SYN-flood [RFC4987], for example, is a memory-exhausting 166 attack while an ACK-flood is a CPU-exhausting attack. Attacks on the 167 link are carried out by sending enough traffic so that the link 168 becomes congested, thereby likely causing packet loss for legitimate 169 traffic. Stateful firewalls can also be attacked by sending traffic 170 that causes the firewall to maintain an excessive number of states 171 that may jeopardize the firewall's operation overall, besides likely 172 performance impacts. The firewall then runs out of memory, and can 173 no longer instantiate the states required to process legitimate 174 flows. Other possible DDoS attacks are discussed in [RFC4732]. 176 In many cases, it may not be possible for network administrators to 177 determine the cause(s) of an attack. They may instead just realize 178 that certain resources seem to be under attack. This document 179 defines a lightweight protocol that allows a DOTS client to request 180 mitigation from one or more DOTS servers for protection against 181 detected, suspected, or anticipated attacks. This protocol enables 182 cooperation between DOTS agents to permit a highly-automated network 183 defense that is robust, reliable, and secure. Note that "secure" 184 means the support of the features defined in Section 2.4 of 185 [RFC8612]. 187 An example of a network diagram that illustrates a deployment of DOTS 188 agents is shown in Figure 1. In this example, a DOTS server is 189 operating on the access network. A DOTS client is located on the LAN 190 (Local Area Network), while a DOTS gateway is embedded in the CPE 191 (Customer Premises Equipment). 193 Network 194 Resource CPE router Access network __________ 195 +-----------+ +--------------+ +-------------+ / \ 196 | |___| |____| |___ | Internet | 197 |DOTS client| | DOTS gateway | | DOTS server | | | 198 | | | | | | | | 199 +-----------+ +--------------+ +-------------+ \__________/ 201 Figure 1: Sample DOTS Deployment (1) 203 DOTS servers can also be reachable over the Internet, as depicted in 204 Figure 2. 206 Network DDoS mitigation 207 Resource CPE router __________ service 208 +-----------+ +-------------+ / \ +-------------+ 209 | |___| |____| |___ | | 210 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 211 | | | | | | | | 212 +-----------+ +-------------+ \__________/ +-------------+ 214 Figure 2: Sample DOTS Deployment (2) 216 In typical deployments, the DOTS client belongs to a different 217 administrative domain than the DOTS server. For example, the DOTS 218 client is embedded in a firewall protecting services owned and 219 operated by a customer, while the DOTS server is owned and operated 220 by a different administrative entity (service provider, typically) 221 providing DDoS mitigation services. The latter might or might not 222 provide connectivity services to the network hosting the DOTS client. 224 The DOTS server may (not) be co-located with the DOTS mitigator. In 225 typical deployments, the DOTS server belongs to the same 226 administrative domain as the mitigator. The DOTS client can 227 communicate directly with a DOTS server or indirectly via a DOTS 228 gateway. 230 The document adheres to the DOTS architecture 231 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 232 channel protocol are documented in [RFC8612]. This document 233 satisfies all the use cases discussed in [I-D.ietf-dots-use-cases]. 235 This document focuses on the DOTS signal channel. This is a 236 companion document of the DOTS data channel specification 237 [I-D.ietf-dots-data-channel] that defines a configuration and a bulk 238 data exchange mechanism supporting the DOTS signal channel. 240 2. Terminology 242 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 243 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 244 "OPTIONAL" in this document are to be interpreted as described in BCP 245 14 [RFC2119][RFC8174] when, and only when, they appear in all 246 capitals, as shown here. 248 (D)TLS is used for statements that apply to both Transport Layer 249 Security [RFC5246][RFC8446] and Datagram Transport Layer Security 250 [RFC6347]. Specific terms are used for any statement that applies to 251 either protocol alone. 253 The reader should be familiar with the terms defined in [RFC8612]. 255 The meaning of the symbols in YANG tree diagrams is defined in 256 [RFC8340]. 258 3. Design Overview 260 The DOTS signal channel is built on top of the Constrained 261 Application Protocol (CoAP) [RFC7252], a lightweight protocol 262 originally designed for constrained devices and networks. The many 263 features of CoAP (expectation of packet loss, support for 264 asynchronous Non-confirmable messaging, congestion control, small 265 message overhead limiting the need for fragmentation, use of minimal 266 resources, and support for (D)TLS) makes it a good candidate to build 267 the DOTS signaling mechanism from. 269 DOTS clients and servers behave as CoAP endpoints. By default, a 270 DOTS client (or server) behaves as a CoAP client (or server). 271 Nevertheless, a DOTS client (or server) behaves as a CoAP server (or 272 client) for specific operations such as DOTS heartbeat operations 273 (Section 4.7). 275 The DOTS signal channel is layered on existing standards (Figure 3). 277 +---------------------+ 278 | DOTS Signal Channel | 279 +---------------------+ 280 | CoAP | 281 +----------+----------+ 282 | TLS | DTLS | 283 +----------+----------+ 284 | TCP | UDP | 285 +----------+----------+ 286 | IP | 287 +---------------------+ 289 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 290 (D)TLS 292 In some cases, a DOTS client and server may have mutual agreement to 293 use a specific port number, such as by explicit configuration or 294 dynamic discovery [I-D.ietf-dots-server-discovery]. Absent such 295 mutual agreement, the DOTS signal channel MUST run over port number 296 TBD as defined in Section 9.1, for both UDP and TCP. In order to use 297 a distinct port number (as opposed to TBD), DOTS clients and servers 298 SHOULD support a configurable parameter to supply the port number to 299 use. 301 Note: The rationale for not using the default port number 5684 302 ((D)TLS CoAP) is to avoid the discovery of services and resources 303 discussed in [RFC7252] and allow for differentiated behaviors in 304 environments where both a DOTS gateway and an IoT gateway (e.g., 305 Figure 3 of [RFC7452]) are co-located. 307 Particularly, the use of a default port number is meant to 308 simplify DOTS deployment in scenarios where no explicit IP address 309 configuration is required. For example, the use of the default 310 router as DOTS server aims to ease DOTS deployment within LANs (in 311 which, CPEs embed a DOTS gateway as illustrated in Figures 1 and 312 2) without requiring a sophisticated discovery method and 313 configuration tasks within the LAN. It is also possible to use 314 anycast addresses for DOTS servers to simplify DOTS client 315 configuration, including service discovery. In such anycast-based 316 scenario, a DOTS client initiating a DOTS session to the DOTS 317 server anycast address may, for example, be (1) redirected to the 318 DOTS server unicast address to be used by the DOTS client 319 following the procedure discussed in Section 4.6 or (2) relayed to 320 a unicast DOTS server. 322 The signal channel uses the "coaps" URI scheme defined in Section 6 323 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 324 [RFC8323] to identify DOTS server resources accessible using CoAP 325 over UDP secured with DTLS and CoAP over TCP secured with TLS, 326 respectively. 328 The DOTS signal channel can be established between two DOTS agents 329 prior or during an attack. The DOTS signal channel is initiated by 330 the DOTS client. The DOTS client can then negotiate, configure, and 331 retrieve the DOTS signal channel session behavior with its DOTS peer 332 (Section 4.5). Once the signal channel is established, the DOTS 333 agents may periodically send heartbeats to keep the channel active 334 (Section 4.7). At any time, the DOTS client may send a mitigation 335 request message (Section 4.4) to a DOTS server over the active signal 336 channel. While mitigation is active (because of the higher 337 likelihood of packet loss during a DDoS attack), the DOTS server 338 periodically sends status messages to the client, including basic 339 mitigation feedback details. Mitigation remains active until the 340 DOTS client explicitly terminates mitigation, or the mitigation 341 lifetime expires. Also, the DOTS server may rely on the signal 342 channel session loss to trigger mitigation for pre-configured 343 mitigation requests (if any). 345 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 346 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 347 capabilities. A Happy Eyeballs procedure for DOTS signal channel is 348 specified in Section 4.3. 350 A DOTS client is entitled to access only to resources it creates. In 351 particular, a DOTS client can not retrieve data related to mitigation 352 requests created by other DOTS clients of the same DOTS client 353 domain. 355 Messages exchanged between DOTS agents are serialized using Concise 356 Binary Object Representation (CBOR) [RFC7049], a binary encoding 357 scheme designed for small code and message size. CBOR-encoded 358 payloads are used to carry signal channel-specific payload messages 359 which convey request parameters and response information such as 360 errors. In order to allow reusing data models across protocols, 361 [RFC7951] specifies the JavaScript Object Notation (JSON) encoding of 362 YANG-modeled data. A similar effort for CBOR is defined in 363 [I-D.ietf-core-yang-cbor]. 365 DOTS agents determine that a CBOR data structure is a DOTS signal 366 channel object from the application context, such as from the port 367 number assigned to the DOTS signal channel. The other method DOTS 368 agents use to indicate that a CBOR data structure is a DOTS signal 369 channel object is the use of the "application/dots+cbor" content type 370 (Section 9.3). 372 This document specifies a YANG module for representing DOTS 373 mitigation scopes, DOTS signal channel session configuration data, 374 and DOTS redirected signaling (Section 5). All parameters in the 375 payload of the DOTS signal channel are mapped to CBOR types as 376 specified in Table 4 (Section 6). 378 In order to prevent fragmentation, DOTS agents must follow the 379 recommendations documented in Section 4.6 of [RFC7252]. Refer to 380 Section 7.3 for more details. 382 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 383 payload included in CoAP responses with 2.xx Response Codes MUST be 384 of content type "application/dots+cbor". CoAP responses with 4.xx 385 and 5.xx error Response Codes MUST include a diagnostic payload 386 (Section 5.5.2 of [RFC7252]). The Diagnostic Payload may contain 387 additional information to aid troubleshooting. 389 In deployments where multiple DOTS clients are enabled in a network 390 (owned and operated by the same entity), the DOTS server may detect 391 conflicting mitigation requests from these clients. This document 392 does not aim to specify a comprehensive list of conditions under 393 which a DOTS server will characterize two mitigation requests from 394 distinct DOTS clients as conflicting, nor recommend a DOTS server 395 behavior for processing conflicting mitigation requests. Those 396 considerations are implementation- and deployment-specific. 397 Nevertheless, the document specifies the mechanisms to notify DOTS 398 clients when conflicts occur, including the conflict cause 399 (Section 4.4). 401 In deployments where one or more translators (e.g., Traditional NAT 402 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 403 enabled between the client's network and the DOTS server, DOTS signal 404 channel messages forwarded to a DOTS server MUST NOT include internal 405 IP addresses/prefixes and/or port numbers; external addresses/ 406 prefixes and/or port numbers as assigned by the translator MUST be 407 used instead. This document does not make any recommendation about 408 possible translator discovery mechanisms. The following are some 409 (non-exhaustive) deployment examples that may be considered: 411 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 412 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 413 external addresses/prefixes and/or port numbers. Information 414 retrieved by means of PCP or STUN will be used to feed the DOTS 415 signal channel messages that will be sent to a DOTS server. 417 o A DOTS gateway may be co-located with the translator. The DOTS 418 gateway will need to update the DOTS messages, based upon the 419 local translator's binding table. 421 4. DOTS Signal Channel: Messages & Behaviors 423 4.1. DOTS Server(s) Discovery 425 This document assumes that DOTS clients are provisioned with the 426 reachability information of their DOTS server(s) using any of a 427 variety of means (e.g., local configuration, or dynamic means such as 428 DHCP [I-D.ietf-dots-server-discovery]). The description of such 429 means is out of scope of this document. 431 Likewise, it is out of scope of this document to specify the behavior 432 to be followed by a DOTS client to send DOTS requests when multiple 433 DOTS servers are provisioned (e.g., contact all DOTS servers, select 434 one DOTS server among the list). Such behavior is specified in other 435 documents (e.g., [I-D.ietf-dots-multihoming]). 437 4.2. CoAP URIs 439 The DOTS server MUST support the use of the path-prefix of "/.well- 440 known/" as defined in [RFC8615] and the registered name of "dots". 441 Each DOTS operation is indicated by a path-suffix that indicates the 442 intended operation. The operation path (Table 1) is appended to the 443 path-prefix to form the URI used with a CoAP request to perform the 444 desired DOTS operation. 446 +-----------------------+----------------+-------------+ 447 | Operation | Operation Path | Details | 448 +-----------------------+----------------+-------------+ 449 | Mitigation | /mitigate | Section 4.4 | 450 +-----------------------+----------------+-------------+ 451 | Session configuration | /config | Section 4.5 | 452 +-----------------------+----------------+-------------+ 453 | Heartbeat | /hb | Section 4.7 | 454 +-----------------------+----------------+-------------+ 456 Table 1: Operations and their Corresponding URIs 458 4.3. Happy Eyeballs for DOTS Signal Channel 460 [RFC8612] mentions that DOTS agents will have to support both 461 connectionless and connection-oriented protocols. As such, the DOTS 462 signal channel is designed to operate with DTLS over UDP and TLS over 463 TCP. Further, a DOTS client may acquire a list of IPv4 and IPv6 464 addresses (Section 4.1), each of which can be used to contact the 465 DOTS server using UDP and TCP. If no list of IPv4 and IPv6 addresses 466 to contact the DOTS server is configured (or discovered), the DOTS 467 client adds the IPv4/IPv6 addresses of its default router to the 468 candidate list to contact the DOTS server. 470 The following specifies the procedure to follow to select the address 471 family and the transport protocol for sending DOTS signal channel 472 messages. 474 Such procedure is needed to avoid experiencing long connection 475 delays. For example, if an IPv4 path to reach a DOTS server is 476 functional, but the DOTS server's IPv6 path is non-functional, a 477 dual-stack DOTS client may experience a significant connection delay 478 compared to an IPv4-only DOTS client, in the same network conditions. 479 The other problem is that if a middlebox between the DOTS client and 480 DOTS server is configured to block UDP traffic, the DOTS client will 481 fail to establish a DTLS association with the DOTS server and, as a 482 consequence, will have to fall back to TLS over TCP, thereby 483 incurring significant connection delays. 485 To overcome these connection setup problems, the DOTS client attempts 486 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 487 both DTLS over UDP and TLS over TCP following a DOTS Happy Eyeballs 488 approach. To some extent, this approach is similar to the Happy 489 Eyeballs mechanism defined in [RFC8305]. The connection attempts are 490 performed by the DOTS client when it initializes, or in general when 491 it has to select an address family and transport to contact its DOTS 492 server. The results of the Happy Eyeballs procedure are used by the 493 DOTS client for sending its subsequent messages to the DOTS server. 494 The difference in behavior with respect to the Happy Eyeballs 495 mechanism [RFC8305] are listed below: 497 o The order of preference of the DOTS signal channel address family 498 and transport protocol (most preferred first) is: UDP over IPv6, 499 UDP over IPv4, TCP over IPv6, and finally TCP over IPv4. This 500 order adheres to the address preference order specified in 501 [RFC6724] and the DOTS signal channel preference which privileges 502 the use of UDP over TCP (to avoid TCP's head of line blocking). 504 o The DOTS client after successfully establishing a connection MUST 505 cache information regarding the outcome of each connection attempt 506 for a specific time period, and it uses that information to avoid 507 thrashing the network with subsequent attempts. The cached 508 information is flushed when its age exceeds a specific time period 509 on the order of few minutes (e.g., 10 min). Typically, if the 510 DOTS client has to re-establish the connection with the same DOTS 511 server within few seconds after the Happy Eyeballs mechanism is 512 completed, caching avoids trashing the network especially in the 513 presence of DDoS attack traffic. 515 o If DOTS signal channel session is established with TLS (but DTLS 516 failed), the DOTS client periodically repeats the mechanism to 517 discover whether DOTS signal channel messages with DTLS over UDP 518 becomes available from the DOTS server, so the DOTS client can 519 migrate the DOTS signal channel from TCP to UDP. Such probing 520 SHOULD NOT be done more frequently than every 24 hours and MUST 521 NOT be done more frequently than every 5 minutes. 523 When connection attempts are made during an attack, the DOTS client 524 SHOULD use a "Connection Attempt Delay" [RFC8305] set to 100 ms. 526 In reference to Figure 4, the DOTS client proceeds with the 527 connection attempts following the rules in [RFC8305]. In this 528 example, it is assumed that the IPv6 path is broken and UDP traffic 529 is dropped by a middlebox but has little impact to the DOTS client 530 because there is no long delay before using IPv4 and TCP. 532 +-----------+ +-----------+ 533 |DOTS client| |DOTS server| 534 +-----------+ +-----------+ 535 | | 536 T0 |--DTLS ClientHello, IPv6 ---->X | 537 T1 |--DTLS ClientHello, IPv4 ---->X | 538 T2 |--TCP SYN, IPv6-------------->X | 539 T3 |--TCP SYN, IPv4--------------------------------------->| 540 |<-TCP SYNACK-------------------------------------------| 541 |--TCP ACK--------------------------------------------->| 542 |<------------Establish TLS Session-------------------->| 543 |----------------DOTS signal--------------------------->| 544 | | 546 Note: 547 * Retransmission messages are not shown. 548 * T1-T0=T2-T1=T3-T2= Connection Attempt Delay. 550 Figure 4: DOTS Happy Eyeballs (Sample Flow) 552 A single DOTS signal channel between DOTS agents can be used to 553 exchange multiple DOTS signal messages. To reduce DOTS client and 554 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 556 4.4. DOTS Mitigation Methods 558 The following methods are used by a DOTS client to request, withdraw, 559 or retrieve the status of mitigation requests: 561 PUT: DOTS clients use the PUT method to request mitigation from a 562 DOTS server (Section 4.4.1). During active mitigation, DOTS 563 clients may use PUT requests to carry mitigation efficacy 564 updates to the DOTS server (Section 4.4.3). 566 GET: DOTS clients may use the GET method to subscribe to DOTS 567 server status messages, or to retrieve the list of its 568 mitigations maintained by a DOTS server (Section 4.4.2). 570 DELETE: DOTS clients use the DELETE method to withdraw a request for 571 mitigation from a DOTS server (Section 4.4.4). 573 Mitigation request and response messages are marked as Non- 574 confirmable messages (Section 2.2 of [RFC7252]). 576 DOTS agents MUST NOT send more than one UDP datagram per round-trip 577 time (RTT) to the peer DOTS agent on average following the data 578 transmission guidelines discussed in Section 3.1.3 of [RFC8085]. 580 Requests marked by the DOTS client as Non-confirmable messages are 581 sent at regular intervals until a response is received from the DOTS 582 server. If the DOTS client cannot maintain an RTT estimate, it MUST 583 NOT send more than one Non-confirmable request every 3 seconds, and 584 SHOULD use an even less aggressive rate whenever possible (case 2 in 585 Section 3.1.3 of [RFC8085]). Mitigation requests MUST NOT be delayed 586 because of checks on probing rate (Section 4.7 of [RFC7252]). 588 JSON encoding of YANG modelled data [RFC7951] is used to illustrate 589 the various methods defined in the following sub-sections. Also, the 590 examples use the Labels defined in Sections 9.6.2, 9.6.3, 9.6.4, and 591 9.6.5. 593 4.4.1. Request Mitigation 595 When a DOTS client requires mitigation for some reason, the DOTS 596 client uses the CoAP PUT method to send a mitigation request to its 597 DOTS server(s) (Figures 5 and 6). 599 If a DOTS client is entitled to solicit the DOTS service, the DOTS 600 server enables mitigation on behalf of the DOTS client by 601 communicating the DOTS client's request to a mitigator (which may be 602 co-located with the DOTS server) and relaying the feedback of the 603 thus-selected mitigator to the requesting DOTS client. 605 Header: PUT (Code=0.03) 606 Uri-Path: ".well-known" 607 Uri-Path: "dots" 608 Uri-Path: "mitigate" 609 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 610 Uri-Path: "mid=123" 611 Content-Format: "application/dots+cbor" 613 { 614 ... 615 } 617 Figure 5: PUT to Convey DOTS Mitigation Requests 619 The order of the Uri-Path options is important as it defines the CoAP 620 resource. In particular, 'mid' MUST follow 'cuid'. 622 The additional Uri-Path parameters to those defined in Section 4.2 623 are as follows: 625 cuid: Stands for Client Unique Identifier. A globally unique 626 identifier that is meant to prevent collisions among DOTS 627 clients, especially those from the same domain. It MUST be 628 generated by DOTS clients. 630 For the reasons discussed in Appendix A, implementations SHOULD 631 set 'cuid' using the following procedure: first, the 632 Distinguished Encoding Rules (DER)-encoded Abstract Syntax 633 Notation One (ASN.1) representation of the Subject Public Key 634 Info (SPKI) of the DOTS client X.509 certificate [RFC5280], the 635 DOTS client raw public key [RFC7250], the "Pre-Shared Key (PSK) 636 identity" used by the DOTS client in the TLS 1.2 637 ClientKeyExchange message, or the "identity" used by the DOTS 638 client in the "pre_shared_key" TLS 1.3 extension is input to 639 the SHA-256 [RFC6234] cryptographic hash. Then, the output of 640 the cryptographic hash algorithm is truncated to 16 bytes; 641 truncation is done by stripping off the final 16 bytes. The 642 truncated output is base64url encoded (Section 5 of [RFC4648]) 643 with the trailing "=" removed from the encoding, and the 644 resulting value used as the 'cuid'. 646 The 'cuid' is intended to be stable when communicating with a 647 given DOTS server, i.e., the 'cuid' used by a DOTS client 648 SHOULD NOT change over time. Distinct 'cuid' values MAY be 649 used by a single DOTS client per DOTS server. 651 If a DOTS client has to change its 'cuid' for some reason, it 652 MUST NOT do so when mitigations are still active for the old 653 'cuid'. The 'cuid' SHOULD be 22 characters to avoid DOTS 654 signal message fragmentation over UDP. Furthermore, if that 655 DOTS client created aliases and filtering entries at the DOTS 656 server by means of the DOTS data channel, it MUST delete all 657 the entries bound to the old 'cuid' and re-install them using 658 the new 'cuid'. 660 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS 661 peer to notify that the 'cuid' is already in-use by another 662 DOTS client. Upon receipt of that error code, a new 'cuid' 663 MUST be generated by the DOTS peer (e.g., using [RFC4122]). 665 Client-domain DOTS gateways MUST handle 'cuid' collision 666 directly and it is RECOMMENDED that 'cuid' collision is handled 667 directly by server-domain DOTS gateways. 669 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 670 Triggers for such rewriting are out of scope. 672 This is a mandatory Uri-Path parameter. 674 mid: Identifier for the mitigation request represented with an 675 integer. This identifier MUST be unique for each mitigation 676 request bound to the DOTS client, i.e., the 'mid' parameter 677 value in the mitigation request needs to be unique (per 'cuid' 678 and DOTS server) relative to the 'mid' parameter values of 679 active mitigation requests conveyed from the DOTS client to the 680 DOTS server. 682 In order to handle out-of-order delivery of mitigation 683 requests, 'mid' values MUST increase monotonically. 685 If the 'mid' value has reached 3/4 of (2**32 - 1) (i.e., 686 3221225471) and no attack is detected, the DOTS client MUST 687 reset 'mid' to 0 to handle 'mid' rollover. If the DOTS client 688 maintains mitigation requests with pre-configured scopes, it 689 MUST re-create them with the 'mid' restarting at 0. 691 This identifier MUST be generated by the DOTS client. 693 This is a mandatory Uri-Path parameter. 695 'cuid' and 'mid' MUST NOT appear in the PUT request message body 696 (Figure 6). The schema in Figure 6 uses the types defined in 697 Section 6. Note that this figure (and other similar figures 698 depicting a schema) are non-normative sketches of the structure of 699 the message. 701 { 702 "ietf-dots-signal-channel:mitigation-scope": { 703 "scope": [ 704 { 705 "target-prefix": [ 706 "string" 707 ], 708 "target-port-range": [ 709 { 710 "lower-port": number, 711 "upper-port": number 712 } 713 ], 714 "target-protocol": [ 715 number 716 ], 717 "target-fqdn": [ 718 "string" 719 ], 720 "target-uri": [ 721 "string" 722 ], 723 "alias-name": [ 724 "string" 725 ], 726 "lifetime": number, 727 "trigger-mitigation": true|false 728 } 729 ] 730 } 731 } 733 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 734 Schema) 736 The parameters in the CBOR body (Figure 6) of the PUT request are 737 described below: 739 target-prefix: A list of prefixes identifying resources under 740 attack. Prefixes are represented using Classless Inter-Domain 741 Routing (CIDR) notation [RFC4632]. 742 As a reminder, the prefix length must be less than or equal to 32 743 (or 128) for IPv4 (or IPv6). 745 The prefix list MUST NOT include broadcast, loopback, or multicast 746 addresses. These addresses are considered as invalid values. In 747 addition, the DOTS server MUST validate that target prefixes are 748 within the scope of the DOTS client domain. Other validation 749 checks may be supported by DOTS servers. 751 This is an optional attribute. 753 target-port-range: A list of port numbers bound to resources under 754 attack. 756 A port range is defined by two bounds, a lower port number (lower- 757 port) and an upper port number (upper-port). When only 'lower- 758 port' is present, it represents a single port number. 760 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 761 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 762 [RFC4340], a range of ports can be, for example, 0-1023, 763 1024-65535, or 1024-49151. 765 This is an optional attribute. 767 target-protocol: A list of protocols involved in an attack. Values 768 are taken from the IANA protocol registry [proto_numbers]. 770 If 'target-protocol' is not specified, then the request applies to 771 any protocol. 773 This is an optional attribute. 775 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 776 identifying resources under attack [RFC8499]. 778 How a name is passed to an underlying name resolution library is 779 implementation- and deployment-specific. Nevertheless, once the 780 name is resolved into one or multiple IP addresses, DOTS servers 781 MUST apply the same validation checks as those for 'target- 782 prefix'. 784 The use of FQDNs may be suboptimal because: 786 * It induces both an extra load and increased delays on the DOTS 787 server to handle and manage DNS resolution requests. 789 * It does not guarantee that the DOTS server will resolve a name 790 to the same IP addresses that the DOTS client does. 792 This is an optional attribute. 794 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 795 identifying resources under attack. 797 The same validation checks used for 'target-fqdn' MUST be followed 798 by DOTS servers to validate a target URI. 800 This is an optional attribute. 802 alias-name: A list of aliases of resources for which the mitigation 803 is requested. Aliases can be created using the DOTS data channel 804 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 805 configuration, or other means. 807 An alias is used in subsequent signal channel exchanges to refer 808 more efficiently to the resources under attack. 810 This is an optional attribute. 812 lifetime: Lifetime of the mitigation request in seconds. The 813 RECOMMENDED lifetime of a mitigation request is 3600 seconds -- 814 this value was chosen to be long enough so that refreshing is not 815 typically a burden on the DOTS client, while still making the 816 request expire in a timely manner when the client has unexpectedly 817 quit. DOTS clients MUST include this parameter in their 818 mitigation requests. Upon the expiry of this lifetime, and if the 819 request is not refreshed, the mitigation request is removed. The 820 request can be refreshed by sending the same request again. 822 A lifetime of '0' in a mitigation request is an invalid value. 824 A lifetime of negative one (-1) indicates indefinite lifetime for 825 the mitigation request. The DOTS server MAY refuse indefinite 826 lifetime, for policy reasons; the granted lifetime value is 827 returned in the response. DOTS clients MUST be prepared to not be 828 granted mitigations with indefinite lifetimes. 830 The DOTS server MUST always indicate the actual lifetime in the 831 response and the remaining lifetime in status messages sent to the 832 DOTS client. 834 This is a mandatory attribute. 836 trigger-mitigation: If the parameter value is set to 'false', DDoS 837 mitigation will not be triggered for the mitigation request unless 838 the DOTS signal channel session is lost. 840 If the DOTS client ceases to respond to heartbeat messages, the 841 DOTS server can detect that the DOTS signal channel session is 842 lost. More details are discussed in Section 4.7. 844 The default value of the parameter is 'true' (that is, the 845 mitigation starts immediately). If 'trigger-mitigation' is not 846 present in a request, this is equivalent to receiving a request 847 with 'trigger-mitigation' set to 'true'. 849 This is an optional attribute. 851 In deployments where server-domain DOTS gateways are enabled, 852 identity information about the origin source client domain ('cdid') 853 SHOULD be propagated to the DOTS server. That information is meant 854 to assist the DOTS server to enforce some policies such as grouping 855 DOTS clients that belong to the same DOTS domain, limiting the number 856 of DOTS requests, and identifying the mitigation scope. These 857 policies can be enforced per-client, per-client domain, or both. 858 Also, the identity information may be used for auditing and debugging 859 purposes. 861 Figure 7 shows an example of a request relayed by a server-domain 862 DOTS gateway. 864 Header: PUT (Code=0.03) 865 Uri-Path: ".well-known" 866 Uri-Path: "dots" 867 Uri-Path: "mitigate" 868 Uri-Path: "cdid=7eeaf349529eb55ed50113" 869 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 870 Uri-Path: "mid=123" 871 Content-Format: "application/dots+cbor" 873 { 874 ... 875 } 877 Figure 7: PUT for DOTS Mitigation Request as Relayed by a DOTS 878 Gateway 880 A server-domain DOTS gateway SHOULD add the following Uri-Path 881 parameter: 883 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed by 884 a server-domain DOTS gateway to propagate the source domain 885 identity from the gateway's client-facing-side to the gateway's 886 server-facing-side, and from the gateway's server-facing-side 887 to the DOTS server. 'cdid' may be used by the final DOTS server 888 for policy enforcement purposes (e.g., enforce a quota on 889 filtering rules). These policies are deployment-specific. 891 Server-domain DOTS gateways SHOULD support a configuration 892 option to instruct whether 'cdid' parameter is to be inserted. 894 In order to accommodate deployments that require enforcing per- 895 client policies, per-client domain policies, or a combination 896 thereof, server-domain DOTS gateways instructed to insert the 897 'cdid' parameter MUST supply the SPKI hash of the DOTS client 898 X.509 certificate, the DOTS client raw public key, or the hash 899 of the "PSK identity" in the 'cdid', following the same rules 900 for generating the hash conveyed in 'cuid', which is then used 901 by the ultimate DOTS server to determine the corresponding 902 client's domain. The 'cdid' generated by a server-domain 903 gateway is likely to be the same as the 'cuid' except if the 904 DOTS message was relayed by a client-domain DOTS gateway or the 905 'cuid' was generated from a rogue DOTS client. 907 If a DOTS client is provisioned, for example, with distinct 908 certificates as a function of the peer server-domain DOTS 909 gateway, distinct 'cdid' values may be supplied by a server- 910 domain DOTS gateway. The ultimate DOTS server MUST treat those 911 'cdid' values as equivalent. 913 The 'cdid' attribute MUST NOT be generated and included by DOTS 914 clients. 916 DOTS servers MUST ignore 'cdid' attributes that are directly 917 supplied by source DOTS clients or client-domain DOTS gateways. 918 This implies that first server-domain DOTS gateways MUST strip 919 'cdid' attributes supplied by DOTS clients. DOTS servers 920 SHOULD support a configuration parameter to identify DOTS 921 gateways that are trusted to supply 'cdid' attributes. 923 Only single-valued 'cdid' are defined in this document. That 924 is, only the first on-path server-domain DOTS gateway can 925 insert a 'cdid' value. This specification does not allow 926 multiple server-domain DOTS gateways, whenever involved in the 927 path, to insert a 'cdid' value for each server-domain gateway. 929 This is an optional Uri-Path. When present, 'cdid' MUST be 930 positioned before 'cuid'. 932 A DOTS gateway SHOULD add the CoAP Hop-Limit Option 933 [I-D.ietf-core-hop-limit]. 935 Because of the complexity to handle partial failure cases, this 936 specification does not allow for including multiple mitigation 937 requests in the same PUT request. Concretely, a DOTS client MUST NOT 938 include multiple entries in the 'scope' array of the same PUT 939 request. 941 FQDN and URI mitigation scopes may be thought of as a form of scope 942 alias, in which the addresses associated with the domain name or URI 943 (as resolved by the DOTS server) represent the scope of the 944 mitigation. Particularly, the IP addresses to which the host 945 subcomponent of authority component of an URI resolves represent the 946 'target-prefix', the URI scheme represents the 'target-protocol', the 947 port subcomponent of authority component of an URI represents the 948 'target-port-range'. If the optional port information is not present 949 in the authority component, the default port defined for the URI 950 scheme represents the 'target-port'. 952 In the PUT request at least one of the attributes 'target-prefix', 953 'target-fqdn','target-uri', or 'alias-name' MUST be present. 955 Attributes and Uri-Path parameters with empty values MUST NOT be 956 present in a request and render the entire request invalid. 958 Figure 8 shows a PUT request example to signal that TCP port numbers 959 80, 8080, and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 960 servers are under attack. The presence of 'cdid' indicates that a 961 server-domain DOTS gateway has modified the initial PUT request sent 962 by the DOTS client. Note that 'cdid' MUST NOT appear in the PUT 963 request message body. 965 Header: PUT (Code=0.03) 966 Uri-Path: ".well-known" 967 Uri-Path: "dots" 968 Uri-Path: "mitigate" 969 Uri-Path: "cdid=7eeaf349529eb55ed50113" 970 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 971 Uri-Path: "mid=123" 972 Content-Format: "application/dots+cbor" 974 { 975 "ietf-dots-signal-channel:mitigation-scope": { 976 "scope": [ 977 { 978 "target-prefix": [ 979 "2001:db8:6401::1/128", 980 "2001:db8:6401::2/128" 981 ], 982 "target-port-range": [ 983 { 984 "lower-port": 80 985 }, 986 { 987 "lower-port": 443 988 }, 989 { 990 "lower-port": 8080 991 } 992 ], 993 "target-protocol": [ 994 6 995 ], 996 "lifetime": 3600 997 } 998 ] 999 } 1000 } 1002 Figure 8: PUT for DOTS Mitigation Request (An Example) 1004 The corresponding CBOR encoding format for the payload is shown in 1005 Figure 9. 1007 A1 # map(1) 1008 01 # unsigned(1) 1009 A1 # map(1) 1010 02 # unsigned(2) 1011 81 # array(1) 1012 A3 # map(3) 1013 06 # unsigned(6) 1014 82 # array(2) 1015 74 # text(20) 1016 323030313A6462383A363430313A3A312F313238 1017 74 # text(20) 1018 323030313A6462383A363430313A3A322F313238 1019 07 # unsigned(7) 1020 83 # array(3) 1021 A1 # map(1) 1022 08 # unsigned(8) 1023 18 50 # unsigned(80) 1024 A1 # map(1) 1025 08 # unsigned(8) 1026 19 01BB # unsigned(443) 1027 A1 # map(1) 1028 08 # unsigned(8) 1029 19 1F90 # unsigned(8080) 1030 0A # unsigned(10) 1031 81 # array(1) 1032 06 # unsigned(6) 1033 0E # unsigned(14) 1034 19 0E10 # unsigned(3600) 1036 Figure 9: PUT for DOTS Mitigation Request (CBOR) 1038 In both DOTS signal and data channel sessions, the DOTS client MUST 1039 authenticate itself to the DOTS server (Section 8). The DOTS server 1040 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 1041 the DOTS client identity or username from the client certificate. 1042 The DOTS client identity allows the DOTS server to accept mitigation 1043 requests with scopes that the DOTS client is authorized to manage. 1045 The DOTS server couples the DOTS signal and data channel sessions 1046 using the DOTS client identity and optionally the 'cdid' parameter 1047 value, so the DOTS server can validate whether the aliases conveyed 1048 in the mitigation request were indeed created by the same DOTS client 1049 using the DOTS data channel session. If the aliases were not created 1050 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 1051 the response. 1053 The DOTS server couples the DOTS signal channel sessions using the 1054 DOTS client identity and optionally the 'cdid' parameter value, and 1055 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 1056 detect duplicate mitigation requests. If the mitigation request 1057 contains the 'alias-name' and other parameters identifying the target 1058 resources (such as 'target-prefix', 'target-port-range', 'target- 1059 fqdn', or 'target-uri'), the DOTS server appends the parameter values 1060 in 'alias-name' with the corresponding parameter values in 'target- 1061 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 1063 The DOTS server indicates the result of processing the PUT request 1064 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 1065 codes are some sort of invalid requests (client errors). COAP 5.xx 1066 codes are returned if the DOTS server is in an error state or is 1067 currently unavailable to provide mitigation in response to the 1068 mitigation request from the DOTS client. 1070 Figure 10 shows an example response to a PUT request that is 1071 successfully processed by a DOTS server (i.e., CoAP 2.xx response 1072 codes). This version of the specification forbids 'cuid' and 'cdid' 1073 (if used) to be returned in a response message body. 1075 { 1076 "ietf-dots-signal-channel:mitigation-scope": { 1077 "scope": [ 1078 { 1079 "mid": 123, 1080 "lifetime": 3600 1081 } 1082 ] 1083 } 1084 } 1086 Figure 10: 2.xx Response Body 1088 If the request is missing a mandatory attribute, does not include 1089 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1090 parameters, or contains invalid or unknown parameters, the DOTS 1091 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1092 ignore comprehension-optional parameters they don't understand 1093 (Section 9.6.1.1). 1095 A DOTS server that receives a mitigation request with a lifetime set 1096 to '0' MUST reply with a 4.00 (Bad Request). 1098 If the DOTS server does not find the 'mid' parameter value conveyed 1099 in the PUT request in its configuration data, it MAY accept the 1100 mitigation request by sending back a 2.01 (Created) response to the 1101 DOTS client; the DOTS server will consequently try to mitigate the 1102 attack. A DOTS server could reject mitigation requests when it is 1103 near capacity or needs to rate-limit a particular client, for 1104 example. 1106 The relative order of two mitigation requests, having the same 1107 'trigger-mitigation' type, from a DOTS client is determined by 1108 comparing their respective 'mid' values. If two mitigation requests 1109 with the same 'trigger-mitigation' type have overlapping mitigation 1110 scopes, the mitigation request with the highest numeric 'mid' value 1111 will override the other mitigation request. Two mitigation requests 1112 from a DOTS client have overlapping scopes if there is a common IP 1113 address, IP prefix, FQDN, URI, or alias-name. To avoid maintaining a 1114 long list of overlapping mitigation requests (i.e., requests with the 1115 same 'trigger-mitigation' type and overlapping scopes) from a DOTS 1116 client and avoid error-prone provisioning of mitigation requests from 1117 a DOTS client, the overlapped lower numeric 'mid' MUST be 1118 automatically deleted and no longer available at the DOTS server. 1119 For example, if the DOTS server receives a mitigation request which 1120 overlaps with an existing mitigation with a higher numeric 'mid', the 1121 DOTS server rejects the request by returning 4.09 (Conflict) to the 1122 DOTS client. The response includes enough information for a DOTS 1123 client to recognize the source of the conflict as described below in 1124 the 'conflict-information' subtree with only the relevant nodes 1125 listed: 1127 conflict-information: Indicates that a mitigation request is 1128 conflicting with another mitigation request. This optional 1129 attribute has the following structure: 1131 conflict-cause: Indicates the cause of the conflict. The 1132 following values are defined: 1134 1: Overlapping targets. 'conflict-scope' provides more details 1135 about the conflicting target clauses. 1137 conflict-scope: Characterizes the exact conflict scope. It may 1138 include a list of IP addresses, a list of prefixes, a list of 1139 port numbers, a list of target protocols, a list of FQDNs, a 1140 list of URIs, a list of alias-names, or a 'mid'. 1142 If the DOTS server receives a mitigation request which overlaps with 1143 an active mitigation request, but both having distinct 'trigger- 1144 mitigation' types, the DOTS server SHOULD deactivate (absent explicit 1145 policy/configuration otherwise) the mitigation request with 'trigger- 1146 mitigation' set to false. Particularly, if the mitigation request 1147 with 'trigger-mitigation' set to false is active, the DOTS server 1148 withdraws the mitigation request (i.e., status code is set to '7' as 1149 defined in Table 2) and transitions the status of the mitigation 1150 request to '8'. 1152 Upon DOTS signal channel session loss with a peer DOTS client, the 1153 DOTS server SHOULD withdraw (absent explicit policy/configuration 1154 otherwise) any active mitigation requests overlapping with mitigation 1155 requests having 'trigger-mitigation' set to false from that DOTS 1156 client, as the loss of the session implicitly activates these 1157 preconfigured mitigation requests and they take precedence. Note 1158 that active-but-terminating period is not observed for mitigations 1159 withdrawn at the initiative of the DOTS server. 1161 DOTS clients may adopt various strategies for setting the scopes of 1162 immediate and pre-configured mitigation requests to avoid potential 1163 conflicts. For example, a DOTS client may tweak pre-configured 1164 scopes so that the scope of any overlapping immediate mitigation 1165 request will be a subset of the pre-configured scopes. Also, if an 1166 immediate mitigation request overlaps with any of the pre-configured 1167 scopes, the DOTS client sets the scope of the overlapping immediate 1168 mitigation request to be a subset of the pre-configured scopes, so as 1169 to get a broad mitigation when the DOTS signal channel collapses and 1170 maximize the chance of recovery. 1172 If the request is conflicting with an existing mitigation request 1173 from a different DOTS client, the DOTS server may return 2.01 1174 (Created) or 4.09 (Conflict) to the requesting DOTS client. If the 1175 DOTS server decides to maintain the new mitigation request, the DOTS 1176 server returns 2.01 (Created) to the requesting DOTS client. If the 1177 DOTS server decides to reject the new mitigation request, the DOTS 1178 server returns 4.09 (Conflict) to the requesting DOTS client. For 1179 both 2.01 (Created) and 4.09 (Conflict) responses, the response 1180 includes enough information for a DOTS client to recognize the source 1181 of the conflict as described below: 1183 conflict-information: Indicates that a mitigation request is 1184 conflicting with another mitigation request(s) from other DOTS 1185 client(s). This optional attribute has the following structure: 1187 conflict-status: Indicates the status of a conflicting mitigation 1188 request. The following values are defined: 1190 1: DOTS server has detected conflicting mitigation requests 1191 from different DOTS clients. This mitigation request is 1192 currently inactive until the conflicts are resolved. 1193 Another mitigation request is active. 1195 2: DOTS server has detected conflicting mitigation requests 1196 from different DOTS clients. This mitigation request is 1197 currently active. 1199 3: DOTS server has detected conflicting mitigation requests 1200 from different DOTS clients. All conflicting mitigation 1201 requests are inactive. 1203 conflict-cause: Indicates the cause of the conflict. The 1204 following values are defined: 1206 1: Overlapping targets. 'conflict-scope' provides more details 1207 about the conflicting target clauses. 1209 2: Conflicts with an existing accept-list. This code is 1210 returned when the DDoS mitigation detects source addresses/ 1211 prefixes in the accept-listed ACLs are attacking the 1212 target. 1214 3: CUID Collision. This code is returned when a DOTS client 1215 uses a 'cuid' that is already used by another DOTS client. 1216 This code is an indication that the request has been 1217 rejected and a new request with a new 'cuid' is to be re- 1218 sent by the DOTS client (see the example shown in 1219 Figure 11). Note that 'conflict-status', 'conflict-scope', 1220 and 'retry-timer' MUST NOT be returned in the error 1221 response. 1223 conflict-scope: Characterizes the exact conflict scope. It may 1224 include a list of IP addresses, a list of prefixes, a list of 1225 port numbers, a list of target protocols, a list of FQDNs, a 1226 list of URIs, a list of alias-names, or references to 1227 conflicting ACLs (by an 'acl-name', typically 1228 [I-D.ietf-dots-data-channel]). 1230 retry-timer: Indicates, in seconds, the time after which the DOTS 1231 client may re-issue the same request. The DOTS server returns 1232 'retry-timer' only to DOTS client(s) for which a mitigation 1233 request is deactivated. Any retransmission of the same 1234 mitigation request before the expiry of this timer is likely to 1235 be rejected by the DOTS server for the same reasons. 1237 The retry-timer SHOULD be equal to the lifetime of the active 1238 mitigation request resulting in the deactivation of the 1239 conflicting mitigation request. 1241 If the DOTS server decides to maintain a state for the 1242 deactivated mitigation request, the DOTS server updates the 1243 lifetime of the deactivated mitigation request to 'retry-timer 1244 + 45 seconds' (that is, this mitigation request remains 1245 deactivated for the entire duration of 'retry-timer + 45 1246 seconds') so that the DOTS client can refresh the deactivated 1247 mitigation request after 'retry-timer' seconds, but before the 1248 expiry of the lifetime, and check if the conflict is resolved. 1250 Header: PUT (Code=0.03) 1251 Uri-Path: ".well-known" 1252 Uri-Path: "dots" 1253 Uri-Path: "mitigate" 1254 Uri-Path: "cuid=7eeaf349529eb55ed50113" 1255 Uri-Path: "mid=12" 1257 (1) Request with a conflicting 'cuid' 1259 { 1260 "ietf-dots-signal-channel:mitigation-scope": { 1261 "scope": [ 1262 { 1263 "conflict-information": { 1264 "conflict-cause": "cuid-collision" 1265 } 1266 } 1267 ] 1268 } 1269 } 1271 (2) Message body of the 4.09 (Conflict) response 1272 from the DOTS server 1274 Header: PUT (Code=0.03) 1275 Uri-Path: ".well-known" 1276 Uri-Path: "dots" 1277 Uri-Path: "mitigate" 1278 Uri-Path: "cuid=f30d281ce6b64fc5a0b91e" 1279 Uri-Path: "mid=12" 1281 (3) Request with a new 'cuid' 1283 Figure 11: Example of Generating a New 'cuid' 1285 As an active attack evolves, DOTS clients can adjust the scope of 1286 requested mitigation as necessary, by refining the scope of resources 1287 requiring mitigation. This can be achieved by sending a PUT request 1288 with a new 'mid' value that will override the existing one with 1289 overlapping mitigation scopes. 1291 For a mitigation request to continue beyond the initial negotiated 1292 lifetime, the DOTS client has to refresh the current mitigation 1293 request by sending a new PUT request. This PUT request MUST use the 1294 same 'mid' value, and MUST repeat all the other parameters as sent in 1295 the original mitigation request apart from a possible change to the 1296 lifetime parameter value. In such case, the DOTS server MAY update 1297 the mitigation request, and a 2.04 (Changed) response is returned to 1298 indicate a successful update of the mitigation request. If this is 1299 not the case, the DOTS server MUST reject the request with a 4.00 1300 (Bad Request). 1302 4.4.2. Retrieve Information Related to a Mitigation 1304 A GET request is used by a DOTS client to retrieve information 1305 (including status) of DOTS mitigations from a DOTS server. 1307 'cuid' is a mandatory Uri-Path parameter for GET requests. 1309 Uri-Path parameters with empty values MUST NOT be present in a 1310 request. 1312 The same considerations for manipulating 'cdid' parameter by server- 1313 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1314 GET requests. 1316 The 'c' Uri-Query option is used to control selection of 1317 configuration and non-configuration data nodes. Concretely, the 'c' 1318 (content) parameter and its permitted values defined in the following 1319 table [I-D.ietf-core-comi] can be used to retrieve non-configuration 1320 data (attack mitigation status), configuration data, or both. The 1321 DOTS server MAY support this optional filtering capability. It can 1322 safely ignore it if not supported. If the DOTS client supports the 1323 optional filtering capability, it SHOULD use "c=n" query (to get back 1324 only the dynamically changing data) or "c=c" query (to get back the 1325 static configuration values) when the DDoS attack is active to limit 1326 the size of the response. 1328 +-------+-----------------------------------------------------+ 1329 | Value | Description | 1330 +-------+-----------------------------------------------------+ 1331 | c | Return only configuration descendant data nodes | 1332 | n | Return only non-configuration descendant data nodes | 1333 | a | Return all descendant data nodes | 1334 +-------+-----------------------------------------------------+ 1336 The DOTS client can use Block-wise transfer [RFC7959] to get the list 1337 of all its mitigations maintained by a DOTS server, it can send 1338 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1339 size of the response. If the representation of all the active 1340 mitigation requests associated with the DOTS client does not fit 1341 within a single datagram, the DOTS server MUST use the Block2 Option 1342 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1343 in the response to indicate the total size of the resource 1344 representation. The DOTS client retrieves the rest of the 1345 representation by sending additional GET requests with Block2 Options 1346 containing NUM values greater than zero. The DOTS client MUST adhere 1347 to the block size preferences indicated by the DOTS server in the 1348 response. If the DOTS server uses the Block2 Option in the GET 1349 response and the response is for a dynamically changing resource 1350 (e.g., "c=n" or "c=a" query), the DOTS server MUST include the ETag 1351 Option in the response. The DOTS client MUST include the same ETag 1352 value in subsequent GET requests to retrieve the rest of the 1353 representation. 1355 The following examples illustrate how a DOTS client retrieves active 1356 mitigation requests from a DOTS server. In particular: 1358 o Figure 12 shows the example of a GET request to retrieve all DOTS 1359 mitigation requests signaled by a DOTS client. 1361 o Figure 13 shows the example of a GET request to retrieve a 1362 specific DOTS mitigation request signaled by a DOTS client. The 1363 configuration data to be reported in the response is formatted in 1364 the same order as was processed by the DOTS server in the original 1365 mitigation request. 1367 These two examples assume the default of "c=a"; that is, the DOTS 1368 client asks for all data to be reported by the DOTS server. 1370 Header: GET (Code=0.01) 1371 Uri-Path: ".well-known" 1372 Uri-Path: "dots" 1373 Uri-Path: "mitigate" 1374 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1375 Observe: 0 1377 Figure 12: GET to Retrieve all DOTS Mitigation Requests 1379 Header: GET (Code=0.01) 1380 Uri-Path: ".well-known" 1381 Uri-Path: "dots" 1382 Uri-Path: "mitigate" 1383 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1384 Uri-Path: "mid=12332" 1385 Observe: 0 1387 Figure 13: GET to Retrieve a Specific DOTS Mitigation Request 1389 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1390 the GET request in its configuration data for the requesting DOTS 1391 client, it MUST respond with a 4.04 (Not Found) error response code. 1392 Likewise, the same error MUST be returned as a response to a request 1393 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1394 defined) of a given DOTS client if the DOTS server does not find any 1395 mitigation record for that DOTS client. As a reminder, a DOTS client 1396 is identified by its identity (e.g., client certificate, 'cuid') and 1397 optionally the 'cdid'. 1399 Figure 14 shows a response example of all active mitigation requests 1400 associated with the DOTS client as maintained by the DOTS server. 1401 The response indicates the mitigation status of each mitigation 1402 request. 1404 { 1405 "ietf-dots-signal-channel:mitigation-scope": { 1406 "scope": [ 1407 { 1408 "mid": 12332, 1409 "mitigation-start": "1507818434", 1410 "target-prefix": [ 1411 "2001:db8:6401::1/128", 1412 "2001:db8:6401::2/128" 1413 ], 1414 "target-protocol": [ 1415 17 1416 ], 1417 "lifetime": 1756, 1418 "status": "attack-successfully-mitigated", 1419 "bytes-dropped": "134334555", 1420 "bps-dropped": "43344", 1421 "pkts-dropped": "333334444", 1422 "pps-dropped": "432432" 1423 }, 1424 { 1425 "mid": 12333, 1426 "mitigation-start": "1507818393", 1427 "target-prefix": [ 1428 "2001:db8:6401::1/128", 1429 "2001:db8:6401::2/128" 1430 ], 1431 "target-protocol": [ 1432 6 1433 ], 1434 "lifetime": 1755, 1435 "status": "attack-stopped", 1436 "bytes-dropped": "0", 1437 "bps-dropped": "0", 1438 "pkts-dropped": "0", 1439 "pps-dropped": "0" 1440 } 1441 ] 1442 } 1443 } 1445 Figure 14: Response Body to a GET Request 1447 The mitigation status parameters are described below: 1449 mitigation-start: Mitigation start time is expressed in seconds 1450 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1452 [RFC7049]). The CBOR encoding is modified so that the leading tag 1453 1 (epoch-based date/time) MUST be omitted. 1455 This is a mandatory attribute when an attack mitigation is active. 1456 Particularly, 'mitigation-start' is not returned for a mitigation 1457 with 'status' code set to 8. 1459 lifetime: The remaining lifetime of the mitigation request, in 1460 seconds. 1462 This is a mandatory attribute. 1464 status: Status of attack mitigation. The various possible values of 1465 'status' parameter are explained in Table 2. 1467 This is a mandatory attribute. 1469 bytes-dropped: The total dropped byte count for the mitigation 1470 request since the attack mitigation is triggered. The count wraps 1471 around when it reaches the maximum value of unsigned integer64. 1473 This is an optional attribute. 1475 bps-dropped: The average number of dropped bytes per second for the 1476 mitigation request since the attack mitigation is triggered. This 1477 average SHOULD be over five-minute intervals (that is, measuring 1478 bytes into five-minute buckets and then averaging these buckets 1479 over the time since the mitigation was triggered). 1481 This is an optional attribute. 1483 pkts-dropped: The total number of dropped packet count for the 1484 mitigation request since the attack mitigation is triggered. The 1485 count wraps around when it reaches the maximum value of unsigned 1486 integer64. 1488 This is an optional attribute. 1490 pps-dropped: The average number of dropped packets per second for 1491 the mitigation request since the attack mitigation is triggered. 1492 This average SHOULD be over five-minute intervals (that is, 1493 measuring packets into five-minute buckets and then averaging 1494 these buckets over the time since the mitigation was triggered). 1496 This is an optional attribute. 1498 +-----------+-------------------------------------------------------+ 1499 | Parameter | Description | 1500 | Value | | 1501 +-----------+-------------------------------------------------------+ 1502 | 1 | Attack mitigation setup is in progress (e.g., | 1503 | | changing the network path to redirect the inbound | 1504 | | traffic to a DOTS mitigator). | 1505 +-----------+-------------------------------------------------------+ 1506 | 2 | Attack is being successfully mitigated (e.g., traffic | 1507 | | is redirected to a DDoS mitigator and attack traffic | 1508 | | is dropped). | 1509 +-----------+-------------------------------------------------------+ 1510 | 3 | Attack has stopped and the DOTS client can withdraw | 1511 | | the mitigation request. This status code will be | 1512 | | transmitted for immediate mitigation requests till | 1513 | | the mitigation is withdrawn or the lifetime expires. | 1514 | | For mitigation requests with pre-configured scopes | 1515 | | (i.e., 'trigger-mitigation' set to 'false'), this | 1516 | | status code will be transmitted 4 times and then | 1517 | | transition to "8". | 1518 +-----------+-------------------------------------------------------+ 1519 | 4 | Attack has exceeded the mitigation provider | 1520 | | capability. | 1521 +-----------+-------------------------------------------------------+ 1522 | 5 | DOTS client has withdrawn the mitigation request and | 1523 | | the mitigation is active but terminating. | 1524 +-----------+-------------------------------------------------------+ 1525 | 6 | Attack mitigation is now terminated. | 1526 +-----------+-------------------------------------------------------+ 1527 | 7 | Attack mitigation is withdrawn (by the DOTS server). | 1528 | | If a mitigation request with 'trigger-mitigation' set | 1529 | | to false is withdrawn because it overlaps with an | 1530 | | immediate mitigation request, this status code will | 1531 | | be transmitted 4 times and then transition to "8" for | 1532 | | the mitigation request with pre-configured scopes. | 1533 +-----------+-------------------------------------------------------+ 1534 | 8 | Attack mitigation will be triggered for the | 1535 | | mitigation request only when the DOTS signal channel | 1536 | | session is lost. | 1537 +-----------+-------------------------------------------------------+ 1539 Table 2: Values of 'status' Parameter 1541 4.4.2.1. DOTS Servers Sending Mitigation Status 1543 The Observe Option defined in [RFC7641] extends the CoAP core 1544 protocol with a mechanism for a CoAP client to "observe" a resource 1545 on a CoAP server: The client retrieves a representation of the 1546 resource and requests this representation be updated by the server as 1547 long as the client is interested in the resource. DOTS 1548 implementations MUST use the Observe Option for both 'mitigate' and 1549 'config' (Section 4.2). 1551 A DOTS client conveys the Observe Option set to '0' in the GET 1552 request to receive asynchronous notifications of attack mitigation 1553 status from the DOTS server. 1555 Unidirectional mitigation notifications within the bidirectional 1556 signal channel enables asynchronous notifications between the agents. 1557 [RFC7641] indicates that (1) a notification can be sent in a 1558 Confirmable or a Non-confirmable message, and (2) the message type 1559 used is typically application-dependent and may be determined by the 1560 server for each notification individually. For DOTS server 1561 application, the message type MUST always be set to Non-confirmable 1562 even if the underlying COAP library elects a notification to be sent 1563 in a Confirmable message. This overrides the behavior defined in 1564 Section 4.5 of [RFC7641] to send a Confirmable message instead of a 1565 Non-confirmable message at least every 24 hour for the following 1566 reasons: First, the DOTS signal channel uses a heartbeat mechanism to 1567 determine if the DOTS client is alive. Second, Confirmable messages 1568 are not suitable during an attack. 1570 Due to the higher likelihood of packet loss during a DDoS attack, the 1571 DOTS server periodically sends attack mitigation status to the DOTS 1572 client and also notifies the DOTS client whenever the status of the 1573 attack mitigation changes. If the DOTS server cannot maintain an RTT 1574 estimate, it MUST NOT send more than one asynchronous notification 1575 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1576 possible (case 2 in Section 3.1.3 of [RFC8085]). 1578 When conflicting requests are detected, the DOTS server enforces the 1579 corresponding policy (e.g., accept all requests, reject all requests, 1580 accept only one request but reject all the others, ...). It is 1581 assumed that this policy is supplied by the DOTS server administrator 1582 or it is a default behavior of the DOTS server implementation. Then, 1583 the DOTS server sends notification message(s) to the DOTS client(s) 1584 at the origin of the conflict (refer to the conflict parameters 1585 defined in Section 4.4.1). A conflict notification message includes 1586 information about the conflict cause, scope, and the status of the 1587 mitigation request(s). For example, 1589 o A notification message with 'status' code set to '7 (Attack 1590 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1591 to a DOTS client to indicate that an active mitigation request is 1592 deactivated because a conflict is detected. 1594 o A notification message with 'status' code set to '1 (Attack 1595 mitigation is in progress)' and 'conflict-status' set to '2' is 1596 sent to a DOTS client to indicate that this mitigation request is 1597 in progress, but a conflict is detected. 1599 Upon receipt of a conflict notification message indicating that a 1600 mitigation request is deactivated because of a conflict, a DOTS 1601 client MUST NOT resend the same mitigation request before the expiry 1602 of 'retry-timer'. It is also recommended that DOTS clients support 1603 means to alert administrators about mitigation conflicts. 1605 A DOTS client that is no longer interested in receiving notifications 1606 from the DOTS server can simply "forget" the observation. When the 1607 DOTS server sends the next notification, the DOTS client will not 1608 recognize the token in the message and thus will return a Reset 1609 message. This causes the DOTS server to remove the associated entry. 1610 Alternatively, the DOTS client can explicitly deregister itself by 1611 issuing a GET request that has the Token field set to the token of 1612 the observation to be cancelled and includes an Observe Option with 1613 the value set to '1' (deregister). The latter is more deterministic 1614 and thus is RECOMMENDED. 1616 Figure 15 shows an example of a DOTS client requesting a DOTS server 1617 to send notifications related to a mitigation request. Note that for 1618 mitigations with pre-configured scopes (i.e., 'trigger-mitigation' 1619 set to 'false'), the state will need to transition from 3 (attack- 1620 stopped) to 8 (attack-mitigation-signal-loss). 1622 +-----------+ +-----------+ 1623 |DOTS client| |DOTS server| 1624 +-----------+ +-----------+ 1625 | | 1626 | GET / | 1627 | Token: 0x4a | Registration 1628 | Observe: 0 | 1629 +----------------------------------------->| 1630 | | 1631 | 2.05 Content | 1632 | Token: 0x4a | Notification of 1633 | Observe: 12 | the current state 1634 | status: "attack-mitigation-in-progress" | 1635 | | 1636 |<-----------------------------------------+ 1637 | 2.05 Content | 1638 | Token: 0x4a | Notification upon 1639 | Observe: 44 | a state change 1640 | status: "attack-successfully-mitigated" | 1641 | | 1642 |<-----------------------------------------+ 1643 | 2.05 Content | 1644 | Token: 0x4a | Notification upon 1645 | Observe: 60 | a state change 1646 | status: "attack-stopped" | 1647 |<-----------------------------------------+ 1648 | | 1649 ... 1651 Figure 15: Notifications of Attack Mitigation Status 1653 4.4.2.2. DOTS Clients Polling for Mitigation Status 1655 The DOTS client can send the GET request at frequent intervals 1656 without the Observe Option to retrieve the configuration data of the 1657 mitigation request and non-configuration data (i.e., the attack 1658 status). DOTS clients MAY be configured with a policy indicating the 1659 frequency of polling DOTS servers to get the mitigation status. This 1660 frequency MUST NOT be more than one UDP datagram per RTT as discussed 1661 in Section 3.1.3 of [RFC8085]. 1663 If the DOTS server has been able to mitigate the attack and the 1664 attack has stopped, the DOTS server indicates as such in the status. 1665 In such case, the DOTS client recalls the mitigation request by 1666 issuing a DELETE request for this mitigation request (Section 4.4.4). 1668 A DOTS client SHOULD react to the status of the attack as per the 1669 information sent by the DOTS server rather than performing its own 1670 detection that the attack has been mitigated. This ensures that the 1671 DOTS client does not recall a mitigation request prematurely because 1672 it is possible that the DOTS client does not sense the DDoS attack on 1673 its resources, but the DOTS server could be actively mitigating the 1674 attack because the attack is not completely averted. 1676 4.4.3. Efficacy Update from DOTS Clients 1678 While DDoS mitigation is in progress, due to the likelihood of packet 1679 loss, a DOTS client MAY periodically transmit DOTS mitigation 1680 efficacy updates to the relevant DOTS server. A PUT request is used 1681 to convey the mitigation efficacy update to the DOTS server. This 1682 PUT request is treated as a refresh of the current mitigation. 1684 The PUT request used for efficacy update MUST include all the 1685 parameters used in the PUT request to carry the DOTS mitigation 1686 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1687 value. If this is not the case, the DOTS server MUST reject the 1688 request with a 4.00 (Bad Request). 1690 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1691 value is used to make the PUT request conditional on the current 1692 existence of the mitigation request. If UDP is used as transport, 1693 CoAP requests may arrive out-of-order. For example, the DOTS client 1694 may send a PUT request to convey an efficacy update to the DOTS 1695 server followed by a DELETE request to withdraw the mitigation 1696 request, but the DELETE request arrives at the DOTS server before the 1697 PUT request. To handle out-of-order delivery of requests, if an If- 1698 Match Option is present in the PUT request and the 'mid' in the 1699 request matches a mitigation request from that DOTS client, the 1700 request is processed by the DOTS server. If no match is found, the 1701 PUT request is silently ignored by the DOTS server. 1703 An example of an efficacy update message, which includes an If-Match 1704 Option with an empty value, is depicted in Figure 16. 1706 Header: PUT (Code=0.03) 1707 Uri-Path: ".well-known" 1708 Uri-Path: "dots" 1709 Uri-Path: "mitigate" 1710 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1711 Uri-Path: "mid=123" 1712 If-Match: 1713 Content-Format: "application/dots+cbor" 1715 { 1716 "ietf-dots-signal-channel:mitigation-scope": { 1717 "scope": [ 1718 { 1719 "target-prefix": [ 1720 "2001:db8:6401::1/128", 1721 "2001:db8:6401::2/128" 1722 ], 1723 "target-port-range": [ 1724 { 1725 "lower-port": 80 1726 }, 1727 { 1728 "lower-port": 443 1729 }, 1730 { 1731 "lower-port": 8080 1732 } 1733 ], 1734 "target-protocol": [ 1735 6 1736 ], 1737 "attack-status": "under-attack" 1738 } 1739 ] 1740 } 1741 } 1743 Figure 16: An Example of Efficacy Update 1745 The 'attack-status' parameter is a mandatory attribute when 1746 performing an efficacy update. The various possible values contained 1747 in the 'attack-status' parameter are described in Table 3. 1749 +-----------+-------------------------------------------------------+ 1750 | Parameter | Description | 1751 | value | | 1752 +-----------+-------------------------------------------------------+ 1753 | 1 | The DOTS client determines that it is still under | 1754 | | attack. | 1755 +-----------+-------------------------------------------------------+ 1756 | 2 | The DOTS client determines that the attack is | 1757 | | successfully mitigated (e.g., attack traffic is not | 1758 | | seen). | 1759 +-----------+-------------------------------------------------------+ 1761 Table 3: Values of 'attack-status' Parameter 1763 The DOTS server indicates the result of processing a PUT request 1764 using CoAP response codes. The response code 2.04 (Changed) is 1765 returned if the DOTS server has accepted the mitigation efficacy 1766 update. The error response code 5.03 (Service Unavailable) is 1767 returned if the DOTS server has erred or is incapable of performing 1768 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age option 1769 to indicate the number of seconds after which to retry. 1771 4.4.4. Withdraw a Mitigation 1773 DELETE requests are used to withdraw DOTS mitigation requests from 1774 DOTS servers (Figure 17). 1776 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1777 requests. 1779 The same considerations for manipulating 'cdid' parameter by DOTS 1780 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1781 requests. Uri-Path parameters with empty values MUST NOT be present 1782 in a request. 1784 Header: DELETE (Code=0.04) 1785 Uri-Path: ".well-known" 1786 Uri-Path: "dots" 1787 Uri-Path: "mitigate" 1788 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1789 Uri-Path: "mid=123" 1791 Figure 17: Withdraw a DOTS Mitigation 1793 If the DELETE request does not include 'cuid' and 'mid' parameters, 1794 the DOTS server MUST reply with a 4.00 (Bad Request). 1796 Once the request is validated, the DOTS server immediately 1797 acknowledges a DOTS client's request to withdraw the DOTS signal 1798 using 2.02 (Deleted) response code with no response payload. A 2.02 1799 (Deleted) Response Code is returned even if the 'mid' parameter value 1800 conveyed in the DELETE request does not exist in its configuration 1801 data before the request. 1803 If the DOTS server finds the 'mid' parameter value conveyed in the 1804 DELETE request in its configuration data for the DOTS client, then to 1805 protect against route or DNS flapping caused by a DOTS client rapidly 1806 removing a mitigation, and to dampen the effect of oscillating 1807 attacks, the DOTS server MAY allow mitigation to continue for a 1808 limited period after acknowledging a DOTS client's withdrawal of a 1809 mitigation request. During this period, the DOTS server status 1810 messages SHOULD indicate that mitigation is active but terminating 1811 (Section 4.4.2). 1813 The initial active-but-terminating period SHOULD be sufficiently long 1814 to absorb latency incurred by route propagation. The active-but- 1815 terminating period SHOULD be set by default to 120 seconds. If the 1816 client requests mitigation again before the initial active-but- 1817 terminating period elapses, the DOTS server MAY exponentially 1818 increase (the base of the exponent is 2) the active-but-terminating 1819 period up to a maximum of 300 seconds (5 minutes). 1821 Once the active-but-terminating period elapses, the DOTS server MUST 1822 treat the mitigation as terminated, as the DOTS client is no longer 1823 responsible for the mitigation. 1825 If a mitigation is triggered due to a signal channel loss, the DOTS 1826 server relies upon normal triggers to stop that mitigation 1827 (typically, receipt of a valid DELETE request, expiry of the 1828 mitigation lifetime, or scrubbing the traffic to the attack target). 1829 In particular, the DOTS server MUST NOT consider the signal channel 1830 recovery as a trigger to stop the mitigation. 1832 4.5. DOTS Signal Channel Session Configuration 1834 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1835 channel session behavior with its DOTS peers. The DOTS signal 1836 channel can be used, for example, to configure the following: 1838 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1839 send heartbeats to each other after mutual authentication is 1840 successfully completed in order to keep the DOTS signal channel 1841 open. Heartbeat messages are exchanged between DOTS agents every 1842 'heartbeat-interval' seconds to detect the current status of the 1843 DOTS signal channel session. 1845 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1846 indicates the maximum number of consecutive heartbeat messages 1847 for which a DOTS agent did not receive a response before 1848 concluding that the session is disconnected or defunct. 1850 c. Acceptable probing rate (probing-rate): This parameter indicates 1851 the average data rate that must not be exceeded by a DOTS agent 1852 in sending to a peer DOTS agent that does not respond. 1854 d. Acceptable signal loss ratio: Maximum retransmissions, 1855 retransmission timeout value, and other message transmission 1856 parameters for Confirmable messages over the DOTS signal channel. 1858 When the DOTS signal channel is established over a reliable transport 1859 (e.g., TCP), there is no need for the reliability mechanisms provided 1860 by CoAP over UDP since the underlying TCP connection provides 1861 retransmissions and deduplication [RFC8323]. As a reminder, CoAP 1862 over reliable transports does not support Confirmable or Non- 1863 confirmable message types. As such, the transmission-related 1864 parameters (missing-hb-allowed and acceptable signal loss ratio) are 1865 negotiated only for DOTS over unreliable transports. 1867 The same or distinct configuration sets may be used during times when 1868 a mitigation is active ('mitigating-config') and when no mitigation 1869 is active ('idle-config'). This is particularly useful for DOTS 1870 servers that might want to reduce heartbeat frequency or cease 1871 heartbeat exchanges when an active DOTS client has not requested 1872 mitigation. If distinct configurations are used, DOTS agents MUST 1873 follow the appropriate configuration set as a function of the 1874 mitigation activity (e.g., if no mitigation request is active (also 1875 referred to as 'idle' time), 'idle-config'-related values must be 1876 followed). Additionally, DOTS agents MUST automatically switch to 1877 the other configuration upon a change in the mitigation activity 1878 (e.g., if an attack mitigation is launched after an 'idle' time, the 1879 DOTS agent switches from 'idle-config' to 'mitigating-config'-related 1880 values). 1882 CoAP Requests and responses are indicated for reliable delivery by 1883 marking them as Confirmable messages. DOTS signal channel session 1884 configuration requests and responses are marked as Confirmable 1885 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1886 message is retransmitted using a default timeout and exponential 1887 back-off between retransmissions, until the DOTS server sends an 1888 Acknowledgement message (ACK) with the same Message ID conveyed from 1889 the DOTS client. 1891 Message transmission parameters are defined in Section 4.8 of 1892 [RFC7252]. The DOTS server can either piggyback the response in the 1893 acknowledgement message or, if the DOTS server cannot respond 1894 immediately to a request carried in a Confirmable message, it simply 1895 responds with an Empty Acknowledgement message so that the DOTS 1896 client can stop retransmitting the request. Empty Acknowledgement 1897 messages are explained in Section 2.2 of [RFC7252]. When the 1898 response is ready, the server sends it in a new Confirmable message 1899 which in turn needs to be acknowledged by the DOTS client (see 1900 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1901 exchanged between DOTS agents during 'idle' time, except heartbeat 1902 messages, are marked as Confirmable messages. 1904 Implementation Note: A DOTS client that receives a response in a 1905 Confirmable message may want to clean up the message state right 1906 after sending the ACK. If that ACK is lost and the DOTS server 1907 retransmits the Confirmable message, the DOTS client may no longer 1908 have any state that would help it correlate this response: from 1909 the DOTS client's standpoint, the retransmission message is 1910 unexpected. The DOTS client will send a Reset message so it does 1911 not receive any more retransmissions. This behavior is normal and 1912 not an indication of an error (see Section 5.3.2 of [RFC7252] for 1913 more details). 1915 4.5.1. Discover Configuration Parameters 1917 A GET request is used to obtain acceptable (e.g., minimum and maximum 1918 values) and current configuration parameters on the DOTS server for 1919 DOTS signal channel session configuration. This procedure occurs 1920 between a DOTS client and its immediate peer DOTS server. As such, 1921 this GET request MUST NOT be relayed by a DOTS gateway. 1923 Figure 18 shows how to obtain configuration parameters that the DOTS 1924 server will find acceptable. 1926 Header: GET (Code=0.01) 1927 Uri-Path: ".well-known" 1928 Uri-Path: "dots" 1929 Uri-Path: "config" 1931 Figure 18: GET to Retrieve Configuration 1933 The DOTS server in the 2.05 (Content) response conveys the current, 1934 minimum, and maximum attribute values acceptable by the DOTS server 1935 (Figure 19). 1937 { 1938 "ietf-dots-signal-channel:signal-config": { 1939 "mitigating-config": { 1940 "heartbeat-interval": { 1941 "max-value": number, 1942 "min-value": number, 1943 "current-value": number 1944 }, 1945 "missing-hb-allowed": { 1946 "max-value": number, 1947 "min-value": number, 1948 "current-value": number 1949 }, 1950 "probing-rate": { 1951 "max-value": number, 1952 "min-value": number, 1953 "current-value": number 1954 }, 1955 "max-retransmit": { 1956 "max-value": number, 1957 "min-value": number, 1958 "current-value": number 1959 }, 1960 "ack-timeout": { 1961 "max-value-decimal": "string", 1962 "min-value-decimal": "string", 1963 "current-value-decimal": "string" 1964 }, 1965 "ack-random-factor": { 1966 "max-value-decimal": "string", 1967 "min-value-decimal": "string", 1968 "current-value-decimal": "string" 1969 } 1970 }, 1971 "idle-config": { 1972 "heartbeat-interval": { 1973 "max-value": number, 1974 "min-value": number, 1975 "current-value": number 1976 }, 1977 "missing-hb-allowed": { 1978 "max-value": number, 1979 "min-value": number, 1980 "current-value": number 1981 }, 1982 "probing-rate": { 1983 "max-value": number, 1984 "min-value": number, 1985 "current-value": number 1986 }, 1987 "max-retransmit": { 1988 "max-value": number, 1989 "min-value": number, 1990 "current-value": number 1991 }, 1992 "ack-timeout": { 1993 "max-value-decimal": "string", 1994 "min-value-decimal": "string", 1995 "current-value-decimal": "string" 1996 }, 1997 "ack-random-factor": { 1998 "max-value-decimal": "string", 1999 "min-value-decimal": "string", 2000 "current-value-decimal": "string" 2001 } 2002 } 2003 } 2004 } 2006 Figure 19: GET Configuration Response Body Schema 2008 The parameters in Figure 19 are described below: 2010 mitigating-config: Set of configuration parameters to use when a 2011 mitigation is active. The following parameters may be included: 2013 heartbeat-interval: Time interval in seconds between two 2014 consecutive heartbeat messages. 2016 '0' is used to disable the heartbeat mechanism. 2018 This is an optional attribute. 2020 missing-hb-allowed: Maximum number of consecutive heartbeat 2021 messages for which the DOTS agent did not receive a response 2022 before concluding that the session is disconnected. 2024 This is an optional attribute. 2026 probing-rate: The average data rate that must not be exceeded by 2027 a DOTS agent in sending to a peer DOTS agent that does not 2028 respond (referred to as PROBING_RATE parameter in CoAP). 2030 This is an optional attribute. 2032 max-retransmit: Maximum number of retransmissions for a message 2033 (referred to as MAX_RETRANSMIT parameter in CoAP). 2035 This is an optional attribute. 2037 ack-timeout: Timeout value in seconds used to calculate the 2038 initial retransmission timeout value (referred to as 2039 ACK_TIMEOUT parameter in CoAP). 2041 This is an optional attribute. 2043 ack-random-factor: Random factor used to influence the timing of 2044 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 2045 CoAP). 2047 This is an optional attribute. 2049 idle-config: Set of configuration parameters to use when no 2050 mitigation is active. This attribute has the same structure as 2051 'mitigating-config'. 2053 Figure 20 shows an example of acceptable and current configuration 2054 parameters on a DOTS server for DOTS signal channel session 2055 configuration. The same acceptable configuration is used during 2056 mitigation and idle times. 2058 { 2059 "ietf-dots-signal-channel:signal-config": { 2060 "mitigating-config": { 2061 "heartbeat-interval": { 2062 "max-value": 240, 2063 "min-value": 15, 2064 "current-value": 30 2065 }, 2066 "missing-hb-allowed": { 2067 "max-value": 20, 2068 "min-value": 3, 2069 "current-value": 15 2070 }, 2071 "probing-rate": { 2072 "max-value": 20, 2073 "min-value": 5, 2074 "current-value": 15 2075 }, 2076 "max-retransmit": { 2077 "max-value": 15, 2078 "min-value": 2, 2079 "current-value": 3 2080 }, 2081 "ack-timeout": { 2082 "max-value-decimal": "30.00", 2083 "min-value-decimal": "1.00", 2084 "current-value-decimal": "2.00" 2086 }, 2087 "ack-random-factor": { 2088 "max-value-decimal": "4.00", 2089 "min-value-decimal": "1.10", 2090 "current-value-decimal": "1.50" 2091 } 2092 }, 2093 "idle-config": { 2094 "heartbeat-interval": { 2095 "max-value": 240, 2096 "min-value": 15, 2097 "current-value": 30 2098 }, 2099 "missing-hb-allowed": { 2100 "max-value": 20, 2101 "min-value": 3, 2102 "current-value": 15 2103 }, 2104 "probing-rate": { 2105 "max-value": 20, 2106 "min-value": 5, 2107 "current-value": 15 2108 }, 2109 "max-retransmit": { 2110 "max-value": 15, 2111 "min-value": 2, 2112 "current-value": 3 2113 }, 2114 "ack-timeout": { 2115 "max-value-decimal": "30.00", 2116 "min-value-decimal": "1.00", 2117 "current-value-decimal": "2.00" 2118 }, 2119 "ack-random-factor": { 2120 "max-value-decimal": "4.00", 2121 "min-value-decimal": "1.10", 2122 "current-value-decimal": "1.50" 2123 } 2124 } 2125 } 2126 } 2128 Figure 20: Example of a Configuration Response Body 2130 4.5.2. Convey DOTS Signal Channel Session Configuration 2132 A PUT request (Figures 21 and 22) is used to convey the configuration 2133 parameters for the signal channel (e.g., heartbeat interval, maximum 2134 retransmissions). Message transmission parameters for CoAP are 2135 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 2136 transmission parameter values are ack-timeout (2 seconds), max- 2137 retransmit (3), and ack-random-factor (1.5). In addition to those 2138 parameters, the RECOMMENDED specific DOTS transmission parameter 2139 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 2140 (15). 2142 Note: heartbeat-interval should be tweaked to also assist DOTS 2143 messages for NAT traversal (SIG-011 of [RFC8612]). According to 2144 [RFC8085], heartbeat messages must not be sent more frequently 2145 than once every 15 seconds and should use longer intervals when 2146 possible. Furthermore, [RFC4787] recommends NATs to use a state 2147 timeout of 2 minutes or longer, but experience shows that sending 2148 packets every 15 to 30 seconds is necessary to prevent the 2149 majority of middleboxes from losing state for UDP flows. From 2150 that standpoint, the RECOMMENDED minimum heartbeat-interval is 15 2151 seconds and the RECOMMENDED maximum heartbeat-interval is 240 2152 seconds. The recommended value of 30 seconds is selected to 2153 anticipate the expiry of NAT state. 2155 A heartbeat-interval of 30 seconds may be considered as too chatty 2156 in some deployments. For such deployments, DOTS agents may 2157 negotiate longer heartbeat-interval values to prevent any network 2158 overload with too frequent heartbeats. 2160 Different heartbeat intervals can be defined for 'mitigating- 2161 config' and 'idle-config' to reduce being too chatty during idle 2162 times. If there is an on-path translator between the DOTS client 2163 (standalone or part of a DOTS gateway) and the DOTS server, the 2164 'mitigating-config' heartbeat-interval has to be smaller than the 2165 translator session timeout. It is recommended that the 'idle- 2166 config' heartbeat-interval is also smaller than the translator 2167 session timeout to prevent translator traversal issues, or 2168 disabled entirely. Means to discover the lifetime assigned by a 2169 translator are out of scope. 2171 Given that the size of the heartbeat request can not exceed 2172 (heartbeat-interval * probing-rate) bytes, probing-rate should be 2173 set appropriately to avoid slowing down heartbeat exchanges. For 2174 example, probing-rate may be set to 2 * ("size of encrypted DOTS 2175 heartbeat request"/heartbeat-interval) or (("size of encrypted 2176 DOTS heartbeat request" + "average size of an encrypted mitigation 2177 request")/heartbeat-interval). Absent any explicit configuration 2178 or inability to dynamically adjust probing-rate values 2179 (Section 4.8.1 of [RFC7252]), DOTS agents use 5 bytes/second as a 2180 default probing-rate value. 2182 If the DOTS agent wishes to change the default values of message 2183 transmission parameters, it SHOULD follow the guidance given in 2184 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2185 values for message transmission parameters and default values for 2186 non-negotiated message transmission parameters. 2188 The signal channel session configuration is applicable to a single 2189 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2190 Path MUST NOT be used. 2192 Header: PUT (Code=0.03) 2193 Uri-Path: ".well-known" 2194 Uri-Path: "dots" 2195 Uri-Path: "config" 2196 Uri-Path: "sid=123" 2197 Content-Format: "application/dots+cbor" 2199 { 2200 ... 2201 } 2203 Figure 21: PUT to Convey the DOTS Signal Channel Session 2204 Configuration Data 2206 The additional Uri-Path parameter to those defined in Table 1 is as 2207 follows: 2209 sid: Session Identifier is an identifier for the DOTS signal channel 2210 session configuration data represented as an integer. This 2211 identifier MUST be generated by DOTS clients. 'sid' values MUST 2212 increase monotonically (when a new PUT is generated by a DOTS 2213 client to convey the configuration parameters for the signal 2214 channel). 2216 This is a mandatory attribute. 2218 { 2219 "ietf-dots-signal-channel:signal-config": { 2220 "mitigating-config": { 2221 "heartbeat-interval": { 2222 "current-value": number 2223 }, 2224 "missing-hb-allowed": { 2225 "current-value": number 2226 }, 2227 "probing-rate": { 2228 "current-value": number 2229 }, 2230 "max-retransmit": { 2231 "current-value": number 2232 }, 2233 "ack-timeout": { 2234 "current-value-decimal": "string" 2235 }, 2236 "ack-random-factor": { 2237 "current-value-decimal": "string" 2238 } 2239 }, 2240 "idle-config": { 2241 "heartbeat-interval": { 2242 "current-value": number 2243 }, 2244 "missing-hb-allowed": { 2245 "current-value": number 2246 }, 2247 "probing-rate": { 2248 "current-value": number 2249 }, 2250 "max-retransmit": { 2251 "current-value": number 2252 }, 2253 "ack-timeout": { 2254 "current-value-decimal": "string" 2255 }, 2256 "ack-random-factor": { 2257 "current-value-decimal": "string" 2258 } 2259 } 2260 } 2261 } 2263 Figure 22: PUT to Convey the DOTS Signal Channel Session 2264 Configuration Data (Message Body Schema) 2266 The meaning of the parameters in the CBOR body (Figure 22) is defined 2267 in Section 4.5.1. 2269 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2270 allowed', 'probing-rate', 'max-retransmit', 'ack-timeout', and 'ack- 2271 random-factor' MUST be present in the PUT request. Note that 2272 'heartbeat-interval', 'missing-hb-allowed', 'probing-rate', 'max- 2273 retransmit', 'ack-timeout', and 'ack-random-factor', if present, do 2274 not need to be provided for both 'mitigating-config', and 'idle- 2275 config' in a PUT request. 2277 The PUT request with a higher numeric 'sid' value overrides the DOTS 2278 signal channel session configuration data installed by a PUT request 2279 with a lower numeric 'sid' value. To avoid maintaining a long list 2280 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2281 automatically deleted and no longer available at the DOTS server. 2283 Figure 23 shows a PUT request example to convey the configuration 2284 parameters for the DOTS signal channel. In this example, the 2285 heartbeat mechanism is disabled when no mitigation is active, while 2286 the heartbeat interval is set to '30' when a mitigation is active. 2288 Header: PUT (Code=0.03) 2289 Uri-Path: ".well-known" 2290 Uri-Path: "dots" 2291 Uri-Path: "config" 2292 Uri-Path: "sid=123" 2293 Content-Format: "application/dots+cbor" 2295 { 2296 "ietf-dots-signal-channel:signal-config": { 2297 "mitigating-config": { 2298 "heartbeat-interval": { 2299 "current-value": 30 2300 }, 2301 "missing-hb-allowed": { 2302 "current-value": 15 2303 }, 2304 "probing-rate": { 2305 "current-value": 15 2306 }, 2307 "max-retransmit": { 2308 "current-value": 3 2309 }, 2310 "ack-timeout": { 2311 "current-value-decimal": "2.00" 2312 }, 2313 "ack-random-factor": { 2314 "current-value-decimal": "1.50" 2315 } 2316 }, 2317 "idle-config": { 2318 "heartbeat-interval": { 2319 "current-value": 0 2320 }, 2321 "max-retransmit": { 2322 "current-value": 3 2323 }, 2324 "ack-timeout": { 2325 "current-value-decimal": "2.00" 2326 }, 2327 "ack-random-factor": { 2328 "current-value-decimal": "1.50" 2329 } 2330 } 2331 } 2332 } 2334 Figure 23: PUT to Convey the Configuration Parameters 2336 The DOTS server indicates the result of processing the PUT request 2337 using CoAP response codes: 2339 o If the request is missing a mandatory attribute, does not include 2340 a 'sid' Uri-Path, or contains one or more invalid or unknown 2341 parameters, 4.00 (Bad Request) MUST be returned in the response. 2343 o If the DOTS server does not find the 'sid' parameter value 2344 conveyed in the PUT request in its configuration data and if the 2345 DOTS server has accepted the configuration parameters, then a 2346 response code 2.01 (Created) MUST be returned in the response. 2348 o If the DOTS server finds the 'sid' parameter value conveyed in the 2349 PUT request in its configuration data and if the DOTS server has 2350 accepted the updated configuration parameters, 2.04 (Changed) MUST 2351 be returned in the response. 2353 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 2354 'probing-rate', 'max-retransmit', 'target-protocol', 'ack- 2355 timeout', and 'ack-random-factor' attribute values are not 2356 acceptable to the DOTS server, 4.22 (Unprocessable Entity) MUST be 2357 returned in the response. Upon receipt of this error code, the 2358 DOTS client SHOULD retrieve the maximum and minimum attribute 2359 values acceptable to the DOTS server (Section 4.5.1). 2361 The DOTS client may re-try and send the PUT request with updated 2362 attribute values acceptable to the DOTS server. 2364 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2365 to retrieve the negotiated configuration. The response does not need 2366 to include 'sid' in its message body. 2368 4.5.3. Configuration Freshness and Notifications 2370 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2371 DOTS server to associate a validity time with a configuration it 2372 sends. This feature allows the update of the configuration data if a 2373 change occurs at the DOTS server side. For example, the new 2374 configuration may instruct a DOTS client to cease heartbeats or 2375 reduce heartbeat frequency. 2377 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2379 Returning a Max-Age Option set to 2**32-1 is equivalent to 2380 associating an infinite lifetime with the configuration. 2382 If a non-zero value of Max-Age Option is received by a DOTS client, 2383 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2384 the current and acceptable configuration before the expiry of the 2385 value enclosed in the Max-Age option. This request is considered by 2386 the client and the server as a means to refresh the configuration 2387 parameters for the signal channel. When a DDoS attack is active, 2388 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2389 MUST NOT terminate the (D)TLS session after the expiry of the value 2390 returned in Max-Age Option. 2392 If Max-Age Option is not returned in a response, the DOTS client 2393 initiates GET requests to refresh the configuration parameters each 2394 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2395 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2396 responses. Considerations related to which value to use and how such 2397 value is set, are implementation- and deployment-specific. 2399 If an Observe Option set to 0 is included in the configuration 2400 request, the DOTS server sends notifications of any configuration 2401 change (Section 4.2 of [RFC7641]). 2403 If a DOTS server detects that a misbehaving DOTS client does not 2404 contact the DOTS server after the expiry of Max-Age and retrieve the 2405 signal channel configuration data, it MAY terminate the (D)TLS 2406 session. A (D)TLS session is terminated by the receipt of an 2407 authenticated message that closes the connection (e.g., a fatal alert 2408 (Section 6 of [RFC8446])). 2410 4.5.4. Delete DOTS Signal Channel Session Configuration 2412 A DELETE request is used to delete the installed DOTS signal channel 2413 session configuration data (Figure 24). 2415 Header: DELETE (Code=0.04) 2416 Uri-Path: ".well-known" 2417 Uri-Path: "dots" 2418 Uri-Path: "config" 2419 Uri-Path: "sid=123" 2421 Figure 24: Delete Configuration 2423 The DOTS server resets the DOTS signal channel session configuration 2424 back to the default values and acknowledges a DOTS client's request 2425 to remove the DOTS signal channel session configuration using 2.02 2426 (Deleted) response code. 2428 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2429 to set the configuration parameters to default values. Such a 2430 request does not include any 'sid'. 2432 4.6. Redirected Signaling 2434 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2435 [I-D.ietf-dots-architecture]. 2437 If a DOTS server wants to redirect a DOTS client to an alternative 2438 DOTS server for a signal session, then the response code 5.03 2439 (Service Unavailable) will be returned in the response to the DOTS 2440 client. 2442 The DOTS server can return the error response code 5.03 in response 2443 to a request from the DOTS client or convey the error response code 2444 5.03 in a unidirectional notification response from the DOTS server. 2446 The DOTS server in the error response conveys the alternate DOTS 2447 server's FQDN, and the alternate DOTS server's IP address(es) values 2448 in the CBOR body (Figure 25). 2450 { 2451 "ietf-dots-signal-channel:redirected-signal": { 2452 "alt-server": "string", 2453 "alt-server-record": [ 2454 "string" 2455 ] 2456 } 2458 Figure 25: Redirected Server Error Response Body Schema 2460 The parameters are described below: 2462 alt-server: FQDN of an alternate DOTS server. 2464 This is a mandatory attribute. 2466 alt-server-record: A list of IP addresses of an alternate DOTS 2467 server. 2469 This is an optional attribute. 2471 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2472 server in a Max-Age Option. That is, the time interval that the 2473 alternate DOTS server may be cached for use by a DOTS client. A Max- 2474 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2475 This value means that the alternate DOTS server is to be used until 2476 the alternate DOTS server redirects the traffic with another 5.03 2477 response which encloses an alternate server. 2479 A Max-Age Option set to '0' may be returned for redirecting 2480 mitigation requests. Such value means that the redirection applies 2481 only for the mitigation request in progress. Returning short TTL in 2482 a Max-Age Option may adversely impact DOTS clients on slow links. 2483 Returning short values should be avoided under such conditions. 2485 If the alternate DOTS server TTL has expired, the DOTS client MUST 2486 use the DOTS server(s), that was provisioned using means discussed in 2487 Section 4.1. This fall back mechanism is triggered immediately upon 2488 expiry of the TTL, except when a DDoS attack is active. 2490 Requests issued by misbehaving DOTS clients which do not honor the 2491 TTL conveyed in the Max-Age Option or react to explicit re-direct 2492 messages can be rejected by DOTS servers. 2494 Figure 26 shows a 5.03 response example to convey the DOTS alternate 2495 server 'alt-server.example' together with its IP addresses 2496 2001:db8:6401::1 and 2001:db8:6401::2. 2498 { 2499 "ietf-dots-signal-channel:redirected-signal": { 2500 "alt-server": "alt-server.example", 2501 "alt-server-record": [ 2502 "2001:db8:6401::1", 2503 "2001:db8:6401::2" 2504 ] 2505 } 2507 Figure 26: Example of Redirected Server Error Response Body 2509 When the DOTS client receives 5.03 response with an alternate server 2510 included, it considers the current request as failed, but SHOULD try 2511 re-sending the request to the alternate DOTS server. During a DDoS 2512 attack, the DNS server may be the target of another DDoS attack, 2513 alternate DOTS server's IP addresses conveyed in the 5.03 response 2514 help the DOTS client skip DNS lookup of the alternate DOTS server, at 2515 the cost of trusting the first DOTS server to provide accurate 2516 information. The DOTS client can then try to establish a UDP or a 2517 TCP session with the alternate DOTS server. The DOTS client MAY 2518 implement a method to construct IPv4-embedded IPv6 addresses 2519 [RFC6052]; this is required to handle the scenario where an IPv6-only 2520 DOTS client communicates with an IPv4-only alternate DOTS server. 2522 If the DOTS client has been redirected to a DOTS server to which it 2523 has already communicated with within the last five (5) minutes, it 2524 MUST ignore the redirection and try to contact other DOTS servers 2525 listed in the local configuration or discovered using dynamic means 2526 such as DHCP or SRV procedures [I-D.ietf-dots-server-discovery]. It 2527 is RECOMMENDED that DOTS clients support means to alert 2528 administrators about redirect loops. 2530 4.7. Heartbeat Mechanism 2532 To provide an indication of signal health and distinguish an 'idle' 2533 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2534 agent sends a heartbeat over the signal channel to maintain its half 2535 of the channel (also, aligned with the "consents" recommendation in 2536 Section 6 of [RFC8085]). The DOTS agent similarly expects a 2537 heartbeat from its peer DOTS agent, and may consider a session 2538 terminated in the prolonged absence of a peer agent heartbeat. 2539 Concretely, while the communication between the DOTS agents is 2540 otherwise quiescent, the DOTS client will probe the DOTS server to 2541 ensure it has maintained cryptographic state and vice versa. Such 2542 probes can also keep firewalls and/or stateful translators bindings 2543 alive. This probing reduces the frequency of establishing a new 2544 handshake when a DOTS signal needs to be conveyed to the DOTS server. 2546 Implementation Note: Given that CoAP roles can be multiplexed over 2547 the same session as discussed in [RFC7252] and already supported 2548 by CoAP implementations, both the DOTS client and server can send 2549 DOTS heartbeat requests. 2551 The DOTS Heartbeat mechanism uses non-confirmable PUT requests 2552 (Figure 27) with an expected 2.04 (Changed) Response Code 2553 (Figure 28). This procedure occurs between a DOTS agent and its 2554 immediate peer DOTS agent. As such, this PUT request MUST NOT be 2555 relayed by a DOTS gateway. The PUT request used for DOTS heartbeat 2556 MUST NOT have a 'cuid', 'cdid,' or 'mid' Uri-Path. 2558 Header: PUT (Code=0.03) 2559 Uri-Path: ".well-known" 2560 Uri-Path: "dots" 2561 Uri-Path: "hb" 2562 Content-Format: "application/dots+cbor" 2564 { 2565 "ietf-dots-signal-channel:heartbeat": { 2566 "peer-hb-status": true 2567 } 2568 } 2570 Figure 27: PUT to Check Peer DOTS Agent is Responding 2572 The mandatory 'peer-hb-status' attribute is set to 'true' (or 2573 'false') to indicates that a DOTS agent is (or not) receiving 2574 heartbeat messages from its peer in the last (2 * heartbeat-interval) 2575 period. Such information can be used by a peer DOTS agent to detect 2576 or confirm connectivity issues and react accordingly. For example, 2577 if a DOTS client receives 2.04 response for its heartbeat messages 2578 but no server-initiated heartbeat messages, the DOTS client sets 2579 'peer-hb-status' to 'false'. The DOTS server will need then to try 2580 another strategy for sending the heartbeats (e.g., adjust the 2581 heartbeat interval or send a server-initiated heartbeat immediately 2582 after receiving a client-initiated heartbeat message). 2584 Header: (Code=2.04) 2586 Figure 28: Response to a DOTS Heartbeat Request 2588 DOTS servers MAY trigger their heartbeat requests immediately after 2589 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2590 is the responsibility of DOTS clients to ensure that on-path 2591 translators/firewalls are maintaining a binding so that the same 2592 external IP address and/or port number is retained for the DOTS 2593 signal channel session. 2595 Under normal traffic conditions (i.e., no attack is ongoing), if a 2596 DOTS agent does not receive any response from the peer DOTS agent for 2597 'missing-hb-allowed' number of consecutive heartbeat messages, it 2598 concludes that the DOTS signal channel session is disconnected. The 2599 DOTS client MUST then try to re-establish the DOTS signal channel 2600 session, preferably by resuming the (D)TLS session. 2602 Note: If a new DOTS signal channel session cannot be established, 2603 the DOTS client SHOULD NOT retry to establish the DOTS signal 2604 channel session more frequently than every 300 seconds (5 minutes) 2605 and MUST NOT retry more frequently than every 60 seconds (1 2606 minute). It is recommended that DOTS clients support means to 2607 alert administrators about the failure to establish a (D)TLS 2608 session. 2610 In case of a massive DDoS attack that saturates the incoming link(s) 2611 to the DOTS client, all traffic from the DOTS server to the DOTS 2612 client will likely be dropped, although the DOTS server receives 2613 heartbeat requests in addition to DOTS messages sent by the DOTS 2614 client. In this scenario, DOTS clients MUST behave differently to 2615 handle message transmission and DOTS signal channel session 2616 liveliness during link saturation: 2618 The DOTS client MUST NOT consider the DOTS signal channel session 2619 terminated even after a maximum 'missing-hb-allowed' threshold is 2620 reached. The DOTS client SHOULD keep on using the current DOTS 2621 signal channel session to send heartbeat requests over it, so that 2622 the DOTS server knows the DOTS client has not disconnected the 2623 DOTS signal channel session. 2625 After the maximum 'missing-hb-allowed' threshold is reached, the 2626 DOTS client SHOULD try to establish a new DOTS signal channel 2627 session. The DOTS client SHOULD send mitigation requests over the 2628 current DOTS signal channel session and, in parallel, send the 2629 mitigation requests over the new DOTS signal channel session. 2630 This may be handled, for example, by resumption of the (D)TLS 2631 session or using 0-RTT mode in DTLS 1.3 to piggyback the 2632 mitigation request in the ClientHello message. 2634 As soon as the link is no longer saturated, if traffic from the 2635 DOTS server reaches the DOTS client over the current DOTS signal 2636 channel session, the DOTS client can stop the new DOTS signal 2637 channel session attempt or if a new DOTS signal channel session is 2638 successful then disconnect the current DOTS signal channel 2639 session. 2641 If the DOTS server receives traffic from the peer DOTS client (e.g., 2642 peer DOTS client initiated heartbeats) but maximum 'missing-hb- 2643 allowed' threshold is reached, the DOTS server MUST NOT consider the 2644 DOTS signal channel session disconnected. The DOTS server MUST keep 2645 on using the current DOTS signal channel session so that the DOTS 2646 client can send mitigation requests over the current DOTS signal 2647 channel session. In this case, the DOTS server can identify the DOTS 2648 client is under attack and the inbound link to the DOTS client 2649 (domain) is saturated. Furthermore, if the DOTS server does not 2650 receive a mitigation request from the DOTS client, it implies the 2651 DOTS client has not detected the attack or, if an attack mitigation 2652 is in progress, it implies the applied DDoS mitigation actions are 2653 not yet effective to handle the DDoS attack volume. 2655 If the DOTS server does not receive any traffic from the peer DOTS 2656 client during the time span required to exhaust the maximum 'missing- 2657 hb-allowed' threshold, the DOTS server concludes the session is 2658 disconnected. The DOTS server can then trigger pre-configured 2659 mitigation requests for this DOTS client (if any). 2661 In DOTS over TCP, the sender of a DOTS heartbeat message has to allow 2662 up to 'heartbeat-interval' seconds when waiting for a heartbeat 2663 reply. When a failure is detected by a DOTS client, it proceeds with 2664 the session recovery following the same approach as the one used for 2665 unreliable transports. 2667 5. DOTS Signal Channel YANG Modules 2669 This document defines a YANG [RFC7950] module for DOTS mitigation 2670 scope, DOTS signal channel session configuration data, DOTS 2671 redirection signaling, and DOTS heartbeats. 2673 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2674 interaction with the DOTS server as seen by the DOTS client. A DOTS 2675 server is allowed to update the non-configurable 'ro' entities in the 2676 responses. This YANG module is not intended to be used via NETCONF/ 2677 RESTCONF for DOTS server management purposes; such module is out of 2678 the scope of this document. It serves only to provide a data model 2679 and encoding, but not a management data model. 2681 A companion YANG module is defined to include a collection of types 2682 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2684 5.1. Tree Structure 2686 This document defines the YANG module "ietf-dots-signal-channel" 2687 (Section 5.3), which has the following tree structure. A DOTS signal 2688 message can be a mitigation, a configuration, a redirect, or a 2689 heartbeat message. 2691 module: ietf-dots-signal-channel 2692 +--rw dots-signal 2693 +--rw (message-type)? 2694 +--:(mitigation-scope) 2695 | +--rw scope* [cuid mid] 2696 | +--rw cdid? string 2697 | +--rw cuid string 2698 | +--rw mid uint32 2699 | +--rw target-prefix* inet:ip-prefix 2700 | +--rw target-port-range* [lower-port] 2701 | | +--rw lower-port inet:port-number 2702 | | +--rw upper-port? inet:port-number 2703 | +--rw target-protocol* uint8 2704 | +--rw target-fqdn* inet:domain-name 2705 | +--rw target-uri* inet:uri 2706 | +--rw alias-name* string 2707 | +--rw lifetime? int32 2708 | +--rw trigger-mitigation? boolean 2709 | +--ro mitigation-start? uint64 2710 | +--ro status? iana-signal:status 2711 | +--ro conflict-information 2712 | | +--ro conflict-status? iana-signal:conflict-status 2713 | | +--ro conflict-cause? iana-signal:conflict-cause 2714 | | +--ro retry-timer? uint32 2715 | | +--ro conflict-scope 2716 | | +--ro target-prefix* inet:ip-prefix 2717 | | +--ro target-port-range* [lower-port] 2718 | | | +--ro lower-port inet:port-number 2719 | | | +--ro upper-port? inet:port-number 2720 | | +--ro target-protocol* uint8 2721 | | +--ro target-fqdn* inet:domain-name 2722 | | +--ro target-uri* inet:uri 2723 | | +--ro alias-name* string 2724 | | +--ro acl-list* [acl-name] 2725 | | | +--ro acl-name 2726 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2727 | | | | acl/name 2728 | | | +--ro acl-type? 2729 | | | -> /ietf-data:dots-data/dots-client/acls/ 2730 | | | acl/type 2731 | | +--ro mid? -> ../../../mid 2732 | +--ro bytes-dropped? yang:zero-based-counter64 2733 | +--ro bps-dropped? yang:gauge64 2734 | +--ro pkts-dropped? yang:zero-based-counter64 2735 | +--ro pps-dropped? yang:gauge64 2736 | +--rw attack-status? iana-signal:attack-status 2737 +--:(signal-config) 2738 | +--rw sid uint32 2739 | +--rw mitigating-config 2740 | | +--rw heartbeat-interval 2741 | | | +--ro max-value? uint16 2742 | | | +--ro min-value? uint16 2743 | | | +--rw current-value? uint16 2744 | | +--rw missing-hb-allowed 2745 | | | +--ro max-value? uint16 2746 | | | +--ro min-value? uint16 2747 | | | +--rw current-value? uint16 2748 | | +--rw probing-rate 2749 | | | +--ro max-value? uint16 2750 | | | +--ro min-value? uint16 2751 | | | +--rw current-value? uint16 2752 | | +--rw max-retransmit 2753 | | | +--ro max-value? uint16 2754 | | | +--ro min-value? uint16 2755 | | | +--rw current-value? uint16 2756 | | +--rw ack-timeout 2757 | | | +--ro max-value-decimal? decimal64 2758 | | | +--ro min-value-decimal? decimal64 2759 | | | +--rw current-value-decimal? decimal64 2760 | | +--rw ack-random-factor 2761 | | +--ro max-value-decimal? decimal64 2762 | | +--ro min-value-decimal? decimal64 2763 | | +--rw current-value-decimal? decimal64 2764 | +--rw idle-config 2765 | +--rw heartbeat-interval 2766 | | +--ro max-value? uint16 2767 | | +--ro min-value? uint16 2768 | | +--rw current-value? uint16 2769 | +--rw missing-hb-allowed 2770 | | +--ro max-value? uint16 2771 | | +--ro min-value? uint16 2772 | | +--rw current-value? uint16 2773 | +--rw probing-rate 2774 | | +--ro max-value? uint16 2775 | | +--ro min-value? uint16 2776 | | +--rw current-value? uint16 2777 | +--rw max-retransmit 2778 | | +--ro max-value? uint16 2779 | | +--ro min-value? uint16 2780 | | +--rw current-value? uint16 2781 | +--rw ack-timeout 2782 | | +--ro max-value-decimal? decimal64 2783 | | +--ro min-value-decimal? decimal64 2784 | | +--rw current-value-decimal? decimal64 2785 | +--rw ack-random-factor 2786 | +--ro max-value-decimal? decimal64 2787 | +--ro min-value-decimal? decimal64 2788 | +--rw current-value-decimal? decimal64 2789 +--:(redirected-signal) 2790 | +--ro alt-server string 2791 | +--ro alt-server-record* inet:ip-address 2792 +--:(heartbeat) 2793 +--rw peer-hb-status boolean 2795 5.2. IANA DOTS Signal Channel YANG Module 2797 file "iana-dots-signal-channel@2019-01-17.yang" 2798 module iana-dots-signal-channel { 2799 yang-version 1.1; 2800 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2801 prefix iana-signal; 2803 organization 2804 "IANA"; 2805 contact 2806 "Internet Assigned Numbers Authority 2808 Postal: ICANN 2809 12025 Waterfront Drive, Suite 300 2810 Los Angeles, CA 90094-2536 2811 United States of America 2812 Tel: +1 310 301 5800 2813 "; 2814 description 2815 "This module contains a collection of YANG data types defined 2816 by IANA and used for DOTS signal channel protocol. 2818 Copyright (c) 2019 IETF Trust and the persons identified as 2819 authors of the code. All rights reserved. 2821 Redistribution and use in source and binary forms, with or 2822 without modification, is permitted pursuant to, and subject 2823 to the license terms contained in, the Simplified BSD License 2824 set forth in Section 4.c of the IETF Trust's Legal Provisions 2825 Relating to IETF Documents 2826 (http://trustee.ietf.org/license-info). 2828 This version of this YANG module is part of RFC XXXX; see 2829 the RFC itself for full legal notices."; 2831 revision 2019-01-17 { 2832 description 2833 "Initial revision."; 2834 reference 2835 "RFC XXXX: Distributed Denial-of-Service Open Threat 2836 Signaling (DOTS) Signal Channel Specification"; 2837 } 2839 typedef status { 2840 type enumeration { 2841 enum attack-mitigation-in-progress { 2842 value 1; 2843 description 2844 "Attack mitigation setup is in progress (e.g., changing 2845 the network path to re-route the inbound traffic 2846 to DOTS mitigator)."; 2847 } 2848 enum attack-successfully-mitigated { 2849 value 2; 2850 description 2851 "Attack is being successfully mitigated (e.g., traffic 2852 is redirected to a DDoS mitigator and attack 2853 traffic is dropped or blackholed)."; 2854 } 2855 enum attack-stopped { 2856 value 3; 2857 description 2858 "Attack has stopped and the DOTS client can 2859 withdraw the mitigation request."; 2860 } 2861 enum attack-exceeded-capability { 2862 value 4; 2863 description 2864 "Attack has exceeded the mitigation provider 2865 capability."; 2866 } 2867 enum dots-client-withdrawn-mitigation { 2868 value 5; 2869 description 2870 "DOTS client has withdrawn the mitigation 2871 request and the mitigation is active but 2872 terminating."; 2873 } 2874 enum attack-mitigation-terminated { 2875 value 6; 2876 description 2877 "Attack mitigation is now terminated."; 2878 } 2879 enum attack-mitigation-withdrawn { 2880 value 7; 2881 description 2882 "Attack mitigation is withdrawn."; 2883 } 2884 enum attack-mitigation-signal-loss { 2885 value 8; 2886 description 2887 "Attack mitigation will be triggered 2888 for the mitigation request only when 2889 the DOTS signal channel session is lost."; 2890 } 2891 } 2892 description 2893 "Enumeration for status reported by the DOTS server."; 2894 } 2896 typedef conflict-status { 2897 type enumeration { 2898 enum request-inactive-other-active { 2899 value 1; 2900 description 2901 "DOTS Server has detected conflicting mitigation 2902 requests from different DOTS clients. 2903 This mitigation request is currently inactive 2904 until the conflicts are resolved. Another 2905 mitigation request is active."; 2906 } 2907 enum request-active { 2908 value 2; 2909 description 2910 "DOTS Server has detected conflicting mitigation 2911 requests from different DOTS clients. 2912 This mitigation request is currently active."; 2913 } 2914 enum all-requests-inactive { 2915 value 3; 2916 description 2917 "DOTS Server has detected conflicting mitigation 2918 requests from different DOTS clients. All 2919 conflicting mitigation requests are inactive."; 2920 } 2921 } 2922 description 2923 "Enumeration for conflict status."; 2924 } 2926 typedef conflict-cause { 2927 type enumeration { 2928 enum overlapping-targets { 2929 value 1; 2930 description 2931 "Overlapping targets. conflict-scope provides 2932 more details about the exact conflict."; 2933 } 2934 enum conflict-with-acceptlist { 2935 value 2; 2936 description 2937 "Conflicts with an existing accept-list. 2939 This code is returned when the DDoS mitigation 2940 detects that some of the source addresses/prefixes 2941 listed in the accept-list ACLs are actually 2942 attacking the target."; 2943 } 2944 enum cuid-collision { 2945 value 3; 2946 description 2947 "Conflicts with the cuid used by another 2948 DOTS client."; 2949 } 2950 } 2951 description 2952 "Enumeration for conflict causes."; 2953 } 2954 typedef attack-status { 2955 type enumeration { 2956 enum under-attack { 2957 value 1; 2958 description 2959 "The DOTS client determines that it is still under 2960 attack."; 2961 } 2962 enum attack-successfully-mitigated { 2963 value 2; 2964 description 2965 "The DOTS client determines that the attack is 2966 successfully mitigated."; 2967 } 2968 } 2969 description 2970 "Enumeration for attack status codes."; 2971 } 2972 } 2973 2975 5.3. IETF DOTS Signal Channel YANG Module 2977 This module uses the common YANG types defined in [RFC6991] and types 2978 defined in [I-D.ietf-dots-data-channel]. 2980 file "ietf-dots-signal-channel@2019-11-13.yang" 2981 module ietf-dots-signal-channel { 2982 yang-version 1.1; 2983 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2984 prefix signal; 2986 import ietf-inet-types { 2987 prefix inet; 2988 reference "Section 4 of RFC 6991"; 2989 } 2990 import ietf-yang-types { 2991 prefix yang; 2992 reference "Section 3 of RFC 6991"; 2993 } 2994 import ietf-dots-data-channel { 2995 prefix ietf-data; 2996 reference 2997 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2998 (DOTS) Data Channel Specification"; 2999 } 3000 import iana-dots-signal-channel { 3001 prefix iana-signal; 3003 } 3005 organization 3006 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3007 contact 3008 "WG Web: 3009 WG List: 3011 Editor: Konda, Tirumaleswar Reddy 3012 3014 Editor: Mohamed Boucadair 3015 3017 Author: Prashanth Patil 3018 3020 Author: Andrew Mortensen 3021 3023 Author: Nik Teague 3024 "; 3025 description 3026 "This module contains YANG definition for the signaling 3027 messages exchanged between a DOTS client and a DOTS server. 3029 Copyright (c) 2019 IETF Trust and the persons identified as 3030 authors of the code. All rights reserved. 3032 Redistribution and use in source and binary forms, with or 3033 without modification, is permitted pursuant to, and subject 3034 to the license terms contained in, the Simplified BSD License 3035 set forth in Section 4.c of the IETF Trust's Legal Provisions 3036 Relating to IETF Documents 3037 (http://trustee.ietf.org/license-info). 3039 This version of this YANG module is part of RFC XXXX; see 3040 the RFC itself for full legal notices."; 3042 revision 2019-11-13 { 3043 description 3044 "Initial revision."; 3045 reference 3046 "RFC XXXX: Distributed Denial-of-Service Open Threat 3047 Signaling (DOTS) Signal Channel Specification"; 3048 } 3050 /* 3051 * Groupings 3052 */ 3054 grouping mitigation-scope { 3055 description 3056 "Specifies the scope of the mitigation request."; 3057 list scope { 3058 key "cuid mid"; 3059 description 3060 "The scope of the request."; 3061 leaf cdid { 3062 type string; 3063 description 3064 "The cdid should be included by a server-domain 3065 DOTS gateway to propagate the client domain 3066 identification information from the 3067 gateway's client-facing-side to the gateway's 3068 server-facing-side, and from the gateway's 3069 server-facing-side to the DOTS server. 3071 It may be used by the final DOTS server 3072 for policy enforcement purposes."; 3073 } 3074 leaf cuid { 3075 type string; 3076 description 3077 "A unique identifier that is 3078 generated by a DOTS client to prevent 3079 request collisions. It is expected that the 3080 cuid will remain consistent throughout the 3081 lifetime of the DOTS client."; 3082 } 3083 leaf mid { 3084 type uint32; 3085 description 3086 "Mitigation request identifier. 3088 This identifier must be unique for each mitigation 3089 request bound to the DOTS client."; 3090 } 3091 uses ietf-data:target; 3092 leaf-list alias-name { 3093 type string; 3094 description 3095 "An alias name that points to a resource."; 3096 } 3097 leaf lifetime { 3098 type int32; 3099 units "seconds"; 3100 default "3600"; 3101 description 3102 "Indicates the lifetime of the mitigation request. 3104 A lifetime of '0' in a mitigation request is an 3105 invalid value. 3107 A lifetime of negative one (-1) indicates indefinite 3108 lifetime for the mitigation request."; 3109 } 3110 leaf trigger-mitigation { 3111 type boolean; 3112 default "true"; 3113 description 3114 "If set to 'false', DDoS mitigation will not be 3115 triggered unless the DOTS signal channel 3116 session is lost."; 3117 } 3118 leaf mitigation-start { 3119 type uint64; 3120 config false; 3121 description 3122 "Mitigation start time is represented in seconds 3123 relative to 1970-01-01T00:00:00Z in UTC time."; 3124 } 3125 leaf status { 3126 type iana-signal:status; 3127 config false; 3128 description 3129 "Indicates the status of a mitigation request. 3130 It must be included in responses only."; 3131 } 3132 container conflict-information { 3133 config false; 3134 description 3135 "Indicates that a conflict is detected. 3136 Must only be used for responses."; 3137 leaf conflict-status { 3138 type iana-signal:conflict-status; 3139 description 3140 "Indicates the conflict status."; 3141 } 3142 leaf conflict-cause { 3143 type iana-signal:conflict-cause; 3144 description 3145 "Indicates the cause of the conflict."; 3146 } 3147 leaf retry-timer { 3148 type uint32; 3149 units "seconds"; 3150 description 3151 "The DOTS client must not re-send the 3152 same request that has a conflict before the expiry of 3153 this timer."; 3154 } 3155 container conflict-scope { 3156 description 3157 "Provides more information about the conflict scope."; 3158 uses ietf-data:target { 3159 when "../conflict-cause = 'overlapping-targets'"; 3160 } 3161 leaf-list alias-name { 3162 when "../../conflict-cause = 'overlapping-targets'"; 3163 type string; 3164 description 3165 "Conflicting alias-name."; 3166 } 3167 list acl-list { 3168 when "../../conflict-cause = 'conflict-with-acceptlist'"; 3169 key "acl-name"; 3170 description 3171 "List of conflicting ACLs as defined in the DOTS data 3172 channel. These ACLs are uniquely defined by 3173 cuid and acl-name."; 3174 leaf acl-name { 3175 type leafref { 3176 path "/ietf-data:dots-data/ietf-data:dots-client/" 3177 + "ietf-data:acls/ietf-data:acl/ietf-data:name"; 3178 } 3179 description 3180 "Reference to the conflicting ACL name bound to 3181 a DOTS client."; 3182 } 3183 leaf acl-type { 3184 type leafref { 3185 path "/ietf-data:dots-data/ietf-data:dots-client/" 3186 + "ietf-data:acls/ietf-data:acl/ietf-data:type"; 3187 } 3188 description 3189 "Reference to the conflicting ACL type bound to 3190 a DOTS client."; 3191 } 3192 } 3193 leaf mid { 3194 when "../../conflict-cause = 'overlapping-targets'"; 3195 type leafref { 3196 path "../../../mid"; 3197 } 3198 description 3199 "Reference to the conflicting 'mid' bound to 3200 the same DOTS client."; 3201 } 3202 } 3203 } 3204 leaf bytes-dropped { 3205 type yang:zero-based-counter64; 3206 units "bytes"; 3207 config false; 3208 description 3209 "The total dropped byte count for the mitigation 3210 request since the attack mitigation is triggered. 3211 The count wraps around when it reaches the maximum value 3212 of counter64 for dropped bytes."; 3213 } 3214 leaf bps-dropped { 3215 type yang:gauge64; 3216 config false; 3217 description 3218 "The average number of dropped bits per second for 3219 the mitigation request since the attack 3220 mitigation is triggered. This should be over 3221 five-minute intervals (that is, measuring bytes 3222 into five-minute buckets and then averaging these 3223 buckets over the time since the mitigation was 3224 triggered)."; 3225 } 3226 leaf pkts-dropped { 3227 type yang:zero-based-counter64; 3228 config false; 3229 description 3230 "The total number of dropped packet count for the 3231 mitigation request since the attack mitigation is 3232 triggered. The count wraps around when it reaches 3233 the maximum value of counter64 for dropped packets."; 3234 } 3235 leaf pps-dropped { 3236 type yang:gauge64; 3237 config false; 3238 description 3239 "The average number of dropped packets per second 3240 for the mitigation request since the attack 3241 mitigation is triggered. This should be over 3242 five-minute intervals (that is, measuring packets 3243 into five-minute buckets and then averaging these 3244 buckets over the time since the mitigation was 3245 triggered)."; 3246 } 3247 leaf attack-status { 3248 type iana-signal:attack-status; 3249 description 3250 "Indicates the status of an attack as seen by the 3251 DOTS client."; 3252 } 3253 } 3254 } 3256 grouping config-parameters { 3257 description 3258 "Subset of DOTS signal channel session configuration."; 3259 container heartbeat-interval { 3260 description 3261 "DOTS agents regularly send heartbeats to each other 3262 after mutual authentication is successfully 3263 completed in order to keep the DOTS signal channel 3264 open."; 3265 leaf max-value { 3266 type uint16; 3267 units "seconds"; 3268 config false; 3269 description 3270 "Maximum acceptable heartbeat-interval value."; 3271 } 3272 leaf min-value { 3273 type uint16; 3274 units "seconds"; 3275 config false; 3276 description 3277 "Minimum acceptable heartbeat-interval value."; 3278 } 3279 leaf current-value { 3280 type uint16; 3281 units "seconds"; 3282 default "30"; 3283 description 3284 "Current heartbeat-interval value. 3286 '0' means that heartbeat mechanism is deactivated."; 3287 } 3288 } 3289 container missing-hb-allowed { 3290 description 3291 "Maximum number of missing heartbeats allowed."; 3292 leaf max-value { 3293 type uint16; 3294 config false; 3295 description 3296 "Maximum acceptable missing-hb-allowed value."; 3297 } 3298 leaf min-value { 3299 type uint16; 3300 config false; 3301 description 3302 "Minimum acceptable missing-hb-allowed value."; 3303 } 3304 leaf current-value { 3305 type uint16; 3306 default "15"; 3307 description 3308 "Current missing-hb-allowed value."; 3309 } 3310 } 3311 container probing-rate { 3312 description 3313 "The limit for sending non-confirmable messages with 3314 no response."; 3315 leaf max-value { 3316 type uint16; 3317 units "byte/second"; 3318 config false; 3319 description 3320 "Maximum acceptable probing-rate value."; 3321 } 3322 leaf min-value { 3323 type uint16; 3324 units "byte/second"; 3325 config false; 3326 description 3327 "Minimum acceptable probing-rate value."; 3328 } 3329 leaf current-value { 3330 type uint16; 3331 units "byte/second"; 3332 default "5"; 3333 description 3334 "Current probing-rate value."; 3335 } 3336 } 3337 container max-retransmit { 3338 description 3339 "Maximum number of retransmissions of a Confirmable 3340 message."; 3341 leaf max-value { 3342 type uint16; 3343 config false; 3344 description 3345 "Maximum acceptable max-retransmit value."; 3346 } 3347 leaf min-value { 3348 type uint16; 3349 config false; 3350 description 3351 "Minimum acceptable max-retransmit value."; 3352 } 3353 leaf current-value { 3354 type uint16; 3355 default "3"; 3356 description 3357 "Current max-retransmit value."; 3358 } 3359 } 3360 container ack-timeout { 3361 description 3362 "Initial retransmission timeout value."; 3363 leaf max-value-decimal { 3364 type decimal64 { 3365 fraction-digits 2; 3366 } 3367 units "seconds"; 3368 config false; 3369 description 3370 "Maximum ack-timeout value."; 3371 } 3372 leaf min-value-decimal { 3373 type decimal64 { 3374 fraction-digits 2; 3375 } 3376 units "seconds"; 3377 config false; 3378 description 3379 "Minimum ack-timeout value."; 3380 } 3381 leaf current-value-decimal { 3382 type decimal64 { 3383 fraction-digits 2; 3384 } 3385 units "seconds"; 3386 default "2"; 3387 description 3388 "Current ack-timeout value."; 3389 } 3390 } 3391 container ack-random-factor { 3392 description 3393 "Random factor used to influence the timing of 3394 retransmissions."; 3395 leaf max-value-decimal { 3396 type decimal64 { 3397 fraction-digits 2; 3398 } 3399 config false; 3400 description 3401 "Maximum acceptable ack-random-factor value."; 3402 } 3403 leaf min-value-decimal { 3404 type decimal64 { 3405 fraction-digits 2; 3406 } 3407 config false; 3408 description 3409 "Minimum acceptable ack-random-factor value."; 3410 } 3411 leaf current-value-decimal { 3412 type decimal64 { 3413 fraction-digits 2; 3414 } 3415 default "1.5"; 3416 description 3417 "Current ack-random-factor value."; 3418 } 3419 } 3420 } 3422 grouping signal-config { 3423 description 3424 "DOTS signal channel session configuration."; 3425 leaf sid { 3426 type uint32; 3427 mandatory true; 3428 description 3429 "An identifier for the DOTS signal channel 3430 session configuration data."; 3431 } 3432 container mitigating-config { 3433 description 3434 "Configuration parameters to use when a mitigation 3435 is active."; 3436 uses config-parameters; 3437 } 3438 container idle-config { 3439 description 3440 "Configuration parameters to use when no mitigation 3441 is active."; 3442 uses config-parameters; 3443 } 3444 } 3446 grouping redirected-signal { 3447 description 3448 "Grouping for the redirected signaling."; 3449 leaf alt-server { 3450 type string; 3451 config false; 3452 mandatory true; 3453 description 3454 "FQDN of an alternate server."; 3455 } 3456 leaf-list alt-server-record { 3457 type inet:ip-address; 3458 config false; 3459 description 3460 "List of records for the alternate server."; 3461 } 3462 } 3464 /* 3465 * Main Container for DOTS Signal Channel 3466 */ 3468 container dots-signal { 3469 description 3470 "Main container for DOTS signal message. 3472 A DOTS signal message can be a mitigation, a configuration, 3473 or a redirected signal message."; 3474 choice message-type { 3475 description 3476 "Can be a mitigation, a configuration, or a redirect 3477 message."; 3478 case mitigation-scope { 3479 description 3480 "Mitigation scope of a mitigation message."; 3481 uses mitigation-scope; 3482 } 3483 case signal-config { 3484 description 3485 "Configuration message."; 3486 uses signal-config; 3487 } 3488 case redirected-signal { 3489 description 3490 "Redirected signaling."; 3491 uses redirected-signal; 3492 } 3493 case heartbeat { 3494 description 3495 "DOTS heartbeats."; 3496 leaf peer-hb-status { 3497 type boolean; 3498 mandatory true; 3499 description 3500 "Indicates whether a DOTS agent receives heartbeats 3501 from its peer. The value is set to 'true' if the 3502 DOTS agent is receiving heartbeat messages 3503 from its peer."; 3504 } 3505 } 3506 } 3507 } 3508 } 3509 3511 6. YANG/JSON Mapping Parameters to CBOR 3513 All parameters in the payload of the DOTS signal channel MUST be 3514 mapped to CBOR types as shown in Table 4 and are assigned an integer 3515 key to save space. 3517 o Note: Implementers must check that the mapping output provided by 3518 their YANG-to-CBOR encoding schemes is aligned with the content of 3519 Table 4. For example, some CBOR and JSON types for enumerations 3520 and the 64-bit quantities can differ depending on the encoder 3521 used. 3523 The CBOR key values are divided into two types: comprehension- 3524 required and comprehension-optional. DOTS agents can safely ignore 3525 comprehension-optional values they don't understand, but cannot 3526 successfully process a request if it contains comprehension-required 3527 values that are not understood. The 4.00 response SHOULD include a 3528 diagnostic payload describing the unknown comprehension-required CBOR 3529 key values. The initial set of CBOR key values defined in this 3530 specification are of type comprehension-required. 3532 +----------------------+-------------+-----+---------------+--------+ 3533 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3534 | | Type | Key | Type & | Type | 3535 | | | | Information | | 3536 +----------------------+-------------+-----+---------------+--------+ 3537 | ietf-dots-signal-cha | | | | | 3538 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3539 | scope | list | 2 | 4 array | Array | 3540 | cdid | string | 3 | 3 text string | String | 3541 | cuid | string | 4 | 3 text string | String | 3542 | mid | uint32 | 5 | 0 unsigned | Number | 3543 | target-prefix | leaf-list | 6 | 4 array | Array | 3544 | | inet: | | | | 3545 | | ip-prefix | | 3 text string | String | 3546 | target-port-range | list | 7 | 4 array | Array | 3547 | lower-port | inet: | | | | 3548 | | port-number| 8 | 0 unsigned | Number | 3549 | upper-port | inet: | | | | 3550 | | port-number| 9 | 0 unsigned | Number | 3551 | target-protocol | leaf-list | 10 | 4 array | Array | 3552 | | uint8 | | 0 unsigned | Number | 3553 | target-fqdn | leaf-list | 11 | 4 array | Array | 3554 | | inet: | | | | 3555 | | domain-name| | 3 text string | String | 3556 | target-uri | leaf-list | 12 | 4 array | Array | 3557 | | inet:uri | | 3 text string | String | 3558 | alias-name | leaf-list | 13 | 4 array | Array | 3559 | | string | | 3 text string | String | 3560 | lifetime | int32 | 14 | 0 unsigned | Number | 3561 | | | | 1 negative | Number | 3562 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3563 | status | enumeration | 16 | 0 unsigned | String | 3564 | conflict-information | container | 17 | 5 map | Object | 3565 | conflict-status | enumeration | 18 | 0 unsigned | String | 3566 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3567 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3568 | conflict-scope | container | 21 | 5 map | Object | 3569 | acl-list | list | 22 | 4 array | Array | 3570 | acl-name | leafref | 23 | 3 text string | String | 3571 | acl-type | leafref | 24 | 3 text string | String | 3572 | bytes-dropped | yang:zero- | | | | 3573 | | based- | | | | 3574 | | counter64 | 25 | 0 unsigned | String | 3575 | bps-dropped | yang:gauge64| 26 | 0 unsigned | String | 3576 | pkts-dropped | yang:zero- | | | | 3577 | | based- | | | | 3578 | | counter64 | 27 | 0 unsigned | String | 3579 | pps-dropped | yang:gauge64| 28 | 0 unsigned | String | 3580 | attack-status | enumeration | 29 | 0 unsigned | String | 3581 | ietf-dots-signal- | | | | | 3582 | channel:signal-config| container | 30 | 5 map | Object | 3583 | sid | uint32 | 31 | 0 unsigned | Number | 3584 | mitigating-config | container | 32 | 5 map | Object | 3585 | heartbeat-interval | container | 33 | 5 map | Object | 3586 | max-value | uint16 | 34 | 0 unsigned | Number | 3587 | min-value | uint16 | 35 | 0 unsigned | Number | 3588 | current-value | uint16 | 36 | 0 unsigned | Number | 3589 | missing-hb-allowed | container | 37 | 5 map | Object | 3590 | max-retransmit | container | 38 | 5 map | Object | 3591 | ack-timeout | container | 39 | 5 map | Object | 3592 | ack-random-factor | container | 40 | 5 map | Object | 3593 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3594 | | | | [-2, integer]| String | 3595 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3596 | | | | [-2, integer]| String | 3597 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3598 | | | | [-2, integer]| String | 3599 | idle-config | container | 44 | 5 map | Object | 3600 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3601 | | | | 7 bits 21 | True | 3602 | ietf-dots-signal-cha | | | | | 3603 |nnel:redirected-signal| container | 46 | 5 map | Object | 3604 | alt-server | string | 47 | 3 text string | String | 3605 | alt-server-record | leaf-list | 48 | 4 array | Array | 3606 | | inet: | | | | 3607 | | ip-address | | 3 text string | String | 3608 | ietf-dots-signal-cha | | | | | 3609 | nnel:heartbeat | container | 49 | 5 map | Object | 3610 | probing-rate | container | 50 | 5 map | Object | 3611 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3612 | | | | 7 bits 21 | True | 3613 +----------------------+-------------+-----+---------------+--------+ 3615 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3616 Mappings to JSON and YANG 3618 7. (D)TLS Protocol Profile and Performance Considerations 3620 7.1. (D)TLS Protocol Profile 3622 This section defines the (D)TLS protocol profile of DOTS signal 3623 channel over (D)TLS and DOTS data channel over TLS. 3625 There are known attacks on (D)TLS, such as man-in-the-middle and 3626 protocol downgrade attacks. These are general attacks on (D)TLS and, 3627 as such, they are not specific to DOTS over (D)TLS; refer to the 3628 (D)TLS RFCs for discussion of these security issues. DOTS agents 3629 MUST adhere to the (D)TLS implementation recommendations and security 3630 considerations of [RFC7525] except with respect to (D)TLS version. 3631 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3632 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3633 or later. 3635 When a DOTS client is configured with a domain name of the DOTS 3636 server, and connects to its configured DOTS server, the server may 3637 present it with a PKIX certificate. In order to ensure proper 3638 authentication, a DOTS client MUST verify the entire certification 3639 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3640 validation techniques to compare the domain name with the certificate 3641 provided. Certification authorities that issue DOTS server 3642 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3643 DOTS server SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3644 identifier types in certificate requests (as described in Section 2.3 3645 of [RFC6125]) and the wildcard character '*' SHOULD NOT be included 3646 in the presented identifier. DOTS doesn't use URI-IDs for server 3647 identity verification. 3649 A key challenge to deploying DOTS is the provisioning of DOTS 3650 clients, including the distribution of keying material to DOTS 3651 clients to enable the required mutual authentication of DOTS agents. 3652 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3653 certificate enrollment by which domains operating DOTS servers may 3654 provide DOTS clients with all the necessary cryptographic keying 3655 material, including a private key and a certificate to authenticate 3656 themselves. One deployment option is DOTS clients behave as EST 3657 clients for certificate enrollment from an EST server provisioned by 3658 the mitigation provider. This document does not specify which EST or 3659 other mechanism the DOTS client uses to achieve initial enrollment. 3661 The Server Name Indication (SNI) extension [RFC6066] defines a 3662 mechanism for a client to tell a (D)TLS server the name of the server 3663 it wants to contact. This is a useful extension for hosting 3664 environments where multiple virtual servers are reachable over a 3665 single IP address. The DOTS client may or may not know if it is 3666 interacting with a DOTS server in a virtual server hosting 3667 environment, so the DOTS client SHOULD include the DOTS server FQDN 3668 in the SNI extension. 3670 Implementations compliant with this profile MUST implement all of the 3671 following items: 3673 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3674 equivalent mechanism to protect against replay attacks. 3676 o DTLS session resumption without server-side state to resume 3677 session and convey the DOTS signal. 3679 o At least one of raw public keys [RFC7250] or PSK handshake 3680 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3681 ServerHello, and can be used by DOTS agents that cannot obtain 3682 certificates. 3684 Implementations compliant with this profile SHOULD implement all of 3685 the following items to reduce the delay required to deliver a DOTS 3686 signal channel message: 3688 o TLS False Start [RFC7918] which reduces round-trips by allowing 3689 the TLS client's second flight of messages (ChangeCipherSpec) to 3690 also contain the DOTS signal. TLS False Start is formally defined 3691 for use with TLS, but the same technique is applicable to DTLS as 3692 well. 3694 o Cached Information Extension [RFC7924] which avoids transmitting 3695 the server's certificate and certificate chain if the client has 3696 cached that information from a previous TLS handshake. 3698 Compared to UDP, DOTS signal channel over TCP requires an additional 3699 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3700 implementations are encouraged to implement TCP Fast Open [RFC7413] 3701 to eliminate that RTT. 3703 7.2. (D)TLS 1.3 Considerations 3705 TLS 1.3 provides critical latency improvements for connection 3706 establishment over TLS 1.2. The DTLS 1.3 protocol 3707 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3708 equivalent security guarantees. (D)TLS 1.3 provides two basic 3709 handshake modes the DOTS signal channel can take advantage of: 3711 o A full handshake mode in which a DOTS client can send a DOTS 3712 mitigation request message after one round trip and the DOTS 3713 server immediately responds with a DOTS mitigation response. This 3714 assumes no packet loss is experienced. 3716 o 0-RTT mode in which the DOTS client can authenticate itself and 3717 send DOTS mitigation request messages in the first message, thus 3718 reducing handshake latency. 0-RTT only works if the DOTS client 3719 has previously communicated with that DOTS server, which is very 3720 likely with the DOTS signal channel. 3722 The DOTS client has to establish a (D)TLS session with the DOTS 3723 server during 'idle' time and share a PSK. 3725 During a DDoS attack, the DOTS client can use the (D)TLS session 3726 to convey the DOTS mitigation request message and, if there is no 3727 response from the server after multiple retries, the DOTS client 3728 can resume the (D)TLS session in 0-RTT mode using PSK. 3730 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to 3731 send early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" 3732 as early data; such messages MUST be rejected by DOTS servers. 3733 Section 8 of [RFC8446] discusses some mechanisms to implement to 3734 limit the impact of replay attacks on 0-RTT data. If the DOTS 3735 server accepts 0-RTT, it MUST implement one of these mechanisms to 3736 prevent replay at the TLS layer. A DOTS server can reject 0-RTT 3737 by sending a TLS HelloRetryRequest. 3739 The DOTS signal channel messages sent as early data by the DOTS 3740 client are idempotent requests. As a reminder, the Message ID 3741 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3742 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3743 in each CoAP request. The DOTS server(s) MUST use the Message ID 3744 and the Token in the DOTS signal channel message to detect replay 3745 of early data at the application layer, and accept 0-RTT data at 3746 most once from the same DOTS client. This anti-replay defense 3747 requires sharing the Message ID and the Token in the 0-RTT data 3748 between DOTS servers in the DOTS server domain. DOTS servers do 3749 not rely on transport coordinates to identify DOTS peers. As 3750 specified in Section 4.4.1, DOTS servers couple the DOTS signal 3751 channel sessions using the DOTS client identity and optionally the 3752 'cdid' parameter value. Furthermore, 'mid' value is monotonically 3753 increased by the DOTS client for each mitigation request, 3754 attackers replaying mitigation requests with lower numeric 'mid' 3755 values and overlapping scopes with mitigation requests having 3756 higher numeric 'mid' values will be rejected systematically by the 3757 DOTS server. Likewise, 'sid' value is monotonically increased by 3758 the DOTS client for each configuration request (Section 4.5.2), 3759 attackers replaying configuration requests with lower numeric 3760 'sid' values will be rejected by the DOTS server if it maintains a 3761 higher numeric 'sid' value for this DOTS client. 3763 Owing to the aforementioned protections, all DOTS signal channel 3764 requests are safe to transmit in TLS 1.3 as early data. Refer to 3765 [I-D.boucadair-dots-earlydata] for more details. 3767 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3768 message exchange is shown in Figure 29. 3770 DOTS Client DOTS Server 3772 ClientHello 3773 (0-RTT DOTS signal message) 3774 --------> 3775 ServerHello 3776 {EncryptedExtensions} 3777 {Finished} 3778 <-------- [DOTS signal message] 3779 (end_of_early_data) 3780 {Finished} --------> 3781 [DOTS signal message] <-------> [DOTS signal message] 3783 Note that: 3784 () Indicates messages protected 0-RTT keys 3785 {} Indicates messages protected using handshake keys 3786 [] Indicates messages protected using 1-RTT keys 3788 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 3790 7.3. DTLS MTU and Fragmentation 3792 To avoid DOTS signal message fragmentation and the subsequent 3793 decreased probability of message delivery, DOTS agents MUST ensure 3794 that the DTLS record fit within a single datagram. As a reminder, 3795 DTLS handles fragmentation and reassembly only for handshake messages 3796 and not for the application data (Section 4.1.1 of [RFC6347]). If 3797 the PMTU cannot be discovered, DOTS agents MUST assume a PMTU of 1280 3798 bytes, as IPv6 requires that every link in the Internet have an MTU 3799 of 1280 octets or greater as specified in [RFC8200]. If IPv4 support 3800 on legacy or otherwise unusual networks is a consideration and the 3801 PMTU is unknown, DOTS implementations MAY assume on a PMTU of 576 3802 bytes for IPv4 datagrams, as every IPv4 host must be capable of 3803 receiving a packet whose length is equal to 576 bytes as discussed in 3804 [RFC0791] and [RFC1122]. 3806 The DOTS client must consider the amount of record expansion expected 3807 by the DTLS processing when calculating the size of CoAP message that 3808 fits within the path MTU. Path MTU MUST be greater than or equal to 3809 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 3810 overhead of the negotiated DTLS cipher suite + block padding] 3811 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 3812 the path MTU then the DOTS client MUST split the DOTS signal into 3813 separate messages; for example, the list of addresses in the 'target- 3814 prefix' parameter could be split into multiple lists and each list 3815 conveyed in a new PUT request. 3817 Implementation Note: DOTS choice of message size parameters works 3818 well with IPv6 and with most of today's IPv4 paths. However, with 3819 IPv4, it is harder to safely make sure that there is no IP 3820 fragmentation. If the IPv4 path MTU is unknown, implementations may 3821 want to limit themselves to more conservative IPv4 datagram sizes 3822 such as 576 bytes, as per [RFC0791]. 3824 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3826 (D)TLS based upon client certificate can be used for mutual 3827 authentication between DOTS agents. If, for example, a DOTS gateway 3828 is involved, DOTS clients and DOTS gateways must perform mutual 3829 authentication; only authorized DOTS clients are allowed to send DOTS 3830 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3831 perform mutual authentication; a DOTS server only allows DOTS signal 3832 channel messages from an authorized DOTS gateway, thereby creating a 3833 two-link chain of transitive authentication between the DOTS client 3834 and the DOTS server. 3836 The DOTS server should support certificate-based client 3837 authentication. The DOTS client should respond to the DOTS server's 3838 TLS CertificateRequest message with the PKIX certificate held by the 3839 DOTS client. DOTS client certificate validation must be performed as 3840 per [RFC5280] and the DOTS client certificate must conform to the 3841 [RFC5280] certificate profile. If a DOTS client does not support TLS 3842 client certificate authentication, it must support pre-shared key 3843 based or raw public key based client authentication. 3845 +---------------------------------------------+ 3846 | example.com domain +---------+ | 3847 | | AAA | | 3848 | +---------------+ | Server | | 3849 | | Application | +------+--+ | 3850 | | server +<---------------+ ^ | 3851 | | (DOTS client) | | | | 3852 | +---------------+ | | | 3853 | V V | example.net domain 3854 | +-----+----+--+ | +---------------+ 3855 | +--------------+ | | | | | 3856 | | Guest +<----x---->+ DOTS +<------>+ DOTS | 3857 | | (DOTS client)| | gateway | | | server | 3858 | +--------------+ | | | | | 3859 | +----+--------+ | +---------------+ 3860 | ^ | 3861 | | | 3862 | +----------------+ | | 3863 | | DDoS detector | | | 3864 | | (DOTS client) +<-------------+ | 3865 | +----------------+ | 3866 +---------------------------------------------+ 3868 Figure 30: Example of Authentication and Authorization of DOTS Agents 3870 In the example depicted in Figure 30, the DOTS gateway and DOTS 3871 clients within the 'example.com' domain mutually authenticate. After 3872 the DOTS gateway validates the identity of a DOTS client, it 3873 communicates with the AAA server in the 'example.com' domain to 3874 determine if the DOTS client is authorized to request DDoS 3875 mitigation. If the DOTS client is not authorized, a 4.01 3876 (Unauthorized) is returned in the response to the DOTS client. In 3877 this example, the DOTS gateway only allows the application server and 3878 DDoS attack detector to request DDoS mitigation, but does not permit 3879 the user of type 'guest' to request DDoS mitigation. 3881 Also, DOTS gateways and servers located in different domains must 3882 perform mutual authentication (e.g., using certificates). A DOTS 3883 server will only allow a DOTS gateway with a certificate for a 3884 particular domain to request mitigation for that domain. In 3885 reference to Figure 30, the DOTS server only allows the DOTS gateway 3886 to request mitigation for 'example.com' domain and not for other 3887 domains. 3889 9. IANA Considerations 3891 9.1. DOTS Signal Channel UDP and TCP Port Number 3893 IANA is requested to assign the port number TBD to the DOTS signal 3894 channel protocol for both UDP and TCP from the "Service Name and 3895 Transport Protocol Port Number Registry" available at 3896 https://www.iana.org/assignments/service-names-port-numbers/service- 3897 names-port-numbers.xhtml. 3899 The assignment of port number 4646 is strongly suggested, as 4646 is 3900 the ASCII decimal value for ".." (DOTS). 3902 9.2. Well-Known 'dots' URI 3904 This document requests IANA to register the 'dots' well-known URI 3905 (Table 5) in the Well-Known URIs registry 3906 (https://www.iana.org/assignments/well-known-uris/well-known- 3907 uris.xhtml) as defined by [RFC8615]: 3909 +----------+----------------+---------------------+-----------------+ 3910 | URI | Change | Specification | Related | 3911 | suffix | controller | document(s) | information | 3912 +----------+----------------+---------------------+-----------------+ 3913 | dots | IETF | [RFCXXXX] | None | 3914 +----------+----------------+---------------------+-----------------+ 3916 Table 5: 'dots' well-known URI 3918 9.3. Media Type Registration 3920 This document requests IANA to register the "application/dots+cbor" 3921 media type in the "Media Types" registry [IANA.MediaTypes] in the 3922 manner described in [RFC6838], which can be used to indicate that the 3923 content is a DOTS signal channel object: 3925 o Type name: application 3926 o Subtype name: dots+cbor 3927 o Required parameters: N/A 3928 o Optional parameters: N/A 3929 o Encoding considerations: binary 3930 o Security considerations: See the Security Considerations section 3931 of [RFCXXXX] 3932 o Interoperability considerations: N/A 3933 o Published specification: [RFCXXXX] 3934 o Applications that use this media type: DOTS agents sending DOTS 3935 messages over CoAP over (D)TLS. 3936 o Fragment identifier considerations: N/A 3937 o Additional information: 3939 Magic number(s): N/A 3940 File extension(s): N/A 3941 Macintosh file type code(s): N/A 3942 o Person & email address to contact for further information: 3943 IESG, iesg@ietf.org 3944 o Intended usage: COMMON 3945 o Restrictions on usage: none 3946 o Author: See Authors' Addresses section. 3947 o Change controller: IESG 3948 o Provisional registration? No 3950 9.4. CoAP Content-Formats Registration 3952 This document requests IANA to register the CoAP Content-Format ID 3953 for the "application/dots+cbor" media type in the "CoAP Content- 3954 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3956 o Media Type: application/dots+cbor 3957 o Encoding: - 3958 o Id: TBD1 3959 o Reference: [RFCXXXX] 3961 9.5. CBOR Tag Registration 3963 This section defines the DOTS CBOR tag as another means for 3964 applications to declare that a CBOR data structure is a DOTS signal 3965 channel object. Its use is optional and is intended for use in cases 3966 in which this information would not otherwise be known. DOTS CBOR 3967 tag is not required for DOTS signal channel protocol version 3968 specified in this document. If present, the DOTS tag MUST prefix a 3969 DOTS signal channel object. 3971 This document requests IANA to register the DOTS signal channel CBOR 3972 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3973 range: 3975 o CBOR Tag: TBD2 (please assign the same value as the Content- 3976 Format) 3977 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3978 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3979 object, as defined in [RFCXXXX] 3980 o Description of Semantics: [RFCXXXX] 3982 9.6. DOTS Signal Channel Protocol Registry 3984 The document requests IANA to create a new registry, entitled "DOTS 3985 Signal Channel Registry". The following sections define sub- 3986 registries. 3988 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3990 The document requests IANA to create a new sub-registry, entitled 3991 "DOTS Signal Channel CBOR Key Values". 3993 The structure of this sub-registry is provided in Section 9.6.1.1. 3994 Section 9.6.1.2 provides how the registry is initially populated with 3995 the values in Table 4. 3997 9.6.1.1. Registration Template 3999 Parameter name: 4000 Parameter name as used in the DOTS signal channel. 4002 CBOR Key Value: 4003 Key value for the parameter. The key value MUST be an integer in 4004 the 1-65535 range. The key values of the comprehension-required 4005 range (0x0001 - 0x3FFF) and of the comprehension-optional range 4006 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 4007 [RFC8126]). The key values of the comprehension-optional range 4008 (0x4000 - 0x7FFF) are assigned by Specification Required 4009 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 4010 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 4011 [RFC8126]). 4013 Registration requests for the 0x4000 - 0x7FFF range are evaluated 4014 after a three-week review period on the dots-signal-reg- 4015 review@ietf.org mailing list, on the advice of one or more 4016 Designated Experts. However, to allow for the allocation of 4017 values prior to publication, the Designated Experts may approve 4018 registration once they are satisfied that such a specification 4019 will be published. New registration requests should be sent in 4020 the form of an email to the review mailing list; the request 4021 should use an appropriate subject (e.g., "Request to register CBOR 4022 Key Value for DOTS: example"). IANA will only accept new 4023 registrations from the Designated Experts, and will check that 4024 review was requested on the mailing list in accordance with these 4025 procedures. 4027 Within the review period, the Designated Experts will either 4028 approve or deny the registration request, communicating this 4029 decision to the review list and IANA. Denials should include an 4030 explanation and, if applicable, suggestions as to how to make the 4031 request successful. Registration requests that are undetermined 4032 for a period longer than 21 days can be brought to the IESG's 4033 attention (using the iesg@ietf.org mailing list) for resolution. 4035 Criteria that should be applied by the Designated Experts includes 4036 determining whether the proposed registration duplicates existing 4037 functionality, whether it is likely to be of general applicability 4038 or whether it is useful only for a single use case, and whether 4039 the registration description is clear. IANA must only accept 4040 registry updates to the 0x4000 - 0x7FFF range from the Designated 4041 Experts and should direct all requests for registration to the 4042 review mailing list. It is suggested that multiple Designated 4043 Experts be appointed. In cases where a registration decision 4044 could be perceived as creating a conflict of interest for a 4045 particular Expert, that Expert should defer to the judgment of the 4046 other Experts. 4048 CBOR Major Type: 4049 CBOR Major type and optional tag for the parameter. 4051 Change Controller: 4052 For Standards Track RFCs, list the "IESG". For others, give the 4053 name of the responsible party. Other details (e.g., email 4054 address) may also be included. 4056 Specification Document(s): 4057 Reference to the document or documents that specify the parameter, 4058 preferably including URIs that can be used to retrieve copies of 4059 the documents. An indication of the relevant sections may also be 4060 included but is not required. 4062 9.6.1.2. Initial Sub-Registry Content 4064 +----------------------+-------+-------+------------+---------------+ 4065 | Parameter Name | CBOR | CBOR | Change | Specification | 4066 | | Key | Major | Controller | Document(s) | 4067 | | Value | Type | | | 4068 +----------------------+-------+-------+------------+---------------+ 4069 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 4070 | nel:mitigation-scope | | | | | 4071 | scope | 2 | 4 | IESG | [RFCXXXX] | 4072 | cdid | 3 | 3 | IESG | [RFCXXXX] | 4073 | cuid | 4 | 3 | IESG | [RFCXXXX] | 4074 | mid | 5 | 0 | IESG | [RFCXXXX] | 4075 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 4076 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 4077 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 4078 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 4079 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 4080 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 4081 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 4082 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 4083 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 4084 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 4085 | status | 16 | 0 | IESG | [RFCXXXX] | 4086 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 4087 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 4088 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 4089 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 4090 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 4091 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 4092 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 4093 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 4094 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 4095 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 4096 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 4097 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 4098 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 4099 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 4100 | channel:signal-config| | | | | 4101 | sid | 31 | 0 | IESG | [RFCXXXX] | 4102 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 4103 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 4104 | min-value | 34 | 0 | IESG | [RFCXXXX] | 4105 | max-value | 35 | 0 | IESG | [RFCXXXX] | 4106 | current-value | 36 | 0 | IESG | [RFCXXXX] | 4107 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 4108 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 4109 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 4110 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 4111 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 4112 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 4113 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 4114 | decimal | | | | | 4115 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 4116 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 4117 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 4118 | nel:redirected-signal| | | | | 4119 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 4120 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 4121 | ietf-dots-signal-chan| 49 | 5 | IESG | [RFCXXXX] | 4122 | nel:heartbeat | | | | | 4123 | probing-rate | 50 | 5 | IESG | [RFCXXXX] | 4124 | peer-hb-status | 51 | 7 | IESG | [RFCXXXX] | 4125 +----------------------+-------+-------+------------+---------------+ 4126 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 4128 9.6.2. Status Codes Sub-Registry 4130 The document requests IANA to create a new sub-registry, entitled 4131 "DOTS Signal Channel Status Codes". Codes in this registry are used 4132 as valid values of 'status' parameter. 4134 The registry is initially populated with the following values: 4136 +-----+----------------------------------+--------------+-----------+ 4137 | Cod | Label | Description | Reference | 4138 | e | | | | 4139 +-----+----------------------------------+--------------+-----------+ 4140 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 4141 | | | mitigation | | 4142 | | | setup is in | | 4143 | | | progress | | 4144 | | | (e.g., | | 4145 | | | changing the | | 4146 | | | network path | | 4147 | | | to redirect | | 4148 | | | the inbound | | 4149 | | | traffic to a | | 4150 | | | DOTS | | 4151 | | | mitigator). | | 4152 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 4153 | | | being | | 4154 | | | successfully | | 4155 | | | mitigated | | 4156 | | | (e.g., | | 4157 | | | traffic is | | 4158 | | | redirected | | 4159 | | | to a DDoS | | 4160 | | | mitigator | | 4161 | | | and attack | | 4162 | | | traffic is | | 4163 | | | dropped). | | 4164 | 3 | attack-stopped | Attack has | [RFCXXXX] | 4165 | | | stopped and | | 4166 | | | the DOTS | | 4167 | | | client can | | 4168 | | | withdraw the | | 4169 | | | mitigation | | 4170 | | | request. | | 4171 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 4172 | | | exceeded the | | 4173 | | | mitigation | | 4174 | | | provider | | 4175 | | | capability. | | 4176 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 4177 | | | has | | 4178 | | | withdrawn | | 4179 | | | the | | 4180 | | | mitigation | | 4181 | | | request and | | 4182 | | | the | | 4183 | | | mitigation | | 4184 | | | is active | | 4185 | | | but | | 4186 | | | terminating. | | 4187 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 4188 | | | mitigation | | 4189 | | | is now | | 4190 | | | terminated. | | 4191 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 4192 | | | mitigation | | 4193 | | | is | | 4194 | | | withdrawn. | | 4195 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 4196 | | | mitigation | | 4197 | | | will be | | 4198 | | | triggered | | 4199 | | | for the | | 4200 | | | mitigation | | 4201 | | | request only | | 4202 | | | when the | | 4203 | | | DOTS signal | | 4204 | | | channel | | 4205 | | | session is | | 4206 | | | lost. | | 4207 +-----+----------------------------------+--------------+-----------+ 4209 New codes can be assigned via Standards Action [RFC8126]. 4211 9.6.3. Conflict Status Codes Sub-Registry 4213 The document requests IANA to create a new sub-registry, entitled 4214 "DOTS Signal Channel Conflict Status Codes". Codes in this registry 4215 are used as valid values of 'conflict-status' parameter. 4217 The registry is initially populated with the following values: 4219 +------+-------------------------------+----------------+-----------+ 4220 | Code | Label | Description | Reference | 4221 +------+-------------------------------+----------------+-----------+ 4222 | 1 | request-inactive-other-active | DOTS server | [RFCXXXX] | 4223 | | | has detected | | 4224 | | | conflicting | | 4225 | | | mitigation | | 4226 | | | requests from | | 4227 | | | different DOTS | | 4228 | | | clients. This | | 4229 | | | mitigation | | 4230 | | | request is | | 4231 | | | currently | | 4232 | | | inactive until | | 4233 | | | the conflicts | | 4234 | | | are resolved. | | 4235 | | | Another | | 4236 | | | mitigation | | 4237 | | | request is | | 4238 | | | active. | | 4239 | 2 | request-active | DOTS server | [RFCXXXX] | 4240 | | | has detected | | 4241 | | | conflicting | | 4242 | | | mitigation | | 4243 | | | requests from | | 4244 | | | different DOTS | | 4245 | | | clients. This | | 4246 | | | mitigation | | 4247 | | | request is | | 4248 | | | currently | | 4249 | | | active. | | 4250 | 3 | all-requests-inactive | DOTS server | [RFCXXXX] | 4251 | | | has detected | | 4252 | | | conflicting | | 4253 | | | mitigation | | 4254 | | | requests from | | 4255 | | | different DOTS | | 4256 | | | clients. All | | 4257 | | | conflicting | | 4258 | | | mitigation | | 4259 | | | requests are | | 4260 | | | inactive. | | 4261 +------+-------------------------------+----------------+-----------+ 4263 New codes can be assigned via Standards Action [RFC8126]. 4265 9.6.4. Conflict Cause Codes Sub-Registry 4267 The document requests IANA to create a new sub-registry, entitled 4268 "DOTS Signal Channel Conflict Cause Codes". Codes in this registry 4269 are used as valid values of 'conflict-cause' parameter. 4271 The registry is initially populated with the following values: 4273 +------+--------------------------+---------------------+-----------+ 4274 | Code | Label | Description | Reference | 4275 +------+--------------------------+---------------------+-----------+ 4276 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4277 | | | targets. | | 4278 | 2 | conflict-with-acceptlist | Conflicts with an | [RFCXXXX] | 4279 | | | existing accept- | | 4280 | | | list. This code is | | 4281 | | | returned when the | | 4282 | | | DDoS mitigation | | 4283 | | | detects source | | 4284 | | | addresses/prefixes | | 4285 | | | in the accept- | | 4286 | | | listed ACLs are | | 4287 | | | attacking the | | 4288 | | | target. | | 4289 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 4290 | | | This code is | | 4291 | | | returned when a | | 4292 | | | DOTS client uses a | | 4293 | | | 'cuid' that is | | 4294 | | | already used by | | 4295 | | | another DOTS | | 4296 | | | client. | | 4297 +------+--------------------------+---------------------+-----------+ 4299 New codes can be assigned via Standards Action [RFC8126]. 4301 9.6.5. Attack Status Codes Sub-Registry 4303 The document requests IANA to create a new sub-registry, entitled 4304 "DOTS Signal Channel Attack Status Codes". Codes in this registry 4305 are used as valid values of 'attack-status' parameter. 4307 The registry is initially populated with the following values: 4309 +------+-------------------------------+----------------+-----------+ 4310 | Code | Label | Description | Reference | 4311 +------+-------------------------------+----------------+-----------+ 4312 | 1 | under-attack | The DOTS | [RFCXXXX] | 4313 | | | client | | 4314 | | | determines | | 4315 | | | that it is | | 4316 | | | still under | | 4317 | | | attack. | | 4318 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 4319 | | | client | | 4320 | | | determines | | 4321 | | | that the | | 4322 | | | attack is | | 4323 | | | successfully | | 4324 | | | mitigated. | | 4325 +------+-------------------------------+----------------+-----------+ 4327 New codes can be assigned via Standards Action [RFC8126]. 4329 9.7. DOTS Signal Channel YANG Modules 4331 This document requests IANA to register the following URIs in the 4332 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4334 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4335 Registrant Contact: The IESG. 4336 XML: N/A; the requested URI is an XML namespace. 4338 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4339 Registrant Contact: IANA. 4340 XML: N/A; the requested URI is an XML namespace. 4342 This document requests IANA to register the following YANG modules in 4343 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4344 Parameters" registry. 4346 Name: ietf-dots-signal-channel 4347 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4348 Maintained by IANA: N 4349 Prefix: signal 4350 Reference: RFC XXXX 4352 Name: iana-dots-signal-channel 4353 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4354 Maintained by IANA: Y 4355 Prefix: iana-signal 4356 Reference: RFC XXXX 4358 This document defines the initial version of the IANA-maintained 4359 iana-dots-signal-channel YANG module. IANA is requested to add this 4360 note: 4362 Status, conflict status, conflict cause, and attack status values 4363 must not be directly added to the iana-dots-signal-channel YANG 4364 module. They must instead be respectively added to the "DOTS 4365 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4366 Codes", and "DOTS Attack Status Codes" registries. 4368 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4369 status' value is respectively added to the "DOTS Status Codes", "DOTS 4370 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4371 Status Codes" registry, a new "enum" statement must be added to the 4372 iana-dots-signal-channel YANG module. The following "enum" 4373 statement, and substatements thereof, should be defined: 4375 "enum": Replicates the label from the registry. 4377 "value": Contains the IANA-assigned value corresponding to the 4378 'status', 'conflict-status', 'conflict-cause', or 4379 'attack-status'. 4381 "description": Replicates the description from the registry. 4383 "reference": Replicates the reference from the registry and adds 4384 the title of the document. 4386 When the iana-dots-signal-channel YANG module is updated, a new 4387 "revision" statement must be added in front of the existing revision 4388 statements. 4390 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4391 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4392 Status Codes" registries: 4394 When this registry is modified, the YANG module iana-dots-signal- 4395 channel must be updated as defined in [RFCXXXX]. 4397 10. Security Considerations 4399 High-level DOTS security considerations are documented in [RFC8612] 4400 and [I-D.ietf-dots-architecture]. 4402 Authenticated encryption MUST be used for data confidentiality and 4403 message integrity. The interaction between the DOTS agents requires 4404 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4405 (TLS) with a cipher suite offering confidentiality protection, and 4406 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4407 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4408 is specified in Section 7. 4410 If TCP is used between DOTS agents, an attacker may be able to inject 4411 RST packets, bogus application segments, etc., regardless of whether 4412 TLS authentication is used. Because the application data is TLS 4413 protected, this will not result in the application receiving bogus 4414 data, but it will constitute a DoS on the connection. This attack 4415 can be countered by using TCP-AO [RFC5925]. Although not widely 4416 adopted, if TCP-AO is used, then any bogus packets injected by an 4417 attacker will be rejected by the TCP-AO integrity check and therefore 4418 will never reach the TLS layer. 4420 An attack vector that can be achieved if the 'cuid' is guessable is a 4421 misbehaving DOTS client from within the client's domain which uses 4422 the 'cuid' of another DOTS client of the domain to delete or alter 4423 active mitigations. For this attack vector to happen, the 4424 misbehaving client needs to pass the security validation checks by 4425 the DOTS server, and eventually the checks of a client-domain DOTS 4426 gateway. 4428 A similar attack can be achieved by a compromised DOTS client which 4429 can sniff the TLS 1.2 handshake, use the client certificate to 4430 identify the 'cuid' used by another DOTS client. This attack is not 4431 possible if algorithms such as version 4 Universally Unique 4432 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4433 the 'cuid' because such UUIDs are not a deterministic function of the 4434 client certificate. Likewise, this attack is not possible with TLS 4435 1.3 because most of the TLS handshake is encrypted and the client 4436 certificate is not visible to eavesdroppers. 4438 A compromised DOTS client can collude with a DDoS attacker to send 4439 mitigation request for a target resource, gets the mitigation 4440 efficacy from the DOTS server, and conveys the mitigation efficacy to 4441 the DDoS attacker to possibly change the DDoS attack strategy. 4442 Obviously, signaling an attack by the compromised DOTS client to the 4443 DOTS server will trigger attack mitigation. This attack can be 4444 prevented by monitoring and auditing DOTS clients to detect 4445 misbehavior and to deter misuse, and by only authorizing the DOTS 4446 client to request mitigation for specific target resources (e.g., an 4447 application server is authorized to request mitigation for its IP 4448 addresses but a DDoS mitigator can request mitigation for any target 4449 resource in the network). Furthermore, DOTS clients are typically 4450 co-located on network security services (e.g., firewall) and a 4451 compromised security service potentially can do a lot more damage to 4452 the network. 4454 Rate-limiting DOTS requests, including those with new 'cuid' values, 4455 from the same DOTS client defends against DoS attacks that would 4456 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4457 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4458 DOTS servers. 4460 In order to prevent leaking internal information outside a client- 4461 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4462 the identification information that pertains to internal DOTS clients 4463 (e.g., source IP address, client's hostname) unless explicitly 4464 configured to do so. 4466 DOTS servers MUST verify that requesting DOTS clients are entitled to 4467 trigger actions on a given IP prefix. That is, only actions on IP 4468 resources that belong to the DOTS client' domain MUST be authorized 4469 by a DOTS server. The exact mechanism for the DOTS servers to 4470 validate that the target prefixes are within the scope of the DOTS 4471 client domain is deployment-specific. 4473 The presence of DOTS gateways may lead to infinite forwarding loops, 4474 which is undesirable. To prevent and detect such loops, this 4475 document uses the Hop-Limit Option. 4477 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4478 privacy enabling protocols (e.g., DNS over TLS [RFC7858] or DoH 4479 [RFC8484]) to prevent eavesdroppers from possibly identifying the 4480 target resources protected by the DDoS mitigation service, and means 4481 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 4482 [RFC4034]). 4484 CoAP-specific security considerations are discussed in Section 11 of 4485 [RFC7252], while CBOR-related security considerations are discussed 4486 in Section 8 of [RFC7049]. 4488 11. Contributors 4490 The following individuals have contributed to this document: 4492 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4494 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4495 mgeller@cisco.com 4497 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4498 Email: rgm@htt-consult.com 4500 o Dan Wing, Email: dwing-ietf@fuggles.com 4502 12. Acknowledgements 4504 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 4505 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 4506 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 4507 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 4508 and comments. 4510 The authors would like to give special thanks to Kaname Nishizuka and 4511 Jon Shallow for their efforts in implementing the protocol and 4512 performing interop testing at IETF Hackathons. 4514 Thanks to the core WG for the recommendations on Hop-Limit and 4515 redirect signaling. 4517 Special thanks to Benjamin Kaduk for the detailed AD review. 4519 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 4520 Kuehlewind, and Alissa Cooper for the review. 4522 Thanks to Carsten Bormann for his review of the DOTS heartbeat 4523 mechanism. 4525 13. References 4527 13.1. Normative References 4529 [I-D.ietf-core-hop-limit] 4530 Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 4531 Application Protocol (CoAP) Hop-Limit Option", draft-ietf- 4532 core-hop-limit-07 (work in progress), October 2019. 4534 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4535 DOI 10.17487/RFC0791, September 1981, 4536 . 4538 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4539 Communication Layers", STD 3, RFC 1122, 4540 DOI 10.17487/RFC1122, October 1989, 4541 . 4543 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4544 Requirement Levels", BCP 14, RFC 2119, 4545 DOI 10.17487/RFC2119, March 1997, 4546 . 4548 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4549 DOI 10.17487/RFC3688, January 2004, 4550 . 4552 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4553 Resource Identifier (URI): Generic Syntax", STD 66, 4554 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4555 . 4557 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4558 Ciphersuites for Transport Layer Security (TLS)", 4559 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4560 . 4562 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4563 (CIDR): The Internet Address Assignment and Aggregation 4564 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4565 2006, . 4567 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4568 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4569 . 4571 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4572 (TLS) Protocol Version 1.2", RFC 5246, 4573 DOI 10.17487/RFC5246, August 2008, 4574 . 4576 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4577 Housley, R., and W. Polk, "Internet X.509 Public Key 4578 Infrastructure Certificate and Certificate Revocation List 4579 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4580 . 4582 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4583 Extensions: Extension Definitions", RFC 6066, 4584 DOI 10.17487/RFC6066, January 2011, 4585 . 4587 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4588 Verification of Domain-Based Application Service Identity 4589 within Internet Public Key Infrastructure Using X.509 4590 (PKIX) Certificates in the Context of Transport Layer 4591 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4592 2011, . 4594 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4595 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4596 January 2012, . 4598 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4599 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4600 . 4602 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4603 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4604 October 2013, . 4606 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4607 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4608 Transport Layer Security (TLS) and Datagram Transport 4609 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4610 June 2014, . 4612 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4613 Application Protocol (CoAP)", RFC 7252, 4614 DOI 10.17487/RFC7252, June 2014, 4615 . 4617 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4618 "Recommendations for Secure Use of Transport Layer 4619 Security (TLS) and Datagram Transport Layer Security 4620 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4621 2015, . 4623 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4624 Application Protocol (CoAP)", RFC 7641, 4625 DOI 10.17487/RFC7641, September 2015, 4626 . 4628 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4629 Layer Security (TLS) False Start", RFC 7918, 4630 DOI 10.17487/RFC7918, August 2016, 4631 . 4633 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4634 (TLS) Cached Information Extension", RFC 7924, 4635 DOI 10.17487/RFC7924, July 2016, 4636 . 4638 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4639 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4640 . 4642 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4643 the Constrained Application Protocol (CoAP)", RFC 7959, 4644 DOI 10.17487/RFC7959, August 2016, 4645 . 4647 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4648 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4649 March 2017, . 4651 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4652 Writing an IANA Considerations Section in RFCs", BCP 26, 4653 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4654 . 4656 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4657 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4658 May 2017, . 4660 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4661 (IPv6) Specification", STD 86, RFC 8200, 4662 DOI 10.17487/RFC8200, July 2017, 4663 . 4665 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4666 Better Connectivity Using Concurrency", RFC 8305, 4667 DOI 10.17487/RFC8305, December 2017, 4668 . 4670 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4671 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4672 Application Protocol) over TCP, TLS, and WebSockets", 4673 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4674 . 4676 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4677 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4678 . 4680 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 4681 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 4682 . 4684 13.2. Informative References 4686 [I-D.boucadair-dots-earlydata] 4687 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4688 boucadair-dots-earlydata-00 (work in progress), January 4689 2019. 4691 [I-D.ietf-core-comi] 4692 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 4693 Petrov, "CoAP Management Interface", draft-ietf-core- 4694 comi-08 (work in progress), September 2019. 4696 [I-D.ietf-core-yang-cbor] 4697 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 4698 Data Modeled with YANG", draft-ietf-core-yang-cbor-11 4699 (work in progress), September 2019. 4701 [I-D.ietf-dots-architecture] 4702 Mortensen, A., Reddy.K, T., Andreasen, F., Teague, N., and 4703 R. Compton, "Distributed-Denial-of-Service Open Threat 4704 Signaling (DOTS) Architecture", draft-ietf-dots- 4705 architecture-14 (work in progress), May 2019. 4707 [I-D.ietf-dots-data-channel] 4708 Boucadair, M. and T. Reddy.K, "Distributed Denial-of- 4709 Service Open Threat Signaling (DOTS) Data Channel 4710 Specification", draft-ietf-dots-data-channel-31 (work in 4711 progress), July 2019. 4713 [I-D.ietf-dots-multihoming] 4714 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 4715 Deployment Considerations for Distributed-Denial-of- 4716 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 4717 multihoming-02 (work in progress), July 2019. 4719 [I-D.ietf-dots-server-discovery] 4720 Boucadair, M. and T. Reddy.K, "Distributed-Denial-of- 4721 Service Open Threat Signaling (DOTS) Agent Discovery", 4722 draft-ietf-dots-server-discovery-06 (work in progress), 4723 November 2019. 4725 [I-D.ietf-dots-use-cases] 4726 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 4727 L., and K. Nishizuka, "Use cases for DDoS Open Threat 4728 Signaling", draft-ietf-dots-use-cases-20 (work in 4729 progress), September 2019. 4731 [I-D.ietf-tls-dtls13] 4732 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4733 Datagram Transport Layer Security (DTLS) Protocol Version 4734 1.3", draft-ietf-tls-dtls13-34 (work in progress), 4735 November 2019. 4737 [IANA.CBOR.Tags] 4738 IANA, "Concise Binary Object Representation (CBOR) Tags", 4739 . 4742 [IANA.CoAP.Content-Formats] 4743 IANA, "CoAP Content-Formats", 4744 . 4747 [IANA.MediaTypes] 4748 IANA, "Media Types", 4749 . 4751 [proto_numbers] 4752 "IANA, "Protocol Numbers"", 2011, 4753 . 4755 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4756 Address Translator (Traditional NAT)", RFC 3022, 4757 DOI 10.17487/RFC3022, January 2001, 4758 . 4760 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 4761 Rose, "Resource Records for the DNS Security Extensions", 4762 RFC 4034, DOI 10.17487/RFC4034, March 2005, 4763 . 4765 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4766 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4767 DOI 10.17487/RFC4122, July 2005, 4768 . 4770 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4771 Congestion Control Protocol (DCCP)", RFC 4340, 4772 DOI 10.17487/RFC4340, March 2006, 4773 . 4775 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4776 Denial-of-Service Considerations", RFC 4732, 4777 DOI 10.17487/RFC4732, December 2006, 4778 . 4780 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4781 Translation (NAT) Behavioral Requirements for Unicast 4782 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4783 2007, . 4785 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4786 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4787 . 4789 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4790 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4791 . 4793 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4794 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4795 DOI 10.17487/RFC5389, October 2008, 4796 . 4798 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4799 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4800 June 2010, . 4802 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4803 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4804 DOI 10.17487/RFC6052, October 2010, 4805 . 4807 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4808 NAT64: Network Address and Protocol Translation from IPv6 4809 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4810 April 2011, . 4812 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4813 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4814 DOI 10.17487/RFC6234, May 2011, 4815 . 4817 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4818 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4819 . 4821 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4822 "Default Address Selection for Internet Protocol Version 6 4823 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4824 . 4826 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4827 Specifications and Registration Procedures", BCP 13, 4828 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4829 . 4831 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4832 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4833 DOI 10.17487/RFC6887, April 2013, 4834 . 4836 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4837 A., and H. Ashida, "Common Requirements for Carrier-Grade 4838 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4839 April 2013, . 4841 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4842 "Enrollment over Secure Transport", RFC 7030, 4843 DOI 10.17487/RFC7030, October 2013, 4844 . 4846 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4847 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4848 . 4850 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4851 "Architectural Considerations in Smart Object Networking", 4852 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4853 . 4855 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4856 NETCONF Protocol over Transport Layer Security (TLS) with 4857 Mutual X.509 Authentication", RFC 7589, 4858 DOI 10.17487/RFC7589, June 2015, 4859 . 4861 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 4862 and P. Hoffman, "Specification for DNS over Transport 4863 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 4864 2016, . 4866 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4867 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4868 . 4870 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4871 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4872 . 4874 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 4875 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 4876 . 4878 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4879 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4880 January 2019, . 4882 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4883 Threat Signaling (DOTS) Requirements", RFC 8612, 4884 DOI 10.17487/RFC8612, May 2019, 4885 . 4887 Appendix A. CUID Generation 4889 The document recommends the use of SPKI to generate the 'cuid'. This 4890 design choice is motivated by the following reasons: 4892 o SPKI is globally unique. 4894 o It is deterministic. 4896 o It allows to avoid extra cycles that may be induced by 'cuid' 4897 collision. 4899 o DOTS clients do not need to store the 'cuid' in a persistent 4900 storage. 4902 o It allows to detect compromised DOTS clients that do not adhere to 4903 the 'cuid' generation algorithm. 4905 Authors' Addresses 4907 Tirumaleswar Reddy (editor) 4908 McAfee, Inc. 4909 Embassy Golf Link Business Park 4910 Bangalore, Karnataka 560071 4911 India 4913 Email: kondtir@gmail.com 4915 Mohamed Boucadair (editor) 4916 Orange 4917 Rennes 35000 4918 France 4920 Email: mohamed.boucadair@orange.com 4921 Prashanth Patil 4922 Cisco Systems, Inc. 4924 Email: praspati@cisco.com 4926 Andrew Mortensen 4927 Arbor Networks, Inc. 4928 2727 S. State St 4929 Ann Arbor, MI 48104 4930 United States 4932 Email: andrew@moretension.com 4934 Nik Teague 4935 Iron Mountain Data Centers 4936 United Kingdom 4938 Email: nteague@ironmountain.co.uk