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