idnits 2.17.00 (12 Aug 2021) /tmp/idnits33500/draft-ietf-dots-signal-channel-40.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 2702 has weird spacing: '...er-port ine...' -- The document date (December 18, 2019) is 884 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 4396, but not defined == Outdated reference: draft-ietf-core-hop-limit has been published as RFC 8768 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-11) exists of draft-ietf-core-comi-08 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-11 == Outdated reference: draft-ietf-dots-architecture has been published as RFC 8811 == Outdated reference: draft-ietf-dots-data-channel has been published as RFC 8783 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-02 == Outdated reference: draft-ietf-dots-server-discovery has been published as RFC 8973 == Outdated reference: draft-ietf-dots-use-cases has been published as RFC 8903 == Outdated reference: draft-ietf-tls-dtls13 has been published as RFC 9147 -- Obsolete informational reference (is this intentional?): RFC 5389 (Obsoleted by RFC 8489) Summary: 5 errors (**), 0 flaws (~~), 12 warnings (==), 2 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: June 20, 2020 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Iron Mountain Data Centers 12 December 18, 2019 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-40 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 June 20, 2020. 72 Copyright Notice 74 Copyright (c) 2019 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 . . . . . 35 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. The use of anycast is meant 314 to simplify DOTS client configuration, including service 315 discovery. In such anycast-based scenario, a DOTS client 316 initiating a DOTS session to the DOTS server anycast address may, 317 for example, be (1) redirected to the DOTS server unicast address 318 to be used by the DOTS client following the procedure discussed in 319 Section 4.6 or (2) relayed to a unicast DOTS server. 321 The signal channel uses the "coaps" URI scheme defined in Section 6 322 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 323 [RFC8323] to identify DOTS server resources accessible using CoAP 324 over UDP secured with DTLS and CoAP over TCP secured with TLS, 325 respectively. 327 The DOTS signal channel can be established between two DOTS agents 328 prior or during an attack. The DOTS signal channel is initiated by 329 the DOTS client. The DOTS client can then negotiate, configure, and 330 retrieve the DOTS signal channel session behavior with its DOTS peer 331 (Section 4.5). Once the signal channel is established, the DOTS 332 agents may periodically send heartbeats to keep the channel active 333 (Section 4.7). At any time, the DOTS client may send a mitigation 334 request message (Section 4.4) to a DOTS server over the active signal 335 channel. While mitigation is active (because of the higher 336 likelihood of packet loss during a DDoS attack), the DOTS server 337 periodically sends status messages to the client, including basic 338 mitigation feedback details. Mitigation remains active until the 339 DOTS client explicitly terminates mitigation, or the mitigation 340 lifetime expires. Also, the DOTS server may rely on the signal 341 channel session loss to trigger mitigation for pre-configured 342 mitigation requests (if any). 344 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 345 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 346 capabilities. A Happy Eyeballs procedure for DOTS signal channel is 347 specified in Section 4.3. 349 A DOTS client is entitled to access only to resources it creates. In 350 particular, a DOTS client can not retrieve data related to mitigation 351 requests created by other DOTS clients of the same DOTS client 352 domain. 354 Messages exchanged between DOTS agents are serialized using Concise 355 Binary Object Representation (CBOR) [RFC7049], a binary encoding 356 scheme designed for small code and message size. CBOR-encoded 357 payloads are used to carry signal channel-specific payload messages 358 which convey request parameters and response information such as 359 errors. In order to allow reusing data models across protocols, 360 [RFC7951] specifies the JavaScript Object Notation (JSON) encoding of 361 YANG-modeled data. A similar effort for CBOR is defined in 362 [I-D.ietf-core-yang-cbor]. 364 DOTS agents determine that a CBOR data structure is a DOTS signal 365 channel object from the application context, such as from the port 366 number assigned to the DOTS signal channel. The other method DOTS 367 agents use to indicate that a CBOR data structure is a DOTS signal 368 channel object is the use of the "application/dots+cbor" content type 369 (Section 9.3). 371 This document specifies a YANG module for representing DOTS 372 mitigation scopes, DOTS signal channel session configuration data, 373 and DOTS redirected signaling (Section 5). All parameters in the 374 payload of the DOTS signal channel are mapped to CBOR types as 375 specified in Table 4 (Section 6). 377 In order to prevent fragmentation, DOTS agents must follow the 378 recommendations documented in Section 4.6 of [RFC7252]. Refer to 379 Section 7.3 for more details. 381 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 382 payload included in CoAP responses with 2.xx Response Codes MUST be 383 of content type "application/dots+cbor". CoAP responses with 4.xx 384 and 5.xx error Response Codes MUST include a diagnostic payload 385 (Section 5.5.2 of [RFC7252]). The Diagnostic Payload may contain 386 additional information to aid troubleshooting. 388 In deployments where multiple DOTS clients are enabled in a network 389 (owned and operated by the same entity), the DOTS server may detect 390 conflicting mitigation requests from these clients. This document 391 does not aim to specify a comprehensive list of conditions under 392 which a DOTS server will characterize two mitigation requests from 393 distinct DOTS clients as conflicting, nor recommend a DOTS server 394 behavior for processing conflicting mitigation requests. Those 395 considerations are implementation- and deployment-specific. 396 Nevertheless, the document specifies the mechanisms to notify DOTS 397 clients when conflicts occur, including the conflict cause 398 (Section 4.4). 400 In deployments where one or more translators (e.g., Traditional NAT 401 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 402 enabled between the client's network and the DOTS server, DOTS signal 403 channel messages forwarded to a DOTS server MUST NOT include internal 404 IP addresses/prefixes and/or port numbers; external addresses/ 405 prefixes and/or port numbers as assigned by the translator MUST be 406 used instead. This document does not make any recommendation about 407 possible translator discovery mechanisms. The following are some 408 (non-exhaustive) deployment examples that may be considered: 410 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 411 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 412 external addresses/prefixes and/or port numbers. Information 413 retrieved by means of PCP or STUN will be used to feed the DOTS 414 signal channel messages that will be sent to a DOTS server. 416 o A DOTS gateway may be co-located with the translator. The DOTS 417 gateway will need to update the DOTS messages, based upon the 418 local translator's binding table. 420 4. DOTS Signal Channel: Messages & Behaviors 422 4.1. DOTS Server(s) Discovery 424 This document assumes that DOTS clients are provisioned with the 425 reachability information of their DOTS server(s) using any of a 426 variety of means (e.g., local configuration, or dynamic means such as 427 DHCP [I-D.ietf-dots-server-discovery]). The description of such 428 means is out of scope of this document. 430 Likewise, it is out of scope of this document to specify the behavior 431 to be followed by a DOTS client to send DOTS requests when multiple 432 DOTS servers are provisioned (e.g., contact all DOTS servers, select 433 one DOTS server among the list). Such behavior is specified in other 434 documents (e.g., [I-D.ietf-dots-multihoming]). 436 4.2. CoAP URIs 438 The DOTS server MUST support the use of the path-prefix of "/.well- 439 known/" as defined in [RFC8615] and the registered name of "dots". 440 Each DOTS operation is indicated by a path-suffix that indicates the 441 intended operation. The operation path (Table 1) is appended to the 442 path-prefix to form the URI used with a CoAP request to perform the 443 desired DOTS operation. 445 +-----------------------+----------------+-------------+ 446 | Operation | Operation Path | Details | 447 +-----------------------+----------------+-------------+ 448 | Mitigation | /mitigate | Section 4.4 | 449 +-----------------------+----------------+-------------+ 450 | Session configuration | /config | Section 4.5 | 451 +-----------------------+----------------+-------------+ 452 | Heartbeat | /hb | Section 4.7 | 453 +-----------------------+----------------+-------------+ 455 Table 1: Operations and their Corresponding URIs 457 4.3. Happy Eyeballs for DOTS Signal Channel 459 [RFC8612] mentions that DOTS agents will have to support both 460 connectionless and connection-oriented protocols. As such, the DOTS 461 signal channel is designed to operate with DTLS over UDP and TLS over 462 TCP. Further, a DOTS client may acquire a list of IPv4 and IPv6 463 addresses (Section 4.1), each of which can be used to contact the 464 DOTS server using UDP and TCP. If no list of IPv4 and IPv6 addresses 465 to contact the DOTS server is configured (or discovered), the DOTS 466 client adds the IPv4/IPv6 addresses of its default router to the 467 candidate list to contact the DOTS server. 469 The following specifies the procedure to follow to select the address 470 family and the transport protocol for sending DOTS signal channel 471 messages. 473 Such procedure is needed to avoid experiencing long connection 474 delays. For example, if an IPv4 path to reach a DOTS server is 475 functional, but the DOTS server's IPv6 path is non-functional, a 476 dual-stack DOTS client may experience a significant connection delay 477 compared to an IPv4-only DOTS client, in the same network conditions. 478 The other problem is that if a middlebox between the DOTS client and 479 DOTS server is configured to block UDP traffic, the DOTS client will 480 fail to establish a DTLS association with the DOTS server and, as a 481 consequence, will have to fall back to TLS over TCP, thereby 482 incurring significant connection delays. 484 To overcome these connection setup problems, the DOTS client attempts 485 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 486 both DTLS over UDP and TLS over TCP following a DOTS Happy Eyeballs 487 approach. To some extent, this approach is similar to the Happy 488 Eyeballs mechanism defined in [RFC8305]. The connection attempts are 489 performed by the DOTS client when it initializes, or in general when 490 it has to select an address family and transport to contact its DOTS 491 server. The results of the Happy Eyeballs procedure are used by the 492 DOTS client for sending its subsequent messages to the DOTS server. 493 The difference in behavior with respect to the Happy Eyeballs 494 mechanism [RFC8305] are listed below: 496 o The order of preference of the DOTS signal channel address family 497 and transport protocol (most preferred first) is: UDP over IPv6, 498 UDP over IPv4, TCP over IPv6, and finally TCP over IPv4. This 499 order adheres to the address preference order specified in 500 [RFC6724] and the DOTS signal channel preference which privileges 501 the use of UDP over TCP (to avoid TCP's head of line blocking). 503 o The DOTS client after successfully establishing a connection MUST 504 cache information regarding the outcome of each connection attempt 505 for a specific time period, and it uses that information to avoid 506 thrashing the network with subsequent attempts. The cached 507 information is flushed when its age exceeds a specific time period 508 on the order of few minutes (e.g., 10 min). Typically, if the 509 DOTS client has to re-establish the connection with the same DOTS 510 server within few seconds after the Happy Eyeballs mechanism is 511 completed, caching avoids trashing the network especially in the 512 presence of DDoS attack traffic. 514 o If DOTS signal channel session is established with TLS (but DTLS 515 failed), the DOTS client periodically repeats the mechanism to 516 discover whether DOTS signal channel messages with DTLS over UDP 517 becomes available from the DOTS server, so the DOTS client can 518 migrate the DOTS signal channel from TCP to UDP. Such probing 519 SHOULD NOT be done more frequently than every 24 hours and MUST 520 NOT be done more frequently than every 5 minutes. 522 When connection attempts are made during an attack, the DOTS client 523 SHOULD use a "Connection Attempt Delay" [RFC8305] set to 100 ms. 525 In reference to Figure 4, the DOTS client proceeds with the 526 connection attempts following the rules in [RFC8305]. In this 527 example, it is assumed that the IPv6 path is broken and UDP traffic 528 is dropped by a middlebox but has little impact to the DOTS client 529 because there is no long delay before using IPv4 and TCP. 531 +-----------+ +-----------+ 532 |DOTS client| |DOTS server| 533 +-----------+ +-----------+ 534 | | 535 T0 |--DTLS ClientHello, IPv6 ---->X | 536 T1 |--DTLS ClientHello, IPv4 ---->X | 537 T2 |--TCP SYN, IPv6-------------->X | 538 T3 |--TCP SYN, IPv4--------------------------------------->| 539 |<-TCP SYNACK-------------------------------------------| 540 |--TCP ACK--------------------------------------------->| 541 |<------------Establish TLS Session-------------------->| 542 |----------------DOTS signal--------------------------->| 543 | | 545 Note: 546 * Retransmission messages are not shown. 547 * T1-T0=T2-T1=T3-T2= Connection Attempt Delay. 549 Figure 4: DOTS Happy Eyeballs (Sample Flow) 551 A single DOTS signal channel between DOTS agents can be used to 552 exchange multiple DOTS signal messages. To reduce DOTS client and 553 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 555 4.4. DOTS Mitigation Methods 557 The following methods are used by a DOTS client to request, withdraw, 558 or retrieve the status of mitigation requests: 560 PUT: DOTS clients use the PUT method to request mitigation from a 561 DOTS server (Section 4.4.1). During active mitigation, DOTS 562 clients may use PUT requests to carry mitigation efficacy 563 updates to the DOTS server (Section 4.4.3). 565 GET: DOTS clients may use the GET method to subscribe to DOTS 566 server status messages, or to retrieve the list of its 567 mitigations maintained by a DOTS server (Section 4.4.2). 569 DELETE: DOTS clients use the DELETE method to withdraw a request for 570 mitigation from a DOTS server (Section 4.4.4). 572 Mitigation request and response messages are marked as Non- 573 confirmable messages (Section 2.2 of [RFC7252]). 575 DOTS agents MUST NOT send more than one UDP datagram per round-trip 576 time (RTT) to the peer DOTS agent on average following the data 577 transmission guidelines discussed in Section 3.1.3 of [RFC8085]. 579 Requests marked by the DOTS client as Non-confirmable messages are 580 sent at regular intervals until a response is received from the DOTS 581 server. If the DOTS client cannot maintain an RTT estimate, it MUST 582 NOT send more than one Non-confirmable request every 3 seconds, and 583 SHOULD use an even less aggressive rate whenever possible (case 2 in 584 Section 3.1.3 of [RFC8085]). Mitigation requests MUST NOT be delayed 585 because of checks on probing rate (Section 4.7 of [RFC7252]). 587 JSON encoding of YANG modelled data [RFC7951] is used to illustrate 588 the various methods defined in the following sub-sections. Also, the 589 examples use the Labels defined in Sections 9.6.2, 9.6.3, 9.6.4, and 590 9.6.5. 592 4.4.1. Request Mitigation 594 When a DOTS client requires mitigation for some reason, the DOTS 595 client uses the CoAP PUT method to send a mitigation request to its 596 DOTS server(s) (Figures 5 and 6). 598 If a DOTS client is entitled to solicit the DOTS service, the DOTS 599 server enables mitigation on behalf of the DOTS client by 600 communicating the DOTS client's request to a mitigator (which may be 601 co-located with the DOTS server) and relaying the feedback of the 602 thus-selected mitigator to the requesting DOTS client. 604 Header: PUT (Code=0.03) 605 Uri-Path: ".well-known" 606 Uri-Path: "dots" 607 Uri-Path: "mitigate" 608 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 609 Uri-Path: "mid=123" 610 Content-Format: "application/dots+cbor" 612 { 613 ... 614 } 616 Figure 5: PUT to Convey DOTS Mitigation Requests 618 The order of the Uri-Path options is important as it defines the CoAP 619 resource. In particular, 'mid' MUST follow 'cuid'. 621 The additional Uri-Path parameters to those defined in Section 4.2 622 are as follows: 624 cuid: Stands for Client Unique Identifier. A globally unique 625 identifier that is meant to prevent collisions among DOTS 626 clients, especially those from the same domain. It MUST be 627 generated by DOTS clients. 629 For the reasons discussed in Appendix A, implementations SHOULD 630 set 'cuid' using the following procedure: first, the 631 Distinguished Encoding Rules (DER)-encoded Abstract Syntax 632 Notation One (ASN.1) representation of the Subject Public Key 633 Info (SPKI) of the DOTS client X.509 certificate [RFC5280], the 634 DOTS client raw public key [RFC7250], the "Pre-Shared Key (PSK) 635 identity" used by the DOTS client in the TLS 1.2 636 ClientKeyExchange message, or the "identity" used by the DOTS 637 client in the "pre_shared_key" TLS 1.3 extension is input to 638 the SHA-256 [RFC6234] cryptographic hash. Then, the output of 639 the cryptographic hash algorithm is truncated to 16 bytes; 640 truncation is done by stripping off the final 16 bytes. The 641 truncated output is base64url encoded (Section 5 of [RFC4648]) 642 with the trailing "=" removed from the encoding, and the 643 resulting value used as the 'cuid'. 645 The 'cuid' is intended to be stable when communicating with a 646 given DOTS server, i.e., the 'cuid' used by a DOTS client 647 SHOULD NOT change over time. Distinct 'cuid' values MAY be 648 used by a single DOTS client per DOTS server. 650 If a DOTS client has to change its 'cuid' for some reason, it 651 MUST NOT do so when mitigations are still active for the old 652 'cuid'. The 'cuid' SHOULD be 22 characters to avoid DOTS 653 signal message fragmentation over UDP. Furthermore, if that 654 DOTS client created aliases and filtering entries at the DOTS 655 server by means of the DOTS data channel, it MUST delete all 656 the entries bound to the old 'cuid' and re-install them using 657 the new 'cuid'. 659 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS 660 peer to notify that the 'cuid' is already in-use by another 661 DOTS client. Upon receipt of that error code, a new 'cuid' 662 MUST be generated by the DOTS peer (e.g., using [RFC4122]). 664 Client-domain DOTS gateways MUST handle 'cuid' collision 665 directly and it is RECOMMENDED that 'cuid' collision is handled 666 directly by server-domain DOTS gateways. 668 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 669 Triggers for such rewriting are out of scope. 671 This is a mandatory Uri-Path parameter. 673 mid: Identifier for the mitigation request represented with an 674 integer. This identifier MUST be unique for each mitigation 675 request bound to the DOTS client, i.e., the 'mid' parameter 676 value in the mitigation request needs to be unique (per 'cuid' 677 and DOTS server) relative to the 'mid' parameter values of 678 active mitigation requests conveyed from the DOTS client to the 679 DOTS server. 681 In order to handle out-of-order delivery of mitigation 682 requests, 'mid' values MUST increase monotonically. 684 If the 'mid' value has reached 3/4 of (2**32 - 1) (i.e., 685 3221225471) and no attack is detected, the DOTS client MUST 686 reset 'mid' to 0 to handle 'mid' rollover. If the DOTS client 687 maintains mitigation requests with pre-configured scopes, it 688 MUST re-create them with the 'mid' restarting at 0. 690 This identifier MUST be generated by the DOTS client. 692 This is a mandatory Uri-Path parameter. 694 'cuid' and 'mid' MUST NOT appear in the PUT request message body 695 (Figure 6). The schema in Figure 6 uses the types defined in 696 Section 6. Note that this figure (and other similar figures 697 depicting a schema) are non-normative sketches of the structure of 698 the message. 700 { 701 "ietf-dots-signal-channel:mitigation-scope": { 702 "scope": [ 703 { 704 "target-prefix": [ 705 "string" 706 ], 707 "target-port-range": [ 708 { 709 "lower-port": number, 710 "upper-port": number 711 } 712 ], 713 "target-protocol": [ 714 number 715 ], 716 "target-fqdn": [ 717 "string" 718 ], 719 "target-uri": [ 720 "string" 721 ], 722 "alias-name": [ 723 "string" 724 ], 725 "lifetime": number, 726 "trigger-mitigation": true|false 727 } 728 ] 729 } 730 } 732 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 733 Schema) 735 The parameters in the CBOR body (Figure 6) of the PUT request are 736 described below: 738 target-prefix: A list of prefixes identifying resources under 739 attack. Prefixes are represented using Classless Inter-Domain 740 Routing (CIDR) notation [RFC4632]. 741 As a reminder, the prefix length must be less than or equal to 32 742 (or 128) for IPv4 (or IPv6). 744 The prefix list MUST NOT include broadcast, loopback, or multicast 745 addresses. These addresses are considered as invalid values. In 746 addition, the DOTS server MUST validate that target prefixes are 747 within the scope of the DOTS client domain. Other validation 748 checks may be supported by DOTS servers. 750 This is an optional attribute. 752 target-port-range: A list of port numbers bound to resources under 753 attack. 755 A port range is defined by two bounds, a lower port number (lower- 756 port) and an upper port number (upper-port). When only 'lower- 757 port' is present, it represents a single port number. 759 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 760 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 761 [RFC4340], a range of ports can be, for example, 0-1023, 762 1024-65535, or 1024-49151. 764 This is an optional attribute. 766 target-protocol: A list of protocols involved in an attack. Values 767 are taken from the IANA protocol registry [proto_numbers]. 769 If 'target-protocol' is not specified, then the request applies to 770 any protocol. 772 This is an optional attribute. 774 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 775 identifying resources under attack [RFC8499]. 777 How a name is passed to an underlying name resolution library is 778 implementation- and deployment-specific. Nevertheless, once the 779 name is resolved into one or multiple IP addresses, DOTS servers 780 MUST apply the same validation checks as those for 'target- 781 prefix'. 783 The use of FQDNs may be suboptimal because: 785 * It induces both an extra load and increased delays on the DOTS 786 server to handle and manage DNS resolution requests. 788 * It does not guarantee that the DOTS server will resolve a name 789 to the same IP addresses that the DOTS client does. 791 This is an optional attribute. 793 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 794 identifying resources under attack. 796 The same validation checks used for 'target-fqdn' MUST be followed 797 by DOTS servers to validate a target URI. 799 This is an optional attribute. 801 alias-name: A list of aliases of resources for which the mitigation 802 is requested. Aliases can be created using the DOTS data channel 803 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 804 configuration, or other means. 806 An alias is used in subsequent signal channel exchanges to refer 807 more efficiently to the resources under attack. 809 This is an optional attribute. 811 lifetime: Lifetime of the mitigation request in seconds. The 812 RECOMMENDED lifetime of a mitigation request is 3600 seconds -- 813 this value was chosen to be long enough so that refreshing is not 814 typically a burden on the DOTS client, while still making the 815 request expire in a timely manner when the client has unexpectedly 816 quit. DOTS clients MUST include this parameter in their 817 mitigation requests. Upon the expiry of this lifetime, and if the 818 request is not refreshed, the mitigation request is removed. The 819 request can be refreshed by sending the same request again. 821 A lifetime of '0' in a mitigation request is an invalid value. 823 A lifetime of negative one (-1) indicates indefinite lifetime for 824 the mitigation request. The DOTS server MAY refuse indefinite 825 lifetime, for policy reasons; the granted lifetime value is 826 returned in the response. DOTS clients MUST be prepared to not be 827 granted mitigations with indefinite lifetimes. 829 The DOTS server MUST always indicate the actual lifetime in the 830 response and the remaining lifetime in status messages sent to the 831 DOTS client. 833 This is a mandatory attribute. 835 trigger-mitigation: If the parameter value is set to 'false', DDoS 836 mitigation will not be triggered for the mitigation request unless 837 the DOTS signal channel session is lost. 839 If the DOTS client ceases to respond to heartbeat messages, the 840 DOTS server can detect that the DOTS signal channel session is 841 lost. More details are discussed in Section 4.7. 843 The default value of the parameter is 'true' (that is, the 844 mitigation starts immediately). If 'trigger-mitigation' is not 845 present in a request, this is equivalent to receiving a request 846 with 'trigger-mitigation' set to 'true'. 848 This is an optional attribute. 850 In deployments where server-domain DOTS gateways are enabled, 851 identity information about the origin source client domain ('cdid') 852 SHOULD be propagated to the DOTS server. That information is meant 853 to assist the DOTS server to enforce some policies such as grouping 854 DOTS clients that belong to the same DOTS domain, limiting the number 855 of DOTS requests, and identifying the mitigation scope. These 856 policies can be enforced per-client, per-client domain, or both. 857 Also, the identity information may be used for auditing and debugging 858 purposes. 860 Figure 7 shows an example of a request relayed by a server-domain 861 DOTS gateway. 863 Header: PUT (Code=0.03) 864 Uri-Path: ".well-known" 865 Uri-Path: "dots" 866 Uri-Path: "mitigate" 867 Uri-Path: "cdid=7eeaf349529eb55ed50113" 868 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 869 Uri-Path: "mid=123" 870 Content-Format: "application/dots+cbor" 872 { 873 ... 874 } 876 Figure 7: PUT for DOTS Mitigation Request as Relayed by a DOTS 877 Gateway 879 A server-domain DOTS gateway SHOULD add the following Uri-Path 880 parameter: 882 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed by 883 a server-domain DOTS gateway to propagate the source domain 884 identity from the gateway's client-facing-side to the gateway's 885 server-facing-side, and from the gateway's server-facing-side 886 to the DOTS server. 'cdid' may be used by the final DOTS server 887 for policy enforcement purposes (e.g., enforce a quota on 888 filtering rules). These policies are deployment-specific. 890 Server-domain DOTS gateways SHOULD support a configuration 891 option to instruct whether 'cdid' parameter is to be inserted. 893 In order to accommodate deployments that require enforcing per- 894 client policies, per-client domain policies, or a combination 895 thereof, server-domain DOTS gateways instructed to insert the 896 'cdid' parameter MUST supply the SPKI hash of the DOTS client 897 X.509 certificate, the DOTS client raw public key, or the hash 898 of the "PSK identity" in the 'cdid', following the same rules 899 for generating the hash conveyed in 'cuid', which is then used 900 by the ultimate DOTS server to determine the corresponding 901 client's domain. The 'cdid' generated by a server-domain 902 gateway is likely to be the same as the 'cuid' except if the 903 DOTS message was relayed by a client-domain DOTS gateway or the 904 'cuid' was generated from a rogue DOTS client. 906 If a DOTS client is provisioned, for example, with distinct 907 certificates as a function of the peer server-domain DOTS 908 gateway, distinct 'cdid' values may be supplied by a server- 909 domain DOTS gateway. The ultimate DOTS server MUST treat those 910 'cdid' values as equivalent. 912 The 'cdid' attribute MUST NOT be generated and included by DOTS 913 clients. 915 DOTS servers MUST ignore 'cdid' attributes that are directly 916 supplied by source DOTS clients or client-domain DOTS gateways. 917 This implies that first server-domain DOTS gateways MUST strip 918 'cdid' attributes supplied by DOTS clients. DOTS servers 919 SHOULD support a configuration parameter to identify DOTS 920 gateways that are trusted to supply 'cdid' attributes. 922 Only single-valued 'cdid' are defined in this document. That 923 is, only the first on-path server-domain DOTS gateway can 924 insert a 'cdid' value. This specification does not allow 925 multiple server-domain DOTS gateways, whenever involved in the 926 path, to insert a 'cdid' value for each server-domain gateway. 928 This is an optional Uri-Path. When present, 'cdid' MUST be 929 positioned before 'cuid'. 931 A DOTS gateway SHOULD add the CoAP Hop-Limit Option 932 [I-D.ietf-core-hop-limit]. 934 Because of the complexity to handle partial failure cases, this 935 specification does not allow for including multiple mitigation 936 requests in the same PUT request. Concretely, a DOTS client MUST NOT 937 include multiple entries in the 'scope' array of the same PUT 938 request. 940 FQDN and URI mitigation scopes may be thought of as a form of scope 941 alias, in which the addresses associated with the domain name or URI 942 (as resolved by the DOTS server) represent the scope of the 943 mitigation. Particularly, the IP addresses to which the host 944 subcomponent of authority component of an URI resolves represent the 945 'target-prefix', the URI scheme represents the 'target-protocol', the 946 port subcomponent of authority component of an URI represents the 947 'target-port-range'. If the optional port information is not present 948 in the authority component, the default port defined for the URI 949 scheme represents the 'target-port'. 951 In the PUT request at least one of the attributes 'target-prefix', 952 'target-fqdn','target-uri', or 'alias-name' MUST be present. 954 Attributes and Uri-Path parameters with empty values MUST NOT be 955 present in a request and render the entire request invalid. 957 Figure 8 shows a PUT request example to signal that TCP port numbers 958 80, 8080, and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 959 servers are under attack. The presence of 'cdid' indicates that a 960 server-domain DOTS gateway has modified the initial PUT request sent 961 by the DOTS client. Note that 'cdid' MUST NOT appear in the PUT 962 request message body. 964 Header: PUT (Code=0.03) 965 Uri-Path: ".well-known" 966 Uri-Path: "dots" 967 Uri-Path: "mitigate" 968 Uri-Path: "cdid=7eeaf349529eb55ed50113" 969 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 970 Uri-Path: "mid=123" 971 Content-Format: "application/dots+cbor" 973 { 974 "ietf-dots-signal-channel:mitigation-scope": { 975 "scope": [ 976 { 977 "target-prefix": [ 978 "2001:db8:6401::1/128", 979 "2001:db8:6401::2/128" 980 ], 981 "target-port-range": [ 982 { 983 "lower-port": 80 984 }, 985 { 986 "lower-port": 443 987 }, 988 { 989 "lower-port": 8080 990 } 991 ], 992 "target-protocol": [ 993 6 994 ], 995 "lifetime": 3600 996 } 997 ] 998 } 999 } 1001 Figure 8: PUT for DOTS Mitigation Request (An Example) 1003 The corresponding CBOR encoding format for the payload is shown in 1004 Figure 9. 1006 A1 # map(1) 1007 01 # unsigned(1) 1008 A1 # map(1) 1009 02 # unsigned(2) 1010 81 # array(1) 1011 A3 # map(3) 1012 06 # unsigned(6) 1013 82 # array(2) 1014 74 # text(20) 1015 323030313A6462383A363430313A3A312F313238 1016 74 # text(20) 1017 323030313A6462383A363430313A3A322F313238 1018 07 # unsigned(7) 1019 83 # array(3) 1020 A1 # map(1) 1021 08 # unsigned(8) 1022 18 50 # unsigned(80) 1023 A1 # map(1) 1024 08 # unsigned(8) 1025 19 01BB # unsigned(443) 1026 A1 # map(1) 1027 08 # unsigned(8) 1028 19 1F90 # unsigned(8080) 1029 0A # unsigned(10) 1030 81 # array(1) 1031 06 # unsigned(6) 1032 0E # unsigned(14) 1033 19 0E10 # unsigned(3600) 1035 Figure 9: PUT for DOTS Mitigation Request (CBOR) 1037 In both DOTS signal and data channel sessions, the DOTS client MUST 1038 authenticate itself to the DOTS server (Section 8). The DOTS server 1039 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 1040 the DOTS client identity or username from the client certificate. 1041 The DOTS client identity allows the DOTS server to accept mitigation 1042 requests with scopes that the DOTS client is authorized to manage. 1044 The DOTS server couples the DOTS signal and data channel sessions 1045 using the DOTS client identity and optionally the 'cdid' parameter 1046 value, so the DOTS server can validate whether the aliases conveyed 1047 in the mitigation request were indeed created by the same DOTS client 1048 using the DOTS data channel session. If the aliases were not created 1049 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 1050 the response. 1052 The DOTS server couples the DOTS signal channel sessions using the 1053 DOTS client identity and optionally the 'cdid' parameter value, and 1054 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 1055 detect duplicate mitigation requests. If the mitigation request 1056 contains the 'alias-name' and other parameters identifying the target 1057 resources (such as 'target-prefix', 'target-port-range', 'target- 1058 fqdn', or 'target-uri'), the DOTS server appends the parameter values 1059 in 'alias-name' with the corresponding parameter values in 'target- 1060 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 1062 The DOTS server indicates the result of processing the PUT request 1063 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 1064 codes are some sort of invalid requests (client errors). COAP 5.xx 1065 codes are returned if the DOTS server is in an error state or is 1066 currently unavailable to provide mitigation in response to the 1067 mitigation request from the DOTS client. 1069 Figure 10 shows an example response to a PUT request that is 1070 successfully processed by a DOTS server (i.e., CoAP 2.xx response 1071 codes). This version of the specification forbids 'cuid' and 'cdid' 1072 (if used) to be returned in a response message body. 1074 { 1075 "ietf-dots-signal-channel:mitigation-scope": { 1076 "scope": [ 1077 { 1078 "mid": 123, 1079 "lifetime": 3600 1080 } 1081 ] 1082 } 1083 } 1085 Figure 10: 2.xx Response Body 1087 If the request is missing a mandatory attribute, does not include 1088 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1089 parameters, or contains invalid or unknown parameters, the DOTS 1090 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1091 ignore comprehension-optional parameters they don't understand 1092 (Section 9.6.1.1). 1094 A DOTS server that receives a mitigation request with a lifetime set 1095 to '0' MUST reply with a 4.00 (Bad Request). 1097 If the DOTS server does not find the 'mid' parameter value conveyed 1098 in the PUT request in its configuration data, it MAY accept the 1099 mitigation request by sending back a 2.01 (Created) response to the 1100 DOTS client; the DOTS server will consequently try to mitigate the 1101 attack. A DOTS server could reject mitigation requests when it is 1102 near capacity or needs to rate-limit a particular client, for 1103 example. 1105 The relative order of two mitigation requests, having the same 1106 'trigger-mitigation' type, from a DOTS client is determined by 1107 comparing their respective 'mid' values. If two mitigation requests 1108 with the same 'trigger-mitigation' type have overlapping mitigation 1109 scopes, the mitigation request with the highest numeric 'mid' value 1110 will override the other mitigation request. Two mitigation requests 1111 from a DOTS client have overlapping scopes if there is a common IP 1112 address, IP prefix, FQDN, URI, or alias-name. To avoid maintaining a 1113 long list of overlapping mitigation requests (i.e., requests with the 1114 same 'trigger-mitigation' type and overlapping scopes) from a DOTS 1115 client and avoid error-prone provisioning of mitigation requests from 1116 a DOTS client, the overlapped lower numeric 'mid' MUST be 1117 automatically deleted and no longer available at the DOTS server. 1118 For example, if the DOTS server receives a mitigation request which 1119 overlaps with an existing mitigation with a higher numeric 'mid', the 1120 DOTS server rejects the request by returning 4.09 (Conflict) to the 1121 DOTS client. The response includes enough information for a DOTS 1122 client to recognize the source of the conflict as described below in 1123 the 'conflict-information' subtree with only the relevant nodes 1124 listed: 1126 conflict-information: Indicates that a mitigation request is 1127 conflicting with another mitigation request. This optional 1128 attribute has the following structure: 1130 conflict-cause: Indicates the cause of the conflict. The 1131 following values are defined: 1133 1: Overlapping targets. 'conflict-scope' provides more details 1134 about the conflicting target clauses. 1136 conflict-scope: Characterizes the exact conflict scope. It may 1137 include a list of IP addresses, a list of prefixes, a list of 1138 port numbers, a list of target protocols, a list of FQDNs, a 1139 list of URIs, a list of alias-names, or a 'mid'. 1141 If the DOTS server receives a mitigation request which overlaps with 1142 an active mitigation request, but both having distinct 'trigger- 1143 mitigation' types, the DOTS server SHOULD deactivate (absent explicit 1144 policy/configuration otherwise) the mitigation request with 'trigger- 1145 mitigation' set to false. Particularly, if the mitigation request 1146 with 'trigger-mitigation' set to false is active, the DOTS server 1147 withdraws the mitigation request (i.e., status code is set to '7' as 1148 defined in Table 2) and transitions the status of the mitigation 1149 request to '8'. 1151 Upon DOTS signal channel session loss with a peer DOTS client, the 1152 DOTS server SHOULD withdraw (absent explicit policy/configuration 1153 otherwise) any active mitigation requests overlapping with mitigation 1154 requests having 'trigger-mitigation' set to false from that DOTS 1155 client, as the loss of the session implicitly activates these 1156 preconfigured mitigation requests and they take precedence. Note 1157 that active-but-terminating period is not observed for mitigations 1158 withdrawn at the initiative of the DOTS server. 1160 DOTS clients may adopt various strategies for setting the scopes of 1161 immediate and pre-configured mitigation requests to avoid potential 1162 conflicts. For example, a DOTS client may tweak pre-configured 1163 scopes so that the scope of any overlapping immediate mitigation 1164 request will be a subset of the pre-configured scopes. Also, if an 1165 immediate mitigation request overlaps with any of the pre-configured 1166 scopes, the DOTS client sets the scope of the overlapping immediate 1167 mitigation request to be a subset of the pre-configured scopes, so as 1168 to get a broad mitigation when the DOTS signal channel collapses and 1169 maximize the chance of recovery. 1171 If the request is conflicting with an existing mitigation request 1172 from a different DOTS client, the DOTS server may return 2.01 1173 (Created) or 4.09 (Conflict) to the requesting DOTS client. If the 1174 DOTS server decides to maintain the new mitigation request, the DOTS 1175 server returns 2.01 (Created) to the requesting DOTS client. If the 1176 DOTS server decides to reject the new mitigation request, the DOTS 1177 server returns 4.09 (Conflict) to the requesting DOTS client. For 1178 both 2.01 (Created) and 4.09 (Conflict) responses, the response 1179 includes enough information for a DOTS client to recognize the source 1180 of the conflict as described below: 1182 conflict-information: Indicates that a mitigation request is 1183 conflicting with another mitigation request(s) from other DOTS 1184 client(s). This optional attribute has the following structure: 1186 conflict-status: Indicates the status of a conflicting mitigation 1187 request. The following values are defined: 1189 1: DOTS server has detected conflicting mitigation requests 1190 from different DOTS clients. This mitigation request is 1191 currently inactive until the conflicts are resolved. 1192 Another mitigation request is active. 1194 2: DOTS server has detected conflicting mitigation requests 1195 from different DOTS clients. This mitigation request is 1196 currently active. 1198 3: DOTS server has detected conflicting mitigation requests 1199 from different DOTS clients. All conflicting mitigation 1200 requests are inactive. 1202 conflict-cause: Indicates the cause of the conflict. The 1203 following values are defined: 1205 1: Overlapping targets. 'conflict-scope' provides more details 1206 about the conflicting target clauses. 1208 2: Conflicts with an existing accept-list. This code is 1209 returned when the DDoS mitigation detects source addresses/ 1210 prefixes in the accept-listed ACLs are attacking the 1211 target. 1213 3: CUID Collision. This code is returned when a DOTS client 1214 uses a 'cuid' that is already used by another DOTS client. 1215 This code is an indication that the request has been 1216 rejected and a new request with a new 'cuid' is to be re- 1217 sent by the DOTS client (see the example shown in 1218 Figure 11). Note that 'conflict-status', 'conflict-scope', 1219 and 'retry-timer' MUST NOT be returned in the error 1220 response. 1222 conflict-scope: Characterizes the exact conflict scope. It may 1223 include a list of IP addresses, a list of prefixes, a list of 1224 port numbers, a list of target protocols, a list of FQDNs, a 1225 list of URIs, a list of alias-names, or references to 1226 conflicting ACLs (by an 'acl-name', typically 1227 [I-D.ietf-dots-data-channel]). 1229 retry-timer: Indicates, in seconds, the time after which the DOTS 1230 client may re-issue the same request. The DOTS server returns 1231 'retry-timer' only to DOTS client(s) for which a mitigation 1232 request is deactivated. Any retransmission of the same 1233 mitigation request before the expiry of this timer is likely to 1234 be rejected by the DOTS server for the same reasons. 1236 The retry-timer SHOULD be equal to the lifetime of the active 1237 mitigation request resulting in the deactivation of the 1238 conflicting mitigation request. 1240 If the DOTS server decides to maintain a state for the 1241 deactivated mitigation request, the DOTS server updates the 1242 lifetime of the deactivated mitigation request to 'retry-timer 1243 + 45 seconds' (that is, this mitigation request remains 1244 deactivated for the entire duration of 'retry-timer + 45 1245 seconds') so that the DOTS client can refresh the deactivated 1246 mitigation request after 'retry-timer' seconds, but before the 1247 expiry of the lifetime, and check if the conflict is resolved. 1249 Header: PUT (Code=0.03) 1250 Uri-Path: ".well-known" 1251 Uri-Path: "dots" 1252 Uri-Path: "mitigate" 1253 Uri-Path: "cuid=7eeaf349529eb55ed50113" 1254 Uri-Path: "mid=12" 1256 (1) Request with a conflicting 'cuid' 1258 { 1259 "ietf-dots-signal-channel:mitigation-scope": { 1260 "scope": [ 1261 { 1262 "conflict-information": { 1263 "conflict-cause": "cuid-collision" 1264 } 1265 } 1266 ] 1267 } 1268 } 1270 (2) Message body of the 4.09 (Conflict) response 1271 from the DOTS server 1273 Header: PUT (Code=0.03) 1274 Uri-Path: ".well-known" 1275 Uri-Path: "dots" 1276 Uri-Path: "mitigate" 1277 Uri-Path: "cuid=f30d281ce6b64fc5a0b91e" 1278 Uri-Path: "mid=12" 1280 (3) Request with a new 'cuid' 1282 Figure 11: Example of Generating a New 'cuid' 1284 As an active attack evolves, DOTS clients can adjust the scope of 1285 requested mitigation as necessary, by refining the scope of resources 1286 requiring mitigation. This can be achieved by sending a PUT request 1287 with a new 'mid' value that will override the existing one with 1288 overlapping mitigation scopes. 1290 For a mitigation request to continue beyond the initial negotiated 1291 lifetime, the DOTS client has to refresh the current mitigation 1292 request by sending a new PUT request. This PUT request MUST use the 1293 same 'mid' value, and MUST repeat all the other parameters as sent in 1294 the original mitigation request apart from a possible change to the 1295 lifetime parameter value. In such case, the DOTS server MAY update 1296 the mitigation request, and a 2.04 (Changed) response is returned to 1297 indicate a successful update of the mitigation request. If this is 1298 not the case, the DOTS server MUST reject the request with a 4.00 1299 (Bad Request). 1301 4.4.2. Retrieve Information Related to a Mitigation 1303 A GET request is used by a DOTS client to retrieve information 1304 (including status) of DOTS mitigations from a DOTS server. 1306 'cuid' is a mandatory Uri-Path parameter for GET requests. 1308 Uri-Path parameters with empty values MUST NOT be present in a 1309 request. 1311 The same considerations for manipulating 'cdid' parameter by server- 1312 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1313 GET requests. 1315 The 'c' Uri-Query option is used to control selection of 1316 configuration and non-configuration data nodes. Concretely, the 'c' 1317 (content) parameter and its permitted values defined in the following 1318 table [I-D.ietf-core-comi] can be used to retrieve non-configuration 1319 data (attack mitigation status), configuration data, or both. The 1320 DOTS server MAY support this optional filtering capability. It can 1321 safely ignore it if not supported. If the DOTS client supports the 1322 optional filtering capability, it SHOULD use "c=n" query (to get back 1323 only the dynamically changing data) or "c=c" query (to get back the 1324 static configuration values) when the DDoS attack is active to limit 1325 the size of the response. 1327 +-------+-----------------------------------------------------+ 1328 | Value | Description | 1329 +-------+-----------------------------------------------------+ 1330 | c | Return only configuration descendant data nodes | 1331 | n | Return only non-configuration descendant data nodes | 1332 | a | Return all descendant data nodes | 1333 +-------+-----------------------------------------------------+ 1335 The DOTS client can use Block-wise transfer [RFC7959] to get the list 1336 of all its mitigations maintained by a DOTS server, it can send 1337 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1338 size of the response. If the representation of all the active 1339 mitigation requests associated with the DOTS client does not fit 1340 within a single datagram, the DOTS server MUST use the Block2 Option 1341 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1342 in the response to indicate the total size of the resource 1343 representation. The DOTS client retrieves the rest of the 1344 representation by sending additional GET requests with Block2 Options 1345 containing NUM values greater than zero. The DOTS client MUST adhere 1346 to the block size preferences indicated by the DOTS server in the 1347 response. If the DOTS server uses the Block2 Option in the GET 1348 response and the response is for a dynamically changing resource 1349 (e.g., "c=n" or "c=a" query), the DOTS server MUST include the ETag 1350 Option in the response. The DOTS client MUST include the same ETag 1351 value in subsequent GET requests to retrieve the rest of the 1352 representation. 1354 The following examples illustrate how a DOTS client retrieves active 1355 mitigation requests from a DOTS server. In particular: 1357 o Figure 12 shows the example of a GET request to retrieve all DOTS 1358 mitigation requests signaled by a DOTS client. 1360 o Figure 13 shows the example of a GET request to retrieve a 1361 specific DOTS mitigation request signaled by a DOTS client. The 1362 configuration data to be reported in the response is formatted in 1363 the same order as was processed by the DOTS server in the original 1364 mitigation request. 1366 These two examples assume the default of "c=a"; that is, the DOTS 1367 client asks for all data to be reported by the DOTS server. 1369 Header: GET (Code=0.01) 1370 Uri-Path: ".well-known" 1371 Uri-Path: "dots" 1372 Uri-Path: "mitigate" 1373 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1374 Observe: 0 1376 Figure 12: GET to Retrieve all DOTS Mitigation Requests 1378 Header: GET (Code=0.01) 1379 Uri-Path: ".well-known" 1380 Uri-Path: "dots" 1381 Uri-Path: "mitigate" 1382 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1383 Uri-Path: "mid=12332" 1384 Observe: 0 1386 Figure 13: GET to Retrieve a Specific DOTS Mitigation Request 1388 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1389 the GET request in its configuration data for the requesting DOTS 1390 client, it MUST respond with a 4.04 (Not Found) error response code. 1391 Likewise, the same error MUST be returned as a response to a request 1392 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1393 defined) of a given DOTS client if the DOTS server does not find any 1394 mitigation record for that DOTS client. As a reminder, a DOTS client 1395 is identified by its identity (e.g., client certificate, 'cuid') and 1396 optionally the 'cdid'. 1398 Figure 14 shows a response example of all active mitigation requests 1399 associated with the DOTS client as maintained by the DOTS server. 1400 The response indicates the mitigation status of each mitigation 1401 request. 1403 { 1404 "ietf-dots-signal-channel:mitigation-scope": { 1405 "scope": [ 1406 { 1407 "mid": 12332, 1408 "mitigation-start": "1507818434", 1409 "target-prefix": [ 1410 "2001:db8:6401::1/128", 1411 "2001:db8:6401::2/128" 1412 ], 1413 "target-protocol": [ 1414 17 1415 ], 1416 "lifetime": 1756, 1417 "status": "attack-successfully-mitigated", 1418 "bytes-dropped": "134334555", 1419 "bps-dropped": "43344", 1420 "pkts-dropped": "333334444", 1421 "pps-dropped": "432432" 1422 }, 1423 { 1424 "mid": 12333, 1425 "mitigation-start": "1507818393", 1426 "target-prefix": [ 1427 "2001:db8:6401::1/128", 1428 "2001:db8:6401::2/128" 1429 ], 1430 "target-protocol": [ 1431 6 1432 ], 1433 "lifetime": 1755, 1434 "status": "attack-stopped", 1435 "bytes-dropped": "0", 1436 "bps-dropped": "0", 1437 "pkts-dropped": "0", 1438 "pps-dropped": "0" 1439 } 1440 ] 1441 } 1442 } 1444 Figure 14: Response Body to a GET Request 1446 The mitigation status parameters are described below: 1448 mitigation-start: Mitigation start time is expressed in seconds 1449 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1451 [RFC7049]). The CBOR encoding is modified so that the leading tag 1452 1 (epoch-based date/time) MUST be omitted. 1454 This is a mandatory attribute when an attack mitigation is active. 1455 Particularly, 'mitigation-start' is not returned for a mitigation 1456 with 'status' code set to 8. 1458 lifetime: The remaining lifetime of the mitigation request, in 1459 seconds. 1461 This is a mandatory attribute. 1463 status: Status of attack mitigation. The various possible values of 1464 'status' parameter are explained in Table 2. 1466 This is a mandatory attribute. 1468 bytes-dropped: The total dropped byte count for the mitigation 1469 request since the attack mitigation is triggered. The count wraps 1470 around when it reaches the maximum value of unsigned integer64. 1472 This is an optional attribute. 1474 bps-dropped: The average number of dropped bytes per second for the 1475 mitigation request since the attack mitigation is triggered. This 1476 average SHOULD be over five-minute intervals (that is, measuring 1477 bytes into five-minute buckets and then averaging these buckets 1478 over the time since the mitigation was triggered). 1480 This is an optional attribute. 1482 pkts-dropped: The total number of dropped packet count for the 1483 mitigation request since the attack mitigation is triggered. The 1484 count wraps around when it reaches the maximum value of unsigned 1485 integer64. 1487 This is an optional attribute. 1489 pps-dropped: The average number of dropped packets per second for 1490 the mitigation request since the attack mitigation is triggered. 1491 This average SHOULD be over five-minute intervals (that is, 1492 measuring packets into five-minute buckets and then averaging 1493 these buckets over the time since the mitigation was triggered). 1495 This is an optional attribute. 1497 +-----------+-------------------------------------------------------+ 1498 | Parameter | Description | 1499 | Value | | 1500 +-----------+-------------------------------------------------------+ 1501 | 1 | Attack mitigation setup is in progress (e.g., | 1502 | | changing the network path to redirect the | 1503 | | inbound traffic to a DOTS mitigator). | 1504 +-----------+-------------------------------------------------------+ 1505 | 2 | Attack is being successfully mitigated (e.g., traffic | 1506 | | is redirected to a DDoS mitigator and | 1507 | | attack traffic is dropped). | 1508 +-----------+-------------------------------------------------------+ 1509 | 3 | Attack has stopped and the DOTS client can withdraw | 1510 | | the mitigation request. This status code | 1511 | | will be transmitted for immediate | 1512 | | mitigation requests till the mitigation is withdrawn | 1513 | | or the lifetime expires. For mitigation | 1514 | | requests with pre-configured scopes | 1515 | | (i.e., 'trigger-mitigation' set to 'false'), this | 1516 | | status code will be transmitted 4 times | 1517 | | and then 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- | 1529 | | mitigation' set to false is withdrawn | 1530 | | because it overlaps with an immediate mitigation | 1531 | | request, this status code will be transmitted 4 times | 1532 | | and then transition to "8" for the | 1533 | | mitigation request with pre-configured | 1534 | | scopes. | 1535 +-----------+-------------------------------------------------------+ 1536 | 8 | Attack mitigation will be triggered for the | 1537 | | mitigation request only when the DOTS | 1538 | | signal channel session is lost. | 1539 +-----------+-------------------------------------------------------+ 1541 Table 2: Values of 'status' Parameter 1543 4.4.2.1. DOTS Servers Sending Mitigation Status 1545 The Observe Option defined in [RFC7641] extends the CoAP core 1546 protocol with a mechanism for a CoAP client to "observe" a resource 1547 on a CoAP server: The client retrieves a representation of the 1548 resource and requests this representation be updated by the server as 1549 long as the client is interested in the resource. DOTS 1550 implementations MUST use the Observe Option for both 'mitigate' and 1551 'config' (Section 4.2). 1553 A DOTS client conveys the Observe Option set to '0' in the GET 1554 request to receive asynchronous notifications of attack mitigation 1555 status from the DOTS server. 1557 Unidirectional mitigation notifications within the bidirectional 1558 signal channel enables asynchronous notifications between the agents. 1559 [RFC7641] indicates that (1) a notification can be sent in a 1560 Confirmable or a Non-confirmable message, and (2) the message type 1561 used is typically application-dependent and may be determined by the 1562 server for each notification individually. For DOTS server 1563 application, the message type MUST always be set to Non-confirmable 1564 even if the underlying COAP library elects a notification to be sent 1565 in a Confirmable message. This overrides the behavior defined in 1566 Section 4.5 of [RFC7641] to send a Confirmable message instead of a 1567 Non-confirmable message at least every 24 hour for the following 1568 reasons: First, the DOTS signal channel uses a heartbeat mechanism to 1569 determine if the DOTS client is alive. Second, Confirmable messages 1570 are not suitable during an attack. 1572 Due to the higher likelihood of packet loss during a DDoS attack, the 1573 DOTS server periodically sends attack mitigation status to the DOTS 1574 client and also notifies the DOTS client whenever the status of the 1575 attack mitigation changes. If the DOTS server cannot maintain an RTT 1576 estimate, it MUST NOT send more than one asynchronous notification 1577 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1578 possible (case 2 in Section 3.1.3 of [RFC8085]). 1580 When conflicting requests are detected, the DOTS server enforces the 1581 corresponding policy (e.g., accept all requests, reject all requests, 1582 accept only one request but reject all the others, ...). It is 1583 assumed that this policy is supplied by the DOTS server administrator 1584 or it is a default behavior of the DOTS server implementation. Then, 1585 the DOTS server sends notification message(s) to the DOTS client(s) 1586 at the origin of the conflict (refer to the conflict parameters 1587 defined in Section 4.4.1). A conflict notification message includes 1588 information about the conflict cause, scope, and the status of the 1589 mitigation request(s). For example, 1590 o A notification message with 'status' code set to '7 (Attack 1591 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1592 to a DOTS client to indicate that an active mitigation request is 1593 deactivated because a conflict is detected. 1595 o A notification message with 'status' code set to '1 (Attack 1596 mitigation is in progress)' and 'conflict-status' set to '2' is 1597 sent to a DOTS client to indicate that this mitigation request is 1598 in progress, but a conflict is detected. 1600 Upon receipt of a conflict notification message indicating that a 1601 mitigation request is deactivated because of a conflict, a DOTS 1602 client MUST NOT resend the same mitigation request before the expiry 1603 of 'retry-timer'. It is also recommended that DOTS clients support 1604 means to alert administrators about mitigation conflicts. 1606 A DOTS client that is no longer interested in receiving notifications 1607 from the DOTS server can simply "forget" the observation. When the 1608 DOTS server sends the next notification, the DOTS client will not 1609 recognize the token in the message and thus will return a Reset 1610 message. This causes the DOTS server to remove the associated entry. 1611 Alternatively, the DOTS client can explicitly deregister itself by 1612 issuing a GET request that has the Token field set to the token of 1613 the observation to be cancelled and includes an Observe Option with 1614 the value set to '1' (deregister). The latter is more deterministic 1615 and thus is RECOMMENDED. 1617 Figure 15 shows an example of a DOTS client requesting a DOTS server 1618 to send notifications related to a mitigation request. Note that for 1619 mitigations with pre-configured scopes (i.e., 'trigger-mitigation' 1620 set to 'false'), the state will need to transition from 3 (attack- 1621 stopped) to 8 (attack-mitigation-signal-loss). 1623 +-----------+ +-----------+ 1624 |DOTS client| |DOTS server| 1625 +-----------+ +-----------+ 1626 | | 1627 | GET / | 1628 | Token: 0x4a | Registration 1629 | Observe: 0 | 1630 +----------------------------------------->| 1631 | | 1632 | 2.05 Content | 1633 | Token: 0x4a | Notification of 1634 | Observe: 12 | the current state 1635 | status: "attack-mitigation-in-progress" | 1636 | | 1637 |<-----------------------------------------+ 1638 | 2.05 Content | 1639 | Token: 0x4a | Notification upon 1640 | Observe: 44 | a state change 1641 | status: "attack-successfully-mitigated" | 1642 | | 1643 |<-----------------------------------------+ 1644 | 2.05 Content | 1645 | Token: 0x4a | Notification upon 1646 | Observe: 60 | a state change 1647 | status: "attack-stopped" | 1648 |<-----------------------------------------+ 1649 | | 1650 ... 1652 Figure 15: Notifications of Attack Mitigation Status 1654 4.4.2.2. DOTS Clients Polling for Mitigation Status 1656 The DOTS client can send the GET request at frequent intervals 1657 without the Observe Option to retrieve the configuration data of the 1658 mitigation request and non-configuration data (i.e., the attack 1659 status). DOTS clients MAY be configured with a policy indicating the 1660 frequency of polling DOTS servers to get the mitigation status. This 1661 frequency MUST NOT be more than one UDP datagram per RTT as discussed 1662 in Section 3.1.3 of [RFC8085]. 1664 If the DOTS server has been able to mitigate the attack and the 1665 attack has stopped, the DOTS server indicates as such in the status. 1666 In such case, the DOTS client recalls the mitigation request by 1667 issuing a DELETE request for this mitigation request (Section 4.4.4). 1669 A DOTS client SHOULD react to the status of the attack as per the 1670 information sent by the DOTS server rather than performing its own 1671 detection that the attack has been mitigated. This ensures that the 1672 DOTS client does not recall a mitigation request prematurely because 1673 it is possible that the DOTS client does not sense the DDoS attack on 1674 its resources, but the DOTS server could be actively mitigating the 1675 attack because the attack is not completely averted. 1677 4.4.3. Efficacy Update from DOTS Clients 1679 While DDoS mitigation is in progress, due to the likelihood of packet 1680 loss, a DOTS client MAY periodically transmit DOTS mitigation 1681 efficacy updates to the relevant DOTS server. A PUT request is used 1682 to convey the mitigation efficacy update to the DOTS server. This 1683 PUT request is treated as a refresh of the current mitigation. 1685 The PUT request used for efficacy update MUST include all the 1686 parameters used in the PUT request to carry the DOTS mitigation 1687 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1688 value. If this is not the case, the DOTS server MUST reject the 1689 request with a 4.00 (Bad Request). 1691 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1692 value is used to make the PUT request conditional on the current 1693 existence of the mitigation request. If UDP is used as transport, 1694 CoAP requests may arrive out-of-order. For example, the DOTS client 1695 may send a PUT request to convey an efficacy update to the DOTS 1696 server followed by a DELETE request to withdraw the mitigation 1697 request, but the DELETE request arrives at the DOTS server before the 1698 PUT request. To handle out-of-order delivery of requests, if an If- 1699 Match Option is present in the PUT request and the 'mid' in the 1700 request matches a mitigation request from that DOTS client, the 1701 request is processed by the DOTS server. If no match is found, the 1702 PUT request is silently ignored by the DOTS server. 1704 An example of an efficacy update message, which includes an If-Match 1705 Option with an empty value, is depicted in Figure 16. 1707 Header: PUT (Code=0.03) 1708 Uri-Path: ".well-known" 1709 Uri-Path: "dots" 1710 Uri-Path: "mitigate" 1711 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1712 Uri-Path: "mid=123" 1713 If-Match: 1714 Content-Format: "application/dots+cbor" 1716 { 1717 "ietf-dots-signal-channel:mitigation-scope": { 1718 "scope": [ 1719 { 1720 "target-prefix": [ 1721 "2001:db8:6401::1/128", 1722 "2001:db8:6401::2/128" 1723 ], 1724 "target-port-range": [ 1725 { 1726 "lower-port": 80 1727 }, 1728 { 1729 "lower-port": 443 1730 }, 1731 { 1732 "lower-port": 8080 1733 } 1734 ], 1735 "target-protocol": [ 1736 6 1737 ], 1738 "attack-status": "under-attack" 1739 } 1740 ] 1741 } 1742 } 1744 Figure 16: An Example of Efficacy Update 1746 The 'attack-status' parameter is a mandatory attribute when 1747 performing an efficacy update. The various possible values contained 1748 in the 'attack-status' parameter are described in Table 3. 1750 +-----------+-------------------------------------------------------+ 1751 | Parameter | Description | 1752 | value | | 1753 +-----------+-------------------------------------------------------+ 1754 | 1 | The DOTS client determines that it is still under | 1755 | | attack. | 1756 +-----------+-------------------------------------------------------+ 1757 | 2 | The DOTS client determines that the attack is | 1758 | | successfully mitigated (e.g., attack | 1759 | | traffic is not seen). | 1760 +-----------+-------------------------------------------------------+ 1762 Table 3: Values of 'attack-status' Parameter 1764 The DOTS server indicates the result of processing a PUT request 1765 using CoAP response codes. The response code 2.04 (Changed) is 1766 returned if the DOTS server has accepted the mitigation efficacy 1767 update. The error response code 5.03 (Service Unavailable) is 1768 returned if the DOTS server has erred or is incapable of performing 1769 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age option 1770 to indicate the number of seconds after which to retry. 1772 4.4.4. Withdraw a Mitigation 1774 DELETE requests are used to withdraw DOTS mitigation requests from 1775 DOTS servers (Figure 17). 1777 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1778 requests. 1780 The same considerations for manipulating 'cdid' parameter by DOTS 1781 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1782 requests. Uri-Path parameters with empty values MUST NOT be present 1783 in a request. 1785 Header: DELETE (Code=0.04) 1786 Uri-Path: ".well-known" 1787 Uri-Path: "dots" 1788 Uri-Path: "mitigate" 1789 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1790 Uri-Path: "mid=123" 1792 Figure 17: Withdraw a DOTS Mitigation 1794 If the DELETE request does not include 'cuid' and 'mid' parameters, 1795 the DOTS server MUST reply with a 4.00 (Bad Request). 1797 Once the request is validated, the DOTS server immediately 1798 acknowledges a DOTS client's request to withdraw the DOTS signal 1799 using 2.02 (Deleted) response code with no response payload. A 2.02 1800 (Deleted) Response Code is returned even if the 'mid' parameter value 1801 conveyed in the DELETE request does not exist in its configuration 1802 data before the request. 1804 If the DOTS server finds the 'mid' parameter value conveyed in the 1805 DELETE request in its configuration data for the DOTS client, then to 1806 protect against route or DNS flapping caused by a DOTS client rapidly 1807 removing a mitigation, and to dampen the effect of oscillating 1808 attacks, the DOTS server MAY allow mitigation to continue for a 1809 limited period after acknowledging a DOTS client's withdrawal of a 1810 mitigation request. During this period, the DOTS server status 1811 messages SHOULD indicate that mitigation is active but terminating 1812 (Section 4.4.2). 1814 The initial active-but-terminating period SHOULD be sufficiently long 1815 to absorb latency incurred by route propagation. The active-but- 1816 terminating period SHOULD be set by default to 120 seconds. If the 1817 client requests mitigation again before the initial active-but- 1818 terminating period elapses, the DOTS server MAY exponentially 1819 increase (the base of the exponent is 2) the active-but-terminating 1820 period up to a maximum of 300 seconds (5 minutes). 1822 Once the active-but-terminating period elapses, the DOTS server MUST 1823 treat the mitigation as terminated, as the DOTS client is no longer 1824 responsible for the mitigation. 1826 If a mitigation is triggered due to a signal channel loss, the DOTS 1827 server relies upon normal triggers to stop that mitigation 1828 (typically, receipt of a valid DELETE request, expiry of the 1829 mitigation lifetime, or scrubbing the traffic to the attack target). 1830 In particular, the DOTS server MUST NOT consider the signal channel 1831 recovery as a trigger to stop the mitigation. 1833 4.5. DOTS Signal Channel Session Configuration 1835 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1836 channel session behavior with its DOTS peers. The DOTS signal 1837 channel can be used, for example, to configure the following: 1839 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1840 send heartbeats to each other after mutual authentication is 1841 successfully completed in order to keep the DOTS signal channel 1842 open. Heartbeat messages are exchanged between DOTS agents every 1843 'heartbeat-interval' seconds to detect the current status of the 1844 DOTS signal channel session. 1846 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1847 indicates the maximum number of consecutive heartbeat messages 1848 for which a DOTS agent did not receive a response before 1849 concluding that the session is disconnected or defunct. 1851 c. Acceptable probing rate (probing-rate): This parameter indicates 1852 the average data rate that must not be exceeded by a DOTS agent 1853 in sending to a peer DOTS agent that does not respond. 1855 d. Acceptable signal loss ratio: Maximum retransmissions, 1856 retransmission timeout value, and other message transmission 1857 parameters for Confirmable messages over the DOTS signal channel. 1859 When the DOTS signal channel is established over a reliable transport 1860 (e.g., TCP), there is no need for the reliability mechanisms provided 1861 by CoAP over UDP since the underlying TCP connection provides 1862 retransmissions and deduplication [RFC8323]. As a reminder, CoAP 1863 over reliable transports does not support Confirmable or Non- 1864 confirmable message types. As such, the transmission-related 1865 parameters (missing-hb-allowed and acceptable signal loss ratio) are 1866 negotiated only for DOTS over unreliable transports. 1868 The same or distinct configuration sets may be used during times when 1869 a mitigation is active ('mitigating-config') and when no mitigation 1870 is active ('idle-config'). This is particularly useful for DOTS 1871 servers that might want to reduce heartbeat frequency or cease 1872 heartbeat exchanges when an active DOTS client has not requested 1873 mitigation. If distinct configurations are used, DOTS agents MUST 1874 follow the appropriate configuration set as a function of the 1875 mitigation activity (e.g., if no mitigation request is active (also 1876 referred to as 'idle' time), 'idle-config'-related values must be 1877 followed). Additionally, DOTS agents MUST automatically switch to 1878 the other configuration upon a change in the mitigation activity 1879 (e.g., if an attack mitigation is launched after an 'idle' time, the 1880 DOTS agent switches from 'idle-config' to 'mitigating-config'-related 1881 values). 1883 CoAP Requests and responses are indicated for reliable delivery by 1884 marking them as Confirmable messages. DOTS signal channel session 1885 configuration requests and responses are marked as Confirmable 1886 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1887 message is retransmitted using a default timeout and exponential 1888 back-off between retransmissions, until the DOTS server sends an 1889 Acknowledgement message (ACK) with the same Message ID conveyed from 1890 the DOTS client. 1892 Message transmission parameters are defined in Section 4.8 of 1893 [RFC7252]. The DOTS server can either piggyback the response in the 1894 acknowledgement message or, if the DOTS server cannot respond 1895 immediately to a request carried in a Confirmable message, it simply 1896 responds with an Empty Acknowledgement message so that the DOTS 1897 client can stop retransmitting the request. Empty Acknowledgement 1898 messages are explained in Section 2.2 of [RFC7252]. When the 1899 response is ready, the server sends it in a new Confirmable message 1900 which in turn needs to be acknowledged by the DOTS client (see 1901 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1902 exchanged between DOTS agents during 'idle' time, except heartbeat 1903 messages, are marked as Confirmable messages. 1905 Implementation Note: A DOTS client that receives a response in a 1906 Confirmable message may want to clean up the message state right 1907 after sending the ACK. If that ACK is lost and the DOTS server 1908 retransmits the Confirmable message, the DOTS client may no longer 1909 have any state that would help it correlate this response: from 1910 the DOTS client's standpoint, the retransmission message is 1911 unexpected. The DOTS client will send a Reset message so it does 1912 not receive any more retransmissions. This behavior is normal and 1913 not an indication of an error (see Section 5.3.2 of [RFC7252] for 1914 more details). 1916 4.5.1. Discover Configuration Parameters 1918 A GET request is used to obtain acceptable (e.g., minimum and maximum 1919 values) and current configuration parameters on the DOTS server for 1920 DOTS signal channel session configuration. This procedure occurs 1921 between a DOTS client and its immediate peer DOTS server. As such, 1922 this GET request MUST NOT be relayed by a DOTS gateway. 1924 Figure 18 shows how to obtain configuration parameters that the DOTS 1925 server will find acceptable. 1927 Header: GET (Code=0.01) 1928 Uri-Path: ".well-known" 1929 Uri-Path: "dots" 1930 Uri-Path: "config" 1932 Figure 18: GET to Retrieve Configuration 1934 The DOTS server in the 2.05 (Content) response conveys the current, 1935 minimum, and maximum attribute values acceptable by the DOTS server 1936 (Figure 19). 1938 { 1939 "ietf-dots-signal-channel:signal-config": { 1940 "mitigating-config": { 1941 "heartbeat-interval": { 1942 "max-value": number, 1943 "min-value": number, 1944 "current-value": number 1945 }, 1946 "missing-hb-allowed": { 1947 "max-value": number, 1948 "min-value": number, 1949 "current-value": number 1950 }, 1951 "probing-rate": { 1952 "max-value": number, 1953 "min-value": number, 1954 "current-value": number 1955 }, 1956 "max-retransmit": { 1957 "max-value": number, 1958 "min-value": number, 1959 "current-value": number 1960 }, 1961 "ack-timeout": { 1962 "max-value-decimal": "string", 1963 "min-value-decimal": "string", 1964 "current-value-decimal": "string" 1965 }, 1966 "ack-random-factor": { 1967 "max-value-decimal": "string", 1968 "min-value-decimal": "string", 1969 "current-value-decimal": "string" 1970 } 1971 }, 1972 "idle-config": { 1973 "heartbeat-interval": { 1974 "max-value": number, 1975 "min-value": number, 1976 "current-value": number 1977 }, 1978 "missing-hb-allowed": { 1979 "max-value": number, 1980 "min-value": number, 1981 "current-value": number 1982 }, 1983 "probing-rate": { 1984 "max-value": number, 1985 "min-value": number, 1986 "current-value": number 1987 }, 1988 "max-retransmit": { 1989 "max-value": number, 1990 "min-value": number, 1991 "current-value": number 1992 }, 1993 "ack-timeout": { 1994 "max-value-decimal": "string", 1995 "min-value-decimal": "string", 1996 "current-value-decimal": "string" 1997 }, 1998 "ack-random-factor": { 1999 "max-value-decimal": "string", 2000 "min-value-decimal": "string", 2001 "current-value-decimal": "string" 2002 } 2003 } 2004 } 2005 } 2007 Figure 19: GET Configuration Response Body Schema 2009 The parameters in Figure 19 are described below: 2011 mitigating-config: Set of configuration parameters to use when a 2012 mitigation is active. The following parameters may be included: 2014 heartbeat-interval: Time interval in seconds between two 2015 consecutive heartbeat messages. 2017 '0' is used to disable the heartbeat mechanism. 2019 This is an optional attribute. 2021 missing-hb-allowed: Maximum number of consecutive heartbeat 2022 messages for which the DOTS agent did not receive a response 2023 before concluding that the session is disconnected. 2025 This is an optional attribute. 2027 probing-rate: The average data rate that must not be exceeded by 2028 a DOTS agent in sending to a peer DOTS agent that does not 2029 respond (referred to as PROBING_RATE parameter in CoAP). 2031 This is an optional attribute. 2033 max-retransmit: Maximum number of retransmissions for a message 2034 (referred to as MAX_RETRANSMIT parameter in CoAP). 2036 This is an optional attribute. 2038 ack-timeout: Timeout value in seconds used to calculate the 2039 initial retransmission timeout value (referred to as 2040 ACK_TIMEOUT parameter in CoAP). 2042 This is an optional attribute. 2044 ack-random-factor: Random factor used to influence the timing of 2045 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 2046 CoAP). 2048 This is an optional attribute. 2050 idle-config: Set of configuration parameters to use when no 2051 mitigation is active. This attribute has the same structure as 2052 'mitigating-config'. 2054 Figure 20 shows an example of acceptable and current configuration 2055 parameters on a DOTS server for DOTS signal channel session 2056 configuration. The same acceptable configuration is used during 2057 mitigation and idle times. 2059 { 2060 "ietf-dots-signal-channel:signal-config": { 2061 "mitigating-config": { 2062 "heartbeat-interval": { 2063 "max-value": 240, 2064 "min-value": 15, 2065 "current-value": 30 2066 }, 2067 "missing-hb-allowed": { 2068 "max-value": 20, 2069 "min-value": 3, 2070 "current-value": 15 2071 }, 2072 "probing-rate": { 2073 "max-value": 20, 2074 "min-value": 5, 2075 "current-value": 15 2076 }, 2077 "max-retransmit": { 2078 "max-value": 15, 2079 "min-value": 2, 2080 "current-value": 3 2081 }, 2082 "ack-timeout": { 2083 "max-value-decimal": "30.00", 2084 "min-value-decimal": "1.00", 2085 "current-value-decimal": "2.00" 2087 }, 2088 "ack-random-factor": { 2089 "max-value-decimal": "4.00", 2090 "min-value-decimal": "1.10", 2091 "current-value-decimal": "1.50" 2092 } 2093 }, 2094 "idle-config": { 2095 "heartbeat-interval": { 2096 "max-value": 240, 2097 "min-value": 15, 2098 "current-value": 30 2099 }, 2100 "missing-hb-allowed": { 2101 "max-value": 20, 2102 "min-value": 3, 2103 "current-value": 15 2104 }, 2105 "probing-rate": { 2106 "max-value": 20, 2107 "min-value": 5, 2108 "current-value": 15 2109 }, 2110 "max-retransmit": { 2111 "max-value": 15, 2112 "min-value": 2, 2113 "current-value": 3 2114 }, 2115 "ack-timeout": { 2116 "max-value-decimal": "30.00", 2117 "min-value-decimal": "1.00", 2118 "current-value-decimal": "2.00" 2119 }, 2120 "ack-random-factor": { 2121 "max-value-decimal": "4.00", 2122 "min-value-decimal": "1.10", 2123 "current-value-decimal": "1.50" 2124 } 2125 } 2126 } 2127 } 2129 Figure 20: Example of a Configuration Response Body 2131 4.5.2. Convey DOTS Signal Channel Session Configuration 2133 A PUT request (Figures 21 and 22) is used to convey the configuration 2134 parameters for the signal channel (e.g., heartbeat interval, maximum 2135 retransmissions). Message transmission parameters for CoAP are 2136 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 2137 transmission parameter values are ack-timeout (2 seconds), max- 2138 retransmit (3), and ack-random-factor (1.5). In addition to those 2139 parameters, the RECOMMENDED specific DOTS transmission parameter 2140 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 2141 (15). 2143 Note: heartbeat-interval should be tweaked to also assist DOTS 2144 messages for NAT traversal (SIG-011 of [RFC8612]). According to 2145 [RFC8085], heartbeat messages must not be sent more frequently 2146 than once every 15 seconds and should use longer intervals when 2147 possible. Furthermore, [RFC4787] recommends NATs to use a state 2148 timeout of 2 minutes or longer, but experience shows that sending 2149 packets every 15 to 30 seconds is necessary to prevent the 2150 majority of middleboxes from losing state for UDP flows. From 2151 that standpoint, the RECOMMENDED minimum heartbeat-interval is 15 2152 seconds and the RECOMMENDED maximum heartbeat-interval is 240 2153 seconds. The recommended value of 30 seconds is selected to 2154 anticipate the expiry of NAT state. 2156 A heartbeat-interval of 30 seconds may be considered as too chatty 2157 in some deployments. For such deployments, DOTS agents may 2158 negotiate longer heartbeat-interval values to prevent any network 2159 overload with too frequent heartbeats. 2161 Different heartbeat intervals can be defined for 'mitigating- 2162 config' and 'idle-config' to reduce being too chatty during idle 2163 times. If there is an on-path translator between the DOTS client 2164 (standalone or part of a DOTS gateway) and the DOTS server, the 2165 'mitigating-config' heartbeat-interval has to be smaller than the 2166 translator session timeout. It is recommended that the 'idle- 2167 config' heartbeat-interval is also smaller than the translator 2168 session timeout to prevent translator traversal issues, or 2169 disabled entirely. Means to discover the lifetime assigned by a 2170 translator are out of scope. 2172 Given that the size of the heartbeat request can not exceed 2173 (heartbeat-interval * probing-rate) bytes, probing-rate should be 2174 set appropriately to avoid slowing down heartbeat exchanges. For 2175 example, probing-rate may be set to 2 * ("size of encrypted DOTS 2176 heartbeat request"/heartbeat-interval) or (("size of encrypted 2177 DOTS heartbeat request" + "average size of an encrypted mitigation 2178 request")/heartbeat-interval). Absent any explicit configuration 2179 or inability to dynamically adjust probing-rate values 2180 (Section 4.8.1 of [RFC7252]), DOTS agents use 5 bytes/second as a 2181 default probing-rate value. 2183 If the DOTS agent wishes to change the default values of message 2184 transmission parameters, it SHOULD follow the guidance given in 2185 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2186 values for message transmission parameters and default values for 2187 non-negotiated message transmission parameters. 2189 The signal channel session configuration is applicable to a single 2190 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2191 Path MUST NOT be used. 2193 Header: PUT (Code=0.03) 2194 Uri-Path: ".well-known" 2195 Uri-Path: "dots" 2196 Uri-Path: "config" 2197 Uri-Path: "sid=123" 2198 Content-Format: "application/dots+cbor" 2200 { 2201 ... 2202 } 2204 Figure 21: PUT to Convey the DOTS Signal Channel Session 2205 Configuration Data 2207 The additional Uri-Path parameter to those defined in Table 1 is as 2208 follows: 2210 sid: Session Identifier is an identifier for the DOTS signal channel 2211 session configuration data represented as an integer. This 2212 identifier MUST be generated by DOTS clients. 'sid' values MUST 2213 increase monotonically (when a new PUT is generated by a DOTS 2214 client to convey the configuration parameters for the signal 2215 channel). 2217 This is a mandatory attribute. 2219 { 2220 "ietf-dots-signal-channel:signal-config": { 2221 "mitigating-config": { 2222 "heartbeat-interval": { 2223 "current-value": number 2224 }, 2225 "missing-hb-allowed": { 2226 "current-value": number 2227 }, 2228 "probing-rate": { 2229 "current-value": number 2230 }, 2231 "max-retransmit": { 2232 "current-value": number 2233 }, 2234 "ack-timeout": { 2235 "current-value-decimal": "string" 2236 }, 2237 "ack-random-factor": { 2238 "current-value-decimal": "string" 2239 } 2240 }, 2241 "idle-config": { 2242 "heartbeat-interval": { 2243 "current-value": number 2244 }, 2245 "missing-hb-allowed": { 2246 "current-value": number 2247 }, 2248 "probing-rate": { 2249 "current-value": number 2250 }, 2251 "max-retransmit": { 2252 "current-value": number 2253 }, 2254 "ack-timeout": { 2255 "current-value-decimal": "string" 2256 }, 2257 "ack-random-factor": { 2258 "current-value-decimal": "string" 2259 } 2260 } 2261 } 2262 } 2264 Figure 22: PUT to Convey the DOTS Signal Channel Session 2265 Configuration Data (Message Body Schema) 2267 The meaning of the parameters in the CBOR body (Figure 22) is defined 2268 in Section 4.5.1. 2270 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2271 allowed', 'probing-rate', 'max-retransmit', 'ack-timeout', and 'ack- 2272 random-factor' MUST be present in the PUT request. Note that 2273 'heartbeat-interval', 'missing-hb-allowed', 'probing-rate', 'max- 2274 retransmit', 'ack-timeout', and 'ack-random-factor', if present, do 2275 not need to be provided for both 'mitigating-config', and 'idle- 2276 config' in a PUT request. 2278 The PUT request with a higher numeric 'sid' value overrides the DOTS 2279 signal channel session configuration data installed by a PUT request 2280 with a lower numeric 'sid' value. To avoid maintaining a long list 2281 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2282 automatically deleted and no longer available at the DOTS server. 2284 Figure 23 shows a PUT request example to convey the configuration 2285 parameters for the DOTS signal channel. In this example, the 2286 heartbeat mechanism is disabled when no mitigation is active, while 2287 the heartbeat interval is set to '30' when a mitigation is active. 2289 Header: PUT (Code=0.03) 2290 Uri-Path: ".well-known" 2291 Uri-Path: "dots" 2292 Uri-Path: "config" 2293 Uri-Path: "sid=123" 2294 Content-Format: "application/dots+cbor" 2296 { 2297 "ietf-dots-signal-channel:signal-config": { 2298 "mitigating-config": { 2299 "heartbeat-interval": { 2300 "current-value": 30 2301 }, 2302 "missing-hb-allowed": { 2303 "current-value": 15 2304 }, 2305 "probing-rate": { 2306 "current-value": 15 2307 }, 2308 "max-retransmit": { 2309 "current-value": 3 2310 }, 2311 "ack-timeout": { 2312 "current-value-decimal": "2.00" 2313 }, 2314 "ack-random-factor": { 2315 "current-value-decimal": "1.50" 2316 } 2317 }, 2318 "idle-config": { 2319 "heartbeat-interval": { 2320 "current-value": 0 2321 }, 2322 "max-retransmit": { 2323 "current-value": 3 2324 }, 2325 "ack-timeout": { 2326 "current-value-decimal": "2.00" 2327 }, 2328 "ack-random-factor": { 2329 "current-value-decimal": "1.50" 2330 } 2331 } 2332 } 2333 } 2335 Figure 23: PUT to Convey the Configuration Parameters 2337 The DOTS server indicates the result of processing the PUT request 2338 using CoAP response codes: 2340 o If the request is missing a mandatory attribute, does not include 2341 a 'sid' Uri-Path, or contains one or more invalid or unknown 2342 parameters, 4.00 (Bad Request) MUST be returned in the response. 2344 o If the DOTS server does not find the 'sid' parameter value 2345 conveyed in the PUT request in its configuration data and if the 2346 DOTS server has accepted the configuration parameters, then a 2347 response code 2.01 (Created) MUST be returned in the response. 2349 o If the DOTS server finds the 'sid' parameter value conveyed in the 2350 PUT request in its configuration data and if the DOTS server has 2351 accepted the updated configuration parameters, 2.04 (Changed) MUST 2352 be returned in the response. 2354 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 2355 'probing-rate', 'max-retransmit', 'target-protocol', 'ack- 2356 timeout', and 'ack-random-factor' attribute values are not 2357 acceptable to the DOTS server, 4.22 (Unprocessable Entity) MUST be 2358 returned in the response. Upon receipt of this error code, the 2359 DOTS client SHOULD retrieve the maximum and minimum attribute 2360 values acceptable to the DOTS server (Section 4.5.1). 2362 The DOTS client may re-try and send the PUT request with updated 2363 attribute values acceptable to the DOTS server. 2365 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2366 to retrieve the negotiated configuration. The response does not need 2367 to include 'sid' in its message body. 2369 4.5.3. Configuration Freshness and Notifications 2371 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2372 DOTS server to associate a validity time with a configuration it 2373 sends. This feature allows the update of the configuration data if a 2374 change occurs at the DOTS server side. For example, the new 2375 configuration may instruct a DOTS client to cease heartbeats or 2376 reduce heartbeat frequency. 2378 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2380 Returning a Max-Age Option set to 2**32-1 is equivalent to 2381 associating an infinite lifetime with the configuration. 2383 If a non-zero value of Max-Age Option is received by a DOTS client, 2384 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2385 the current and acceptable configuration before the expiry of the 2386 value enclosed in the Max-Age option. This request is considered by 2387 the client and the server as a means to refresh the configuration 2388 parameters for the signal channel. When a DDoS attack is active, 2389 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2390 MUST NOT terminate the (D)TLS session after the expiry of the value 2391 returned in Max-Age Option. 2393 If Max-Age Option is not returned in a response, the DOTS client 2394 initiates GET requests to refresh the configuration parameters each 2395 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2396 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2397 responses. Considerations related to which value to use and how such 2398 value is set, are implementation- and deployment-specific. 2400 If an Observe Option set to 0 is included in the configuration 2401 request, the DOTS server sends notifications of any configuration 2402 change (Section 4.2 of [RFC7641]). 2404 If a DOTS server detects that a misbehaving DOTS client does not 2405 contact the DOTS server after the expiry of Max-Age and retrieve the 2406 signal channel configuration data, it MAY terminate the (D)TLS 2407 session. A (D)TLS session is terminated by the receipt of an 2408 authenticated message that closes the connection (e.g., a fatal alert 2409 (Section 6 of [RFC8446])). 2411 4.5.4. Delete DOTS Signal Channel Session Configuration 2413 A DELETE request is used to delete the installed DOTS signal channel 2414 session configuration data (Figure 24). 2416 Header: DELETE (Code=0.04) 2417 Uri-Path: ".well-known" 2418 Uri-Path: "dots" 2419 Uri-Path: "config" 2420 Uri-Path: "sid=123" 2422 Figure 24: Delete Configuration 2424 The DOTS server resets the DOTS signal channel session configuration 2425 back to the default values and acknowledges a DOTS client's request 2426 to remove the DOTS signal channel session configuration using 2.02 2427 (Deleted) response code. 2429 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2430 to set the configuration parameters to default values. Such a 2431 request does not include any 'sid'. 2433 4.6. Redirected Signaling 2435 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2436 [I-D.ietf-dots-architecture]. 2438 If a DOTS server wants to redirect a DOTS client to an alternative 2439 DOTS server for a signal session, then the response code 5.03 2440 (Service Unavailable) will be returned in the response to the DOTS 2441 client. 2443 The DOTS server can return the error response code 5.03 in response 2444 to a request from the DOTS client or convey the error response code 2445 5.03 in a unidirectional notification response from the DOTS server. 2447 The DOTS server in the error response conveys the alternate DOTS 2448 server's FQDN, and the alternate DOTS server's IP address(es) values 2449 in the CBOR body (Figure 25). 2451 { 2452 "ietf-dots-signal-channel:redirected-signal": { 2453 "alt-server": "string", 2454 "alt-server-record": [ 2455 "string" 2456 ] 2457 } 2459 Figure 25: Redirected Server Error Response Body Schema 2461 The parameters are described below: 2463 alt-server: FQDN of an alternate DOTS server. 2465 This is a mandatory attribute. 2467 alt-server-record: A list of IP addresses of an alternate DOTS 2468 server. 2470 This is an optional attribute. 2472 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2473 server in a Max-Age Option. That is, the time interval that the 2474 alternate DOTS server may be cached for use by a DOTS client. A Max- 2475 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2476 This value means that the alternate DOTS server is to be used until 2477 the alternate DOTS server redirects the traffic with another 5.03 2478 response which encloses an alternate server. 2480 A Max-Age Option set to '0' may be returned for redirecting 2481 mitigation requests. Such value means that the redirection applies 2482 only for the mitigation request in progress. Returning short TTL in 2483 a Max-Age Option may adversely impact DOTS clients on slow links. 2484 Returning short values should be avoided under such conditions. 2486 If the alternate DOTS server TTL has expired, the DOTS client MUST 2487 use the DOTS server(s), that was provisioned using means discussed in 2488 Section 4.1. This fall back mechanism is triggered immediately upon 2489 expiry of the TTL, except when a DDoS attack is active. 2491 Requests issued by misbehaving DOTS clients which do not honor the 2492 TTL conveyed in the Max-Age Option or react to explicit re-direct 2493 messages can be rejected by DOTS servers. 2495 Figure 26 shows a 5.03 response example to convey the DOTS alternate 2496 server 'alt-server.example' together with its IP addresses 2497 2001:db8:6401::1 and 2001:db8:6401::2. 2499 { 2500 "ietf-dots-signal-channel:redirected-signal": { 2501 "alt-server": "alt-server.example", 2502 "alt-server-record": [ 2503 "2001:db8:6401::1", 2504 "2001:db8:6401::2" 2505 ] 2506 } 2508 Figure 26: Example of Redirected Server Error Response Body 2510 When the DOTS client receives 5.03 response with an alternate server 2511 included, it considers the current request as failed, but SHOULD try 2512 re-sending the request to the alternate DOTS server. During a DDoS 2513 attack, the DNS server may be the target of another DDoS attack, 2514 alternate DOTS server's IP addresses conveyed in the 5.03 response 2515 help the DOTS client skip DNS lookup of the alternate DOTS server, at 2516 the cost of trusting the first DOTS server to provide accurate 2517 information. The DOTS client can then try to establish a UDP or a 2518 TCP session with the alternate DOTS server. The DOTS client MAY 2519 implement a method to construct IPv4-embedded IPv6 addresses 2520 [RFC6052]; this is required to handle the scenario where an IPv6-only 2521 DOTS client communicates with an IPv4-only alternate DOTS server. 2523 If the DOTS client has been redirected to a DOTS server to which it 2524 has already communicated with within the last five (5) minutes, it 2525 MUST ignore the redirection and try to contact other DOTS servers 2526 listed in the local configuration or discovered using dynamic means 2527 such as DHCP or SRV procedures [I-D.ietf-dots-server-discovery]. It 2528 is RECOMMENDED that DOTS clients support means to alert 2529 administrators about redirect loops. 2531 4.7. Heartbeat Mechanism 2533 To provide an indication of signal health and distinguish an 'idle' 2534 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2535 agent sends a heartbeat over the signal channel to maintain its half 2536 of the channel (also, aligned with the "consents" recommendation in 2537 Section 6 of [RFC8085]). The DOTS agent similarly expects a 2538 heartbeat from its peer DOTS agent, and may consider a session 2539 terminated in the prolonged absence of a peer agent heartbeat. 2540 Concretely, while the communication between the DOTS agents is 2541 otherwise quiescent, the DOTS client will probe the DOTS server to 2542 ensure it has maintained cryptographic state and vice versa. Such 2543 probes can also keep firewalls and/or stateful translators bindings 2544 alive. This probing reduces the frequency of establishing a new 2545 handshake when a DOTS signal needs to be conveyed to the DOTS server. 2547 Implementation Note: Given that CoAP roles can be multiplexed over 2548 the same session as discussed in [RFC7252] and already supported 2549 by CoAP implementations, both the DOTS client and server can send 2550 DOTS heartbeat requests. 2552 The DOTS Heartbeat mechanism uses non-confirmable PUT requests 2553 (Figure 27) with an expected 2.04 (Changed) Response Code 2554 (Figure 28). This procedure occurs between a DOTS agent and its 2555 immediate peer DOTS agent. As such, this PUT request MUST NOT be 2556 relayed by a DOTS gateway. The PUT request used for DOTS heartbeat 2557 MUST NOT have a 'cuid', 'cdid,' or 'mid' Uri-Path. 2559 Header: PUT (Code=0.03) 2560 Uri-Path: ".well-known" 2561 Uri-Path: "dots" 2562 Uri-Path: "hb" 2563 Content-Format: "application/dots+cbor" 2565 { 2566 "ietf-dots-signal-channel:heartbeat": { 2567 "peer-hb-status": true 2568 } 2569 } 2571 Figure 27: PUT to Check Peer DOTS Agent is Responding 2573 The mandatory 'peer-hb-status' attribute is set to 'true' (or 2574 'false') to indicates that a DOTS agent is (or not) receiving 2575 heartbeat messages from its peer in the last (2 * heartbeat-interval) 2576 period. Such information can be used by a peer DOTS agent to detect 2577 or confirm connectivity issues and react accordingly. For example, 2578 if a DOTS client receives 2.04 response for its heartbeat messages 2579 but no server-initiated heartbeat messages, the DOTS client sets 2580 'peer-hb-status' to 'false'. The DOTS server will need then to try 2581 another strategy for sending the heartbeats (e.g., adjust the 2582 heartbeat interval or send a server-initiated heartbeat immediately 2583 after receiving a client-initiated heartbeat message). 2585 Header: (Code=2.04) 2587 Figure 28: Response to a DOTS Heartbeat Request 2589 DOTS servers MAY trigger their heartbeat requests immediately after 2590 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2591 is the responsibility of DOTS clients to ensure that on-path 2592 translators/firewalls are maintaining a binding so that the same 2593 external IP address and/or port number is retained for the DOTS 2594 signal channel session. 2596 Under normal traffic conditions (i.e., no attack is ongoing), if a 2597 DOTS agent does not receive any response from the peer DOTS agent for 2598 'missing-hb-allowed' number of consecutive heartbeat messages, it 2599 concludes that the DOTS signal channel session is disconnected. The 2600 DOTS client MUST then try to re-establish the DOTS signal channel 2601 session, preferably by resuming the (D)TLS session. 2603 Note: If a new DOTS signal channel session cannot be established, 2604 the DOTS client SHOULD NOT retry to establish the DOTS signal 2605 channel session more frequently than every 300 seconds (5 minutes) 2606 and MUST NOT retry more frequently than every 60 seconds (1 2607 minute). It is recommended that DOTS clients support means to 2608 alert administrators about the failure to establish a (D)TLS 2609 session. 2611 In case of a massive DDoS attack that saturates the incoming link(s) 2612 to the DOTS client, all traffic from the DOTS server to the DOTS 2613 client will likely be dropped, although the DOTS server receives 2614 heartbeat requests in addition to DOTS messages sent by the DOTS 2615 client. In this scenario, DOTS clients MUST behave differently to 2616 handle message transmission and DOTS signal channel session 2617 liveliness during link saturation: 2619 The DOTS client MUST NOT consider the DOTS signal channel session 2620 terminated even after a maximum 'missing-hb-allowed' threshold is 2621 reached. The DOTS client SHOULD keep on using the current DOTS 2622 signal channel session to send heartbeat requests over it, so that 2623 the DOTS server knows the DOTS client has not disconnected the 2624 DOTS signal channel session. 2626 After the maximum 'missing-hb-allowed' threshold is reached, the 2627 DOTS client SHOULD try to establish a new DOTS signal channel 2628 session. The DOTS client SHOULD send mitigation requests over the 2629 current DOTS signal channel session and, in parallel, send the 2630 mitigation requests over the new DOTS signal channel session. 2631 This may be handled, for example, by resumption of the (D)TLS 2632 session or using 0-RTT mode in DTLS 1.3 to piggyback the 2633 mitigation request in the ClientHello message. 2635 As soon as the link is no longer saturated, if traffic from the 2636 DOTS server reaches the DOTS client over the current DOTS signal 2637 channel session, the DOTS client can stop the new DOTS signal 2638 channel session attempt or if a new DOTS signal channel session is 2639 successful then disconnect the current DOTS signal channel 2640 session. 2642 If the DOTS server receives traffic from the peer DOTS client (e.g., 2643 peer DOTS client initiated heartbeats) but maximum 'missing-hb- 2644 allowed' threshold is reached, the DOTS server MUST NOT consider the 2645 DOTS signal channel session disconnected. The DOTS server MUST keep 2646 on using the current DOTS signal channel session so that the DOTS 2647 client can send mitigation requests over the current DOTS signal 2648 channel session. In this case, the DOTS server can identify the DOTS 2649 client is under attack and the inbound link to the DOTS client 2650 (domain) is saturated. Furthermore, if the DOTS server does not 2651 receive a mitigation request from the DOTS client, it implies the 2652 DOTS client has not detected the attack or, if an attack mitigation 2653 is in progress, it implies the applied DDoS mitigation actions are 2654 not yet effective to handle the DDoS attack volume. 2656 If the DOTS server does not receive any traffic from the peer DOTS 2657 client during the time span required to exhaust the maximum 'missing- 2658 hb-allowed' threshold, the DOTS server concludes the session is 2659 disconnected. The DOTS server can then trigger pre-configured 2660 mitigation requests for this DOTS client (if any). 2662 In DOTS over TCP, the sender of a DOTS heartbeat message has to allow 2663 up to 'heartbeat-interval' seconds when waiting for a heartbeat 2664 reply. When a failure is detected by a DOTS client, it proceeds with 2665 the session recovery following the same approach as the one used for 2666 unreliable transports. 2668 5. DOTS Signal Channel YANG Modules 2670 This document defines a YANG [RFC7950] module for DOTS mitigation 2671 scope, DOTS signal channel session configuration data, DOTS 2672 redirection signaling, and DOTS heartbeats. 2674 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2675 interaction with the DOTS server as seen by the DOTS client. A DOTS 2676 server is allowed to update the non-configurable 'ro' entities in the 2677 responses. This YANG module is not intended to be used via NETCONF/ 2678 RESTCONF for DOTS server management purposes; such module is out of 2679 the scope of this document. It serves only to provide a data model 2680 and encoding, but not a management data model. 2682 A companion YANG module is defined to include a collection of types 2683 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2685 5.1. Tree Structure 2687 This document defines the YANG module "ietf-dots-signal-channel" 2688 (Section 5.3), which has the following tree structure. A DOTS signal 2689 message can be a mitigation, a configuration, a redirect, or a 2690 heartbeat message. 2692 module: ietf-dots-signal-channel 2693 +--rw dots-signal 2694 +--rw (message-type)? 2695 +--:(mitigation-scope) 2696 | +--rw scope* [cuid mid] 2697 | +--rw cdid? string 2698 | +--rw cuid string 2699 | +--rw mid uint32 2700 | +--rw target-prefix* inet:ip-prefix 2701 | +--rw target-port-range* [lower-port] 2702 | | +--rw lower-port inet:port-number 2703 | | +--rw upper-port? inet:port-number 2704 | +--rw target-protocol* uint8 2705 | +--rw target-fqdn* inet:domain-name 2706 | +--rw target-uri* inet:uri 2707 | +--rw alias-name* string 2708 | +--rw lifetime? int32 2709 | +--rw trigger-mitigation? boolean 2710 | +--ro mitigation-start? uint64 2711 | +--ro status? iana-signal:status 2712 | +--ro conflict-information 2713 | | +--ro conflict-status? iana-signal:conflict-status 2714 | | +--ro conflict-cause? iana-signal:conflict-cause 2715 | | +--ro retry-timer? uint32 2716 | | +--ro conflict-scope 2717 | | +--ro target-prefix* inet:ip-prefix 2718 | | +--ro target-port-range* [lower-port] 2719 | | | +--ro lower-port inet:port-number 2720 | | | +--ro upper-port? inet:port-number 2721 | | +--ro target-protocol* uint8 2722 | | +--ro target-fqdn* inet:domain-name 2723 | | +--ro target-uri* inet:uri 2724 | | +--ro alias-name* string 2725 | | +--ro acl-list* [acl-name] 2726 | | | +--ro acl-name 2727 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2728 | | | | acl/name 2729 | | | +--ro acl-type? 2730 | | | -> /ietf-data:dots-data/dots-client/acls/ 2731 | | | acl/type 2732 | | +--ro mid? -> ../../../mid 2733 | +--ro bytes-dropped? yang:zero-based-counter64 2734 | +--ro bps-dropped? yang:gauge64 2735 | +--ro pkts-dropped? yang:zero-based-counter64 2736 | +--ro pps-dropped? yang:gauge64 2737 | +--rw attack-status? iana-signal:attack-status 2738 +--:(signal-config) 2739 | +--rw sid uint32 2740 | +--rw mitigating-config 2741 | | +--rw heartbeat-interval 2742 | | | +--ro max-value? uint16 2743 | | | +--ro min-value? uint16 2744 | | | +--rw current-value? uint16 2745 | | +--rw missing-hb-allowed 2746 | | | +--ro max-value? uint16 2747 | | | +--ro min-value? uint16 2748 | | | +--rw current-value? uint16 2749 | | +--rw probing-rate 2750 | | | +--ro max-value? uint16 2751 | | | +--ro min-value? uint16 2752 | | | +--rw current-value? uint16 2753 | | +--rw max-retransmit 2754 | | | +--ro max-value? uint16 2755 | | | +--ro min-value? uint16 2756 | | | +--rw current-value? uint16 2757 | | +--rw ack-timeout 2758 | | | +--ro max-value-decimal? decimal64 2759 | | | +--ro min-value-decimal? decimal64 2760 | | | +--rw current-value-decimal? decimal64 2761 | | +--rw ack-random-factor 2762 | | +--ro max-value-decimal? decimal64 2763 | | +--ro min-value-decimal? decimal64 2764 | | +--rw current-value-decimal? decimal64 2765 | +--rw idle-config 2766 | +--rw heartbeat-interval 2767 | | +--ro max-value? uint16 2768 | | +--ro min-value? uint16 2769 | | +--rw current-value? uint16 2770 | +--rw missing-hb-allowed 2771 | | +--ro max-value? uint16 2772 | | +--ro min-value? uint16 2773 | | +--rw current-value? uint16 2774 | +--rw probing-rate 2775 | | +--ro max-value? uint16 2776 | | +--ro min-value? uint16 2777 | | +--rw current-value? uint16 2778 | +--rw max-retransmit 2779 | | +--ro max-value? uint16 2780 | | +--ro min-value? uint16 2781 | | +--rw current-value? uint16 2782 | +--rw ack-timeout 2783 | | +--ro max-value-decimal? decimal64 2784 | | +--ro min-value-decimal? decimal64 2785 | | +--rw current-value-decimal? decimal64 2786 | +--rw ack-random-factor 2787 | +--ro max-value-decimal? decimal64 2788 | +--ro min-value-decimal? decimal64 2789 | +--rw current-value-decimal? decimal64 2790 +--:(redirected-signal) 2791 | +--ro alt-server string 2792 | +--ro alt-server-record* inet:ip-address 2793 +--:(heartbeat) 2794 +--rw peer-hb-status boolean 2796 5.2. IANA DOTS Signal Channel YANG Module 2798 file "iana-dots-signal-channel@2019-01-17.yang" 2799 module iana-dots-signal-channel { 2800 yang-version 1.1; 2801 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2802 prefix iana-signal; 2804 organization 2805 "IANA"; 2806 contact 2807 "Internet Assigned Numbers Authority 2809 Postal: ICANN 2810 12025 Waterfront Drive, Suite 300 2811 Los Angeles, CA 90094-2536 2812 United States of America 2813 Tel: +1 310 301 5800 2814 "; 2815 description 2816 "This module contains a collection of YANG data types defined 2817 by IANA and used for DOTS signal channel protocol. 2819 Copyright (c) 2019 IETF Trust and the persons identified as 2820 authors of the code. All rights reserved. 2822 Redistribution and use in source and binary forms, with or 2823 without modification, is permitted pursuant to, and subject 2824 to the license terms contained in, the Simplified BSD License 2825 set forth in Section 4.c of the IETF Trust's Legal Provisions 2826 Relating to IETF Documents 2827 (http://trustee.ietf.org/license-info). 2829 This version of this YANG module is part of RFC XXXX; see 2830 the RFC itself for full legal notices."; 2832 revision 2019-01-17 { 2833 description 2834 "Initial revision."; 2835 reference 2836 "RFC XXXX: Distributed Denial-of-Service Open Threat 2837 Signaling (DOTS) Signal Channel Specification"; 2838 } 2840 typedef status { 2841 type enumeration { 2842 enum attack-mitigation-in-progress { 2843 value 1; 2844 description 2845 "Attack mitigation setup is in progress (e.g., changing 2846 the network path to re-route the inbound traffic 2847 to DOTS mitigator)."; 2848 } 2849 enum attack-successfully-mitigated { 2850 value 2; 2851 description 2852 "Attack is being successfully mitigated (e.g., traffic 2853 is redirected to a DDoS mitigator and attack 2854 traffic is dropped or blackholed)."; 2855 } 2856 enum attack-stopped { 2857 value 3; 2858 description 2859 "Attack has stopped and the DOTS client can 2860 withdraw the mitigation request."; 2861 } 2862 enum attack-exceeded-capability { 2863 value 4; 2864 description 2865 "Attack has exceeded the mitigation provider 2866 capability."; 2867 } 2868 enum dots-client-withdrawn-mitigation { 2869 value 5; 2870 description 2871 "DOTS client has withdrawn the mitigation 2872 request and the mitigation is active but 2873 terminating."; 2874 } 2875 enum attack-mitigation-terminated { 2876 value 6; 2877 description 2878 "Attack mitigation is now terminated."; 2879 } 2880 enum attack-mitigation-withdrawn { 2881 value 7; 2882 description 2883 "Attack mitigation is withdrawn."; 2884 } 2885 enum attack-mitigation-signal-loss { 2886 value 8; 2887 description 2888 "Attack mitigation will be triggered 2889 for the mitigation request only when 2890 the DOTS signal channel session is lost."; 2891 } 2892 } 2893 description 2894 "Enumeration for status reported by the DOTS server."; 2895 } 2897 typedef conflict-status { 2898 type enumeration { 2899 enum request-inactive-other-active { 2900 value 1; 2901 description 2902 "DOTS Server has detected conflicting mitigation 2903 requests from different DOTS clients. 2904 This mitigation request is currently inactive 2905 until the conflicts are resolved. Another 2906 mitigation request is active."; 2907 } 2908 enum request-active { 2909 value 2; 2910 description 2911 "DOTS Server has detected conflicting mitigation 2912 requests from different DOTS clients. 2913 This mitigation request is currently active."; 2914 } 2915 enum all-requests-inactive { 2916 value 3; 2917 description 2918 "DOTS Server has detected conflicting mitigation 2919 requests from different DOTS clients. All 2920 conflicting mitigation requests are inactive."; 2921 } 2922 } 2923 description 2924 "Enumeration for conflict status."; 2925 } 2927 typedef conflict-cause { 2928 type enumeration { 2929 enum overlapping-targets { 2930 value 1; 2931 description 2932 "Overlapping targets. conflict-scope provides 2933 more details about the exact conflict."; 2934 } 2935 enum conflict-with-acceptlist { 2936 value 2; 2937 description 2938 "Conflicts with an existing accept-list. 2940 This code is returned when the DDoS mitigation 2941 detects that some of the source addresses/prefixes 2942 listed in the accept-list ACLs are actually 2943 attacking the target."; 2944 } 2945 enum cuid-collision { 2946 value 3; 2947 description 2948 "Conflicts with the cuid used by another 2949 DOTS client."; 2950 } 2951 } 2952 description 2953 "Enumeration for conflict causes."; 2954 } 2955 typedef attack-status { 2956 type enumeration { 2957 enum under-attack { 2958 value 1; 2959 description 2960 "The DOTS client determines that it is still under 2961 attack."; 2962 } 2963 enum attack-successfully-mitigated { 2964 value 2; 2965 description 2966 "The DOTS client determines that the attack is 2967 successfully mitigated."; 2968 } 2969 } 2970 description 2971 "Enumeration for attack status codes."; 2972 } 2973 } 2974 2976 5.3. IETF DOTS Signal Channel YANG Module 2978 This module uses the common YANG types defined in [RFC6991] and types 2979 defined in [I-D.ietf-dots-data-channel]. 2981 file "ietf-dots-signal-channel@2019-11-13.yang" 2982 module ietf-dots-signal-channel { 2983 yang-version 1.1; 2984 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2985 prefix signal; 2987 import ietf-inet-types { 2988 prefix inet; 2989 reference "Section 4 of RFC 6991"; 2990 } 2991 import ietf-yang-types { 2992 prefix yang; 2993 reference "Section 3 of RFC 6991"; 2994 } 2995 import ietf-dots-data-channel { 2996 prefix ietf-data; 2997 reference 2998 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2999 (DOTS) Data Channel Specification"; 3000 } 3001 import iana-dots-signal-channel { 3002 prefix iana-signal; 3004 } 3006 organization 3007 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3008 contact 3009 "WG Web: 3010 WG List: 3012 Editor: Konda, Tirumaleswar Reddy 3013 3015 Editor: Mohamed Boucadair 3016 3018 Author: Prashanth Patil 3019 3021 Author: Andrew Mortensen 3022 3024 Author: Nik Teague 3025 "; 3026 description 3027 "This module contains YANG definition for the signaling 3028 messages exchanged between a DOTS client and a DOTS server. 3030 Copyright (c) 2019 IETF Trust and the persons identified as 3031 authors of the code. All rights reserved. 3033 Redistribution and use in source and binary forms, with or 3034 without modification, is permitted pursuant to, and subject 3035 to the license terms contained in, the Simplified BSD License 3036 set forth in Section 4.c of the IETF Trust's Legal Provisions 3037 Relating to IETF Documents 3038 (http://trustee.ietf.org/license-info). 3040 This version of this YANG module is part of RFC XXXX; see 3041 the RFC itself for full legal notices."; 3043 revision 2019-11-13 { 3044 description 3045 "Initial revision."; 3046 reference 3047 "RFC XXXX: Distributed Denial-of-Service Open Threat 3048 Signaling (DOTS) Signal Channel Specification"; 3049 } 3051 /* 3052 * Groupings 3053 */ 3055 grouping mitigation-scope { 3056 description 3057 "Specifies the scope of the mitigation request."; 3058 list scope { 3059 key "cuid mid"; 3060 description 3061 "The scope of the request."; 3062 leaf cdid { 3063 type string; 3064 description 3065 "The cdid should be included by a server-domain 3066 DOTS gateway to propagate the client domain 3067 identification information from the 3068 gateway's client-facing-side to the gateway's 3069 server-facing-side, and from the gateway's 3070 server-facing-side to the DOTS server. 3072 It may be used by the final DOTS server 3073 for policy enforcement purposes."; 3074 } 3075 leaf cuid { 3076 type string; 3077 description 3078 "A unique identifier that is 3079 generated by a DOTS client to prevent 3080 request collisions. It is expected that the 3081 cuid will remain consistent throughout the 3082 lifetime of the DOTS client."; 3083 } 3084 leaf mid { 3085 type uint32; 3086 description 3087 "Mitigation request identifier. 3089 This identifier must be unique for each mitigation 3090 request bound to the DOTS client."; 3091 } 3092 uses ietf-data:target; 3093 leaf-list alias-name { 3094 type string; 3095 description 3096 "An alias name that points to a resource."; 3097 } 3098 leaf lifetime { 3099 type int32; 3100 units "seconds"; 3101 default "3600"; 3102 description 3103 "Indicates the lifetime of the mitigation request. 3105 A lifetime of '0' in a mitigation request is an 3106 invalid value. 3108 A lifetime of negative one (-1) indicates indefinite 3109 lifetime for the mitigation request."; 3110 } 3111 leaf trigger-mitigation { 3112 type boolean; 3113 default "true"; 3114 description 3115 "If set to 'false', DDoS mitigation will not be 3116 triggered unless the DOTS signal channel 3117 session is lost."; 3118 } 3119 leaf mitigation-start { 3120 type uint64; 3121 config false; 3122 description 3123 "Mitigation start time is represented in seconds 3124 relative to 1970-01-01T00:00:00Z in UTC time."; 3125 } 3126 leaf status { 3127 type iana-signal:status; 3128 config false; 3129 description 3130 "Indicates the status of a mitigation request. 3131 It must be included in responses only."; 3132 } 3133 container conflict-information { 3134 config false; 3135 description 3136 "Indicates that a conflict is detected. 3137 Must only be used for responses."; 3138 leaf conflict-status { 3139 type iana-signal:conflict-status; 3140 description 3141 "Indicates the conflict status."; 3142 } 3143 leaf conflict-cause { 3144 type iana-signal:conflict-cause; 3145 description 3146 "Indicates the cause of the conflict."; 3147 } 3148 leaf retry-timer { 3149 type uint32; 3150 units "seconds"; 3151 description 3152 "The DOTS client must not re-send the 3153 same request that has a conflict before the expiry of 3154 this timer."; 3155 } 3156 container conflict-scope { 3157 description 3158 "Provides more information about the conflict scope."; 3159 uses ietf-data:target { 3160 when "../conflict-cause = 'overlapping-targets'"; 3161 } 3162 leaf-list alias-name { 3163 when "../../conflict-cause = 'overlapping-targets'"; 3164 type string; 3165 description 3166 "Conflicting alias-name."; 3167 } 3168 list acl-list { 3169 when "../../conflict-cause = 'conflict-with-acceptlist'"; 3170 key "acl-name"; 3171 description 3172 "List of conflicting ACLs as defined in the DOTS data 3173 channel. These ACLs are uniquely defined by 3174 cuid and acl-name."; 3175 leaf acl-name { 3176 type leafref { 3177 path "/ietf-data:dots-data/ietf-data:dots-client/" 3178 + "ietf-data:acls/ietf-data:acl/ietf-data:name"; 3179 } 3180 description 3181 "Reference to the conflicting ACL name bound to 3182 a DOTS client."; 3183 } 3184 leaf acl-type { 3185 type leafref { 3186 path "/ietf-data:dots-data/ietf-data:dots-client/" 3187 + "ietf-data:acls/ietf-data:acl/ietf-data:type"; 3188 } 3189 description 3190 "Reference to the conflicting ACL type bound to 3191 a DOTS client."; 3192 } 3193 } 3194 leaf mid { 3195 when "../../conflict-cause = 'overlapping-targets'"; 3196 type leafref { 3197 path "../../../mid"; 3198 } 3199 description 3200 "Reference to the conflicting 'mid' bound to 3201 the same DOTS client."; 3202 } 3203 } 3204 } 3205 leaf bytes-dropped { 3206 type yang:zero-based-counter64; 3207 units "bytes"; 3208 config false; 3209 description 3210 "The total dropped byte count for the mitigation 3211 request since the attack mitigation is triggered. 3212 The count wraps around when it reaches the maximum value 3213 of counter64 for dropped bytes."; 3214 } 3215 leaf bps-dropped { 3216 type yang:gauge64; 3217 config false; 3218 description 3219 "The average number of dropped bits per second for 3220 the mitigation request since the attack 3221 mitigation is triggered. This should be over 3222 five-minute intervals (that is, measuring bytes 3223 into five-minute buckets and then averaging these 3224 buckets over the time since the mitigation was 3225 triggered)."; 3226 } 3227 leaf pkts-dropped { 3228 type yang:zero-based-counter64; 3229 config false; 3230 description 3231 "The total number of dropped packet count for the 3232 mitigation request since the attack mitigation is 3233 triggered. The count wraps around when it reaches 3234 the maximum value of counter64 for dropped packets."; 3235 } 3236 leaf pps-dropped { 3237 type yang:gauge64; 3238 config false; 3239 description 3240 "The average number of dropped packets per second 3241 for the mitigation request since the attack 3242 mitigation is triggered. This should be over 3243 five-minute intervals (that is, measuring packets 3244 into five-minute buckets and then averaging these 3245 buckets over the time since the mitigation was 3246 triggered)."; 3247 } 3248 leaf attack-status { 3249 type iana-signal:attack-status; 3250 description 3251 "Indicates the status of an attack as seen by the 3252 DOTS client."; 3253 } 3254 } 3255 } 3257 grouping config-parameters { 3258 description 3259 "Subset of DOTS signal channel session configuration."; 3260 container heartbeat-interval { 3261 description 3262 "DOTS agents regularly send heartbeats to each other 3263 after mutual authentication is successfully 3264 completed in order to keep the DOTS signal channel 3265 open."; 3266 leaf max-value { 3267 type uint16; 3268 units "seconds"; 3269 config false; 3270 description 3271 "Maximum acceptable heartbeat-interval value."; 3272 } 3273 leaf min-value { 3274 type uint16; 3275 units "seconds"; 3276 config false; 3277 description 3278 "Minimum acceptable heartbeat-interval value."; 3279 } 3280 leaf current-value { 3281 type uint16; 3282 units "seconds"; 3283 default "30"; 3284 description 3285 "Current heartbeat-interval value. 3287 '0' means that heartbeat mechanism is deactivated."; 3288 } 3289 } 3290 container missing-hb-allowed { 3291 description 3292 "Maximum number of missing heartbeats allowed."; 3293 leaf max-value { 3294 type uint16; 3295 config false; 3296 description 3297 "Maximum acceptable missing-hb-allowed value."; 3298 } 3299 leaf min-value { 3300 type uint16; 3301 config false; 3302 description 3303 "Minimum acceptable missing-hb-allowed value."; 3304 } 3305 leaf current-value { 3306 type uint16; 3307 default "15"; 3308 description 3309 "Current missing-hb-allowed value."; 3310 } 3311 } 3312 container probing-rate { 3313 description 3314 "The limit for sending non-confirmable messages with 3315 no response."; 3316 leaf max-value { 3317 type uint16; 3318 units "byte/second"; 3319 config false; 3320 description 3321 "Maximum acceptable probing-rate value."; 3322 } 3323 leaf min-value { 3324 type uint16; 3325 units "byte/second"; 3326 config false; 3327 description 3328 "Minimum acceptable probing-rate value."; 3329 } 3330 leaf current-value { 3331 type uint16; 3332 units "byte/second"; 3333 default "5"; 3334 description 3335 "Current probing-rate value."; 3336 } 3337 } 3338 container max-retransmit { 3339 description 3340 "Maximum number of retransmissions of a Confirmable 3341 message."; 3342 leaf max-value { 3343 type uint16; 3344 config false; 3345 description 3346 "Maximum acceptable max-retransmit value."; 3347 } 3348 leaf min-value { 3349 type uint16; 3350 config false; 3351 description 3352 "Minimum acceptable max-retransmit value."; 3353 } 3354 leaf current-value { 3355 type uint16; 3356 default "3"; 3357 description 3358 "Current max-retransmit value."; 3359 } 3360 } 3361 container ack-timeout { 3362 description 3363 "Initial retransmission timeout value."; 3364 leaf max-value-decimal { 3365 type decimal64 { 3366 fraction-digits 2; 3367 } 3368 units "seconds"; 3369 config false; 3370 description 3371 "Maximum ack-timeout value."; 3372 } 3373 leaf min-value-decimal { 3374 type decimal64 { 3375 fraction-digits 2; 3376 } 3377 units "seconds"; 3378 config false; 3379 description 3380 "Minimum ack-timeout value."; 3381 } 3382 leaf current-value-decimal { 3383 type decimal64 { 3384 fraction-digits 2; 3385 } 3386 units "seconds"; 3387 default "2"; 3388 description 3389 "Current ack-timeout value."; 3390 } 3391 } 3392 container ack-random-factor { 3393 description 3394 "Random factor used to influence the timing of 3395 retransmissions."; 3396 leaf max-value-decimal { 3397 type decimal64 { 3398 fraction-digits 2; 3399 } 3400 config false; 3401 description 3402 "Maximum acceptable ack-random-factor value."; 3403 } 3404 leaf min-value-decimal { 3405 type decimal64 { 3406 fraction-digits 2; 3407 } 3408 config false; 3409 description 3410 "Minimum acceptable ack-random-factor value."; 3411 } 3412 leaf current-value-decimal { 3413 type decimal64 { 3414 fraction-digits 2; 3415 } 3416 default "1.5"; 3417 description 3418 "Current ack-random-factor value."; 3419 } 3420 } 3421 } 3423 grouping signal-config { 3424 description 3425 "DOTS signal channel session configuration."; 3426 leaf sid { 3427 type uint32; 3428 mandatory true; 3429 description 3430 "An identifier for the DOTS signal channel 3431 session configuration data."; 3432 } 3433 container mitigating-config { 3434 description 3435 "Configuration parameters to use when a mitigation 3436 is active."; 3437 uses config-parameters; 3438 } 3439 container idle-config { 3440 description 3441 "Configuration parameters to use when no mitigation 3442 is active."; 3443 uses config-parameters; 3444 } 3445 } 3447 grouping redirected-signal { 3448 description 3449 "Grouping for the redirected signaling."; 3450 leaf alt-server { 3451 type string; 3452 config false; 3453 mandatory true; 3454 description 3455 "FQDN of an alternate server."; 3456 } 3457 leaf-list alt-server-record { 3458 type inet:ip-address; 3459 config false; 3460 description 3461 "List of records for the alternate server."; 3462 } 3463 } 3465 /* 3466 * Main Container for DOTS Signal Channel 3467 */ 3469 container dots-signal { 3470 description 3471 "Main container for DOTS signal message. 3473 A DOTS signal message can be a mitigation, a configuration, 3474 or a redirected signal message."; 3475 choice message-type { 3476 description 3477 "Can be a mitigation, a configuration, or a redirect 3478 message."; 3479 case mitigation-scope { 3480 description 3481 "Mitigation scope of a mitigation message."; 3482 uses mitigation-scope; 3483 } 3484 case signal-config { 3485 description 3486 "Configuration message."; 3487 uses signal-config; 3488 } 3489 case redirected-signal { 3490 description 3491 "Redirected signaling."; 3492 uses redirected-signal; 3493 } 3494 case heartbeat { 3495 description 3496 "DOTS heartbeats."; 3497 leaf peer-hb-status { 3498 type boolean; 3499 mandatory true; 3500 description 3501 "Indicates whether a DOTS agent receives heartbeats 3502 from its peer."; 3503 } 3504 } 3505 } 3506 } 3507 } 3508 3510 6. YANG/JSON Mapping Parameters to CBOR 3512 All parameters in the payload of the DOTS signal channel MUST be 3513 mapped to CBOR types as shown in Table 4 and are assigned an integer 3514 key to save space. 3516 o Note: Implementers must check that the mapping output provided by 3517 their YANG-to-CBOR encoding schemes is aligned with the content of 3518 Table 4. For example, some CBOR and JSON types for enumerations 3519 and the 64-bit quantities can differ depending on the encoder 3520 used. 3522 The CBOR key values are divided into two types: comprehension- 3523 required and comprehension-optional. DOTS agents can safely ignore 3524 comprehension-optional values they don't understand, but cannot 3525 successfully process a request if it contains comprehension-required 3526 values that are not understood. The 4.00 response SHOULD include a 3527 diagnostic payload describing the unknown comprehension-required CBOR 3528 key values. The initial set of CBOR key values defined in this 3529 specification are of type comprehension-required. 3531 +----------------------+-------------+-----+---------------+--------+ 3532 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3533 | | Type | Key | Type & | Type | 3534 | | | | Information | | 3535 +----------------------+-------------+-----+---------------+--------+ 3536 | ietf-dots-signal-cha | | | | | 3537 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3538 | scope | list | 2 | 4 array | Array | 3539 | cdid | string | 3 | 3 text string | String | 3540 | cuid | string | 4 | 3 text string | String | 3541 | mid | uint32 | 5 | 0 unsigned | Number | 3542 | target-prefix | leaf-list | 6 | 4 array | Array | 3543 | | inet: | | | | 3544 | | ip-prefix | | 3 text string | String | 3545 | target-port-range | list | 7 | 4 array | Array | 3546 | lower-port | inet: | | | | 3547 | | port-number| 8 | 0 unsigned | Number | 3548 | upper-port | inet: | | | | 3549 | | port-number| 9 | 0 unsigned | Number | 3550 | target-protocol | leaf-list | 10 | 4 array | Array | 3551 | | uint8 | | 0 unsigned | Number | 3552 | target-fqdn | leaf-list | 11 | 4 array | Array | 3553 | | inet: | | | | 3554 | | domain-name| | 3 text string | String | 3555 | target-uri | leaf-list | 12 | 4 array | Array | 3556 | | inet:uri | | 3 text string | String | 3557 | alias-name | leaf-list | 13 | 4 array | Array | 3558 | | string | | 3 text string | String | 3559 | lifetime | int32 | 14 | 0 unsigned | Number | 3560 | | | | 1 negative | Number | 3561 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3562 | status | enumeration | 16 | 0 unsigned | String | 3563 | conflict-information | container | 17 | 5 map | Object | 3564 | conflict-status | enumeration | 18 | 0 unsigned | String | 3565 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3566 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3567 | conflict-scope | container | 21 | 5 map | Object | 3568 | acl-list | list | 22 | 4 array | Array | 3569 | acl-name | leafref | 23 | 3 text string | String | 3570 | acl-type | leafref | 24 | 3 text string | String | 3571 | bytes-dropped | yang:zero- | | | | 3572 | | based- | | | | 3573 | | counter64 | 25 | 0 unsigned | String | 3574 | bps-dropped | yang:gauge64| 26 | 0 unsigned | String | 3575 | pkts-dropped | yang:zero- | | | | 3576 | | based- | | | | 3577 | | counter64 | 27 | 0 unsigned | String | 3578 | pps-dropped | yang:gauge64| 28 | 0 unsigned | String | 3579 | attack-status | enumeration | 29 | 0 unsigned | String | 3580 | ietf-dots-signal- | | | | | 3581 | channel:signal-config| container | 30 | 5 map | Object | 3582 | sid | uint32 | 31 | 0 unsigned | Number | 3583 | mitigating-config | container | 32 | 5 map | Object | 3584 | heartbeat-interval | container | 33 | 5 map | Object | 3585 | max-value | uint16 | 34 | 0 unsigned | Number | 3586 | min-value | uint16 | 35 | 0 unsigned | Number | 3587 | current-value | uint16 | 36 | 0 unsigned | Number | 3588 | missing-hb-allowed | container | 37 | 5 map | Object | 3589 | max-retransmit | container | 38 | 5 map | Object | 3590 | ack-timeout | container | 39 | 5 map | Object | 3591 | ack-random-factor | container | 40 | 5 map | Object | 3592 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3593 | | | | [-2, integer]| String | 3594 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3595 | | | | [-2, integer]| String | 3596 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3597 | | | | [-2, integer]| String | 3598 | idle-config | container | 44 | 5 map | Object | 3599 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3600 | | | | 7 bits 21 | True | 3601 | ietf-dots-signal-cha | | | | | 3602 |nnel:redirected-signal| container | 46 | 5 map | Object | 3603 | alt-server | string | 47 | 3 text string | String | 3604 | alt-server-record | leaf-list | 48 | 4 array | Array | 3605 | | inet: | | | | 3606 | | ip-address | | 3 text string | String | 3607 | ietf-dots-signal-cha | | | | | 3608 | nnel:heartbeat | container | 49 | 5 map | Object | 3609 | probing-rate | container | 50 | 5 map | Object | 3610 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3611 | | | | 7 bits 21 | True | 3612 +----------------------+-------------+-----+---------------+--------+ 3614 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3615 Mappings to JSON and YANG 3617 7. (D)TLS Protocol Profile and Performance Considerations 3619 7.1. (D)TLS Protocol Profile 3621 This section defines the (D)TLS protocol profile of DOTS signal 3622 channel over (D)TLS and DOTS data channel over TLS. 3624 There are known attacks on (D)TLS, such as man-in-the-middle and 3625 protocol downgrade attacks. These are general attacks on (D)TLS and, 3626 as such, they are not specific to DOTS over (D)TLS; refer to the 3627 (D)TLS RFCs for discussion of these security issues. DOTS agents 3628 MUST adhere to the (D)TLS implementation recommendations and security 3629 considerations of [RFC7525] except with respect to (D)TLS version. 3630 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3631 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3632 or later. 3634 When a DOTS client is configured with a domain name of the DOTS 3635 server, and connects to its configured DOTS server, the server may 3636 present it with a PKIX certificate. In order to ensure proper 3637 authentication, a DOTS client MUST verify the entire certification 3638 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3639 validation techniques to compare the domain name with the certificate 3640 provided. Certification authorities that issue DOTS server 3641 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3642 DOTS server SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3643 identifier types in certificate requests (as described in Section 2.3 3644 of [RFC6125]) and the wildcard character '*' SHOULD NOT be included 3645 in the presented identifier. DOTS doesn't use URI-IDs for server 3646 identity verification. 3648 A key challenge to deploying DOTS is the provisioning of DOTS 3649 clients, including the distribution of keying material to DOTS 3650 clients to enable the required mutual authentication of DOTS agents. 3651 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3652 certificate enrollment by which domains operating DOTS servers may 3653 provide DOTS clients with all the necessary cryptographic keying 3654 material, including a private key and a certificate to authenticate 3655 themselves. One deployment option is DOTS clients behave as EST 3656 clients for certificate enrollment from an EST server provisioned by 3657 the mitigation provider. This document does not specify which EST or 3658 other mechanism the DOTS client uses to achieve initial enrollment. 3660 The Server Name Indication (SNI) extension [RFC6066] defines a 3661 mechanism for a client to tell a (D)TLS server the name of the server 3662 it wants to contact. This is a useful extension for hosting 3663 environments where multiple virtual servers are reachable over a 3664 single IP address. The DOTS client may or may not know if it is 3665 interacting with a DOTS server in a virtual server hosting 3666 environment, so the DOTS client SHOULD include the DOTS server FQDN 3667 in the SNI extension. 3669 Implementations compliant with this profile MUST implement all of the 3670 following items: 3672 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3673 equivalent mechanism to protect against replay attacks. 3675 o DTLS session resumption without server-side state to resume 3676 session and convey the DOTS signal. 3678 o At least one of raw public keys [RFC7250] or PSK handshake 3679 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3680 ServerHello, and can be used by DOTS agents that cannot obtain 3681 certificates. 3683 Implementations compliant with this profile SHOULD implement all of 3684 the following items to reduce the delay required to deliver a DOTS 3685 signal channel message: 3687 o TLS False Start [RFC7918] which reduces round-trips by allowing 3688 the TLS client's second flight of messages (ChangeCipherSpec) to 3689 also contain the DOTS signal. TLS False Start is formally defined 3690 for use with TLS, but the same technique is applicable to DTLS as 3691 well. 3693 o Cached Information Extension [RFC7924] which avoids transmitting 3694 the server's certificate and certificate chain if the client has 3695 cached that information from a previous TLS handshake. 3697 Compared to UDP, DOTS signal channel over TCP requires an additional 3698 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3699 implementations are encouraged to implement TCP Fast Open [RFC7413] 3700 to eliminate that RTT. 3702 7.2. (D)TLS 1.3 Considerations 3704 TLS 1.3 provides critical latency improvements for connection 3705 establishment over TLS 1.2. The DTLS 1.3 protocol 3706 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3707 equivalent security guarantees. (D)TLS 1.3 provides two basic 3708 handshake modes the DOTS signal channel can take advantage of: 3710 o A full handshake mode in which a DOTS client can send a DOTS 3711 mitigation request message after one round trip and the DOTS 3712 server immediately responds with a DOTS mitigation response. This 3713 assumes no packet loss is experienced. 3715 o 0-RTT mode in which the DOTS client can authenticate itself and 3716 send DOTS mitigation request messages in the first message, thus 3717 reducing handshake latency. 0-RTT only works if the DOTS client 3718 has previously communicated with that DOTS server, which is very 3719 likely with the DOTS signal channel. 3721 The DOTS client has to establish a (D)TLS session with the DOTS 3722 server during 'idle' time and share a PSK. 3724 During a DDoS attack, the DOTS client can use the (D)TLS session 3725 to convey the DOTS mitigation request message and, if there is no 3726 response from the server after multiple retries, the DOTS client 3727 can resume the (D)TLS session in 0-RTT mode using PSK. 3729 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to 3730 send early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" 3731 as early data; such messages MUST be rejected by DOTS servers. 3732 Section 8 of [RFC8446] discusses some mechanisms to implement to 3733 limit the impact of replay attacks on 0-RTT data. If the DOTS 3734 server accepts 0-RTT, it MUST implement one of these mechanisms to 3735 prevent replay at the TLS layer. A DOTS server can reject 0-RTT 3736 by sending a TLS HelloRetryRequest. 3738 The DOTS signal channel messages sent as early data by the DOTS 3739 client are idempotent requests. As a reminder, the Message ID 3740 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3741 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3742 in each CoAP request. The DOTS server(s) MUST use the Message ID 3743 and the Token in the DOTS signal channel message to detect replay 3744 of early data at the application layer, and accept 0-RTT data at 3745 most once from the same DOTS client. This anti-replay defense 3746 requires sharing the Message ID and the Token in the 0-RTT data 3747 between DOTS servers in the DOTS server domain. DOTS servers do 3748 not rely on transport coordinates to identify DOTS peers. As 3749 specified in Section 4.4.1, DOTS servers couple the DOTS signal 3750 channel sessions using the DOTS client identity and optionally the 3751 'cdid' parameter value. Furthermore, 'mid' value is monotonically 3752 increased by the DOTS client for each mitigation request, 3753 attackers replaying mitigation requests with lower numeric 'mid' 3754 values and overlapping scopes with mitigation requests having 3755 higher numeric 'mid' values will be rejected systematically by the 3756 DOTS server. Likewise, 'sid' value is monotonically increased by 3757 the DOTS client for each configuration request (Section 4.5.2), 3758 attackers replaying configuration requests with lower numeric 3759 'sid' values will be rejected by the DOTS server if it maintains a 3760 higher numeric 'sid' value for this DOTS client. 3762 Owing to the aforementioned protections, all DOTS signal channel 3763 requests are safe to transmit in TLS 1.3 as early data. Refer to 3764 [I-D.boucadair-dots-earlydata] for more details. 3766 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3767 message exchange is shown in Figure 29. 3769 DOTS Client DOTS Server 3771 ClientHello 3772 (0-RTT DOTS signal message) 3773 --------> 3774 ServerHello 3775 {EncryptedExtensions} 3776 {Finished} 3777 <-------- [DOTS signal message] 3778 (end_of_early_data) 3779 {Finished} --------> 3780 [DOTS signal message] <-------> [DOTS signal message] 3782 Note that: 3783 () Indicates messages protected 0-RTT keys 3784 {} Indicates messages protected using handshake keys 3785 [] Indicates messages protected using 1-RTT keys 3787 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 3789 7.3. DTLS MTU and Fragmentation 3791 To avoid DOTS signal message fragmentation and the subsequent 3792 decreased probability of message delivery, DOTS agents MUST ensure 3793 that the DTLS record fit within a single datagram. As a reminder, 3794 DTLS handles fragmentation and reassembly only for handshake messages 3795 and not for the application data (Section 4.1.1 of [RFC6347]). If 3796 the PMTU cannot be discovered, DOTS agents MUST assume a PMTU of 1280 3797 bytes, as IPv6 requires that every link in the Internet have an MTU 3798 of 1280 octets or greater as specified in [RFC8200]. If IPv4 support 3799 on legacy or otherwise unusual networks is a consideration and the 3800 PMTU is unknown, DOTS implementations MAY assume on a PMTU of 576 3801 bytes for IPv4 datagrams, as every IPv4 host must be capable of 3802 receiving a packet whose length is equal to 576 bytes as discussed in 3803 [RFC0791] and [RFC1122]. 3805 The DOTS client must consider the amount of record expansion expected 3806 by the DTLS processing when calculating the size of CoAP message that 3807 fits within the path MTU. Path MTU MUST be greater than or equal to 3808 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 3809 overhead of the negotiated DTLS cipher suite + block padding] 3810 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 3811 the path MTU then the DOTS client MUST split the DOTS signal into 3812 separate messages; for example, the list of addresses in the 'target- 3813 prefix' parameter could be split into multiple lists and each list 3814 conveyed in a new PUT request. 3816 Implementation Note: DOTS choice of message size parameters works 3817 well with IPv6 and with most of today's IPv4 paths. However, with 3818 IPv4, it is harder to safely make sure that there is no IP 3819 fragmentation. If the IPv4 path MTU is unknown, implementations may 3820 want to limit themselves to more conservative IPv4 datagram sizes 3821 such as 576 bytes, as per [RFC0791]. 3823 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3825 (D)TLS based upon client certificate can be used for mutual 3826 authentication between DOTS agents. If, for example, a DOTS gateway 3827 is involved, DOTS clients and DOTS gateways must perform mutual 3828 authentication; only authorized DOTS clients are allowed to send DOTS 3829 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3830 perform mutual authentication; a DOTS server only allows DOTS signal 3831 channel messages from an authorized DOTS gateway, thereby creating a 3832 two-link chain of transitive authentication between the DOTS client 3833 and the DOTS server. 3835 The DOTS server should support certificate-based client 3836 authentication. The DOTS client should respond to the DOTS server's 3837 TLS CertificateRequest message with the PKIX certificate held by the 3838 DOTS client. DOTS client certificate validation must be performed as 3839 per [RFC5280] and the DOTS client certificate must conform to the 3840 [RFC5280] certificate profile. If a DOTS client does not support TLS 3841 client certificate authentication, it must support pre-shared key 3842 based or raw public key based client authentication. 3844 +---------------------------------------------+ 3845 | example.com domain +---------+ | 3846 | | AAA | | 3847 | +---------------+ | Server | | 3848 | | Application | +------+--+ | 3849 | | server +<---------------+ ^ | 3850 | | (DOTS client) | | | | 3851 | +---------------+ | | | 3852 | V V | example.net domain 3853 | +-----+----+--+ | +---------------+ 3854 | +--------------+ | | | | | 3855 | | Guest +<----x---->+ DOTS +<------>+ DOTS | 3856 | | (DOTS client)| | gateway | | | server | 3857 | +--------------+ | | | | | 3858 | +----+--------+ | +---------------+ 3859 | ^ | 3860 | | | 3861 | +----------------+ | | 3862 | | DDoS detector | | | 3863 | | (DOTS client) +<-------------+ | 3864 | +----------------+ | 3865 +---------------------------------------------+ 3867 Figure 30: Example of Authentication and Authorization of DOTS Agents 3869 In the example depicted in Figure 30, the DOTS gateway and DOTS 3870 clients within the 'example.com' domain mutually authenticate. After 3871 the DOTS gateway validates the identity of a DOTS client, it 3872 communicates with the AAA server in the 'example.com' domain to 3873 determine if the DOTS client is authorized to request DDoS 3874 mitigation. If the DOTS client is not authorized, a 4.01 3875 (Unauthorized) is returned in the response to the DOTS client. In 3876 this example, the DOTS gateway only allows the application server and 3877 DDoS attack detector to request DDoS mitigation, but does not permit 3878 the user of type 'guest' to request DDoS mitigation. 3880 Also, DOTS gateways and servers located in different domains must 3881 perform mutual authentication (e.g., using certificates). A DOTS 3882 server will only allow a DOTS gateway with a certificate for a 3883 particular domain to request mitigation for that domain. In 3884 reference to Figure 30, the DOTS server only allows the DOTS gateway 3885 to request mitigation for 'example.com' domain and not for other 3886 domains. 3888 9. IANA Considerations 3890 9.1. DOTS Signal Channel UDP and TCP Port Number 3892 IANA is requested to assign the port number TBD to the DOTS signal 3893 channel protocol for both UDP and TCP from the "Service Name and 3894 Transport Protocol Port Number Registry" available at 3895 https://www.iana.org/assignments/service-names-port-numbers/service- 3896 names-port-numbers.xhtml. 3898 The assignment of port number 4646 is strongly suggested, as 4646 is 3899 the ASCII decimal value for ".." (DOTS). 3901 9.2. Well-Known 'dots' URI 3903 This document requests IANA to register the 'dots' well-known URI 3904 (Table 5) in the Well-Known URIs registry 3905 (https://www.iana.org/assignments/well-known-uris/well-known- 3906 uris.xhtml) as defined by [RFC8615]: 3908 +----------+----------------+---------------------+-----------------+ 3909 | URI | Change | Specification | Related | 3910 | suffix | controller | document(s) | information | 3911 +----------+----------------+---------------------+-----------------+ 3912 | dots | IETF | [RFCXXXX] | None | 3913 +----------+----------------+---------------------+-----------------+ 3915 Table 5: 'dots' well-known URI 3917 9.3. Media Type Registration 3919 This document requests IANA to register the "application/dots+cbor" 3920 media type in the "Media Types" registry [IANA.MediaTypes] in the 3921 manner described in [RFC6838], which can be used to indicate that the 3922 content is a DOTS signal channel object: 3924 o Type name: application 3925 o Subtype name: dots+cbor 3926 o Required parameters: N/A 3927 o Optional parameters: N/A 3928 o Encoding considerations: binary 3929 o Security considerations: See the Security Considerations section 3930 of [RFCXXXX] 3931 o Interoperability considerations: N/A 3932 o Published specification: [RFCXXXX] 3933 o Applications that use this media type: DOTS agents sending DOTS 3934 messages over CoAP over (D)TLS. 3935 o Fragment identifier considerations: N/A 3936 o Additional information: 3938 Magic number(s): N/A 3939 File extension(s): N/A 3940 Macintosh file type code(s): N/A 3941 o Person & email address to contact for further information: 3942 IESG, iesg@ietf.org 3943 o Intended usage: COMMON 3944 o Restrictions on usage: none 3945 o Author: See Authors' Addresses section. 3946 o Change controller: IESG 3947 o Provisional registration? No 3949 9.4. CoAP Content-Formats Registration 3951 This document requests IANA to register the CoAP Content-Format ID 3952 for the "application/dots+cbor" media type in the "CoAP Content- 3953 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3955 o Media Type: application/dots+cbor 3956 o Encoding: - 3957 o Id: TBD1 3958 o Reference: [RFCXXXX] 3960 9.5. CBOR Tag Registration 3962 This section defines the DOTS CBOR tag as another means for 3963 applications to declare that a CBOR data structure is a DOTS signal 3964 channel object. Its use is optional and is intended for use in cases 3965 in which this information would not otherwise be known. DOTS CBOR 3966 tag is not required for DOTS signal channel protocol version 3967 specified in this document. If present, the DOTS tag MUST prefix a 3968 DOTS signal channel object. 3970 This document requests IANA to register the DOTS signal channel CBOR 3971 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3972 range: 3974 o CBOR Tag: TBD2 (please assign the same value as the Content- 3975 Format) 3976 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3977 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3978 object, as defined in [RFCXXXX] 3979 o Description of Semantics: [RFCXXXX] 3981 9.6. DOTS Signal Channel Protocol Registry 3983 The document requests IANA to create a new registry, entitled "DOTS 3984 Signal Channel Registry". The following sections define sub- 3985 registries. 3987 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3989 The document requests IANA to create a new sub-registry, entitled 3990 "DOTS Signal Channel CBOR Key Values". 3992 The structure of this sub-registry is provided in Section 9.6.1.1. 3993 Section 9.6.1.2 provides how the registry is initially populated with 3994 the values in Table 4. 3996 9.6.1.1. Registration Template 3998 Parameter name: 3999 Parameter name as used in the DOTS signal channel. 4001 CBOR Key Value: 4002 Key value for the parameter. The key value MUST be an integer in 4003 the 1-65535 range. The key values of the comprehension-required 4004 range (0x0001 - 0x3FFF) and of the comprehension-optional range 4005 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 4006 [RFC8126]). The key values of the comprehension-optional range 4007 (0x4000 - 0x7FFF) are assigned by Specification Required 4008 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 4009 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 4010 [RFC8126]). 4012 Registration requests for the 0x4000 - 0x7FFF range are evaluated 4013 after a three-week review period on the dots-signal-reg- 4014 review@ietf.org mailing list, on the advice of one or more 4015 Designated Experts. However, to allow for the allocation of 4016 values prior to publication, the Designated Experts may approve 4017 registration once they are satisfied that such a specification 4018 will be published. New registration requests should be sent in 4019 the form of an email to the review mailing list; the request 4020 should use an appropriate subject (e.g., "Request to register CBOR 4021 Key Value for DOTS: example"). IANA will only accept new 4022 registrations from the Designated Experts, and will check that 4023 review was requested on the mailing list in accordance with these 4024 procedures. 4026 Within the review period, the Designated Experts will either 4027 approve or deny the registration request, communicating this 4028 decision to the review list and IANA. Denials should include an 4029 explanation and, if applicable, suggestions as to how to make the 4030 request successful. Registration requests that are undetermined 4031 for a period longer than 21 days can be brought to the IESG's 4032 attention (using the iesg@ietf.org mailing list) for resolution. 4034 Criteria that should be applied by the Designated Experts includes 4035 determining whether the proposed registration duplicates existing 4036 functionality, whether it is likely to be of general applicability 4037 or whether it is useful only for a single use case, and whether 4038 the registration description is clear. IANA must only accept 4039 registry updates to the 0x4000 - 0x7FFF range from the Designated 4040 Experts and should direct all requests for registration to the 4041 review mailing list. It is suggested that multiple Designated 4042 Experts be appointed. In cases where a registration decision 4043 could be perceived as creating a conflict of interest for a 4044 particular Expert, that Expert should defer to the judgment of the 4045 other Experts. 4047 CBOR Major Type: 4048 CBOR Major type and optional tag for the parameter. 4050 Change Controller: 4051 For Standards Track RFCs, list the "IESG". For others, give the 4052 name of the responsible party. Other details (e.g., email 4053 address) may also be included. 4055 Specification Document(s): 4056 Reference to the document or documents that specify the parameter, 4057 preferably including URIs that can be used to retrieve copies of 4058 the documents. An indication of the relevant sections may also be 4059 included but is not required. 4061 9.6.1.2. Initial Sub-Registry Content 4063 +----------------------+-------+-------+------------+---------------+ 4064 | Parameter Name | CBOR | CBOR | Change | Specification | 4065 | | Key | Major | Controller | Document(s) | 4066 | | Value | Type | | | 4067 +----------------------+-------+-------+------------+---------------+ 4068 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 4069 | nel:mitigation-scope | | | | | 4070 | scope | 2 | 4 | IESG | [RFCXXXX] | 4071 | cdid | 3 | 3 | IESG | [RFCXXXX] | 4072 | cuid | 4 | 3 | IESG | [RFCXXXX] | 4073 | mid | 5 | 0 | IESG | [RFCXXXX] | 4074 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 4075 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 4076 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 4077 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 4078 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 4079 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 4080 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 4081 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 4082 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 4083 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 4084 | status | 16 | 0 | IESG | [RFCXXXX] | 4085 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 4086 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 4087 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 4088 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 4089 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 4090 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 4091 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 4092 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 4093 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 4094 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 4095 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 4096 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 4097 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 4098 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 4099 | channel:signal-config| | | | | 4100 | sid | 31 | 0 | IESG | [RFCXXXX] | 4101 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 4102 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 4103 | min-value | 34 | 0 | IESG | [RFCXXXX] | 4104 | max-value | 35 | 0 | IESG | [RFCXXXX] | 4105 | current-value | 36 | 0 | IESG | [RFCXXXX] | 4106 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 4107 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 4108 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 4109 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 4110 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 4111 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 4112 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 4113 | decimal | | | | | 4114 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 4115 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 4116 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 4117 | nel:redirected-signal| | | | | 4118 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 4119 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 4120 | ietf-dots-signal-chan| 49 | 5 | IESG | [RFCXXXX] | 4121 | nel:heartbeat | | | | | 4122 | probing-rate | 50 | 5 | IESG | [RFCXXXX] | 4123 | peer-hb-status | 51 | 7 | IESG | [RFCXXXX] | 4124 +----------------------+-------+-------+------------+---------------+ 4125 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 4127 9.6.2. Status Codes Sub-Registry 4129 The document requests IANA to create a new sub-registry, entitled 4130 "DOTS Signal Channel Status Codes". Codes in this registry are used 4131 as valid values of 'status' parameter. 4133 The registry is initially populated with the following values: 4135 +-----+----------------------------------+--------------+-----------+ 4136 | Cod | Label | Description | Reference | 4137 | e | | | | 4138 +-----+----------------------------------+--------------+-----------+ 4139 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 4140 | | | mitigation | | 4141 | | | setup is in | | 4142 | | | progress | | 4143 | | | (e.g., | | 4144 | | | changing the | | 4145 | | | network path | | 4146 | | | to redirect | | 4147 | | | the inbound | | 4148 | | | traffic to a | | 4149 | | | DOTS | | 4150 | | | mitigator). | | 4151 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 4152 | | | being | | 4153 | | | successfully | | 4154 | | | mitigated | | 4155 | | | (e.g., | | 4156 | | | traffic is | | 4157 | | | redirected | | 4158 | | | to a DDoS | | 4159 | | | mitigator | | 4160 | | | and attack | | 4161 | | | traffic is | | 4162 | | | dropped). | | 4163 | 3 | attack-stopped | Attack has | [RFCXXXX] | 4164 | | | stopped and | | 4165 | | | the DOTS | | 4166 | | | client can | | 4167 | | | withdraw the | | 4168 | | | mitigation | | 4169 | | | request. | | 4170 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 4171 | | | exceeded the | | 4172 | | | mitigation | | 4173 | | | provider | | 4174 | | | capability. | | 4175 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 4176 | | | has | | 4177 | | | withdrawn | | 4178 | | | the | | 4179 | | | mitigation | | 4180 | | | request and | | 4181 | | | the | | 4182 | | | mitigation | | 4183 | | | is active | | 4184 | | | but | | 4185 | | | terminating. | | 4186 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 4187 | | | mitigation | | 4188 | | | is now | | 4189 | | | terminated. | | 4190 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 4191 | | | mitigation | | 4192 | | | is | | 4193 | | | withdrawn. | | 4194 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 4195 | | | mitigation | | 4196 | | | will be | | 4197 | | | triggered | | 4198 | | | for the | | 4199 | | | mitigation | | 4200 | | | request | | 4201 | | | only when | | 4202 | | | the DOTS | | 4203 | | | 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 | | 4282 | | | when the DDoS | | 4283 | | | mitigation detects | | 4284 | | | source | | 4285 | | | addresses/prefixes | | 4286 | | | in the | | 4287 | | | accept-listed ACLs | | 4288 | | | are attacking the | | 4289 | | | target. | | 4290 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 4291 | | | This code is | | 4292 | | | returned when a | | 4293 | | | DOTS client uses a | | 4294 | | | 'cuid' that is | | 4295 | | | already used by | | 4296 | | | another DOTS | | 4297 | | | client. | | 4298 +------+--------------------------+---------------------+-----------+ 4300 New codes can be assigned via Standards Action [RFC8126]. 4302 9.6.5. Attack Status Codes Sub-Registry 4304 The document requests IANA to create a new sub-registry, entitled 4305 "DOTS Signal Channel Attack Status Codes". Codes in this registry 4306 are used as valid values of 'attack-status' parameter. 4308 The registry is initially populated with the following values: 4310 +------+-------------------------------+----------------+-----------+ 4311 | Code | Label | Description | Reference | 4312 +------+-------------------------------+----------------+-----------+ 4313 | 1 | under-attack | The DOTS | [RFCXXXX] | 4314 | | | client | | 4315 | | | determines | | 4316 | | | that it is | | 4317 | | | still under | | 4318 | | | attack. | | 4319 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 4320 | | | client | | 4321 | | | determines | | 4322 | | | that the | | 4323 | | | attack is | | 4324 | | | successfully | | 4325 | | | mitigated. | | 4326 +------+-------------------------------+----------------+-----------+ 4328 New codes can be assigned via Standards Action [RFC8126]. 4330 9.7. DOTS Signal Channel YANG Modules 4332 This document requests IANA to register the following URIs in the 4333 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4335 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4336 Registrant Contact: The IESG. 4337 XML: N/A; the requested URI is an XML namespace. 4339 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4340 Registrant Contact: IANA. 4341 XML: N/A; the requested URI is an XML namespace. 4343 This document requests IANA to register the following YANG modules in 4344 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4345 Parameters" registry. 4347 Name: ietf-dots-signal-channel 4348 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4349 Maintained by IANA: N 4350 Prefix: signal 4351 Reference: RFC XXXX 4353 Name: iana-dots-signal-channel 4354 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4355 Maintained by IANA: Y 4356 Prefix: iana-signal 4357 Reference: RFC XXXX 4359 This document defines the initial version of the IANA-maintained 4360 iana-dots-signal-channel YANG module. IANA is requested to add this 4361 note: 4363 Status, conflict status, conflict cause, and attack status values 4364 must not be directly added to the iana-dots-signal-channel YANG 4365 module. They must instead be respectively added to the "DOTS 4366 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4367 Codes", and "DOTS Attack Status Codes" registries. 4369 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4370 status' value is respectively added to the "DOTS Status Codes", "DOTS 4371 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4372 Status Codes" registry, a new "enum" statement must be added to the 4373 iana-dots-signal-channel YANG module. The following "enum" 4374 statement, and substatements thereof, should be defined: 4376 "enum": Replicates the label from the registry. 4378 "value": Contains the IANA-assigned value corresponding to the 4379 'status', 'conflict-status', 'conflict-cause', or 4380 'attack-status'. 4382 "description": Replicates the description from the registry. 4384 "reference": Replicates the reference from the registry and adds 4385 the title of the document. 4387 When the iana-dots-signal-channel YANG module is updated, a new 4388 "revision" statement must be added in front of the existing revision 4389 statements. 4391 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4392 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4393 Status Codes" registries: 4395 When this registry is modified, the YANG module iana-dots-signal- 4396 channel must be updated as defined in [RFCXXXX]. 4398 10. Security Considerations 4400 High-level DOTS security considerations are documented in [RFC8612] 4401 and [I-D.ietf-dots-architecture]. 4403 Authenticated encryption MUST be used for data confidentiality and 4404 message integrity. The interaction between the DOTS agents requires 4405 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4406 (TLS) with a cipher suite offering confidentiality protection, and 4407 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4408 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4409 is specified in Section 7. 4411 If TCP is used between DOTS agents, an attacker may be able to inject 4412 RST packets, bogus application segments, etc., regardless of whether 4413 TLS authentication is used. Because the application data is TLS 4414 protected, this will not result in the application receiving bogus 4415 data, but it will constitute a DoS on the connection. This attack 4416 can be countered by using TCP-AO [RFC5925]. Although not widely 4417 adopted, if TCP-AO is used, then any bogus packets injected by an 4418 attacker will be rejected by the TCP-AO integrity check and therefore 4419 will never reach the TLS layer. 4421 An attack vector that can be achieved if the 'cuid' is guessable is a 4422 misbehaving DOTS client from within the client's domain which uses 4423 the 'cuid' of another DOTS client of the domain to delete or alter 4424 active mitigations. For this attack vector to happen, the 4425 misbehaving client needs to pass the security validation checks by 4426 the DOTS server, and eventually the checks of a client-domain DOTS 4427 gateway. 4429 A similar attack can be achieved by a compromised DOTS client which 4430 can sniff the TLS 1.2 handshake, use the client certificate to 4431 identify the 'cuid' used by another DOTS client. This attack is not 4432 possible if algorithms such as version 4 Universally Unique 4433 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4434 the 'cuid' because such UUIDs are not a deterministic function of the 4435 client certificate. Likewise, this attack is not possible with TLS 4436 1.3 because most of the TLS handshake is encrypted and the client 4437 certificate is not visible to eavesdroppers. 4439 A compromised DOTS client can collude with a DDoS attacker to send 4440 mitigation request for a target resource, gets the mitigation 4441 efficacy from the DOTS server, and conveys the mitigation efficacy to 4442 the DDoS attacker to possibly change the DDoS attack strategy. 4443 Obviously, signaling an attack by the compromised DOTS client to the 4444 DOTS server will trigger attack mitigation. This attack can be 4445 prevented by monitoring and auditing DOTS clients to detect 4446 misbehavior and to deter misuse, and by only authorizing the DOTS 4447 client to request mitigation for specific target resources (e.g., an 4448 application server is authorized to request mitigation for its IP 4449 addresses but a DDoS mitigator can request mitigation for any target 4450 resource in the network). Furthermore, DOTS clients are typically 4451 co-located on network security services (e.g., firewall) and a 4452 compromised security service potentially can do a lot more damage to 4453 the network. 4455 Rate-limiting DOTS requests, including those with new 'cuid' values, 4456 from the same DOTS client defends against DoS attacks that would 4457 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4458 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4459 DOTS servers. 4461 In order to prevent leaking internal information outside a client- 4462 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4463 the identification information that pertains to internal DOTS clients 4464 (e.g., source IP address, client's hostname) unless explicitly 4465 configured to do so. 4467 DOTS servers MUST verify that requesting DOTS clients are entitled to 4468 trigger actions on a given IP prefix. That is, only actions on IP 4469 resources that belong to the DOTS client' domain MUST be authorized 4470 by a DOTS server. The exact mechanism for the DOTS servers to 4471 validate that the target prefixes are within the scope of the DOTS 4472 client domain is deployment-specific. 4474 The presence of DOTS gateways may lead to infinite forwarding loops, 4475 which is undesirable. To prevent and detect such loops, this 4476 document uses the Hop-Limit Option. 4478 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4479 privacy enabling protocols (e.g., DNS over TLS [RFC7858] or DoH 4480 [RFC8484]) to prevent eavesdroppers from possibly identifying the 4481 target resources protected by the DDoS mitigation service, and means 4482 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 4483 [RFC4034]). 4485 CoAP-specific security considerations are discussed in Section 11 of 4486 [RFC7252], while CBOR-related security considerations are discussed 4487 in Section 8 of [RFC7049]. 4489 11. Contributors 4491 The following individuals have contributed to this document: 4493 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4495 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4496 mgeller@cisco.com 4498 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4499 Email: rgm@htt-consult.com 4501 o Dan Wing, Email: dwing-ietf@fuggles.com 4503 12. Acknowledgements 4505 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 4506 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 4507 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 4508 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 4509 and comments. 4511 The authors would like to give special thanks to Kaname Nishizuka and 4512 Jon Shallow for their efforts in implementing the protocol and 4513 performing interop testing at IETF Hackathons. 4515 Thanks to the core WG for the recommendations on Hop-Limit and 4516 redirect signaling. 4518 Special thanks to Benjamin Kaduk for the detailed AD review. 4520 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 4521 Kuehlewind, and Alissa Cooper for the review. 4523 Thanks to Carsten Bormann for his review of the DOTS heartbeat 4524 mechanism. 4526 13. References 4528 13.1. Normative References 4530 [I-D.ietf-core-hop-limit] 4531 Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 4532 Application Protocol (CoAP) Hop-Limit Option", draft-ietf- 4533 core-hop-limit-07 (work in progress), October 2019. 4535 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4536 DOI 10.17487/RFC0791, September 1981, 4537 . 4539 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4540 Communication Layers", STD 3, RFC 1122, 4541 DOI 10.17487/RFC1122, October 1989, 4542 . 4544 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4545 Requirement Levels", BCP 14, RFC 2119, 4546 DOI 10.17487/RFC2119, March 1997, 4547 . 4549 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4550 DOI 10.17487/RFC3688, January 2004, 4551 . 4553 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4554 Resource Identifier (URI): Generic Syntax", STD 66, 4555 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4556 . 4558 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4559 Ciphersuites for Transport Layer Security (TLS)", 4560 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4561 . 4563 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4564 (CIDR): The Internet Address Assignment and Aggregation 4565 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4566 2006, . 4568 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4569 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4570 . 4572 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4573 (TLS) Protocol Version 1.2", RFC 5246, 4574 DOI 10.17487/RFC5246, August 2008, 4575 . 4577 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4578 Housley, R., and W. Polk, "Internet X.509 Public Key 4579 Infrastructure Certificate and Certificate Revocation List 4580 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4581 . 4583 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4584 Extensions: Extension Definitions", RFC 6066, 4585 DOI 10.17487/RFC6066, January 2011, 4586 . 4588 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4589 Verification of Domain-Based Application Service Identity 4590 within Internet Public Key Infrastructure Using X.509 4591 (PKIX) Certificates in the Context of Transport Layer 4592 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4593 2011, . 4595 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4596 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4597 January 2012, . 4599 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4600 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4601 . 4603 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4604 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4605 October 2013, . 4607 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4608 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4609 Transport Layer Security (TLS) and Datagram Transport 4610 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4611 June 2014, . 4613 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4614 Application Protocol (CoAP)", RFC 7252, 4615 DOI 10.17487/RFC7252, June 2014, 4616 . 4618 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4619 "Recommendations for Secure Use of Transport Layer 4620 Security (TLS) and Datagram Transport Layer Security 4621 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4622 2015, . 4624 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4625 Application Protocol (CoAP)", RFC 7641, 4626 DOI 10.17487/RFC7641, September 2015, 4627 . 4629 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4630 Layer Security (TLS) False Start", RFC 7918, 4631 DOI 10.17487/RFC7918, August 2016, 4632 . 4634 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4635 (TLS) Cached Information Extension", RFC 7924, 4636 DOI 10.17487/RFC7924, July 2016, 4637 . 4639 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4640 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4641 . 4643 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4644 the Constrained Application Protocol (CoAP)", RFC 7959, 4645 DOI 10.17487/RFC7959, August 2016, 4646 . 4648 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4649 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4650 March 2017, . 4652 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4653 Writing an IANA Considerations Section in RFCs", BCP 26, 4654 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4655 . 4657 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4658 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4659 May 2017, . 4661 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4662 (IPv6) Specification", STD 86, RFC 8200, 4663 DOI 10.17487/RFC8200, July 2017, 4664 . 4666 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4667 Better Connectivity Using Concurrency", RFC 8305, 4668 DOI 10.17487/RFC8305, December 2017, 4669 . 4671 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4672 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4673 Application Protocol) over TCP, TLS, and WebSockets", 4674 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4675 . 4677 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4678 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4679 . 4681 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 4682 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 4683 . 4685 13.2. Informative References 4687 [I-D.boucadair-dots-earlydata] 4688 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4689 boucadair-dots-earlydata-00 (work in progress), January 4690 2019. 4692 [I-D.ietf-core-comi] 4693 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 4694 Petrov, "CoAP Management Interface", draft-ietf-core- 4695 comi-08 (work in progress), September 2019. 4697 [I-D.ietf-core-yang-cbor] 4698 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 4699 Data Modeled with YANG", draft-ietf-core-yang-cbor-11 4700 (work in progress), September 2019. 4702 [I-D.ietf-dots-architecture] 4703 Mortensen, A., Reddy.K, T., Andreasen, F., Teague, N., and 4704 R. Compton, "Distributed-Denial-of-Service Open Threat 4705 Signaling (DOTS) Architecture", draft-ietf-dots- 4706 architecture-14 (work in progress), May 2019. 4708 [I-D.ietf-dots-data-channel] 4709 Boucadair, M. and T. Reddy.K, "Distributed Denial-of- 4710 Service Open Threat Signaling (DOTS) Data Channel 4711 Specification", draft-ietf-dots-data-channel-31 (work in 4712 progress), July 2019. 4714 [I-D.ietf-dots-multihoming] 4715 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 4716 Deployment Considerations for Distributed-Denial-of- 4717 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 4718 multihoming-02 (work in progress), July 2019. 4720 [I-D.ietf-dots-server-discovery] 4721 Boucadair, M. and T. Reddy.K, "Distributed-Denial-of- 4722 Service Open Threat Signaling (DOTS) Agent Discovery", 4723 draft-ietf-dots-server-discovery-06 (work in progress), 4724 November 2019. 4726 [I-D.ietf-dots-use-cases] 4727 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 4728 L., and K. Nishizuka, "Use cases for DDoS Open Threat 4729 Signaling", draft-ietf-dots-use-cases-20 (work in 4730 progress), September 2019. 4732 [I-D.ietf-tls-dtls13] 4733 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4734 Datagram Transport Layer Security (DTLS) Protocol Version 4735 1.3", draft-ietf-tls-dtls13-34 (work in progress), 4736 November 2019. 4738 [IANA.CBOR.Tags] 4739 IANA, "Concise Binary Object Representation (CBOR) Tags", 4740 . 4743 [IANA.CoAP.Content-Formats] 4744 IANA, "CoAP Content-Formats", 4745 . 4748 [IANA.MediaTypes] 4749 IANA, "Media Types", 4750 . 4752 [proto_numbers] 4753 "IANA, "Protocol Numbers"", 2011, 4754 . 4756 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4757 Address Translator (Traditional NAT)", RFC 3022, 4758 DOI 10.17487/RFC3022, January 2001, 4759 . 4761 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 4762 Rose, "Resource Records for the DNS Security Extensions", 4763 RFC 4034, DOI 10.17487/RFC4034, March 2005, 4764 . 4766 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4767 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4768 DOI 10.17487/RFC4122, July 2005, 4769 . 4771 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4772 Congestion Control Protocol (DCCP)", RFC 4340, 4773 DOI 10.17487/RFC4340, March 2006, 4774 . 4776 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4777 Denial-of-Service Considerations", RFC 4732, 4778 DOI 10.17487/RFC4732, December 2006, 4779 . 4781 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4782 Translation (NAT) Behavioral Requirements for Unicast 4783 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4784 2007, . 4786 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4787 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4788 . 4790 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4791 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4792 . 4794 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4795 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4796 DOI 10.17487/RFC5389, October 2008, 4797 . 4799 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4800 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4801 June 2010, . 4803 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4804 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4805 DOI 10.17487/RFC6052, October 2010, 4806 . 4808 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4809 NAT64: Network Address and Protocol Translation from IPv6 4810 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4811 April 2011, . 4813 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4814 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4815 DOI 10.17487/RFC6234, May 2011, 4816 . 4818 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4819 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4820 . 4822 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4823 "Default Address Selection for Internet Protocol Version 6 4824 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4825 . 4827 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4828 Specifications and Registration Procedures", BCP 13, 4829 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4830 . 4832 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4833 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4834 DOI 10.17487/RFC6887, April 2013, 4835 . 4837 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4838 A., and H. Ashida, "Common Requirements for Carrier-Grade 4839 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4840 April 2013, . 4842 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4843 "Enrollment over Secure Transport", RFC 7030, 4844 DOI 10.17487/RFC7030, October 2013, 4845 . 4847 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4848 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4849 . 4851 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4852 "Architectural Considerations in Smart Object Networking", 4853 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4854 . 4856 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4857 NETCONF Protocol over Transport Layer Security (TLS) with 4858 Mutual X.509 Authentication", RFC 7589, 4859 DOI 10.17487/RFC7589, June 2015, 4860 . 4862 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 4863 and P. Hoffman, "Specification for DNS over Transport 4864 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 4865 2016, . 4867 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4868 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4869 . 4871 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4872 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4873 . 4875 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 4876 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 4877 . 4879 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4880 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4881 January 2019, . 4883 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4884 Threat Signaling (DOTS) Requirements", RFC 8612, 4885 DOI 10.17487/RFC8612, May 2019, 4886 . 4888 Appendix A. CUID Generation 4890 The document recommends the use of SPKI to generate the 'cuid'. This 4891 design choice is motivated by the following reasons: 4893 o SPKI is globally unique. 4895 o It is deterministic. 4897 o It allows to avoid extra cycles that may be induced by 'cuid' 4898 collision. 4900 o DOTS clients do not need to store the 'cuid' in a persistent 4901 storage. 4903 o It allows to detect compromised DOTS clients that do not adhere to 4904 the 'cuid' generation algorithm. 4906 Authors' Addresses 4908 Tirumaleswar Reddy (editor) 4909 McAfee, Inc. 4910 Embassy Golf Link Business Park 4911 Bangalore, Karnataka 560071 4912 India 4914 Email: kondtir@gmail.com 4916 Mohamed Boucadair (editor) 4917 Orange 4918 Rennes 35000 4919 France 4921 Email: mohamed.boucadair@orange.com 4922 Prashanth Patil 4923 Cisco Systems, Inc. 4925 Email: praspati@cisco.com 4927 Andrew Mortensen 4928 Arbor Networks, Inc. 4929 2727 S. State St 4930 Ann Arbor, MI 48104 4931 United States 4933 Email: andrew@moretension.com 4935 Nik Teague 4936 Iron Mountain Data Centers 4937 United Kingdom 4939 Email: nteague@ironmountain.co.uk