idnits 2.17.1 draft-ietf-dots-rfc8782-bis-02.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 : ---------------------------------------------------------------------------- ** There are 4 instances of too long lines in the document, the longest one being 8 characters in excess of 72. 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 (November 17, 2020) is 1255 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 4797, but not defined == Missing Reference: 'RFCXXXx' is mentioned on line 4242, but not defined == Missing Reference: 'RFXXXX' is mentioned on line 4300, 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-04 == 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: 7 errors (**), 0 flaws (~~), 12 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: May 21, 2021 T. Reddy.K 7 McAfee 8 November 17, 2020 10 Distributed Denial-of-Service Open Threat Signaling (DOTS) Signal 11 Channel Specification 12 draft-ietf-dots-rfc8782-bis-02 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 May 21, 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 . . . 84 90 7.1. (D)TLS Protocol Profile . . . . . . . . . . . . . . . . . 84 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 string 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/data-channel:dots-client/" 3267 + "data-channel:acls/data-channel:acl/data-channel:name"; 3268 } 3269 description 3270 "Reference to the conflicting ACL name bound to 3271 a DOTS client."; 3272 } 3273 leaf acl-type { 3274 type leafref { 3275 path "/data-channel:dots-data/data-channel:dots-client/" 3276 + "data-channel:acls/data-channel:acl/data-channel:type"; 3277 } 3278 description 3279 "Reference to the conflicting ACL type bound to 3280 a DOTS client."; 3281 } 3282 } 3283 leaf mid { 3284 when "../../conflict-cause = 'overlapping-targets'"; 3285 type uint32; 3286 description 3287 "Reference to the conflicting 'mid' bound to 3288 the same DOTS client."; 3289 } 3290 } 3291 } 3292 leaf bytes-dropped { 3293 type yang:zero-based-counter64; 3294 units "bytes"; 3295 description 3296 "The total dropped byte count for the mitigation 3297 request since the attack mitigation was triggered. 3298 The count wraps around when it reaches the maximum value 3299 of counter64 for dropped bytes."; 3300 } 3301 leaf bps-dropped { 3302 type yang:gauge64; 3303 description 3304 "The average number of dropped bits per second for 3305 the mitigation request since the attack 3306 mitigation was triggered. This should be over 3307 five-minute intervals (that is, measuring bytes 3308 into five-minute buckets and then averaging these 3309 buckets over the time since the mitigation was 3310 triggered)."; 3311 } 3312 leaf pkts-dropped { 3313 type yang:zero-based-counter64; 3314 description 3315 "The total number of dropped packet count for the 3316 mitigation request since the attack mitigation was 3317 triggered. The count wraps around when it reaches 3318 the maximum value of counter64 for dropped packets."; 3319 } 3320 leaf pps-dropped { 3321 type yang:gauge64; 3322 description 3323 "The average number of dropped packets per second 3324 for the mitigation request since the attack 3325 mitigation was triggered. This should be over 3326 five-minute intervals (that is, measuring packets 3327 into five-minute buckets and then averaging these 3328 buckets over the time since the mitigation was 3329 triggered)."; 3330 } 3331 } 3332 case client-to-server-only { 3333 description 3334 "These data nodes appear only in a mitigation message 3335 sent from the client to the server."; 3336 leaf attack-status { 3337 type iana-dots-signal:attack-status; 3338 description 3339 "Indicates the status of an attack as seen by the 3340 DOTS client. 3342 Ths is is a mandatory attribute when a client 3343 performs an efficacy update."; 3344 } 3345 } 3346 } 3347 } 3348 } 3350 grouping config-parameters { 3351 description 3352 "Subset of DOTS signal channel session configuration."; 3353 container heartbeat-interval { 3354 description 3355 "DOTS agents regularly send heartbeats to each other 3356 after mutual authentication is successfully 3357 completed in order to keep the DOTS signal channel 3358 open."; 3359 choice direction { 3360 description 3361 "Indicates the communication direction in which the 3362 data nodes can be included."; 3363 case server-to-client-only { 3364 description 3365 "These data nodes appear only in a mitigation message 3366 sent from the server to the client."; 3367 leaf max-value { 3368 type uint16; 3369 units "seconds"; 3370 description 3371 "Maximum acceptable heartbeat-interval value."; 3372 } 3373 leaf min-value { 3374 type uint16; 3375 units "seconds"; 3376 description 3377 "Minimum acceptable heartbeat-interval value."; 3378 } 3379 } 3380 } 3381 leaf current-value { 3382 type uint16; 3383 units "seconds"; 3384 default "30"; 3385 description 3386 "Current heartbeat-interval value. 3388 '0' means that heartbeat mechanism is deactivated."; 3389 } 3390 } 3391 container missing-hb-allowed { 3392 description 3393 "Maximum number of missing heartbeats allowed."; 3394 choice direction { 3395 description 3396 "Indicates the communication direction in which the 3397 data nodes can be included."; 3398 case server-to-client-only { 3399 description 3400 "These data nodes appear only in a mitigation message 3401 sent from the server to the client."; 3402 leaf max-value { 3403 type uint16; 3404 description 3405 "Maximum acceptable missing-hb-allowed value."; 3406 } 3407 leaf min-value { 3408 type uint16; 3409 description 3410 "Minimum acceptable missing-hb-allowed value."; 3411 } 3412 } 3413 } 3414 leaf current-value { 3415 type uint16; 3416 default "15"; 3417 description 3418 "Current missing-hb-allowed value."; 3419 } 3420 } 3421 container probing-rate { 3422 description 3423 "The limit for sending Non-confirmable messages with 3424 no response."; 3425 choice direction { 3426 description 3427 "Indicates the communication direction in which the 3428 data nodes can be included."; 3429 case server-to-client-only { 3430 description 3431 "These data nodes appear only in a mitigation message 3432 sent from the server to the client."; 3433 leaf max-value { 3434 type uint16; 3435 units "byte/second"; 3436 description 3437 "Maximum acceptable probing-rate value."; 3438 } 3439 leaf min-value { 3440 type uint16; 3441 units "byte/second"; 3442 description 3443 "Minimum acceptable probing-rate value."; 3444 } 3445 } 3446 } 3447 leaf current-value { 3448 type uint16; 3449 units "byte/second"; 3450 default "5"; 3451 description 3452 "Current probing-rate value."; 3453 } 3454 } 3455 container max-retransmit { 3456 description 3457 "Maximum number of retransmissions of a Confirmable 3458 message."; 3459 choice direction { 3460 description 3461 "Indicates the communication direction in which the 3462 data nodes can be included."; 3463 case server-to-client-only { 3464 description 3465 "These data nodes appear only in a mitigation message 3466 sent from the server to the client."; 3467 leaf max-value { 3468 type uint16; 3469 description 3470 "Maximum acceptable max-retransmit value."; 3471 } 3472 leaf min-value { 3473 type uint16; 3474 description 3475 "Minimum acceptable max-retransmit value."; 3476 } 3477 } 3478 } 3479 leaf current-value { 3480 type uint16; 3481 default "3"; 3482 description 3483 "Current max-retransmit value."; 3484 } 3485 } 3486 container ack-timeout { 3487 description 3488 "Initial retransmission timeout value."; 3489 choice direction { 3490 description 3491 "Indicates the communication direction in which the 3492 data nodes can be included."; 3493 case server-to-client-only { 3494 description 3495 "These data nodes appear only in a mitigation message 3496 sent from the server to the client."; 3497 leaf max-value-decimal { 3498 type decimal64 { 3499 fraction-digits 2; 3500 } 3501 units "seconds"; 3502 description 3503 "Maximum ack-timeout value."; 3505 } 3506 leaf min-value-decimal { 3507 type decimal64 { 3508 fraction-digits 2; 3509 } 3510 units "seconds"; 3511 description 3512 "Minimum ack-timeout value."; 3513 } 3514 } 3515 } 3516 leaf current-value-decimal { 3517 type decimal64 { 3518 fraction-digits 2; 3519 } 3520 units "seconds"; 3521 default "2"; 3522 description 3523 "Current ack-timeout value."; 3524 } 3525 } 3526 container ack-random-factor { 3527 description 3528 "Random factor used to influence the timing of 3529 retransmissions."; 3530 choice direction { 3531 description 3532 "Indicates the communication direction in which the 3533 data nodes can be included."; 3534 case server-to-client-only { 3535 description 3536 "These data nodes appear only in a mitigation message 3537 sent from the server to the client."; 3538 leaf max-value-decimal { 3539 type decimal64 { 3540 fraction-digits 2; 3541 } 3542 description 3543 "Maximum acceptable ack-random-factor value."; 3544 } 3545 leaf min-value-decimal { 3546 type decimal64 { 3547 fraction-digits 2; 3548 } 3549 description 3550 "Minimum acceptable ack-random-factor value."; 3551 } 3552 } 3554 } 3555 leaf current-value-decimal { 3556 type decimal64 { 3557 fraction-digits 2; 3558 } 3559 default "1.5"; 3560 description 3561 "Current ack-random-factor value."; 3562 } 3563 } 3564 } 3566 grouping signal-config { 3567 description 3568 "DOTS signal channel session configuration."; 3569 container mitigating-config { 3570 description 3571 "Configuration parameters to use when a mitigation 3572 is active."; 3573 uses config-parameters; 3574 } 3575 container idle-config { 3576 description 3577 "Configuration parameters to use when no mitigation 3578 is active."; 3579 uses config-parameters; 3580 } 3581 } 3583 grouping redirected-signal { 3584 description 3585 "Grouping for the redirected signaling."; 3586 choice direction { 3587 description 3588 "Indicates the communication direction in which the 3589 data nodes can be included."; 3590 case server-to-client-only { 3591 description 3592 "These data nodes appear only in a mitigation message 3593 sent from the server to the client."; 3594 leaf alt-server { 3595 type string; 3596 mandatory true; 3597 description 3598 "FQDN of an alternate server."; 3599 } 3600 leaf-list alt-server-record { 3601 type inet:ip-address; 3602 description 3603 "List of records for the alternate server."; 3604 } 3605 } 3606 } 3607 } 3609 /* 3610 * DOTS Signal Channel Structure 3611 */ 3612 sx:structure dots-signal { 3613 description 3614 "Main structure for DOTS signal message. 3616 A DOTS signal message can be a mitigation, a configuration, 3617 or a redirected signal message."; 3618 choice message-type { 3619 description 3620 "Can be a mitigation, a configuration, or a redirect 3621 message."; 3622 case mitigation-scope { 3623 description 3624 "Mitigation scope of a mitigation message."; 3625 uses mitigation-scope; 3626 } 3627 case signal-config { 3628 description 3629 "Configuration message."; 3630 uses signal-config; 3631 } 3632 case redirected-signal { 3633 description 3634 "Redirected signaling."; 3635 uses redirected-signal; 3636 } 3637 case heartbeat { 3638 description 3639 "DOTS heartbeats."; 3640 leaf peer-hb-status { 3641 type boolean; 3642 mandatory true; 3643 description 3644 "Indicates whether a DOTS agent receives heartbeats 3645 from its peer. The value is set to 'true' if the 3646 DOTS agent is receiving heartbeat messages 3647 from its peer."; 3648 } 3649 } 3651 } 3652 } 3653 } 3654 3656 6. YANG/JSON Mapping Parameters to CBOR 3658 All parameters in the payload of the DOTS signal channel MUST be 3659 mapped to CBOR types as shown in Table 5 and are assigned an integer 3660 key to save space. 3662 Note: Implementers must check that the mapping output provided by 3663 their YANG-to-CBOR encoding schemes is aligned with the content of 3664 Table 5. For example, some CBOR and JSON types for enumerations 3665 and the 64-bit quantities can differ depending on the encoder 3666 used. 3668 The CBOR key values are divided into two types: comprehension- 3669 required and comprehension-optional. DOTS agents can safely ignore 3670 comprehension-optional values they don't understand, but they cannot 3671 successfully process a request if it contains comprehension-required 3672 values that are not understood. The 4.00 response SHOULD include a 3673 diagnostic payload describing the unknown comprehension-required CBOR 3674 key values. The initial set of CBOR key values defined in this 3675 specification are of type comprehension-required. 3677 +---------------------+--------------+------+-------------+--------+ 3678 | Parameter Name | YANG Type | CBOR | CBOR Major | JSON | 3679 | | | Key | Type & | Type | 3680 | | | | Information | | 3681 +=====================+==============+======+=============+========+ 3682 | ietf-dots-signal- | container | 1 | 5 map | Object | 3683 | channel:mitigation- | | | | | 3684 | scope | | | | | 3685 +---------------------+--------------+------+-------------+--------+ 3686 | scope | list | 2 | 4 array | Array | 3687 +---------------------+--------------+------+-------------+--------+ 3688 | cdid | string | 3 | 3 text | String | 3689 | | | | string | | 3690 +---------------------+--------------+------+-------------+--------+ 3691 | cuid | string | 4 | 3 text | String | 3692 | | | | string | | 3693 +---------------------+--------------+------+-------------+--------+ 3694 | mid | uint32 | 5 | 0 unsigned | Number | 3695 +---------------------+--------------+------+-------------+--------+ 3696 | target-prefix | leaf-list | 6 | 4 array | Array | 3697 | +--------------+------+-------------+--------+ 3698 | | inet:ip- | | 3 text | String | 3699 | | prefix | | string | | 3700 +---------------------+--------------+------+-------------+--------+ 3701 | target-port-range | list | 7 | 4 array | Array | 3702 +---------------------+--------------+------+-------------+--------+ 3703 | lower-port | inet:port- | 8 | 0 unsigned | Number | 3704 | | number | | | | 3705 +---------------------+--------------+------+-------------+--------+ 3706 | upper-port | inet:port- | 9 | 0 unsigned | Number | 3707 | | number | | | | 3708 +---------------------+--------------+------+-------------+--------+ 3709 | target-protocol | leaf-list | 10 | 4 array | Array | 3710 | +--------------+------+-------------+--------+ 3711 | | uint8 | | 0 unsigned | Number | 3712 +---------------------+--------------+------+-------------+--------+ 3713 | target-fqdn | leaf-list | 11 | 4 array | Array | 3714 | +--------------+------+-------------+--------+ 3715 | | inet:domain- | | 3 text | String | 3716 | | name | | string | | 3717 +---------------------+--------------+------+-------------+--------+ 3718 | target-uri | leaf-list | 12 | 4 array | Array | 3719 | +--------------+------+-------------+--------+ 3720 | | inet:uri | | 3 text | String | 3721 | | | | string | | 3722 +---------------------+--------------+------+-------------+--------+ 3723 | alias-name | leaf-list | 13 | 4 array | Array | 3724 | +--------------+------+-------------+--------+ 3725 | | string | | 3 text | String | 3726 | | | | string | | 3727 +---------------------+--------------+------+-------------+--------+ 3728 | lifetime | union | 14 | 0 unsigned | Number | 3729 | | | +-------------+--------+ 3730 | | | | 1 negative | Number | 3731 +---------------------+--------------+------+-------------+--------+ 3732 | mitigation-start | uint64 | 15 | 0 unsigned | String | 3733 +---------------------+--------------+------+-------------+--------+ 3734 | status | enumeration | 16 | 0 unsigned | String | 3735 +---------------------+--------------+------+-------------+--------+ 3736 | conflict- | container | 17 | 5 map | Object | 3737 | information | | | | | 3738 +---------------------+--------------+------+-------------+--------+ 3739 | conflict-status | enumeration | 18 | 0 unsigned | String | 3740 +---------------------+--------------+------+-------------+--------+ 3741 | conflict-cause | enumeration | 19 | 0 unsigned | String | 3742 +---------------------+--------------+------+-------------+--------+ 3743 | retry-timer | uint32 | 20 | 0 unsigned | String | 3744 +---------------------+--------------+------+-------------+--------+ 3745 | conflict-scope | container | 21 | 5 map | Object | 3746 +---------------------+--------------+------+-------------+--------+ 3747 | acl-list | list | 22 | 4 array | Array | 3748 +---------------------+--------------+------+-------------+--------+ 3749 | acl-name | leafref | 23 | 3 text | String | 3750 | | | | string | | 3751 +---------------------+--------------+------+-------------+--------+ 3752 | acl-type | leafref | 24 | 3 text | String | 3753 | | | | string | | 3754 +---------------------+--------------+------+-------------+--------+ 3755 | bytes-dropped | yang:zero- | 25 | 0 unsigned | String | 3756 | | based- | | | | 3757 | | counter64 | | | | 3758 +---------------------+--------------+------+-------------+--------+ 3759 | bps-dropped | yang:gauge64 | 26 | 0 unsigned | String | 3760 +---------------------+--------------+------+-------------+--------+ 3761 | pkts-dropped | yang:zero- | 27 | 0 unsigned | String | 3762 | | based- | | | | 3763 | | counter64 | | | | 3764 +---------------------+--------------+------+-------------+--------+ 3765 | pps-dropped | yang:gauge64 | 28 | 0 unsigned | String | 3766 +---------------------+--------------+------+-------------+--------+ 3767 | attack-status | enumeration | 29 | 0 unsigned | String | 3768 +---------------------+--------------+------+-------------+--------+ 3769 | ietf-dots-signal- | container | 30 | 5 map | Object | 3770 | channel:signal- | | | | | 3771 | config | | | | | 3772 +---------------------+--------------+------+-------------+--------+ 3773 | sid | uint32 | 31 | 0 unsigned | Number | 3774 +---------------------+--------------+------+-------------+--------+ 3775 | mitigating-config | container | 32 | 5 map | Object | 3776 +---------------------+--------------+------+-------------+--------+ 3777 | heartbeat-interval | container | 33 | 5 map | Object | 3778 +---------------------+--------------+------+-------------+--------+ 3779 | max-value | uint16 | 34 | 0 unsigned | Number | 3780 +---------------------+--------------+------+-------------+--------+ 3781 | min-value | uint16 | 35 | 0 unsigned | Number | 3782 +---------------------+--------------+------+-------------+--------+ 3783 | current-value | uint16 | 36 | 0 unsigned | Number | 3784 +---------------------+--------------+------+-------------+--------+ 3785 | missing-hb-allowed | container | 37 | 5 map | Object | 3786 +---------------------+--------------+------+-------------+--------+ 3787 | max-retransmit | container | 38 | 5 map | Object | 3788 +---------------------+--------------+------+-------------+--------+ 3789 | ack-timeout | container | 39 | 5 map | Object | 3790 +---------------------+--------------+------+-------------+--------+ 3791 | ack-random-factor | container | 40 | 5 map | Object | 3792 +---------------------+--------------+------+-------------+--------+ 3793 | max-value-decimal | decimal64 | 41 | 6 tag 4 | String | 3794 | | | | [-2, | | 3795 | | | | integer] | | 3796 +---------------------+--------------+------+-------------+--------+ 3797 | min-value-decimal | decimal64 | 42 | 6 tag 4 | String | 3798 | | | | [-2, | | 3799 | | | | integer] | | 3800 +---------------------+--------------+------+-------------+--------+ 3801 | current-value- | decimal64 | 43 | 6 tag 4 | String | 3802 | decimal | | | [-2, | | 3803 | | | | integer] | | 3804 +---------------------+--------------+------+-------------+--------+ 3805 | idle-config | container | 44 | 5 map | Object | 3806 +---------------------+--------------+------+-------------+--------+ 3807 | trigger-mitigation | boolean | 45 | 7 bits 20 | False | 3808 | | | +-------------+--------+ 3809 | | | | 7 bits 21 | True | 3810 +---------------------+--------------+------+-------------+--------+ 3811 | ietf-dots-signal- | container | 46 | 5 map | Object | 3812 | channel:redirected- | | | | | 3813 | signal | | | | | 3814 +---------------------+--------------+------+-------------+--------+ 3815 | alt-server | string | 47 | 3 text | String | 3816 | | | | string | | 3817 +---------------------+--------------+------+-------------+--------+ 3818 | alt-server-record | leaf-list | 48 | 4 array | Array | 3819 | +--------------+------+-------------+--------+ 3820 | | inet:ip- | | 3 text | String | 3821 | | address | | string | | 3822 +---------------------+--------------+------+-------------+--------+ 3823 | ietf-dots-signal- | container | 49 | 5 map | Object | 3824 | channel:heartbeat | | | | | 3825 +---------------------+--------------+------+-------------+--------+ 3826 | probing-rate | container | 50 | 5 map | Object | 3827 +---------------------+--------------+------+-------------+--------+ 3828 | peer-hb-status | boolean | 51 | 7 bits 20 | False | 3829 | | | +-------------+--------+ 3830 | | | | 7 bits 21 | True | 3831 +---------------------+--------------+------+-------------+--------+ 3833 Table 5: CBOR Key Values Used in DOTS Signal Channel Messages & 3834 Their Mappings to JSON and YANG 3836 7. (D)TLS Protocol Profile and Performance Considerations 3838 7.1. (D)TLS Protocol Profile 3840 This section defines the (D)TLS protocol profile of DOTS signal 3841 channel over (D)TLS and DOTS data channel over TLS. 3843 There are known attacks on (D)TLS, such as man-in-the-middle and 3844 protocol downgrade attacks. These are general attacks on (D)TLS and, 3845 as such, they are not specific to DOTS over (D)TLS; refer to the 3846 (D)TLS RFCs for discussion of these security issues. DOTS agents 3847 MUST adhere to the (D)TLS implementation recommendations and security 3848 considerations of [RFC7525] except with respect to (D)TLS version. 3849 Because DOTS signal channel encryption relying upon (D)TLS is 3850 virtually a greenfield deployment, DOTS agents MUST implement only 3851 (D)TLS 1.2 or later. 3853 When a DOTS client is configured with a domain name of the DOTS 3854 server, and it connects to its configured DOTS server, the server may 3855 present it with a PKIX certificate. In order to ensure proper 3856 authentication, a DOTS client MUST verify the entire certification 3857 path per [RFC5280]. Additionally, the DOTS client MUST use [RFC6125] 3858 validation techniques to compare the domain name with the certificate 3859 provided. Certification authorities that issue DOTS server 3860 certificates SHOULD support the DNS-ID and SRV-ID identifier types. 3861 DOTS servers SHOULD prefer the use of DNS-ID and SRV-ID over CN-ID 3862 identifier types in certificate requests (as described in Section 2.3 3863 of [RFC6125]), and the wildcard character '*' SHOULD NOT be included 3864 in the presented identifier. DOTS doesn't use URI-IDs for server 3865 identity verification. 3867 A key challenge to deploying DOTS is the provisioning of DOTS 3868 clients, including the distribution of keying material to DOTS 3869 clients to enable the required mutual authentication of DOTS agents. 3870 Enrollment over Secure Transport (EST) [RFC7030] defines a method of 3871 certificate enrollment by which domains operating DOTS servers may 3872 provide DOTS clients with all the necessary cryptographic keying 3873 material, including a private key and a certificate, to authenticate 3874 themselves. One deployment option is to have DOTS clients behave as 3875 EST clients for certificate enrollment from an EST server provisioned 3876 by the mitigation provider. This document does not specify which EST 3877 or other mechanism the DOTS client uses to achieve initial 3878 enrollment. 3880 The Server Name Indication (SNI) extension [RFC6066] defines a 3881 mechanism for a client to tell a (D)TLS server the name of the server 3882 it wants to contact. This is a useful extension for hosting 3883 environments where multiple virtual servers are reachable over a 3884 single IP address. The DOTS client may or may not know if it is 3885 interacting with a DOTS server in a virtual server hosting 3886 environment, so the DOTS client SHOULD include the DOTS server FQDN 3887 in the SNI extension. 3889 Implementations compliant with this profile MUST implement all of the 3890 following items: 3892 o DTLS record replay detection (Section 3.3 of [RFC6347]) or an 3893 equivalent mechanism to protect against replay attacks. 3895 o DTLS session resumption without server-side state to resume 3896 session and convey the DOTS signal. 3898 o At least one of raw public keys [RFC7250] or PSK handshake 3899 [RFC4279] with (EC)DHE key exchange. This reduces the size of the 3900 ServerHello. Also, this can be used by DOTS agents that cannot 3901 obtain certificates. 3903 Implementations compliant with this profile SHOULD implement all of 3904 the following items to reduce the delay required to deliver a DOTS 3905 signal channel message: 3907 o TLS False Start [RFC7918], which reduces round-trips by allowing 3908 the TLS client's second flight of messages (ChangeCipherSpec) to 3909 also contain the DOTS signal. TLS False Start is formally defined 3910 for use with TLS, but the same technique is applicable to DTLS as 3911 well. 3913 o Cached Information Extension [RFC7924] which avoids transmitting 3914 the server's certificate and certificate chain if the client has 3915 cached that information from a previous TLS handshake. 3917 Compared to UDP, DOTS signal channel over TCP requires an additional 3918 round-trip time (RTT) of latency to establish a TCP connection. DOTS 3919 implementations are encouraged to implement TCP Fast Open [RFC7413] 3920 to eliminate that RTT. 3922 7.2. (D)TLS 1.3 Considerations 3924 TLS 1.3 provides useful latency improvements for connection 3925 establishment over TLS 1.2. The DTLS 1.3 protocol 3926 [I-D.ietf-tls-dtls13] is based upon the TLS 1.3 protocol and provides 3927 equivalent security guarantees. (D)TLS 1.3 provides two basic 3928 handshake modes the DOTS signal channel can take advantage of: 3930 o A full handshake mode in which a DOTS client can send a DOTS 3931 mitigation request message after one round trip and the DOTS 3932 server immediately responds with a DOTS mitigation response. This 3933 assumes no packet loss is experienced. 3935 o 0-RTT mode in which the DOTS client can authenticate itself and 3936 send DOTS mitigation request messages in the first message, thus 3937 reducing handshake latency. 0-RTT only works if the DOTS client 3938 has previously communicated with that DOTS server, which is very 3939 likely with the DOTS signal channel. 3941 The DOTS client has to establish a (D)TLS session with the DOTS 3942 server during 'idle' time and share a PSK. 3944 During a DDoS attack, the DOTS client can use the (D)TLS session to 3945 convey the DOTS mitigation request message and, if there is no 3946 response from the server after multiple retries, the DOTS client can 3947 resume the (D)TLS session in 0-RTT mode using PSK. 3949 DOTS servers that support (D)TLS 1.3 MAY allow DOTS clients to send 3950 early data (0-RTT). DOTS clients MUST NOT send "CoAP Ping" as early 3951 data; such messages MUST be rejected by DOTS servers. Section 8 of 3952 [RFC8446] discusses some mechanisms to implement in order to limit 3953 the impact of replay attacks on 0-RTT data. If the DOTS server 3954 accepts 0-RTT, it MUST implement one of these mechanisms to prevent 3955 replay at the TLS layer. A DOTS server can reject 0-RTT by sending a 3956 TLS HelloRetryRequest. 3958 The DOTS signal channel messages sent as early data by the DOTS 3959 client are idempotent requests. As a reminder, the Message ID 3960 (Section 3 of [RFC7252]) is changed each time a new CoAP request is 3961 sent, and the Token (Section 5.3.1 of [RFC7252]) is randomized in 3962 each CoAP request. The DOTS server(s) MUST use the Message ID and 3963 the Token in the DOTS signal channel message to detect replay of 3964 early data at the application layer and accept 0-RTT data at most 3965 once from the same DOTS client. This anti-replay defense requires 3966 sharing the Message ID and the Token in the 0-RTT data between DOTS 3967 servers in the DOTS server domain. DOTS servers do not rely on 3968 transport coordinates to identify DOTS peers. As specified in 3969 Section 4.4.1, DOTS servers couple the DOTS signal channel sessions 3970 using the DOTS client identity and optionally the 'cdid' parameter 3971 value. Furthermore, the 'mid' value is monotonically increased by 3972 the DOTS client for each mitigation request, thus attackers that 3973 replay mitigation requests with lower numeric 'mid' values and 3974 overlapping scopes with mitigation requests having higher numeric 3975 'mid' values will be rejected systematically by the DOTS server. 3976 Likewise, the 'sid' value is monotonically increased by the DOTS 3977 client for each configuration request (Section 4.5.2); attackers 3978 replaying configuration requests with lower numeric 'sid' values will 3979 be rejected by the DOTS server if it maintains a higher numeric 'sid' 3980 value for this DOTS client. 3982 Owing to the aforementioned protections, all DOTS signal channel 3983 requests are safe to transmit in TLS 1.3 as early data. Refer to 3984 [I-D.boucadair-dots-earlydata] for more details. 3986 A simplified TLS 1.3 handshake with 0-RTT DOTS mitigation request 3987 message exchange is shown in Figure 29. 3989 DOTS Client DOTS Server 3991 ClientHello 3992 (0-RTT DOTS signal message) 3993 --------> 3994 ServerHello 3995 {EncryptedExtensions} 3996 {Finished} 3997 <-------- [DOTS signal message] 3998 (end_of_early_data) 3999 {Finished} --------> 4000 [DOTS signal message] <-------> [DOTS signal message] 4002 Note that: 4003 () Indicates messages protected 0-RTT keys 4004 {} Indicates messages protected using handshake keys 4005 [] Indicates messages protected using 1-RTT keys 4007 Figure 29: A Simplified TLS 1.3 Handshake with 0-RTT 4009 7.3. DTLS MTU and Fragmentation 4011 To avoid DOTS signal message fragmentation and the subsequent 4012 decreased probability of message delivery, DOTS agents MUST ensure 4013 that the DTLS record fits within a single datagram. As a reminder, 4014 DTLS handles fragmentation and reassembly only for handshake messages 4015 and not for the application data (Section 4.1.1 of [RFC6347]). If 4016 the path MTU (PMTU) cannot be discovered, DOTS agents MUST assume a 4017 PMTU of 1280 bytes, as IPv6 requires that every link in the Internet 4018 have an MTU of 1280 octets or greater as specified in [RFC8200]. If 4019 IPv4 support on legacy or otherwise unusual networks is a 4020 consideration and the PMTU is unknown, DOTS implementations MAY 4021 assume a PMTU of 576 bytes for IPv4 datagrams, as every IPv4 host 4022 must be capable of receiving a packet whose length is equal to 576 4023 bytes as discussed in [RFC0791] and [RFC1122]. 4025 The DOTS client must consider the amount of record expansion expected 4026 by the DTLS processing when calculating the size of the CoAP message 4027 that fits within the PMTU. PMTU MUST be greater than or equal to 4028 [CoAP message size + DTLS 1.2 overhead of 13 octets + authentication 4029 overhead of the negotiated DTLS cipher suite + block padding] 4030 (Section 4.1.1.1 of [RFC6347]). If the total request size exceeds 4031 the PMTU, then the DOTS client MUST split the DOTS signal into 4032 separate messages; for example, the list of addresses in the 'target- 4033 prefix' parameter could be split into multiple lists and each list 4034 conveyed in a new PUT request. 4036 | Implementation Note: DOTS choice of message size parameters 4037 | works well with IPv6 and with most of today's IPv4 paths. 4038 | However, with IPv4, it is harder to safely make sure that there 4039 | is no IP fragmentation. If the IPv4 PMTU is unknown, 4040 | implementations may want to limit themselves to more 4041 | conservative IPv4 datagram sizes such as 576 bytes, per 4042 | [RFC0791]. 4044 8. Mutual Authentication of DOTS Agents & Authorization of DOTS Clients 4046 (D)TLS based upon client certificates can be used for mutual 4047 authentication between DOTS agents. If, for example, a DOTS gateway 4048 is involved, DOTS clients and DOTS gateways must perform mutual 4049 authentication; only authorized DOTS clients are allowed to send DOTS 4050 signals to a DOTS gateway. The DOTS gateway and the DOTS server must 4051 perform mutual authentication; a DOTS server only allows DOTS signal 4052 channel messages from an authorized DOTS gateway, thereby creating a 4053 two-link chain of transitive authentication between the DOTS client 4054 and the DOTS server. 4056 The DOTS server should support certificate-based client 4057 authentication. The DOTS client should respond to the DOTS server's 4058 TLS CertificateRequest message with the PKIX certificate held by the 4059 DOTS client. DOTS client certificate validation must be performed 4060 per [RFC5280], and the DOTS client certificate must conform to the 4061 [RFC5280] certificate profile. If a DOTS client does not support TLS 4062 client certificate authentication, it must support client 4063 authentication based on pre-shared key or raw public key. 4065 +---------------------------------------------+ 4066 | example.com domain +---------+ | 4067 | | AAA | | 4068 | +---------------+ | Server | | 4069 | | Application | +------+--+ | 4070 | | server +<---------------+ ^ | 4071 | | (DOTS client) | | | | 4072 | +---------------+ | | | 4073 | V V | example.net domain 4074 | +-----+----+--+ | +---------------+ 4075 | +--------------+ | | | | | 4076 | | Guest +<----x---->+ DOTS +<----->+ DOTS | 4077 | | (DOTS client)| | gateway | | | server | 4078 | +--------------+ | | | | | 4079 | +----+--------+ | +---------------+ 4080 | ^ | 4081 | | | 4082 | +----------------+ | | 4083 | | DDoS detector | | | 4084 | | (DOTS client) +<-------------+ | 4085 | +----------------+ | 4086 +---------------------------------------------+ 4088 Figure 30: Example of Authentication and Authorization of DOTS Agents 4090 In the example depicted in Figure 30, the DOTS gateway and DOTS 4091 clients within the 'example.com' domain mutually authenticate. After 4092 the DOTS gateway validates the identity of a DOTS client, it 4093 communicates with the AAA server in the 'example.com' domain to 4094 determine if the DOTS client is authorized to request DDoS 4095 mitigation. If the DOTS client is not authorized, a 4.01 4096 (Unauthorized) is returned in the response to the DOTS client. In 4097 this example, the DOTS gateway only allows the application server and 4098 DDoS attack detector to request DDoS mitigation, but does not permit 4099 the user of type 'guest' to request DDoS mitigation. 4101 Also, DOTS gateways and servers located in different domains must 4102 perform mutual authentication (e.g., using certificates). A DOTS 4103 server will only allow a DOTS gateway with a certificate for a 4104 particular domain to request mitigation for that domain. In 4105 reference to Figure 30, the DOTS server only allows the DOTS gateway 4106 to request mitigation for the 'example.com' domain and not for other 4107 domains. 4109 9. Error Handling 4111 This section is a summary of the Error Code responses that can be 4112 returned by a DOTS server. These error responses must contain a CoAP 4113 4.xx or 5.xx Response Code. 4115 In general, there may be an additional plain text diagnostic payload 4116 (Section 5.5.2 of [RFC7252]) to help troubleshooting in the body of 4117 the response unless detailed otherwise. 4119 Errors returned by a DOTS server can be broken into two categories, 4120 those associated with CoAP itself and those generated during the 4121 validation of the provided data by the DOTS server. 4123 The following list of common CoAP errors that are implemented by DOTS 4124 servers. This list is not exhaustive, other errors defined by CoAP 4125 and associated RFCs may be applicable. 4127 o 4.00 (Bad Request) is returned by the DOTS server when the DOTS 4128 client has sent a request that violates the DOTS protocol 4129 (Section 4). 4131 o 4.01 (Unauthorized) is returned by the DOTS server when the DOTS 4132 client is not authorized to access the DOTS server (Section 4). 4134 o 4.02 (Bad Option) is returned by the DOTS server when one or more 4135 CoAP options are unknown or malformed by the CoAP layer [RFC7252]. 4137 o 4.04 (Not Found) is returned by the DOTS server when the DOTS 4138 client is requesting a 'mid' or 'sid' that is not valid 4139 (Section 4). 4141 o 4.05 (Method Not Allowed) is returned by the DOTS server when the 4142 DOTS client is requesting a resource by a method (e.g., GET) that 4143 is not supported by the DOTS server [RFC7252]. 4145 o 4.08 (Request Entity Incomplete) is returned by the DOTS server if 4146 one or multiple blocks of a block transfer request is missing 4147 [RFC7959]. 4149 o 4.09 (Conflict) is returned by the DOTS server if the DOTS server 4150 detects that a request conflicts with a previous request. The 4151 response body is formatted using "application/dots+cbor", and 4152 contains the "conflict-clause" (Section 4.4). 4154 o 4.13 (Request Entity Too Large) may be returned by the DOTS server 4155 during a block transfer request [RFC7959]. 4157 o 4.15 (Unsupported Content-Format) is returned by the DOTS server 4158 when the Content-Format used in the request is not formatted as 4159 "application/dots+cbor" (Section 4). 4161 o 4.22 (Unprocessable Entity) is returned by the DOTS server when 4162 one or more session configuration parameters are not valid 4163 (Section 4.5). 4165 o 5.03 (Service Unavailable) is returned by the DOTS server if the 4166 DOTS server is unable to handle the request (Section 4). An 4167 example is the DOTS server needs to redirect the DOTS client to 4168 use an alternate DOTS server (Section 4.6). The response body is 4169 formatted using "application/dots+cbor", and contains how to 4170 handle the 5.03 Response Code. 4172 o 5.08 (Hop Limit Reached) is returned by the DOTS server if there 4173 is a data path loop through upstream DOTS gateways. The response 4174 body is formatted using plain text and contains a list of servers 4175 that are in the data path loop [RFC8768]. 4177 10. IANA Considerations 4179 10.1. DOTS Signal Channel UDP and TCP Port Number 4181 IANA has assigned the port number 4646 (the ASCII decimal value for 4182 ".." (DOTS)) to the DOTS signal channel protocol for both UDP and TCP 4183 from the "Service Name and Transport Protocol Port Number Registry" 4184 available at . 4187 IANA is requested to update these entries with the RFC number to be 4188 assigned to this docuement: 4190 Service Name: dots-signal 4191 Port Number: 4646 4192 Transport Protocol: TCP 4193 Description: Distributed Denial-of-Service Open Threat Signaling 4194 (DOTS) Signal Channel 4195 Assignee: IESG 4196 Contact: IETF Chair 4197 Registration Date: 2020-01-16 4198 Reference: [RFCXXXX] 4200 Service Name: dots-signal 4201 Port Number: 4646 4202 Transport Protocol: UDP 4203 Description: Distributed Denial-of-Service Open Threat Signaling 4204 (DOTS) Signal Channel 4205 Assignee: IESG 4206 Contact: IETF Chair 4207 Registration Date: 2020-01-16 4208 Reference: [RFCXXXX] 4210 10.2. Well-Known 'dots' URI 4212 IANA is requested to update the the 'dots' well-known URI (Table 6) 4213 entry in the Well- Known URIs registry [URI] as follows: 4215 +------------+------------+-----------+-----------+-------------+ 4216 | URI Suffix | Change | Reference | Status | Related | 4217 | | Controller | | | information | 4218 +============+============+===========+===========+=============+ 4219 | dots | IETF | [RFCXXXX] | permanent | None | 4220 +------------+------------+-----------+-----------+-------------+ 4222 Table 6: 'dots' Well-Known URI 4224 10.3. Media Type Registration 4226 IANA is requested to update the "application/dots+cbor" media type in 4227 the "Media Types" registry [IANA-MediaTypes] in the manner described 4228 in [RFC6838], which can be used to indicate that the content is a 4229 DOTS signal channel object: 4231 Type name: application 4233 Subtype name: dots+cbor 4235 Required parameters: N/A 4237 Optional parameters: N/A 4239 Encoding considerations: binary 4241 Security considerations: See the Security Considerations section of 4242 [RFCXXXx]. 4244 Interoperability considerations: N/A 4246 Published specification: [RFCXXXX] 4248 Applications that use this media type: DOTS agents sending DOTS 4249 messages over CoAP over (D)TLS. 4251 Fragment identifier considerations: N/A 4253 Additional information: 4255 Deprecated alias names for this type: N/A 4256 Magic number(s): N/A 4257 File extension(s): N/A 4258 Macintosh file type code(s): N/A 4260 Person & email address to contact for further information: IESG, 4261 iesg@ietf.org 4263 Intended usage: COMMON 4265 Restrictions on usage: none 4267 Author: See Authors' Addresses section. 4269 Change controller: IESG 4271 Provisional registration? No 4273 10.4. CoAP Content-Formats Registration 4275 IANA is requested to update the CoAP Content-Format ID for the 4276 "application/ dots+cbor" media type in the "CoAP Content-Formats" 4277 registry [IANA-CoAP-Content-Formats]: 4279 o Media Type: application/dots+cbor 4280 o Encoding: - 4281 o Id: 271 4282 o Reference: [RFCXXXX] 4284 10.5. CBOR Tag Registration 4286 This section defines the DOTS CBOR tag as another means for 4287 applications to declare that a CBOR data structure is a DOTS signal 4288 channel object. Its use is optional and is intended for use in cases 4289 in which this information would not otherwise be known. The DOTS 4290 CBOR tag is not required for DOTS signal channel protocol version 4291 specified in this document. If present, the DOTS tag MUST prefix a 4292 DOTS signal channel object. 4294 IANA is requested to update the DOTS signal channel CBOR tag in the 4295 "CBOR Tags" registry [IANA-CBOR-Tags]: 4297 * Tag: 271 4298 * Data Item: DDoS Open Threat Signaling (DOTS) signal channel object 4299 * Semantics: DDoS Open Threat Signaling (DOTS) signal channel 4300 object, as defined in [RFXXXX] 4301 * Reference: [RFCXXXX] 4303 10.6. DOTS Signal Channel Protocol Registry 4305 The following sections update the "Distributed Denial-of- Service 4306 Open Threat Signaling (DOTS) Signal Channel" subregistries 4307 [REG-DOTS]. 4309 10.6.1. DOTS Signal Channel CBOR Key Values Subregistry 4311 The structure of this subregistry is provided in Section 10.6.1.1. 4313 10.6.1.1. Registration Template 4315 This specification requests IANA to update the allocation policy of 4316 "DOTS Signal Channel CBOR Key Values" registry as follows: 4318 Parameter name: 4319 Parameter name as used in the DOTS signal channel. 4321 CBOR Key Value: 4322 Key value for the parameter. The key value MUST be an integer in 4323 the 1-65535 range. 4325 OLD: 4326 +-------------+-------------------------+------------------------+ 4327 | Range | Registration Procedures | Note | 4328 +=============+=========================+========================+ 4329 | 1-16383 | IETF Review | comprehension-required | 4330 | 16384-32767 | Specification Required | comprehension-optional | 4331 | 32768-49151 | IETF Review | comprehension-optional | 4332 | 49152-65535 | Private Use | comprehension-optional | 4333 +-------------+-------------------------+------------------------+ 4335 NEW: 4336 +-------------+-------------------------+------------------------+ 4337 | Range | Registration Procedures | Note | 4338 +=============+=========================+========================+ 4339 | 1-127 | IETF Review | comprehension-required | 4340 | 128-255 | IETF Review | comprehension-optional | 4341 | 256-16383 | IETF Review | comprehension-required | 4342 | 16384-32767 | Specification Required | comprehension-optional | 4343 | 32768-49151 | IETF Review | comprehension-optional | 4344 | 49152-65535 | Private Use | comprehension-optional | 4345 +-------------+-------------------------+------------------------+ 4347 Registration requests for the 16384-32767 range are evaluated 4348 after a three-week review period on the dots-signal-reg- 4349 review@ietf.org mailing list, on the advice of one or more 4350 Designated Experts. However, to allow for the allocation of 4351 values prior to publication, the Designated Experts may approve 4352 registration once they are satisfied that such a specification 4353 will be published. New registration requests should be sent in 4354 the form of an email to the review mailing list; the request 4355 should use an appropriate subject (e.g., "Request to register CBOR 4356 Key Value for DOTS: example"). IANA will only accept new 4357 registrations from the Designated Experts, and it will check that 4358 review was requested on the mailing list in accordance with these 4359 procedures. 4361 Within the review period, the Designated Experts will either 4362 approve or deny the registration request, communicating this 4363 decision to the review list and IANA. Denials should include an 4364 explanation and, if applicable, suggestions as to how to make the 4365 request successful. Registration requests that are undetermined 4366 for a period longer than 21 days can be brought to the IESG's 4367 attention (using the iesg@ietf.org mailing list) for resolution. 4369 Criteria that should be applied by the Designated Experts include 4370 determining whether the proposed registration duplicates existing 4371 functionality, whether it is likely to be of general applicability 4372 or whether it is useful only for a single use case, and whether 4373 the registration description is clear. IANA must only accept 4374 registry updates to the 16384-32767 range from the Designated 4375 Experts and should direct all requests for registration to the 4376 review mailing list. It is suggested that multiple Designated 4377 Experts be appointed. In cases where a registration decision 4378 could be perceived as creating a conflict of interest for a 4379 particular Expert, that Expert should defer to the judgment of the 4380 other Experts. 4382 CBOR Major Type: 4383 CBOR Major type and optional tag for the parameter. 4385 Change Controller: 4386 For Standards Track RFCs, list the "IESG". For others, give the 4387 name of the responsible party. Other details (e.g., email 4388 address) may also be included. 4390 Specification Document(s): 4391 Reference to the document or documents that specify the parameter, 4392 preferably including URIs that can be used to retrieve copies of 4393 the documents. An indication of the relevant sections may also be 4394 included but is not required. 4396 10.6.1.2. Update Subregistry Content 4398 IANA is requested to update these entries from the "DOTS Signal 4399 Channel CBOR Key Values" registry with the RFC number to be assigned 4400 to this document: 4402 +---------------------+------------+-----+----------+---------------+ 4403 | Parameter Name | CBOR Key |CBOR | Change | Specification | 4404 | | Value |Major|Controller| Document(s) | 4405 | | |Type | | | 4406 +=====================+============+=====+==========+===============+ 4407 | Reserved | 0 | | | [RFCXXXX] | 4408 +---------------------+------------+-----+----------+---------------+ 4409 | ietf-dots-signal- | 1 | 5 | IESG | [RFCXXXX] | 4410 | channel:mitigation- | | | | | 4411 | scope | | | | | 4412 +---------------------+------------+-----+----------+---------------+ 4413 | scope | 2 | 4 | IESG | [RFCXXXX] | 4414 +---------------------+------------+-----+----------+---------------+ 4415 | cdid | 3 | 3 | IESG | [RFCXXXX] | 4416 +---------------------+------------+-----+----------+---------------+ 4417 | cuid | 4 | 3 | IESG | [RFCXXXX] | 4418 +---------------------+------------+-----+----------+---------------+ 4419 | mid | 5 | 0 | IESG | [RFCXXXX] | 4420 +---------------------+------------+-----+----------+---------------+ 4421 | target-prefix | 6 | 4 | IESG | [RFCXXXX] | 4422 +---------------------+------------+-----+----------+---------------+ 4423 | target-port-range | 7 | 4 | IESG | [RFCXXXX] | 4424 +---------------------+------------+-----+----------+---------------+ 4425 | lower-port | 8 | 0 | IESG | [RFCXXXX] | 4426 +---------------------+------------+-----+----------+---------------+ 4427 | upper-port | 9 | 0 | IESG | [RFCXXXX] | 4428 +---------------------+------------+-----+----------+---------------+ 4429 | target-protocol | 10 | 4 | IESG | [RFCXXXX] | 4430 +---------------------+------------+-----+----------+---------------+ 4431 | target-fqdn | 11 | 4 | IESG | [RFCXXXX] | 4432 +---------------------+------------+-----+----------+---------------+ 4433 | target-uri | 12 | 4 | IESG | [RFCXXXX] | 4434 +---------------------+------------+-----+----------+---------------+ 4435 | alias-name | 13 | 4 | IESG | [RFCXXXX] | 4436 +---------------------+------------+-----+----------+---------------+ 4437 | lifetime | 14 | 0/1 | IESG | [RFCXXXX] | 4438 +---------------------+------------+-----+----------+---------------+ 4439 | mitigation-start | 15 | 0 | IESG | [RFCXXXX] | 4440 +---------------------+------------+-----+----------+---------------+ 4441 | status | 16 | 0 | IESG | [RFCXXXX] | 4442 +---------------------+------------+-----+----------+---------------+ 4443 |conflict-information | 17 | 5 | IESG | [RFCXXXX] | 4444 +---------------------+------------+-----+----------+---------------+ 4445 | conflict-status | 18 | 0 | IESG | [RFCXXXX] | 4446 +---------------------+------------+-----+----------+---------------+ 4447 | conflict-cause | 19 | 0 | IESG | [RFCXXXX] | 4448 +---------------------+------------+-----+----------+---------------+ 4449 | retry-timer | 20 | 0 | IESG | [RFCXXXX] | 4450 +---------------------+------------+-----+----------+---------------+ 4451 | conflict-scope | 21 | 5 | IESG | [RFCXXXX] | 4452 +---------------------+------------+-----+----------+---------------+ 4453 | acl-list | 22 | 4 | IESG | [RFCXXXX] | 4454 +---------------------+------------+-----+----------+---------------+ 4455 | acl-name | 23 | 3 | IESG | [RFCXXXX] | 4456 +---------------------+------------+-----+----------+---------------+ 4457 | acl-type | 24 | 3 | IESG | [RFCXXXX] | 4458 +---------------------+------------+-----+----------+---------------+ 4459 | bytes-dropped | 25 | 0 | IESG | [RFCXXXX] | 4460 +---------------------+------------+-----+----------+---------------+ 4461 | bps-dropped | 26 | 0 | IESG | [RFCXXXX] | 4462 +---------------------+------------+-----+----------+---------------+ 4463 | pkts-dropped | 27 | 0 | IESG | [RFCXXXX] | 4464 +---------------------+------------+-----+----------+---------------+ 4465 | pps-dropped | 28 | 0 | IESG | [RFCXXXX] | 4466 +---------------------+------------+-----+----------+---------------+ 4467 | attack-status | 29 | 0 | IESG | [RFCXXXX] | 4468 +---------------------+------------+-----+----------+---------------+ 4469 | ietf-dots-signal- | 30 | 5 | IESG | [RFCXXXX] | 4470 |channel:signal-config| | | | | 4471 +---------------------+------------+-----+----------+---------------+ 4472 | sid | 31 | 0 | IESG | [RFCXXXX] | 4473 +---------------------+------------+-----+----------+---------------+ 4474 | mitigating-config | 32 | 5 | IESG | [RFCXXXX] | 4475 +---------------------+------------+-----+----------+---------------+ 4476 | heartbeat-interval | 33 | 5 | IESG | [RFCXXXX] | 4477 +---------------------+------------+-----+----------+---------------+ 4478 | min-value | 34 | 0 | IESG | [RFCXXXX] | 4479 +---------------------+------------+-----+----------+---------------+ 4480 | max-value | 35 | 0 | IESG | [RFCXXXX] | 4481 +---------------------+------------+-----+----------+---------------+ 4482 | current-value | 36 | 0 | IESG | [RFCXXXX] | 4483 +---------------------+------------+-----+----------+---------------+ 4484 | missing-hb-allowed | 37 | 5 | IESG | [RFCXXXX] | 4485 +---------------------+------------+-----+----------+---------------+ 4486 | max-retransmit | 38 | 5 | IESG | [RFCXXXX] | 4487 +---------------------+------------+-----+----------+---------------+ 4488 | ack-timeout | 39 | 5 | IESG | [RFCXXXX] | 4489 +---------------------+------------+-----+----------+---------------+ 4490 | ack-random-factor | 40 | 5 | IESG | [RFCXXXX] | 4491 +---------------------+------------+-----+----------+---------------+ 4492 | min-value-decimal | 41 |6tag4| IESG | [RFCXXXX] | 4493 +---------------------+------------+-----+----------+---------------+ 4494 | max-value-decimal | 42 |6tag4| IESG | [RFCXXXX] | 4495 +---------------------+------------+-----+----------+---------------+ 4496 |current-value-decimal| 43 |6tag4| IESG | [RFCXXXX] | 4497 +---------------------+------------+-----+----------+---------------+ 4498 | idle-config | 44 | 5 | IESG | [RFCXXXX] | 4499 +---------------------+------------+-----+----------+---------------+ 4500 | trigger-mitigation | 45 | 7 | IESG | [RFCXXXX] | 4501 +---------------------+------------+-----+----------+---------------+ 4502 | ietf-dots-signal- | 46 | 5 | IESG | [RFCXXXX] | 4503 | channel:redirected- | | | | | 4504 | signal | | | | | 4505 +---------------------+------------+-----+----------+---------------+ 4506 | alt-server | 47 | 3 | IESG | [RFCXXXX] | 4507 +---------------------+------------+-----+----------+---------------+ 4508 | alt-server-record | 48 | 4 | IESG | [RFCXXXX] | 4509 +---------------------+------------+-----+----------+---------------+ 4510 | ietf-dots-signal- | 49 | 5 | IESG | [RFCXXXX] | 4511 | channel:heartbeat | | | | | 4512 +---------------------+------------+-----+----------+---------------+ 4513 | probing-rate | 50 | 5 | IESG | [RFCXXXX] | 4514 +---------------------+------------+-----+----------+---------------+ 4515 | peer-hb-status | 51 | 7 | IESG | [RFCXXXX] | 4516 +---------------------+------------+-----+----------+---------------+ 4517 | Unassigned | 52-49151 | | | | 4518 +---------------------+------------+-----+----------+---------------+ 4519 |Reserved for Private |49152-65535 | | | [RFCXXXX] | 4520 | Use | | | | | 4521 +---------------------+------------+-----+----------+---------------+ 4523 Table 6: Initial DOTS Signal Channel CBOR Key Values Registry 4525 10.6.2. Status Codes Subregistry 4527 IANA is requested to update these entries from the "DOTS Signal 4528 Channel Status Codes" registry with the RFC number to be assigned to 4529 this document: 4531 +--------------+---------------+----------------------+-----------+ 4532 | Code | Label | Description | Reference | 4533 +==============+===============+======================+===========+ 4534 | 0 | Reserved | | [RFCXXXX] | 4535 +--------------+---------------+----------------------+-----------+ 4536 | 1 | attack- | Attack mitigation | [RFCXXXX] | 4537 | | mitigation- | setup is in progress | | 4538 | | in-progress | (e.g., changing the | | 4539 | | | network path to | | 4540 | | | redirect the inbound | | 4541 | | | traffic to a DOTS | | 4542 | | | mitigator). | | 4543 +--------------+---------------+----------------------+-----------+ 4544 | 2 | attack- | Attack is being | [RFCXXXX] | 4545 | | successfully- | successfully | | 4546 | | mitigated | mitigated (e.g., | | 4547 | | | traffic is | | 4548 | | | redirected to a DDoS | | 4549 | | | mitigator and attack | | 4550 | | | traffic is dropped). | | 4551 +--------------+---------------+----------------------+-----------+ 4552 | 3 | attack- | Attack has stopped | [RFCXXXX] | 4553 | | stopped | and the DOTS client | | 4554 | | | can withdraw the | | 4555 | | | mitigation request. | | 4556 +--------------+---------------+----------------------+-----------+ 4557 | 4 | attack- | Attack has exceeded | [RFCXXXX] | 4558 | | exceeded- | the mitigation | | 4559 | | capability | provider capability. | | 4560 +--------------+---------------+----------------------+-----------+ 4561 | 5 | dots-client- | DOTS client has | [RFCXXXX] | 4562 | | withdrawn- | withdrawn the | | 4563 | | mitigation | mitigation request | | 4564 | | | and the mitigation | | 4565 | | | is active but | | 4566 | | | terminating. | | 4567 +--------------+---------------+----------------------+-----------+ 4568 | 6 | attack- | Attack mitigation is | [RFCXXXX] | 4569 | | mitigation- | now terminated. | | 4570 | | terminated | | | 4571 +--------------+---------------+----------------------+-----------+ 4572 | 7 | attack- | Attack mitigation is | [RFCXXXX] | 4573 | | mitigation- | withdrawn. | | 4574 | | withdrawn | | | 4575 +--------------+---------------+----------------------+-----------+ 4576 | 8 | attack- | Attack mitigation | [RFCXXXX] | 4577 | | mitigation- | will be triggered | | 4578 | | signal-loss | for the mitigation | | 4579 | | | request only when | | 4580 | | | the DOTS signal | | 4581 | | | channel session is | | 4582 | | | lost. | | 4583 +--------------+---------------+----------------------+-----------+ 4584 | 9-2147483647 | Unassigned | | | 4585 +--------------+---------------+----------------------+-----------+ 4587 Table 8: Initial DOTS Signal Channel Status Codes 4589 New codes can be assigned via Standards Action [RFC8126]. 4591 10.6.3. Conflict Status Codes Subregistry 4593 IANA is requested to update these entries from the "DOTS Signal 4594 Channel Conflict Status Codes" registry with the RFC number to be 4595 assigned to this document: 4597 +--------------+-------------------+--------------------+-----------+ 4598 | Code | Label | Description | Reference | 4599 +==============+===================+====================+===========+ 4600 | 0 | Reserved | | [RFCXXXX] | 4601 +--------------+-------------------+--------------------+-----------+ 4602 | 1 | request-inactive- | DOTS server | [RFCXXXX] | 4603 | | other-active | has detected | | 4604 | | | conflicting | | 4605 | | | mitigation | | 4606 | | | requests from | | 4607 | | | different DOTS | | 4608 | | | clients. This | | 4609 | | | mitigation | | 4610 | | | request is | | 4611 | | | currently | | 4612 | | | inactive until | | 4613 | | | the conflicts | | 4614 | | | are resolved. | | 4615 | | | Another | | 4616 | | | mitigation | | 4617 | | | request is | | 4618 | | | active. | | 4619 +--------------+-------------------+--------------------+-----------+ 4620 | 2 | request-active | DOTS server | [RFCXXXX] | 4621 | | | has detected | | 4622 | | | conflicting | | 4623 | | | mitigation | | 4624 | | | requests from | | 4625 | | | different DOTS | | 4626 | | | clients. This | | 4627 | | | mitigation | | 4628 | | | request is | | 4629 | | | currently | | 4630 | | | active. | | 4631 +--------------+-------------------+--------------------+-----------+ 4632 | 3 | all-requests- | DOTS server | [RFCXXXX] | 4633 | | inactive | has detected | | 4634 | | | conflicting | | 4635 | | | mitigation | | 4636 | | | requests from | | 4637 | | | different DOTS | | 4638 | | | clients. All | | 4639 | | | conflicting | | 4640 | | | mitigation | | 4641 | | | requests are | | 4642 | | | inactive. | | 4643 +--------------+-------------------+--------------------+-----------+ 4644 | 4-2147483647 | Unassigned | | | 4645 +--------------+-------------------+--------------------+-----------+ 4647 Table 9: Initial DOTS Signal Channel Conflict Status Codes 4649 New codes can be assigned via Standards Action [RFC8126]. 4651 10.6.4. Conflict Cause Codes Subregistry 4653 IANA is requested to update these entries from the "DOTS Signal 4654 Channel Conflict Cause Codes" registry with the RFC number to be 4655 assigned to this document: 4657 +--------------+---------------------+----------------+-----------+ 4658 | Code | Label | Description | Reference | 4659 +==============+=====================+================+===========+ 4660 | 0 | Reserved | | [RFCXXXX] | 4661 +--------------+---------------------+----------------+-----------+ 4662 | 1 | overlapping-targets | Overlapping | [RFCXXXX] | 4663 | | | targets. | | 4664 +--------------+---------------------+----------------+-----------+ 4665 | 2 | conflict-with- | Conflicts with | [RFCXXXX] | 4666 | | acceptlist | an existing | | 4667 | | | accept-list. | | 4668 | | | This code is | | 4669 | | | returned when | | 4670 | | | the DDoS | | 4671 | | | mitigation | | 4672 | | | detects source | | 4673 | | | addresses/ | | 4674 | | | prefixes in | | 4675 | | | the accept- | | 4676 | | | listed ACLs | | 4677 | | | are attacking | | 4678 | | | the target. | | 4679 +--------------+---------------------+----------------+-----------+ 4680 | 3 | cuid-collision | CUID | [RFCXXXX] | 4681 | | | Collision. | | 4682 | | | This code is | | 4683 | | | returned when | | 4684 | | | a DOTS client | | 4685 | | | uses a 'cuid' | | 4686 | | | that is | | 4687 | | | already used | | 4688 | | | by another | | 4689 | | | DOTS client. | | 4690 +--------------+---------------------+----------------+-----------+ 4691 | 4-2147483647 | Unassigned | | | 4692 +--------------+---------------------+----------------+-----------+ 4694 Table 10: Initial DOTS Signal Channel Conflict Cause Codes 4696 New codes can be assigned via Standards Action [RFC8126]. 4698 10.6.5. Attack Status Codes Subregistry 4700 IANA is requested to update these entries from the "DOTS Signal 4701 Channel Attack Status Codes" registry with the RFC number to be 4702 assigned to this document: 4704 +--------------+----------------------+-----------------+-----------+ 4705 | Code | Label | Description | Reference | 4706 +==============+======================+=================+===========+ 4707 | 0 | Reserved | | [RFCXXXX] | 4708 +--------------+----------------------+-----------------+-----------+ 4709 | 1 | under-attack | The DOTS | [RFCXXXX] | 4710 | | | client | | 4711 | | | determines | | 4712 | | | that it is | | 4713 | | | still under | | 4714 | | | attack. | | 4715 +--------------+----------------------+-----------------+-----------+ 4716 | 2 | attack-successfully- | The DOTS | [RFCXXXX] | 4717 | | mitigated | client | | 4718 | | | determines | | 4719 | | | that the | | 4720 | | | attack is | | 4721 | | | successfully | | 4722 | | | mitigated. | | 4723 +--------------+----------------------+-----------------+-----------+ 4724 | 3-2147483647 | Unassigned | | | 4725 +--------------+----------------------+-----------------+-----------+ 4727 Table 11: Initial DOTS Signal Channel Attack Status Codes 4729 New codes can be assigned via Standards Action [RFC8126]. 4731 10.7. DOTS Signal Channel YANG Modules 4733 IANA already registered the following URIs in the "ns" subregistry 4734 within the "IETF XML Registry" [RFC3688]: 4736 URI: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4737 Registrant Contact: The IESG. 4738 XML: N/A; the requested URI is an XML namespace. 4740 URI: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4741 Registrant Contact: IANA. 4742 XML: N/A; the requested URI is an XML namespace. 4744 This document requests IANA to update the following YANG modules in 4745 the "YANG Module Names" subregistry [RFC6020] within the "YANG 4746 Parameters" registry. 4748 Name: ietf-dots-signal-channel 4749 Maintained by IANA: N 4750 Namespace: urn:ietf:params:xml:ns:yang:ietf-dots-signal-channel 4751 Prefix: dots-signal 4752 Reference: RFCXXXX 4754 Name: iana-dots-signal-channel 4755 Maintained by IANA: Y 4756 Namespace: urn:ietf:params:xml:ns:yang:iana-dots-signal-channel 4757 Prefix: iana-dots-signal 4758 Reference: RFCXXXX 4760 This document defines the initial version of the IANA-maintained 4761 iana-dots-signal-channel YANG module. IANA is requested to maintain 4762 this note: 4764 Status, conflict status, conflict cause, and attack status values 4765 must not be directly added to the iana-dots-signal-channel YANG 4766 module. They must instead be respectively added to the "DOTS 4767 Status Codes", "DOTS Conflict Status Codes", "DOTS Conflict Cause 4768 Codes", and "DOTS Attack Status Codes" registries. 4770 When a 'status', 'conflict-status', 'conflict-cause', or 'attack- 4771 status' value is respectively added to the "DOTS Status Codes", "DOTS 4772 Conflict Status Codes", "DOTS Conflict Cause Codes", or "DOTS Attack 4773 Status Codes" registry, a new "enum" statement must be added to the 4774 iana-dots-signal-channel YANG module. The following "enum" 4775 statement, and substatements thereof, should be defined: 4777 "enum": Replicates the label from the registry. 4779 "value": Contains the IANA-assigned value corresponding to the 4780 'status', 'conflict-status', 'conflict-cause', or 4781 'attack-status'. 4783 "description": Replicates the description from the registry. 4785 "reference": Replicates the reference from the registry and adds 4786 the title of the document. 4788 When the iana-dots-signal-channel YANG module is updated, a new 4789 "revision" statement must be added in front of the existing revision 4790 statements. 4792 IANA is requested to update this note of "DOTS Status Codes", "DOTS 4793 Conflict Status Codes", "DOTS Conflict Cause Codes", and "DOTS Attack 4794 Status Codes" registries: 4796 When this registry is modified, the YANG module iana-dots-signal- 4797 channel must be updated as defined in [RFCXXXX]. 4799 11. Security Considerations 4801 High-level DOTS security considerations are documented in [RFC8612] 4802 and [RFC8811]. 4804 Authenticated encryption MUST be used for data confidentiality and 4805 message integrity. The interaction between the DOTS agents requires 4806 Datagram Transport Layer Security (DTLS) or Transport Layer Security 4807 (TLS) with a cipher suite offering confidentiality protection, and 4808 the guidance given in [RFC7525] MUST be followed to avoid attacks on 4809 (D)TLS. The (D)TLS protocol profile used for the DOTS signal channel 4810 is specified in Section 7. 4812 If TCP is used between DOTS agents, an attacker may be able to inject 4813 RST packets, bogus application segments, etc., regardless of whether 4814 TLS authentication is used. Because the application data is TLS 4815 protected, this will not result in the application receiving bogus 4816 data, but it will constitute a DoS on the connection. This attack 4817 can be countered by using TCP Authentication Option (TCP-AO) 4818 [RFC5925]. Although not widely adopted, if TCP-AO is used, then any 4819 bogus packets injected by an attacker will be rejected by the TCP-AO 4820 integrity check and therefore will never reach the TLS layer. 4822 If the 'cuid' is guessable, a misbehaving DOTS client from within the 4823 client's domain can use the 'cuid' of another DOTS client of the 4824 domain to delete or alter active mitigations. For this attack vector 4825 to happen, the misbehaving client needs to pass the security 4826 validation checks by the DOTS server, and eventually the checks of a 4827 client-domain DOTS gateway. 4829 A similar attack can be achieved by a compromised DOTS client that 4830 can sniff the TLS 1.2 handshake, use the client certificate to 4831 identify the 'cuid' used by another DOTS client. This attack is not 4832 possible if algorithms such as version 4 Universally Unique 4833 IDentifiers (UUIDs) in Section 4.4 of [RFC4122] are used to generate 4834 the 'cuid' because such UUIDs are not a deterministic function of the 4835 client certificate. Likewise, this attack is not possible with TLS 4836 1.3 because most of the TLS handshake is encrypted and the client 4837 certificate is not visible to eavesdroppers. 4839 A compromised DOTS client can collude with a DDoS attacker to send 4840 mitigation request for a target resource, get the mitigation efficacy 4841 from the DOTS server, and convey the mitigation efficacy to the DDoS 4842 attacker to possibly change the DDoS attack strategy. Obviously, 4843 signaling an attack by the compromised DOTS client to the DOTS server 4844 will trigger attack mitigation. This attack can be prevented by 4845 monitoring and auditing DOTS clients to detect misbehavior and to 4846 deter misuse, and by only authorizing the DOTS client to request 4847 mitigation for specific target resources (e.g., an application server 4848 is authorized to request mitigation for its IP addresses, but a DDoS 4849 mitigator can request mitigation for any target resource in the 4850 network). Furthermore, DOTS clients are typically co-located on 4851 network security services (e.g., firewall), and a compromised 4852 security service potentially can do a lot more damage to the network. 4854 Rate-limiting DOTS requests, including those with new 'cuid' values, 4855 from the same DOTS client defend against DoS attacks that would 4856 result in varying the 'cuid' to exhaust DOTS server resources. Rate- 4857 limit policies SHOULD be enforced on DOTS gateways (if deployed) and 4858 DOTS servers. 4860 In order to prevent leaking internal information outside a client's 4861 domain, DOTS gateways located in the client domain SHOULD NOT reveal 4862 the identification information that pertains to internal DOTS clients 4863 (e.g., source IP address, client's hostname) unless explicitly 4864 configured to do so. 4866 DOTS servers MUST verify that requesting DOTS clients are entitled to 4867 trigger actions on a given IP prefix. That is, only actions on IP 4868 resources that belong to the DOTS client's domain MUST be authorized 4869 by a DOTS server. The exact mechanism for the DOTS servers to 4870 validate that the target prefixes are within the scope of the DOTS 4871 client domain is deployment specific. 4873 The presence of DOTS gateways may lead to infinite forwarding loops, 4874 which is undesirable. To prevent and detect such loops, this 4875 document uses the Hop-Limit Option. 4877 When FQDNs are used as targets, the DOTS server MUST rely upon DNS 4878 privacy-enabling protocols (e.g., DNS over TLS [RFC7858] or DNS over 4879 HTTPS (DoH) [RFC8484]) to prevent eavesdroppers from possibly 4880 identifying the target resources protected by the DDoS mitigation 4881 service to ensure the target FQDN resolution is authentic (e.g., 4882 DNSSEC [RFC4034]). 4884 CoAP-specific security considerations are discussed in Section 11 of 4885 [RFC7252], while CBOR-related security considerations are discussed 4886 in Section 8 of [RFC7049]. 4888 This document defines YANG data structures that are meant to be used 4889 as an abstract representation of DOTS signal channel messages. As 4890 such, the "ietf-dots-signal-channel" module does not introduce any 4891 new vulnerabilities beyond those specified above. 4893 12. References 4895 12.1. Normative References 4897 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791, 4898 DOI 10.17487/RFC0791, September 1981, 4899 . 4901 [RFC1122] Braden, R., Ed., "Requirements for Internet Hosts - 4902 Communication Layers", STD 3, RFC 1122, 4903 DOI 10.17487/RFC1122, October 1989, 4904 . 4906 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4907 Requirement Levels", BCP 14, RFC 2119, 4908 DOI 10.17487/RFC2119, March 1997, 4909 . 4911 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 4912 DOI 10.17487/RFC3688, January 2004, 4913 . 4915 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 4916 Resource Identifier (URI): Generic Syntax", STD 66, 4917 RFC 3986, DOI 10.17487/RFC3986, January 2005, 4918 . 4920 [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key 4921 Ciphersuites for Transport Layer Security (TLS)", 4922 RFC 4279, DOI 10.17487/RFC4279, December 2005, 4923 . 4925 [RFC4632] Fuller, V. and T. Li, "Classless Inter-domain Routing 4926 (CIDR): The Internet Address Assignment and Aggregation 4927 Plan", BCP 122, RFC 4632, DOI 10.17487/RFC4632, August 4928 2006, . 4930 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 4931 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 4932 . 4934 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 4935 (TLS) Protocol Version 1.2", RFC 5246, 4936 DOI 10.17487/RFC5246, August 2008, 4937 . 4939 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 4940 Housley, R., and W. Polk, "Internet X.509 Public Key 4941 Infrastructure Certificate and Certificate Revocation List 4942 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 4943 . 4945 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 4946 the Network Configuration Protocol (NETCONF)", RFC 6020, 4947 DOI 10.17487/RFC6020, October 2010, 4948 . 4950 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 4951 Extensions: Extension Definitions", RFC 6066, 4952 DOI 10.17487/RFC6066, January 2011, 4953 . 4955 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 4956 Verification of Domain-Based Application Service Identity 4957 within Internet Public Key Infrastructure Using X.509 4958 (PKIX) Certificates in the Context of Transport Layer 4959 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 4960 2011, . 4962 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 4963 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 4964 January 2012, . 4966 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 4967 RFC 6991, DOI 10.17487/RFC6991, July 2013, 4968 . 4970 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 4971 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 4972 October 2013, . 4974 [RFC7250] Wouters, P., Ed., Tschofenig, H., Ed., Gilmore, J., 4975 Weiler, S., and T. Kivinen, "Using Raw Public Keys in 4976 Transport Layer Security (TLS) and Datagram Transport 4977 Layer Security (DTLS)", RFC 7250, DOI 10.17487/RFC7250, 4978 June 2014, . 4980 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 4981 Application Protocol (CoAP)", RFC 7252, 4982 DOI 10.17487/RFC7252, June 2014, 4983 . 4985 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 4986 "Recommendations for Secure Use of Transport Layer 4987 Security (TLS) and Datagram Transport Layer Security 4988 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 4989 2015, . 4991 [RFC7641] Hartke, K., "Observing Resources in the Constrained 4992 Application Protocol (CoAP)", RFC 7641, 4993 DOI 10.17487/RFC7641, September 2015, 4994 . 4996 [RFC7918] Langley, A., Modadugu, N., and B. Moeller, "Transport 4997 Layer Security (TLS) False Start", RFC 7918, 4998 DOI 10.17487/RFC7918, August 2016, 4999 . 5001 [RFC7924] Santesson, S. and H. Tschofenig, "Transport Layer Security 5002 (TLS) Cached Information Extension", RFC 7924, 5003 DOI 10.17487/RFC7924, July 2016, 5004 . 5006 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 5007 RFC 7950, DOI 10.17487/RFC7950, August 2016, 5008 . 5010 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 5011 the Constrained Application Protocol (CoAP)", RFC 7959, 5012 DOI 10.17487/RFC7959, August 2016, 5013 . 5015 [RFC8085] Eggert, L., Fairhurst, G., and G. Shepherd, "UDP Usage 5016 Guidelines", BCP 145, RFC 8085, DOI 10.17487/RFC8085, 5017 March 2017, . 5019 [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for 5020 Writing an IANA Considerations Section in RFCs", BCP 26, 5021 RFC 8126, DOI 10.17487/RFC8126, June 2017, 5022 . 5024 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 5025 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 5026 May 2017, . 5028 [RFC8200] Deering, S. and R. Hinden, "Internet Protocol, Version 6 5029 (IPv6) Specification", STD 86, RFC 8200, 5030 DOI 10.17487/RFC8200, July 2017, 5031 . 5033 [RFC8305] Schinazi, D. and T. Pauly, "Happy Eyeballs Version 2: 5034 Better Connectivity Using Concurrency", RFC 8305, 5035 DOI 10.17487/RFC8305, December 2017, 5036 . 5038 [RFC8323] Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 5039 Silverajan, B., and B. Raymor, Ed., "CoAP (Constrained 5040 Application Protocol) over TCP, TLS, and WebSockets", 5041 RFC 8323, DOI 10.17487/RFC8323, February 2018, 5042 . 5044 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 5045 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 5046 . 5048 [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers 5049 (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, 5050 . 5052 [RFC8768] Boucadair, M., Reddy.K, T., and J. Shallow, "Constrained 5053 Application Protocol (CoAP) Hop-Limit Option", RFC 8768, 5054 DOI 10.17487/RFC8768, March 2020, 5055 . 5057 [RFC8783] Boucadair, M., Ed. and T. Reddy.K, Ed., "Distributed 5058 Denial-of-Service Open Threat Signaling (DOTS) Data 5059 Channel Specification", RFC 8783, DOI 10.17487/RFC8783, 5060 May 2020, . 5062 [RFC8791] Bierman, A., Bjoerklund, M., and K. Watsen, "YANG Data 5063 Structure Extensions", RFC 8791, DOI 10.17487/RFC8791, 5064 June 2020, . 5066 12.2. Informative References 5068 [I-D.boucadair-dots-earlydata] 5069 Boucadair, M. and R. K, "Using Early Data in DOTS", draft- 5070 boucadair-dots-earlydata-00 (work in progress), January 5071 2019. 5073 [I-D.ietf-core-comi] 5074 Veillette, M., Stok, P., Pelov, A., Bierman, A., and I. 5075 Petrov, "CoAP Management Interface (CORECONF)", draft- 5076 ietf-core-comi-10 (work in progress), July 2020. 5078 [I-D.ietf-core-yang-cbor] 5079 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 5080 Data Modeled with YANG", draft-ietf-core-yang-cbor-13 5081 (work in progress), July 2020. 5083 [I-D.ietf-dots-multihoming] 5084 Boucadair, M., Reddy.K, T., and W. Pan, "Multi-homing 5085 Deployment Considerations for Distributed-Denial-of- 5086 Service Open Threat Signaling (DOTS)", draft-ietf-dots- 5087 multihoming-04 (work in progress), May 2020. 5089 [I-D.ietf-dots-server-discovery] 5090 Boucadair, M. and T. Reddy.K, "Distributed-Denial-of- 5091 Service Open Threat Signaling (DOTS) Agent Discovery", 5092 draft-ietf-dots-server-discovery-15 (work in progress), 5093 November 2020. 5095 [I-D.ietf-dots-telemetry] 5096 Boucadair, M., Reddy.K, T., Doron, E., chenmeiling, c., 5097 and J. Shallow, "Distributed Denial-of-Service Open Threat 5098 Signaling (DOTS) Telemetry", draft-ietf-dots-telemetry-14 5099 (work in progress), November 2020. 5101 [I-D.ietf-dots-use-cases] 5102 Dobbins, R., Migault, D., Moskowitz, R., Teague, N., Xia, 5103 L., and K. Nishizuka, "Use cases for DDoS Open Threat 5104 Signaling", draft-ietf-dots-use-cases-25 (work in 5105 progress), July 2020. 5107 [I-D.ietf-tls-dtls13] 5108 Rescorla, E., Tschofenig, H., and N. Modadugu, "The 5109 Datagram Transport Layer Security (DTLS) Protocol Version 5110 1.3", draft-ietf-tls-dtls13-39 (work in progress), 5111 November 2020. 5113 [IANA-CBOR-Tags] 5114 IANA, "Concise Binary Object Representation (CBOR) Tags", 5115 . 5118 [IANA-CoAP-Content-Formats] 5119 IANA, "CoAP Content-Formats", 5120 . 5123 [IANA-MediaTypes] 5124 IANA, "Media Types", 5125 . 5127 [IANA-Proto] 5128 IANA, "Protocol Numbers", 2011, 5129 . 5131 [REG-DOTS] 5132 IANA, "Distributed Denial-of-Service Open Threat Signaling 5133 (DOTS) Signal Channel", 5134 . 5136 [RFC3022] Srisuresh, P. and K. Egevang, "Traditional IP Network 5137 Address Translator (Traditional NAT)", RFC 3022, 5138 DOI 10.17487/RFC3022, January 2001, 5139 . 5141 [RFC4034] Arends, R., Austein, R., Larson, M., Massey, D., and S. 5142 Rose, "Resource Records for the DNS Security Extensions", 5143 RFC 4034, DOI 10.17487/RFC4034, March 2005, 5144 . 5146 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 5147 Unique IDentifier (UUID) URN Namespace", RFC 4122, 5148 DOI 10.17487/RFC4122, July 2005, 5149 . 5151 [RFC4340] Kohler, E., Handley, M., and S. Floyd, "Datagram 5152 Congestion Control Protocol (DCCP)", RFC 4340, 5153 DOI 10.17487/RFC4340, March 2006, 5154 . 5156 [RFC4732] Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet 5157 Denial-of-Service Considerations", RFC 4732, 5158 DOI 10.17487/RFC4732, December 2006, 5159 . 5161 [RFC4787] Audet, F., Ed. and C. Jennings, "Network Address 5162 Translation (NAT) Behavioral Requirements for Unicast 5163 UDP", BCP 127, RFC 4787, DOI 10.17487/RFC4787, January 5164 2007, . 5166 [RFC4960] Stewart, R., Ed., "Stream Control Transmission Protocol", 5167 RFC 4960, DOI 10.17487/RFC4960, September 2007, 5168 . 5170 [RFC4987] Eddy, W., "TCP SYN Flooding Attacks and Common 5171 Mitigations", RFC 4987, DOI 10.17487/RFC4987, August 2007, 5172 . 5174 [RFC5925] Touch, J., Mankin, A., and R. Bonica, "The TCP 5175 Authentication Option", RFC 5925, DOI 10.17487/RFC5925, 5176 June 2010, . 5178 [RFC6052] Bao, C., Huitema, C., Bagnulo, M., Boucadair, M., and X. 5179 Li, "IPv6 Addressing of IPv4/IPv6 Translators", RFC 6052, 5180 DOI 10.17487/RFC6052, October 2010, 5181 . 5183 [RFC6146] Bagnulo, M., Matthews, P., and I. van Beijnum, "Stateful 5184 NAT64: Network Address and Protocol Translation from IPv6 5185 Clients to IPv4 Servers", RFC 6146, DOI 10.17487/RFC6146, 5186 April 2011, . 5188 [RFC6234] Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms 5189 (SHA and SHA-based HMAC and HKDF)", RFC 6234, 5190 DOI 10.17487/RFC6234, May 2011, 5191 . 5193 [RFC6296] Wasserman, M. and F. Baker, "IPv6-to-IPv6 Network Prefix 5194 Translation", RFC 6296, DOI 10.17487/RFC6296, June 2011, 5195 . 5197 [RFC6724] Thaler, D., Ed., Draves, R., Matsumoto, A., and T. Chown, 5198 "Default Address Selection for Internet Protocol Version 6 5199 (IPv6)", RFC 6724, DOI 10.17487/RFC6724, September 2012, 5200 . 5202 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 5203 Specifications and Registration Procedures", BCP 13, 5204 RFC 6838, DOI 10.17487/RFC6838, January 2013, 5205 . 5207 [RFC6887] Wing, D., Ed., Cheshire, S., Boucadair, M., Penno, R., and 5208 P. Selkirk, "Port Control Protocol (PCP)", RFC 6887, 5209 DOI 10.17487/RFC6887, April 2013, 5210 . 5212 [RFC6888] Perreault, S., Ed., Yamagata, I., Miyakawa, S., Nakagawa, 5213 A., and H. Ashida, "Common Requirements for Carrier-Grade 5214 NATs (CGNs)", BCP 127, RFC 6888, DOI 10.17487/RFC6888, 5215 April 2013, . 5217 [RFC7030] Pritikin, M., Ed., Yee, P., Ed., and D. Harkins, Ed., 5218 "Enrollment over Secure Transport", RFC 7030, 5219 DOI 10.17487/RFC7030, October 2013, 5220 . 5222 [RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP 5223 Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014, 5224 . 5226 [RFC7452] Tschofenig, H., Arkko, J., Thaler, D., and D. McPherson, 5227 "Architectural Considerations in Smart Object Networking", 5228 RFC 7452, DOI 10.17487/RFC7452, March 2015, 5229 . 5231 [RFC7589] Badra, M., Luchuk, A., and J. Schoenwaelder, "Using the 5232 NETCONF Protocol over Transport Layer Security (TLS) with 5233 Mutual X.509 Authentication", RFC 7589, 5234 DOI 10.17487/RFC7589, June 2015, 5235 . 5237 [RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D., 5238 and P. Hoffman, "Specification for DNS over Transport 5239 Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May 5240 2016, . 5242 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 5243 RFC 7951, DOI 10.17487/RFC7951, August 2016, 5244 . 5246 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 5247 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 5248 . 5250 [RFC8484] Hoffman, P. and P. McManus, "DNS Queries over HTTPS 5251 (DoH)", RFC 8484, DOI 10.17487/RFC8484, October 2018, 5252 . 5254 [RFC8489] Petit-Huguenin, M., Salgueiro, G., Rosenberg, J., Wing, 5255 D., Mahy, R., and P. Matthews, "Session Traversal 5256 Utilities for NAT (STUN)", RFC 8489, DOI 10.17487/RFC8489, 5257 February 2020, . 5259 [RFC8499] Hoffman, P., Sullivan, A., and K. Fujiwara, "DNS 5260 Terminology", BCP 219, RFC 8499, DOI 10.17487/RFC8499, 5261 January 2019, . 5263 [RFC8612] Mortensen, A., Reddy, T., and R. Moskowitz, "DDoS Open 5264 Threat Signaling (DOTS) Requirements", RFC 8612, 5265 DOI 10.17487/RFC8612, May 2019, 5266 . 5268 [RFC8782] Reddy.K, T., Ed., Boucadair, M., Ed., Patil, P., 5269 Mortensen, A., and N. Teague, "Distributed Denial-of- 5270 Service Open Threat Signaling (DOTS) Signal Channel 5271 Specification", RFC 8782, DOI 10.17487/RFC8782, May 2020, 5272 . 5274 [RFC8811] Mortensen, A., Ed., Reddy.K, T., Ed., Andreasen, F., 5275 Teague, N., and R. Compton, "DDoS Open Threat Signaling 5276 (DOTS) Architecture", RFC 8811, DOI 10.17487/RFC8811, 5277 August 2020, . 5279 [URI] IANA, "Well-Known URIs", 5280 . 5283 Appendix A. Summary of Changes From RFC8782 5285 The main changes compared to [RFC8782] are as follows: 5287 o Update the "ietf-dots-signal-channel" YANG module (Section 5.3) 5288 and the tree structure (Section 5.1) to follow the new YANG data 5289 structure specified in [RFC8791]. In particular: 5291 * Add in 'choice' to indicate the communication direction in 5292 which a data node applies. If no 'choice' is indicated, a data 5293 node can appear in both directions (i.e., from DOTS clients to 5294 DOTS servers and vice versa). 5296 * Remove 'config' clauses. Note that 'config' statements will be 5297 ignored (if present) anyway according to Section 4 of 5298 [RFC8791]. This supersedes the references to the use of 'ro' 5299 and 'rw' which are now covered by 'choice' above. 5301 * Remove 'cuid', 'cdid', and 'sid' data nodes from the structure 5302 because these data nodes are included as Uri-Path options, not 5303 within the message body. 5305 * Remove the list keys for the mitigation scope message type 5306 (i.e., 'cuid' and 'mid'). 'mid' is not indicated as a key 5307 because it is included as Uri-Path option for requests and in 5308 the message body for responses. Note that Section 4 of 5309 [RFC8791] specifies that a list does not require to have a key 5310 statement defined. 5312 o Add a new section with a summary of the error code responses that 5313 can be returned by a DOTS server (Section 9). 5315 o Update the IANA section to allocate a new range for comprehension- 5316 optional attributes (Section 10.6.1.1). This modification is 5317 motivated by the need to allow for compact DOTS signal messages 5318 that include a long list of comprehension-optional attributes, 5319 e.g., DOTS telemetry messages [I-D.ietf-dots-telemetry]. 5321 Appendix B. CUID Generation 5323 The document recommends the use of SPKI to generate the 'cuid'. This 5324 design choice is motivated by the following reasons: 5326 o SPKI is globally unique. 5328 o It is deterministic. 5330 o It allows the avoidance of extra cycles that may be induced by 5331 'cuid' collision. 5333 o DOTS clients do not need to store the 'cuid' in a persistent 5334 storage. 5336 o It allows the detection of compromised DOTS clients that do not 5337 adhere to the 'cuid' generation algorithm. 5339 Appendix C. Acknowledgements 5341 Many thanks to Martin Bjoerklund for the suggestion to use RFC8791. 5343 Thanks to Ebben Aries for the yangdoctors review and Dan Romascanu 5344 for the opsdir review. 5346 C.1. Acknowledgements from RFC8782 5348 Thanks to Christian Jacquenet, Roland Dobbins, Roman Danyliw, Michael 5349 Richardson, Ehud Doron, Kaname Nishizuka, Dave Dolson, Liang Xia, 5350 Gilbert Clark, Xialiang Frank, Jim Schaad, Klaus Hartke, Nesredien 5351 Suleiman, Stephen Farrell, and Yoshifumi Nishida for the discussion 5352 and comments. 5354 The authors would like to give special thanks to Kaname Nishizuka and 5355 Jon Shallow for their efforts in implementing the protocol and 5356 performing interop testing at IETF Hackathons. 5358 Thanks to the core WG for the recommendations on Hop-Limit and 5359 redirect signaling. 5361 Special thanks to Benjamin Kaduk for the detailed AD review. 5363 Thanks to Alexey Melnikov, Adam Roach, Suresh Krishnan, Mirja 5364 Kuehlewind, and Alissa Cooper for the review. 5366 Thanks to Carsten Bormann for his review of the DOTS heartbeat 5367 mechanism. 5369 Appendix D. Contributors 5371 D.1. Authors of RFC8782 5373 The authors of RFC8782 are listed below: 5375 Tirumaleswar Reddy.K (editor) 5376 McAfee, Inc. 5377 Embassy Golf Link Business Park 5378 Bangalore 560071 5379 Karnataka 5380 India 5382 Email: kondtir@gmail.com 5384 Mohamed Boucadair (editor) 5385 Orange 5386 35000 Rennes 5387 France 5389 Email: mohamed.boucadair@orange.com 5391 Prashanth Patil 5392 Cisco Systems, Inc. 5394 Email: praspati@cisco.com 5396 Andrew Mortensen 5397 Arbor Networks, Inc. 5398 2727 S. State Street 5399 Ann Arbor, MI 48104 5400 United States of America 5402 Email: andrew@moretension.com 5404 Nik Teague 5405 Iron Mountain Data Centers 5406 United Kingdom 5408 Email: nteague@ironmountain.co.uk 5410 D.2. Contributors to RFC8782 5412 The following individuals have contributed to RFC8782: 5414 Jon Shallow 5415 NCC Group 5417 Email: jon.shallow@nccgroup.trust 5419 Mike Geller 5420 Cisco Systems, Inc. 5421 FL 33309 5422 United States of America 5424 Email: mgeller@cisco.com 5426 Robert Moskowitz 5427 HTT Consulting 5428 Oak Park, MI 42837 5429 United States of America 5431 Email: rgm@htt-consult.com 5433 Authors' Addresses 5435 Mohamed Boucadair (editor) 5436 Orange 5437 Rennes 35000 5438 France 5440 Email: mohamed.boucadair@orange.com 5442 Jon Shallow 5443 United Kingdom 5445 Email: supjps-ietf@jpshallow.com 5447 Tirumaleswar Reddy.K 5448 McAfee, Inc. 5449 Embassy Golf Link Business Park 5450 Bangalore, Karnataka 560071 5451 India 5453 Email: kondtir@gmail.com