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