idnits 2.17.1 draft-ietf-dots-signal-channel-31.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 2475 has weird spacing: '...er-port ine...' -- The document date (March 28, 2019) is 1855 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 4089, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6347 (Obsoleted by RFC 9147) ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) ** Downref: Normative reference to an Informational RFC: RFC 7918 == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-04 == Outdated reference: A later version (-07) exists of draft-ietf-core-hop-limit-03 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-07 == Outdated reference: A later version (-18) exists of draft-ietf-dots-architecture-12 == Outdated reference: A later version (-31) exists of draft-ietf-dots-data-channel-27 == 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 (~~), 10 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS T. Reddy, Ed. 3 Internet-Draft McAfee 4 Intended status: Standards Track M. Boucadair, Ed. 5 Expires: September 29, 2019 Orange 6 P. Patil 7 Cisco 8 A. Mortensen 9 Arbor Networks, Inc. 10 N. Teague 11 Verisign, Inc. 12 March 28, 2019 14 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 15 Channel Specification 16 draft-ietf-dots-signal-channel-31 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 September 29, 2019. 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 . . . . . . . . . . . . . . . . . . . . . . . . 9 95 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 10 96 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 11 97 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 12 98 4.4.2. Retrieve Information Related to a Mitigation . . . . 27 99 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 32 100 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 35 101 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 36 102 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 38 103 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 39 104 4.5.1. Discover Configuration Parameters . . . . . . . . . . 41 105 4.5.2. Convey DOTS Signal Channel Session Configuration . . 45 106 4.5.3. Configuration Freshness and Notifications . . . . . . 50 107 4.5.4. Delete DOTS Signal Channel Session Configuration . . 51 108 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 52 109 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 54 110 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 55 111 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 55 112 5.2. IANA DOTS Signal Channel YANG Module . . . . . . . . . . 57 113 5.3. IETF DOTS Signal Channel YANG Module . . . . . . . . . . 61 114 6. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 71 115 7. (D)TLS Protocol Profile and Performance Considerations . . . 74 116 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 74 117 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 75 118 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 77 119 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 120 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 121 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 122 9.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . . 79 123 9.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . . 79 124 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 80 125 9.4. CoAP Content-Formats Registration . . . . . . . . . . . . 80 126 9.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . . 80 127 9.6. DOTS Signal Channel Protocol Registry . . . . . . . . . . 81 128 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry . . 81 129 9.6.1.1. Registration Template . . . . . . . . . . . . . . 81 130 9.6.1.2. Initial Sub-Registry Content . . . . . . . . . . 83 131 9.6.2. Status Codes Sub-Registry . . . . . . . . . . . . . . 84 132 9.6.3. Conflict Status Codes Sub-Registry . . . . . . . . . 86 133 9.6.4. Conflict Cause Codes Sub-Registry . . . . . . . . . . 88 134 9.6.5. Attack Status Codes Sub-Registry . . . . . . . . . . 88 135 9.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 89 136 10. Security Considerations . . . . . . . . . . . . . . . . . . . 90 137 11. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 92 138 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 92 139 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 93 140 13.1. Normative References . . . . . . . . . . . . . . . . . . 93 141 13.2. Informative References . . . . . . . . . . . . . . . . . 95 142 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 100 144 1. Introduction 146 A distributed denial-of-service (DDoS) attack is a distributed 147 attempt to make machines or network resources unavailable to their 148 intended users. In most cases, sufficient scale for an effective 149 attack can be achieved by compromising enough end-hosts and using 150 those infected hosts to perpetrate and amplify the attack. The 151 victim in this attack can be an application server, a host, a router, 152 a firewall, or an entire network. 154 Network applications have finite resources like CPU cycles, the 155 number of processes or threads they can create and use, the maximum 156 number of simultaneous connections they can handle, the limited 157 resources of the control plane, etc. When processing network 158 traffic, such applications are supposed to use these resources to 159 provide the intended functionality in the most efficient manner. 160 However, a DDoS attacker may be able to prevent an application from 161 performing its intended task by making the application exhaust its 162 finite resources. 164 A TCP DDoS SYN-flood [RFC4987], for example, is a memory-exhausting 165 attack while an ACK-flood is a CPU-exhausting attack. Attacks on the 166 link are carried out by sending enough traffic so that the link 167 becomes congested, thereby likely causing packet loss for legitimate 168 traffic. Stateful firewalls can also be attacked by sending traffic 169 that causes the firewall to maintain an excessive number of states 170 that may jeopardize the firewall's operation overall, besides likely 171 performance impacts. The firewall then runs out of memory, and can 172 no longer instantiate the states required to process legitimate 173 flows. Other possible DDoS attacks are discussed in [RFC4732]. 175 In many cases, it may not be possible for network administrators to 176 determine the cause(s) of an attack. They may instead just realize 177 that certain resources seem to be under attack. This document 178 defines a lightweight protocol that allows a DOTS client to request 179 mitigation from one or more DOTS servers for protection against 180 detected, suspected, or anticipated attacks. This protocol enables 181 cooperation between DOTS agents to permit a highly-automated network 182 defense that is robust, reliable, and secure. Note that "secure" 183 means the support of the features defined in Section 2.4 of 184 [I-D.ietf-dots-requirements]. 186 An example of a network diagram that illustrates a deployment of DOTS 187 agents is shown in Figure 1. In this example, a DOTS server is 188 operating on the access network. A DOTS client is located on the LAN 189 (Local Area Network), while a DOTS gateway is embedded in the CPE 190 (Customer Premises Equipment). 192 Network 193 Resource CPE router Access network __________ 194 +-----------+ +--------------+ +-------------+ / \ 195 | |___| |____| |___ | Internet | 196 |DOTS client| | DOTS gateway | | DOTS server | | | 197 | | | | | | | | 198 +-----------+ +--------------+ +-------------+ \__________/ 200 Figure 1: Sample DOTS Deployment (1) 202 DOTS servers can also be reachable over the Internet, as depicted in 203 Figure 2. 205 Network DDoS mitigation 206 Resource CPE router __________ service 207 +-----------+ +-------------+ / \ +-------------+ 208 | |___| |____| |___ | | 209 |DOTS client| |DOTS gateway | | Internet | | DOTS server | 210 | | | | | | | | 211 +-----------+ +-------------+ \__________/ +-------------+ 213 Figure 2: Sample DOTS Deployment (2) 215 In typical deployments, the DOTS client belongs to a different 216 administrative domain than the DOTS server. For example, the DOTS 217 client is embedded in a firewall protecting services owned and 218 operated by a customer, while the DOTS server is owned and operated 219 by a different administrative entity (service provider, typically) 220 providing DDoS mitigation services. The latter might or might not 221 provide connectivity services to the network hosting the DOTS client. 223 The DOTS server may (not) be co-located with the DOTS mitigator. In 224 typical deployments, the DOTS server belongs to the same 225 administrative domain as the mitigator. The DOTS client can 226 communicate directly with a DOTS server or indirectly via a DOTS 227 gateway. 229 The document adheres to the DOTS architecture 230 [I-D.ietf-dots-architecture]. The requirements for DOTS signal 231 channel protocol are documented in [I-D.ietf-dots-requirements]. 232 This document satisfies all the use cases discussed in 233 [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 254 [I-D.ietf-dots-requirements]. 256 The meaning of the symbols in YANG tree diagrams is defined in 257 [RFC8340]. 259 3. Design Overview 261 The DOTS signal channel is built on top of the Constrained 262 Application Protocol (CoAP) [RFC7252], a lightweight protocol 263 originally designed for constrained devices and networks. The many 264 features of CoAP (expectation of packet loss, support for 265 asynchronous Non-confirmable messaging, congestion control, small 266 message overhead limiting the need for fragmentation, use of minimal 267 resources, and support for (D)TLS) makes it a good candidate to build 268 the DOTS signaling mechanism from. 270 The DOTS signal channel is layered on existing standards (Figure 3). 272 +---------------------+ 273 | DOTS Signal Channel | 274 +---------------------+ 275 | CoAP | 276 +----------+----------+ 277 | TLS | DTLS | 278 +----------+----------+ 279 | TCP | UDP | 280 +----------+----------+ 281 | IP | 282 +---------------------+ 284 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 285 (D)TLS 287 By default, a DOTS signal channel MUST run over port number TBD as 288 defined in Section 9.1, for both UDP and TCP, unless the DOTS server 289 has a mutual agreement with its DOTS clients to use a different port 290 number. DOTS clients MAY alternatively support means to dynamically 291 discover the ports used by their DOTS servers (e.g., 292 [I-D.boucadair-dots-server-discovery]). In order to use a distinct 293 port number (as opposed to TBD), DOTS clients and servers SHOULD 294 support a configurable parameter to supply the port number to use. 295 The rationale for not using the default port number 5684 ((D)TLS 296 CoAP) is to allow for differentiated behaviors in environments where 297 both a DOTS gateway and an IoT gateway (e.g., Figure 3 of [RFC7452]) 298 are present. 300 The signal channel uses the "coaps" URI scheme defined in Section 6 301 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 302 [RFC8323] to identify DOTS server resources accessible using CoAP 303 over UDP secured with DTLS and CoAP over TCP secured with TLS, 304 respectively. 306 The signal channel is initiated by the DOTS client (Section 4.4). 307 Once the signal channel is established, the DOTS agents periodically 308 send heartbeats to keep the channel active (Section 4.7). At any 309 time, the DOTS client may send a mitigation request message to a DOTS 310 server over the active channel. While mitigation is active (because 311 of the higher likelihood of packet loss during a DDoS attack), the 312 DOTS server periodically sends status messages to the client, 313 including basic mitigation feedback details. Mitigation remains 314 active until the DOTS client explicitly terminates mitigation, or the 315 mitigation lifetime expires. 317 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 318 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 319 capabilities. A Happy Eyeballs procedure for DOTS signal channel is 320 specified in Section 4.3. 322 A DOTS client is entitled to access only to resources it creates. In 323 particular, a DOTS client can not retrieve data related to mitigation 324 requests created by other DOTS clients of the same DOTS client 325 domain. 327 Messages exchanged between DOTS agents are serialized using Concise 328 Binary Object Representation (CBOR) [RFC7049], a binary encoding 329 scheme designed for small code and message size. CBOR-encoded 330 payloads are used to carry signal channel-specific payload messages 331 which convey request parameters and response information such as 332 errors. In order to allow reusing data models across protocols, 333 [RFC7951] specifies the JavaScript Object Notation (JSON) encoding of 334 YANG-modeled data. A similar effort for CBOR is defined in 335 [I-D.ietf-core-yang-cbor]. 337 DOTS agents primarily determine that a CBOR data structure is a DOTS 338 signal channel object from the application context, such as from the 339 port number assigned to the DOTS signal channel. The other method 340 DOTS agents use to indicate that a CBOR data structure is a DOTS 341 signal channel object is the use of the "application/dots+cbor" 342 content type (Section 9.3). 344 This document specifies a YANG module for representing DOTS 345 mitigation scopes, DOTS signal channel session configuration data, 346 and DOTS redirected signalling (Section 5). Representing these data 347 as CBOR data can either follow the rules in [I-D.ietf-core-yang-cbor] 348 or those in [RFC7951] combined with JSON/CBOR conversion rules in 349 [RFC7049]; both approaches produce a valid encoding. All parameters 350 in the payload of the DOTS signal channel are mapped to CBOR types as 351 specified in Section 6. 353 In order to prevent fragmentation, DOTS agents must follow the 354 recommendations documented in Section 4.6 of [RFC7252]. Refer to 355 Section 7.3 for more details. 357 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 358 payload included in CoAP responses with 2.xx Response Codes MUST be 359 of content type "application/dots+cbor". CoAP responses with 4.xx 360 and 5.xx error Response Codes MUST include a diagnostic payload 361 (Section 5.5.2 of [RFC7252]). The Diagnostic Payload may contain 362 additional information to aid troubleshooting. 364 In deployments where multiple DOTS clients are enabled in a network 365 (owned and operated by the same entity), the DOTS server may detect 366 conflicting mitigation requests from these clients. This document 367 does not aim to specify a comprehensive list of conditions under 368 which a DOTS server will characterize two mitigation requests from 369 distinct DOTS clients as conflicting, nor recommend a DOTS server 370 behavior for processing conflicting mitigation requests. Those 371 considerations are implementation- and deployment-specific. 372 Nevertheless, the document specifies the mechanisms to notify DOTS 373 clients when conflicts occur, including the conflict cause 374 (Section 4.4). 376 In deployments where one or more translators (e.g., Traditional NAT 377 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 378 enabled between the client's network and the DOTS server, DOTS signal 379 channel messages forwarded to a DOTS server MUST NOT include internal 380 IP addresses/prefixes and/or port numbers; external addresses/ 381 prefixes and/or port numbers as assigned by the translator MUST be 382 used instead. This document does not make any recommendation about 383 possible translator discovery mechanisms. The following are some 384 (non-exhaustive) deployment examples that may be considered: 386 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 387 Utilities for NAT (STUN) [RFC5389] may be used to retrieve the 388 external addresses/prefixes and/or port numbers. Information 389 retrieved by means of PCP or STUN will be used to feed the DOTS 390 signal channel messages that will be sent to a DOTS server. 392 o A DOTS gateway may be co-located with the translator. The DOTS 393 gateway will need to update the DOTS messages, based upon the 394 local translator's binding table. 396 4. DOTS Signal Channel: Messages & Behaviors 398 4.1. DOTS Server(s) Discovery 400 This document assumes that DOTS clients are provisioned with the 401 reachability information of their DOTS server(s) using any of a 402 variety of means (e.g., local configuration, or dynamic means such as 403 DHCP). The description of such means is out of scope of this 404 document. 406 Likewise, it is out of scope of this document to specify the behavior 407 to be followed by a DOTS client to send DOTS requests when multiple 408 DOTS servers are provisioned (e.g., contact all DOTS servers, select 409 one DOTS server among the list). 411 4.2. CoAP URIs 413 The DOTS server MUST support the use of the path-prefix of "/.well- 414 known/" as defined in [RFC5785] and the registered name of "dots". 415 Each DOTS operation is indicated by a path-suffix that indicates the 416 intended operation. The operation path (Table 1) is appended to the 417 path-prefix to form the URI used with a CoAP request to perform the 418 desired DOTS operation. 420 +-----------------------+----------------+-------------+ 421 | Operation | Operation Path | Details | 422 +-----------------------+----------------+-------------+ 423 | Mitigation | /mitigate | Section 4.4 | 424 +-----------------------+----------------+-------------+ 425 | Session configuration | /config | Section 4.5 | 426 +-----------------------+----------------+-------------+ 428 Table 1: Operations and their Corresponding URIs 430 4.3. Happy Eyeballs for DOTS Signal Channel 432 [I-D.ietf-dots-requirements] mentions that DOTS agents will have to 433 support both connectionless and connection-oriented protocols. As 434 such, the DOTS signal channel is designed to operate with DTLS over 435 UDP and TLS over TCP. Further, a DOTS client may acquire a list of 436 IPv4 and IPv6 addresses (Section 4.1), each of which can be used to 437 contact the DOTS server using UDP and TCP. The following specifies 438 the procedure to follow to select the address family and the 439 transport protocol for sending DOTS signal channel messages. 441 Such procedure is needed to avoid experiencing long connection 442 delays. For example, if an IPv4 path to reach a DOTS server is 443 functional, but the DOTS server's IPv6 path is non-functional, a 444 dual-stack DOTS client may experience a significant connection delay 445 compared to an IPv4-only DOTS client, in the same network conditions. 446 The other problem is that if a middlebox between the DOTS client and 447 DOTS server is configured to block UDP traffic, the DOTS client will 448 fail to establish a DTLS association with the DOTS server and, as a 449 consequence, will have to fall back to TLS over TCP, thereby 450 incurring significant connection delays. 452 To overcome these connection setup problems, the DOTS client attempts 453 to connect to its DOTS server(s) using both IPv6 and IPv4, and tries 454 both DTLS over UDP and TLS over TCP in a manner similar to the Happy 455 Eyeballs mechanism [RFC8305]. These connection attempts are 456 performed by the DOTS client when it initializes, or in general when 457 it has to select an address family and transport to contact its DOTS 458 server. The results of the Happy Eyeballs procedure are used by the 459 DOTS client for sending its subsequent messages to the DOTS server. 460 Note that the DOTS client after successfully establishing a 461 connection MUST cache information regarding the outcome of each 462 connection attempt for a specific time period, and it uses that 463 information to avoid thrashing the network with subsequent attempts. 465 The order of preference of the DOTS signal channel address family and 466 transport protocol (most preferred first) is: UDP over IPv6, UDP over 467 IPv4, TCP over IPv6, and finally TCP over IPv4. This order adheres 468 to the address preference order specified in [RFC6724] and the DOTS 469 signal channel preference which privileges the use of UDP over TCP 470 (to avoid TCP's head of line blocking). 472 In reference to Figure 4, the DOTS client sends two TCP SYNs and two 473 DTLS ClientHello messages at the same time over IPv6 and IPv4. In 474 this example, it is assumed that the IPv6 path is broken and UDP 475 traffic is dropped by a middlebox but has little impact to the DOTS 476 client because there is no long delay before using IPv4 and TCP. The 477 DOTS client periodically repeats the mechanism to discover whether 478 DOTS signal channel messages with DTLS over UDP becomes available 479 from the DOTS server, so the DOTS client can migrate the DOTS signal 480 channel from TCP to UDP. Such probing SHOULD NOT be done more 481 frequently than every 24 hours and MUST NOT be done more frequently 482 than every 5 minutes. 484 A single DOTS signal channel between DOTS agents can be used to 485 exchange multiple DOTS signal messages. To reduce DOTS client and 486 DOTS server workload, DOTS clients SHOULD re-use the (D)TLS session. 488 +-----------+ +-----------+ 489 |DOTS client| |DOTS server| 490 +-----------+ +-----------+ 491 | | 492 |--DTLS ClientHello, IPv6 ---->X | 493 |--TCP SYN, IPv6-------------->X | 494 |--DTLS ClientHello, IPv4 ---->X | 495 |--TCP SYN, IPv4--------------------------------------->| 496 |--DTLS ClientHello, IPv6 ---->X | 497 |--TCP SYN, IPv6-------------->X | 498 |<-TCP SYNACK-------------------------------------------| 499 |--DTLS ClientHello, IPv4 ---->X | 500 |--TCP ACK--------------------------------------------->| 501 |<------------Establish TLS Session-------------------->| 502 |----------------DOTS signal--------------------------->| 503 | | 505 Figure 4: DOTS Happy Eyeballs (Sample Flow) 507 4.4. DOTS Mitigation Methods 509 The following methods are used by a DOTS client to request, withdraw, 510 or retrieve the status of mitigation requests: 512 PUT: DOTS clients use the PUT method to request mitigation from a 513 DOTS server (Section 4.4.1). During active mitigation, DOTS 514 clients may use PUT requests to carry mitigation efficacy 515 updates to the DOTS server (Section 4.4.3). 517 GET: DOTS clients may use the GET method to subscribe to DOTS 518 server status messages, or to retrieve the list of its 519 mitigations maintained by a DOTS server (Section 4.4.2). 521 DELETE: DOTS clients use the DELETE method to withdraw a request for 522 mitigation from a DOTS server (Section 4.4.4). 524 Mitigation request and response messages are marked as Non- 525 confirmable messages (Section 2.2 of [RFC7252]). 527 DOTS agents SHOULD follow the data transmission guidelines discussed 528 in Section 3.1.3 of [RFC8085] and control transmission behavior by 529 not sending more than one UDP datagram per round-trip time (RTT) to 530 the peer DOTS agent on average. 532 Requests marked by the DOTS client as Non-confirmable messages are 533 sent at regular intervals until a response is received from the DOTS 534 server. If the DOTS client cannot maintain an RTT estimate, it 535 SHOULD NOT send more than one Non-confirmable request every 3 536 seconds, and SHOULD use an even less aggressive rate whenever 537 possible (case 2 in Section 3.1.3 of [RFC8085]). 539 JSON diagnostic notation is used to illustrate the various methods 540 defined in the following sub-sections. Also, the examples use the 541 Labels defined in Sections 9.6.2, 9.6.3, 9.6.4, and 9.6.5. 543 4.4.1. Request Mitigation 545 When a DOTS client requires mitigation for some reason, the DOTS 546 client uses the CoAP PUT method to send a mitigation request to its 547 DOTS server(s) (Figures 5 and 6). 549 If a DOTS client is entitled to solicit the DOTS service, the DOTS 550 server enables mitigation on behalf of the DOTS client by 551 communicating the DOTS client's request to a mitigator (which may be 552 colocated with the DOTS server) and relaying the feedback of the 553 thus-selected mitigator to the requesting DOTS client. 555 Header: PUT (Code=0.03) 556 Uri-Path: ".well-known" 557 Uri-Path: "dots" 558 Uri-Path: "mitigate" 559 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 560 Uri-Path: "mid=123" 561 Content-Format: "application/dots+cbor" 562 { 563 ... 564 } 566 Figure 5: PUT to Convey DOTS Mitigation Requests 568 The order of the Uri-Path options is important as it defines the CoAP 569 resource. In particular, 'mid' MUST follow 'cuid'. 571 The additional Uri-Path parameters to those defined in Section 4.2 572 are as follows: 574 cuid: Stands for Client Unique Identifier. A globally unique 575 identifier that is meant to prevent collisions among DOTS clients, 576 especially those from the same domain. It MUST be generated by 577 DOTS clients. 579 Implementations SHOULD set 'cuid' to the output of a cryptographic 580 hash algorithm whose input is the Distinguished Encoding Rules 581 (DER)-encoded Abstract Syntax Notation One (ASN.1) representation 582 of the Subject Public Key Info (SPKI) of the DOTS client X.509 583 certificate [RFC5280], the DOTS client raw public key [RFC7250], 584 or the "Pre-Shared Key (PSK) identity" used by the DOTS client in 585 the TLS ClientKeyExchange message. In this version of the 586 specification, the cryptographic hash algorithm used is SHA-256 587 [RFC6234]. The output of the cryptographic hash algorithm is 588 truncated to 16 bytes; truncation is done by stripping off the 589 final 16 bytes. The truncated output is base64url encoded. 591 The 'cuid' is intended to be stable when communicating with a 592 given DOTS server, i.e., the 'cuid' used by a DOTS client SHOULD 593 NOT change over time. Distinct 'cuid' values MAY be used by a 594 single DOTS client per DOTS server. 596 If a DOTS client has to change its 'cuid' for some reason, it MUST 597 NOT do so when mitigations are still active for the old 'cuid'. 598 The 'cuid' SHOULD be 22 characters to avoid DOTS signal message 599 fragmentation over UDP. Furthermore, if that DOTS client created 600 aliases and filtering entries at the DOTS server by means of the 601 DOTS data channel, it MUST delete all the entries bound to the old 602 'cuid' and re-install them using the new 'cuid'. 604 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS peer 605 to notify that the 'cuid' is already in-use by another DOTS 606 client. Upon receipt of that error code, a new 'cuid' MUST be 607 generated by the DOTS peer (e.g., using [RFC4122]). 609 Client-domain DOTS gateways MUST handle 'cuid' collision directly 610 and it is RECOMMENDED that 'cuid' collision is handled directly by 611 server-domain DOTS gateways. 613 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 614 Triggers for such rewriting are out of scope. 616 This is a mandatory Uri-Path parameter. 618 mid: Identifier for the mitigation request represented with an 619 integer. This identifier MUST be unique for each mitigation 620 request bound to the DOTS client, i.e., the 'mid' parameter value 621 in the mitigation request needs to be unique (per 'cuid' and DOTS 622 server) relative to the 'mid' parameter values of active 623 mitigation requests conveyed from the DOTS client to the DOTS 624 server. 626 In order to handle out-of-order delivery of mitigation requests, 627 'mid' values MUST increase monotonically. 629 If the 'mid' value has reached 3/4 of (2**32 - 1) (i.e., 630 3221225471) and no attack is detected, the DOTS client MUST reset 631 'mid' to 0 to handle 'mid' rollover. If the DOTS client maintains 632 mitigation requests with pre-configured scopes, it MUST re-create 633 them with the 'mid' restarting at 0. 635 This identifier MUST be generated by the DOTS client. 637 This is a mandatory Uri-Path parameter. 639 'cuid' and 'mid' MUST NOT appear in the PUT request message body 640 (Figure 6). 642 Content-Format: "application/dots+cbor" 643 { 644 "ietf-dots-signal-channel:mitigation-scope": { 645 "scope": [ 646 { 647 "target-prefix": [ 648 "string" 649 ], 650 "target-port-range": [ 651 { 652 "lower-port": number, 653 "upper-port": number 654 } 655 ], 656 "target-protocol": [ 657 number 658 ], 659 "target-fqdn": [ 660 "string" 661 ], 662 "target-uri": [ 663 "string" 664 ], 665 "alias-name": [ 666 "string" 667 ], 668 "lifetime": number, 669 "trigger-mitigation": true|false 670 } 671 ] 672 } 673 } 675 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 676 Schema) 678 The parameters in the CBOR body (Figure 6) of the PUT request are 679 described below: 681 target-prefix: A list of prefixes identifying resources under 682 attack. Prefixes are represented using Classless Inter-Domain 683 Routing (CIDR) notation [RFC4632]. 684 As a reminder, the prefix length must be less than or equal to 32 685 (resp. 128) for IPv4 (resp. IPv6). 687 The prefix list MUST NOT include broadcast, loopback, or multicast 688 addresses. These addresses are considered as invalid values. In 689 addition, the DOTS server MUST validate that target prefixes are 690 within the scope of the DOTS client domain. Other validation 691 checks may be supported by DOTS servers. 693 This is an optional attribute. 695 target-port-range: A list of port numbers bound to resources under 696 attack. 698 A port range is defined by two bounds, a lower port number (lower- 699 port) and an upper port number (upper-port). When only 'lower- 700 port' is present, it represents a single port number. 702 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 703 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 704 [RFC4340], a range of ports can be, for example, 0-1023, 705 1024-65535, or 1024-49151. 707 This is an optional attribute. 709 target-protocol: A list of protocols involved in an attack. Values 710 are taken from the IANA protocol registry [proto_numbers]. 712 If 'target-protocol' is not specified, then the request applies to 713 any protocol. 715 This is an optional attribute. 717 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 718 identifying resources under attack [RFC8499]. 720 How a name is passed to an underlying name resolution library is 721 implementation- and deployment-specific. Nevertheless, once the 722 name is resolved into one or multiple IP addresses, DOTS servers 723 MUST apply the same validation checks as those for 'target- 724 prefix'. 726 The use of FQDNs may be suboptimal because: 728 * It induces both an extra load and increased delays on the DOTS 729 server to handle and manage DNS resolution requests. 731 * It does not guarantee that the DOTS server will resolve a name 732 to the same IP addresses that the DOTS client does. 734 This is an optional attribute. 736 target-uri: A list of Uniform Resource Identifiers (URIs) [RFC3986] 737 identifying resources under attack. 739 The same validation checks used for 'target-fqdn' MUST be followed 740 by DOTS servers to validate a target URI. 742 This is an optional attribute. 744 alias-name: A list of aliases of resources for which the mitigation 745 is requested. Aliases can be created using the DOTS data channel 746 (Section 6.1 of [I-D.ietf-dots-data-channel]), direct 747 configuration, or other means. 749 An alias is used in subsequent signal channel exchanges to refer 750 more efficiently to the resources under attack. 752 This is an optional attribute. 754 lifetime: Lifetime of the mitigation request in seconds. The 755 RECOMMENDED lifetime of a mitigation request is 3600 seconds -- 756 this value was chosen to be long enough so that refreshing is not 757 typically a burden on the DOTS client, while still making the 758 request expire in a timely manner when the client has unexpectedly 759 quit. DOTS clients MUST include this parameter in their 760 mitigation requests. Upon the expiry of this lifetime, and if the 761 request is not refreshed, the mitigation request is removed. The 762 request can be refreshed by sending the same request again. 764 A lifetime of '0' in a mitigation request is an invalid value. 766 A lifetime of negative one (-1) indicates indefinite lifetime for 767 the mitigation request. The DOTS server MAY refuse indefinite 768 lifetime, for policy reasons; the granted lifetime value is 769 returned in the response. DOTS clients MUST be prepared to not be 770 granted mitigations with indefinite lifetimes. 772 The DOTS server MUST always indicate the actual lifetime in the 773 response and the remaining lifetime in status messages sent to the 774 DOTS client. 776 This is a mandatory attribute. 778 trigger-mitigation: If the parameter value is set to 'false', DDoS 779 mitigation will not be triggered for the mitigation request unless 780 the DOTS signal channel session is lost. 782 If the DOTS client ceases to respond to heartbeat messages, the 783 DOTS server can detect that the DOTS signal channel session is 784 lost. 786 The default value of the parameter is 'true' (that is, the 787 mitigation starts immediately). If 'trigger-mitigation' is not 788 present in a request, this is equivalent to receiving a request 789 with 'trigger-mitigation' set to 'true'. 791 This is an optional attribute. 793 In deployments where server-domain DOTS gateways are enabled, 794 identity information about the origin source client domain SHOULD be 795 propagated to the DOTS server. That information is meant to assist 796 the DOTS server to enforce some policies such as grouping DOTS 797 clients that belong to the same DOTS domain, limiting the number of 798 DOTS requests, and identifying the mitigation scope. These policies 799 can be enforced per-client, per-client domain, or both. Also, the 800 identity information may be used for auditing and debugging purposes. 802 Figure 7 shows an example of a request relayed by a server-domain 803 DOTS gateway. 805 Header: PUT (Code=0.03) 806 Uri-Path: ".well-known" 807 Uri-Path: "dots" 808 Uri-Path: "mitigate" 809 Uri-Path: "cdid=7eeaf349529eb55ed50113" 810 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 811 Uri-Path: "mid=123" 812 Content-Format: "application/dots+cbor" 813 { 814 ... 815 } 817 Figure 7: PUT for DOTS Mitigation Request as Relayed by a DOTS 818 Gateway 820 A server-domain DOTS gateway SHOULD add the following Uri-Path 821 parameter: 823 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed 824 by a server-domain DOTS gateway to propagate the source domain 825 identity from the gateway's client-facing-side to the gateway's 826 server-facing-side, and from the gateway's server-facing-side to 827 the DOTS server. 'cdid' may be used by the final DOTS server for 828 policy enforcement purposes (e.g., enforce a quota on filtering 829 rules). These policies are deployment-specific. 831 Server-domain DOTS gateways SHOULD support a configuration option 832 to instruct whether 'cdid' parameter is to be inserted. 834 In order to accommodate deployments that require enforcing per- 835 client policies, per-client domain policies, or a combination 836 thereof, server-domain DOTS gateways instructed to insert the 837 'cdid' parameter MUST supply the SPKI hash of the DOTS client 838 X.509 certificate, the DOTS client raw public key, or the hash of 839 the "PSK identity" in the 'cdid', following the same rules for 840 generating the hash conveyed in 'cuid', which is then used by the 841 ultimate DOTS server to determine the corresponding client's 842 domain. The 'cdid' generated by a server-domain gateway is likely 843 to be the same as the 'cuid' except if the DOTS message was 844 relayed by a client-domain DOTS gateway or the 'cuid' was 845 generated from a rogue DOTS client. 847 If a DOTS client is provisioned, for example, with distinct 848 certificates as a function of the peer server-domain DOTS gateway, 849 distinct 'cdid' values may be supplied by a server-domain DOTS 850 gateway. The ultimate DOTS server MUST treat those 'cdid' values 851 as equivalent. 853 The 'cdid' attribute MUST NOT be generated and included by DOTS 854 clients. 856 DOTS servers MUST ignore 'cdid' attributes that are directly 857 supplied by source DOTS clients or client-domain DOTS gateways. 858 This implies that first server-domain DOTS gateways MUST strip 859 'cdid' attributes supplied by DOTS clients. DOTS servers SHOULD 860 support a configuration parameter to identify DOTS gateways that 861 are trusted to supply 'cdid' attributes. 863 Only single-valued 'cdid' are defined in this document. That is, 864 only the first on-path server-domain DOTS gateway can insert a 865 'cdid' value. This specification does not allow multiple server- 866 domain DOTS gateways, whenever involved in the path, to insert a 867 'cdid' value for each server-domain gateway. 869 This is an optional Uri-Path. When present, 'cdid' MUST be 870 positioned before 'cuid'. 872 A DOTS gateway MAY add the CoAP Hop-Limit Option 873 [I-D.ietf-core-hop-limit]. 875 Because of the complexity to handle partial failure cases, this 876 specification does not allow for including multiple mitigation 877 requests in the same PUT request. Concretely, a DOTS client MUST NOT 878 include multiple entries in the 'scope' array of the same PUT 879 request. 881 FQDN and URI mitigation scopes may be thought of as a form of scope 882 alias, in which the addresses associated with the domain name or URI 883 (as resolved by the DOTS server) represent the full scope of the 884 mitigation. 886 In the PUT request at least one of the attributes 'target-prefix', 887 'target-fqdn','target-uri', or 'alias-name' MUST be present. 889 Attributes and Uri-Path parameters with empty values MUST NOT be 890 present in a request and render the entire request invalid. 892 Figure 8 shows a PUT request example to signal that TCP port numbers 893 80, 8080, and 443 used by 2001:db8:6401::1 and 2001:db8:6401::2 894 servers are under attack (illustrated in JSON diagnostic notation). 895 The presence of 'cdid' indicates that a server-domain DOTS gateway 896 has modified the initial PUT request sent by the DOTS client. Note 897 that 'cdid' MUST NOT appear in the PUT request message body. 899 Header: PUT (Code=0.03) 900 Uri-Path: ".well-known" 901 Uri-Path: "dots" 902 Uri-Path: "mitigate" 903 Uri-Path: "cdid=7eeaf349529eb55ed50113" 904 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 905 Uri-Path: "mid=123" 906 Content-Format: "application/dots+cbor" 907 { 908 "ietf-dots-signal-channel:mitigation-scope": { 909 "scope": [ 910 { 911 "target-prefix": [ 912 "2001:db8:6401::1/128", 913 "2001:db8:6401::2/128" 914 ], 915 "target-port-range": [ 916 { 917 "lower-port": 80 918 }, 919 { 920 "lower-port": 443 921 }, 922 { 923 "lower-port": 8080 924 } 925 ], 926 "target-protocol": [ 927 6 928 ], 929 "lifetime": 3600 930 } 931 ] 932 } 933 } 935 Figure 8: PUT for DOTS Mitigation Request (An Example) 937 The corresponding CBOR encoding format for the payload is shown in 938 Figure 9. 940 A1 # map(1) 941 01 # unsigned(1) 942 A1 # map(1) 943 02 # unsigned(2) 944 81 # array(1) 945 A3 # map(3) 946 06 # unsigned(6) 947 82 # array(2) 948 74 # text(20) 949 323030313A6462383A363430313A3A312F313238 950 74 # text(20) 951 323030313A6462383A363430313A3A322F313238 952 07 # unsigned(7) 953 83 # array(3) 954 A1 # map(1) 955 08 # unsigned(8) 956 18 50 # unsigned(80) 957 A1 # map(1) 958 08 # unsigned(8) 959 19 01BB # unsigned(443) 960 A1 # map(1) 961 08 # unsigned(8) 962 19 1F90 # unsigned(8080) 963 0A # unsigned(10) 964 81 # array(1) 965 06 # unsigned(6) 966 0E # unsigned(14) 967 19 0E10 # unsigned(3600) 969 Figure 9: PUT for DOTS Mitigation Request (CBOR) 971 In both DOTS signal and data channel sessions, the DOTS client MUST 972 authenticate itself to the DOTS server (Section 8). The DOTS server 973 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 974 the DOTS client identity or username from the client certificate. 975 The DOTS client identity allows the DOTS server to accept mitigation 976 requests with scopes that the DOTS client is authorized to manage. 978 The DOTS server couples the DOTS signal and data channel sessions 979 using the DOTS client identity and optionally the 'cdid' parameter 980 value, so the DOTS server can validate whether the aliases conveyed 981 in the mitigation request were indeed created by the same DOTS client 982 using the DOTS data channel session. If the aliases were not created 983 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 984 the response. 986 The DOTS server couples the DOTS signal channel sessions using the 987 DOTS client identity and optionally the 'cdid' parameter value, and 988 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 989 detect duplicate mitigation requests. If the mitigation request 990 contains the 'alias-name' and other parameters identifying the target 991 resources (such as 'target-prefix', 'target-port-range', 'target- 992 fqdn', or 'target-uri'), the DOTS server appends the parameter values 993 in 'alias-name' with the corresponding parameter values in 'target- 994 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 996 The DOTS server indicates the result of processing the PUT request 997 using CoAP response codes. CoAP 2.xx codes are success. CoAP 4.xx 998 codes are some sort of invalid requests (client errors). COAP 5.xx 999 codes are returned if the DOTS server is in an error state or is 1000 currently unavailable to provide mitigation in response to the 1001 mitigation request from the DOTS client. 1003 Figure 10 shows an example response to a PUT request that is 1004 successfully processed by a DOTS server (i.e., CoAP 2.xx response 1005 codes). This version of the specification forbids 'cuid' and 'cdid' 1006 (if used) to be returned in a response message body. 1008 { 1009 "ietf-dots-signal-channel:mitigation-scope": { 1010 "scope": [ 1011 { 1012 "mid": 123, 1013 "lifetime": 3600 1014 } 1015 ] 1016 } 1017 } 1019 Figure 10: 2.xx Response Body 1021 If the request is missing a mandatory attribute, does not include 1022 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1023 parameters, or contains invalid or unknown parameters, the DOTS 1024 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1025 ignore comprehension-optional parameters they don't understand. 1027 A DOTS server that receives a mitigation request with a lifetime set 1028 to '0' MUST reply with a 4.00 (Bad Request). 1030 If the DOTS server does not find the 'mid' parameter value conveyed 1031 in the PUT request in its configuration data, it MAY accept the 1032 mitigation request by sending back a 2.01 (Created) response to the 1033 DOTS client; the DOTS server will consequently try to mitigate the 1034 attack. A DOTS server could reject mitigation requests when it is 1035 near capacity or needs to rate-limit a particular client, for 1036 example. 1038 If the DOTS server finds the 'mid' parameter value conveyed in the 1039 PUT request in its configuration data bound to that DOTS client, it 1040 MAY update the mitigation request, and a 2.04 (Changed) response is 1041 returned to indicate a successful update of the mitigation request. 1043 The relative order of two mitigation requests, having the same 1044 'trigger-mitigation' type, from a DOTS client is determined by 1045 comparing their respective 'mid' values. If two mitigation requests 1046 with the same 'trigger-mitigation' type have overlapping mitigation 1047 scopes, the mitigation request with the highest numeric 'mid' value 1048 will override the other mitigation request. Two mitigation requests 1049 from a DOTS client have overlapping scopes if there is a common IP 1050 address, IP prefix, FQDN, URI, or alias-name. To avoid maintaining a 1051 long list of overlapping mitigation requests (i.e., requests with the 1052 same 'trigger-mitigation' type and overlapping scopes) from a DOTS 1053 client and avoid error-prone provisioning of mitigation requests from 1054 a DOTS client, the overlapped lower numeric 'mid' MUST be 1055 automatically deleted and no longer available at the DOTS server. 1056 For example, if the DOTS server receives a mitigation request which 1057 overlaps with an existing mitigation with a higher numeric 'mid', the 1058 DOTS server rejects the request by returning 4.09 (Conflict) to the 1059 DOTS client. The response includes enough information for a DOTS 1060 client to recognize the source of the conflict as described below in 1061 the 'conflict-information' subtree with only the relevant nodes 1062 listed: 1064 conflict-information: Indicates that a mitigation request is 1065 conflicting with another mitigation request. This optional 1066 attribute has the following structure: 1068 conflict-cause: Indicates the cause of the conflict. The 1069 following values are defined: 1071 1: Overlapping targets. 'conflict-scope' provides more details 1072 about the conflicting target clauses. 1074 conflict-scope: Characterizes the exact conflict scope. It may 1075 include a list of IP addresses, a list of prefixes, a list of 1076 port numbers, a list of target protocols, a list of FQDNs, a 1077 list of URIs, a list of alias-names, or a 'mid'. 1079 If the DOTS server receives a mitigation request which overlaps with 1080 an active mitigation request, but both having distinct 'trigger- 1081 mitigation' types, the DOTS server MUST deactivate (absent explicit 1082 policy/configuration otherwise) the mitigation request with 'trigger- 1083 mitigation' set to false. Particularly, if the mitigation request 1084 with 'trigger-mitigation' set to false is active, the DOTS server 1085 withdraws the mitigation request (i.e., status code is set to '7' as 1086 defined in Table 2) and transitions the status of the mitigation 1087 request to '8'. 1089 Upon DOTS signal channel session loss with a peer DOTS client, the 1090 DOTS server MUST withdraw (absent explicit policy/configuration 1091 otherwise) any active mitigation requests overlapping with mitigation 1092 requests having 'trigger-mitigation' set to false from that DOTS 1093 client, as the loss of the session implictily activates these 1094 preconfigured mitigation requests and they take precedence. Note 1095 that active-but-terminating period is not observed for mitigations 1096 withdrawn at the initiative of the DOTS server. 1098 DOTS clients may adopt various strategies for setting the scopes of 1099 immediate and pre-configured mitigation requests to avoid potential 1100 conflicts. For example, a DOTS client may tweak pre-configured 1101 scopes so that the scope of any overlapping immediate mitigation 1102 request will be a subset of the pre-configured scopes. Also, if an 1103 immediate mitigation request overlaps with any of the pre-configured 1104 scopes, the DOTS client sets the scope of the overlapping immediate 1105 mitigation request to be a subset of the pre-configured scopes, so as 1106 to get a broad mitigation when the DOTS signal channel collapses and 1107 maximize the chance of recovery. 1109 If the request is conflicting with an existing mitigation request 1110 from a different DOTS client, the DOTS server may return 2.01 1111 (Created) or 4.09 (Conflict) to the requesting DOTS client. If the 1112 DOTS server decides to maintain the new mitigation request, the DOTS 1113 server returns 2.01 (Created) to the requesting DOTS client. If the 1114 DOTS server decides to reject the new mitigation request, the DOTS 1115 server returns 4.09 (Conflict) to the requesting DOTS client. For 1116 both 2.01 (Created) and 4.09 (Conflict) responses, the response 1117 includes enough information for a DOTS client to recognize the source 1118 of the conflict as described below: 1120 conflict-information: Indicates that a mitigation request is 1121 conflicting with another mitigation request(s) from other DOTS 1122 client(s). This optional attribute has the following structure: 1124 conflict-status: Indicates the status of a conflicting mitigation 1125 request. The following values are defined: 1127 1: DOTS server has detected conflicting mitigation requests 1128 from different DOTS clients. This mitigation request is 1129 currently inactive until the conflicts are resolved. 1130 Another mitigation request is active. 1132 2: DOTS server has detected conflicting mitigation requests 1133 from different DOTS clients. This mitigation request is 1134 currently active. 1136 3: DOTS server has detected conflicting mitigation requests 1137 from different DOTS clients. All conflicting mitigation 1138 requests are inactive. 1140 conflict-cause: Indicates the cause of the conflict. The 1141 following values are defined: 1143 1: Overlapping targets. 'conflict-scope' provides more details 1144 about the conflicting target clauses. 1146 2: Conflicts with an existing accept-list. This code is 1147 returned when the DDoS mitigation detects source addresses/ 1148 prefixes in the accept-listed ACLs are attacking the 1149 target. 1151 3: CUID Collision. This code is returned when a DOTS client 1152 uses a 'cuid' that is already used by another DOTS client. 1153 This code is an indication that the request has been 1154 rejected and a new request with a new 'cuid' is to be re- 1155 sent by the DOTS client (see the example shown in 1156 Figure 11). Note that 'conflict-status', 'conflict-scope', 1157 and 'retry-timer' MUST NOT be returned in the error 1158 response. 1160 conflict-scope: Characterizes the exact conflict scope. It may 1161 include a list of IP addresses, a list of prefixes, a list of 1162 port numbers, a list of target protocols, a list of FQDNs, a 1163 list of URIs, a list of alias-names, or references to 1164 conflicting ACLs (by an 'acl-name', typically 1165 [I-D.ietf-dots-data-channel]). 1167 retry-timer: Indicates, in seconds, the time after which the DOTS 1168 client may re-issue the same request. The DOTS server returns 1169 'retry-timer' only to DOTS client(s) for which a mitigation 1170 request is deactivated. Any retransmission of the same 1171 mitigation request before the expiry of this timer is likely to 1172 be rejected by the DOTS server for the same reasons. 1174 The retry-timer SHOULD be equal to the lifetime of the active 1175 mitigation request resulting in the deactivation of the 1176 conflicting mitigation request. The lifetime of the 1177 deactivated mitigation request will be updated to (retry-timer 1178 + 45 seconds), so the DOTS client can refresh the deactivated 1179 mitigation request after retry-timer seconds before expiry of 1180 lifetime and check if the conflict is resolved. 1182 Header: PUT (Code=0.03) 1183 Uri-Path: ".well-known" 1184 Uri-Path: "dots" 1185 Uri-Path: "mitigate" 1186 Uri-Path: "cuid=7eeaf349529eb55ed50113" 1187 Uri-Path: "mid=12" 1189 (1) Request with a conflicting 'cuid' 1191 Header: PUT (Code=0.03) 1192 Uri-Path: ".well-known" 1193 Uri-Path: "dots" 1194 Uri-Path: "mitigate" 1195 Uri-Path: "cuid=f30d281ce6b64fc5a0b91e" 1196 Uri-Path: "mid=12" 1198 (2) Request with a new 'cuid' 1200 Figure 11: Example of Generating a New 'cuid' 1202 As an active attack evolves, DOTS clients can adjust the scope of 1203 requested mitigation as necessary, by refining the scope of resources 1204 requiring mitigation. This can be achieved by sending a PUT request 1205 with a new 'mid' value that will override the existing one with 1206 overlapping mitigation scopes. 1208 For a mitigation request to continue beyond the initial negotiated 1209 lifetime, the DOTS client has to refresh the current mitigation 1210 request by sending a new PUT request. This PUT request MUST use the 1211 same 'mid' value, and MUST repeat all the other parameters as sent in 1212 the original mitigation request apart from a possible change to the 1213 lifetime parameter value. 1215 4.4.2. Retrieve Information Related to a Mitigation 1217 A GET request is used by a DOTS client to retrieve information 1218 (including status) of DOTS mitigations from a DOTS server. 1220 'cuid' is a mandatory Uri-Path parameter for GET requests. 1222 Uri-Path parameters with empty values MUST NOT be present in a 1223 request. 1225 The same considerations for manipulating 'cdid' parameter by server- 1226 domain DOTS gateways specified in Section 4.4.1 MUST be followed for 1227 GET requests. 1229 The 'c' (content) parameter and its permitted values defined in 1230 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1231 (attack mitigation status), configuration data, or both. The DOTS 1232 server MAY support this optional filtering capability. It can safely 1233 ignore it if not supported. If the DOTS client supports the optional 1234 filtering capability, it SHOULD use "c=n" query (to get back only the 1235 dynamically changing data) or "c=c" query (to get back the static 1236 configuration values) when the DDoS attack is active to limit the 1237 size of the response. 1239 The DOTS client can use Block-wise transfer [RFC7959] to get the list 1240 of all its mitigations maintained by a DOTS server, it can send 1241 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1242 size of the response. If the representation of all the active 1243 mitigation requests associated with the DOTS client does not fit 1244 within a single datagram, the DOTS server MUST use the Block2 Option 1245 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1246 in the response to indicate the total size of the resource 1247 representation. The DOTS client retrieves the rest of the 1248 representation by sending additional GET requests with Block2 Options 1249 containing NUM values greater than zero. The DOTS client MUST adhere 1250 to the block size preferences indicated by the DOTS server in the 1251 response. If the DOTS server uses the Block2 Option in the GET 1252 response and the response is for a dynamically changing resource 1253 (e.g. "c=n" or "c=a" query), the DOTS server MUST include the ETag 1254 Option in the response. The DOTS client MUST include the same ETag 1255 value in subsequent GET requests to retrieve the rest of the 1256 representation. 1258 The following examples illustrate how a DOTS client retrieves active 1259 mitigation requests from a DOTS server. In particular: 1261 o Figure 12 shows the example of a GET request to retrieve all DOTS 1262 mitigation requests signaled by a DOTS client. 1264 o Figure 13 shows the example of a GET request to retrieve a 1265 specific DOTS mitigation request signaled by a DOTS client. The 1266 configuration data to be reported in the response is formatted in 1267 the same order as was processed by the DOTS server in the original 1268 mitigation request. 1270 These two examples assume the default of "c=a"; that is, the DOTS 1271 client asks for all data to be reported by the DOTS server. 1273 Header: GET (Code=0.01) 1274 Uri-Path: ".well-known" 1275 Uri-Path: "dots" 1276 Uri-Path: "mitigate" 1277 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1278 Observe: 0 1280 Figure 12: GET to Retrieve all DOTS Mitigation Requests 1282 Header: GET (Code=0.01) 1283 Uri-Path: ".well-known" 1284 Uri-Path: "dots" 1285 Uri-Path: "mitigate" 1286 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1287 Uri-Path: "mid=12332" 1288 Observe: 0 1290 Figure 13: GET to Retrieve a Specific DOTS Mitigation Request 1292 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1293 the GET request in its configuration data for the requesting DOTS 1294 client, it MUST respond with a 4.04 (Not Found) error response code. 1295 Likewise, the same error MUST be returned as a response to a request 1296 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1297 defined) of a given DOTS client if the DOTS server does not find any 1298 mitigation record for that DOTS client. As a reminder, a DOTS client 1299 is identified by its identity (e.g., client certificate, 'cuid') and 1300 optionally the 'cdid'. 1302 Figure 14 shows a response example of all active mitigation requests 1303 associated with the DOTS client as maintained by the DOTS server. 1304 The response indicates the mitigation status of each mitigation 1305 request. 1307 { 1308 "ietf-dots-signal-channel:mitigation-scope": { 1309 "scope": [ 1310 { 1311 "mid": 12332, 1312 "mitigation-start": "1507818434", 1313 "target-prefix": [ 1314 "2001:db8:6401::1/128", 1315 "2001:db8:6401::2/128" 1316 ], 1317 "target-protocol": [ 1318 17 1319 ], 1320 "lifetime": 1756, 1321 "status": "attack-successfully-mitigated", 1322 "bytes-dropped": "134334555", 1323 "bps-dropped": "43344", 1324 "pkts-dropped": "333334444", 1325 "pps-dropped": "432432" 1326 }, 1327 { 1328 "mid": 12333, 1329 "mitigation-start": "1507818393", 1330 "target-prefix": [ 1331 "2001:db8:6401::1/128", 1332 "2001:db8:6401::2/128" 1333 ], 1334 "target-protocol": [ 1335 6 1336 ], 1337 "lifetime": 1755, 1338 "status": "attack-stopped", 1339 "bytes-dropped": "0", 1340 "bps-dropped": "0", 1341 "pkts-dropped": "0", 1342 "pps-dropped": "0" 1343 } 1344 ] 1345 } 1346 } 1348 Figure 14: Response Body to a GET Request 1350 The mitigation status parameters are described below: 1352 mitigation-start: Mitigation start time is expressed in seconds 1353 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1355 [RFC7049]). The CBOR encoding is modified so that the leading tag 1356 1 (epoch-based date/time) MUST be omitted. 1358 This is a mandatory attribute when an attack mitigation is active. 1359 Particularly, 'mitigation-start' is not returned for a mitigation 1360 with 'status' code set to 8. 1362 lifetime: The remaining lifetime of the mitigation request, in 1363 seconds. 1365 This is a mandatory attribute. 1367 status: Status of attack mitigation. The various possible values of 1368 'status' parameter are explained in Table 2. 1370 This is a mandatory attribute. 1372 bytes-dropped: The total dropped byte count for the mitigation 1373 request since the attack mitigation is triggered. The count wraps 1374 around when it reaches the maximum value of unsigned integer64. 1376 This is an optional attribute. 1378 bps-dropped: The average number of dropped bytes per second for the 1379 mitigation request since the attack mitigation is triggered. This 1380 average SHOULD be over five-minute intervals. 1382 This is an optional attribute. 1384 pkts-dropped: The total number of dropped packet count for the 1385 mitigation request since the attack mitigation is triggered. The 1386 count wraps around when it reaches the maximum value of unsigned 1387 integer64. 1389 This is an optional attribute. 1391 pps-dropped: The average number of dropped packets per second for 1392 the mitigation request since the attack mitigation is triggered. 1393 This average SHOULD be over five-minute intervals. 1395 This is an optional attribute. 1397 +-----------+-------------------------------------------------------+ 1398 | Parameter | Description | 1399 | Value | | 1400 +-----------+-------------------------------------------------------+ 1401 | 1 | Attack mitigation setup is in progress (e.g., | 1402 | | changing the network path to redirect the inbound | 1403 | | traffic to a DOTS mitigator). | 1404 +-----------+-------------------------------------------------------+ 1405 | 2 | Attack is being successfully mitigated (e.g., traffic | 1406 | | is redirected to a DDoS mitigator and attack traffic | 1407 | | is dropped). | 1408 +-----------+-------------------------------------------------------+ 1409 | 3 | Attack has stopped and the DOTS client can withdraw | 1410 | | the mitigation request. This status code will be | 1411 | | transmitted for immediate mitigation requests till | 1412 | | the mitigation is withdrawn or the lifetime expires. | 1413 | | For mitigation requests with pre-configured scopes | 1414 | | (i.e., 'trigger-mitigation' set to 'false'), this | 1415 | | status code will be transmitted 4 times and then | 1416 | | transition to "8". | 1417 +-----------+-------------------------------------------------------+ 1418 | 4 | Attack has exceeded the mitigation provider | 1419 | | capability. | 1420 +-----------+-------------------------------------------------------+ 1421 | 5 | DOTS client has withdrawn the mitigation request and | 1422 | | the mitigation is active but terminating. | 1423 +-----------+-------------------------------------------------------+ 1424 | 6 | Attack mitigation is now terminated. | 1425 +-----------+-------------------------------------------------------+ 1426 | 7 | Attack mitigation is withdrawn (by the DOTS server). | 1427 | | If a mitigation request with 'trigger-mitigation' set | 1428 | | to false is withdrawn because it overlaps with an | 1429 | | immediate mitigation request, this status code will | 1430 | | be transmitted 4 times and then transition to "8" for | 1431 | | the mitigation request with pre-configured scopes. | 1432 +-----------+-------------------------------------------------------+ 1433 | 8 | Attack mitigation will be triggered for the | 1434 | | mitigation request only when the DOTS signal channel | 1435 | | session is lost. | 1436 +-----------+-------------------------------------------------------+ 1438 Table 2: Values of 'status' Parameter 1440 4.4.2.1. DOTS Servers Sending Mitigation Status 1442 The Observe Option defined in [RFC7641] extends the CoAP core 1443 protocol with a mechanism for a CoAP client to "observe" a resource 1444 on a CoAP server: The client retrieves a representation of the 1445 resource and requests this representation be updated by the server as 1446 long as the client is interested in the resource. DOTS 1447 implementations MUST use the Observe Option for both 'mitigate' and 1448 'config' (Section 4.2). 1450 A DOTS client conveys the Observe Option set to '0' in the GET 1451 request to receive asynchronous notifications of attack mitigation 1452 status from the DOTS server. 1454 Unidirectional mitigation notifications within the bidirectional 1455 signal channel enables asynchronous notifications between the agents. 1456 [RFC7641] indicates that (1) a notification can be sent in a 1457 Confirmable or a Non-confirmable message, and (2) the message type 1458 used is typically application dependent and may be determined by the 1459 server for each notification individually. For DOTS server 1460 application, the message type MUST always be set to Non-confirmable 1461 even if the underlying COAP library elects a notification to be sent 1462 in a Confirmable message. 1464 Due to the higher likelihood of packet loss during a DDoS attack, the 1465 DOTS server periodically sends attack mitigation status to the DOTS 1466 client and also notifies the DOTS client whenever the status of the 1467 attack mitigation changes. If the DOTS server cannot maintain an RTT 1468 estimate, it SHOULD NOT send more than one asynchronous notification 1469 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1470 possible (case 2 in Section 3.1.3 of [RFC8085]). 1472 When conflicting requests are detected, the DOTS server enforces the 1473 corresponding policy (e.g., accept all requests, reject all requests, 1474 accept only one request but reject all the others, ...). It is 1475 assumed that this policy is supplied by the DOTS server administrator 1476 or it is a default behavior of the DOTS server implementation. Then, 1477 the DOTS server sends notification message(s) to the DOTS client(s) 1478 at the origin of the conflict (refer to the conflict parameters 1479 defined in Section 4.4.1). A conflict notification message includes 1480 information about the conflict cause, scope, and the status of the 1481 mitigation request(s). For example, 1483 o A notification message with 'status' code set to '7 (Attack 1484 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1485 to a DOTS client to indicate that an active mitigation request is 1486 deactivated because a conflict is detected. 1488 o A notification message with 'status' code set to '1 (Attack 1489 mitigation is in progress)' and 'conflict-status' set to '2' is 1490 sent to a DOTS client to indicate that this mitigation request is 1491 in progress, but a conflict is detected. 1493 Upon receipt of a conflict notification message indicating that a 1494 mitigation request is deactivated because of a conflict, a DOTS 1495 client MUST NOT resend the same mitigation request before the expiry 1496 of 'retry-timer'. It is also recommended that DOTS clients support 1497 means to alert administrators about mitigation conflicts. 1499 A DOTS client that is no longer interested in receiving notifications 1500 from the DOTS server can simply "forget" the observation. When the 1501 DOTS server sends the next notification, the DOTS client will not 1502 recognize the token in the message and thus will return a Reset 1503 message. This causes the DOTS server to remove the associated entry. 1504 Alternatively, the DOTS client can explicitly deregister itself by 1505 issuing a GET request that has the Token field set to the token of 1506 the observation to be cancelled and includes an Observe Option with 1507 the value set to '1' (deregister). The latter is RECOMMENDED. 1509 Figure 15 shows an example of a DOTS client requesting a DOTS server 1510 to send notifications related to a mitigation request. Note that for 1511 mitigations with pre-configured scopes (i.e., 'trigger-mitigation' 1512 set to 'false'), the state will need to transition from 3 (attack- 1513 stopped) to 8 (attack-mitigation-signal-loss). 1515 +-----------+ +-----------+ 1516 |DOTS client| |DOTS server| 1517 +-----------+ +-----------+ 1518 | | 1519 | GET / | 1520 | Token: 0x4a | Registration 1521 | Observe: 0 | 1522 +----------------------------------------->| 1523 | | 1524 | 2.05 Content | 1525 | Token: 0x4a | Notification of 1526 | Observe: 12 | the current state 1527 | status: "attack-mitigation-in-progress" | 1528 | | 1529 |<-----------------------------------------+ 1530 | 2.05 Content | 1531 | Token: 0x4a | Notification upon 1532 | Observe: 44 | a state change 1533 | status: "attack-successfully-mitigated" | 1534 | | 1535 |<-----------------------------------------+ 1536 | 2.05 Content | 1537 | Token: 0x4a | Notification upon 1538 | Observe: 60 | a state change 1539 | status: "attack-stopped" | 1540 |<-----------------------------------------+ 1541 | | 1542 ... 1544 Figure 15: Notifications of Attack Mitigation Status 1546 4.4.2.2. DOTS Clients Polling for Mitigation Status 1548 The DOTS client can send the GET request at frequent intervals 1549 without the Observe Option to retrieve the configuration data of the 1550 mitigation request and non-configuration data (i.e., the attack 1551 status). The frequency of polling the DOTS server to get the 1552 mitigation status SHOULD follow the transmission guidelines in 1553 Section 3.1.3 of [RFC8085]. 1555 If the DOTS server has been able to mitigate the attack and the 1556 attack has stopped, the DOTS server indicates as such in the status. 1557 In such case, the DOTS client recalls the mitigation request by 1558 issuing a DELETE request for this mitigation request (Section 4.4.4). 1560 A DOTS client SHOULD react to the status of the attack as per the 1561 information sent by the DOTS server rather than performing its own 1562 detection that the attack has been mitigated. This ensures that the 1563 DOTS client does not recall a mitigation request prematurely because 1564 it is possible that the DOTS client does not sense the DDoS attack on 1565 its resources, but the DOTS server could be actively mitigating the 1566 attack because the attack is not completely averted. 1568 4.4.3. Efficacy Update from DOTS Clients 1570 While DDoS mitigation is in progress, due to the likelihood of packet 1571 loss, a DOTS client MAY periodically transmit DOTS mitigation 1572 efficacy updates to the relevant DOTS server. A PUT request is used 1573 to convey the mitigation efficacy update to the DOTS server. This 1574 PUT request is treated as a refresh of the current mitigation. 1576 The PUT request used for efficacy update MUST include all the 1577 parameters used in the PUT request to carry the DOTS mitigation 1578 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1579 value. If this is not the case, the DOTS server MUST reject the 1580 request with a 4.00 (Bad Request). 1582 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1583 value is used to make the PUT request conditional on the current 1584 existence of the mitigation request. If UDP is used as transport, 1585 CoAP requests may arrive out-of-order. For example, the DOTS client 1586 may send a PUT request to convey an efficacy update to the DOTS 1587 server followed by a DELETE request to withdraw the mitigation 1588 request, but the DELETE request arrives at the DOTS server before the 1589 PUT request. To handle out-of-order delivery of requests, if an If- 1590 Match Option is present in the PUT request and the 'mid' in the 1591 request matches a mitigation request from that DOTS client, the 1592 request is processed by the DOTS server. If no match is found, the 1593 PUT request is silently ignored by the DOTS server. 1595 An example of an efficacy update message, which includes an If-Match 1596 Option with an empty value, is depicted in Figure 16. 1598 Header: PUT (Code=0.03) 1599 Uri-Path: ".well-known" 1600 Uri-Path: "dots" 1601 Uri-Path: "mitigate" 1602 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1603 Uri-Path: "mid=123" 1604 Content-Format: "application/dots+cbor" 1605 If-Match: 1606 { 1607 "ietf-dots-signal-channel:mitigation-scope": { 1608 "scope": [ 1609 { 1610 "target-prefix": [ 1611 "2001:db8:6401::1/128", 1612 "2001:db8:6401::2/128" 1613 ], 1614 "target-port-range": [ 1615 { 1616 "lower-port": 80 1617 }, 1618 { 1619 "lower-port": 443 1620 }, 1621 { 1622 "lower-port": 8080 1623 } 1624 ], 1625 "target-protocol": [ 1626 6 1627 ], 1628 "attack-status": "under-attack" 1629 } 1630 ] 1631 } 1632 } 1634 Figure 16: An Example of Efficacy Update 1636 The 'attack-status' parameter is a mandatory attribute when 1637 performing an efficacy update. The various possible values contained 1638 in the 'attack-status' parameter are described in Table 3. 1640 +-----------+-------------------------------------------------------+ 1641 | Parameter | Description | 1642 | value | | 1643 +-----------+-------------------------------------------------------+ 1644 | 1 | The DOTS client determines that it is still under | 1645 | | attack. | 1646 +-----------+-------------------------------------------------------+ 1647 | 2 | The DOTS client determines that the attack is | 1648 | | successfully mitigated (e.g., attack traffic is not | 1649 | | seen). | 1650 +-----------+-------------------------------------------------------+ 1652 Table 3: Values of 'attack-status' Parameter 1654 The DOTS server indicates the result of processing a PUT request 1655 using CoAP response codes. The response code 2.04 (Changed) is 1656 returned if the DOTS server has accepted the mitigation efficacy 1657 update. The error response code 5.03 (Service Unavailable) is 1658 returned if the DOTS server has erred or is incapable of performing 1659 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age option 1660 to indicate the number of seconds after which to retry. 1662 4.4.4. Withdraw a Mitigation 1664 DELETE requests are used to withdraw DOTS mitigation requests from 1665 DOTS servers (Figure 17). 1667 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1668 requests. 1670 The same considerations for manipulating 'cdid' parameter by DOTS 1671 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1672 requests. Uri-Path parameters with empty values MUST NOT be present 1673 in a request. 1675 Header: DELETE (Code=0.04) 1676 Uri-Path: ".well-known" 1677 Uri-Path: "dots" 1678 Uri-Path: "mitigate" 1679 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1680 Uri-Path: "mid=123" 1682 Figure 17: Withdraw a DOTS Mitigation 1684 If the DELETE request does not include 'cuid' and 'mid' parameters, 1685 the DOTS server MUST reply with a 4.00 (Bad Request). 1687 Once the request is validated, the DOTS server immediately 1688 acknowledges a DOTS client's request to withdraw the DOTS signal 1689 using 2.02 (Deleted) response code with no response payload. A 2.02 1690 (Deleted) Response Code is returned even if the 'mid' parameter value 1691 conveyed in the DELETE request does not exist in its configuration 1692 data before the request. 1694 If the DOTS server finds the 'mid' parameter value conveyed in the 1695 DELETE request in its configuration data for the DOTS client, then to 1696 protect against route or DNS flapping caused by a DOTS client rapidly 1697 removing a mitigation, and to dampen the effect of oscillating 1698 attacks, the DOTS server MAY allow mitigation to continue for a 1699 limited period after acknowledging a DOTS client's withdrawal of a 1700 mitigation request. During this period, the DOTS server status 1701 messages SHOULD indicate that mitigation is active but terminating 1702 (Section 4.4.2). 1704 The initial active-but-terminating period SHOULD be sufficiently long 1705 to absorb latency incurred by route propagation. The active-but- 1706 terminating period SHOULD be set by default to 120 seconds. If the 1707 client requests mitigation again before the initial active-but- 1708 terminating period elapses, the DOTS server MAY exponentially 1709 increase (the base of the exponent is 2) the active-but-terminating 1710 period up to a maximum of 300 seconds (5 minutes). 1712 Once the active-but-terminating period elapses, the DOTS server MUST 1713 treat the mitigation as terminated, as the DOTS client is no longer 1714 responsible for the mitigation. For example, if there is a financial 1715 relationship between the DOTS client and server domains, the DOTS 1716 client stops incurring cost at this point. 1718 If a mitigation is triggered due to a signal channel loss, the DOTS 1719 server relies upon normal triggers to stop that mitigation 1720 (typically, receipt of a valid DELETE request, expiry of the 1721 mitigation lifetime, or scrubbing the traffic to the attack target). 1722 In particular, the DOTS server MUST NOT consider the signal channel 1723 recovery as a trigger to stop the mitigation. 1725 4.5. DOTS Signal Channel Session Configuration 1727 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1728 channel session behavior with its DOTS peers. The DOTS signal 1729 channel can be used, for example, to configure the following: 1731 a. Heartbeat interval (heartbeat-interval): DOTS agents regularly 1732 send heartbeats (CoAP Ping/Pong) to each other after mutual 1733 authentication is successfully completed in order to keep the 1734 DOTS signal channel open. Heartbeat messages are exchanged 1735 between DOTS agents every 'heartbeat-interval' seconds to detect 1736 the current status of the DOTS signal channel session. 1738 b. Missing heartbeats allowed (missing-hb-allowed): This variable 1739 indicates the maximum number of consecutive heartbeat messages 1740 for which a DOTS agent did not receive a response before 1741 concluding that the session is disconnected or defunct. 1743 c. Acceptable signal loss ratio: Maximum retransmissions, 1744 retransmission timeout value, and other message transmission 1745 parameters for the DOTS signal channel. 1747 The same or distinct configuration sets may be used during times when 1748 a mitigation is active ('mitigating-config') and when no mitigation 1749 is active ('idle-config'). This is particularly useful for DOTS 1750 servers that might want to reduce heartbeat frequency or cease 1751 heartbeat exchanges when an active DOTS client has not requested 1752 mitigation. If distinct configurations are used, DOTS agents MUST 1753 follow the appropriate configuration set as a function of the 1754 mitigation activity (e.g., if no mitigation request is active (also 1755 referred to as 'idle' time), 'idle-config'-related values must be 1756 followed). Additionally, DOTS agents MUST automatically switch to 1757 the other configuration upon a change in the mitigation activity 1758 (e.g., if an attack mitigation is launched after an 'idle' time, the 1759 DOTS agent switches from 'idle-config' to 'mitigating-config'-related 1760 values). 1762 CoAP Requests and responses are indicated for reliable delivery by 1763 marking them as Confirmable messages. DOTS signal channel session 1764 configuration requests and responses are marked as Confirmable 1765 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1766 message is retransmitted using a default timeout and exponential 1767 back-off between retransmissions, until the DOTS server sends an 1768 Acknowledgement message (ACK) with the same Message ID conveyed from 1769 the DOTS client. 1771 Message transmission parameters are defined in Section 4.8 of 1772 [RFC7252]. The DOTS server can either piggyback the response in the 1773 acknowledgement message or, if the DOTS server cannot respond 1774 immediately to a request carried in a Confirmable message, it simply 1775 responds with an Empty Acknowledgement message so that the DOTS 1776 client can stop retransmitting the request. Empty Acknowledgement 1777 messages are explained in Section 2.2 of [RFC7252]. When the 1778 response is ready, the server sends it in a new Confirmable message 1779 which in turn needs to be acknowledged by the DOTS client (see 1780 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1781 exchanged between DOTS agents during 'idle' time are marked as 1782 Confirmable messages. 1784 Implementation Note: A DOTS client that receives a response in a 1785 Confirmable message may want to clean up the message state right 1786 after sending the ACK. If that ACK is lost and the DOTS server 1787 retransmits the Confirmable message, the DOTS client may no longer 1788 have any state that would help it correlate this response: from 1789 the DOTS client's standpoint, the retransmission message is 1790 unexpected. The DOTS client will send a Reset message so it does 1791 not receive any more retransmissions. This behavior is normal and 1792 not an indication of an error (see Section 5.3.2 of [RFC7252] for 1793 more details). 1795 4.5.1. Discover Configuration Parameters 1797 A GET request is used to obtain acceptable (e.g., minimum and maximum 1798 values) and current configuration parameters on the DOTS server for 1799 DOTS signal channel session configuration. This procedure occurs 1800 between a DOTS client and its immediate peer DOTS server. As such, 1801 this GET request MUST NOT be relayed by a DOTS gateway. 1803 Figure 18 shows how to obtain acceptable configuration parameters for 1804 the DOTS server. 1806 Header: GET (Code=0.01) 1807 Uri-Path: ".well-known" 1808 Uri-Path: "dots" 1809 Uri-Path: "config" 1811 Figure 18: GET to Retrieve Configuration 1813 The DOTS server in the 2.05 (Content) response conveys the current, 1814 minimum, and maximum attribute values acceptable by the DOTS server 1815 (Figure 19). 1817 Content-Format: "application/dots+cbor" 1818 { 1819 "ietf-dots-signal-channel:signal-config": { 1820 "mitigating-config": { 1821 "heartbeat-interval": { 1822 "max-value": number, 1823 "min-value": number, 1824 "current-value": number 1825 }, 1826 "missing-hb-allowed": { 1827 "max-value": number, 1828 "min-value": number, 1829 "current-value": number 1830 }, 1831 "max-retransmit": { 1832 "max-value": number, 1833 "min-value": number, 1834 "current-value": number 1835 }, 1836 "ack-timeout": { 1837 "max-value-decimal": "string", 1838 "min-value-decimal": "string", 1839 "current-value-decimal": "string" 1840 }, 1841 "ack-random-factor": { 1842 "max-value-decimal": "string", 1843 "min-value-decimal": "string", 1844 "current-value-decimal": "string" 1845 } 1846 }, 1847 "idle-config": { 1848 "heartbeat-interval": { 1849 "max-value": number, 1850 "min-value": number, 1851 "current-value": number 1852 }, 1853 "missing-hb-allowed": { 1854 "max-value": number, 1855 "min-value": number, 1856 "current-value": number 1857 }, 1858 "max-retransmit": { 1859 "max-value": number, 1860 "min-value": number, 1861 "current-value": number 1862 }, 1863 "ack-timeout": { 1864 "max-value-decimal": "string", 1865 "min-value-decimal": "string", 1866 "current-value-decimal": "string" 1867 }, 1868 "ack-random-factor": { 1869 "max-value-decimal": "string", 1870 "min-value-decimal": "string", 1871 "current-value-decimal": "string" 1872 } 1873 } 1874 } 1875 } 1877 Figure 19: GET Configuration Response Body Schema 1879 The parameters in Figure 19 are described below: 1881 mitigating-config: Set of configuration parameters to use when a 1882 mitigation is active. The following parameters may be included: 1884 heartbeat-interval: Time interval in seconds between two 1885 consecutive heartbeat messages. 1887 '0' is used to disable the heartbeat mechanism. 1889 This is an optional attribute. 1891 missing-hb-allowed: Maximum number of consecutive heartbeat 1892 messages for which the DOTS agent did not receive a response 1893 before concluding that the session is disconnected. 1895 This is an optional attribute. 1897 max-retransmit: Maximum number of retransmissions for a message 1898 (referred to as MAX_RETRANSMIT parameter in CoAP). 1900 This is an optional attribute. 1902 ack-timeout: Timeout value in seconds used to calculate the 1903 initial retransmission timeout value (referred to as 1904 ACK_TIMEOUT parameter in CoAP). 1906 This is an optional attribute. 1908 ack-random-factor: Random factor used to influence the timing of 1909 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 1910 CoAP). 1912 This is an optional attribute. 1914 idle-config: Set of configuration parameters to use when no 1915 mitigation is active. This attribute has the same structure as 1916 'mitigating-config'. 1918 Figure 20 shows an example of acceptable and current configuration 1919 parameters on a DOTS server for DOTS signal channel session 1920 configuration. The same acceptable configuration is used during 1921 mitigation and idle times. 1923 Content-Format: "application/dots+cbor" 1924 { 1925 "ietf-dots-signal-channel:signal-config": { 1926 "mitigating-config": { 1927 "heartbeat-interval": { 1928 "max-value": 240, 1929 "min-value": 15, 1930 "current-value": 30 1931 }, 1932 "missing-hb-allowed": { 1933 "max-value": 9, 1934 "min-value": 3, 1935 "current-value": 5 1936 }, 1937 "max-retransmit": { 1938 "max-value": 15, 1939 "min-value": 2, 1940 "current-value": 3 1941 }, 1942 "ack-timeout": { 1943 "max-value-decimal": "30.00", 1944 "min-value-decimal": "1.00", 1945 "current-value-decimal": "2.00" 1946 }, 1947 "ack-random-factor": { 1948 "max-value-decimal": "4.00", 1949 "min-value-decimal": "1.10", 1950 "current-value-decimal": "1.50" 1951 } 1952 }, 1953 "idle-config": { 1954 "heartbeat-interval": { 1955 "max-value": 240, 1956 "min-value": 15, 1957 "current-value": 30 1958 }, 1959 "missing-hb-allowed": { 1960 "max-value": 9, 1961 "min-value": 3, 1962 "current-value": 5 1963 }, 1964 "max-retransmit": { 1965 "max-value": 15, 1966 "min-value": 2, 1967 "current-value": 3 1968 }, 1969 "ack-timeout": { 1970 "max-value-decimal": "30.00", 1971 "min-value-decimal": "1.00", 1972 "current-value-decimal": "2.00" 1973 }, 1974 "ack-random-factor": { 1975 "max-value-decimal": "4.00", 1976 "min-value-decimal": "1.10", 1977 "current-value-decimal": "1.50" 1978 } 1979 } 1980 } 1981 } 1983 Figure 20: Example of a Configuration Response Body 1985 4.5.2. Convey DOTS Signal Channel Session Configuration 1987 A PUT request (Figures 21 and 22) is used to convey the configuration 1988 parameters for the signal channel (e.g., heartbeat interval, maximum 1989 retransmissions). Message transmission parameters for CoAP are 1990 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 1991 transmission parameter values are ack-timeout (2 seconds), max- 1992 retransmit (3), ack-random-factor (1.5). In addition to those 1993 parameters, the RECOMMENDED specific DOTS transmission parameter 1994 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 1995 (5). 1997 Note: heartbeat-interval should be tweaked to also assist DOTS 1998 messages for NAT traversal (SIG-011 of 1999 [I-D.ietf-dots-requirements]). According to [RFC8085], keepalive 2000 messages must not be sent more frequently than once every 15 2001 seconds and should use longer intervals when possible. 2002 Furthermore, [RFC4787] recommends NATs to use a state timeout of 2 2003 minutes or longer, but experience shows that sending packets every 2004 15 to 30 seconds is necessary to prevent the majority of 2005 middleboxes from losing state for UDP flows. From that 2006 standpoint, this specification recommends a minimum heartbeat- 2007 interval of 15 seconds and a maximum heartbeat-interval of 240 2008 seconds. The recommended value of 30 seconds is selected to 2009 anticipate the expiry of NAT state. 2011 A heartbeat-interval of 30 seconds may be considered as too chatty 2012 in some deployments. For such deployments, DOTS agents may 2013 negotiate longer heartbeat-interval values to prevent any network 2014 overload with too frequent keepalives. 2016 Different heartbeat intervals can be defined for 'mitigating- 2017 config' and 'idle-config' to reduce being too chatty during idle 2018 times. If there is an on-path translator between the DOTS client 2019 (standalone or part of a DOTS gateway) and the DOTS server, the 2020 'mitigating-config' heartbeat-interval has to be smaller than the 2021 translator session timeout. It is recommended that the 'idle- 2022 config' heartbeat-interval is also smaller than the translator 2023 session timeout to prevent translator traversal issues, or 2024 disabled entirely. Means to discover the lifetime assigned by a 2025 translator are out of scope. 2027 When a Confirmable "CoAP Ping" is sent, and if there is no response, 2028 the "CoAP Ping" is retransmitted max-retransmit number of times by 2029 the CoAP layer using an initial timeout set to a random duration 2030 between ack-timeout and (ack-timeout*ack-random-factor) and 2031 exponential back-off between retransmissions. By choosing the 2032 recommended transmission parameters, the "CoAP Ping" will timeout 2033 after 45 seconds. If the DOTS agent does not receive any response 2034 from the peer DOTS agent for 'missing-hb-allowed' number of 2035 consecutive "CoAP Ping" Confirmable messages, it concludes that the 2036 DOTS signal channel session is disconnected. A DOTS client MUST NOT 2037 transmit a "CoAP Ping" while waiting for the previous "CoAP Ping" 2038 response from the same DOTS server. 2040 If the DOTS agent wishes to change the default values of message 2041 transmission parameters, it SHOULD follow the guidance given in 2042 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2043 values for message transmission parameters and default values for 2044 non-negotiated message transmission parameters. 2046 The signal channel session configuration is applicable to a single 2047 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2048 Path MUST NOT be used. 2050 Header: PUT (Code=0.03) 2051 Uri-Path: ".well-known" 2052 Uri-Path: "dots" 2053 Uri-Path: "config" 2054 Uri-Path: "sid=123" 2055 Content-Format: "application/dots+cbor" 2056 { 2057 ... 2058 } 2060 Figure 21: PUT to Convey the DOTS Signal Channel Session 2061 Configuration Data 2063 The additional Uri-Path parameter to those defined in Table 1 is as 2064 follows: 2066 sid: Session Identifier is an identifier for the DOTS signal channel 2067 session configuration data represented as an integer. This 2068 identifier MUST be generated by DOTS clients. 'sid' values MUST 2069 increase monotonically (when a new PUT is generated by a DOTS 2070 client to convey the configuration parameters for the signal 2071 channel). 2073 This is a mandatory attribute. 2075 Content-Format: "application/dots+cbor" 2076 { 2077 "ietf-dots-signal-channel:signal-config": { 2078 "mitigating-config": { 2079 "heartbeat-interval": { 2080 "current-value": number 2081 }, 2082 "missing-hb-allowed": { 2083 "current-value": number 2084 }, 2085 "max-retransmit": { 2086 "current-value": number 2087 }, 2088 "ack-timeout": { 2089 "current-value-decimal": "string" 2090 }, 2091 "ack-random-factor": { 2092 "current-value-decimal": "string" 2093 } 2094 }, 2095 "idle-config": { 2096 "heartbeat-interval": { 2097 "current-value": number 2098 }, 2099 "missing-hb-allowed": { 2100 "current-value": number 2101 }, 2102 "max-retransmit": { 2103 "current-value": number 2104 }, 2105 "ack-timeout": { 2106 "current-value-decimal": "string" 2107 }, 2108 "ack-random-factor": { 2109 "current-value-decimal": "string" 2110 } 2111 } 2112 } 2113 } 2115 Figure 22: PUT to Convey the DOTS Signal Channel Session 2116 Configuration Data (Message Body Schema) 2118 The meaning of the parameters in the CBOR body (Figure 22) is defined 2119 in Section 4.5.1. 2121 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2122 allowed', 'max-retransmit', 'ack-timeout', and 'ack-random-factor' 2123 MUST be present in the PUT request. Note that 'heartbeat-interval', 2124 'missing-hb-allowed', 'max-retransmit', 'ack-timeout', and 'ack- 2125 random-factor', if present, do not need to be provided for both 2126 'mitigating-config', and 'idle-config' in a PUT request. 2128 The PUT request with a higher numeric 'sid' value overrides the DOTS 2129 signal channel session configuration data installed by a PUT request 2130 with a lower numeric 'sid' value. To avoid maintaining a long list 2131 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2132 automatically deleted and no longer available at the DOTS server. 2134 Figure 23 shows a PUT request example to convey the configuration 2135 parameters for the DOTS signal channel. In this example, the 2136 heartbeat mechanism is disabled when no mitigation is active, while 2137 the heartbeat interval is set to '91' when a mitigation is active. 2139 Header: PUT (Code=0.03) 2140 Uri-Path: ".well-known" 2141 Uri-Path: "dots" 2142 Uri-Path: "config" 2143 Uri-Path: "sid=123" 2144 Content-Format: "application/dots+cbor" 2145 { 2146 "ietf-dots-signal-channel:signal-config": { 2147 "mitigating-config": { 2148 "heartbeat-interval": { 2149 "current-value": 91 2150 }, 2151 "missing-hb-allowed": { 2152 "current-value": 3 2153 }, 2154 "max-retransmit": { 2155 "current-value": 3 2156 }, 2157 "ack-timeout": { 2158 "current-value-decimal": "2.00" 2159 }, 2160 "ack-random-factor": { 2161 "current-value-decimal": "1.50" 2162 } 2163 }, 2164 "idle-config": { 2165 "heartbeat-interval": { 2166 "current-value": 0 2167 }, 2168 "max-retransmit": { 2169 "current-value": 3 2170 }, 2171 "ack-timeout": { 2172 "current-value-decimal": "2.00" 2173 }, 2174 "ack-random-factor": { 2175 "current-value-decimal": "1.50" 2176 } 2177 } 2178 } 2179 } 2181 Figure 23: PUT to Convey the Configuration Parameters 2183 The DOTS server indicates the result of processing the PUT request 2184 using CoAP response codes: 2186 o If the request is missing a mandatory attribute, does not include 2187 a 'sid' Uri-Path, or contains one or more invalid or unknown 2188 parameters, 4.00 (Bad Request) MUST be returned in the response. 2190 o If the DOTS server does not find the 'sid' parameter value 2191 conveyed in the PUT request in its configuration data and if the 2192 DOTS server has accepted the configuration parameters, then a 2193 response code 2.01 (Created) MUST be returned in the response. 2195 o If the DOTS server finds the 'sid' parameter value conveyed in the 2196 PUT request in its configuration data and if the DOTS server has 2197 accepted the updated configuration parameters, 2.04 (Changed) MUST 2198 be returned in the response. 2200 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 'max- 2201 retransmit', 'target-protocol', 'ack-timeout', and 'ack-random- 2202 factor' attribute values are not acceptable to the DOTS server, 2203 4.22 (Unprocessable Entity) MUST be returned in the response. 2204 Upon receipt of this error code, the DOTS client SHOULD retrieve 2205 the maximum and minimum attribute values acceptable to the DOTS 2206 server (Section 4.5.1). 2208 The DOTS client may re-try and send the PUT request with updated 2209 attribute values acceptable to the DOTS server. 2211 A DOTS client may issue a GET message with 'sid' Uri-Path parameter 2212 to retrieve the negotiated configuration. The response does not need 2213 to include 'sid' in its message body. 2215 4.5.3. Configuration Freshness and Notifications 2217 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2218 DOTS server to associate a validity time with a configuration it 2219 sends. This feature allows the update of the configuration data if a 2220 change occurs at the DOTS server side. For example, the new 2221 configuration may instruct a DOTS client to cease heartbeats or 2222 reduce heartbeat frequency. 2224 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2226 Returning a Max-Age Option set to 2**32-1 is equivalent to 2227 associating an infinite lifetime with the configuration. 2229 If a non-zero value of Max-Age Option is received by a DOTS client, 2230 it MUST issue a GET request with 'sid' Uri-Path parameter to retrieve 2231 the current and acceptable configuration before the expiry of the 2232 value enclosed in the Max-Age option. This request is considered by 2233 the client and the server as a means to refresh the configuration 2234 parameters for the signal channel. When a DDoS attack is active, 2235 refresh requests MUST NOT be sent by DOTS clients and the DOTS server 2236 MUST NOT terminate the (D)TLS session after the expiry of the value 2237 returned in Max-Age Option. 2239 If Max-Age Option is not returned in a response, the DOTS client 2240 initiates GET requests to refresh the configuration parameters each 2241 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2242 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2243 responses. Considerations related to which value to use and how such 2244 value is set, are implementation- and deployment-specific. 2246 If an Observe Option set to 0 is included in the configuration 2247 request, the DOTS server sends notifications of any configuration 2248 change (Section 4.2 of [RFC7641]). 2250 If a DOTS server detects that a misbehaving DOTS client does not 2251 contact the DOTS server after the expiry of Max-Age and retrieve the 2252 signal channel configuration data, it MAY terminate the (D)TLS 2253 session. A (D)TLS session is terminated by the receipt of an 2254 authenticated message that closes the connection (e.g., a fatal alert 2255 (Section 6 of [RFC8446])). 2257 4.5.4. Delete DOTS Signal Channel Session Configuration 2259 A DELETE request is used to delete the installed DOTS signal channel 2260 session configuration data (Figure 24). 2262 Header: DELETE (Code=0.04) 2263 Uri-Path: ".well-known" 2264 Uri-Path: "dots" 2265 Uri-Path: "config" 2266 Uri-Path: "sid=123" 2268 Figure 24: Delete Configuration 2270 The DOTS server resets the DOTS signal channel session configuration 2271 back to the default values and acknowledges a DOTS client's request 2272 to remove the DOTS signal channel session configuration using 2.02 2273 (Deleted) response code. 2275 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2276 to set the configuration parameters to default values. Such a 2277 request does not include any 'sid'. 2279 4.6. Redirected Signaling 2281 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2282 [I-D.ietf-dots-architecture]. 2284 If a DOTS server wants to redirect a DOTS client to an alternative 2285 DOTS server for a signal session, then the response code 5.03 2286 (Service Unavailable) will be returned in the response to the DOTS 2287 client. 2289 The DOTS server can return the error response code 5.03 in response 2290 to a request from the DOTS client or convey the error response code 2291 5.03 in a unidirectional notification response from the DOTS server. 2293 The DOTS server in the error response conveys the alternate DOTS 2294 server's FQDN, and the alternate DOTS server's IP address(es) values 2295 in the CBOR body (Figure 25). 2297 { 2298 "ietf-dots-signal-channel:redirected-signal": { 2299 "alt-server": "string", 2300 "alt-server-record": [ 2301 "string" 2302 ] 2303 } 2305 Figure 25: Redirected Server Error Response Body Schema 2307 The parameters are described below: 2309 alt-server: FQDN of an alternate DOTS server. 2311 This is a mandatory attribute. 2313 alt-server-record: A list of IP addresses of an alternate DOTS 2314 server. 2316 This is an optional attribute. 2318 The DOTS server returns the Time to live (TTL) of the alternate DOTS 2319 server in a Max-Age Option. That is, the time interval that the 2320 alternate DOTS server may be cached for use by a DOTS client. A Max- 2321 Age Option set to 2**32-1 is equivalent to receiving an infinite TTL. 2322 This value means that the alternate DOTS server is to be used until 2323 the alternate DOTS server redirects the traffic with another 5.03 2324 response which encloses an alternate server. 2326 A Max-Age Option set to '0' may be returned for redirecting 2327 mitigation requests. Such value means that the redirection applies 2328 only for the mitigation request in progress. Returning short TTL in 2329 a Max-Age Option may adversely impact DOTS clients on slow links. 2330 Returning short values should be avoided under such conditions. 2332 If the alternate DOTS server TTL has expired, the DOTS client MUST 2333 use the DOTS server(s), that was provisioned using means discussed in 2334 Section 4.1. This fall back mechanism is triggered immediately upon 2335 expiry of the TTL, except when a DDoS attack is active. 2337 Requests issued by misbehaving DOTS clients which do not honor the 2338 TTL conveyed in the Max-Age Option or react to explicit re-direct 2339 messages can be rejected by DOTS servers. 2341 Figure 26 shows a 5.03 response example to convey the DOTS alternate 2342 server 'alt-server.example' together with its IP addresses 2343 2001:db8:6401::1 and 2001:db8:6401::2. 2345 { 2346 "ietf-dots-signal-channel:redirected-signal": { 2347 "alt-server": "alt-server.example", 2348 "alt-server-record": [ 2349 "2001:db8:6401::1", 2350 "2001:db8:6401::2" 2351 ] 2352 } 2354 Figure 26: Example of Redirected Server Error Response Body 2356 When the DOTS client receives 5.03 response with an alternate server 2357 included, it considers the current request as failed, but SHOULD try 2358 re-sending the request to the alternate DOTS server. During a DDoS 2359 attack, the DNS server may be the target of another DDoS attack, 2360 alternate DOTS server's IP addresses conveyed in the 5.03 response 2361 help the DOTS client skip DNS lookup of the alternate DOTS server, at 2362 the cost of trusting the first DOTS server to provide accurate 2363 information. The DOTS client can then try to establish a UDP or a 2364 TCP session with the alternate DOTS server. The DOTS client MAY 2365 implement a method to construct IPv4-embedded IPv6 addresses 2366 [RFC6052]; this is required to handle the scenario where an IPv6-only 2367 DOTS client communicates with an IPv4-only alternate DOTS server. 2369 If the DOTS client has been redirected to a DOTS server to which it 2370 has already communicated with within the last five (5) minutes, it 2371 MUST ignore the redirection and try to contact other DOTS servers 2372 listed in the local configuration or discovered using dynamic means 2373 such as DHCP or SRV procedures. It is RECOMMENDED that DOTS clients 2374 support means to alert administrators about redirect loops. 2376 4.7. Heartbeat Mechanism 2378 To provide an indication of signal health and distinguish an 'idle' 2379 signal channel from a 'disconnected' or 'defunct' session, the DOTS 2380 agent sends a heartbeat over the signal channel to maintain its half 2381 of the channel. The DOTS agent similarly expects a heartbeat from 2382 its peer DOTS agent, and may consider a session terminated in the 2383 prolonged absence of a peer agent heartbeat. Concretely, while the 2384 communication between the DOTS agents is otherwise quiescent, the 2385 DOTS client will probe the DOTS server to ensure it has maintained 2386 cryptographic state and vice versa. Such probes can also keep 2387 firewalls and/or stateful translators bindings alive. This probing 2388 reduces the frequency of establishing a new handshake when a DOTS 2389 signal needs to be conveyed to the DOTS server. 2391 DOTS servers MAY trigger their heartbeat requests immediately after 2392 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2393 is the responsibility of DOTS clients to ensure that on-path 2394 translators/firewalls are maintaining a binding so that the same 2395 external IP address and/or port number is retained for the DOTS 2396 signal channel session. 2398 In case of a massive DDoS attack that saturates the incoming link(s) 2399 to the DOTS client, all traffic from the DOTS server to the DOTS 2400 client will likely be dropped, although the DOTS server receives 2401 heartbeat requests in addition to DOTS messages sent by the DOTS 2402 client. In this scenario, the DOTS agents MUST behave differently to 2403 handle message transmission and DOTS signal channel session 2404 liveliness during link saturation: 2406 o The DOTS client MUST NOT consider the DOTS signal channel session 2407 terminated even after a maximum 'missing-hb-allowed' threshold is 2408 reached. The DOTS client SHOULD keep on using the current DOTS 2409 signal channel session to send heartbeat requests over it, so that 2410 the DOTS server knows the DOTS client has not disconnected the 2411 DOTS signal channel session. 2413 After the maximum 'missing-hb-allowed' threshold is reached, the 2414 DOTS client SHOULD try to resume the (D)TLS session. The DOTS 2415 client SHOULD send mitigation requests over the current DOTS 2416 signal channel session, and in parallel, for example, try to 2417 resume the (D)TLS session or use 0-RTT mode in DTLS 1.3 to 2418 piggyback the mitigation request in the ClientHello message. 2420 As soon as the link is no longer saturated, if traffic from the 2421 DOTS server reaches the DOTS client over the current DOTS signal 2422 channel session, the DOTS client can stop (D)TLS session 2423 resumption or if (D)TLS session resumption is successful then 2424 disconnect the current DOTS signal channel session. 2426 o If the DOTS server does not receive any traffic from the peer DOTS 2427 client, then the DOTS server sends heartbeat requests to the DOTS 2428 client and after maximum 'missing-hb-allowed' threshold is 2429 reached, the DOTS server concludes the session is disconnected. 2431 In DOTS over UDP, heartbeat messages MUST be exchanged between the 2432 DOTS agents using the "CoAP Ping" mechanism defined in Section 4.2 of 2433 [RFC7252]. Concretely, the DOTS agent sends an Empty Confirmable 2434 message and the peer DOTS agent will respond by sending a Reset 2435 message. 2437 In DOTS over TCP, heartbeat messages MUST be exchanged between the 2438 DOTS agents using the Ping and Pong messages specified in Section 5.4 2439 of [RFC8323]. That is, the DOTS agent sends a Ping message and the 2440 peer DOTS agent would respond by sending a single Pong message. 2442 5. DOTS Signal Channel YANG Modules 2444 This document defines a YANG [RFC7950] module for DOTS mitigation 2445 scope, DOTS signal channel session configuration data, and DOTS 2446 redirection signalling. 2448 This YANG module (ietf-dots-signal-channel) defines the DOTS client 2449 interaction with the DOTS server as seen by the DOTS client. A DOTS 2450 server is allowed to update the non-configurable 'ro' entities in the 2451 responses. This YANG module is not intended to be used via NETCONF/ 2452 RESTCONF for DOTS server management purposes; such module is out of 2453 the scope of this document. It serves only to provide a data model 2454 and encoding, but not a management data model. 2456 A companion YANG module is defined to include a collection of types 2457 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2459 5.1. Tree Structure 2461 This document defines the YANG module "ietf-dots-signal-channel" 2462 (Section 5.3), which has the following tree structure. A DOTS signal 2463 message can either be a mitigation or a configuration message. 2465 module: ietf-dots-signal-channel 2466 +--rw dots-signal 2467 +--rw (message-type)? 2468 +--:(mitigation-scope) 2469 | +--rw scope* [cuid mid] 2470 | +--rw cdid? string 2471 | +--rw cuid string 2472 | +--rw mid uint32 2473 | +--rw target-prefix* inet:ip-prefix 2474 | +--rw target-port-range* [lower-port] 2475 | | +--rw lower-port inet:port-number 2476 | | +--rw upper-port? inet:port-number 2477 | +--rw target-protocol* uint8 2478 | +--rw target-fqdn* inet:domain-name 2479 | +--rw target-uri* inet:uri 2480 | +--rw alias-name* string 2481 | +--rw lifetime? int32 2482 | +--rw trigger-mitigation? boolean 2483 | +--ro mitigation-start? uint64 2484 | +--ro status? iana-signal:status 2485 | +--ro conflict-information 2486 | | +--ro conflict-status? iana-signal:conflict-status 2487 | | +--ro conflict-cause? iana-signal:conflict-cause 2488 | | +--ro retry-timer? uint32 2489 | | +--ro conflict-scope 2490 | | +--ro target-prefix* inet:ip-prefix 2491 | | +--ro target-port-range* [lower-port] 2492 | | | +--ro lower-port inet:port-number 2493 | | | +--ro upper-port? inet:port-number 2494 | | +--ro target-protocol* uint8 2495 | | +--ro target-fqdn* inet:domain-name 2496 | | +--ro target-uri* inet:uri 2497 | | +--ro alias-name* string 2498 | | +--ro acl-list* [acl-name] 2499 | | | +--ro acl-name 2500 | | | | -> /ietf-data:dots-data/dots-client/acls/ 2501 | | | | acl/name 2502 | | | +--ro acl-type? 2503 | | | -> /ietf-data:dots-data/dots-client/acls/ 2504 | | | acl/type 2505 | | +--ro mid? -> ../../../mid 2506 | +--ro bytes-dropped? yang:zero-based-counter64 2507 | +--ro bps-dropped? yang:zero-based-counter64 2508 | +--ro pkts-dropped? yang:zero-based-counter64 2509 | +--ro pps-dropped? yang:zero-based-counter64 2510 | +--rw attack-status? iana-signal:attack-status 2511 +--:(signal-config) 2512 | +--rw sid uint32 2513 | +--rw mitigating-config 2514 | | +--rw heartbeat-interval 2515 | | | +--ro max-value? uint16 2516 | | | +--ro min-value? uint16 2517 | | | +--rw current-value? uint16 2518 | | +--rw missing-hb-allowed 2519 | | | +--ro max-value? uint16 2520 | | | +--ro min-value? uint16 2521 | | | +--rw current-value? uint16 2522 | | +--rw max-retransmit 2523 | | | +--ro max-value? uint16 2524 | | | +--ro min-value? uint16 2525 | | | +--rw current-value? uint16 2526 | | +--rw ack-timeout 2527 | | | +--ro max-value-decimal? decimal64 2528 | | | +--ro min-value-decimal? decimal64 2529 | | | +--rw current-value-decimal? decimal64 2530 | | +--rw ack-random-factor 2531 | | +--ro max-value-decimal? decimal64 2532 | | +--ro min-value-decimal? decimal64 2533 | | +--rw current-value-decimal? decimal64 2534 | +--rw idle-config 2535 | +--rw heartbeat-interval 2536 | | +--ro max-value? uint16 2537 | | +--ro min-value? uint16 2538 | | +--rw current-value? uint16 2539 | +--rw missing-hb-allowed 2540 | | +--ro max-value? uint16 2541 | | +--ro min-value? uint16 2542 | | +--rw current-value? uint16 2543 | +--rw max-retransmit 2544 | | +--ro max-value? uint16 2545 | | +--ro min-value? uint16 2546 | | +--rw current-value? uint16 2547 | +--rw ack-timeout 2548 | | +--ro max-value-decimal? decimal64 2549 | | +--ro min-value-decimal? decimal64 2550 | | +--rw current-value-decimal? decimal64 2551 | +--rw ack-random-factor 2552 | +--ro max-value-decimal? decimal64 2553 | +--ro min-value-decimal? decimal64 2554 | +--rw current-value-decimal? decimal64 2555 +--:(redirected-signal) 2556 +--ro alt-server string 2557 +--ro alt-server-record* inet:ip-address 2559 5.2. IANA DOTS Signal Channel YANG Module 2561 file "iana-dots-signal-channel@2019-01-17.yang" 2562 module iana-dots-signal-channel { 2563 yang-version 1.1; 2564 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2565 prefix iana-signal; 2567 organization 2568 "IANA"; 2569 contact 2570 "Internet Assigned Numbers Authority 2572 Postal: ICANN 2573 12025 Waterfront Drive, Suite 300 2574 Los Angeles, CA 90094-2536 2575 United States of America 2576 Tel: +1 310 301 5800 2577 "; 2578 description 2579 "This module contains a collection of YANG data types defined 2580 by IANA and used for DOTS signal channel protocol. 2582 Copyright (c) 2019 IETF Trust and the persons identified as 2583 authors of the code. All rights reserved. 2585 Redistribution and use in source and binary forms, with or 2586 without modification, is permitted pursuant to, and subject 2587 to the license terms contained in, the Simplified BSD License 2588 set forth in Section 4.c of the IETF Trust's Legal Provisions 2589 Relating to IETF Documents 2590 (http://trustee.ietf.org/license-info). 2592 This version of this YANG module is part of RFC XXXX; see 2593 the RFC itself for full legal notices."; 2595 revision 2019-01-17 { 2596 description 2597 "Initial revision."; 2598 reference 2599 "RFC XXXX: Distributed Denial-of-Service Open Threat 2600 Signaling (DOTS) Signal Channel Specification"; 2601 } 2603 typedef status { 2604 type enumeration { 2605 enum attack-mitigation-in-progress { 2606 value 1; 2607 description 2608 "Attack mitigation setup is in progress (e.g., changing 2609 the network path to re-route the inbound traffic 2610 to DOTS mitigator)."; 2611 } 2612 enum attack-successfully-mitigated { 2613 value 2; 2614 description 2615 "Attack is being successfully mitigated (e.g., traffic 2616 is redirected to a DDoS mitigator and attack 2617 traffic is dropped or blackholed)."; 2618 } 2619 enum attack-stopped { 2620 value 3; 2621 description 2622 "Attack has stopped and the DOTS client can 2623 withdraw the mitigation request."; 2624 } 2625 enum attack-exceeded-capability { 2626 value 4; 2627 description 2628 "Attack has exceeded the mitigation provider 2629 capability."; 2630 } 2631 enum dots-client-withdrawn-mitigation { 2632 value 5; 2633 description 2634 "DOTS client has withdrawn the mitigation 2635 request and the mitigation is active but 2636 terminating."; 2637 } 2638 enum attack-mitigation-terminated { 2639 value 6; 2640 description 2641 "Attack mitigation is now terminated."; 2642 } 2643 enum attack-mitigation-withdrawn { 2644 value 7; 2645 description 2646 "Attack mitigation is withdrawn."; 2647 } 2648 enum attack-mitigation-signal-loss { 2649 value 8; 2650 description 2651 "Attack mitigation will be triggered 2652 for the mitigation request only when 2653 the DOTS signal channel session is lost."; 2654 } 2655 } 2656 description 2657 "Enumeration for status reported by the DOTS server."; 2658 } 2659 typedef conflict-status { 2660 type enumeration { 2661 enum request-inactive-other-active { 2662 value 1; 2663 description 2664 "DOTS Server has detected conflicting mitigation 2665 requests from different DOTS clients. 2666 This mitigation request is currently inactive 2667 until the conflicts are resolved. Another 2668 mitigation request is active."; 2669 } 2670 enum request-active { 2671 value 2; 2672 description 2673 "DOTS Server has detected conflicting mitigation 2674 requests from different DOTS clients. 2675 This mitigation request is currently active."; 2676 } 2677 enum all-requests-inactive { 2678 value 3; 2679 description 2680 "DOTS Server has detected conflicting mitigation 2681 requests from different DOTS clients. All 2682 conflicting mitigation requests are inactive."; 2683 } 2684 } 2685 description 2686 "Enumeration for conflict status."; 2687 } 2689 typedef conflict-cause { 2690 type enumeration { 2691 enum overlapping-targets { 2692 value 1; 2693 description 2694 "Overlapping targets. conflict-scope provides 2695 more details about the exact conflict."; 2696 } 2697 enum conflict-with-acceptlist { 2698 value 2; 2699 description 2700 "Conflicts with an existing accept-list. 2702 This code is returned when the DDoS mitigation 2703 detects that some of the source addresses/prefixes 2704 listed in the accept-list ACLs are actually 2705 attacking the target."; 2706 } 2707 enum cuid-collision { 2708 value 3; 2709 description 2710 "Conflicts with the cuid used by another 2711 DOTS client."; 2712 } 2713 } 2714 description 2715 "Enumeration for conflict causes."; 2716 } 2718 typedef attack-status { 2719 type enumeration { 2720 enum under-attack { 2721 value 1; 2722 description 2723 "The DOTS client determines that it is still under 2724 attack."; 2725 } 2726 enum attack-successfully-mitigated { 2727 value 2; 2728 description 2729 "The DOTS client determines that the attack is 2730 successfully mitigated."; 2731 } 2732 } 2733 description 2734 "Enumeration for attack status codes."; 2735 } 2736 } 2737 2739 5.3. IETF DOTS Signal Channel YANG Module 2741 This module uses the common YANG types defined in [RFC6991] and types 2742 defined in [I-D.ietf-dots-data-channel]. 2744 file "ietf-dots-signal-channel@2019-01-17.yang" 2745 module ietf-dots-signal-channel { 2746 yang-version 1.1; 2747 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 2748 prefix signal; 2750 import ietf-inet-types { 2751 prefix inet; 2752 reference "Section 4 of RFC 6991"; 2753 } 2754 import ietf-yang-types { 2755 prefix yang; 2756 reference "Section 3 of RFC 6991"; 2757 } 2758 import ietf-dots-data-channel { 2759 prefix ietf-data; 2760 reference 2761 "RFC YYYY: Distributed Denial-of-Service Open Threat Signaling 2762 (DOTS) Data Channel Specification"; 2763 } 2764 import iana-dots-signal-channel { 2765 prefix iana-signal; 2766 } 2768 organization 2769 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 2770 contact 2771 "WG Web: 2772 WG List: 2774 Editor: Konda, Tirumaleswar Reddy 2775 2777 Editor: Mohamed Boucadair 2778 2780 Author: Prashanth Patil 2781 2783 Author: Andrew Mortensen 2784 2786 Author: Nik Teague 2787 "; 2788 description 2789 "This module contains YANG definition for the signaling 2790 messages exchanged between a DOTS client and a DOTS server. 2792 Copyright (c) 2019 IETF Trust and the persons identified as 2793 authors of the code. All rights reserved. 2795 Redistribution and use in source and binary forms, with or 2796 without modification, is permitted pursuant to, and subject 2797 to the license terms contained in, the Simplified BSD License 2798 set forth in Section 4.c of the IETF Trust's Legal Provisions 2799 Relating to IETF Documents 2800 (http://trustee.ietf.org/license-info). 2802 This version of this YANG module is part of RFC XXXX; see 2803 the RFC itself for full legal notices."; 2805 revision 2019-01-17 { 2806 description 2807 "Initial revision."; 2808 reference 2809 "RFC XXXX: Distributed Denial-of-Service Open Threat 2810 Signaling (DOTS) Signal Channel Specification"; 2811 } 2813 /* 2814 * Groupings 2815 */ 2817 grouping mitigation-scope { 2818 description 2819 "Specifies the scope of the mitigation request."; 2820 list scope { 2821 key "cuid mid"; 2822 description 2823 "The scope of the request."; 2824 leaf cdid { 2825 type string; 2826 description 2827 "The cdid should be included by a server-domain 2828 DOTS gateway to propagate the client domain 2829 identification information from the 2830 gateway's client-facing-side to the gateway's 2831 server-facing-side, and from the gateway's 2832 server-facing-side to the DOTS server. 2834 It may be used by the final DOTS server 2835 for policy enforcement purposes."; 2836 } 2837 leaf cuid { 2838 type string; 2839 description 2840 "A unique identifier that is 2841 generated by a DOTS client to prevent 2842 request collisions. It is expected that the 2843 cuid will remain consistent throughout the 2844 lifetime of the DOTS client."; 2845 } 2846 leaf mid { 2847 type uint32; 2848 description 2849 "Mitigation request identifier. 2851 This identifier must be unique for each mitigation 2852 request bound to the DOTS client."; 2853 } 2854 uses ietf-data:target; 2855 leaf-list alias-name { 2856 type string; 2857 description 2858 "An alias name that points to a resource."; 2859 } 2860 leaf lifetime { 2861 type int32; 2862 units "seconds"; 2863 default "3600"; 2864 description 2865 "Indicates the lifetime of the mitigation request. 2867 A lifetime of '0' in a mitigation request is an 2868 invalid value. 2870 A lifetime of negative one (-1) indicates indefinite 2871 lifetime for the mitigation request."; 2872 } 2873 leaf trigger-mitigation { 2874 type boolean; 2875 default "true"; 2876 description 2877 "If set to 'false', DDoS mitigation will not be 2878 triggered unless the DOTS signal channel 2879 session is lost."; 2880 } 2881 leaf mitigation-start { 2882 type uint64; 2883 config false; 2884 description 2885 "Mitigation start time is represented in seconds 2886 relative to 1970-01-01T00:00:00Z in UTC time."; 2887 } 2888 leaf status { 2889 type iana-signal:status; 2890 config false; 2891 description 2892 "Indicates the status of a mitigation request. 2893 It must be included in responses only."; 2894 } 2895 container conflict-information { 2896 config false; 2897 description 2898 "Indicates that a conflict is detected. 2900 Must only be used for responses."; 2901 leaf conflict-status { 2902 type iana-signal:conflict-status; 2903 description 2904 "Indicates the conflict status."; 2905 } 2906 leaf conflict-cause { 2907 type iana-signal:conflict-cause; 2908 description 2909 "Indicates the cause of the conflict."; 2910 } 2911 leaf retry-timer { 2912 type uint32; 2913 units "seconds"; 2914 description 2915 "The DOTS client must not re-send the 2916 same request that has a conflict before the expiry of 2917 this timer."; 2918 } 2919 container conflict-scope { 2920 description 2921 "Provides more information about the conflict scope."; 2922 uses ietf-data:target { 2923 when "../conflict-cause = 'overlapping-targets'"; 2924 } 2925 leaf-list alias-name { 2926 when "../../conflict-cause = 'overlapping-targets'"; 2927 type string; 2928 description 2929 "Conflicting alias-name."; 2930 } 2931 list acl-list { 2932 when "../../conflict-cause = 'conflict-with-acceptlist'"; 2933 key "acl-name"; 2934 description 2935 "List of conflicting ACLs as defined in the DOTS data 2936 channel. These ACLs are uniquely defined by 2937 cuid and acl-name."; 2938 leaf acl-name { 2939 type leafref { 2940 path "/ietf-data:dots-data/ietf-data:dots-client/" 2941 + "ietf-data:acls/ietf-data:acl/ietf-data:name"; 2942 } 2943 description 2944 "Reference to the conflicting ACL name bound to 2945 a DOTS client."; 2946 } 2947 leaf acl-type { 2948 type leafref { 2949 path "/ietf-data:dots-data/ietf-data:dots-client/" 2950 + "ietf-data:acls/ietf-data:acl/ietf-data:type"; 2951 } 2952 description 2953 "Reference to the conflicting ACL type bound to 2954 a DOTS client."; 2955 } 2956 } 2957 leaf mid { 2958 when "../../conflict-cause = 'overlapping-targets'"; 2959 type leafref { 2960 path "../../../mid"; 2961 } 2962 description 2963 "Reference to the conflicting 'mid' bound to 2964 the same DOTS client."; 2965 } 2966 } 2967 } 2968 leaf bytes-dropped { 2969 type yang:zero-based-counter64; 2970 units "bytes"; 2971 config false; 2972 description 2973 "The total dropped byte count for the mitigation 2974 request since the attack mitigation is triggered. 2975 The count wraps around when it reaches the maximum value 2976 of counter64 for dropped bytes."; 2977 } 2978 leaf bps-dropped { 2979 type yang:zero-based-counter64; 2980 config false; 2981 description 2982 "The average number of dropped bits per second for 2983 the mitigation request since the attack 2984 mitigation is triggered. This should be a 2985 five-minute average."; 2986 } 2987 leaf pkts-dropped { 2988 type yang:zero-based-counter64; 2989 config false; 2990 description 2991 "The total number of dropped packet count for the 2992 mitigation request since the attack mitigation is 2993 triggered. The count wraps around when it reaches 2994 the maximum value of counter64 for dropped packets."; 2995 } 2996 leaf pps-dropped { 2997 type yang:zero-based-counter64; 2998 config false; 2999 description 3000 "The average number of dropped packets per second 3001 for the mitigation request since the attack 3002 mitigation is triggered. This should be a 3003 five-minute average."; 3004 } 3005 leaf attack-status { 3006 type iana-signal:attack-status; 3007 description 3008 "Indicates the status of an attack as seen by the 3009 DOTS client."; 3010 } 3011 } 3012 } 3014 grouping config-parameters { 3015 description 3016 "Subset of DOTS signal channel session configuration."; 3017 container heartbeat-interval { 3018 description 3019 "DOTS agents regularly send heartbeats to each other 3020 after mutual authentication is successfully 3021 completed in order to keep the DOTS signal channel 3022 open."; 3023 leaf max-value { 3024 type uint16; 3025 units "seconds"; 3026 config false; 3027 description 3028 "Maximum acceptable heartbeat-interval value."; 3029 } 3030 leaf min-value { 3031 type uint16; 3032 units "seconds"; 3033 config false; 3034 description 3035 "Minimum acceptable heartbeat-interval value."; 3036 } 3037 leaf current-value { 3038 type uint16; 3039 units "seconds"; 3040 default "30"; 3041 description 3042 "Current heartbeat-interval value. 3044 '0' means that heartbeat mechanism is deactivated."; 3045 } 3046 } 3047 container missing-hb-allowed { 3048 description 3049 "Maximum number of missing heartbeats allowed."; 3050 leaf max-value { 3051 type uint16; 3052 config false; 3053 description 3054 "Maximum acceptable missing-hb-allowed value."; 3055 } 3056 leaf min-value { 3057 type uint16; 3058 config false; 3059 description 3060 "Minimum acceptable missing-hb-allowed value."; 3061 } 3062 leaf current-value { 3063 type uint16; 3064 default "5"; 3065 description 3066 "Current missing-hb-allowed value."; 3067 } 3068 } 3069 container max-retransmit { 3070 description 3071 "Maximum number of retransmissions of a Confirmable 3072 message."; 3073 leaf max-value { 3074 type uint16; 3075 config false; 3076 description 3077 "Maximum acceptable max-retransmit value."; 3078 } 3079 leaf min-value { 3080 type uint16; 3081 config false; 3082 description 3083 "Minimum acceptable max-retransmit value."; 3084 } 3085 leaf current-value { 3086 type uint16; 3087 default "3"; 3088 description 3089 "Current max-retransmit value."; 3090 } 3091 } 3092 container ack-timeout { 3093 description 3094 "Initial retransmission timeout value."; 3095 leaf max-value-decimal { 3096 type decimal64 { 3097 fraction-digits 2; 3098 } 3099 units "seconds"; 3100 config false; 3101 description 3102 "Maximum ack-timeout value."; 3103 } 3104 leaf min-value-decimal { 3105 type decimal64 { 3106 fraction-digits 2; 3107 } 3108 units "seconds"; 3109 config false; 3110 description 3111 "Minimum ack-timeout value."; 3112 } 3113 leaf current-value-decimal { 3114 type decimal64 { 3115 fraction-digits 2; 3116 } 3117 units "seconds"; 3118 default "2"; 3119 description 3120 "Current ack-timeout value."; 3121 } 3122 } 3123 container ack-random-factor { 3124 description 3125 "Random factor used to influence the timing of 3126 retransmissions."; 3127 leaf max-value-decimal { 3128 type decimal64 { 3129 fraction-digits 2; 3130 } 3131 config false; 3132 description 3133 "Maximum acceptable ack-random-factor value."; 3134 } 3135 leaf min-value-decimal { 3136 type decimal64 { 3137 fraction-digits 2; 3138 } 3139 config false; 3140 description 3141 "Minimum acceptable ack-random-factor value."; 3142 } 3143 leaf current-value-decimal { 3144 type decimal64 { 3145 fraction-digits 2; 3146 } 3147 default "1.5"; 3148 description 3149 "Current ack-random-factor value."; 3150 } 3151 } 3152 } 3154 grouping signal-config { 3155 description 3156 "DOTS signal channel session configuration."; 3157 leaf sid { 3158 type uint32; 3159 mandatory true; 3160 description 3161 "An identifier for the DOTS signal channel 3162 session configuration data."; 3163 } 3164 container mitigating-config { 3165 description 3166 "Configuration parameters to use when a mitigation 3167 is active."; 3168 uses config-parameters; 3169 } 3170 container idle-config { 3171 description 3172 "Configuration parameters to use when no mitigation 3173 is active."; 3174 uses config-parameters; 3175 } 3176 } 3178 grouping redirected-signal { 3179 description 3180 "Grouping for the redirected signaling."; 3181 leaf alt-server { 3182 type string; 3183 config false; 3184 mandatory true; 3185 description 3186 "FQDN of an alternate server."; 3187 } 3188 leaf-list alt-server-record { 3189 type inet:ip-address; 3190 config false; 3191 description 3192 "List of records for the alternate server."; 3193 } 3194 } 3196 /* 3197 * Main Container for DOTS Signal Channel 3198 */ 3200 container dots-signal { 3201 description 3202 "Main container for DOTS signal message. 3204 A DOTS signal message can be a mitigation, a configuration, 3205 or a redirected signal message."; 3206 choice message-type { 3207 description 3208 "Can be a mitigation, a configuration, or a redirect 3209 message."; 3210 case mitigation-scope { 3211 description 3212 "Mitigation scope of a mitigation message."; 3213 uses mitigation-scope; 3214 } 3215 case signal-config { 3216 description 3217 "Configuration message."; 3218 uses signal-config; 3219 } 3220 case redirected-signal { 3221 description 3222 "Redirected signaling."; 3223 uses redirected-signal; 3224 } 3225 } 3226 } 3227 } 3228 3230 6. YANG/JSON Mapping Parameters to CBOR 3232 All parameters in the payload of the DOTS signal channel MUST be 3233 mapped to CBOR types as shown in Table 4 and are assigned an integer 3234 key to save space. The CBOR key values are divided into two types: 3235 comprehension-required and comprehension-optional. DOTS agents can 3236 safely ignore comprehension-optional values they don't understand, 3237 but cannot successfully process a request if it contains 3238 comprehension-required values that are not understood. The 4.00 3239 response SHOULD include a diagnostic payload describing the unknown 3240 comprehension-required CBOR key values. The initial set of CBOR key 3241 values defined in this specification are of type comprehension- 3242 required. 3244 +----------------------+-------------+-----+---------------+--------+ 3245 | Parameter Name | YANG | CBOR| CBOR Major | JSON | 3246 | | Type | Key | Type & | Type | 3247 | | | | Information | | 3248 +----------------------+-------------+-----+---------------+--------+ 3249 | ietf-dots-signal-cha | | | | | 3250 | nnel:mitigation-scope| container | 1 | 5 map | Object | 3251 | scope | list | 2 | 4 array | Array | 3252 | cdid | string | 3 | 3 text string | String | 3253 | cuid | string | 4 | 3 text string | String | 3254 | mid | uint32 | 5 | 0 unsigned | Number | 3255 | target-prefix | leaf-list | 6 | 4 array | Array | 3256 | | inet: | | | | 3257 | | ip-prefix | | 3 text string | String | 3258 | target-port-range | list | 7 | 4 array | Array | 3259 | lower-port | inet: | | | | 3260 | | port-number| 8 | 0 unsigned | Number | 3261 | upper-port | inet: | | | | 3262 | | port-number| 9 | 0 unsigned | Number | 3263 | target-protocol | leaf-list | 10 | 4 array | Array | 3264 | | uint8 | | 0 unsigned | Number | 3265 | target-fqdn | leaf-list | 11 | 4 array | Array | 3266 | | inet: | | | | 3267 | | domain-name| | 3 text string | String | 3268 | target-uri | leaf-list | 12 | 4 array | Array | 3269 | | inet:uri | | 3 text string | String | 3270 | alias-name | leaf-list | 13 | 4 array | Array | 3271 | | string | | 3 text string | String | 3272 | lifetime | int32 | 14 | 0 unsigned | Number | 3273 | | | | 1 negative | Number | 3274 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3275 | status | enumeration | 16 | 0 unsigned | String | 3276 | conflict-information | container | 17 | 5 map | Object | 3277 | conflict-status | enumeration | 18 | 0 unsigned | String | 3278 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3279 | retry-timer | uint32 | 20 | 0 unsigned | Number | 3280 | conflict-scope | container | 21 | 5 map | Object | 3281 | acl-list | list | 22 | 4 array | Array | 3282 | acl-name | leafref | 23 | 3 text string | String | 3283 | acl-type | leafref | 24 | 3 text string | String | 3284 | bytes-dropped | yang:zero- | | | | 3285 | | based- | | | | 3286 | | counter64 | 25 | 0 unsigned | String | 3287 | bps-dropped | yang:zero- | | | | 3288 | | based- | | | | 3289 | | counter64 | 26 | 0 unsigned | String | 3290 | pkts-dropped | yang:zero- | | | | 3291 | | based- | | | | 3292 | | counter64 | 27 | 0 unsigned | String | 3293 | pps-dropped | yang:zero- | | | | 3294 | | based- | | | | 3295 | | counter64 | 28 | 0 unsigned | String | 3296 | attack-status | enumeration | 29 | 0 unsigned | String | 3297 | ietf-dots-signal- | | | | | 3298 | channel:signal-config| container | 30 | 5 map | Object | 3299 | sid | uint32 | 31 | 0 unsigned | Number | 3300 | mitigating-config | container | 32 | 5 map | Object | 3301 | heartbeat-interval | container | 33 | 5 map | Object | 3302 | max-value | uint16 | 34 | 0 unsigned | Number | 3303 | min-value | uint16 | 35 | 0 unsigned | Number | 3304 | current-value | uint16 | 36 | 0 unsigned | Number | 3305 | missing-hb-allowed | container | 37 | 5 map | Object | 3306 | max-retransmit | container | 38 | 5 map | Object | 3307 | ack-timeout | container | 39 | 5 map | Object | 3308 | ack-random-factor | container | 40 | 5 map | Object | 3309 | max-value-decimal | decimal64 | 41 | 6 tag 4 | | 3310 | | | | [-2, integer]| String | 3311 | min-value-decimal | decimal64 | 42 | 6 tag 4 | | 3312 | | | | [-2, integer]| String | 3313 | current-value-decimal| decimal64 | 43 | 6 tag 4 | | 3314 | | | | [-2, integer]| String | 3315 | idle-config | container | 44 | 5 map | Object | 3316 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3317 | | | | 7 bits 21 | True | 3318 | ietf-dots-signal-cha | | | | | 3319 |nnel:redirected-signal| container | 46 | 5 map | Object | 3320 | alt-server | string | 47 | 3 text string | String | 3321 | alt-server-record | leaf-list | 48 | 4 array | Array | 3322 | | inet: | | | | 3323 | | ip-address | | 3 text string | String | 3324 +----------------------+-------------+-----+---------------+--------+ 3326 Table 4: CBOR Key Values Used in DOTS Signal Channel Messages & Their 3327 Mappings to JSON and YANG 3329 7. (D)TLS Protocol Profile and Performance Considerations 3331 7.1. (D)TLS Protocol Profile 3333 This section defines the (D)TLS protocol profile of DOTS signal 3334 channel over (D)TLS and DOTS data channel over TLS. 3336 There are known attacks on (D)TLS, such as man-in-the-middle and 3337 protocol downgrade attacks. These are general attacks on (D)TLS and, 3338 as such, they are not specific to DOTS over (D)TLS; refer to the 3339 (D)TLS RFCs for discussion of these security issues. DOTS agents 3340 MUST adhere to the (D)TLS implementation recommendations and security 3341 considerations of [RFC7525] except with respect to (D)TLS version. 3342 Since DOTS signal channel encryption relying upon (D)TLS is virtually 3343 a green-field deployment, DOTS agents MUST implement only (D)TLS 1.2 3344 or later. 3346 When a DOTS client is configured with a domain name of the DOTS 3347 server, and connects to its configured DOTS server, the server may 3348 present it with a PKIX certificate. In order to ensure proper 3349 authentication, a DOTS client MUST verify the entire certification 3350 path per [RFC5280]. The DOTS client additionally uses [RFC6125] 3351 validation techniques to compare the domain name with the certificate 3352 provided. 3354 A key challenge to deploying DOTS is the provisioning of DOTS 3355 clients, including the distribution of keying material to DOTS 3356 clients to enable the required mutual authentication of DOTS agents. 3357 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3358 certificate enrollment by which domains operating DOTS servers may 3359 provide DOTS clients with all the necessary cryptographic keying 3360 material, including a private key and a certificate to authenticate 3361 themselves. One deployment option is DOTS clients behave as EST 3362 clients for certificate enrollment from an EST server provisioned by 3363 the mitigation provider. This document does not specify which EST or 3364 other mechanism the DOTS client uses to achieve initial enrollment. 3366 The Server Name Indication (SNI) extension [RFC6066] defines a 3367 mechanism for a client to tell a (D)TLS server the name of the server 3368 it wants to contact. This is a useful extension for hosting 3369 environments where multiple virtual servers are reachable over a 3370 single IP address. The DOTS client may or may not know if it is 3371 interacting with a DOTS server in a virtual server hosting 3372 environment, so the DOTS client SHOULD include the DOTS server FQDN 3373 in the SNI extension. 3375 Implementations compliant with this profile MUST implement all of the 3376 following items: 3378 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3379 equivalent mechanism to protect against replay attacks. 3381 o DTLS session resumption without server-side state to resume 3382 session and convey the DOTS signal. 3384 o At least one of raw public keys [RFC7250] or PSK handshake 3385 [RFC4279] with (EC)DHE key exchange which reduces the size of the 3386 ServerHello, and can be used by DOTS agents that cannot obtain 3387 certificates. 3389 Implementations compliant with this profile SHOULD implement all of 3390 the following items to reduce the delay required to deliver a DOTS 3391 signal channel message: 3393 o TLS False Start [RFC7918] which reduces round-trips by allowing 3394 the TLS client's second flight of messages (ChangeCipherSpec) to 3395 also contain the DOTS signal. TLS False Start is formally defined 3396 for use with TLS, but the same technique is applicable to DTLS as 3397 well. 3399 o Cached Information Extension [RFC7924] which avoids transmitting 3400 the server's certificate and certificate chain if the client has 3401 cached that information from a previous TLS handshake. 3403 Compared to UDP, DOTS signal channel over TCP requires an additional 3404 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3405 implementations are encouraged to implement TCP Fast Open [RFC7413] 3406 to eliminate that RTT. 3408 7.2. (D)TLS 1.3 Considerations 3410 TLS 1.3 provides critical latency improvements for connection 3411 establishment over TLS 1.2. The DTLS 1.3 protocol 3412 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3413 equivalent security guarantees. (D)TLS 1.3 provides two basic 3414 handshake modes the DOTS signal channel can take advantage of: 3416 o A full handshake mode in which a DOTS client can send a DOTS 3417 mitigation request message after one round trip and the DOTS 3418 server immediately responds with a DOTS mitigation response. This 3419 assumes no packet loss is experienced. 3421 o 0-RTT mode in which the DOTS client can authenticate itself and 3422 send DOTS mitigation request messages in the first message, thus 3423 reducing handshake latency. 0-RTT only works if the DOTS client 3424 has previously communicated with that DOTS server, which is very 3425 likely with the DOTS signal channel. 3427 The DOTS client has to establish a (D)TLS session with the DOTS 3428 server during 'idle' time and share a PSK. 3430 During a DDoS attack, the DOTS client can use the (D)TLS session 3431 to convey the DOTS mitigation request message and, if there is no 3432 response from the server after multiple retries, the DOTS client 3433 can resume the (D)TLS session in 0-RTT mode using PSK. 3435 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to 3436 send early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" 3437 as early data; such messages MUST be rejected by DOTS servers. 3438 Section 8 of [RFC8446] discusses some mechanisms to implement to 3439 limit the impact of replay attacks on 0-RTT data. If the DOTS 3440 server accepts 0-RTT, it MUST implement one of these mechanisms to 3441 prevent replay at the TLS layer. A DOTS server can reject 0-RTT 3442 by sending a TLS HelloRetryRequest. 3444 The DOTS signal channel messages sent as early data by the DOTS 3445 client are idempotent requests. As a reminder, the Message ID 3446 (Section 3 of [RFC7252]) is changed each time a new CoAP request 3447 is sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized 3448 in each CoAP request. The DOTS server(s) MUST use the Message ID 3449 and the Token in the DOTS signal channel message to detect replay 3450 of early data at the application layer, and accept 0-RTT data at 3451 most once from the same DOTS client. This anti-replay defense 3452 requires sharing the Message ID and the Token in the 0-RTT data 3453 between DOTS servers in the DOTS server domain. DOTS servers do 3454 not rely on transport coordinates to identify DOTS peers. As 3455 specified in Section 4.4.1, DOTS servers couple the DOTS signal 3456 channel sessions using the DOTS client identity and optionally the 3457 'cdid' parameter value. Furthermore, 'mid' value is monotonically 3458 increased by the DOTS client for each mitigation request, 3459 attackers replaying mitigation requests with lower numeric 'mid' 3460 values and overlapping scopes with mitigation requests having 3461 higher numeric 'mid' values will be rejected systematically by the 3462 DOTS server. Likewise, 'sid' value is monotonically increased by 3463 the DOTS client for each configuration request (Section 4.5.2), 3464 attackers replaying configuration requests with lower numeric 3465 'sid' values will be rejected by the DOTS server if it maintains a 3466 higher numeric 'sid' value for this DOTS client. 3468 Owing to the aforementioned protections, all DOTS signal channel 3469 requests are safe to transmit in TLS 1.3 as early data. Refer to 3470 [I-D.boucadair-dots-earlydata] for more details. 3472 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3473 message exchange is shown in Figure 27. 3475 DOTS Client DOTS Server 3477 ClientHello 3478 (0-RTT DOTS signal message) 3479 --------> 3480 ServerHello 3481 {EncryptedExtensions} 3482 {Finished} 3483 <-------- [DOTS signal message] 3484 (end_of_early_data) 3485 {Finished} --------> 3486 [DOTS signal message] <-------> [DOTS signal message] 3488 Note that: 3489 () Indicates messages protected 0-RTT keys 3490 {} Indicates messages protected using handshake keys 3491 [] Indicates messages protected using 1-RTT keys 3493 Figure 27: A Simplified TLS 1.3 Handshake with 0-RTT 3495 7.3. DTLS MTU and Fragmentation 3497 To avoid DOTS signal message fragmentation and the subsequent 3498 decreased probability of message delivery, DOTS agents MUST ensure 3499 that the DTLS record MUST fit within a single datagram. If the path 3500 MTU is not known to the DOTS server, an IP MTU of 1280 bytes SHOULD 3501 be assumed. The DOTS client must consider the amount of record 3502 expansion expected by the DTLS processing when calculating the size 3503 of CoAP message that fits within the path MTU. Path MTU MUST be 3504 greater than or equal to [CoAP message size + DTLS 1.2 overhead of 13 3505 octets + authentication overhead of the negotiated DTLS cipher suite 3506 + block padding] (Section 4.1.1.1 of [RFC6347]). If the total 3507 request size exceeds the path MTU then the DOTS client MUST split the 3508 DOTS signal into separate messages; for example, the list of 3509 addresses in the 'target-prefix' parameter could be split into 3510 multiple lists and each list conveyed in a new PUT request. 3512 Implementation Note: DOTS choice of message size parameters works 3513 well with IPv6 and with most of today's IPv4 paths. However, with 3514 IPv4, it is harder to safely make sure that there is no IP 3515 fragmentation. If the IPv4 path MTU is unknown, implementations may 3516 want to limit themselves to more conservative IPv4 datagram sizes 3517 such as 576 bytes, as per [RFC0791]. IP packets whose size does not 3518 exceed 576 bytes should never need to be fragmented: therefore, 3519 sending a maximum of 500 bytes of DOTS signal over a UDP datagram 3520 will generally avoid IP fragmentation. 3522 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 3524 (D)TLS based upon client certificate can be used for mutual 3525 authentication between DOTS agents. If, for example, a DOTS gateway 3526 is involved, DOTS clients and DOTS gateways must perform mutual 3527 authentication; only authorized DOTS clients are allowed to send DOTS 3528 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 3529 perform mutual authentication; a DOTS server only allows DOTS signal 3530 channel messages from an authorized DOTS gateway, thereby creating a 3531 two-link chain of transitive authentication between the DOTS client 3532 and the DOTS server. 3534 The DOTS server should support certificate-based client 3535 authentication. The DOTS client should respond to the DOTS server's 3536 TLS CertificateRequest message with the PKIX certificate held by the 3537 DOTS client. DOTS client certificate validation must be performed as 3538 per [RFC5280] and the DOTS client certificate must conform to the 3539 [RFC5280] certificate profile. If a DOTS client does not support TLS 3540 client certificate authentication, it must support pre-shared key 3541 based or raw public key based client authentication. 3543 +-----------------------------------------------+ 3544 | example.com domain +---------+ | 3545 | | AAA | | 3546 | +---------------+ | Server | | 3547 | | Application | +------+--+ | 3548 | | server +<-----------------+ ^ | 3549 | | (DOTS client) | | | | 3550 | +---------------+ | | | 3551 | V V | example.net domain 3552 | +-----+----+--+ | +---------------+ 3553 | +--------------+ | | | | | 3554 | | Guest +<-----x----->+ DOTS +<------>+ DOTS | 3555 | | (DOTS client)| | gateway | | | server | 3556 | +--------------+ | | | | | 3557 | +----+--------+ | +---------------+ 3558 | ^ | 3559 | | | 3560 | +----------------+ | | 3561 | | DDoS detector | | | 3562 | | (DOTS client) +<---------------+ | 3563 | +----------------+ | 3564 +-----------------------------------------------+ 3566 Figure 28: Example of Authentication and Authorization of DOTS Agents 3568 In the example depicted in Figure 28, the DOTS gateway and DOTS 3569 clients within the 'example.com' domain mutually authenticate. After 3570 the DOTS gateway validates the identity of a DOTS client, it 3571 communicates with the AAA server in the 'example.com' domain to 3572 determine if the DOTS client is authorized to request DDoS 3573 mitigation. If the DOTS client is not authorized, a 4.01 3574 (Unauthorized) is returned in the response to the DOTS client. In 3575 this example, the DOTS gateway only allows the application server and 3576 DDoS attack detector to request DDoS mitigation, but does not permit 3577 the user of type 'guest' to request DDoS mitigation. 3579 Also, DOTS gateways and servers located in different domains must 3580 perform mutual authentication (e.g., using certificates). A DOTS 3581 server will only allow a DOTS gateway with a certificate for a 3582 particular domain to request mitigation for that domain. In 3583 reference to Figure 28, the DOTS server only allows the DOTS gateway 3584 to request mitigation for 'example.com' domain and not for other 3585 domains. 3587 9. IANA Considerations 3589 9.1. DOTS Signal Channel UDP and TCP Port Number 3591 IANA is requested to assign the port number TBD to the DOTS signal 3592 channel protocol for both UDP and TCP from the "Service Name and 3593 Transport Protocol Port Number Registry" available at 3594 https://www.iana.org/assignments/service-names-port-numbers/service- 3595 names-port-numbers.xhtml. 3597 The assignment of port number 4646 is strongly suggested, as 4646 is 3598 the ASCII decimal value for ".." (DOTS). 3600 9.2. Well-Known 'dots' URI 3602 This document requests IANA to register the 'dots' well-known URI 3603 (Table 5) in the Well-Known URIs registry 3604 (https://www.iana.org/assignments/well-known-uris/well-known- 3605 uris.xhtml) as defined by [RFC5785]: 3607 +----------+----------------+---------------------+-----------------+ 3608 | URI | Change | Specification | Related | 3609 | suffix | controller | document(s) | information | 3610 +----------+----------------+---------------------+-----------------+ 3611 | dots | IETF | [RFCXXXX] | None | 3612 +----------+----------------+---------------------+-----------------+ 3614 Table 5: 'dots' well-known URI 3616 9.3. Media Type Registration 3618 This document requests IANA to register the "application/dots+cbor" 3619 media type in the "Media Types" registry [IANA.MediaTypes] in the 3620 manner described in [RFC6838], which can be used to indicate that the 3621 content is a DOTS signal channel object: 3623 o Type name: application 3624 o Subtype name: dots+cbor 3625 o Required parameters: N/A 3626 o Optional parameters: N/A 3627 o Encoding considerations: binary 3628 o Security considerations: See the Security Considerations section 3629 of [RFCXXXX] 3630 o Interoperability considerations: N/A 3631 o Published specification: [RFCXXXX] 3632 o Applications that use this media type: DOTS agents sending DOTS 3633 messages over CoAP over (D)TLS. 3634 o Fragment identifier considerations: N/A 3635 o Additional information: 3637 Magic number(s): N/A 3638 File extension(s): N/A 3639 Macintosh file type code(s): N/A 3640 o Person & email address to contact for further information: 3641 IESG, iesg@ietf.org 3642 o Intended usage: COMMON 3643 o Restrictions on usage: none 3644 o Author: See Authors' Addresses section. 3645 o Change controller: IESG 3646 o Provisional registration? No 3648 9.4. CoAP Content-Formats Registration 3650 This document requests IANA to register the CoAP Content-Format ID 3651 for the "application/dots+cbor" media type in the "CoAP Content- 3652 Formats" registry [IANA.CoAP.Content-Formats] (0-255 range): 3654 o Media Type: application/dots+cbor 3655 o Encoding: - 3656 o Id: TBD1 3657 o Reference: [RFCXXXX] 3659 9.5. CBOR Tag Registration 3661 This section defines the DOTS CBOR tag as another means for 3662 applications to declare that a CBOR data structure is a DOTS signal 3663 channel object. Its use is optional and is intended for use in cases 3664 in which this information would not otherwise be known. DOTS CBOR 3665 tag is not required for DOTS signal channel protocol version 3666 specified in this document. If present, the DOTS tag MUST prefix a 3667 DOTS signal channel object. 3669 This document requests IANA to register the DOTS signal channel CBOR 3670 tag in the "CBOR Tags" registry [IANA.CBOR.Tags] using the 24-255 3671 range: 3673 o CBOR Tag: TBD2 (please assign the same value as the Content- 3674 Format) 3675 o Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 3676 o Semantics: DDoS Open Threat Signaling (DOTS) signal channel 3677 object, as defined in [RFCXXXX] 3678 o Description of Semantics: [RFCXXXX] 3680 9.6. DOTS Signal Channel Protocol Registry 3682 The document requests IANA to create a new registry, entitled "DOTS 3683 Signal Channel Registry". The following sections define sub- 3684 registries. 3686 9.6.1. DOTS Signal Channel CBOR Key Values Sub-Registry 3688 The document requests IANA to create a new sub-registry, entitled 3689 "DOTS Signal Channel CBOR Key Values". 3691 The structure of this sub-registry is provided in Section 9.6.1.1. 3692 Section 9.6.1.2 provides how the registry is initially populated with 3693 the values in Table 4. 3695 9.6.1.1. Registration Template 3697 Parameter name: 3698 Parameter name as used in the DOTS signal channel. 3700 CBOR Key Value: 3701 Key value for the parameter. The key value MUST be an integer in 3702 the 1-65535 range. The key values of the comprehension-required 3703 range (0x0001 - 0x3FFF) and of the comprehension-optional range 3704 (0x8000 - 0xBFFF) are assigned by IETF Review (Section 4.8 of 3705 [RFC8126]). The key values of the comprehension-optional range 3706 (0x4000 - 0x7FFF) are assigned by Specification Required 3707 (Section 4.6 of [RFC8126]) and of the comprehension-optional range 3708 (0xC000 - 0xFFFF) are reserved for Private Use (Section 4.1 of 3709 [RFC8126]). 3711 Registration requests for the 0x4000 - 0x7FFF range are evaluated 3712 after a three-week review period on the dots-signal-reg- 3713 review@ietf.org mailing list, on the advice of one or more 3714 Designated Experts. However, to allow for the allocation of 3715 values prior to publication, the Designated Experts may approve 3716 registration once they are satisfied that such a specification 3717 will be published. New registration requests should be sent in 3718 the form of an email to the review mailing list; the request 3719 should use an appropriate subject (e.g., "Request to register CBOR 3720 Key Value for DOTS: example"). IANA will only accept new 3721 registrations from the Designated Experts, and will check that 3722 review was requested on the mailing list in accordance with these 3723 procedures. 3725 Within the review period, the Designated Experts will either 3726 approve or deny the registration request, communicating this 3727 decision to the review list and IANA. Denials should include an 3728 explanation and, if applicable, suggestions as to how to make the 3729 request successful. Registration requests that are undetermined 3730 for a period longer than 21 days can be brought to the IESG's 3731 attention (using the iesg@ietf.org mailing list) for resolution. 3733 Criteria that should be applied by the Designated Experts includes 3734 determining whether the proposed registration duplicates existing 3735 functionality, whether it is likely to be of general applicability 3736 or whether it is useful only for a single use case, and whether 3737 the registration description is clear. IANA must only accept 3738 registry updates to the 0x4000 - 0x7FFF range from the Designated 3739 Experts and should direct all requests for registration to the 3740 review mailing list. It is suggested that multiple Designated 3741 Experts be appointed. In cases where a registration decision 3742 could be perceived as creating a conflict of interest for a 3743 particular Expert, that Expert should defer to the judgment of the 3744 other Experts. 3746 CBOR Major Type: 3747 CBOR Major type and optional tag for the parameter. 3749 Change Controller: 3750 For Standards Track RFCs, list the "IESG". For others, give the 3751 name of the responsible party. Other details (e.g., email 3752 address) may also be included. 3754 Specification Document(s): 3755 Reference to the document or documents that specify the parameter, 3756 preferably including URIs that can be used to retrieve copies of 3757 the documents. An indication of the relevant sections may also be 3758 included but is not required. 3760 9.6.1.2. Initial Sub-Registry Content 3762 +----------------------+-------+-------+------------+---------------+ 3763 | Parameter Name | CBOR | CBOR | Change | Specification | 3764 | | Key | Major | Controller | Document(s) | 3765 | | Value | Type | | | 3766 +----------------------+-------+-------+------------+---------------+ 3767 | ietf-dots-signal-chan| 1 | 5 | IESG | [RFCXXXX] | 3768 | nel:mitigation-scope | | | | | 3769 | scope | 2 | 4 | IESG | [RFCXXXX] | 3770 | cdid | 3 | 3 | IESG | [RFCXXXX] | 3771 | cuid | 4 | 3 | IESG | [RFCXXXX] | 3772 | mid | 5 | 0 | IESG | [RFCXXXX] | 3773 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 3774 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 3775 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 3776 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 3777 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 3778 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 3779 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 3780 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 3781 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 3782 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 3783 | status | 16 | 0 | IESG | [RFCXXXX] | 3784 | conflict-information | 17 | 5 | IESG | [RFCXXXX] | 3785 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 3786 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 3787 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 3788 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 3789 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 3790 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 3791 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 3792 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 3793 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 3794 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 3795 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 3796 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 3797 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 3798 | channel:signal-config| | | | | 3799 | sid | 31 | 0 | IESG | [RFCXXXX] | 3800 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 3801 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 3802 | min-value | 34 | 0 | IESG | [RFCXXXX] | 3803 | max-value | 35 | 0 | IESG | [RFCXXXX] | 3804 | current-value | 36 | 0 | IESG | [RFCXXXX] | 3805 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 3806 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 3807 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 3808 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 3809 | min-value-decimal | 41 | 6tag4 | IESG | [RFCXXXX] | 3810 | max-value-decimal | 42 | 6tag4 | IESG | [RFCXXXX] | 3811 | current-value- | 43 | 6tag4 | IESG | [RFCXXXX] | 3812 | decimal | | | | | 3813 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 3814 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 3815 | ietf-dots-signal-chan| 46 | 5 | IESG | [RFCXXXX] | 3816 | nel:redirected-signal| | | | | 3817 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 3818 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 3819 +----------------------+-------+-------+------------+---------------+ 3821 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 3823 9.6.2. Status Codes Sub-Registry 3825 The document requests IANA to create a new sub-registry, entitled 3826 "DOTS Signal Channel Status Codes". Codes in this registry are used 3827 as valid values of 'status' parameter. 3829 The registry is initially populated with the following values: 3831 +-----+----------------------------------+--------------+-----------+ 3832 | Cod | Label | Description | Reference | 3833 | e | | | | 3834 +-----+----------------------------------+--------------+-----------+ 3835 | 1 | attack-mitigation-in-progress | Attack | [RFCXXXX] | 3836 | | | mitigation | | 3837 | | | setup is in | | 3838 | | | progress | | 3839 | | | (e.g., | | 3840 | | | changing the | | 3841 | | | network path | | 3842 | | | to redirect | | 3843 | | | the inbound | | 3844 | | | traffic to a | | 3845 | | | DOTS | | 3846 | | | mitigator). | | 3847 | 2 | attack-successfully-mitigated | Attack is | [RFCXXXX] | 3848 | | | being | | 3849 | | | successfully | | 3850 | | | mitigated | | 3851 | | | (e.g., | | 3852 | | | traffic is | | 3853 | | | redirected | | 3854 | | | to a DDoS | | 3855 | | | mitigator | | 3856 | | | and attack | | 3857 | | | traffic is | | 3858 | | | dropped). | | 3859 | 3 | attack-stopped | Attack has | [RFCXXXX] | 3860 | | | stopped and | | 3861 | | | the DOTS | | 3862 | | | client can | | 3863 | | | withdraw the | | 3864 | | | mitigation | | 3865 | | | request. | | 3866 | 4 | attack-exceeded-capability | Attack has | [RFCXXXX] | 3867 | | | exceeded the | | 3868 | | | mitigation | | 3869 | | | provider | | 3870 | | | capability. | | 3871 | 5 | dots-client-withdrawn-mitigation | DOTS client | [RFCXXXX] | 3872 | | | has | | 3873 | | | withdrawn | | 3874 | | | the | | 3875 | | | mitigation | | 3876 | | | request and | | 3877 | | | the | | 3878 | | | mitigation | | 3879 | | | is active | | 3880 | | | but | | 3881 | | | terminating. | | 3882 | 6 | attack-mitigation-terminated | Attack | [RFCXXXX] | 3883 | | | mitigation | | 3884 | | | is now | | 3885 | | | terminated. | | 3886 | 7 | attack-mitigation-withdrawn | Attack | [RFCXXXX] | 3887 | | | mitigation | | 3888 | | | is | | 3889 | | | withdrawn. | | 3890 | 8 | attack-mitigation-signal-loss | Attack | [RFCXXXX] | 3891 | | | mitigation | | 3892 | | | will be | | 3893 | | | triggered | | 3894 | | | for the | | 3895 | | | mitigation | | 3896 | | | request only | | 3897 | | | when the | | 3898 | | | DOTS signal | | 3899 | | | channel | | 3900 | | | session is | | 3901 | | | lost. | | 3902 +-----+----------------------------------+--------------+-----------+ 3903 New codes can be assigned via Standards Action [RFC8126]. 3905 9.6.3. Conflict Status Codes Sub-Registry 3907 The document requests IANA to create a new sub-registry, entitled 3908 "DOTS Signal Channel Conflict Status Codes". Codes in this registry 3909 are used as valid values of 'conflict-status' parameter. 3911 The registry is initially populated with the following values: 3913 +------+-------------------------------+----------------+-----------+ 3914 | Code | Label | Description | Reference | 3915 +------+-------------------------------+----------------+-----------+ 3916 | 1 | request-inactive-other-active | DOTS server | [RFCXXXX] | 3917 | | | has detected | | 3918 | | | conflicting | | 3919 | | | mitigation | | 3920 | | | requests from | | 3921 | | | different DOTS | | 3922 | | | clients. This | | 3923 | | | mitigation | | 3924 | | | request is | | 3925 | | | currently | | 3926 | | | inactive until | | 3927 | | | the conflicts | | 3928 | | | are resolved. | | 3929 | | | Another | | 3930 | | | mitigation | | 3931 | | | request is | | 3932 | | | active. | | 3933 | 2 | request-active | DOTS server | [RFCXXXX] | 3934 | | | has detected | | 3935 | | | conflicting | | 3936 | | | mitigation | | 3937 | | | requests from | | 3938 | | | different DOTS | | 3939 | | | clients. This | | 3940 | | | mitigation | | 3941 | | | request is | | 3942 | | | currently | | 3943 | | | active. | | 3944 | 3 | all-requests-inactive | DOTS server | [RFCXXXX] | 3945 | | | has detected | | 3946 | | | conflicting | | 3947 | | | mitigation | | 3948 | | | requests from | | 3949 | | | different DOTS | | 3950 | | | clients. All | | 3951 | | | conflicting | | 3952 | | | mitigation | | 3953 | | | requests are | | 3954 | | | inactive. | | 3955 +------+-------------------------------+----------------+-----------+ 3957 New codes can be assigned via Standards Action [RFC8126]. 3959 9.6.4. Conflict Cause Codes Sub-Registry 3961 The document requests IANA to create a new sub-registry, entitled 3962 "DOTS Signal Channel Conflict Cause Codes". Codes in this registry 3963 are used as valid values of 'conflict-cause' parameter. 3965 The registry is initially populated with the following values: 3967 +------+--------------------------+---------------------+-----------+ 3968 | Code | Label | Description | Reference | 3969 +------+--------------------------+---------------------+-----------+ 3970 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 3971 | | | targets. | | 3972 | 2 | conflict-with-acceptlist | Conflicts with an | [RFCXXXX] | 3973 | | | existing accept- | | 3974 | | | list. This code is | | 3975 | | | returned when the | | 3976 | | | DDoS mitigation | | 3977 | | | detects source | | 3978 | | | addresses/prefixes | | 3979 | | | in the accept- | | 3980 | | | listed ACLs are | | 3981 | | | attacking the | | 3982 | | | target. | | 3983 | 3 | cuid-collision | CUID Collision. | [RFCXXXX] | 3984 | | | This code is | | 3985 | | | returned when a | | 3986 | | | DOTS client uses a | | 3987 | | | 'cuid' that is | | 3988 | | | already used by | | 3989 | | | another DOTS | | 3990 | | | client. | | 3991 +------+--------------------------+---------------------+-----------+ 3993 New codes can be assigned via Standards Action [RFC8126]. 3995 9.6.5. Attack Status Codes Sub-Registry 3997 The document requests IANA to create a new sub-registry, entitled 3998 "DOTS Signal Channel Attack Status Codes". Codes in this registry 3999 are used as valid values of 'attack-status' parameter. 4001 The registry is initially populated with the following values: 4003 +------+-------------------------------+----------------+-----------+ 4004 | Code | Label | Description | Reference | 4005 +------+-------------------------------+----------------+-----------+ 4006 | 1 | under-attack | The DOTS | [RFCXXXX] | 4007 | | | client | | 4008 | | | determines | | 4009 | | | that it is | | 4010 | | | still under | | 4011 | | | attack. | | 4012 | 2 | attack-successfully-mitigated | The DOTS | [RFCXXXX] | 4013 | | | client | | 4014 | | | determines | | 4015 | | | that the | | 4016 | | | attack is | | 4017 | | | successfully | | 4018 | | | mitigated. | | 4019 +------+-------------------------------+----------------+-----------+ 4021 New codes can be assigned via Standards Action [RFC8126]. 4023 9.7. DOTS Signal Channel YANG Modules 4025 This document requests IANA to register the following URIs in the 4026 "ns" subregistry within the "IETF XML Registry" [RFC3688]: 4028 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4029 Registrant Contact: The IESG. 4030 XML: N/A; the requested URI is an XML namespace. 4032 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4033 Registrant Contact: IANA. 4034 XML: N/A; the requested URI is an XML namespace. 4036 This document requests IANA to register the following YANG modules in 4037 the "YANG Module Names" subregistry [RFC7950] within the "YANG 4038 Parameters" registry. 4040 Name: ietf-signal 4041 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4042 Maintained by IANA: N 4043 Prefix: signal 4044 Reference: RFC XXXX 4046 Name: iana-signal 4047 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4048 Maintained by IANA: Y 4049 Prefix: iana-signal 4050 Reference: RFC XXXX 4052 This document defines the initial version of the IANA-maintained 4053 iana-dots-signal-channel YANG module. IANA is requested to add this 4054 note: 4056 Status, conflict status, conflict cause, and attack status values 4057 must not be directly added to the iana-dots-signal-channel YANG 4058 module. They must instead be respectively added to the "DOTS 4059 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4060 Codes", and "DOTS Attack Status Codes" registries. 4062 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4063 status' value is respectively added to the "DOTS Status Codes", "DOTS 4064 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4065 Status Codes" registry, a new "enum" statement must be added to the 4066 iana-dots-signal-channel YANG module. The following "enum" 4067 statement, and substatements thereof, should be defined: 4069 "enum": Replicates the label from the registry. 4071 "value": Contains the IANA-assigned value corresponding to the 4072 'status', 'conflict-status', 'conflict-cause', or 4073 'attack-status'. 4075 "description": Replicates the description from the registry. 4077 "reference": Replicates the reference from the registry and add the 4078 title of the document. 4080 When the iana-dots-signal-channel YANG module is updated, a new 4081 "revision" statement must be added in front of the existing revision 4082 statements. 4084 IANA is requested to add this note to "DOTS Status Codes", "DOTS 4085 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4086 Status Codes" registries: 4088 When this registry is modified, the YANG module iana-dots-signal- 4089 channel must be updated as defined in [RFCXXXX]. 4091 10. Security Considerations 4093 High-level DOTS security considerations are documented in 4094 [I-D.ietf-dots-requirements] and [I-D.ietf-dots-architecture]. 4096 Authenticated encryption MUST be used for data confidentiality and 4097 message integrity. The interaction between the DOTS agents requires 4098 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4099 (TLS) with a cipher suite offering confidentiality protection, and 4100 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4101 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4102 is specified in Section 7. 4104 If TCP is used between DOTS agents, an attacker may be able to inject 4105 RST packets, bogus application segments, etc., regardless of whether 4106 TLS authentication is used. Because the application data is TLS 4107 protected, this will not result in the application receiving bogus 4108 data, but it will constitute a DoS on the connection. This attack 4109 can be countered by using TCP-AO [RFC5925]. If TCP-AO is used, then 4110 any bogus packets injected by an attacker will be rejected by the 4111 TCP-AO integrity check and therefore will never reach the TLS layer. 4113 An attack vector that can be achieved if the 'cuid' is guessable is a 4114 misbehaving DOTS client from within the client's domain which uses 4115 the 'cuid' of another DOTS client of the domain to delete or alter 4116 active mitigations. For this attack vector to happen, the 4117 misbehaving client needs to pass the security validation checks by 4118 the DOTS server, and eventually the checks of a client-domain DOTS 4119 gateway. 4121 A similar attack can be achieved by a compromised DOTS client which 4122 can sniff the TLS 1.2 handshake, use the client certificate to 4123 identify the 'cuid' used by another DOTS client. This attack is not 4124 possible if algorithms such as [RFC4122] are used to generate the 4125 'cuid'. Likewise, this attack is not possible with TLS 1.3 because 4126 most of the TLS handshake is encrypted and the client certificate is 4127 not visible to eavesdroppers. 4129 Rate-limiting DOTS requests, including those with new 'cuid' values, 4130 from the same DOTS client defends against DoS attacks that would 4131 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4132 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4133 DOTS servers. 4135 In order to prevent leaking internal information outside a client- 4136 domain, DOTS gateways located in the client-domain SHOULD NOT reveal 4137 the identification information that pertains to internal DOTS clients 4138 (e.g., source IP address, client's hostname) unless explicitly 4139 configured to do so. 4141 DOTS servers MUST verify that requesting DOTS clients are entitled to 4142 trigger actions on a given IP prefix. That is, only actions on IP 4143 resources that belong to the DOTS client' domain MUST be authorized 4144 by a DOTS server. The exact mechanism for the DOTS servers to 4145 validate that the target prefixes are within the scope of the DOTS 4146 client domain is deployment-specific. 4148 The presence of DOTS gateways may lead to infinite forwarding loops, 4149 which is undesirable. To prevent and detect such loops, this 4150 document uses the Hop-Limit Option. 4152 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4153 privacy enabling protocols (e.g., DNS over TLS [RFC7858], DoH 4154 [RFC8484]) to prevent eavesdroppers from possibly identifying the 4155 target resources protected by the DDoS mitigation service and means 4156 to ensure the target FQDN resolution is authentic (e.g., DNSSEC 4157 [RFC4034]). 4159 CoAP-specific security considerations are discussed in Section 11 of 4160 [RFC7252], while CBOR-related security considerations are discussed 4161 in Section 8 of [RFC7049]. 4163 11. Contributors 4165 The following individuals have contributed to this document: 4167 o Jon Shallow, NCC Group, Email: jon.shallow@nccgroup.trust 4169 o Mike Geller, Cisco Systems, Inc. 3250 Florida 33309 USA, Email: 4170 mgeller@cisco.com 4172 o Robert Moskowitz, HTT Consulting Oak Park, MI 42837 United States, 4173 Email: rgm@htt-consult.com 4175 o Dan Wing, Email: dwing-ietf@fuggles.com 4177 12. Acknowledgements 4179 Thanks to Christian Jacquenet, Roland Dobbins, Roman D. Danyliw, 4180 Michael Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang 4181 Xia, Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, 4182 Nesredien Suleiman, and Stephen Farrell for the discussion and 4183 comments. 4185 The authors would like to give special thanks to Kaname Nishizuka and 4186 Jon Shallow for their efforts in implementing the protocol and 4187 performing interop testing at IETF Hackathons. 4189 Thanks to the core WG for the recommendations on Hop-Limit and 4190 redirect signaling. 4192 Special thanks to Benjamin Kaduk for the detailed AD review. 4194 13. References 4196 13.1. Normative References 4198 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4199 Requirement Levels", BCP 14, RFC 2119, 4200 DOI 10.17487/RFC2119, March 1997, 4201 . 4203 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4204 DOI 10.17487/RFC3688, January 2004, 4205 . 4207 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4208 Ciphersuites for Transport Layer Security (TLS)", 4209 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4210 . 4212 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4213 (CIDR): The Internet Address Assignment and Aggregation 4214 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4215 2006, . 4217 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4218 (TLS) Protocol Version 1.2", RFC 5246, 4219 DOI 10.17487/RFC5246, August 2008, 4220 . 4222 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4223 Housley, R., and W. Polk, "Internet X.509 Public Key 4224 Infrastructure Certificate and Certificate Revocation List 4225 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4226 . 4228 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 4229 Uniform Resource Identifiers (URIs)", RFC 5785, 4230 DOI 10.17487/RFC5785, April 2010, 4231 . 4233 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4234 Extensions: Extension Definitions", RFC 6066, 4235 DOI 10.17487/RFC6066, January 2011, 4236 . 4238 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4239 Verification of Domain-Based Application Service Identity 4240 within Internet Public Key Infrastructure Using X.509 4241 (PKIX) Certificates in the Context of Transport Layer 4242 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4243 2011, . 4245 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4246 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4247 January 2012, . 4249 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4250 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4251 . 4253 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4254 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4255 October 2013, . 4257 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4258 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4259 Transport Layer Security (TLS) and Datagram Transport 4260 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4261 June 2014, . 4263 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4264 Application Protocol (CoAP)", RFC 7252, 4265 DOI 10.17487/RFC7252, June 2014, 4266 . 4268 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4269 "Recommendations for Secure Use of Transport Layer 4270 Security (TLS) and Datagram Transport Layer Security 4271 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4272 2015, . 4274 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4275 Application Protocol (CoAP)", RFC 7641, 4276 DOI 10.17487/RFC7641, September 2015, 4277 . 4279 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4280 Layer Security (TLS) False Start", RFC 7918, 4281 DOI 10.17487/RFC7918, August 2016, 4282 . 4284 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 4285 (TLS) Cached Information Extension", RFC 7924, 4286 DOI 10.17487/RFC7924, July 2016, 4287 . 4289 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 4290 RFC 7950, DOI 10.17487/RFC7950, August 2016, 4291 . 4293 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 4294 RFC 7951, DOI 10.17487/RFC7951, August 2016, 4295 . 4297 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 4298 the Constrained Application Protocol (CoAP)", RFC 7959, 4299 DOI 10.17487/RFC7959, August 2016, 4300 . 4302 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 4303 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 4304 March 2017, . 4306 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 4307 Writing an IANA Considerations Section in RFCs", BCP 26, 4308 RFC 8126, DOI 10.17487/RFC8126, June 2017, 4309 . 4311 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 4312 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 4313 May 2017, . 4315 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 4316 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 4317 Application Protocol) over TCP, TLS, and WebSockets", 4318 RFC 8323, DOI 10.17487/RFC8323, February 2018, 4319 . 4321 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 4322 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 4323 . 4325 13.2. Informative References 4327 [I-D.boucadair-dots-earlydata] 4328 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 4329 boucadair-dots-earlydata-00 (work in progress), January 4330 2019. 4332 [I-D.boucadair-dots-server-discovery] 4333 Boucadair, M., K, R., and P. Patil, "Distributed-Denial- 4334 of-Service Open Threat Signaling (DOTS) Server Discovery", 4335 draft-boucadair-dots-server-discovery-05 (work in 4336 progress), October 2018. 4338 [I-D.ietf-core-comi] 4339 Veillette, M., Stok, P., Pelov, A., and A. Bierman, "CoAP 4340 Management Interface", draft-ietf-core-comi-04 (work in 4341 progress), November 2018. 4343 [I-D.ietf-core-hop-limit] 4344 Boucadair, M., K, R., and J. Shallow, "Constrained 4345 Application Protocol (CoAP) Hop Limit Option", draft-ietf- 4346 core-hop-limit-03 (work in progress), February 2019. 4348 [I-D.ietf-core-yang-cbor] 4349 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 4350 Minaburo, "CBOR Encoding of Data Modeled with YANG", 4351 draft-ietf-core-yang-cbor-07 (work in progress), September 4352 2018. 4354 [I-D.ietf-dots-architecture] 4355 Mortensen, A., Andreasen, F., K, R., Teague, N., Compton, 4356 R., and c. christopher_gray3@cable.comcast.com, 4357 "Distributed-Denial-of-Service Open Threat Signaling 4358 (DOTS) Architecture", draft-ietf-dots-architecture-12 4359 (work in progress), February 2019. 4361 [I-D.ietf-dots-data-channel] 4362 Boucadair, M. and R. K, "Distributed Denial-of-Service 4363 Open Threat Signaling (DOTS) Data Channel Specification", 4364 draft-ietf-dots-data-channel-27 (work in progress), 4365 February 2019. 4367 [I-D.ietf-dots-requirements] 4368 Mortensen, A., K, R., and R. Moskowitz, "Distributed 4369 Denial of Service (DDoS) Open Threat Signaling 4370 Requirements", draft-ietf-dots-requirements-22 (work in 4371 progress), March 2019. 4373 [I-D.ietf-dots-use-cases] 4374 Dobbins, R., Migault, D., Fouant, S., Moskowitz, R., 4375 Teague, N., Xia, L., and K. Nishizuka, "Use cases for DDoS 4376 Open Threat Signaling", draft-ietf-dots-use-cases-17 (work 4377 in progress), January 2019. 4379 [I-D.ietf-tls-dtls13] 4380 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 4381 Datagram Transport Layer Security (DTLS) Protocol Version 4382 1.3", draft-ietf-tls-dtls13-31 (work in progress), March 4383 2019. 4385 [IANA.CBOR.Tags] 4386 IANA, "Concise Binary Object Representation (CBOR) Tags", 4387 . 4390 [IANA.CoAP.Content-Formats] 4391 IANA, "CoAP Content-Formats", 4392 . 4395 [IANA.MediaTypes] 4396 IANA, "Media Types", 4397 . 4399 [proto_numbers] 4400 "IANA, "Protocol Numbers"", 2011, 4401 . 4403 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4404 DOI 10.17487/RFC0791, September 1981, 4405 . 4407 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 4408 Address Translator (Traditional NAT)", RFC 3022, 4409 DOI 10.17487/RFC3022, January 2001, 4410 . 4412 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4413 Resource Identifier (URI): Generic Syntax", STD 66, 4414 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4415 . 4417 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 4418 Rose, "Resource Records for the DNS Security Extensions", 4419 RFC 4034, DOI 10.17487/RFC4034, March 2005, 4420 . 4422 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 4423 Unique IDentifier (UUID) URN Namespace", RFC 4122, 4424 DOI 10.17487/RFC4122, July 2005, 4425 . 4427 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 4428 Congestion Control Protocol (DCCP)", RFC 4340, 4429 DOI 10.17487/RFC4340, March 2006, 4430 . 4432 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 4433 Denial-of-Service Considerations", RFC 4732, 4434 DOI 10.17487/RFC4732, December 2006, 4435 . 4437 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 4438 Translation (NAT) Behavioral Requirements for Unicast 4439 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 4440 2007, . 4442 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 4443 RFC 4960, DOI 10.17487/RFC4960, September 2007, 4444 . 4446 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 4447 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 4448 . 4450 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing, 4451 "Session Traversal Utilities for NAT (STUN)", RFC 5389, 4452 DOI 10.17487/RFC5389, October 2008, 4453 . 4455 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 4456 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 4457 June 2010, . 4459 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 4460 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 4461 DOI 10.17487/RFC6052, October 2010, 4462 . 4464 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 4465 NAT64: Network Address and Protocol Translation from IPv6 4466 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 4467 April 2011, . 4469 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 4470 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 4471 DOI 10.17487/RFC6234, May 2011, 4472 . 4474 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 4475 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 4476 . 4478 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 4479 "Default Address Selection for Internet Protocol Version 6 4480 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 4481 . 4483 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 4484 Specifications and Registration Procedures", BCP 13, 4485 RFC 6838, DOI 10.17487/RFC6838, January 2013, 4486 . 4488 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 4489 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 4490 DOI 10.17487/RFC6887, April 2013, 4491 . 4493 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 4494 A., and H. Ashida, "Common Requirements for Carrier-Grade 4495 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 4496 April 2013, . 4498 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 4499 "Enrollment over Secure Transport", RFC 7030, 4500 DOI 10.17487/RFC7030, October 2013, 4501 . 4503 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 4504 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 4505 . 4507 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 4508 "Architectural Considerations in Smart Object Networking", 4509 RFC 7452, DOI 10.17487/RFC7452, March 2015, 4510 . 4512 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 4513 NETCONF Protocol over Transport Layer Security (TLS) with 4514 Mutual X.509 Authentication", RFC 7589, 4515 DOI 10.17487/RFC7589, June 2015, 4516 . 4518 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 4519 and P. Hoffman, "Specification for DNS over Transport 4520 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 4521 2016, . 4523 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 4524 Better Connectivity Using Concurrency", RFC 8305, 4525 DOI 10.17487/RFC8305, December 2017, 4526 . 4528 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 4529 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 4530 . 4532 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 4533 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 4534 . 4536 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 4537 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 4538 January 2019, . 4540 Authors' Addresses 4542 Tirumaleswar Reddy (editor) 4543 McAfee, Inc. 4544 Embassy Golf Link Business Park 4545 Bangalore, Karnataka 560071 4546 India 4548 Email: kondtir@gmail.com 4550 Mohamed Boucadair (editor) 4551 Orange 4552 Rennes 35000 4553 France 4555 Email: mohamed.boucadair@orange.com 4557 Prashanth Patil 4558 Cisco Systems, Inc. 4560 Email: praspati@cisco.com 4561 Andrew Mortensen 4562 Arbor Networks, Inc. 4563 2727 S. State St 4564 Ann Arbor, MI 48104 4565 United States 4567 Email: andrew@moretension.com 4569 Nik Teague 4570 Verisign, Inc. 4571 United States 4573 Email: nteague@verisign.com