idnits 2.17.1 draft-ietf-dots-rfc8782-bis-04.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 2720 has weird spacing: '...er-port ine...' == Line 2743 has weird spacing: '...er-port ine...' == Line 2750 has weird spacing: '...cl-name lea...' -- The document date (December 3, 2020) is 1233 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 4800, but not defined ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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-10 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-13 == Outdated reference: A later version (-13) exists of draft-ietf-dots-multihoming-05 == Outdated reference: A later version (-25) exists of draft-ietf-dots-telemetry-14 == Outdated reference: A later version (-43) exists of draft-ietf-tls-dtls13-39 -- Obsolete informational reference (is this intentional?): RFC 4960 (Obsoleted by RFC 9260) -- Obsolete informational reference (is this intentional?): RFC 8499 (Obsoleted by RFC 9499) -- Obsolete informational reference (is this intentional?): RFC 8782 (Obsoleted by RFC 9132) Summary: 6 errors (**), 0 flaws (~~), 10 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DOTS M. Boucadair, Ed. 3 Internet-Draft Orange 4 Obsoletes: 8782 (if approved) J. Shallow 5 Intended status: Standards Track 6 Expires: June 6, 2021 T. Reddy.K 7 McAfee 8 December 3, 2020 10 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 11 Channel Specification 12 draft-ietf-dots-rfc8782-bis-04 14 Abstract 16 This document specifies the Distributed Denial-of-Service Open Threat 17 Signaling (DOTS) signal channel, a protocol for signaling the need 18 for protection against Distributed Denial-of-Service (DDoS) attacks 19 to a server capable of enabling network traffic mitigation on behalf 20 of the requesting client. 22 A companion document defines the DOTS data channel, a separate 23 reliable communication layer for DOTS management and configuration 24 purposes. 26 This document obsoletes RFC 8782. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on June 6, 2021. 45 Copyright Notice 47 Copyright (c) 2020 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. Design Overview . . . . . . . . . . . . . . . . . . . . . . . 6 65 3.1. Backward Compatibility Considerations . . . . . . . . . . 9 66 4. DOTS Signal Channel: Messages & Behaviors . . . . . . . . . . 10 67 4.1. DOTS Server(s) Discovery . . . . . . . . . . . . . . . . 10 68 4.2. CoAP URIs . . . . . . . . . . . . . . . . . . . . . . . . 10 69 4.3. Happy Eyeballs for DOTS Signal Channel . . . . . . . . . 10 70 4.4. DOTS Mitigation Methods . . . . . . . . . . . . . . . . . 13 71 4.4.1. Request Mitigation . . . . . . . . . . . . . . . . . 13 72 4.4.2. Retrieve Information Related to a Mitigation . . . . 29 73 4.4.2.1. DOTS Servers Sending Mitigation Status . . . . . 35 74 4.4.2.2. DOTS Clients Polling for Mitigation Status . . . 37 75 4.4.3. Efficacy Update from DOTS Clients . . . . . . . . . . 38 76 4.4.4. Withdraw a Mitigation . . . . . . . . . . . . . . . . 40 77 4.5. DOTS Signal Channel Session Configuration . . . . . . . . 41 78 4.5.1. Discover Configuration Parameters . . . . . . . . . . 43 79 4.5.2. Convey DOTS Signal Channel Session Configuration . . 48 80 4.5.3. Configuration Freshness and Notifications . . . . . . 54 81 4.5.4. Delete DOTS Signal Channel Session Configuration . . 55 82 4.6. Redirected Signaling . . . . . . . . . . . . . . . . . . 56 83 4.7. Heartbeat Mechanism . . . . . . . . . . . . . . . . . . . 58 84 5. DOTS Signal Channel YANG Modules . . . . . . . . . . . . . . 61 85 5.1. Tree Structure . . . . . . . . . . . . . . . . . . . . . 61 86 5.2. IANA DOTS Signal Channel YANG Module . . . . . . . . . . 64 87 5.3. IETF DOTS Signal Channel YANG Module . . . . . . . . . . 68 88 6. YANG/JSON Mapping Parameters to CBOR . . . . . . . . . . . . 81 89 7. (D)TLS Protocol Profile and Performance Considerations . . . 85 90 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 85 91 7.2. (D)TLS 1.3 Considerations . . . . . . . . . . . . . . . . 86 92 7.3. DTLS MTU and Fragmentation . . . . . . . . . . . . . . . 88 94 8. Mutual Authentication of DOTS Agents & Authorization of DOTS 95 Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 96 9. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 91 97 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 92 98 10.1. DOTS Signal Channel UDP and TCP Port Number . . . . . . 92 99 10.2. Well-Known 'dots' URI . . . . . . . . . . . . . . . . . 93 100 10.3. Media Type Registration . . . . . . . . . . . . . . . . 93 101 10.4. CoAP Content-Formats Registration . . . . . . . . . . . 94 102 10.5. CBOR Tag Registration . . . . . . . . . . . . . . . . . 95 103 10.6. DOTS Signal Channel Protocol Registry . . . . . . . . . 95 104 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry . . 95 105 10.6.1.1. Registration Template . . . . . . . . . . . . . 95 106 10.6.1.2. Update Subregistry Content . . . . . . . . . . . 97 107 10.6.2. Status Codes Subregistry . . . . . . . . . . . . . . 100 108 10.6.3. Conflict Status Codes Subregistry . . . . . . . . . 101 109 10.6.4. Conflict Cause Codes Subregistry . . . . . . . . . . 102 110 10.6.5. Attack Status Codes Subregistry . . . . . . . . . . 103 111 10.7. DOTS Signal Channel YANG Modules . . . . . . . . . . . . 104 112 11. Security Considerations . . . . . . . . . . . . . . . . . . . 106 113 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 108 114 12.1. Normative References . . . . . . . . . . . . . . . . . . 108 115 12.2. Informative References . . . . . . . . . . . . . . . . . 111 116 Appendix A. Summary of Changes From RFC8782 . . . . . . . . . . 116 117 Appendix B. CUID Generation . . . . . . . . . . . . . . . . . . 117 118 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 117 119 C.1. Acknowledgements from RFC8782 . . . . . . . . . . . . . . 117 120 Appendix D. Contributors . . . . . . . . . . . . . . . . . . . . 118 121 D.1. Authors of RFC8782 . . . . . . . . . . . . . . . . . . . 118 122 D.2. Contributors to RFC8782 . . . . . . . . . . . . . . . . . 119 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 120 125 1. Introduction 127 A Distributed Denial-of-Service (DDoS) attack is a distributed 128 attempt to make machines or network resources unavailable to their 129 intended users. In most cases, sufficient scale for an effective 130 attack can be achieved by compromising enough end hosts and using 131 those infected hosts to perpetrate and amplify the attack. The 132 victim in this attack can be an application server, a host, a router, 133 a firewall, or an entire network. 135 Network applications have finite resources like CPU cycles, the 136 number of processes or threads they can create and use, the maximum 137 number of simultaneous connections they can handle, the resources 138 assigned to the control plane, etc. When processing network traffic, 139 such applications are supposed to use these resources to provide the 140 intended functionality in the most efficient manner. However, a DDoS 141 attacker may be able to prevent an application from performing its 142 intended task by making the application exhaust its finite resources. 144 A TCP DDoS SYN flood [RFC4987], for example, is a memory-exhausting 145 attack while an ACK flood is a CPU-exhausting attack. Attacks on the 146 link are carried out by sending enough traffic so that the link 147 becomes congested, thereby likely causing packet loss for legitimate 148 traffic. Stateful firewalls can also be attacked by sending traffic 149 that causes the firewall to maintain an excessive number of states 150 that may jeopardize the firewall's operation overall, in addition to 151 likely performance impacts. The firewall then runs out of memory, 152 and it can no longer instantiate the states required to process 153 legitimate flows. Other possible DDoS attacks are discussed in 154 [RFC4732]. 156 In many cases, it may not be possible for network administrators to 157 determine the cause(s) of an attack. They may instead just realize 158 that certain resources seem to be under attack. This document 159 defines a lightweight protocol that allows a DOTS client to request 160 mitigation from one or more DOTS servers for protection against 161 detected, suspected, or anticipated attacks. This protocol enables 162 cooperation between DOTS agents to permit a highly automated network 163 defense that is robust, reliable, and secure. Note that "secure" 164 means the support of the features defined in Section 2.4 of 165 [RFC8612]. 167 An example of a network diagram that illustrates a deployment of DOTS 168 agents is shown in Figure 1. In this example, a DOTS server is 169 operating on the access network. A DOTS client is located on the LAN 170 (Local Area Network), while a DOTS gateway is embedded in the CPE 171 (Customer Premises Equipment). 173 Network 174 Resource CPE Router Access Network __________ 175 +-----------+ +--------------+ +-------------+ / \ 176 | |___| |____| |___ | Internet | 177 |DOTS Client| | DOTS Gateway | | DOTS Server | | | 178 | | | | | | | | 179 +-----------+ +--------------+ +-------------+ \__________/ 181 Figure 1: Sample DOTS Deployment (1) 183 DOTS servers can also be reachable over the Internet, as depicted in 184 Figure 2. 186 Network DDoS Mitigation 187 Resource CPE Router __________ Service 188 +-----------+ +--------------+ / \ +-------------+ 189 | |___| |____| |___ | | 190 |DOTS Client| | DOTS Gateway | | Internet | | DOTS Server | 191 | | | | | | | | 192 +-----------+ +--------------+ \__________/ +-------------+ 194 Figure 2: Sample DOTS Deployment (2) 196 In typical deployments, the DOTS client belongs to a different 197 administrative domain than the DOTS server. For example, the DOTS 198 client is embedded in a firewall protecting services owned and 199 operated by a customer, while the DOTS server is owned and operated 200 by a different administrative entity (service provider, typically) 201 providing DDoS mitigation services. The latter might or might not 202 provide connectivity services to the network hosting the DOTS client. 204 The DOTS server may (not) be co-located with the DOTS mitigator. In 205 typical deployments, the DOTS server belongs to the same 206 administrative domain as the mitigator. The DOTS client can 207 communicate directly with a DOTS server or indirectly via a DOTS 208 gateway. 210 This document adheres to the DOTS architecture [RFC8811]. The 211 requirements for DOTS signal channel protocol are documented in 212 [RFC8612]. This document satisfies all the use cases discussed in 213 [I-D.ietf-dots-use-cases]. 215 This document focuses on the DOTS signal channel. This is a 216 companion document of the DOTS data channel specification [RFC8783] 217 that defines a configuration and a bulk data exchange mechanism 218 supporting the DOTS signal channel. 220 Backward compatibility (including upgrade) considerations are 221 discussed in Section 3.1. 223 2. Terminology 225 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 226 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 227 "OPTIONAL" in this document are to be interpreted as described in BCP 228 14 [RFC2119][RFC8174] when, and only when, they appear in all 229 capitals, as shown here. 231 (D)TLS is used for statements that apply to both Transport Layer 232 Security [RFC5246] [RFC8446] and Datagram Transport Layer Security 234 [RFC6347]. Specific terms are used for any statement that applies to 235 either protocol alone. 237 The reader should be familiar with the terms defined in [RFC8612]. 239 The meaning of the symbols in YANG tree diagrams are defined in 240 [RFC8340] and [RFC8791]. 242 3. Design Overview 244 The DOTS signal channel is built on top of the Constrained 245 Application Protocol (CoAP) [RFC7252], a lightweight protocol 246 originally designed for constrained devices and networks. The many 247 features of CoAP (expectation of packet loss, support for 248 asynchronous Non-confirmable messaging, congestion control, small 249 message overhead limiting the need for fragmentation, use of minimal 250 resources, and support for (D)TLS) make it a good candidate upon 251 which to build the DOTS signaling mechanism. 253 DOTS clients and servers behave as CoAP endpoints. By default, a 254 DOTS client (or server) behaves as a CoAP client (or server). 255 Nevertheless, a DOTS client (or server) behaves as a CoAP server (or 256 client) for specific operations such as DOTS heartbeat operations 257 (Section 4.7). 259 The DOTS signal channel is layered on existing standards (see 260 Figure 3). 262 +---------------------+ 263 | DOTS Signal Channel | 264 +---------------------+ 265 | CoAP | 266 +----------+----------+ 267 | TLS | DTLS | 268 +----------+----------+ 269 | TCP | UDP | 270 +----------+----------+ 271 | IP | 272 +---------------------+ 274 Figure 3: Abstract Layering of DOTS Signal Channel over CoAP over 275 (D)TLS 277 In some cases, a DOTS client and server may have a mutual agreement 278 to use a specific port number, such as by explicit configuration or 279 dynamic discovery [I-D.ietf-dots-server-discovery]. Absent such 280 mutual agreement, the DOTS signal channel MUST run over port number 281 4646 as defined in Section 10.1, for both UDP and TCP. In order to 282 use a distinct port number (as opposed to 4646), DOTS clients and 283 servers SHOULD support a configurable parameter to supply the port 284 number to use. 286 | Note: The rationale for not using the default port number 5684 287 | ((D)TLS CoAP) is to avoid the discovery of services and 288 | resources discussed in [RFC7252] and allow for differentiated 289 | behaviors in environments where both a DOTS gateway and an 290 | Internet of Things (IoT) gateway (e.g., Figure 3 of [RFC7452]) 291 | are co-located. 292 | 293 | Particularly, the use of a default port number is meant to 294 | simplify DOTS deployment in scenarios where no explicit IP 295 | address configuration is required. For example, the use of the 296 | default router as the DOTS server aims to ease DOTS deployment 297 | within LANs (in which CPEs embed a DOTS gateway as illustrated 298 | in Figures 1 and 2) without requiring a sophisticated discovery 299 | method and configuration tasks within the LAN. It is also 300 | possible to use anycast addresses for DOTS servers to simplify 301 | DOTS client configuration, including service discovery. In 302 | such an anycast-based scenario, a DOTS client initiating a DOTS 303 | session to the DOTS server anycast address may, for example, be 304 | (1) redirected to the DOTS server unicast address to be used by 305 | the DOTS client following the procedure discussed in 306 | Section 4.6 or (2) relayed to a unicast DOTS server. 308 The signal channel uses the "coaps" URI scheme defined in Section 6 309 of [RFC7252] and the "coaps+tcp" URI scheme defined in Section 8.2 of 310 [RFC8323] to identify DOTS server resources that are accessible using 311 CoAP over UDP secured with DTLS and CoAP over TCP secured with TLS, 312 respectively. 314 The DOTS signal channel can be established between two DOTS agents 315 prior to or during an attack. The DOTS signal channel is initiated 316 by the DOTS client. The DOTS client can then negotiate, configure, 317 and retrieve the DOTS signal channel session behavior with its DOTS 318 peer (Section 4.5). Once the signal channel is established, the DOTS 319 agents may periodically send heartbeats to keep the channel active 320 (Section 4.7). At any time, the DOTS client may send a mitigation 321 request message (Section 4.4) to a DOTS server over the active signal 322 channel. While mitigation is active (because of the higher 323 likelihood of packet loss during a DDoS attack), the DOTS server 324 periodically sends status messages to the client, including basic 325 mitigation feedback details. Mitigation remains active until the 326 DOTS client explicitly terminates mitigation or the mitigation 327 lifetime expires. Also, the DOTS server may rely on the signal 328 channel session loss to trigger mitigation for preconfigured 329 mitigation requests (if any). 331 DOTS signaling can happen with DTLS over UDP and TLS over TCP. 332 Likewise, DOTS requests may be sent using IPv4 or IPv6 transfer 333 capabilities. A Happy Eyeballs procedure for the DOTS signal channel 334 is specified in Section 4.3. 336 A DOTS client is entitled to access only the resources it creates. 337 In particular, a DOTS client cannot retrieve data related to 338 mitigation requests created by other DOTS clients of the same DOTS 339 client domain. 341 Messages exchanged between DOTS agents are serialized using Concise 342 Binary Object Representation (CBOR) [RFC7049], a binary encoding 343 scheme designed for small code and message size. CBOR-encoded 344 payloads are used to carry signal channel-specific payload messages 345 that convey request parameters and response information such as 346 errors. In order to allow the reusing of data models across 347 protocols, [RFC7951] specifies the JavaScript Object Notation (JSON) 348 encoding of YANG-modeled data. A similar effort for CBOR is defined 349 in [I-D.ietf-core-yang-cbor]. 351 DOTS agents determine that a CBOR data structure is a DOTS signal 352 channel object from the application context, such as from the port 353 number assigned to the DOTS signal channel. The other method DOTS 354 agents use to indicate that a CBOR data structure is a DOTS signal 355 channel object is the use of the "application/dots+cbor" content type 356 (Section 10.3). 358 This document specifies a YANG module for representing DOTS 359 mitigation scopes, DOTS signal channel session configuration data, 360 and DOTS redirected signaling (Section 5). All parameters in the 361 payload of the DOTS signal channel are mapped to CBOR types as 362 specified in Table 5 (Section 6). 364 In order to prevent fragmentation, DOTS agents must follow the 365 recommendations documented in Section 4.6 of [RFC7252]. Refer to 366 Section 7.3 for more details. 368 DOTS agents MUST support GET, PUT, and DELETE CoAP methods. The 369 payload included in CoAP responses with 2.xx Response Codes MUST be 370 of content type "application/dots+cbor". CoAP responses with 4.xx 371 and 5.xx error Response Codes MUST include a diagnostic payload 372 (Section 5.5.2 of [RFC7252]). The diagnostic payload may contain 373 additional information to aid troubleshooting. 375 In deployments where multiple DOTS clients are enabled in a network 376 (owned and operated by the same entity), the DOTS server may detect 377 conflicting mitigation requests from these clients. This document 378 does not aim to specify a comprehensive list of conditions under 379 which a DOTS server will characterize two mitigation requests from 380 distinct DOTS clients as conflicting, nor does it recommend a DOTS 381 server behavior for processing conflicting mitigation requests. 382 Those considerations are implementation and deployment specific. 383 Nevertheless, this document specifies the mechanisms to notify DOTS 384 clients when conflicts occur, including the conflict cause 385 (Section 4.4). 387 In deployments where one or more translators (e.g., Traditional NAT 388 [RFC3022], CGN [RFC6888], NAT64 [RFC6146], NPTv6 [RFC6296]) are 389 enabled between the client's network and the DOTS server, any DOTS 390 signal channel messages forwarded to a DOTS server MUST NOT include 391 internal IP addresses/prefixes and/or port numbers; instead, external 392 addresses/prefixes and/or port numbers as assigned by the translator 393 MUST be used. This document does not make any recommendations about 394 possible translator discovery mechanisms. The following are some 395 (non-exhaustive) deployment examples that may be considered: 397 o Port Control Protocol (PCP) [RFC6887] or Session Traversal 398 Utilities for NAT (STUN) [RFC8489] may be used to retrieve the 399 external addresses/prefixes and/or port numbers. Information 400 retrieved by means of PCP or STUN will be used to feed the DOTS 401 signal channel messages that will be sent to a DOTS server. 403 o A DOTS gateway may be co-located with the translator. The DOTS 404 gateway will need to update the DOTS messages based upon the local 405 translator's binding table. 407 3.1. Backward Compatibility Considerations 409 The main changes to [RFC8782] are listed in Appendix A. These 410 modifications are made with the constraint to avoid changes to the 411 mapping table defined in Table 5 of [RFC8782] (see also Section 6). 412 For both legacy and implementations that follow the present 413 specification, a DOTS signal channel attribute will thus have the 414 same CBOR key value and CBOR major type. The only upgrade that is 415 required to [RFC8782] implementations is to handle the CBOR key value 416 range "128-255" as comprehension-optional instead of comprehension- 417 required. Note that this range is anticipated to be used by the DOTS 418 telemetry [I-D.ietf-dots-telemetry] in which the following means are 419 supported to avoid that a DOTS signal channel message enriched with 420 telemetry data will exacerbate message failure: (1) DOTS agents use 421 dedicated (new) path suffixes (Section 5 of 422 [I-D.ietf-dots-telemetry]) and (2) a DOTS server won't include 423 telemetry attributes in its responses unless it is explicitly told to 424 do so by a DOTS client (Section 6.1.2 of [I-D.ietf-dots-telemetry]). 426 Future DOTS extensions that request a CBOR value in the range 427 "128-255" must support means similar to the aforementioned DOTS 428 telemetry ones. 430 4. DOTS Signal Channel: Messages & Behaviors 432 4.1. DOTS Server(s) Discovery 434 This document assumes that DOTS clients are provisioned with the 435 reachability information of their DOTS server(s) using any of a 436 variety of means (e.g., local configuration or dynamic means such as 437 DHCP [I-D.ietf-dots-server-discovery]). The description of such 438 means is out of scope of this document. 440 Likewise, it is out of the scope of this document to specify the 441 behavior to be followed by a DOTS client in order to send DOTS 442 requests when multiple DOTS servers are provisioned (e.g., contact 443 all DOTS servers, select one DOTS server among the list). Such 444 behavior is specified in other documents (e.g., 445 [I-D.ietf-dots-multihoming]). 447 4.2. CoAP URIs 449 The DOTS server MUST support the use of the path prefix of "/.well- 450 known/" as defined in [RFC8615] and the registered name of "dots". 451 Each DOTS operation is denoted by a path suffix that indicates the 452 intended operation. The operation path (Table 1) is appended to the 453 path prefix to form the URI used with a CoAP request to perform the 454 desired DOTS operation. 456 +-----------------------+----------------+-------------+ 457 | Operation | Operation Path | Details | 458 +=======================+================+=============+ 459 | Mitigation | /mitigate | Section 4.4 | 460 +-----------------------+----------------+-------------+ 461 | Session configuration | /config | Section 4.5 | 462 +-----------------------+----------------+-------------+ 463 | Heartbeat | /hb | Section 4.7 | 464 +-----------------------+----------------+-------------+ 466 Table 1: Operations and Corresponding URIs 468 4.3. Happy Eyeballs for DOTS Signal Channel 470 [RFC8612] mentions that DOTS agents will have to support both 471 connectionless and connection-oriented protocols. As such, the DOTS 472 signal channel is designed to operate with DTLS over UDP and TLS over 473 TCP. Further, a DOTS client may acquire a list of IPv4 and IPv6 474 addresses (Section 4.1), each of which can be used to contact the 475 DOTS server using UDP and TCP. If no list of IPv4 and IPv6 addresses 476 to contact the DOTS server is configured (or discovered), the DOTS 477 client adds the IPv4/IPv6 addresses of its default router to the 478 candidate list to contact the DOTS server. 480 The following specifies the procedure to follow to select the address 481 family and the transport protocol for sending DOTS signal channel 482 messages. 484 Such a procedure is needed to avoid experiencing long connection 485 delays. For example, if an IPv4 path to a DOTS server is functional, 486 but the DOTS server's IPv6 path is nonfunctional, a dual-stack DOTS 487 client may experience a significant connection delay compared to an 488 IPv4-only DOTS client in the same network conditions. The other 489 problem is that if a middlebox between the DOTS client and DOTS 490 server is configured to block UDP traffic, the DOTS client will fail 491 to establish a DTLS association with the DOTS server; consequently, 492 it will have to fall back to TLS over TCP, thereby incurring 493 significant connection delays. 495 To overcome these connection setup problems, the DOTS client attempts 496 to connect to its DOTS server(s) using both IPv6 and IPv4, and it 497 tries both DTLS over UDP and TLS over TCP following a DOTS Happy 498 Eyeballs approach. To some extent, this approach is similar to the 499 Happy Eyeballs mechanism defined in [RFC8305]. The connection 500 attempts are performed by the DOTS client when it initializes or, in 501 general, when it has to select an address family and transport to 502 contact its DOTS server. The results of the Happy Eyeballs procedure 503 are used by the DOTS client for sending its subsequent messages to 504 the DOTS server. The differences in behavior with respect to the 505 Happy Eyeballs mechanism [RFC8305] are listed below: 507 o The order of preference of the DOTS signal channel address family 508 and transport protocol (most preferred first) is the following: 509 UDP over IPv6, UDP over IPv4, TCP over IPv6, and finally TCP over 510 IPv4. This order adheres to the address preference order 511 specified in [RFC6724] and the DOTS signal channel preference that 512 promotes the use of UDP over TCP (to avoid TCP's head of line 513 blocking). 515 o After successfully establishing a connection, the DOTS client MUST 516 cache information regarding the outcome of each connection attempt 517 for a specific time period; it uses that information to avoid 518 thrashing the network with subsequent attempts. The cached 519 information is flushed when its age exceeds a specific time period 520 on the order of few minutes (e.g., 10 min). Typically, if the 521 DOTS client has to reestablish the connection with the same DOTS 522 server within a few seconds after the Happy Eyeballs mechanism is 523 completed, caching avoids thrashing the network especially in the 524 presence of DDoS attack traffic. 526 o If a DOTS signal channel session is established with TLS (but DTLS 527 failed), the DOTS client periodically repeats the mechanism to 528 discover whether DOTS signal channel messages with DTLS over UDP 529 become available from the DOTS server; this is so the DOTS client 530 can migrate the DOTS signal channel from TCP to UDP. Such probing 531 SHOULD NOT be done more frequently than every 24 hours and MUST 532 NOT be done more frequently than every 5 minutes. 534 When connection attempts are made during an attack, the DOTS client 535 SHOULD use a "Connection Attempt Delay" [RFC8305] set to 100 ms. 537 In Figure 4, the DOTS client proceeds with the connection attempts 538 following the rules in [RFC8305]. In this example, it is assumed 539 that the IPv6 path is broken and UDP traffic is dropped by a 540 middlebox, but this has little impact on the DOTS client because 541 there is not a long delay before using IPv4 and TCP. 543 +-----------+ +-----------+ 544 |DOTS Client| |DOTS Server| 545 +-----------+ +-----------+ 546 | | 547 T0 |--DTLS ClientHello, IPv6 ---->X | 548 T1 |--DTLS ClientHello, IPv4 ---->X | 549 T2 |--TCP SYN, IPv6-------------->X | 550 T3 |--TCP SYN, IPv4------------------------------------->| 551 |<-TCP SYNACK-----------------------------------------| 552 |--TCP ACK------------------------------------------->| 553 |<------------Establish TLS Session------------------>| 554 |----------------DOTS signal------------------------->| 555 | | 557 Note: 558 * Retransmission messages are not shown. 559 * T1-T0=T2-T1=T3-T2= Connection Attempt Delay. 561 Figure 4: DOTS Happy Eyeballs (Sample Flow) 563 A single DOTS signal channel between DOTS agents can be used to 564 exchange multiple DOTS signal messages. To reduce DOTS client and 565 DOTS server workload, DOTS clients SHOULD reuse the (D)TLS session. 567 4.4. DOTS Mitigation Methods 569 The following methods are used by a DOTS client to request, withdraw, 570 or retrieve the status of mitigation requests: 572 PUT: DOTS clients use the PUT method to request mitigation from a 573 DOTS server (Section 4.4.1). During active mitigation, DOTS 574 clients may use PUT requests to carry mitigation efficacy 575 updates to the DOTS server (Section 4.4.3). 577 GET: DOTS clients may use the GET method to subscribe to DOTS 578 server status messages or to retrieve the list of its 579 mitigations maintained by a DOTS server (Section 4.4.2). 581 DELETE: DOTS clients use the DELETE method to withdraw a request for 582 mitigation from a DOTS server (Section 4.4.4). 584 Mitigation request and response messages are marked as Non- 585 confirmable messages (Section 2.2 of [RFC7252]). 587 DOTS agents MUST NOT send more than one UDP datagram per round-trip 588 time (RTT) to the peer DOTS agent on average following the data 589 transmission guidelines discussed in Section 3.1.3 of [RFC8085]. 591 Requests marked by the DOTS client as Non-confirmable messages are 592 sent at regular intervals until a response is received from the DOTS 593 server. If the DOTS client cannot maintain an RTT estimate, it MUST 594 NOT send more than one Non-confirmable request every 3 seconds, and 595 SHOULD use an even less aggressive rate whenever possible (case 2 in 596 Section 3.1.3 of [RFC8085]). Mitigation requests MUST NOT be delayed 597 because of checks on probing rate (Section 4.7 of [RFC7252]). 599 JSON encoding of YANG modeled data [RFC7951] is used to illustrate 600 the various methods defined in the following subsections. Also, the 601 examples use the Labels defined in Sections 10.6.2, 10.6.3, 10.6.4, 602 and 10.6.5. 604 4.4.1. Request Mitigation 606 When a DOTS client requires mitigation for some reason, the DOTS 607 client uses the CoAP PUT method to send a mitigation request to its 608 DOTS server(s) (Figures 5 and 6). 610 If a DOTS client is entitled to solicit the DOTS service, the DOTS 611 server enables mitigation on behalf of the DOTS client by 612 communicating the DOTS client's request to a mitigator (which may be 613 co-located with the DOTS server) and relaying the feedback of the 614 thus-selected mitigator to the requesting DOTS client. 616 Header: PUT (Code=0.03) 617 Uri-Path: ".well-known" 618 Uri-Path: "dots" 619 Uri-Path: "mitigate" 620 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 621 Uri-Path: "mid=123" 622 Content-Format: "application/dots+cbor" 624 { 625 ... 626 } 628 Figure 5: PUT to Convey DOTS Mitigation Requests 630 The order of the Uri-Path options is important as it defines the CoAP 631 resource. In particular, 'mid' MUST follow 'cuid'. 633 The additional Uri-Path parameters to those defined in Section 4.2 634 are as follows: 636 cuid: Stands for Client Unique Identifier. A globally unique 637 identifier that is meant to prevent collisions among DOTS 638 clients, especially those from the same domain. It MUST be 639 generated by DOTS clients. 641 For the reasons discussed in Appendix A, implementations SHOULD 642 set 'cuid' using the following procedure: first, the DOTS 643 client inputs one of the following into the SHA-256 [RFC6234] 644 cryptographic hash: the DER-encoded ASN.1 representation of the 645 Subject Public Key Info (SPKI) of its X.509 certificate 646 [RFC5280], its raw public key [RFC7250], the "Pre-Shared Key 647 (PSK) identity" it uses in the TLS 1.2 ClientKeyExchange 648 message, or the "identity" it uses in the "pre_shared_key" TLS 649 1.3 extension. Then, the output of the cryptographic hash 650 algorithm is truncated to 16 bytes; truncation is done by 651 stripping off the final 16 bytes. The truncated output is 652 base64url encoded (Section 5 of [RFC4648]) with the trailing 653 "=" removed from the encoding, and the resulting value used as 654 the 'cuid'. 656 The 'cuid' is intended to be stable when communicating with a 657 given DOTS server, i.e., the 'cuid' used by a DOTS client 658 SHOULD NOT change over time. Distinct 'cuid' values MAY be 659 used by a single DOTS client per DOTS server. 661 If a DOTS client has to change its 'cuid' for some reason, it 662 MUST NOT do so when mitigations are still active for the old 663 'cuid'. The 'cuid' SHOULD be 22 characters to avoid DOTS 664 signal message fragmentation over UDP. Furthermore, if that 665 DOTS client created aliases and filtering entries at the DOTS 666 server by means of the DOTS data channel, it MUST delete all 667 the entries bound to the old 'cuid' and reinstall them using 668 the new 'cuid'. 670 DOTS servers MUST return 4.09 (Conflict) error code to a DOTS 671 peer to notify that the 'cuid' is already in use by another 672 DOTS client. Upon receipt of that error code, a new 'cuid' 673 MUST be generated by the DOTS peer (e.g., using [RFC4122]). 675 Client-domain DOTS gateways MUST handle 'cuid' collision 676 directly and it is RECOMMENDED that 'cuid' collision is handled 677 directly by server-domain DOTS gateways. 679 DOTS gateways MAY rewrite the 'cuid' used by peer DOTS clients. 680 Triggers for such rewriting are out of scope. 682 This is a mandatory Uri-Path parameter. 684 mid: Identifier for the mitigation request represented with an 685 integer. This identifier MUST be unique for each mitigation 686 request bound to the DOTS client, i.e., the 'mid' parameter 687 value in the mitigation request needs to be unique (per 'cuid' 688 and DOTS server) relative to the 'mid' parameter values of 689 active mitigation requests conveyed from the DOTS client to the 690 DOTS server. 692 In order to handle out-of-order delivery of mitigation 693 requests, 'mid' values MUST increase monotonically. 695 If the 'mid' value has reached 3/4 of (2^(32) - 1) (i.e., 696 3221225471) and no attack is detected, the DOTS client MUST 697 reset 'mid' to 0 to handle 'mid' rollover. If the DOTS client 698 maintains mitigation requests with preconfigured scopes, it 699 MUST recreate them with the 'mid' restarting at 0. 701 This identifier MUST be generated by the DOTS client. 703 This is a mandatory Uri-Path parameter. 705 'cuid' and 'mid' MUST NOT appear in the PUT request message body 706 (Figure 6). The schema in Figure 6 uses the types defined in 707 Section 6. Note that this figure (and other similar figures 708 depicting a schema) are non-normative sketches of the structure of 709 the message. 711 { 712 "ietf-dots-signal-channel:mitigation-scope": { 713 "scope": [ 714 { 715 "target-prefix": [ 716 "string" 717 ], 718 "target-port-range": [ 719 { 720 "lower-port": number, 721 "upper-port": number 722 } 723 ], 724 "target-protocol": [ 725 number 726 ], 727 "target-fqdn": [ 728 "string" 729 ], 730 "target-uri": [ 731 "string" 732 ], 733 "alias-name": [ 734 "string" 735 ], 736 "lifetime": number, 737 "trigger-mitigation": true|false 738 } 739 ] 740 } 741 } 743 Figure 6: PUT to Convey DOTS Mitigation Requests (Message Body 744 Schema) 746 The parameters in the CBOR body (Figure 6) of the PUT request are 747 described below: 749 target-prefix: A list of prefixes identifying resources under 750 attack. Prefixes are represented using Classless Inter-Domain 751 Routing (CIDR) notation [RFC4632]. 753 As a reminder, the prefix length must be less than or equal to 32 754 for IPv4 and 128 for IPv6. 756 The prefix list MUST NOT include broadcast, loopback, or multicast 757 addresses. These addresses are considered to be invalid values. 758 In addition, the DOTS server MUST validate that target prefixes 759 are within the scope of the DOTS client domain. Other validation 760 checks may be supported by DOTS servers. 762 This is an optional attribute. 764 target-port-range: A list of port numbers bound to resources under 765 attack. 767 A port range is defined by two bounds, a lower port number 768 ('lower-port') and an upper port number ('upper-port'). When only 769 'lower-port' is present, it represents a single port number. 771 For TCP, UDP, Stream Control Transmission Protocol (SCTP) 772 [RFC4960], or Datagram Congestion Control Protocol (DCCP) 773 [RFC4340], a range of ports can be, for example, 0-1023, 774 1024-65535, or 1024-49151. 776 This is an optional attribute. 778 target-protocol: A list of protocols involved in an attack. Values 779 are taken from the IANA protocol registry [IANA-Proto]. 781 If 'target-protocol' is not specified, then the request applies to 782 any protocol. 784 This is an optional attribute. 786 target-fqdn: A list of Fully Qualified Domain Names (FQDNs) 787 identifying resources under attack [RFC8499]. 789 How a name is passed to an underlying name resolution library is 790 implementation and deployment specific. Nevertheless, once the 791 name is resolved into one or multiple IP addresses, DOTS servers 792 MUST apply the same validation checks as those for 'target- 793 prefix'. 795 The use of FQDNs may be suboptimal because: 797 * It induces both an extra load and increased delays on the DOTS 798 server to handle and manage DNS resolution requests. 800 * It does not guarantee that the DOTS server will resolve a name 801 to the same IP addresses that the DOTS client does. 803 This is an optional attribute. 805 target-uri: A list of URIs [RFC3986] identifying resources under 806 attack. 808 The same validation checks used for 'target-fqdn' MUST be followed 809 by DOTS servers to validate a target URI. 811 This is an optional attribute. 813 alias-name: A list of aliases of resources for which the mitigation 814 is requested. Aliases can be created using the DOTS data channel 815 (Section 6.1 of [RFC8783]), direct configuration, or other means. 817 An alias is used in subsequent signal channel exchanges to refer 818 more efficiently to the resources under attack. 820 This is an optional attribute. 822 lifetime: Lifetime of the mitigation request in seconds. The 823 RECOMMENDED lifetime of a mitigation request is 3600 seconds: this 824 value was chosen to be long enough so that refreshing is not 825 typically a burden on the DOTS client, while still making the 826 request expire in a timely manner when the client has unexpectedly 827 quit. DOTS clients MUST include this parameter in their 828 mitigation requests. Upon the expiry of this lifetime, and if the 829 request is not refreshed, the mitigation request is removed. The 830 request can be refreshed by sending the same request again. 832 A lifetime of '0' in a mitigation request is an invalid value. 834 A lifetime of negative one (-1) indicates indefinite lifetime for 835 the mitigation request. The DOTS server MAY refuse an indefinite 836 lifetime, for policy reasons; the granted lifetime value is 837 returned in the response. DOTS clients MUST be prepared to not be 838 granted mitigations with indefinite lifetimes. 840 The DOTS server MUST always indicate the actual lifetime in the 841 response and the remaining lifetime in status messages sent to the 842 DOTS client. 844 This is a mandatory attribute. 846 trigger-mitigation: If the parameter value is set to 'false', DDoS 847 mitigation will not be triggered for the mitigation request unless 848 the DOTS signal channel session is lost. 850 If the DOTS client ceases to respond to heartbeat messages, the 851 DOTS server can detect that the DOTS signal channel session is 852 lost. More details are discussed in Section 4.7. 854 The default value of the parameter is 'true' (that is, the 855 mitigation starts immediately). If 'trigger-mitigation' is not 856 present in a request, this is equivalent to receiving a request 857 with 'trigger-mitigation' set to 'true'. 859 This is an optional attribute. 861 In deployments where server-domain DOTS gateways are enabled, 862 identity information about the origin source client domain ('cdid') 863 SHOULD be propagated to the DOTS server. That information is meant 864 to assist the DOTS server in enforcing some policies such as grouping 865 DOTS clients that belong to the same DOTS domain, limiting the number 866 of DOTS requests, and identifying the mitigation scope. These 867 policies can be enforced per client, per client domain, or both. 868 Also, the identity information may be used for auditing and debugging 869 purposes. 871 Figure 7 shows an example of a request relayed by a server-domain 872 DOTS gateway. 874 Header: PUT (Code=0.03) 875 Uri-Path: ".well-known" 876 Uri-Path: "dots" 877 Uri-Path: "mitigate" 878 Uri-Path: "cdid=7eeaf349529eb55ed50113" 879 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 880 Uri-Path: "mid=123" 881 Content-Format: "application/dots+cbor" 883 { 884 ... 885 } 887 Figure 7: PUT for DOTS Mitigation Request as Relayed by a DOTS 888 Gateway 890 A server-domain DOTS gateway SHOULD add the following Uri-Path 891 parameter: 893 cdid: Stands for Client Domain Identifier. The 'cdid' is conveyed by 894 a server-domain DOTS gateway to propagate the source domain 895 identity from the gateway's client-facing side to the gateway's 896 server-facing side, and from the gateway's server-facing side 897 to the DOTS server. 'cdid' may be used by the final DOTS server 898 for policy enforcement purposes (e.g., enforce a quota on 899 filtering rules). These policies are deployment specific. 901 Server-domain DOTS gateways SHOULD support a configuration 902 option to instruct whether 'cdid' parameter is to be inserted. 904 In order to accommodate deployments that require enforcing per- 905 client policies, per-client domain policies, or a combination 906 thereof, server-domain DOTS gateways instructed to insert the 907 'cdid' parameter MUST supply the SPKI hash of the DOTS client 908 X.509 certificate, the DOTS client raw public key, or the hash 909 of the "PSK identity" in the 'cdid', following the same rules 910 for generating the hash conveyed in 'cuid', which is then used 911 by the ultimate DOTS server to determine the corresponding 912 client's domain. The 'cdid' generated by a server-domain 913 gateway is likely to be the same as the 'cuid' except the case 914 in which the DOTS message was relayed by a client-domain DOTS 915 gateway or the 'cuid' was generated from a rogue DOTS client. 917 If a DOTS client is provisioned, for example, with distinct 918 certificates as a function of the peer server-domain DOTS 919 gateway, distinct 'cdid' values may be supplied by a server- 920 domain DOTS gateway. The ultimate DOTS server MUST treat those 921 'cdid' values as equivalent. 923 The 'cdid' attribute MUST NOT be generated and included by DOTS 924 clients. 926 DOTS servers MUST ignore 'cdid' attributes that are directly 927 supplied by source DOTS clients or client-domain DOTS gateways. 928 This implies that first server-domain DOTS gateways MUST strip 929 'cdid' attributes supplied by DOTS clients. DOTS servers 930 SHOULD support a configuration parameter to identify DOTS 931 gateways that are trusted to supply 'cdid' attributes. 933 Only single-valued 'cdid' are defined in this document. That 934 is, only the first on-path server-domain DOTS gateway can 935 insert a 'cdid' value. This specification does not allow 936 multiple server-domain DOTS gateways, whenever involved in the 937 path, to insert a 'cdid' value for each server-domain gateway. 939 This is an optional Uri-Path. When present, 'cdid' MUST be 940 positioned before 'cuid'. 942 A DOTS gateway SHOULD add the CoAP Hop-Limit Option [RFC8768]. 944 Because of the complexity of handling partial failure cases, this 945 specification does not allow the inclusion of multiple mitigation 946 requests in the same PUT request. Concretely, a DOTS client MUST NOT 947 include multiple entries in the 'scope' array of the same PUT 948 request. 950 FQDN and URI mitigation scopes may be thought of as a form of scope 951 alias, in which the addresses associated with the domain name or URI 952 (as resolved by the DOTS server) represent the scope of the 953 mitigation. Particularly, the IP addresses to which the host 954 subcomponent of authority component of a URI resolves represent the 955 'target-prefix', the URI scheme represents the 'target-protocol', the 956 port subcomponent of authority component of a URI represents the 957 'target-port-range'. If the optional port information is not present 958 in the authority component, the default port defined for the URI 959 scheme represents the 'target-port'. 961 In the PUT request, at least one of the attributes 'target-prefix', 962 'target-fqdn','target-uri', or 'alias-name' MUST be present. 964 Attributes and Uri-Path parameters with empty values MUST NOT be 965 present in a request as an empty value will render the entire request 966 invalid. 968 Figure 8 shows a PUT request example to signal that servers 969 2001:db8:6401::1 and 2001:db8:6401::2 are receiving attack traffic on 970 TCP port numbers 80, 8080, and 443. The presence of 'cdid' indicates 971 that a server-domain DOTS gateway has modified the initial PUT 972 request sent by the DOTS client. Note that 'cdid' MUST NOT appear in 973 the PUT request message body. 975 Header: PUT (Code=0.03) 976 Uri-Path: ".well-known" 977 Uri-Path: "dots" 978 Uri-Path: "mitigate" 979 Uri-Path: "cdid=7eeaf349529eb55ed50113" 980 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 981 Uri-Path: "mid=123" 982 Content-Format: "application/dots+cbor" 984 { 985 "ietf-dots-signal-channel:mitigation-scope": { 986 "scope": [ 987 { 988 "target-prefix": [ 989 "2001:db8:6401::1/128", 990 "2001:db8:6401::2/128" 991 ], 992 "target-port-range": [ 993 { 994 "lower-port": 80 995 }, 996 { 997 "lower-port": 443 998 }, 999 { 1000 "lower-port": 8080 1001 } 1002 ], 1003 "target-protocol": [ 1004 6 1005 ], 1006 "lifetime": 3600 1007 } 1008 ] 1009 } 1010 } 1012 Figure 8: PUT for DOTS Mitigation Request (An Example) 1014 The corresponding CBOR encoding format for the payload is shown in 1015 Figure 9. 1017 A1 # map(1) 1018 01 # unsigned(1) 1019 A1 # map(1) 1020 02 # unsigned(2) 1021 81 # array(1) 1022 A4 # map(4) 1023 06 # unsigned(6) 1024 82 # array(2) 1025 74 # text(20) 1026 323030313A6462383A363430313A3A312F313238 1027 74 # text(20) 1028 323030313A6462383A363430313A3A322F313238 1029 07 # unsigned(7) 1030 83 # array(3) 1031 A1 # map(1) 1032 08 # unsigned(8) 1033 18 50 # unsigned(80) 1034 A1 # map(1) 1035 08 # unsigned(8) 1036 19 01BB # unsigned(443) 1037 A1 # map(1) 1038 08 # unsigned(8) 1039 19 1F90 # unsigned(8080) 1040 0A # unsigned(10) 1041 81 # array(1) 1042 06 # unsigned(6) 1043 0E # unsigned(14) 1044 19 0E10 # unsigned(3600) 1046 Figure 9: PUT for DOTS Mitigation Request (CBOR) 1048 In both DOTS signal and data channel sessions, the DOTS client MUST 1049 authenticate itself to the DOTS server (Section 8). The DOTS server 1050 MAY use the algorithm presented in Section 7 of [RFC7589] to derive 1051 the DOTS client identity or username from the client certificate. 1052 The DOTS client identity allows the DOTS server to accept mitigation 1053 requests with scopes that the DOTS client is authorized to manage. 1055 The DOTS server couples the DOTS signal and data channel sessions 1056 using the DOTS client identity and optionally the 'cdid' parameter 1057 value, so the DOTS server can validate whether the aliases conveyed 1058 in the mitigation request were indeed created by the same DOTS client 1059 using the DOTS data channel session. If the aliases were not created 1060 by the DOTS client, the DOTS server MUST return 4.00 (Bad Request) in 1061 the response. 1063 The DOTS server couples the DOTS signal channel sessions using the 1064 DOTS client identity and optionally the 'cdid' parameter value, and 1065 the DOTS server uses 'mid' and 'cuid' Uri-Path parameter values to 1066 detect duplicate mitigation requests. If the mitigation request 1067 contains the 'alias-name' and other parameters identifying the target 1068 resources (such as 'target-prefix', 'target-port-range', 'target- 1069 fqdn', or 'target-uri'), the DOTS server appends the parameter values 1070 in 'alias-name' with the corresponding parameter values in 'target- 1071 prefix', 'target-port-range', 'target-fqdn', or 'target-uri'. 1073 The DOTS server indicates the result of processing the PUT request 1074 using CoAP Response Codes. CoAP 2.xx codes are success. CoAP 4.xx 1075 codes are some sort of invalid requests (client errors). COAP 5.xx 1076 codes are returned if the DOTS server is in an error state or is 1077 currently unavailable to provide mitigation in response to the 1078 mitigation request from the DOTS client. 1080 Figure 10 shows an example response to a PUT request that is 1081 successfully processed by a DOTS server (i.e., CoAP 2.xx Response 1082 Codes). This version of the specification forbids 'cuid' and 'cdid' 1083 (if used) to be returned in a response message body. 1085 { 1086 "ietf-dots-signal-channel:mitigation-scope": { 1087 "scope": [ 1088 { 1089 "mid": 123, 1090 "lifetime": 3600 1091 } 1092 ] 1093 } 1094 } 1096 Figure 10: 2.xx Response Body 1098 If the request is missing a mandatory attribute, does not include 1099 'cuid' or 'mid' Uri-Path options, includes multiple 'scope' 1100 parameters, or contains invalid or unknown parameters, the DOTS 1101 server MUST reply with 4.00 (Bad Request). DOTS agents can safely 1102 ignore comprehension-optional parameters they don't understand 1103 (Section 10.6.1.1). 1105 A DOTS server that receives a mitigation request with a 'lifetime' 1106 set to '0' MUST reply with a 4.00 (Bad Request). 1108 If the DOTS server does not find the 'mid' parameter value conveyed 1109 in the PUT request in its configuration data, it MAY accept the 1110 mitigation request by sending back a 2.01 (Created) response to the 1111 DOTS client; the DOTS server will consequently try to mitigate the 1112 attack. A DOTS server could reject mitigation requests when it is 1113 near capacity or needs to rate-limit a particular client, for 1114 example. 1116 The relative order of two mitigation requests with the same 'trigger- 1117 mitigation' type from a DOTS client is determined by comparing their 1118 respective 'mid' values. If two mitigation requests with the same 1119 'trigger-mitigation' type have overlapping mitigation scopes, the 1120 mitigation request with the highest numeric 'mid' value will override 1121 the other mitigation request. Two mitigation requests from a DOTS 1122 client have overlapping scopes if there is a common IP address, IP 1123 prefix, FQDN, URI, or alias. To avoid maintaining a long list of 1124 overlapping mitigation requests (i.e., requests with the same 1125 'trigger-mitigation' type and overlapping scopes) from a DOTS client 1126 and to avoid error-prone provisioning of mitigation requests from a 1127 DOTS client, the overlapped lower numeric 'mid' MUST be automatically 1128 deleted and no longer available at the DOTS server. For example, if 1129 the DOTS server receives a mitigation request that overlaps with an 1130 existing mitigation with a higher numeric 'mid', the DOTS server 1131 rejects the request by returning 4.09 (Conflict) to the DOTS client. 1132 The response includes enough information for a DOTS client to 1133 recognize the source of the conflict as described below in the 1134 'conflict-information' subtree with only the relevant nodes listed: 1136 conflict-information: Indicates that a mitigation request is 1137 conflicting with another mitigation request. This optional 1138 attribute has the following structure: 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 conflict-scope: Characterizes the exact conflict scope. It may 1147 include a list of IP addresses, a list of prefixes, a list of 1148 port numbers, a list of target protocols, a list of FQDNs, a 1149 list of URIs, a list of aliases, or a 'mid'. 1151 If the DOTS server receives a mitigation request that overlaps with 1152 an active mitigation request, but both have distinct 'trigger- 1153 mitigation' types, the DOTS server SHOULD deactivate (absent explicit 1154 policy/configuration otherwise) the mitigation request with 'trigger- 1155 mitigation' set to 'false'. Particularly, if the mitigation request 1156 with 'trigger-mitigation' set to 'false' is active, the DOTS server 1157 withdraws the mitigation request (i.e., status code is set to '7' as 1158 defined in Table 3) and transitions the status of the mitigation 1159 request to '8'. 1161 Upon DOTS signal channel session loss with a peer DOTS client, the 1162 DOTS server SHOULD withdraw (absent explicit policy/configuration 1163 otherwise) any active mitigation requests that overlap with 1164 mitigation requests having 'trigger-mitigation' set to 'false' from 1165 that DOTS client, as the loss of the session implicitly activates 1166 these preconfigured mitigation requests, and they take precedence. 1167 Note that the active-but-terminating period is not observed for 1168 mitigations withdrawn at the initiative of the DOTS server. 1170 DOTS clients may adopt various strategies for setting the scopes of 1171 immediate and preconfigured mitigation requests to avoid potential 1172 conflicts. For example, a DOTS client may tweak preconfigured scopes 1173 so that the scope of any overlapping immediate mitigation request 1174 will be a subset of the preconfigured scopes. Also, if an immediate 1175 mitigation request overlaps with any of the preconfigured scopes, the 1176 DOTS client sets the scope of the overlapping immediate mitigation 1177 request to be a subset of the preconfigured scopes, so as to get a 1178 broad mitigation when the DOTS signal channel collapses and to 1179 maximize the chance of recovery. 1181 If the request conflicts with an existing mitigation request from a 1182 different DOTS client, the DOTS server may return 2.01 (Created) or 1183 4.09 (Conflict) to the requesting DOTS client. If the DOTS server 1184 decides to maintain the new mitigation request, the DOTS server 1185 returns 2.01 (Created) to the requesting DOTS client. If the DOTS 1186 server decides to reject the new mitigation request, the DOTS server 1187 returns 4.09 (Conflict) to the requesting DOTS client. For both 2.01 1188 (Created) and 4.09 (Conflict) responses, the response includes enough 1189 information for a DOTS client to recognize the source of the conflict 1190 as described below: 1192 conflict-information: Indicates that a mitigation request is 1193 conflicting with another mitigation request(s) from other DOTS 1194 client(s). This optional attribute has the following structure: 1196 conflict-status: Indicates the status of a conflicting mitigation 1197 request. The following values are defined: 1199 1: DOTS server has detected conflicting mitigation requests 1200 from different DOTS clients. This mitigation request is 1201 currently inactive until the conflicts are resolved. 1202 Another mitigation request is active. 1204 2: DOTS server has detected conflicting mitigation requests 1205 from different DOTS clients. This mitigation request is 1206 currently active. 1208 3: DOTS server has detected conflicting mitigation requests 1209 from different DOTS clients. All conflicting mitigation 1210 requests are inactive. 1212 conflict-cause: Indicates the cause of the conflict. The 1213 following values are defined: 1215 1: Overlapping targets. 'conflict-scope' provides more details 1216 about the conflicting target clauses. 1218 2: Conflicts with an existing accept-list. This code is 1219 returned when the DDoS mitigation detects source addresses/ 1220 prefixes in the accept-listed ACLs are attacking the 1221 target. 1223 3: CUID Collision. This code is returned when a DOTS client 1224 uses a 'cuid' that is already used by another DOTS client. 1225 This code is an indication that the request has been 1226 rejected and a new request with a new 'cuid' is to be re- 1227 sent by the DOTS client (see the example shown in 1228 Figure 11). Note that 'conflict-status', 'conflict-scope', 1229 and 'retry-timer' MUST NOT be returned in the error 1230 response. 1232 conflict-scope: Characterizes the exact conflict scope. It may 1233 include a list of IP addresses, a list of prefixes, a list of 1234 port numbers, a list of target protocols, a list of FQDNs, a 1235 list of URIs, a list of aliases, or references to conflicting 1236 ACLs (by an 'acl-name', typically [RFC8783]). 1238 retry-timer: Indicates, in seconds, the time after which the DOTS 1239 client may reissue the same request. The DOTS server returns 1240 'retry-timer' only to DOTS client(s) for which a mitigation 1241 request is deactivated. Any retransmission of the same 1242 mitigation request before the expiry of this timer is likely to 1243 be rejected by the DOTS server for the same reasons. 1245 The 'retry-timer' SHOULD be equal to the lifetime of the active 1246 mitigation request resulting in the deactivation of the 1247 conflicting mitigation request. 1249 If the DOTS server decides to maintain a state for the 1250 deactivated mitigation request, the DOTS server updates the 1251 lifetime of the deactivated mitigation request to 'retry-timer 1252 + 45 seconds' (that is, this mitigation request remains 1253 deactivated for the entire duration of 'retry-timer + 45 1254 seconds') so that the DOTS client can refresh the deactivated 1255 mitigation request after 'retry-timer' seconds, but before the 1256 expiry of the lifetime, and check if the conflict is resolved. 1258 Header: PUT (Code=0.03) 1259 Uri-Path: ".well-known" 1260 Uri-Path: "dots" 1261 Uri-Path: "mitigate" 1262 Uri-Path: "cuid=7eeaf349529eb55ed50113" 1263 Uri-Path: "mid=12" 1265 (1) Request with a conflicting 'cuid' 1267 { 1268 "ietf-dots-signal-channel:mitigation-scope": { 1269 "scope": [ 1270 { 1271 "conflict-information": { 1272 "conflict-cause": "cuid-collision" 1273 } 1274 } 1275 ] 1276 } 1277 } 1279 (2) Message body of the 4.09 (Conflict) response 1280 from the DOTS server 1282 Header: PUT (Code=0.03) 1283 Uri-Path: ".well-known" 1284 Uri-Path: "dots" 1285 Uri-Path: "mitigate" 1286 Uri-Path: "cuid=f30d281ce6b64fc5a0b91e" 1287 Uri-Path: "mid=12" 1289 (3) Request with a new 'cuid' 1291 Figure 11: Example of Generating a New 'cuid' 1293 As an active attack evolves, DOTS clients can adjust the scope of 1294 requested mitigation as necessary, by refining the scope of resources 1295 requiring mitigation. This can be achieved by sending a PUT request 1296 with a new 'mid' value that will override the existing one with 1297 overlapping mitigation scopes. 1299 For a mitigation request to continue beyond the initial negotiated 1300 lifetime, the DOTS client has to refresh the current mitigation 1301 request by sending a new PUT request. This PUT request MUST use the 1302 same 'mid' value, and it MUST repeat all the other parameters as sent 1303 in the original mitigation request apart from a possible change to 1304 the 'lifetime' parameter value. In such a case, the DOTS server MAY 1305 update the mitigation request, and a 2.04 (Changed) response is 1306 returned to indicate a successful update of the mitigation request. 1307 If this is not the case, the DOTS server MUST reject the request with 1308 a 4.00 (Bad Request). 1310 4.4.2. Retrieve Information Related to a Mitigation 1312 A GET request is used by a DOTS client to retrieve information 1313 (including status) of DOTS mitigations from a DOTS server. 1315 'cuid' is a mandatory Uri-Path parameter for GET requests. 1317 Uri-Path parameters with empty values MUST NOT be present in a 1318 request. 1320 The same considerations for manipulating the 'cdid' parameter by 1321 server-domain DOTS gateways specified in Section 4.4.1 MUST be 1322 followed for GET requests. 1324 The 'c' Uri-Query option is used to control selection of 1325 configuration and non-configuration data nodes. Concretely, the 'c' 1326 (content) parameter and its permitted values defined in Table 2 1327 [I-D.ietf-core-comi] can be used to retrieve non-configuration data 1328 (attack mitigation status), configuration data, or both. The DOTS 1329 server MAY support this optional filtering capability. It can safely 1330 ignore it if not supported. If the DOTS client supports the optional 1331 filtering capability, it SHOULD use "c=n" query (to get back only the 1332 dynamically changing data) or "c=c" query (to get back the static 1333 configuration values) when the DDoS attack is active to limit the 1334 size of the response. 1336 +-------+-----------------------------------------------------+ 1337 | Value | Description | 1338 +=======+=====================================================+ 1339 | c | Return only configuration descendant data nodes | 1340 +-------+-----------------------------------------------------+ 1341 | n | Return only non-configuration descendant data nodes | 1342 +-------+-----------------------------------------------------+ 1343 | a | Return all descendant data nodes | 1344 +-------+-----------------------------------------------------+ 1346 Table 2: Permitted Values of the 'c' Parameter 1348 The DOTS client can use block-wise transfer [RFC7959] to get the list 1349 of all its mitigations maintained by a DOTS server, it can send a 1350 Block2 Option in a GET request with NUM = 0 to aid in limiting the 1351 size of the response. If the representation of all the active 1352 mitigation requests associated with the DOTS client does not fit 1353 within a single datagram, the DOTS server MUST use the Block2 Option 1354 with NUM = 0 in the GET response. The Size2 Option may be conveyed 1355 in the response to indicate the total size of the resource 1356 representation. The DOTS client retrieves the rest of the 1357 representation by sending additional GET requests with Block2 Options 1358 containing NUM values greater than zero. The DOTS client MUST adhere 1359 to the block size preferences indicated by the DOTS server in the 1360 response. If the DOTS server uses the Block2 Option in the GET 1361 response, and the response is for a dynamically changing resource 1362 (e.g., "c=n" or "c=a" query), the DOTS server MUST include the ETag 1363 Option in the response. The DOTS client MUST include the same ETag 1364 value in subsequent GET requests to retrieve the rest of the 1365 representation. 1367 The following examples illustrate how a DOTS client retrieves active 1368 mitigation requests from a DOTS server. In particular: 1370 o Figure 12 shows the example of a GET request to retrieve all DOTS 1371 mitigation requests signaled by a DOTS client. 1373 o Figure 13 shows the example of a GET request to retrieve a 1374 specific DOTS mitigation request signaled by a DOTS client. The 1375 configuration data to be reported in the response is formatted in 1376 the same order as it was processed by the DOTS server in the 1377 original mitigation request. 1379 These two examples assume the default of "c=a"; that is, the DOTS 1380 client asks for all data to be reported by the DOTS server. 1382 Header: GET (Code=0.01) 1383 Uri-Path: ".well-known" 1384 Uri-Path: "dots" 1385 Uri-Path: "mitigate" 1386 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1387 Observe: 0 1389 Figure 12: GET to Retrieve All DOTS Mitigation Requests 1391 Header: GET (Code=0.01) 1392 Uri-Path: ".well-known" 1393 Uri-Path: "dots" 1394 Uri-Path: "mitigate" 1395 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1396 Uri-Path: "mid=12332" 1397 Observe: 0 1399 Figure 13: GET to Retrieve a Specific DOTS Mitigation Request 1401 If the DOTS server does not find the 'mid' Uri-Path value conveyed in 1402 the GET request in its configuration data for the requesting DOTS 1403 client, it MUST respond with a 4.04 (Not Found) error Response Code. 1404 Likewise, the same error MUST be returned as a response to a request 1405 to retrieve all mitigation records (i.e., 'mid' Uri-Path is not 1406 defined) of a given DOTS client if the DOTS server does not find any 1407 mitigation record for that DOTS client. As a reminder, a DOTS client 1408 is identified by its identity (e.g., client certificate, 'cuid') and 1409 optionally the 'cdid'. 1411 Figure 14 shows a response example of all active mitigation requests 1412 associated with the DOTS client as maintained by the DOTS server. 1413 The response indicates the mitigation status of each mitigation 1414 request. 1416 { 1417 "ietf-dots-signal-channel:mitigation-scope": { 1418 "scope": [ 1419 { 1420 "mid": 12332, 1421 "mitigation-start": "1507818434", 1422 "target-prefix": [ 1423 "2001:db8:6401::1/128", 1424 "2001:db8:6401::2/128" 1425 ], 1426 "target-protocol": [ 1427 17 1428 ], 1429 "lifetime": 1756, 1430 "status": "attack-successfully-mitigated", 1431 "bytes-dropped": "134334555", 1432 "bps-dropped": "43344", 1433 "pkts-dropped": "333334444", 1434 "pps-dropped": "432432" 1435 }, 1436 { 1437 "mid": 12333, 1438 "mitigation-start": "1507818393", 1439 "target-prefix": [ 1440 "2001:db8:6401::1/128", 1441 "2001:db8:6401::2/128" 1442 ], 1443 "target-protocol": [ 1444 6 1445 ], 1446 "lifetime": 1755, 1447 "status": "attack-stopped", 1448 "bytes-dropped": "0", 1449 "bps-dropped": "0", 1450 "pkts-dropped": "0", 1451 "pps-dropped": "0" 1452 } 1453 ] 1454 } 1455 } 1457 Figure 14: Response Body to a GET Request 1459 The mitigation status parameters are described below: 1461 mitigation-start: Mitigation start time is expressed in seconds 1462 relative to 1970-01-01T00:00Z in UTC time (Section 2.4.1 of 1464 [RFC7049]). The CBOR encoding is modified so that the leading tag 1465 1 (epoch-based date/time) MUST be omitted. 1467 This is a mandatory attribute when an attack mitigation is active. 1468 Particularly, 'mitigation-start' is not returned for a mitigation 1469 with 'status' code set to 8. 1471 lifetime: The remaining lifetime of the mitigation request, in 1472 seconds. 1474 This is a mandatory attribute. 1476 status: Status of attack mitigation. The various possible values of 1477 'status' parameter are explained in Table 3. 1479 This is a mandatory attribute. 1481 bytes-dropped: The total dropped byte count for the mitigation 1482 request since the attack mitigation was triggered. The count 1483 wraps around when it reaches the maximum value of unsigned 1484 integer64. 1486 This is an optional attribute. 1488 bps-dropped: The average number of dropped bytes per second for the 1489 mitigation request since the attack mitigation was triggered. 1490 This average SHOULD be over five-minute intervals (that is, 1491 measuring bytes into five-minute buckets and then averaging these 1492 buckets over the time since the mitigation was triggered). 1494 This is an optional attribute. 1496 pkts-dropped: The total number of dropped packet count for the 1497 mitigation request since the attack mitigation was triggered. The 1498 count wraps around when it reaches the maximum value of unsigned 1499 integer64. 1501 This is an optional attribute. 1503 pps-dropped: The average number of dropped packets per second for 1504 the mitigation request since the attack mitigation was triggered. 1505 This average SHOULD be over five-minute intervals (that is, 1506 measuring packets into five-minute buckets and then averaging 1507 these buckets over the time since the mitigation was triggered). 1509 This is an optional attribute. 1511 +-----------+----------------------------------------------------+ 1512 | Parameter | Description | 1513 | Value | | 1514 +===========+====================================================+ 1515 | 1 | Attack mitigation setup is in progress (e.g., | 1516 | | changing the network path to redirect the inbound | 1517 | | traffic to a DOTS mitigator). | 1518 +-----------+----------------------------------------------------+ 1519 | 2 | Attack is being successfully mitigated (e.g., | 1520 | | traffic is redirected to a DDoS mitigator and | 1521 | | attack traffic is dropped). | 1522 +-----------+----------------------------------------------------+ 1523 | 3 | Attack has stopped and the DOTS client can | 1524 | | withdraw the mitigation request. This status code | 1525 | | will be transmitted for immediate mitigation | 1526 | | requests till the mitigation is withdrawn or the | 1527 | | lifetime expires. For mitigation requests with | 1528 | | preconfigured scopes (i.e., 'trigger-mitigation' | 1529 | | set to 'false'), this status code will be | 1530 | | transmitted four times and then transition to "8". | 1531 +-----------+----------------------------------------------------+ 1532 | 4 | Attack has exceeded the mitigation provider | 1533 | | capability. | 1534 +-----------+----------------------------------------------------+ 1535 | 5 | DOTS client has withdrawn the mitigation request | 1536 | | and the mitigation is active but terminating. | 1537 +-----------+----------------------------------------------------+ 1538 | 6 | Attack mitigation is now terminated. | 1539 +-----------+----------------------------------------------------+ 1540 | 7 | Attack mitigation is withdrawn (by the DOTS | 1541 | | server). If a mitigation request with 'trigger- | 1542 | | mitigation' set to 'false' is withdrawn because it | 1543 | | overlaps with an immediate mitigation request, | 1544 | | this status code will be transmitted four times | 1545 | | and then transition to "8" for the mitigation | 1546 | | request with preconfigured scopes. | 1547 +-----------+----------------------------------------------------+ 1548 | 8 | Attack mitigation will be triggered for the | 1549 | | mitigation request only when the DOTS signal | 1550 | | channel session is lost. | 1551 +-----------+----------------------------------------------------+ 1553 Table 3: Values of 'status' Parameter 1555 4.4.2.1. DOTS Servers Sending Mitigation Status 1557 The Observe Option defined in [RFC7641] extends the CoAP core 1558 protocol with a mechanism for a CoAP client to "observe" a resource 1559 on a CoAP server: the client retrieves a representation of the 1560 resource and requests this representation be updated by the server as 1561 long as the client is interested in the resource. DOTS 1562 implementations MUST use the Observe Option for both 'mitigate' and 1563 'config' (Section 4.2). 1565 A DOTS client conveys the Observe Option set to '0' in the GET 1566 request to receive asynchronous notifications of attack mitigation 1567 status from the DOTS server. 1569 Unidirectional mitigation notifications within the bidirectional 1570 signal channel enables asynchronous notifications between the agents. 1571 [RFC7641] indicates that (1) a notification can be sent in a 1572 Confirmable or a Non-confirmable message, and (2) the message type 1573 used is typically application dependent and may be determined by the 1574 server for each notification individually. For the DOTS server 1575 application, the message type MUST always be set to Non-confirmable 1576 even if the underlying COAP library elects a notification to be sent 1577 in a Confirmable message. This overrides the behavior defined in 1578 Section 4.5 of [RFC7641] to send a Confirmable message instead of a 1579 Non-confirmable message at least every 24 hours for the following 1580 reasons: First, the DOTS signal channel uses a heartbeat mechanism to 1581 determine if the DOTS client is alive. Second, Confirmable messages 1582 are not suitable during an attack. 1584 Due to the higher likelihood of packet loss during a DDoS attack, the 1585 DOTS server periodically sends attack mitigation status to the DOTS 1586 client and also notifies the DOTS client whenever the status of the 1587 attack mitigation changes. If the DOTS server cannot maintain an RTT 1588 estimate, it MUST NOT send more than one asynchronous notification 1589 every 3 seconds, and SHOULD use an even less aggressive rate whenever 1590 possible (case 2 in Section 3.1.3 of [RFC8085]). 1592 When conflicting requests are detected, the DOTS server enforces the 1593 corresponding policy (e.g., accept all requests, reject all requests, 1594 accept only one request but reject all the others). It is assumed 1595 that this policy is supplied by the DOTS server administrator or that 1596 it is a default behavior of the DOTS server implementation. Then, 1597 the DOTS server sends a notification message(s) to the DOTS client(s) 1598 at the origin of the conflict (refer to the conflict parameters 1599 defined in Section 4.4.1). A conflict notification message includes 1600 information about the conflict cause, scope, and the status of the 1601 mitigation request(s). For example: 1603 o A notification message with 'status' code set to '7 (Attack 1604 mitigation is withdrawn)' and 'conflict-status' set to '1' is sent 1605 to a DOTS client to indicate that an active mitigation request is 1606 deactivated because a conflict is detected. 1608 o A notification message with 'status' code set to '1 (Attack 1609 mitigation is in progress)' and 'conflict-status' set to '2' is 1610 sent to a DOTS client to indicate that this mitigation request is 1611 in progress, but a conflict is detected. 1613 Upon receipt of a conflict notification message indicating that a 1614 mitigation request is deactivated because of a conflict, a DOTS 1615 client MUST NOT resend the same mitigation request before the expiry 1616 of 'retry-timer'. It is also recommended that DOTS clients support 1617 the means to alert administrators about mitigation conflicts. 1619 A DOTS client that is no longer interested in receiving notifications 1620 from the DOTS server can simply "forget" the observation. When the 1621 DOTS server sends the next notification, the DOTS client will not 1622 recognize the token in the message and, thus, will return a Reset 1623 message. This causes the DOTS server to remove the associated entry. 1624 Alternatively, the DOTS client can explicitly de-register itself by 1625 issuing a GET request that has the Token field set to the token of 1626 the observation to be canceled and includes an Observe Option with 1627 the value set to '1' (de-register). The latter is more deterministic 1628 and, thus, is RECOMMENDED. 1630 Figure 15 shows an example of a DOTS client requesting a DOTS server 1631 to send notifications related to a mitigation request. Note that for 1632 mitigations with preconfigured scopes (i.e., 'trigger-mitigation' set 1633 to 'false'), the state will need to transition from 3 (attack- 1634 stopped) to 8 (attack-mitigation-signal-loss). 1636 +-----------+ +-----------+ 1637 |DOTS Client| |DOTS Server| 1638 +-----------+ +-----------+ 1639 | | 1640 | GET / | 1641 | Token: 0x4a | Registration 1642 | Observe: 0 | 1643 +----------------------------------------->| 1644 | | 1645 | 2.05 Content | 1646 | Token: 0x4a | Notification of 1647 | Observe: 12 | the current state 1648 | status: "attack-mitigation-in-progress" | 1649 |<-----------------------------------------+ 1650 | | 1651 | 2.05 Content | 1652 | Token: 0x4a | Notification upon 1653 | Observe: 44 | a state change 1654 | status: "attack-successfully-mitigated" | 1655 |<-----------------------------------------+ 1656 | | 1657 | 2.05 Content | 1658 | Token: 0x4a | Notification upon 1659 | Observe: 60 | a state change 1660 | status: "attack-stopped" | 1661 |<-----------------------------------------+ 1662 | | 1663 ... 1665 Figure 15: Notifications of Attack Mitigation Status 1667 4.4.2.2. DOTS Clients Polling for Mitigation Status 1669 The DOTS client can send the GET request at frequent intervals 1670 without the Observe Option to retrieve the configuration data of the 1671 mitigation request and non-configuration data (i.e., the attack 1672 status). DOTS clients MAY be configured with a policy indicating the 1673 frequency of polling DOTS servers to get the mitigation status. This 1674 frequency MUST NOT be more than one UDP datagram per RTT as discussed 1675 in Section 3.1.3 of [RFC8085]. 1677 If the DOTS server has been able to mitigate the attack and the 1678 attack has stopped, the DOTS server indicates as such in the status. 1679 In such case, the DOTS client recalls the mitigation request by 1680 issuing a DELETE request for this mitigation request (Section 4.4.4). 1682 A DOTS client SHOULD react to the status of the attack per the 1683 information sent by the DOTS server rather than performing its own 1684 detection that the attack has been mitigated. This ensures that the 1685 DOTS client does not recall a mitigation request prematurely because 1686 it is possible that the DOTS client does not sense the DDoS attack on 1687 its resources, but the DOTS server could be actively mitigating the 1688 attack because the attack is not completely averted. 1690 4.4.3. Efficacy Update from DOTS Clients 1692 While DDoS mitigation is in progress, due to the likelihood of packet 1693 loss, a DOTS client MAY periodically transmit DOTS mitigation 1694 efficacy updates to the relevant DOTS server. A PUT request is used 1695 to convey the mitigation efficacy update to the DOTS server. This 1696 PUT request is treated as a refresh of the current mitigation. 1698 The PUT request used for the efficacy update MUST include all the 1699 parameters used in the PUT request to carry the DOTS mitigation 1700 request (Section 4.4.1) unchanged apart from the 'lifetime' parameter 1701 value. If this is not the case, the DOTS server MUST reject the 1702 request with a 4.00 (Bad Request). 1704 The If-Match Option (Section 5.10.8.1 of [RFC7252]) with an empty 1705 value is used to make the PUT request conditional on the current 1706 existence of the mitigation request. If UDP is used as transport, 1707 CoAP requests may arrive out of order. For example, the DOTS client 1708 may send a PUT request to convey an efficacy update to the DOTS 1709 server followed by a DELETE request to withdraw the mitigation 1710 request, but the DELETE request arrives at the DOTS server before the 1711 PUT request. To handle out-of-order delivery of requests, if an If- 1712 Match Option is present in the PUT request and the 'mid' in the 1713 request matches a mitigation request from that DOTS client, the 1714 request is processed by the DOTS server. If no match is found, the 1715 PUT request is silently ignored by the DOTS server. 1717 An example of an efficacy update message, which includes an If-Match 1718 Option with an empty value, is depicted in Figure 16. 1720 Header: PUT (Code=0.03) 1721 Uri-Path: ".well-known" 1722 Uri-Path: "dots" 1723 Uri-Path: "mitigate" 1724 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1725 Uri-Path: "mid=123" 1726 If-Match: 1727 Content-Format: "application/dots+cbor" 1729 { 1730 "ietf-dots-signal-channel:mitigation-scope": { 1731 "scope": [ 1732 { 1733 "target-prefix": [ 1734 "2001:db8:6401::1/128", 1735 "2001:db8:6401::2/128" 1736 ], 1737 "target-port-range": [ 1738 { 1739 "lower-port": 80 1740 }, 1741 { 1742 "lower-port": 443 1743 }, 1744 { 1745 "lower-port": 8080 1746 } 1747 ], 1748 "target-protocol": [ 1749 6 1750 ], 1751 "attack-status": "under-attack" 1752 } 1753 ] 1754 } 1755 } 1757 Figure 16: An Example of Efficacy Update 1759 The 'attack-status' parameter is a mandatory attribute when 1760 performing an efficacy update. The various possible values contained 1761 in the 'attack-status' parameter are described in Table 4. 1763 +-----------+-------------------------------------+ 1764 | Parameter | Description | 1765 | Value | | 1766 +===========+=====================================+ 1767 | 1 | The DOTS client determines that it | 1768 | | is still under attack. | 1769 +-----------+-------------------------------------+ 1770 | 2 | The DOTS client determines that the | 1771 | | attack is successfully mitigated | 1772 | | (e.g., attack traffic is not seen). | 1773 +-----------+-------------------------------------+ 1775 Table 4: Values of 'attack-status' Parameter 1777 The DOTS server indicates the result of processing a PUT request 1778 using CoAP Response Codes. The Response Code 2.04 (Changed) is 1779 returned if the DOTS server has accepted the mitigation efficacy 1780 update. The error Response Code 5.03 (Service Unavailable) is 1781 returned if the DOTS server has erred or is incapable of performing 1782 the mitigation. As specified in [RFC7252], 5.03 uses Max-Age Option 1783 to indicate the number of seconds after which to retry. 1785 4.4.4. Withdraw a Mitigation 1787 DELETE requests are used to withdraw DOTS mitigation requests from 1788 DOTS servers (Figure 17). 1790 'cuid' and 'mid' are mandatory Uri-Path parameters for DELETE 1791 requests. 1793 The same considerations for manipulating 'cdid' parameter by DOTS 1794 gateways, as specified in Section 4.4.1, MUST be followed for DELETE 1795 requests. Uri-Path parameters with empty values MUST NOT be present 1796 in a request. 1798 Header: DELETE (Code=0.04) 1799 Uri-Path: ".well-known" 1800 Uri-Path: "dots" 1801 Uri-Path: "mitigate" 1802 Uri-Path: "cuid=dz6pHjaADkaFTbjr0JGBpw" 1803 Uri-Path: "mid=123" 1805 Figure 17: Withdraw a DOTS Mitigation 1807 If the DELETE request does not include 'cuid' and 'mid' parameters, 1808 the DOTS server MUST reply with a 4.00 (Bad Request). 1810 Once the request is validated, the DOTS server immediately 1811 acknowledges a DOTS client's request to withdraw the DOTS signal 1812 using 2.02 (Deleted) Response Code with no response payload. A 2.02 1813 (Deleted) Response Code is returned even if the 'mid' parameter value 1814 conveyed in the DELETE request does not exist in its configuration 1815 data before the request. 1817 If the DOTS server finds the 'mid' parameter value conveyed in the 1818 DELETE request in its configuration data for the DOTS client, then to 1819 protect against route or DNS flapping caused by a DOTS client rapidly 1820 removing a mitigation, and to dampen the effect of oscillating 1821 attacks, the DOTS server MAY allow mitigation to continue for a 1822 limited period after acknowledging a DOTS client's withdrawal of a 1823 mitigation request. During this period, the DOTS server status 1824 messages SHOULD indicate that mitigation is active but terminating 1825 (Section 4.4.2). 1827 The initial active-but-terminating period SHOULD be sufficiently long 1828 to absorb latency incurred by route propagation. The active-but- 1829 terminating period SHOULD be set by default to 120 seconds. If the 1830 client requests mitigation again before the initial active-but- 1831 terminating period elapses, the DOTS server MAY exponentially 1832 increase (the base of the exponent is 2) the active-but-terminating 1833 period up to a maximum of 300 seconds (5 minutes). 1835 Once the active-but-terminating period elapses, the DOTS server MUST 1836 treat the mitigation as terminated, as the DOTS client is no longer 1837 responsible for the mitigation. 1839 If a mitigation is triggered due to a signal channel loss, the DOTS 1840 server relies upon normal triggers to stop that mitigation 1841 (typically, receipt of a valid DELETE request, expiry of the 1842 mitigation lifetime, or scrubbing the traffic to the attack target). 1843 In particular, the DOTS server MUST NOT consider the signal channel 1844 recovery as a trigger to stop the mitigation. 1846 4.5. DOTS Signal Channel Session Configuration 1848 A DOTS client can negotiate, configure, and retrieve the DOTS signal 1849 channel session behavior with its DOTS peers. The DOTS signal 1850 channel can be used, for example, to configure the following: 1852 a. Heartbeat interval ('heartbeat-interval'): DOTS agents regularly 1853 send heartbeats to each other after mutual authentication is 1854 successfully completed in order to keep the DOTS signal channel 1855 open. Heartbeat messages are exchanged between DOTS agents every 1856 'heartbeat-interval' seconds to detect the current status of the 1857 DOTS signal channel session. 1859 b. Missing heartbeats allowed ('missing-hb-allowed'): This variable 1860 indicates the maximum number of consecutive heartbeat messages 1861 for which a DOTS agent did not receive a response before 1862 concluding that the session is disconnected or defunct. 1864 c. Acceptable probing rate ('probing-rate'): This parameter 1865 indicates the average data rate that must not be exceeded by a 1866 DOTS agent in sending to a peer DOTS agent that does not respond. 1868 d. Acceptable signal loss ratio: Maximum retransmissions, 1869 retransmission timeout value, and other message transmission 1870 parameters for Confirmable messages over the DOTS signal channel. 1872 When the DOTS signal channel is established over a reliable transport 1873 (e.g., TCP), there is no need for the reliability mechanisms provided 1874 by CoAP over UDP since the underlying TCP connection provides 1875 retransmissions and deduplication [RFC8323]. As a reminder, CoAP 1876 over reliable transports does not support Confirmable or Non- 1877 confirmable message types. As such, the transmission-related 1878 parameters ('missing-hb-allowed' and acceptable signal loss ratio) 1879 are negotiated only for DOTS over unreliable transports. 1881 The same or distinct configuration sets may be used during times when 1882 a mitigation is active ('mitigating-config') and when no mitigation 1883 is active ('idle-config'). This is particularly useful for DOTS 1884 servers that might want to reduce heartbeat frequency or cease 1885 heartbeat exchanges when an active DOTS client has not requested 1886 mitigation. If distinct configurations are used, DOTS agents MUST 1887 follow the appropriate configuration set as a function of the 1888 mitigation activity (e.g., if no mitigation request is active (also 1889 referred to as 'idle' time), values related to 'idle-config' must be 1890 followed). Additionally, DOTS agents MUST automatically switch to 1891 the other configuration upon a change in the mitigation activity 1892 (e.g., if an attack mitigation is launched after an 'idle' time, the 1893 DOTS agent switches from values related to 'idle-config' to values 1894 related to 'mitigating-config'). 1896 CoAP requests and responses are indicated for reliable delivery by 1897 marking them as Confirmable messages. DOTS signal channel session 1898 configuration requests and responses are marked as Confirmable 1899 messages. As explained in Section 2.1 of [RFC7252], a Confirmable 1900 message is retransmitted using a default timeout and exponential 1901 backoff between retransmissions, until the DOTS server sends an 1902 Acknowledgement message (ACK) with the same Message ID conveyed from 1903 the DOTS client. 1905 Message transmission parameters are defined in Section 4.8 of 1906 [RFC7252]. The DOTS server can either piggyback the response in the 1907 Acknowledgement message or, if the DOTS server cannot respond 1908 immediately to a request carried in a Confirmable message, it simply 1909 responds with an Empty Acknowledgement message so that the DOTS 1910 client can stop retransmitting the request. Empty Acknowledgement 1911 messages are explained in Section 2.2 of [RFC7252]. When the 1912 response is ready, the server sends it in a new Confirmable message, 1913 which, in turn, needs to be acknowledged by the DOTS client (see 1914 Sections 5.2.1 and 5.2.2 of [RFC7252]). Requests and responses 1915 exchanged between DOTS agents during 'idle' time, except heartbeat 1916 messages, are marked as Confirmable messages. 1918 | Implementation Note: A DOTS client that receives a response in 1919 | a Confirmable message may want to clean up the message state 1920 | right after sending the ACK. If that ACK is lost and the DOTS 1921 | server retransmits the Confirmable message, the DOTS client may 1922 | no longer have any state that would help it correlate this 1923 | response: from the DOTS client's standpoint, the retransmission 1924 | message is unexpected. The DOTS client will send a Reset 1925 | message so it does not receive any more retransmissions. This 1926 | behavior is normal and not an indication of an error (see 1927 | Section 5.3.2 of [RFC7252] for more details). 1929 4.5.1. Discover Configuration Parameters 1931 A GET request is used to obtain acceptable (e.g., minimum and maximum 1932 values) and current configuration parameters on the DOTS server for 1933 DOTS signal channel session configuration. This procedure occurs 1934 between a DOTS client and its immediate peer DOTS server. As such, 1935 this GET request MUST NOT be relayed by a DOTS gateway. 1937 Figure 18 shows how to obtain configuration parameters that the DOTS 1938 server will find acceptable. 1940 Header: GET (Code=0.01) 1941 Uri-Path: ".well-known" 1942 Uri-Path: "dots" 1943 Uri-Path: "config" 1945 Figure 18: GET to Retrieve Configuration 1947 The DOTS server in the 2.05 (Content) response conveys the current, 1948 minimum, and maximum attribute values acceptable by the DOTS server 1949 (Figure 19). 1951 { 1952 "ietf-dots-signal-channel:signal-config": { 1953 "mitigating-config": { 1954 "heartbeat-interval": { 1955 "max-value": number, 1956 "min-value": number, 1957 "current-value": number 1958 }, 1959 "missing-hb-allowed": { 1960 "max-value": number, 1961 "min-value": number, 1962 "current-value": number 1963 }, 1964 "probing-rate": { 1965 "max-value": number, 1966 "min-value": number, 1967 "current-value": number 1968 }, 1969 "max-retransmit": { 1970 "max-value": number, 1971 "min-value": number, 1972 "current-value": number 1973 }, 1974 "ack-timeout": { 1975 "max-value-decimal": "string", 1976 "min-value-decimal": "string", 1977 "current-value-decimal": "string" 1978 }, 1979 "ack-random-factor": { 1980 "max-value-decimal": "string", 1981 "min-value-decimal": "string", 1982 "current-value-decimal": "string" 1983 } 1984 }, 1985 "idle-config": { 1986 "heartbeat-interval": { 1987 "max-value": number, 1988 "min-value": number, 1989 "current-value": number 1990 }, 1991 "missing-hb-allowed": { 1992 "max-value": number, 1993 "min-value": number, 1994 "current-value": number 1995 }, 1996 "probing-rate": { 1997 "max-value": number, 1998 "min-value": number, 1999 "current-value": number 2000 }, 2001 "max-retransmit": { 2002 "max-value": number, 2003 "min-value": number, 2004 "current-value": number 2005 }, 2006 "ack-timeout": { 2007 "max-value-decimal": "string", 2008 "min-value-decimal": "string", 2009 "current-value-decimal": "string" 2010 }, 2011 "ack-random-factor": { 2012 "max-value-decimal": "string", 2013 "min-value-decimal": "string", 2014 "current-value-decimal": "string" 2015 } 2016 } 2017 } 2018 } 2020 Figure 19: GET Configuration Response Body Schema 2022 The parameters in Figure 19 are described below: 2024 mitigating-config: Set of configuration parameters to use when a 2025 mitigation is active. The following parameters may be included: 2027 heartbeat-interval: Time interval in seconds between two 2028 consecutive heartbeat messages. 2030 '0' is used to disable the heartbeat mechanism. 2032 This is an optional attribute. 2034 missing-hb-allowed: Maximum number of consecutive heartbeat 2035 messages for which the DOTS agent did not receive a response 2036 before concluding that the session is disconnected. 2038 This is an optional attribute. 2040 probing-rate: The average data rate that must not be exceeded by 2041 a DOTS agent in sending to a peer DOTS agent that does not 2042 respond (referred to as PROBING_RATE parameter in CoAP). 2044 This is an optional attribute. 2046 max-retransmit: Maximum number of retransmissions for a message 2047 (referred to as MAX_RETRANSMIT parameter in CoAP). 2049 This is an optional attribute. 2051 ack-timeout: Timeout value in seconds used to calculate the 2052 initial retransmission timeout value (referred to as 2053 ACK_TIMEOUT parameter in CoAP). 2055 This is an optional attribute. 2057 ack-random-factor: Random factor used to influence the timing of 2058 retransmissions (referred to as ACK_RANDOM_FACTOR parameter in 2059 CoAP). 2061 This is an optional attribute. 2063 idle-config: Set of configuration parameters to use when no 2064 mitigation is active. This attribute has the same structure as 2065 'mitigating-config'. 2067 Figure 20 shows an example of acceptable and current configuration 2068 parameters on a DOTS server for DOTS signal channel session 2069 configuration. The same acceptable configuration is used during 2070 mitigation and idle times. 2072 { 2073 "ietf-dots-signal-channel:signal-config": { 2074 "mitigating-config": { 2075 "heartbeat-interval": { 2076 "max-value": 240, 2077 "min-value": 15, 2078 "current-value": 30 2079 }, 2080 "missing-hb-allowed": { 2081 "max-value": 20, 2082 "min-value": 3, 2083 "current-value": 15 2084 }, 2085 "probing-rate": { 2086 "max-value": 20, 2087 "min-value": 5, 2088 "current-value": 15 2089 }, 2090 "max-retransmit": { 2091 "max-value": 15, 2092 "min-value": 2, 2093 "current-value": 3 2094 }, 2095 "ack-timeout": { 2096 "max-value-decimal": "30.00", 2097 "min-value-decimal": "1.00", 2098 "current-value-decimal": "2.00" 2100 }, 2101 "ack-random-factor": { 2102 "max-value-decimal": "4.00", 2103 "min-value-decimal": "1.10", 2104 "current-value-decimal": "1.50" 2105 } 2106 }, 2107 "idle-config": { 2108 "heartbeat-interval": { 2109 "max-value": 240, 2110 "min-value": 15, 2111 "current-value": 30 2112 }, 2113 "missing-hb-allowed": { 2114 "max-value": 20, 2115 "min-value": 3, 2116 "current-value": 15 2117 }, 2118 "probing-rate": { 2119 "max-value": 20, 2120 "min-value": 5, 2121 "current-value": 15 2122 }, 2123 "max-retransmit": { 2124 "max-value": 15, 2125 "min-value": 2, 2126 "current-value": 3 2127 }, 2128 "ack-timeout": { 2129 "max-value-decimal": "30.00", 2130 "min-value-decimal": "1.00", 2131 "current-value-decimal": "2.00" 2132 }, 2133 "ack-random-factor": { 2134 "max-value-decimal": "4.00", 2135 "min-value-decimal": "1.10", 2136 "current-value-decimal": "1.50" 2137 } 2138 } 2139 } 2140 } 2142 Figure 20: Example of a Configuration Response Body 2144 4.5.2. Convey DOTS Signal Channel Session Configuration 2146 A PUT request (Figures 21 and 22) is used to convey the configuration 2147 parameters for the signal channel (e.g., heartbeat interval, maximum 2148 retransmissions). Message transmission parameters for CoAP are 2149 defined in Section 4.8 of [RFC7252]. The RECOMMENDED values of 2150 transmission parameter values are 'ack-timeout' (2 seconds), 'max- 2151 retransmit' (3), and 'ack-random-factor' (1.5). In addition to those 2152 parameters, the RECOMMENDED specific DOTS transmission parameter 2153 values are 'heartbeat-interval' (30 seconds) and 'missing-hb-allowed' 2154 (15). 2156 | Note: 'heartbeat-interval' should be tweaked to also assist 2157 | DOTS messages for NAT traversal (SIG-011 of [RFC8612]). 2158 | According to [RFC8085], heartbeat messages must not be sent 2159 | more frequently than once every 15 seconds and should use 2160 | longer intervals when possible. Furthermore, [RFC4787] 2161 | recommends that NATs use a state timeout of 2 minutes or 2162 | longer, but experience shows that sending packets every 15 to 2163 | 30 seconds is necessary to prevent the majority of middleboxes 2164 | from losing state for UDP flows. From that standpoint, the 2165 | RECOMMENDED minimum 'heartbeat-interval' is 15 seconds and the 2166 | RECOMMENDED maximum 'heartbeat-interval' is 240 seconds. The 2167 | recommended value of 30 seconds is selected to anticipate the 2168 | expiry of NAT state. 2169 | 2170 | A 'heartbeat-interval' of 30 seconds may be considered to be 2171 | too chatty in some deployments. For such deployments, DOTS 2172 | agents may negotiate longer 'heartbeat-interval' values to 2173 | prevent any network overload with too frequent heartbeats. 2174 | 2175 | Different heartbeat intervals can be defined for 'mitigating- 2176 | config' and 'idle-config' to reduce being too chatty during 2177 | idle times. If there is an on-path translator between the DOTS 2178 | client (standalone or part of a DOTS gateway) and the DOTS 2179 | server, the 'mitigating-config' 'heartbeat-interval' has to be 2180 | smaller than the translator session timeout. It is recommended 2181 | that the 'idle-config' 'heartbeat-interval' also be smaller 2182 | than the translator session timeout to prevent translator 2183 | traversal issues or that it be disabled entirely. Means to 2184 | discover the lifetime assigned by a translator are out of 2185 | scope. 2186 | 2187 | Given that the size of the heartbeat request cannot exceed 2188 | ('heartbeat-interval' * 'probing-rate') bytes, 'probing-rate' 2189 | should be set appropriately to avoid slowing down heartbeat 2190 | exchanges. For example, 'probing-rate' may be set to 2 * 2191 | ("size of encrypted DOTS heartbeat request"/'heartbeat- 2192 | interval') or (("size of encrypted DOTS heartbeat request" + 2193 | "average size of an encrypted mitigation request")/'heartbeat- 2194 | interval'). Absent any explicit configuration or inability to 2195 | dynamically adjust 'probing-rate' values (Section 4.8.1 of 2196 | [RFC7252]), DOTS agents use 5 bytes/second as a default 2197 | 'probing-rate' value. 2199 If the DOTS agent wishes to change the default values of message 2200 transmission parameters, it SHOULD follow the guidance given in 2201 Section 4.8.1 of [RFC7252]. The DOTS agents MUST use the negotiated 2202 values for message transmission parameters and default values for 2203 non-negotiated message transmission parameters. 2205 The signal channel session configuration is applicable to a single 2206 DOTS signal channel session between DOTS agents, so the 'cuid' Uri- 2207 Path MUST NOT be used. 2209 Header: PUT (Code=0.03) 2210 Uri-Path: ".well-known" 2211 Uri-Path: "dots" 2212 Uri-Path: "config" 2213 Uri-Path: "sid=123" 2214 Content-Format: "application/dots+cbor" 2216 { 2217 ... 2218 } 2220 Figure 21: PUT to Convey the DOTS Signal Channel Session 2221 Configuration Data 2223 The additional Uri-Path parameter to those defined in Table 1 is as 2224 follows: 2226 sid: Session Identifier is an identifier for the DOTS signal channel 2227 session configuration data represented as an integer. This 2228 identifier MUST be generated by DOTS clients. 'sid' values MUST 2229 increase monotonically (when a new PUT is generated by a DOTS 2230 client to convey the configuration parameters for the signal 2231 channel). 2233 This is a mandatory attribute. 2235 { 2236 "ietf-dots-signal-channel:signal-config": { 2237 "mitigating-config": { 2238 "heartbeat-interval": { 2239 "current-value": number 2240 }, 2241 "missing-hb-allowed": { 2242 "current-value": number 2243 }, 2244 "probing-rate": { 2245 "current-value": number 2246 }, 2247 "max-retransmit": { 2248 "current-value": number 2249 }, 2250 "ack-timeout": { 2251 "current-value-decimal": "string" 2252 }, 2253 "ack-random-factor": { 2254 "current-value-decimal": "string" 2255 } 2256 }, 2257 "idle-config": { 2258 "heartbeat-interval": { 2259 "current-value": number 2260 }, 2261 "missing-hb-allowed": { 2262 "current-value": number 2263 }, 2264 "probing-rate": { 2265 "current-value": number 2266 }, 2267 "max-retransmit": { 2268 "current-value": number 2269 }, 2270 "ack-timeout": { 2271 "current-value-decimal": "string" 2272 }, 2273 "ack-random-factor": { 2274 "current-value-decimal": "string" 2275 } 2276 } 2277 } 2278 } 2280 Figure 22: PUT to Convey the DOTS Signal Channel Session 2281 Configuration Data (Message Body Schema) 2283 The meaning of the parameters in the CBOR body (Figure 22) is defined 2284 in Section 4.5.1. 2286 At least one of the attributes 'heartbeat-interval', 'missing-hb- 2287 allowed', 'probing-rate', 'max-retransmit', 'ack-timeout', and 'ack- 2288 random-factor' MUST be present in the PUT request. Note that 2289 'heartbeat-interval', 'missing-hb-allowed', 'probing-rate', 'max- 2290 retransmit', 'ack-timeout', and 'ack-random-factor', if present, do 2291 not need to be provided for both 'mitigating-config', and 'idle- 2292 config' in a PUT request. 2294 The PUT request with a higher numeric 'sid' value overrides the DOTS 2295 signal channel session configuration data installed by a PUT request 2296 with a lower numeric 'sid' value. To avoid maintaining a long list 2297 of 'sid' requests from a DOTS client, the lower numeric 'sid' MUST be 2298 automatically deleted and no longer available at the DOTS server. 2300 Figure 23 shows a PUT request example to convey the configuration 2301 parameters for the DOTS signal channel. In this example, the 2302 heartbeat mechanism is disabled when no mitigation is active, while 2303 the heartbeat interval is set to '30' when a mitigation is active. 2305 Header: PUT (Code=0.03) 2306 Uri-Path: ".well-known" 2307 Uri-Path: "dots" 2308 Uri-Path: "config" 2309 Uri-Path: "sid=123" 2310 Content-Format: "application/dots+cbor" 2312 { 2313 "ietf-dots-signal-channel:signal-config": { 2314 "mitigating-config": { 2315 "heartbeat-interval": { 2316 "current-value": 30 2317 }, 2318 "missing-hb-allowed": { 2319 "current-value": 15 2320 }, 2321 "probing-rate": { 2322 "current-value": 15 2323 }, 2324 "max-retransmit": { 2325 "current-value": 3 2326 }, 2327 "ack-timeout": { 2328 "current-value-decimal": "2.00" 2329 }, 2330 "ack-random-factor": { 2331 "current-value-decimal": "1.50" 2332 } 2333 }, 2334 "idle-config": { 2335 "heartbeat-interval": { 2336 "current-value": 0 2337 }, 2338 "max-retransmit": { 2339 "current-value": 3 2340 }, 2341 "ack-timeout": { 2342 "current-value-decimal": "2.00" 2343 }, 2344 "ack-random-factor": { 2345 "current-value-decimal": "1.50" 2346 } 2347 } 2348 } 2349 } 2351 Figure 23: PUT to Convey the Configuration Parameters 2353 The DOTS server indicates the result of processing the PUT request 2354 using CoAP Response Codes: 2356 o If the request is missing a mandatory attribute, does not include 2357 a 'sid' Uri-Path, or contains one or more invalid or unknown 2358 parameters, 4.00 (Bad Request) MUST be returned in the response. 2360 o If the DOTS server does not find the 'sid' parameter value 2361 conveyed in the PUT request in its configuration data and if the 2362 DOTS server has accepted the configuration parameters, then a 2363 Response Code 2.01 (Created) MUST be returned in the response. 2365 o If the DOTS server finds the 'sid' parameter value conveyed in the 2366 PUT request in its configuration data and if the DOTS server has 2367 accepted the updated configuration parameters, 2.04 (Changed) MUST 2368 be returned in the response. 2370 o If any of the 'heartbeat-interval', 'missing-hb-allowed', 2371 'probing-rate', 'max-retransmit', 'target-protocol', 'ack- 2372 timeout', and 'ack-random-factor' attribute values are not 2373 acceptable to the DOTS server, 4.22 (Unprocessable Entity) MUST be 2374 returned in the response. Upon receipt of this error code, the 2375 DOTS client SHOULD retrieve the maximum and minimum attribute 2376 values acceptable to the DOTS server (Section 4.5.1). 2378 The DOTS client may retry and send the PUT request with updated 2379 attribute values acceptable to the DOTS server. 2381 A DOTS client may issue a GET message with a 'sid' Uri-Path parameter 2382 to retrieve the negotiated configuration. The response does not need 2383 to include 'sid' in its message body. 2385 4.5.3. Configuration Freshness and Notifications 2387 Max-Age Option (Section 5.10.5 of [RFC7252]) SHOULD be returned by a 2388 DOTS server to associate a validity time with a configuration it 2389 sends. This feature allows the update of the configuration data if a 2390 change occurs at the DOTS server side. For example, the new 2391 configuration may instruct a DOTS client to cease heartbeats or 2392 reduce heartbeat frequency. 2394 It is NOT RECOMMENDED to return a Max-Age Option set to 0. 2396 Returning a Max-Age Option set to 2^(32)-1 is equivalent to 2397 associating an infinite lifetime with the configuration. 2399 If a non-zero value of Max-Age Option is received by a DOTS client, 2400 it MUST issue a GET request with a 'sid' Uri-Path parameter to 2401 retrieve the current and acceptable configuration before the expiry 2402 of the value enclosed in the Max-Age Option. This request is 2403 considered by the client and the server to be a means to refresh the 2404 configuration parameters for the signal channel. When a DDoS attack 2405 is active, refresh requests MUST NOT be sent by DOTS clients, and the 2406 DOTS server MUST NOT terminate the (D)TLS session after the expiry of 2407 the value returned in Max-Age Option. 2409 If Max-Age Option is not returned in a response, the DOTS client 2410 initiates GET requests to refresh the configuration parameters each 2411 60 seconds (Section 5.10.5 of [RFC7252]). To prevent such overload, 2412 it is RECOMMENDED that DOTS servers return a Max-Age Option in GET 2413 responses. Considerations related to which value to use and how such 2414 a value is set are implementation and deployment specific. 2416 If an Observe Option set to 0 is included in the configuration 2417 request, the DOTS server sends notifications of any configuration 2418 change (Section 4.2 of [RFC7641]). 2420 If a DOTS server detects that a misbehaving DOTS client does not 2421 contact the DOTS server after the expiry of Max-Age to retrieve the 2422 signal channel configuration data, it MAY terminate the (D)TLS 2423 session. A (D)TLS session is terminated by the receipt of an 2424 authenticated message that closes the connection (e.g., a fatal alert 2425 (Section 6 of [RFC8446])). 2427 4.5.4. Delete DOTS Signal Channel Session Configuration 2429 A DELETE request is used to delete the installed DOTS signal channel 2430 session configuration data (Figure 24). 2432 Header: DELETE (Code=0.04) 2433 Uri-Path: ".well-known" 2434 Uri-Path: "dots" 2435 Uri-Path: "config" 2436 Uri-Path: "sid=123" 2438 Figure 24: Delete Configuration 2440 The DOTS server resets the DOTS signal channel session configuration 2441 back to the default values and acknowledges a DOTS client's request 2442 to remove the DOTS signal channel session configuration using 2.02 2443 (Deleted) Response Code. 2445 Upon bootstrapping or reboot, a DOTS client MAY send a DELETE request 2446 to set the configuration parameters to default values. Such a 2447 request does not include any 'sid'. 2449 4.6. Redirected Signaling 2451 Redirected DOTS signaling is discussed in detail in Section 3.2.2 of 2452 [RFC8811]. 2454 If a DOTS server wants to redirect a DOTS client to an alternative 2455 DOTS server for a signal session, then the Response Code 5.03 2456 (Service Unavailable) will be returned in the response to the DOTS 2457 client. 2459 The DOTS server can return the error Response Code 5.03 in response 2460 to a request from the DOTS client or convey the error Response Code 2461 5.03 in a unidirectional notification response from the DOTS server. 2463 The DOTS server in the error response conveys the alternate DOTS 2464 server's FQDN, and the alternate DOTS server's IP address(es) values 2465 in the CBOR body (Figure 25). 2467 { 2468 "ietf-dots-signal-channel:redirected-signal": { 2469 "alt-server": "string", 2470 "alt-server-record": [ 2471 "string" 2472 ] 2473 } 2474 } 2476 Figure 25: Redirected Server Error Response Body Schema 2478 The parameters are described below: 2480 alt-server: FQDN of an alternate DOTS server. 2482 This is a mandatory attribute. 2484 alt-server-record: A list of IP addresses of an alternate DOTS 2485 server. 2487 This is an optional attribute. 2489 The DOTS server returns the Time to Live (TTL) of the alternate DOTS 2490 server in a Max-Age Option. That is, the time interval that the 2491 alternate DOTS server may be cached for use by a DOTS client. A Max- 2492 Age Option set to 2^(32)-1 is equivalent to receiving an infinite 2493 TTL. This value means that the alternate DOTS server is to be used 2494 until the alternate DOTS server redirects the traffic with another 2495 5.03 response that conveys an alternate server's FQDN. 2497 A Max-Age Option set to '0' may be returned for redirecting 2498 mitigation requests. Such a value means that the redirection applies 2499 only for the mitigation request in progress. Returning short TTL in 2500 a Max-Age Option may adversely impact DOTS clients on slow links. 2501 Returning short values should be avoided under such conditions. 2503 If the alternate DOTS server TTL has expired, the DOTS client MUST 2504 use the DOTS server(s) that was provisioned using means discussed in 2505 Section 4.1. This fallback mechanism is triggered immediately upon 2506 expiry of the TTL, except when a DDoS attack is active. 2508 Requests issued by misbehaving DOTS clients that do not honor the TTL 2509 conveyed in the Max-Age Option or react to explicit redirect messages 2510 can be rejected by DOTS servers. 2512 Figure 26 shows a 5.03 response example to convey the DOTS alternate 2513 server 'alt-server.example' together with its IP addresses 2514 2001:db8:6401::1 and 2001:db8:6401::2. 2516 { 2517 "ietf-dots-signal-channel:redirected-signal": { 2518 "alt-server": "alt-server.example", 2519 "alt-server-record": [ 2520 "2001:db8:6401::1", 2521 "2001:db8:6401::2" 2522 ] 2523 } 2524 } 2526 Figure 26: Example of Redirected Server Error Response Body 2528 When the DOTS client receives a 5.03 response with an alternate 2529 server included, it considers the current request to have failed, but 2530 it SHOULD try resending the request to the alternate DOTS server. 2531 During a DDoS attack, the DNS server may be the target of another 2532 DDoS attack, the alternate DOTS server's IP addresses conveyed in the 2533 5.03 response help the DOTS client skip the DNS lookup of the 2534 alternate DOTS server, at the cost of trusting the first DOTS server 2535 to provide accurate information. The DOTS client can then try to 2536 establish a UDP or a TCP session with the alternate DOTS server. The 2537 DOTS client MAY implement a method to construct IPv4-embedded IPv6 2538 addresses [RFC6052]; this is required to handle the scenario where an 2539 IPv6-only DOTS client communicates with an IPv4-only alternate DOTS 2540 server. 2542 If the DOTS client has been redirected to a DOTS server with which it 2543 has already communicated within the last five (5) minutes, it MUST 2544 ignore the redirection and try to contact other DOTS servers listed 2545 in the local configuration or discovered using dynamic means such as 2546 DHCP or SRV procedures [I-D.ietf-dots-server-discovery]. It is 2547 RECOMMENDED that DOTS clients support the means to alert 2548 administrators about redirect loops. 2550 4.7. Heartbeat Mechanism 2552 To provide an indication of signal health and to distinguish an 2553 'idle' signal channel from a 'disconnected' or 'defunct' session, the 2554 DOTS agent sends a heartbeat over the signal channel to maintain its 2555 half of the channel (also, aligned with the "consents" recommendation 2556 in Section 6 of [RFC8085]). The DOTS agent similarly expects a 2557 heartbeat from its peer DOTS agent, and it may consider a session 2558 terminated in the prolonged absence of a peer agent heartbeat. 2559 Concretely, while the communication between the DOTS agents is 2560 otherwise quiescent, the DOTS client will probe the DOTS server to 2561 ensure it has maintained cryptographic state and vice versa. Such 2562 probes can also keep the bindings of firewalls and/or stateful 2563 translators alive. This probing reduces the frequency of 2564 establishing a new handshake when a DOTS signal needs to be conveyed 2565 to the DOTS server. 2567 | Implementation Note: Given that CoAP roles can be multiplexed 2568 | over the same session as discussed in [RFC7252] and are already 2569 | supported by CoAP implementations, both the DOTS client and 2570 | server can send DOTS heartbeat requests. 2572 The DOTS heartbeat mechanism uses Non-confirmable PUT requests 2573 (Figure 27) with an expected 2.04 (Changed) Response Code 2574 (Figure 28). This procedure occurs between a DOTS agent and its 2575 immediate peer DOTS agent. As such, this PUT request MUST NOT be 2576 relayed by a DOTS gateway. The PUT request used for DOTS heartbeat 2577 MUST NOT have a 'cuid', 'cdid', or 'mid' Uri-Path. 2579 Header: PUT (Code=0.03) 2580 Uri-Path: ".well-known" 2581 Uri-Path: "dots" 2582 Uri-Path: "hb" 2583 Content-Format: "application/dots+cbor" 2585 { 2586 "ietf-dots-signal-channel:heartbeat": { 2587 "peer-hb-status": true 2588 } 2589 } 2591 Figure 27: PUT to Check Peer DOTS Agent Is Responding 2593 The mandatory 'peer-hb-status' attribute is set to 'true' (or 2594 'false') to indicate that a DOTS agent is (or is not) receiving 2595 heartbeat messages from its peer in the last (2 * 'heartbeat- 2596 interval') period. Such information can be used by a peer DOTS agent 2597 to detect or confirm connectivity issues and react accordingly. For 2598 example, if a DOTS client receives a 2.04 response for its heartbeat 2599 messages but no server-initiated heartbeat messages, the DOTS client 2600 sets 'peer-hb-status' to 'false'. The DOTS server then will need to 2601 try another strategy for sending the heartbeats (e.g., adjust the 2602 heartbeat interval or send a server-initiated heartbeat immediately 2603 after receiving a client-initiated heartbeat message). 2605 Header: (Code=2.04) 2607 Figure 28: Response to a DOTS Heartbeat Request 2609 DOTS servers MAY trigger their heartbeat requests immediately after 2610 receiving heartbeat probes from peer DOTS clients. As a reminder, it 2611 is the responsibility of DOTS clients to ensure that on-path 2612 translators/firewalls are maintaining a binding so that the same 2613 external IP address and/or port number is retained for the DOTS 2614 signal channel session. 2616 Under normal traffic conditions (i.e., no attack is ongoing), if a 2617 DOTS agent does not receive any response from the peer DOTS agent for 2618 'missing-hb-allowed' number of consecutive heartbeat messages, it 2619 concludes that the DOTS signal channel session is disconnected. The 2620 DOTS client MUST then try to reestablish the DOTS signal channel 2621 session, preferably by resuming the (D)TLS session. 2623 | Note: If a new DOTS signal channel session cannot be 2624 | established, the DOTS client SHOULD NOT retry to establish the 2625 | DOTS signal channel session more frequently than every 300 2626 | seconds (5 minutes) and MUST NOT retry more frequently than 2627 | every 60 seconds (1 minute). It is recommended that DOTS 2628 | clients support the means to alert administrators about the 2629 | failure to establish a (D)TLS session. 2631 In case of a massive DDoS attack that saturates the incoming link(s) 2632 to the DOTS client, all traffic from the DOTS server to the DOTS 2633 client will likely be dropped, although the DOTS server receives 2634 heartbeat requests in addition to DOTS messages sent by the DOTS 2635 client. In this scenario, DOTS clients MUST behave differently to 2636 handle message transmission and DOTS signal channel session 2637 liveliness during link saturation: 2639 The DOTS client MUST NOT consider the DOTS signal channel session 2640 terminated even after a maximum 'missing-hb-allowed' threshold is 2641 reached. The DOTS client SHOULD keep on using the current DOTS 2642 signal channel session to send heartbeat requests over it, so that 2643 the DOTS server knows the DOTS client has not disconnected the 2644 DOTS signal channel session. 2646 After the maximum 'missing-hb-allowed' threshold is reached, the 2647 DOTS client SHOULD try to establish a new DOTS signal channel 2648 session. The DOTS client SHOULD send mitigation requests over the 2649 current DOTS signal channel session and, in parallel, send the 2650 mitigation requests over the new DOTS signal channel session. 2651 This may be handled, for example, by resumption of the (D)TLS 2652 session or using 0-RTT mode in DTLS 1.3 to piggyback the 2653 mitigation request in the ClientHello message. 2655 As soon as the link is no longer saturated, if traffic from the 2656 DOTS server reaches the DOTS client over the current DOTS signal 2657 channel session, the DOTS client can stop the new DOTS signal 2658 channel session attempt or if a new DOTS signal channel session is 2659 successful then disconnect the current DOTS signal channel 2660 session. 2662 If the DOTS server receives traffic from the peer DOTS client (e.g., 2663 peer DOTS client-initiated heartbeats) but the maximum 'missing-hb- 2664 allowed' threshold is reached, the DOTS server MUST NOT consider the 2665 DOTS signal channel session disconnected. The DOTS server MUST keep 2666 on using the current DOTS signal channel session so that the DOTS 2667 client can send mitigation requests over the current DOTS signal 2668 channel session. In this case, the DOTS server can identify that the 2669 DOTS client is under attack and that the inbound link to the DOTS 2670 client (domain) is saturated. Furthermore, if the DOTS server does 2671 not receive a mitigation request from the DOTS client, it implies 2672 that the DOTS client has not detected the attack or, if an attack 2673 mitigation is in progress, it implies that the applied DDoS 2674 mitigation actions are not yet effectively handling the DDoS attack 2675 volume. 2677 If the DOTS server does not receive any traffic from the peer DOTS 2678 client during the time span required to exhaust the maximum 'missing- 2679 hb-allowed' threshold, the DOTS server concludes the session is 2680 disconnected. The DOTS server can then trigger preconfigured 2681 mitigation requests for this DOTS client (if any). 2683 In DOTS over TCP, the sender of a DOTS heartbeat message has to allow 2684 up to 'heartbeat-interval' seconds when waiting for a heartbeat 2685 reply. When a failure is detected by a DOTS client, it proceeds with 2686 the session recovery, following the same approach as the one used for 2687 unreliable transports. 2689 5. DOTS Signal Channel YANG Modules 2691 This document defines a YANG module [RFC7950] for DOTS mitigation 2692 scope, DOTS signal channel session configuration data, DOTS 2693 redirection signaling, and DOTS heartbeats. 2695 This YANG module is not intended to be used via NETCONF/RESTCONF for 2696 DOTS server management purposes; such a module is out of the scope of 2697 this document. It serves only to provide abstract data structures. 2698 This document uses the "structure" extension specified in [RFC8791]. 2700 A companion YANG module is defined to include a collection of types 2701 defined by IANA: "iana-dots-signal-channel" (Section 5.2). 2703 5.1. Tree Structure 2705 This document defines the YANG module "ietf-dots-signal-channel", 2706 which has the following tree structure. A DOTS signal message can be 2707 a mitigation, a configuration, a redirect, or a heartbeat message. 2709 This tree structure obsoletes the one described in Section 5.1 of 2710 [RFC8782]. 2712 module: ietf-dots-signal-channel 2714 structure dots-signal: 2715 +-- (message-type)? 2716 +--:(mitigation-scope) 2717 | +-- scope* [] 2718 | +-- target-prefix* inet:ip-prefix 2719 | +-- target-port-range* [lower-port] 2720 | | +-- lower-port inet:port-number 2721 | | +-- upper-port? inet:port-number 2722 | +-- target-protocol* uint8 2723 | +-- target-fqdn* inet:domain-name 2724 | +-- target-uri* inet:uri 2725 | +-- alias-name* string 2726 | +-- lifetime? union 2727 | +-- trigger-mitigation? boolean 2728 | +-- (direction)? 2729 | +--:(server-to-client-only) 2730 | | +-- mid? uint32 2731 | | +-- mitigation-start? uint64 2732 | | +-- status? 2733 | | | iana-dots-signal:status 2734 | | +-- conflict-information 2735 | | | +-- conflict-status? 2736 | | | | iana-dots-signal:conflict-status 2737 | | | +-- conflict-cause? 2738 | | | | iana-dots-signal:conflict-cause 2739 | | | +-- retry-timer? uint32 2740 | | | +-- conflict-scope 2741 | | | +-- target-prefix* inet:ip-prefix 2742 | | | +-- target-port-range* [lower-port] 2743 | | | | +-- lower-port inet:port-number 2744 | | | | +-- upper-port? inet:port-number 2745 | | | +-- target-protocol* uint8 2746 | | | +-- target-fqdn* inet:domain-name 2747 | | | +-- target-uri* inet:uri 2748 | | | +-- alias-name* string 2749 | | | +-- acl-list* [acl-name] 2750 | | | | +-- acl-name leafref 2751 | | | | +-- acl-type? leafref 2752 | | | +-- mid? uint32 2753 | | +-- bytes-dropped? 2754 | | | yang:zero-based-counter64 2755 | | +-- bps-dropped? yang:gauge64 2756 | | +-- pkts-dropped? 2757 | | | yang:zero-based-counter64 2758 | | +-- pps-dropped? yang:gauge64 2759 | +--:(client-to-server-only) 2760 | +-- attack-status? 2761 | iana-dots-signal:attack-status 2762 +--:(signal-config) 2763 | +-- mitigating-config 2764 | | +-- heartbeat-interval 2765 | | | +-- (direction)? 2766 | | | | +--:(server-to-client-only) 2767 | | | | +-- max-value? uint16 2768 | | | | +-- min-value? uint16 2769 | | | +-- current-value? uint16 2770 | | +-- missing-hb-allowed 2771 | | | +-- (direction)? 2772 | | | | +--:(server-to-client-only) 2773 | | | | +-- max-value? uint16 2774 | | | | +-- min-value? uint16 2775 | | | +-- current-value? uint16 2776 | | +-- probing-rate 2777 | | | +-- (direction)? 2778 | | | | +--:(server-to-client-only) 2779 | | | | +-- max-value? uint16 2780 | | | | +-- min-value? uint16 2781 | | | +-- current-value? uint16 2782 | | +-- max-retransmit 2783 | | | +-- (direction)? 2784 | | | | +--:(server-to-client-only) 2785 | | | | +-- max-value? uint16 2786 | | | | +-- min-value? uint16 2787 | | | +-- current-value? uint16 2788 | | +-- ack-timeout 2789 | | | +-- (direction)? 2790 | | | | +--:(server-to-client-only) 2791 | | | | +-- max-value-decimal? decimal64 2792 | | | | +-- min-value-decimal? decimal64 2793 | | | +-- current-value-decimal? decimal64 2794 | | +-- ack-random-factor 2795 | | +-- (direction)? 2796 | | | +--:(server-to-client-only) 2797 | | | +-- max-value-decimal? decimal64 2798 | | | +-- min-value-decimal? decimal64 2799 | | +-- current-value-decimal? decimal64 2800 | +-- idle-config 2801 | +-- heartbeat-interval 2802 | | +-- (direction)? 2803 | | | +--:(server-to-client-only) 2804 | | | +-- max-value? uint16 2805 | | | +-- min-value? uint16 2806 | | +-- current-value? uint16 2807 | +-- missing-hb-allowed 2808 | | +-- (direction)? 2809 | | | +--:(server-to-client-only) 2810 | | | +-- max-value? uint16 2811 | | | +-- min-value? uint16 2812 | | +-- current-value? uint16 2813 | +-- probing-rate 2814 | | +-- (direction)? 2815 | | | +--:(server-to-client-only) 2816 | | | +-- max-value? uint16 2817 | | | +-- min-value? uint16 2818 | | +-- current-value? uint16 2819 | +-- max-retransmit 2820 | | +-- (direction)? 2821 | | | +--:(server-to-client-only) 2822 | | | +-- max-value? uint16 2823 | | | +-- min-value? uint16 2824 | | +-- current-value? uint16 2825 | +-- ack-timeout 2826 | | +-- (direction)? 2827 | | | +--:(server-to-client-only) 2828 | | | +-- max-value-decimal? decimal64 2829 | | | +-- min-value-decimal? decimal64 2830 | | +-- current-value-decimal? decimal64 2831 | +-- ack-random-factor 2832 | +-- (direction)? 2833 | | +--:(server-to-client-only) 2834 | | +-- max-value-decimal? decimal64 2835 | | +-- min-value-decimal? decimal64 2836 | +-- current-value-decimal? decimal64 2837 +--:(redirected-signal) 2838 | +-- (direction)? 2839 | +--:(server-to-client-only) 2840 | +-- alt-server inet:domain-name 2841 | +-- alt-server-record* inet:ip-address 2842 +--:(heartbeat) 2843 +-- peer-hb-status boolean 2845 5.2. IANA DOTS Signal Channel YANG Module 2847 This version obsoletes the version described in Section 5.2 of 2848 [RFC8782]. 2850 file "iana-dots-signal-channel@2020-09-24.yang" 2851 module iana-dots-signal-channel { 2852 yang-version 1.1; 2853 namespace "urn:ietf:params:xml:ns:yang:iana-dots-signal-channel"; 2854 prefix iana-dots-signal; 2856 organization 2857 "IANA"; 2858 contact 2859 "Internet Assigned Numbers Authority 2861 Postal: ICANN 2862 12025 Waterfront Drive, Suite 300 2863 Los Angeles, CA 90094-2536 2864 United States of America 2865 Tel: +1 310 301 5800 2866 "; 2867 description 2868 "This module contains a collection of YANG data types defined 2869 by IANA and used for DOTS signal channel protocol. 2871 Copyright (c) 2020 IETF Trust and the persons identified as 2872 authors of the code. All rights reserved. 2874 Redistribution and use in source and binary forms, with or 2875 without modification, is permitted pursuant to, and subject 2876 to the license terms contained in, the Simplified BSD License 2877 set forth in Section 4.c of the IETF Trust's Legal Provisions 2878 Relating to IETF Documents 2879 (http://trustee.ietf.org/license-info). 2881 This version of this YANG module is part of RFC 8782; see 2882 the RFC itself for full legal notices."; 2884 revision 2020-09-24 { 2885 description 2886 "Updated the prefix used for the module."; 2887 reference 2888 "RFC XXXX: Distributed Denial-of-Service Open Threat 2889 Signaling (DOTS) Signal Channel Specification"; 2890 } 2892 revision 2020-05-28 { 2893 description 2894 "Initial revision."; 2895 reference 2896 "RFC 8782: Distributed Denial-of-Service Open Threat 2897 Signaling (DOTS) Signal Channel Specification"; 2898 } 2900 typedef status { 2901 type enumeration { 2902 enum attack-mitigation-in-progress { 2903 value 1; 2904 description 2905 "Attack mitigation setup is in progress (e.g., changing 2906 the network path to reroute the inbound traffic 2907 to DOTS mitigator)."; 2908 } 2909 enum attack-successfully-mitigated { 2910 value 2; 2911 description 2912 "Attack is being successfully mitigated (e.g., traffic 2913 is redirected to a DDoS mitigator and attack 2914 traffic is dropped or blackholed)."; 2915 } 2916 enum attack-stopped { 2917 value 3; 2918 description 2919 "Attack has stopped and the DOTS client can 2920 withdraw the mitigation request."; 2921 } 2922 enum attack-exceeded-capability { 2923 value 4; 2924 description 2925 "Attack has exceeded the mitigation provider 2926 capability."; 2927 } 2928 enum dots-client-withdrawn-mitigation { 2929 value 5; 2930 description 2931 "DOTS client has withdrawn the mitigation 2932 request and the mitigation is active but 2933 terminating."; 2934 } 2935 enum attack-mitigation-terminated { 2936 value 6; 2937 description 2938 "Attack mitigation is now terminated."; 2939 } 2940 enum attack-mitigation-withdrawn { 2941 value 7; 2942 description 2943 "Attack mitigation is withdrawn."; 2944 } 2945 enum attack-mitigation-signal-loss { 2946 value 8; 2947 description 2948 "Attack mitigation will be triggered 2949 for the mitigation request only when 2950 the DOTS signal channel session is lost."; 2951 } 2952 } 2953 description 2954 "Enumeration for status reported by the DOTS server."; 2955 } 2957 typedef conflict-status { 2958 type enumeration { 2959 enum request-inactive-other-active { 2960 value 1; 2961 description 2962 "DOTS Server has detected conflicting mitigation 2963 requests from different DOTS clients. 2964 This mitigation request is currently inactive 2965 until the conflicts are resolved. Another 2966 mitigation request is active."; 2967 } 2968 enum request-active { 2969 value 2; 2970 description 2971 "DOTS Server has detected conflicting mitigation 2972 requests from different DOTS clients. 2974 This mitigation request is currently active."; 2975 } 2976 enum all-requests-inactive { 2977 value 3; 2978 description 2979 "DOTS Server has detected conflicting mitigation 2980 requests from different DOTS clients. All 2981 conflicting mitigation requests are inactive."; 2982 } 2983 } 2984 description 2985 "Enumeration for conflict status."; 2986 } 2988 typedef conflict-cause { 2989 type enumeration { 2990 enum overlapping-targets { 2991 value 1; 2992 description 2993 "Overlapping targets. conflict-scope provides 2994 more details about the exact conflict."; 2995 } 2996 enum conflict-with-acceptlist { 2997 value 2; 2998 description 2999 "Conflicts with an existing accept-list. 3001 This code is returned when the DDoS mitigation 3002 detects that some of the source addresses/prefixes 3003 listed in the accept-list ACLs are actually 3004 attacking the target."; 3005 } 3006 enum cuid-collision { 3007 value 3; 3008 description 3009 "Conflicts with the cuid used by another 3010 DOTS client."; 3011 } 3012 } 3013 description 3014 "Enumeration for conflict causes."; 3015 } 3017 typedef attack-status { 3018 type enumeration { 3019 enum under-attack { 3020 value 1; 3021 description 3022 "The DOTS client determines that it is still under 3023 attack."; 3024 } 3025 enum attack-successfully-mitigated { 3026 value 2; 3027 description 3028 "The DOTS client determines that the attack is 3029 successfully mitigated."; 3030 } 3031 } 3032 description 3033 "Enumeration for attack status codes."; 3034 } 3035 } 3036 3038 5.3. IETF DOTS Signal Channel YANG Module 3040 This module uses the common YANG types defined in [RFC6991] and types 3041 defined in [RFC8783]. 3043 This version obsoletes the version described in Section 5.3 of 3044 [RFC8782]. 3046 file "ietf-dots-signal-channel@2020-09-24.yang" 3047 module ietf-dots-signal-channel { 3048 yang-version 1.1; 3049 namespace "urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel"; 3050 prefix dots-signal; 3052 import ietf-inet-types { 3053 prefix inet; 3054 reference 3055 "Section 4 of RFC 6991"; 3056 } 3057 import ietf-yang-types { 3058 prefix yang; 3059 reference 3060 "Section 3 of RFC 6991"; 3061 } 3062 import ietf-dots-data-channel { 3063 prefix data-channel; 3064 reference 3065 "RFC 8783: Distributed Denial-of-Service Open Threat Signaling 3066 (DOTS) Data Channel Specification"; 3067 } 3068 import iana-dots-signal-channel { 3069 prefix iana-dots-signal; 3070 reference 3071 "RFC XXXX: Distributed Denial-of-Service Open Threat Signaling 3072 (DOTS) Signal Channel Specification"; 3073 } 3074 import ietf-yang-structure-ext { 3075 prefix sx; 3076 reference 3077 "RFC 8791: YANG Data Structure Extensions"; 3078 } 3080 organization 3081 "IETF DDoS Open Threat Signaling (DOTS) Working Group"; 3082 contact 3083 "WG Web: 3084 WG List: 3086 Editor: Mohamed Boucadair 3087 3089 Editor: Jon Shallow 3090 3092 Author: Konda, Tirumaleswar Reddy.K 3093 3095 Author: Prashanth Patil 3096 3098 Author: Andrew Mortensen 3099 3101 Author: Nik Teague 3102 "; 3103 description 3104 "This module contains YANG definition for the signaling 3105 messages exchanged between a DOTS client and a DOTS server. 3107 Copyright (c) 2020 IETF Trust and the persons identified as 3108 authors of the code. All rights reserved. 3110 Redistribution and use in source and binary forms, with or 3111 without modification, is permitted pursuant to, and subject 3112 to the license terms contained in, the Simplified BSD License 3113 set forth in Section 4.c of the IETF Trust's Legal Provisions 3114 Relating to IETF Documents 3115 (http://trustee.ietf.org/license-info). 3117 This version of this YANG module is part of RFC XXXX; see 3118 the RFC itself for full legal notices."; 3120 revision 2020-09-24 { 3121 description 3122 "Updated revision to comply with RFC8791."; 3123 reference 3124 "RFC XXXX: Distributed Denial-of-Service Open Threat 3125 Signaling (DOTS) Signal Channel Specification"; 3126 } 3127 revision 2020-05-28 { 3128 description 3129 "Initial revision."; 3130 reference 3131 "RFC 8782: Distributed Denial-of-Service Open Threat 3132 Signaling (DOTS) Signal Channel Specification"; 3133 } 3135 /* 3136 * Groupings 3137 */ 3139 grouping mitigation-scope { 3140 description 3141 "Specifies the scope of the mitigation request."; 3142 list scope { 3143 description 3144 "The scope of the request."; 3145 uses data-channel:target; 3146 leaf-list alias-name { 3147 type string; 3148 description 3149 "An alias name that points to a resource."; 3150 } 3151 leaf lifetime { 3152 type union { 3153 type uint32; 3154 type int32 { 3155 range "-1"; 3156 } 3157 } 3158 units "seconds"; 3159 default "3600"; 3160 description 3161 "Indicates the lifetime of the mitigation request. 3163 A lifetime of '0' in a mitigation request is an 3164 invalid value. 3166 A lifetime of negative one (-1) indicates indefinite 3167 lifetime for the mitigation request. 3169 Lifetime is mandatory in a mitigation request. 3171 The DOTS server must always indicate the actual lifetime 3172 in the response to an accepted mitigation request and the 3173 remaining lifetime in status messages sent to the 3174 DOTS client."; 3175 } 3176 leaf trigger-mitigation { 3177 type boolean; 3178 default "true"; 3179 description 3180 "If set to 'false', DDoS mitigation will not be 3181 triggered unless the DOTS signal channel 3182 session is lost."; 3183 } 3184 choice direction { 3185 description 3186 "Indicates the communication direction in which the 3187 data nodes can be included."; 3188 case server-to-client-only { 3189 description 3190 "These data nodes appear only in a mitigation message 3191 sent from the server to the client."; 3192 leaf mid { 3193 type uint32; 3194 description 3195 "Mitigation request identifier. 3197 This identifier must be unique for each mitigation 3198 request bound to the DOTS client."; 3199 } 3200 leaf mitigation-start { 3201 type uint64; 3202 description 3203 "Mitigation start time is represented in seconds 3204 relative to 1970-01-01T00:00:00Z in UTC time. 3206 This is a mandatory attribute when an attack mitigation 3207 is active. It must not be returned for a 3208 mitigation with 'status' code set to 8."; 3209 } 3210 leaf status { 3211 type iana-dots-signal:status; 3212 description 3213 "Indicates the status of a mitigation request. 3215 It must be included in responses only. 3217 This is a mandatory attribute if a mitigation 3218 request is accepted and processed by the server."; 3219 } 3220 container conflict-information { 3221 description 3222 "Indicates that a conflict is detected. 3223 Must only be used for responses."; 3224 leaf conflict-status { 3225 type iana-dots-signal:conflict-status; 3226 description 3227 "Indicates the conflict status."; 3228 } 3229 leaf conflict-cause { 3230 type iana-dots-signal:conflict-cause; 3231 description 3232 "Indicates the cause of the conflict."; 3233 } 3234 leaf retry-timer { 3235 type uint32; 3236 units "seconds"; 3237 description 3238 "The DOTS client must not resend the 3239 same request that has a conflict before the expiry of 3240 this timer."; 3241 } 3242 container conflict-scope { 3243 description 3244 "Provides more information about the conflict scope."; 3245 uses data-channel:target { 3246 when "/dots-signal/scope/conflict-information/" 3247 + "conflict-cause = 'overlapping-targets'"; 3248 } 3249 leaf-list alias-name { 3250 when "../../conflict-cause = 'overlapping-targets'"; 3251 type string; 3252 description 3253 "Conflicting alias-name."; 3254 } 3255 list acl-list { 3256 when "../../conflict-cause =" 3257 + " 'conflict-with-acceptlist'"; 3258 key "acl-name"; 3259 description 3260 "List of conflicting ACLs as defined in the DOTS data 3261 channel. These ACLs are uniquely defined by 3262 cuid and acl-name."; 3264 leaf acl-name { 3265 type leafref { 3266 path "/data-channel:dots-data" 3267 + "/data-channel:dots-client/data-channel:acls" 3268 + "/data-channel:acl/data-channel:name"; 3269 } 3270 description 3271 "Reference to the conflicting ACL name bound to 3272 a DOTS client."; 3273 } 3274 leaf acl-type { 3275 type leafref { 3276 path "/data-channel:dots-data" 3277 + "/data-channel:dots-client/data-channel:acls" 3278 + "/data-channel:acl/data-channel:type"; 3279 } 3280 description 3281 "Reference to the conflicting ACL type bound to 3282 a DOTS client."; 3283 } 3284 } 3285 leaf mid { 3286 when "../../conflict-cause = 'overlapping-targets'"; 3287 type uint32; 3288 description 3289 "Reference to the conflicting 'mid' bound to 3290 the same DOTS client."; 3291 } 3292 } 3293 } 3294 leaf bytes-dropped { 3295 type yang:zero-based-counter64; 3296 units "bytes"; 3297 description 3298 "The total dropped byte count for the mitigation 3299 request since the attack mitigation was triggered. 3300 The count wraps around when it reaches the maximum value 3301 of counter64 for dropped bytes."; 3302 } 3303 leaf bps-dropped { 3304 type yang:gauge64; 3305 description 3306 "The average number of dropped bits per second for 3307 the mitigation request since the attack 3308 mitigation was triggered. This should be over 3309 five-minute intervals (that is, measuring bytes 3310 into five-minute buckets and then averaging these 3311 buckets over the time since the mitigation was 3312 triggered)."; 3313 } 3314 leaf pkts-dropped { 3315 type yang:zero-based-counter64; 3316 description 3317 "The total number of dropped packet count for the 3318 mitigation request since the attack mitigation was 3319 triggered. The count wraps around when it reaches 3320 the maximum value of counter64 for dropped packets."; 3321 } 3322 leaf pps-dropped { 3323 type yang:gauge64; 3324 description 3325 "The average number of dropped packets per second 3326 for the mitigation request since the attack 3327 mitigation was triggered. This should be over 3328 five-minute intervals (that is, measuring packets 3329 into five-minute buckets and then averaging these 3330 buckets over the time since the mitigation was 3331 triggered)."; 3332 } 3333 } 3334 case client-to-server-only { 3335 description 3336 "These data nodes appear only in a mitigation message 3337 sent from the client to the server."; 3338 leaf attack-status { 3339 type iana-dots-signal:attack-status; 3340 description 3341 "Indicates the status of an attack as seen by the 3342 DOTS client. 3344 Ths is is a mandatory attribute when a client 3345 performs an efficacy update."; 3346 } 3347 } 3348 } 3349 } 3350 } 3352 grouping config-parameters { 3353 description 3354 "Subset of DOTS signal channel session configuration."; 3355 container heartbeat-interval { 3356 description 3357 "DOTS agents regularly send heartbeats to each other 3358 after mutual authentication is successfully 3359 completed in order to keep the DOTS signal channel 3360 open."; 3361 choice direction { 3362 description 3363 "Indicates the communication direction in which the 3364 data nodes can be included."; 3365 case server-to-client-only { 3366 description 3367 "These data nodes appear only in a mitigation message 3368 sent from the server to the client."; 3369 leaf max-value { 3370 type uint16; 3371 units "seconds"; 3372 description 3373 "Maximum acceptable heartbeat-interval value."; 3374 } 3375 leaf min-value { 3376 type uint16; 3377 units "seconds"; 3378 description 3379 "Minimum acceptable heartbeat-interval value."; 3380 } 3381 } 3382 } 3383 leaf current-value { 3384 type uint16; 3385 units "seconds"; 3386 default "30"; 3387 description 3388 "Current heartbeat-interval value. 3390 '0' means that heartbeat mechanism is deactivated."; 3391 } 3392 } 3393 container missing-hb-allowed { 3394 description 3395 "Maximum number of missing heartbeats allowed."; 3396 choice direction { 3397 description 3398 "Indicates the communication direction in which the 3399 data nodes can be included."; 3400 case server-to-client-only { 3401 description 3402 "These data nodes appear only in a mitigation message 3403 sent from the server to the client."; 3404 leaf max-value { 3405 type uint16; 3406 description 3407 "Maximum acceptable missing-hb-allowed value."; 3409 } 3410 leaf min-value { 3411 type uint16; 3412 description 3413 "Minimum acceptable missing-hb-allowed value."; 3414 } 3415 } 3416 } 3417 leaf current-value { 3418 type uint16; 3419 default "15"; 3420 description 3421 "Current missing-hb-allowed value."; 3422 } 3423 } 3424 container probing-rate { 3425 description 3426 "The limit for sending Non-confirmable messages with 3427 no response."; 3428 choice direction { 3429 description 3430 "Indicates the communication direction in which the 3431 data nodes can be included."; 3432 case server-to-client-only { 3433 description 3434 "These data nodes appear only in a mitigation message 3435 sent from the server to the client."; 3436 leaf max-value { 3437 type uint16; 3438 units "byte/second"; 3439 description 3440 "Maximum acceptable probing-rate value."; 3441 } 3442 leaf min-value { 3443 type uint16; 3444 units "byte/second"; 3445 description 3446 "Minimum acceptable probing-rate value."; 3447 } 3448 } 3449 } 3450 leaf current-value { 3451 type uint16; 3452 units "byte/second"; 3453 default "5"; 3454 description 3455 "Current probing-rate value."; 3456 } 3458 } 3459 container max-retransmit { 3460 description 3461 "Maximum number of retransmissions of a Confirmable 3462 message."; 3463 choice direction { 3464 description 3465 "Indicates the communication direction in which the 3466 data nodes can be included."; 3467 case server-to-client-only { 3468 description 3469 "These data nodes appear only in a mitigation message 3470 sent from the server to the client."; 3471 leaf max-value { 3472 type uint16; 3473 description 3474 "Maximum acceptable max-retransmit value."; 3475 } 3476 leaf min-value { 3477 type uint16; 3478 description 3479 "Minimum acceptable max-retransmit value."; 3480 } 3481 } 3482 } 3483 leaf current-value { 3484 type uint16; 3485 default "3"; 3486 description 3487 "Current max-retransmit value."; 3488 } 3489 } 3490 container ack-timeout { 3491 description 3492 "Initial retransmission timeout value."; 3493 choice direction { 3494 description 3495 "Indicates the communication direction in which the 3496 data nodes can be included."; 3497 case server-to-client-only { 3498 description 3499 "These data nodes appear only in a mitigation message 3500 sent from the server to the client."; 3501 leaf max-value-decimal { 3502 type decimal64 { 3503 fraction-digits 2; 3504 } 3505 units "seconds"; 3506 description 3507 "Maximum ack-timeout value."; 3508 } 3509 leaf min-value-decimal { 3510 type decimal64 { 3511 fraction-digits 2; 3512 } 3513 units "seconds"; 3514 description 3515 "Minimum ack-timeout value."; 3516 } 3517 } 3518 } 3519 leaf current-value-decimal { 3520 type decimal64 { 3521 fraction-digits 2; 3522 } 3523 units "seconds"; 3524 default "2"; 3525 description 3526 "Current ack-timeout value."; 3527 } 3528 } 3529 container ack-random-factor { 3530 description 3531 "Random factor used to influence the timing of 3532 retransmissions."; 3533 choice direction { 3534 description 3535 "Indicates the communication direction in which the 3536 data nodes can be included."; 3537 case server-to-client-only { 3538 description 3539 "These data nodes appear only in a mitigation message 3540 sent from the server to the client."; 3541 leaf max-value-decimal { 3542 type decimal64 { 3543 fraction-digits 2; 3544 } 3545 description 3546 "Maximum acceptable ack-random-factor value."; 3547 } 3548 leaf min-value-decimal { 3549 type decimal64 { 3550 fraction-digits 2; 3551 } 3552 description 3553 "Minimum acceptable ack-random-factor value."; 3555 } 3556 } 3557 } 3558 leaf current-value-decimal { 3559 type decimal64 { 3560 fraction-digits 2; 3561 } 3562 default "1.5"; 3563 description 3564 "Current ack-random-factor value."; 3565 } 3566 } 3567 } 3569 grouping signal-config { 3570 description 3571 "DOTS signal channel session configuration."; 3572 container mitigating-config { 3573 description 3574 "Configuration parameters to use when a mitigation 3575 is active."; 3576 uses config-parameters; 3577 } 3578 container idle-config { 3579 description 3580 "Configuration parameters to use when no mitigation 3581 is active."; 3582 uses config-parameters; 3583 } 3584 } 3586 grouping redirected-signal { 3587 description 3588 "Grouping for the redirected signaling."; 3589 choice direction { 3590 description 3591 "Indicates the communication direction in which the 3592 data nodes can be included."; 3593 case server-to-client-only { 3594 description 3595 "These data nodes appear only in a mitigation message 3596 sent from the server to the client."; 3597 leaf alt-server { 3598 type inet:domain-name; 3599 mandatory true; 3600 description 3601 "FQDN of an alternate server."; 3602 } 3603 leaf-list alt-server-record { 3604 type inet:ip-address; 3605 description 3606 "List of records for the alternate server."; 3607 } 3608 } 3609 } 3610 } 3612 /* 3613 * DOTS Signal Channel Structure 3614 */ 3616 sx:structure dots-signal { 3617 description 3618 "Main structure for DOTS signal message. 3620 A DOTS signal message can be a mitigation, a configuration, 3621 or a redirected signal message."; 3622 choice message-type { 3623 description 3624 "Can be a mitigation, a configuration, or a redirect 3625 message."; 3626 case mitigation-scope { 3627 description 3628 "Mitigation scope of a mitigation message."; 3629 uses mitigation-scope; 3630 } 3631 case signal-config { 3632 description 3633 "Configuration message."; 3634 uses signal-config; 3635 } 3636 case redirected-signal { 3637 description 3638 "Redirected signaling."; 3639 uses redirected-signal; 3640 } 3641 case heartbeat { 3642 description 3643 "DOTS heartbeats."; 3644 leaf peer-hb-status { 3645 type boolean; 3646 mandatory true; 3647 description 3648 "Indicates whether a DOTS agent receives heartbeats 3649 from its peer. The value is set to 'true' if the 3650 DOTS agent is receiving heartbeat messages 3651 from its peer."; 3652 } 3653 } 3654 } 3655 } 3656 } 3657 3659 6. YANG/JSON Mapping Parameters to CBOR 3661 All parameters in the payload of the DOTS signal channel MUST be 3662 mapped to CBOR types as shown in Table 5 and are assigned an integer 3663 key to save space. 3665 Note: Implementers must check that the mapping output provided by 3666 their YANG-to-CBOR encoding schemes is aligned with the content of 3667 Table 5. For example, some CBOR and JSON types for enumerations 3668 and the 64-bit quantities can differ depending on the encoder 3669 used. 3671 The CBOR key values are divided into two types: comprehension- 3672 required and comprehension-optional. DOTS agents can safely ignore 3673 comprehension-optional values they don't understand, but they cannot 3674 successfully process a request if it contains comprehension-required 3675 values that are not understood. The 4.00 response SHOULD include a 3676 diagnostic payload describing the unknown comprehension-required CBOR 3677 key values. The initial set of CBOR key values defined in this 3678 specification are of type comprehension-required. 3680 +---------------------+--------------+------+-------------+--------+ 3681 | Parameter Name | YANG Type | CBOR | CBOR Major | JSON | 3682 | | | Key | Type & | Type | 3683 | | | | Information | | 3684 +=====================+==============+======+=============+========+ 3685 | ietf-dots-signal- | container | 1 | 5 map | Object | 3686 | channel:mitigation- | | | | | 3687 | scope | | | | | 3688 +---------------------+--------------+------+-------------+--------+ 3689 | scope | list | 2 | 4 array | Array | 3690 +---------------------+--------------+------+-------------+--------+ 3691 | cdid | string | 3 | 3 text | String | 3692 | | | | string | | 3693 +---------------------+--------------+------+-------------+--------+ 3694 | cuid | string | 4 | 3 text | String | 3695 | | | | string | | 3696 +---------------------+--------------+------+-------------+--------+ 3697 | mid | uint32 | 5 | 0 unsigned | Number | 3698 +---------------------+--------------+------+-------------+--------+ 3699 | target-prefix | leaf-list | 6 | 4 array | Array | 3700 | +--------------+------+-------------+--------+ 3701 | | inet:ip- | | 3 text | String | 3702 | | prefix | | string | | 3703 +---------------------+--------------+------+-------------+--------+ 3704 | target-port-range | list | 7 | 4 array | Array | 3705 +---------------------+--------------+------+-------------+--------+ 3706 | lower-port | inet:port- | 8 | 0 unsigned | Number | 3707 | | number | | | | 3708 +---------------------+--------------+------+-------------+--------+ 3709 | upper-port | inet:port- | 9 | 0 unsigned | Number | 3710 | | number | | | | 3711 +---------------------+--------------+------+-------------+--------+ 3712 | target-protocol | leaf-list | 10 | 4 array | Array | 3713 | +--------------+------+-------------+--------+ 3714 | | uint8 | | 0 unsigned | Number | 3715 +---------------------+--------------+------+-------------+--------+ 3716 | target-fqdn | leaf-list | 11 | 4 array | Array | 3717 | +--------------+------+-------------+--------+ 3718 | | inet:domain- | | 3 text | String | 3719 | | name | | string | | 3720 +---------------------+--------------+------+-------------+--------+ 3721 | target-uri | leaf-list | 12 | 4 array | Array | 3722 | +--------------+------+-------------+--------+ 3723 | | inet:uri | | 3 text | String | 3724 | | | | string | | 3725 +---------------------+--------------+------+-------------+--------+ 3726 | alias-name | leaf-list | 13 | 4 array | Array | 3727 | +--------------+------+-------------+--------+ 3728 | | string | | 3 text | String | 3729 | | | | string | | 3730 +---------------------+--------------+------+-------------+--------+ 3731 | lifetime | union | 14 | 0 unsigned | Number | 3732 | | | +-------------+--------+ 3733 | | | | 1 negative | Number | 3734 +---------------------+--------------+------+-------------+--------+ 3735 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3736 +---------------------+--------------+------+-------------+--------+ 3737 | status | enumeration | 16 | 0 unsigned | String | 3738 +---------------------+--------------+------+-------------+--------+ 3739 | conflict- | container | 17 | 5 map | Object | 3740 | information | | | | | 3741 +---------------------+--------------+------+-------------+--------+ 3742 | conflict-status | enumeration | 18 | 0 unsigned | String | 3743 +---------------------+--------------+------+-------------+--------+ 3744 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3745 +---------------------+--------------+------+-------------+--------+ 3746 | retry-timer | uint32 | 20 | 0 unsigned | String | 3747 +---------------------+--------------+------+-------------+--------+ 3748 | conflict-scope | container | 21 | 5 map | Object | 3749 +---------------------+--------------+------+-------------+--------+ 3750 | acl-list | list | 22 | 4 array | Array | 3751 +---------------------+--------------+------+-------------+--------+ 3752 | acl-name | leafref | 23 | 3 text | String | 3753 | | | | string | | 3754 +---------------------+--------------+------+-------------+--------+ 3755 | acl-type | leafref | 24 | 3 text | String | 3756 | | | | string | | 3757 +---------------------+--------------+------+-------------+--------+ 3758 | bytes-dropped | yang:zero- | 25 | 0 unsigned | String | 3759 | | based- | | | | 3760 | | counter64 | | | | 3761 +---------------------+--------------+------+-------------+--------+ 3762 | bps-dropped | yang:gauge64 | 26 | 0 unsigned | String | 3763 +---------------------+--------------+------+-------------+--------+ 3764 | pkts-dropped | yang:zero- | 27 | 0 unsigned | String | 3765 | | based- | | | | 3766 | | counter64 | | | | 3767 +---------------------+--------------+------+-------------+--------+ 3768 | pps-dropped | yang:gauge64 | 28 | 0 unsigned | String | 3769 +---------------------+--------------+------+-------------+--------+ 3770 | attack-status | enumeration | 29 | 0 unsigned | String | 3771 +---------------------+--------------+------+-------------+--------+ 3772 | ietf-dots-signal- | container | 30 | 5 map | Object | 3773 | channel:signal- | | | | | 3774 | config | | | | | 3775 +---------------------+--------------+------+-------------+--------+ 3776 | sid | uint32 | 31 | 0 unsigned | Number | 3777 +---------------------+--------------+------+-------------+--------+ 3778 | mitigating-config | container | 32 | 5 map | Object | 3779 +---------------------+--------------+------+-------------+--------+ 3780 | heartbeat-interval | container | 33 | 5 map | Object | 3781 +---------------------+--------------+------+-------------+--------+ 3782 | max-value | uint16 | 34 | 0 unsigned | Number | 3783 +---------------------+--------------+------+-------------+--------+ 3784 | min-value | uint16 | 35 | 0 unsigned | Number | 3785 +---------------------+--------------+------+-------------+--------+ 3786 | current-value | uint16 | 36 | 0 unsigned | Number | 3787 +---------------------+--------------+------+-------------+--------+ 3788 | missing-hb-allowed | container | 37 | 5 map | Object | 3789 +---------------------+--------------+------+-------------+--------+ 3790 | max-retransmit | container | 38 | 5 map | Object | 3791 +---------------------+--------------+------+-------------+--------+ 3792 | ack-timeout | container | 39 | 5 map | Object | 3793 +---------------------+--------------+------+-------------+--------+ 3794 | ack-random-factor | container | 40 | 5 map | Object | 3795 +---------------------+--------------+------+-------------+--------+ 3796 | max-value-decimal | decimal64 | 41 | 6 tag 4 | String | 3797 | | | | [-2, | | 3798 | | | | integer] | | 3799 +---------------------+--------------+------+-------------+--------+ 3800 | min-value-decimal | decimal64 | 42 | 6 tag 4 | String | 3801 | | | | [-2, | | 3802 | | | | integer] | | 3803 +---------------------+--------------+------+-------------+--------+ 3804 | current-value- | decimal64 | 43 | 6 tag 4 | String | 3805 | decimal | | | [-2, | | 3806 | | | | integer] | | 3807 +---------------------+--------------+------+-------------+--------+ 3808 | idle-config | container | 44 | 5 map | Object | 3809 +---------------------+--------------+------+-------------+--------+ 3810 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3811 | | | +-------------+--------+ 3812 | | | | 7 bits 21 | True | 3813 +---------------------+--------------+------+-------------+--------+ 3814 | ietf-dots-signal- | container | 46 | 5 map | Object | 3815 | channel:redirected- | | | | | 3816 | signal | | | | | 3817 +---------------------+--------------+------+-------------+--------+ 3818 | alt-server | inet:domain- | 47 | 3 text | String | 3819 | | name | | string | | 3820 +---------------------+--------------+------+-------------+--------+ 3821 | alt-server-record | leaf-list | 48 | 4 array | Array | 3822 | +--------------+------+-------------+--------+ 3823 | | inet:ip- | | 3 text | String | 3824 | | address | | string | | 3825 +---------------------+--------------+------+-------------+--------+ 3826 | ietf-dots-signal- | container | 49 | 5 map | Object | 3827 | channel:heartbeat | | | | | 3828 +---------------------+--------------+------+-------------+--------+ 3829 | probing-rate | container | 50 | 5 map | Object | 3830 +---------------------+--------------+------+-------------+--------+ 3831 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3832 | | | +-------------+--------+ 3833 | | | | 7 bits 21 | True | 3834 +---------------------+--------------+------+-------------+--------+ 3836 Table 5: CBOR Key Values Used in DOTS Signal Channel Messages & 3837 Their Mappings to JSON and YANG 3839 7. (D)TLS Protocol Profile and Performance Considerations 3841 7.1. (D)TLS Protocol Profile 3843 This section defines the (D)TLS protocol profile of DOTS signal 3844 channel over (D)TLS and DOTS data channel over TLS. 3846 There are known attacks on (D)TLS, such as man-in-the-middle and 3847 protocol downgrade attacks. These are general attacks on (D)TLS and, 3848 as such, they are not specific to DOTS over (D)TLS; refer to the 3849 (D)TLS RFCs for discussion of these security issues. DOTS agents 3850 MUST adhere to the (D)TLS implementation recommendations and security 3851 considerations of [RFC7525] except with respect to (D)TLS version. 3852 Because DOTS signal channel encryption relying upon (D)TLS is 3853 virtually a greenfield deployment, DOTS agents MUST implement only 3854 (D)TLS 1.2 or later. 3856 When a DOTS client is configured with a domain name of the DOTS 3857 server, and it connects to its configured DOTS server, the server may 3858 present it with a PKIX certificate. In order to ensure proper 3859 authentication, a DOTS client MUST verify the entire certification 3860 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3861 validation techniques to compare the domain name with the certificate 3862 provided. Certification authorities that issue DOTS server 3863 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3864 DOTS servers SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3865 identifier types in certificate requests (as described in Section 2.3 3866 of [RFC6125]), and the wildcard character '*' SHOULD NOT be included 3867 in the presented identifier. DOTS doesn't use URI-IDs for server 3868 identity verification. 3870 A key challenge to deploying DOTS is the provisioning of DOTS 3871 clients, including the distribution of keying material to DOTS 3872 clients to enable the required mutual authentication of DOTS agents. 3873 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3874 certificate enrollment by which domains operating DOTS servers may 3875 provide DOTS clients with all the necessary cryptographic keying 3876 material, including a private key and a certificate, to authenticate 3877 themselves. One deployment option is to have DOTS clients behave as 3878 EST clients for certificate enrollment from an EST server provisioned 3879 by the mitigation provider. This document does not specify which EST 3880 or other mechanism the DOTS client uses to achieve initial 3881 enrollment. 3883 The Server Name Indication (SNI) extension [RFC6066] defines a 3884 mechanism for a client to tell a (D)TLS server the name of the server 3885 it wants to contact. This is a useful extension for hosting 3886 environments where multiple virtual servers are reachable over a 3887 single IP address. The DOTS client may or may not know if it is 3888 interacting with a DOTS server in a virtual server hosting 3889 environment, so the DOTS client SHOULD include the DOTS server FQDN 3890 in the SNI extension. 3892 Implementations compliant with this profile MUST implement all of the 3893 following items: 3895 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3896 equivalent mechanism to protect against replay attacks. 3898 o DTLS session resumption without server-side state to resume 3899 session and convey the DOTS signal. 3901 o At least one of raw public keys [RFC7250] or PSK handshake 3902 [RFC4279] with (EC)DHE key exchange. This reduces the size of the 3903 ServerHello. Also, this can be used by DOTS agents that cannot 3904 obtain certificates. 3906 Implementations compliant with this profile SHOULD implement all of 3907 the following items to reduce the delay required to deliver a DOTS 3908 signal channel message: 3910 o TLS False Start [RFC7918], which reduces round-trips by allowing 3911 the TLS client's second flight of messages (ChangeCipherSpec) to 3912 also contain the DOTS signal. TLS False Start is formally defined 3913 for use with TLS, but the same technique is applicable to DTLS as 3914 well. 3916 o Cached Information Extension [RFC7924] which avoids transmitting 3917 the server's certificate and certificate chain if the client has 3918 cached that information from a previous TLS handshake. 3920 Compared to UDP, DOTS signal channel over TCP requires an additional 3921 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3922 implementations are encouraged to implement TCP Fast Open [RFC7413] 3923 to eliminate that RTT. 3925 7.2. (D)TLS 1.3 Considerations 3927 TLS 1.3 provides useful latency improvements for connection 3928 establishment over TLS 1.2. The DTLS 1.3 protocol 3929 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3930 equivalent security guarantees. (D)TLS 1.3 provides two basic 3931 handshake modes the DOTS signal channel can take advantage of: 3933 o A full handshake mode in which a DOTS client can send a DOTS 3934 mitigation request message after one round trip and the DOTS 3935 server immediately responds with a DOTS mitigation response. This 3936 assumes no packet loss is experienced. 3938 o 0-RTT mode in which the DOTS client can authenticate itself and 3939 send DOTS mitigation request messages in the first message, thus 3940 reducing handshake latency. 0-RTT only works if the DOTS client 3941 has previously communicated with that DOTS server, which is very 3942 likely with the DOTS signal channel. 3944 The DOTS client has to establish a (D)TLS session with the DOTS 3945 server during 'idle' time and share a PSK. 3947 During a DDoS attack, the DOTS client can use the (D)TLS session to 3948 convey the DOTS mitigation request message and, if there is no 3949 response from the server after multiple retries, the DOTS client can 3950 resume the (D)TLS session in 0-RTT mode using PSK. 3952 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to send 3953 early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" as early 3954 data; such messages MUST be rejected by DOTS servers. Section 8 of 3955 [RFC8446] discusses some mechanisms to implement in order to limit 3956 the impact of replay attacks on 0-RTT data. If the DOTS server 3957 accepts 0-RTT, it MUST implement one of these mechanisms to prevent 3958 replay at the TLS layer. A DOTS server can reject 0-RTT by sending a 3959 TLS HelloRetryRequest. 3961 The DOTS signal channel messages sent as early data by the DOTS 3962 client are idempotent requests. As a reminder, the Message ID 3963 (Section 3 of [RFC7252]) is changed each time a new CoAP request is 3964 sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized in 3965 each CoAP request. The DOTS server(s) MUST use the Message ID and 3966 the Token in the DOTS signal channel message to detect replay of 3967 early data at the application layer and accept 0-RTT data at most 3968 once from the same DOTS client. This anti-replay defense requires 3969 sharing the Message ID and the Token in the 0-RTT data between DOTS 3970 servers in the DOTS server domain. DOTS servers do not rely on 3971 transport coordinates to identify DOTS peers. As specified in 3972 Section 4.4.1, DOTS servers couple the DOTS signal channel sessions 3973 using the DOTS client identity and optionally the 'cdid' parameter 3974 value. Furthermore, the 'mid' value is monotonically increased by 3975 the DOTS client for each mitigation request, thus attackers that 3976 replay mitigation requests with lower numeric 'mid' values and 3977 overlapping scopes with mitigation requests having higher numeric 3978 'mid' values will be rejected systematically by the DOTS server. 3979 Likewise, the 'sid' value is monotonically increased by the DOTS 3980 client for each configuration request (Section 4.5.2); attackers 3981 replaying configuration requests with lower numeric 'sid' values will 3982 be rejected by the DOTS server if it maintains a higher numeric 'sid' 3983 value for this DOTS client. 3985 Owing to the aforementioned protections, all DOTS signal channel 3986 requests are safe to transmit in TLS 1.3 as early data. Refer to 3987 [I-D.boucadair-dots-earlydata] for more details. 3989 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3990 message exchange is shown in Figure 29. 3992 DOTS Client DOTS Server 3994 ClientHello 3995 (0-RTT DOTS signal message) 3996 --------> 3997 ServerHello 3998 {EncryptedExtensions} 3999 {Finished} 4000 <-------- [DOTS signal message] 4001 (end_of_early_data) 4002 {Finished} --------> 4003 [DOTS signal message] <-------> [DOTS signal message] 4005 Note that: 4006 () Indicates messages protected 0-RTT keys 4007 {} Indicates messages protected using handshake keys 4008 [] Indicates messages protected using 1-RTT keys 4010 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 4012 7.3. DTLS MTU and Fragmentation 4014 To avoid DOTS signal message fragmentation and the subsequent 4015 decreased probability of message delivery, DOTS agents MUST ensure 4016 that the DTLS record fits within a single datagram. As a reminder, 4017 DTLS handles fragmentation and reassembly only for handshake messages 4018 and not for the application data (Section 4.1.1 of [RFC6347]). If 4019 the path MTU (PMTU) cannot be discovered, DOTS agents MUST assume a 4020 PMTU of 1280 bytes, as IPv6 requires that every link in the Internet 4021 have an MTU of 1280 octets or greater as specified in [RFC8200]. If 4022 IPv4 support on legacy or otherwise unusual networks is a 4023 consideration and the PMTU is unknown, DOTS implementations MAY 4024 assume a PMTU of 576 bytes for IPv4 datagrams, as every IPv4 host 4025 must be capable of receiving a packet whose length is equal to 576 4026 bytes as discussed in [RFC0791] and [RFC1122]. 4028 The DOTS client must consider the amount of record expansion expected 4029 by the DTLS processing when calculating the size of the CoAP message 4030 that fits within the PMTU. PMTU MUST be greater than or equal to 4031 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 4032 overhead of the negotiated DTLS cipher suite + block padding] 4033 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 4034 the PMTU, then the DOTS client MUST split the DOTS signal into 4035 separate messages; for example, the list of addresses in the 'target- 4036 prefix' parameter could be split into multiple lists and each list 4037 conveyed in a new PUT request. 4039 | Implementation Note: DOTS choice of message size parameters 4040 | works well with IPv6 and with most of today's IPv4 paths. 4041 | However, with IPv4, it is harder to safely make sure that there 4042 | is no IP fragmentation. If the IPv4 PMTU is unknown, 4043 | implementations may want to limit themselves to more 4044 | conservative IPv4 datagram sizes such as 576 bytes, per 4045 | [RFC0791]. 4047 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 4049 (D)TLS based upon client certificates can be used for mutual 4050 authentication between DOTS agents. If, for example, a DOTS gateway 4051 is involved, DOTS clients and DOTS gateways must perform mutual 4052 authentication; only authorized DOTS clients are allowed to send DOTS 4053 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 4054 perform mutual authentication; a DOTS server only allows DOTS signal 4055 channel messages from an authorized DOTS gateway, thereby creating a 4056 two-link chain of transitive authentication between the DOTS client 4057 and the DOTS server. 4059 The DOTS server should support certificate-based client 4060 authentication. The DOTS client should respond to the DOTS server's 4061 TLS CertificateRequest message with the PKIX certificate held by the 4062 DOTS client. DOTS client certificate validation must be performed 4063 per [RFC5280], and the DOTS client certificate must conform to the 4064 [RFC5280] certificate profile. If a DOTS client does not support TLS 4065 client certificate authentication, it must support client 4066 authentication based on pre-shared key or raw public key. 4068 +---------------------------------------------+ 4069 | example.com domain +---------+ | 4070 | | AAA | | 4071 | +---------------+ | Server | | 4072 | | Application | +------+--+ | 4073 | | server +<---------------+ ^ | 4074 | | (DOTS client) | | | | 4075 | +---------------+ | | | 4076 | V V | example.net domain 4077 | +-----+----+--+ | +---------------+ 4078 | +--------------+ | | | | | 4079 | | Guest +<----x---->+ DOTS +<----->+ DOTS | 4080 | | (DOTS client)| | gateway | | | server | 4081 | +--------------+ | | | | | 4082 | +----+--------+ | +---------------+ 4083 | ^ | 4084 | | | 4085 | +----------------+ | | 4086 | | DDoS detector | | | 4087 | | (DOTS client) +<-------------+ | 4088 | +----------------+ | 4089 +---------------------------------------------+ 4091 Figure 30: Example of Authentication and Authorization of DOTS Agents 4093 In the example depicted in Figure 30, the DOTS gateway and DOTS 4094 clients within the 'example.com' domain mutually authenticate. After 4095 the DOTS gateway validates the identity of a DOTS client, it 4096 communicates with the AAA server in the 'example.com' domain to 4097 determine if the DOTS client is authorized to request DDoS 4098 mitigation. If the DOTS client is not authorized, a 4.01 4099 (Unauthorized) is returned in the response to the DOTS client. In 4100 this example, the DOTS gateway only allows the application server and 4101 DDoS attack detector to request DDoS mitigation, but does not permit 4102 the user of type 'guest' to request DDoS mitigation. 4104 Also, DOTS gateways and servers located in different domains must 4105 perform mutual authentication (e.g., using certificates). A DOTS 4106 server will only allow a DOTS gateway with a certificate for a 4107 particular domain to request mitigation for that domain. In 4108 reference to Figure 30, the DOTS server only allows the DOTS gateway 4109 to request mitigation for the 'example.com' domain and not for other 4110 domains. 4112 9. Error Handling 4114 This section is a summary of the Error Code responses that can be 4115 returned by a DOTS server. These error responses must contain a CoAP 4116 4.xx or 5.xx Response Code. 4118 In general, there may be an additional plain text diagnostic payload 4119 (Section 5.5.2 of [RFC7252]) to help troubleshooting in the body of 4120 the response unless detailed otherwise. 4122 Errors returned by a DOTS server can be broken into two categories, 4123 those associated with CoAP itself and those generated during the 4124 validation of the provided data by the DOTS server. 4126 The following list of common CoAP errors that are implemented by DOTS 4127 servers. This list is not exhaustive, other errors defined by CoAP 4128 and associated RFCs may be applicable. 4130 o 4.00 (Bad Request) is returned by the DOTS server when the DOTS 4131 client has sent a request that violates the DOTS protocol 4132 (Section 4). 4134 o 4.01 (Unauthorized) is returned by the DOTS server when the DOTS 4135 client is not authorized to access the DOTS server (Section 4). 4137 o 4.02 (Bad Option) is returned by the DOTS server when one or more 4138 CoAP options are unknown or malformed by the CoAP layer [RFC7252]. 4140 o 4.04 (Not Found) is returned by the DOTS server when the DOTS 4141 client is requesting a 'mid' or 'sid' that is not valid 4142 (Section 4). 4144 o 4.05 (Method Not Allowed) is returned by the DOTS server when the 4145 DOTS client is requesting a resource by a method (e.g., GET) that 4146 is not supported by the DOTS server [RFC7252]. 4148 o 4.08 (Request Entity Incomplete) is returned by the DOTS server if 4149 one or multiple blocks of a block transfer request is missing 4150 [RFC7959]. 4152 o 4.09 (Conflict) is returned by the DOTS server if the DOTS server 4153 detects that a request conflicts with a previous request. The 4154 response body is formatted using "application/dots+cbor", and 4155 contains the "conflict-clause" (Section 4.4). 4157 o 4.13 (Request Entity Too Large) may be returned by the DOTS server 4158 during a block transfer request [RFC7959]. 4160 o 4.15 (Unsupported Content-Format) is returned by the DOTS server 4161 when the Content-Format used in the request is not formatted as 4162 "application/dots+cbor" (Section 4). 4164 o 4.22 (Unprocessable Entity) is returned by the DOTS server when 4165 one or more session configuration parameters are not valid 4166 (Section 4.5). 4168 o 5.03 (Service Unavailable) is returned by the DOTS server if the 4169 DOTS server is unable to handle the request (Section 4). An 4170 example is the DOTS server needs to redirect the DOTS client to 4171 use an alternate DOTS server (Section 4.6). The response body is 4172 formatted using "application/dots+cbor", and contains how to 4173 handle the 5.03 Response Code. 4175 o 5.08 (Hop Limit Reached) is returned by the DOTS server if there 4176 is a data path loop through upstream DOTS gateways. The response 4177 body is formatted using plain text and contains a list of servers 4178 that are in the data path loop [RFC8768]. 4180 10. IANA Considerations 4182 10.1. DOTS Signal Channel UDP and TCP Port Number 4184 IANA has assigned the port number 4646 (the ASCII decimal value for 4185 ".." (DOTS)) to the DOTS signal channel protocol for both UDP and TCP 4186 from the "Service Name and Transport Protocol Port Number Registry" 4187 available at . 4190 IANA is requested to update these entries with the RFC number to be 4191 assigned to this docuement: 4193 Service Name: dots-signal 4194 Port Number: 4646 4195 Transport Protocol: TCP 4196 Description: Distributed Denial-of-Service Open Threat Signaling 4197 (DOTS) Signal Channel 4198 Assignee: IESG 4199 Contact: IETF Chair 4200 Registration Date: 2020-01-16 4201 Reference: [RFCXXXX] 4203 Service Name: dots-signal 4204 Port Number: 4646 4205 Transport Protocol: UDP 4206 Description: Distributed Denial-of-Service Open Threat Signaling 4207 (DOTS) Signal Channel 4208 Assignee: IESG 4209 Contact: IETF Chair 4210 Registration Date: 2020-01-16 4211 Reference: [RFCXXXX] 4213 10.2. Well-Known 'dots' URI 4215 IANA is requested to update the the 'dots' well-known URI (Table 6) 4216 entry in the Well- Known URIs registry [URI] as follows: 4218 +------------+------------+-----------+-----------+-------------+ 4219 | URI Suffix | Change | Reference | Status | Related | 4220 | | Controller | | | information | 4221 +============+============+===========+===========+=============+ 4222 | dots | IETF | [RFCXXXX] | permanent | None | 4223 +------------+------------+-----------+-----------+-------------+ 4225 Table 6: 'dots' Well-Known URI 4227 10.3. Media Type Registration 4229 IANA is requested to update the "application/dots+cbor" media type in 4230 the "Media Types" registry [IANA-MediaTypes] in the manner described 4231 in [RFC6838], which can be used to indicate that the content is a 4232 DOTS signal channel object: 4234 Type name: application 4236 Subtype name: dots+cbor 4238 Required parameters: N/A 4240 Optional parameters: N/A 4242 Encoding considerations: binary 4244 Security considerations: See the Security Considerations section of 4245 [RFCXXXX]. 4247 Interoperability considerations: N/A 4249 Published specification: [RFCXXXX] 4251 Applications that use this media type: DOTS agents sending DOTS 4252 messages over CoAP over (D)TLS. 4254 Fragment identifier considerations: N/A 4256 Additional information: 4258 Deprecated alias names for this type: N/A 4259 Magic number(s): N/A 4260 File extension(s): N/A 4261 Macintosh file type code(s): N/A 4263 Person & email address to contact for further information: IESG, 4264 iesg@ietf.org 4266 Intended usage: COMMON 4268 Restrictions on usage: none 4270 Author: See Authors' Addresses section. 4272 Change controller: IESG 4274 Provisional registration? No 4276 10.4. CoAP Content-Formats Registration 4278 IANA is requested to update the CoAP Content-Format ID for the 4279 "application/ dots+cbor" media type in the "CoAP Content-Formats" 4280 registry [IANA-CoAP-Content-Formats]: 4282 o Media Type: application/dots+cbor 4283 o Encoding: - 4284 o Id: 271 4285 o Reference: [RFCXXXX] 4287 10.5. CBOR Tag Registration 4289 This section defines the DOTS CBOR tag as another means for 4290 applications to declare that a CBOR data structure is a DOTS signal 4291 channel object. Its use is optional and is intended for use in cases 4292 in which this information would not otherwise be known. The DOTS 4293 CBOR tag is not required for DOTS signal channel protocol version 4294 specified in this document. If present, the DOTS tag MUST prefix a 4295 DOTS signal channel object. 4297 IANA is requested to update the DOTS signal channel CBOR tag in the 4298 "CBOR Tags" registry [IANA-CBOR-Tags]: 4300 * Tag: 271 4301 * Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 4302 * Semantics: DDoS Open Threat Signaling (DOTS) signal channel 4303 object, as defined in [RFCXXXX] 4304 * Reference: [RFCXXXX] 4306 10.6. DOTS Signal Channel Protocol Registry 4308 The following sections update the "Distributed Denial-of- Service 4309 Open Threat Signaling (DOTS) Signal Channel" subregistries 4310 [REG-DOTS]. 4312 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry 4314 The structure of this subregistry is provided in Section 10.6.1.1. 4316 10.6.1.1. Registration Template 4318 This specification requests IANA to update the allocation policy of 4319 "DOTS Signal Channel CBOR Key Values" registry as follows: 4321 Parameter name: 4322 Parameter name as used in the DOTS signal channel. 4324 CBOR Key Value: 4325 Key value for the parameter. The key value MUST be an integer in 4326 the 1-65535 range. 4328 OLD: 4329 +-------------+-------------------------+------------------------+ 4330 | Range | Registration Procedures | Note | 4331 +=============+=========================+========================+ 4332 | 1-16383 | IETF Review | comprehension-required | 4333 | 16384-32767 | Specification Required | comprehension-optional | 4334 | 32768-49151 | IETF Review | comprehension-optional | 4335 | 49152-65535 | Private Use | comprehension-optional | 4336 +-------------+-------------------------+------------------------+ 4338 NEW: 4339 +-------------+-------------------------+------------------------+ 4340 | Range | Registration Procedures | Note | 4341 +=============+=========================+========================+ 4342 | 1-127 | IETF Review | comprehension-required | 4343 | 128-255 | IETF Review | comprehension-optional | 4344 | 256-16383 | IETF Review | comprehension-required | 4345 | 16384-32767 | Specification Required | comprehension-optional | 4346 | 32768-49151 | IETF Review | comprehension-optional | 4347 | 49152-65535 | Private Use | comprehension-optional | 4348 +-------------+-------------------------+------------------------+ 4350 Registration requests for the 16384-32767 range are evaluated 4351 after a three-week review period on the dots-signal-reg- 4352 review@ietf.org mailing list, on the advice of one or more 4353 Designated Experts. However, to allow for the allocation of 4354 values prior to publication, the Designated Experts may approve 4355 registration once they are satisfied that such a specification 4356 will be published. New registration requests should be sent in 4357 the form of an email to the review mailing list; the request 4358 should use an appropriate subject (e.g., "Request to register CBOR 4359 Key Value for DOTS: example"). IANA will only accept new 4360 registrations from the Designated Experts, and it will check that 4361 review was requested on the mailing list in accordance with these 4362 procedures. 4364 Within the review period, the Designated Experts will either 4365 approve or deny the registration request, communicating this 4366 decision to the review list and IANA. Denials should include an 4367 explanation and, if applicable, suggestions as to how to make the 4368 request successful. Registration requests that are undetermined 4369 for a period longer than 21 days can be brought to the IESG's 4370 attention (using the iesg@ietf.org mailing list) for resolution. 4372 Criteria that should be applied by the Designated Experts include 4373 determining whether the proposed registration duplicates existing 4374 functionality, whether it is likely to be of general applicability 4375 or whether it is useful only for a single use case, and whether 4376 the registration description is clear. IANA must only accept 4377 registry updates to the 16384-32767 range from the Designated 4378 Experts and should direct all requests for registration to the 4379 review mailing list. It is suggested that multiple Designated 4380 Experts be appointed. In cases where a registration decision 4381 could be perceived as creating a conflict of interest for a 4382 particular Expert, that Expert should defer to the judgment of the 4383 other Experts. 4385 CBOR Major Type: 4386 CBOR Major type and optional tag for the parameter. 4388 Change Controller: 4389 For Standards Track RFCs, list the "IESG". For others, give the 4390 name of the responsible party. Other details (e.g., email 4391 address) may also be included. 4393 Specification Document(s): 4394 Reference to the document or documents that specify the parameter, 4395 preferably including URIs that can be used to retrieve copies of 4396 the documents. An indication of the relevant sections may also be 4397 included but is not required. 4399 10.6.1.2. Update Subregistry Content 4401 IANA is requested to update these entries from the "DOTS Signal 4402 Channel CBOR Key Values" registry with the RFC number to be assigned 4403 to this document: 4405 +---------------------+------------+-----+----------+---------------+ 4406 | Parameter Name | CBOR Key |CBOR | Change | Specification | 4407 | | Value |Major|Controller| Document(s) | 4408 | | |Type | | | 4409 +=====================+============+=====+==========+===============+ 4410 | Reserved | 0 | | | [RFCXXXX] | 4411 +---------------------+------------+-----+----------+---------------+ 4412 | ietf-dots-signal- | 1 | 5 | IESG | [RFCXXXX] | 4413 | channel:mitigation- | | | | | 4414 | scope | | | | | 4415 +---------------------+------------+-----+----------+---------------+ 4416 | scope | 2 | 4 | IESG | [RFCXXXX] | 4417 +---------------------+------------+-----+----------+---------------+ 4418 | cdid | 3 | 3 | IESG | [RFCXXXX] | 4419 +---------------------+------------+-----+----------+---------------+ 4420 | cuid | 4 | 3 | IESG | [RFCXXXX] | 4421 +---------------------+------------+-----+----------+---------------+ 4422 | mid | 5 | 0 | IESG | [RFCXXXX] | 4423 +---------------------+------------+-----+----------+---------------+ 4424 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 4425 +---------------------+------------+-----+----------+---------------+ 4426 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 4427 +---------------------+------------+-----+----------+---------------+ 4428 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 4429 +---------------------+------------+-----+----------+---------------+ 4430 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 4431 +---------------------+------------+-----+----------+---------------+ 4432 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 4433 +---------------------+------------+-----+----------+---------------+ 4434 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 4435 +---------------------+------------+-----+----------+---------------+ 4436 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 4437 +---------------------+------------+-----+----------+---------------+ 4438 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 4439 +---------------------+------------+-----+----------+---------------+ 4440 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 4441 +---------------------+------------+-----+----------+---------------+ 4442 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 4443 +---------------------+------------+-----+----------+---------------+ 4444 | status | 16 | 0 | IESG | [RFCXXXX] | 4445 +---------------------+------------+-----+----------+---------------+ 4446 |conflict-information | 17 | 5 | IESG | [RFCXXXX] | 4447 +---------------------+------------+-----+----------+---------------+ 4448 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 4449 +---------------------+------------+-----+----------+---------------+ 4450 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 4451 +---------------------+------------+-----+----------+---------------+ 4452 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 4453 +---------------------+------------+-----+----------+---------------+ 4454 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 4455 +---------------------+------------+-----+----------+---------------+ 4456 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 4457 +---------------------+------------+-----+----------+---------------+ 4458 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 4459 +---------------------+------------+-----+----------+---------------+ 4460 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 4461 +---------------------+------------+-----+----------+---------------+ 4462 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 4463 +---------------------+------------+-----+----------+---------------+ 4464 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 4465 +---------------------+------------+-----+----------+---------------+ 4466 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 4467 +---------------------+------------+-----+----------+---------------+ 4468 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 4469 +---------------------+------------+-----+----------+---------------+ 4470 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 4471 +---------------------+------------+-----+----------+---------------+ 4472 |ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 4473 |channel:signal-config| | | | | 4474 +---------------------+------------+-----+----------+---------------+ 4475 | sid | 31 | 0 | IESG | [RFCXXXX] | 4476 +---------------------+------------+-----+----------+---------------+ 4477 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 4478 +---------------------+------------+-----+----------+---------------+ 4479 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 4480 +---------------------+------------+-----+----------+---------------+ 4481 | min-value | 34 | 0 | IESG | [RFCXXXX] | 4482 +---------------------+------------+-----+----------+---------------+ 4483 | max-value | 35 | 0 | IESG | [RFCXXXX] | 4484 +---------------------+------------+-----+----------+---------------+ 4485 | current-value | 36 | 0 | IESG | [RFCXXXX] | 4486 +---------------------+------------+-----+----------+---------------+ 4487 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 4488 +---------------------+------------+-----+----------+---------------+ 4489 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 4490 +---------------------+------------+-----+----------+---------------+ 4491 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 4492 +---------------------+------------+-----+----------+---------------+ 4493 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 4494 +---------------------+------------+-----+----------+---------------+ 4495 | min-value-decimal | 41 |6tag4| IESG | [RFCXXXX] | 4496 +---------------------+------------+-----+----------+---------------+ 4497 | max-value-decimal | 42 |6tag4| IESG | [RFCXXXX] | 4498 +---------------------+------------+-----+----------+---------------+ 4499 |current-value-decimal| 43 |6tag4| IESG | [RFCXXXX] | 4500 +---------------------+------------+-----+----------+---------------+ 4501 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 4502 +---------------------+------------+-----+----------+---------------+ 4503 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 4504 +---------------------+------------+-----+----------+---------------+ 4505 | ietf-dots-signal- | 46 | 5 | IESG | [RFCXXXX] | 4506 | channel:redirected- | | | | | 4507 | signal | | | | | 4508 +---------------------+------------+-----+----------+---------------+ 4509 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 4510 +---------------------+------------+-----+----------+---------------+ 4511 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 4512 +---------------------+------------+-----+----------+---------------+ 4513 | ietf-dots-signal- | 49 | 5 | IESG | [RFCXXXX] | 4514 | channel:heartbeat | | | | | 4515 +---------------------+------------+-----+----------+---------------+ 4516 | probing-rate | 50 | 5 | IESG | [RFCXXXX] | 4517 +---------------------+------------+-----+----------+---------------+ 4518 | peer-hb-status | 51 | 7 | IESG | [RFCXXXX] | 4519 +---------------------+------------+-----+----------+---------------+ 4520 | Unassigned | 52-49151 | | | | 4521 +---------------------+------------+-----+----------+---------------+ 4522 |Reserved for Private |49152-65535 | | | [RFCXXXX] | 4523 | Use | | | | | 4524 +---------------------+------------+-----+----------+---------------+ 4526 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 4528 10.6.2. Status Codes Subregistry 4530 IANA is requested to update these entries from the "DOTS Signal 4531 Channel Status Codes" registry with the RFC number to be assigned to 4532 this document: 4534 +--------------+---------------+----------------------+-----------+ 4535 | Code | Label | Description | Reference | 4536 +==============+===============+======================+===========+ 4537 | 0 | Reserved | | [RFCXXXX] | 4538 +--------------+---------------+----------------------+-----------+ 4539 | 1 | attack- | Attack mitigation | [RFCXXXX] | 4540 | | mitigation- | setup is in progress | | 4541 | | in-progress | (e.g., changing the | | 4542 | | | network path to | | 4543 | | | redirect the inbound | | 4544 | | | traffic to a DOTS | | 4545 | | | mitigator). | | 4546 +--------------+---------------+----------------------+-----------+ 4547 | 2 | attack- | Attack is being | [RFCXXXX] | 4548 | | successfully- | successfully | | 4549 | | mitigated | mitigated (e.g., | | 4550 | | | traffic is | | 4551 | | | redirected to a DDoS | | 4552 | | | mitigator and attack | | 4553 | | | traffic is dropped). | | 4554 +--------------+---------------+----------------------+-----------+ 4555 | 3 | attack- | Attack has stopped | [RFCXXXX] | 4556 | | stopped | and the DOTS client | | 4557 | | | can withdraw the | | 4558 | | | mitigation request. | | 4559 +--------------+---------------+----------------------+-----------+ 4560 | 4 | attack- | Attack has exceeded | [RFCXXXX] | 4561 | | exceeded- | the mitigation | | 4562 | | capability | provider capability. | | 4563 +--------------+---------------+----------------------+-----------+ 4564 | 5 | dots-client- | DOTS client has | [RFCXXXX] | 4565 | | withdrawn- | withdrawn the | | 4566 | | mitigation | mitigation request | | 4567 | | | and the mitigation | | 4568 | | | is active but | | 4569 | | | terminating. | | 4570 +--------------+---------------+----------------------+-----------+ 4571 | 6 | attack- | Attack mitigation is | [RFCXXXX] | 4572 | | mitigation- | now terminated. | | 4573 | | terminated | | | 4574 +--------------+---------------+----------------------+-----------+ 4575 | 7 | attack- | Attack mitigation is | [RFCXXXX] | 4576 | | mitigation- | withdrawn. | | 4577 | | withdrawn | | | 4578 +--------------+---------------+----------------------+-----------+ 4579 | 8 | attack- | Attack mitigation | [RFCXXXX] | 4580 | | mitigation- | will be triggered | | 4581 | | signal-loss | for the mitigation | | 4582 | | | request only when | | 4583 | | | the DOTS signal | | 4584 | | | channel session is | | 4585 | | | lost. | | 4586 +--------------+---------------+----------------------+-----------+ 4587 | 9-2147483647 | Unassigned | | | 4588 +--------------+---------------+----------------------+-----------+ 4590 Table 8: Initial DOTS Signal Channel Status Codes 4592 New codes can be assigned via Standards Action [RFC8126]. 4594 10.6.3. Conflict Status Codes Subregistry 4596 IANA is requested to update these entries from the "DOTS Signal 4597 Channel Conflict Status Codes" registry with the RFC number to be 4598 assigned to this document: 4600 +--------------+-------------------+--------------------+-----------+ 4601 | Code | Label | Description | Reference | 4602 +==============+===================+====================+===========+ 4603 | 0 | Reserved | | [RFCXXXX] | 4604 +--------------+-------------------+--------------------+-----------+ 4605 | 1 | request-inactive- | DOTS server | [RFCXXXX] | 4606 | | other-active | has detected | | 4607 | | | conflicting | | 4608 | | | mitigation | | 4609 | | | requests from | | 4610 | | | different DOTS | | 4611 | | | clients. This | | 4612 | | | mitigation | | 4613 | | | request is | | 4614 | | | currently | | 4615 | | | inactive until | | 4616 | | | the conflicts | | 4617 | | | are resolved. | | 4618 | | | Another | | 4619 | | | mitigation | | 4620 | | | request is | | 4621 | | | active. | | 4622 +--------------+-------------------+--------------------+-----------+ 4623 | 2 | request-active | DOTS server | [RFCXXXX] | 4624 | | | has detected | | 4625 | | | conflicting | | 4626 | | | mitigation | | 4627 | | | requests from | | 4628 | | | different DOTS | | 4629 | | | clients. This | | 4630 | | | mitigation | | 4631 | | | request is | | 4632 | | | currently | | 4633 | | | active. | | 4634 +--------------+-------------------+--------------------+-----------+ 4635 | 3 | all-requests- | DOTS server | [RFCXXXX] | 4636 | | inactive | has detected | | 4637 | | | conflicting | | 4638 | | | mitigation | | 4639 | | | requests from | | 4640 | | | different DOTS | | 4641 | | | clients. All | | 4642 | | | conflicting | | 4643 | | | mitigation | | 4644 | | | requests are | | 4645 | | | inactive. | | 4646 +--------------+-------------------+--------------------+-----------+ 4647 | 4-2147483647 | Unassigned | | | 4648 +--------------+-------------------+--------------------+-----------+ 4650 Table 9: Initial DOTS Signal Channel Conflict Status Codes 4652 New codes can be assigned via Standards Action [RFC8126]. 4654 10.6.4. Conflict Cause Codes Subregistry 4656 IANA is requested to update these entries from the "DOTS Signal 4657 Channel Conflict Cause Codes" registry with the RFC number to be 4658 assigned to this document: 4660 +--------------+---------------------+----------------+-----------+ 4661 | Code | Label | Description | Reference | 4662 +==============+=====================+================+===========+ 4663 | 0 | Reserved | | [RFCXXXX] | 4664 +--------------+---------------------+----------------+-----------+ 4665 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4666 | | | targets. | | 4667 +--------------+---------------------+----------------+-----------+ 4668 | 2 | conflict-with- | Conflicts with | [RFCXXXX] | 4669 | | acceptlist | an existing | | 4670 | | | accept-list. | | 4671 | | | This code is | | 4672 | | | returned when | | 4673 | | | the DDoS | | 4674 | | | mitigation | | 4675 | | | detects source | | 4676 | | | addresses/ | | 4677 | | | prefixes in | | 4678 | | | the accept- | | 4679 | | | listed ACLs | | 4680 | | | are attacking | | 4681 | | | the target. | | 4682 +--------------+---------------------+----------------+-----------+ 4683 | 3 | cuid-collision | CUID | [RFCXXXX] | 4684 | | | Collision. | | 4685 | | | This code is | | 4686 | | | returned when | | 4687 | | | a DOTS client | | 4688 | | | uses a 'cuid' | | 4689 | | | that is | | 4690 | | | already used | | 4691 | | | by another | | 4692 | | | DOTS client. | | 4693 +--------------+---------------------+----------------+-----------+ 4694 | 4-2147483647 | Unassigned | | | 4695 +--------------+---------------------+----------------+-----------+ 4697 Table 10: Initial DOTS Signal Channel Conflict Cause Codes 4699 New codes can be assigned via Standards Action [RFC8126]. 4701 10.6.5. Attack Status Codes Subregistry 4703 IANA is requested to update these entries from the "DOTS Signal 4704 Channel Attack Status Codes" registry with the RFC number to be 4705 assigned to this document: 4707 +--------------+----------------------+-----------------+-----------+ 4708 | Code | Label | Description | Reference | 4709 +==============+======================+=================+===========+ 4710 | 0 | Reserved | | [RFCXXXX] | 4711 +--------------+----------------------+-----------------+-----------+ 4712 | 1 | under-attack | The DOTS | [RFCXXXX] | 4713 | | | client | | 4714 | | | determines | | 4715 | | | that it is | | 4716 | | | still under | | 4717 | | | attack. | | 4718 +--------------+----------------------+-----------------+-----------+ 4719 | 2 | attack-successfully- | The DOTS | [RFCXXXX] | 4720 | | mitigated | client | | 4721 | | | determines | | 4722 | | | that the | | 4723 | | | attack is | | 4724 | | | successfully | | 4725 | | | mitigated. | | 4726 +--------------+----------------------+-----------------+-----------+ 4727 | 3-2147483647 | Unassigned | | | 4728 +--------------+----------------------+-----------------+-----------+ 4730 Table 11: Initial DOTS Signal Channel Attack Status Codes 4732 New codes can be assigned via Standards Action [RFC8126]. 4734 10.7. DOTS Signal Channel YANG Modules 4736 IANA already registered the following URIs in the "ns" subregistry 4737 within the "IETF XML Registry" [RFC3688]: 4739 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4740 Registrant Contact: The IESG. 4741 XML: N/A; the requested URI is an XML namespace. 4743 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4744 Registrant Contact: IANA. 4745 XML: N/A; the requested URI is an XML namespace. 4747 This document requests IANA to update the following YANG modules in 4748 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4749 Parameters" registry. 4751 Name: ietf-dots-signal-channel 4752 Maintained by IANA: N 4753 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4754 Prefix: dots-signal 4755 Reference: RFCXXXX 4757 Name: iana-dots-signal-channel 4758 Maintained by IANA: Y 4759 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4760 Prefix: iana-dots-signal 4761 Reference: RFCXXXX 4763 This document defines the initial version of the IANA-maintained 4764 iana-dots-signal-channel YANG module. IANA is requested to maintain 4765 this note: 4767 Status, conflict status, conflict cause, and attack status values 4768 must not be directly added to the iana-dots-signal-channel YANG 4769 module. They must instead be respectively added to the "DOTS 4770 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4771 Codes", and "DOTS Attack Status Codes" registries. 4773 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4774 status' value is respectively added to the "DOTS Status Codes", "DOTS 4775 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4776 Status Codes" registry, a new "enum" statement must be added to the 4777 iana-dots-signal-channel YANG module. The following "enum" 4778 statement, and substatements thereof, should be defined: 4780 "enum": Replicates the label from the registry. 4782 "value": Contains the IANA-assigned value corresponding to the 4783 'status', 'conflict-status', 'conflict-cause', or 4784 'attack-status'. 4786 "description": Replicates the description from the registry. 4788 "reference": Replicates the reference from the registry and adds 4789 the title of the document. 4791 When the iana-dots-signal-channel YANG module is updated, a new 4792 "revision" statement must be added in front of the existing revision 4793 statements. 4795 IANA is requested to update this note of "DOTS Status Codes", "DOTS 4796 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4797 Status Codes" registries: 4799 When this registry is modified, the YANG module iana-dots-signal- 4800 channel must be updated as defined in [RFCXXXX]. 4802 11. Security Considerations 4804 High-level DOTS security considerations are documented in [RFC8612] 4805 and [RFC8811]. 4807 Authenticated encryption MUST be used for data confidentiality and 4808 message integrity. The interaction between the DOTS agents requires 4809 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4810 (TLS) with a cipher suite offering confidentiality protection, and 4811 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4812 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4813 is specified in Section 7. 4815 If TCP is used between DOTS agents, an attacker may be able to inject 4816 RST packets, bogus application segments, etc., regardless of whether 4817 TLS authentication is used. Because the application data is TLS 4818 protected, this will not result in the application receiving bogus 4819 data, but it will constitute a DoS on the connection. This attack 4820 can be countered by using TCP Authentication Option (TCP-AO) 4821 [RFC5925]. Although not widely adopted, if TCP-AO is used, then any 4822 bogus packets injected by an attacker will be rejected by the TCP-AO 4823 integrity check and therefore will never reach the TLS layer. 4825 If the 'cuid' is guessable, a misbehaving DOTS client from within the 4826 client's domain can use the 'cuid' of another DOTS client of the 4827 domain to delete or alter active mitigations. For this attack vector 4828 to happen, the misbehaving client needs to pass the security 4829 validation checks by the DOTS server, and eventually the checks of a 4830 client-domain DOTS gateway. 4832 A similar attack can be achieved by a compromised DOTS client that 4833 can sniff the TLS 1.2 handshake, use the client certificate to 4834 identify the 'cuid' used by another DOTS client. This attack is not 4835 possible if algorithms such as version 4 Universally Unique 4836 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4837 the 'cuid' because such UUIDs are not a deterministic function of the 4838 client certificate. Likewise, this attack is not possible with TLS 4839 1.3 because most of the TLS handshake is encrypted and the client 4840 certificate is not visible to eavesdroppers. 4842 A compromised DOTS client can collude with a DDoS attacker to send 4843 mitigation request for a target resource, get the mitigation efficacy 4844 from the DOTS server, and convey the mitigation efficacy to the DDoS 4845 attacker to possibly change the DDoS attack strategy. Obviously, 4846 signaling an attack by the compromised DOTS client to the DOTS server 4847 will trigger attack mitigation. This attack can be prevented by 4848 monitoring and auditing DOTS clients to detect misbehavior and to 4849 deter misuse, and by only authorizing the DOTS client to request 4850 mitigation for specific target resources (e.g., an application server 4851 is authorized to request mitigation for its IP addresses, but a DDoS 4852 mitigator can request mitigation for any target resource in the 4853 network). Furthermore, DOTS clients are typically co-located on 4854 network security services (e.g., firewall), and a compromised 4855 security service potentially can do a lot more damage to the network. 4857 Rate-limiting DOTS requests, including those with new 'cuid' values, 4858 from the same DOTS client defend against DoS attacks that would 4859 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4860 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4861 DOTS servers. 4863 In order to prevent leaking internal information outside a client's 4864 domain, DOTS gateways located in the client domain SHOULD NOT reveal 4865 the identification information that pertains to internal DOTS clients 4866 (e.g., source IP address, client's hostname) unless explicitly 4867 configured to do so. 4869 DOTS servers MUST verify that requesting DOTS clients are entitled to 4870 trigger actions on a given IP prefix. That is, only actions on IP 4871 resources that belong to the DOTS client's domain MUST be authorized 4872 by a DOTS server. The exact mechanism for the DOTS servers to 4873 validate that the target prefixes are within the scope of the DOTS 4874 client domain is deployment specific. 4876 The presence of DOTS gateways may lead to infinite forwarding loops, 4877 which is undesirable. To prevent and detect such loops, this 4878 document uses the Hop-Limit Option. 4880 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4881 privacy-enabling protocols (e.g., DNS over TLS [RFC7858] or DNS over 4882 HTTPS (DoH) [RFC8484]) to prevent eavesdroppers from possibly 4883 identifying the target resources protected by the DDoS mitigation 4884 service to ensure the target FQDN resolution is authentic (e.g., 4885 DNSSEC [RFC4034]). 4887 CoAP-specific security considerations are discussed in Section 11 of 4888 [RFC7252], while CBOR-related security considerations are discussed 4889 in Section 8 of [RFC7049]. 4891 This document defines YANG data structures that are meant to be used 4892 as an abstract representation of DOTS signal channel messages. As 4893 such, the "ietf-dots-signal-channel" module does not introduce any 4894 new vulnerabilities beyond those specified above. 4896 12. References 4898 12.1. Normative References 4900 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4901 DOI 10.17487/RFC0791, September 1981, 4902 . 4904 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4905 Communication Layers", STD 3, RFC 1122, 4906 DOI 10.17487/RFC1122, October 1989, 4907 . 4909 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4910 Requirement Levels", BCP 14, RFC 2119, 4911 DOI 10.17487/RFC2119, March 1997, 4912 . 4914 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4915 DOI 10.17487/RFC3688, January 2004, 4916 . 4918 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4919 Resource Identifier (URI): Generic Syntax", STD 66, 4920 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4921 . 4923 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4924 Ciphersuites for Transport Layer Security (TLS)", 4925 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4926 . 4928 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4929 (CIDR): The Internet Address Assignment and Aggregation 4930 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4931 2006, . 4933 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4934 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4935 . 4937 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4938 (TLS) Protocol Version 1.2", RFC 5246, 4939 DOI 10.17487/RFC5246, August 2008, 4940 . 4942 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4943 Housley, R., and W. Polk, "Internet X.509 Public Key 4944 Infrastructure Certificate and Certificate Revocation List 4945 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4946 . 4948 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 4949 the Network Configuration Protocol (NETCONF)", RFC 6020, 4950 DOI 10.17487/RFC6020, October 2010, 4951 . 4953 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4954 Extensions: Extension Definitions", RFC 6066, 4955 DOI 10.17487/RFC6066, January 2011, 4956 . 4958 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4959 Verification of Domain-Based Application Service Identity 4960 within Internet Public Key Infrastructure Using X.509 4961 (PKIX) Certificates in the Context of Transport Layer 4962 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4963 2011, . 4965 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4966 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4967 January 2012, . 4969 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4970 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4971 . 4973 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4974 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4975 October 2013, . 4977 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4978 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4979 Transport Layer Security (TLS) and Datagram Transport 4980 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4981 June 2014, . 4983 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4984 Application Protocol (CoAP)", RFC 7252, 4985 DOI 10.17487/RFC7252, June 2014, 4986 . 4988 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4989 "Recommendations for Secure Use of Transport Layer 4990 Security (TLS) and Datagram Transport Layer Security 4991 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4992 2015, . 4994 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4995 Application Protocol (CoAP)", RFC 7641, 4996 DOI 10.17487/RFC7641, September 2015, 4997 . 4999 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 5000 Layer Security (TLS) False Start", RFC 7918, 5001 DOI 10.17487/RFC7918, August 2016, 5002 . 5004 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 5005 (TLS) Cached Information Extension", RFC 7924, 5006 DOI 10.17487/RFC7924, July 2016, 5007 . 5009 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 5010 RFC 7950, DOI 10.17487/RFC7950, August 2016, 5011 . 5013 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 5014 the Constrained Application Protocol (CoAP)", RFC 7959, 5015 DOI 10.17487/RFC7959, August 2016, 5016 . 5018 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 5019 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 5020 March 2017, . 5022 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 5023 Writing an IANA Considerations Section in RFCs", BCP 26, 5024 RFC 8126, DOI 10.17487/RFC8126, June 2017, 5025 . 5027 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5028 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5029 May 2017, . 5031 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 5032 (IPv6) Specification", STD 86, RFC 8200, 5033 DOI 10.17487/RFC8200, July 2017, 5034 . 5036 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 5037 Better Connectivity Using Concurrency", RFC 8305, 5038 DOI 10.17487/RFC8305, December 2017, 5039 . 5041 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 5042 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 5043 Application Protocol) over TCP, TLS, and WebSockets", 5044 RFC 8323, DOI 10.17487/RFC8323, February 2018, 5045 . 5047 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 5048 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 5049 . 5051 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 5052 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 5053 . 5055 [RFC8768] Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 5056 Application Protocol (CoAP) Hop-Limit Option", RFC 8768, 5057 DOI 10.17487/RFC8768, March 2020, 5058 . 5060 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 5061 Denial-of-Service Open Threat Signaling (DOTS) Data 5062 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 5063 May 2020, . 5065 [RFC8791] Bierman, A., Bjoerklund, M., and K. Watsen, "YANG Data 5066 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 5067 June 2020, . 5069 12.2. Informative References 5071 [I-D.boucadair-dots-earlydata] 5072 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 5073 boucadair-dots-earlydata-00 (work in progress), January 5074 2019. 5076 [I-D.ietf-core-comi] 5077 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 5078 Petrov, "CoAP Management Interface (CORECONF)", draft- 5079 ietf-core-comi-10 (work in progress), July 2020. 5081 [I-D.ietf-core-yang-cbor] 5082 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 5083 Data Modeled with YANG", draft-ietf-core-yang-cbor-13 5084 (work in progress), July 2020. 5086 [I-D.ietf-dots-multihoming] 5087 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 5088 Deployment Considerations for Distributed-Denial-of- 5089 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 5090 multihoming-05 (work in progress), November 2020. 5092 [I-D.ietf-dots-server-discovery] 5093 Boucadair, M. and T. Reddy.K, "Distributed-Denial-of- 5094 Service Open Threat Signaling (DOTS) Agent Discovery", 5095 draft-ietf-dots-server-discovery-15 (work in progress), 5096 November 2020. 5098 [I-D.ietf-dots-telemetry] 5099 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 5100 and J. Shallow, "Distributed Denial-of-Service Open Threat 5101 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-14 5102 (work in progress), November 2020. 5104 [I-D.ietf-dots-use-cases] 5105 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 5106 L., and K. Nishizuka, "Use cases for DDoS Open Threat 5107 Signaling", draft-ietf-dots-use-cases-25 (work in 5108 progress), July 2020. 5110 [I-D.ietf-tls-dtls13] 5111 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 5112 Datagram Transport Layer Security (DTLS) Protocol Version 5113 1.3", draft-ietf-tls-dtls13-39 (work in progress), 5114 November 2020. 5116 [IANA-CBOR-Tags] 5117 IANA, "Concise Binary Object Representation (CBOR) Tags", 5118 . 5121 [IANA-CoAP-Content-Formats] 5122 IANA, "CoAP Content-Formats", 5123 . 5126 [IANA-MediaTypes] 5127 IANA, "Media Types", 5128 . 5130 [IANA-Proto] 5131 IANA, "Protocol Numbers", 2011, 5132 . 5134 [REG-DOTS] 5135 IANA, "Distributed Denial-of-Service Open Threat Signaling 5136 (DOTS) Signal Channel", 5137 . 5139 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 5140 Address Translator (Traditional NAT)", RFC 3022, 5141 DOI 10.17487/RFC3022, January 2001, 5142 . 5144 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 5145 Rose, "Resource Records for the DNS Security Extensions", 5146 RFC 4034, DOI 10.17487/RFC4034, March 2005, 5147 . 5149 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 5150 Unique IDentifier (UUID) URN Namespace", RFC 4122, 5151 DOI 10.17487/RFC4122, July 2005, 5152 . 5154 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 5155 Congestion Control Protocol (DCCP)", RFC 4340, 5156 DOI 10.17487/RFC4340, March 2006, 5157 . 5159 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 5160 Denial-of-Service Considerations", RFC 4732, 5161 DOI 10.17487/RFC4732, December 2006, 5162 . 5164 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 5165 Translation (NAT) Behavioral Requirements for Unicast 5166 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 5167 2007, . 5169 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 5170 RFC 4960, DOI 10.17487/RFC4960, September 2007, 5171 . 5173 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 5174 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 5175 . 5177 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 5178 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 5179 June 2010, . 5181 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 5182 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 5183 DOI 10.17487/RFC6052, October 2010, 5184 . 5186 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 5187 NAT64: Network Address and Protocol Translation from IPv6 5188 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 5189 April 2011, . 5191 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 5192 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 5193 DOI 10.17487/RFC6234, May 2011, 5194 . 5196 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 5197 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 5198 . 5200 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 5201 "Default Address Selection for Internet Protocol Version 6 5202 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 5203 . 5205 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 5206 Specifications and Registration Procedures", BCP 13, 5207 RFC 6838, DOI 10.17487/RFC6838, January 2013, 5208 . 5210 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 5211 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 5212 DOI 10.17487/RFC6887, April 2013, 5213 . 5215 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 5216 A., and H. Ashida, "Common Requirements for Carrier-Grade 5217 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 5218 April 2013, . 5220 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 5221 "Enrollment over Secure Transport", RFC 7030, 5222 DOI 10.17487/RFC7030, October 2013, 5223 . 5225 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 5226 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 5227 . 5229 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 5230 "Architectural Considerations in Smart Object Networking", 5231 RFC 7452, DOI 10.17487/RFC7452, March 2015, 5232 . 5234 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 5235 NETCONF Protocol over Transport Layer Security (TLS) with 5236 Mutual X.509 Authentication", RFC 7589, 5237 DOI 10.17487/RFC7589, June 2015, 5238 . 5240 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 5241 and P. Hoffman, "Specification for DNS over Transport 5242 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 5243 2016, . 5245 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 5246 RFC 7951, DOI 10.17487/RFC7951, August 2016, 5247 . 5249 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 5250 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 5251 . 5253 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 5254 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 5255 . 5257 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 5258 D., Mahy, R., and P. Matthews, "Session Traversal 5259 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 5260 February 2020, . 5262 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 5263 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 5264 January 2019, . 5266 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 5267 Threat Signaling (DOTS) Requirements", RFC 8612, 5268 DOI 10.17487/RFC8612, May 2019, 5269 . 5271 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 5272 Mortensen, A., and N. Teague, "Distributed Denial-of- 5273 Service Open Threat Signaling (DOTS) Signal Channel 5274 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 5275 . 5277 [RFC8811] Mortensen, A., Ed., Reddy.K, T., Ed., Andreasen, F., 5278 Teague, N., and R. Compton, "DDoS Open Threat Signaling 5279 (DOTS) Architecture", RFC 8811, DOI 10.17487/RFC8811, 5280 August 2020, . 5282 [URI] IANA, "Well-Known URIs", 5283 . 5286 Appendix A. Summary of Changes From RFC8782 5288 The main changes compared to [RFC8782] are as follows: 5290 o Update the "ietf-dots-signal-channel" YANG module (Section 5.3) 5291 and the tree structure (Section 5.1) to follow the new YANG data 5292 structure specified in [RFC8791]. In particular: 5294 * Add in 'choice' to indicate the communication direction in 5295 which a data node applies. If no 'choice' is indicated, a data 5296 node can appear in both directions (i.e., from DOTS clients to 5297 DOTS servers and vice versa). 5299 * Remove 'config' clauses. Note that 'config' statements will be 5300 ignored (if present) anyway according to Section 4 of 5301 [RFC8791]. This supersedes the references to the use of 'ro' 5302 and 'rw' which are now covered by 'choice' above. 5304 * Remove 'cuid', 'cdid', and 'sid' data nodes from the structure 5305 because these data nodes are included as Uri-Path options, not 5306 within the message body. 5308 * Remove the list keys for the mitigation scope message type 5309 (i.e., 'cuid' and 'mid'). 'mid' is not indicated as a key 5310 because it is included as Uri-Path option for requests and in 5311 the message body for responses. Note that Section 4 of 5312 [RFC8791] specifies that a list does not require to have a key 5313 statement defined. 5315 o Add a new section with a summary of the error code responses that 5316 can be returned by a DOTS server (Section 9). 5318 o Update the IANA section to allocate a new range for comprehension- 5319 optional attributes (Section 10.6.1.1). This modification is 5320 motivated by the need to allow for compact DOTS signal messages 5321 that include a long list of comprehension-optional attributes, 5322 e.g., DOTS telemetry messages [I-D.ietf-dots-telemetry]. 5324 Appendix B. CUID Generation 5326 The document recommends the use of SPKI to generate the 'cuid'. This 5327 design choice is motivated by the following reasons: 5329 o SPKI is globally unique. 5331 o It is deterministic. 5333 o It allows the avoidance of extra cycles that may be induced by 5334 'cuid' collision. 5336 o DOTS clients do not need to store the 'cuid' in a persistent 5337 storage. 5339 o It allows the detection of compromised DOTS clients that do not 5340 adhere to the 'cuid' generation algorithm. 5342 Appendix C. Acknowledgements 5344 Many thanks to Martin Bjoerklund for the suggestion to use RFC8791. 5346 Thanks to Valery Smyslov for the comments, guidance, and support. 5348 Thanks to Ebben Aries for the yangdoctors review and Dan Romascanu 5349 for the opsdir review. 5351 C.1. Acknowledgements from RFC8782 5353 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 5354 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 5355 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 5356 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 5357 and comments. 5359 The authors would like to give special thanks to Kaname Nishizuka and 5360 Jon Shallow for their efforts in implementing the protocol and 5361 performing interop testing at IETF Hackathons. 5363 Thanks to the core WG for the recommendations on Hop-Limit and 5364 redirect signaling. 5366 Special thanks to Benjamin Kaduk for the detailed AD review. 5368 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 5369 Kuehlewind, and Alissa Cooper for the review. 5371 Thanks to Carsten Bormann for his review of the DOTS heartbeat 5372 mechanism. 5374 Appendix D. Contributors 5376 D.1. Authors of RFC8782 5378 The authors of RFC8782 are listed below: 5380 Tirumaleswar Reddy.K (editor) 5381 McAfee, Inc. 5382 Embassy Golf Link Business Park 5383 Bangalore 560071 5384 Karnataka 5385 India 5387 Email: kondtir@gmail.com 5389 Mohamed Boucadair (editor) 5390 Orange 5391 35000 Rennes 5392 France 5394 Email: mohamed.boucadair@orange.com 5396 Prashanth Patil 5397 Cisco Systems, Inc. 5399 Email: praspati@cisco.com 5401 Andrew Mortensen 5402 Arbor Networks, Inc. 5403 2727 S. State Street 5404 Ann Arbor, MI 48104 5405 United States of America 5407 Email: andrew@moretension.com 5409 Nik Teague 5410 Iron Mountain Data Centers 5411 United Kingdom 5413 Email: nteague@ironmountain.co.uk 5415 D.2. Contributors to RFC8782 5417 The following individuals have contributed to RFC8782: 5419 Jon Shallow 5420 NCC Group 5422 Email: jon.shallow@nccgroup.trust 5424 Mike Geller 5425 Cisco Systems, Inc. 5426 FL 33309 5427 United States of America 5429 Email: mgeller@cisco.com 5431 Robert Moskowitz 5432 HTT Consulting 5433 Oak Park, MI 42837 5434 United States of America 5436 Email: rgm@htt-consult.com 5438 Authors' Addresses 5440 Mohamed Boucadair (editor) 5441 Orange 5442 Rennes 35000 5443 France 5445 Email: mohamed.boucadair@orange.com 5447 Jon Shallow 5448 United Kingdom 5450 Email: supjps-ietf@jpshallow.com 5452 Tirumaleswar Reddy.K 5453 McAfee, Inc. 5454 Embassy Golf Link Business Park 5455 Bangalore, Karnataka 560071 5456 India 5458 Email: kondtir@gmail.com