idnits 2.17.1 draft-ietf-dots-signal-channel-36.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 2627 has weird spacing: '...er-port ine...' -- The document date (July 23, 2019) is 1738 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 4265, but not defined == Outdated reference: A later version (-07) exists of draft-ietf-core-hop-limit-04 ** 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-07 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-10 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-14 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-30 == 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-04 == Outdated reference: A later version (-25) exists of draft-ietf-dots-use-cases-18 == 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 (~~), 12 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: January 24, 2020 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Iron Mountain Data Centers 12 July 23, 2019 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-36 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 January 24, 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 MAY 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, then the DOTS server sends heartbeat requests to the DOTS 2576 client and after maximum 'missing-hb-allowed' threshold is reached, 2577 the DOTS server concludes the session is disconnected. The DOTS 2578 server can then trigger pre-configured mitigation requests for this 2579 DOTS client (if any). 2581 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2582 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2583 [RFC7252]. 2585 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2586 DOTS agents using the Ping and Pong messages specified in Section 5.4 2587 of [RFC8323]. That is, the DOTS agent sends a Ping message and the 2588 peer DOTS agent would respond by sending a single Pong message. The 2589 sender of a Ping message has to allow up to 'heartbeat-interval' 2590 seconds when waiting for a Pong reply. When a failure is detected by 2591 a DOTS client, it proceeds with the session recovery following the 2592 same approach as the one used for unreliable transports. 2594 5. DOTS Signal Channel YANG Modules 2596 This document defines a YANG [RFC7950] module for DOTS mitigation 2597 scope, DOTS signal channel session configuration data, and DOTS 2598 redirection signaling. 2600 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2601 interaction with the DOTS server as seen by the DOTS client. A DOTS 2602 server is allowed to update the non-configurable 'ro' entities in the 2603 responses. This YANG module is not intended to be used via NETCONF/ 2604 RESTCONF for DOTS server management purposes; such module is out of 2605 the scope of this document. It serves only to provide a data model 2606 and encoding, but not a management data model. 2608 A companion YANG module is defined to include a collection of types 2609 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2611 5.1. Tree Structure 2613 This document defines the YANG module "ietf-dots-signal-channel" 2614 (Section 5.3), which has the following tree structure. A DOTS signal 2615 message can be a mitigation, a configuration, or a redirect message. 2617 module: ietf-dots-signal-channel 2618 +--rw dots-signal 2619 +--rw (message-type)? 2620 +--:(mitigation-scope) 2621 | +--rw scope* [cuid mid] 2622 | +--rw cdid? string 2623 | +--rw cuid string 2624 | +--rw mid uint32 2625 | +--rw target-prefix* inet:ip-prefix 2626 | +--rw target-port-range* [lower-port] 2627 | | +--rw lower-port inet:port-number 2628 | | +--rw upper-port? inet:port-number 2629 | +--rw target-protocol* uint8 2630 | +--rw target-fqdn* inet:domain-name 2631 | +--rw target-uri* inet:uri 2632 | +--rw alias-name* string 2633 | +--rw lifetime? int32 2634 | +--rw trigger-mitigation? boolean 2635 | +--ro mitigation-start? uint64 2636 | +--ro status? iana-signal:status 2637 | +--ro conflict-information 2638 | | +--ro conflict-status? iana-signal:conflict-status 2639 | | +--ro conflict-cause? iana-signal:conflict-cause 2640 | | +--ro retry-timer? uint32 2641 | | +--ro conflict-scope 2642 | | +--ro target-prefix* inet:ip-prefix 2643 | | +--ro target-port-range* [lower-port] 2644 | | | +--ro lower-port inet:port-number 2645 | | | +--ro upper-port? inet:port-number 2646 | | +--ro target-protocol* uint8 2647 | | +--ro target-fqdn* inet:domain-name 2648 | | +--ro target-uri* inet:uri 2649 | | +--ro alias-name* string 2650 | | +--ro acl-list* [acl-name] 2651 | | | +--ro acl-name 2652 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2653 | | | | acl/name 2654 | | | +--ro acl-type? 2655 | | | -> /ietf-data:dots-data/dots-client/acls/ 2656 | | | acl/type 2657 | | +--ro mid? -> ../../../mid 2658 | +--ro bytes-dropped? yang:zero-based-counter64 2659 | +--ro bps-dropped? yang:gauge64 2660 | +--ro pkts-dropped? yang:zero-based-counter64 2661 | +--ro pps-dropped? yang:gauge64 2662 | +--rw attack-status? iana-signal:attack-status 2663 +--:(signal-config) 2664 | +--rw sid uint32 2665 | +--rw mitigating-config 2666 | | +--rw heartbeat-interval 2667 | | | +--ro max-value? uint16 2668 | | | +--ro min-value? uint16 2669 | | | +--rw current-value? uint16 2670 | | +--rw missing-hb-allowed 2671 | | | +--ro max-value? uint16 2672 | | | +--ro min-value? uint16 2673 | | | +--rw current-value? uint16 2674 | | +--rw max-retransmit 2675 | | | +--ro max-value? uint16 2676 | | | +--ro min-value? uint16 2677 | | | +--rw current-value? uint16 2678 | | +--rw ack-timeout 2679 | | | +--ro max-value-decimal? decimal64 2680 | | | +--ro min-value-decimal? decimal64 2681 | | | +--rw current-value-decimal? decimal64 2682 | | +--rw ack-random-factor 2683 | | +--ro max-value-decimal? decimal64 2684 | | +--ro min-value-decimal? decimal64 2685 | | +--rw current-value-decimal? decimal64 2686 | +--rw idle-config 2687 | +--rw heartbeat-interval 2688 | | +--ro max-value? uint16 2689 | | +--ro min-value? uint16 2690 | | +--rw current-value? uint16 2691 | +--rw missing-hb-allowed 2692 | | +--ro max-value? uint16 2693 | | +--ro min-value? uint16 2694 | | +--rw current-value? uint16 2695 | +--rw max-retransmit 2696 | | +--ro max-value? uint16 2697 | | +--ro min-value? uint16 2698 | | +--rw current-value? uint16 2699 | +--rw ack-timeout 2700 | | +--ro max-value-decimal? decimal64 2701 | | +--ro min-value-decimal? decimal64 2702 | | +--rw current-value-decimal? decimal64 2703 | +--rw ack-random-factor 2704 | +--ro max-value-decimal? decimal64 2705 | +--ro min-value-decimal? decimal64 2706 | +--rw current-value-decimal? decimal64 2707 +--:(redirected-signal) 2708 +--ro alt-server string 2709 +--ro alt-server-record* inet:ip-address 2711 5.2. IANA DOTS Signal Channel YANG Module 2713 file "iana-dots-signal-channel@2019-01-17.yang" 2714 module iana-dots-signal-channel { 2715 yang-version 1.1; 2716 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2717 prefix iana-signal; 2719 organization 2720 "IANA"; 2721 contact 2722 "Internet Assigned Numbers Authority 2724 Postal: ICANN 2725 12025 Waterfront Drive, Suite 300 2726 Los Angeles, CA 90094-2536 2727 United States of America 2728 Tel: +1 310 301 5800 2729 "; 2730 description 2731 "This module contains a collection of YANG data types defined 2732 by IANA and used for DOTS signal channel protocol. 2734 Copyright (c) 2019 IETF Trust and the persons identified as 2735 authors of the code. All rights reserved. 2737 Redistribution and use in source and binary forms, with or 2738 without modification, is permitted pursuant to, and subject 2739 to the license terms contained in, the Simplified BSD License 2740 set forth in Section 4.c of the IETF Trust's Legal Provisions 2741 Relating to IETF Documents 2742 (http://trustee.ietf.org/license-info). 2744 This version of this YANG module is part of RFC XXXX; see 2745 the RFC itself for full legal notices."; 2747 revision 2019-01-17 { 2748 description 2749 "Initial revision."; 2750 reference 2751 "RFC XXXX: Distributed Denial-of-Service Open Threat 2752 Signaling (DOTS) Signal Channel Specification"; 2753 } 2755 typedef status { 2756 type enumeration { 2757 enum attack-mitigation-in-progress { 2758 value 1; 2759 description 2760 "Attack mitigation setup is in progress (e.g., changing 2761 the network path to re-route the inbound traffic 2762 to DOTS mitigator)."; 2763 } 2764 enum attack-successfully-mitigated { 2765 value 2; 2766 description 2767 "Attack is being successfully mitigated (e.g., traffic 2768 is redirected to a DDoS mitigator and attack 2769 traffic is dropped or blackholed)."; 2770 } 2771 enum attack-stopped { 2772 value 3; 2773 description 2774 "Attack has stopped and the DOTS client can 2775 withdraw the mitigation request."; 2776 } 2777 enum attack-exceeded-capability { 2778 value 4; 2779 description 2780 "Attack has exceeded the mitigation provider 2781 capability."; 2782 } 2783 enum dots-client-withdrawn-mitigation { 2784 value 5; 2785 description 2786 "DOTS client has withdrawn the mitigation 2787 request and the mitigation is active but 2788 terminating."; 2789 } 2790 enum attack-mitigation-terminated { 2791 value 6; 2792 description 2793 "Attack mitigation is now terminated."; 2794 } 2795 enum attack-mitigation-withdrawn { 2796 value 7; 2797 description 2798 "Attack mitigation is withdrawn."; 2799 } 2800 enum attack-mitigation-signal-loss { 2801 value 8; 2802 description 2803 "Attack mitigation will be triggered 2804 for the mitigation request only when 2805 the DOTS signal channel session is lost."; 2806 } 2807 } 2808 description 2809 "Enumeration for status reported by the DOTS server."; 2810 } 2812 typedef conflict-status { 2813 type enumeration { 2814 enum request-inactive-other-active { 2815 value 1; 2816 description 2817 "DOTS Server has detected conflicting mitigation 2818 requests from different DOTS clients. 2819 This mitigation request is currently inactive 2820 until the conflicts are resolved. Another 2821 mitigation request is active."; 2822 } 2823 enum request-active { 2824 value 2; 2825 description 2826 "DOTS Server has detected conflicting mitigation 2827 requests from different DOTS clients. 2828 This mitigation request is currently active."; 2829 } 2830 enum all-requests-inactive { 2831 value 3; 2832 description 2833 "DOTS Server has detected conflicting mitigation 2834 requests from different DOTS clients. All 2835 conflicting mitigation requests are inactive."; 2836 } 2837 } 2838 description 2839 "Enumeration for conflict status."; 2840 } 2842 typedef conflict-cause { 2843 type enumeration { 2844 enum overlapping-targets { 2845 value 1; 2846 description 2847 "Overlapping targets. conflict-scope provides 2848 more details about the exact conflict."; 2849 } 2850 enum conflict-with-acceptlist { 2851 value 2; 2852 description 2853 "Conflicts with an existing accept-list. 2855 This code is returned when the DDoS mitigation 2856 detects that some of the source addresses/prefixes 2857 listed in the accept-list ACLs are actually 2858 attacking the target."; 2859 } 2860 enum cuid-collision { 2861 value 3; 2862 description 2863 "Conflicts with the cuid used by another 2864 DOTS client."; 2865 } 2866 } 2867 description 2868 "Enumeration for conflict causes."; 2869 } 2871 typedef attack-status { 2872 type enumeration { 2873 enum under-attack { 2874 value 1; 2875 description 2876 "The DOTS client determines that it is still under 2877 attack."; 2878 } 2879 enum attack-successfully-mitigated { 2880 value 2; 2881 description 2882 "The DOTS client determines that the attack is 2883 successfully mitigated."; 2884 } 2885 } 2886 description 2887 "Enumeration for attack status codes."; 2888 } 2889 } 2890 2892 5.3. IETF DOTS Signal Channel YANG Module 2894 This module uses the common YANG types defined in [RFC6991] and types 2895 defined in [I-D.ietf-dots-data-channel]. 2897 file "ietf-dots-signal-channel@2019-01-17.yang" 2898 module ietf-dots-signal-channel { 2899 yang-version 1.1; 2900 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2901 prefix signal; 2903 import ietf-inet-types { 2904 prefix inet; 2905 reference "Section 4 of RFC 6991"; 2906 } 2907 import ietf-yang-types { 2908 prefix yang; 2909 reference "Section 3 of RFC 6991"; 2910 } 2911 import ietf-dots-data-channel { 2912 prefix ietf-data; 2913 reference 2914 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2915 (DOTS) Data Channel Specification"; 2916 } 2917 import iana-dots-signal-channel { 2918 prefix iana-signal; 2919 } 2921 organization 2922 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2923 contact 2924 "WG Web: 2925 WG List: 2927 Editor: Konda, Tirumaleswar Reddy 2928 2930 Editor: Mohamed Boucadair 2931 2933 Author: Prashanth Patil 2934 2936 Author: Andrew Mortensen 2937 2939 Author: Nik Teague 2940 "; 2941 description 2942 "This module contains YANG definition for the signaling 2943 messages exchanged between a DOTS client and a DOTS server. 2945 Copyright (c) 2019 IETF Trust and the persons identified as 2946 authors of the code. All rights reserved. 2948 Redistribution and use in source and binary forms, with or 2949 without modification, is permitted pursuant to, and subject 2950 to the license terms contained in, the Simplified BSD License 2951 set forth in Section 4.c of the IETF Trust's Legal Provisions 2952 Relating to IETF Documents 2953 (http://trustee.ietf.org/license-info). 2955 This version of this YANG module is part of RFC XXXX; see 2956 the RFC itself for full legal notices."; 2958 revision 2019-01-17 { 2959 description 2960 "Initial revision."; 2961 reference 2962 "RFC XXXX: Distributed Denial-of-Service Open Threat 2963 Signaling (DOTS) Signal Channel Specification"; 2964 } 2966 /* 2967 * Groupings 2968 */ 2970 grouping mitigation-scope { 2971 description 2972 "Specifies the scope of the mitigation request."; 2973 list scope { 2974 key "cuid mid"; 2975 description 2976 "The scope of the request."; 2977 leaf cdid { 2978 type string; 2979 description 2980 "The cdid should be included by a server-domain 2981 DOTS gateway to propagate the client domain 2982 identification information from the 2983 gateway's client-facing-side to the gateway's 2984 server-facing-side, and from the gateway's 2985 server-facing-side to the DOTS server. 2987 It may be used by the final DOTS server 2988 for policy enforcement purposes."; 2989 } 2990 leaf cuid { 2991 type string; 2992 description 2993 "A unique identifier that is 2994 generated by a DOTS client to prevent 2995 request collisions. It is expected that the 2996 cuid will remain consistent throughout the 2997 lifetime of the DOTS client."; 2998 } 2999 leaf mid { 3000 type uint32; 3001 description 3002 "Mitigation request identifier. 3004 This identifier must be unique for each mitigation 3005 request bound to the DOTS client."; 3006 } 3007 uses ietf-data:target; 3008 leaf-list alias-name { 3009 type string; 3010 description 3011 "An alias name that points to a resource."; 3012 } 3013 leaf lifetime { 3014 type int32; 3015 units "seconds"; 3016 default "3600"; 3017 description 3018 "Indicates the lifetime of the mitigation request. 3020 A lifetime of '0' in a mitigation request is an 3021 invalid value. 3023 A lifetime of negative one (-1) indicates indefinite 3024 lifetime for the mitigation request."; 3025 } 3026 leaf trigger-mitigation { 3027 type boolean; 3028 default "true"; 3029 description 3030 "If set to 'false', DDoS mitigation will not be 3031 triggered unless the DOTS signal channel 3032 session is lost."; 3033 } 3034 leaf mitigation-start { 3035 type uint64; 3036 config false; 3037 description 3038 "Mitigation start time is represented in seconds 3039 relative to 1970-01-01T00:00:00Z in UTC time."; 3040 } 3041 leaf status { 3042 type iana-signal:status; 3043 config false; 3044 description 3045 "Indicates the status of a mitigation request. 3046 It must be included in responses only."; 3047 } 3048 container conflict-information { 3049 config false; 3050 description 3051 "Indicates that a conflict is detected. 3052 Must only be used for responses."; 3053 leaf conflict-status { 3054 type iana-signal:conflict-status; 3055 description 3056 "Indicates the conflict status."; 3057 } 3058 leaf conflict-cause { 3059 type iana-signal:conflict-cause; 3060 description 3061 "Indicates the cause of the conflict."; 3062 } 3063 leaf retry-timer { 3064 type uint32; 3065 units "seconds"; 3066 description 3067 "The DOTS client must not re-send the 3068 same request that has a conflict before the expiry of 3069 this timer."; 3070 } 3071 container conflict-scope { 3072 description 3073 "Provides more information about the conflict scope."; 3074 uses ietf-data:target { 3075 when "../conflict-cause = 'overlapping-targets'"; 3076 } 3077 leaf-list alias-name { 3078 when "../../conflict-cause = 'overlapping-targets'"; 3079 type string; 3080 description 3081 "Conflicting alias-name."; 3082 } 3083 list acl-list { 3084 when "../../conflict-cause = 'conflict-with-acceptlist'"; 3085 key "acl-name"; 3086 description 3087 "List of conflicting ACLs as defined in the DOTS data 3088 channel. These ACLs are uniquely defined by 3089 cuid and acl-name."; 3090 leaf acl-name { 3091 type leafref { 3092 path "/ietf-data:dots-data/ietf-data:dots-client/" 3093 + "ietf-data:acls/ietf-data:acl/ietf-data:name"; 3094 } 3095 description 3096 "Reference to the conflicting ACL name bound to 3097 a DOTS client."; 3098 } 3099 leaf acl-type { 3100 type leafref { 3101 path "/ietf-data:dots-data/ietf-data:dots-client/" 3102 + "ietf-data:acls/ietf-data:acl/ietf-data:type"; 3103 } 3104 description 3105 "Reference to the conflicting ACL type bound to 3106 a DOTS client."; 3107 } 3108 } 3109 leaf mid { 3110 when "../../conflict-cause = 'overlapping-targets'"; 3111 type leafref { 3112 path "../../../mid"; 3113 } 3114 description 3115 "Reference to the conflicting 'mid' bound to 3116 the same DOTS client."; 3117 } 3118 } 3119 } 3120 leaf bytes-dropped { 3121 type yang:zero-based-counter64; 3122 units "bytes"; 3123 config false; 3124 description 3125 "The total dropped byte count for the mitigation 3126 request since the attack mitigation is triggered. 3127 The count wraps around when it reaches the maximum value 3128 of counter64 for dropped bytes."; 3129 } 3130 leaf bps-dropped { 3131 type yang:gauge64; 3132 config false; 3133 description 3134 "The average number of dropped bits per second for 3135 the mitigation request since the attack 3136 mitigation is triggered. This should be over 3137 five-minute intervals (that is, measuring bytes 3138 into five-minute buckets and then averaging these 3139 buckets over the time since the mitigation was 3140 triggered)."; 3141 } 3142 leaf pkts-dropped { 3143 type yang:zero-based-counter64; 3144 config false; 3145 description 3146 "The total number of dropped packet count for the 3147 mitigation request since the attack mitigation is 3148 triggered. The count wraps around when it reaches 3149 the maximum value of counter64 for dropped packets."; 3150 } 3151 leaf pps-dropped { 3152 type yang:gauge64; 3153 config false; 3154 description 3155 "The average number of dropped packets per second 3156 for the mitigation request since the attack 3157 mitigation is triggered. This should be over 3158 five-minute intervals (that is, measuring packets 3159 into five-minute buckets and then averaging these 3160 buckets over the time since the mitigation was 3161 triggered)."; 3162 } 3163 leaf attack-status { 3164 type iana-signal:attack-status; 3165 description 3166 "Indicates the status of an attack as seen by the 3167 DOTS client."; 3168 } 3169 } 3170 } 3172 grouping config-parameters { 3173 description 3174 "Subset of DOTS signal channel session configuration."; 3175 container heartbeat-interval { 3176 description 3177 "DOTS agents regularly send heartbeats to each other 3178 after mutual authentication is successfully 3179 completed in order to keep the DOTS signal channel 3180 open."; 3181 leaf max-value { 3182 type uint16; 3183 units "seconds"; 3184 config false; 3185 description 3186 "Maximum acceptable heartbeat-interval value."; 3187 } 3188 leaf min-value { 3189 type uint16; 3190 units "seconds"; 3191 config false; 3192 description 3193 "Minimum acceptable heartbeat-interval value."; 3194 } 3195 leaf current-value { 3196 type uint16; 3197 units "seconds"; 3198 default "30"; 3199 description 3200 "Current heartbeat-interval value. 3202 '0' means that heartbeat mechanism is deactivated."; 3203 } 3204 } 3205 container missing-hb-allowed { 3206 description 3207 "Maximum number of missing heartbeats allowed."; 3208 leaf max-value { 3209 type uint16; 3210 config false; 3211 description 3212 "Maximum acceptable missing-hb-allowed value."; 3213 } 3214 leaf min-value { 3215 type uint16; 3216 config false; 3217 description 3218 "Minimum acceptable missing-hb-allowed value."; 3219 } 3220 leaf current-value { 3221 type uint16; 3222 default "5"; 3223 description 3224 "Current missing-hb-allowed value."; 3225 } 3226 } 3227 container max-retransmit { 3228 description 3229 "Maximum number of retransmissions of a Confirmable 3230 message."; 3231 leaf max-value { 3232 type uint16; 3233 config false; 3234 description 3235 "Maximum acceptable max-retransmit value."; 3236 } 3237 leaf min-value { 3238 type uint16; 3239 config false; 3240 description 3241 "Minimum acceptable max-retransmit value."; 3242 } 3243 leaf current-value { 3244 type uint16; 3245 default "3"; 3246 description 3247 "Current max-retransmit value."; 3248 } 3249 } 3250 container ack-timeout { 3251 description 3252 "Initial retransmission timeout value."; 3253 leaf max-value-decimal { 3254 type decimal64 { 3255 fraction-digits 2; 3256 } 3257 units "seconds"; 3258 config false; 3259 description 3260 "Maximum ack-timeout value."; 3261 } 3262 leaf min-value-decimal { 3263 type decimal64 { 3264 fraction-digits 2; 3265 } 3266 units "seconds"; 3267 config false; 3268 description 3269 "Minimum ack-timeout value."; 3270 } 3271 leaf current-value-decimal { 3272 type decimal64 { 3273 fraction-digits 2; 3274 } 3275 units "seconds"; 3276 default "2"; 3277 description 3278 "Current ack-timeout value."; 3279 } 3280 } 3281 container ack-random-factor { 3282 description 3283 "Random factor used to influence the timing of 3284 retransmissions."; 3285 leaf max-value-decimal { 3286 type decimal64 { 3287 fraction-digits 2; 3288 } 3289 config false; 3290 description 3291 "Maximum acceptable ack-random-factor value."; 3292 } 3293 leaf min-value-decimal { 3294 type decimal64 { 3295 fraction-digits 2; 3296 } 3297 config false; 3298 description 3299 "Minimum acceptable ack-random-factor value."; 3300 } 3301 leaf current-value-decimal { 3302 type decimal64 { 3303 fraction-digits 2; 3304 } 3305 default "1.5"; 3306 description 3307 "Current ack-random-factor value."; 3308 } 3309 } 3310 } 3312 grouping signal-config { 3313 description 3314 "DOTS signal channel session configuration."; 3315 leaf sid { 3316 type uint32; 3317 mandatory true; 3318 description 3319 "An identifier for the DOTS signal channel 3320 session configuration data."; 3321 } 3322 container mitigating-config { 3323 description 3324 "Configuration parameters to use when a mitigation 3325 is active."; 3326 uses config-parameters; 3327 } 3328 container idle-config { 3329 description 3330 "Configuration parameters to use when no mitigation 3331 is active."; 3332 uses config-parameters; 3333 } 3334 } 3336 grouping redirected-signal { 3337 description 3338 "Grouping for the redirected signaling."; 3339 leaf alt-server { 3340 type string; 3341 config false; 3342 mandatory true; 3343 description 3344 "FQDN of an alternate server."; 3345 } 3346 leaf-list alt-server-record { 3347 type inet:ip-address; 3348 config false; 3349 description 3350 "List of records for the alternate server."; 3351 } 3352 } 3354 /* 3355 * Main Container for DOTS Signal Channel 3356 */ 3358 container dots-signal { 3359 description 3360 "Main container for DOTS signal message. 3362 A DOTS signal message can be a mitigation, a configuration, 3363 or a redirected signal message."; 3364 choice message-type { 3365 description 3366 "Can be a mitigation, a configuration, or a redirect 3367 message."; 3368 case mitigation-scope { 3369 description 3370 "Mitigation scope of a mitigation message."; 3371 uses mitigation-scope; 3373 } 3374 case signal-config { 3375 description 3376 "Configuration message."; 3377 uses signal-config; 3378 } 3379 case redirected-signal { 3380 description 3381 "Redirected signaling."; 3382 uses redirected-signal; 3383 } 3384 } 3385 } 3386 } 3387 3389 6. YANG/JSON Mapping Parameters to CBOR 3391 All parameters in the payload of the DOTS signal channel MUST be 3392 mapped to CBOR types as shown in Table 4 and are assigned an integer 3393 key to save space. 3395 o Note: Implementers must check that the mapping output provided by 3396 their YANG-to-CBOR encoding schemes is aligned with the content of 3397 Table 4. For example, some CBOR and JSON types for enumerations 3398 and the 64-bit quantities can differ depending on the encoder 3399 used. 3401 The CBOR key values are divided into two types: comprehension- 3402 required and comprehension-optional. DOTS agents can safely ignore 3403 comprehension-optional values they don't understand, but cannot 3404 successfully process a request if it contains comprehension-required 3405 values that are not understood. The 4.00 response SHOULD include a 3406 diagnostic payload describing the unknown comprehension-required CBOR 3407 key values. The initial set of CBOR key values defined in this 3408 specification are of type comprehension-required. 3410 +----------------------+-------------+-----+---------------+--------+ 3411 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3412 | | Type | Key | Type & | Type | 3413 | | | | Information | | 3414 +----------------------+-------------+-----+---------------+--------+ 3415 | ietf-dots-signal-cha | | | | | 3416 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3417 | scope | list | 2 | 4 array | Array | 3418 | cdid | string | 3 | 3 text string | String | 3419 | cuid | string | 4 | 3 text string | String | 3420 | mid | uint32 | 5 | 0 unsigned | Number | 3421 | target-prefix | leaf-list | 6 | 4 array | Array | 3422 | | inet: | | | | 3423 | | ip-prefix | | 3 text string | String | 3424 | target-port-range | list | 7 | 4 array | Array | 3425 | lower-port | inet: | | | | 3426 | | port-number| 8 | 0 unsigned | Number | 3427 | upper-port | inet: | | | | 3428 | | port-number| 9 | 0 unsigned | Number | 3429 | target-protocol | leaf-list | 10 | 4 array | Array | 3430 | | uint8 | | 0 unsigned | Number | 3431 | target-fqdn | leaf-list | 11 | 4 array | Array | 3432 | | inet: | | | | 3433 | | domain-name| | 3 text string | String | 3434 | target-uri | leaf-list | 12 | 4 array | Array | 3435 | | inet:uri | | 3 text string | String | 3436 | alias-name | leaf-list | 13 | 4 array | Array | 3437 | | string | | 3 text string | String | 3438 | lifetime | int32 | 14 | 0 unsigned | Number | 3439 | | | | 1 negative | Number | 3440 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3441 | status | enumeration | 16 | 0 unsigned | String | 3442 | conflict-information | container | 17 | 5 map | Object | 3443 | conflict-status | enumeration | 18 | 0 unsigned | String | 3444 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3445 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3446 | conflict-scope | container | 21 | 5 map | Object | 3447 | acl-list | list | 22 | 4 array | Array | 3448 | acl-name | leafref | 23 | 3 text string | String | 3449 | acl-type | leafref | 24 | 3 text string | String | 3450 | bytes-dropped | yang:zero- | | | | 3451 | | based- | | | | 3452 | | counter64 | 25 | 0 unsigned | String | 3453 | bps-dropped | yang:gauge64| 26 | 0 unsigned | String | 3454 | pkts-dropped | yang:zero- | | | | 3455 | | based- | | | | 3456 | | counter64 | 27 | 0 unsigned | String | 3457 | pps-dropped | yang:gauge64| 28 | 0 unsigned | String | 3458 | attack-status | enumeration | 29 | 0 unsigned | String | 3459 | ietf-dots-signal- | | | | | 3460 | channel:signal-config| container | 30 | 5 map | Object | 3461 | sid | uint32 | 31 | 0 unsigned | Number | 3462 | mitigating-config | container | 32 | 5 map | Object | 3463 | heartbeat-interval | container | 33 | 5 map | Object | 3464 | max-value | uint16 | 34 | 0 unsigned | Number | 3465 | min-value | uint16 | 35 | 0 unsigned | Number | 3466 | current-value | uint16 | 36 | 0 unsigned | Number | 3467 | missing-hb-allowed | container | 37 | 5 map | Object | 3468 | max-retransmit | container | 38 | 5 map | Object | 3469 | ack-timeout | container | 39 | 5 map | Object | 3470 | ack-random-factor | container | 40 | 5 map | Object | 3471 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3472 | | | | [-2, integer]| String | 3473 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3474 | | | | [-2, integer]| String | 3475 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3476 | | | | [-2, integer]| String | 3477 | idle-config | container | 44 | 5 map | Object | 3478 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3479 | | | | 7 bits 21 | True | 3480 | ietf-dots-signal-cha | | | | | 3481 |nnel:redirected-signal| container | 46 | 5 map | Object | 3482 | alt-server | string | 47 | 3 text string | String | 3483 | alt-server-record | leaf-list | 48 | 4 array | Array | 3484 | | inet: | | | | 3485 | | ip-address | | 3 text string | String | 3486 +----------------------+-------------+-----+---------------+--------+ 3488 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3489 Mappings to JSON and YANG 3491 7. (D)TLS Protocol Profile and Performance Considerations 3493 7.1. (D)TLS Protocol Profile 3495 This section defines the (D)TLS protocol profile of DOTS signal 3496 channel over (D)TLS and DOTS data channel over TLS. 3498 There are known attacks on (D)TLS, such as man-in-the-middle and 3499 protocol downgrade attacks. These are general attacks on (D)TLS and, 3500 as such, they are not specific to DOTS over (D)TLS; refer to the 3501 (D)TLS RFCs for discussion of these security issues. DOTS agents 3502 MUST adhere to the (D)TLS implementation recommendations and security 3503 considerations of [RFC7525] except with respect to (D)TLS version. 3504 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3505 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3506 or later. 3508 When a DOTS client is configured with a domain name of the DOTS 3509 server, and connects to its configured DOTS server, the server may 3510 present it with a PKIX certificate. In order to ensure proper 3511 authentication, a DOTS client MUST verify the entire certification 3512 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3513 validation techniques to compare the domain name with the certificate 3514 provided. Certification authorities that issue DOTS server 3515 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3516 DOTS server SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3517 identifier types in certificate requests (as described in Section 2.3 3518 of [RFC6125]) and the wildcard character '*' SHOULD NOT be included 3519 in the presented identifier. DOTS doesn't use URI-IDs for server 3520 identity verification. 3522 A key challenge to deploying DOTS is the provisioning of DOTS 3523 clients, including the distribution of keying material to DOTS 3524 clients to enable the required mutual authentication of DOTS agents. 3525 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3526 certificate enrollment by which domains operating DOTS servers may 3527 provide DOTS clients with all the necessary cryptographic keying 3528 material, including a private key and a certificate to authenticate 3529 themselves. One deployment option is DOTS clients behave as EST 3530 clients for certificate enrollment from an EST server provisioned by 3531 the mitigation provider. This document does not specify which EST or 3532 other mechanism the DOTS client uses to achieve initial enrollment. 3534 The Server Name Indication (SNI) extension [RFC6066] defines a 3535 mechanism for a client to tell a (D)TLS server the name of the server 3536 it wants to contact. This is a useful extension for hosting 3537 environments where multiple virtual servers are reachable over a 3538 single IP address. The DOTS client may or may not know if it is 3539 interacting with a DOTS server in a virtual server hosting 3540 environment, so the DOTS client SHOULD include the DOTS server FQDN 3541 in the SNI extension. 3543 Implementations compliant with this profile MUST implement all of the 3544 following items: 3546 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3547 equivalent mechanism to protect against replay attacks. 3549 o DTLS session resumption without server-side state to resume 3550 session and convey the DOTS signal. 3552 o At least one of raw public keys [RFC7250] or PSK handshake 3553 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3554 ServerHello, and can be used by DOTS agents that cannot obtain 3555 certificates. 3557 Implementations compliant with this profile SHOULD implement all of 3558 the following items to reduce the delay required to deliver a DOTS 3559 signal channel message: 3561 o TLS False Start [RFC7918] which reduces round-trips by allowing 3562 the TLS client's second flight of messages (ChangeCipherSpec) to 3563 also contain the DOTS signal. TLS False Start is formally defined 3564 for use with TLS, but the same technique is applicable to DTLS as 3565 well. 3567 o Cached Information Extension [RFC7924] which avoids transmitting 3568 the server's certificate and certificate chain if the client has 3569 cached that information from a previous TLS handshake. 3571 Compared to UDP, DOTS signal channel over TCP requires an additional 3572 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3573 implementations are encouraged to implement TCP Fast Open [RFC7413] 3574 to eliminate that RTT. 3576 7.2. (D)TLS 1.3 Considerations 3578 TLS 1.3 provides critical latency improvements for connection 3579 establishment over TLS 1.2. The DTLS 1.3 protocol 3580 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3581 equivalent security guarantees. (D)TLS 1.3 provides two basic 3582 handshake modes the DOTS signal channel can take advantage of: 3584 o A full handshake mode in which a DOTS client can send a DOTS 3585 mitigation request message after one round trip and the DOTS 3586 server immediately responds with a DOTS mitigation response. This 3587 assumes no packet loss is experienced. 3589 o 0-RTT mode in which the DOTS client can authenticate itself and 3590 send DOTS mitigation request messages in the first message, thus 3591 reducing handshake latency. 0-RTT only works if the DOTS client 3592 has previously communicated with that DOTS server, which is very 3593 likely with the DOTS signal channel. 3595 The DOTS client has to establish a (D)TLS session with the DOTS 3596 server during 'idle' time and share a PSK. 3598 During a DDoS attack, the DOTS client can use the (D)TLS session 3599 to convey the DOTS mitigation request message and, if there is no 3600 response from the server after multiple retries, the DOTS client 3601 can resume the (D)TLS session in 0-RTT mode using PSK. 3603 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to 3604 send early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" 3605 as early data; such messages MUST be rejected by DOTS servers. 3606 Section 8 of [RFC8446] discusses some mechanisms to implement to 3607 limit the impact of replay attacks on 0-RTT data. If the DOTS 3608 server accepts 0-RTT, it MUST implement one of these mechanisms to 3609 prevent replay at the TLS layer. A DOTS server can reject 0-RTT 3610 by sending a TLS HelloRetryRequest. 3612 The DOTS signal channel messages sent as early data by the DOTS 3613 client are idempotent requests. As a reminder, the Message ID 3614 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3615 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3616 in each CoAP request. The DOTS server(s) MUST use the Message ID 3617 and the Token in the DOTS signal channel message to detect replay 3618 of early data at the application layer, and accept 0-RTT data at 3619 most once from the same DOTS client. This anti-replay defense 3620 requires sharing the Message ID and the Token in the 0-RTT data 3621 between DOTS servers in the DOTS server domain. DOTS servers do 3622 not rely on transport coordinates to identify DOTS peers. As 3623 specified in Section 4.4.1, DOTS servers couple the DOTS signal 3624 channel sessions using the DOTS client identity and optionally the 3625 'cdid' parameter value. Furthermore, 'mid' value is monotonically 3626 increased by the DOTS client for each mitigation request, 3627 attackers replaying mitigation requests with lower numeric 'mid' 3628 values and overlapping scopes with mitigation requests having 3629 higher numeric 'mid' values will be rejected systematically by the 3630 DOTS server. Likewise, 'sid' value is monotonically increased by 3631 the DOTS client for each configuration request (Section 4.5.2), 3632 attackers replaying configuration requests with lower numeric 3633 'sid' values will be rejected by the DOTS server if it maintains a 3634 higher numeric 'sid' value for this DOTS client. 3636 Owing to the aforementioned protections, all DOTS signal channel 3637 requests are safe to transmit in TLS 1.3 as early data. Refer to 3638 [I-D.boucadair-dots-earlydata] for more details. 3640 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3641 message exchange is shown in Figure 27. 3643 DOTS Client DOTS Server 3645 ClientHello 3646 (0-RTT DOTS signal message) 3647 --------> 3648 ServerHello 3649 {EncryptedExtensions} 3650 {Finished} 3651 <-------- [DOTS signal message] 3652 (end_of_early_data) 3653 {Finished} --------> 3654 [DOTS signal message] <-------> [DOTS signal message] 3656 Note that: 3657 () Indicates messages protected 0-RTT keys 3658 {} Indicates messages protected using handshake keys 3659 [] Indicates messages protected using 1-RTT keys 3661 Figure 27: A Simplified TLS 1.3 Handshake with 0-RTT 3663 7.3. DTLS MTU and Fragmentation 3665 To avoid DOTS signal message fragmentation and the subsequent 3666 decreased probability of message delivery, DOTS agents MUST ensure 3667 that the DTLS record fit within a single datagram. As a reminder, 3668 DTLS handles fragmentation and reassembly only for handshake messages 3669 and not for the application data (Section 4.1.1 of [RFC6347]). If 3670 the PMTU cannot be discovered, DOTS agents MUST assume a PMTU of 1280 3671 bytes, as IPv6 requires that every link in the Internet have an MTU 3672 of 1280 octets or greater as specified in [RFC8200]. If IPv4 support 3673 on legacy or otherwise unusual networks is a consideration and the 3674 PMTU is unknown, DOTS implementations MAY assume on a PMTU of 576 3675 bytes for IPv4 datagrams, as every IPv4 host must be capable of 3676 receiving a packet whose length is equal to 576 bytes as discussed in 3677 [RFC0791] and [RFC1122]. 3679 The DOTS client must consider the amount of record expansion expected 3680 by the DTLS processing when calculating the size of CoAP message that 3681 fits within the path MTU. Path MTU MUST be greater than or equal to 3682 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 3683 overhead of the negotiated DTLS cipher suite + block padding] 3684 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 3685 the path MTU then the DOTS client MUST split the DOTS signal into 3686 separate messages; for example, the list of addresses in the 'target- 3687 prefix' parameter could be split into multiple lists and each list 3688 conveyed in a new PUT request. 3690 Implementation Note: DOTS choice of message size parameters works 3691 well with IPv6 and with most of today's IPv4 paths. However, with 3692 IPv4, it is harder to safely make sure that there is no IP 3693 fragmentation. If the IPv4 path MTU is unknown, implementations may 3694 want to limit themselves to more conservative IPv4 datagram sizes 3695 such as 576 bytes, as per [RFC0791]. 3697 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3699 (D)TLS based upon client certificate can be used for mutual 3700 authentication between DOTS agents. If, for example, a DOTS gateway 3701 is involved, DOTS clients and DOTS gateways must perform mutual 3702 authentication; only authorized DOTS clients are allowed to send DOTS 3703 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3704 perform mutual authentication; a DOTS server only allows DOTS signal 3705 channel messages from an authorized DOTS gateway, thereby creating a 3706 two-link chain of transitive authentication between the DOTS client 3707 and the DOTS server. 3709 The DOTS server should support certificate-based client 3710 authentication. The DOTS client should respond to the DOTS server's 3711 TLS CertificateRequest message with the PKIX certificate held by the 3712 DOTS client. DOTS client certificate validation must be performed as 3713 per [RFC5280] and the DOTS client certificate must conform to the 3714 [RFC5280] certificate profile. If a DOTS client does not support TLS 3715 client certificate authentication, it must support pre-shared key 3716 based or raw public key based client authentication. 3718 +---------------------------------------------+ 3719 | example.com domain +---------+ | 3720 | | AAA | | 3721 | +---------------+ | Server | | 3722 | | Application | +------+--+ | 3723 | | server +<---------------+ ^ | 3724 | | (DOTS client) | | | | 3725 | +---------------+ | | | 3726 | V V | example.net domain 3727 | +-----+----+--+ | +---------------+ 3728 | +--------------+ | | | | | 3729 | | Guest +<----x---->+ DOTS +<------>+ DOTS | 3730 | | (DOTS client)| | gateway | | | server | 3731 | +--------------+ | | | | | 3732 | +----+--------+ | +---------------+ 3733 | ^ | 3734 | | | 3735 | +----------------+ | | 3736 | | DDoS detector | | | 3737 | | (DOTS client) +<-------------+ | 3738 | +----------------+ | 3739 +---------------------------------------------+ 3741 Figure 28: Example of Authentication and Authorization of DOTS Agents 3743 In the example depicted in Figure 28, the DOTS gateway and DOTS 3744 clients within the 'example.com' domain mutually authenticate. After 3745 the DOTS gateway validates the identity of a DOTS client, it 3746 communicates with the AAA server in the 'example.com' domain to 3747 determine if the DOTS client is authorized to request DDoS 3748 mitigation. If the DOTS client is not authorized, a 4.01 3749 (Unauthorized) is returned in the response to the DOTS client. In 3750 this example, the DOTS gateway only allows the application server and 3751 DDoS attack detector to request DDoS mitigation, but does not permit 3752 the user of type 'guest' to request DDoS mitigation. 3754 Also, DOTS gateways and servers located in different domains must 3755 perform mutual authentication (e.g., using certificates). A DOTS 3756 server will only allow a DOTS gateway with a certificate for a 3757 particular domain to request mitigation for that domain. In 3758 reference to Figure 28, the DOTS server only allows the DOTS gateway 3759 to request mitigation for 'example.com' domain and not for other 3760 domains. 3762 9. IANA Considerations 3764 9.1. DOTS Signal Channel UDP and TCP Port Number 3766 IANA is requested to assign the port number TBD to the DOTS signal 3767 channel protocol for both UDP and TCP from the "Service Name and 3768 Transport Protocol Port Number Registry" available at 3769 https://www.iana.org/assignments/service-names-port-numbers/service- 3770 names-port-numbers.xhtml. 3772 The assignment of port number 4646 is strongly suggested, as 4646 is 3773 the ASCII decimal value for ".." (DOTS). 3775 9.2. Well-Known 'dots' URI 3777 This document requests IANA to register the 'dots' well-known URI 3778 (Table 5) in the Well-Known URIs registry 3779 (https://www.iana.org/assignments/well-known-uris/well-known- 3780 uris.xhtml) as defined by [RFC5785]: 3782 +----------+----------------+---------------------+-----------------+ 3783 | URI | Change | Specification | Related | 3784 | suffix | controller | document(s) | information | 3785 +----------+----------------+---------------------+-----------------+ 3786 | dots | IETF | [RFCXXXX] | None | 3787 +----------+----------------+---------------------+-----------------+ 3789 Table 5: 'dots' well-known URI 3791 9.3. Media Type Registration 3793 This document requests IANA to register the "application/dots+cbor" 3794 media type in the "Media Types" registry [IANA.MediaTypes] in the 3795 manner described in [RFC6838], which can be used to indicate that the 3796 content is a DOTS signal channel object: 3798 o Type name: application 3799 o Subtype name: dots+cbor 3800 o Required parameters: N/A 3801 o Optional parameters: N/A 3802 o Encoding considerations: binary 3803 o Security considerations: See the Security Considerations section 3804 of [RFCXXXX] 3805 o Interoperability considerations: N/A 3806 o Published specification: [RFCXXXX] 3807 o Applications that use this media type: DOTS agents sending DOTS 3808 messages over CoAP over (D)TLS. 3809 o Fragment identifier considerations: N/A 3810 o Additional information: 3812 Magic number(s): N/A 3813 File extension(s): N/A 3814 Macintosh file type code(s): N/A 3815 o Person & email address to contact for further information: 3816 IESG, iesg@ietf.org 3817 o Intended usage: COMMON 3818 o Restrictions on usage: none 3819 o Author: See Authors' Addresses section. 3820 o Change controller: IESG 3821 o Provisional registration? No 3823 9.4. CoAP Content-Formats Registration 3825 This document requests IANA to register the CoAP Content-Format ID 3826 for the "application/dots+cbor" media type in the "CoAP Content- 3827 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3829 o Media Type: application/dots+cbor 3830 o Encoding: - 3831 o Id: TBD1 3832 o Reference: [RFCXXXX] 3834 9.5. CBOR Tag Registration 3836 This section defines the DOTS CBOR tag as another means for 3837 applications to declare that a CBOR data structure is a DOTS signal 3838 channel object. Its use is optional and is intended for use in cases 3839 in which this information would not otherwise be known. DOTS CBOR 3840 tag is not required for DOTS signal channel protocol version 3841 specified in this document. If present, the DOTS tag MUST prefix a 3842 DOTS signal channel object. 3844 This document requests IANA to register the DOTS signal channel CBOR 3845 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3846 range: 3848 o CBOR Tag: TBD2 (please assign the same value as the Content- 3849 Format) 3850 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3851 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3852 object, as defined in [RFCXXXX] 3853 o Description of Semantics: [RFCXXXX] 3855 9.6. DOTS Signal Channel Protocol Registry 3857 The document requests IANA to create a new registry, entitled "DOTS 3858 Signal Channel Registry". The following sections define sub- 3859 registries. 3861 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3863 The document requests IANA to create a new sub-registry, entitled 3864 "DOTS Signal Channel CBOR Key Values". 3866 The structure of this sub-registry is provided in Section 9.6.1.1. 3867 Section 9.6.1.2 provides how the registry is initially populated with 3868 the values in Table 4. 3870 9.6.1.1. Registration Template 3872 Parameter name: 3873 Parameter name as used in the DOTS signal channel. 3875 CBOR Key Value: 3876 Key value for the parameter. The key value MUST be an integer in 3877 the 1-65535 range. The key values of the comprehension-required 3878 range (0x0001 - 0x3FFF) and of the comprehension-optional range 3879 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 3880 [RFC8126]). The key values of the comprehension-optional range 3881 (0x4000 - 0x7FFF) are assigned by Specification Required 3882 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 3883 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 3884 [RFC8126]). 3886 Registration requests for the 0x4000 - 0x7FFF range are evaluated 3887 after a three-week review period on the dots-signal-reg- 3888 review@ietf.org mailing list, on the advice of one or more 3889 Designated Experts. However, to allow for the allocation of 3890 values prior to publication, the Designated Experts may approve 3891 registration once they are satisfied that such a specification 3892 will be published. New registration requests should be sent in 3893 the form of an email to the review mailing list; the request 3894 should use an appropriate subject (e.g., "Request to register CBOR 3895 Key Value for DOTS: example"). IANA will only accept new 3896 registrations from the Designated Experts, and will check that 3897 review was requested on the mailing list in accordance with these 3898 procedures. 3900 Within the review period, the Designated Experts will either 3901 approve or deny the registration request, communicating this 3902 decision to the review list and IANA. Denials should include an 3903 explanation and, if applicable, suggestions as to how to make the 3904 request successful. Registration requests that are undetermined 3905 for a period longer than 21 days can be brought to the IESG's 3906 attention (using the iesg@ietf.org mailing list) for resolution. 3908 Criteria that should be applied by the Designated Experts includes 3909 determining whether the proposed registration duplicates existing 3910 functionality, whether it is likely to be of general applicability 3911 or whether it is useful only for a single use case, and whether 3912 the registration description is clear. IANA must only accept 3913 registry updates to the 0x4000 - 0x7FFF range from the Designated 3914 Experts and should direct all requests for registration to the 3915 review mailing list. It is suggested that multiple Designated 3916 Experts be appointed. In cases where a registration decision 3917 could be perceived as creating a conflict of interest for a 3918 particular Expert, that Expert should defer to the judgment of the 3919 other Experts. 3921 CBOR Major Type: 3922 CBOR Major type and optional tag for the parameter. 3924 Change Controller: 3925 For Standards Track RFCs, list the "IESG". For others, give the 3926 name of the responsible party. Other details (e.g., email 3927 address) may also be included. 3929 Specification Document(s): 3930 Reference to the document or documents that specify the parameter, 3931 preferably including URIs that can be used to retrieve copies of 3932 the documents. An indication of the relevant sections may also be 3933 included but is not required. 3935 9.6.1.2. Initial Sub-Registry Content 3937 +----------------------+-------+-------+------------+---------------+ 3938 | Parameter Name | CBOR | CBOR | Change | Specification | 3939 | | Key | Major | Controller | Document(s) | 3940 | | Value | Type | | | 3941 +----------------------+-------+-------+------------+---------------+ 3942 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3943 | nel:mitigation-scope | | | | | 3944 | scope | 2 | 4 | IESG | [RFCXXXX] | 3945 | cdid | 3 | 3 | IESG | [RFCXXXX] | 3946 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3947 | mid | 5 | 0 | IESG | [RFCXXXX] | 3948 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3949 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3950 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3951 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3952 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3953 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3954 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3955 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3956 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3957 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3958 | status | 16 | 0 | IESG | [RFCXXXX] | 3959 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3960 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3961 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3962 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3963 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3964 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3965 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3966 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3967 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3968 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3969 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3970 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3971 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3972 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3973 | channel:signal-config| | | | | 3974 | sid | 31 | 0 | IESG | [RFCXXXX] | 3975 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3976 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3977 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3978 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3979 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3980 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3981 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3982 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3983 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3984 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3985 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3986 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3987 | decimal | | | | | 3988 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3989 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3990 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 3991 | nel:redirected-signal| | | | | 3992 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 3993 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 3994 +----------------------+-------+-------+------------+---------------+ 3996 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 3998 9.6.2. Status Codes Sub-Registry 4000 The document requests IANA to create a new sub-registry, entitled 4001 "DOTS Signal Channel Status Codes". Codes in this registry are used 4002 as valid values of 'status' parameter. 4004 The registry is initially populated with the following values: 4006 +-----+----------------------------------+--------------+-----------+ 4007 | Cod | Label | Description | Reference | 4008 | e | | | | 4009 +-----+----------------------------------+--------------+-----------+ 4010 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 4011 | | | mitigation | | 4012 | | | setup is in | | 4013 | | | progress | | 4014 | | | (e.g., | | 4015 | | | changing the | | 4016 | | | network path | | 4017 | | | to redirect | | 4018 | | | the inbound | | 4019 | | | traffic to a | | 4020 | | | DOTS | | 4021 | | | mitigator). | | 4022 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 4023 | | | being | | 4024 | | | successfully | | 4025 | | | mitigated | | 4026 | | | (e.g., | | 4027 | | | traffic is | | 4028 | | | redirected | | 4029 | | | to a DDoS | | 4030 | | | mitigator | | 4031 | | | and attack | | 4032 | | | traffic is | | 4033 | | | dropped). | | 4034 | 3 | attack-stopped | Attack has | [RFCXXXX] | 4035 | | | stopped and | | 4036 | | | the DOTS | | 4037 | | | client can | | 4038 | | | withdraw the | | 4039 | | | mitigation | | 4040 | | | request. | | 4041 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 4042 | | | exceeded the | | 4043 | | | mitigation | | 4044 | | | provider | | 4045 | | | capability. | | 4046 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 4047 | | | has | | 4048 | | | withdrawn | | 4049 | | | the | | 4050 | | | mitigation | | 4051 | | | request and | | 4052 | | | the | | 4053 | | | mitigation | | 4054 | | | is active | | 4055 | | | but | | 4056 | | | terminating. | | 4057 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 4058 | | | mitigation | | 4059 | | | is now | | 4060 | | | terminated. | | 4061 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 4062 | | | mitigation | | 4063 | | | is | | 4064 | | | withdrawn. | | 4065 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 4066 | | | mitigation | | 4067 | | | will be | | 4068 | | | triggered | | 4069 | | | for the | | 4070 | | | mitigation | | 4071 | | | request only | | 4072 | | | when the | | 4073 | | | DOTS signal | | 4074 | | | channel | | 4075 | | | session is | | 4076 | | | lost. | | 4077 +-----+----------------------------------+--------------+-----------+ 4079 New codes can be assigned via Standards Action [RFC8126]. 4081 9.6.3. Conflict Status Codes Sub-Registry 4083 The document requests IANA to create a new sub-registry, entitled 4084 "DOTS Signal Channel Conflict Status Codes". Codes in this registry 4085 are used as valid values of 'conflict-status' parameter. 4087 The registry is initially populated with the following values: 4089 +------+-------------------------------+----------------+-----------+ 4090 | Code | Label | Description | Reference | 4091 +------+-------------------------------+----------------+-----------+ 4092 | 1 | request-inactive-other-active | DOTS server | [RFCXXXX] | 4093 | | | has detected | | 4094 | | | conflicting | | 4095 | | | mitigation | | 4096 | | | requests from | | 4097 | | | different DOTS | | 4098 | | | clients. This | | 4099 | | | mitigation | | 4100 | | | request is | | 4101 | | | currently | | 4102 | | | inactive until | | 4103 | | | the conflicts | | 4104 | | | are resolved. | | 4105 | | | Another | | 4106 | | | mitigation | | 4107 | | | request is | | 4108 | | | active. | | 4109 | 2 | request-active | DOTS server | [RFCXXXX] | 4110 | | | has detected | | 4111 | | | conflicting | | 4112 | | | mitigation | | 4113 | | | requests from | | 4114 | | | different DOTS | | 4115 | | | clients. This | | 4116 | | | mitigation | | 4117 | | | request is | | 4118 | | | currently | | 4119 | | | active. | | 4120 | 3 | all-requests-inactive | DOTS server | [RFCXXXX] | 4121 | | | has detected | | 4122 | | | conflicting | | 4123 | | | mitigation | | 4124 | | | requests from | | 4125 | | | different DOTS | | 4126 | | | clients. All | | 4127 | | | conflicting | | 4128 | | | mitigation | | 4129 | | | requests are | | 4130 | | | inactive. | | 4131 +------+-------------------------------+----------------+-----------+ 4133 New codes can be assigned via Standards Action [RFC8126]. 4135 9.6.4. Conflict Cause Codes Sub-Registry 4137 The document requests IANA to create a new sub-registry, entitled 4138 "DOTS Signal Channel Conflict Cause Codes". Codes in this registry 4139 are used as valid values of 'conflict-cause' parameter. 4141 The registry is initially populated with the following values: 4143 +------+--------------------------+---------------------+-----------+ 4144 | Code | Label | Description | Reference | 4145 +------+--------------------------+---------------------+-----------+ 4146 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4147 | | | targets. | | 4148 | 2 | conflict-with-acceptlist | Conflicts with an | [RFCXXXX] | 4149 | | | existing accept- | | 4150 | | | list. This code is | | 4151 | | | returned when the | | 4152 | | | DDoS mitigation | | 4153 | | | detects source | | 4154 | | | addresses/prefixes | | 4155 | | | in the accept- | | 4156 | | | listed ACLs are | | 4157 | | | attacking the | | 4158 | | | target. | | 4159 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 4160 | | | This code is | | 4161 | | | returned when a | | 4162 | | | DOTS client uses a | | 4163 | | | 'cuid' that is | | 4164 | | | already used by | | 4165 | | | another DOTS | | 4166 | | | client. | | 4167 +------+--------------------------+---------------------+-----------+ 4169 New codes can be assigned via Standards Action [RFC8126]. 4171 9.6.5. Attack Status Codes Sub-Registry 4173 The document requests IANA to create a new sub-registry, entitled 4174 "DOTS Signal Channel Attack Status Codes". Codes in this registry 4175 are used as valid values of 'attack-status' parameter. 4177 The registry is initially populated with the following values: 4179 +------+-------------------------------+----------------+-----------+ 4180 | Code | Label | Description | Reference | 4181 +------+-------------------------------+----------------+-----------+ 4182 | 1 | under-attack | The DOTS | [RFCXXXX] | 4183 | | | client | | 4184 | | | determines | | 4185 | | | that it is | | 4186 | | | still under | | 4187 | | | attack. | | 4188 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 4189 | | | client | | 4190 | | | determines | | 4191 | | | that the | | 4192 | | | attack is | | 4193 | | | successfully | | 4194 | | | mitigated. | | 4195 +------+-------------------------------+----------------+-----------+ 4197 New codes can be assigned via Standards Action [RFC8126]. 4199 9.7. DOTS Signal Channel YANG Modules 4201 This document requests IANA to register the following URIs in the 4202 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4204 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4205 Registrant Contact: The IESG. 4206 XML: N/A; the requested URI is an XML namespace. 4208 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4209 Registrant Contact: IANA. 4210 XML: N/A; the requested URI is an XML namespace. 4212 This document requests IANA to register the following YANG modules in 4213 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4214 Parameters" registry. 4216 Name: ietf-signal 4217 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4218 Maintained by IANA: N 4219 Prefix: signal 4220 Reference: RFC XXXX 4222 Name: iana-signal 4223 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4224 Maintained by IANA: Y 4225 Prefix: iana-signal 4226 Reference: RFC XXXX 4228 This document defines the initial version of the IANA-maintained 4229 iana-dots-signal-channel YANG module. IANA is requested to add this 4230 note: 4232 Status, conflict status, conflict cause, and attack status values 4233 must not be directly added to the iana-dots-signal-channel YANG 4234 module. They must instead be respectively added to the "DOTS 4235 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4236 Codes", and "DOTS Attack Status Codes" registries. 4238 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4239 status' value is respectively added to the "DOTS Status Codes", "DOTS 4240 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4241 Status Codes" registry, a new "enum" statement must be added to the 4242 iana-dots-signal-channel YANG module. The following "enum" 4243 statement, and substatements thereof, should be defined: 4245 "enum": Replicates the label from the registry. 4247 "value": Contains the IANA-assigned value corresponding to the 4248 'status', 'conflict-status', 'conflict-cause', or 4249 'attack-status'. 4251 "description": Replicates the description from the registry. 4253 "reference": Replicates the reference from the registry and add the 4254 title of the document. 4256 When the iana-dots-signal-channel YANG module is updated, a new 4257 "revision" statement must be added in front of the existing revision 4258 statements. 4260 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4261 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4262 Status Codes" registries: 4264 When this registry is modified, the YANG module iana-dots-signal- 4265 channel must be updated as defined in [RFCXXXX]. 4267 10. Security Considerations 4269 High-level DOTS security considerations are documented in [RFC8612] 4270 and [I-D.ietf-dots-architecture]. 4272 Authenticated encryption MUST be used for data confidentiality and 4273 message integrity. The interaction between the DOTS agents requires 4274 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4275 (TLS) with a cipher suite offering confidentiality protection, and 4276 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4277 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4278 is specified in Section 7. 4280 If TCP is used between DOTS agents, an attacker may be able to inject 4281 RST packets, bogus application segments, etc., regardless of whether 4282 TLS authentication is used. Because the application data is TLS 4283 protected, this will not result in the application receiving bogus 4284 data, but it will constitute a DoS on the connection. This attack 4285 can be countered by using TCP-AO [RFC5925]. Although not widely 4286 adopted, if TCP-AO is used, then any bogus packets injected by an 4287 attacker will be rejected by the TCP-AO integrity check and therefore 4288 will never reach the TLS layer. 4290 An attack vector that can be achieved if the 'cuid' is guessable is a 4291 misbehaving DOTS client from within the client's domain which uses 4292 the 'cuid' of another DOTS client of the domain to delete or alter 4293 active mitigations. For this attack vector to happen, the 4294 misbehaving client needs to pass the security validation checks by 4295 the DOTS server, and eventually the checks of a client-domain DOTS 4296 gateway. 4298 A similar attack can be achieved by a compromised DOTS client which 4299 can sniff the TLS 1.2 handshake, use the client certificate to 4300 identify the 'cuid' used by another DOTS client. This attack is not 4301 possible if algorithms such as version 4 Universally Unique 4302 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4303 the 'cuid' because such UUIDs are not a deterministic function of the 4304 client certificate. Likewise, this attack is not possible with TLS 4305 1.3 because most of the TLS handshake is encrypted and the client 4306 certificate is not visible to eavesdroppers. 4308 A compromised DOTS client can collude with a DDoS attacker to send 4309 mitigation request for a target resource, gets the mitigation 4310 efficacy from the DOTS server, and conveys the mitigation efficacy to 4311 the DDoS attacker to possibly change the DDoS attack strategy. 4312 Obviously, signaling an attack by the compromised DOTS client to the 4313 DOTS server will trigger attack mitigation. This attack can be 4314 prevented by monitoring and auditing DOTS clients to detect 4315 misbehavior and to deter misuse, and by only authorizing the DOTS 4316 client to request mitigation for specific target resources (e.g., an 4317 application server is authorized to request mitigation for its IP 4318 addresses but a DDoS mitigator can request mitigation for any target 4319 resource in the network). Furthermore, DOTS clients are typically 4320 co-located on network security services (e.g., firewall) and a 4321 compromised security service potentially can do a lot more damage to 4322 the network. 4324 Rate-limiting DOTS requests, including those with new 'cuid' values, 4325 from the same DOTS client defends against DoS attacks that would 4326 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4327 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4328 DOTS servers. 4330 In order to prevent leaking internal information outside a client- 4331 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4332 the identification information that pertains to internal DOTS clients 4333 (e.g., source IP address, client's hostname) unless explicitly 4334 configured to do so. 4336 DOTS servers MUST verify that requesting DOTS clients are entitled to 4337 trigger actions on a given IP prefix. That is, only actions on IP 4338 resources that belong to the DOTS client' domain MUST be authorized 4339 by a DOTS server. The exact mechanism for the DOTS servers to 4340 validate that the target prefixes are within the scope of the DOTS 4341 client domain is deployment-specific. 4343 The presence of DOTS gateways may lead to infinite forwarding loops, 4344 which is undesirable. To prevent and detect such loops, this 4345 document uses the Hop-Limit Option. 4347 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4348 privacy enabling protocols (e.g., DNS over TLS [RFC7858] or DoH 4349 [RFC8484]) to prevent eavesdroppers from possibly identifying the 4350 target resources protected by the DDoS mitigation service, and means 4351 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 4352 [RFC4034]). 4354 CoAP-specific security considerations are discussed in Section 11 of 4355 [RFC7252], while CBOR-related security considerations are discussed 4356 in Section 8 of [RFC7049]. 4358 11. Contributors 4360 The following individuals have contributed to this document: 4362 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4364 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4365 mgeller@cisco.com 4367 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4368 Email: rgm@htt-consult.com 4370 o Dan Wing, Email: dwing-ietf@fuggles.com 4372 12. Acknowledgements 4374 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 4375 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 4376 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 4377 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 4378 and comments. 4380 The authors would like to give special thanks to Kaname Nishizuka and 4381 Jon Shallow for their efforts in implementing the protocol and 4382 performing interop testing at IETF Hackathons. 4384 Thanks to the core WG for the recommendations on Hop-Limit and 4385 redirect signaling. 4387 Special thanks to Benjamin Kaduk for the detailed AD review. 4389 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 4390 Kuehlewind, and Alissa Cooper for the review. 4392 13. References 4394 13.1. Normative References 4396 [I-D.ietf-core-hop-limit] 4397 Boucadair, M., K, R., and J. Shallow, "Constrained 4398 Application Protocol (CoAP) Hop-Limit Option", draft-ietf- 4399 core-hop-limit-04 (work in progress), July 2019. 4401 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4402 DOI 10.17487/RFC0791, September 1981, 4403 . 4405 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4406 Communication Layers", STD 3, RFC 1122, 4407 DOI 10.17487/RFC1122, October 1989, 4408 . 4410 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4411 Requirement Levels", BCP 14, RFC 2119, 4412 DOI 10.17487/RFC2119, March 1997, 4413 . 4415 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4416 DOI 10.17487/RFC3688, January 2004, 4417 . 4419 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4420 Resource Identifier (URI): Generic Syntax", STD 66, 4421 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4422 . 4424 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4425 Ciphersuites for Transport Layer Security (TLS)", 4426 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4427 . 4429 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4430 (CIDR): The Internet Address Assignment and Aggregation 4431 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4432 2006, . 4434 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4435 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4436 . 4438 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4439 (TLS) Protocol Version 1.2", RFC 5246, 4440 DOI 10.17487/RFC5246, August 2008, 4441 . 4443 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4444 Housley, R., and W. Polk, "Internet X.509 Public Key 4445 Infrastructure Certificate and Certificate Revocation List 4446 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4447 . 4449 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4450 Uniform Resource Identifiers (URIs)", RFC 5785, 4451 DOI 10.17487/RFC5785, April 2010, 4452 . 4454 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4455 Extensions: Extension Definitions", RFC 6066, 4456 DOI 10.17487/RFC6066, January 2011, 4457 . 4459 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4460 Verification of Domain-Based Application Service Identity 4461 within Internet Public Key Infrastructure Using X.509 4462 (PKIX) Certificates in the Context of Transport Layer 4463 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4464 2011, . 4466 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4467 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4468 January 2012, . 4470 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4471 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4472 . 4474 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4475 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4476 October 2013, . 4478 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4479 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4480 Transport Layer Security (TLS) and Datagram Transport 4481 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4482 June 2014, . 4484 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4485 Application Protocol (CoAP)", RFC 7252, 4486 DOI 10.17487/RFC7252, June 2014, 4487 . 4489 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4490 "Recommendations for Secure Use of Transport Layer 4491 Security (TLS) and Datagram Transport Layer Security 4492 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4493 2015, . 4495 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4496 Application Protocol (CoAP)", RFC 7641, 4497 DOI 10.17487/RFC7641, September 2015, 4498 . 4500 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4501 Layer Security (TLS) False Start", RFC 7918, 4502 DOI 10.17487/RFC7918, August 2016, 4503 . 4505 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4506 (TLS) Cached Information Extension", RFC 7924, 4507 DOI 10.17487/RFC7924, July 2016, 4508 . 4510 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4511 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4512 . 4514 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4515 the Constrained Application Protocol (CoAP)", RFC 7959, 4516 DOI 10.17487/RFC7959, August 2016, 4517 . 4519 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4520 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4521 March 2017, . 4523 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4524 Writing an IANA Considerations Section in RFCs", BCP 26, 4525 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4526 . 4528 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4529 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4530 May 2017, . 4532 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 4533 (IPv6) Specification", STD 86, RFC 8200, 4534 DOI 10.17487/RFC8200, July 2017, 4535 . 4537 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4538 Better Connectivity Using Concurrency", RFC 8305, 4539 DOI 10.17487/RFC8305, December 2017, 4540 . 4542 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4543 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4544 Application Protocol) over TCP, TLS, and WebSockets", 4545 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4546 . 4548 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4549 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4550 . 4552 13.2. Informative References 4554 [I-D.boucadair-dots-earlydata] 4555 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4556 boucadair-dots-earlydata-00 (work in progress), January 4557 2019. 4559 [I-D.ietf-core-comi] 4560 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 4561 Petrov, "CoAP Management Interface", draft-ietf-core- 4562 comi-07 (work in progress), July 2019. 4564 [I-D.ietf-core-yang-cbor] 4565 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 4566 Data Modeled with YANG", draft-ietf-core-yang-cbor-10 4567 (work in progress), April 2019. 4569 [I-D.ietf-dots-architecture] 4570 Mortensen, A., K, R., Andreasen, F., Teague, N., and R. 4571 Compton, "Distributed-Denial-of-Service Open Threat 4572 Signaling (DOTS) Architecture", draft-ietf-dots- 4573 architecture-14 (work in progress), May 2019. 4575 [I-D.ietf-dots-data-channel] 4576 Boucadair, M. and R. K, "Distributed Denial-of-Service 4577 Open Threat Signaling (DOTS) Data Channel Specification", 4578 draft-ietf-dots-data-channel-30 (work in progress), July 4579 2019. 4581 [I-D.ietf-dots-multihoming] 4582 Boucadair, M., K, R., and W. Pan, "Multi-homing Deployment 4583 Considerations for Distributed-Denial-of-Service Open 4584 Threat Signaling (DOTS)", draft-ietf-dots-multihoming-02 4585 (work in progress), July 2019. 4587 [I-D.ietf-dots-server-discovery] 4588 Boucadair, M. and R. K, "Distributed-Denial-of-Service 4589 Open Threat Signaling (DOTS) Server Discovery", draft- 4590 ietf-dots-server-discovery-04 (work in progress), June 4591 2019. 4593 [I-D.ietf-dots-use-cases] 4594 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 4595 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 4596 Open Threat Signaling", draft-ietf-dots-use-cases-18 (work 4597 in progress), July 2019. 4599 [I-D.ietf-tls-dtls13] 4600 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4601 Datagram Transport Layer Security (DTLS) Protocol Version 4602 1.3", draft-ietf-tls-dtls13-32 (work in progress), July 4603 2019. 4605 [IANA.CBOR.Tags] 4606 IANA, "Concise Binary Object Representation (CBOR) Tags", 4607 . 4610 [IANA.CoAP.Content-Formats] 4611 IANA, "CoAP Content-Formats", 4612 . 4615 [IANA.MediaTypes] 4616 IANA, "Media Types", 4617 . 4619 [proto_numbers] 4620 "IANA, "Protocol Numbers"", 2011, 4621 . 4623 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4624 Address Translator (Traditional NAT)", RFC 3022, 4625 DOI 10.17487/RFC3022, January 2001, 4626 . 4628 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 4629 Rose, "Resource Records for the DNS Security Extensions", 4630 RFC 4034, DOI 10.17487/RFC4034, March 2005, 4631 . 4633 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4634 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4635 DOI 10.17487/RFC4122, July 2005, 4636 . 4638 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4639 Congestion Control Protocol (DCCP)", RFC 4340, 4640 DOI 10.17487/RFC4340, March 2006, 4641 . 4643 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4644 Denial-of-Service Considerations", RFC 4732, 4645 DOI 10.17487/RFC4732, December 2006, 4646 . 4648 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4649 Translation (NAT) Behavioral Requirements for Unicast 4650 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4651 2007, . 4653 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4654 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4655 . 4657 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4658 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4659 . 4661 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4662 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4663 DOI 10.17487/RFC5389, October 2008, 4664 . 4666 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4667 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4668 June 2010, . 4670 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4671 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4672 DOI 10.17487/RFC6052, October 2010, 4673 . 4675 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4676 NAT64: Network Address and Protocol Translation from IPv6 4677 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4678 April 2011, . 4680 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4681 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4682 DOI 10.17487/RFC6234, May 2011, 4683 . 4685 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4686 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4687 . 4689 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4690 "Default Address Selection for Internet Protocol Version 6 4691 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4692 . 4694 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4695 Specifications and Registration Procedures", BCP 13, 4696 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4697 . 4699 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4700 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4701 DOI 10.17487/RFC6887, April 2013, 4702 . 4704 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4705 A., and H. Ashida, "Common Requirements for Carrier-Grade 4706 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4707 April 2013, . 4709 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4710 "Enrollment over Secure Transport", RFC 7030, 4711 DOI 10.17487/RFC7030, October 2013, 4712 . 4714 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4715 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4716 . 4718 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4719 "Architectural Considerations in Smart Object Networking", 4720 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4721 . 4723 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4724 NETCONF Protocol over Transport Layer Security (TLS) with 4725 Mutual X.509 Authentication", RFC 7589, 4726 DOI 10.17487/RFC7589, June 2015, 4727 . 4729 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 4730 and P. Hoffman, "Specification for DNS over Transport 4731 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 4732 2016, . 4734 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4735 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4736 . 4738 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4739 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4740 . 4742 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 4743 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 4744 . 4746 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4747 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4748 January 2019, . 4750 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 4751 Threat Signaling (DOTS) Requirements", RFC 8612, 4752 DOI 10.17487/RFC8612, May 2019, 4753 . 4755 Appendix A. CUID Generation 4757 The document recommends the use of SPKI to generate the 'cuid'. This 4758 design choice is motivated by the following reasons: 4760 o SPKI is globally unique. 4762 o It is deterministic. 4764 o It allows to avoid extra cycles that may be induced by 'cuid' 4765 collision. 4767 o DOTS clients do not need to store the 'cuid' in a persistent 4768 storage. 4770 o It allows to detect compromised DOTS clients that do not adhere to 4771 the 'cuid' generation algorithm. 4773 Authors' Addresses 4775 Tirumaleswar Reddy (editor) 4776 McAfee, Inc. 4777 Embassy Golf Link Business Park 4778 Bangalore, Karnataka 560071 4779 India 4781 Email: kondtir@gmail.com 4783 Mohamed Boucadair (editor) 4784 Orange 4785 Rennes 35000 4786 France 4788 Email: mohamed.boucadair@orange.com 4789 Prashanth Patil 4790 Cisco Systems, Inc. 4792 Email: praspati@cisco.com 4794 Andrew Mortensen 4795 Arbor Networks, Inc. 4796 2727 S. State St 4797 Ann Arbor, MI 48104 4798 United States 4800 Email: andrew@moretension.com 4802 Nik Teague 4803 Iron Mountain Data Centers 4804 United Kingdom 4806 Email: nteague@ironmountain.co.uk