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